opencode-swarm-plugin 0.44.1 → 0.45.0

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 cells with `hive_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 `hive_query(status="in_progress")` for active work
+- Check `swarmmail_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 cells 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.