opencode-swarm-plugin 0.23.6 → 0.25.0

package/.turbo/turbo-build.log

@@ -1,9 +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 36ms
+Bundled 196 modules in 32ms
 
-  index.js  1.14 MB  (entry point)
+  index.js  1.16 MB  (entry point)
 
-Bundled 196 modules in 34ms
+Bundled 197 modules in 31ms
 
-  plugin.js  1.12 MB  (entry point)
+  plugin.js  1.13 MB  (entry point)
 

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # opencode-swarm-plugin
 
+## 0.25.0
+
+### Minor Changes
+
+- [`b70ae35`](https://github.com/joelhooks/swarm-tools/commit/b70ae352876515bdfe68511d72bb472c85b7fdfc) Thanks [@joelhooks](https://github.com/joelhooks)! - Add Socratic planning phase and improved worker prompts to swarm setup
+
+  **SWARM_COMMAND template:**
+
+  - Added Phase 0: Socratic Planning - asks clarifying questions before decomposing
+  - Supports `--fast`, `--auto`, `--confirm-only` flags to skip questions
+  - ONE question at a time with concrete options and recommendations
+
+  **Worker agent template:**
+
+  - Reinforces the 9-step survival checklist from SUBTASK_PROMPT_V2
+  - Explicitly lists all steps with emphasis on non-negotiables
+  - Explains WHY skipping steps causes problems (lost work, conflicts, etc.)
+
+  **Agent path consolidation:**
+
+  - Now creates nested paths: `~/.config/opencode/agent/swarm/worker.md`
+  - Matches `Task(subagent_type="swarm/worker")` format
+  - Cleans up legacy flat files (`swarm-worker.md`) on reinstall
+
+  To get the new prompts, run `swarm setup` and choose "Reinstall everything".
+
+## 0.24.0
+
+### Minor Changes
+
+- [`434f48f`](https://github.com/joelhooks/swarm-tools/commit/434f48f207c3509f6b924caeb47cd6e019dcc0e1) Thanks [@joelhooks](https://github.com/joelhooks)! - Add worker survival checklist and Socratic planning for swarm coordination
+
+  **Worker Survival Checklist (9-step mandatory flow):**
+
+  - Workers now follow a strict initialization sequence: swarmmail_init → semantic-memory_find → skills_use → swarmmail_reserve
+  - Workers reserve their own files (coordinators no longer reserve on behalf of workers)
+  - Auto-checkpoint at 25/50/75% progress milestones
+  - Workers store learnings via semantic-memory before completing
+
+  **Socratic Planning:**
+
+  - New `swarm_plan_interactive` tool with 4 modes: socratic (default), fast, auto, confirm-only
+  - Default mode asks clarifying questions before decomposition
+  - Escape hatches for experienced users: `--fast`, `--auto`, `--confirm-only` flags on /swarm command
+
+  **Updated Skills:**
+
+  - swarm-coordination skill now documents worker survival patterns and coordinator rules
+
+### Patch Changes
+
+- [#15](https://github.com/joelhooks/swarm-tools/pull/15) [`299f2d3`](https://github.com/joelhooks/swarm-tools/commit/299f2d3305796bcb411f9b90715cda3513d17b54) Thanks [@tayiorbeii](https://github.com/tayiorbeii)! - Sync bundled skills into the global skills directory during `swarm setup` reinstall, fix bundled-skill path resolution, and make AGENTS.md skill-awareness updates work without relying on `opencode run`.
+
 ## 0.23.6
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,9 @@
 
 OpenCode plugin for multi-agent swarm coordination with learning capabilities.
 
+**🌐 Website:** [swarmtools.ai](https://swarmtools.ai)  
+**📚 Full Documentation:** [swarmtools.ai/docs](https://swarmtools.ai/docs)
+
 ```
  ███████╗██╗    ██╗ █████╗ ██████╗ ███╗   ███╗
  ██╔════╝██║    ██║██╔══██╗██╔══██╗████╗ ████║
@@ -18,7 +21,7 @@ OpenCode plugin for multi-agent swarm coordination with learning capabilities.
 - **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
+- **Checkpoint & Recovery** - Auto-checkpoint at 25/50/75%, survive context death (9 integration tests ✅)
 
 ## Install
 
@@ -76,8 +79,8 @@ swarm setup
 | `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_checkpoint`             | Save progress snapshot (auto at 25/50/75%)      |
+| `swarm_recover`                | Resume from checkpoint (returns full context)   |
 | `swarm_learn`                  | Extract learnings from outcome                  |
 | `swarm_broadcast`              | Send message to all active agents               |
 | `swarm_accumulate_error`       | Track recurring errors (3-strike system)        |
@@ -94,6 +97,69 @@ swarm setup
 | `skills_read`   | Read skill content      |
 | `skills_create` | Create new skill        |
 
+## Checkpoint & Recovery
+
+Ensures work survives context compaction or crashes. Proven by 9 integration tests.
+
+### Auto-Checkpoint Milestones
+
+When `swarm_progress` reports 25%, 50%, or 75% completion, a checkpoint is automatically saved to PGLite:
+
+```typescript
+// Stored in .swarm-mail/ directory (no external database needed)
+{
+  epic_id: "bd-123",
+  bead_id: "bd-123.1",
+  strategy: "file-based",
+  files: ["src/auth.ts", "src/middleware.ts"],
+  progress_percent: 50,
+  directives: {
+    shared_context: "OAuth implementation notes",
+    skills_to_load: ["testing-patterns"],
+    coordinator_notes: "Watch for race conditions"
+  },
+  recovery: {
+    last_checkpoint: 1234567890,
+    files_modified: ["src/auth.ts"],
+    error_context: "Optional: error details if checkpoint during error"
+  }
+}
+```
+
+### Tools
+
+**swarm_checkpoint** - Manually save a checkpoint:
+```typescript
+swarm_checkpoint({
+  project_key: "/abs/path",
+  agent_name: "WorkerA",
+  bead_id: "bd-123.1",
+  epic_id: "bd-123",
+  files_modified: ["src/auth.ts"],
+  progress_percent: 30,
+  directives: { shared_context: "..." },
+  error_context: "Optional"
+})
+```
+
+**swarm_recover** - Resume from last checkpoint:
+```typescript
+swarm_recover({
+  project_key: "/abs/path",
+  epic_id: "bd-123"
+})
+// Returns:
+// {
+//   found: true,
+//   context: { epic_id, bead_id, files, strategy, directives, recovery },
+//   age_seconds: 120
+// }
+```
+
+### Failure Handling
+
+Checkpoint failures are **non-fatal**—work continues even if checkpointing fails. Prevents infrastructure from blocking actual work.
+
 ## Bundled Skills
 
 Located in `global-skills/`:
@@ -126,6 +192,74 @@ src/
 
 ## Dependencies
 
+### Required
+
+| Dependency | Purpose |
+|------------|---------|
+| [OpenCode](https://opencode.ai) | AI coding agent (the plugin runs inside OpenCode) |
+| [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking |
+
+### Optional (Highly Recommended)
+
+These tools significantly enhance the swarm experience:
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| [CASS](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context - queries past sessions for similar decompositions | See below |
+| [UBS](https://github.com/Dicklesworthstone/ultimate_bug_scanner) | Bug scanning - runs on subtask completion to catch issues | See below |
+| [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence - stores patterns across sessions | See below |
+
+#### Installing CASS
+
+```bash
+# Clone and install
+git clone https://github.com/Dicklesworthstone/coding_agent_session_search
+cd coding_agent_session_search
+pip install -e .
+
+# Build the index (run periodically to index new sessions)
+cass index
+```
+
+#### Installing UBS
+
+```bash
+# Clone and install
+git clone https://github.com/Dicklesworthstone/ultimate_bug_scanner
+cd ultimate_bug_scanner
+pip install -e .
+```
+
+#### Installing semantic-memory
+
+Requires [Ollama](https://ollama.ai) with an embedding model:
+
+```bash
+# 1. Install Ollama (macOS)
+brew install ollama
+
+# 2. Start Ollama service
+ollama serve
+
+# 3. Pull an embedding model
+ollama pull mxbai-embed-large
+
+# 4. Install the OpenCode plugin
+# Add to your OpenCode config
+```
+
+The `semantic-memory_check` tool verifies Ollama is ready.
+
+**Why install these?**
+
+- **CASS** - When you run `/swarm "Add OAuth"`, the coordinator queries CASS for similar past tasks. Without it, decomposition is based only on the current task description.
+- **UBS** - Every `swarm_complete` runs UBS to scan for bugs. Without it, you lose automatic bug detection.
+- **semantic-memory** - Pattern maturity and anti-pattern detection persist across sessions. Without it, learning resets each session.
+
+Run `swarm doctor` to check which dependencies are installed.
+
+### npm Dependencies
+
 - [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
@@ -154,6 +288,24 @@ swarm init      # Initialize beads in project
 swarm config    # Show config file paths
 ```
 
+## Roadmap
+
+### Planned Features
+
+- **Enhanced Learning** - Pattern extraction from successful/failed decompositions
+- **Swarm Observability** - Real-time visualization of agent coordination
+- **Advanced Strategies** - Risk-based decomposition, critical path optimization
+- **Multi-Project Coordination** - Cross-repo dependencies and shared context
+- **Learning Export/Import** - Share pattern maturity across teams
+
+### Experimental
+
+- **Auto-healing Swarms** - Agents detect and recover from blockers autonomously
+- **Semantic Code Search** - Vector-based codebase exploration for decomposition context
+- **Prevention Pipeline Integration** - Auto-generate prevention patterns from debug sessions
+
+See [swarmtools.ai/docs](https://swarmtools.ai/docs) for latest updates and detailed guides.
+
 ## License
 
 MIT