Review Workflow

Flow-Next uses review gates before and after implementation.

Cross-model review is not a Flow-Next invention; people have paired one model against another as a reviewer for a while. Wiring it as an autonomous adversarial loop, where a different model challenges every plan and implementation automatically, at each handover and inside the autonomous modes (with or without Ralph), is something Flow-Next was one of the first to ship.

flowchart LR
  Spec["Spec"] --> PlanReview["Plan review"]
  PlanReview --> Work["Work"]
  Work --> ImplReview["Implementation review"]
  ImplReview -->|needs work| Work
  ImplReview -->|ship| Completion["Completion review"]
  Completion --> PR["make-pr"]
  Completion -.optional.-> QA["Live-app QA"]
  QA -.-> PR

The static gates above (plan / impl / completion review) read code and specs. The optional live-app QA stage drives the running app — slot it in after work, around or before make-pr.

Review backends

Every gate runs through a configurable review backend — a different model than the one that wrote the artefact. Pick the one your team already runs; the verdict grammar, receipts, fix loop, and optional --deep / --validate passes are identical across all of them.

Backend	Driver	Reviewer models	Shape
RepoPrompt (rp)	RepoPrompt CE + CE-first CLI ladder	chosen in the RepoPrompt window / session	macOS GUI; rpce-cli is preferred, discontinued Classic is compatibility-only, and Builder discovers context the diff alone would miss
OpenAI Codex (codex)	codex CLI	GPT-5.x family	headless, cross-platform
GitHub Copilot (copilot)	copilot CLI	Claude 4.x + GPT-5.x families	headless, cross-platform
Cursor CLI (cursor)	cursor-agent CLI	several vendor families in one place - ask cursor-agent --list-models for the current ids	headless subprocess; reviews billed against your existing Cursor subscription
Host (host)	Host-native fresh-context subagent	Cross-family pin from AGENTS.md model-routing (never the session model)	Bare only — no subprocess; preferred from inside Cursor

Host (host) is a model-less selection sentinel, not a CLI. Review runs as a host-native fresh-context subagent pinned to a model family that did not write the diff (pins live in the AGENTS.md model-routing section - never on the backend string; host:<model> is rejected). Every re-review is a new subagent. Fail-closed: without a cross-family pin, interactive runs ask; autonomous runs stop with NEEDS_HUMAN rather than silent same-family self-review. Setup on Cursor leads the backend menu with Host (Recommended). On Grok, Host is also offered, but Grok’s only native model family is grok-4.5 - native host review fails closed for a Grok writer unless the writer is non-Grok; cross-family review on Grok comes through bridge backends (codex / cursor / copilot). See Orchestration → Cursor host and Install → Grok.

Cursor CLI (cursor-agent) runs the same headless contract and verdict grammar as codex/copilot, with reviews billed against your Cursor subscription instead of a separate API key. It is resume-only (the first review persists Cursor’s session_id; re-reviews resume it) and folds reasoning effort into the model name (Cursor convention), so a spec is cursor:<model> with no :effort rung. From inside Cursor this path is circular — prefer host.

Set it once with /flow-next:setup, or override per run:

# persist the default (.flow/config.json)
flowctl config set review.backend codex
flowctl config set review.backend host          # preferred from inside Cursor

# override for a single run
/flow-next:impl-review fn-1 --review=rp|codex|copilot|cursor|host|none

# full spec form — backend:model:effort (host is bare only)
FLOW_REVIEW_BACKEND=codex:<model>:high

none is an explicit opt-out (skip review). The :model:effort suffix is optional and backend-specific — RepoPrompt picks its model in-app, so it takes no suffix; Codex and Copilot accept a :model:effort suffix (e.g. copilot:<model>:high); Cursor CLI takes a model only (e.g. cursor:<model>) since effort is baked into the model name; host accepts no suffix at all. The chosen backend is recorded as the mode field on every review receipt.

A per-task review: (or per-spec default_review) override routes end-to-end — it wins over the project default and env/config, so a task set to review: cursor:... under a codex project default actually reviews with cursor. Implementation reviews also carry an always-on code-smell baseline (Fowler Refactoring — Feature Envy, Data Clumps, Primitive Obsession, …) across every backend.

Plan review

/flow-next:plan-review fn-1

Checks whether the spec and plan are complete enough before work begins.

Use it when the work is high risk, cross-module, product-facing, or likely to be delegated. A plan review should catch missing requirements and bad decomposition while the fix is still cheap.

Implementation review

/flow-next:impl-review fn-1

Runs a second model over the diff. Only introduced findings count toward blocking verdicts.

Use a different model or backend than the implementation model when possible. The point is adversarial pressure, not another pass from the same context. The workflow is a loop: review finds introduced issues, /flow-next:work fixes them, review runs again, and the handoff continues only once the verdict is shippable.

What the reviewer actually receives (3.16.0)

The reviewer runs in your checkout with a shell, so it is handed identities, not content: the reviewed base..head range, the exact list of changed paths (git diff --numstat --no-renames -z, so nothing is elided, renames appear as real paths, and non-ASCII filenames survive), the repo-relative spec and task paths, and a few context hints. It reads the diff and the specs itself, at whatever depth each part warrants.

Earlier releases embedded the diff body in the prompt under a 50 KB cap, which meant a large change was reviewed against a truncated sample. Nothing is trimmed to fit now, and if a git read behind the evidence fails, the review stops with the underlying error before a review round is spent - rather than returning a verdict formed from nothing.

Re-reviews continue the reviewer’s own session, so when it checks whether your fixes landed it compares against findings it remembers making rather than a re-rendered list. When a session cannot be resumed, the prior findings travel in the prompt as before.

Expect better-informed reviews rather than cheaper ones: a fetching reviewer spends turns on tool calls, so it is slower on a large diff and its measured token use went up, not down. The dispatch bound is 1800 seconds, overridable with FLOW_REVIEW_EXEC_TIMEOUT.

Completion review

/flow-next:spec-completion-review fn-1

Checks the combined implementation against the whole spec after all tasks are done.

This is different from implementation review. Implementation review checks a diff. Completion review checks whether the full spec is satisfied after all tasks, merges, and fix loops.

Live-app QA (optional)

/flow-next:qa fn-1

Every gate above is static — it reads code or specs. QA is the live-app gate: it drives the running app like a real user, derives scenarios straight from the spec (AC, R-IDs, boundaries), files P0/P1/P2 findings with evidence, and emits a YES/NO qa_verdict receipt that can feed completion review.

Opt-in — it needs a live deploy + a driver (Flow-Next Drive); with neither it surfaces a BLOCKED verdict rather than failing, and adds nothing to the base flow when unused. It is forbidden from marking PASS by reading source.

PR review

/flow-next:make-pr fn-1
/flow-next:resolve-pr 123

The PR body summarizes acceptance coverage, critical files, decisions, memory, deferred findings, and review focus.

With the opt-in HTML artifact mode (2.0.0+), make-pr also emits a PR render lens — a self-contained, diff-derived HTML review instrument with a churn map grouped by review intent, an R-ID → evidence table verified against the spec export, and a where-to-look checklist. Read-only by design: PR feedback stays in review threads.

Review escalation

Signal	Response
Plan review finds unclear product behavior	Rerun /flow-next:interview --scope=business
Plan review finds technical gaps	Rerun /flow-next:interview --scope=technical
Impl review finds introduced bug	Rerun /flow-next:work on affected task
Impl review flags architectural mismatch	Revisit spec decision context
Completion review finds uncovered acceptance criteria	Add or repair task coverage
Live-app QA files a P0/P1 (or a BLOCKED/NA verdict)	File the finding to the bug track, add a fix task, or supply the missing deploy/driver
Human reviewer is confused	Improve task summaries or regenerate PR body

Review is part of the workflow, not an afterthought at the end.