Story Flow: Claude builds, Codex reviews in worktrees
Stop your coding agent from grading its own homework: one story, one worktree, an exit code that decides done, and an independent read-only reviewer.
Free
Works with the AI Agents you already use
Claude Code
Cursor
Codex CLI
Muse
Dots+22 moreClaude CodeCursorCodex CLIMuseDots
OpenClaw
Manus
Grok
Grok Bot+18 agentsStory Flow: Claude builds, Codex reviews in worktrees
Example session with this skill installed
start story CAN-001
- Read your context and instructions
- Compiled the story flow
Summary
CAN-001 was built and verified in its own worktree. The Codex review could not run because the Codex account was out of quota, so the pipeline stopped at that gate instead of reporting done. Nothing was pushed.
Real run from our install test, lightly trimmed. It shows the failure gate doing its job.
| Stage | Result |
|---|---|
| Worktree | .claude/worktrees/CAN-001 on branch worktree-CAN-001, based on origin/main. Main checkout untouched. |
| Spec | specs/CAN-001.md written from the backlog acceptance criteria. Scope: one test, no production code. |
| Build | Implementer committed cb9cea7: adds test_mixed_whitespace, asserting word_count(" a\tb\n") == 2. |
| Verify before review | scripts/verify-project.sh exit 0, 3 tests OK. Focused -k test_mixed_whitespace passed. |
| Codex review | Failed: usage limit reached. Trace in .claude-flow/CAN-001/review-trace.jsonl. Fix pass and final verify skipped. |
Done-when status
- Focused test command exits 0
-
bash scripts/verify-project.shexits 0 onworktree-CAN-001 -
VERDICT: PASSin.claude-flow/CAN-001/review.md: no review yet - Human opens the PR and merges
The agent did not review the change itself to stand in for Codex: the flow requires an independent reviewer.
Next steps
bash <skill-dir>/scripts/story.sh CAN-001 --from review
Rerun the review once Codex has quota. It skips the build, reruns verification, then hands the branch to Codex.
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. Claude Code implements and commits inside its own Git worktree. Your project's verifier must exit 0. Codex CLI reviews the branch diff in a read-only sandbox and writes VERDICT: PASS or VERDICT: CHANGES_REQUESTED. Claude 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 a story is material enough that an independent review raises confidence, and its acceptance criteria can be written as commands.
Known limits.
- Needs both the
claudeandcodexCLIs, logged in, with quota for both. - If the review stage fails (for example on Codex quota), resume with
story.sh <ID> --from review; it skips only the build and reruns verification first. - Visual or UX judgments cannot be checked by the verifier; record them as human gates.
Where it fits
- Project Setup, once per repository: plan, backlog, verifier
- Story Flow or Codex Dual-Session Story Flow (this skill), 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
Project Setup is optional but recommended: without it the story flows fall back to auto-detected checks, with no backlog or project-owned verifier.
How to use
- Unzip into your skills folder and say
set up this repo for the story flowonce per repository. - Add
scripts/verify-project.shwith your real lint, test and build commands (the Project Setup skill can scaffold it). - Say
start story ABC-123. The story ID must matchPREFIX-nnn. - Read the diff, push, open the PR and merge yourself.
Requirements
git, claude, codex, jq, tee, and your project's own toolchain. macOS, Linux, or Windows through WSL. Bash 3.2 is enough.
Works best with: Project Setup (scaffolds the verifier and backlog) and Merged Worktree Cleanup (tears down the worktree after you merge).
How to use
Skills on Agensi run inside your AI agent. Copy the prompt, paste it into your agent, and it connects to Agensi and installs this skill for you. If a payment is needed, your agent shows it to you first.
Reviews
2 people have installed this skill.
Trust & safety
Security scanned
Verified clean 4 days ago
- Free to download with an account
Requires
Git