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)

• Initialize Swarm Mail (swarmmail_init ).

• Query past learnings (hivemind_find ).

• Decompose (swarm_plan_prompt

• swarm_validate_decomposition ).

• Spawn via TeammateTool for real-time coordination.

• Review via native team messaging + swarm_review for persistence.

• Record outcomes (swarm_complete ).

Fallback (Task Subagents)

• Initialize Swarm Mail (swarmmail_init ).

• Query past learnings (hivemind_find ).

• Decompose (swarm_plan_prompt

• swarm_validate_decomposition ).

• Spawn workers via Task(subagent_type="swarm-worker", prompt="...") .

• Review worker output (swarm_review

• swarm_review_feedback ).

• Record outcomes (swarm_complete ).

Worker Protocol (Dual-Path)

With Agent Teams

• Auto-initialize via session-start hook.

• Reserve files (swarmmail_reserve ) — native teams have NO file locking.

• Use TaskUpdate for UI spinners + swarm_progress for persistent tracking.

• Complete with swarm_complete (auto-releases reservations).

Without Agent Teams

• Initialize Swarm Mail (swarmmail_init ).

• Reserve files (swarmmail_reserve ).

• Work within scope and report progress (swarm_progress ).

• 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:

• Coordinator sets story to in_progress when spawning worker

• Worker completes work and sets to ready_for_review

• 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