opencode-swarm-plugin 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,265 @@
 # 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

package/README.md

@@ -1,6 +1,6 @@
 # opencode-swarm-plugin
 
-OpenCode plugin for multi-agent swarm coordination with learning capabilities.
+**Multi-agent swarm coordination for OpenCode - break tasks into parallel subtasks, spawn worker agents, learn from outcomes.**
 
 **🌐 Website:** [swarmtools.ai](https://swarmtools.ai)  
 **📚 Full Documentation:** [swarmtools.ai/docs](https://swarmtools.ai/docs)
@@ -14,38 +14,109 @@ OpenCode plugin for multi-agent swarm coordination with learning capabilities.
  ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝
 ```
 
-## Install
+## Quickstart (<2 minutes)
+
+### 1. Install
 
 ```bash
-# Install
 npm install -g opencode-swarm-plugin@latest
 swarm setup
+```
+
+### 2. Initialize in Your Project
+
+```bash
+cd your-project
+swarm init
+```
+
+### 3. Run Your First Swarm
+
+```bash
+# Inside OpenCode
+/swarm "Add user authentication with OAuth"
+```
 
-# For semantic memory (optional but recommended)
+**What happens:**
+- Task decomposed into parallel subtasks (coordinator queries past similar tasks)
+- Worker agents spawn with file reservations
+- Progress tracked with auto-checkpoints at 25/50/75%
+- Completion runs bug scans, releases file locks, records learnings
+
+Done. You're swarming.
+
+---
+
+## Optional But Recommended
+
+### Semantic Memory (for pattern learning)
+
+```bash
 brew install ollama
 ollama serve &
 ollama pull mxbai-embed-large
 ```
 
-> *"High-variability sequencing of whole-task problems."*  
-> — 4C/ID Instructional Design Model
+Without Ollama, memory falls back to full-text search (still works, just less semantic).
 
-## Features
+### Historical Context (CASS)
 
-- **Swarm Coordination** - Break tasks into parallel subtasks, spawn worker agents
-- **Hive Integration** - Git-backed work item 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
-- **Checkpoint & Recovery** - Auto-checkpoint at 25/50/75%, survive context death (9 integration tests ✅)
+Queries past AI sessions for similar decompositions:
 
-## Usage
+```bash
+git clone https://github.com/Dicklesworthstone/coding_agent_session_search
+cd coding_agent_session_search
+pip install -e .
+cass index  # Run periodically to index new sessions
+```
+
+### Bug Scanning (UBS)
+
+Auto-runs on subtask completion:
 
 ```bash
-/swarm "Add user authentication with OAuth"
+git clone https://github.com/Dicklesworthstone/ultimate_bug_scanner
+cd ultimate_bug_scanner
+pip install -e .
 ```
 
-## Tools Provided
+Check status: `swarm doctor`
+
+---
+
+## Core Concepts
+
+### The Hive 🐝
+
+Work items (cells) stored in `.hive/` and synced to git. Each cell is a unit of work - think GitHub issue but local-first.
+
+**Cell IDs:** Project-prefixed for clarity (e.g., `swarm-mail-lf2p4u-abc123` not generic `bd-xxx`)
+
+### The Swarm
+
+Parallel agents coordinated via **Swarm Mail** (message passing + file reservations). Coordinator spawns workers → workers reserve files → do work → report progress → complete with verification.
+
+### Learning
+
+- **Pattern maturity** tracks what decomposition strategies work
+- **Confidence decay** fades unreliable patterns (90-day half-life)
+- **Anti-pattern inversion** auto-marks failing approaches to avoid
+- **Outcome tracking** learns from speed, errors, retries
+
+### Checkpoint & Recovery
+
+Auto-saves progress at milestones. Survives context death or crashes. Data stored in embedded libSQL (no external DB needed).
+
+**When checkpoints happen:**
+- Auto at 25%, 50%, 75% progress
+- Before risky operations (via `swarm_checkpoint`)
+- On errors (captures error context for recovery)
+
+**Recovery:** `swarm_recover(project_key, epic_id)` returns full context to resume work.
+
+---
+
+## Tools Reference
 
 ### Hive (Work Item Tracking)
 
@@ -73,31 +144,21 @@ ollama pull mxbai-embed-large
 | `swarmmail_reserve`      | Reserve files for exclusive edit |
 | `swarmmail_release`      | Release reservations             |
 
-### Swarm (Task Orchestration)
+### Swarm 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_progress`               | Report subtask progress                         |
 | `swarm_complete`               | Complete subtask (releases reservations)        |
-| `swarm_record_outcome`         | Record outcome for learning                     |
 | `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)        |
-| `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                  |
+| `swarm_recover`                | Resume from checkpoint                          |
+| `swarm_review`                 | Generate review prompt for coordinator          |
+| `swarm_review_feedback`        | Send approval/rejection to worker (3-strike)    |
 
 ### Skills (Knowledge Injection)
 
@@ -108,73 +169,7 @@ ollama pull mxbai-embed-large
 | `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 libSQL:
-
-```typescript
-// Stored in system temp directory (no external database needed)
-{
-  epic_id: "hv-123",
-  cell_id: "hv-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",
-  cell_id: "hv-123.1",
-  epic_id: "hv-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: "hv-123"
-})
-// Returns:
-// {
-//   found: true,
-//   context: { epic_id, cell_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/`:
-
+**Bundled skills:**
 - **testing-patterns** - 25 dependency-breaking techniques, characterization tests
 - **swarm-coordination** - Multi-agent decomposition, file reservations
 - **cli-builder** - Argument parsing, help text, subcommands
@@ -182,85 +177,38 @@ Located in `global-skills/`:
 - **learning-systems** - Confidence decay, pattern maturity
 - **skill-creator** - Meta-skill for creating new skills
 
-## Architecture
-
-```
-src/
-├── hive.ts            # Hive integration (work item tracking)
-├── 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
-```
-
-## Dependencies
-
-### Required
-
-| Dependency | Purpose |
-|------------|---------|
-| [OpenCode](https://opencode.ai) | AI coding agent (the plugin runs inside OpenCode) |
-
-### Required for Semantic Memory
-
-| Dependency | Purpose | Install |
-|------------|---------|---------|
-| [Ollama](https://ollama.ai) | Embedding model for semantic memory | `brew install ollama && ollama serve & && ollama pull mxbai-embed-large` |
+---
 
-### Optional (Highly Recommended)
+## What's New in v0.32
 
-These tools significantly enhance the swarm experience:
+- **libSQL storage** (embedded SQLite) replaced PGLite - no external DB needed
+- **95% integration test coverage** - checkpoint/recovery proven with 9 tests
+- **Coordinator review gate** - `swarm_review` + `swarm_review_feedback` with 3-strike rule
+- **Smart ID resolution** - partial hashes work like git (`mjhgw0g` matches `opencode-swarm-monorepo-lf2p4u-mjhgw0ggt00`)
+- **Auto-sync at key events** - no more forgotten `hive_sync` calls
+- **Project-prefixed cell IDs** - `swarm-mail-xxx` instead of generic `bd-xxx`
 
-| 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 |
+---
 
-> **Note:** Semantic memory is now embedded in the plugin. No separate installation needed - just install Ollama for vector embeddings.
-
-#### Installing CASS
+## Architecture
 
-```bash
-# Clone and install
-git clone https://github.com/Dicklesworthstone/coding_agent_session_search
-cd coding_agent_session_search
-pip install -e .
+Built on [swarm-mail](../swarm-mail) event sourcing primitives. Data stored in libSQL (embedded SQLite).
 
-# 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 .
+src/
+├── hive.ts                # Work item tracking integration
+├── swarm-mail.ts          # Agent coordination tools
+├── swarm-orchestrate.ts   # Coordinator logic (spawns workers)
+├── swarm-decompose.ts     # Task decomposition strategies
+├── swarm-review.ts        # Review gate for completed work
+├── skills.ts              # Knowledge injection system
+├── learning.ts            # Pattern maturity, outcomes
+├── anti-patterns.ts       # Anti-pattern detection
+├── structured.ts          # JSON parsing utilities
+└── schemas/               # Zod validation schemas
 ```
 
-**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** - Run manually on code to catch bugs before commit. Not integrated into swarm workflow but recommended for pre-commit validation.
-- **Ollama** - Enables vector similarity search for semantic memory. Without it, memory falls back to full-text search (still functional, less semantic).
-
-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
-- [zod](https://zod.dev) - Schema validation
+---
 
 ## Development
 
@@ -276,32 +224,29 @@ bun test
 bun run typecheck
 ```
 
+---
+
 ## CLI
 
 ```bash
 swarm setup     # Install and configure
-swarm doctor    # Check dependencies
+swarm doctor    # Check dependencies (CASS, UBS, Ollama)
 swarm init      # Initialize hive 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
+## Further Reading
 
-### Experimental
+- **[Full Docs](https://swarmtools.ai/docs)** - Deep dives, patterns, best practices
+- **[swarm-mail Package](../swarm-mail)** - Event sourcing primitives, database layer
+- **[AGENTS.md](../../AGENTS.md)** - Monorepo guide, testing strategy, TDD workflow
 
-- **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
+> *"High-variability sequencing of whole-task problems."*  
+> — 4C/ID Instructional Design Model
 
-See [swarmtools.ai/docs](https://swarmtools.ai/docs) for latest updates and detailed guides.
+---
 
 ## License