opencode-swarm-plugin 0.6.3 → 0.10.0

package/README.md

@@ -3,689 +3,332 @@
 [![npm version](https://img.shields.io/npm/v/opencode-swarm-plugin.svg)](https://www.npmjs.com/package/opencode-swarm-plugin)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Multi-agent swarm coordination for [OpenCode](https://opencode.ai) with learning capabilities, beads integration, and Agent Mail.
-
-## Overview
-
-This plugin provides intelligent, self-improving tools for multi-agent workflows in OpenCode:
-
-- **Type-safe beads operations** - Zod-validated wrappers around the `bd` CLI with proper error handling
-- **Agent Mail integration** - File reservations, async messaging, and thread coordination between agents
-- **Structured outputs** - Reliable JSON responses with schema validation and retry support
-- **Swarm primitives** - Task decomposition, status tracking, and parallel agent coordination
-- **Learning from outcomes** - Confidence decay, implicit feedback scoring, and pattern maturity tracking
-- **Anti-pattern detection** - Automatically learns what decomposition strategies fail and avoids them
-- **Pre-completion validation** - UBS bug scanning before marking tasks complete
-- **History-informed decomposition** - Queries CASS for similar past tasks to inform strategy
-- **Graceful degradation** - Works with whatever tools are available, degrades features when tools missing
-- **Swarm discipline** - Enforces beads tracking, aggressive planning, and agent communication
+```
+ ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
+ ██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║
+ ███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
+ ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
+ ███████║╚███╔███╔╝██║  ██║██║  ██║██║ ╚═╝ ██║
+ ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝
 
-## Quick Start
+    \ ` - ' /
+   - .(o o). -
+    (  >.<  )        Multi-agent coordination for OpenCode
+     /|   |\         Break complex tasks into parallel subtasks,
+    (_|   |_)        spawn agents, coordinate via messaging.
+      bzzzz...       The plugin learns from outcomes.
+```
 
-### 1. Install Dependencies
+## Install
 
 ```bash
-# OpenCode (plugin host)
-brew install sst/tap/opencode
-
-# Beads CLI (issue tracking)
-npm install -g @joelhooks/beads
-```
-
-### 2. Install Plugin
+npm install -g opencode-swarm-plugin
+swarm setup
+```
+
+The setup wizard handles everything:
+
+```
+┌  opencode-swarm-plugin v0.10.0
+│
+◇  Checking dependencies...
+│
+◆  OpenCode
+◆  Beads
+◆  Go
+▲  Agent Mail (optional)
+▲  Redis (optional)
+│
+◆  Install optional dependencies?
+│  ◻ Agent Mail - Multi-agent coordination
+│  ◻ Redis - Rate limiting
+│
+◇  Setting up OpenCode integration...
+│
+◆  Plugin: ~/.config/opencode/plugins/swarm.ts
+◆  Command: ~/.config/opencode/commands/swarm.md
+◆  Agent: ~/.config/opencode/agents/swarm-planner.md
+│
+└  Setup complete!
+```
+
+Then in your project:
 
 ```bash
-npm install opencode-swarm-plugin
+cd your-project
+swarm init
 ```
 
-### 3. Create Plugin Wrapper
+## CLI
 
-Create a file at `~/.config/opencode/plugins/swarm.ts`:
-
-```ts
-import { SwarmPlugin } from "opencode-swarm-plugin";
-export default SwarmPlugin;
+```
+swarm setup     Interactive installer - checks and installs all dependencies
+swarm doctor    Health check - shows status of all dependencies
+swarm init      Initialize beads in current project
+swarm config    Show paths to generated config files
+swarm version   Show version and banner
+swarm help      Show help
 ```
 
-That's it! OpenCode will load the plugin automatically.
-
-### 4. Copy Examples (Recommended)
-
-```bash
-# Create directories
-mkdir -p ~/.config/opencode/commands ~/.config/opencode/agents
+## Usage
 
-# Copy /swarm command
-cp node_modules/opencode-swarm-plugin/examples/commands/swarm.md ~/.config/opencode/commands/
+In OpenCode:
 
-# Copy @swarm-planner agent
-cp node_modules/opencode-swarm-plugin/examples/agents/swarm-planner.md ~/.config/opencode/agents/
+```
+/swarm "Add user authentication with OAuth"
 ```
 
-### 5. Initialize Beads in Your Project
+Or invoke the planner directly:
 
-```bash
-cd your-project
-bd init
+```
+@swarm-planner "Refactor all components to use hooks"
 ```
 
-### Alternative: Direct Copy (No Wrapper)
+## Customization
 
-If you prefer not to use the wrapper pattern:
+Run `swarm config` to see your config file paths:
 
-```bash
-mkdir -p ~/.config/opencode/plugins
-cp node_modules/opencode-swarm-plugin/dist/plugin.js ~/.config/opencode/plugins/swarm.js
 ```
+🔌 Plugin loader
+   ~/.config/opencode/plugins/swarm.ts
 
-## Dependencies
+📜 /swarm command prompt
+   ~/.config/opencode/commands/swarm.md
 
-### Required
+🤖 @swarm-planner agent
+   ~/.config/opencode/agents/swarm-planner.md
+```
 
-| Dependency                                      | Purpose                   | Install                           |
-| ----------------------------------------------- | ------------------------- | --------------------------------- |
-| [OpenCode](https://opencode.ai)                 | Plugin host               | `brew install sst/tap/opencode`   |
-| [Beads CLI](https://github.com/joelhooks/beads) | Git-backed issue tracking | `npm install -g @joelhooks/beads` |
+### /swarm Command
 
-### Optional (Graceful Degradation)
+The `/swarm` command is defined in `~/.config/opencode/commands/swarm.md`:
 
-The plugin works without these, but with reduced functionality:
+```markdown
+---
+description: Decompose task into parallel subtasks and coordinate agents
+---
 
-| Dependency                                            | Purpose                  | Without It                               |
-| ----------------------------------------------------- | ------------------------ | ---------------------------------------- |
-| [Agent Mail](https://github.com/joelhooks/agent-mail) | Multi-agent coordination | No file reservations, no agent messaging |
-| [Redis](https://redis.io)                             | Rate limiting            | Falls back to SQLite                     |
-| [CASS](https://github.com/Dicklesworthstone/cass)     | Historical context       | No "similar past tasks" in decomposition |
-| [UBS](https://github.com/joelhooks/ubs)               | Bug scanning             | No pre-completion validation             |
+You are a swarm coordinator. Take a complex task, break it into beads,
+and unleash parallel agents.
 
-### Verify Installation
+## Usage
 
-```bash
-# Check OpenCode
-opencode --version
+/swarm <task description or bead-id>
 
-# Check Beads
-bd --version
+## Workflow
 
-# Check Agent Mail (if using multi-agent)
-curl http://127.0.0.1:8765/health/liveness
+1. **Initialize**: `agentmail_init` with project_path and task_description
+2. **Decompose**: Use `swarm_select_strategy` then `swarm_plan_prompt`
+3. **Create beads**: `beads_create_epic` with subtasks and file assignments
+4. **Reserve files**: `agentmail_reserve` for each subtask's files
+5. **Spawn agents**: Use Task tool with `swarm_spawn_subtask` prompts
+6. **Monitor**: Check `agentmail_inbox` for progress
+7. **Complete**: `swarm_complete` when done, then `beads_sync` to push
 
-# Check Redis (optional)
-redis-cli ping
-```
-
-## Installation Details
+## Strategy Selection
 
-### From npm
+| Strategy      | Best For                | Keywords                              |
+| ------------- | ----------------------- | ------------------------------------- |
+| file-based    | Refactoring, migrations | refactor, migrate, rename, update all |
+| feature-based | New features            | add, implement, build, create         |
+| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent  |
 
-```bash
-npm install opencode-swarm-plugin
-# or
-bun add opencode-swarm-plugin
-# or
-pnpm add opencode-swarm-plugin
+Begin decomposition now.
 ```
 
-### Plugin Setup (Wrapper Pattern)
+### @swarm-planner Agent
 
-Create `~/.config/opencode/plugins/swarm.ts`:
+The `@swarm-planner` agent is defined in `~/.config/opencode/agents/swarm-planner.md`:
 
-```ts
-import { SwarmPlugin } from "opencode-swarm-plugin";
-export default SwarmPlugin;
-```
+````markdown
+---
+name: swarm-planner
+description: Strategic task decomposition for swarm coordination
+model: claude-sonnet-4-5
+---
 
-OpenCode runs on Bun and loads TypeScript directly - no build step needed.
+You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 
-### Plugin Setup (Direct Copy)
+## Workflow
 
-Alternatively, copy the pre-built bundle:
+1. Call `swarm_select_strategy` to analyze the task
+2. Call `swarm_plan_prompt` to get strategy-specific guidance
+3. Create a BeadTree following the guidelines
+4. Return ONLY valid JSON - no markdown, no explanation
 
-```bash
-mkdir -p ~/.config/opencode/plugins
-cp node_modules/opencode-swarm-plugin/dist/plugin.js ~/.config/opencode/plugins/swarm.js
+## Output Format
+
+```json
+{
+  "epic": { "title": "...", "description": "..." },
+  "subtasks": [
+    {
+      "title": "...",
+      "description": "...",
+      "files": ["src/..."],
+      "dependencies": [],
+      "estimated_complexity": 2
+    }
+  ]
+}
 ```
+````
 
-### Example Files
+## Rules
 
-Copy the `/swarm` command and `@swarm-planner` agent:
+- 2-7 subtasks (too few = not parallel, too many = overhead)
+- No file overlap between subtasks
+- Include tests with the code they test
+- Order by dependency (if B needs A, A comes first)
 
-```bash
-# Command
-mkdir -p ~/.config/opencode/commands
-cp node_modules/opencode-swarm-plugin/examples/commands/swarm.md ~/.config/opencode/commands/
+````
 
-# Agent
-mkdir -p ~/.config/opencode/agents
-cp node_modules/opencode-swarm-plugin/examples/agents/swarm-planner.md ~/.config/opencode/agents/
-```
+Edit these files to customize behavior. Run `swarm setup` to regenerate defaults.
 
-> **Note:** The package has two entry points:
->
-> - `dist/index.js` - Full library exports (schemas, errors, utilities, learning modules)
-> - `dist/plugin.js` - Plugin entry point that only exports the `plugin` function for OpenCode
+## Dependencies
 
-## Tools Reference
+| Dependency | Purpose | Required |
+|------------|---------|----------|
+| [OpenCode](https://opencode.ai) | Plugin host | Yes |
+| [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking | Yes |
+| [Go](https://go.dev) | Required for Agent Mail | No |
+| [Agent Mail](https://github.com/joelhooks/agent-mail) | Multi-agent coordination, file reservations | No |
+| [CASS](https://github.com/Dicklesworthstone/cass) | Historical context from past sessions | No |
+| [UBS](https://github.com/joelhooks/ubs) | Pre-completion bug scanning | No |
+| [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence | No |
+| [Redis](https://redis.io) | Rate limiting (SQLite fallback available) | No |
 
-### Beads Tools
-
-| Tool                | Description                                                         |
-| ------------------- | ------------------------------------------------------------------- |
-| `beads_create`      | Create a new bead with type-safe validation                         |
-| `beads_create_epic` | Create epic with subtasks in one atomic operation                   |
-| `beads_query`       | Query beads with filters (replaces `bd list`, `bd ready`, `bd wip`) |
-| `beads_update`      | Update bead status/description/priority                             |
-| `beads_close`       | Close a bead with reason                                            |
-| `beads_start`       | Mark bead as in-progress (shortcut)                                 |
-| `beads_ready`       | Get next ready bead (unblocked, highest priority)                   |
-| `beads_sync`        | Sync beads to git and push (MANDATORY at session end)               |
-| `beads_link_thread` | Link bead to Agent Mail thread                                      |
-
-### Agent Mail Tools
-
-| Tool                         | Description                                          |
-| ---------------------------- | ---------------------------------------------------- |
-| `agentmail_init`             | Initialize session (ensure project + register agent) |
-| `agentmail_send`             | Send message to other agents                         |
-| `agentmail_inbox`            | Fetch inbox (CONTEXT-SAFE: bodies excluded, limit 5) |
-| `agentmail_read_message`     | Fetch ONE message body by ID                         |
-| `agentmail_summarize_thread` | Summarize thread (PREFERRED over fetching all)       |
-| `agentmail_reserve`          | Reserve file paths for exclusive editing             |
-| `agentmail_release`          | Release file reservations                            |
-| `agentmail_ack`              | Acknowledge a message                                |
-| `agentmail_search`           | Search messages (FTS5 syntax)                        |
-| `agentmail_health`           | Check if Agent Mail server is running                |
+All dependencies are checked and can be installed via `swarm setup`.
 
-## Rate Limiting
+## Tools Reference
 
-Client-side, per-agent rate limits prevent abuse and ensure fair resource usage across agents. Uses Redis as primary store (`localhost:6379`) with automatic SQLite fallback (`~/.config/opencode/rate-limits.db`).
-
-### Default Limits
-
-| Endpoint           | Per Minute | Per Hour |
-| ------------------ | ---------- | -------- |
-| `send`             | 20         | 200      |
-| `reserve`          | 10         | 100      |
-| `release`          | 10         | 100      |
-| `ack`              | 20         | 200      |
-| `inbox`            | 60         | 600      |
-| `read_message`     | 60         | 600      |
-| `summarize_thread` | 30         | 300      |
-| `search`           | 30         | 300      |
-
-### Configuration
-
-| Environment Variable                      | Description                                                                 |
-| ----------------------------------------- | --------------------------------------------------------------------------- |
-| `OPENCODE_RATE_LIMIT_REDIS_URL`           | Redis connection URL (default: `redis://localhost:6379`)                    |
-| `OPENCODE_RATE_LIMIT_SQLITE_PATH`         | SQLite database path (default: `~/.config/opencode/rate-limits.db`)         |
-| `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_MIN`  | Per-minute limit for endpoint (e.g., `OPENCODE_RATE_LIMIT_SEND_PER_MIN=30`) |
-| `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_HOUR` | Per-hour limit for endpoint (e.g., `OPENCODE_RATE_LIMIT_SEND_PER_HOUR=300`) |
-
-### Troubleshooting
-
-- **Rate limit exceeded errors** - Adjust limits via environment variables for your workload
-- **Redis unavailable** - Automatic SQLite fallback with warning logged; no action needed
-- **SQLite cleanup** - Expired entries cleaned automatically on init
-
-### Swarm Tools
-
-| Tool                           | Description                                                              |
-| ------------------------------ | ------------------------------------------------------------------------ |
-| `swarm_init`                   | Check tool availability, report degraded features                        |
-| `swarm_select_strategy`        | Analyze task and recommend decomposition strategy                        |
-| `swarm_plan_prompt`            | Generate strategy-specific planning prompt with CASS integration         |
-| `swarm_decompose`              | Generate decomposition prompt, optionally queries CASS for similar tasks |
-| `swarm_validate_decomposition` | Validate decomposition response, detect instruction conflicts            |
-| `swarm_status`                 | Get swarm status by epic ID                                              |
-| `swarm_progress`               | Report progress on a subtask                                             |
-| `swarm_complete`               | Mark subtask complete with UBS bug scan, release reservations            |
-| `swarm_record_outcome`         | Record outcome for implicit feedback (duration, errors, retries)         |
-| `swarm_subtask_prompt`         | Generate prompt for spawned subtask agent (V1 - includes coordination)   |
-| `swarm_spawn_subtask`          | Generate V2 prompt with Agent Mail/beads instructions for subagents      |
-| `swarm_complete_subtask`       | Handle subtask completion: close bead, create issue beads                |
-| `swarm_evaluation_prompt`      | Generate self-evaluation prompt                                          |
-
-### Structured Output Tools
-
-| Tool                             | Description                                              |
-| -------------------------------- | -------------------------------------------------------- |
-| `structured_extract_json`        | Extract JSON from markdown/text with multiple strategies |
-| `structured_validate`            | Validate response against named schema                   |
-| `structured_parse_evaluation`    | Parse and validate evaluation response                   |
-| `structured_parse_decomposition` | Parse and validate task decomposition                    |
-| `structured_parse_bead_tree`     | Parse and validate bead tree for epic creation           |
+### Swarm
+
+| Tool | Description |
+|------|-------------|
+| `swarm_init` | Initialize swarm session |
+| `swarm_select_strategy` | Analyze task, recommend decomposition strategy (file/feature/risk-based) |
+| `swarm_plan_prompt` | Generate strategy-specific planning prompt with CASS history |
+| `swarm_decompose` | Generate decomposition prompt |
+| `swarm_validate_decomposition` | Validate response, detect file conflicts |
+| `swarm_spawn_subtask` | Generate worker agent prompt with Agent Mail/beads instructions |
+| `swarm_status` | Get swarm progress by epic ID |
+| `swarm_progress` | Report subtask progress to coordinator |
+| `swarm_complete` | Complete subtask - runs UBS scan, releases reservations |
+| `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
+
+### Beads
+
+| Tool | Description |
+|------|-------------|
+| `beads_create` | Create bead with type-safe validation |
+| `beads_create_epic` | Create epic + subtasks atomically |
+| `beads_query` | Query beads with filters (status, type, ready) |
+| `beads_update` | Update status/description/priority |
+| `beads_close` | Close bead with reason |
+| `beads_start` | Mark bead as in-progress |
+| `beads_ready` | Get next unblocked bead |
+| `beads_sync` | Sync to git and push |
+| `beads_link_thread` | Link bead to Agent Mail thread |
+
+### Agent Mail
+
+| Tool | Description |
+|------|-------------|
+| `agentmail_init` | Initialize session, register agent |
+| `agentmail_send` | Send message to agents |
+| `agentmail_inbox` | Fetch inbox (max 5, no bodies - context safe) |
+| `agentmail_read_message` | Fetch single message body by ID |
+| `agentmail_summarize_thread` | Summarize thread (preferred over fetching all) |
+| `agentmail_reserve` | Reserve file paths for exclusive editing |
+| `agentmail_release` | Release file reservations |
+| `agentmail_ack` | Acknowledge message |
+| `agentmail_search` | Search messages by keyword |
+| `agentmail_health` | Check if Agent Mail server is running |
+
+### Structured Output
+
+| Tool | Description |
+|------|-------------|
+| `structured_extract_json` | Extract JSON from markdown/text (multiple strategies) |
+| `structured_validate` | Validate response against schema |
+| `structured_parse_evaluation` | Parse self-evaluation response |
+| `structured_parse_decomposition` | Parse task decomposition response |
+| `structured_parse_bead_tree` | Parse bead tree for epic creation |
 
 ## Decomposition Strategies
 
-The plugin supports three decomposition strategies, auto-selected based on task keywords:
-
-### File-Based Strategy
-
-Best for: Refactoring, migrations, pattern changes across codebase
-
-**Keywords**: refactor, migrate, rename, update all, convert, upgrade
+### File-Based
 
-**Guidelines**:
+Best for: refactoring, migrations, pattern changes
 
 - Group files by directory or type
 - Handle shared types/utilities first
 - Minimize cross-directory dependencies
 
-### Feature-Based Strategy
+**Keywords**: refactor, migrate, rename, update all, replace
 
-Best for: New features, adding functionality
+### Feature-Based
 
-**Keywords**: add, implement, build, create, feature, new
-
-**Guidelines**:
+Best for: new features, adding functionality
 
 - Each subtask is a complete vertical slice
 - Start with data layer, then logic, then UI
 - Keep related components together
 
-### Risk-Based Strategy
-
-Best for: Bug fixes, security issues, critical changes
+**Keywords**: add, implement, build, create, feature
 
-**Keywords**: fix, bug, security, critical, urgent, hotfix
+### Risk-Based
 
-**Guidelines**:
+Best for: bug fixes, security issues
 
 - Write tests FIRST
 - Isolate risky changes
 - Audit similar code for same issue
 
-### Strategy Selection
-
-Use `swarm_select_strategy` to see the recommended strategy:
-
-```typescript
-swarm_select_strategy({ task: "Add user authentication" });
-// Returns: { strategy: "feature-based", confidence: 0.85, reasoning: "..." }
-```
-
-Or let `swarm_plan_prompt` auto-select:
-
-```typescript
-swarm_plan_prompt({ task: "Refactor all components to use hooks" });
-// Auto-selects file-based strategy
-```
-
-## Example Planner Agent
-
-The plugin includes an example planner agent at `examples/agents/swarm-planner.md`.
-
-Copy to your OpenCode agents directory:
-
-```bash
-cp examples/agents/swarm-planner.md ~/.config/opencode/agents/
-```
-
-Then invoke with:
-
-```
-@swarm-planner "Add user authentication with OAuth"
-```
-
-The planner uses `swarm_select_strategy` and `swarm_plan_prompt` internally to create optimal decompositions.
-
-### Schemas (for structured outputs)
-
-The plugin exports Zod schemas for validated agent responses:
-
-| Schema                       | Purpose                                      |
-| ---------------------------- | -------------------------------------------- |
-| `TaskDecompositionSchema`    | Decompose task into parallelizable subtasks  |
-| `EvaluationSchema`           | Agent self-evaluation of completed work      |
-| `WeightedEvaluationSchema`   | Evaluation with confidence-weighted criteria |
-| `SwarmStatusSchema`          | Swarm progress tracking                      |
-| `SwarmSpawnResultSchema`     | Result of spawning agent swarm               |
-| `BeadSchema`                 | Validated bead data                          |
-| `EpicCreateResultSchema`     | Atomic epic creation result                  |
-| `FeedbackEventSchema`        | Feedback event for learning                  |
-| `OutcomeSignalsSchema`       | Implicit feedback from task outcomes         |
-| `DecompositionPatternSchema` | Tracked decomposition pattern                |
-| `PatternMaturitySchema`      | Pattern maturity state tracking              |
-
-## Usage Examples
-
-### Basic Bead Creation
-
-```typescript
-// Create a bug report with priority
-await tools["beads_create"]({
-  title: "Fix login redirect loop",
-  type: "bug",
-  priority: 1,
-  description: "Users stuck in redirect after OAuth callback",
-});
-```
-
-### Atomic Epic with Subtasks
-
-```typescript
-// Create epic and all subtasks atomically (with rollback hints on failure)
-const result = await tools["beads_create_epic"]({
-  epic_title: "Implement user dashboard",
-  epic_description: "New dashboard with metrics and activity feed",
-  subtasks: [
-    {
-      title: "Create dashboard layout",
-      priority: 2,
-      files: ["src/components/Dashboard.tsx"],
-    },
-    {
-      title: "Add metrics API endpoint",
-      priority: 2,
-      files: ["src/api/metrics.ts"],
-    },
-    {
-      title: "Build activity feed component",
-      priority: 3,
-      files: ["src/components/ActivityFeed.tsx"],
-    },
-  ],
-});
-```
-
-### Agent Mail Coordination
-
-```typescript
-// 1. Initialize session
-await tools["agentmail_init"]({
-  project_path: "/Users/you/project",
-  task_description: "Working on auth refactor",
-});
-// Returns: { agent: { name: "BlueLake", ... } }
-
-// 2. Reserve files before editing
-await tools["agentmail_reserve"]({
-  paths: ["src/auth/**", "src/middleware/auth.ts"],
-  reason: "bd-abc123: Auth refactor",
-  ttl_seconds: 3600,
-});
-
-// 3. Check inbox (bodies excluded by default)
-const messages = await tools["agentmail_inbox"]({ limit: 5 });
-
-// 4. Send status update to other agents
-await tools["agentmail_send"]({
-  to: ["RedStone", "GreenCastle"],
-  subject: "Auth refactor complete",
-  body: "Finished updating the auth middleware. Ready for review.",
-  thread_id: "bd-abc123",
-});
-
-// 5. Release reservations when done
-await tools["agentmail_release"]({});
-```
-
-### Swarm Workflow
-
-```typescript
-// 1. Create epic for the work
-const epic = await tools["beads_create_epic"]({
-  epic_title: "Add export feature",
-  subtasks: [
-    { title: "Export to CSV", files: ["src/export/csv.ts"] },
-    { title: "Export to JSON", files: ["src/export/json.ts"] },
-    { title: "Export to PDF", files: ["src/export/pdf.ts"] },
-  ],
-});
-
-// 2. Each parallel agent reserves its files
-// Agent 1 (BlueLake):
-await tools["agentmail_reserve"]({
-  paths: ["src/export/csv.ts"],
-  reason: `${epic.subtasks[0].id}: Export to CSV`,
-});
-
-// 3. Agents communicate via thread
-await tools["agentmail_send"]({
-  to: ["Coordinator"],
-  subject: "CSV export complete",
-  body: "Implemented CSV export with streaming support.",
-  thread_id: epic.epic.id,
-});
-
-// 4. Coordinator uses summarize_thread (not fetch all)
-const summary = await tools["agentmail_summarize_thread"]({
-  thread_id: epic.epic.id,
-  include_examples: true,
-});
-```
-
-## Learning Capabilities
-
-The plugin learns from swarm outcomes to improve future decompositions.
-
-### Confidence Decay
-
-Evaluation criteria weights decay over time unless revalidated. If a criterion (e.g., `type_safe`) has been historically unreliable, its weight decreases.
-
-```typescript
-import {
-  calculateDecayedValue,
-  calculateCriterionWeight,
-} from "opencode-swarm-plugin";
-
-// Value decays by 50% every 90 days (configurable half-life)
-const weight = calculateDecayedValue(timestamp, now, halfLifeDays);
-
-// Calculate criterion weight from feedback history
-const criterionWeight = calculateCriterionWeight(feedbackEvents);
-// { criterion: "type_safe", weight: 0.85, helpful_count: 10, harmful_count: 2 }
-```
-
-### Implicit Feedback Scoring
-
-The `swarm_record_outcome` tool tracks task outcomes and infers feedback:
-
-- **Fast completion + success** → helpful signal
-- **Slow completion + errors + retries** → harmful signal
-
-```typescript
-// Record outcome after completing a subtask
-await tools["swarm_record_outcome"]({
-  bead_id: "bd-abc123.1",
-  duration_ms: 60000,
-  error_count: 0,
-  retry_count: 0,
-  success: true,
-  files_touched: ["src/auth.ts"],
-});
-// Returns feedback events for each criterion
-```
-
-### Anti-Pattern Learning
-
-Failed decomposition patterns are automatically inverted to anti-patterns:
+**Keywords**: fix, bug, security, critical, urgent
 
-```typescript
-import {
-  recordPatternObservation,
-  formatAntiPatternsForPrompt,
-} from "opencode-swarm-plugin";
+## Learning
 
-// Record pattern failure
-const result = recordPatternObservation(pattern, false, beadId);
-if (result.inversion) {
-  // Pattern was inverted: "Split by file type" → "AVOID: Split by file type. Failed 4/5 times (80% failure rate)"
-}
-
-// Include anti-patterns in decomposition prompts
-const antiPatternContext = formatAntiPatternsForPrompt(patterns);
-```
-
-### Pattern Maturity
-
-Patterns progress through maturity states: `candidate` → `established` → `proven` (or `deprecated`).
-
-```typescript
-import {
-  calculateMaturityState,
-  getMaturityMultiplier,
-} from "opencode-swarm-plugin";
-
-// Calculate state from feedback
-const state = calculateMaturityState(feedbackEvents);
-// "candidate" | "established" | "proven" | "deprecated"
-
-// Get weight multiplier for pattern ranking
-const multiplier = getMaturityMultiplier("proven"); // 1.5
-```
+The plugin learns from outcomes:
 
-### UBS Pre-Completion Scan
-
-The `swarm_complete` tool runs UBS (Ultimate Bug Scanner) on modified files before marking complete:
-
-```typescript
-await tools["swarm_complete"]({
-  project_key: "/path/to/project",
-  agent_name: "BlueLake",
-  bead_id: "bd-abc123.1",
-  summary: "Implemented auth flow",
-  files_touched: ["src/auth.ts", "src/middleware.ts"],
-  // skip_ubs_scan: true  // Optional: bypass scan
-});
-// Blocks completion if critical bugs found
-```
-
-### CASS History Context
-
-The `swarm_decompose` tool queries CASS (Cross-Agent Session Search) for similar past tasks:
-
-```typescript
-await tools["swarm_decompose"]({
-  task: "Add user authentication with OAuth",
-  max_subtasks: 5,
-  query_cass: true, // Default: true
-  cass_limit: 3, // Max results to include
-});
-// Includes successful patterns from past decompositions in context
-```
+| Mechanism | How It Works |
+|-----------|--------------|
+| Confidence decay | Criteria weights fade unless revalidated (90-day half-life) |
+| Implicit feedback | Fast + success = helpful signal, slow + errors = harmful |
+| Pattern maturity | candidate → established → proven (or deprecated) |
+| Anti-patterns | Patterns with >60% failure rate auto-invert |
 
 ## Context Preservation
 
-**CRITICAL**: This plugin enforces context-safe defaults to prevent session exhaustion.
-
-### Why These Constraints Exist
+Hard limits to prevent context exhaustion:
 
-| Constraint           | Default                      | Reason                                             |
-| -------------------- | ---------------------------- | -------------------------------------------------- |
-| Inbox limit          | 5 messages                   | Fetching 20+ messages with bodies exhausts context |
-| Bodies excluded      | `include_bodies: false`      | Message bodies can be huge; fetch individually     |
-| Summarize over fetch | `summarize_thread` preferred | Get key points, not raw message dump               |
+| Constraint | Default | Reason |
+|------------|---------|--------|
+| Inbox limit | 5 messages | Prevents token burn |
+| Bodies excluded | Always | Fetch individually when needed |
+| Summarize preferred | Yes | Key points, not raw dump |
 
-### The Pattern
-
-```typescript
-// WRONG: This can dump thousands of tokens into context
-const messages = await tools["agentmail_inbox"]({
-  limit: 20,
-  include_bodies: true, // Plugin prevents this
-});
-
-// RIGHT: Headers only, then fetch specific messages
-const headers = await tools["agentmail_inbox"]({ limit: 5 });
-const importantMessage = await tools["agentmail_read_message"]({
-  message_id: headers[0].id,
-});
-
-// BEST: Summarize threads instead of fetching all messages
-const summary = await tools["agentmail_summarize_thread"]({
-  thread_id: "bd-abc123",
-});
-```
-
-### Hard Caps
-
-The plugin enforces these limits regardless of input:
-
-- `agentmail_inbox` - Max 5 messages, bodies always excluded
-- Thread summaries use LLM mode for concise output
-- File reservations auto-track for cleanup
-
-## Custom Commands
-
-This plugin provides tools that work with OpenCode's [custom commands](https://opencode.ai/docs/commands). Create a `/swarm` command to orchestrate multi-agent work.
-
-### Setup /swarm Command
-
-Copy the example command to your OpenCode config:
-
-```bash
-cp examples/commands/swarm.md ~/.config/opencode/command/
-```
-
-### Usage
-
-```
-/swarm "Add user authentication with OAuth providers"
-```
-
-### How It Works
-
-1. **Decompose** - `swarm_decompose` breaks task into subtasks with file assignments
-2. **Create beads** - `beads_create_epic` creates epic + subtasks atomically
-3. **Spawn agents** - `swarm_spawn_subtask` generates prompts WITH Agent Mail/beads instructions
-4. **Parallel work** - Subagents use Agent Mail to communicate, beads to track progress
-5. **Coordination** - Agents report progress, ask questions, announce blockers via Agent Mail
-6. **Completion** - Agents use `swarm_complete` when done
-7. **Cleanup** - `beads_sync` pushes to git
-
-### Subagent Capabilities
-
-Spawned subagents have **full access** to all plugin tools:
-
-- **Agent Mail** - `agentmail_send`, `agentmail_inbox`, `agentmail_reserve`, etc.
-- **Beads** - `beads_update`, `beads_create`, `swarm_complete`
-- All standard OpenCode tools
-
-The prompts tell agents to actively communicate and coordinate.
-
-## Error Handling
+## Rate Limiting
 
-The plugin provides typed errors for robust error handling:
+Client-side limits (Redis primary, SQLite fallback):
 
-```typescript
-import {
-  BeadError,
-  BeadValidationError,
-  AgentMailError,
-  AgentMailNotInitializedError,
-  FileReservationConflictError,
-} from "opencode-swarm-plugin";
+| Endpoint | Per Minute | Per Hour |
+|----------|------------|----------|
+| send | 20 | 200 |
+| reserve | 10 | 100 |
+| inbox | 60 | 600 |
 
-try {
-  await tools["agentmail_reserve"]({ paths: ["src/index.ts"] });
-} catch (error) {
-  if (error instanceof FileReservationConflictError) {
-    console.log("Conflicts:", error.conflicts);
-    // [{ path: "src/index.ts", holders: ["RedStone"] }]
-  }
-}
-```
+Configure via `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_MIN` env vars.
 
 ## Development
 
 ```bash
-# Install dependencies
 bun install
-
-# Type check
 bun run typecheck
-
-# Run tests
 bun test
-
-# Build for distribution
 bun run build
-
-# Clean build artifacts
-bun run clean
-```
+````
 
 ## License