Multi-Agent Story Flow: Build, Verify & Read-Only Review

    2

    Stop your coding agent from grading its own homework. One story, one isolated Git worktree, an exit code that decides "done", and a separate cross-model reviewer in a read-only session.

    Free

    3 uses5.0 (1 review)

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Multi-Agent Story Flow: Build, Verify & Read-Only Review

    Example session with this skill installed

    start story CAN-001

    • Read your context and instructions
    • Compiled the multi-agent 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.

    StageResult
    Worktree.claude/worktrees/CAN-001 on branch worktree-CAN-001, based on origin/main. Main checkout untouched.
    Specspecs/CAN-001.md written from the backlog acceptance criteria. Scope: one test, no production code.
    BuildImplementer committed cb9cea7: adds test_mixed_whitespace, asserting word_count(" a\tb\n") == 2.
    Verify before reviewscripts/verify-project.sh exit 0, 3 tests OK. Focused -k test_mixed_whitespace passed.
    Codex reviewFailed: 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.sh exits 0 on worktree-CAN-001
    • VERDICT: PASS in .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 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_CLI and REVIEWER_CLI logged 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

    1. Project Setup, once per repository: plan, backlog, verifier
    2. Multi-Agent Story Flow (this skill) or Dual-Session Story Flow, once per story: build, verify, independent review
    3. You: read the diff, push, open the PR, merge
    4. 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

    1. Unzip once into a shared folder that every agent can use: mkdir -p ~/.agents/skills/start-story-multi-agent && unzip -o start-story-multi-agent-<version>.zip -d ~/.agents/skills/start-story-multi-agent. Codex CLI and Gemini CLI read ~/.agents/skills directly. Point the others at the same folder instead of making a second copy:

      • Claude Code: mkdir -p ~/.claude/skills && ln -sfn ~/.agents/skills/start-story-multi-agent ~/.claude/skills/start-story-multi-agent
      • Cursor: mkdir -p ~/.cursor/skills && ln -sfn ~/.agents/skills/start-story-multi-agent ~/.cursor/skills/start-story-multi-agent
      • Antigravity: mkdir -p ~/.gemini/config/skills && ln -sfn ~/.agents/skills/start-story-multi-agent ~/.gemini/config/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.

    2. Add scripts/verify-project.sh with your real lint, test and build commands (the project-setup skill can scaffold it).

    3. Say start story ABC-123. Override BUILDER_CLI or REVIEWER_CLI (claude, codex, gemini, opencode) whenever you want a different model pair.

    4. 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.

    Works best with: Project Setup (scaffolds the verifier and backlog) and Merged Worktree Cleanup (tears down the worktree after you merge).

    Needs both the claude and codex CLIs, logged in, with quota for both. At most one automated fix pass per story; anything left after it goes to you. If the review stage fails, 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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    5.0
    1 review
    5
    1
    4
    0
    3
    0
    2
    0
    1
    0

    This skill has been used 3 times.

    Trust & safety

    Security scan

    Security scan passed 7 days ago

    • Free with an Agensi account

    Requires

    Git
    Claude Code CLI
    Codex CLI
    jq

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Network Access
    Environment Variables

    File Scopes

    .claude/worktrees/**
    .claude-flow/**
    .claude/hooks/format-file.sh
    .git/hooks/pre-commit
    specs/**

    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.

    Listed16 days ago
    Updated7 days ago

    What's inside

    Frequently Asked Questions

    No. It stops before push, PR creation and merge, by design, and prints a suggested gh pr create command for you to run after you have read the diff.

    No. Each story gets its own Git worktree and branch under .claude/worktrees/<ID>, created from the base branch without checking out or pulling your primary worktree.

    Any stack whose checks run as one command that exits non-zero on failure, provided as scripts/verify-project.sh. Before you write one, Rust, Node.js, Go, Java, Python and .NET projects are detected automatically from their build files.

    Yes. Set SOT_QUERY to one narrow query or issue URL. The agent reads it once, writes the local spec, and works from that spec without further remote fetches.

    Claude gets exactly one committed fix pass, then verification and a Codex re-review run again. Anything still unresolved after that comes back to you instead of starting an agent-to-agent loop.