opencode-swarm-plugin 0.26.1 → 0.27.0

package/docs/planning/ADR-007-swarm-enhancements-worktree-review.md

@@ -0,0 +1,168 @@
+# ADR-007: Swarm Enhancements - Worktree Isolation + Structured Review
+
+## Status
+
+Proposed
+
+## Context
+
+After reviewing [nexxeln/opencode-config](https://github.com/nexxeln/opencode-config), we identified several patterns that would strengthen our swarm coordination:
+
+1. **Git worktree isolation** - Each worker gets a complete isolated copy of the repo
+2. **Structured review loop** - Workers must pass review before completion
+3. **Retry options on abort** - Clean recovery paths when things go wrong
+
+Currently our swarm uses:
+- **File reservations** via Swarm Mail for conflict prevention
+- **UBS scan** on completion for bug detection
+- **Manual cleanup** on abort
+
+## Decision
+
+### 1. Optional Worktree Isolation Mode
+
+Add `isolation` parameter to swarm initialization:
+
+```typescript
+swarm_init({
+  task: "Large refactor across 50 files",
+  isolation: "worktree"  // or "reservation" (default)
+})
+```
+
+**When to use worktrees:**
+- Large refactors touching many files
+- High risk of merge conflicts
+- Need complete isolation (different node_modules, etc.)
+
+**When to use reservations (default):**
+- Most swarm tasks
+- Quick parallel work
+- Lower overhead
+
+**Worktree lifecycle:**
+```
+swarm_worktree_create(task_id) → /path/to/worktree
+  ↓
+worker does work in worktree
+  ↓
+swarm_worktree_merge(task_id)  → cherry-pick commit to main
+  ↓
+swarm_worktree_cleanup(task_id) → remove worktree
+```
+
+**On abort:** Hard reset main to start commit, delete all worktrees.
+
+### 2. Structured Review Step
+
+The coordinator reviews worker output before marking complete. This replaces the current "trust but verify with UBS" approach.
+
+**Review flow:**
+```
+worker completes → coordinator reviews → approved/needs_changes
+                                              ↓
+                                    if needs_changes: worker fixes (max 3 attempts)
+                                              ↓
+                                    if approved: mark complete
+```
+
+**Review prompt includes:**
+- Epic goal (the big picture)
+- Task requirements
+- What completed tasks this builds on (dependency context)
+- What future tasks depend on this (downstream context)
+- The actual code changes
+
+**Why coordinator reviews (not separate reviewer agent):**
+- Coordinator already has full epic context loaded
+- Avoids spawning another agent just for review
+- Keeps the feedback loop tight
+- Coordinator can make judgment calls about "good enough"
+
+**Review criteria:**
+1. Does it fulfill the task requirements?
+2. Does it serve the epic goal?
+3. Will downstream tasks be able to use it?
+4. Are there critical bugs? (UBS scan still runs)
+
+### 3. Retry Options on Abort
+
+When a swarm aborts (user request or failure), provide clear recovery paths:
+
+```json
+{
+  "retry_options": {
+    "same_plan": "/swarm --retry",
+    "edit_plan": "/swarm --retry --edit",
+    "fresh_start": "/swarm \"original task\""
+  }
+}
+```
+
+**`--retry`**: Resume with same plan, skip completed tasks
+**`--retry --edit`**: Show plan for modification before resuming
+**Fresh start**: Decompose from scratch
+
+This requires persisting swarm session state (already have this via Hive cells).
+
+## Implementation
+
+### Phase 1: Structured Review (Priority)
+1. Add review step to `swarm_complete`
+2. Create review prompt with epic context injection
+3. Handle needs_changes → worker retry loop (max 3)
+4. Keep UBS scan as additional safety net
+
+### Phase 2: Worktree Isolation
+1. Add `isolation` mode to `swarm_init`
+2. Implement worktree lifecycle tools
+3. Update worker prompts to work in worktree path
+4. Add cherry-pick merge on completion
+5. Add cleanup on abort
+
+### Phase 3: Retry Options
+1. Persist session state for recovery
+2. Add `--retry` and `--retry --edit` flags
+3. Skip completed tasks on retry
+4. Show plan editor for `--edit` mode
+
+## Consequences
+
+### Positive
+- **Better quality**: Structured review catches issues before integration
+- **Safer large refactors**: Worktree isolation eliminates merge conflicts
+- **Cleaner recovery**: Retry options reduce friction after failures
+- **Coordinator stays in control**: Review keeps human-in-the-loop feel
+
+### Negative
+- **More complexity**: Two isolation modes to maintain
+- **Slower completion**: Review step adds latency
+- **Disk usage**: Worktrees consume space (mitigated by cleanup)
+
+### Neutral
+- **Credit**: Patterns inspired by nexxeln/opencode-config - should acknowledge in docs
+
+## Alternatives Considered
+
+### Separate Reviewer Agent
+nexxeln uses a dedicated reviewer subagent. We chose coordinator-as-reviewer because:
+- Avoids context duplication (coordinator already has epic context)
+- Faster feedback loop
+- Coordinator can make "ship it" judgment calls
+
+### Staged Changes on Finalize
+nexxeln soft-resets to leave changes staged for user review. We're skipping this because:
+- Our flow already has explicit commit step
+- Hive tracks what changed
+- User can always `git diff` before committing
+
+### Always Use Worktrees
+Could simplify by always using worktrees. Rejected because:
+- Overkill for most tasks
+- Slower setup/teardown
+- File reservations work fine for typical parallel work
+
+## References
+
+- [nexxeln/opencode-config](https://github.com/nexxeln/opencode-config) - Source of inspiration
+- Epic: `bd-lf2p4u-mjaja96b9da` - Swarm Enhancements

package/docs/testing/context-recovery-test.md

@@ -38,7 +38,7 @@ This test scenario verifies that the swarm coordination system can survive conte
    - Epic bead with at least one subtask
    - Example:
      ```bash
-     beads_create_epic(
+     hive_create_epic(
        epic_title: "Test Context Recovery",
        subtasks: [
          { title: "Modify test files", files: ["test/file1.ts", "test/file2.ts"] }
@@ -151,7 +151,7 @@ This test scenario verifies that the swarm coordination system can survive conte
    ```typescript
    // Query the event store directly (if you have access)
    // Or check via beads metadata
-   beads_query(status: "in_progress")
+   hive_query(status: "in_progress")
    ```
    
    **Expected result:**

package/evals/README.md

@@ -71,13 +71,13 @@ evalite("My decomposition test", {
   },
   task: async (input) => {
     // Call your decomposition logic here
-    // Should return BeadTree JSON as string
+    // Should return CellTree JSON as string
   },
   scorers: [subtaskIndependence, coverageCompleteness],
 });
 ```
 
-## BeadTree Format
+## CellTree Format
 
 Scorers expect output as JSON string matching:
 

package/evals/scorers/index.ts

@@ -1,5 +1,5 @@
 import { createScorer } from "evalite";
-import type { BeadTree } from "../../src/schemas/index.js";
+import type { CellTree } from "../../src/schemas/index.js";
 
 /**
  * Custom scorers for evaluating swarm task decomposition quality
@@ -18,7 +18,7 @@ export const subtaskIndependence = createScorer({
   description: "Checks that no files appear in multiple subtasks",
   scorer: ({ output }) => {
     try {
-      const beadTree = JSON.parse(String(output)) as BeadTree;
+      const beadTree = JSON.parse(String(output)) as CellTree;
       const fileMap = new Map<string, number>();
 
       // Track which files appear in which subtasks
@@ -48,7 +48,7 @@ export const subtaskIndependence = createScorer({
     } catch (error) {
       return {
         score: 0,
-        message: `Failed to parse BeadTree: ${error}`,
+        message: `Failed to parse CellTree: ${error}`,
       };
     }
   },
@@ -82,7 +82,7 @@ export const coverageCompleteness = createScorer({
   description: "Checks that subtasks cover the full task scope",
   scorer: ({ output, expected }) => {
     try {
-      const beadTree = JSON.parse(String(output)) as BeadTree;
+      const beadTree = JSON.parse(String(output)) as CellTree;
 
       // If expected files specified, check coverage
       const expectedData = expected as Record<string, unknown> | undefined;
@@ -127,7 +127,7 @@ export const coverageCompleteness = createScorer({
     } catch (error) {
       return {
         score: 0,
-        message: `Failed to parse BeadTree: ${error}`,
+        message: `Failed to parse CellTree: ${error}`,
       };
     }
   },
@@ -148,7 +148,7 @@ export const instructionClarity = createScorer({
   description: "Checks that subtasks have clear, actionable instructions",
   scorer: ({ output }) => {
     try {
-      const beadTree = JSON.parse(String(output)) as BeadTree;
+      const beadTree = JSON.parse(String(output)) as CellTree;
 
       if (beadTree.subtasks.length === 0) {
         return {
@@ -193,7 +193,7 @@ export const instructionClarity = createScorer({
     } catch (error) {
       return {
         score: 0,
-        message: `Failed to parse BeadTree: ${error}`,
+        message: `Failed to parse CellTree: ${error}`,
       };
     }
   },

package/examples/commands/swarm.md

@@ -42,7 +42,7 @@ Swarm Mail is embedded (no external server needed) and provides:
 
 - File reservations to prevent conflicts
 - Message passing between agents
-- Thread-based coordination tied to beads
+- Thread-based coordination tied to cells
 
 ## Workflow
 
@@ -201,7 +201,7 @@ swarm_plan_interactive(
 >
 > **DO NOT decompose inline in the coordinator thread.** This consumes massive context with file reading, CASS queries, and reasoning.
 >
-> **ALWAYS delegate to a `swarm/planner` subagent** that returns only the validated BeadTree JSON.
+> **ALWAYS delegate to a `swarm/planner` subagent** that returns only the validated CellTree JSON.
 
 **❌ Don't do this (inline planning):**
 
@@ -215,7 +215,7 @@ swarm_plan_interactive(
 
 ```bash
 # 1. Create planning bead
-beads_create(title="Plan: <task>", type="task", description="Decompose into subtasks")
+hive_create(title="Plan: <task>", type="task", description="Decompose into subtasks")
 
 # 2. Get final prompt from swarm_plan_interactive (when ready_to_decompose=true)
 # final_prompt = <from last swarm_plan_interactive call>
@@ -225,22 +225,22 @@ Task(
   subagent_type="swarm/planner",
   description="Decompose task: <task>",
   prompt="
-You are a swarm planner. Generate a BeadTree for this task.
+You are a swarm planner. Generate a CellTree for this task.
 
 <final_prompt from swarm_plan_interactive>
 
 ## Instructions
 1. Reason about decomposition strategy
-2. Generate BeadTree JSON
+2. Generate CellTree JSON
 3. Validate with swarm_validate_decomposition
-4. Return ONLY the validated BeadTree JSON (no analysis)
+4. Return ONLY the validated CellTree JSON (no analysis)
 
-Output: Valid BeadTree JSON only.
+Output: Valid CellTree JSON only.
   "
 )
 
 # 4. Subagent returns validated JSON, parse it
-# beadTree = <result from subagent>
+# cellTree = <result from subagent>
 ```
 
 **Planning Mode Behavior:**
@@ -262,25 +262,23 @@ Output: Valid BeadTree JSON only.
 ### 5. Create Beads
 
 ```bash
-beads_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
+hive_create_epic(epic_title="<task>", subtasks=[{title, files, priority}...])
 ```
 
 Rules:
 
-- Each bead completable by one agent
+- Each cell completable by one agent
 - Independent where possible (parallelizable)
-- 3-7 beads per swarm
+- 3-7 cells per swarm
 - No file overlap between subtasks
 
-### 6. Reserve Files (via Swarm Mail)
+### 6. Spawn Agents (Workers Reserve Their Own Files)
 
-```bash
-swarmmail_reserve(paths=[<files>], reason="<bead-id>: <description>", ttl_seconds=3600)
-```
-
-No two agents should edit the same file. Reservations prevent conflicts.
-
-### 7. Spawn Agents
+> **⚠️ CRITICAL: Coordinator NEVER reserves files.**
+>
+> Workers reserve their own files via `swarmmail_reserve()` as their first action.
+> This is how conflict detection works - reservation = ownership.
+> If coordinator reserves, workers get blocked and swarm stalls.
 
 **CRITICAL: Spawn ALL in a SINGLE message with multiple Task calls.**
 
@@ -330,7 +328,7 @@ swarmmail_read_message(message_id=N)  # Read specific message
 - Worker blocked >5 min → Check inbox, offer guidance
 - File conflict → Mediate, reassign files
 - Worker asking questions → Answer directly
-- Scope creep → Redirect, create new bead for extras
+- Scope creep → Redirect, create new cell for extras
 
 If incompatibilities spotted, broadcast:
 
@@ -343,7 +341,7 @@ swarmmail_send(to=["*"], subject="Coordinator Update", body="<guidance>", import
 ```bash
 swarm_complete(project_key="$PWD", agent_name="<your-name>", bead_id="<epic-id>", summary="<done>", files_touched=[...])
 swarmmail_release()  # Release any remaining reservations
-beads_sync()
+hive_sync()
 ```
 
 ### 10. Create PR (unless --to-main)
@@ -408,9 +406,9 @@ Not: Do Everything Inline → Run Out of Context → Fail
 - [ ] **swarmmail_init** called FIRST
 - [ ] Knowledge gathered (semantic-memory, CASS, pdf-brain, skills)
 - [ ] **Planning delegated to swarm/planner subagent** (NOT inline)
-- [ ] BeadTree validated (no file conflicts)
+- [ ] CellTree validated (no file conflicts)
 - [ ] Epic + subtasks created
-- [ ] Files reserved via **swarmmail_reserve**
+- [ ] **Coordinator did NOT reserve files** (workers do this themselves)
 - [ ] Workers spawned in parallel
 - [ ] Progress monitored via **swarmmail_inbox** (limit=5, no bodies)
 - [ ] PR created (or pushed to main)