flow-next-impl-review

gmickel's avatarfrom gmickel

John Carmack-level implementation review via flowctl rp wrappers. Use when reviewing code changes, PRs, or implementations. Triggers on /flow-next:impl-review.

⭐32stars🔀3forks📁View on GitHub🕐Updated Jan 9, 2026⬇️4downloads

When & Why to Use This Skill

This Claude skill provides high-performance, 'John Carmack-level' implementation reviews for code changes and pull requests. By coordinating advanced backends like RepoPrompt and Codex, it automates the detection of architectural flaws and code quality issues, offering an autonomous fix-and-review loop to ensure production-grade software standards without manual intervention.

Use Cases

  • Automated PR Auditing: Conduct deep-dive reviews of branch changes against the main codebase to identify logic errors, performance bottlenecks, and architectural anti-patterns.
  • Task-Scoped Implementation Review: Use the --base flag to focus review efforts on specific commits or task IDs, providing targeted feedback for incremental feature development.
  • Autonomous Quality Assurance Loop: Execute an internal fix-and-commit cycle where the agent automatically addresses reviewer feedback, commits improvements, and re-validates code until it meets 'SHIP' standards.
  • Standardized Code Governance: Enforce high-level engineering standards across a team by using consistent review backends (RepoPrompt/Codex) and automated verdict parsing.
nameflow-next-impl-review
descriptionJohn Carmack-level implementation review via RepoPrompt or Codex. Use when reviewing code changes, PRs, or implementations. Triggers on /flow-next:impl-review.

Implementation Review Mode

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

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

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

⚠️ RepoPrompt 1.6.0+ Required: The RP backend now uses builder review mode which requires RepoPrompt 1.6.0 or later. Check version: rp-cli --version

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

FLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl"

Backend Selection

Priority (first match wins):

  1. --review=rp|codex|export|none argument
  2. FLOW_REVIEW_BACKEND env var (rp, codex, none)
  3. .flow/config.json → review.backend
  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=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|none"
  exit 1
fi

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

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 impl-review exclusively
  2. Pass --receipt for session continuity on re-reviews
  3. 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>] [focus areas]

  • --base <commit> - Compare against this commit instead of main/master (for task-scoped reviews)
  • 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)

Workflow

See workflow.md for full details on each backend.

FLOWCTL="${CLAUDE_PLUGIN_ROOT}/scripts/flowctl"
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)
  • 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).

Step 1: Detect Backend

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

Codex Backend

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

# Use BASE_COMMIT if provided, else fall back to main
if [[ -n "$BASE_COMMIT" ]]; then
  $FLOWCTL codex impl-review "$TASK_ID" --base "$BASE_COMMIT" --receipt "$RECEIPT_PATH"
else
  $FLOWCTL codex impl-review "$TASK_ID" --base main --receipt "$RECEIPT_PATH"
fi
# Output includes VERDICT=SHIP|NEEDS_WORK|MAJOR_RETHINK

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

RepoPrompt Backend

# Step 1: Identify changes (use BASE_COMMIT if provided, else main/master)
git branch --show-current
if [[ -n "$BASE_COMMIT" ]]; then
  DIFF_BASE="$BASE_COMMIT"
else
  DIFF_BASE="main"
  git rev-parse main >/dev/null 2>&1 || DIFF_BASE="master"
fi
git log ${DIFF_BASE}..HEAD --oneline
git diff ${DIFF_BASE}..HEAD --name-only

# Step 2: Atomic setup
eval "$($FLOWCTL rp setup-review --repo-root "$REPO_ROOT" --summary "Review implementation: <summary>")"
# Outputs W=<window> T=<tab>. If fails → <promise>RETRY</promise>

# Step 3: Augment selection (add changed files)
$FLOWCTL rp select-add --window "$W" --tab "$T" path/to/changed/files...

# Step 4: Build and send review prompt (see workflow.md)
$FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/review-prompt.md --new-chat --chat-name "Impl Review: [BRANCH]"

# Step 5: Write receipt if REVIEW_RECEIPT_PATH set

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.

If verdict is NEEDS_WORK, loop internally until SHIP:

  1. Parse issues from reviewer feedback (Critical → Major → Minor)
  2. Fix code and run tests/lints
  3. Commit fixes (mandatory before re-review)
  4. Re-review:
    • Codex: Re-run flowctl codex impl-review (receipt enables context)
    • 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.