joelhooks/swarm-coordination

Swarm Coordination

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

When to Swarm

Always swarm when /swarm is invoked. The user's explicit invocation overrides any heuristics.

Swarming serves multiple purposes beyond parallelization:

• Context preservation - workers offload work from coordinator
• Session resilience - workers persist if coordinator compacts
• Progress tracking - hive cells track completion state
• Learning capture - hivemind stores discoveries per subtask

Even small tasks (1-2 files) benefit from swarming when context is precious.

For sequential work, use dependencies between subtasks rather than refusing to swarm.

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

• Foreground agents can access MCP tools.
• Background agents do not have MCP tools.
• Use foreground workers for swarmmail_*, swarm_*, hive_*, and MCP calls.
• Use background workers for doc edits and static work only.

MCP Lifecycle Mitigation

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

Coordinator Protocol (High-Level)

1. Initialize Swarm Mail (swarmmail_init).
2. Query past learnings (hivemind_find) - MANDATORY before decomposition.
3. Decompose (swarm_plan_prompt + swarm_validate_decomposition).
4. Spawn workers with explicit file lists.
5. Review worker output (swarm_review + swarm_review_feedback).
6. Record outcomes (swarm_complete).
7. Store learnings (hivemind_store) - MANDATORY after swarm completion.

Worker Protocol (High-Level)

1. Initialize Swarm Mail (swarmmail_init).
2. Reserve files (swarmmail_reserve).
3. Work within scope and report progress.
4. Store discoveries (hivemind_store) - any gotchas, patterns, or decisions made.
5. Complete with swarm_complete.

Hivemind Usage (MANDATORY)

Agents MUST use hivemind to build collective memory:

Before work:

hivemind_find({ query: "relevant topic or codebase pattern" })

During work (when discovering something):

hivemind_store({
  information: "The auth module requires X before Y",
  tags: "auth,gotcha,codebase-name"
})

After work:

hivemind_store({
  information: "Completed task X. Key learnings: ...",
  tags: "swarm,completion,epic-id"
})

Store liberally. Memory is cheap; re-discovering gotchas is expensive.

File Reservations

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

Progress Reporting

Use swarm_progress at 25%, 50%, and 75% completion to trigger auto-checkpoints.

Spawning Workers (CRITICAL - Read This)

Step 1: Prepare the subtask with swarm_spawn_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 tool

// 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 proper 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 - always 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