/implement-review

name: implement-review
description: Review loop for staged changes. Detects content type, prepares a review request for Codex (Terminal-relay manual default, opt-in Auto-terminal codex-exec subprocess, or IDE plugin) or an explicitly selected Agy, Copilot, or headless Claude backend, categorizes feedback, revises, and iterates. Works for code, papers, proposals, or any text-based output.

Implement-Review

Overview

A review loop for staged changes. Claude Code detects the content type, sends the changes to one or more reviewers, categorizes the feedback, revises, and iterates. Codex is the primary reviewer via three channels: terminal relay (manual copy-paste, default on every platform), Auto-terminal (opt-in subprocess dispatch), or IDE plugin. The Auto-terminal channel also supports explicit cross-vendor reviewer backends for GitHub Copilot CLI, Claude Code, and Gemini through Antigravity CLI. Other reviewers are driven ad-hoc by the user through their own UI and only need to honor the `Review-<AgentName>.md` save contract defined in Phase 1c. Reviewer defaults and coordinator rewrites follow Path selection.

When to plan-review first

**Any complex task benefits from a plan review BEFORE execution**, not only writing or code. Plan-first catches architectural holes while they are still cheap to fix. The scope includes: system design, refactors, paper outlines, proposal structure, data-pipeline redesigns, multi-stage debugging strategies, teaching / curriculum planning, release-process changes, migration plans, and anything else where the shape of the work precedes and constrains the execution.

**Plan-review is a Phase 0 before the staged-change loop below.** If the user asks for a plan review, or if the task clearly meets the signals below, do not apply the staged-change prerequisite in Phase 1 yet. Tell the reviewer to read the plan file directly (or paste the plan contents via the terminal path when the reviewer cannot access the file) and critique the design, not `git diff --cached`. After the plan has no High findings and no new design blockers, execute the work and resume the normal staged-output review flow at Prerequisites / Phase 1.

When to plan-first

Signals that the round-trip pays off:

• **Blast radius is large** -- multiple files, cross-cutting concerns, shared state, multiple stakeholders, or the organizing structure of a deliverable.
• **Irreversible once executed** -- publishes, submissions, deployments, immutable packages, paper submissions, external commitments.
• **History shows a pattern** -- "got the structure wrong, redo next cycle" has happened on this track before.
• **Uncertainty in the approach** -- the user is weighing alternatives and wants the design validated, not the execution reviewed.
• **Context is unfamiliar** -- new codebase, domain, audience, agency, collaborator workflow, or external constraint set, where a wrong assumption can shape the rest of the work.

When to skip plan-first

• Change is small, local, reversible.
• The design is already worked out and only execution feedback is wanted.
• Plan and execution would be the same artifact (three-line bug fix, one-sentence footnote).

Process

1. Write the plan to a scratch file `PLAN-<identifier>.md` in the most natural location for the task (repo root for code, paper-repo root for Overleaf-style docs, a local scratch directory beside the deliverable for tasks that do not live in git). If the plan lands inside a git worktree, add it to `.git/info/exclude` so `git add -A` does not accidentally stage it; outside git, keep it as a clearly named scratch file outside the final deliverable and delete it after review. 2. Content varies by task but at minimum include: purpose, non-goals, structure, regression or failure analysis, validation plan, open questions. Keep it terse -- 1 to 3 pages. 3. Send the plan through a plan-review prompt (not the staged-change template). Make clear this is a pre-execution design review and that the plan file path or pasted contents are what the reviewer should read; instruct the reviewer to critique the design rather than to run `git diff --cached`. A reviewer with direct repository access reads the named files once. A snapshot backend (Antigravity) sees only the exported index, so a gitignored plan, an untracked evidence note, or an untracked local override is pasted into the request once, each under a `--- SUPPLIED INPUT: <path> ---` heading that names its source path; the reviewer reads the supplied copy and never the original worktree. Use the normal "Save your complete review to Review-<AgentName>.md" save-contract from Phase 1c. 4. **Reviewer must answer the scope-challenge questions** (see "Adversarial scope challenge" below) before any in-scope correctness review. 5. Iterate until the review has no High findings and no new design blockers. 6. Then execute (code, draft, revise, deploy). 7. Run the normal review cycle on the staged output. It is typically smaller because the architecture was already validated. 8. After the work ships or is submitted, delete the PLAN file.

Adversarial scope challenge (mandatory in plan-review)

Plan-review **must** be adversarial about plan purpose and shape, **not** about low-probability edge cases. The single biggest plan-review failure mode in this maintainer's history was not "the plan had a bug" — it was "the plan's scope was over-conservative, deferring user value across an extra release cycle worth of process tax." Examples:

• Conservative scope (`v0.5.7 = ref bump only; defer compact to v0.6.0`) → the user's real projects would have stayed on large `AGENTS.md` files for another release cycle. The apparent product ask was a one-line bundled manifest flip, but existing-consumer delivery also required bundled-default drift detection in aa plus real-project upgrade tests. The scope challenge should force reviewers to price both parts: user value now, and the smallest code path that actually del