opencode-swarm-plugin 0.12.31 → 0.13.1

package/examples/skills/swarm-coordination/SKILL.md

@@ -8,23 +8,47 @@ tags:
 tools:
   - swarm_decompose
   - swarm_complete
-  - agentmail_init
-  - agentmail_send
+  - 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 beads
+
 ## 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
@@ -34,6 +58,7 @@ Do NOT use swarm coordination when:
 ### 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?
@@ -42,7 +67,8 @@ Before decomposing, understand:
 ### 2. Choose a Decomposition Strategy
 
 **Parallel Strategy** - For independent subtasks:
-```
+
+```text
 Parent Task: "Add user authentication"
 ├── Subtask 1: "Create auth API endpoints" (backend)
 ├── Subtask 2: "Build login/signup forms" (frontend)
@@ -51,7 +77,8 @@ Parent Task: "Add user authentication"
 ```
 
 **Sequential Strategy** - When order matters:
-```
+
+```text
 Parent Task: "Migrate database schema"
 ├── Step 1: "Create migration files"
 ├── Step 2: "Update model definitions"
@@ -60,7 +87,8 @@ Parent Task: "Migrate database schema"
 ```
 
 **Hybrid Strategy** - Mixed dependencies:
-```
+
+```text
 Parent Task: "Add feature X"
 ├── Phase 1 (parallel):
 │   ├── Subtask A: "Design API"
@@ -76,73 +104,189 @@ Parent Task: "Add feature X"
 
 When multiple agents work on the same codebase:
 
-1. **Reserve files before editing** - Use `agentmail_reserve` to claim files
-2. **Respect reservations** - Don't edit files reserved by other agents
-3. **Release when done** - Files auto-release on task completion
-4. **Coordinate on shared files** - If you must edit a reserved file, send a message to the owning agent
+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
+
+```typescript
+// 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
-```
-agentmail_send(recipients: ["all"], message: "Completed API endpoints, ready for frontend integration")
+
+```typescript
+swarmmail_send({
+  to: ["*"],
+  subject: "API Complete",
+  body: "Completed API endpoints, ready for frontend integration",
+  thread_id: epic_id,
+});
 ```
 
 ### Direct Coordination
-```
-agentmail_send(recipients: ["frontend-agent"], message: "Auth API is at /api/auth/*, here's the spec...")
+
+```typescript
+swarmmail_send({
+  to: ["frontend-agent"],
+  subject: "Auth API Spec",
+  body: "Auth API is at /api/auth/*, here's the spec...",
+  thread_id: epic_id,
+});
 ```
 
-### Blocking on Dependencies
+### Checking for Messages
+
+```typescript
+// 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 });
 ```
-# Wait for a dependency before proceeding
-agentmail_receive(wait: true, filter: "api-complete")
+
+### Reporting Blockers
+
+```typescript
+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. **Small, focused subtasks** - Each subtask should be completable in one agent session
-2. **Clear boundaries** - Define exactly what files/modules each subtask touches
-3. **Explicit handoffs** - When one task enables another, communicate clearly
-4. **Graceful failures** - If a subtask fails, don't block the whole swarm
-5. **Progress updates** - Use beads to track subtask status
+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
+
 ```yaml
 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
+
 ```yaml
 decomposition:
   strategy: sequential
+  skills: [testing-patterns]
   subtasks:
     - reproduce-bug
     - identify-root-cause
     - implement-fix
     - add-regression-test
+  recommended_skills: [testing-patterns]
 ```
 
 ### Refactoring
+
 ```yaml
 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:**
+
+```markdown
+## 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               |

package/global-skills/swarm-coordination/SKILL.md

@@ -15,11 +15,13 @@ tools:
   - swarm_progress
   - beads_create_epic
   - beads_query
-  - agentmail_init
-  - agentmail_send
-  - agentmail_inbox
-  - agentmail_reserve
-  - agentmail_release
+  - swarmmail_init
+  - swarmmail_send
+  - swarmmail_inbox
+  - swarmmail_read_message
+  - swarmmail_reserve
+  - swarmmail_release
+  - swarmmail_health
   - semantic-memory_find
   - cass_search
   - pdf-brain_search
@@ -33,6 +35,16 @@ references:
 
 Multi-agent orchestration for parallel task execution. The coordinator breaks work into subtasks, spawns worker agents, monitors progress, and aggregates results.
 
+## 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 beads
+
 ## When to Swarm
 
 **DO swarm when:**
@@ -53,19 +65,29 @@ Multi-agent orchestration for parallel task execution. The coordinator breaks wo
 
 ## Coordinator Workflow
 
-### Phase 1: Knowledge Gathering (MANDATORY)
+### Phase 1: Initialize Swarm Mail (FIRST)
+
+```typescript
+// ALWAYS initialize first - registers you as coordinator
+await swarmmail_init({
+  project_path: "$PWD",
+  task_description: "Swarm: <task summary>",
+});
+```
+
+### Phase 2: Knowledge Gathering (MANDATORY)
 
 Before decomposing, query ALL knowledge sources:
 
 ```typescript
 // 1. Past learnings from this project
-semantic - memory_find({ query: "<task keywords>", limit: 5 });
+semantic_memory_find({ query: "<task keywords>", limit: 5 });
 
 // 2. How similar tasks were solved before
 cass_search({ query: "<task description>", limit: 5 });
 
 // 3. Design patterns and prior art
-pdf - brain_search({ query: "<domain concepts>", limit: 5 });
+pdf_brain_search({ query: "<domain concepts>", limit: 5 });
 
 // 4. Available skills to inject into workers
 skills_list();
@@ -73,7 +95,7 @@ skills_list();
 
 Synthesize findings into `shared_context` for workers.
 
-### Phase 2: Decomposition
+### Phase 3: Decomposition
 
 ```typescript
 // Auto-select strategy and generate decomposition prompt
@@ -97,7 +119,25 @@ await beads_create_epic({
 });
 ```
 
-### Phase 3: Spawn Workers
+### Phase 4: Reserve Files (via Swarm Mail)
+
+```typescript
+// Reserve files for each subtask BEFORE spawning workers
+await swarmmail_reserve({
+  paths: ["src/auth/**"],
+  reason: "bd-123: Auth service implementation",
+  ttl_seconds: 3600,
+  exclusive: true,
+});
+```
+
+**Rules:**
+
+- No file overlap between subtasks
+- Coordinator mediates conflicts
+- `swarm_complete` auto-releases
+
+### Phase 5: Spawn Workers
 
 ```typescript
 for (const subtask of subtasks) {
@@ -118,25 +158,41 @@ for (const subtask of subtasks) {
 }
 ```
 
-### Phase 4: Monitor & Intervene
+### Phase 6: Monitor & Intervene
 
 ```typescript
 // Check progress
 const status = await swarm_status({ epic_id, project_key });
 
-// Check for messages
-const inbox = await agentmail_inbox({ limit: 5 });
+// Check for messages from workers
+const inbox = await swarmmail_inbox({ limit: 5 });
+
+// Read specific message if needed
+const message = await swarmmail_read_message({ message_id: N });
 
 // Intervene if needed (see Intervention Patterns)
 ```
 
-### Phase 5: Aggregate & Complete
+### Phase 7: Aggregate & Complete
 
 - Verify all subtasks completed
 - Run final verification (typecheck, tests)
 - Close epic with summary
+- Release any remaining reservations
 - Record outcomes for learning
 
+```typescript
+await swarm_complete({
+  project_key: "$PWD",
+  agent_name: "coordinator",
+  bead_id: epic_id,
+  summary: "All subtasks complete",
+  files_touched: [...],
+});
+await swarmmail_release(); // Release any remaining reservations
+await beads_sync();
+```
+
 ## Decomposition Strategies
 
 Four strategies, auto-selected by task keywords:
@@ -150,37 +206,13 @@ Four strategies, auto-selected by task keywords:
 
 See `references/strategies.md` for full details.
 
-## File Reservation Protocol
-
-Workers MUST reserve files before editing:
-
-```typescript
-// Reserve (exclusive by default)
-await agentmail_reserve({
-  paths: ["src/auth/**"],
-  reason: "bd-123: Auth service implementation",
-  ttl_seconds: 3600,
-});
-
-// Work...
-
-// Release (or let swarm_complete handle it)
-await agentmail_release({ paths: ["src/auth/**"] });
-```
-
-**Rules:**
-
-- No file overlap between subtasks
-- Coordinator mediates conflicts
-- `swarm_complete` auto-releases
-
 ## Communication Protocol
 
-Workers communicate via Agent Mail with epic ID as thread:
+Workers communicate via Swarm Mail with epic ID as thread:
 
 ```typescript
 // Progress update
-agentmail_send({
+swarmmail_send({
   to: ["coordinator"],
   subject: "Auth API complete",
   body: "Endpoints ready at /api/auth/*",
@@ -188,7 +220,7 @@ agentmail_send({
 });
 
 // Blocker
-agentmail_send({
+swarmmail_send({
   to: ["coordinator"],
   subject: "BLOCKED: Need DB schema",
   body: "Can't proceed without users table",
@@ -265,25 +297,51 @@ One blocker affects multiple subtasks.
 - Thread: {epic_id}
 ```
 
-## Quick Reference
+## 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               |
+
+## Full Swarm Flow
 
 ```typescript
-// Full swarm flow
-semantic - memory_find({ query }); // 1. Check learnings
-cass_search({ query }); // 2. Check history
-pdf - brain_search({ query }); // 3. Check patterns
-skills_list(); // 4. Check skills
-
-swarm_plan_prompt({ task }); // 5. Generate decomposition
-swarm_validate_decomposition(); // 6. Validate
-beads_create_epic(); // 7. Create beads
-
-swarm_spawn_subtask(); // 8. Spawn workers (loop)
-swarm_status(); // 9. Monitor
-agentmail_inbox(); // 10. Check messages
-
-// Workers complete with:
-swarm_complete(); // Auto: close bead, release files, notify
+// 1. Initialize Swarm Mail FIRST
+swarmmail_init({ project_path: "$PWD", task_description: "..." });
+
+// 2. Gather knowledge
+semantic_memory_find({ query });
+cass_search({ query });
+pdf_brain_search({ query });
+skills_list();
+
+// 3. Decompose
+swarm_plan_prompt({ task });
+swarm_validate_decomposition();
+beads_create_epic();
+
+// 4. Reserve files
+swarmmail_reserve({ paths, reason, ttl_seconds });
+
+// 5. Spawn workers (loop)
+swarm_spawn_subtask();
+
+// 6. Monitor
+swarm_status();
+swarmmail_inbox();
+swarmmail_read_message({ message_id });
+
+// 7. Complete
+swarm_complete();
+swarmmail_release();
+beads_sync();
 ```
 
 See `references/coordinator-patterns.md` for detailed patterns.