flow-next-impl-review

Implementation Review Mode

Workflow is backend-split. Read [workflow-common.md](workflow-common.md) for Phase 0 (backend detection + philosophy + trivial-diff triage + phase-ordering matrix + cross-backend deep/validator/walkthrough phases), then read ONLY the file matching your active backend:

• BACKEND=codex → [workflow-codex.md](workflow-codex.md)
• BACKEND=copilot → [workflow-copilot.md](workflow-copilot.md)
• BACKEND=rp → [workflow-rp.md](workflow-rp.md)

Do not load the other two — only the active backend's file is needed.

Conduct a John Carmack-level review of implementation changes on the current branch.

Role: Code Review Coordinator (NOT the reviewer) Backends: RepoPrompt (rp), Codex CLI (codex), or GitHub Copilot CLI (copilot)

Preamble

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Define once; subsequent blocks (here and in workflow-*.md) use $FLOWCTL:

FLOWCTL="$HOME/.codex/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Backend Selection

Priority (first match wins):

1. --review=rp|codex|copilot|export|none argument
2. FLOW_REVIEW_BACKEND env var — bare backend (rp, codex, copilot, none) OR spec form (codex:gpt-5.4:xhigh, copilot:claude-opus-4.5)
3. .flow/config.json → review.backend (same bare / spec forms)
4. Error - no auto-detection

Parse from arguments first

Check $ARGUMENTS for:

• --review=rp or --review rp → use rp
• --review=codex or --review codex → use codex
• --review=copilot or --review copilot → use copilot
• --review=export or --review export → use export
• --review=none or --review none → skip review

If found, use that backend and skip all other detection.

Otherwise read from config

BACKEND=$($FLOWCTL review-backend)

if [[ "$BACKEND" == "ASK" ]]; then
 echo "Error: No review backend configured."
 echo "Run /flow-next:setup to configure, or pass --review=rp|codex|copilot|none"
 exit 1
fi

echo "Review backend: $BACKEND (override: --review=rp|codex|copilot|none)"

Backend at a glance

• rp — RepoPrompt (macOS GUI); builder auto-selects context. Primary backend.
• codex — Codex CLI (cross-platform); uses OpenAI models (default gpt-5.5). FLOW_CODEX_MODEL / FLOW_CODEX_EFFORT env vars, or --spec codex:gpt-5.4:xhigh.
• copilot — GitHub Copilot CLI (cross-platform); supports Claude Opus/Sonnet/Haiku 4.5 and GPT-5.2 families via a Copilot subscription. FLOW_COPILOT_MODEL / FLOW_COPILOT_EFFORT env vars, or --spec copilot:claude-opus-4.5:xhigh.

Spec grammar: backend[:model[:effort]] — FLOW_REVIEW_BACKEND and .flow/config.json review.backend both accept this. Examples: codex, codex:gpt-5.2, copilot:claude-opus-4.5:xhigh. Per-task review (set via flowctl task set-backend) overrides env.

Critical Rules

For rp backend:

1. DO NOT REVIEW CODE YOURSELF - you coordinate, RepoPrompt reviews
2. MUST WAIT for actual RP response - never simulate/skip the review
3. MUST use setup-review (5-15 min, DO NOT RETRY) - handles window selection + builder atomically
4. DO NOT add --json flag to chat-send (2-10 min, DO NOT RETRY) - it suppresses the review response
5. Re-reviews MUST stay in SAME chat - omit --new-chat after first review

For codex backend:

1. Use $FLOWCTL codex impl-review exclusively
2. Pass --receipt for session continuity on re-reviews
3. Parse verdict from command output

For copilot backend:

1. Use $FLOWCTL copilot impl-review exclusively
2. Pass --receipt for session continuity on re-reviews (session only resumes when prior receipt has mode == "copilot")
3. Model + effort resolved via (first match wins): --spec backend:model:effort flag, per-task review, FLOW_REVIEW_BACKEND spec, FLOW_COPILOT_MODEL / FLOW_COPILOT_EFFORT env vars, registry defaults
4. Parse verdict from command output

For all backends:

• If REVIEW_RECEIPT_PATH set: write receipt after review (any verdict)
• Any failure → output <promise>RETRY</promise> and stop

FORBIDDEN:

• Self-declaring SHIP without actual backend verdict
• Mixing backends mid-review (stick to one)
• Skipping review when backend is "none" without user consent

Input

Arguments: $ARGUMENTS Format: [task ID] [--base <commit>] [--validate] [--deep[=passes]] [--interactive] [focus areas]

• --base <commit> - Compare against this commit instead of main/master (for task-scoped reviews)
• --validate - After NEEDS_WORK verdict, run a validator pass that drops false-positive findings (fn-32.1, opt-in)
• --deep / --deep=<passes> - Run additional specialized passes (adversarial / security / performance) after primary review (fn-32.2, opt-in)
• --interactive - On NEEDS_WORK, walk through each finding with the user (Apply/Defer/Skip/Acknowledge) (fn-32.3, opt-in, Ralph-incompatible)
• Task ID - Optional, for context and receipt tracking
• Focus areas - Optional, specific areas to examine

Scope behavior:

• With --base: Reviews only changes since that commit (task-scoped)
• Without --base: Reviews entire branch vs main/master (full branch review)

Opt-in flags (fn-32):

• --validate — adds a validator pass on NEEDS_WORK that re-checks each finding

for false positives. All findings dropping upgrades verdict to SHIP.

• FLOW_VALIDATE_REVIEW=1 env var — enables --validate session-wide (works in Ralph).
• --deep — adds adversarial pass always + security/performance auto-enabled

per diff paths. --deep=adversarial,security restricts to listed passes.

• FLOW_REVIEW_DEEP=1 env var — enables --deep session-wide (works in Ralph).
• --interactive — per-finding walkthrough on NEEDS_WORK. No env var form —

per-invocation only, always hard-errors in Ralph mode (REVIEW_RECEIPT_PATH or FLOW_RALPH=1) to prevent accidental autonomous engagement.

• Default review behavior (no flags) is unchanged.

Workflow

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

Step 0: Parse Arguments

Parse $ARGUMENTS for:

• --base <commit> → BASE_COMMIT (if provided, use for scoped diff)
• --no-triage → set TRIAGE_DISABLED=1 (skip trivial-diff pre-check)
• --validate → set VALIDATE=true (fn-32.1 validator pass on NEEDS_WORK)
• --deep / --deep=<passes> → set DEEP=true + optional DEEP_PASSES CSV (fn-32.2)
• --interactive → set INTERACTIVE=true (fn-32.3 per-finding walkthrough on NEEDS_WORK; Ralph-blocked)
• First positional arg matching fn-* → TASK_ID
• Remaining args → focus areas

If --base not provided, BASE_COMMIT stays empty (will fall back to main/master).

Validate flag + env var:

VALIDATE=false
# Parse --validate from $ARGUMENTS (same pattern as --base)
for arg in $ARGUMENTS; do
 case "$arg" in
 --validate) VALIDATE=true ;;
 esac
done

# Env opt-in (Ralph-friendly)
if [[ "${FLOW_VALIDATE_REVIEW:-}" == "1" ]]; then
 VALIDATE=true
fi

VALIDATE gates the validator pass in [workflow-common.md](workflow-common.md). When false (default), behavior is unchanged.

Deep flag + env var:

DEEP=false
DEEP_PASSES="" # optional CSV: "adversarial,security"
for arg in $ARGUMENTS; do
 case "$arg" in
 --deep) DEEP=true ;;
 --deep=*) DEEP=true; DEEP_PASSES="${arg#--deep=}" ;;
 esac
done

# Env opt-in (Ralph-friendly)
if [[ "${FLOW_REVIEW_DEEP:-}" == "1" ]]; then
 DEEP=true
fi

DEEP gates the deep-pass phase in [workflow-common.md](workflow-common.md). When false (default), behavior is unchanged.

Pass selection (when DEEP=true):

# If explicit CSV provided, use those passes verbatim.
# Otherwise: adversarial always + security/performance auto-enabled by
# changed-file globs via `flowctl review-deep-auto`.
if [[ -n "$DEEP_PASSES" ]]; then
 SELECTED_PASSES="${DEEP_PASSES//,/ }"
else
 # Determine changed files for auto-enable heuristic
 if [[ -n "$BASE_COMMIT" ]]; then
 CHANGED="$(git dif