Code Reviewer

code-reviewer

Reviews code in the current working tree through a chosen persona. Reference docs in references/ are loaded on demand — load only the persona and mode refs the user picks.

Inputs

$ARGUMENTS — one of:

• File or directory path (src/foo.ts, src/)
• diff — review git diff
• staged — review git diff --staged
• Empty — ask the user what to review

Workflow

1. Determine scope

Resolve $ARGUMENTS to a concrete set of files + diff:

2. Choose persona(s) — load on demand

Ask the user which review angle. In Claude Code use AskUserQuestion with multiSelect: true; in other agents use the equivalent multi-select prompt. Always present these exact 5 options (4 personas + an "All" convenience option):

1. Adversarial — devil's advocate, harsh, looks for everything wrong → load references/personas/adversarial.md
2. Security — threat modeling, OWASP, input handling → load references/personas/security.md
3. Architecture — design, abstractions, coupling, modularity → load references/personas/architecture.md
4. Performance — algorithmic complexity, memory, I/O patterns → load references/personas/performance.md
5. All — run every persona; loads all four refs and locks step 3 to a parallel mode

If the user picks "All", treat it as [adversarial, security, architecture, performance]. Don't omit the "All" option even when the user already named a persona in their request — they may want to broaden it.

Only load the references the user actually picked. Don't pre-load all four unless they chose "All" — that's the whole point of progressive disclosure.

If the user picked more than one persona, prefer a parallel mode in step 3 (multi-bg-agent or agent-team). Sequential in-process across multiple personas is slow and pollutes context.

3. Choose mode

Four modes, ordered by review quality (best → worst). The reviewing agent should default to the highest-quality option that's actually available on the host:

Why cross-model is the recommendation: code review is an independence problem. A second model — even a smaller one — has different training data, different priors, and different blind spots, so it surfaces issues the first model rationalizes past. Same-model parallel agents (bg-agent / team) reduce context-pollution but share the model's biases. In-process review compounds both problems: same biases, same context.

First, detect available CLIs — this drives the recommendation:

node scripts/detect-clis.mjs --available-only --pretty

The script outputs JSON of available AI CLIs on $PATH (codex, gemini, aider, etc.).

Recommendation logic, applied in order:

1. At least one non-current-agent CLI available → recommend cross-model handoff. Strong default — propose it even when the user didn't explicitly say "second opinion". For multi-persona, you can either pick one CLI and run all personas through it sequentially, or (if multiple CLIs are available) split personas across CLIs.
2. No other CLI AND ≥2 personas → recommend a parallel same-model mode. Use agent team on hosts with a native team primitive (Claude Code), otherwise multi-bg-agent.
3. No other CLI AND 1 persona → fall back to in-process. Tell the user explicitly: "no second model on this machine — running same-model in-process; quality is lower".
4. Never silently default to in-process. If you reach in-process, it's because cross-model wasn't available and parallel modes don't apply. Say so.

Ask the user (AskUserQuestion or equivalent) to confirm the recommended mode before running. Load only the reference(s) for the chosen mode.

4. Run the review

In-process: apply the loaded persona reference as the guiding lens. Read the code in scope, produce findings. If multiple personas were selected and the user accepted in-process anyway, run them one at a time and merge findings using the rules in references/parallel-execution.md §"Step 4 — Merge".

Cross-model: see references/cross-model-handoff.md — uses the bundled invoke-cli.mjs with secret-shield preflight + prompt-shield wrap. Capture the child CLI's stdout verbatim as the review.

Multi-bg-agent / Agent team: see references/parallel-execution.md — fan out one persona per agent with shared scope, collect each agent's findings, merge into one three-tier report with persona tags.

5. Format the output

Apply references/review-output-format.md:

• Group findings by severity (error / warn / info — matches our skill-toolkit tiers)
• Use file:line references so the user can click to source
• Include a one-line summary at the top
• Reference, don't reproduce — describe the issue and point to file:line; do not paste code or diff lines into output (the user already has the file open)

Examples

The bad examples violate the skill's design: progressive disclosure (load only what's needed) and independence-by-default (prefer a different model when one is on the machine).

Security

Cross-model mode forwards local file / diff content to a third-party AI CLI on the same machine. That crosses a trust boundary even though the source content is local: code under review can contain embedded secrets (API keys, tokens) and prompt-injection-style markers (intentionally or accidentally). Two complementary mitigations are built into scripts/invoke-cli.mjs and fire when the agent uses the --instructions <file> --untrusted-content <file> form.

Credential exfiltration: the script runs a regex-based secret scan on the content before composing the prompt. Default --secret-mode scan refuses to forward when any known secret format (AWS, GitHub, OpenAI, Anthropic, Slack, Stripe, Google API, JWT, PEM private keys) is detected. --secret-mode redact substitutes [REDACTED-{type}-{n}] placeholders. --secret-mode allow skips the check (use only when you've already audited the content). Source: scripts/secret-shield/.

Prompt injection: the script generates a fresh 12-hex salt per invocation and wraps the content in <untrusted-{{salt}}>...</untrusted-{{salt}}> with an anti-injection preamble before piping to the child CLI. Attacker-embedded closing tags (whether intentional or accidental) can't escape the wrap because they can't predict the salt. Source: scripts/prompt-shield/.

In-process review, multi-bg-agent, and agent-team do not cross trust boundaries — they all run within the same agent harness on the local machine, no external sink, no preflight needed. Cross-model is the only mode where preflight applies. Background and threat model: contributing/prompt-injection.md.

References

• references/personas/adversarial.md — harsh, devil's-advocate persona
• references/personas/security.md — security-focused review lens
• references/personas/architecture.md — design / coupling / modularity
• references/personas/performance.md — complexity, memory, I/O
• references/cross-model-handoff.md — how to invoke detected CLIs
• references/parallel-execution.md — multi-bg-agent + agent-team fan-out and merge
• references/review-output-format.md — three-tier output spec
• scripts/detect-clis.mjs — node script, ships with the skill, probes for ~20 AI CLIs and emits JSON