/flow-next-plan-review

name: flow-next-plan-review
description: Carmack-level plan review via Codex, Copilot, Cursor, Claude or a host reviewer. Use when reviewing Flow specs or design docs. Triggers on /flow-next:plan-review.
user-invocable: false

Plan Review Mode

**Workflow is backend-split. Read [workflow.md](workflow.md) for common orchestration and backend resolution, then read ONLY the file matching the selected review backend:**

• `BACKEND=codex` → [workflow-codex.md](workflow-codex.md)
• `BACKEND=copilot` → [workflow-copilot.md](workflow-copilot.md)
• `BACKEND=cursor` → [workflow-cursor.md](workflow-cursor.md)
• `BACKEND=claude` → [workflow-claude.md](workflow-claude.md)
• `BACKEND=host` → [workflow-host.md](workflow-host.md)

Do not load the other backend files. `BACKEND=none` and an unknown explicit value terminate from the common workflow without loading any backend file.

Conduct a John Carmack-level review of spec plans.

**Role**: Code Review Coordinator (NOT the reviewer) **Backends**: Codex CLI (codex), GitHub Copilot CLI (copilot), Cursor CLI (cursor), Claude Code CLI (claude), or host-native (`host`)

Read [working-rules.md](../../references/working-rules.md) first unless you already have this run; it holds for every step of this skill.

Preamble — execute common routing exactly once

Read and execute [workflow.md](workflow.md) Phase 0 once. It defines `$FLOWCTL`, parses an explicit `--review` mode before configured-backend resolution, resolves `SPEC_ID`, and handles `ASK`, `none` and unknown values. Never invoke `flowctl review-backend` a second time.

Common Critical Rules

• The coordinator never self-declares a verdict.
• Stick to one backend for the full review/fix cycle.
• If `REVIEW_RECEIPT_PATH` is set, every review verdict writes a receipt.
• Any backend/transport failure outputs `RETRY: no verdict (backend or transport failure)` and stops;

never silently fall back to a different backend. When its `CLI message:` reports a usage, credit or spend limit, report that message and stop instead of `RETRY:`; a retry fails the same way. Autonomous callers receive the same retry terminal and decide whether to re-enter. A no-verdict dispatch is refunded and recorded by flowctl; never manually reset the review counter for a transport failure. Exit 5 / `TRANSPORT_UNHEALTHY` means stop automatic retries and repair the backend.

• `none` skips only when selected explicitly or resolved from configuration.
• **Foreground rule:** run every `flowctl <backend> plan-review` call as one **blocking foreground** Bash call with a generous timeout (10 minutes; verdicts typically land in 1–7) — never `run_in_background` + monitor/poll (a background completion does not reliably resume a subagent context). Host-backend subagent dispatches are also blocking.

Backend-specific invocation, availability, model, session-continuity, receipt, and anti-pattern rules live only in the selected backend file.

Input

Arguments: $ARGUMENTS

Format: `<flow-spec-id> [focus areas] [--review=<mode>] [mode:autonomous]`. `mode:autonomous` marks an unattended run (working-rules.md's review loop applies); it is not a focus area.

Workflow

1. Execute [workflow.md](workflow.md) Phase 0. 2. If it returns for `none` or an unknown value, stop. Do not read a backend file. 3. Read exactly the selected `workflow-<backend>.md`. 4. Execute one backend dispatch and carry its verdict directly into the shared Fix Loop below. 5. Continue in that loop until its terminal contract is satisfied.

Fix Loop (INTERNAL)

**The fix loop never pauses for user confirmation**; never use AskUserQuestion in it. Which findings it fixes, and which it lists as follow-ups, follows the Review section of [working-rules.md](../../references/working-rules.md).

`MAJOR_RETHINK` is not a fix-loop input. Surface the reviewer's rationale and stop with `BLOCKED: DESIGN_CONFLICT`. `NEEDS_HUMAN` is not one either: stop and hand the reviewer's question to the person, on every backend. Only `NEEDS_WORK` enters the loop.

Attended: one fix pass, then one re-review, whose verdict is terminal. When working-rules.md's review loop applies (an unattended run, or a request to review until SHIP), repeat the steps below until SHIP or an `ESCALATE:`. The flowctl cap below stays as the backstop; never keep an agent-side counter.

**The cap is enforced deterministically by flowctl:** every dispatch reserves a spec-scoped round before launch. SHIP / NEEDS_WORK / MAJOR_RETHINK / NEEDS_HUMAN consume it; a no-verdict transport failure is durably recorded and refunded. At `${MAX_REVIEW_ITERATIONS:-8}` verdict rounds, flowctl refuses with `ESCALATE:` and exit 4. More than `${MAX_REVIEW_TRANSPORT_FAILURES:-2}` consecutive no-verdict failures stop separately with `TRANSPORT_UNHEALTHY` + exit 5. Callers invoke plan-review once and act on its terminal result. The verdict counter resets only on SHIP or an explicit re-plan, never on an edit, fresh invocation, or transport failure.**

**ANTI-PATTERN:** a delivered verdict is never a transport failure - never re-dispatch or re-frame `NEEDS_WORK` as a backend/sandbox problem to claim a refund. And never widen the reviewer sandbox: reviewers are read-only by contract, so a sandbox-blocked reviewer means something asked it to mutate the workspace. Fix that instead (Windows resolves via `auto`).

When the verdict is `NEEDS_WORK`:

1. Parse all valid issues from reviewer feedback. 2. Fix the user-edited current spec, never a checkpoint copy: read the spec file now (`spec_path` from `$FLOWCTL show <SPEC_ID> --json`), edit it in place with targeted edits (a whole-file rewrite drops a person's edits), then persist that file. The file on disk is the input, so an edit the user made between cycles survives; on a `set-plan` failure, surface its error and stop the cycle.

   $FLOWCTL spec set-plan <SPEC_ID> --file <spec path> --json

3. Sync affected task specs when requirements, acceptance