opencode-swarm-plugin 0.12.27 → 0.12.29

package/README.md

@@ -197,20 +197,14 @@ skills_use(name="swarm-coordination")   # Load swarm workflow
 
 ### Bundled Skills
 
-| Skill                        | Tags                 | Description                                                                          |
-| ---------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
-| `agent-patterns`             | ai, agents, patterns | AI agent design patterns - capability whiteboards, architecture evolution, evals     |
-| `cli-builder`                | cli, typescript, bun | Building TypeScript CLIs with Bun - argument parsing, subcommands, output formatting |
-| `code-review`                | review, quality      | Code review patterns - systematic checklists, feedback patterns                      |
-| `debugging`                  | debugging, errors    | Systematic debugging - root cause analysis, error resolution                         |
-| `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              |
-| `resilience-patterns`        | errors, recovery     | Error recovery, retry strategies, graceful degradation                               |
-| `skill-creator`              | meta, skills         | Guide for creating effective skills                                                  |
-| `swarm-coordination`         | swarm, multi-agent   | Multi-agent coordination patterns for swarm workflows                                |
-| `tacit-knowledge-extraction` | knowledge, patterns  | Extracting tacit knowledge into pattern languages                                    |
-| `testing-strategies`         | testing, vitest      | Testing async/swarm operations, mocking patterns                                     |
-| `zod-validation`             | zod, typescript      | Schema validation patterns with Zod                                                  |
+| Skill                | Tags                 | Description                                                                          |
+| -------------------- | -------------------- | ------------------------------------------------------------------------------------ |
+| `cli-builder`        | cli, typescript, bun | Building TypeScript CLIs with Bun - argument parsing, subcommands, output formatting |
+| `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                                |
+| `system-design`      | design, architecture | Building reusable systems - deep modules, complexity management, design red flags    |
 
 ### Skill Locations
 

package/bin/swarm.ts

@@ -1084,17 +1084,17 @@ async function setup() {
       const s = p.spinner();
       s.start("Updating AGENTS.md...");
 
-      const agentsPrompt = `You are updating the user's AGENTS.md file to add skill awareness.
+      const agentsPrompt = `You are updating the user's AGENTS.md file to add swarm plugin awareness.
 
 ## Task
-Read ${agentsPath} and add a Skills section if one doesn't exist. If a skills section exists, update it.
+Read ${agentsPath} and add sections for Skills, CASS, and Semantic Memory if they don't exist. Update existing sections if present.
 
 ## What to Add
 
-1. **Tool Preferences** - If there's a tool_preferences or similar section, add skills tools:
-   - skills_list - discover available skills
-   - skills_use - load skill for context injection  
-   - skills_read - read full skill content
+1. **Tool Preferences** - If there's a tool_preferences section, add these tools:
+   - skills_list, skills_use, skills_read - knowledge injection
+   - cass_search, cass_view, cass_expand - search past agent sessions
+   - semantic-memory_find, semantic-memory_store - persistent learning
 
 2. **Skills Section** - Add this (adapt style to match the file):
 
@@ -1110,17 +1110,65 @@ Skills are reusable knowledge packages. Load them on-demand for specialized task
 **Usage:**
 \`\`\`
 skills_list()                              # See available skills
-skills_use(name="debugging")               # Load a skill
-skills_use(name="code-review", context="reviewing auth") # With context
+skills_use(name="swarm-coordination")      # Load a skill
+skills_use(name="cli-builder", context="building a new CLI") # With context
 \`\`\`
 
-**Bundled Skills:** agent-patterns, cli-builder, code-review, debugging, learning-systems, mcp-tool-authoring, resilience-patterns, skill-creator, swarm-coordination, tacit-knowledge-extraction, testing-strategies, zod-validation
+**Bundled Skills:** cli-builder, learning-systems, mcp-tool-authoring, skill-creator, swarm-coordination
+
+3. **CASS Section** - Add this:
+
+### CASS (Cross-Agent Session Search)
+
+Search across ALL your AI coding agent histories before solving problems from scratch.
+
+**When to Use:**
+- BEFORE implementing anything - check if any agent solved it before
+- When debugging - "what did I try last time this error happened?"
+- When learning patterns - "how did Cursor handle this API?"
+
+**Usage:**
+\`\`\`
+cass_search(query="authentication token refresh", limit=5)  # Search all agents
+cass_search(query="useEffect cleanup", agent="claude", days=7)  # Filter by agent/time
+cass_view(path="/path/from/search", line=42)  # View specific result
+cass_expand(path="/path", line=42, context=10)  # Expand context around match
+\`\`\`
+
+**Pro tip:** Query CASS at the START of complex tasks. Past solutions save time.
+
+4. **Semantic Memory Section** - Add this:
+
+### Semantic Memory (Persistent Learning)
+
+Store and retrieve learnings across sessions. Memories persist and are searchable.
+
+**When to Use:**
+- After solving a tricky problem - store the solution
+- After making architectural decisions - store the reasoning
+- Before starting work - search for relevant past learnings
+- When you discover project-specific patterns
+
+**Usage:**
+\`\`\`
+# Store a learning
+semantic-memory_store(information="OAuth refresh tokens need 5min buffer before expiry", metadata="auth, tokens")
+
+# Search for relevant memories
+semantic-memory_find(query="token refresh", limit=5)
+
+# Validate a memory is still accurate (resets decay timer)
+semantic-memory_validate(id="mem_123")
+\`\`\`
+
+**Pro tip:** Store the WHY, not just the WHAT. Future you needs context.
 
 ## Rules
 - Preserve existing content and style
-- Don't duplicate - update if skills section exists
-- Keep tone consistent
-- Place near tool preferences or as logical new section
+- Don't duplicate - update existing sections if present
+- Keep tone consistent with the rest of the file
+- Place sections in logical order (Skills, CASS, Semantic Memory)
+- If there's a tool_preferences section, add the tools there too
 
 Edit the file now.`;
 
@@ -1641,61 +1689,63 @@ async function agents() {
   const s = p.spinner();
   s.start("Updating AGENTS.md with skill awareness...");
 
-  const prompt = `You are updating the user's AGENTS.md file to add skill awareness.
+  const prompt = `You are updating the user's AGENTS.md file to add swarm plugin awareness.
 
 ## Task
-Read ~/.config/opencode/AGENTS.md and add a Skills section if one doesn't exist.
+Read ~/.config/opencode/AGENTS.md and add sections for Skills, CASS, and Semantic Memory if they don't exist.
 
 ## What to Add
-Add a section about using skills. Include:
 
-1. **Tool Preferences Update** - Add skills_* tools to the tool priority list:
-   - skills_list - discover available skills
-   - skills_use - load skill for context injection
-   - skills_read - read full skill content
+1. **Tool Preferences** - Add these tools to any tool_preferences section:
+   - skills_list, skills_use, skills_read - knowledge injection
+   - cass_search, cass_view, cass_expand - search past agent sessions
+   - semantic-memory_find, semantic-memory_store - persistent learning
 
-2. **Skills Section** - Add this section (adapt to match the file's style):
+2. **Skills Section**:
 
 ### Skills (Knowledge Injection)
 
-Skills are reusable knowledge packages. Load them on-demand for specialized tasks.
+Skills are reusable knowledge packages. Load on-demand for specialized tasks.
 
-**When to Use Skills:**
-- Before starting unfamiliar work - check if a skill exists
-- When you need domain-specific patterns
-- For complex workflows that benefit from guidance
+**When to Use:** Before unfamiliar work, when you need domain patterns, for complex workflows.
 
-**Available Skills** (run \`skills_list()\` to see current list):
-- agent-patterns: AI agent design patterns
-- cli-builder: TypeScript CLI patterns
-- code-review: Review checklists
-- debugging: Root cause analysis
-- learning-systems: Feedback scoring, pattern maturity
-- mcp-tool-authoring: Building MCP tools
-- resilience-patterns: Error recovery, retries
-- skill-creator: Creating new skills
-- swarm-coordination: Multi-agent workflows
-- tacit-knowledge-extraction: Pattern mining
-- testing-strategies: Vitest patterns
-- zod-validation: Schema validation
-
-**Usage Pattern:**
 \`\`\`
-# Check what's available
-skills_list()
+skills_list()                              # See available skills
+skills_use(name="swarm-coordination")      # Load a skill
+\`\`\`
+
+**Bundled:** cli-builder, learning-systems, mcp-tool-authoring, skill-creator, swarm-coordination
+
+3. **CASS Section**:
+
+### CASS (Cross-Agent Session Search)
+
+Search ALL your AI coding agent histories before solving from scratch.
 
-# Load a skill before starting work
-skills_use(name="debugging")
+**When to Use:** BEFORE implementing - check if solved before. When debugging - what worked last time?
 
-# Load with context
-skills_use(name="code-review", context="reviewing auth changes")
+\`\`\`
+cass_search(query="auth token refresh", limit=5)  # Search all agents
+cass_view(path="/path/from/search", line=42)      # View result
+\`\`\`
+
+4. **Semantic Memory Section**:
+
+### Semantic Memory (Persistent Learning)
+
+Store and retrieve learnings across sessions.
+
+**When to Use:** After solving tricky problems, after architectural decisions, before starting work.
+
+\`\`\`
+semantic-memory_store(information="OAuth needs 5min buffer", metadata="auth")
+semantic-memory_find(query="token refresh", limit=5)
 \`\`\`
 
 ## Rules
-- Preserve the existing content and style
-- Add the skills section in a logical place (near tool preferences or as a new section)
-- Don't duplicate if a skills section already exists - update it instead
-- Keep the tone consistent with the rest of the file
+- Preserve existing content and style
+- Don't duplicate - update if sections exist
+- Keep tone consistent
 
 Edit the file now.`;
 

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