opencode-swarm-plugin 0.32.0 → 0.34.0

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).
+
+### Historical Context (CASS)
 
-## Features
+Queries past AI sessions for similar decompositions:
+
+```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
+```
 
-- **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 ✅)
+### Bug Scanning (UBS)
 
-## Usage
+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,45 @@ 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
+## What's New in v0.33
 
-| Dependency | Purpose |
-|------------|---------|
-| [OpenCode](https://opencode.ai) | AI coding agent (the plugin runs inside OpenCode) |
+- **Pino logging infrastructure** - Structured JSON logs with daily rotation to `~/.config/swarm-tools/logs/`
+- **Compaction hook instrumented** - 14 log points across all phases (START, GATHER, RENDER, DECIDE, COMPLETE)
+- **`swarm log` CLI** - Query/tail logs with module, level, and time filters
+- **Analytics queries** - 5 pre-built queries based on Four Golden Signals (latency, traffic, errors, saturation, conflicts)
 
-### Required for Semantic Memory
+### v0.32
 
-| Dependency | Purpose | Install |
-|------------|---------|---------|
-| [Ollama](https://ollama.ai) | Embedding model for semantic memory | `brew install ollama && ollama serve & && ollama pull mxbai-embed-large` |
+- **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`
 
-### 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 |
-
-> **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 +231,50 @@ 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
+### Logging & Observability
 
-### Planned Features
+Structured Pino logging with daily rotation:
 
-- **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
+```bash
+# Enable pretty logging during development
+SWARM_LOG_PRETTY=1 opencode
+
+# Query logs
+swarm log                      # Tail recent logs
+swarm log compaction           # Filter by module
+swarm log --level warn         # Filter by level (warn+)
+swarm log --since 1h           # Last hour
+swarm log --json | jq          # Pipe to jq for analysis
+```
 
-### Experimental
+**Log files:** `~/.config/swarm-tools/logs/`
+- `swarm.1log`, `swarm.2log`, ... (main logs)
+- `compaction.1log`, ... (module-specific)
+- Daily rotation, 14-day retention
 
-- **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
+---
+
+## Further Reading
+
+- **[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
+
+> *"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