opencode-swarm-plugin 0.12.29 → 0.12.31

package/README.md

@@ -203,7 +203,7 @@ skills_use(name="swarm-coordination")   # Load swarm workflow
 | `learning-systems`   | learning, feedback   | Implicit feedback scoring, confidence decay, anti-pattern detection                  |
 | `mcp-tool-authoring` | mcp, tools           | Building MCP tools - schema definition, context passing, error handling              |
 | `skill-creator`      | meta, skills         | Guide for creating effective skills                                                  |
-| `swarm-coordination` | swarm, multi-agent   | Multi-agent coordination patterns for swarm workflows                                |
+| `swarm-coordination` | swarm, multi-agent   | Complete swarm playbook - strategies, coordinator patterns, failure recovery         |
 | `system-design`      | design, architecture | Building reusable systems - deep modules, complexity management, design red flags    |
 
 ### Skill Locations

package/bin/swarm.ts

@@ -497,23 +497,65 @@ $ARGUMENTS
 
 ## Workflow
 
-1. **Initialize**: \`agentmail_init\` with project_path and task_description
-2. **Decompose**: Use \`swarm_select_strategy\` then \`swarm_plan_prompt\` to break down the task
-3. **Create beads**: \`beads_create_epic\` with subtasks and file assignments
-4. **Reserve files**: \`agentmail_reserve\` for each subtask's files
-5. **Spawn agents**: Use Task tool with \`swarm_spawn_subtask\` prompts
-6. **Monitor**: Check \`agentmail_inbox\` for progress, use \`agentmail_summarize_thread\` for overview
-7. **Complete**: \`swarm_complete\` when done, then \`beads_sync\` to push
-
-## Strategy Selection
-
-| Strategy      | Best For                | Keywords                               |
-| ------------- | ----------------------- | -------------------------------------- |
-| file-based    | Refactoring, migrations | refactor, migrate, rename, update all  |
-| feature-based | New features            | add, implement, build, create, feature |
-| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent   |
-
-Begin decomposition now.
+### 1. Initialize
+\`agentmail_init(project_path="$PWD", task_description="Swarm: <task>")\`
+
+### 2. Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings into shared_context for workers.
+
+### 3. Decompose
+\`\`\`
+swarm_select_strategy(task="<task>")
+swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")
+swarm_validate_decomposition(response="<BeadTree JSON>")
+\`\`\`
+
+### 4. Create Beads
+\`beads_create_epic(epic_title="<task>", subtasks=[...])\`
+
+### 5. Reserve Files
+\`agentmail_reserve(paths=[...], reason="<bead-id>: <desc>")\`
+
+### 6. Spawn Agents (ALL in single message)
+\`\`\`
+swarm_spawn_subtask(bead_id, epic_id, subtask_title, files, shared_context)
+Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+### 7. Monitor
+\`\`\`
+swarm_status(epic_id, project_key)
+agentmail_inbox()
+\`\`\`
+
+Intervene if: blocked >5min, file conflicts, scope creep.
+
+### 8. Complete
+\`\`\`
+swarm_complete(...)
+beads_sync()
+\`\`\`
+
+## Strategy Reference
+
+| Strategy       | Best For                 | Keywords                               |
+| -------------- | ------------------------ | -------------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all  |
+| feature-based  | New features             | add, implement, build, create, feature |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |
+| research-based | Investigation, discovery | research, investigate, explore, learn  |
+
+Begin with knowledge gathering now.
 `;
 
 const getPlannerAgent = (model: string) => `---
@@ -526,12 +568,30 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 
 ## Workflow
 
-1. Call \`swarm_select_strategy\` to analyze the task
-2. Call \`swarm_plan_prompt\` to get strategy-specific guidance
-3. Create a BeadTree following the guidelines
-4. Return ONLY valid JSON - no markdown, no explanation
+### 1. Knowledge Gathering (MANDATORY)
 
-## Output Format
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings - note relevant patterns, past approaches, and skills to recommend.
+
+### 2. Strategy Selection
+
+\`swarm_select_strategy(task="<task>")\`
+
+### 3. Generate Plan
+
+\`swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")\`
+
+### 4. Output BeadTree
+
+Return ONLY valid JSON - no markdown, no explanation:
 
 \`\`\`json
 {
@@ -539,7 +599,7 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
   "subtasks": [
     {
       "title": "...",
-      "description": "...",
+      "description": "Include relevant context from knowledge gathering",
       "files": ["src/..."],
       "dependencies": [],
       "estimated_complexity": 2
@@ -554,6 +614,7 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 - No file overlap between subtasks
 - Include tests with the code they test
 - Order by dependency (if B needs A, A comes first)
+- Pass synthesized knowledge to workers via subtask descriptions
 `;
 
 const getWorkerAgent = (model: string) => `---
@@ -564,17 +625,45 @@ model: ${model}
 
 You are a swarm worker agent. Execute your assigned subtask efficiently.
 
+## Context
+
+Your prompt includes shared_context from the coordinator's knowledge gathering:
+- Relevant patterns from pdf-brain
+- Similar past approaches from CASS
+- Project-specific learnings from semantic-memory
+
+**Use this context** - it contains patterns and prior art relevant to your task.
+
+## Workflow
+
+1. **Read** assigned files to understand current state
+2. **Check skills** if you need domain guidance: \`skills_use(name="<relevant-skill>")\`
+3. **Implement** changes following patterns from shared_context
+4. **Verify** (typecheck, lint if applicable)
+5. **Complete** with \`swarm_complete\`
+
 ## Rules
+
 - Focus ONLY on your assigned files
-- Report progress via Agent Mail
-- Use beads_update to track status
-- Call swarm_complete when done
+- Report blockers immediately via Agent Mail (don't spin)
+- Use beads_update if blocked
+- Call swarm_complete when done - it handles bead closure and file release
 
-## Workflow
-1. Read assigned files
-2. Implement changes
-3. Verify (typecheck if applicable)
-4. Report completion
+## Communication
+
+\`\`\`
+agentmail_send(
+  to=["coordinator"],
+  subject="Progress/Blocker",
+  body="...",
+  thread_id="<epic_id>"
+)
+\`\`\`
+
+## Learning
+
+If you discover a reusable pattern worth preserving:
+\`semantic-memory_store(information="<pattern + why it matters>")\`
 `;
 
 // ============================================================================

package/examples/commands/swarm.md

@@ -23,20 +23,45 @@ $ARGUMENTS
 agentmail_init(project_path="$PWD", task_description="Swarm: <task summary>")
 ```
 
-### 2. Create Feature Branch (unless --to-main)
+### 2. Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+```
+# Past learnings from this project
+semantic-memory_find(query="<task keywords>", limit=5)
+
+# How similar tasks were solved before
+cass_search(query="<task description>", limit=5)
+
+# Design patterns and prior art
+pdf-brain_search(query="<domain concepts>", limit=5)
+
+# Available skills to inject into workers
+skills_list()
+```
+
+Synthesize findings into shared context for workers. Note:
+
+- Relevant patterns from pdf-brain
+- Similar past approaches from CASS
+- Project-specific learnings from semantic-memory
+- Skills to recommend for subtasks
+
+### 3. Create Feature Branch (unless --to-main)
 
 ```bash
 git checkout -b swarm/<short-task-name>
 git push -u origin HEAD
 ```
 
-### 3. Decompose Task
+### 4. Decompose Task
 
 Use strategy selection and planning:
 
 ```
 swarm_select_strategy(task="<the task>")
-swarm_plan_prompt(task="<the task>", strategy="<auto or selected>")
+swarm_plan_prompt(task="<the task>", strategy="<auto or selected>", context="<synthesized knowledge>")
 ```
 
 Follow the prompt to create a BeadTree, then validate:
@@ -45,7 +70,7 @@ Follow the prompt to create a BeadTree, then validate:
 swarm_validate_decomposition(response="<your BeadTree JSON>")
 ```
 
-### 4. Create Beads
+### 5. Create Beads
 
 ```
 beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
@@ -56,8 +81,9 @@ Rules:
 - Each bead completable by one agent
 - Independent where possible (parallelizable)
 - 3-7 beads per swarm
+- No file overlap between subtasks
 
-### 5. Reserve Files
+### 6. Reserve Files
 
 ```
 agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
@@ -65,43 +91,56 @@ agentmail_reserve(paths=[<files>], reason="<bead-id>: <description>")
 
 No two agents should edit the same file.
 
-### 6. Spawn Agents
+### 7. Spawn Agents
 
 **CRITICAL: Spawn ALL in a SINGLE message with multiple Task calls.**
 
 For each subtask:
 
 ```
-swarm_spawn_subtask(bead_id="<id>", epic_id="<epic>", subtask_title="<title>", files=[...])
+swarm_spawn_subtask(
+  bead_id="<id>",
+  epic_id="<epic>",
+  subtask_title="<title>",
+  files=[...],
+  shared_context="<synthesized knowledge from step 2>"
+)
 ```
 
 Then spawn:
 
 ```
-Task(subagent_type="swarm-worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
+Task(subagent_type="swarm/worker", description="<bead-title>", prompt="<from swarm_spawn_subtask>")
 ```
 
-### 7. Monitor (unless --no-sync)
+### 8. Monitor (unless --no-sync)
 
 ```
-swarm_status(epic_id="<epic-id>")
+swarm_status(epic_id="<epic-id>", project_key="$PWD")
 agentmail_inbox()
 ```
 
+**Intervention triggers:**
+
+- Worker blocked >5 min → Check inbox, offer guidance
+- File conflict → Mediate, reassign files
+- Worker asking questions → Answer directly
+- Scope creep → Redirect, create new bead for extras
+
 If incompatibilities spotted, broadcast:
 
 ```
 agentmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", importance="high")
 ```
 
-### 8. Complete
+### 9. Complete
 
 ```
 swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
 beads_sync()
 ```
 
-### 9. Create PR (unless --to-main)
+### 10. Create PR (unless --to-main)
 
 ```bash
 gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Beads\n<list>"
@@ -109,10 +148,22 @@ gh pr create --title "feat: <epic title>" --body "## Summary\n<bullets>\n\n## Be
 
 ## Strategy Reference
 
-| Strategy      | Best For                | Keywords                              |
-| ------------- | ----------------------- | ------------------------------------- |
-| file-based    | Refactoring, migrations | refactor, migrate, rename, update all |
-| feature-based | New features            | add, implement, build, create, new    |
-| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent  |
-
-Begin decomposition now.
+| Strategy       | Best For                 | Keywords                              |
+| -------------- | ------------------------ | ------------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all |
+| feature-based  | New features             | add, implement, build, create, new    |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent  |
+| research-based | Investigation, discovery | research, investigate, explore, learn |
+
+## Quick Checklist
+
+- [ ] Knowledge gathered (semantic-memory, CASS, pdf-brain, skills)
+- [ ] Strategy selected
+- [ ] BeadTree validated (no file conflicts)
+- [ ] Epic + subtasks created
+- [ ] Files reserved
+- [ ] Workers spawned in parallel
+- [ ] Progress monitored
+- [ ] PR created (or pushed to main)
+
+Begin with knowledge gathering now.

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

@@ -6,161 +6,284 @@ tags:
   - multi-agent
   - coordination
 tools:
+  - swarm_plan_prompt
   - swarm_decompose
-  - swarm_complete
+  - swarm_validate_decomposition
   - swarm_spawn_subtask
+  - swarm_complete
+  - swarm_status
+  - swarm_progress
+  - beads_create_epic
+  - beads_query
   - agentmail_init
   - agentmail_send
   - agentmail_inbox
   - agentmail_reserve
+  - agentmail_release
+  - semantic-memory_find
+  - cass_search
+  - pdf-brain_search
+  - skills_list
+references:
+  - references/strategies.md
+  - references/coordinator-patterns.md
 ---
 
-# Swarm Coordination Skill
+# Swarm Coordination
 
-This skill provides guidance for effective multi-agent coordination in OpenCode swarm workflows.
+Multi-agent orchestration for parallel task execution. The coordinator breaks work into subtasks, spawns worker agents, monitors progress, and aggregates results.
 
-## When to Use Swarm Coordination
+## When to Swarm
 
-Use swarm coordination when:
+**DO swarm 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
+- Task touches 3+ files
+- Natural parallel boundaries exist (frontend/backend/tests)
+- Different specializations needed
+- Time-to-completion matters
 
-Do NOT use swarm coordination when:
+**DON'T swarm 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 is 1-2 files
+- Heavy sequential dependencies
+- Coordination overhead > benefit
+- Tight feedback loop needed
 
-## Task Decomposition Strategy
+**Heuristic:** If you can describe the task in one sentence without "and", don't swarm.
 
-### 1. Analyze the Task
+## Coordinator Workflow
 
-Before decomposing, understand:
+### Phase 1: Knowledge Gathering (MANDATORY)
 
-- 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?
+Before decomposing, query ALL knowledge sources:
 
-### 2. Choose a Decomposition Strategy
+```typescript
+// 1. Past learnings from this project
+semantic - memory_find({ query: "<task keywords>", limit: 5 });
 
-**Parallel Strategy** - For independent subtasks:
+// 2. How similar tasks were solved before
+cass_search({ query: "<task description>", limit: 5 });
 
-```
-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)
-```
+// 3. Design patterns and prior art
+pdf - brain_search({ query: "<domain concepts>", limit: 5 });
 
-**Sequential Strategy** - When order matters:
+// 4. Available skills to inject into workers
+skills_list();
+```
 
+Synthesize findings into `shared_context` for workers.
+
+### Phase 2: Decomposition
+
+```typescript
+// Auto-select strategy and generate decomposition prompt
+const plan = await swarm_plan_prompt({
+  task: "Add user authentication with OAuth",
+  max_subtasks: 5,
+  query_cass: true, // searches history
+  include_skills: true, // lists relevant skills
+});
+
+// Agent responds with BeadTree JSON, then validate
+const validation = await swarm_validate_decomposition({
+  response: agentResponse,
+});
+
+// Create epic + subtasks atomically
+await beads_create_epic({
+  epic_title: "Add OAuth Authentication",
+  epic_description: "...",
+  subtasks: validation.subtasks,
+});
 ```
-Parent Task: "Migrate database schema"
-├── Step 1: "Create migration files"
-├── Step 2: "Update model definitions"
-├── Step 3: "Run migrations"
-└── Step 4: "Verify data integrity"
+
+### Phase 3: Spawn Workers
+
+```typescript
+for (const subtask of subtasks) {
+  const prompt = await swarm_spawn_subtask({
+    bead_id: subtask.id,
+    epic_id: epic.id,
+    subtask_title: subtask.title,
+    subtask_description: subtask.description,
+    files: subtask.files,
+    shared_context: synthesizedContext,
+  });
+
+  // Spawn via Task tool
+  Task({
+    subagent_type: "swarm/worker",
+    prompt: prompt.worker_prompt,
+  });
+}
 ```
 
-**Hybrid Strategy** - Mixed dependencies:
+### Phase 4: Monitor & Intervene
 
-```
-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"
+```typescript
+// Check progress
+const status = await swarm_status({ epic_id, project_key });
+
+// Check for messages
+const inbox = await agentmail_inbox({ limit: 5 });
+
+// Intervene if needed (see Intervention Patterns)
 ```
 
-## File Reservation Protocol
+### Phase 5: Aggregate & Complete
 
-When multiple agents work on the same codebase:
+- Verify all subtasks completed
+- Run final verification (typecheck, tests)
+- Close epic with summary
+- Record outcomes for learning
 
-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
+## Decomposition Strategies
 
-## Communication Patterns
+Four strategies, auto-selected by task keywords:
 
-### Broadcasting Updates
+| Strategy           | Best For                      | Keywords                              |
+| ------------------ | ----------------------------- | ------------------------------------- |
+| **file-based**     | Refactoring, migrations       | refactor, migrate, rename, update all |
+| **feature-based**  | New features, vertical slices | add, implement, build, create         |
+| **risk-based**     | Bug fixes, security           | fix, bug, security, critical          |
+| **research-based** | Investigation, discovery      | research, investigate, explore        |
 
-```
-agentmail_send(to: ["all"], subject: "API Complete", body: "Completed API endpoints, ready for frontend integration")
-```
+See `references/strategies.md` for full details.
 
-### Direct Coordination
+## File Reservation Protocol
 
-```
-agentmail_send(to: ["frontend-agent"], subject: "Auth API Ready", body: "Auth API is at /api/auth/*, here's the spec...")
-```
+Workers MUST reserve files before editing:
 
-### Checking for Messages
+```typescript
+// Reserve (exclusive by default)
+await agentmail_reserve({
+  paths: ["src/auth/**"],
+  reason: "bd-123: Auth service implementation",
+  ttl_seconds: 3600,
+});
 
-```
-# Check inbox for updates (context-safe: max 5, no bodies)
-agentmail_inbox()
+// Work...
 
-# Read specific message when needed
-agentmail_read_message(message_id: 123)
+// Release (or let swarm_complete handle it)
+await agentmail_release({ paths: ["src/auth/**"] });
 ```
 
-## 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
-
-## Common Patterns
-
-### Feature Development
-
-```yaml
-decomposition:
-  strategy: hybrid
-  phases:
-    - name: design
-      parallel: true
-      subtasks: [api-design, ui-design]
-    - name: implement
-      parallel: true
-      subtasks: [backend, frontend]
-    - name: validate
-      parallel: true
-      subtasks: [tests, docs, review]
+**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:
+
+```typescript
+// Progress update
+agentmail_send({
+  to: ["coordinator"],
+  subject: "Auth API complete",
+  body: "Endpoints ready at /api/auth/*",
+  thread_id: epic_id,
+});
+
+// Blocker
+agentmail_send({
+  to: ["coordinator"],
+  subject: "BLOCKED: Need DB schema",
+  body: "Can't proceed without users table",
+  thread_id: epic_id,
+  importance: "urgent",
+});
 ```
 
-### Bug Fix Swarm
+**Coordinator checks inbox regularly** - don't let workers spin.
+
+## Intervention Patterns
+
+| Signal                  | Action                               |
+| ----------------------- | ------------------------------------ |
+| Worker blocked >5 min   | Check inbox, offer guidance          |
+| File conflict           | Mediate, reassign files              |
+| Worker asking questions | Answer directly                      |
+| Scope creep             | Redirect, create new bead for extras |
+| Repeated failures       | Take over or reassign                |
+
+## Failure Recovery
+
+### Incompatible Outputs
+
+Two workers produce conflicting results.
 
-```yaml
-decomposition:
-  strategy: sequential
-  subtasks:
-    - reproduce-bug
-    - identify-root-cause
-    - implement-fix
-    - add-regression-test
+**Fix:** Pick one approach, re-run other with constraint.
+
+### Worker Drift
+
+Worker implements something different than asked.
+
+**Fix:** Revert, re-run with explicit instructions.
+
+### Cascade Failure
+
+One blocker affects multiple subtasks.
+
+**Fix:** Unblock manually, reassign dependent work, accept partial completion.
+
+## Anti-Patterns
+
+| Anti-Pattern         | Symptom                          | Fix                           |
+| -------------------- | -------------------------------- | ----------------------------- |
+| **Mega-Coordinator** | Coordinator editing files        | Coordinator only orchestrates |
+| **Silent Swarm**     | No communication, late conflicts | Require updates, check inbox  |
+| **Over-Decomposed**  | 10 subtasks for 20 lines         | 2-5 subtasks max              |
+| **Under-Specified**  | "Implement backend"              | Clear goal, files, criteria   |
+
+## Shared Context Template
+
+```markdown
+## Project Context
+
+- Repository: {repo}
+- Stack: {tech stack}
+- Patterns: {from pdf-brain}
+
+## Task Context
+
+- Epic: {title}
+- Goal: {success criteria}
+- Constraints: {scope, time}
+
+## Prior Art
+
+- Similar tasks: {from CASS}
+- Learnings: {from semantic-memory}
+
+## Coordination
+
+- Active subtasks: {list}
+- Reserved files: {list}
+- Thread: {epic_id}
 ```
 
-### Refactoring
+## Quick Reference
+
+```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
 
-```yaml
-decomposition:
-  strategy: parallel
-  subtasks:
-    - refactor-module-a
-    - refactor-module-b
-    - update-imports
-    - run-full-test-suite
+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
 ```
+
+See `references/coordinator-patterns.md` for detailed patterns.

package/global-skills/swarm-coordination/references/coordinator-patterns.md

@@ -0,0 +1,235 @@
+# Coordinator Patterns
+
+The coordinator is the orchestration layer that manages the swarm. This document covers the coordinator's responsibilities, decision points, and intervention patterns.
+
+## Coordinator Responsibilities
+
+### 1. Knowledge Gathering (BEFORE decomposition)
+
+**MANDATORY**: Before decomposing any task, the coordinator MUST query all available knowledge sources:
+
+```
+# 1. Search semantic memory for past learnings
+semantic-memory_find(query="<task keywords>", limit=5)
+
+# 2. Search CASS for similar past tasks
+cass_search(query="<task description>", limit=5)
+
+# 3. Search pdf-brain for design patterns and prior art
+pdf-brain_search(query="<domain concepts>", limit=5)
+
+# 4. List available skills
+skills_list()
+```
+
+**Why this matters:** From "Patterns for Building AI Agents":
+
+> "AI agents, like people, make better decisions when they understand the full context rather than working from fragments."
+
+The coordinator synthesizes findings into `shared_context` that all workers receive.
+
+### 2. Task Decomposition
+
+After knowledge gathering:
+
+1. Select strategy (auto or explicit)
+2. Generate decomposition with `swarm_plan_prompt` or `swarm_decompose`
+3. Validate with `swarm_validate_decomposition`
+4. Create beads with `beads_create_epic`
+
+### 3. Worker Spawning
+
+For each subtask:
+
+1. Generate worker prompt with `swarm_spawn_subtask`
+2. Include relevant skills in prompt
+3. Spawn worker agent via Task tool
+4. Track bead status
+
+### 4. Progress Monitoring
+
+- Check `beads_query(status="in_progress")` for active work
+- Check `agentmail_inbox()` for worker messages
+- Intervene on blockers (see Intervention Patterns below)
+
+### 5. Completion & Aggregation
+
+- Verify all subtasks completed via bead status
+- Aggregate results from worker summaries
+- Run final verification (typecheck, tests)
+- Close epic bead with summary
+
+---
+
+## Decision Points
+
+### When to Swarm vs Single Agent
+
+**Swarm when:**
+
+- 3+ files need modification
+- Task has natural parallel boundaries
+- Different specializations needed (frontend/backend/tests)
+- Time-to-completion matters
+
+**Single agent when:**
+
+- Task touches 1-2 files
+- Heavy sequential dependencies
+- Coordination overhead > parallelization benefit
+- Task requires tight feedback loop
+
+**Heuristic:** If you can describe the task in one sentence without "and", probably single agent.
+
+### When to Intervene
+
+| Signal                    | Action                                                |
+| ------------------------- | ----------------------------------------------------- |
+| Worker blocked >5 min     | Check inbox, offer guidance                           |
+| File conflict detected    | Mediate, reassign files                               |
+| Worker asking questions   | Answer directly, don't spawn new agent                |
+| Scope creep detected      | Redirect to original task, create new bead for extras |
+| Worker failing repeatedly | Take over subtask or reassign                         |
+
+### When to Abort
+
+- Critical blocker affects all subtasks
+- Scope changed fundamentally mid-swarm
+- Resource exhaustion (context, time, cost)
+
+On abort: Close all beads with reason, summarize partial progress.
+
+---
+
+## Context Engineering
+
+From "Patterns for Building AI Agents":
+
+> "Instead of just instructing subagents 'Do this specific task,' you should try to ensure they are able to share context along the way."
+
+### Shared Context Template
+
+```markdown
+## Project Context
+
+- Repository: {repo_name}
+- Tech stack: {stack}
+- Relevant patterns: {patterns from pdf-brain}
+
+## Task Context
+
+- Epic: {epic_title}
+- Goal: {what success looks like}
+- Constraints: {time, scope, dependencies}
+
+## Prior Art
+
+- Similar past tasks: {from CASS}
+- Relevant learnings: {from semantic-memory}
+
+## Coordination
+
+- Other active subtasks: {list}
+- Shared files to avoid: {reserved files}
+- Communication channel: thread_id={epic_id}
+```
+
+### Context Compression
+
+For long-running swarms, compress context periodically:
+
+- Summarize completed subtasks (don't list all details)
+- Keep only active blockers and decisions
+- Preserve key learnings for remaining work
+
+---
+
+## Failure Modes & Recovery
+
+### Incompatible Parallel Outputs
+
+**Problem:** Two agents produce conflicting results that can't be merged.
+
+**From "Patterns for Building AI Agents":**
+
+> "Subagents can create responses that are in conflict — forcing the final agent to combine two incompatible, intermediate products."
+
+**Prevention:**
+
+- Clear file boundaries (no overlap)
+- Explicit interface contracts in shared_context
+- Sequential phases for tightly coupled work
+
+**Recovery:**
+
+- Identify conflict source
+- Pick one approach, discard other
+- Re-run losing subtask with winning approach as constraint
+
+### Worker Drift
+
+**Problem:** Worker goes off-task, implements something different.
+
+**Prevention:**
+
+- Specific, actionable subtask descriptions
+- Clear success criteria in prompt
+- File list as hard constraint
+
+**Recovery:**
+
+- Revert changes
+- Re-run with more explicit instructions
+- Consider taking over manually
+
+### Cascade Failure
+
+**Problem:** One failure blocks multiple dependent subtasks.
+
+**Prevention:**
+
+- Minimize dependencies in decomposition
+- Front-load risky/uncertain work
+- Have fallback plans for critical paths
+
+**Recovery:**
+
+- Unblock manually if possible
+- Reassign dependent work
+- Partial completion is okay - close what's done
+
+---
+
+## Anti-Patterns
+
+### The Mega-Coordinator
+
+**Problem:** Coordinator does too much work itself instead of delegating.
+
+**Symptom:** Coordinator editing files, running tests, debugging.
+
+**Fix:** Coordinator only orchestrates. If you're writing code, you're a worker.
+
+### The Silent Swarm
+
+**Problem:** Workers don't communicate, coordinator doesn't monitor.
+
+**Symptom:** Swarm runs for 30 minutes, then fails with conflicts.
+
+**Fix:** Require progress updates. Check inbox regularly. Intervene early.
+
+### The Over-Decomposed Task
+
+**Problem:** 10 subtasks for a 20-line change.
+
+**Symptom:** Coordination overhead exceeds actual work.
+
+**Fix:** 2-5 subtasks is the sweet spot. If task is small, don't swarm.
+
+### The Under-Specified Subtask
+
+**Problem:** "Implement the backend" with no details.
+
+**Symptom:** Worker asks questions, guesses wrong, or stalls.
+
+**Fix:** Each subtask needs: clear goal, file list, success criteria, context.

package/global-skills/swarm-coordination/references/strategies.md

@@ -0,0 +1,138 @@
+# Decomposition Strategies
+
+Four strategies for breaking tasks into parallelizable subtasks. The coordinator auto-selects based on task keywords, or you can specify explicitly.
+
+## File-Based Strategy
+
+**Best for:** Refactoring, migrations, pattern changes across codebase
+
+**Keywords:** refactor, migrate, update all, rename, replace, convert, upgrade, deprecate, remove, cleanup, lint, format
+
+### Guidelines
+
+- Group files by directory or type (e.g., all components, all tests)
+- Minimize cross-directory dependencies within a subtask
+- Handle shared types/utilities FIRST if they change
+- Each subtask should be a complete transformation of its file set
+- Consider import/export relationships when grouping
+
+### Anti-Patterns
+
+- Don't split tightly coupled files across subtasks
+- Don't group files that have no relationship
+- Don't forget to update imports when moving/renaming
+
+### Examples
+
+| Task                                | Decomposition                                 |
+| ----------------------------------- | --------------------------------------------- |
+| Migrate all components to new API   | Split by component directory                  |
+| Rename `userId` to `accountId`      | Split by module (types first, then consumers) |
+| Update all tests to use new matcher | Split by test directory                       |
+
+---
+
+## Feature-Based Strategy
+
+**Best for:** New features, adding functionality, vertical slices
+
+**Keywords:** add, implement, build, create, feature, new, integrate, connect, enable, support
+
+### Guidelines
+
+- Each subtask is a complete vertical slice (UI + logic + data)
+- Start with data layer/types, then logic, then UI
+- Keep related components together (form + validation + submission)
+- Separate concerns that can be developed independently
+- Consider user-facing features as natural boundaries
+
+### Anti-Patterns
+
+- Don't split a single feature across multiple subtasks
+- Don't create subtasks that can't be tested independently
+- Don't forget integration points between features
+
+### Examples
+
+| Task            | Decomposition                                        |
+| --------------- | ---------------------------------------------------- |
+| Add user auth   | [OAuth setup, Session management, Protected routes]  |
+| Build dashboard | [Data fetching, Chart components, Layout/navigation] |
+| Add search      | [Search API, Search UI, Results display]             |
+
+---
+
+## Risk-Based Strategy
+
+**Best for:** Bug fixes, security issues, critical changes, hotfixes
+
+**Keywords:** fix, bug, security, vulnerability, critical, urgent, hotfix, patch, audit, review
+
+### Guidelines
+
+- Write tests FIRST to capture expected behavior
+- Isolate the risky change to minimize blast radius
+- Add monitoring/logging around the change
+- Create rollback plan as part of the task
+- Audit similar code for the same issue
+
+### Anti-Patterns
+
+- Don't make multiple risky changes in one subtask
+- Don't skip tests for "simple" fixes
+- Don't forget to check for similar issues elsewhere
+
+### Examples
+
+| Task               | Decomposition                                                             |
+| ------------------ | ------------------------------------------------------------------------- |
+| Fix auth bypass    | [Add regression test, Fix vulnerability, Audit similar endpoints]         |
+| Fix race condition | [Add test reproducing issue, Implement fix, Add concurrency tests]        |
+| Security audit     | [Scan for vulnerabilities, Fix critical issues, Document remaining risks] |
+
+---
+
+## Research-Based Strategy
+
+**Best for:** Investigation, learning, discovery, debugging options
+
+**Keywords:** research, investigate, explore, find out, discover, understand, learn about, analyze, compare, evaluate, study, debug options, configuration options
+
+### Guidelines
+
+- Split by information source (PDFs, repos, history, web)
+- Each agent searches with different query angles
+- Include a synthesis subtask that depends on all search subtasks
+- Use pdf-brain for documentation/books if available
+- Use repo-crawl for GitHub repos if URL provided
+- Use CASS for past agent session history
+- Assign NO files to research subtasks (read-only)
+
+### Anti-Patterns
+
+- Don't have one agent search everything sequentially
+- Don't skip synthesis - raw search results need consolidation
+- Don't forget to check tool availability before assigning sources
+
+### Examples
+
+| Task                   | Decomposition                                                                |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| Research auth patterns | [Search PDFs, Search repos, Search history, Synthesize]                      |
+| Investigate error      | [Search CASS for similar errors, Search repo for error handling, Synthesize] |
+| Learn about library    | [Search docs, Search examples, Search issues, Synthesize findings]           |
+
+---
+
+## Strategy Selection
+
+The coordinator auto-selects strategy by matching task keywords. Override with explicit strategy when:
+
+- Task spans multiple categories (e.g., "fix bug and add feature")
+- You have domain knowledge the keywords don't capture
+- Past experience suggests a different approach
+
+```
+swarm_plan_prompt(task="...", strategy="risk-based")  // explicit override
+swarm_plan_prompt(task="...")                          // auto-select
+```

package/package.json

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