joelhooks/swarm-coordination

Swarm Coordination

This skill guides multi-agent coordination for OpenCode swarm workflows.

When to Use

• Tasks touching 3+ files
• Parallelizable work (frontend/backend/tests)
• Work requiring specialized agents
• Time-to-completion matters

Avoid swarming for 1–2 file changes or tightly sequential work.

Tool Access (Wildcard)

This skill is configured with tools: ["*"] per user choice. If you need curated access later, replace the wildcard with explicit tool lists.

Foreground vs Background vs Agent Teams

• Foreground agents can access MCP tools.
• Background agents do not have MCP tools.
• Agent Team Teammates (when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled) have independent context and messaging.
• Use foreground workers for swarmmail_*, swarm_*, hive_*, and MCP calls.
• Use background workers for doc edits and static work only.

MCP Lifecycle

Claude Code auto-launches MCP servers from mcpServers configuration. Do not require manual swarm mcp-serve except for debugging.

Agent teams spawn separate instances with their own MCP connections. Each teammate has independent tool access.

Coordinator Protocol (Dual-Path)

Native Teams (When Available)

1. Initialize Swarm Mail (swarmmail_init).
2. Query past learnings (hivemind_find).
3. Decompose (swarm_plan_prompt + swarm_validate_decomposition).
4. Spawn via TeammateTool for real-time coordination.
5. Review via native team messaging + swarm_review for persistence.
6. Record outcomes (swarm_complete).

Fallback (Task Subagents)

1. Initialize Swarm Mail (swarmmail_init).
2. Query past learnings (hivemind_find).
3. Decompose (swarm_plan_prompt + swarm_validate_decomposition).
4. Spawn workers via Task(subagent_type="swarm-worker", prompt="...").
5. Review worker output (swarm_review + swarm_review_feedback).
6. Record outcomes (swarm_complete).

Worker Protocol (Dual-Path)

With Agent Teams

1. Auto-initialize via session-start hook.
2. Reserve files (swarmmail_reserve) — native teams have NO file locking.
3. Use TaskUpdate for UI spinners + swarm_progress for persistent tracking.
4. Complete with swarm_complete (auto-releases reservations).

Without Agent Teams

1. Initialize Swarm Mail (swarmmail_init).
2. Reserve files (swarmmail_reserve).
3. Work within scope and report progress (swarm_progress).
4. Complete with swarm_complete.

File Reservations

Workers must reserve files before editing and release via swarm_complete. Coordinators never reserve files.

Progress Reporting

Use TaskUpdate for UI spinners (shows instant feedback in Claude Code) and swarm_progress at 25%, 50%, and 75% completion for persistent tracking and auto-checkpoints.

Spawning Workers (CRITICAL - Read This)

Step 1: Prepare the subtask

const spawnResult = await swarm_spawn_subtask({
  bead_id: "cell-abc123",           // The hive cell ID for this subtask
  epic_id: "epic-xyz789",           // Parent epic ID
  subtask_title: "Add logging utilities",
  subtask_description: "Create a logger module with structured logging support",
  files: ["src/utils/logger.ts", "src/utils/logger.test.ts"],  // Array of strings, NOT a JSON string
  shared_context: "This epic is adding observability. Other workers are adding metrics and tracing.",
  project_path: "/absolute/path/to/project"  // Required for tracking
});

Step 2: Spawn the worker with Task

// Parse the result to get the prompt
const { prompt, recommended_model } = JSON.parse(spawnResult);

// Spawn the worker
await Task({
  subagent_type: "swarm:worker",
  prompt: prompt,
  model: recommended_model  // Optional: use the auto-selected model
});

Common Mistakes

WRONG - files as JSON string:

files: '["src/auth.ts"]'  // DON'T do this

CORRECT - files as array:

files: ["src/auth.ts", "src/auth.test.ts"]  // Do this

WRONG - missing project_path:

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  // No project_path - worker can't initialize tracking!
})

CORRECT - include project_path:

swarm_spawn_subtask({
  bead_id: "...",
  epic_id: "...",
  project_path: "/Users/joel/myproject"  // Required!
})

Parallel vs Sequential Spawning

Parallel (independent tasks)

Send multiple Task calls in a single message:

// All in one message - runs in parallel
Task({ subagent_type: "swarm:worker", prompt: prompt1 })
Task({ subagent_type: "swarm:worker", prompt: prompt2 })
Task({ subagent_type: "swarm:worker", prompt: prompt3 })

Sequential (dependent tasks)

Await each before spawning next:

const result1 = await Task({ subagent_type: "swarm:worker", prompt: prompt1 });
// Review result1...
const result2 = await Task({ subagent_type: "swarm:worker", prompt: prompt2 });

Story Status Flow

Status transitions should flow:

1. Coordinator sets story to in_progress when spawning worker
2. Worker completes work and sets to ready_for_review
3. Coordinator reviews and sets to passed or failed

Workers do NOT set final status - that's the coordinator's job after review.

Skill Loading Guidance

Workers should load skills based on task type:

• Tests or fixes → testing-patterns
• Architecture → system-design
• CLI work → cli-builder
• Coordination → swarm-coordination