opencode-swarm-plugin 0.20.0 → 0.22.0

package/README.md

@@ -1,7 +1,6 @@
 # opencode-swarm-plugin
 
 [![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)
 
 ```
  ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
@@ -13,636 +12,467 @@
 
     \ ` - ' /
    - .(o o). -
-    (  >.<  )        Multi-agent coordination for OpenCode
-     /|   |\         Break complex tasks into parallel subtasks,
-    (_|   |_)        spawn agents, coordinate via messaging.
-      bzzzz...       The plugin learns from outcomes.
-```
-
-## Install
-
-```bash
-npm install -g opencode-swarm-plugin@latest
-swarm setup
-```
-
-The setup wizard handles everything:
-
-```
-┌  opencode-swarm-plugin v0.16.0
-│
-◇  Checking dependencies...
-│
-◆  OpenCode
-◆  Beads
-▲  CASS (optional)
-▲  UBS (optional)
-▲  semantic-memory (optional)
-│
-◇  Setting up OpenCode integration...
-│
-◆  Plugin: ~/.config/opencode/plugin/swarm.ts
-◆  Command: ~/.config/opencode/command/swarm.md
-◆  Agent: ~/.config/opencode/agent/swarm-planner.md
-│
-└  Setup complete!
-```
-
-Then in your project:
-
-```bash
-cd your-project
-swarm init
-```
-
-## Migrating from MCP Agent Mail
-
-If you were using the MCP-based Agent Mail (pre-v0.15), here's how to migrate:
-
-### What Changed
+    (  >.<  )        Break big tasks into small ones.
+     /|   |\         Spawn agents to work in parallel.
+    (_|   |_)        Learn from what works.
+      bzzzz...
+```
+
+## The Problem
+
+You're working with an AI coding agent. You ask it to "add OAuth authentication." It starts writing code. Five minutes later, you realize it's going down the wrong path. Or it's touching files it shouldn't. Or it's making changes that conflict with what you just did in another session.
+
+**The fundamental issue:** AI agents are single-threaded, context-limited, and have no memory of what worked before.
+
+## The Solution
+
+What if the agent could:
+
+- **Break the task into pieces** that can be worked on simultaneously
+- **Spawn parallel workers** that don't step on each other
+- **Remember what worked** and avoid patterns that failed
+- **Survive context compaction** without losing progress
+
+That's what Swarm does.
+
+## How It Works
+
+```
+                            "Add OAuth"
+                                 │
+                                 ▼
+                    ┌────────────────────────┐
+                    │      COORDINATOR       │
+                    │                        │
+                    │  1. Query CASS:        │
+                    │     "How did we solve  │
+                    │      this before?"     │
+                    │                        │
+                    │  2. Pick strategy:     │
+                    │     file-based?        │
+                    │     feature-based?     │
+                    │     risk-based?        │
+                    │                        │
+                    │  3. Break into pieces  │
+                    └────────────────────────┘
+                                 │
+           ┌─────────────────────┼─────────────────────┐
+           ▼                     ▼                     ▼
+    ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+    │  Worker A   │       │  Worker B   │       │  Worker C   │
+    │             │       │             │       │             │
+    │ auth/oauth  │       │ auth/session│       │ auth/tests  │
+    │   🔒 files  │       │   🔒 files  │       │   🔒 files  │
+    │             │       │             │       │             │
+    │ "I need     │──────►│ "Got it,    │       │ "Running    │
+    │  session    │       │  here's the │       │  tests..."  │
+    │  types"     │       │  interface" │       │             │
+    └─────────────┘       └─────────────┘       └─────────────┘
+           │                     │                     │
+           │                     │                     │
+           └─────────────────────┼─────────────────────┘
+                                 │
+                                 ▼
+                    ┌────────────────────────┐
+                    │    LEARNING SYSTEM     │
+                    │                        │
+                    │  "File-based split     │
+                    │   worked well for      │
+                    │   auth - 3 workers,    │
+                    │   15 min, 0 conflicts" │
+                    │                        │
+                    │  Next time: use this   │
+                    │  pattern again         │
+                    └────────────────────────┘
+```
+
+### The Flow
+
+1. **You give it a task**: `/swarm "Add OAuth authentication"`
+
+2. **It queries history**: "Have we done something like this before?" (via CASS - cross-agent session search)
+
+3. **It picks a strategy**:
+   - **File-based**: "Split by directory structure" (good for refactoring)
+   - **Feature-based**: "Split by vertical slices" (good for new features)
+   - **Risk-based**: "Tests first, then implementation" (good for bug fixes)
+   - **Research-based**: "Explore before committing" (good for unknowns)
+
+4. **It breaks the work into beads** (git-backed issues):
 
-- **Before:** Agent Mail required a separate MCP server running Go-based agent-mail
-- **After:** Agent Mail is now embedded using PGLite (no external dependencies)
-
-### Migration Steps
-
-1. **Update the plugin:**
-
-   ```bash
-   npm install -g opencode-swarm-plugin@latest
+   ```
+   Epic: Add OAuth
+   ├─ Bead 1: OAuth provider integration (src/auth/oauth.ts)
+   ├─ Bead 2: Session management (src/auth/session.ts)
+   └─ Bead 3: Integration tests (tests/auth/)
    ```
 
-2. **Remove MCP configuration** (if present):
-   - Delete any `agent-mail` MCP server configuration from your OpenCode config
-   - The embedded version starts automatically
-
-3. **Data Migration:**
-   - Previous MCP data is NOT automatically migrated
-   - For most users, starting fresh is recommended (swarm state is ephemeral)
-   - If you need historical data, export from MCP before upgrading
-
-### Breaking Changes
+5. **It spawns parallel workers**:
+   - Each worker reserves its files (no conflicts)
+   - Workers coordinate via Swarm Mail (actor-model messaging)
+   - Progress is checkpointed at 25%, 50%, 75%
 
-- `agentmail_*` tools now use embedded PGLite instead of MCP
-- No external server required
-- Slightly different error messages (more actionable)
+6. **It learns from the outcome**:
+   - Fast + success = good signal
+   - Slow + errors = bad signal
+   - Patterns that fail >60% of the time get auto-inverted
 
-### Rollback
+## What Makes It Different
 
-If you need to rollback:
+### It Survives Context Death
 
-```bash
-npm install -g opencode-swarm-plugin@0.14.x
-```
-
-And restore your MCP configuration.
-
-## CLI
+OpenCode compacts context when it gets too long. Swarms used to die when this happened. Not anymore.
 
 ```
-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
+     Session 1                    Context                   Session 2
+         │                       Compacts                       │
+         ▼                          💥                          ▼
+┌─────────────────┐                                   ┌─────────────────┐
+│ swarm running   │                                   │ swarm_recover() │
+│ ├─ 25% ✓ saved  │                                   │       │         │
+│ ├─ 50% ✓ saved  │ ─────────────────────────────────►│       ▼         │
+│ └─ 75% ✓ saved  │      checkpoints survive          │ resume at 75%   │
+└─────────────────┘                                   └─────────────────┘
 ```
 
-## Usage
+**Checkpoints capture:**
 
-In OpenCode:
+- Which subtasks are done/in-progress/pending
+- File reservations (who owns what)
+- Shared context for workers
+- Progress percentage
 
-```
-/swarm "Add user authentication with OAuth"
-```
+**Recovery restores:**
 
-Or invoke the planner directly:
+- Swarm state from last checkpoint
+- File locks (prevents conflicts)
+- Worker context (what they were doing)
 
-```
-@swarm-planner "Refactor all components to use hooks"
-```
+All stored in PGLite (embedded Postgres) - no external servers, survives across sessions.
 
-## Customization
+### It Learns From Outcomes
 
-Run `swarm config` to see your config file paths:
+Every swarm completion records:
 
-```
-🔌 Plugin loader
-   ~/.config/opencode/plugin/swarm.ts
+- Duration (how long did it take?)
+- Errors (how many retries?)
+- Files touched (did scope match prediction?)
+- Success (did tests pass? were changes accepted?)
 
-📜 /swarm command prompt
-   ~/.config/opencode/command/swarm.md
+This feeds back into the decomposition strategy:
 
-🤖 @swarm-planner agent
-   ~/.config/opencode/agent/swarm-planner.md
 ```
+                    ┌─────────────────────────────────┐
+                    │         LEARNING LOOP           │
+                    └─────────────────────────────────┘
+                                    │
+        ┌───────────────────────────┼───────────────────────────┐
+        ▼                           ▼                           ▼
+┌───────────────┐           ┌───────────────┐           ┌───────────────┐
+│   OUTCOMES    │           │   PATTERNS    │           │ ANTI-PATTERNS │
+│               │           │               │           │               │
+│ fast+success  │           │  candidate    │           │ >60% failure  │
+│ = good signal │──────────►│      ↓        │──────────►│ = auto-invert │
+│               │           │  established  │           │               │
+│ slow+errors   │           │      ↓        │           │ "split by X"  │
+│ = bad signal  │           │    proven     │           │ becomes       │
+│               │           │               │           │ "DON'T split  │
+└───────────────┘           └───────────────┘           │  by X"        │
+                                                        └───────────────┘
 
-### /swarm Command
-
-The `/swarm` command is defined in `~/.config/opencode/command/swarm.md`:
-
-```markdown
----
-description: Decompose task into parallel subtasks and coordinate agents
----
+                    Confidence decays over 90 days
+                    unless patterns are revalidated
+```
 
-You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
+**Pattern maturity lifecycle:**
 
-## Task
+- `candidate` → new pattern, low confidence
+- `established` → validated 3+ times
+- `proven` → 10+ successes (gets 1.5x weight in future decompositions)
+- `deprecated` → >60% failure rate (auto-inverted to anti-pattern)
 
-$ARGUMENTS
+**Confidence decay:** Patterns fade over 90 days unless revalidated. Prevents stale knowledge from dominating.
 
-## Workflow
+### Swarm Mail: Actor-Model Coordination
 
-1. **Initialize**: `swarmmail_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**: `swarmmail_reserve` for each subtask's files
-5. **Spawn agents**: Use Task tool with `swarm_spawn_subtask` prompts
-6. **Monitor**: Check `swarmmail_inbox` for progress
-7. **Complete**: `swarm_complete` when done, then `beads_sync` to push
+Workers don't just run in parallel - they coordinate via **Swarm Mail**, an event-sourced actor model built on local-first primitives.
 
-## Strategy Selection
+**What makes Swarm Mail different from traditional agent messaging:**
 
-| 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  |
+- **Actor model over durable streams** - DurableMailbox, DurableLock, DurableDeferred (inspired by Electric SQL patterns)
+- **Local-first with PGlite** - embedded Postgres, no external servers, survives across sessions
+- **Event-sourced coordination** - append-only log, materialized views, full audit trail
+- **Context-safe by design** - hard caps on inbox (max 5 messages), thread summarization, body-on-demand
 
-Begin decomposition now.
 ```
-
-> **Note**: The `$ARGUMENTS` placeholder captures everything you type after `/swarm`. This is how your task description gets passed to the agent.
-
-### Agents
-
-The setup wizard creates two agents with your chosen models:
-
-**@swarm-planner** (`~/.config/opencode/agent/swarm-planner.md`) - Coordinator that decomposes tasks:
-
-```yaml
----
-name: swarm-planner
-description: Strategic task decomposition for swarm coordination
-model: anthropic/claude-sonnet-4-5 # Your chosen coordinator model
----
+┌──────────────────────────────────────────────────────────────┐
+│                      SWARM MAIL                              │
+│                                                              │
+│  Worker A: "I need the SessionUser type"                    │
+│            ↓                                                 │
+│  Worker B: "Here's the interface:"                          │
+│            interface SessionUser {                           │
+│              id: string                                      │
+│              email: string                                   │
+│              roles: string[]                                 │
+│            }                                                 │
+│            ↓                                                 │
+│  Worker A: "Got it, implementing OAuth flow now"            │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-**@swarm-worker** (`~/.config/opencode/agent/swarm-worker.md`) - Fast executor for subtasks:
+**File reservations** prevent conflicts:
 
-```yaml
----
-name: swarm-worker
-description: Executes subtasks in a swarm - fast, focused, cost-effective
-model: anthropic/claude-haiku-4-5 # Your chosen worker model
----
-```
-
-### Decomposition Rules
-
-- **2-7 subtasks** - Too few = not parallel, too many = coordination overhead
-- **No file overlap** - Each file appears in exactly one subtask
-- **Include tests** - Put test files with the code they test
-- **Order by dependency** - If B needs A's output, A comes first (lower index)
-
-Edit these files to customize behavior. Run `swarm setup` to regenerate defaults.
+- Worker A reserves `src/auth/oauth.ts` (exclusive via DurableLock)
+- Worker B tries to reserve it → blocked
+- Worker B waits or works on something else
 
-## Skills
+**Inbox limits** prevent context bloat:
 
-Skills are reusable knowledge packages that agents can load on-demand. They contain domain expertise, workflows, and patterns that help agents perform specialized tasks.
-
-### Using Skills
-
-```bash
-# List available skills
-swarm tool skills_list
+- Max 5 messages per fetch (headers only)
+- Read individual message bodies on demand
+- Thread summarization for long conversations
 
-# Read a skill's content
-swarm tool skills_read --json '{"name": "debugging"}'
+All coordination state survives context compaction and session restarts.
 
-# Use a skill (get formatted for context injection)
-swarm tool skills_use --json '{"name": "code-review", "context": "reviewing a PR"}'
-```
+#### Architecture: 3-Tier Stack
 
-In OpenCode, agents can use skills directly:
+Swarm Mail is built on **Durable Streams primitives** (inspired by Kyle Matthews' [Electric SQL patterns](https://x.com/kylemathews/status/1999896667030700098)):
 
 ```
-skills_list()                           # See what's available
-skills_use(name="debugging")            # Load debugging patterns
-skills_use(name="swarm-coordination")   # Load swarm workflow
+┌─────────────────────────────────────────────────────────────┐
+│                     SWARM MAIL STACK                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  TIER 3: COORDINATION                                       │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  ask<Req, Res>() - Request/Response (RPC-style)       │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                          │                                  │
+│  TIER 2: PATTERNS        ▼                                  │
+│  ┌─────────────────┐  ┌─────────────────┐                  │
+│  │ DurableMailbox  │  │  DurableLock    │                  │
+│  │ Actor Inbox     │  │  File Mutex     │                  │
+│  └─────────────────┘  └─────────────────┘                  │
+│          │                    │                             │
+│  TIER 1: PRIMITIVES           ▼                             │
+│  ┌─────────────────┐  ┌─────────────────┐                  │
+│  │ DurableCursor   │  │ DurableDeferred │                  │
+│  │ Checkpointed    │  │ Distributed     │                  │
+│  │ Reader          │  │ Promise         │                  │
+│  └─────────────────┘  └─────────────────┘                  │
+│                          │                                  │
+│  STORAGE                 ▼                                  │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │      PGLite (Embedded Postgres) + Migrations          │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-### Bundled Skills
-
-| 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   | Complete swarm playbook - strategies, coordinator patterns, failure recovery         |
-| `system-design`      | design, architecture | Building reusable systems - deep modules, complexity management, design red flags    |
-
-### Skill Locations
-
-Skills are loaded from three locations (in order):
+**Tier 1 - Primitives:**
 
-1. **Project skills**: `.opencode/skills/`, `.claude/skills/`, or `skills/`
-2. **Global skills**: `~/.config/opencode/skills/`
-3. **Bundled skills**: Included with the plugin
+- **DurableCursor** - Positioned event stream consumption with checkpointing (exactly-once)
+- **DurableDeferred** - URL-addressable distributed promises for async coordination
+- **DurableLock** - CAS-based mutual exclusion for file reservations (TTL + retry/backoff)
 
-### Creating Skills
+**Tier 2 - Patterns:**
 
-```bash
-# Initialize project skills directory
-swarm tool skills_init
-
-# Create a new skill
-swarm tool skills_create --json '{"name": "my-skill", "description": "What it does", "tags": ["tag1", "tag2"]}'
-```
+- **DurableMailbox** - Actor inbox with typed envelopes (sender, replyTo, payload)
+- File reservation protocol built on DurableLock
 
-Or use the `skill-creator` skill for guidance:
+**Tier 3 - Coordination:**
 
-```
-skills_use(name="skill-creator")
-```
+- **ask()** pattern - Synchronous-style RPC over async streams (creates DurableDeferred, appends to mailbox, returns promise)
 
-Each skill is a directory containing:
+#### Message Flow Example
 
 ```
-my-skill/
-  SKILL.md           # Main content (required)
-  references/        # Optional supporting files
-    patterns.md
-    examples.md
+Agent A                    Event Stream                Agent B
+   │                            │                         │
+   │  ask("get SessionUser")    │                         │
+   ├───────────────────────────>│                         │
+   │  (creates deferred)        │                         │
+   │                            │   consume event         │
+   │                            ├────────────────────────>│
+   │                            │                         │
+   │                            │   reply to deferred     │
+   │                            │<────────────────────────┤
+   │  await deferred.value      │                         │
+   │<───────────────────────────┤                         │
+   │                            │                         │
+   │  SessionUser interface     │                         │
+   │                            │                         │
 ```
 
-### SKILL.md Format
+**Why this matters:**
 
-```markdown
----
-name: my-skill
-description: Brief description for discovery
-tags:
-  - tag1
-  - tag2
----
+- No external servers (Redis, Kafka, NATS) - just PGlite
+- Full audit trail - every message is an event
+- Resumable - cursors checkpoint position, survive crashes
+- Type-safe - Effect-TS with full inference
 
-# My Skill
+> **Architecture deep-dive:** See [Swarm Mail Architecture](docs/swarm-mail-architecture.md) for complete implementation details, database schemas, and Effect-TS patterns.
 
-## When to Use
+### It Has Skills
 
-- Trigger condition 1
-- Trigger condition 2
+Skills are knowledge packages agents can load. Teach once, use everywhere.
 
-## Patterns
+```typescript
+skills_use((name = "testing-patterns")); // Load Feathers seams + Beck's 4 rules
+skills_use((name = "swarm-coordination")); // Load swarm workflow patterns
+```
 
-### Pattern Name
+**Bundled skills:**
 
-Description and examples...
+- `testing-patterns` - 25 dependency-breaking techniques, characterization tests
+- `swarm-coordination` - Multi-agent decomposition, file reservations
+- `cli-builder` - Argument parsing, help text, subcommands
+- `system-design` - Architecture decisions, module boundaries
+- `learning-systems` - Confidence decay, pattern maturity
 
-## Anti-Patterns
+**Create your own:**
 
-What NOT to do...
+```bash
+swarm init  # Creates .opencode/skills/ in project
 ```
 
-## Dependencies
-
-| Dependency                                                                                             | Purpose                                                      | Required |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
-| [OpenCode](https://opencode.ai)                                                                        | Plugin host                                                  | Yes      |
-| [Beads](https://github.com/steveyegge/beads)                                                           | Git-backed issue tracking                                    | Yes      |
-| [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions                        | No       |
-| [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner)                | Pre-completion bug scanning using AI-powered static analysis | No       |
-| [semantic-memory](https://github.com/joelhooks/semantic-memory)                                        | Learning persistence                                         | No       |
-| [Redis](https://redis.io)                                                                              | Rate limiting (SQLite fallback available)                    | No       |
+Skills can include:
 
-All dependencies are checked and can be installed via `swarm setup`.
+- Step-by-step workflows
+- Code examples
+- Reference documentation
+- Executable scripts
 
-### Installing Optional Dependencies
-
-**UBS (Ultimate Bug Scanner)** - Scans code for bugs before task completion:
+## Install
 
 ```bash
-curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh" | bash
+npm install -g opencode-swarm-plugin@latest
+swarm setup
 ```
 
-**CASS (Coding Agent Session Search)** - Indexes and searches AI coding agent history:
+## Usage
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode
+/swarm "Add user authentication with OAuth"
 ```
 
-> **Note:** Swarm Mail is now embedded (PGLite in-process) and works out of the box with no external dependencies. No Go or external servers required.
-
-## Tools Reference
-
-### 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 Swarm Mail/beads instructions           |
-| `swarm_status`                 | Get swarm progress by epic ID                                             |
-| `swarm_progress`               | Report subtask progress to coordinator                                    |
-| `swarm_complete`               | Complete subtask - runs UBS (Ultimate Bug Scanner), 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 Swarm Mail thread                 |
-
-### Swarm Mail (Embedded - Primary)
-
-| Tool                     | Description                                   |
-| ------------------------ | --------------------------------------------- |
-| `swarmmail_init`         | Initialize session, register agent            |
-| `swarmmail_send`         | Send message to agents                        |
-| `swarmmail_inbox`        | Fetch inbox (max 5, no bodies - context safe) |
-| `swarmmail_read_message` | Fetch single message body by ID               |
-| `swarmmail_reserve`      | Reserve file paths for exclusive editing      |
-| `swarmmail_release`      | Release file reservations                     |
-| `swarmmail_ack`          | Acknowledge message                           |
-| `swarmmail_health`       | Check embedded database health                |
-
-### Agent Mail (Deprecated - MCP-based)
-
-> **Note:** The MCP-based `agentmail_*` tools in `src/agent-mail.ts` are **deprecated** as of v0.14.0. They remain for backward compatibility but will be removed in v1.0.0.
->
-> **Use `swarmmail_*` tools instead** - embedded PGLite implementation with no external server required. See [Migrating from MCP Agent Mail](#migrating-from-mcp-agent-mail) for migration guide.
-
-## Event-Sourced Architecture (Embedded)
-
-> **🙏 Built on the shoulders of giants**
->
-> The Swarm Mail system is deeply inspired by and builds upon [**MCP Agent Mail**](https://github.com/Dicklesworthstone/mcp_agent_mail) by [@Dicklesworthstone](https://github.com/Dicklesworthstone). The original MCP Agent Mail pioneered multi-agent coordination patterns including file reservations, thread-based messaging, and agent registration - concepts that form the foundation of this embedded implementation.
->
-> If you need a production-ready, battle-tested solution with a full Go server, **use MCP Agent Mail directly**. This embedded version is an experimental alternative that trades the external server for in-process PGLite, optimized for single-machine development workflows.
->
-> **Key contributions from MCP Agent Mail:**
->
-> - File reservation protocol with conflict detection
-> - Agent registration and heartbeat patterns
-> - Thread-based message organization
-> - Importance levels and acknowledgment tracking
->
-> Thank you to the MCP Agent Mail team for open-sourcing such a well-designed system.
-
-> **🎯 Quality Patterns from Superpowers**
->
-> Several verification and debugging patterns in this plugin are inspired by [**Superpowers**](https://github.com/obra/superpowers) by [@obra](https://github.com/obra) (Jesse Vincent). Superpowers is a complete software development workflow for coding agents built on composable "skills".
->
-> **Key patterns adopted:**
->
-> - **Verification Gate** - The Gate Function (IDENTIFY → RUN → READ → VERIFY → CLAIM) ensures no completion claims without fresh verification evidence
-> - **3-Strike Architecture Rule** - After 3 failed fixes, question the architecture, not the bug
-> - **CSO (Claude Search Optimization)** - Skill descriptions that answer "Should I read this right now?"
-> - **Defense-in-Depth** - Validate at every layer data passes through
->
-> Thank you Jesse for open-sourcing such a thoughtfully designed system.
-
-The plugin includes an embedded event-sourced Swarm Mail implementation as an alternative to the external MCP server. This provides the same multi-agent coordination capabilities without requiring a separate server process.
-
-### Architecture Comparison
-
-**MCP-based (deprecated, external):**
-
-```
-plugin tools → HTTP → MCP Server (Go process) → SQLite
-```
+The coordinator will:
 
-**Event-sourced (embedded, current):**
+1. Query CASS for similar past tasks
+2. Select decomposition strategy
+3. Break into subtasks (beads)
+4. Spawn parallel workers
+5. Track progress with checkpoints
+6. Record outcome for learning
 
-```
-plugin tools → streams/agent-mail.ts → streams/store.ts → PGLite (in-process)
-                                             ↓
-                                    streams/projections.ts
-                                             ↓
-                              Materialized views (agents, messages, reservations)
-                                             ↓
-                                        Fast reads
-```
+## Architecture
 
-### Architecture Flow
+Everything runs in-process. No external servers.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│                        Plugin Tools Layer                        │
-│  (swarmmail_init, swarmmail_send, swarmmail_reserve, etc.)      │
-└──────────────────────────────┬──────────────────────────────────┘
-                               │
-                               ▼
+│                         YOUR TASK                               │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│                     streams/agent-mail.ts                        │
-│                    (High-level API wrapper)                      │
-└──────────────────────────────┬──────────────────────────────────┘
-                               │
-                               ▼
+│  DECOMPOSITION         strategy selection, subtask creation     │
+│                        (queries CASS, semantic memory)          │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│                       streams/events.ts                          │
-│        11 event types: agent_registered, message_sent,          │
-│     file_reserved, message_read, message_acked, etc.            │
-└──────────────────────────────┬──────────────────────────────────┘
-                               │
-                               ▼
+│  BEADS                 git-backed issues for each subtask       │
+│                        (atomic epic + subtasks creation)        │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│                        streams/store.ts                          │
-│              Append-only event log (PGLite storage)             │
-│       appendEvent() • readEvents() • replayEvents()             │
-└──────────────────────────────┬──────────────────────────────────┘
-                               │
-                               ▼
+│  SWARM MAIL            actor-model coordination (local-first)   │
+│                        (DurableMailbox, DurableLock, PGlite)    │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│                     streams/projections.ts                       │
-│                  Build materialized views from events            │
-│    getAgents() • getInbox() • getActiveReservations()           │
-│              checkConflicts() • threadStats()                    │
-└─────────────────────────────┬────────────────────────────────────┘
-                              │
-                              ▼
+│  PGLITE                embedded postgres, event-sourced state   │
+│                        (append-only log, materialized views)    │
+└─────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│              Materialized Tables (Derived State)                │
-│     agents • messages • reservations • message_reads            │
-│              (Rebuilt by replaying event log)                   │
+│  LEARNING              outcomes feed back into decomposition    │
+│                        (confidence decay, pattern maturity)     │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-### Module Descriptions
-
-| Module                     | Responsibility                                                                                     |
-| -------------------------- | -------------------------------------------------------------------------------------------------- |
-| **streams/events.ts**      | Zod schemas for 11 event types (agent_registered, message_sent, file_reserved, task_progress, etc) |
-| **streams/store.ts**       | Append-only event log with PGLite backend (appendEvent, readEvents, replayEvents)                  |
-| **streams/projections.ts** | Materialize views from events (getAgents, getInbox, checkConflicts, threadStats)                   |
-| **streams/agent-mail.ts**  | High-level API matching MCP interface (initAgent, sendAgentMessage, reserveAgentFiles)             |
-| **streams/debug.ts**       | Debugging utilities (debugEvents, debugAgent, debugMessage, inspectState)                          |
-
-### Key Benefits
-
-- **No external dependencies** - Runs in-process with PGLite (Postgres compiled to WASM)
-- **Full audit trail** - Every state change is an immutable event
-- **Crash recovery** - Rebuild state by replaying events from log
-- **Time-travel debugging** - Replay events up to any point in time
-- **Testability** - 127 tests passing across streams module
-- **Durable Streams protocol** - Inspired by Electric SQL's event sourcing patterns
-
-### Event Types
-
-The system emits 11 event types tracked in `streams/events.ts`:
-
-| Event              | Triggered By                          |
-| ------------------ | ------------------------------------- |
-| `agent_registered` | Agent initialization                  |
-| `message_sent`     | Sending inter-agent message           |
-| `file_reserved`    | Reserving files for exclusive editing |
-| `file_released`    | Releasing file reservations           |
-| `message_read`     | Reading a message                     |
-| `message_acked`    | Acknowledging a message               |
-| `task_started`     | Starting work on a bead               |
-| `task_progress`    | Reporting progress update             |
-| `task_completed`   | Completing a bead                     |
-| `task_blocked`     | Marking a task as blocked             |
-| `agent_active`     | Agent heartbeat/keep-alive            |
-
-### Materialized Views
-
-Projections build these derived tables from the event log:
+### Event Sourcing
 
-| View            | Contains                                               |
-| --------------- | ------------------------------------------------------ |
-| `agents`        | Registered agents with metadata and last activity      |
-| `messages`      | All inter-agent messages with thread/importance        |
-| `reservations`  | Active file reservations with TTL and exclusivity flag |
-| `message_reads` | Read receipts for message tracking                     |
+All state is stored as an append-only event log:
 
-State is always derived - delete the tables and replay events to rebuild.
-
-### 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
-
-### File-Based
-
-Best for: refactoring, migrations, pattern changes
-
-- Group files by directory or type
-- Handle shared types/utilities first
-- Minimize cross-directory dependencies
-
-**Keywords**: refactor, migrate, rename, update all, replace
-
-### Feature-Based
-
-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
-
-**Keywords**: add, implement, build, create, feature
-
-### Risk-Based
-
-Best for: bug fixes, security issues
-
-- Write tests FIRST
-- Isolate risky changes
-- Audit similar code for same issue
-
-**Keywords**: fix, bug, security, critical, urgent
-
-## Learning
+```
+Event Log (PGLite)
+├─ agent_registered      → Agent joins swarm
+├─ message_sent          → Agent-to-agent communication
+├─ file_reserved         → Exclusive file lock acquired
+├─ file_released         → Lock released
+├─ swarm_checkpointed    → Progress snapshot saved
+├─ decomposition_generated → Task broken into subtasks
+└─ subtask_outcome       → Worker completion result
 
-The plugin learns from outcomes:
+Materialized Views (derived from events)
+├─ agents                → Active agents per project
+├─ messages              → Agent inbox/outbox
+├─ file_reservations     → Current file locks
+└─ eval_records          → Outcome data for learning
+```
 
-| 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                 |
+**Why event sourcing?**
 
-## Context Preservation
+- **Audit trail** - full history of what happened
+- **Replay** - reconstruct state from events
+- **Debugging** - see exactly what went wrong
+- **Learning** - analyze outcomes over time
 
-Hard limits to prevent context exhaustion:
+See the [Swarm Mail Architecture](docs/swarm-mail-architecture.md) section above for details on the durable primitives (DurableCursor, DurableDeferred, DurableLock, DurableMailbox) and how they enable exactly-once processing, request/response patterns, and actor coordination.
 
-| 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       |
+## Dependencies
 
-## Rate Limiting
+| Required                                     | Optional                                                                                      |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [OpenCode](https://opencode.ai)              | [CASS](https://github.com/Dicklesworthstone/coding_agent_session_search) - historical context |
+| [Beads](https://github.com/steveyegge/beads) | [UBS](https://github.com/Dicklesworthstone/ultimate_bug_scanner) - bug scanning               |
+|                                              | [semantic-memory](https://github.com/joelhooks/semantic-memory) - learning persistence        |
 
-Client-side limits (Redis primary, SQLite fallback):
+Run `swarm doctor` to check status.
 
-| Endpoint | Per Minute | Per Hour |
-| -------- | ---------- | -------- |
-| send     | 20         | 200      |
-| reserve  | 10         | 100      |
-| inbox    | 60         | 600      |
+## CLI
 
-Configure via `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_MIN` env vars.
+```bash
+swarm setup     # Install and configure
+swarm doctor    # Check dependencies
+swarm init      # Initialize beads in project
+swarm config    # Show config file paths
+```
 
 ## Development
 
 ```bash
 bun install
-bun run typecheck
-bun test
+bun test                # Unit tests (230 tests)
+bun run test:integration # Integration tests
 bun run build
 ```
 
-## Troubleshooting
-
-### 1. First Step: Run Doctor
-
-```bash
-swarm doctor
-```
-
-This checks all dependencies and shows their installation status.
-
-### 2. Common Issues
-
-| Issue                       | Cause                              | Solution                                          |
-| --------------------------- | ---------------------------------- | ------------------------------------------------- |
-| `beads: command not found`  | Beads CLI not installed            | `npm install -g @joelhooks/beads`                 |
-| `bd: command not found`     | Same as above                      | `npm install -g @joelhooks/beads`                 |
-| Verification Gate fails     | TypeScript errors or test failures | Fix errors shown, or use `skip_verification=true` |
-| File reservation conflict   | Another agent has the file         | Wait for release, or check `swarmmail_inbox`      |
-| `Mandate not found`         | ID doesn't exist                   | Use `mandate_list` to see available mandates      |
-| Swarm Mail connection error | Database not initialized           | Run `swarm setup` again                           |
-| `Agent not registered`      | Session not initialized            | Call `swarmmail_init` first                       |
+## Credits
 
-### 3. Getting Help
+**Inspiration & Core Ideas:**
 
-- Run `swarm doctor` for dependency status
-- Check `swarmmail_health` for database status
-- File issues at: https://github.com/joelhooks/opencode-swarm-plugin/issues
+- [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) - **THE INSPIRATION** for multi-agent coordination. Swarm Mail is our implementation built on actor-model primitives (DurableMailbox, DurableLock) with local-first PGlite and event sourcing.
+- [Superpowers](https://github.com/obra/superpowers) - verification patterns, Socratic planning, skill architecture
+- [Electric SQL](https://electric-sql.com) - durable streams and event sourcing patterns that power Swarm Mail
+- [Evalite](https://evalite.dev) - outcome-based evaluation framework for learning systems
 
 ## License