- Home
- Skills
- Agents & Orchestration
- Dual-Session Story Flow: AI Builder + Read-Only Reviewer
Works with the AI Agents you already use
Dual-Session Story Flow: AI Builder + Read-Only Reviewer
Build each feature with two separate AI sessions on the tool you already use: one implements in an isolated worktree, one reviews read-only, and a verifier exit code decides when it is done.
Free
Dual-Session Story Flow: AI Builder + Read-Only Reviewer
Example session with this skill installed
Run story CAN-002 with the dual-session flow.
- Read your context and instructions
- Compiled the dual-session story flow
Summary
CAN-002 is implemented, verified and independently reviewed in its own worktree. Verdict: PASS. The flow stopped before push; the branch is ready for your review.
Real run from our install test on a small Python library with AGENT_CLI=codex, lightly trimmed.
| Stage | Result |
|---|---|
| Worktree | .agent-worktrees/CAN-002 on branch codex/CAN-002 from main. Main checkout untouched. |
| Implementer session (Codex, workspace-write) | Added line_count(text) with str.splitlines() semantics and tests/test_lines.py, committed 61c72dd (3 files, +35). Reported checks passed and no unresolved risks. |
| Verify before review | scripts/verify-project.sh exit 0, 5 tests OK. |
| Reviewer session (Codex, read-only) | Compared the diff with specs/CAN-002.md, reran both acceptance commands, checked empty input and a trailing newline. VERDICT: PASS, no P0, P1 or P2 findings. |
| Fix pass | Skipped: the review passed. |
| Final verify | exit 0, VERIFY PASSED 61c72dd. |
Done-when status
-
python3 -m unittest discover -s tests -vpasses, includingline_count("") == 0,line_count("a") == 1andline_count("a\nb\n") == 2 -
bash scripts/verify-project.shexits 0 oncodex/CAN-002 -
VERDICT: PASSin.codex-flow/CAN-002/CAN-002-review.md - You read the diff, push and open the PR
Next step
gh pr create --base main --head codex/CAN-002 --fill
Connects securely to your tools. The creator never sees your data.
About this skill
What it does
The problem. A single AI coding session that writes and reviews its own code agrees with itself. Long review loops burn tokens without converging, and an agent with push rights can ship before you look.
What the skill does. It starts a fresh implementer session with write access inside a dedicated Git worktree, requires it to commit spec, code and tests, runs your verifier, then starts a separate reviewer session in read-only mode. Works out of the box with Codex CLI (AGENT_CLI=codex), and supports Claude Code (AGENT_CLI=claude), Gemini CLI (AGENT_CLI=gemini), OpenCode (AGENT_CLI=opencode), or IDE sessions in Cursor, Google Antigravity, and Windsurf via --from review. Findings must name severity, file and line, a failure scenario and a minimal fix. At most one fix pass and one re-review follow.
Why not just prompt for it. The isolation is real: separate processes, separate context windows, read-only review enforcement, a separate worktree, and an exit code as the gate.
Use it when you use one primary AI coding tool or subscription and still want an independent review on a story with checkable acceptance criteria.
Known limits.
- Quota is consumed by two sessions per story, more when a fix pass runs.
- If the review stage stops (for example on quota) or you implemented the story interactively in an IDE, resume with
story.sh <ID> --from review; it skips only the build and reruns verification first. - Non-mechanical judgments must be recorded as human gates.
Which one should I pick?
- Multi-Agent Story Flow: 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 (this skill): 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 or 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
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/dual-session-story-flow: 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/dual-session-story-flow ~/.claude/skills/dual-session-story-flow - Cursor:
ln -sfn ~/.agents/skills/dual-session-story-flow ~/.cursor/skills/dual-session-story-flow - Antigravity:
ln -sfn ~/.agents/skills/dual-session-story-flow ~/.gemini/config/skills/dual-session-story-flow - Windows:
mklink /J "%USERPROFILE%\.claude\skills\dual-session-story-flow" "%USERPROFILE%\.agents\skills\dual-session-story-flow"
Have the ZIP instead?
unzip -o dual-session-story-flow-1.1.1.zip -d ~/.agents/skills/dual-session-story-flow. 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 checks. -
Write
specs/<ID>.mdfrom the bundled template, then run the story (AGENT_CLI=codexby default, orAGENT_CLI=claude|gemini|opencode). The ID must matchPREFIX-nnn. -
Review the diff, push, open the PR and merge yourself.
Requirements
git, bash 3.2+, tee, at least one supported agent CLI (codex, claude, gemini, or opencode), and your project's toolchain. macOS, Linux, or Windows through WSL.
Changelog
1.1.1
- With
AGENT_CLI=claude, the builder session now runs headless with scoped permissions: it can edit and commit inside the story worktree, whilegit push,git merge,git rebase,git resetandghare denied by Claude Code itself. - The Claude reviewer session can read the branch diff 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
AGENT_CLIsupportscodex,claude,geminiandopencode, plus--from reviewfor IDE agents.
Works best with: Project Setup (verifier and backlog) and Merged Worktree Cleanup (after the merge).
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Agents & Orchestration.
Runs both sessions on one agent CLI (codex, claude, gemini or opencode); for a different model as reviewer, use Multi-Agent Story Flow. Two sessions per story, more with a fix pass. At most one fix pass and one re-review, then unresolved findings come back 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. 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 buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
1 use
Times used to date
Free to use
No account required to browse
Trust & safety
Security scan
Security scan passed 15 days ago
- Free with an Agensi account
- Software
Git
Needs one of Codex CLI, Claude Code, Gemini CLI or OpenCode.
Permissions
File Scopes
Network: `git fetch` (skip with `FETCH_BASE=0`), plus your chosen `AGENT_CLI` for the implementer and read-only reviewer sessions. Writes: the worktree at `.agent-worktrees/<ID>` and traces under `.codex-flow/<ID>/`. Never: pushes, opens a pull request, or merges. With `AGENT_CLI=claude`, git push, merge, rebase, reset and gh are denied to the builder.