agentleFS
grimoire-rsgrimoire-rs/grimoire-vscode/.claude/skills/swarm-review/SKILL.md

swarm-review

Skill0 starsChanged 4 months agoApache-2.0View on GitHub

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.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. dralgorhythm/claude-agentic-framework★ 118same name
    2. AnmarHani/SwarmVault★ 5same name
    3. babs/skills★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 7 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read classify.md. Compute diff metrics once (git diff <base>...HEAD --name-only for files, --shortstat for lines).

    line 80
  2. Very specific:

    Default: EnterPlanMode with meta-plan path.

    line 105
  3. Distinctive:

    NO auto-fixing — review read-only.

    line 185
  4. Distinctive:

    NO approving with unresolved Block-tier findings

    line 186
  5. Distinctive:

    NO nitpicking style covered by ESLint/Prettier

    line 187
  6. Very specific:

    NO mid-flow AskUserQuestion during classification

    line 188
  7. Distinctive:

    NO exceeding 8 parallel workers

    line 189
  8. Distinctive:

    ALWAYS reference specific files and lines

    line 190
  9. Distinctive:

    ALWAYS suggest alternatives, not just problems

    line 191
  10. Distinctive:

    ALWAYS classify every finding as actionable or deferred

    line 192
  11. Very specific:

    ALWAYS stay within diff scope (<base>...HEAD)

    line 193
  12. Very specific:

    To /swarm-execute: when actionable findings exist and user want them fixed.

    line 201

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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):

  1. Full GitHub PR URL
  2. PR <N> / pull/<N> → PR
  3. #<N> or bare integer → probe PR via mcp__github__pull_request_read
  4. Branch name — verify via git rev-parse --verify <name>
  5. 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.

PerspectiveWorker / focusTier use
Spec-complianceworker-reviewer (spec-compliance, phase: post-implementation)all
Test coverageworker-reviewer (quality, lens: test-coverage)high, max
Qualityworker-reviewer (quality)all
Securityworker-reviewer (security)high (security paths), max
Performanceworker-reviewer (performance)high (hot paths), max
Architectureworker-architectmax (+ adversarial)
Documentationworker-doc-reviewerhigh, max
CLI UXworker-reviewer (quality, lens: cli-ux)max (+ adversarial)
SOTAworker-researchermax (+ adversarial)
Cross-modelcodex-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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.