mirror of
https://github.com/anthropics/claude-code.git
synced 2026-04-22 03:59:35 +00:00
2a0197e654
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
153 lines
4.3 KiB
Markdown
153 lines
4.3 KiB
Markdown
# 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`
|
|
```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`
|
|
```markdown
|
|
| 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
|