opencode-swarm-plugin 0.31.7 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,399 @@
 # opencode-swarm-plugin
 
+## 0.33.0
+
+### Minor Changes
+
+- [`c41abcf`](https://github.com/joelhooks/swarm-tools/commit/c41abcfa37292b72fe41e0cf9d25c6612ae75fa2) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🎓 Skills Grow Up: Discovery Moves to OpenCode
+
+  > _"The best code is no code at all. Every new line of code you willingly bring into the world is code that has to be debugged, code that has to be read and understood, code that has to be supported."_
+  > — Jeff Atwood
+
+  Skills outgrew the nest. OpenCode is shipping native skills support following the [Agent Skills spec](https://spec.agentskills.com/), and our discovery tools are now redundant. Time to deprecate the scaffolding and let the platform handle what it does best.
+
+  ### What Changed
+
+  **Deprecated Tools** (soft deprecation with console warnings):
+
+  - `skills_list` - OpenCode will handle discovery natively
+  - `skills_use` - OpenCode will handle loading via `use skill <name>` syntax
+  - `skills_read` - OpenCode will handle resource access transparently
+  - `skills_execute` - OpenCode will handle script execution in skill context
+
+  **Authoring Tools Kept** (fully functional, no changes):
+
+  - `skills_create` - Create new skills with SKILL.md template
+  - `skills_update` - Update existing skill content
+  - `skills_init` - Initialize skills directory in projects
+  - `skills_add_script` - Add executable scripts to skills
+  - `skills_delete` - Remove project skills
+
+  **Bundled Skills** - All 6 global skills remain intact and spec-compliant:
+
+  - `testing-patterns` - Feathers seams + Beck's 4 rules
+  - `swarm-coordination` - Multi-agent task orchestration
+  - `cli-builder` - Command-line interface patterns
+  - `learning-systems` - Confidence decay, pattern maturity
+  - `skill-creator` - Meta-skill for authoring new skills
+  - `system-design` - Architecture decision frameworks
+
+  ### Why It Matters
+
+  **Before:** Two overlapping skill systems causing confusion. Agents could use plugin tools OR OpenCode's native syntax, with different behavior and semantics.
+
+  **After:** One canonical path. OpenCode owns discovery and loading. Plugin owns authoring and validation. Clean separation of concerns.
+
+  **Benefits:**
+
+  - No tool conflicts between plugin and platform
+  - Native OpenCode syntax (`use skill testing-patterns`) works seamlessly
+  - Simpler mental model for users
+  - Authoring tools remain for creating spec-compliant skills
+
+  ### Migration Path
+
+  **For Discovery/Loading:**
+
+  ```typescript
+  // OLD (deprecated, still works but warns)
+  skills_list()
+  skills_use(name="testing-patterns")
+
+  // NEW (OpenCode native syntax)
+  use skill testing-patterns
+  use skill cli-builder with "building argument parser"
+  ```
+
+  **For Authoring (no change needed):**
+
+  ```typescript
+  // Still fully supported
+  skills_create((name = "my-skill"), (description = "Domain expertise"));
+  skills_update((name = "my-skill"), (content = "Updated SKILL.md"));
+  skills_add_script(
+    (skill_name = "my-skill"),
+    (script_name = "validate.ts"),
+    (content = "...")
+  );
+  ```
+
+  ### Backward Compatibility
+
+  **Yes, with warnings.** Deprecated tools continue to function but emit console warnings directing users to OpenCode's native syntax. No breaking changes in this release.
+
+  Future major version (v1.0) will remove deprecated discovery tools entirely. Authoring tools remain permanent.
+
+  ### What This Means for Bundled Skills
+
+  Nothing changes. All 6 global skills ship with the plugin and are accessible via OpenCode's native `use skill <name>` syntax. They follow the Agent Skills spec and work identically whether loaded via deprecated plugin tools or native OpenCode.
+
+  The `global-skills/` directory remains the canonical source for our curated skill library.
+
+- [`4feebaf`](https://github.com/joelhooks/swarm-tools/commit/4feebafed61caa8e2e8729b44bd415d71afd6834) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🐝 LLM-Powered Compaction: The Swarm Remembers
+
+  > "The best way to predict the future is to invent it." — Alan Kay
+
+  Compaction just got smarter. Instead of static "here's what to preserve" instructions, the swarm now **generates dynamic continuation prompts** with actual state data.
+
+  **What changed:**
+
+  The `experimental.session.compacting` hook now uses a three-level fallback chain:
+
+  1. **LLM-Generated Prompt** (NEW) - Queries actual swarm state (cells, epics, subtasks), shells out to `opencode run -m <liteModel>` to generate a structured continuation prompt with real IDs, real status, real next actions
+  2. **Static Context** - Falls back to `SWARM_COMPACTION_CONTEXT` if LLM fails
+  3. **Detection Fallback** - For low-confidence swarm detection, injects `SWARM_DETECTION_FALLBACK`
+  4. **None** - No injection if no swarm evidence
+
+  **Progressive Enhancement:**
+
+  Uses OpenCode PR #5907's new `output.prompt` API when available:
+
+  ```typescript
+  if ("prompt" in output) {
+    output.prompt = llmGeneratedPrompt; // Replaces entire compaction prompt
+  } else {
+    output.context.push(llmGeneratedPrompt); // Old API fallback
+  }
+  ```
+
+  **New interfaces:**
+
+  - `SwarmStateSnapshot` - Structured state for LLM input
+  - `querySwarmState()` - Queries cells via swarm CLI
+  - `generateCompactionPrompt()` - Shells out to lite model (30s timeout)
+
+  **Why it matters:**
+
+  Before: "Hey, you should preserve swarm state" (agent has to figure out what that means)
+  After: "Here's epic bd-xyz with 3/5 subtasks done, bd-xyz.2 is blocked on auth, spawn bd-xyz.4 next"
+
+  The coordinator wakes up from compaction with **concrete data**, not instructions to go find data.
+
+  **Backward compatible:** Falls back gracefully on older OpenCode versions or LLM failures.
+
+- [`652fd16`](https://github.com/joelhooks/swarm-tools/commit/652fd16ff424eff92ebb3f5da0599caf676de2ce) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔭 Observability Stack MVP: See What Your Swarm Is Doing
+
+  > "You can't improve what you can't measure." — Peter Drucker
+
+  The swarm just got eyes. This release adds comprehensive observability for multi-agent coordination, answering the eternal question: "Why did my epic fail?"
+
+  ### What's New
+
+  **Structured Error Classes** (swarm-mail)
+
+  - `BaseSwarmError` with rich context: agent, bead_id, epic_id, timestamp, recent events
+  - Specialized errors: `ReservationError`, `CheckpointError`, `ValidationError`, `DecompositionError`
+  - Every error includes actionable suggestions for resolution
+  - Full `toJSON()` serialization for logging and debugging
+
+  **DEBUG Logging** (swarm-mail)
+
+  - `DEBUG=swarm:*` environment variable filtering
+  - 4 subsystems: `swarm:events`, `swarm:reservations`, `swarm:messages`, `swarm:checkpoints`
+  - Zero overhead when disabled
+
+  **swarm-db CLI** (swarm-mail)
+
+  ```bash
+  # Raw SQL queries (SELECT only, max 1000 rows)
+  swarm-db query "SELECT type, COUNT(*) FROM events GROUP BY type"
+
+  # Pre-built analytics
+  swarm-db analytics failed-decompositions --since 7d --format json
+
+  # List available analytics
+  swarm-db list
+  ```
+
+  **10 Pre-built Analytics Queries** (Four Golden Signals mapped)
+  | Query | What It Answers |
+  |-------|-----------------|
+  | `failed-decompositions` | Which strategies are failing? |
+  | `strategy-success-rates` | What's working? |
+  | `lock-contention` | Where are agents fighting over files? |
+  | `agent-activity` | Who's doing what? |
+  | `message-latency` | How fast is coordination? |
+  | `scope-violations` | Who's touching files they shouldn't? |
+  | `task-duration` | How long do tasks take? |
+  | `checkpoint-frequency` | Are agents checkpointing enough? |
+  | `recovery-success` | Do checkpoints actually help? |
+  | `human-feedback` | What are reviewers rejecting? |
+
+  **Agent-Facing Tools** (opencode-swarm-plugin)
+
+  ```typescript
+  // Query analytics programmatically
+  swarm_analytics({
+    query: "failed-decompositions",
+    since: "7d",
+    format: "summary",
+  });
+
+  // Raw SQL for power users (max 50 rows, context-safe)
+  swarm_query({ sql: "SELECT * FROM events WHERE type = 'task_blocked'" });
+
+  // Auto-diagnosis for debugging
+  swarm_diagnose({
+    epic_id: "bd-123",
+    include: ["blockers", "errors", "timeline"],
+  });
+
+  // Learning insights for feedback loops
+  swarm_insights({ scope: "epic", metrics: ["success_rate", "avg_duration"] });
+  ```
+
+  ### Why This Matters
+
+  Before: "The swarm failed. No idea why."
+  After: "Strategy X failed 80% of the time due to file conflicts. Switching to Y."
+
+  Event sourcing was already 80% of the solution. This release adds the diagnostic views to make that data actionable.
+
+  ### Test Coverage
+
+  - 588 tests passing
+  - 1214 assertions
+  - Full TDD: every feature started with a failing test
+
+- [`ca9936d`](https://github.com/joelhooks/swarm-tools/commit/ca9936d09b749449ef3c88fd3ec8b937f6ed7c29) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔬 Research Phase: Docs Before Decomposition
+
+  Swarm coordinators now gather documentation BEFORE breaking down tasks. No more workers fumbling through outdated API assumptions.
+
+  **What's New:**
+
+  - **swarm/researcher agent** - READ-ONLY doc gatherer that discovers tools, reads lockfiles, fetches version-specific docs, and stores findings in semantic-memory
+  - **Pre-decomposition research** - Coordinator analyzes task → identifies tech stack → spawns researchers → injects findings into shared_context
+  - **On-demand research for workers** - Workers can spawn researchers when hitting unknowns mid-task
+  - **`--check-upgrades` flag** - Compare installed vs latest versions from npm registry
+
+  **New Tools:**
+
+  | Tool                     | Purpose                                                     |
+  | ------------------------ | ----------------------------------------------------------- |
+  | `swarm_discover_tools`   | Runtime discovery of available doc tools (MCP, CLI, skills) |
+  | `swarm_get_versions`     | Parse lockfiles (npm/pnpm/yarn/bun) for installed versions  |
+  | `swarm_spawn_researcher` | Generate researcher prompt for Task tool                    |
+  | `swarm_research_phase`   | Manual trigger for research orchestration                   |
+
+  **Architecture:**
+
+  ```
+  Coordinator receives task
+      ↓
+  runResearchPhase(task, projectPath)
+      ↓
+    extractTechStack() → identify technologies
+    discoverDocTools() → find available tools
+    getInstalledVersions() → read lockfiles
+    Spawn researchers (parallel)
+    Collect summaries → shared_context
+      ↓
+  Normal decomposition with enriched context
+  ```
+
+  **Why This Matters:**
+
+  Workers now start with version-specific documentation instead of hallucinating APIs. Researchers store detailed findings in semantic-memory, so future agents don't repeat the research.
+
+### Patch Changes
+
+- Updated dependencies [[`652fd16`](https://github.com/joelhooks/swarm-tools/commit/652fd16ff424eff92ebb3f5da0599caf676de2ce)]:
+  - swarm-mail@1.4.0
+
+## 0.32.0
+
+### Minor Changes
+
+- [#54](https://github.com/joelhooks/swarm-tools/pull/54) [`358e18f`](https://github.com/joelhooks/swarm-tools/commit/358e18f0f7f18d03492ef16c2c1d3edd85c00101) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔍 Coordinator Review Gate + UBS Removal
+
+  > _"This asynchronous back and forth between submitter and reviewer can add days to the process of getting changes made. Do Code Reviews Promptly!"_
+  > — Sam Newman, _Building Microservices_
+
+  Two changes that make swarm coordination tighter:
+
+  ### Coordinator Review Tools
+
+  New tools for coordinators to review worker output before approval:
+
+  ```
+  ┌─────────────────────────────────────────────────────┐
+  │              COORDINATOR REVIEW FLOW                │
+  ├─────────────────────────────────────────────────────┤
+  │  1. Worker completes → sends completion message     │
+  │  2. Coordinator: swarm_review(task_id, files)       │
+  │     → Gets diff + epic context + review prompt      │
+  │  3. Coordinator reviews against epic goals          │
+  │  4. swarm_review_feedback(status, issues)           │
+  │     → approved: worker can finalize                 │
+  │     → needs_changes: worker gets feedback           │
+  │  5. 3-strike rule: 3 rejections = blocked           │
+  └─────────────────────────────────────────────────────┘
+  ```
+
+  **New tools:**
+
+  - `swarm_review` - Generate review prompt with epic context + git diff
+  - `swarm_review_feedback` - Send approval/rejection with structured issues
+
+  **Updated prompts:**
+
+  - Coordinator prompt now includes review checklist
+  - Worker prompt explains the review gate
+  - Skills updated with review patterns
+
+  ### UBS Scan Removed from swarm_complete
+
+  The `skip_ubs_scan` parameter is gone. UBS was already disabled in v0.31 for performance - this cleans up the vestigial code.
+
+  **Removed:**
+
+  - `skip_ubs_scan` parameter from schema
+  - `ubs_scan` deprecation object from output
+  - All UBS-related helper functions
+  - ~100 lines of dead code
+
+  **If you need UBS scanning:** Run it manually before commit:
+
+  ```bash
+  ubs scan src/
+  ```
+
+  ### CLI Improvements
+
+  The `swarm` CLI got smarter:
+
+  - Better error messages for missing dependencies
+  - Cleaner output formatting
+  - Improved help text
+
+### Patch Changes
+
+- [#54](https://github.com/joelhooks/swarm-tools/pull/54) [`358e18f`](https://github.com/joelhooks/swarm-tools/commit/358e18f0f7f18d03492ef16c2c1d3edd85c00101) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🧪 Integration Test Coverage: 0% → 95%
+
+  > _"Many characterization tests look like 'sunny day' tests. They don't test many special conditions; they just verify that particular behaviors are present. From their presence, we can infer that refactoring hasn't broken anything."_
+  > — Michael Feathers, _Working Effectively with Legacy Code_
+
+  We had a bug that broke ALL swarm tools:
+
+  ```
+  Error: [streams/store] dbOverride parameter is required for this function.
+  PGlite getDatabase() has been removed.
+  ```
+
+  **Why didn't tests catch it?** No integration tests exercised the full tool → store → DB path.
+
+  **Now they do.**
+
+  ```
+  ┌─────────────────────────────────────────────────────────────────┐
+  │              tool-adapter.integration.test.ts                   │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  20 tests | 75 assertions | 1.3s                                │
+  │                                                                 │
+  │  ✅ swarmmail_* tools (6 tests)                                 │
+  │  ✅ hive_* tools (7 tests)                                      │
+  │  ✅ swarm_progress, swarm_status (2 tests)                      │
+  │  ✅ swarm_broadcast, swarm_checkpoint (2 tests)                 │
+  │  ✅ semantic_memory_store, semantic_memory_find (2 tests)       │
+  │  ✅ Smoke test - 9 tools in sequence (1 test)                   │
+  └─────────────────────────────────────────────────────────────────┘
+  ```
+
+  ### What's Tested
+
+  Each test calls `tool.execute()` and verifies:
+
+  1. No "dbOverride required" error (the bug symptom)
+  2. Tool returns expected structure
+  3. Full path works: tool → store → DB → response
+
+  ### The Smoke Test
+
+  Runs 9 tools in sequence to catch interaction bugs:
+
+  ```
+  swarmmail_init → hive_create → swarmmail_reserve → swarm_progress
+  → semantic_memory_store → semantic_memory_find → swarmmail_send
+  → hive_close → swarmmail_release
+  ```
+
+  If ANY step throws "dbOverride required", the test fails.
+
+  ### Also Fixed
+
+  - **Auto-adapter creation** in store.ts - functions now auto-create adapters when not provided
+  - **Exported `clearAdapterCache()`** for test isolation
+  - **Migrated test files** from old `getDatabase()` to adapter pattern
+
+  ### Mandatory Coordinator Review Loop
+
+  Added `COORDINATOR_POST_WORKER_CHECKLIST` constant and `post_completion_instructions` field to `swarm_spawn_subtask`. Coordinators now get explicit instructions to review worker output before spawning the next worker.
+
+  The "dbOverride required" bug **cannot recur undetected**.
+
+- Updated dependencies [[`358e18f`](https://github.com/joelhooks/swarm-tools/commit/358e18f0f7f18d03492ef16c2c1d3edd85c00101), [`358e18f`](https://github.com/joelhooks/swarm-tools/commit/358e18f0f7f18d03492ef16c2c1d3edd85c00101), [`358e18f`](https://github.com/joelhooks/swarm-tools/commit/358e18f0f7f18d03492ef16c2c1d3edd85c00101), [`358e18f`](https://github.com/joelhooks/swarm-tools/commit/358e18f0f7f18d03492ef16c2c1d3edd85c00101)]:
+  - swarm-mail@1.3.0
+
 ## 0.31.7
 
 ### Patch Changes