Agent-Skills.md

Agent Skills: Plan Review Mode

Carmack-level plan review via RepoPrompt or Codex. Use when reviewing Flow specs or design docs. Triggers on /flow-next:plan-review.

UncategorizedID: gmickel/gmickel-claude-marketplace/flow-next-plan-review

Repository

gmickel/gmickel-claude-marketplace
gmickelLicense: MIT
65651

Install this agent skill to your local

pnpm dlx add-skill https://github.com/gmickel/flow-next/tree/HEAD/plugins/flow-next/skills/flow-next-plan-review

Skill Files

Browse the full folder contents for flow-next-plan-review.

Download Skill

Loading file tree…

plugins/flow-next/skills/flow-next-plan-review/SKILL.md

Skill Metadata

Name
flow-next-plan-review
Description
Carmack-level plan review via RepoPrompt or Codex. Use when reviewing Flow specs or design docs. Triggers on /flow-next:plan-review.

Plan Review Mode

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

Conduct a John Carmack-level review of spec plans.

Role: Code Review Coordinator (NOT the reviewer) Backends (branch on the Preamble RP_ELIGIBLE guard):

  • When RP_ELIGIBLE=1: RepoPrompt (rp), Codex CLI (codex), GitHub Copilot CLI (copilot), or Cursor CLI (cursor)
  • When RP_ELIGIBLE=0: Codex CLI (codex), GitHub Copilot CLI (copilot), or Cursor CLI (cursor) — rp is macOS-only; never list it in guidance you surface (--review=rp stays accepted)

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="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

# RepoPrompt is macOS-only (rp-cli bridges the GUI). Only offer the rp path
# when it can actually run: on macOS, or when rp-cli is already on PATH.
if [ "$(uname 2>/dev/null)" = "Darwin" ] || command -v rp-cli >/dev/null 2>&1; then
  RP_ELIGIBLE=1
else
  RP_ELIGIBLE=0
fi

When RP_ELIGIBLE=0 (not macOS, no rp-cli), never steer the user toward rp: every backend summary, recommendation, or override hint you surface presents only the runnable configured backends codex, copilot, cursor (plus none). export is an explicit one-off review MODE (--review=export), not a configured backend — never present it as one. Suppression is not a ban: an explicit --review=rp, FLOW_REVIEW_BACKEND=rp, or review.backend=rp still resolves to rp and errors at runtime via require_rp_cli() as today.

Backend Selection

Priority (first match wins):

  1. --review=rp|codex|copilot|cursor|export|none argument
  2. FLOW_REVIEW_BACKEND env var — bare backend (rp, codex, copilot, cursor, none) OR spec form (codex:gpt-5.4:xhigh, copilot:claude-opus-4.5, cursor:gpt-5.5-high)
  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=cursor or --review cursor → use cursor
  • --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

# Priority: --review flag > per-spec `default_review` override > env > config.
# Resolve the spec id from $ARGUMENTS FIRST so a per-spec `default_review` override routes to the
# right backend BEFORE branching (empty → env/config, no regression). `$1` is the positional spec
# arg — the backend blocks below reuse it as `SPEC_ID`.
SPEC_ID="${1:-}"   # the spec-id positional arg (canonicalized by review-backend); empty falls back to env/config
BACKEND=$($FLOWCTL review-backend "$SPEC_ID")

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

if [ "$RP_ELIGIBLE" = 1 ]; then
  echo "Review backend: $BACKEND (override: --review=rp|codex|copilot|cursor|none)"
else
  echo "Review backend: $BACKEND (override: --review=codex|copilot|cursor|none)"
fi

Backend at a glance

When RP_ELIGIBLE=0, omit the rp line below from any guidance you surface (explicit --review=rp still honored):

  • 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.
  • cursor — Cursor CLI (cursor-agent, cross-platform); reaches gpt-5.5-high (1M-ctx default), the gpt-5.3-codex family, composer-2.5, and claude-opus-4-8-thinking-high via a Cursor subscription. FLOW_CURSOR_MODEL env var, or --spec cursor:gpt-5.5-high. Cursor folds reasoning effort into the model name — no effort field.

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, cursor:gpt-5.5-high (cursor takes model only — no :effort). Per-spec default_review (set via flowctl spec set-backend) overrides env.

Critical Rules

For rp backend:

  1. DO NOT REVIEW THE PLAN 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 plan-review exclusively
  2. Pass --receipt for session continuity on re-reviews
  3. Parse verdict from command output

For copilot backend:

  1. Use $FLOWCTL copilot plan-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-spec default_review, FLOW_REVIEW_BACKEND spec, FLOW_COPILOT_MODEL / FLOW_COPILOT_EFFORT env vars, registry defaults
  4. Parse verdict from command output

For cursor backend:

  1. Use $FLOWCTL cursor plan-review exclusively (requires --files <code files>, same as codex/copilot)
  2. Pass --receipt for session continuity on re-reviews (session only resumes when prior receipt has mode == "cursor")
  3. Model resolved via (first match wins): --spec cursor:<model> flag, per-spec default_review, FLOW_REVIEW_BACKEND spec, FLOW_CURSOR_MODEL env var, registry default (gpt-5.5-high). No effort — Cursor bakes effort into the model name; cursor:<model>:<effort> is rejected
  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
  • 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)

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: <flow-spec-id> [focus areas]

Workflow

See workflow.md for full details on each backend.

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

Step 0: Detect Backend

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

Codex Backend

SPEC_ID="${1:-}"
RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt-${SPEC_ID}.json}"  # fn-90 R5: spec-scoped default (concurrent specs no longer collide); explicit REVIEW_RECEIPT_PATH still wins

# Save checkpoint before review (recovery point if context compacts)
$FLOWCTL checkpoint save --spec "$SPEC_ID" --json

# --files: comma-separated CODE files for reviewer context
# Spec/task specs are auto-included; pass files the plan will CREATE or MODIFY
# How to identify: read the spec, find files mentioned or directories affected
# Example: spec touches auth → pass existing auth files for context
#
# Dynamic approach (if spec mentions specific paths):
#   CODE_FILES=$(grep -oE 'src/[^ ]+\.(ts|py|js)' .flow/specs/${SPEC_ID}.md | sort -u | paste -sd,)
# Or list key files manually:
# Derive REAL reviewer anchors from the spec's `## Key files / interfaces` (the canonical,
# scaffold-mandated source); fall back to any file-like tokens in the spec. NEVER a hardcoded
# guess — the cross-platform backends need real code paths or they only catch spec-internal
# inconsistency, not "this plan contradicts how the codebase actually works."
CODE_FILES="$(awk '/^## Key files/{f=1;next} /^## /{f=0} f' ".flow/specs/${SPEC_ID}.md" | grep -oE '`[^`]+\.[A-Za-z0-9]+`' | tr -d '`' | grep -vE '^https?:' | sort -u | head -20 | paste -sd, -)"
[ -z "$CODE_FILES" ] && CODE_FILES="$(grep -oE '[A-Za-z0-9_./-]+\.(py|ts|tsx|js|jsx|go|rs|rb|java|php|c|cpp|h|md|sh)' ".flow/specs/${SPEC_ID}.md" | grep -vE '^https?:' | sort -u | head -20 | paste -sd, -)"

$FLOWCTL codex plan-review "$SPEC_ID" --files "$CODE_FILES" --receipt "$RECEIPT_PATH"
# Output includes VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK

On NEEDS_WORK: fix plan via $FLOWCTL spec set-plan AND sync affected task specs via $FLOWCTL task set-spec, then re-run (receipt enables session continuity).

Note: codex plan-review automatically includes task specs in the review prompt.

Copilot Backend

SPEC_ID="${1:-}"
RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt-${SPEC_ID}.json}"  # fn-90 R5: spec-scoped default (concurrent specs no longer collide); explicit REVIEW_RECEIPT_PATH still wins

# Save checkpoint before review (recovery point if context compacts)
$FLOWCTL checkpoint save --spec "$SPEC_ID" --json

# --files: comma-separated CODE files for reviewer context (same shape as codex)
# Spec/task specs are auto-included; pass files the plan will CREATE or MODIFY
# Derive REAL reviewer anchors from the spec's `## Key files / interfaces` (the canonical,
# scaffold-mandated source); fall back to any file-like tokens in the spec. NEVER a hardcoded
# guess — the cross-platform backends need real code paths or they only catch spec-internal
# inconsistency, not "this plan contradicts how the codebase actually works."
CODE_FILES="$(awk '/^## Key files/{f=1;next} /^## /{f=0} f' ".flow/specs/${SPEC_ID}.md" | grep -oE '`[^`]+\.[A-Za-z0-9]+`' | tr -d '`' | grep -vE '^https?:' | sort -u | head -20 | paste -sd, -)"
[ -z "$CODE_FILES" ] && CODE_FILES="$(grep -oE '[A-Za-z0-9_./-]+\.(py|ts|tsx|js|jsx|go|rs|rb|java|php|c|cpp|h|md|sh)' ".flow/specs/${SPEC_ID}.md" | grep -vE '^https?:' | sort -u | head -20 | paste -sd, -)"

# 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.5 FLOW_COPILOT_EFFORT=high

$FLOWCTL copilot plan-review "$SPEC_ID" --files "$CODE_FILES" --receipt "$RECEIPT_PATH"
# Output includes VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK

On NEEDS_WORK: fix plan via $FLOWCTL spec set-plan AND sync affected task specs via $FLOWCTL task set-spec, then re-run. Session resume only when prior receipt has mode == "copilot".

Note: copilot plan-review automatically includes task specs in the review prompt (same as codex).

Cursor Backend

SPEC_ID="${1:-}"
RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt-${SPEC_ID}.json}"  # fn-90 R5: spec-scoped default (concurrent specs no longer collide); explicit REVIEW_RECEIPT_PATH still wins

# Save checkpoint before review (recovery point if context compacts)
$FLOWCTL checkpoint save --spec "$SPEC_ID" --json

# --files: comma-separated CODE files for reviewer context (same shape as codex)
# Spec/task specs are auto-included; pass files the plan will CREATE or MODIFY
# Derive REAL reviewer anchors from the spec's `## Key files / interfaces` (the canonical,
# scaffold-mandated source); fall back to any file-like tokens in the spec. NEVER a hardcoded
# guess — the cross-platform backends need real code paths or they only catch spec-internal
# inconsistency, not "this plan contradicts how the codebase actually works."
CODE_FILES="$(awk '/^## Key files/{f=1;next} /^## /{f=0} f' ".flow/specs/${SPEC_ID}.md" | grep -oE '`[^`]+\.[A-Za-z0-9]+`' | tr -d '`' | grep -vE '^https?:' | sort -u | head -20 | paste -sd, -)"
[ -z "$CODE_FILES" ] && CODE_FILES="$(grep -oE '[A-Za-z0-9_./-]+\.(py|ts|tsx|js|jsx|go|rs|rb|java|php|c|cpp|h|md|sh)' ".flow/specs/${SPEC_ID}.md" | grep -vE '^https?:' | sort -u | head -20 | paste -sd, -)"

# Override model (pick one):
#   --spec cursor:gpt-5.5-high             (preferred)
#   FLOW_REVIEW_BACKEND=cursor:gpt-5.5-high
#   FLOW_CURSOR_MODEL=composer-2.5
# Cursor folds effort into the model name — no :<effort> and no FLOW_CURSOR_EFFORT.

$FLOWCTL cursor plan-review "$SPEC_ID" --files "$CODE_FILES" --receipt "$RECEIPT_PATH"
# Output includes VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK

On NEEDS_WORK: fix plan via $FLOWCTL spec set-plan AND sync affected task specs via $FLOWCTL task set-spec, then re-run. Session resume only when prior receipt has mode == "cursor".

Note: cursor plan-review automatically includes task specs in the review prompt (same as codex).

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. Get plan content and save checkpoint
  2. Atomic setup (setup-review) → sets $W and $T
  3. Augment selection (spec + task specs)
  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 production-grade world-class software and architecture. Never use AskUserQuestion in this loop.

MAJOR_RETHINK is NOT a fix-loop input. Every backend can emit MAJOR_RETHINK (a valid verdict tag), but it means the plan/approach is wrong — not something to patch finding-by-finding. Do NOT enter the fix loop on it. Escalate immediately: surface the reviewer's rationale to the caller and stop with a typed BLOCKED: DESIGN_CONFLICT (Ralph mode: output <promise>RETRY</promise>). A re-plan is a human decision, never an ad-hoc patch. Only NEEDS_WORK drives the loop below.

MAX ITERATIONS (backend-agnostic — applies to ALL backends: rp, codex, copilot, cursor): keep an iteration counter in agent context, starting at 0. Each fix+re-review cycle increments it. When the counter reaches ${MAX_REVIEW_ITERATIONS:-4} (default 4; env-overridable, configurable in Ralph's config.env) and the verdict is still NEEDS_WORK, BREAK the loop and escalate: surface the surviving findings to the caller and stop (in Ralph mode output <promise>RETRY</promise> so the next iteration starts fresh). Never loop unbounded. The per-backend workflow files defer to this cap. The cap is now ALSO enforced deterministically by flowctl (fn-90 R5): each flowctl <backend> plan-review dispatch increments a cumulative spec-scoped counter (plan_review_rounds) and REFUSES at ${MAX_REVIEW_ITERATIONS:-4} with an ESCALATE: marker + exit 4 — the flowctl counter survives across fresh /flow-next:plan-review invocations, so a caller-side "re-invoke until SHIP" outer loop can no longer reset the cap by re-entering. This loop is INTERNAL — the caller (e.g. /flow-next:plan, pilot) invokes plan-review ONCE and acts on the terminal verdict; the flowctl counter resets ONLY on a SHIP verdict or an explicit re-plan (flowctl spec reset-review-rounds <spec-id>), never on a fresh invocation or a spec edit.

If verdict is NEEDS_WORK, loop internally until SHIP or the iteration cap:

  1. Parse issues from reviewer feedback
  2. Fix spec (stdin preferred, temp file if content has single quotes): 
    # Preferred: stdin heredoc
$FLOWCTL spec set-plan <SPEC_ID> --file - --json <<'EOF'
<updated spec content>
EOF

# Or temp file — literal unique path per the path-persistence rule
$FLOWCTL spec set-plan <SPEC_ID> --file "${TMPDIR:-/tmp}/flow-plan-review-updated-plan-<spec-id>-<suffix>.md" --json
  3. Sync affected task specs - If spec changes affect task specs, update them: 
    $FLOWCTL task set-spec <TASK_ID> --file - --json <<'EOF'
<updated task spec content>
EOF
    Task specs need updating when spec changes affect:
    • State/enum values referenced in tasks
    • Acceptance criteria that tasks implement
    • Approach/design decisions tasks depend on
    • Lock/retry/error handling semantics
    • API signatures or type definitions
  4. Re-review:
    • Codex: Re-run flowctl codex plan-review (receipt enables context)
    • Copilot: Re-run flowctl copilot plan-review (receipt enables context; must be mode == "copilot" to resume)
    • Cursor: Re-run flowctl cursor plan-review (receipt enables context; must be mode == "cursor" to resume)
    • RP: $FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file <literal re-review path from workflow.md's fix loop> (NO --new-chat; stdout redirected to the same literal response file, Read once)
  5. Repeat until <verdict>SHIP</verdict> — or the MAX ITERATIONS cap above breaks the loop (escalate with surviving findings)

Recovery: If context compaction occurred during review, restore from checkpoint:

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

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