opencode-swarm-plugin 0.12.30 → 0.13.0

package/.opencode/skills/tdd/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: tdd
+description: "Test-Driven Development workflow with RED-GREEN-REFACTOR, lore from Kent Beck, Michael Feathers, and Ousterhout's counterpoint"
+tags:
+  - testing
+  - workflow
+  - methodology
+  - tdd
+---
+
+# Test-Driven Development (TDD)
+
+## The Rhythm: RED-GREEN-REFACTOR
+
+```
+1. RED    - Write failing test first (define expected behavior)
+2. GREEN  - Minimal implementation to pass (don't over-engineer)
+3. REFACTOR - Clean up, remove duplication, run tests again
+```
+
+## Why TDD Works (The Lore)
+
+### Kent Beck (Test-Driven Development by Example)
+
+> "The act of writing a unit test is more an act of design than verification."
+
+- Tests become executable documentation of intent
+- "Fake it til you make it" - start with hardcoded values, generalize
+- Small steps reduce debugging time
+- Confidence to refactor comes from test coverage
+
+### Michael Feathers (Working Effectively with Legacy Code)
+
+> "The most powerful feature-addition technique I know of is test-driven development."
+
+- TDD works in both OO and procedural code
+- Writing tests first forces you to think about interfaces
+- Tests are the safety net that enables aggressive refactoring
+- Legacy code = code without tests
+
+### Martin Fowler (Refactoring)
+
+> "Kent Beck baked this habit of writing the test first into a technique called Test-Driven Development."
+
+- TDD relies on short cycles
+- Tests enable refactoring
+- Refactoring becomes safe - tests catch regressions instantly
+
+## The Counterpoint: Know When to Break the Rule
+
+### John Ousterhout (A Philosophy of Software Design)
+
+> "The problem with test-driven development is that it focuses attention on getting specific features working, rather than finding the best design."
+
+**When TDD can hurt:**
+
+- Can lead to tactical programming (feature-focused, not design-focused)
+- May produce code that's easy to test but hard to understand
+- Risk of over-testing implementation details
+
+**The balance:**
+
+- For exploratory/architectural work, design first, then add tests
+- Don't let tests drive you into a corner
+- Step back periodically to evaluate overall design
+
+## When to Use TDD
+
+✅ **Use TDD for:**
+
+- New features with clear requirements
+- Bug fixes (write test that reproduces bug first)
+- Refactoring existing code (add characterization tests first)
+- API design (tests reveal ergonomics)
+- Any code that will be maintained long-term
+
+❌ **Skip TDD for:**
+
+- Exploratory spikes (but add tests after if keeping the code)
+- Emergency hotfixes (but add tests immediately after)
+- Pure UI/styling changes
+- One-off scripts
+- Throwaway prototypes
+
+## The TDD Workflow
+
+```bash
+# 1. Write test, watch it fail
+bun test src/thing.test.ts  # RED - test fails
+
+# 2. Implement minimal code to pass
+bun test src/thing.test.ts  # GREEN - test passes
+
+# 3. Refactor, tests still pass
+bun test src/thing.test.ts  # GREEN - still passing
+
+# 4. Repeat for next behavior
+```
+
+## TDD Patterns
+
+### Start with the Assertion
+
+Write the assertion first, then work backwards:
+
+```typescript
+// Start here
+expect(result).toBe(42);
+
+// Then figure out what 'result' is
+const result = calculate(input);
+
+// Then figure out what 'input' is
+const input = { value: 21 };
+```
+
+### Triangulation
+
+Use multiple examples to drive generalization:
+
+```typescript
+it("doubles 2", () => expect(double(2)).toBe(4));
+it("doubles 3", () => expect(double(3)).toBe(6));
+// Now you MUST implement the general solution
+```
+
+### Obvious Implementation
+
+When the solution is obvious, just write it:
+
+```typescript
+function add(a: number, b: number): number {
+  return a + b; // Don't fake this
+}
+```
+
+### Fake It Til You Make It
+
+When unsure, start with hardcoded values:
+
+```typescript
+// First pass
+function fibonacci(n: number): number {
+  return 1; // Passes for n=1
+}
+
+// Add test for n=2, then generalize
+```
+
+## Testing Pyramid
+
+```
+        /\
+       /  \     E2E (few)
+      /----\
+     /      \   Integration (some)
+    /--------\
+   /          \ Unit (many)
+  --------------
+```
+
+- **Unit tests**: Fast, isolated, test one thing
+- **Integration tests**: Test component interactions
+- **E2E tests**: Test full user flows (expensive, use sparingly)
+
+## Common TDD Mistakes
+
+1. **Writing too many tests at once** - One failing test at a time
+2. **Testing implementation, not behavior** - Test what, not how
+3. **Skipping the refactor step** - Technical debt accumulates
+4. **Over-mocking** - Don't mock what you don't own
+5. **Testing private methods** - Test through public interface
+
+## Integration with Beads
+
+When working on a bead:
+
+1. Start bead: `beads_start(id="bd-123")`
+2. Write failing test for the requirement
+3. Implement to pass
+4. Refactor
+5. Close bead: `beads_close(id="bd-123", reason="Done: tests passing")`

package/README.md

@@ -36,11 +36,11 @@ The setup wizard handles everything:
 ◆  OpenCode
 ◆  Beads
 ◆  Go
-▲  Agent Mail (optional)
+▲  Swarm Mail (optional)
 ▲  Redis (optional)
 │
 ◆  Install optional dependencies?
-│  ◻ Agent Mail - Multi-agent coordination
+│  ◻ Swarm Mail - Multi-agent coordination
 │  ◻ Redis - Rate limiting
 │
 ◇  Setting up OpenCode integration...
@@ -271,16 +271,16 @@ What NOT to do...
 
 ## Dependencies
 
-| Dependency                                                                                             | Purpose                                                      | Required |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
-| [OpenCode](https://opencode.ai)                                                                        | Plugin host                                                  | Yes      |
-| [Beads](https://github.com/steveyegge/beads)                                                           | Git-backed issue tracking                                    | Yes      |
-| [Go](https://go.dev)                                                                                   | Required for Agent Mail                                      | No       |
-| [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail)                                  | Multi-agent coordination, file reservations                  | No       |
-| [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions                        | No       |
-| [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner)                | Pre-completion bug scanning using AI-powered static analysis | No       |
-| [semantic-memory](https://github.com/joelhooks/semantic-memory)                                        | Learning persistence                                         | No       |
-| [Redis](https://redis.io)                                                                              | Rate limiting (SQLite fallback available)                    | No       |
+| Dependency                                                                                             | Purpose                                                                                                | Required |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | -------- |
+| [OpenCode](https://opencode.ai)                                                                        | Plugin host                                                                                            | Yes      |
+| [Beads](https://github.com/steveyegge/beads)                                                           | Git-backed issue tracking                                                                              | Yes      |
+| [Go](https://go.dev)                                                                                   | Required for Swarm Mail                                                                                | No       |
+| [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       |
+| [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions                                                                  | No       |
+| [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner)                | Pre-completion bug scanning using AI-powered static analysis                                           | No       |
+| [semantic-memory](https://github.com/joelhooks/semantic-memory)                                        | Learning persistence                                                                                   | No       |
+| [Redis](https://redis.io)                                                                              | Rate limiting (SQLite fallback available)                                                              | No       |
 
 All dependencies are checked and can be installed via `swarm setup`.
 
@@ -298,12 +298,14 @@ curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_sca
 curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode
 ```
 
-**MCP Agent Mail** - Multi-agent coordination and file reservations:
+**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:
 
 ```bash
 curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh" | bash -s -- --yes
 ```
 
+> **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.
+
 ## Tools Reference
 
 ### Swarm
@@ -315,7 +317,7 @@ curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/m
 | `swarm_plan_prompt`            | Generate strategy-specific planning prompt with CASS history              |
 | `swarm_decompose`              | Generate decomposition prompt                                             |
 | `swarm_validate_decomposition` | Validate response, detect file conflicts                                  |
-| `swarm_spawn_subtask`          | Generate worker agent prompt with Agent Mail/beads instructions           |
+| `swarm_spawn_subtask`          | Generate worker agent prompt with Swarm Mail/beads instructions           |
 | `swarm_status`                 | Get swarm progress by epic ID                                             |
 | `swarm_progress`               | Report subtask progress to coordinator                                    |
 | `swarm_complete`               | Complete subtask - runs UBS (Ultimate Bug Scanner), releases reservations |
@@ -333,9 +335,22 @@ curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/m
 | `beads_start`       | Mark bead as in-progress                       |
 | `beads_ready`       | Get next unblocked bead                        |
 | `beads_sync`        | Sync to git and push                           |
-| `beads_link_thread` | Link bead to Agent Mail thread                 |
+| `beads_link_thread` | Link bead to Swarm Mail thread                 |
+
+### Swarm Mail (Embedded - Primary)
+
+| Tool                     | Description                                   |
+| ------------------------ | --------------------------------------------- |
+| `swarmmail_init`         | Initialize session, register agent            |
+| `swarmmail_send`         | Send message to agents                        |
+| `swarmmail_inbox`        | Fetch inbox (max 5, no bodies - context safe) |
+| `swarmmail_read_message` | Fetch single message body by ID               |
+| `swarmmail_reserve`      | Reserve file paths for exclusive editing      |
+| `swarmmail_release`      | Release file reservations                     |
+| `swarmmail_ack`          | Acknowledge message                           |
+| `swarmmail_health`       | Check embedded database health                |
 
-### Agent Mail
+### Agent Mail (Legacy MCP - Optional)
 
 | Tool                         | Description                                    |
 | ---------------------------- | ---------------------------------------------- |
@@ -348,7 +363,140 @@ curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/m
 | `agentmail_release`          | Release file reservations                      |
 | `agentmail_ack`              | Acknowledge message                            |
 | `agentmail_search`           | Search messages by keyword                     |
-| `agentmail_health`           | Check if Agent Mail server is running          |
+| `agentmail_health`           | Check if MCP Agent Mail server is running      |
+
+## Event-Sourced Architecture (Embedded)
+
+> **🙏 Built on the shoulders of giants**
+>
+> The Swarm Mail system is deeply inspired by and builds upon [**MCP Agent Mail**](https://github.com/Dicklesworthstone/mcp_agent_mail) by [@Dicklesworthstone](https://github.com/Dicklesworthstone). The original MCP Agent Mail pioneered multi-agent coordination patterns including file reservations, thread-based messaging, and agent registration - concepts that form the foundation of this embedded implementation.
+>
+> If you need a production-ready, battle-tested solution with a full Go server, **use MCP Agent Mail directly**. This embedded version is an experimental alternative that trades the external server for in-process PGLite, optimized for single-machine development workflows.
+>
+> **Key contributions from MCP Agent Mail:**
+>
+> - File reservation protocol with conflict detection
+> - Agent registration and heartbeat patterns
+> - Thread-based message organization
+> - Importance levels and acknowledgment tracking
+>
+> Thank you to the MCP Agent Mail team for open-sourcing such a well-designed system.
+
+The plugin includes an embedded event-sourced Swarm Mail implementation as an alternative to the external MCP server. This provides the same multi-agent coordination capabilities without requiring a separate server process.
+
+### Architecture Comparison
+
+**MCP-based (external):**
+
+```
+plugin tools → HTTP → MCP Server (Go process) → SQLite
+```
+
+**Event-sourced (embedded):**
+
+```
+plugin tools → streams/agent-mail.ts → streams/store.ts → PGLite (in-process)
+                                             ↓
+                                    streams/projections.ts
+                                             ↓
+                              Materialized views (agents, messages, reservations)
+                                             ↓
+                                        Fast reads
+```
+
+### Architecture Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Plugin Tools Layer                        │
+│  (agentmail_init, agentmail_send, agentmail_reserve, etc.)      │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     streams/agent-mail.ts                        │
+│                    (High-level API wrapper)                      │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       streams/events.ts                          │
+│        11 event types: agent_registered, message_sent,          │
+│     file_reserved, message_read, message_acked, etc.            │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        streams/store.ts                          │
+│              Append-only event log (PGLite storage)             │
+│       appendEvent() • readEvents() • replayEvents()             │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     streams/projections.ts                       │
+│                  Build materialized views from events            │
+│    getAgents() • getInbox() • getActiveReservations()           │
+│              checkConflicts() • threadStats()                    │
+└─────────────────────────────┬────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              Materialized Tables (Derived State)                │
+│     agents • messages • reservations • message_reads            │
+│              (Rebuilt by replaying event log)                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Module Descriptions
+
+| Module                     | Responsibility                                                                                     |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| **streams/events.ts**      | Zod schemas for 11 event types (agent_registered, message_sent, file_reserved, task_progress, etc) |
+| **streams/store.ts**       | Append-only event log with PGLite backend (appendEvent, readEvents, replayEvents)                  |
+| **streams/projections.ts** | Materialize views from events (getAgents, getInbox, checkConflicts, threadStats)                   |
+| **streams/agent-mail.ts**  | High-level API matching MCP interface (initAgent, sendAgentMessage, reserveAgentFiles)             |
+| **streams/debug.ts**       | Debugging utilities (debugEvents, debugAgent, debugMessage, inspectState)                          |
+
+### Key Benefits
+
+- **No external dependencies** - Runs in-process with PGLite (Postgres compiled to WASM)
+- **Full audit trail** - Every state change is an immutable event
+- **Crash recovery** - Rebuild state by replaying events from log
+- **Time-travel debugging** - Replay events up to any point in time
+- **Testability** - 127 tests passing across streams module
+- **Durable Streams protocol** - Inspired by Electric SQL's event sourcing patterns
+
+### Event Types
+
+The system emits 11 event types tracked in `streams/events.ts`:
+
+| Event              | Triggered By                          |
+| ------------------ | ------------------------------------- |
+| `agent_registered` | Agent initialization                  |
+| `message_sent`     | Sending inter-agent message           |
+| `file_reserved`    | Reserving files for exclusive editing |
+| `file_released`    | Releasing file reservations           |
+| `message_read`     | Reading a message                     |
+| `message_acked`    | Acknowledging a message               |
+| `task_started`     | Starting work on a bead               |
+| `task_progress`    | Reporting progress update             |
+| `task_completed`   | Completing a bead                     |
+| `task_blocked`     | Marking a task as blocked             |
+| `agent_active`     | Agent heartbeat/keep-alive            |
+
+### Materialized Views
+
+Projections build these derived tables from the event log:
+
+| View            | Contains                                               |
+| --------------- | ------------------------------------------------------ |
+| `agents`        | Registered agents with metadata and last activity      |
+| `messages`      | All inter-agent messages with thread/importance        |
+| `reservations`  | Active file reservations with TTL and exclusivity flag |
+| `message_reads` | Read receipts for message tracking                     |
+
+State is always derived - delete the tables and replay events to rebuild.
 
 ### Structured Output
 

package/bin/swarm.ts

@@ -497,23 +497,65 @@ $ARGUMENTS
 
 ## Workflow
 
-1. **Initialize**: \`agentmail_init\` with project_path and task_description
-2. **Decompose**: Use \`swarm_select_strategy\` then \`swarm_plan_prompt\` to break down the task
-3. **Create beads**: \`beads_create_epic\` with subtasks and file assignments
-4. **Reserve files**: \`agentmail_reserve\` for each subtask's files
-5. **Spawn agents**: Use Task tool with \`swarm_spawn_subtask\` prompts
-6. **Monitor**: Check \`agentmail_inbox\` for progress, use \`agentmail_summarize_thread\` for overview
-7. **Complete**: \`swarm_complete\` when done, then \`beads_sync\` to push
-
-## Strategy Selection
-
-| Strategy      | Best For                | Keywords                               |
-| ------------- | ----------------------- | -------------------------------------- |
-| file-based    | Refactoring, migrations | refactor, migrate, rename, update all  |
-| feature-based | New features            | add, implement, build, create, feature |
-| risk-based    | Bug fixes, security     | fix, bug, security, critical, urgent   |
-
-Begin decomposition now.
+### 1. Initialize
+\`agentmail_init(project_path="$PWD", task_description="Swarm: <task>")\`
+
+### 2. Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings into shared_context for workers.
+
+### 3. Decompose
+\`\`\`
+swarm_select_strategy(task="<task>")
+swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")
+swarm_validate_decomposition(response="<BeadTree JSON>")
+\`\`\`
+
+### 4. Create Beads
+\`beads_create_epic(epic_title="<task>", subtasks=[...])\`
+
+### 5. Reserve Files
+\`agentmail_reserve(paths=[...], reason="<bead-id>: <desc>")\`
+
+### 6. Spawn Agents (ALL in single message)
+\`\`\`
+swarm_spawn_subtask(bead_id, epic_id, subtask_title, files, shared_context)
+Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+### 7. Monitor
+\`\`\`
+swarm_status(epic_id, project_key)
+agentmail_inbox()
+\`\`\`
+
+Intervene if: blocked >5min, file conflicts, scope creep.
+
+### 8. Complete
+\`\`\`
+swarm_complete(...)
+beads_sync()
+\`\`\`
+
+## Strategy Reference
+
+| Strategy       | Best For                 | Keywords                               |
+| -------------- | ------------------------ | -------------------------------------- |
+| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all  |
+| feature-based  | New features             | add, implement, build, create, feature |
+| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |
+| research-based | Investigation, discovery | research, investigate, explore, learn  |
+
+Begin with knowledge gathering now.
 `;
 
 const getPlannerAgent = (model: string) => `---
@@ -526,12 +568,30 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 
 ## Workflow
 
-1. Call \`swarm_select_strategy\` to analyze the task
-2. Call \`swarm_plan_prompt\` to get strategy-specific guidance
-3. Create a BeadTree following the guidelines
-4. Return ONLY valid JSON - no markdown, no explanation
+### 1. Knowledge Gathering (MANDATORY)
 
-## Output Format
+**Before decomposing, query ALL knowledge sources:**
+
+\`\`\`
+semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
+cass_search(query="<task description>", limit=5)         # Similar past tasks  
+pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
+skills_list()                                            # Available skills
+\`\`\`
+
+Synthesize findings - note relevant patterns, past approaches, and skills to recommend.
+
+### 2. Strategy Selection
+
+\`swarm_select_strategy(task="<task>")\`
+
+### 3. Generate Plan
+
+\`swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")\`
+
+### 4. Output BeadTree
+
+Return ONLY valid JSON - no markdown, no explanation:
 
 \`\`\`json
 {
@@ -539,7 +599,7 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
   "subtasks": [
     {
       "title": "...",
-      "description": "...",
+      "description": "Include relevant context from knowledge gathering",
       "files": ["src/..."],
       "dependencies": [],
       "estimated_complexity": 2
@@ -554,6 +614,7 @@ You are a swarm planner. Decompose tasks into optimal parallel subtasks.
 - No file overlap between subtasks
 - Include tests with the code they test
 - Order by dependency (if B needs A, A comes first)
+- Pass synthesized knowledge to workers via subtask descriptions
 `;
 
 const getWorkerAgent = (model: string) => `---
@@ -564,17 +625,45 @@ model: ${model}
 
 You are a swarm worker agent. Execute your assigned subtask efficiently.
 
+## Context
+
+Your prompt includes shared_context from the coordinator's knowledge gathering:
+- Relevant patterns from pdf-brain
+- Similar past approaches from CASS
+- Project-specific learnings from semantic-memory
+
+**Use this context** - it contains patterns and prior art relevant to your task.
+
+## Workflow
+
+1. **Read** assigned files to understand current state
+2. **Check skills** if you need domain guidance: \`skills_use(name="<relevant-skill>")\`
+3. **Implement** changes following patterns from shared_context
+4. **Verify** (typecheck, lint if applicable)
+5. **Complete** with \`swarm_complete\`
+
 ## Rules
+
 - Focus ONLY on your assigned files
-- Report progress via Agent Mail
-- Use beads_update to track status
-- Call swarm_complete when done
+- Report blockers immediately via Agent Mail (don't spin)
+- Use beads_update if blocked
+- Call swarm_complete when done - it handles bead closure and file release
 
-## Workflow
-1. Read assigned files
-2. Implement changes
-3. Verify (typecheck if applicable)
-4. Report completion
+## Communication
+
+\`\`\`
+agentmail_send(
+  to=["coordinator"],
+  subject="Progress/Blocker",
+  body="...",
+  thread_id="<epic_id>"
+)
+\`\`\`
+
+## Learning
+
+If you discover a reusable pattern worth preserving:
+\`semantic-memory_store(information="<pattern + why it matters>")\`
 `;
 
 // ============================================================================