Swarm Coordination Skill

Step 1: Analyze Task for Parallelization

Identify parallelizable work:

Pattern	Example	Strategy
Independent tasks	Review multiple files	Spawn in parallel
Dependent tasks	Design → Implement	Sequential spawn
Fan-out/Fan-in	Multiple reviews → Consolidate	Parallel + Aggregation
Pipeline	Parse → Transform → Validate	Sequential handoff

Step 2: Spawn Agents in Parallel

Use the Task tool to spawn multiple agents in a single message:

// Spawn multiple agents in ONE message for parallel execution
Task({
  task_id: 'task-1',
  subagent_type: 'general-purpose',
  description: 'Architect reviewing design',
  prompt: 'Review architecture...',
});

Task({
  task_id: 'task-2',
  subagent_type: 'general-purpose',
  description: 'Security reviewing design',
  prompt: 'Review security...',
});

Key: Both Task calls must be in the SAME message for true parallelism.

Step 3: Define Handoff Format

Use structured formats for agent communication:

## Agent Handoff: [Source] → [Target]

### Context

- Task: [What was done]
- Files: [Files touched]

### Findings

- [Key finding 1]
- [Key finding 2]

### Recommendations

- [Action item 1]
- [Action item 2]

### Artifacts

- [Path to artifact 1]
- [Path to artifact 2]

Step 4: Aggregate Results

Combine outputs from parallel agents:

## Swarm Results Aggregation

### Participating Agents

- Architect: Completed ✅
- Security: Completed ✅
- DevOps: Completed ✅

### Consensus Points

- [Point all agents agree on]

### Conflicts

- [Point agents disagree on]
- Resolution: [How to resolve]

### Combined Recommendations

1. [Prioritized recommendation]
2. [Prioritized recommendation]

Step 5: Handle Failures

Strategies for partial failures:

Scenario	Strategy
Agent timeout	Retry with simpler prompt
Agent error	Continue with available results
Conflicting results	Use consensus-voting skill
Missing critical result	Block and retry

</execution_process>

<best_practices>

1. Parallelize Aggressively: Independent work should run in parallel
2. Structured Handoffs: Use consistent formats for communication
3. Graceful Degradation: Continue with partial results when safe
4. Clear Aggregation: Combine results systematically
5. Track Provenance: Know which agent produced each result

</best_practices>

Get architecture, security, and performance reviews for the new API design

Swarm Coordination:

// Spawn 3 reviewers in parallel (single message)
Task({ task_id: 'task-3', description: 'Architect reviewing API', prompt: '...' });
Task({ task_id: 'task-4', description: 'Security reviewing API', prompt: '...' });
Task({ task_id: 'task-5', description: 'Performance reviewing API', prompt: '...' });

Aggregated Results:

## API Design Review (3 agents)

### Consensus

- RESTful design is appropriate
- Need authentication on all endpoints

### Recommendations by Priority

1. [HIGH] Add rate limiting (Security)
2. [HIGH] Use connection pooling (Performance)
3. [MED] Add versioning to URLs (Architect)

</usage_example>

Rules

• Always spawn independent agents in parallel
• Use structured handoff formats
• Handle partial failures gracefully

Related Workflow

This skill has a corresponding workflow for complex multi-agent scenarios:

• Workflow: .claude/workflows/enterprise/swarm-coordination-skill-workflow.md
• When to use workflow: For massively parallel task execution with Queen/Worker topology, fault tolerance, and distributed coordination (large-scale refactoring, parallel code review, multi-file implementation)
• When to use skill directly: For simple parallel agent spawning or when integrating swarm patterns into other workflows

Workflow Integration

This skill powers multi-agent orchestration patterns across the framework:

Router Decision: .claude/workflows/core/router-decision.md

• Router uses swarm patterns for parallel agent spawning
• Planning Orchestration Matrix defines when to use swarm coordination

Artifact Lifecycle: .claude/workflows/core/skill-lifecycle.md

• Swarm patterns apply to artifact creation at scale
• Parallel validation of multiple artifacts

Related Workflows:

• consensus-voting skill for resolving conflicting agent outputs
• context-compressor skill for aggregating parallel results
• Enterprise workflows in .claude/workflows/enterprise/ use swarm patterns

---

Iron Laws

1. NEVER spawn workers sequentially — all independent agents must be dispatched in a single message
2. ALWAYS implement failure detection; never let a hung worker block the swarm indefinitely
3. NEVER allow cross-worker communication — all coordination must flow through the Queen
4. ALWAYS use structured handoff format for worker reports to enable programmatic aggregation
5. NEVER spawn more than 7 workers in a single fan-out — coordination overhead dominates beyond that

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Sequential spawning	No parallelism; swarm executes like a queue	Spawn all independent workers in a single message
Cross-worker communication	O(N²) coordination chaos	All worker-to-worker communication flows through the Queen
No failure handling	One worker crash stalls the swarm	Detect hung/failed workers and re-spawn with fresh state
Unbounded parallelism	Coordination overhead exceeds speedup beyond 7 workers	Limit to 5-7 workers per fan-out for optimal throughput
Free-form worker reports	Cannot aggregate results programmatically	Require all workers to use the structured handoff template

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.