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 - RepoPrompt, Codex CLI, GitHub Copilot CLI, Cursor 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 after /flow-next:plan lands the spec and its task breakdown, before /flow-next:work starts implementation. The reviewer sees both the spec narrative and the task graph - gaps surfaced now avoid wasted worker cycles later.

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 Ralph runs 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=rp|codex|copilot|cursor|claude|host|export|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 pilot skips it 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. The trade is priced in What each layer costs.

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.

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. The skill loops fix → review until the backend returns SHIP.

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...
Review round 2: 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>   # re-review until SHIP
/flow-next:work <spec-id>          # implementation