opencode-swarm-plugin 0.12.29 → 0.12.30

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/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.30",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",