Flux impl review

Implementation Review Mode

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

Lightweight per-task review using a single model. Catches obvious bugs and issues before moving to the next task. The heavy-weight review (adversarial dual-model, external bot self-heal, browser QA, learning capture) runs once at epic completion via /flux:epic-review.

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

Session Phase Tracking

On entry (after FLUXCTL is resolved), set the session phase:

$FLUXCTL session-phase set impl_review

On completion, reset:

$FLUXCTL session-phase set idle

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

PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
FLUXCTL="${PLUGIN_ROOT}/scripts/fluxctl"

Backend Selection

Priority (first match wins):

1. --review=rp|codex|export|none argument
2. FLUX_REVIEW_BACKEND env var (rp, codex, none)
3. .flux/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=$($FLUXCTL review-backend)

if [[ "$BACKEND" == "ASK" ]]; then
  echo "Error: No review backend configured."
  echo "Run /flux: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 $FLUXCTL 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
• Use flux-receive-review when interpreting reviewer comments or deciding whether to push back.

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.

PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
FLUXCTL="${PLUGIN_ROOT}/scripts/fluxctl"
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
$FLUXCTL architecture status --json

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
  $FLUXCTL codex impl-review "$TASK_ID" --base "$BASE_COMMIT" --receipt "$RECEIPT_PATH"
else
  $FLUXCTL 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).

If the implementation changes high-level architecture and .flux/brain/codebase/architecture.md was not updated, treat that as a real review issue rather than optional cleanup.

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. Identify changes (use BASE_COMMIT if provided)
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 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 fluxctl codex impl-review (receipt enables context)
   • RP: $FLUXCTL 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.

Before replying that an issue is fixed or advancing to SHIP, apply flux-verify-claims.

Note: This is a lightweight per-task pass. The full adversarial review (dual-model consensus, external bot self-heal, browser QA, learning capture) runs at epic completion via /flux:epic-review.

---

Human Review (After SHIP)

Only runs if review.humanReview is true in .flux/config.json.

After the reviewer returns <verdict>SHIP</verdict>, check config:

HUMAN_REVIEW=$($FLUXCTL config get review.humanReview 2>/dev/null || echo "false")

If HUMAN_REVIEW is true, ask the user:

Review passed — SHIP. Want to review the diff yourself before moving on? If you spot a pattern you do not want repeated in this repo, reply with it and Flux will help decide whether it should become a project rule (for example a lintcn rule).

If the user says yes, print the command and move on immediately (non-blocking):

┌─────────────────────────────────────────────────────┐
│  Run this in a separate terminal to review the diff │
│                                                     │
│  bunx critique ${BASE_COMMIT:-main}                 │
│                                                     │
│  Install Critique (requires Bun):                   │
│  curl -fsSL https://bun.sh/install | bash           │
│  bun install -g critique                            │
└─────────────────────────────────────────────────────┘

If the user comes back with a manual review finding, do not treat it as an unstructured comment. Invoke review-for-engineering-taste and run the structuralization checkpoint in ../../docs/review-structuralization.md:

• confirm whether the pattern was actually undesirable here
• decide whether it is an objective anti-pattern, a project convention, or a one-off
• if it is confirmed and machine-detectable, recommend or implement a lintcn rule
• default new taste-driven rules to warn unless the pattern is clearly an objective anti-pattern

If the user says no, or if HUMAN_REVIEW is false, skip silently.

Do NOT block on the external review command finishing. But if the user reports findings in-session, process them through the checkpoint before closing the review thread.

---

Update Check (End of Command)

ALWAYS run at the very end of /flux:impl-review execution:

PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
UPDATE_JSON=$("$PLUGIN_ROOT/scripts/version-check.sh" 2>/dev/null || echo '{"update_available":false}')
UPDATE_AVAILABLE=$(echo "$UPDATE_JSON" | jq -r '.update_available')
LOCAL_VER=$(echo "$UPDATE_JSON" | jq -r '.local_version')
REMOTE_VER=$(echo "$UPDATE_JSON" | jq -r '.remote_version')

If update available, append to output:

---
Flux update available: v${LOCAL_VER} → v${REMOTE_VER}
Update Flux from the same source you installed it from, then restart your agent session.
---