Skip to main content
skill CX Codex

flow-next-plan-review — Claude Code skill for plan review

The flow-next-plan-review skill routes Flow specs and plans to a selected reviewer, then handles fixes and a follow-up review. Use it to check a Flow document before moving ahead.

MIT ★ 730 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Open on GitHub

What flow-next-plan-review does

The skill coordinates reviews of Flow plans and specs through Codex, Copilot, Cursor, Claude Code, or a host-native backend. The backend can be selected with --review, a per-spec setting, an environment variable, or project configuration. The coordinator does not issue its own verdict; it dispatches the review and follows the result.

When the verdict is NEEDS_WORK, the skill edits the current spec, saves it through flowctl, syncs affected task specs, and sends it back to the same backend. An attended run allows one fix pass and one re-review; autonomous runs follow the review loop and flowctl limits. A backend failure stops the process, with no automatic switch to another backend, so check backend availability first.

A Flow spec and a configured review backend are needed. Selecting none, rp, or export ends the common route without starting a backend.

What it helps with

  • review a Flow plan before implementation
  • surface issues in a spec and get a reviewer verdict
  • apply findings to the current plan and request another review
  • route plan checks through a chosen backend

Example prompts for the agent

  • Run /flow-next:plan-review for spec SPEC_ID and review it with Codex.
  • Review plan SPEC_ID, focusing on error handling, with --review=claude.
  • Run an unattended review of plan SPEC_ID with mode:autonomous.

How to install flow-next-plan-review

1Plugin marketplace

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

This installs the whole flow-next plugin with all its skills

2Skills CLI (Vercel)

npx skills add gmickel/flow-next --skill flow-next-plan-review -a claude-code

3Manually: put the files in place

~/.claude/skills/flow-next-plan-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/flow-next-plan-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about flow-next-plan-review

How do I install flow-next-plan-review in Claude Code?

First add the marketplace with /plugin marketplace add gmickel/flow-next, then install the plugin with /plugin install flow-next@flow-next.

What does flow-next-plan-review do?

It sends a Flow plan or spec to the selected reviewer, processes findings, and coordinates a follow-up review.

How does the skill choose a review backend?

It checks --review first, followed by the per-spec setting, FLOW_REVIEW_BACKEND, and .flow/config.json. It does not automatically detect a backend.

Source text

SKILL.md · MIT
---
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 explicit
`--review=rp` or `--review=export` 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`, `rp` and `export`. Never invoke
`flowctl review-backend` a second time.

## Backend Selection

Priority (first match wins):

1. `--review=codex|copilot|cursor|claude|host|none`
2. Per-spec `default_review`
3. `FLOW_REVIEW_BACKEND`
4. `.flow/config.json` `review.backend`
5. Error — no auto-detection

Configured values accept `backend[:model[:effort]]`; `cursor` takes a model but
no effort, `claude` takes `claude[:<model>[:<effort>]]`, and `host` and `none` are bare-only.

## 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`, `rp` or `export`, 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: edit the spec
   file in place (`spec_path` from `$FLOWCTL show <SPEC_ID> --json`), 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.

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

3. Sync affected task specs when requirements, acceptance, design decisions,
   interfaces, retry/error semantics, or state values changed.
4. Re-enter the SAME selected backend file's re-review step. Never load or mix
   another backend. Codex/Copilot/Cursor/Claude resume only through a same-mode receipt;
   host uses a fresh read-only subagent.
5. Attended, stop after that one re-review: `SHIP` completes; `NEEDS_WORK` surfaces the
   surviving findings to the caller, never a second fix pass. In the review loop, repeat
   from step 1 as above.

**Done when:** the review ends in one of exactly five states — a `SHIP` from the
backend, a re-review `NEEDS_WORK` with its surviving findings surfaced, a
`MAJOR_RETHINK` escalated as `BLOCKED: DESIGN_CONFLICT`, a
`RETRY: no verdict (backend or transport failure)` from a backend/transport failure, or flowctl's
`ESCALATE:` cap refusal with the surviving findings surfaced. A round that ends
with a `NEEDS_WORK` neither fixed in the current spec nor re-entered into the
same backend has broken this.

**Maintainability pointer.** When the verdict's `maintainability:` block names a finding
(anything other than `none identified`): read
[references/maintainability-pointer.md](references/maintainability-pointer.md) and record it.

Recovery after context compaction:

```bash
$FLOWCTL checkpoint restore --spec <SPEC_ID> --json
```

Every re-review follows the selected backend file's receipt/status rules.

© Gordon Mickel · MIT · gmickel/flow-next

Similar skills

All skills for Code review and refactoring →

From the same set70

The whole set →
flow-next-tracker-sync flow-next-tracker-sync projects a flow-next spec onto a Linear, GitHub, GitLab or Jira issue and keeps body, status and comments in sync, with the spec staying authoritative. CX Codex +1 ★ 730repo stars claude-md-scout claude-md-scout audits CLAUDE.md and AGENTS.md files on an eight-point substance scale, verifying real commands and repo specifics before agents start working. CX Codex ★ 730repo stars flow-gap-analyst The flow-gap-analyst subagent examines a short feature brief for unclear requirements, missing steps, and edge cases. Use it to surface questions before implementation begins. CX Codex ★ 730repo stars flow-next-deps flow-next-deps shows spec dependency graph, execution order and blocking chains. Use it when you ask 'what's blocking what' or 'what order should specs run'. CX Codex +1 ★ 730repo stars flow-next-impl-review Runs John Carmack-style implementation review via a chosen backend — claude, codex, copilot, cursor or a human. Invoked with /flow-next:impl-review. CX Codex +1 ★ 730repo stars flow-next-work flow-next-work executes Flow-Next specs and tasks step by step: manages Git branches, tracks task states in .flow/ via flowctl, runs tests, and creates clean commits. CX Codex +1 ★ 730repo stars flow-next-spec-completion-review flow-next-spec-completion-review is a skill that checks whether a spec's tasks together meet its requirements. Run it before marking work on the spec complete. CX Codex +1 ★ 730repo stars flow-next-capture flow-next-capture synthesizes the active conversation context into a structured flow-next spec under .flow/specs/ using the bundled flowctl tool. CX Codex +1 ★ 730repo stars

Project sponsors

Companies that keep this analytics open