{
  "markdown": "# Devflow — Cross-Tool AI Workflow Orchestrator\n\n[![test](https://github.com/yuriykuzin/devflow/actions/workflows/test.yml/badge.svg)](https://github.com/yuriykuzin/devflow/actions/workflows/test.yml)\n\nAutomates the planning → implementation → review pipeline across multiple AI coding tools (Claude Code, Codex CLI, opencode, Gemini CLI, Cursor).\n\n## How It Works\n\nDevflow adds a **cross-tool orchestration layer** on top of [Superpowers](https://github.com/obra/superpowers). It delegates internal process to superpowers skills (brainstorming, writing-plans, TDD, code review) and adds **external review loops** by calling other AI tools via their CLI.\n\n```\nYou (in Claude Code):  \"devflow:run — add caching for /skills endpoint\"\n  │\n  ├─ Phase 1: PLAN (current tool + superpowers:brainstorming + superpowers:writing-plans)\n  │    └─ External review (read-only): \"Review this plan...\" → iterate until OK\n  │\n  ├─ Phase 2: IMPLEMENT (external tool or current tool + superpowers:subagent-driven-development)\n  │    └─ External review (read-only): \"Review this code...\" → iterate until OK\n  │\n  └─ Phase 3: REVIEW (cross-tool verification)\n       └─ Both current tool and external tool review final result\n       └─ Report saved to docs/devflow/reports/\n```\n\n## Requirements\n\n- At least one external CLI tool: `codex` (recommended) or `claude`\n- Bash access (all agentic environments provide this)\n- **Optional**: [Superpowers](https://github.com/obra/superpowers) plugin for internal workflow skills (brainstorming, TDD, etc.). Devflow works without it but is more powerful with it.\n\n## Installation\n\nFollows the superpowers pattern: **clone → symlink → done**.\n\n### Quick install\n\n```bash\ngit clone https://github.com/yuriykuzin/devflow.git ~/.codex/devflow\n~/.codex/devflow/install.sh\n```\n\nYou can clone to **any directory** — the install script creates symlinks pointing to wherever it lives. `~/.codex/devflow` is the recommended convention.\n\nRun `install.sh --status` to check, `install.sh --choose` to select tools, or `install.sh --uninstall` to remove.\n\n### Manual install (per platform)\n\n**Codex CLI** — one directory symlink (Codex scans recursively):\n```bash\nmkdir -p ~/.agents/skills\nln -s /path/to/devflow/skills ~/.agents/skills/devflow\n```\n\n**Claude Code** — registered automatically by `install.sh` (creates local marketplace + copies to plugin cache). Restart Claude Code after install. If skills don't appear, start with:\n```bash\nclaude --plugin-dir /path/to/devflow\n```\n\n**opencode** — one symlink **per skill**, because opencode discovers\n`~/.config/opencode/skills/<name>/SKILL.md` and a single link to the whole `skills/` tree\nwould bury every skill one level too deep:\n```bash\nmkdir -p ~/.config/opencode/skills\nfor d in /path/to/devflow/skills/*/; do ln -s \"${d%/}\" ~/.config/opencode/skills/\"$(basename \"$d\")\"; done\n```\n\n**Cursor** — reads plugin manifest from the repo directly (no setup needed).\n\n**Gemini CLI** — reads `GEMINI.md` and `gemini-extension.json` from the repo directly.\n\n**Config** (optional):\n```bash\nmkdir -p ~/.devflow\ncp /path/to/devflow/config.default.yaml ~/.devflow/config.yaml\n```\n\n## Updating\n\n```bash\ncd /path/to/devflow && git pull\n```\n\nCodex, opencode, Cursor, and Gemini use symlinks or direct reads — changes propagate instantly.\nClaude Code uses a cached copy — re-run `install.sh` after pulling to update the cache.\n\n## Uninstalling\n\n```bash\n/path/to/devflow/install.sh --uninstall\n```\n\nOr manually:\n```bash\nrm ~/.agents/skills/devflow                                          # Codex\nrm -rf ~/.devflow                                                     # Config (optional)\n```\n\n## Multi-Agent Coexistence\n\nDevflow works seamlessly across multiple agentic apps on the same machine:\n\n- **Single source of truth**: the git repo — clone it anywhere, symlinks point back\n- **Shared config**: `~/.devflow/config.yaml` is read by all agents\n- **Symlinks**: Codex (`~/.agents/skills/devflow`) points back to the repo\n- **Direct reads**: Cursor and Gemini read from the repo directory; Claude Code uses a plugin-cache copy (re-run `install.sh` after `git pull`)\n- **Session files**: stored under `RUN_DIR`, a deterministic path derived from a hash of\n  the repo root under `${DEVFLOW_RUN_HOME:-$HOME/.devflow/run}` (namespaced per project, never\n  inside the repo, and never under a write-mode call's default writable roots) —\n  `bash scripts/devflow-runner.sh dir` always resolves back to the same directory\n  for a given checkout; run it to recover the path rather than guessing. Abandoned run dirs\n  are auto-reclaimed after `DEVFLOW_RUN_TTL_DAYS` (default 7) days of inactivity. Only dirs\n  that are ours (uid match) and past the TTL are pruned, and the age is measured from last use,\n  so a steadily-reused checkout is never swept. Concurrency is a convention, not an enforced\n  guarantee: one devflow pipeline per checkout at a time, parallel work in git worktrees\n- **Per-project overrides**: `.devflow.yaml` in project root overrides global config\n\n## Configuration\n\nGlobal config: `~/.devflow/config.yaml`\nProject override: `.devflow.yaml` in project root\n\n### Which tool reviews\n\nThe point of an external review is a **different** tool's eyes, so the reviewing backend is\npicked by which tool is hosting the run — not by one global switch:\n\n```yaml\nexternal_review:\n  from_claude: codex     # hosted by Claude Code → external review via codex\n  from_codex: none       # hosted by Codex → internal personas only\n```\n\n`none` means the host runs its internal persona reviewers and the orchestrator decides from\nthose alone. `backend:` remains the fallback for a host not listed, and still selects the\nimplementer backend for handoff calls:\n\n```yaml\nbackend: claude   # or: codex\n```\n\nYou can also override per-project by creating `.devflow.yaml` in the project root with just:\n```yaml\nbackend: codex   # this project uses Codex regardless of global setting\n```\n\n### Full Config Reference\n\n```yaml\nbackend: claude           # codex | claude — change this one line to switch\n\nclaude:\n  reviewer:\n    model: \"opus\"          # alias for claude-opus-4-6\n    effort: \"max\"          # --effort max (thorough reviews)\n  implementer:\n    model: \"sonnet\"        # alias for claude-sonnet-4-6\n    effort: \"high\"         # --effort high (fast implementation)\n  session_reuse: true\n\ncodex:\n  command_path: \"\"         # \"\" = auto-resolve & validate (exec --json), prefer Homebrew,\n                           # skip NVM-shadowed old CLI; set absolute path to force\n  reviewer:\n    model: \"gpt-5.5\"\n    effort: \"high\"         # via -c 'model_reasoning_effort=\"...\"'\n  implementer:\n    model: \"gpt-5.5\"\n    effort: \"high\"\n  session_reuse: true\n\nautonomy: attended         # attended | unattended\noutput_dir: \"docs/devflow/reports\"\n```\n\n> The only keys that change behavior are `backend`, `model`, `effort`, `command_path`, `session_reuse`, `autonomy`, `output_dir`, `review_personas`, and `integrations`. The CLI invocation (flags, read-only vs write posture, session capture) is built by the runner — see `skills/using-devflow/references/cross-tool-runner.md`.\n\n**Environment overrides** (not config-file keys): `DEVFLOW_RUN_TTL_DAYS` (default `7`) sets how many idle days before an abandoned per-project run dir under `${DEVFLOW_RUN_HOME:-$HOME/.devflow/run}` is auto-reclaimed on the next `dir` call; set it to a non-number to disable the sweep entirely.\n\n### Model Tiers\n\n| Role | claude backend | codex backend | Purpose |\n|------|---------------|---------------|----------|\n| Reviewer | opus / max | gpt-5.5 / high | Thorough plan and code reviews |\n| Implementer | sonnet / high | gpt-5.5 / high | Fast, capable code generation |\n| Orchestrator | (host model) | (host model) | The agent running devflow (e.g., opus-4.6) |\n\n### Session Reuse\n\nWhen `<backend>.session_reuse: true`, devflow captures the session ID on the first call and resumes subsequent iterations in the same session. This:\n- Saves ~20k tokens per resumed call\n- Preserves review context across iterations\n- Enables session handoff between phases (plan review → implementation review)\n\nSession capture is done by the runner via `scripts/devflow-json.py` (a stdlib-only,\nfail-closed JSON extractor — no `jq` dependency), and differs by backend:\n- **claude**: `session_id` from the `--output-format json` object, resume with `--resume <id>`\n- **codex**: `thread_id` from the `--json` JSONL, resume with `exec resume <id>` using the\n  same full flag shape as a fresh call (`-c model_reasoning_effort` before `exec`,\n  `--json`, `-m`)\n\n### External Calls Are Non-Blocking\n\nExternal reviews are launched in the background and polled via their event stream\n(adaptive backoff, ~8–10 min hard-cap), so they never die at a host's command timeout.\nThe codex binary is auto-resolved and validated (`exec --json` support; Homebrew\npreferred; NVM-shadowed CLIs skipped) — override with `codex.command_path`. The skill reads\n`.devflow.yaml` and passes `backend`/`model`/`effort` as explicit flags on each call; the\nrunner resolves the trusted binary itself (never from a flag). The\ncanonical procedure lives in `skills/using-devflow/references/cross-tool-runner.md`.\n\n## Skills\n\n| Skill | Description | When to use |\n|-------|-------------|-------------|\n| `devflow:plan` | Planning with cross-tool review loop | \"Plan this feature\" |\n| `devflow:implement` | Implementation with cross-tool review | \"Implement this plan\" |\n| `devflow:review` | Cross-tool review of existing code | \"Review my changes\" |\n| `devflow:run` | Full pipeline (plan → implement → review) | \"Build this feature end-to-end\" |\n\n## Relationship with Superpowers\n\nDevflow and superpowers are **complementary, not competing**:\n\n| Level | What | Who |\n|-------|------|-----|\n| Cross-tool orchestration | Which tool does which step, external review loops, session management | **devflow** |\n| Single-tool process | How to brainstorm, plan, write tests, review code within one agent | **superpowers** |\n\n### Priority rules\n\n- **User says \"devflow\"** or mentions cross-tool review → devflow orchestrates, superpowers used internally\n- **User says \"plan this feature\"** without mentioning cross-tool → superpowers only\n- **Never invoke both** devflow:plan AND superpowers:writing-plans for the same task — devflow already delegates to superpowers\n\n### Without superpowers\n\nDevflow works standalone — cross-tool orchestration, session reuse, and external reviews are fully independent. Internal process quality is lower (no brainstorming skill, no TDD enforcement), but devflow's core value is unaffected.\n\nIf superpowers updates (new skills, improved TDD), devflow automatically benefits because it delegates rather than reimplements.\n\n## File Structure\n\n```\ndevflow/\n├── install.sh                      # Installer with --status / --uninstall\n├── config.default.yaml             # Default config template\n├── README.md                       # This file\n├── GEMINI.md                       # Gemini CLI instructions\n├── gemini-extension.json           # Gemini extension manifest\n├── .claude-plugin/plugin.json      # Claude Code plugin manifest\n├── .cursor-plugin/plugin.json      # Cursor plugin manifest\n├── .codex/INSTALL.md               # Agent-readable install instructions\n├── skills/                         # Skill definitions (shared by all agents)\n│   ├── using-devflow/SKILL.md      # Entry point — skill discovery\n│   ├── using-devflow/references/   # Platform tool mappings + cross-tool-runner.md (canonical external-call procedure)\n│   ├── devflow-plan/SKILL.md       # Plan with cross-tool review\n│   ├── devflow-implement/SKILL.md  # Implement with cross-tool review\n│   ├── devflow-review/SKILL.md     # Standalone cross-tool review\n│   ├── devflow-review/references/  # review-personas.md (persona lenses + tiers)\n│   └── devflow-run/SKILL.md        # Full pipeline orchestrator\n├── scripts/                        # The one load-bearing sh + its helpers\n│   ├── devflow-runner.sh           # Supervises the long backend CLI: dir + run-external\n│   └── devflow-json.py             # stdlib-only JSON extractor (verdict/session), fail-closed\n└── test/                           # Offline, deterministic harness (see test/README.md)\n    ├── run.sh                      # Test runner\n    ├── smoke-real-codex.sh         # opt-in real-CLI smoke test (needs token, not in CI)\n    ├── cases/                      # One file per case (10-dir, 30-invoke, …)\n    └── lib/                        # Fakes (fake-codex, fake-claude) + assert/sandbox helpers\n```\n\nAfter installation:\n```\n/path/to/devflow/                              # Git repo = single source of truth\n~/.devflow/config.yaml                         # Global configuration\n~/.agents/skills/devflow                       # Codex: symlink → skills/\n~/.claude/plugins/cache/devflow-local/...       # Claude Code: plugin cache\n```\n\n## Development\n\nRun the offline test harness — no API token, no network. It drives the real `scripts/devflow-runner.sh` against fake codex/claude stubs in throwaway sandboxes:\n\n```bash\nbash test/run.sh            # all cases\nbash test/run.sh 30 60      # only cases matching these prefixes\n```\n\nCI runs the same suite on Linux and macOS on every push and PR. See [`test/README.md`](test/README.md) for how the harness stays honest and the seams it exposes.\n\n## License\n\nMIT\n",
  "bytes": 13340,
  "sha": "b287f1f15b0deb37c2840f5b6224ac1a173b93e90ec1eaefa0cac87ee53b2dbb",
  "repo_slug": "yuriykuzin/devflow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_yuriykuzin_devflow_015a03f7/readme"
}