Review

Derive slug from the branch name (e.g. feature/binary-bundling → binary-bundling). Derive WORKTREE_PARENT = dirname(<WORKTREE>). Per-cycle implementation worktrees are siblings: <WORKTREE_PARENT>/task-review-<slug>-<N>.

Working directory

All operations in this phase must happen inside <WORKTREE> (or per-cycle sibling worktrees), never in the main repository working tree.

Rules that apply to this coordinator and to every agent it invokes:

• File reads/writes: <WORKTREE>/<relative-path>
• Git commands on the feature branch: git -C "<WORKTREE>" <command>
• Cargo commands: cd "<WORKTREE>" && cargo <command>
• Per-cycle worktrees: created at <WORKTREE_PARENT>/task-review-<slug>-<N>
• Every agent message must include WORKTREE: <worktree_path> with the appropriate path so agents never touch the main repository working tree.
• The PR URL is read-only context that gives the Review Group a pointer to what is under review. All code work targets the feature branch in <WORKTREE>.

Review Add-On format

Each cycle that produces VALID findings records them in an OpenSpec Add-On file:

<WORKTREE>/openspec/changes/<openspec_id>/review-addon-<N>.md

# Review Add-On: Cycle <N>

## Valid Findings

### RC<N>-<seq>: <short title>
**Severity:** critical | major | minor
**File:** <relative-file-path>:<line>
**Finding:** <what is wrong or missing>
**Required fix:** <what must change, specific enough for Developer to act on>

### RC<N>-<seq>: ...

The Implementation Group reads this file. After implementation it is retained as a permanent record in the feature branch.

Agent coordination protocol

Attempt team-based coordination:

TeamCreate({ name: "review-team",
             agents: ["investigator", "contrarian", "developer",
                      "simplifier", "test-developer"] })

Fall back to sequential Agent tool calls if TeamCreate fails. Do not retry teams more than once.

Agent Handoff format

--- AGENT HANDOFF ---
From:     <agent name>
To:       <next agent>
Status:   complete | blocked
Branch:   <branch name>
Done:
  - <key action taken>
Decisions:
  - <decision + rationale, or "none">
Findings:
  - <finding id> — <severity> — <one-line description> — VALID | INVALID
Open:
  - <item + owner, or "none">
Pass forward:
  <2–3 sentences of critical context for the next agent>
--- END HANDOFF ---

Review cycle

Each review cycle runs the following steps. Start with N=1.

Step 1 — Investigator: code review

Invoke investigator with the design doc, branch diff, and OpenSpec tasks. Task:

Working directory: <WORKTREE> — read files only within this directory. Do not access the main repository working tree. WORKTREE: <worktree_path> PR: <pr_url>

Read the design document at <design_doc>. Read all files changed on this feature branch: git -C "<WORKTREE>" diff main...HEAD Read the OpenSpec tasks at <WORKTREE>/openspec/changes/<openspec_id>/tasks.md. If prior review add-ons exist, read them to understand what was already addressed.

Perform a thorough code review against the design specification:

• Does every implemented piece match its design decision exactly?
• Are there correctness bugs, edge-case gaps, or security issues?
• Does the implementation cover all OpenSpec tasks completely and correctly?
• Are there simplicity, maintainability, or logging problems worth raising?
• Are there any regressions relative to prior review cycles?

Produce an Agent Handoff listing every finding with:

• A unique id: RC<N>-<seq>
• Severity: critical | major | minor
• File and line reference
• What is wrong (finding) — do not propose fixes, only findings

Step 2 — Contrarian: challenge and agree

Invoke contrarian with the Investigator handoff. Task:

Working directory: <WORKTREE> — read files only within this directory. Do not access the main repository working tree. WORKTREE: <worktree_path>

Review the Investigator's findings for cycle N. For each finding, read the actual code at the cited location to independently confirm or refute it:

• Mark VALID if the code confirms the finding — the problem genuinely exists.
• Mark INVALID if the code disproves the finding — provide the evidence (exact file:line) that shows the concern does not apply.

For VALID findings, confirm the required fix is clear and appropriately scoped. Do not accept vague findings: if a finding is correct but the required fix is underspecified, strengthen the fix description before marking it VALID.

If there are zero VALID findings: declare the PR approved.

Produce an Agent Handoff listing:

• All VALID findings with confirmed fix descriptions
• All INVALID findings with disproving evidence
• Your verdict: approved | changes required

Step 3 — Route verdict

If Contrarian declares the PR approved (zero VALID findings): Skip to Phase Completion below.

If there are VALID findings:

1. Write the Review Add-On file:

   <WORKTREE>/openspec/changes/<openspec_id>/review-addon-<N>.md
   

   Using the Review Add-On format above. Include only VALID findings.

2. Commit the Add-On to the feature branch:

   git -C "<WORKTREE>" add \
     openspec/changes/<openspec_id>/review-addon-<N>.md
   git -C "<WORKTREE>" commit \
     -m "review(cycle-<N>): record <count> valid findings"
   

3. Proceed to Implementation Group (Step 4).

Step 4 — Create implementation worktree

git -C "<WORKTREE>" worktree add \
  "<WORKTREE_PARENT>/task-review-<slug>-<N>" \
  -b task/review-<slug>-<N>

Step 5 — Developer: implement review findings

Invoke developer with the Review Add-On and feature context. Task:

Working directory: <WORKTREE_PARENT>/task-review-<slug>-<N> (branch: task/review-<slug>-<N>) — do not read or write any files outside this directory. WORKTREE: <WORKTREE_PARENT>/task-review-<slug>-<N>

Read the review add-on at: <WORKTREE>/openspec/changes/<openspec_id>/review-addon-<N>.md

Implement every VALID finding listed (all RC<N>-* items). Follow project conventions: Rust 2021, tokio, anyhow for app code, thiserror for library crates, tracing for logging. Commit your changes. Produce an Agent Handoff.

Step 6 — Simplifier: remove complexity from the fixes

Invoke simplifier with the Developer handoff. Task:

Working directory: <WORKTREE_PARENT>/task-review-<slug>-<N> (branch: task/review-<slug>-<N>) — do not read or write any files outside this directory. WORKTREE: <WORKTREE_PARENT>/task-review-<slug>-<N>

Review changes introduced in this review cycle on branch task/review-<slug>-<N>. Remove dead code, premature abstractions, unnecessary complexity introduced by the review fixes. Do not change behaviour. Commit your changes. Produce an Agent Handoff.

Step 7 — Test Developer: update or add tests

Invoke test-developer with the Simplifier handoff. Task:

Working directory: <WORKTREE_PARENT>/task-review-<slug>-<N> (branch: task/review-<slug>-<N>) — do not read or write any files outside this directory. WORKTREE: <WORKTREE_PARENT>/task-review-<slug>-<N>

Review changes introduced in this review cycle. For each fix: does the existing test suite cover the corrected behaviour? If not, add or update tests to cover it. Think adversarially — each fix addresses a real bug; write a test that would have caught it. Run cd "<WORKTREE_PARENT>/task-review-<slug>-<N>" && cargo test (or pytest for Python files) to confirm all tests pass. Commit your changes. Produce an Agent Handoff with the test results (pass/fail).

Step 8 — Merge, push, and clean up

If all tests pass:

git -C "<WORKTREE>" merge --no-ff task/review-<slug>-<N> \
  -m "fix(review-cycle-<N>): implement <count> review findings"
git -C "<WORKTREE>" worktree remove \
  "<WORKTREE_PARENT>/task-review-<slug>-<N>"
git -C "<WORKTREE>" push origin <branch>

If tests fail: route the Test Developer handoff back to Developer (Step 5) for a targeted fix. This sub-loop runs a maximum of 3 times per cycle before surfacing the failure to the user.

Step 9 — Next cycle

Increment N. Return to Step 1 (Investigator re-reviews the updated branch).

Maximum review cycles: 5. If the Review Group has not approved after 5 cycles, surface the remaining VALID findings to the user along with a summary of what was fixed and what remains unresolved. Do not loop further.

Team cleanup

If TeamCreate succeeded earlier, shut down all agents and delete the team before producing the Phase Handoff:

SendMessage({ to: "investigator",   message: {type: "shutdown_request"} })
SendMessage({ to: "contrarian",     message: {type: "shutdown_request"} })
SendMessage({ to: "developer",      message: {type: "shutdown_request"} })
SendMessage({ to: "simplifier",     message: {type: "shutdown_request"} })
SendMessage({ to: "test-developer", message: {type: "shutdown_request"} })
TeamDelete()

If TeamCreate was never called (sequential fallback path), skip this section.

Phase completion and PR merge

Phase 5 is complete when:

• Contrarian declares the PR approved (zero VALID findings in the latest cycle)
• All per-cycle implementation worktrees have been merged and removed
• The feature branch has been pushed to origin with all fixes

Merge the PR

After approval, merge the PR immediately — do not wait for the user:

gh pr merge <pr_url> --squash --delete-branch \
  --subject "feat(<slug>): <feature description>" \
  --body "Merged after review approval (cycle <N>). See review-addon-*.md for finding history."

Use --squash to keep main history linear. If the repository enforces merge commits (branch protection rule: "Require a linear history" not set), use --merge instead. If gh pr merge fails due to branch protection requiring a human approver, report the PR URL to the user and ask them to merge manually — do not loop or retry.

After a successful merge, clean up the worktree:

git -C "<WORKTREE>" checkout main
git -C "<WORKTREE>" pull origin main
git worktree remove "<WORKTREE>" --force
git branch -d feature/<slug>

Report to the user:

• The PR URL and merge commit SHA
• Review summary: N cycle(s), X VALID findings fixed, Y INVALID discarded
• Worktree cleaned up

Phase Handoff

Produce a Phase Handoff:

=== PHASE HANDOFF ===
Phase:     Review
Status:    complete  (or: blocked — <reason>)
Feature:   <feature description>
Branch:    <branch>
Artifacts:
  <list of review-addon-N.md files created, or "none — approved on first cycle">
Decisions:
  - Review ran <N> cycle(s) before approval
  - Total VALID findings addressed: <count>
  - Total INVALID findings discarded: <count>
  - <notable decisions made during implementation of findings>
For next:  PR merged to main. Worktree removed. Feature complete.
Open:      <unresolved findings or user questions, or "none">
=== END HANDOFF ===