| name | swarm-coordination |
| description | Multi-agent coordination patterns for OpenCode swarm workflows. Use when work
benefits from parallelization or coordination. Covers: decomposition, worker
spawning, file reservations, progress tracking, and review loops.
|
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",
epic_id: "epic-xyz789",
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"],
shared_context: "This epic is adding observability. Other workers are adding metrics and tracing.",
project_path: "/absolute/path/to/project"
});
Step 2: Spawn the worker with Task
const { prompt, recommended_model } = JSON.parse(spawnResult);
await Task({
subagent_type: "swarm:worker",
prompt: prompt,
model: recommended_model
});
Common Mistakes
WRONG - files as JSON string:
files: '["src/auth.ts"]'
CORRECT - files as array:
files: ["src/auth.ts", "src/auth.test.ts"]
WRONG - missing project_path:
swarm_spawn_subtask({
bead_id: "...",
epic_id: "...",
})
CORRECT - include project_path:
swarm_spawn_subtask({
bead_id: "...",
epic_id: "...",
project_path: "/Users/joel/myproject"
})
Parallel vs Sequential Spawning
Parallel (independent tasks)
Send multiple Task calls in a single message:
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 });
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