gmickel/flow-next-epic-review

Epic Completion Review Mode

Read workflow.md for detailed phases and anti-patterns.

Verify that the combined implementation of all epic tasks satisfies the spec requirements. This is NOT a code quality review (that's impl-review's job) — this confirms spec compliance only.

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

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"

Backend Selection

Priority (first match wins):

1. --review=rp|codex|copilot|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=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-epic default_review (set via flowctl epic 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 - handles window selection + builder atomically
4. DO NOT add --json flag to chat-send - 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 completion-review exclusively
2. Pass --receipt for session continuity on re-reviews
3. Parse verdict from command output

For copilot backend:

1. Use $FLOWCTL copilot completion-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-epic default_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 SHIP verdict (RP writes manually after fix loop; codex writes automatically via --receipt)
• 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 silently (must inform user and exit cleanly when backend is "none")

Input

Arguments: $ARGUMENTS Format: <epic-id> [--review=rp|codex|copilot|none]

• Epic ID - Required, e.g. fn-1 or fn-22-53k
• --review - Optional backend override

Workflow

See workflow.md for full details on each backend.

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

Step 0: Parse Arguments

Parse $ARGUMENTS for:

• First positional arg matching fn-* → EPIC_ID
• --review=<backend> → backend override
• Remaining args → focus areas

Step 1: Detect Backend

Run backend detection from SKILL.md above. Then branch:

Codex Backend

RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/completion-review-receipt.json}"

$FLOWCTL codex completion-review "$EPIC_ID" --receipt "$RECEIPT_PATH"
# Output includes VERDICT=SHIP|NEEDS_WORK

On NEEDS_WORK: fix code, commit, re-run (receipt enables session continuity).

Copilot Backend

RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/completion-review-receipt.json}"

# Override model + effort (pick one):
#   --spec copilot:claude-opus-4.5:xhigh   (preferred)
#   FLOW_REVIEW_BACKEND=copilot:claude-opus-4.5:xhigh
#   FLOW_COPILOT_MODEL=gpt-5.2 FLOW_COPILOT_EFFORT=high

$FLOWCTL copilot completion-review "$EPIC_ID" --receipt "$RECEIPT_PATH"
# Output includes VERDICT=SHIP|NEEDS_WORK

On NEEDS_WORK: fix code, commit, re-run. Session resume only when prior receipt has mode == "copilot".

RepoPrompt Backend

⚠️ STOP: You MUST read and execute workflow.md now.

Go to the "RepoPrompt Backend Workflow" section in workflow.md and execute those steps. Do not proceed here until workflow.md phases are complete.

The workflow covers:

1. Gather context (epic spec, tasks, changed files)
2. Atomic setup (setup-review) → sets $W and $T
3. Augment selection and build review prompt
4. Send review and parse verdict

Return here only after workflow.md execution is complete.

Fix Loop (INTERNAL - do not exit to Ralph)

CRITICAL: Do NOT ask user for confirmation. Automatically fix ALL valid issues and re-review — our goal is complete spec compliance. Never use AskUserQuestion in this loop.

If verdict is NEEDS_WORK, loop internally until SHIP:

1. Parse issues from reviewer feedback (missing requirements, incomplete implementations)
2. Fix code and run tests/lints
3. Commit fixes (mandatory before re-review)
4. Re-review:
   • Codex: Re-run flowctl codex completion-review (receipt enables context)
   • Copilot: Re-run flowctl copilot completion-review (receipt enables context; must be mode == "copilot" to resume)
   • RP: $FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md (NO --new-chat)
5. Repeat until <verdict>SHIP</verdict>

CRITICAL: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use --new-chat on the FIRST review.