| name | swarm-review |
| description | Use for branch, PR, or diff review before landing on main. Tier (`low | auto | high | max`) scales breadth from single reviewer to adversarial panel with architect + SOTA-gap + Codex cross-model gate. Triggers: "review", "/swarm-review", pre-merge checks. |
Adversarial Reviewer — Tiered
Thin dispatch layer. Phase plans live in sibling tier files
(tier-low.md, tier-high.md, tier-max.md). This file parse args,
resolve baseline, classify diff (classify.md), resolve overlays
(overlays.md), optionally gate on meta-plan approval, then hand off
to matching tier file. Shared content (worker table, adversarial
protocol, output format, constraints) stay here — perspective-by-
perspective execution lives in tier files.
Argument syntax
/swarm-review [tier] <target> [--flags]
- tier (optional):
low | auto | high | max. Default auto.
- target (optional): branch name; PR ref (
<N> / #<N> /
PR <N> / pull/<N> / full GitHub PR URL); empty → current branch HEAD.
- flags (convention: flags before positional):
--base=<git-ref> — diff baseline; default main. When target
resolves to PR, inferred from gh pr view --json baseRefName
unless user pass --base explicit.--breadth=minimal|full|adversarial — Stage 2 perspective breadth--reviewer=haiku|sonnet|opus — model for worker-reviewer--doc-reviewer=haiku|sonnet — model for worker-doc-reviewer--rca=on|off — Five Whys systemic-fix analysis--codex / --no-codex — cross-model adversarial pass (code-diff scope)--codex-model=luna|terra|sol — Codex model for cross-model pass
(default per tier: high=terra, max=sol; luna if forced at low)--dry-run — meta-plan preview via EnterPlanMode--form — structured AskUserQuestion form; implies --dry-run
--base is pipeline input, not axis. Feeds classifier as diff
baseline for whole run. Overlays (breadth, rca, codex) are
single-axis pipeline adjustments on top of chosen tier.
Workflow
1. Parse arguments and resolve target
Detect target (ordered, first match wins):
- Full GitHub PR URL
PR <N> / pull/<N> → PR#<N> or bare integer → probe PR via mcp__github__pull_request_read- Branch name — verify via
git rev-parse --verify <name>
- Empty → current branch
HEAD
PR metadata (labels, base ref, title, body) feeds both baseline
resolution and classifier. On fetch fail, fall back to free-text
treatment (match /swarm-plan convention).
2. Resolve the baseline
- User pass
--base=<ref> → use verbatim (user wins).
- Else target is PR → use
gh pr view <N> --json baseRefName -q .baseRefName.
- Else default
main.
Fast-fail when git rev-parse --verify <base> fails — print remediation
(did you mean origin/main?) and stop. Empty diff → report "nothing to
review" and exit clean.
3. Classify (only when tier=auto)
Read classify.md. Compute diff metrics once (git diff <base>...HEAD --name-only for files, --shortstat for lines). Apply tier signals
(size + subsystems + structural markers + PR labels). Produce candidate
tier + confidence flag + overlay set. When signals split across adjacent
tiers, mark low-confidence — meta-plan gate in step 5 resolve
it. No mid-flow AskUserQuestion.
4. Resolve overlays
Final config = tier defaults (overlays.md per-tier table) +
classifier overlays + user flag overrides. User flags always win.
5. Meta-plan gate (single consolidated approval point)
Fire when ANY of: --dry-run, --form, tier resolved to max, or
low-confidence classification. Only user-prompt point.
Write .claude/state/plans/meta-plan_review_[target].md with:
Classification (tier + rationale + diff metrics snapshot), Baseline
(source: user-flag / PR-base / default), Overlays (with rationale),
Workers per perspective, Estimated cost, Not Doing (no auto-fixes, no
commits).
Approval UI (always single interaction):
- Default:
EnterPlanMode with meta-plan path; resume on approve.
Fall back to AskUserQuestion Approve/Edit/Cancel if skill resume
after ExitPlanMode unreliable in practice.
--form: ONE AskUserQuestion call with ≤4 batched axis questions
(Tier / Breadth / RCA / Codex), first option "Recommended".
On reject: re-draft with rejection rationale and re-present once.
6. Announce final config (always)
Swarm review
Tier: high (auto — 8 files, 240 lines, 1 subsystem)
Baseline: main (default)
Target: HEAD (branch: soraka)
Overlays: breadth=full, rca=on, codex=off (tier default)
Workers: Stage 1 (2 parallel), Stage 2 (4 parallel)
Codex diff review: off
Proceed? (Ctrl+C to abort; re-run with explicit tier to override)
7. Dispatch to tier file
Read matching tier-{low,high,max}.md and execute its phase plan.
Worker assignment (shared across tiers)
See .claude/rules/workflow-swarm.md for worker types, models, tools,
focus modes. Tier files select subset of these perspectives.
| Perspective | Worker / focus | Tier use |
|---|
| Spec-compliance | worker-reviewer (spec-compliance, phase: post-implementation) | all |
| Test coverage | worker-reviewer (quality, lens: test-coverage) | high, max |
| Quality | worker-reviewer (quality) | all |
| Security | worker-reviewer (security) | high (security paths), max |
| Performance | worker-reviewer (performance) | high (hot paths), max |
| Architecture | worker-architect | max (+ adversarial) |
| Documentation | worker-doc-reviewer | high, max |
| CLI UX | worker-reviewer (quality, lens: cli-ux) | max (+ adversarial) |
| SOTA | worker-researcher | max (+ adversarial) |
| Cross-model | codex-adversary (code-diff) | high (when --codex fires), max (mandatory) |
Max concurrent workers: 8 (per workflow-swarm.md).
Adversarial protocol & output format
Adversarial questioning anchors ("What if this assumption is wrong?",
"Under what conditions would this fail?", "What edge cases weren't
considered?") apply at every tier. Root-cause Five-Whys analysis is
tier-gated via rca axis (see overlays.md).
Output skeleton — tier files add or remove Stage 2 sections per
breadth they run. Every tier produces:
## Code Review: [target]
### Summary
- Verdict: Approved | Needs Work | Request Changes
- Tier / Baseline / Diff: N files, +L / -L lines, S subsystems
### Stage 1 — Correctness (spec-compliance, test-coverage)
### Stage 2 — [perspectives run at this tier]
### Cross-Model Adversarial (Codex) # if --codex fired
### Root-Cause Analysis # if rca=on
### Deferred Findings (human judgment required)
Verdict: Approve (Block/High resolved or deferred with reasoning),
Needs Work (Warn-tier present), Request Changes (unresolved Block-tier /
security / breaking changes / missing tests / arch violations).
Constraints
- NO auto-fixing — review read-only; actionable findings reported, not committed
- NO approving with unresolved Block-tier findings
- NO nitpicking style covered by ESLint/Prettier
- NO mid-flow
AskUserQuestion during classification
- NO exceeding 8 parallel workers
- ALWAYS reference specific files and lines
- ALWAYS suggest alternatives, not just problems
- ALWAYS classify every finding as actionable or deferred
- ALWAYS stay within diff scope (
<base>...HEAD)
Plan Status block (mutate on round entry + verdict)
Mutate the plan's ## Status block: flip Step to /swarm-review → round N on each round entry; on verdict, set awaiting /finalize (Approve) or awaiting /swarm-execute (review-fix loop) (Needs Work / Request Changes); bump Last update. Skip silently when no current_plan.md / no Status block. Full mutation table → plan-status.md.
Handoff
- To
/swarm-execute: when actionable findings exist and user
want them fixed. /swarm-execute runs Review-Fix Loop.
- To
/builder: with remediation task list for specific finding.
- To
/doc-writer: with gap report from worker-doc-reviewer.
- To
/architect: for architectural concerns requiring ADR.
$ARGUMENTS
