opencode-swarm-plugin 0.36.1 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,175 @@
 # opencode-swarm-plugin
 
+## 0.38.0
+
+### Minor Changes
+
+- [`41a1965`](https://github.com/joelhooks/swarm-tools/commit/41a19657b252eb1c7a7dc82bc59ab13589e8758f) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🐝 Coordinators Now Delegate Research to Workers
+
+  Coordinators finally know their place. They orchestrate, they don't fetch.
+
+  **The Problem:**
+  Coordinators were calling `repo-crawl_file`, `webfetch`, `context7_*` directly, burning expensive Sonnet context on raw file contents instead of spawning researcher workers.
+
+  **The Fix:**
+
+  ### Forbidden Tools Section
+
+  COORDINATOR_PROMPT now explicitly lists tools coordinators must NEVER call:
+
+  - `repo-crawl_*`, `repo-autopsy_*` - repository fetching
+  - `webfetch`, `fetch_fetch` - web fetching
+  - `context7_*` - library documentation
+  - `pdf-brain_search`, `pdf-brain_read` - knowledge base
+
+  ### Phase 1.5: Research Phase
+
+  New workflow phase between Initialize and Knowledge Gathering:
+
+  ```
+  swarm_spawn_researcher(
+    research_id="research-nextjs-cache",
+    tech_stack=["Next.js 16 Cache Components"],
+    project_path="/path/to/project"
+  )
+  ```
+
+  ### Strong Coordinator Identity Post-Compaction
+
+  When context compacts, the resuming agent now sees:
+
+  ```
+  ┌─────────────────────────────────────────────────────────────┐
+  │             🐝  YOU ARE THE COORDINATOR  🐝                 │
+  │             NOT A WORKER. NOT AN IMPLEMENTER.               │
+  │                  YOU ORCHESTRATE.                           │
+  └─────────────────────────────────────────────────────────────┘
+  ```
+
+  ### runResearchPhase Returns Spawn Instructions
+
+  ```typescript
+  const result = await runResearchPhase(task, projectPath);
+  // result.spawn_instructions = [
+  //   { research_id, tech, prompt, subagent_type: "swarm/researcher" }
+  // ]
+  ```
+
+  **32+ new tests, all 425 passing.**
+
+- [`b06f69b`](https://github.com/joelhooks/swarm-tools/commit/b06f69bc3db099c14f712585d88b42c801123d01) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔬 Eval Capture Pipeline: Complete
+
+  > "The purpose of computing is insight, not numbers." — Richard Hamming
+
+  Wire all eval-capture functions into the swarm execution path, enabling ground-truth collection from real swarm executions.
+
+  **What changed:**
+
+  | Function                  | Wired Into                     | Purpose                            |
+  | ------------------------- | ------------------------------ | ---------------------------------- |
+  | `captureDecomposition()`  | `swarm_validate_decomposition` | Records task → subtasks mapping    |
+  | `captureSubtaskOutcome()` | `swarm_complete`               | Records per-subtask execution data |
+  | `finalizeEvalRecord()`    | `swarm_record_outcome`         | Computes aggregate metrics         |
+
+  **New npm scripts:**
+
+  ```bash
+  bun run eval:run           # Run all evals
+  bun run eval:decomposition # Decomposition quality
+  bun run eval:coordinator   # Coordinator discipline
+  ```
+
+  **Data flow:**
+
+  ```
+  swarm_decompose → captureDecomposition → .opencode/eval-data.jsonl
+         ↓
+  swarm_complete → captureSubtaskOutcome → updates record with outcomes
+         ↓
+  swarm_record_outcome → finalizeEvalRecord → computes scope_accuracy, time_balance
+         ↓
+  evalite → reads JSONL → scores decomposition quality
+  ```
+
+  **Why it matters:**
+
+  - Enables data-driven decomposition strategy selection
+  - Tracks which strategies work for which task types
+  - Provides ground truth for Evalite evals
+  - Foundation for learning from swarm outcomes
+
+  **Key discovery:** New cell ID format doesn't follow `epicId.subtaskNum` pattern. Must use `cell.parent_id` to get epic ID for subtasks.
+
+### Patch Changes
+
+- [`56e5d4c`](https://github.com/joelhooks/swarm-tools/commit/56e5d4c5ac96ddd2184d12c63e163bb9c291fb69) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🔬 Eval Capture Pipeline: Phase 1
+
+  > "The first step toward wisdom is getting things right. The second step is getting them wrong in interesting ways." — Marvin Minsky
+
+  Wire `captureDecomposition()` into `swarm_validate_decomposition` to record decomposition inputs/outputs for evaluation.
+
+  **What changed:**
+
+  - `swarm_validate_decomposition` now calls `captureDecomposition()` after successful validation
+  - Captures: epicId, projectPath, task, context, strategy, epicTitle, subtasks
+  - Data persisted to `.opencode/eval-data.jsonl` for Evalite consumption
+
+  **Why it matters:**
+
+  - Enables ground-truth collection from real swarm executions
+  - Foundation for decomposition quality evals
+  - Tracks what strategies work for which task types
+
+  **Tests added:**
+
+  - Verifies `captureDecomposition` called with correct params on success
+  - Verifies NOT called on validation failure
+  - Handles optional context/description fields
+
+  **Next:** Wire `captureSubtaskOutcome()` and `finalizeEvalRecord()` to complete the pipeline.
+
+## 0.37.0
+
+### Minor Changes
+
+- [`66b5795`](https://github.com/joelhooks/swarm-tools/commit/66b57951e2c114702c663b98829d5f7626607a16) Thanks [@joelhooks](https://github.com/joelhooks)! - ## 🐝 `swarm cells` - Query Your Hive Like a Pro
+
+  New CLI command AND plugin tool for querying cells directly from the database.
+
+  ### CLI: `swarm cells`
+
+  ```bash
+  swarm cells                      # List all cells (table format)
+  swarm cells --status open        # Filter by status
+  swarm cells --type bug           # Filter by type
+  swarm cells --ready              # Next unblocked cell
+  swarm cells mjkmd                # Partial ID lookup
+  swarm cells --json               # Raw JSON for scripting
+  ```
+
+  **Replaces:** The awkward `swarm tool hive_query --json '{"status":"open"}'` pattern.
+
+  ### Plugin Tool: `hive_cells`
+
+  ```typescript
+  // Agents can now query cells directly
+  hive_cells({ status: "open", type: "task" });
+  hive_cells({ id: "mjkmd" }); // Partial ID works!
+  hive_cells({ ready: true }); // Next unblocked
+  ```
+
+  **Why this matters:**
+
+  - Reads from DATABASE (fast, indexed) not JSONL files
+  - Partial ID resolution built-in
+  - Consistent JSON array output
+  - Rich descriptions encourage agentic use
+
+  ### Also Fixed
+
+  - `swarm_review_feedback` tests updated for coordinator-driven retry architecture
+  - 425 tests passing
+
 ## 0.36.1
 
 ### Patch Changes

package/README.md

@@ -231,6 +231,39 @@ bun test
 bun run typecheck
 ```
 
+### Evaluation Pipeline
+
+Test decomposition quality and coordinator discipline with **Evalite** (TypeScript-native eval framework):
+
+```bash
+# Run all evals
+bun run eval:run
+
+# Run specific suites
+bun run eval:decomposition    # Task decomposition quality
+bun run eval:coordinator      # Coordinator protocol compliance
+```
+
+**What gets evaluated:**
+
+| Eval Suite | Measures | Data Source |
+|------------|----------|-------------|
+| `swarm-decomposition` | Subtask independence, complexity balance, coverage, clarity | Fixtures + captured real decompositions |
+| `coordinator-session` | Violation count, spawn efficiency, review thoroughness | Real sessions from `~/.config/swarm-tools/sessions/` |
+
+**Data capture locations:**
+- Decomposition inputs/outputs: `.opencode/eval-data.jsonl`
+- Coordinator sessions: `~/.config/swarm-tools/sessions/*.jsonl`
+- Subtask outcomes: swarm-mail database (used for pattern learning)
+
+**Custom scorers:**
+- Subtask independence (0-1): Files don't overlap between subtasks
+- Complexity balance (0-1): Subtasks have similar estimated complexity
+- Coverage completeness (0-1): Required files are covered
+- Instruction clarity (0-1): Descriptions are specific and actionable
+
+See [evals/README.md](./evals/README.md) for scorer details and how to write new evals.
+
 ---
 
 ## CLI

package/bin/swarm.test.ts

@@ -197,6 +197,112 @@ READ-ONLY research agent. Never modifies code - only gathers intel and stores fi
 // Log Command Tests (TDD)
 // ============================================================================
 
+// ============================================================================
+// Cells Command Tests (TDD)
+// ============================================================================
+
+/**
+ * Format cells as table output
+ */
+function formatCellsTable(cells: Array<{
+  id: string;
+  title: string;
+  status: string;
+  priority: number;
+}>): string {
+  if (cells.length === 0) {
+    return "No cells found";
+  }
+
+  const rows = cells.map(c => ({
+    id: c.id,
+    title: c.title.length > 50 ? c.title.slice(0, 47) + "..." : c.title,
+    status: c.status,
+    priority: String(c.priority),
+  }));
+
+  // Calculate column widths
+  const widths = {
+    id: Math.max(2, ...rows.map(r => r.id.length)),
+    title: Math.max(5, ...rows.map(r => r.title.length)),
+    status: Math.max(6, ...rows.map(r => r.status.length)),
+    priority: Math.max(8, ...rows.map(r => r.priority.length)),
+  };
+
+  // Build header
+  const header = [
+    "ID".padEnd(widths.id),
+    "TITLE".padEnd(widths.title),
+    "STATUS".padEnd(widths.status),
+    "PRIORITY".padEnd(widths.priority),
+  ].join("  ");
+
+  const separator = "-".repeat(header.length);
+
+  // Build rows
+  const bodyRows = rows.map(r =>
+    [
+      r.id.padEnd(widths.id),
+      r.title.padEnd(widths.title),
+      r.status.padEnd(widths.status),
+      r.priority.padEnd(widths.priority),
+    ].join("  ")
+  );
+
+  return [header, separator, ...bodyRows].join("\n");
+}
+
+describe("Cells command", () => {
+  describe("formatCellsTable", () => {
+    test("formats cells as table with id, title, status, priority", () => {
+      const cells = [
+        {
+          id: "test-abc123-xyz",
+          title: "Fix bug",
+          status: "open",
+          priority: 0,
+          type: "bug",
+          created_at: 1234567890,
+          updated_at: 1234567890,
+        },
+        {
+          id: "test-def456-abc",
+          title: "Add feature",
+          status: "in_progress",
+          priority: 2,
+          type: "feature",
+          created_at: 1234567890,
+          updated_at: 1234567890,
+        },
+      ];
+
+      const table = formatCellsTable(cells);
+
+      // Should contain headers
+      expect(table).toContain("ID");
+      expect(table).toContain("TITLE");
+      expect(table).toContain("STATUS");
+      expect(table).toContain("PRIORITY");
+
+      // Should contain cell data
+      expect(table).toContain("test-abc123-xyz");
+      expect(table).toContain("Fix bug");
+      expect(table).toContain("open");
+      expect(table).toContain("0");
+
+      expect(table).toContain("test-def456-abc");
+      expect(table).toContain("Add feature");
+      expect(table).toContain("in_progress");
+      expect(table).toContain("2");
+    });
+
+    test("returns 'No cells found' for empty array", () => {
+      const table = formatCellsTable([]);
+      expect(table).toBe("No cells found");
+    });
+  });
+});
+
 describe("Log command helpers", () => {
   let testDir: string;