Plan Review

/flow-next:plan-review runs a structured adversarial review of a Flow-Next spec.

The host agent is the coordinator, not the reviewer. The actual critique comes from a separate backend - Codex CLI, GitHub Copilot CLI, Cursor CLI, Claude Code CLI, or a host-native fresh-context subagent (host) - and is captured as a review receipt the spec can be re-checked against.

When to use it

Run plan-review on a strong spec before implementation, with zero tasks or after optional decomposition. With zero tasks the reviewer assesses requirements, design, boundaries, and verification; task ordering and task coverage apply only when a task graph exists. This review does not require or create a decomposition, and it never asks for one. Task count and task split are the owner’s decision; a missing approach order or test sequence is a finding against the spec itself.

Specifically:

• The spec touches risky surfaces (auth, migrations, public APIs) and you want a second pair of eyes that did not see the original conversation.
• The spec is large enough that fixing it post-implementation would mean throwing away worker output.
• You plan to hand the spec to autonomous work and want adversarial pressure on assumptions before flow --auto runs it unattended.

Skip it for trivial specs where the cost of review exceeds the cost of redoing one task.

Backend selection

The backend comes from --review=codex|copilot|cursor|claude|host|none, then FLOW_REVIEW_BACKEND, then .flow/config.json; nothing configured anywhere is a hard error. The ladder, the per-backend notes, and the backend[:model[:effort]] grammar are in Review backends. Per-spec overrides: flowctl spec set-backend.

none as a standing default makes this gate exit cleanly, and flow --auto records the stage as skipped with its reason rather than deadlocking. host keeps the gate with nothing to install. Set review.backend host and add a cross-family reviewer: pin to your routing block.

What the reviewer is asked to do

Every backend gets the same prompt: a Carmack-level adversarial review. The reviewer looks for:

• Acceptance criteria that cannot be observed.
• Implicit assumptions the spec depends on.
• Out-of-scope creep the plan invited.
• Missing edge cases or failure modes.
• Architecture mismatches with the existing codebase.
• Maintainability, from the plan as written (since 5.5.0): the same edit or decision made in more than one place, and a back-edge against the dependency direction or new branching in a module’s hottest function. Each answer is a concrete finding or none identified, advisory; the item never recommends an abstraction, and a finding alone blocks only when it names concrete duplication, a back-edge, or the function absorbing the branching.

Re-review semantics

Receipts persist under .flow/review-receipts/. Re-reviews stay in the same chat session so the reviewer can see what changed since the first pass. On NEEDS_WORK the skill makes one fix pass on the spec, then runs one re-review, and that verdict is final: SHIP completes, and NEEDS_WORK hands the surviving findings back to you. The flowctl round cap stays as a safety net.

A SHIP covers the spec it read. When flowctl spec set-plan later rewrites the spec body (a refine pass, say), the plan review reads stale: work stops on it, and /flow-next:flow and flow --auto run plan-review again before work, whatever the task count. Refine names /flow-next:plan-review <spec-id> as the next step after it changes a spec that has tasks. A spec that was never plan-reviewed routes as before.

Where it stops

• Not a code review - that is /flow-next:impl-review.
• Not a spec-completion check - that is /flow-next:spec-completion-review.
• Not a sanity check on grammar or formatting - the reviewer is asked to challenge substance, not polish.

Worked example

/flow-next:plan-review fn-14-rate-limits

Review round 1 (cross-model backend): NEEDS_WORK
  [Major] R4 untestable as written: "handles bursts gracefully" has no measurable bound
  [Minor] task .2 depends on a header contract R-IDs never pin down
Findings applied to spec, re-reviewing once...
Re-review: SHIP

A plan finding costs minutes; the same gap found during implementation costs a task cycle.

Tips

• Reviewing a one-page plan is the highest-leverage review in the pipeline - never skip it on specs whose failure would be expensive.
• Vague acceptance criteria are the most common finding class; if the reviewer cannot test it, a worker cannot satisfy it.
• Use a different model family than the one that wrote the plan - same-family reviews share the blind spots that produced the gap.

Dynamic usage

Recipes that compose with plan-review in the cookbook:

• Model routing - choose the reviewing backend per spec (--review=<backend>) or per repo (review.backend).
• Prompt into a stage - “review this plan for migration risk specifically” narrows the pass without weakening the verdict contract.

Next step

Address the findings in the spec, then either:

/flow-next:plan-review <spec-id>   # review the revised spec again
/flow-next:work <spec-id>          # implementation