agent-swarm

name	agent-swarm
model	opus
description	Spin up a team of parallel Opus agents to research, design, review, plan, or create beads. Generic multi-agent orchestration for any task that benefits from parallel exploration. Use when user says "spin up N agents", "research swarm", "design swarm", "review with N agents", or "plan with agents".
triggers	["spin up agents","research swarm","design swarm","review swarm","planning swarm","N agents to","team of agents"]
argument-hint	<type: research|design|review|planning|bead-creation> <topic> [--agents N]

Agent Swarm Skill

Orchestrate N parallel Opus agents for research, design, review, planning, or bead creation. Each agent explores one facet independently; results are synthesized by the leader.

When to Use

• Exploring a large codebase area from multiple angles
• Designing a feature with many interacting aspects
• Reviewing a plan/beads through multiple lenses
• Creating detailed implementation plans for complex features
• Creating beads from implementation plans

When NOT to Use

• Simple targeted code search (use Grep/Glob)
• Single-aspect investigation (use Explore agent)
• Oracle consensus validation (use /swarm-oracle-review)
• Full end-to-end pipeline (use /swarm-pipeline)

Swarm Types

Research Swarm

Purpose: Map existing code and system landscape Typical size: 10 agents Each agent: Reads actual source code for one facet, documents findings

Recommended facets (pick N relevant ones):

- Core data model and persistence
- ViewModel layer and state management
- UI/XAML and user interaction
- Hardware/device integration
- Configuration and settings
- Error handling and edge cases
- Test coverage and gaps
- Related subsystem interactions
- User journey and workflow
- Performance and resource management

Second-pass facets (system landscape):

- User journeys and personas
- Settings/configuration architecture
- Readiness and validation pipelines
- Hardware discovery and lifecycle
- Data pipeline end-to-end
- Error/status/notification system
- Surrounding UI context
- Cognitive load and UX audit
- Platform/cross-cutting concerns
- Integration points

Design Swarm

Purpose: Design all aspects of a solution Typical size: 10 agents Each agent: Designs one aspect, shares research context

Recommended aspects:

- Information hierarchy and layout
- Core interaction model
- Progressive disclosure
- Error/status/feedback system
- Setup/onboarding flow
- Data model and architecture
- Integration with existing UI
- Language and localization
- Accessibility
- ViewModel architecture

Review Swarm

Purpose: Review plans/beads through multiple lenses Typical size: 10 agents (technical) + 6 agents (general) Each agent: Independently reviews with one lens

Technical lenses:

- Correctness (does it match design?)
- Conflict detection (contradictions?)
- Test coverage (all paths tested?)
- UX fidelity (matches design?)
- Safety and data integrity
- Performance and scalability
- Localization completeness
- Architecture compliance
- Accessibility
- Feasibility and risk

General review roles:

- User/customer perspective
- Tech lead perspective
- QA engineer perspective
- Conflict resolver (cross-plan contradictions)
- Bead structure advisor (sizing, deps, ACs)
- Executive summary (high-level assessment)

Planning Swarm

Purpose: Create file-by-file implementation plans Typical size: 20 agents Each agent: Reads actual source files, produces line-level change specs

Agent allocation template:

- N agents: per-phase/per-epic plans (one per logical unit)
- 5 agents: cross-cutting (l10n, errors, testing, migration, perf)
- 3 agents: integration plans (how parts connect)
- 2 agents: risk assessment (failure modes, rollback)

Bead Creation Swarm

Purpose: Convert implementation plans to actionable beads Typical size: 6 agents Each agent: Covers 1-2 epics, creates beads via br CLI

Each bead MUST have:

• Description with context
• Given/When/Then acceptance criteria
• Exact file paths to modify
• Test requirements
• Dependencies (use br dep add)
• Priority label (P0-P3)

Orchestration Protocol

Step 1: Define Facets

Based on the swarm type and topic, define N facets (one per agent). Present facets to user for approval before spawning.

Step 2: Prepare Shared Context

Gather context all agents need:

• Research summaries (for design/review swarms)
• Plan documents (for review/bead-creation swarms)
• Relevant foundry docs
• Key file paths

Write shared context to a temp file agents can read.

Step 3: Spawn Agents

Use the built-in Agent tool. Send ONE message with N Agent tool calls so they run concurrently. Each call has its own self-contained prompt (teammates don't share the leader's context).

Agent({
  subagent_type: "general-purpose",
  name: "facet-<slug>",
  team_name: "<feature-or-task>",
  run_in_background: true,
  prompt: "You are researching [FACET] for [FEATURE].\n\nRead CLAUDE.md first, then:\n1. Read actual source code at [FILE_PATHS]\n2. Document findings per the template\n3. Write report to [OUTPUT_PATH]\n4. Commit: git add [OUTPUT_PATH] && git commit -m 'research: [FACET]'"
})

Worktree isolation — pick ONE output channel, not both.

• File output (committed report on the main branch) — default. Do NOT pass isolation: "worktree". A committed report written inside a temporary worktree disappears when the worktree is reaped, so the leader cannot read it from the main checkout. File output requires shared-branch teammates (and file reservations via agent-mail if they touch anything else).
• Message-only output — pass isolation: "worktree" AND change the prompt's step 3 to "Put your findings in your final assistant message (no files)." The leader synthesizes from the agent's returned message (tool result), not from a file path. Use this when the only deliverable is the synthesized summary.

The execution swarm (/swarm) is a different shape entirely — it MUST use shared branch (same-branch, no worktrees) per "Agent Swarm Rules" in CLAUDE.md.

Step 4: Monitor and Collect

Backgrounded teammates notify the leader when they finish. You can also:

TaskList                  # task progress
SendMessage({ to: "facet-<slug>", content: "status?" })   # ping a specific teammate

SendMessage is fine for artifact-swarm teammates (they survive between turns and can answer follow-ups). Do NOT use it on execution-swarm teammates — those are terminal by design.

Wait for all teammates to complete. For file-output teammates, collect reports from the committed output paths. For message-only teammates, use the content of the teammate's final message (returned as the Agent tool result).

Step 5: Synthesize

Read all N reports. Synthesize into a single cohesive document:

• Common findings across agents
• Contradictions or conflicts to resolve
• Key decisions and recommendations
• Gaps identified

Save synthesis to foundation/product/features/ or appropriate location.

Step 6: Present to User

Present synthesis. User decides next action:

• Another swarm round (deeper, different angle)
• Oracle validation (/swarm-oracle-review)
• Proceed to next pipeline phase
• Manual adjustments

Agent Prompt Template

You are agent {N} in a {TYPE} swarm for [FEATURE].
Your assigned facet: [FACET]

## Context
[SHARED_CONTEXT — research summaries, plan refs, etc.]

## Instructions
1. Read CLAUDE.md in the project root
2. [TYPE-SPECIFIC INSTRUCTIONS]
3. Be thorough — read actual source code, not just file names
4. Write your report to: [OUTPUT_PATH]
5. Commit your report immediately:
   git add [OUTPUT_PATH]
   git commit -m "{type}: {facet} research/design/review"

## Output Format
### Summary (3-5 sentences)
### Findings
### Recommendations
### Files Examined
### Issues/Risks

Team Size Guidelines

Task Complexity	Agents	Type
Single subsystem research	6	Research
Full system research	10	Research
Multi-system landscape	10	Research
Feature design	10	Design
Plan review	10+6	Review
Implementation planning	20	Planning
Bead creation	6	Bead creation
Bead hardening	8	Review
Final correctness pass	10	Review
Doc updates	6-8	Varies

Key Rules

1. Each agent reads actual code — never just specs or summaries
2. One facet per agent — no overlap, clear boundaries
3. Commit immediately — each agent commits its output before moving on
4. Synthesis is mandatory — raw reports are not the deliverable
5. User approves facets before spawning agents
6. Spawn all teammates in a single leader message (one Agent call each, in the same response) so they run concurrently, not serially

Related Skills

• /swarm-exec — Launch an implementation swarm (teammates execute beads autonomously, post-planning)
• /swarm-exec-status — Monitor running implementation swarm progress
• /swarm-pipeline — Full pipeline that orchestrates research→design→beads→implementation