swarm-coordination

name	swarm-coordination
description	Multi-agent coordination patterns for OpenCode swarm workflows. Use when working on complex tasks that benefit from parallelization, when coordinating multiple agents, or when managing task decomposition. Do NOT use for simple single-agent tasks.
tags	["swarm","multi-agent","coordination"]
tools	["swarm_decompose","swarm_complete","swarmmail_init","swarmmail_send","swarmmail_inbox","swarmmail_read_message","swarmmail_reserve","swarmmail_release","skills_use","skills_list"]
related_skills	["testing-patterns","system-design","cli-builder"]

Swarm Coordination Skill

This skill provides guidance for effective multi-agent coordination in OpenCode swarm workflows.

IMPORTANT: This skill references global skills in global-skills/. Workers should load domain-specific skills based on their subtask type.

MANDATORY: Swarm Mail

ALL coordination MUST use swarmmail_* tools. This is non-negotiable.

Swarm Mail is embedded (no external server needed) and provides:

• File reservations to prevent conflicts
• Message passing between agents
• Thread-based coordination tied to cells

When to Use Swarm Coordination

Use swarm coordination when:

• A task has multiple independent subtasks that can run in parallel
• The task requires different specializations (e.g., frontend + backend + tests)
• Work can be divided by file/module boundaries
• Time-to-completion matters and parallelization helps

Do NOT use swarm coordination when:

• The task is simple and can be done by one agent
• Subtasks have heavy dependencies on each other
• The overhead of coordination exceeds the benefit

Task Decomposition Strategy

1. Analyze the Task

Before decomposing, understand:

• What are the distinct units of work?
• Which parts can run in parallel vs sequentially?
• What are the file/module boundaries?
• Are there shared resources that need coordination?

2. Choose a Decomposition Strategy

Parallel Strategy - For independent subtasks:

Parent Task: "Add user authentication"
├── Subtask 1: "Create auth API endpoints" (backend)
├── Subtask 2: "Build login/signup forms" (frontend)
├── Subtask 3: "Write auth integration tests" (testing)
└── Subtask 4: "Add auth documentation" (docs)

Sequential Strategy - When order matters:

Parent Task: "Migrate database schema"
├── Step 1: "Create migration files"
├── Step 2: "Update model definitions"
├── Step 3: "Run migrations"
└── Step 4: "Verify data integrity"

Hybrid Strategy - Mixed dependencies:

Parent Task: "Add feature X"
├── Phase 1 (parallel):
│   ├── Subtask A: "Design API"
│   └── Subtask B: "Design UI mockups"
├── Phase 2 (sequential, after Phase 1):
│   └── Subtask C: "Implement based on designs"
└── Phase 3 (parallel):
    ├── Subtask D: "Write tests"
    └── Subtask E: "Update docs"

File Reservation Protocol

When multiple agents work on the same codebase:

1. Initialize Swarm Mail first - Use swarmmail_init before any work
2. Reserve files before editing - Use swarmmail_reserve to claim files
3. Respect reservations - Don't edit files reserved by other agents
4. Release when done - Use swarmmail_release or let swarm_complete handle it
5. Coordinate on shared files - If you must edit a reserved file, send a message to the owning agent

// Initialize first
await swarmmail_init({
  project_path: "$PWD",
  task_description: "Working on auth feature",
});

// Reserve files
await swarmmail_reserve({
  paths: ["src/auth/**"],
  reason: "bd-123: Auth implementation",
  ttl_seconds: 3600,
});

// Work...

// Release when done
await swarmmail_release();

Communication Patterns

Broadcasting Updates

swarmmail_send({
  to: ["*"],
  subject: "API Complete",
  body: "Completed API endpoints, ready for frontend integration",
  thread_id: epic_id,
});

Direct Coordination

swarmmail_send({
  to: ["frontend-agent"],
  subject: "Auth API Spec",
  body: "Auth API is at /api/auth/*, here's the spec...",
  thread_id: epic_id,
});

Checking for Messages

// Check inbox (max 5, no bodies for context safety)
const inbox = await swarmmail_inbox();

// Read specific message body
const message = await swarmmail_read_message({ message_id: N });

Reporting Blockers

swarmmail_send({
  to: ["coordinator"],
  subject: "BLOCKED: Need DB schema",
  body: "Can't proceed without users table",
  thread_id: epic_id,
  importance: "urgent",
});

Best Practices

1. Initialize Swarm Mail first - Always call swarmmail_init before any work
2. Small, focused subtasks - Each subtask should be completable in one agent session
3. Clear boundaries - Define exactly what files/modules each subtask touches
4. Explicit handoffs - When one task enables another, communicate clearly
5. Graceful failures - If a subtask fails, don't block the whole swarm
6. Progress updates - Use beads to track subtask status
7. Load relevant skills - Workers should call skills_use() based on their task type:
   • Testing work → skills_use(name="testing-patterns")
   • Architecture decisions → skills_use(name="system-design")
   • CLI development → skills_use(name="cli-builder")
   • Multi-agent coordination → skills_use(name="swarm-coordination")

Common Patterns

Feature Development

decomposition:
  strategy: hybrid
  skills: [system-design, swarm-coordination]
  phases:
    - name: design
      parallel: true
      subtasks: [api-design, ui-design]
      recommended_skills: [system-design]
    - name: implement
      parallel: true
      subtasks: [backend, frontend]
      recommended_skills: [system-design]
    - name: validate
      parallel: true
      subtasks: [tests, docs, review]
      recommended_skills: [testing-patterns]

Bug Fix Swarm

decomposition:
  strategy: sequential
  skills: [testing-patterns]
  subtasks:
    - reproduce-bug
    - identify-root-cause
    - implement-fix
    - add-regression-test
  recommended_skills: [testing-patterns]

Refactoring

decomposition:
  strategy: parallel
  skills: [testing-patterns, system-design]
  subtasks:
    - refactor-module-a
    - refactor-module-b
    - update-imports
    - run-full-test-suite
  recommended_skills: [testing-patterns, system-design]

Skill Integration Workflow

For Coordinators:

1. Initialize Swarm Mail with swarmmail_init
2. Load swarm-coordination skill
3. Analyze task type
4. Load additional skills based on domain (testing, design, CLI)
5. Include skill recommendations in shared_context for workers

For Workers:

1. Initialize Swarm Mail with swarmmail_init
2. Read shared_context from coordinator
3. Load recommended skills with skills_use(name="skill-name")
4. Apply skill knowledge to subtask
5. Report progress via swarmmail_send
6. Complete with swarm_complete

Example shared_context:

## Context from Coordinator

Past similar tasks: [CASS results]
Project learnings: [semantic-memory results]

## Recommended Skills

- skills_use(name="testing-patterns") - for test creation
- skills_use(name="system-design") - for module boundaries

## Task-Specific Notes

[Domain knowledge from coordinator]

Swarm Mail Quick Reference

Tool	Purpose
swarmmail_init	Initialize session (REQUIRED FIRST)
swarmmail_send	Send message to agents
swarmmail_inbox	Check inbox (max 5, no bodies)
swarmmail_read_message	Read specific message body
swarmmail_reserve	Reserve files for exclusive editing
swarmmail_release	Release file reservations
swarmmail_ack	Acknowledge message
swarmmail_health	Check database health