flow-next-impl-review
John Carmack-level implementation review via flowctl rp wrappers. Use when reviewing code changes, PRs, or implementations. Triggers on /flow-next:impl-review.
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.
| name | flow-next-impl-review |
|---|---|
| description | John 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):
--review=rp|codex|export|noneargumentFLOW_REVIEW_BACKENDenv var (rp,codex,none).flow/config.json→review.backend- Error - no auto-detection
Parse from arguments first
Check $ARGUMENTS for:
--review=rpor--review rp→ use rp--review=codexor--review codex→ use codex--review=exportor--review export→ use export--review=noneor--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:
- DO NOT REVIEW CODE YOURSELF - you coordinate, RepoPrompt reviews
- MUST WAIT for actual RP response - never simulate/skip the review
- MUST use
setup-review- handles window selection + builder atomically - DO NOT add --json flag to chat-send - it suppresses the review response
- Re-reviews MUST stay in SAME chat - omit
--new-chatafter first review
For codex backend:
- Use
$FLOWCTL codex impl-reviewexclusively - Pass
--receiptfor session continuity on re-reviews - Parse verdict from command output
For all backends:
- If
REVIEW_RECEIPT_PATHset: 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:
- Parse issues from reviewer feedback (Critical → Major → Minor)
- Fix code and run tests/lints
- Commit fixes (mandatory before re-review)
- 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)
- Codex: Re-run
- 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.