Code Review

Analyze local git changes (or a PR/MR) against the project's coding guidelines, using 5 to 7 parallel review agents for comprehensive coverage. High-signal findings only: bugs, logic errors, security issues, guideline violations. Excludes style concerns, subjective suggestions, and linter-catchable issues.

Step 1: Parse Arguments and Verify Prerequisites

Parse invocation arguments

Extract from the user's arguments:

1. deep flag (present/absent)
2. harness keyword after deep (present/absent)
3. --branch flag (present/absent) — overrides Step 3's PR auto-route. Has no effect when local changes are present or when an explicit PR is requested (--pr N, #N, or a PR URL). Recorded as force-branch-diff for Step 3.
4. Everything else → scope/focus instructions (natural language, including PR numbers, paths, refs)

Examples:

• /optimus:code-review → local changes, normal mode
• /optimus:code-review src/auth → scope to path, normal mode
• /optimus:code-review --pr 42 or /optimus:code-review #42 → PR mode, normal
• /optimus:code-review --branch → branch diff against the detected base, skip PR auto-route
• /optimus:code-review deep → local changes, deep mode (8 iterations)
• /optimus:code-review deep --branch → branch diff against the detected base, deep mode
• /optimus:code-review deep "focus on src/auth" → scoped, deep mode
• /optimus:code-review deep harness → harness mode (present command and stop)
• /optimus:code-review deep harness "focus on src/auth" → harness mode, scoped

Multi-repo workspace detection

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md for workspace detection. If a multi-repo workspace is detected:

• Run the git commands below inside each child repo (the workspace root has no .git/, so git commands must target individual repos)
• For PR/MR mode, the user must specify which repo — PRs/MRs belong to individual repos
• If changed files cannot be mapped to any child repo (e.g., files at the workspace root), ask the user which repo's context to apply
• Prerequisite loading in Step 4 will resolve per-repo docs independently

Documentation prerequisites

Read $CLAUDE_PLUGIN_ROOT/skills/init/references/prerequisite-check.md and apply the prerequisite check (CLAUDE.md + coding-guidelines.md existence, fallback logic).

Step 2: Deep Mode Activation

Harness mode detection

If the system prompt contains HARNESS_MODE_ACTIVE, read $CLAUDE_PLUGIN_ROOT/references/harness-mode.md and follow its single-iteration execution protocol. The reference covers progress file reading, state initialization, scope and file-list rules, Step 3 / Step 4 overrides under harness mode, and the Step 9 apply/output protocol. Then proceed through Step 3, Step 4, and Step 5 — skip only the Step 2 user confirmation.

If HARNESS_MODE_ACTIVE is NOT in the system prompt, continue with the standard interactive flow below.

Skill-triggered harness invocation

If the harness keyword was detected in Step 1, read the Skill-Triggered Invocation section of $CLAUDE_PLUGIN_ROOT/references/harness-mode.md and follow its steps. Pass:

• skill_name = code-review
• scope = scope text from Step 1 argument parsing
• max_iterations = not specified (use harness default)

The reference protocol presents the command and stops. Do not proceed to Step 3 or any remaining steps.

Interactive deep mode

If the deep flag was detected in Step 1 (without harness), activate deep mode. Deep mode loops review-fix cycles (Steps 5–9) until zero new findings remain or 8 iterations are reached, then presents a single consolidated report with all fixes already applied as local changes.

Before proceeding, check whether a test command is available (from .claude/CLAUDE.md). If no test command exists, deep mode's auto-apply loop has no safety net — fall back to normal mode and warn: "Deep mode requires a test command for safe auto-apply. Falling back to normal mode — re-run /optimus:init to set up test infrastructure first." Then continue with the standard single-pass flow.

If a test command is available, warn the user:

Deep mode runs up to 8 iterative review-fix passes. Each iteration is a full multi-agent review cycle — credit and time consumption multiplies with iteration count. Fixes are applied automatically at each iteration without per-change approval. Low test coverage increases the chance of undetected breakage; consider running /optimus:unit-test first to strengthen the safety net. Each iteration also accumulates context — on large codebases, output quality may degrade in later iterations.

Test command: [test command from CLAUDE.md]

Then use AskUserQuestion — header "Deep mode", question "Proceed with deep mode?":

• Start deep mode — "Run iterative review-fix until clean (max 8 iterations)"
• Normal mode — "Single pass with manual approval instead"

Tell the user: Tip: For large codebases or extended sessions, re-run with /optimus:code-review deep harness to launch the external harness with fresh context per iteration.

If the user did not invoke with deep, skip this step.

If the user selects Normal mode, continue with the standard single-pass flow. Record the user's choice as a deep-mode flag for subsequent steps. If deep mode is confirmed, initialize iteration-count to 1, total-fixed to 0, total-reverted to 0, and accumulated-findings to an empty list. Each entry in accumulated-findings tracks: file (with line), category (Bug, Security, Guideline Violation, Code Quality, Test Coverage Gap, Contract Quality, Intent Mismatch), guideline (the specific project rule, or "General: bug/security/contract quality"; for Intent Mismatch findings the literal string Intent (see Intent claim)), intent claim (only for Intent Mismatch — the quoted claim from ## Intent), summary (one-sentence description of the issue), fix description (brief description of the fix applied or attempted), iteration (which iteration discovered it), and status (updated through apply/test phases). See Step 7 "Deep mode accumulation" for the canonical entry-shape spec.

Step 3: Determine Review Scope

Detect and gather the changes to review. Use the scope/focus instructions parsed in Step 1.

Local changes (default flow)

Run the following git commands to gather all local changes:

# Staged changes
git diff --cached --stat
git diff --cached

# Unstaged changes to tracked files
git diff --stat
git diff

# Untracked files
git status --short

• If local changes found → review them (staged + unstaged + untracked)
• If no local changes → detect the comparison base and check for commits ahead:
  1. Detect platform — read $CLAUDE_PLUGIN_ROOT/skills/pr/references/platform-detection.md and use the Platform Detection Algorithm section to determine if the project is GitHub, GitLab, or unknown.
  2. Detect PR/MR target branch — check if an open PR/MR exists for the current branch and extract its target branch:
     • If GitHub: gh pr view --json number,state,baseRefName 2>/dev/null — only use number and baseRefName if state equals "OPEN"; if state is not "OPEN", treat as "no open PR"
     • If GitLab: glab mr view --output json 2>/dev/null — only use iid and target_branch if state equals "opened"; if state is not "opened", treat as "no open MR". If the command fails, treat as no open MR — unless the failure appears to be an auth or connectivity error, in which case inform the user before falling back
     • If platform unknown: try both, ignore CLI-unavailable errors — use the first result where an open PR/MR is confirmed (state check passed)
     • If no open PR/MR found or CLI unavailable → detect the default branch using $CLAUDE_PLUGIN_ROOT/skills/pr/references/default-branch-detection.md
  3. Use the detected branch as <base-branch> and capture the curre