flow-next-plan-review_skill

Overview

This skill performs Carmack-level plan reviews for Flow epics using either RepoPrompt (rp) or Codex backends. It coordinates review execution, ensures receipts and checkpoints are written, and drives automatic fix-and-retry loops until a SHIP verdict. Trigger with the /flow-next:plan-review command and pass the epic id plus optional focus areas.

How this skill works

The skill detects the review backend from an explicit --review argument, an environment variable, or the configured review.backend and then runs the appropriate review flow. For Codex it saves a checkpoint, invokes flowctl codex plan-review with files and a receipt, and parses the verdict. For RepoPrompt it sets up an atomic review window, selects the epic and task specs, builds the review prompt, sends it, waits for the reviewer response, and extracts the verdict. On NEEDS_WORK the skill automatically applies fixes to epic/task specs and re-runs the same review session until SHIP.

When to use it

• When you need a rigorous, automated review of a Flow epic design or spec before implementation.
• When running Ralph autonomous or overnight coding and you want multi-model review gates.
• When you require reproducible receipts and checkpoints for auditability and recovery.
• When you want an automated fix loop to converge plans to a SHIP verdict without manual prompts.
• When you need to enforce backend-specific rules (rp vs codex) and avoid reviewer drift.

Best practices

• Always supply --review or configure FLOW_REVIEW_BACKEND to avoid auto-detection errors.
• Use the bundled FLOWCTL path (FLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl") rather than a global install.
• For rp backend: never simulate the reviewer, use setup-review, and keep re-reviews in the same chat.
• For codex backend: use flowctl codex plan-review with --receipt to preserve session continuity.
• Write REVIEW_RECEIPT_PATH on every review and save checkpoints before reviews for recovery.

Example use cases

• Review a new epic that touches auth and storage: include existing auth files via --files for reviewer context.
• Run an overnight Ralph job that creates a plan and gates deployment on a Codex verdict with receipts.
• Coordinate a multi-task epic: select all task specs with RepoPrompt and get a single reviewer verdict.
• Automate iterative plan fixes when reviewers return NEEDS_WORK until the plan attains SHIP.