- Home
- Skills
- Agents & Orchestration
- Multi-Agent Story Flow: Claude Builds, Codex Reviews
Works with the AI Agents you already use
Multi-Agent Story Flow: Claude Builds, Codex Reviews
Ship one user story at a time with AI coding agents and stop your agent grading its own homework: an isolated Git worktree, an exit code that decides done, and a different model reviewing read-only.
Free
Multi-Agent Story Flow: Claude Builds, Codex Reviews
Example session with this skill installed
start story CAN-001
- Read your context and instructions
- Compiled the multi-agent story flow
Summary
CAN-001 went from spec to a verified, independently reviewed branch. Claude Code built it, Codex reviewed it in a read-only session, and the flow stopped at the human PR gate. Nothing was pushed.
Real run from our install test on a small Python library, lightly trimmed.
| Stage | Result |
|---|---|
| Worktree | .claude/worktrees/CAN-001 on branch worktree-CAN-001 from main. Main checkout untouched. |
| Build (Claude Code) | Added word_count(text) plus 5 tests in tests/test_words.py, committed bafe52d. 5 turns, $0.42. git push, merge, rebase, reset and gh were blocked by permissions. |
| Verify before review | scripts/verify-project.sh exit 0, 7 tests OK. |
| Review (Codex, read-only) | VERDICT: PASS. No P0, P1 or P2 findings. Checked empty, whitespace-only and mixed whitespace input, and that char_count is unchanged. |
| Fix pass | Skipped: the review passed. |
| Final verify | exit 0, VERIFY PASSED bafe52d. |
Done-when status
-
python3 -m unittest discover -s tests -vpasses, includingword_count("") == 0andword_count(" a b c ") == 3 -
bash scripts/verify-project.shexits 0 onworktree-CAN-001 -
VERDICT: PASSin.claude-flow/CAN-001/review.md - You read the diff, push and open the PR
Next step
gh pr create --base main --head worktree-CAN-001 --fill
Connects securely to your tools. The creator never sees your data.
About this skill
What it does
The problem. Agent-assisted delivery fails in the same places: the agent says the work is complete when nothing ran, the reviewer is the same session that wrote the code, refactors drift into files nobody asked about, and the agent pushes or merges while you are still reading the diff.
What the skill does. It runs one story through a fixed pipeline across two independent AI agents. Your builder agent (default claude, configurable to codex, gemini, opencode, or an IDE agent like Cursor, Google Antigravity, or Windsurf) implements and commits inside its own Git worktree. Your project's verifier must exit 0. A second independent agent (default codex, configurable to claude, gemini, or opencode) reviews the branch diff in a read-only session and writes VERDICT: PASS or VERDICT: CHANGES_REQUESTED. The builder gets at most one fix pass, then verification and review run again. The script prints a suggested gh pr create and stops.
Why not just prompt for it. A prompt asks for discipline; this skill enforces it with mechanisms. Verification is an exit code, review is a separate process with no write access, the worktree isolates the change, and push, PR and merge are never run.
Use it when you want two different AI models or tools to check each other's work on a story with executable acceptance criteria.
Known limits.
- Automated CLI runs need the configured
BUILDER_CLIandREVIEWER_CLIlogged in with quota. - If you build inside an IDE agent (Cursor, Antigravity, Windsurf) or if the review stage stops on quota, run
story.sh <ID> --from review; it skips only the build and reruns verification before review. - Visual or UX judgments cannot be checked by the verifier; record them as human gates.
Which one should I pick?
- Multi-Agent Story Flow (this skill): you have two agent CLIs (for example Claude Code and Codex) and want a different model to review the builder's work. Cross-model review catches blind spots the author model shares with itself.
- Dual-Session Story Flow: you use one tool or subscription. It runs an isolated builder session and a separate read-only reviewer session on the same agent, so it is cheaper and simpler to set up.
Where it fits
- Project Setup, once per repository: plan, backlog, verifier
- Multi-Agent Story Flow (this skill) or Dual-Session Story Flow, once per story: build, verify, independent review
- You: read the diff, push, open the PR, merge
- Merged Worktree Cleanup, after the merge: remove the worktree and branch
Get more from every story with Project Setup. Without it, the flow guesses your checks from stack markers. With it, every story comes from a PRD-backed, risk-first epic backlog with acceptance criteria, and a project-owned verifier decides when it is done.
How to use
-
Connect your agent to the Agensi MCP and ask for this skill. Keep one shared copy in
~/.agents/skills/start-story-multi-agent: Codex CLI and Gemini CLI read it directly. Point other agents at the same folder instead of making a second copy:- Claude Code:
ln -sfn ~/.agents/skills/start-story-multi-agent ~/.claude/skills/start-story-multi-agent - Cursor:
ln -sfn ~/.agents/skills/start-story-multi-agent ~/.cursor/skills/start-story-multi-agent - Antigravity:
ln -sfn ~/.agents/skills/start-story-multi-agent ~/.gemini/config/skills/start-story-multi-agent - Windows:
mklink /J "%USERPROFILE%\.claude\skills\start-story-multi-agent" "%USERPROFILE%\.agents\skills\start-story-multi-agent"
Have the ZIP instead?
unzip -o start-story-multi-agent-1.1.1.zip -d ~/.agents/skills/start-story-multi-agent. Keep only this one copy: a second install of the same skill can make the agent pick the wrong one. - Claude Code:
-
Add
scripts/verify-project.shwith your real lint, test and build commands (theproject-setupskill can scaffold it). -
Say
start story ABC-123. OverrideBUILDER_CLIorREVIEWER_CLI(claude,codex,gemini,opencode) whenever you want a different model pair. -
Read the diff, push, open the PR and merge yourself.
Requirements
git, bash 3.2+, tee, your chosen agent CLIs (claude, codex, gemini, or opencode; jq when BUILDER_CLI=claude), and your project's own toolchain. macOS, Linux, or Windows through WSL.
Changelog
1.1.1
- A Claude Code builder now runs headless with scoped permissions: it can edit and commit inside the story worktree, while
git push,git merge,git rebase,git resetandghare denied by Claude Code itself. - A Claude Code reviewer can read the branch diff (
git diff,log,show,status) and still cannot write. - If an agent stops early (for example on a usage limit), the flow says which stage and agent failed and shows the agent's own message.
- Codex progress is shown as one readable line per step instead of raw JSON.
1.1.0
- Configurable
BUILDER_CLIandREVIEWER_CLIacrossclaude,codex,geminiandopencode, plus--from reviewfor IDE agents.
Works best with: Project Setup (scaffolds the verifier and backlog) and Merged Worktree Cleanup (tears down the worktree after you merge).
Needs your chosen builder and reviewer CLIs (claude, codex, gemini or opencode) logged in with quota. At most one automated fix pass per story; anything left after it goes to you. If a stage stops (for example on a usage limit), the flow names the stage and the agent's error; resume with story.sh <ID> --from review. Visual or UX judgments are not machine-checkable and stay human gates. Push, PR and merge are always yours.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
This skill has been used 3 times.
Trust & safety
Security scan
Security scan passed 15 days ago
- Free with an Agensi account
Requires
Permissions
File Scopes
Network: `git fetch origin` (skip with `FETCH_BASE=0`), your configured `BUILDER_CLI` for implementation, and your configured `REVIEWER_CLI` for read-only review. Writes: the worktree at `.claude/worktrees/<ID>` and traces under `.claude-flow/<ID>/`. The optional setup step copies hooks to `.claude/hooks/format-file.sh` and `.git/hooks/pre-commit`. Never: pushes, opens a pull request, or merges. A Claude Code builder runs with git push, merge, rebase, reset and gh denied.