surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

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

Claudefeat: Add swarm-coordination plugin for multi-agent conflict prevention 2a0197e · on Dec 12, 2025 History

287 lines · 7.4 KBPreview CodeRaw

1	---
2	description: Coordinate multi-agent swarm with conflict prevention, status polling, and checkpoint-based orchestration
3	argument-hint: [task description]
4	---
5
6	# Coordinated Swarm Orchestration
7
8	You are orchestrating a multi-agent swarm to complete a complex task. Follow this checkpoint-based workflow to prevent conflicts and enable proactive monitoring.
9
10	## Task Description
11	$ARGUMENTS
12
13	---
14
15	## Phase 1: Initialization
16
17	Goal: Set up swarm coordination infrastructure
18
19	Actions:
20	1. Create coordination files:
21	- `.claude/swarm-status.json` - Agent status tracking
22	- `.claude/file-claims.md` - File ownership registry
23	- `.claude/swarm-plans/` - Directory for agent plans
24
25	2. Initialize status file:
26	```json
27	{
28	"swarm_id": "[generated-id]",
29	"task": "[task description]",
30	"started": "[timestamp]",
31	"phase": "planning",
32	"agents": {}
33	}
34	```
35
36	3. Initialize file claims:
37	```markdown
38	# File Claims Registry
39
40	\| Agent ID \| File Path \| Claimed At \| Status \|
41	\|----------\|-----------\|------------\|--------\|
42	```
43
44	4. Create todo list tracking all phases
45
46	---
47
48	## Phase 2: Planning (Parallel, Read-Only)
49
50	Goal: Have multiple agents analyze the codebase and create implementation plans WITHOUT making changes
51
52	Actions:
53	1. Launch 2-4 planning agents in parallel, depending on task complexity. Each agent should:
54	- Analyze a different aspect of the task
55	- Create a detailed implementation plan
56	- List ALL files they intend to modify/create/delete
57	- Identify dependencies on other files or agents
58	- CRITICAL: Agents must NOT edit any files - planning only
59
60	2. Each agent writes their plan to `.claude/swarm-plans/[agent-id].md`:
61	```markdown
62	## Agent Plan: [agent-id]
63
64	### Task Summary
65	[What this agent will accomplish]
66
67	### Files to Modify
68	- `path/to/file.ts`: [Description of changes]
69
70	### Files to Create
71	- `path/to/new-file.ts`: [Purpose]
72
73	### Dependencies
74	- Requires: [what this depends on]
75	- Blocks: [what depends on this]
76
77	### Implementation Steps
78	1. [Step 1]
79	2. [Step 2]
80	```
81
82	3. Update swarm status as agents complete:
83	```json
84	{
85	"agents": {
86	"agent-1": {"status": "plan_complete", "plan_file": ".claude/swarm-plans/agent-1.md"}
87	}
88	}
89	```
90
91	---
92
93	## Phase 3: Conflict Detection
94
95	Goal: Review all plans and identify conflicts before implementation
96
97	Actions:
98	1. Wait for ALL planning agents to complete
99	2. Read all plans from `.claude/swarm-plans/`
100	3. Launch the conflict-detector agent to analyze all plans
101	4. Review the conflict report
102
103	If conflicts found:
104	- Present conflict report to user
105	- Ask for resolution preference:
106	- Sequence: Execute conflicting agents one at a time
107	- Reassign: Move conflicting files to single agent
108	- Manual: User provides custom resolution
109	- Update plans based on resolution
110	- Re-run conflict detection to confirm resolution
111
112	If no conflicts:
113	- Proceed to Phase 4
114
115	---
116
117	## Phase 4: File Claiming
118
119	Goal: Register file ownership before implementation begins
120
121	Actions:
122	1. For each approved plan, register file claims in `.claude/file-claims.md`:
123	```markdown
124	\| agent-1 \| src/api/handler.ts \| 2025-01-15T10:30:00Z \| claimed \|
125	\| agent-1 \| src/utils/auth.ts \| 2025-01-15T10:30:00Z \| claimed \|
126	\| agent-2 \| src/db/queries.ts \| 2025-01-15T10:30:00Z \| claimed \|
127	```
128
129	2. Determine execution order based on conflict analysis:
130	- Parallel batch 1: Agents with no conflicts or dependencies
131	- Sequential queue: Agents that must wait for others
132
133	3. Update swarm status:
134	```json
135	{
136	"phase": "implementing",
137	"execution_order": [
138	{"batch": 1, "agents": ["agent-1", "agent-2"], "parallel": true},
139	{"batch": 2, "agents": ["agent-3"], "parallel": false, "waits_for": ["agent-1"]}
140	]
141	}
142	```
143
144	---
145
146	## Phase 5: Implementation with Monitoring
147
148	Goal: Execute implementation with proactive status monitoring
149
150	Actions:
151	1. Launch first batch of implementation agents
152
153	2. Status Polling Loop (every 30-60 seconds during execution):
154	- Launch a status-checker agent (haiku model for speed)
155	- Review status report
156	- If issues detected:
157	- Conflict: Pause later agent, let first complete
158	- Stuck agent: Check logs, consider reassignment
159	- Failed agent: Report to user, decide whether to retry or skip
160
161	3. As each agent completes:
162	- Update swarm status: `"status": "completed"`
163	- Release file claims in `.claude/file-claims.md`: change status to `released`
164	- Launch next queued agents that were waiting
165
166	4. Agent Instructions (include in each implementation agent's prompt):
167	```markdown
168	## Coordination Requirements
169
170	Before editing any file:
171	1. Read `.claude/file-claims.md`
172	2. Verify the file is claimed by YOU (your agent ID)
173	3. If claimed by another agent, SKIP and note in your results
174	4. If not claimed, DO NOT edit - report the missing claim
175
176	After completing work:
177	1. Update your status in swarm communication
178	2. Report files modified for claim release
179
180	If you encounter a conflict:
181	1. STOP editing the conflicted file
182	2. Report the conflict immediately
183	3. Wait for orchestrator resolution
184	```
185
186	---
187
188	## Phase 6: Verification
189
190	Goal: Verify swarm completed successfully
191
192	Actions:
193	1. Check all agents completed:
194	- Read final swarm status
195	- Verify all planned files were modified
196	- Check for any orphaned claims
197
198	2. Run integration checks:
199	- Build/compile if applicable
200	- Run tests if applicable
201	- Check for import/type errors
202
203	3. Clean up coordination files:
204	- Archive swarm status to `.claude/swarm-history/`
205	- Clear file claims
206	- Remove plan files
207
208	---
209
210	## Phase 7: Summary
211
212	Goal: Report swarm execution results
213
214	Actions:
215	1. Summarize:
216	- Total agents launched
217	- Files modified/created/deleted
218	- Conflicts detected and resolved
219	- Issues encountered
220	- Total execution time
221
222	2. Present to user:
223	- What was accomplished
224	- Any items requiring follow-up
225	- Suggested next steps
226
227	---
228
229	## Error Handling
230
231	Agent Failure:
232	1. Log failure in swarm status
233	2. Release failed agent's file claims
234	3. Ask user: retry, skip, or abort swarm
235
236	Unresolvable Conflict:
237	1. Pause all conflicting agents
238	2. Present options to user
239	3. Wait for manual resolution
240
241	Stuck Swarm:
242	1. If no progress for 5+ minutes, alert user
243	2. Provide diagnostic information
244	3. Offer to abort and roll back
245
246	---
247
248	## File Claim Convention (For All Agents)
249
250	Include this instruction block in every implementation agent's system prompt:
251
252	```markdown
253	## File Claiming Protocol
254
255	You are part of a coordinated swarm. Follow these rules strictly:
256
257	1. Before ANY file edit:
258	- Read `.claude/file-claims.md`
259	- Find your agent ID in the registry
260	- Only edit files claimed by YOUR agent ID
261
262	2. If file is claimed by another agent:
263	- DO NOT edit the file
264	- Note in your results: "Skipped [file] - claimed by [other-agent]"
265	- Continue with other work
266
267	3. If file is not in claims registry:
268	- DO NOT edit the file
269	- Report: "Cannot edit [file] - not in approved claims"
270	- This indicates a planning oversight
271
272	4. Update your progress:
273	- After each significant step, your status will be tracked
274	- If you encounter issues, report them clearly
275	```
276
277	---
278
279	## Status Polling Schedule
280
281	During Phase 5, launch status-checker agent:
282	- After initial batch launch: wait 30 seconds, then check
283	- During active execution: check every 45-60 seconds
284	- After agent completion: immediate check to launch next batch
285	- On any reported issue: immediate check
286
287	Use haiku model for status-checker to minimize latency and cost.