opencode-swarm-plugin 0.12.28 → 0.12.30

package/README.md

@@ -203,7 +203,8 @@ 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/global-skills/system-design/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: system-design
+description: Principles for building reusable coding systems. Use when designing modules, APIs, CLIs, or any code meant to be used by others. Based on "A Philosophy of Software Design" by John Ousterhout. Covers deep modules, complexity management, and design red flags.
+tags:
+  - design
+  - architecture
+  - modules
+  - complexity
+---
+
+# System Design
+
+Principles for building reusable, maintainable coding systems. From "A Philosophy of Software Design" by John Ousterhout.
+
+## Core Principle: Fight Complexity
+
+Complexity is the root cause of most software problems. It accumulates incrementally—each shortcut adds a little, until the system becomes unmaintainable.
+
+**Complexity defined:** Anything that makes software hard to understand or modify.
+
+**Symptoms:**
+
+- Change amplification: simple change requires many modifications
+- Cognitive load: how much you need to know to make a change
+- Unknown unknowns: not obvious what needs to change
+
+## Deep Modules
+
+The most important design principle: **make modules deep**.
+
+```
+┌─────────────────────────────┐
+│      Simple Interface       │  ← Small surface area
+├─────────────────────────────┤
+│                             │
+│                             │
+│    Deep Implementation      │  ← Lots of functionality
+│                             │
+│                             │
+└─────────────────────────────┘
+```
+
+**Deep module:** Simple interface, lots of functionality hidden behind it.
+
+**Shallow module:** Complex interface relative to functionality provided. Red flag.
+
+### Examples
+
+**Deep:** Unix file I/O - just 5 calls (open, read, write, lseek, close) hide enormous complexity (buffering, caching, device drivers, permissions, journaling).
+
+**Shallow:** Java's file reading requires BufferedReader wrapping FileReader wrapping FileInputStream. Interface complexity matches implementation complexity.
+
+### Apply This
+
+- Prefer fewer methods that do more over many small methods
+- Hide implementation details aggressively
+- A module's interface should be much simpler than its implementation
+- If interface is as complex as implementation, reconsider the abstraction
+
+## Strategic vs Tactical Programming
+
+**Tactical:** Get it working now. Each task adds small complexities. Debt accumulates.
+
+**Strategic:** Invest time in good design. Slower initially, faster long-term.
+
+```
+Progress
+   │
+   │        Strategic ────────────────→
+   │       /
+   │      /
+   │     / Tactical ─────────→
+   │    /                    ↘ (slows down)
+   │   /
+   └──┴─────────────────────────────────→ Time
+```
+
+**Rule of thumb:** Spend 10-20% of development time on design improvements.
+
+### Working Code Isn't Enough
+
+"Working code" is not the goal. The goal is a great design that also works. If you're satisfied with "it works," you're programming tactically.
+
+## Information Hiding
+
+Each module should encapsulate knowledge that other modules don't need.
+
+**Information leakage (red flag):** Same knowledge appears in multiple places. If one changes, all must change.
+
+**Temporal decomposition (red flag):** Splitting code based on when things happen rather than what information they use. Often causes leakage.
+
+### Apply This
+
+- Ask: "What knowledge does this module encapsulate?"
+- If the answer is "not much," the module is probably shallow
+- Group code by what it knows, not when it runs
+- Private by default; expose only what's necessary
+
+## Define Errors Out of Existence
+
+Exceptions add complexity. The best way to handle them: design so they can't happen.
+
+**Instead of:**
+
+```typescript
+function deleteFile(path: string): void {
+  if (!exists(path)) throw new FileNotFoundError();
+  // delete...
+}
+```
+
+**Do:**
+
+```typescript
+function deleteFile(path: string): void {
+  // Just delete. If it doesn't exist, goal is achieved.
+  // No error to handle.
+}
+```
+
+### Apply This
+
+- Redefine semantics so errors become non-issues
+- Handle edge cases internally rather than exposing them
+- Fewer exceptions = simpler interface = deeper module
+- Ask: "Can I change the definition so this isn't an error?"
+
+## General-Purpose Modules
+
+Somewhat general-purpose modules are deeper than special-purpose ones.
+
+**Not too general:** Don't build a framework when you need a function.
+
+**Not too specific:** Don't hardcode assumptions that limit reuse.
+
+**Sweet spot:** Solve today's problem in a way that naturally handles tomorrow's.
+
+### Questions to Ask
+
+1. What is the simplest interface that covers all current needs?
+2. How many situations will this method be used in?
+3. Is this API easy to use for my current needs?
+
+## Pull Complexity Downward
+
+When complexity is unavoidable, put it in the implementation, not the interface.
+
+**Bad:** Expose complexity to all callers.
+**Good:** Handle complexity once, internally.
+
+It's more important for a module to have a simple interface than a simple implementation.
+
+### Example
+
+Configuration: Instead of requiring callers to configure everything, provide sensible defaults. Handle the complexity of choosing defaults internally.
+
+## Design Twice
+
+Before implementing, consider at least two different designs. Compare them.
+
+**Benefits:**
+
+- Reveals assumptions you didn't know you were making
+- Often the second design is better
+- Even if first design wins, you understand why
+
+**Don't skip this:** "I can't think of another approach" usually means you haven't tried hard enough.
+
+## Red Flags Summary
+
+| Red Flag                | Symptom                                          |
+| ----------------------- | ------------------------------------------------ |
+| Shallow module          | Interface complexity ≈ implementation complexity |
+| Information leakage     | Same knowledge in multiple modules               |
+| Temporal decomposition  | Code split by time, not information              |
+| Overexposure            | Too many methods/params in interface             |
+| Pass-through methods    | Method does little except call another           |
+| Repetition              | Same code pattern appears multiple times         |
+| Special-general mixture | General-purpose code mixed with special-purpose  |
+| Conjoined methods       | Can't understand one without reading another     |
+| Comment repeats code    | Comment says what code obviously does            |
+| Vague name              | Name doesn't convey much information             |
+
+## Applying to CLI/Tool Design
+
+When building CLIs, plugins, or tools:
+
+1. **Deep commands:** Few commands that do a lot, not many shallow ones
+2. **Sensible defaults:** Work without configuration for common cases
+3. **Progressive disclosure:** Simple usage first, advanced options available
+4. **Consistent interface:** Same patterns across all commands
+5. **Error elimination:** Design so common mistakes are impossible
+
+### Example: Good CLI Design
+
+```bash
+# Deep: one command handles the common case well
+swarm setup
+
+# Not shallow: doesn't require 10 flags for basic usage
+# Sensible defaults: picks reasonable models
+# Progressive: advanced users can customize later
+```
+
+## Key Takeaways
+
+1. **Complexity is the enemy.** Every design decision should reduce it.
+2. **Deep modules win.** Simple interface, rich functionality.
+3. **Hide information.** Each module owns specific knowledge.
+4. **Define errors away.** Change semantics to eliminate edge cases.
+5. **Design twice.** Always consider alternatives.
+6. **Strategic > tactical.** Invest in design, not just working code.
+7. **Pull complexity down.** Implementation absorbs complexity, interface stays simple.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.12.28",
+  "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",