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

typescript

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

typescript

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

typescript

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

CORRECT - files as array:

typescript

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

WRONG - missing project_path:

typescript

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

CORRECT - include project_path:

typescript

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:

typescript

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

typescript

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
```

swarm-coordination

NPX Install

Tags

SKILL.md Content

Swarm Coordination

When to Use

Tool Access (Wildcard)

Foreground vs Background vs Agent Teams

MCP Lifecycle

Coordinator Protocol (Dual-Path)

Native Teams (When Available)

Fallback (Task Subagents)

Worker Protocol (Dual-Path)

With Agent Teams

Without Agent Teams

File Reservations

Progress Reporting

Spawning Workers (CRITICAL - Read This)

Step 1: Prepare the subtask

Step 2: Spawn the worker with Task

Common Mistakes

Parallel vs Sequential Spawning

Parallel (independent tasks)

Sequential (dependent tasks)

Story Status Flow

Skill Loading Guidance