--- name: adverse-review description: > Multi-agent adversarial code review. Spawns three reviewer subagents (Auditor, Adversary, Pragmatist) on a single model, runs a cross-examination round, then deterministically synthesizes a single ranked report. Use this for non-trivial PRs, security-sensitive changes, refactors that touch many files, or any change where one perspective has obvious blind spots. Trigger phrases include "adverse review", "adversarial review", "multi-perspective review", "review my changes from multiple angles", "panel review". NOT suitable for trivial diffs (typos, dependency bumps, formatting). --- # Adverse — Multi-Agent Adversarial Code Review This skill is the Claude Code-native side of the [adverse](https://github.com/addyosmani/adverse) project. The same logic is also available as a standalone CLI (`adverse review …`). When you run inside Claude Code, prefer this skill — it uses Claude Code's native Agent tool to spawn reviewers (no subprocess auth issues, faster) and calls Node helpers only for the deterministic source-collection and synthesis steps. ## When to use this skill The user explicitly asked for an adversarial / multi-perspective / panel review of their code, OR they're about to merge / land / ship a non-trivial change and asked for one more pass. If the diff is trivially mechanical (formatting, dependency bumps, typos), do NOT invoke this — say so and stop. ## Prerequisites `node` (>= 20) on PATH. Verify with `node --version`. The skill scripts live under `${SKILL_DIR}/scripts/` and are stdlib-only (no `npm install` needed). If `node` is missing, tell the user: install Node 20+ from nodejs.org (or their package manager) and re-invoke. Do not fall back to a different implementation; the deterministic synthesizer is the contract. ## Phase 0 — decide what to review Pick scope before spending tokens: 1. If the user named a path, that's the scope. 2. Else if `git status --porcelain` reports uncommitted changes, review those (diff mode against `HEAD`). 3. Else if the current branch is ahead of `main` (or `master` / the configured upstream), review the diff since the merge base. 4. Else review the whole working directory. State the scope you picked in one sentence so the user can redirect. ## Phase 1 — collect source Run the Node helper that walks the target and produces a single prompt-ready text block: ```bash node ${SKILL_DIR}/scripts/collect.mjs --target [--diff [base]] --out /tmp/adverse-source.txt --files-out /tmp/adverse-files.json ``` `/tmp/adverse-source.txt` is what you'll embed in the reviewer prompts. `/tmp/adverse-files.json` is the file list (use it to confirm scope to the user). The helper enforces the same source-size caps as the CLI. If collect fails, surface the error to the user — it's almost always "target not found" or "diff is empty". ## Phase 2 — round 1: independent reviews Spawn **three reviewers in parallel** using Claude Code's Agent tool, one per persona. Each one gets: - **System prompt**: read from `${SKILL_DIR}/scripts/prompts/.txt` (auditor / adversary / pragmatist). - **User message**: the contents of `/tmp/adverse-source.txt` prefixed by `${SKILL_DIR}/scripts/prompts/round1.txt`. - **Model**: `opus` unless the user asked for a different one. If the user picks a smaller model, pass it to all three personas — different models across personas defeats the single-model design. Each subagent must respond with a single JSON object matching this schema: ```json { "persona": "", "verdict": "approve|conditional|reject", "summary": "", "findings": [ { "severity": "critical|warning|info", "file": "", "line": , "title": "", "detail": "<2-6 sentences>", "fix": "" } ] } ``` Save each parsed JSON object to disk: - `/tmp/adverse-round1-auditor.json` - `/tmp/adverse-round1-adversary.json` - `/tmp/adverse-round1-pragmatist.json` If a subagent returns malformed JSON, **retry that one persona once** with the parser/validator error appended to the original prompt. If the retry also fails, drop that persona. If fewer than 2 personas survive, abort the run and report the failure — synthesis requires at least 2 voices. When all three are done, combine them into one file for the next phase: ```bash node ${SKILL_DIR}/scripts/combine.mjs \ --round1 /tmp/adverse-round1-auditor.json /tmp/adverse-round1-adversary.json /tmp/adverse-round1-pragmatist.json \ --out /tmp/adverse-round1.json ``` ## Phase 3 — round 2: cross-review For each persona that produced a valid round-1 review, spawn a subagent that: - Sees ALL round-1 reviews (the combined `/tmp/adverse-round1.json`). - Validates findings it agrees with (cross-lane validation is the signal). - Challenges findings it thinks are wrong / overstated (with a concrete reason). - Optionally adds new findings the other angles surfaced. System prompt: same persona file as round 1. User prompt: the contents of `${SKILL_DIR}/scripts/prompts/round2.txt`, then the round-1 combined JSON, then the source block. Output schema: ```json { "persona": "", "validate": [{ "from": "", "title": "", "reason": "<…>" }], "challenge": [{ "from": "<reporter>", "title": "<title>", "reason": "<…>" }], "added": [<finding object>] } ``` Save each to `/tmp/adverse-round2-<persona>.json` and combine: ```bash node ${SKILL_DIR}/scripts/combine.mjs \ --round2 /tmp/adverse-round2-*.json \ --out /tmp/adverse-round2.json ``` If the user asked for a faster review or `--single-round`, skip phase 3 entirely. The synthesizer treats missing round 2 as an empty cross-review. ## Phase 4 — synthesize Run the deterministic synthesizer. This produces the canonical report — never LLM-render the findings yourself, the synthesizer's groupings (cross-validated / consensus / disputed / solo) carry the signal. ```bash node ${SKILL_DIR}/scripts/synthesize.mjs \ --round1 /tmp/adverse-round1.json \ --round2 /tmp/adverse-round2.json \ --out /tmp/adverse-report.md \ --json-out /tmp/adverse-report.json \ --html-out /tmp/adverse-report.html ``` Read `/tmp/adverse-report.md` and present a **summary** to the user, not the full report: 1. The verdict line (e.g., `SHIP-WITH-CAVEATS (2/3 ship, 1/3 block)`). 2. Counts by severity and confidence. 3. The top 3 findings (cross-validated first, then consensus, then disputed) with one-line previews. 4. A pointer to the full report on disk and the HTML dashboard. Then ask the user how they want to proceed: - Apply fixes for cross-validated findings only? (highest confidence) - Apply fixes for everything except disputed? (most common) - Show me a specific finding's full reasoning? - Just save the report; I'll review it myself. Do not start editing files until the user picks one. ## Phase 5 — clean up After the user is done with the report, delete `/tmp/adverse-*` and tell the user the run is complete. Do not commit those files. ## Failure handling | Failure | What to do | |---|---| | `collect.mjs` exits non-zero | Surface the error. Common causes: target doesn't exist, `--diff` on non-git dir, empty diff. | | One reviewer returns garbage twice | Continue with 2 reviewers, mark the run "degraded" in your summary. | | ≥2 reviewers fail | Abort. Tell the user the model is misbehaving and suggest re-running with a different model or with `--single-round`. | | `node` not on PATH | Tell the user to install Node 20+. Do not improvise a fallback. | | User interrupts | Stop spawning new subagents. Tell the user where the partial artifacts are. | ## Notes for the orchestrator - This skill spends ~6 model calls (3 × round-1 + 3 × round-2). Skip round 2 on user request to halve it. - Persona prompts are deliberately written to "stay in your lane" — do NOT override them with general-purpose review instructions, doing so collapses the orthogonality the design relies on. - The synthesizer is deterministic Python-free Node code (`synthesize.mjs`). Counting validate/challenge edges is the consensus signal; do not run a fourth LLM "judge" pass. - The standalone CLI (`adverse review`) is an alternative path that subprocesses any coding agent (`claude -p`, `codex exec`, …). Mention it to the user only if they ask how to run this without Claude Code.