opencode-swarm-plugin 0.15.0 → 0.17.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 (18) hide show
  1. package/.beads/issues.jsonl +11 -0
  2. package/README.md +41 -25
  3. package/bin/swarm.ts +35 -5
  4. package/dist/index.js +923 -46
  5. package/dist/plugin.js +822 -32
  6. package/examples/commands/swarm.md +43 -0
  7. package/global-skills/swarm-coordination/SKILL.md +58 -10
  8. package/package.json +1 -1
  9. package/src/beads.ts +30 -21
  10. package/src/index.ts +78 -0
  11. package/src/mandate-promotion.test.ts +473 -0
  12. package/src/mandate-promotion.ts +239 -0
  13. package/src/mandate-storage.test.ts +578 -0
  14. package/src/mandate-storage.ts +794 -0
  15. package/src/mandates.ts +540 -0
  16. package/src/schemas/index.ts +27 -0
  17. package/src/schemas/mandate.ts +232 -0
  18. package/src/swarm.ts +24 -9
package/.beads/issues.jsonl CHANGED
@@ -582,6 +582,12 @@
582
582
  {"id":"opencode-swarm-plugin-a347","title":"High priority ready bead","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-08T08:36:17.512906-08:00","updated_at":"2025-12-08T08:36:19.481274-08:00","closed_at":"2025-12-08T08:36:19.481274-08:00"}
583
583
  {"id":"opencode-swarm-plugin-a3fa","title":"Lifecycle test bead","description":"50% complete","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:05:34.668388-08:00","updated_at":"2025-12-08T08:05:34.745926-08:00","closed_at":"2025-12-08T08:05:34.745926-08:00"}
584
584
  {"id":"opencode-swarm-plugin-a6lo","title":"Thread link test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:24.861491-08:00","updated_at":"2025-12-08T11:11:26.310192-08:00","closed_at":"2025-12-08T11:11:26.310192-08:00"}
585
+ {"id":"opencode-swarm-plugin-a6rl7","title":"Mandate from Heaven: Agent Voting System","description":"Build a collective intelligence system where agents file and vote on ideas, tips, lore, snippets, and feature requests. High-consensus items become 'mandates' that influence future agent behavior via semantic memory.","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-13T14:56:58.000088-08:00","updated_at":"2025-12-13T14:56:58.000088-08:00"}
586
+ {"id":"opencode-swarm-plugin-a6rl7.1","title":"Core schemas and types for mandate system","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-13T14:56:58.053657-08:00","updated_at":"2025-12-13T14:59:07.218098-08:00","closed_at":"2025-12-13T14:59:07.218098-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-a6rl7.1","depends_on_id":"opencode-swarm-plugin-a6rl7","type":"parent-child","created_at":"2025-12-13T14:56:58.055878-08:00","created_by":"daemon"}]}
587
+ {"id":"opencode-swarm-plugin-a6rl7.2","title":"Mandate storage with semantic-memory backend","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T14:56:58.111874-08:00","updated_at":"2025-12-13T15:05:05.736212-08:00","closed_at":"2025-12-13T15:05:05.736212-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-a6rl7.2","depends_on_id":"opencode-swarm-plugin-a6rl7","type":"parent-child","created_at":"2025-12-13T14:56:58.112928-08:00","created_by":"daemon"}]}
588
+ {"id":"opencode-swarm-plugin-a6rl7.3","title":"Mandate promotion engine with decay","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T14:56:58.164309-08:00","updated_at":"2025-12-13T15:05:08.587143-08:00","closed_at":"2025-12-13T15:05:08.587143-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-a6rl7.3","depends_on_id":"opencode-swarm-plugin-a6rl7","type":"parent-child","created_at":"2025-12-13T14:56:58.165879-08:00","created_by":"daemon"}]}
589
+ {"id":"opencode-swarm-plugin-a6rl7.4","title":"Plugin tools for mandate operations","description":"","status":"in_progress","priority":1,"issue_type":"task","created_at":"2025-12-13T14:56:58.225915-08:00","updated_at":"2025-12-13T15:05:14.868024-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-a6rl7.4","depends_on_id":"opencode-swarm-plugin-a6rl7","type":"parent-child","created_at":"2025-12-13T14:56:58.227213-08:00","created_by":"daemon"}]}
590
+ {"id":"opencode-swarm-plugin-a6rl7.5","title":"Integration tests and plugin export","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T14:56:58.282544-08:00","updated_at":"2025-12-13T14:56:58.282544-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-a6rl7.5","depends_on_id":"opencode-swarm-plugin-a6rl7","type":"parent-child","created_at":"2025-12-13T14:56:58.283786-08:00","created_by":"daemon"}]}
585
591
  {"id":"opencode-swarm-plugin-a76x","title":"New feature request","description":"","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-08T08:21:26.918472-08:00","updated_at":"2025-12-08T08:21:29.744733-08:00","closed_at":"2025-12-08T08:21:29.744733-08:00"}
586
592
  {"id":"opencode-swarm-plugin-a8y","title":"Epic with file references","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:39:10.635641-08:00","updated_at":"2025-12-07T19:39:12.218959-08:00","closed_at":"2025-12-07T19:39:12.218959-08:00"}
587
593
  {"id":"opencode-swarm-plugin-a8y.2","title":"Edit src/b.ts","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:10.693537-08:00","updated_at":"2025-12-07T19:39:12.2636-08:00","closed_at":"2025-12-07T19:39:12.2636-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-a8y.2","depends_on_id":"opencode-swarm-plugin-a8y","type":"parent-child","created_at":"2025-12-07T19:39:10.693862-08:00","created_by":"daemon"}]}
@@ -960,6 +966,11 @@
960
966
  {"id":"opencode-swarm-plugin-gpse","title":"Workflow test epic","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T07:49:11.489232-08:00","updated_at":"2025-12-08T07:49:11.696115-08:00","closed_at":"2025-12-08T07:49:11.696115-08:00"}
961
967
  {"id":"opencode-swarm-plugin-gpse.1","title":"Step 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:49:11.52435-08:00","updated_at":"2025-12-08T07:49:11.619347-08:00","closed_at":"2025-12-08T07:49:11.619347-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpse.1","depends_on_id":"opencode-swarm-plugin-gpse","type":"parent-child","created_at":"2025-12-08T07:49:11.524725-08:00","created_by":"daemon"}]}
962
968
  {"id":"opencode-swarm-plugin-gpse.2","title":"Step 2","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:49:11.56095-08:00","updated_at":"2025-12-08T07:49:11.671061-08:00","closed_at":"2025-12-08T07:49:11.671061-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpse.2","depends_on_id":"opencode-swarm-plugin-gpse","type":"parent-child","created_at":"2025-12-08T07:49:11.561312-08:00","created_by":"daemon"}]}
969
+ {"id":"opencode-swarm-plugin-gpusl","title":"DX Improvements: Actionable Errors \u0026 Troubleshooting","description":"Improve developer experience with actionable error messages that tell users HOW to fix problems, add troubleshooting docs, and enhance CLI doctor output.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-13T15:21:23.537986-08:00","updated_at":"2025-12-13T15:26:06.152115-08:00","closed_at":"2025-12-13T15:26:06.152115-08:00"}
970
+ {"id":"opencode-swarm-plugin-gpusl.1","title":"Add troubleshooting section to README","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.645841-08:00","updated_at":"2025-12-13T15:24:59.766004-08:00","closed_at":"2025-12-13T15:24:59.766004-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.1","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.64819-08:00","created_by":"daemon"}]}
971
+ {"id":"opencode-swarm-plugin-gpusl.2","title":"Make BeadError and SwarmError actionable","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.728838-08:00","updated_at":"2025-12-13T15:25:01.061305-08:00","closed_at":"2025-12-13T15:25:01.061305-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.2","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.730994-08:00","created_by":"daemon"}]}
972
+ {"id":"opencode-swarm-plugin-gpusl.3","title":"Make MandateError and storage errors actionable","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.806569-08:00","updated_at":"2025-12-13T15:25:02.21639-08:00","closed_at":"2025-12-13T15:25:02.21639-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.3","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.808361-08:00","created_by":"daemon"}]}
973
+ {"id":"opencode-swarm-plugin-gpusl.4","title":"Enhance CLI doctor with fix suggestions","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.868538-08:00","updated_at":"2025-12-13T15:25:03.179053-08:00","closed_at":"2025-12-13T15:25:03.179053-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.4","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.869987-08:00","created_by":"daemon"}]}
963
974
  {"id":"opencode-swarm-plugin-gq4y","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:26.032848-08:00","updated_at":"2025-12-08T11:12:28.256366-08:00","closed_at":"2025-12-08T11:12:28.256366-08:00"}
964
975
  {"id":"opencode-swarm-plugin-gr8j","title":"Update test bead","description":"Original description","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-08T11:11:08.754659-08:00","updated_at":"2025-12-08T11:11:11.067841-08:00","closed_at":"2025-12-08T11:11:11.067841-08:00"}
965
976
  {"id":"opencode-swarm-plugin-gswv","title":"Bead to start","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:53:44.538704-08:00","updated_at":"2025-12-08T07:53:46.579794-08:00","closed_at":"2025-12-08T07:53:46.579794-08:00"}
package/README.md CHANGED
@@ -29,19 +29,15 @@ swarm setup
29
29
  The setup wizard handles everything:
30
30
 
31
31
  ```
32
- ┌ opencode-swarm-plugin v0.10.0
32
+ ┌ opencode-swarm-plugin v0.16.0
33
33
  │
34
34
  ◇ Checking dependencies...
35
35
  │
36
36
  ◆ OpenCode
37
37
  ◆ Beads
38
- ◆ Go
39
- ▲ Swarm Mail (optional)
40
- ▲ Redis (optional)
41
- │
42
- ◆ Install optional dependencies?
43
- │ ◻ Swarm Mail - Multi-agent coordination
44
- │ ◻ Redis - Rate limiting
38
+ ▲ CASS (optional)
39
+ ▲ UBS (optional)
40
+ ▲ semantic-memory (optional)
45
41
  │
46
42
  ◇ Setting up OpenCode integration...
47
43
  │
@@ -271,16 +267,14 @@ What NOT to do...
271
267
 
272
268
  ## Dependencies
273
269
 
274
- | Dependency | Purpose | Required |
275
- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | -------- |
276
- | [OpenCode](https://opencode.ai) | Plugin host | Yes |
277
- | [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking | Yes |
278
- | [Go](https://go.dev) | Required for Swarm Mail | No |
279
- | [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) ⭐ | **The original** - Multi-agent coordination, file reservations. Swarm Mail is built on these patterns. | No |
280
- | [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions | No |
281
- | [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner) | Pre-completion bug scanning using AI-powered static analysis | No |
282
- | [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence | No |
283
- | [Redis](https://redis.io) | Rate limiting (SQLite fallback available) | No |
270
+ | Dependency | Purpose | Required |
271
+ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
272
+ | [OpenCode](https://opencode.ai) | Plugin host | Yes |
273
+ | [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking | Yes |
274
+ | [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions | No |
275
+ | [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner) | Pre-completion bug scanning using AI-powered static analysis | No |
276
+ | [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence | No |
277
+ | [Redis](https://redis.io) | Rate limiting (SQLite fallback available) | No |
284
278
 
285
279
  All dependencies are checked and can be installed via `swarm setup`.
286
280
 
@@ -298,13 +292,7 @@ curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_sca
298
292
  curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode
299
293
  ```
300
294
 
301
- **MCP Agent Mail** ⭐ - The original multi-agent coordination system. Swarm Mail's embedded implementation is inspired by and compatible with MCP Agent Mail's protocol:
302
-
303
- ```bash
304
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh" | bash -s -- --yes
305
- ```
306
-
307
- > **Note:** The embedded Swarm Mail (PGLite in-process) is now the primary option and works out of the box with no external dependencies. MCP Agent Mail (external Go server) is still supported for advanced use cases requiring a separate server process.
295
+ > **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.
308
296
 
309
297
  ## Tools Reference
310
298
 
@@ -584,6 +572,34 @@ bun test
584
572
  bun run build
585
573
  ```
586
574
 
575
+ ## Troubleshooting
576
+
577
+ ### 1. First Step: Run Doctor
578
+
579
+ ```bash
580
+ swarm doctor
581
+ ```
582
+
583
+ This checks all dependencies and shows their installation status.
584
+
585
+ ### 2. Common Issues
586
+
587
+ | Issue | Cause | Solution |
588
+ | --------------------------- | ---------------------------------- | ------------------------------------------------- |
589
+ | `beads: command not found` | Beads CLI not installed | `npm install -g @joelhooks/beads` |
590
+ | `bd: command not found` | Same as above | `npm install -g @joelhooks/beads` |
591
+ | Verification Gate fails | TypeScript errors or test failures | Fix errors shown, or use `skip_verification=true` |
592
+ | File reservation conflict | Another agent has the file | Wait for release, or check `swarmmail_inbox` |
593
+ | `Mandate not found` | ID doesn't exist | Use `mandate_list` to see available mandates |
594
+ | Swarm Mail connection error | Database not initialized | Run `swarm setup` again |
595
+ | `Agent not registered` | Session not initialized | Call `swarmmail_init` first |
596
+
597
+ ### 3. Getting Help
598
+
599
+ - Run `swarm doctor` for dependency status
600
+ - Check `swarmmail_health` for database status
601
+ - File issues at: https://github.com/joelhooks/opencode-swarm-plugin/issues
602
+
587
603
  ## License
588
604
 
589
605
  MIT
package/bin/swarm.ts CHANGED
@@ -670,6 +670,34 @@ If you discover a reusable pattern worth preserving:
670
670
  // Commands
671
671
  // ============================================================================
672
672
 
673
+ /**
674
+ * Get the fix command for a dependency
675
+ * Returns null for manual installs (those show a link instead)
676
+ */
677
+ function getFixCommand(dep: Dependency): string | null {
678
+ switch (dep.name) {
679
+ case "OpenCode":
680
+ return "brew install sst/tap/opencode";
681
+ case "Beads":
682
+ return "curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash";
683
+ case "Go":
684
+ return "brew install go (or visit https://go.dev/dl/)";
685
+ case "semantic-memory":
686
+ return "npm install -g semantic-memory";
687
+ case "Redis":
688
+ return "brew install redis && brew services start redis";
689
+ case "MCP Agent Mail":
690
+ return "See: https://github.com/Dicklesworthstone/mcp_agent_mail";
691
+ case "CASS (Coding Agent Session Search)":
692
+ return "See: https://github.com/Dicklesworthstone/coding_agent_session_search";
693
+ case "UBS (Ultimate Bug Scanner)":
694
+ return "See: https://github.com/Dicklesworthstone/ultimate_bug_scanner";
695
+ default:
696
+ // Fallback to generic install command if available
697
+ return dep.installType !== "manual" ? dep.install : null;
698
+ }
699
+ }
700
+
673
701
  async function doctor() {
674
702
  p.intro("swarm doctor v" + VERSION);
675
703
 
@@ -689,7 +717,10 @@ async function doctor() {
689
717
  p.log.success(dep.name + (version ? " v" + version : ""));
690
718
  } else {
691
719
  p.log.error(dep.name + " - not found");
692
- p.log.message(" Install: " + dep.install);
720
+ const fixCmd = getFixCommand(dep);
721
+ if (fixCmd) {
722
+ p.log.message(dim(" └─ Fix: " + fixCmd));
723
+ }
693
724
  }
694
725
  }
695
726
 
@@ -701,10 +732,9 @@ async function doctor() {
701
732
  );
702
733
  } else {
703
734
  p.log.warn(dep.name + " - not found (" + dep.description + ")");
704
- if (dep.installType !== "manual") {
705
- p.log.message(" Install: " + dep.install);
706
- } else {
707
- p.log.message(" See: " + dep.install);
735
+ const fixCmd = getFixCommand(dep);
736
+ if (fixCmd) {
737
+ p.log.message(dim(" └─ Fix: " + fixCmd));
708
738
  }
709
739
  }
710
740
  }