swarm-audit
Skill8 starsChanged 5 days agoMITView on GitHub
Launch a swarm of specialized agents to perform a multi-perspective audit of any design document, architecture, codebase, or proposal.
In this repository35 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- commandsSkill
- agentic-auditSkill
- agent-reviewSkill
- autonomous-dev-flowSkill
- batch-mergeSkill
- bug-huntSkill
- catchupSkill
- check-prSkill
- commitSkill
- create-issueSkill
- create-prSkill
- decideSkill
- decompose-issueSkill
- fix-ciSkill
- full-reviewSkill
- hallucination-checkSkill
- learnSkill
- manual-testing-modeSkill
- mergeSkill
- parallel-devSkill
- prime-directiveSkill
- project-auditSkill
- pulseSkill
- qa-updateSkill
- reconSkill
- session-lifecycleSkill
- skillSkill
- smoke-formSkill
- smoke-testSkill
- start-workingSkill
- tackle-issuesSkill
- tiered-delegationSkill
- visual-briefSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 9 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 25
If TARGET is a file, read it.
- Distinctive: line 29
Create a directory for audit results adjacent to the target:
- Very specific: line 30
If target is a file: <same-dir>/audit-results/
- Very specific: line 31
If target is a topic: docs/audit-results/<slugified-topic>/
- Distinctive: line 92
IMPORTANT: Do NOT run agents in the background.
- Distinctive: line 100
Sample-verify instead of up-tiering everything: If panel output quality is in doubt, have a stronger tier re-check a ~10% sample of …
- Distinctive: line 105
After all agents return, write each agent's findings to its own file:
- Very specific: line 129
Create 00-master-assessment.md that synthesizes all agent findings:
- Very specific: line 169
Never git add -A, git add ., git add -u, git add <dir>/, or git commit -a.
- Distinctive: line 185
Do NOT push unless explicitly asked.
- Distinctive: line 211
Operator: should weight mobile UX: touch targets, offline behavior, reconnect experience
- Distinctive: line 212
Guardian: should weight WebSocket edge cases: stale sockets, tunnel drops, concurrent writes
- Distinctive: line 213
Expert agents: should verify claims against actual Cloudflare/Expo documentation
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/swarm-audit
Launch a swarm of specialized agents to perform a multi-perspective audit of any design document, architecture, codebase, or proposal.
Arguments
$ARGUMENTS- Path to the document or topic to audit, plus optional agent count (default: 6). Examples:docs/architecture/proposal.mddocs/rfc-001.md 8(8 agents)"the authentication flow in src/auth.js" 4
Instructions
1. Parse Arguments
TARGET = first argument (file path or quoted topic description)
AGENT_COUNT = second argument (default: 6, min: 4, max: 10)If TARGET is a file, read it. If TARGET is a topic/description, treat it as the audit subject and explore the relevant code.
2. Create Output Directory
Create a directory for audit results adjacent to the target:
- If target is a file:
<same-dir>/audit-results/ - If target is a topic:
docs/audit-results/<slugified-topic>/
3. Select Agent Panel
Choose AGENT_COUNT agents from this roster. Always include the first 4 (core panel). Add from the extended roster based on relevance to the target.
Core Panel (always included)
| Agent | Nickname | Lens | Personality |
| Skeptic | "Skeptic" | Claims vs reality, false assumptions, what won't work | Cynical systems engineer who has seen too many designs fail. Cross-references every claim against actual code. |
| Builder | "Builder" | Implementability, effort estimates, missing components, dependencies | Pragmatic full-stack dev who will implement this. Revises effort estimates, identifies file-by-file changes. |
| Guardian | "Guardian" | Safety, failure modes, race conditions, data integrity, recovery | Paranoid security/SRE who designs for 3am pages. Finds race conditions and nuclear scenarios. |
| Minimalist | "Minimalist" | YAGNI, complexity reduction, 80/20 cuts, simpler alternatives | Ruthless engineer who believes the best code is no code. Identifies what to cut and proposes minimal alternatives. |
Extended Roster (pick based on relevance)
| Agent | Nickname | Lens | When to Include |
| Operator | "Operator" | UX walkthrough, daily experience, error states, accessibility | Target involves user-facing features, UI, or interaction flows |
| Futurist | "Futurist" | Extensibility, technical debt forecast, plugin architecture | Target involves architecture decisions with long-term implications |
| Domain Expert | "Expert" | Deep domain knowledge for the specific technology | Target involves specific tech. Name the agent after the domain. |
| Adversary | "Adversary" | Attack surface, abuse cases, security boundaries | Target involves auth, networking, data handling, or external interfaces |
| Tester | "Tester" | Testability, edge cases, coverage gaps, test strategy | Target involves complex logic, state machines, or protocol design |
| Historian | "Historian" | Precedent, prior art, industry patterns, what others have done | Target involves novel architecture or unconventional approaches |
| Expo Expert | "Expo Expert" | Expo SDK lifecycle, React Native constraints, OTA updates, dev client vs Expo Go | Target involves mobile app architecture, updates, or Expo-specific features |
| Tunneler | "Tunneler" | Cloudflare tunnels, DNS, TLS, WebSocket proxying, network reliability | Target involves tunnel configuration, connectivity, or networking |
4. Launch Agent Swarm
Launch ALL agents in parallel using the Task tool. Each agent receives:
- The full target document/topic description
- Their specific persona, lens, and rating criteria
- Instructions to explore the actual codebase (read relevant files, not just the doc)
- A rating rubric: rate each section 1-5 with justification
Agent prompt template:
You are **"{NICKNAME}"** -- {PERSONALITY}
Your job is to audit the following from the lens of **{LENS}**.
## Target
{TARGET_CONTENT_OR_DESCRIPTION}
## Your Audit Must Cover
1. Section-by-section ratings (1-5) with justification
2. Top 5 findings in your area of expertise
3. Specific evidence from the codebase (file:line references)
4. Concrete recommendations (not vague suggestions)
5. Overall rating with summary
## Rules
- READ the actual codebase, not just the document. Verify claims against code.
- Be specific. "This might be a problem" is useless. "Line 42 of ws-server.js does X which contradicts the doc's claim of Y" is useful.
- Rate honestly. 3/5 means "adequate." 5/5 means "I cannot find meaningful fault." 1/5 means "fundamentally broken."
- End with a single overall rating and one-paragraph verdict.IMPORTANT: Do NOT run agents in the background. Run them as foreground Task calls so their output returns directly. If running more than 4 agents, batch them: first 4 in parallel, then remaining agents in parallel.
Delegation tiers (cost discipline — do not strip):
Roles per /tiered-delegation: workhorse = one tier below the session ceiling, mechanical = cheapest available tier. Concrete model names live only in that skill's CUSTOMIZE-marker ladder — never here.
- Panel agents run at the workhorse tier by default. Audit breadth is workhorse work. Do not spawn panel agents at the ceiling; the orchestrator's synthesis (step 6) is where the expensive judgment lives.
- Pre-filter at the mechanical tier. Any triage/classification pre-pass (e.g. deciding which files or sections are in scope before the panel reads them) runs at the mechanical tier at low effort.
- Sample-verify instead of up-tiering everything. If panel output quality is in doubt, have a stronger tier re-check a ~10% sample of findings rather than re-running the whole panel up-tier.
- Fan-out budget: ~12 workhorse/ceiling subagents per run. The budget counts workhorse- and ceiling-tier agents (the panel); mechanical-tier pre-filter agents and the ~10% sample-verify checks do not count against it. Exceeding 12 requires an explicit one-line justification recorded in the master assessment; 20 is a hard ceiling that includes every refute/verify agent, and no justification lifts it (≤3 refuters per finding — queue rounds rather than widen). The 10-agent panel maximum sits comfortably inside this budget.
5. Write Individual Reports
After all agents return, write each agent's findings to its own file:
audit-results/
00-master-assessment.md <- You write this (step 6)
01-skeptic.md
02-builder.md
03-guardian.md
04-minimalist.md
05-{agent}.md <- Additional agents
...Each file starts with a header block:
# {Nickname}'s Audit: {Target Title}
**Agent**: {Nickname} -- {one-line personality}
**Overall Rating**: X.X / 5
**Date**: {today}6. Write Master Assessment
Create 00-master-assessment.md that synthesizes all agent findings:
Required Sections
a. Auditor Panel Table List all agents with their perspective, rating, and key contribution.
b. Consensus Findings Items where 4+ agents agree. These are high-confidence findings. Include:
- What they agree on
- Supporting evidence from multiple agents
- Recommended action
c. Contested Points Items where agents disagree. Present each position with the agent's name. Include your assessment of who is right and why.
d. Factual Corrections Specific claims in the target that are wrong, with corrections and which agent found them.
e. Risk Heatmap ASCII grid of likelihood vs impact for identified risks.
f. Recommended Action Plan Synthesized from all agents, prioritized by:
- Consensus severity (more agents agree = higher priority)
- Impact vs effort ratio
- Dependency ordering (what unblocks other work)
g. Final Verdict Aggregate rating (average of all agents, weighted: core panel 1.0x, extended 0.8x). One-paragraph summary of whether the target is ready for implementation, needs revision, or needs fundamental rethinking.
h. Appendix Table linking to each individual report file.
7. Commit Results
Stage and commit the audit files by name.
Stage explicit paths. git status --short first, then git add each report you just wrote.
Never git add -A, git add ., git add -u, git add <dir>/, or git commit -a. A
trailing-slash directory add is a bulk add: the working copy is shared with concurrent sessions,
so the audit directory may also hold a stale report from another run or a file that is not yours.
-u is not the safe one: it restages every tracked file whose worktree copy differs, including
files a clean/smudge filter rewrote without you touching them — that is how git add -u turned a
tracked 21KB .docx into a git-lfs pointer and committed it as an edit.
git status --short <audit-results-directory>
git add <audit-results-directory>/<agent-1>.md <audit-results-directory>/<agent-2>.md <audit-results-directory>/master-assessment.md
git commit -m "docs: swarm audit of <target> (<N> agents)
Aggregate rating: X.X/5. Key findings: <top 3 consensus items>.
"Do NOT push unless explicitly asked.
8. Report to User
Output a concise summary:
- Aggregate rating
- Agent panel (names + individual ratings)
- Top 3 consensus findings
- Top contested point
- Recommended next action
- Path to full results
Configuration
Rating Scale
| Rating | Meaning |
| 5/5 | Excellent. Cannot find meaningful fault. |
| 4/5 | Good. Minor issues that don't block implementation. |
| 3/5 | Adequate. Works but has gaps that need addressing. |
| 2/5 | Concerning. Significant issues that may cause failures. |
| 1/5 | Fundamentally broken. Needs rethinking, not patching. |
Grading Criteria for Chroxy
- Operator should weight mobile UX: touch targets, offline behavior, reconnect experience
- Guardian should weight WebSocket edge cases: stale sockets, tunnel drops, concurrent writes
- Expert agents should verify claims against actual Cloudflare/Expo documentation
Agent Behavior Rules
- Agents MUST read actual source code, not just the target document
- Agents MUST provide file:line references for claims
- Agents MUST rate each major section independently
- Agents MUST end with a concrete top-5 recommendations list
- Agents should be opinionated, not diplomatic. Strong views, loosely held.
Examples
/swarm-audit docs/architecture/proposal.md 8
/swarm-audit "the WebSocket protocol in server/ws-server.js" 4
/swarm-audit docs/rfc-push-notifications.md
/swarm-audit "session management across server restart" 6Does 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
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.

