claude-code/plugins/swarm-coordination/README.md

Swarm Coordination Plugin

Coordinate multi-agent swarms with conflict prevention, status polling, and checkpoint-based orchestration.

The Problem

When multiple agents work in parallel on the same codebase, they can:

• Edit the same files simultaneously, creating conflicts
• Make changes that overwrite each other
• Get stuck in endless loops trying to "fix" each other's code
• Waste effort with duplicate work

The Solution

This plugin implements three complementary coordination patterns:

1. Status Polling (Proactive Monitoring)

The orchestrator periodically spawns lightweight status-checker agents to monitor swarm health:

• Detect stuck or failed agents early
• Identify file conflicts as they emerge
• Enable dynamic load balancing
• Provide real-time progress visibility

2. File Claiming (Ownership Convention)

Agents claim file ownership before editing:

• Prevents multiple agents from editing the same file
• Clear ownership registry in .claude/file-claims.md
• Agents skip files claimed by others
• Claims released after completion

3. Checkpoint-Based Orchestration (Phased Execution)

Separate swarm execution into controlled phases:

1. Planning - Agents analyze and plan (read-only, parallel)
2. Review - Detect conflicts before implementation
3. Resolution - Resolve conflicts with user input
4. Implementation - Execute with monitoring
5. Verification - Validate results

Quick Start

Using the /swarm Command

/swarm Implement user authentication with JWT tokens and session management

The command will guide you through:

1. Initializing coordination files
2. Launching planning agents
3. Reviewing and resolving conflicts
4. Executing implementation with monitoring
5. Verifying completion

Manual Coordination

For custom workflows, use the individual components:

1. Create coordination files:

   • .claude/swarm-status.json
   • .claude/file-claims.md
   • .claude/swarm-plans/

2. Include file claiming instructions in agent prompts

3. Launch status-checker periodically during execution

Plugin Contents

Commands

• /swarm [task] - Full orchestrated swarm workflow

Agents

• status-checker - Monitors swarm health (haiku, fast)
• conflict-detector - Analyzes plans for conflicts
• plan-reviewer - Validates individual agent plans

Skills

• swarm-patterns - Documentation and examples

Coordination Files

.claude/swarm-status.json

{
  "swarm_id": "feature-impl-001",
  "task": "Implement new feature",
  "phase": "implementing",
  "agents": {
    "agent-1": {"status": "working"},
    "agent-2": {"status": "completed"}
  }
}

.claude/file-claims.md

| Agent ID | File Path | Claimed At | Status |
|----------|-----------|------------|--------|
| agent-1 | src/api/handler.ts | 2025-01-15T10:00:00Z | claimed |
| agent-2 | src/db/schema.ts | 2025-01-15T10:00:00Z | released |

Best Practices

1. Always use planning phase - Never skip to implementation
2. Resolve all conflicts - Don't proceed with overlapping claims
3. Poll regularly - Every 30-60 seconds during execution
4. Use haiku for status checks - Fast and cheap
5. Release claims promptly - Don't hold after completion

When to Use

Use this plugin when:

• Multiple agents need to work on the same codebase
• Tasks require parallel execution for speed
• You've experienced agent conflicts before
• You need visibility into swarm progress

When NOT to Use

Skip this plugin when:

• Single agent is sufficient
• Agents work on completely separate codebases
• Tasks are purely read-only (no file modifications)

Troubleshooting

Agents Still Conflict

• Ensure all agents include file claiming instructions
• Verify conflict detection ran before implementation
• Check that claims registry is being read

Status Checker Shows Stuck Agents

• Check agent logs for errors
• Consider increasing timeout
• May need to reassign work

Claims Not Releasing

• Verify agent completion is being tracked
• Manually update claims if needed
• Check for orchestrator errors

Learn More

See the swarm-patterns skill for detailed documentation:

• references/status-polling.md - Polling patterns
• references/file-claiming.md - Claiming conventions
• references/checkpoint-flow.md - Phased orchestration
• examples/simple-swarm.md - Complete example