mirror of https://github.com/anthropics/claude-code.git synced 2026-04-24 22:55:16 +00:00

Files

Claude 2a0197e654 feat: Add swarm-coordination plugin for multi-agent conflict prevention

Implements three complementary patterns for coordinating multi-agent swarms:

1. Status Polling (Fix 1): Orchestrator periodically spawns status-checker
   agents to monitor swarm health, detect stuck agents, and identify
   conflicts early.

2. File Claiming (Fix 2): Agents claim file ownership before editing via
   a claims registry (.claude/file-claims.md). Prevents multiple agents
   from editing the same file simultaneously.

3. Checkpoint-Based Orchestration (Fix 5): Separates swarm execution into
   phases - planning (read-only), conflict detection, resolution, then
   implementation with monitoring.

Plugin contents:
- /swarm command for full orchestrated workflow
- status-checker agent (haiku, lightweight polling)
- conflict-detector agent (analyzes plans for overlaps)
- plan-reviewer agent (validates individual plans)
- swarm-patterns skill with comprehensive documentation

2025-12-12 01:43:30 +00:00

2.7 KiB

Raw Blame History

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:

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

Three-Pillar Solution

This skill teaches three complementary patterns:

Status Polling (Fix 1): Orchestrator proactively monitors agent progress
File Claiming (Fix 2): Agents claim ownership before editing
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

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

2.7 KiB Raw Blame History