opencode-swarm-plugin 0.31.7 → 0.32.0

package/examples/plugin-wrapper-template.ts

@@ -11,6 +11,7 @@
  * - OPENCODE_SESSION_ID: Passed to CLI for session state persistence
  * - OPENCODE_MESSAGE_ID: Passed to CLI for context
  * - OPENCODE_AGENT: Passed to CLI for context
+ * - SWARM_PROJECT_DIR: Project directory (critical for database path)
  */
 import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
@@ -18,6 +19,10 @@ import { spawn } from "child_process";
 
 const SWARM_CLI = "swarm";
 
+// Module-level project directory - set during plugin initialization
+// This is CRITICAL: without it, the CLI uses process.cwd() which may be wrong
+let projectDirectory: string = process.cwd();
+
 // =============================================================================
 // CLI Execution Helper
 // =============================================================================
@@ -27,6 +32,8 @@ const SWARM_CLI = "swarm";
  *
  * Spawns `swarm tool <name> --json '<args>'` and returns the result.
  * Passes session context via environment variables.
+ * 
+ * IMPORTANT: Runs in projectDirectory (set by OpenCode) not process.cwd()
  */
 async function execTool(
   name: string,
@@ -40,12 +47,14 @@ async function execTool(
       : ["tool", name];
 
     const proc = spawn(SWARM_CLI, cliArgs, {
+      cwd: projectDirectory, // Run in project directory, not plugin directory
       stdio: ["ignore", "pipe", "pipe"],
       env: {
         ...process.env,
         OPENCODE_SESSION_ID: ctx.sessionID,
         OPENCODE_MESSAGE_ID: ctx.messageID,
         OPENCODE_AGENT: ctx.agent,
+        SWARM_PROJECT_DIR: projectDirectory, // Also pass as env var
       },
     });
 
@@ -1058,9 +1067,11 @@ Extract from session context:
 
 1. \`swarm_status(epic_id="<epic>", project_key="<path>")\` - Get current state
 2. \`swarmmail_inbox(limit=5)\` - Check for agent messages
-3. **Spawn ready subtasks** - Don't wait, fire them off
-4. **Unblock blocked work** - Resolve dependencies, reassign if needed
-5. **Collect completed work** - Close done subtasks, verify quality
+3. \`swarm_review(project_key, epic_id, task_id, files_touched)\` - Review any completed work
+4. \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\` - Approve or request changes
+5. **Spawn ready subtasks** - Don't wait, fire them off
+6. **Unblock blocked work** - Resolve dependencies, reassign if needed
+7. **Collect completed work** - Close done subtasks, verify quality
 
 ### Keep the Swarm Cooking
 
@@ -1122,8 +1133,12 @@ type ExtendedHooks = Hooks & {
 };
 
 export const SwarmPlugin: Plugin = async (
-  _input: PluginInput,
+  input: PluginInput,
 ): Promise<ExtendedHooks> => {
+  // CRITICAL: Set project directory from OpenCode input
+  // Without this, CLI uses wrong database path
+  projectDirectory = input.directory;
+  
   return {
     tool: {
       // Beads

package/global-skills/swarm-coordination/SKILL.md

@@ -13,6 +13,8 @@ tools:
   - swarm_complete
   - swarm_status
   - swarm_progress
+  - swarm_review
+  - swarm_review_feedback
   - hive_create_epic
   - hive_query
   - swarmmail_init
@@ -442,19 +444,120 @@ for (const subtask of subtasks) {
 }
 ```
 
-### Phase 6: Monitor & Intervene
+### Phase 6: MANDATORY Review Loop (NON-NEGOTIABLE)
 
-```typescript
-// Check progress
-const status = await swarm_status({ epic_id, project_key });
+**⚠️ AFTER EVERY Worker Returns, You MUST Complete This Checklist:**
 
-// Check for messages from workers
-const inbox = await swarmmail_inbox({ limit: 5 });
+This is the **quality gate** that prevents shipping broken code. DO NOT skip this.
 
-// Read specific message if needed
+```typescript
+// ============================================================
+// Step 1: Check Swarm Mail (Worker may have sent messages)
+// ============================================================
+const inbox = await swarmmail_inbox({ limit: 5 });
 const message = await swarmmail_read_message({ message_id: N });
 
-// Intervene if needed (see Intervention Patterns)
+// ============================================================
+// Step 2: Review the Work (Generate review prompt with diff)
+// ============================================================
+const reviewPrompt = await swarm_review({
+  project_key: "/abs/path/to/project",
+  epic_id: "epic-id",
+  task_id: "subtask-id",
+  files_touched: ["src/auth/service.ts", "src/auth/service.test.ts"]
+});
+
+// This generates a review prompt that includes:
+// - Epic context (what we're trying to achieve)
+// - Subtask requirements
+// - Git diff of changes
+// - Dependency status (what came before, what comes next)
+
+// ============================================================
+// Step 3: Evaluate Against Criteria
+// ============================================================
+// Ask yourself:
+// - Does the work fulfill the subtask requirements?
+// - Does it serve the overall epic goal?
+// - Does it enable downstream tasks?
+// - Type safety, no obvious bugs?
+
+// ============================================================
+// Step 4: Send Feedback (Approve or Request Changes)
+// ============================================================
+await swarm_review_feedback({
+  project_key: "/abs/path/to/project",
+  task_id: "subtask-id",
+  worker_id: "WorkerName",
+  status: "approved",  // or "needs_changes"
+  summary: "LGTM - auth service looks solid",
+  issues: "[]"  // or "[{file, line, issue, suggestion}]"
+});
+
+// ============================================================
+// Step 5: ONLY THEN Continue
+// ============================================================
+// If approved:
+//   - Close the cell
+//   - Spawn next worker (if dependencies allow)
+//   - Update swarm status
+//
+// If needs_changes:
+//   - Worker gets feedback
+//   - Worker retries (max 3 attempts)
+//   - Review again when worker re-submits
+//
+// If 3 failures:
+//   - Mark task blocked
+//   - Escalate to human (architectural problem, not "try harder")
+```
+
+**❌ Anti-Pattern (Skipping Review):**
+
+```typescript
+// Worker completes
+swarm_complete({ ... });
+
+// Coordinator immediately spawns next worker
+// ⚠️ WRONG - No quality gate!
+Task({ subagent_type: "swarm/worker", prompt: nextWorkerPrompt });
+```
+
+**✅ Correct Pattern (Review Before Proceeding):**
+
+```typescript
+// Worker completes
+swarm_complete({ ... });
+
+// Coordinator REVIEWS first
+swarm_review({ ... });
+// ... evaluates changes ...
+swarm_review_feedback({ status: "approved" });
+
+// ONLY THEN spawn next worker
+Task({ subagent_type: "swarm/worker", prompt: nextWorkerPrompt });
+```
+
+**Review Workflow (3-Strike Rule):**
+
+1. Worker calls `swarm_complete` → Coordinator notified
+2. Coordinator runs `swarm_review` → Gets diff + epic context
+3. Coordinator evaluates against epic goals
+4. If good: `swarm_review_feedback(status="approved")` → Task closed
+5. If issues: `swarm_review_feedback(status="needs_changes", issues=[...])` → Worker fixes
+6. After 3 rejections → Task marked blocked (architectural problem, not "try harder")
+
+**Review Criteria:**
+- Does work fulfill subtask requirements?
+- Does it serve the overall epic goal?
+- Does it enable downstream tasks?
+- Type safety, no obvious bugs?
+
+**Monitoring & Intervention:**
+
+```typescript
+// Check overall swarm status
+const status = await swarm_status({ epic_id, project_key });
 ```
 
 ### Phase 7: Aggregate & Complete
@@ -778,6 +881,13 @@ One blocker affects multiple subtasks.
 | `swarmmail_ack`          | Acknowledge message                 |
 | `swarmmail_health`       | Check database health               |
 
+## Swarm Review Quick Reference
+
+| Tool                     | Purpose                                    |
+| ------------------------ | ------------------------------------------ |
+| `swarm_review`           | Generate review prompt with epic context + diff |
+| `swarm_review_feedback`  | Send approval/rejection to worker (3-strike rule) |
+
 ## Full Swarm Flow
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.31.7",
+  "version": "0.32.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,7 @@
     "gray-matter": "^4.0.3",
     "ioredis": "^5.4.1",
     "minimatch": "^10.1.1",
-    "swarm-mail": "1.2.2",
+    "swarm-mail": "1.3.0",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/src/compaction-hook.ts

@@ -88,9 +88,11 @@ Extract from session context:
 
 1. \`swarm_status(epic_id="<epic>", project_key="<path>")\` - Get current state
 2. \`swarmmail_inbox(limit=5)\` - Check for agent messages
-3. **Spawn ready subtasks** - Don't wait, fire them off
-4. **Unblock blocked work** - Resolve dependencies, reassign if needed
-5. **Collect completed work** - Close done subtasks, verify quality
+3. \`swarm_review(project_key, epic_id, task_id, files_touched)\` - Review any completed work
+4. \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\` - Approve or request changes
+5. **Spawn ready subtasks** - Don't wait, fire them off
+6. **Unblock blocked work** - Resolve dependencies, reassign if needed
+7. **Collect completed work** - Close done subtasks, verify quality
 
 ### Keep the Swarm Cooking
 

package/src/hive.integration.test.ts

@@ -7,6 +7,8 @@
  * Run with: bun test src/hive.integration.test.ts
  */
 import { describe, it, expect, beforeAll, beforeEach, afterAll } from "vitest";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
   hive_create,
   hive_create_epic,
@@ -56,7 +58,7 @@ const createdBeadIds: string[] = [];
 /**
  * Test project key - use temp directory to isolate tests
  */
-const TEST_PROJECT_KEY = `/tmp/beads-integration-test-${Date.now()}`;
+const TEST_PROJECT_KEY = join(tmpdir(), `beads-integration-test-${Date.now()}`);
 
 /**
  * Adapter instance for verification
@@ -1353,6 +1355,86 @@ describe("beads integration", () => {
   });
 
   describe("hive_sync", () => {
+    it("succeeds with unstaged changes outside .hive/ (stash-before-pull)", async () => {
+      const { mkdirSync, rmSync, writeFileSync, existsSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      const { execSync } = await import("node:child_process");
+
+      // Create a temp git repository with a remote (to trigger pull)
+      const tempProject = join(tmpdir(), `hive-sync-stash-test-${Date.now()}`);
+      const remoteProject = join(tmpdir(), `hive-sync-remote-${Date.now()}`);
+      
+      // Create "remote" bare repo
+      mkdirSync(remoteProject, { recursive: true });
+      execSync("git init --bare", { cwd: remoteProject });
+      
+      // Create local repo
+      mkdirSync(tempProject, { recursive: true });
+      execSync("git init", { cwd: tempProject });
+      execSync('git config user.email "test@example.com"', { cwd: tempProject });
+      execSync('git config user.name "Test User"', { cwd: tempProject });
+      execSync(`git remote add origin ${remoteProject}`, { cwd: tempProject });
+
+      // Create .hive directory and a source file
+      const hiveDir = join(tempProject, ".hive");
+      mkdirSync(hiveDir, { recursive: true });
+      writeFileSync(join(hiveDir, "issues.jsonl"), "");
+      writeFileSync(join(tempProject, "src.ts"), "// initial");
+
+      // Initial commit and push
+      execSync("git add .", { cwd: tempProject });
+      execSync('git commit -m "initial commit"', { cwd: tempProject });
+      execSync("git push -u origin main", { cwd: tempProject });
+
+      // Now create unstaged changes OUTSIDE .hive/
+      writeFileSync(join(tempProject, "src.ts"), "// modified but not staged");
+
+      // Set working directory for hive commands
+      const originalDir = getHiveWorkingDirectory();
+      setHiveWorkingDirectory(tempProject);
+
+      try {
+        // Create a cell (this will mark it dirty and flush will write to JSONL)
+        await hive_create.execute(
+          { title: "Stash test cell", type: "task" },
+          mockContext,
+        );
+
+        // Sync WITH auto_pull=true (this is where the bug manifests)
+        // Before fix: fails with "cannot pull with rebase: You have unstaged changes"
+        // After fix: stashes, pulls, pops, succeeds
+        const result = await hive_sync.execute(
+          { auto_pull: true },
+          mockContext,
+        );
+
+        // Should succeed
+        expect(result).toContain("successfully");
+
+        // Verify .hive changes were committed
+        const hiveStatus = execSync("git status --porcelain .hive/", {
+          cwd: tempProject,
+          encoding: "utf-8",
+        });
+        expect(hiveStatus.trim()).toBe("");
+
+        // Verify unstaged changes are still there (stash was popped)
+        const srcStatus = execSync("git status --porcelain src.ts", {
+          cwd: tempProject,
+          encoding: "utf-8",
+        });
+        expect(srcStatus.trim()).toContain("M src.ts");
+      } finally {
+        // Restore original working directory
+        setHiveWorkingDirectory(originalDir);
+
+        // Cleanup
+        rmSync(tempProject, { recursive: true, force: true });
+        rmSync(remoteProject, { recursive: true, force: true });
+      }
+    });
+
     it("commits .hive changes before pulling (regression test for unstaged changes error)", async () => {
       const { mkdirSync, rmSync, writeFileSync, existsSync } = await import("node:fs");
       const { join } = await import("node:path");

package/src/hive.ts

@@ -22,7 +22,7 @@ import {
   syncMemories,
   type HiveAdapter,
   type Cell as AdapterCell,
-  getSwarmMail,
+  getSwarmMailLibSQL,
   resolvePartialId,
 } from "swarm-mail";
 import { existsSync, readFileSync } from "node:fs";
@@ -508,7 +508,7 @@ export async function getHiveAdapter(projectKey: string): Promise<HiveAdapter> {
     return adapterCache.get(projectKey)!;
   }
 
-  const swarmMail = await getSwarmMail(projectKey);
+  const swarmMail = await getSwarmMailLibSQL(projectKey);
   const db = await swarmMail.getDatabase();
   const adapter = createHiveAdapter(db, projectKey);
 
@@ -1158,7 +1158,7 @@ export const hive_sync = tool({
     );
 
     // 2b. Sync memories to JSONL
-    const swarmMail = await getSwarmMail(projectKey);
+    const swarmMail = await getSwarmMailLibSQL(projectKey);
     const db = await swarmMail.getDatabase();
     const hivePath = join(projectKey, ".hive");
     let memoriesSynced = 0;
@@ -1217,18 +1217,43 @@ export const hive_sync = tool({
       const hasRemote = remoteCheckResult.stdout.trim() !== "";
 
       if (hasRemote) {
-        const pullResult = await withTimeout(
-          runGitCommand(["pull", "--rebase"]),
-          TIMEOUT_MS,
-          "git pull --rebase",
-        );
+        // Check for unstaged changes that would block pull --rebase
+        const statusResult = await runGitCommand(["status", "--porcelain"]);
+        const hasUnstagedChanges = statusResult.stdout.trim() !== "";
+        let didStash = false;
+
+        if (hasUnstagedChanges) {
+          // Stash all changes (including untracked) before pull
+          const stashResult = await runGitCommand(["stash", "push", "-u", "-m", "hive_sync: auto-stash before pull"]);
+          if (stashResult.exitCode === 0) {
+            didStash = true;
+          }
+          // If stash fails (e.g., nothing to stash), continue anyway
+        }
 
-        if (pullResult.exitCode !== 0) {
-          throw new HiveError(
-            `Failed to pull: ${pullResult.stderr}`,
+        try {
+          const pullResult = await withTimeout(
+            runGitCommand(["pull", "--rebase"]),
+            TIMEOUT_MS,
             "git pull --rebase",
-            pullResult.exitCode,
           );
+
+          if (pullResult.exitCode !== 0) {
+            throw new HiveError(
+              `Failed to pull: ${pullResult.stderr}`,
+              "git pull --rebase",
+              pullResult.exitCode,
+            );
+          }
+        } finally {
+          // Pop stash if we stashed
+          if (didStash) {
+            const popResult = await runGitCommand(["stash", "pop"]);
+            if (popResult.exitCode !== 0) {
+              // Stash pop failed - likely a conflict. Log warning but don't fail sync.
+              console.warn(`[hive_sync] Warning: stash pop failed. Your changes are in 'git stash list'. Error: ${popResult.stderr}`);
+            }
+          }
         }
       }
     }