Code Review: $ARGUMENTS
Review the code related to: $ARGUMENTS
Review grading
Use only these finding priorities, in descending order:
- Critical Issues (Must Fix): a verified path causes data loss, a security failure, a materially wrong operation, or makes a core workflow unusable without reasonable recovery.
- Improvements (Should Fix): an ordinary supported workflow demonstrably fails or repeatedly imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
- Suggestions (Nice to Have): a worthwhile improvement with small practical impact, including optional polish, local simplification, and rare recoverable edge cases.
Grade the demonstrated consequence, realistic reachability, and available recovery against project priorities. A category, missing convention, hypothetical future problem, or confidence that a claim is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep unverified claims in validation gaps, outside the graded finding count; distinguish suggestions from defects. For plans, trace the consequence if implemented and state the assumptions.
Use the short labels Must Fix, Should Fix, and Nice to Have in summaries and ledgers.
Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings
separate. When called by code-review, return its requested evidence and impact fields; the parent
owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.
Reference files (load what the run needs)
| File | Load when |
|---|---|
references/agents.md |
Step 3c in comprehensive mode — the per-agent briefs for Agents 1–10, plus how language / project / library-use reviews plug in. |
references/scoring-and-output.md |
Steps 4 to 5 in comprehensive mode — verdict and effort scoring, likelihood/blast-radius triage, applying autofix items, and the output format. |
Flag parsing, scope resolution, and the preflight cleanup (Steps 1–3b.6) need neither.
Usage
/code-review # Preflight cleanup + all 10 review aspects, default scope
/code-review --quick # One integrated review pass, no scorer-agent round
/code-review <target> # Preflight cleanup + all 10 aspects, scoped to target
/code-review --architecture # Architecture only
/code-review --functional # Functional principles only
/code-review --consistency # Consistency with existing codebase patterns only
/code-review --correctness # Logic, failure paths, and changing assumptions
/code-review --security --performance # Two aspects
/code-review --logic src/auth/ # One aspect, scoped to target
/code-review --typescript # TypeScript-specific review only
/code-review --project # Project's own review-project checks only
/code-review --library-use # Library-usage review only (vs the repo's library-use reference)
/code-review --all # Whole repo
/code-review --changed # Unstaged changes only
/code-review --staged # Staged changes only (errors if nothing staged)
/code-review --unpushed # Files changed across all unpushed commits (errors if nothing unpushed)
/code-review --multi # All aspects + external advisors
/code-review --multi --architecture # Architecture only + external advisors
/code-review --all --multi # Whole repo + external opinions
/code-review --re # Review, then re-review only what the fixes changed--re composes with comprehensive aspect selections, --quick, scope flags, or --multi. Invoked after an earlier review in the same conversation, it reviews only what changed since that review (Step 7) instead of starting over.
Review Modes
The default mode is comprehensive: run all selected perspectives independently, then independently score and triage their findings.
Every mode first runs review-tidy --fix over the resolved scope; it coordinates comment cleanup through review-comments and then mechanical cleanup, with formatting last. The cleanup is a preflight edit, not a review perspective: its results are reported separately and are never scored or promoted into Must Fix/Should Fix findings.
--quick runs one thorough integrated review at full reasoning effort, saving time through fewer agents and no separate scoring round. It keeps the normal scope resolution, project-guideline checks, severity output, fix prompt, and optional --re loop, but uses one integrated read-only reviewer and no separate scorer agents. It does not activate automatically from diff size: a tiny auth, migration, or concurrency change may still deserve the comprehensive mode.
--quick composes with a target, one scope flag, or --re. It cannot be combined with aspect flags or --multi; abort with --quick is a complete review preset; remove the aspect flags or --multi.
Aspect Selection
Aspect flags let you run a subset of the review agents instead of all 10. Flags are additive — pass as many as you want. Comment quality is absent from this list because its fix pass always runs before the selected review.
| Flag | Maps to |
|---|---|
--correctness / --logic / --defensive |
Agent 1: Correctness Review (reads review-correctness) |
--architecture |
Agent 2: Architecture Review (delegates to /review-architecture) |
--security |
Agent 3a: Security Review (inline + delegate to /review-security) |
--performance |
Agent 3b: Performance Review (inline + delegate to /review-perf) |
--history |
Agent 4: Historical Context Review (inline) |
--test |
Agent 5: Test Quality (delegates to /test --review) |
--interface |
Agent 6: Interface Design (delegates to /review-interfaces) |
--clean-code |
Agent 7: Clean Code (delegates to /review-cleancode) |
--functional |
Agent 7b: Functional Review (delegates to /review-functional) |
--consistency |
Agent 7c: Consistency Review (delegates to /review-consistency) |
Further aspects are conditional add-ons — in the default (no-aspect-flag) run they are included automatically when they apply; with explicit aspect flags they run only if their own flag is passed (see Step 3b.5 for detection):
| Flag | Maps to |
|---|---|
--cli / --react / --swiftui |
Agent 8b: Project-Shape Review — delegates to review-cli, review-react, or review-swiftui. Auto-included for console entry points, scoped React components, or scoped SwiftUI implementation. Orthogonal to language: it composes with the language review rather than replacing it. |
--typescript / --swift / --python |
Agent 8: Language Review — delegates to the matching review-<language> skill (e.g. review-typescript, review-swift, review-python). Auto-included when the scoped files are of that language. |
--project |
Agent 9: Project-Specific Review — delegates to the project's own review-project skill. Auto-included when that skill exists in the repo. |
--library-use |
Agent 10: Library-Use Review — delegates to review-library-use (checks code against the repo's library-use conventions). Auto-included when the repo has a library-use reference. |
Aspect rules:
- Normalize
--logicand--defensiveto--correctnessbefore selecting agents; any combination of these flags runs Agent 1 exactly once. - In comprehensive mode, no aspect flags → run all 10 core agents, plus any detected language and project-shape reviews, the project review, and the library-use review if present.
- One or more aspect flags → run only those agents, skip the rest. The conditional add-ons run only if
--typescript/--cli/--react/--swiftui/--project/--library-use(or another--<language>) is among the flags. --quickis a complete preset and cannot be combined with aspect flags.--multicomposes with any aspect selection.- The non-flag portion of
$ARGUMENTSis the review target (e.g.src/auth/).
Agents 8–10 are the plug-and-play extension layer (add a language by creating a review-<language> skill; add a shape by creating one like review-cli; a project adds its own review-project). Details in references/agents.md.
Scope Selection
Scope flags determine which files the reviewers inspect. The resolved scope is passed through to every review agent or delegated sub-skill.
| Flag | Meaning |
|---|---|
--staged |
Review staged changes only (git diff --cached). |
--unpushed |
Review files changed across unpushed commits only (git diff <last-pushed>..HEAD). |
--changed |
Review unstaged changes only (git diff). |
--all |
Review the whole repo (git ls-files). |
Scope rules:
- Exactly one scope flag may be passed. Multiple → error.
- Default (no scope flag): behave as
--stagedif anything is staged; otherwise auto-fall back to--changed. Announce the resolved mode at the start of the run so the user isn't surprised. (--unpushedis never auto-selected — it's opt-in only.) - Explicit
--stagedwith nothing staged: abort immediately withNothing staged. Re-run with --all or --changed.(Explicit ≠ default — no silent fallback.) - Explicit
--unpushedwith nothing unpushed: abort immediately withNothing unpushed. Re-run with --staged, --changed, or --all.If there is no remote/upstream (or the range walks back to the root commit) so the range can't be determined reliably, abort and ask the user to pick another scope. (Explicit ≠ default — no silent fallback.) - Target argument wins: if a non-flag target is provided (e.g.
/code-review src/auth/), it overrides scope flags entirely. The target is passed to all sub-agents as-is.
Gotchas
- Both modes silently drop findings that were not traced to a
file:linein the code. Comprehensive mode uses independent scorers; quick mode trades that independent validation for a single reviewer's self-filter. - The verdict is categorical, not a 0–100 score. A model-written number is not a measurement, and a cutoff between anchors flips when the same claim is scored twice.
- The verdict means "is this claim true", never "does it matter". A traced duplication or leaky interface passes as surely as a traced crash and lands in Suggestions or Should Fix by impact. Failing true design findings because they are "not a bug" silently deletes most clean-code and interface output. Effort only orders findings within a section; it never drops one.
- In comprehensive mode, Step 4.5's triage never drops anything silently — every issue routed out of the main severity sections appears in the
Improbable / Not Worth Handlingappendix with itsfile:lineand a one-line reason. Quick mode omits low/medium-impact improbable findings entirely to stay concise. - With
--staged, the preflight edits the working-tree copies and does not stage them. Announce that the cleanup must be staged separately; never rungit addimplicitly. - Reviewers run in parallel on one checkout. A reviewer that edits a file, even briefly to mutation-test, makes the others report its edit as a real bug. Every reviewer is read-only; experiments run in a disposable copy (see
references/agents.md).
Step 1: Locate and Read Project Guidelines
First, find and read any CLAUDE.md files in the repository root and relevant directories to understand project-specific conventions and rules.
Step 2: Identify Relevant Code
Search for and identify all files related to "$ARGUMENTS". Use Glob and Grep to find:
- Direct implementations
- Related tests
- Usages/consumers of this code
Step 3: Resolve Scope and Run the Review
3a. Parse flags
If the removed --comments aspect flag is passed, abort with Comment cleanup now runs automatically before every code review. Use review-comments directly for a standalone comment report.
Strip aspect flags (--correctness, --logic, --architecture, --security, --performance, --history, --test, --interface, --clean-code, --functional, --consistency, --defensive, --typescript, --project, --library-use), scope flags (--staged, --unpushed, --all, --changed), --quick, --multi, and --re from $ARGUMENTS. The remainder is the review target.
If --quick appears with any aspect flag or with --multi, abort with --quick is a complete review preset; remove the aspect flags or --multi. It may compose with a target, one scope flag, and --re.
In comprehensive mode, if any aspect flags are present, launch ONLY the corresponding agents (including the conditional add-ons only when a --<language>/--cli/--react/--swiftui/--project/--library-use flag is passed). Otherwise launch all 10 core agents plus whatever Step 3b.5 detects. In quick mode, follow the single-reviewer branch in Step 3c.
3b. Resolve scope
If a non-flag target was provided, skip this section — pass the target through to every agent as-is.
Otherwise, resolve the scope:
- If more than one scope flag was passed → error:
Pass only one of --staged, --unpushed, --all, --changed. - If
--stagedwas passed explicitly:- Run
git diff --cached --name-only. If empty → abort:Nothing staged. Re-run with --all or --changed. - Resolved scope:
staged.
- Run
- If
--unpushedwas passed explicitly:- Resolve the range:
git rev-list HEAD --not --remotes(oldest unpushed commit's parent → HEAD). If empty → abort:Nothing unpushed. Re-run with --staged, --changed, or --all.If there is no remote/upstream, or the range walks back to the root commit, abort and ask the user to pick another scope. - Resolved scope:
unpushed.
- Resolve the range:
- If
--changedwas passed: resolved scope ischanged. - If
--allwas passed: resolved scope isall. - If no scope flag was passed (default):
- Run
git diff --cached --name-only. If non-empty → resolved scope isstaged. - Otherwise → resolved scope is
changed. - Announce the resolution:
No scope flag — defaulting to --stagedorNo scope flag and nothing staged — defaulting to --changed.
- Run
Compute the file list once based on resolved scope:
staged→git diff --cached --name-onlyunpushed→git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEADchanged→git diff --name-onlyall→git ls-files
This file list is passed to inline agents and is also used to build the target argument for sub-skills that don't natively support --changed (see 3c).
3b.5. Detect language & project reviews
Determine which conditional add-on reviews apply. In comprehensive mode these become additional agents. In quick mode their skill/reference text becomes guidance for the single integrated reviewer. Skip this entirely if explicit aspect flags were passed and none of them is --typescript/--cli/--react/--swiftui/--project/--library-use/another --<language> — in that case the user asked for a specific subset and add-ons don't run.
Language detection registry. For each language below, it applies if the resolved file list matches its extensions, or (for the all scope / when the file list is empty) the repo root has its marker file. If it applies and a review-<language> skill is installed, include that agent in comprehensive mode or record its SKILL.md as guidance for quick mode.
| Language | File extensions | Repo marker | Skill |
|---|---|---|---|
| TypeScript | .ts .tsx .mts .cts |
tsconfig.json |
review-typescript |
| Swift | .swift |
Package.swift, *.xcodeproj, *.xcworkspace |
review-swift |
| Python | .py .pyi |
pyproject.toml, setup.py |
review-python |
| Rust | .rs |
Cargo.toml |
review-rust |
(To add a language: create a review-<language> skill and add a row here.)
Project-shape detection. Shapes are orthogonal to language — a CLI is reviewed the same way whether it is Python or Rust. If the shape applies and the matching skill is installed, include that agent in comprehensive mode or record its SKILL.md as guidance for quick mode. If the skill is not installed, skip silently.
| Shape | Detected by | Skill |
|---|---|---|
| CLI | [project.scripts] / [project.entry-points."console_scripts"] in pyproject.toml, [[bin]] or src/main.rs in a Cargo project, bin in package.json, or a main-package cobra/urfave import in Go |
review-cli |
| React | react in package.json dependencies, and scoped .jsx/.tsx files or files that call hooks (at all scope, the dependency alone) |
review-react |
| SwiftUI | Scoped SwiftUI view, scene, modifier, or control implementation, or UI resources consumed by it; at all scope, that implementation anywhere in the project. An import or a Swift project marker alone is insufficient |
review-swiftui |
In default reviews, when Swift and SwiftUI both apply, include both reviewers. Explicit
aspect flags still select only the requested reviewers. review-swift owns state, identity,
lifetime, dependencies, concurrency, and rendering cost; review-swiftui owns presentation
and interaction. Pass this boundary to both and deduplicate by the underlying cause.
Project review detection. If the repo defines its own project review skill at .claude/skills/review-project/SKILL.md or .agents/skills/review-project/SKILL.md, include the project review agent in comprehensive mode or record its SKILL.md as guidance for quick mode. If neither exists, skip silently.
Library-use review detection. If the repo has a library-use reference at .claude/skills/library-use/SKILL.md or .agents/skills/library-use/SKILL.md, include the review-library-use agent in comprehensive mode or record the reference as guidance for quick mode. If neither exists, skip silently (suggesting library-docs once is fine, but don't block the review).
Check both paths — .claude/skills/ is where Claude Code puts project skills; .agents/skills/ is where the other harnesses discover them. In some projects the latter is a symlink to the former, so either check finds it; others may only have .agents/skills/.
Announce what got auto-included. In comprehensive mode, use messages such as Detected TypeScript — adding review-typescript or Detected a CLI entry point — adding review-cli. In quick mode, say Detected TypeScript — applying review-typescript guidance in the quick review (and likewise for project and library-use guidance).
3b.6. Preflight cleanup
::: claude codex opencode
Before launching any review agent, invoke review-tidy --fix exactly once against the resolved scope. It owns the review-comments invocation and runs formatting after all cleanup edits; do not invoke comment cleanup separately.
:::
::: pi
Before launching any review agent, run review-tidy --fix exactly once against the resolved scope — in this session, not as a subagent. pi has no Skill tool, so read its SKILL.md and apply it directly, including its nested review-comments instructions. Do not invoke comment cleanup separately. Cleanup edits files, which the read-only reviewer agent cannot do; agent: names an agent, never a skill.
:::
| Resolved scope | Arguments for review-tidy |
|---|---|
staged |
--staged --fix |
unpushed |
--unpushed --fix |
changed |
--changed --fix |
all |
--all --fix |
| local path target | <target> --fix |
| other target, such as a PR | <resolved local source file list> --fix |
Treat its combined output as a preflight cleanup summary, not as review findings. Report how many comments were removed or rewritten and what mechanical fixes were applied, and list the deferred items, but do not send those items through scoring or severity triage. Continue immediately when they find nothing.
If a non-file target has no writable local source files, skip the cleanup and state that it requires a local checkout; do not turn that limitation into a review finding.
Keep the file list resolved in Step 3b even if cleanup edits change git status. Review the current contents of those same files, using the originally resolved diff or target to identify the intended change. With staged scope, explicitly say the cleanup edits are unstaged and must be staged separately; do not mutate the index.
3c. Run the selected mode
Quick mode (--quick)
::: claude codex opencode
Do not load references/agents.md. Launch exactly one read-only review agent and give it the resolved scope or target. Use the same model and reasoning effort as a comprehensive reviewer; do not select a faster profile or lower effort for quick mode. It must not delegate to sub-skills or dispatch more agents.
:::
::: pi
Do not load references/agents.md. Launch exactly one child via subagent using the builtin reviewer agent, and give it the brief below plus the resolved file list. reviewer grants only read, grep, find, ls — no bash, no edit, no nested dispatch — so it is read-only by construction. Because it has no bash it cannot resolve a scope itself: pass the concrete file list, not --staged.
:::
For every harness, retain full review reasoning effort. Give the reviewer this integrated brief:
- Read the applicable
AGENTS.md/CLAUDE.mdfiles and the scoped diff or files. For each changed behavior, trace the path from its callers through the implementation and dependencies to its observable result, including failure paths. Read surrounding code and related tests to check the contracts at each boundary; do not stop at the diff hunks. For a whole-file or whole-repo target, trace the main behaviors in scope. - Read
review-correctnessand apply both passes directly without launching another reviewer. Review correctness, edge cases, error handling, regressions, catch-allelse/defaultbranches that would silently absorb a newly added enum or API value, missing or weak tests, security red flags, and interface compatibility. Check performance hazards supported by the traced paths. Also check design and maintainability: module responsibilities, coupling, duplication, interface clarity, hidden shared state, and mutation of caller-owned data. Check consistency: compare each added construct with two or more existing siblings of the same kind and flag divergences in naming, placement, mechanism (errors, logging, config, existing helpers) or registration, citing the precedentfile:lines; documented project rules and newer patterns win over older precedent. Tie each concern to concrete code and its consequences. - If Step 3b.5 detected language, project-shape, project, or library-use guidance, read those matching
SKILL.mdfiles as review references and apply their checks directly. Do not invoke them as skills. - Before accepting or dismissing a suspected issue, trace a concrete triggering input or state, inspect callers and excluding guards, and check whether tests exercise the behavior and assert the relevant result. Use targeted checks when available; run any experiment that writes files in a disposable copy. If the reviewer lacks execution tools, request a specific check from the parent, which must resolve it before final filtering or report the remaining uncertainty.
- Return only actionable findings supported by a concrete code path. For each finding, include severity (
Must Fix,Should Fix, orNice to Have, using Review grading above),file:line, what is wrong, why it matters, a concise fix, thefile:linewhere you traced it, effort (S: one file, local, no interface or test changes;M: several files or new or changed tests;L: a public interface, a migration, or callers in other modules), likelihood (routine,plausible,rare, ortheoretical), and blast radius (low,medium, orhigh). Forrareortheoretical, name the reachability reason and cite any excluding guard. - After verification, omit findings you did not trace through every link in the code and omit
rare/theoreticalfindings with low or medium blast radius. Keep rare high-blast-radius findings and tag them with the short reachability reason. Tracing decides only whether the claim is true; a true finding that matters little isNice to Have, not dropped. - Tag a finding
autofixwhen its fix cannot change production behaviour, any change in what a test executes is proven by running tests, and a wrong call would be visible in the diff and cheap to revert. It must not need new prose, a design choice, or an edit to exported or public code. Examples: a doc line naming a symbol or flag the diff renamed, an import the diff orphaned, a test name that no longer matches, an unexported identifier renamed to the codebase's naming pattern. When the fix changes what a test executes, appendverify: suiteif test code moves unchanged, orverify: mutationif it substitutes different test code. - Do not edit the shared checkout, even temporarily; keep any experiment writes in a disposable copy.
- Always return a short coverage statement naming the behaviors traced, callers/dependencies and tests examined, and checks actually run. State any unexamined scope, checks not run, and material unresolved uncertainties; distinguish these from confirmed findings. Do not infer safety from missing evidence.
- Return
No actionable findings.if nothing survives, followed by the coverage statement and any limitations.
After the agent returns, resolve any requested verification checks before final filtering, without launching more reviewers or scorers. Apply its autofix findings yourself after checking each still meets that test, and list them under Applied automatically; a finding that fails the test goes to its severity section instead. Run a verify: item's check first, in a disposable copy with the fix applied: for verify: suite the full test suite must pass under timeout; for verify: mutation the affected tests must pass, then fail once you break the behaviour they assert in the code under test (grep to confirm the break landed). An item whose check fails or cannot run goes to its severity section. Deduplicate the rest and render the surviving items under Critical Issues (Must Fix), Improvements (Should Fix), and Suggestions (Nice to Have), omitting empty sections. Within a section, list S findings first, then M, then L, each prefixed with its effort tag ([S], [M], [L]). Explain what is wrong, why it matters, and how to fix it. Include the coverage statement and material limitations even when there are no findings. Do not show likelihood or blast-radius metadata and do not launch scorer agents. Then continue to Step 5.5.
Comprehensive mode
Load references/agents.md — it carries the brief for each of Agents 1–10.
Launch the selected review perspectives in parallel, queuing successive batches when runtime capacity requires it.
One agent per perspective. Never pair two aspects in one brief to save agents, not even small ones. A capacity limit queues reviewers; it never merges them. A past run paired functional with consistency, and the consistency half came back covering only what its brief listed.
Brief with the scope, not a checklist of where to look. Give each reviewer the resolved scope or file list, the project facts it cannot cheaply discover, and its aspect brief from references/agents.md. Do not list the units, files or precedents it should examine: a reviewer handed "focus on X, Y, Z" reviews X, Y and Z, and the rest of the diff goes unreviewed for that aspect. If a fact about one file matters, state it as context and say the whole file list remains in scope.
::: claude
Claude Code caps concurrent subagents at CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Launch up to that many at once, then launch each remaining reviewer as soon as one returns. A launch refused with Concurrent subagent limit reached never ran: despite the message's "Do not retry", queue it and launch it when a slot frees, and never drop the aspect. The same limit applies to the scorer round.
:::
::: claude codex opencode
Launch workers that return findings without editing files, including temporary edits: a reviewer that mutates a file to test something and restores it still corrupts what the parallel reviewers read. Include the shared rules from references/agents.md in every brief. Disable delegation tools for ordinary reviewers where supported; read-only access alone does not prevent delegation. If a reviewer coordinates verification, name the checks, bound the descendants, and define when it should stop. Workers can read the relevant sub-skill directly when their harness has no Skill tool.
:::
::: pi
Launch them read-only, as one subagent workflow. pi fans out through a workflowScript, not through repeated tool calls — one subagent call carrying runs.all([...]), one entry per perspective, every entry on the builtin reviewer agent:
:::
::: pi
{ workflowScript: `
const results = await runs.all([
{ key: "correctness", agent: "reviewer", task: "<brief for Agent 1 + resolved file list>" },
{ key: "security", agent: "reviewer", task: "<brief for Agent 3 + resolved file list>" }
]);
return results.map(r => r.output);
` }:::
::: pi
reviewer grants only read, grep, find, ls, so it cannot edit the code it reviews and cannot dispatch further. Use it for the scorer round in Steps 4–5 too. Two pi-specific rules:
- The
agentfield takes a pi agent name, never a skill name. The builtins arescout,researcher,worker,reviewer,oracle,delegate; custom agents live in~/.pi/agent/agents/.{ agent: "review-security" }fails the whole workflow withUnknown agent: review-security. Every harness works this way — identity comes from the agent registry, the task comes from the prompt — so this is not a pi quirk. - Children reach a sub-skill as a file, not as a tool call. pi has no Skill tool.
reviewerruns withinheritSkills: true(set inloadout/settings/pi.jsonundersubagents.agentOverrides), so it sees the skills catalog and loads aSKILL.mdwithreadwhen a brief names one. :::
Each agent should output a list of issues. For each issue, include: what the problem is, where it is (file + line), and why it matters, and tag safe fixes autofix as defined in references/agents.md. Do NOT assign verdicts or effort — scoring happens in a separate pass.
::: claude codex opencode
Sub-agent invocation pattern. When a sub-agent delegates to a sub-skill, pass the resolved scope through directly:
:::
::: pi
Sub-agent invocation pattern. Name the sub-skill in the child's task and let it read that SKILL.md itself — delegation works, it just resolves through the filesystem rather than a Skill tool. What does not carry over is the scope flag: reviewer has no bash, so it cannot turn --staged into a file list. Pass the concrete list resolved in Step 3b instead. The table below is therefore read as scope→file-list on pi, not scope→flag.
:::
::: claude codex opencode
| Resolved scope | Argument passed to sub-skill |
|---|---|
staged |
--staged |
unpushed |
--unpushed |
changed |
--changed |
all |
--all |
| target given | the target itself (e.g. src/auth/) |
All delegated review sub-skills (review-architecture, review-security, review-perf, review-interfaces, review-cleancode, review-functional, review-consistency, review-correctness, review-typescript, test --review) accept --staged | --unpushed | --changed | --all. No special-casing needed. The project's review-project skill is expected to accept the same scope flags — if it doesn't, pass it the target/file list instead.
::: Inline agents (no delegation) work directly against the file list computed in step 3b.
Step 3.5: External Advisor Reviews (--multi only)
If --multi flag is present in $ARGUMENTS, also get external opinions:
::: claude codex opencode
Use the Skill tool to invoke second-opinion --quick, which queries every external advisor it has configured, in parallel. (The advisor roster lives in the second-opinion skill — don't enumerate it here.) Phrase the prompt according to the resolved scope from step 3b:
:::
::: pi
pi has no Skill tool. Read second-opinion/SKILL.md from the skills directory and run its advisor commands yourself with bash, backgrounding them so they run in parallel. Do not dispatch second-opinion as a subagent — it is a skill name, not an agent name. Phrase the prompt according to the resolved scope from step 3b:
:::
staged→ "Review the staged changes (git diff --cached) in this repository."unpushed→ "Review the changes across all unpushed commits (git diffagainst the last pushed commit) in this repository."changed→ "Review the unstaged changes (git diff) in this repository."all→ "Review the codebase in this repository as a whole."- target given → "Review the following target in this repository:
<target>."
Then append: "Provide a focused code review in 300 words or less covering: potential bugs or edge cases, security concerns, performance issues, and architecture/pattern violations."
IMPORTANT: Do NOT proceed to Step 4 until the second-opinion results have been fully received. Wait for all background commands to complete and collect their output before continuing. This prevents completion notifications from appearing after the review summary. If an advisor is missing or errors out, continue with whichever responded — don't drop the others.
Steps 4 to 5: Score, Triage, Autofix, Format (comprehensive mode only)
Skip these steps in quick mode; Step 3c already produced the filtered, formatted review. In comprehensive mode, load references/scoring-and-output.md and follow it. In short: score every issue with independent parallel scorers using the exact prompt there (only traced passes, and the verdict means only "is this true"), have those same scorers return impact, effort, likelihood and blast radius so improbable findings route to an appendix instead of the work list, apply the autofix items, then render the severity sections.
When that reference is done, come back here and do Steps 5.5 and 6 — the rendered output is not the end of the run.
Step 5.5: Snapshot the reviewed state
In both modes, after the output is rendered and any autofix items are applied, record what was reviewed so a re-review can find what changed since. In the session's scratch directory:
- copy every existing file in the Step 3b file list to
cr-snapshot/<round>/, keeping its repo-relative path; - save
git status --porcelainthere asstatus.txt; - save the findings list as
findings.md: each finding's aspect,file:line, one-line claim and section. Step 6 adds each one's disposition (fixed,declined, orappendix) once known.
Do not use git stash, commits or any other git write for this. The snapshot is local scratch, not history.
Step 6: Offer to Fix
This step is mandatory. Rendering the review output is not the end of the workflow — do not end the turn after printing the findings. If there is at least one Must Fix or Should Fix finding, you MUST call the AskUserQuestion tool so the user picks a fix scope by selection instead of typing one out.
Build the options list from the severity tiers that actually have findings, most-inclusive first:
| Option | Fixes | Include when |
|---|---|---|
| "Fix everything" | Must Fix + Improvements + Suggestions | there are Suggestions (Nice to Have) findings alongside at least one Must Fix or Should Fix finding |
| "Address Must Fix + Should Fix" | Must Fix + Improvements | there are both Must Fix and Should Fix findings |
| "Address Must Fix only" | Must Fix | there are Must Fix findings |
| "Fix Should Fix" | Improvements | there are Should Fix findings but no Must Fix findings |
| "Don't fix anything" | nothing | always — last option |
AskUserQuestion takes at most 4 options, so when all tiers are populated drop the narrowest fix option (Address Must Fix only) rather than Don't fix anything — the user can still ask for a narrower scope in free text.
Skip this step entirely (no prompt) only when there are no Must Fix and no Should Fix findings — a run that surfaced nothing but suggestions has nothing worth gating on.
Build the options only from the Critical Issues, Improvements, and Suggestions sections. Applied automatically items are already done and are never offered. Never include Improbable / Not Worth Handling items — not even under "Fix everything". Step 4.5 already judged them not worth doing, and offering to fix them reintroduces exactly the noise the appendix exists to remove.
When the user selects a fix option, apply the fixes for exactly the chosen severity tier(s) — no more, no less. Record each finding's disposition in the snapshot's findings.md.
Code written to fix a finding has not been reviewed. Without --re, end the run with a Not yet reviewed line naming the files the fixes changed, and suggest /code-review --re, which reviews only those changes.
Step 7: Re-Review the Fixes (--re)
A re-review checks only what changed since the last snapshot: the fixes, plus anything else edited since. It is not a second full review, and it does not re-run the preflight cleanup on unchanged files.
It runs in two cases:
--rewas passed and Step 6 applied fixes: continue straight into it./code-review --reis invoked and an earlier review in this conversation left a Step 5.5 snapshot: skip Steps 1–6 and start here from the latest snapshot. This covers fixes applied after the review ended, by the user or by a calling skill. With no snapshot in the conversation, run a normal review that loops as in the first case.
Announce it, e.g. Re-reviewing the 4 files changed since the review (--re).
7a. Compute the delta
Compare each snapshot file with its current content (git diff --no-index), and compare git status --porcelain with status.txt to find files created, deleted or renamed since. The delta is those hunks and files. If it is empty, say Nothing changed since the review. and stop.
If findings.md has no dispositions because the fixes were made outside Step 6, mark each finding whose file:line falls in the delta as fixed and the rest as declined.
7b. Pick the aspects
Start from the aspect of every finding marked fixed, so each fix is checked against the finding it addressed. Then add aspects for what the delta contains:
| The delta contains | Add |
|---|---|
| Changed conditions, control flow, data handling, async or error paths | correctness |
| New or renamed identifiers, files, components, props, exports, keys or strings | consistency, interface |
| New or changed tests, or production changes with no test change | test |
| Changed exported signatures, or code moved between modules | architecture, interface |
| Auth, URLs, input parsing, secrets, shell or SQL | security |
| Loops, queries, render paths or caches | performance |
| Files a language, shape, project or library-use reviewer covered in the original run | that reviewer |
If the original run used aspect flags, choose only from those aspects, plus correctness when production code changed. History, and functional unless the delta adds state or mutation, are rarely worth a re-review.
7c. Pick the depth
Use the delta's size, not the original run's mode:
| Delta | How |
|---|---|
| Renames, moves, strings, comments or config only, under ~30 changed lines, no logic | No sub-agents. Check it yourself: confirm each fixed finding is resolved, grep for references to anything renamed or removed (string literals included), run the affected tests under timeout. |
Under ~200 changed lines across at most ~6 files, or the original run was --quick |
One reviewer, using the quick-mode brief from Step 3c with the delta as its scope and the aspects from 7b as its checklist. No scorer round. |
| Larger | Comprehensive mode, limited to the aspects from 7b, one agent each, scored as usual. Re-run external advisors only here, and only if the original run used --multi. |
7d. Brief and report
Every re-review brief (or your own check) gets:
- the delta as the scope, with the original diff and the full files as context only;
- each
fixedfinding, to confirm resolved or report as not resolved; - each
declinedorappendixfinding, marked as already decided: not to be raised again; - the instruction to report only issues in the delta or caused by it.
Render a Re-review of fixes section listing each fixed finding as resolved or not resolved, then any new findings in the usual severity sections. Take a new Step 5.5 snapshot, then run Step 6 as normal. The loop ends when a re-review has no Must Fix or Should Fix findings, or the user picks "Don't fix anything".
Examples
Clean up, then review the default scope with all 10 agents:
/code-review
Runs review-tidy --fix (including comment cleanup), then 10 parallel review agents (correctness, architecture, security, performance, historical context, test quality, interface design, clean code, functional principles, consistency with existing patterns) against staged changes (or unstaged changes if nothing is staged). The cleanup is summarized separately; review findings are prioritized by severity.
Quick review of a routine small change:
/code-review --quick
Runs one integrated read-only reviewer against staged changes (or unstaged changes if nothing is staged). It uses full reasoning effort, traces behavior through callers, dependencies, and tests, and checks design alongside correctness. It applies detected language, project, and library-use guidance directly, verifies suspected issues before filtering, and reports coverage and unresolved uncertainties. It skips the independent scorer-agent round.
Focused single-aspect review:
/code-review --architecture
Runs only the architecture & patterns agent. Use this when you already know which concern you care about and don't want to wait on the other 9 core agents or sift through their output. Flags are additive — combine them (e.g. --security --performance) to run a handful of aspects without running them all.
Whole-repo review:
/code-review --all
Runs the preflight cleanup and all 10 agents against every file in the repo (git ls-files). Use this for a fresh audit of an unfamiliar project, before a major release, or when nothing in the working tree is changed. Composes with aspect flags and --multi, e.g. /code-review --all --architecture --multi.
Cross-model consensus review:
/code-review --multi
Runs the same 10 review agents plus external reviews from every advisor second-opinion has configured, after the preflight cleanup. The output includes a cross-model agreement section highlighting issues where the internal agents and external advisors converge, giving higher confidence to consensus findings. --multi composes with aspect and scope flags, e.g. /code-review --multi --architecture or /code-review --all --multi.
Review, fix, then re-review automatically:
/code-review --re
Runs the review, offers the fix prompt (Step 6), and once fixes are applied, re-reviews only what they changed. It confirms each fixed finding is resolved and checks the new code with the aspects that change touches. A rename-only fix gets no sub-agents at all, and a small fix gets one reviewer. The loop continues until a re-review comes back with no Must Fix/Should Fix findings or the user declines to fix. Run /code-review --re later in the same conversation to re-review fixes made after the review ended.
Troubleshooting
Too many changed files for agents to handle
Solution: Narrow the review scope by targeting a specific directory or file pattern (e.g., /code-review src/auth/) instead of the entire changeset, or break the PR into smaller, focused reviews.
Agent returns shallow or redundant findings
Solution: Ensure the review target is specific enough to give agents meaningful context; vague targets like "everything" produce generic results. Re-run with a focused target and verify that CLAUDE.md contains project-specific patterns the agents can check against.