---

description: Coordinate multi-agent swarm with conflict prevention, status polling, and checkpoint-based orchestration

argument-hint: [task description]

Coordinated Swarm Orchestration

You are orchestrating a multi-agent swarm to complete a complex task. Follow this checkpoint-based workflow to prevent conflicts and enable proactive monitoring.

Task Description

$ARGUMENTS

---

Phase 1: Initialization

Goal: Set up swarm coordination infrastructure

Actions:

1. Create coordination files:
2. .claude/swarm-status.json - Agent status tracking
3. .claude/file-claims.md - File ownership registry
4. .claude/swarm-plans/ - Directory for agent plans

1. Initialize status file:

{
  "swarm_id": "[generated-id]",
  "task": "[task description]",
  "started": "[timestamp]",
  "phase": "planning",
  "agents": {}
}

1. Initialize file claims:

# File Claims Registry

| Agent ID | File Path | Claimed At | Status |
|----------|-----------|------------|--------|

1. Create todo list tracking all phases

---

Phase 2: Planning (Parallel, Read-Only)

Goal: Have multiple agents analyze the codebase and create implementation plans WITHOUT making changes

Actions:

1. Launch 2-4 planning agents in parallel, depending on task complexity. Each agent should:
2. Analyze a different aspect of the task
3. Create a detailed implementation plan
4. List ALL files they intend to modify/create/delete
5. Identify dependencies on other files or agents
6. CRITICAL: Agents must NOT edit any files - planning only

1. Each agent writes their plan to .claude/swarm-plans/[agent-id].md:

## Agent Plan: [agent-id]

### Task Summary
[What this agent will accomplish]

### Files to Modify
- `path/to/file.ts`: [Description of changes]

### Files to Create
- `path/to/new-file.ts`: [Purpose]

### Dependencies
- Requires: [what this depends on]
- Blocks: [what depends on this]

### Implementation Steps
1. [Step 1]
2. [Step 2]

1. Update swarm status as agents complete:

{
  "agents": {
    "agent-1": {"status": "plan_complete", "plan_file": ".claude/swarm-plans/agent-1.md"}
  }
}

---

Phase 3: Conflict Detection

Goal: Review all plans and identify conflicts before implementation

Actions:

1. Wait for ALL planning agents to complete
2. Read all plans from .claude/swarm-plans/
3. Launch the conflict-detector agent to analyze all plans
4. Review the conflict report

If conflicts found:

• Present conflict report to user
• Ask for resolution preference:
• Sequence: Execute conflicting agents one at a time
• Reassign: Move conflicting files to single agent
• Manual: User provides custom resolution
• Update plans based on resolution
• Re-run conflict detection to confirm resolution

If no conflicts:

• Proceed to Phase 4

---

Phase 4: File Claiming

Goal: Register file ownership before implementation begins

Actions:

1. For each approved plan, register file claims in .claude/file-claims.md:

| agent-1 | src/api/handler.ts | 2025-01-15T10:30:00Z | claimed |
| agent-1 | src/utils/auth.ts | 2025-01-15T10:30:00Z | claimed |
| agent-2 | src/db/queries.ts | 2025-01-15T10:30:00Z | claimed |

1. Determine execution order based on conflict analysis:
2. Parallel batch 1: Agents with no conflicts or dependencies
3. Sequential queue: Agents that must wait for others

1. Update swarm status:

{
  "phase": "implementing",
  "execution_order": [
    {"batch": 1, "agents": ["agent-1", "agent-2"], "parallel": true},
    {"batch": 2, "agents": ["agent-3"], "parallel": false, "waits_for": ["agent-1"]}
  ]
}

---

Phase 5: Implementation with Monitoring

Goal: Execute implementation with proactive status monitoring

Actions:

1. Launch first batch of implementation agents

1. Status Polling Loop (every 30-60 seconds during execution):
2. Launch a status-checker agent (haiku model for speed)
3. Review status report
4. If issues detected:
5. Conflict: Pause later agent, let first complete
6. Stuck agent: Check logs, consider reassignment
7. Failed agent: Report to user, decide whether to retry or skip

1. As each agent completes:
2. Update swarm status: "status": "completed"
3. Release file claims in .claude/file-claims.md: change status to released
4. Launch next queued agents that were waiting

1. Agent Instructions (include in each implementation agent's prompt):

## Coordination Requirements

Before editing any file:
1. Read `.claude/file-claims.md`
2. Verify the file is claimed by YOU (your agent ID)
3. If claimed by another agent, SKIP and note in your results
4. If not claimed, DO NOT edit - report the missing claim

After completing work:
1. Update your status in swarm communication
2. Report files modified for claim release

If you encounter a conflict:
1. STOP editing the conflicted file
2. Report the conflict immediately
3. Wait for orchestrator resolution

---

Phase 6: Verification

Goal: Verify swarm completed successfully

Actions:

1. Check all agents completed:
2. Read final swarm status
3. Verify all planned files were modified
4. Check for any orphaned claims

1. Run integration checks:
2. Build/compile if applicable
3. Run tests if applicable
4. Check for import/type errors

1. Clean up coordination files:
2. Archive swarm status to .claude/swarm-history/
3. Clear file claims
4. Remove plan files

---

Phase 7: Summary

Goal: Report swarm execution results

Actions:

1. Summarize:
2. Total agents launched
3. Files modified/created/deleted
4. Conflicts detected and resolved
5. Issues encountered
6. Total execution time

1. Present to user:
2. What was accomplished
3. Any items requiring follow-up
4. Suggested next steps

---

Error Handling

Agent Failure:

1. Log failure in swarm status
2. Release failed agent's file claims
3. Ask user: retry, skip, or abort swarm

Unresolvable Conflict:

1. Pause all conflicting agents
2. Present options to user
3. Wait for manual resolution

Stuck Swarm:

1. If no progress for 5+ minutes, alert user
2. Provide diagnostic information
3. Offer to abort and roll back

---

File Claim Convention (For All Agents)

Include this instruction block in every implementation agent's system prompt:

## File Claiming Protocol

You are part of a coordinated swarm. Follow these rules strictly:

1. **Before ANY file edit**:
   - Read `.claude/file-claims.md`
   - Find your agent ID in the registry
   - Only edit files claimed by YOUR agent ID

2. **If file is claimed by another agent**:
   - DO NOT edit the file
   - Note in your results: "Skipped [file] - claimed by [other-agent]"
   - Continue with other work

3. **If file is not in claims registry**:
   - DO NOT edit the file
   - Report: "Cannot edit [file] - not in approved claims"
   - This indicates a planning oversight

4. **Update your progress**:
   - After each significant step, your status will be tracked
   - If you encounter issues, report them clearly

---

Status Polling Schedule

During Phase 5, launch status-checker agent:

• After initial batch launch: wait 30 seconds, then check
• During active execution: check every 45-60 seconds
• After agent completion: immediate check to launch next batch
• On any reported issue: immediate check

Use haiku model for status-checker to minimize latency and cost.