agentleFS
blamechrisblamechris/chroxy/.claude/skills/swarm-audit/SKILL.md

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.

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
  1. Distinctive:

    If TARGET is a file, read it.

    line 25
  2. Distinctive:

    Create a directory for audit results adjacent to the target:

    line 29
  3. Very specific:

    If target is a file: <same-dir>/audit-results/

    line 30
  4. Very specific:

    If target is a topic: docs/audit-results/<slugified-topic>/

    line 31
  5. Distinctive:

    IMPORTANT: Do NOT run agents in the background.

    line 92
  6. Distinctive:

    Sample-verify instead of up-tiering everything: If panel output quality is in doubt, have a stronger tier re-check a ~10% sample of …

    line 100
  7. Distinctive:

    After all agents return, write each agent's findings to its own file:

    line 105
  8. Very specific:

    Create 00-master-assessment.md that synthesizes all agent findings:

    line 129
  9. Very specific:

    Never git add -A, git add ., git add -u, git add <dir>/, or git commit -a.

    line 169
  10. Distinctive:

    Do NOT push unless explicitly asked.

    line 185
  11. Distinctive:

    Operator: should weight mobile UX: touch targets, offline behavior, reconnect experience

    line 211
  12. Distinctive:

    Guardian: should weight WebSocket edge cases: stale sockets, tunnel drops, concurrent writes

    line 212
  13. Distinctive:

    Expert agents: should verify claims against actual Cloudflare/Expo documentation

    line 213

≈ “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.

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

/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.md
    • docs/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)

AgentNicknameLensPersonality
Skeptic"Skeptic"Claims vs reality, false assumptions, what won't workCynical systems engineer who has seen too many designs fail. Cross-references every claim against actual code.
Builder"Builder"Implementability, effort estimates, missing components, dependenciesPragmatic full-stack dev who will implement this. Revises effort estimates, identifies file-by-file changes.
Guardian"Guardian"Safety, failure modes, race conditions, data integrity, recoveryParanoid security/SRE who designs for 3am pages. Finds race conditions and nuclear scenarios.
Minimalist"Minimalist"YAGNI, complexity reduction, 80/20 cuts, simpler alternativesRuthless engineer who believes the best code is no code. Identifies what to cut and proposes minimal alternatives.

Extended Roster (pick based on relevance)

AgentNicknameLensWhen to Include
Operator"Operator"UX walkthrough, daily experience, error states, accessibilityTarget involves user-facing features, UI, or interaction flows
Futurist"Futurist"Extensibility, technical debt forecast, plugin architectureTarget involves architecture decisions with long-term implications
Domain Expert"Expert"Deep domain knowledge for the specific technologyTarget involves specific tech. Name the agent after the domain.
Adversary"Adversary"Attack surface, abuse cases, security boundariesTarget involves auth, networking, data handling, or external interfaces
Tester"Tester"Testability, edge cases, coverage gaps, test strategyTarget involves complex logic, state machines, or protocol design
Historian"Historian"Precedent, prior art, industry patterns, what others have doneTarget involves novel architecture or unconventional approaches
Expo Expert"Expo Expert"Expo SDK lifecycle, React Native constraints, OTA updates, dev client vs Expo GoTarget involves mobile app architecture, updates, or Expo-specific features
Tunneler"Tunneler"Cloudflare tunnels, DNS, TLS, WebSocket proxying, network reliabilityTarget involves tunnel configuration, connectivity, or networking

4. Launch Agent Swarm

Launch ALL agents in parallel using the Task tool. Each agent receives:

  1. The full target document/topic description
  2. Their specific persona, lens, and rating criteria
  3. Instructions to explore the actual codebase (read relevant files, not just the doc)
  4. 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:

  1. Consensus severity (more agents agree = higher priority)
  2. Impact vs effort ratio
  3. 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

RatingMeaning
5/5Excellent. Cannot find meaningful fault.
4/5Good. Minor issues that don't block implementation.
3/5Adequate. Works but has gaps that need addressing.
2/5Concerning. Significant issues that may cause failures.
1/5Fundamentally 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" 6

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.