opencode-swarm-plugin 0.20.0 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/.beads/issues.jsonl +202 -0
  2. package/INTEGRATION_EXAMPLE.md +66 -0
  3. package/README.md +127 -562
  4. package/dist/index.js +3842 -2917
  5. package/dist/plugin.js +3824 -2918
  6. package/docs/analysis/subagent-coordination-patterns.md +2 -0
  7. package/evals/README.md +116 -0
  8. package/evals/evalite.config.ts +15 -0
  9. package/evals/example.eval.ts +32 -0
  10. package/evals/fixtures/decomposition-cases.ts +105 -0
  11. package/evals/lib/data-loader.test.ts +288 -0
  12. package/evals/lib/data-loader.ts +111 -0
  13. package/evals/lib/llm.ts +115 -0
  14. package/evals/scorers/index.ts +200 -0
  15. package/evals/scorers/outcome-scorers.test.ts +27 -0
  16. package/evals/scorers/outcome-scorers.ts +349 -0
  17. package/evals/swarm-decomposition.eval.ts +112 -0
  18. package/package.json +8 -1
  19. package/src/beads.ts +49 -0
  20. package/src/eval-capture.ts +487 -0
  21. package/src/index.ts +45 -3
  22. package/src/output-guardrails.test.ts +438 -0
  23. package/src/output-guardrails.ts +381 -0
  24. package/src/schemas/index.ts +18 -0
  25. package/src/schemas/swarm-context.ts +115 -0
  26. package/src/streams/events.test.ts +296 -0
  27. package/src/streams/events.ts +93 -0
  28. package/src/streams/migrations.test.ts +24 -20
  29. package/src/streams/migrations.ts +51 -0
  30. package/src/streams/projections.ts +187 -0
  31. package/src/streams/store.ts +275 -0
  32. package/src/swarm-orchestrate.ts +430 -1
  33. package/src/swarm-prompts.ts +84 -12
package/README.md CHANGED
@@ -1,7 +1,6 @@
1
1
  # opencode-swarm-plugin
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/opencode-swarm-plugin.svg)](https://www.npmjs.com/package/opencode-swarm-plugin)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
4
 
6
5
  ```
7
6
  ███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
@@ -13,636 +12,202 @@
13
12
 
14
13
  \ ` - ' /
15
14
  - .(o o). -
16
- ( >.< ) Multi-agent coordination for OpenCode
17
- /| |\ Break complex tasks into parallel subtasks,
18
- (_| |_) spawn agents, coordinate via messaging.
19
- bzzzz... The plugin learns from outcomes.
15
+ ( >.< ) Break big tasks into small ones.
16
+ /| |\ Spawn agents to work in parallel.
17
+ (_| |_) Learn from what works.
18
+ bzzzz...
20
19
  ```
21
20
 
22
- ## Install
23
-
24
- ```bash
25
- npm install -g opencode-swarm-plugin@latest
26
- swarm setup
27
- ```
21
+ ## What is this?
28
22
 
29
- The setup wizard handles everything:
23
+ You give it a task. It breaks it into pieces. It spawns agents to work on each piece simultaneously. They coordinate so they don't step on each other. When they're done, you have working code.
30
24
 
31
25
  ```
32
- ┌ opencode-swarm-plugin v0.16.0
33
- │
34
- ◇ Checking dependencies...
35
- │
36
- ◆ OpenCode
37
- ◆ Beads
38
- ▲ CASS (optional)
39
- ▲ UBS (optional)
40
- ▲ semantic-memory (optional)
41
- │
42
- ◇ Setting up OpenCode integration...
43
- │
44
- ◆ Plugin: ~/.config/opencode/plugin/swarm.ts
45
- ◆ Command: ~/.config/opencode/command/swarm.md
46
- ◆ Agent: ~/.config/opencode/agent/swarm-planner.md
47
- │
48
- └ Setup complete!
49
- ```
50
-
51
- Then in your project:
52
-
53
- ```bash
54
- cd your-project
55
- swarm init
26
+ "Add OAuth"
27
+ │
28
+ ▼
29
+ ┌────────────────────────┐
30
+ │ COORDINATOR │
31
+ │ picks strategy, splits│
32
+ └────────────────────────┘
33
+ │
34
+ ┌─────────────────────┼─────────────────────┐
35
+ ▼ ▼ ▼
36
+ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
37
+ │ Worker A │ │ Worker B │ │ Worker C │
38
+ │ auth/oauth │ │ auth/session│ │ auth/tests │
39
+ │ 🔒 files │ │ 🔒 files │ │ 🔒 files │
40
+ └─────────────┘ └─────────────┘ └─────────────┘
41
+ │ │ │
42
+ └─────────────────────┼─────────────────────┘
43
+ ▼
44
+ working code
56
45
  ```
57
46
 
58
- ## Migrating from MCP Agent Mail
59
-
60
- If you were using the MCP-based Agent Mail (pre-v0.15), here's how to migrate:
61
-
62
- ### What Changed
63
-
64
- - **Before:** Agent Mail required a separate MCP server running Go-based agent-mail
65
- - **After:** Agent Mail is now embedded using PGLite (no external dependencies)
66
-
67
- ### Migration Steps
68
-
69
- 1. **Update the plugin:**
70
-
71
- ```bash
72
- npm install -g opencode-swarm-plugin@latest
73
- ```
74
-
75
- 2. **Remove MCP configuration** (if present):
76
- - Delete any `agent-mail` MCP server configuration from your OpenCode config
77
- - The embedded version starts automatically
78
-
79
- 3. **Data Migration:**
80
- - Previous MCP data is NOT automatically migrated
81
- - For most users, starting fresh is recommended (swarm state is ephemeral)
82
- - If you need historical data, export from MCP before upgrading
83
-
84
- ### Breaking Changes
85
-
86
- - `agentmail_*` tools now use embedded PGLite instead of MCP
87
- - No external server required
88
- - Slightly different error messages (more actionable)
47
+ The plugin learns from outcomes - what decomposition strategies work, which patterns fail, how long things take. Over time, it gets better at breaking down tasks.
89
48
 
90
- ### Rollback
91
-
92
- If you need to rollback:
49
+ ## Install
93
50
 
94
51
  ```bash
95
- npm install -g opencode-swarm-plugin@0.14.x
96
- ```
97
-
98
- And restore your MCP configuration.
99
-
100
- ## CLI
101
-
102
- ```
103
- swarm setup Interactive installer - checks and installs all dependencies
104
- swarm doctor Health check - shows status of all dependencies
105
- swarm init Initialize beads in current project
106
- swarm config Show paths to generated config files
107
- swarm version Show version and banner
108
- swarm help Show help
52
+ npm install -g opencode-swarm-plugin@latest
53
+ swarm setup
109
54
  ```
110
55
 
111
56
  ## Usage
112
57
 
113
- In OpenCode:
114
-
115
58
  ```
116
59
  /swarm "Add user authentication with OAuth"
117
60
  ```
118
61
 
119
- Or invoke the planner directly:
62
+ ## How it decides to split work
120
63
 
121
64
  ```
122
- @swarm-planner "Refactor all components to use hooks"
65
+ ┌─────────────────────────────────────────────────────────────────┐
66
+ │ STRATEGY SELECTION │
67
+ ├─────────────────────────────────────────────────────────────────┤
68
+ │ │
69
+ │ "refactor auth" ──────► FILE-BASED │
70
+ │ "migrate to v2" Group by directory structure │
71
+ │ "rename all X" Minimize cross-directory deps │
72
+ │ │
73
+ │ "add feature" ──────► FEATURE-BASED │
74
+ │ "implement X" Vertical slices (data→logic→UI) │
75
+ │ "build new" Keep related components together │
76
+ │ │
77
+ │ "fix bug" ──────► RISK-BASED │
78
+ │ "security issue" Tests FIRST │
79
+ │ "critical" Isolate risky changes │
80
+ │ │
81
+ └─────────────────────────────────────────────────────────────────┘
123
82
  ```
124
83
 
125
- ## Customization
84
+ ## What survives when context dies
126
85
 
127
- Run `swarm config` to see your config file paths:
86
+ Swarms used to die when OpenCode compacted context. Not anymore.
128
87
 
129
88
  ```
130
- 🔌 Plugin loader
131
- ~/.config/opencode/plugin/swarm.ts
132
-
133
- 📜 /swarm command prompt
134
- ~/.config/opencode/command/swarm.md
135
-
136
- 🤖 @swarm-planner agent
137
- ~/.config/opencode/agent/swarm-planner.md
138
- ```
139
-
140
- ### /swarm Command
141
-
142
- The `/swarm` command is defined in `~/.config/opencode/command/swarm.md`:
143
-
144
- ```markdown
145
- ---
146
- description: Decompose task into parallel subtasks and coordinate agents
147
- ---
148
-
149
- You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
150
-
151
- ## Task
152
-
153
- $ARGUMENTS
154
-
155
- ## Workflow
156
-
157
- 1. **Initialize**: `swarmmail_init` with project_path and task_description
158
- 2. **Decompose**: Use `swarm_select_strategy` then `swarm_plan_prompt`
159
- 3. **Create beads**: `beads_create_epic` with subtasks and file assignments
160
- 4. **Reserve files**: `swarmmail_reserve` for each subtask's files
161
- 5. **Spawn agents**: Use Task tool with `swarm_spawn_subtask` prompts
162
- 6. **Monitor**: Check `swarmmail_inbox` for progress
163
- 7. **Complete**: `swarm_complete` when done, then `beads_sync` to push
164
-
165
- ## Strategy Selection
166
-
167
- | Strategy | Best For | Keywords |
168
- | ------------- | ----------------------- | ------------------------------------- |
169
- | file-based | Refactoring, migrations | refactor, migrate, rename, update all |
170
- | feature-based | New features | add, implement, build, create |
171
- | risk-based | Bug fixes, security | fix, bug, security, critical, urgent |
172
-
173
- Begin decomposition now.
89
+ Session 1 Context Session 2
90
+ │ Compacts │
91
+ ▼ 💥 ▼
92
+ ┌─────────────────┐ ┌─────────────────┐
93
+ │ swarm running │ │ swarm_recover() │
94
+ │ ├─ 25% ✓ saved │ │ │ │
95
+ │ ├─ 50% ✓ saved │ ─────────────────────────────────►│ ▼ │
96
+ │ └─ 75% ✓ saved │ checkpoints survive │ resume at 75% │
97
+ └─────────────────┘ └─────────────────┘
174
98
  ```
175
99
 
176
- > **Note**: The `$ARGUMENTS` placeholder captures everything you type after `/swarm`. This is how your task description gets passed to the agent.
100
+ The plugin checkpoints at 25%, 50%, and 75% progress. Files reserved, progress tracked, context preserved.
177
101
 
178
- ### Agents
179
-
180
- The setup wizard creates two agents with your chosen models:
102
+ ## Learning
181
103
 
182
- **@swarm-planner** (`~/.config/opencode/agent/swarm-planner.md`) - Coordinator that decomposes tasks:
104
+ The plugin tracks outcomes and adjusts over time:
183
105
 
184
- ```yaml
185
- ---
186
- name: swarm-planner
187
- description: Strategic task decomposition for swarm coordination
188
- model: anthropic/claude-sonnet-4-5 # Your chosen coordinator model
189
- ---
190
106
  ```
107
+ ┌─────────────────────────────────┐
108
+ │ LEARNING LOOP │
109
+ └─────────────────────────────────┘
110
+ │
111
+ ┌───────────────────────────┼───────────────────────────┐
112
+ ▼ ▼ ▼
113
+ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
114
+ │ OUTCOMES │ │ PATTERNS │ │ ANTI-PATTERNS │
115
+ │ │ │ │ │ │
116
+ │ fast+success │ │ candidate │ │ >60% failure │
117
+ │ = good signal │──────────►│ ↓ │──────────►│ = auto-invert │
118
+ │ │ │ established │ │ │
119
+ │ slow+errors │ │ ↓ │ │ "split by X" │
120
+ │ = bad signal │ │ proven │ │ becomes │
121
+ │ │ │ │ │ "DON'T split │
122
+ └───────────────┘ └───────────────┘ │ by X" │
123
+ └───────────────┘
191
124
 
192
- **@swarm-worker** (`~/.config/opencode/agent/swarm-worker.md`) - Fast executor for subtasks:
193
-
194
- ```yaml
195
- ---
196
- name: swarm-worker
197
- description: Executes subtasks in a swarm - fast, focused, cost-effective
198
- model: anthropic/claude-haiku-4-5 # Your chosen worker model
199
- ---
125
+ Confidence decays over 90 days
126
+ unless patterns are revalidated
200
127
  ```
201
128
 
202
- ### Decomposition Rules
203
-
204
- - **2-7 subtasks** - Too few = not parallel, too many = coordination overhead
205
- - **No file overlap** - Each file appears in exactly one subtask
206
- - **Include tests** - Put test files with the code they test
207
- - **Order by dependency** - If B needs A's output, A comes first (lower index)
208
-
209
- Edit these files to customize behavior. Run `swarm setup` to regenerate defaults.
210
-
211
129
  ## Skills
212
130
 
213
- Skills are reusable knowledge packages that agents can load on-demand. They contain domain expertise, workflows, and patterns that help agents perform specialized tasks.
214
-
215
- ### Using Skills
131
+ Skills are knowledge packages agents can load. Teach once, use everywhere.
216
132
 
217
- ```bash
218
- # List available skills
219
- swarm tool skills_list
220
-
221
- # Read a skill's content
222
- swarm tool skills_read --json '{"name": "debugging"}'
223
-
224
- # Use a skill (get formatted for context injection)
225
- swarm tool skills_use --json '{"name": "code-review", "context": "reviewing a PR"}'
226
133
  ```
227
-
228
- In OpenCode, agents can use skills directly:
229
-
134
+ skills_use(name="testing-patterns") # Load testing knowledge
135
+ skills_use(name="swarm-coordination") # Load swarm workflow
230
136
  ```
231
- skills_list() # See what's available
232
- skills_use(name="debugging") # Load debugging patterns
233
- skills_use(name="swarm-coordination") # Load swarm workflow
234
- ```
235
-
236
- ### Bundled Skills
237
-
238
- | Skill | Tags | Description |
239
- | -------------------- | -------------------- | ------------------------------------------------------------------------------------ |
240
- | `cli-builder` | cli, typescript, bun | Building TypeScript CLIs with Bun - argument parsing, subcommands, output formatting |
241
- | `learning-systems` | learning, feedback | Implicit feedback scoring, confidence decay, anti-pattern detection |
242
- | `mcp-tool-authoring` | mcp, tools | Building MCP tools - schema definition, context passing, error handling |
243
- | `skill-creator` | meta, skills | Guide for creating effective skills |
244
- | `swarm-coordination` | swarm, multi-agent | Complete swarm playbook - strategies, coordinator patterns, failure recovery |
245
- | `system-design` | design, architecture | Building reusable systems - deep modules, complexity management, design red flags |
246
-
247
- ### Skill Locations
248
-
249
- Skills are loaded from three locations (in order):
250
137
 
251
- 1. **Project skills**: `.opencode/skills/`, `.claude/skills/`, or `skills/`
252
- 2. **Global skills**: `~/.config/opencode/skills/`
253
- 3. **Bundled skills**: Included with the plugin
138
+ Bundled: `cli-builder`, `learning-systems`, `swarm-coordination`, `system-design`, `testing-patterns`, `skill-creator`
254
139
 
255
- ### Creating Skills
140
+ Create your own in `.opencode/skills/` or `~/.config/opencode/skills/`.
256
141
 
257
- ```bash
258
- # Initialize project skills directory
259
- swarm tool skills_init
260
-
261
- # Create a new skill
262
- swarm tool skills_create --json '{"name": "my-skill", "description": "What it does", "tags": ["tag1", "tag2"]}'
263
- ```
142
+ ## Architecture
264
143
 
265
- Or use the `skill-creator` skill for guidance:
266
-
267
- ```
268
- skills_use(name="skill-creator")
269
- ```
270
-
271
- Each skill is a directory containing:
272
-
273
- ```
274
- my-skill/
275
- SKILL.md # Main content (required)
276
- references/ # Optional supporting files
277
- patterns.md
278
- examples.md
279
- ```
280
-
281
- ### SKILL.md Format
282
-
283
- ```markdown
284
- ---
285
- name: my-skill
286
- description: Brief description for discovery
287
- tags:
288
- - tag1
289
- - tag2
290
- ---
291
-
292
- # My Skill
293
-
294
- ## When to Use
295
-
296
- - Trigger condition 1
297
- - Trigger condition 2
298
-
299
- ## Patterns
300
-
301
- ### Pattern Name
302
-
303
- Description and examples...
304
-
305
- ## Anti-Patterns
306
-
307
- What NOT to do...
308
- ```
309
-
310
- ## Dependencies
311
-
312
- | Dependency | Purpose | Required |
313
- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
314
- | [OpenCode](https://opencode.ai) | Plugin host | Yes |
315
- | [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking | Yes |
316
- | [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions | No |
317
- | [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner) | Pre-completion bug scanning using AI-powered static analysis | No |
318
- | [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence | No |
319
- | [Redis](https://redis.io) | Rate limiting (SQLite fallback available) | No |
320
-
321
- All dependencies are checked and can be installed via `swarm setup`.
322
-
323
- ### Installing Optional Dependencies
324
-
325
- **UBS (Ultimate Bug Scanner)** - Scans code for bugs before task completion:
326
-
327
- ```bash
328
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh" | bash
329
- ```
330
-
331
- **CASS (Coding Agent Session Search)** - Indexes and searches AI coding agent history:
332
-
333
- ```bash
334
- curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode
335
- ```
336
-
337
- > **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.
338
-
339
- ## Tools Reference
340
-
341
- ### Swarm
342
-
343
- | Tool | Description |
344
- | ------------------------------ | ------------------------------------------------------------------------- |
345
- | `swarm_init` | Initialize swarm session |
346
- | `swarm_select_strategy` | Analyze task, recommend decomposition strategy (file/feature/risk-based) |
347
- | `swarm_plan_prompt` | Generate strategy-specific planning prompt with CASS history |
348
- | `swarm_decompose` | Generate decomposition prompt |
349
- | `swarm_validate_decomposition` | Validate response, detect file conflicts |
350
- | `swarm_spawn_subtask` | Generate worker agent prompt with Swarm Mail/beads instructions |
351
- | `swarm_status` | Get swarm progress by epic ID |
352
- | `swarm_progress` | Report subtask progress to coordinator |
353
- | `swarm_complete` | Complete subtask - runs UBS (Ultimate Bug Scanner), releases reservations |
354
- | `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
355
-
356
- ### Beads
357
-
358
- | Tool | Description |
359
- | ------------------- | ---------------------------------------------- |
360
- | `beads_create` | Create bead with type-safe validation |
361
- | `beads_create_epic` | Create epic + subtasks atomically |
362
- | `beads_query` | Query beads with filters (status, type, ready) |
363
- | `beads_update` | Update status/description/priority |
364
- | `beads_close` | Close bead with reason |
365
- | `beads_start` | Mark bead as in-progress |
366
- | `beads_ready` | Get next unblocked bead |
367
- | `beads_sync` | Sync to git and push |
368
- | `beads_link_thread` | Link bead to Swarm Mail thread |
369
-
370
- ### Swarm Mail (Embedded - Primary)
371
-
372
- | Tool | Description |
373
- | ------------------------ | --------------------------------------------- |
374
- | `swarmmail_init` | Initialize session, register agent |
375
- | `swarmmail_send` | Send message to agents |
376
- | `swarmmail_inbox` | Fetch inbox (max 5, no bodies - context safe) |
377
- | `swarmmail_read_message` | Fetch single message body by ID |
378
- | `swarmmail_reserve` | Reserve file paths for exclusive editing |
379
- | `swarmmail_release` | Release file reservations |
380
- | `swarmmail_ack` | Acknowledge message |
381
- | `swarmmail_health` | Check embedded database health |
382
-
383
- ### Agent Mail (Deprecated - MCP-based)
384
-
385
- > **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.
386
- >
387
- > **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.
388
-
389
- ## Event-Sourced Architecture (Embedded)
390
-
391
- > **🙏 Built on the shoulders of giants**
392
- >
393
- > 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.
394
- >
395
- > 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.
396
- >
397
- > **Key contributions from MCP Agent Mail:**
398
- >
399
- > - File reservation protocol with conflict detection
400
- > - Agent registration and heartbeat patterns
401
- > - Thread-based message organization
402
- > - Importance levels and acknowledgment tracking
403
- >
404
- > Thank you to the MCP Agent Mail team for open-sourcing such a well-designed system.
405
-
406
- > **🎯 Quality Patterns from Superpowers**
407
- >
408
- > 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".
409
- >
410
- > **Key patterns adopted:**
411
- >
412
- > - **Verification Gate** - The Gate Function (IDENTIFY → RUN → READ → VERIFY → CLAIM) ensures no completion claims without fresh verification evidence
413
- > - **3-Strike Architecture Rule** - After 3 failed fixes, question the architecture, not the bug
414
- > - **CSO (Claude Search Optimization)** - Skill descriptions that answer "Should I read this right now?"
415
- > - **Defense-in-Depth** - Validate at every layer data passes through
416
- >
417
- > Thank you Jesse for open-sourcing such a thoughtfully designed system.
418
-
419
- 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.
420
-
421
- ### Architecture Comparison
422
-
423
- **MCP-based (deprecated, external):**
424
-
425
- ```
426
- plugin tools → HTTP → MCP Server (Go process) → SQLite
427
- ```
428
-
429
- **Event-sourced (embedded, current):**
430
-
431
- ```
432
- plugin tools → streams/agent-mail.ts → streams/store.ts → PGLite (in-process)
433
- ↓
434
- streams/projections.ts
435
- ↓
436
- Materialized views (agents, messages, reservations)
437
- ↓
438
- Fast reads
439
- ```
440
-
441
- ### Architecture Flow
144
+ Everything runs in-process. No external servers.
442
145
 
443
146
  ```
444
147
  ┌─────────────────────────────────────────────────────────────────┐
445
- │ Plugin Tools Layer │
446
- │ (swarmmail_init, swarmmail_send, swarmmail_reserve, etc.) │
447
- └──────────────────────────────┬──────────────────────────────────┘
448
- │
449
- ▼
148
+ │ YOUR TASK │
149
+ └─────────────────────────────────────────────────────────────────┘
150
+ │
151
+ ▼
450
152
  ┌─────────────────────────────────────────────────────────────────┐
451
- │ streams/agent-mail.ts │
452
- │ (High-level API wrapper) │
453
- └──────────────────────────────┬──────────────────────────────────┘
454
- │
455
- ▼
153
+ │ DECOMPOSITION strategy selection, subtask creation │
154
+ └─────────────────────────────────────────────────────────────────┘
155
+ │
156
+ ▼
456
157
  ┌─────────────────────────────────────────────────────────────────┐
457
- │ streams/events.ts │
458
- │ 11 event types: agent_registered, message_sent, │
459
- │ file_reserved, message_read, message_acked, etc. │
460
- └──────────────────────────────┬──────────────────────────────────┘
461
- │
462
- ▼
158
+ │ BEADS git-backed issues for each subtask │
159
+ └─────────────────────────────────────────────────────────────────┘
160
+ │
161
+ ▼
463
162
  ┌─────────────────────────────────────────────────────────────────┐
464
- │ streams/store.ts │
465
- │ Append-only event log (PGLite storage) │
466
- │ appendEvent() • readEvents() • replayEvents() │
467
- └──────────────────────────────┬──────────────────────────────────┘
468
- │
469
- ▼
163
+ │ SWARM MAIL agent coordination, file reservations │
164
+ └─────────────────────────────────────────────────────────────────┘
165
+ │
166
+ ▼
470
167
  ┌─────────────────────────────────────────────────────────────────┐
471
- │ streams/projections.ts │
472
- │ Build materialized views from events │
473
- │ getAgents() • getInbox() • getActiveReservations() │
474
- │ checkConflicts() • threadStats() │
475
- └─────────────────────────────┬────────────────────────────────────┘
476
- │
477
- ▼
168
+ │ PGLITE embedded postgres, event-sourced state │
169
+ └─────────────────────────────────────────────────────────────────┘
170
+ │
171
+ ▼
478
172
  ┌─────────────────────────────────────────────────────────────────┐
479
- │ Materialized Tables (Derived State) │
480
- │ agents • messages • reservations • message_reads │
481
- │ (Rebuilt by replaying event log) │
173
+ │ LEARNING outcomes feed back into decomposition │
482
174
  └─────────────────────────────────────────────────────────────────┘
483
175
  ```
484
176
 
485
- ### Module Descriptions
486
-
487
- | Module | Responsibility |
488
- | -------------------------- | -------------------------------------------------------------------------------------------------- |
489
- | **streams/events.ts** | Zod schemas for 11 event types (agent_registered, message_sent, file_reserved, task_progress, etc) |
490
- | **streams/store.ts** | Append-only event log with PGLite backend (appendEvent, readEvents, replayEvents) |
491
- | **streams/projections.ts** | Materialize views from events (getAgents, getInbox, checkConflicts, threadStats) |
492
- | **streams/agent-mail.ts** | High-level API matching MCP interface (initAgent, sendAgentMessage, reserveAgentFiles) |
493
- | **streams/debug.ts** | Debugging utilities (debugEvents, debugAgent, debugMessage, inspectState) |
494
-
495
- ### Key Benefits
496
-
497
- - **No external dependencies** - Runs in-process with PGLite (Postgres compiled to WASM)
498
- - **Full audit trail** - Every state change is an immutable event
499
- - **Crash recovery** - Rebuild state by replaying events from log
500
- - **Time-travel debugging** - Replay events up to any point in time
501
- - **Testability** - 127 tests passing across streams module
502
- - **Durable Streams protocol** - Inspired by Electric SQL's event sourcing patterns
503
-
504
- ### Event Types
505
-
506
- The system emits 11 event types tracked in `streams/events.ts`:
507
-
508
- | Event | Triggered By |
509
- | ------------------ | ------------------------------------- |
510
- | `agent_registered` | Agent initialization |
511
- | `message_sent` | Sending inter-agent message |
512
- | `file_reserved` | Reserving files for exclusive editing |
513
- | `file_released` | Releasing file reservations |
514
- | `message_read` | Reading a message |
515
- | `message_acked` | Acknowledging a message |
516
- | `task_started` | Starting work on a bead |
517
- | `task_progress` | Reporting progress update |
518
- | `task_completed` | Completing a bead |
519
- | `task_blocked` | Marking a task as blocked |
520
- | `agent_active` | Agent heartbeat/keep-alive |
521
-
522
- ### Materialized Views
523
-
524
- Projections build these derived tables from the event log:
525
-
526
- | View | Contains |
527
- | --------------- | ------------------------------------------------------ |
528
- | `agents` | Registered agents with metadata and last activity |
529
- | `messages` | All inter-agent messages with thread/importance |
530
- | `reservations` | Active file reservations with TTL and exclusivity flag |
531
- | `message_reads` | Read receipts for message tracking |
532
-
533
- State is always derived - delete the tables and replay events to rebuild.
534
-
535
- ### Structured Output
536
-
537
- | Tool | Description |
538
- | -------------------------------- | ----------------------------------------------------- |
539
- | `structured_extract_json` | Extract JSON from markdown/text (multiple strategies) |
540
- | `structured_validate` | Validate response against schema |
541
- | `structured_parse_evaluation` | Parse self-evaluation response |
542
- | `structured_parse_decomposition` | Parse task decomposition response |
543
- | `structured_parse_bead_tree` | Parse bead tree for epic creation |
544
-
545
- ## Decomposition Strategies
546
-
547
- ### File-Based
548
-
549
- Best for: refactoring, migrations, pattern changes
550
-
551
- - Group files by directory or type
552
- - Handle shared types/utilities first
553
- - Minimize cross-directory dependencies
554
-
555
- **Keywords**: refactor, migrate, rename, update all, replace
556
-
557
- ### Feature-Based
558
-
559
- Best for: new features, adding functionality
560
-
561
- - Each subtask is a complete vertical slice
562
- - Start with data layer, then logic, then UI
563
- - Keep related components together
564
-
565
- **Keywords**: add, implement, build, create, feature
566
-
567
- ### Risk-Based
568
-
569
- Best for: bug fixes, security issues
570
-
571
- - Write tests FIRST
572
- - Isolate risky changes
573
- - Audit similar code for same issue
574
-
575
- **Keywords**: fix, bug, security, critical, urgent
576
-
577
- ## Learning
578
-
579
- The plugin learns from outcomes:
580
-
581
- | Mechanism | How It Works |
582
- | ----------------- | ----------------------------------------------------------- |
583
- | Confidence decay | Criteria weights fade unless revalidated (90-day half-life) |
584
- | Implicit feedback | Fast + success = helpful signal, slow + errors = harmful |
585
- | Pattern maturity | candidate → established → proven (or deprecated) |
586
- | Anti-patterns | Patterns with >60% failure rate auto-invert |
587
-
588
- ## Context Preservation
589
-
590
- Hard limits to prevent context exhaustion:
591
-
592
- | Constraint | Default | Reason |
593
- | ------------------- | ---------- | ------------------------------ |
594
- | Inbox limit | 5 messages | Prevents token burn |
595
- | Bodies excluded | Always | Fetch individually when needed |
596
- | Summarize preferred | Yes | Key points, not raw dump |
177
+ ## Dependencies
597
178
 
598
- ## Rate Limiting
179
+ | Required | Optional |
180
+ | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
181
+ | [OpenCode](https://opencode.ai) | [CASS](https://github.com/Dicklesworthstone/coding_agent_session_search) - historical context |
182
+ | [Beads](https://github.com/steveyegge/beads) | [UBS](https://github.com/Dicklesworthstone/ultimate_bug_scanner) - bug scanning |
183
+ | | [semantic-memory](https://github.com/joelhooks/semantic-memory) - learning persistence |
599
184
 
600
- Client-side limits (Redis primary, SQLite fallback):
185
+ Run `swarm doctor` to check status.
601
186
 
602
- | Endpoint | Per Minute | Per Hour |
603
- | -------- | ---------- | -------- |
604
- | send | 20 | 200 |
605
- | reserve | 10 | 100 |
606
- | inbox | 60 | 600 |
187
+ ## CLI
607
188
 
608
- Configure via `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_MIN` env vars.
189
+ ```
190
+ swarm setup # Install and configure
191
+ swarm doctor # Check dependencies
192
+ swarm init # Initialize beads in project
193
+ swarm config # Show config file paths
194
+ ```
609
195
 
610
196
  ## Development
611
197
 
612
198
  ```bash
613
199
  bun install
614
- bun run typecheck
615
200
  bun test
616
201
  bun run build
617
202
  ```
618
203
 
619
- ## Troubleshooting
620
-
621
- ### 1. First Step: Run Doctor
622
-
623
- ```bash
624
- swarm doctor
625
- ```
626
-
627
- This checks all dependencies and shows their installation status.
628
-
629
- ### 2. Common Issues
630
-
631
- | Issue | Cause | Solution |
632
- | --------------------------- | ---------------------------------- | ------------------------------------------------- |
633
- | `beads: command not found` | Beads CLI not installed | `npm install -g @joelhooks/beads` |
634
- | `bd: command not found` | Same as above | `npm install -g @joelhooks/beads` |
635
- | Verification Gate fails | TypeScript errors or test failures | Fix errors shown, or use `skip_verification=true` |
636
- | File reservation conflict | Another agent has the file | Wait for release, or check `swarmmail_inbox` |
637
- | `Mandate not found` | ID doesn't exist | Use `mandate_list` to see available mandates |
638
- | Swarm Mail connection error | Database not initialized | Run `swarm setup` again |
639
- | `Agent not registered` | Session not initialized | Call `swarmmail_init` first |
204
+ ## Credits
640
205
 
641
- ### 3. Getting Help
206
+ Built on ideas from:
642
207
 
643
- - Run `swarm doctor` for dependency status
644
- - Check `swarmmail_health` for database status
645
- - File issues at: https://github.com/joelhooks/opencode-swarm-plugin/issues
208
+ - [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) - multi-agent coordination patterns
209
+ - [Superpowers](https://github.com/obra/superpowers) - verification patterns and skill architecture
210
+ - [Electric SQL](https://electric-sql.com) - durable streams and event sourcing
646
211
 
647
212
  ## License
648
213