opencode-swarm-plugin 0.22.0 → 0.23.0

package/.turbo/turbo-build.log

@@ -0,0 +1,9 @@
+$ bun build ./src/index.ts --outdir ./dist --target node --external @electric-sql/pglite --external swarm-mail && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node --external @electric-sql/pglite --external swarm-mail && tsc
+Bundled 195 modules in 33ms
+
+  index.js  1.14 MB  (entry point)
+
+Bundled 196 modules in 32ms
+
+  plugin.js  1.12 MB  (entry point)
+

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# opencode-swarm-plugin
+
+## 0.23.0
+
+### Minor Changes
+
+- [`b66d77e`](https://github.com/joelhooks/opencode-swarm-plugin/commit/b66d77e484e9b7021b3264d1a7e8f54a16ea5204) Thanks [@joelhooks](https://github.com/joelhooks)! - Add changesets workflow and semantic memory test isolation
+
+  - OIDC publish workflow with GitHub Actions
+  - Changesets for independent package versioning
+  - TEST_SEMANTIC_MEMORY_COLLECTION env var for test isolation
+  - Prevents test pollution of production semantic-memory

package/README.md

@@ -1,6 +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)
+OpenCode plugin for multi-agent swarm coordination with learning capabilities.
 
 ```
  ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
@@ -9,341 +9,16 @@
  ╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
  ███████║╚███╔███╔╝██║  ██║██║  ██║██║ ╚═╝ ██║
  ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝
-
-    \ ` - ' /
-   - .(o o). -
-    (  >.<  )        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):
-
-   ```
-   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/)
-   ```
-
-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%
-
-6. **It learns from the outcome**:
-   - Fast + success = good signal
-   - Slow + errors = bad signal
-   - Patterns that fail >60% of the time get auto-inverted
-
-## What Makes It Different
-
-### It Survives Context Death
-
-OpenCode compacts context when it gets too long. Swarms used to die when this happened. Not anymore.
-
-```
-     Session 1                    Context                   Session 2
-         │                       Compacts                       │
-         ▼                          💥                          ▼
-┌─────────────────┐                                   ┌─────────────────┐
-│ swarm running   │                                   │ swarm_recover() │
-│ ├─ 25% ✓ saved  │                                   │       │         │
-│ ├─ 50% ✓ saved  │ ─────────────────────────────────►│       ▼         │
-│ └─ 75% ✓ saved  │      checkpoints survive          │ resume at 75%   │
-└─────────────────┘                                   └─────────────────┘
-```
-
-**Checkpoints capture:**
-
-- Which subtasks are done/in-progress/pending
-- File reservations (who owns what)
-- Shared context for workers
-- Progress percentage
-
-**Recovery restores:**
-
-- Swarm state from last checkpoint
-- File locks (prevents conflicts)
-- Worker context (what they were doing)
-
-All stored in PGLite (embedded Postgres) - no external servers, survives across sessions.
-
-### It Learns From Outcomes
-
-Every swarm completion records:
-
-- Duration (how long did it take?)
-- Errors (how many retries?)
-- Files touched (did scope match prediction?)
-- Success (did tests pass? were changes accepted?)
-
-This feeds back into the decomposition strategy:
-
-```
-                    ┌─────────────────────────────────┐
-                    │         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"        │
-                                                        └───────────────┘
-
-                    Confidence decays over 90 days
-                    unless patterns are revalidated
-```
-
-**Pattern maturity lifecycle:**
-
-- `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)
-
-**Confidence decay:** Patterns fade over 90 days unless revalidated. Prevents stale knowledge from dominating.
-
-### Swarm Mail: Actor-Model Coordination
-
-Workers don't just run in parallel - they coordinate via **Swarm Mail**, an event-sourced actor model built on local-first primitives.
-
-**What makes Swarm Mail different from traditional agent messaging:**
-
-- **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
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                      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"            │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
-```
-
-**File reservations** prevent conflicts:
-
-- 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
-
-**Inbox limits** prevent context bloat:
-
-- Max 5 messages per fetch (headers only)
-- Read individual message bodies on demand
-- Thread summarization for long conversations
-
-All coordination state survives context compaction and session restarts.
-
-#### Architecture: 3-Tier Stack
-
-Swarm Mail is built on **Durable Streams primitives** (inspired by Kyle Matthews' [Electric SQL patterns](https://x.com/kylemathews/status/1999896667030700098)):
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     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          │  │
-│  └───────────────────────────────────────────────────────┘  │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
 ```
 
-**Tier 1 - Primitives:**
-
-- **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)
+## Features
 
-**Tier 2 - Patterns:**
-
-- **DurableMailbox** - Actor inbox with typed envelopes (sender, replyTo, payload)
-- File reservation protocol built on DurableLock
-
-**Tier 3 - Coordination:**
-
-- **ask()** pattern - Synchronous-style RPC over async streams (creates DurableDeferred, appends to mailbox, returns promise)
-
-#### Message Flow Example
-
-```
-Agent A                    Event Stream                Agent B
-   │                            │                         │
-   │  ask("get SessionUser")    │                         │
-   ├───────────────────────────>│                         │
-   │  (creates deferred)        │                         │
-   │                            │   consume event         │
-   │                            ├────────────────────────>│
-   │                            │                         │
-   │                            │   reply to deferred     │
-   │                            │<────────────────────────┤
-   │  await deferred.value      │                         │
-   │<───────────────────────────┤                         │
-   │                            │                         │
-   │  SessionUser interface     │                         │
-   │                            │                         │
-```
-
-**Why this matters:**
-
-- 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
-
-> **Architecture deep-dive:** See [Swarm Mail Architecture](docs/swarm-mail-architecture.md) for complete implementation details, database schemas, and Effect-TS patterns.
-
-### It Has Skills
-
-Skills are knowledge packages agents can load. Teach once, use everywhere.
-
-```typescript
-skills_use((name = "testing-patterns")); // Load Feathers seams + Beck's 4 rules
-skills_use((name = "swarm-coordination")); // Load swarm workflow patterns
-```
-
-**Bundled skills:**
-
-- `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
-
-**Create your own:**
-
-```bash
-swarm init  # Creates .opencode/skills/ in project
-```
-
-Skills can include:
-
-- Step-by-step workflows
-- Code examples
-- Reference documentation
-- Executable scripts
+- **Swarm Coordination** - Break tasks into parallel subtasks, spawn worker agents
+- **Beads Integration** - Git-backed issue tracking with atomic epic creation
+- **Agent Mail** - Inter-agent messaging with file reservations
+- **Learning System** - Pattern maturity, anti-pattern detection, confidence decay
+- **Skills System** - Knowledge injection with bundled and custom skills
+- **Checkpointing** - Survive context compaction, resume from last checkpoint
 
 ## Install
 
@@ -358,94 +33,117 @@ swarm setup
 /swarm "Add user authentication with OAuth"
 ```
 
-The coordinator will:
-
-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
+## Tools Provided
+
+### Beads (Issue Tracking)
+
+| Tool                | Purpose                               |
+| ------------------- | ------------------------------------- |
+| `beads_create`      | Create bead with type-safe validation |
+| `beads_create_epic` | Atomic epic + subtasks creation       |
+| `beads_query`       | Query with filters                    |
+| `beads_update`      | Update status/description/priority    |
+| `beads_close`       | Close with reason                     |
+| `beads_start`       | Mark in-progress                      |
+| `beads_ready`       | Get next unblocked bead               |
+| `beads_sync`        | Sync to git                           |
+
+### Swarm Mail (Agent Coordination)
+
+| Tool                     | Purpose                          |
+| ------------------------ | -------------------------------- |
+| `swarmmail_init`         | Initialize session               |
+| `swarmmail_send`         | Send message to agents           |
+| `swarmmail_inbox`        | Fetch inbox (context-safe)       |
+| `swarmmail_read_message` | Fetch one message body           |
+| `swarmmail_reserve`      | Reserve files for exclusive edit |
+| `swarmmail_release`      | Release reservations             |
+
+### Swarm (Task Orchestration)
+
+| Tool                           | Purpose                                         |
+| ------------------------------ | ----------------------------------------------- |
+| `swarm_select_strategy`        | Analyze task, recommend strategy                |
+| `swarm_decompose`              | Generate decomposition prompt (queries CASS)    |
+| `swarm_delegate_planning`      | Delegate planning to planner subagent           |
+| `swarm_validate_decomposition` | Validate response, detect conflicts             |
+| `swarm_plan_prompt`            | Generate strategy-specific decomposition prompt |
+| `swarm_subtask_prompt`         | Generate worker agent prompt                    |
+| `swarm_spawn_subtask`          | Prepare subtask for Task tool spawning          |
+| `swarm_evaluation_prompt`      | Generate self-evaluation prompt                 |
+| `swarm_init`                   | Initialize swarm session                        |
+| `swarm_status`                 | Get swarm progress by epic ID                   |
+| `swarm_progress`               | Report subtask progress to coordinator          |
+| `swarm_complete`               | Complete subtask (runs UBS scan, releases)      |
+| `swarm_record_outcome`         | Record outcome for learning                     |
+| `swarm_checkpoint`             | Save progress snapshot                          |
+| `swarm_recover`                | Resume from checkpoint                          |
+| `swarm_learn`                  | Extract learnings from outcome                  |
+| `swarm_broadcast`              | Send message to all active agents               |
+| `swarm_accumulate_error`       | Track recurring errors (3-strike system)        |
+| `swarm_check_strikes`          | Check if error threshold reached                |
+| `swarm_get_error_context`      | Get context for error pattern                   |
+| `swarm_resolve_error`          | Mark error pattern as resolved                  |
+
+### Skills (Knowledge Injection)
+
+| Tool            | Purpose                 |
+| --------------- | ----------------------- |
+| `skills_list`   | List available skills   |
+| `skills_use`    | Load skill into context |
+| `skills_read`   | Read skill content      |
+| `skills_create` | Create new skill        |
+
+## Bundled Skills
+
+Located in `global-skills/`:
+
+- **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
+- **skill-creator** - Meta-skill for creating new skills
 
 ## Architecture
 
-Everything runs in-process. No external servers.
-
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                         YOUR TASK                               │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  DECOMPOSITION         strategy selection, subtask creation     │
-│                        (queries CASS, semantic memory)          │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  BEADS                 git-backed issues for each subtask       │
-│                        (atomic epic + subtasks creation)        │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  SWARM MAIL            actor-model coordination (local-first)   │
-│                        (DurableMailbox, DurableLock, PGlite)    │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  PGLITE                embedded postgres, event-sourced state   │
-│                        (append-only log, materialized views)    │
-└─────────────────────────────────────────────────────────────────┘
-                                │
-                                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  LEARNING              outcomes feed back into decomposition    │
-│                        (confidence decay, pattern maturity)     │
-└─────────────────────────────────────────────────────────────────┘
+src/
+├── beads.ts           # Beads integration
+├── agent-mail.ts      # Agent Mail tools (legacy MCP wrapper)
+├── swarm-mail.ts      # Swarm Mail tools (new, uses swarm-mail package)
+├── swarm.ts           # Swarm orchestration tools
+├── swarm-orchestrate.ts # Coordinator logic
+├── swarm-decompose.ts # Decomposition strategies
+├── swarm-strategies.ts # Strategy selection
+├── skills.ts          # Skills system
+├── learning.ts        # Pattern maturity, outcomes
+├── anti-patterns.ts   # Anti-pattern detection
+├── structured.ts      # JSON parsing utilities
+├── mandates.ts        # Mandate system
+└── schemas/           # Zod schemas
 ```
 
-### Event Sourcing
-
-All state is stored as an append-only event log:
-
-```
-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
-
-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
-```
-
-**Why event sourcing?**
-
-- **Audit trail** - full history of what happened
-- **Replay** - reconstruct state from events
-- **Debugging** - see exactly what went wrong
-- **Learning** - analyze outcomes over time
+## Dependencies
 
-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.
+- [swarm-mail](../swarm-mail) - Event sourcing primitives (workspace dependency)
+- [@opencode-ai/plugin](https://www.npmjs.com/package/@opencode-ai/plugin) - OpenCode plugin API
+- [effect](https://effect.website) - Effect-TS for type-safe composition
+- [zod](https://zod.dev) - Schema validation
 
-## Dependencies
+## Development
 
-| 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        |
+```bash
+# From monorepo root
+bun turbo build --filter=opencode-swarm-plugin
+bun turbo test --filter=opencode-swarm-plugin
+bun turbo typecheck --filter=opencode-swarm-plugin
 
-Run `swarm doctor` to check status.
+# Or from this directory
+bun run build
+bun test
+bun run typecheck
+```
 
 ## CLI
 
@@ -456,24 +154,6 @@ swarm init      # Initialize beads in project
 swarm config    # Show config file paths
 ```
 
-## Development
-
-```bash
-bun install
-bun test                # Unit tests (230 tests)
-bun run test:integration # Integration tests
-bun run build
-```
-
-## Credits
-
-**Inspiration & Core Ideas:**
-
-- [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
 
 MIT