opencode-swarm-plugin 0.13.0 → 0.13.2

package/.beads/issues.jsonl

@@ -1428,6 +1428,10 @@
 {"id":"opencode-swarm-plugin-qgd2n","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T11:16:36.35338-08:00","updated_at":"2025-12-13T11:16:40.1931-08:00","closed_at":"2025-12-13T11:16:40.1931-08:00"}
 {"id":"opencode-swarm-plugin-qgt38","title":"Document SubtaskSpec estimated_complexity scale","description":"src/schemas/bead.ts:106 - `estimated_complexity: z.number().int().min(1).max(5)` - scale meaning not documented. Add JSDoc: \"/** Complexity estimate (1=trivial, 5=very complex) */\"","status":"open","priority":3,"issue_type":"chore","created_at":"2025-12-10T09:06:10.789511-08:00","updated_at":"2025-12-10T09:06:10.789511-08:00"}
 {"id":"opencode-swarm-plugin-qhr0","title":"Cleanup task","description":"","status":"closed","priority":3,"issue_type":"chore","created_at":"2025-12-08T08:22:16.521307-08:00","updated_at":"2025-12-08T08:22:19.112363-08:00","closed_at":"2025-12-08T08:22:19.112363-08:00"}
+{"id":"opencode-swarm-plugin-qkscs","title":"Production Hardening: Logging, Cleanup, and N+1 Fixes","description":"Fix 3 production readiness gaps in Swarm Mail to improve reliability and debuggability","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-13T13:27:21.122378-08:00","updated_at":"2025-12-13T13:27:21.122378-08:00"}
+{"id":"opencode-swarm-plugin-qkscs.1","title":"Fix N+1 queries in store.ts message and reservation handlers","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-13T13:27:21.179002-08:00","updated_at":"2025-12-13T13:27:21.179002-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-qkscs.1","depends_on_id":"opencode-swarm-plugin-qkscs","type":"parent-child","created_at":"2025-12-13T13:27:21.180631-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-qkscs.2","title":"Implement expired reservation cleanup in projections.ts","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-13T13:27:21.234033-08:00","updated_at":"2025-12-13T13:27:21.234033-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-qkscs.2","depends_on_id":"opencode-swarm-plugin-qkscs","type":"parent-child","created_at":"2025-12-13T13:27:21.235438-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-qkscs.3","title":"Add structured logging for critical operations","description":"","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-13T13:27:21.287551-08:00","updated_at":"2025-12-13T13:27:21.287551-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-qkscs.3","depends_on_id":"opencode-swarm-plugin-qkscs","type":"parent-child","created_at":"2025-12-13T13:27:21.288503-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-ql5z","title":"Test bug with priority","description":"This is a critical bug","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-12-08T08:14:28.392972-08:00","updated_at":"2025-12-08T08:14:30.889299-08:00","closed_at":"2025-12-08T08:14:30.889299-08:00"}
 {"id":"opencode-swarm-plugin-qlrp","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:56:55.899992-08:00","updated_at":"2025-12-08T08:56:58.219456-08:00","closed_at":"2025-12-08T08:56:58.219456-08:00"}
 {"id":"opencode-swarm-plugin-qlzm","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:10:25.282262-08:00","updated_at":"2025-12-08T11:10:27.598379-08:00","closed_at":"2025-12-08T11:10:27.598379-08:00"}

package/dist/index.js

@@ -32968,21 +32968,64 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [TOOLS]
-### Beads
-- beads_update (status: blocked)
-- beads_create (new bugs)
-- beads_close (via swarm_complete)
+## [MANDATORY: SWARM MAIL]
+
+**YOU MUST USE SWARM MAIL FOR ALL COORDINATION.** This is non-negotiable.
+
+### Initialize FIRST (before any work)
+\`\`\`
+swarmmail_init(project_path="$PWD", task_description="{subtask_title}")
+\`\`\`
+
+### Reserve Files (if not already reserved by coordinator)
+\`\`\`
+swarmmail_reserve(paths=[...files...], reason="{bead_id}: {subtask_title}")
+\`\`\`
+
+### Check Inbox Regularly
+\`\`\`
+swarmmail_inbox()  # Check for coordinator messages
+swarmmail_read_message(message_id=N)  # Read specific message
+\`\`\`
+
+### Report Progress (REQUIRED - don't work silently)
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Progress: {bead_id}",
+  body="<what you did, blockers, questions>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### When Blocked
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="BLOCKED: {bead_id}",
+  body="<blocker description, what you need>",
+  importance="high",
+  thread_id="{epic_id}"
+)
+beads_update(id="{bead_id}", status="blocked")
+\`\`\`
+
+### Release Files When Done
+\`\`\`
+swarmmail_release()  # Or let swarm_complete handle it
+\`\`\`
 
-### Agent Mail
-- agentmail_send (thread_id: {epic_id})
+## [OTHER TOOLS]
+### Beads
+- beads_update(id, status) - Mark blocked if stuck
+- beads_create(title, type) - Log new bugs found
 
 ### Skills (if available)
-- skills_list (discover available skills)
-- skills_use (activate a skill for specialized guidance)
+- skills_list() - Discover available skills
+- skills_use(name) - Activate skill for specialized guidance
 
-### Completion
-- swarm_complete (REQUIRED when done)
+### Completion (REQUIRED)
+- swarm_complete(project_key, agent_name, bead_id, summary, files_touched)
 
 ## [LEARNING]
 As you work, note reusable patterns, best practices, or domain insights:
@@ -32991,15 +33034,15 @@ As you work, note reusable patterns, best practices, or domain insights:
 - Good skills have clear "when to use" descriptions with actionable instructions
 - Skills make swarms smarter over time
 
-## [OUTPUT]
-1. Read files first
-2. Implement changes
-3. Verify (typecheck)
-4. Complete with swarm_complete
-
-Return: Summary of changes made. Note any patterns worth preserving as skills.
+## [WORKFLOW]
+1. **swarmmail_init** - Initialize session FIRST
+2. Read assigned files
+3. Implement changes
+4. **swarmmail_send** - Report progress to coordinator
+5. Verify (typecheck)
+6. **swarm_complete** - Mark done, release reservations
 
-**Never work silently.** Communicate progress and blockers immediately.
+**CRITICAL: Never work silently. Send progress updates via swarmmail_send every significant milestone.**
 
 Begin now.`;
 function formatSubtaskPromptV2(params) {

package/dist/plugin.js

@@ -32831,21 +32831,64 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [TOOLS]
-### Beads
-- beads_update (status: blocked)
-- beads_create (new bugs)
-- beads_close (via swarm_complete)
+## [MANDATORY: SWARM MAIL]
+
+**YOU MUST USE SWARM MAIL FOR ALL COORDINATION.** This is non-negotiable.
+
+### Initialize FIRST (before any work)
+\`\`\`
+swarmmail_init(project_path="$PWD", task_description="{subtask_title}")
+\`\`\`
+
+### Reserve Files (if not already reserved by coordinator)
+\`\`\`
+swarmmail_reserve(paths=[...files...], reason="{bead_id}: {subtask_title}")
+\`\`\`
+
+### Check Inbox Regularly
+\`\`\`
+swarmmail_inbox()  # Check for coordinator messages
+swarmmail_read_message(message_id=N)  # Read specific message
+\`\`\`
+
+### Report Progress (REQUIRED - don't work silently)
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Progress: {bead_id}",
+  body="<what you did, blockers, questions>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### When Blocked
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="BLOCKED: {bead_id}",
+  body="<blocker description, what you need>",
+  importance="high",
+  thread_id="{epic_id}"
+)
+beads_update(id="{bead_id}", status="blocked")
+\`\`\`
+
+### Release Files When Done
+\`\`\`
+swarmmail_release()  # Or let swarm_complete handle it
+\`\`\`
 
-### Agent Mail
-- agentmail_send (thread_id: {epic_id})
+## [OTHER TOOLS]
+### Beads
+- beads_update(id, status) - Mark blocked if stuck
+- beads_create(title, type) - Log new bugs found
 
 ### Skills (if available)
-- skills_list (discover available skills)
-- skills_use (activate a skill for specialized guidance)
+- skills_list() - Discover available skills
+- skills_use(name) - Activate skill for specialized guidance
 
-### Completion
-- swarm_complete (REQUIRED when done)
+### Completion (REQUIRED)
+- swarm_complete(project_key, agent_name, bead_id, summary, files_touched)
 
 ## [LEARNING]
 As you work, note reusable patterns, best practices, or domain insights:
@@ -32854,15 +32897,15 @@ As you work, note reusable patterns, best practices, or domain insights:
 - Good skills have clear "when to use" descriptions with actionable instructions
 - Skills make swarms smarter over time
 
-## [OUTPUT]
-1. Read files first
-2. Implement changes
-3. Verify (typecheck)
-4. Complete with swarm_complete
-
-Return: Summary of changes made. Note any patterns worth preserving as skills.
+## [WORKFLOW]
+1. **swarmmail_init** - Initialize session FIRST
+2. Read assigned files
+3. Implement changes
+4. **swarmmail_send** - Report progress to coordinator
+5. Verify (typecheck)
+6. **swarm_complete** - Mark done, release reservations
 
-**Never work silently.** Communicate progress and blockers immediately.
+**CRITICAL: Never work silently. Send progress updates via swarmmail_send every significant milestone.**
 
 Begin now.`;
 function formatSubtaskPromptV2(params) {

package/examples/commands/swarm.md

@@ -15,19 +15,31 @@ $ARGUMENTS
 
 **Default: Feature branch + PR with context sync.**
 
+## 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
+
 ## Workflow
 
-### 1. Initialize
+### 1. Initialize Swarm Mail (FIRST)
 
-```
-agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
+```bash
+swarmmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
+This registers you as the coordinator agent.
+
 ### 2. Knowledge Gathering (MANDATORY)
 
 **Before decomposing, query ALL knowledge sources:**
 
-```
+```bash
 # Past learnings from this project
 semantic-memory_find(query="<task keywords>", limit=5)
 
@@ -43,7 +55,7 @@ skills_list()
 
 **Load coordinator skills based on task type:**
 
-```
+```bash
 # For swarm coordination (ALWAYS load this)
 skills_use(name="swarm-coordination")
 
@@ -75,20 +87,20 @@ git push -u origin HEAD
 
 Use strategy selection and planning:
 
-```
+```bash
 swarm_select_strategy(task="<the task>")
 swarm_plan_prompt(task="<the task>", strategy="<auto or selected>", context="<synthesized knowledge>")
 ```
 
 Follow the prompt to create a BeadTree, then validate:
 
-```
+```bash
 swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
 ### 5. Create Beads
 
-```
+```bash
 beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
 ```
 
@@ -99,13 +111,13 @@ Rules:
 - 3-7 beads per swarm
 - No file overlap between subtasks
 
-### 6. Reserve Files
+### 6. Reserve Files (via Swarm Mail)
 
-```
-agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
+```bash
+swarmmail_reserve(paths=[<files>], reason="<bead-id>: <description>", ttl_seconds=3600)
 ```
 
-No two agents should edit the same file.
+No two agents should edit the same file. Reservations prevent conflicts.
 
 ### 7. Spawn Agents
 
@@ -113,7 +125,7 @@ No two agents should edit the same file.
 
 For each subtask:
 
-```
+```bash
 swarm_spawn_subtask(
   bead_id="<id>",
   epic_id="<epic>",
@@ -140,15 +152,16 @@ See full skill list with skills_list().
 
 Then spawn:
 
-```
+```bash
 Task(subagent_type="swarm/worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
 ### 8. Monitor (unless --no-sync)
 
-```
+```bash
 swarm_status(epic_id="<epic-id>", project_key="$PWD")
-agentmail_inbox()
+swarmmail_inbox()  # Check for worker messages
+swarmmail_read_message(message_id=N)  # Read specific message
 ```
 
 **Intervention triggers:**
@@ -160,14 +173,15 @@ agentmail_inbox()
 
 If incompatibilities spotted, broadcast:
 
-```
-agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
+```bash
+swarmmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high", thread_id="<epic-id>")
 ```
 
 ### 9. Complete
 
-```
+```bash
 swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
+swarmmail_release()  # Release any remaining reservations
 beads_sync()
 ```
 
@@ -177,6 +191,19 @@ beads_sync()
 gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
 ```
 
+## 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               |
+
 ## Strategy Reference
 
 | Strategy       | Best For                 | Keywords                              | Recommended Skills                |
@@ -201,13 +228,14 @@ gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Be
 
 ## Quick Checklist
 
+- [ ] **swarmmail_init** called FIRST
 - [ ] Knowledge gathered (semantic-memory, CASS, pdf-brain, skills)
 - [ ] Strategy selected
 - [ ] BeadTree validated (no file conflicts)
 - [ ] Epic + subtasks created
-- [ ] Files reserved
+- [ ] Files reserved via **swarmmail_reserve**
 - [ ] Workers spawned in parallel
-- [ ] Progress monitored
+- [ ] Progress monitored via **swarmmail_inbox**
 - [ ] PR created (or pushed to main)
 
-Begin with knowledge gathering now.
+Begin with swarmmail_init and knowledge gathering now.

package/examples/plugin-wrapper-template.ts

@@ -383,6 +383,113 @@ const agentmail_health = tool({
   execute: (args, ctx) => execTool("agentmail_health", args, ctx),
 });
 
+// =============================================================================
+// Swarm Mail Tools (Embedded - Primary)
+// =============================================================================
+
+const swarmmail_init = tool({
+  description: "Initialize Swarm Mail session (REQUIRED FIRST)",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to the project"),
+    agent_name: tool.schema.string().optional().describe("Custom agent name"),
+    task_description: tool.schema
+      .string()
+      .optional()
+      .describe("Task description"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_init", args, ctx),
+});
+
+const swarmmail_send = tool({
+  description: "Send message to other agents via Swarm Mail",
+  args: {
+    to: tool.schema
+      .array(tool.schema.string())
+      .describe("Recipient agent names"),
+    subject: tool.schema.string().describe("Message subject"),
+    body: tool.schema.string().describe("Message body"),
+    thread_id: tool.schema
+      .string()
+      .optional()
+      .describe("Thread ID for grouping"),
+    importance: tool.schema
+      .enum(["low", "normal", "high", "urgent"])
+      .optional()
+      .describe("Message importance"),
+    ack_required: tool.schema
+      .boolean()
+      .optional()
+      .describe("Require acknowledgment"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_send", args, ctx),
+});
+
+const swarmmail_inbox = tool({
+  description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, max 5 messages)",
+  args: {
+    limit: tool.schema
+      .number()
+      .max(5)
+      .optional()
+      .describe("Max messages (max 5)"),
+    urgent_only: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only urgent messages"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_inbox", args, ctx),
+});
+
+const swarmmail_read_message = tool({
+  description: "Fetch ONE message body by ID",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_read_message", args, ctx),
+});
+
+const swarmmail_reserve = tool({
+  description: "Reserve file paths for exclusive editing",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .describe("File paths/patterns"),
+    ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
+    exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
+    reason: tool.schema.string().optional().describe("Reservation reason"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_reserve", args, ctx),
+});
+
+const swarmmail_release = tool({
+  description: "Release file reservations",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Paths to release"),
+    reservation_ids: tool.schema
+      .array(tool.schema.number())
+      .optional()
+      .describe("Reservation IDs"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_release", args, ctx),
+});
+
+const swarmmail_ack = tool({
+  description: "Acknowledge a message",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_ack", args, ctx),
+});
+
+const swarmmail_health = tool({
+  description: "Check Swarm Mail database health",
+  args: {},
+  execute: (args, ctx) => execTool("swarmmail_health", args, ctx),
+});
+
 // =============================================================================
 // Structured Tools
 // =============================================================================
@@ -794,7 +901,7 @@ export const SwarmPlugin: Plugin = async (
       beads_ready,
       beads_sync,
       beads_link_thread,
-      // Agent Mail
+      // Agent Mail (Legacy MCP)
       agentmail_init,
       agentmail_send,
       agentmail_inbox,
@@ -805,6 +912,15 @@ export const SwarmPlugin: Plugin = async (
       agentmail_ack,
       agentmail_search,
       agentmail_health,
+      // Swarm Mail (Embedded - Primary)
+      swarmmail_init,
+      swarmmail_send,
+      swarmmail_inbox,
+      swarmmail_read_message,
+      swarmmail_reserve,
+      swarmmail_release,
+      swarmmail_ack,
+      swarmmail_health,
       // Structured
       structured_extract_json,
       structured_validate,

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

@@ -8,8 +8,12 @@ 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:
@@ -24,6 +28,16 @@ This skill provides guidance for effective multi-agent coordination in OpenCode
 
 **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:
@@ -54,7 +68,7 @@ Before decomposing, understand:
 
 **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)
@@ -64,7 +78,7 @@ 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"
@@ -74,7 +88,7 @@ Parent Task: "Migrate database schema"
 
 **Hybrid Strategy** - Mixed dependencies:
 
-```
+```text
 Parent Task: "Add feature X"
 ├── Phase 1 (parallel):
 │   ├── Subtask A: "Design API"
@@ -90,40 +104,87 @@ 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
 
+```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,
+});
 ```
-agentmail_send(recipients: ["frontend-agent"], message: "Auth API is at /api/auth/*, here's the spec...")
-```
 
-### 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 fail, don't block the whole swarm
-5. **Progress updates** - Use beads to track subtask status
-6. **Load relevant skills** - Workers should call `skills_use()` based on their task type:
+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")`
@@ -136,7 +197,7 @@ agentmail_receive(wait: true, filter: "api-complete")
 ```yaml
 decomposition:
   strategy: hybrid
-  skills: [system-design, swarm-coordination] # Load before decomposing
+  skills: [system-design, swarm-coordination]
   phases:
     - name: design
       parallel: true
@@ -157,7 +218,7 @@ decomposition:
 ```yaml
 decomposition:
   strategy: sequential
-  skills: [testing-patterns] # Load before decomposing
+  skills: [testing-patterns]
   subtasks:
     - reproduce-bug
     - identify-root-cause
@@ -171,7 +232,7 @@ decomposition:
 ```yaml
 decomposition:
   strategy: parallel
-  skills: [testing-patterns, system-design] # Load before decomposing
+  skills: [testing-patterns, system-design]
   subtasks:
     - refactor-module-a
     - refactor-module-b
@@ -184,17 +245,20 @@ decomposition:
 
 **For Coordinators:**
 
-1. Load `swarm-coordination` skill first
-2. Analyze task type
-3. Load additional skills based on domain (testing, design, CLI)
-4. Include skill recommendations in `shared_context` for workers
+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. Read `shared_context` from coordinator
-2. Load recommended skills with `skills_use(name="skill-name")`
-3. Apply skill knowledge to subtask
-4. Report completion
+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:**
 
@@ -214,26 +278,15 @@ Project learnings: [semantic-memory results]
 [Domain knowledge from coordinator]
 ```
 
-### Bug Fix Swarm
-
-```yaml
-decomposition:
-  strategy: sequential
-  subtasks:
-    - reproduce-bug
-    - identify-root-cause
-    - implement-fix
-    - add-regression-test
-```
-
-### Refactoring
-
-```yaml
-decomposition:
-  strategy: parallel
-  subtasks:
-    - refactor-module-a
-    - refactor-module-b
-    - update-imports
-    - run-full-test-suite
-```
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/swarm.integration.test.ts

@@ -1315,24 +1315,29 @@ describe("Swarm Prompt V2 (with Agent Mail/Beads)", () => {
   describe("SUBTASK_PROMPT_V2", () => {
     it("contains expected sections", () => {
       // Check all main sections are present in the template
-      expect(SUBTASK_PROMPT_V2).toContain("## Task");
+      expect(SUBTASK_PROMPT_V2).toContain("[TASK]");
       expect(SUBTASK_PROMPT_V2).toContain("{subtask_title}");
       expect(SUBTASK_PROMPT_V2).toContain("{subtask_description}");
 
-      expect(SUBTASK_PROMPT_V2).toContain("## Files");
+      expect(SUBTASK_PROMPT_V2).toContain("[FILES]");
       expect(SUBTASK_PROMPT_V2).toContain("{file_list}");
 
-      expect(SUBTASK_PROMPT_V2).toContain("## Context");
+      expect(SUBTASK_PROMPT_V2).toContain("[CONTEXT]");
       expect(SUBTASK_PROMPT_V2).toContain("{shared_context}");
 
-      expect(SUBTASK_PROMPT_V2).toContain("## Workflow");
+      expect(SUBTASK_PROMPT_V2).toContain("[WORKFLOW]");
     });
 
-    it("DOES contain Agent Mail instructions", () => {
-      // V2 prompt tells agents to USE Agent Mail
-      expect(SUBTASK_PROMPT_V2).toContain("Agent Mail");
-      expect(SUBTASK_PROMPT_V2).toContain("agentmail_send");
+    it("DOES contain Swarm Mail instructions (MANDATORY)", () => {
+      // V2 prompt tells agents to USE Swarm Mail - this is non-negotiable
+      expect(SUBTASK_PROMPT_V2).toContain("SWARM MAIL");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_init");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_send");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_inbox");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_reserve");
+      expect(SUBTASK_PROMPT_V2).toContain("swarmmail_release");
       expect(SUBTASK_PROMPT_V2).toContain("thread_id");
+      expect(SUBTASK_PROMPT_V2).toContain("non-negotiable");
     });
 
     it("DOES contain beads instructions", () => {
@@ -1344,10 +1349,11 @@ describe("Swarm Prompt V2 (with Agent Mail/Beads)", () => {
       expect(SUBTASK_PROMPT_V2).toContain("swarm_complete");
     });
 
-    it("instructs agents to communicate", () => {
+    it("instructs agents to communicate via swarmmail", () => {
       expect(SUBTASK_PROMPT_V2).toContain("Never work silently");
-      expect(SUBTASK_PROMPT_V2).toContain("Report progress");
+      expect(SUBTASK_PROMPT_V2).toContain("progress");
       expect(SUBTASK_PROMPT_V2).toContain("coordinator");
+      expect(SUBTASK_PROMPT_V2).toContain("CRITICAL");
     });
   });
 });

package/src/swarm.ts

@@ -709,21 +709,64 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [TOOLS]
-### Beads
-- beads_update (status: blocked)
-- beads_create (new bugs)
-- beads_close (via swarm_complete)
+## [MANDATORY: SWARM MAIL]
+
+**YOU MUST USE SWARM MAIL FOR ALL COORDINATION.** This is non-negotiable.
+
+### Initialize FIRST (before any work)
+\`\`\`
+swarmmail_init(project_path="$PWD", task_description="{subtask_title}")
+\`\`\`
+
+### Reserve Files (if not already reserved by coordinator)
+\`\`\`
+swarmmail_reserve(paths=[...files...], reason="{bead_id}: {subtask_title}")
+\`\`\`
+
+### Check Inbox Regularly
+\`\`\`
+swarmmail_inbox()  # Check for coordinator messages
+swarmmail_read_message(message_id=N)  # Read specific message
+\`\`\`
+
+### Report Progress (REQUIRED - don't work silently)
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Progress: {bead_id}",
+  body="<what you did, blockers, questions>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### When Blocked
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="BLOCKED: {bead_id}",
+  body="<blocker description, what you need>",
+  importance="high",
+  thread_id="{epic_id}"
+)
+beads_update(id="{bead_id}", status="blocked")
+\`\`\`
+
+### Release Files When Done
+\`\`\`
+swarmmail_release()  # Or let swarm_complete handle it
+\`\`\`
 
-### Agent Mail
-- agentmail_send (thread_id: {epic_id})
+## [OTHER TOOLS]
+### Beads
+- beads_update(id, status) - Mark blocked if stuck
+- beads_create(title, type) - Log new bugs found
 
 ### Skills (if available)
-- skills_list (discover available skills)
-- skills_use (activate a skill for specialized guidance)
+- skills_list() - Discover available skills
+- skills_use(name) - Activate skill for specialized guidance
 
-### Completion
-- swarm_complete (REQUIRED when done)
+### Completion (REQUIRED)
+- swarm_complete(project_key, agent_name, bead_id, summary, files_touched)
 
 ## [LEARNING]
 As you work, note reusable patterns, best practices, or domain insights:
@@ -732,15 +775,15 @@ As you work, note reusable patterns, best practices, or domain insights:
 - Good skills have clear "when to use" descriptions with actionable instructions
 - Skills make swarms smarter over time
 
-## [OUTPUT]
-1. Read files first
-2. Implement changes
-3. Verify (typecheck)
-4. Complete with swarm_complete
-
-Return: Summary of changes made. Note any patterns worth preserving as skills.
+## [WORKFLOW]
+1. **swarmmail_init** - Initialize session FIRST
+2. Read assigned files
+3. Implement changes
+4. **swarmmail_send** - Report progress to coordinator
+5. Verify (typecheck)
+6. **swarm_complete** - Mark done, release reservations
 
-**Never work silently.** Communicate progress and blockers immediately.
+**CRITICAL: Never work silently. Send progress updates via swarmmail_send every significant milestone.**
 
 Begin now.`;