Swarm Coordination Patterns

Comprehensive guidance for coordinating multi-agent swarms to prevent conflicts and enable proactive monitoring.

When to Activate

Activate this skill when:

• Orchestrating multiple agents working on the same codebase
• Implementing features that require parallel agent execution
• Designing workflows where agents might edit overlapping files
• Debugging swarm coordination issues

Core Concepts

The Problem with Uncoordinated Swarms

When multiple agents work in parallel without coordination:

1. File Conflicts: Multiple agents edit the same file simultaneously
2. Merge Conflicts: Changes overwrite each other
3. Endless Loops: Agents "fix" each other's code in circles
4. Wasted Work: Duplicate effort on same files

Three-Pillar Solution

This skill teaches three complementary patterns:

1. Status Polling (Fix 1): Orchestrator proactively monitors agent progress
2. File Claiming (Fix 2): Agents claim ownership before editing
3. Checkpoint Orchestration (Fix 5): Plan first, detect conflicts, then implement

Key Files

Coordination Files

• .claude/swarm-status.json - Central status tracking
• .claude/file-claims.md - File ownership registry
• .claude/swarm-plans/ - Agent implementation plans

Status File Format

{
  "swarm_id": "swarm-20250115-abc123",
  "task": "Implement user authentication",
  "started": "2025-01-15T10:00:00Z",
  "phase": "implementing",
  "agents": {
    "auth-impl": {"status": "working", "last_update": "2025-01-15T10:05:00Z"},
    "db-schema": {"status": "completed", "last_update": "2025-01-15T10:03:00Z"}
  },
  "execution_order": [
    {"batch": 1, "agents": ["db-schema"], "parallel": false},
    {"batch": 2, "agents": ["auth-impl", "api-routes"], "parallel": true}
  ]
}

File Claims Format

# File Claims Registry

| Agent ID | File Path | Claimed At | Status |
|----------|-----------|------------|--------|
| auth-impl | src/auth/handler.ts | 2025-01-15T10:00:00Z | claimed |
| auth-impl | src/auth/types.ts | 2025-01-15T10:00:00Z | claimed |
| db-schema | src/db/schema.ts | 2025-01-15T10:00:00Z | released |

References

• references/status-polling.md - Detailed polling patterns
• references/file-claiming.md - File ownership conventions
• references/checkpoint-flow.md - Phase-based orchestration
• examples/simple-swarm.md - Basic two-agent swarm
• examples/complex-swarm.md - Multi-phase feature implementation

Quick Start

1. Use /swarm [task] command for full orchestrated flow
2. For manual coordination, create the three coordination files
3. Include file claiming instructions in all implementation agents
4. Launch status-checker every 30-60 seconds during execution