opencode-swarm-plugin 0.14.0 → 0.16.0

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

@@ -63,6 +63,53 @@ Swarm Mail is embedded (no external server needed) and provides:
 
 **Heuristic:** If you can describe the task in one sentence without "and", don't swarm.
 
+## Task Clarity Check (BEFORE Decomposing)
+
+**Before decomposing, ask: Is this task clear enough to parallelize?**
+
+### Vague Task Signals (ASK QUESTIONS FIRST)
+
+| Signal                   | Example                        | Problem                          |
+| ------------------------ | ------------------------------ | -------------------------------- |
+| No files mentioned       | "improve performance"          | Where? Which files?              |
+| Vague verbs              | "fix", "update", "make better" | What specifically?               |
+| Large undefined scope    | "refactor the codebase"        | Which parts? What pattern?       |
+| Missing success criteria | "add auth"                     | OAuth? JWT? Session? What flows? |
+| Ambiguous boundaries     | "handle errors"                | Which errors? Where? How?        |
+
+### How to Clarify
+
+```markdown
+The task "<task>" needs clarification before I can decompose it.
+
+**Question:** [Specific question about scope/files/approach]
+
+Options:
+a) [Option A] - [trade-off]
+b) [Option B] - [trade-off]
+c) [Option C] - [trade-off]
+
+I'd recommend (a) because [reason]. Which approach?
+```
+
+**Rules:**
+
+- ONE question at a time (don't overwhelm)
+- Offer 2-3 concrete options when possible
+- Lead with your recommendation and why
+- Wait for answer before asking next question
+
+### Clear Task Signals (PROCEED to decompose)
+
+| Signal             | Example                        | Why it's clear   |
+| ------------------ | ------------------------------ | ---------------- |
+| Specific files     | "update src/auth/\*.ts"        | Scope defined    |
+| Concrete verbs     | "migrate from X to Y"          | Action defined   |
+| Defined scope      | "the payment module"           | Boundaries clear |
+| Measurable outcome | "tests pass", "no type errors" | Success criteria |
+
+**When in doubt, ask.** A 30-second clarification beats a 30-minute wrong decomposition.
+
 ## Coordinator Workflow
 
 ### Phase 1: Initialize Swarm Mail (FIRST)
@@ -95,30 +142,76 @@ skills_list();
 
 Synthesize findings into `shared_context` for workers.
 
-### Phase 3: Decomposition
+### Phase 3: Decomposition (DELEGATE TO SUBAGENT)
+
+> **⚠️ CRITICAL: Context Preservation Pattern**
+>
+> **NEVER do planning inline in the coordinator thread.** Decomposition work (file reading, CASS searching, reasoning about task breakdown) consumes massive amounts of context and will exhaust your token budget on long swarms.
+>
+> **ALWAYS delegate planning to a `swarm/planner` subagent** and receive only the structured BeadTree JSON result back.
+
+**❌ Anti-Pattern (Context-Heavy):**
+
+```typescript
+// DON'T DO THIS - pollutes main thread context
+const plan = await swarm_plan_prompt({ task, ... });
+// ... agent reasons about decomposition inline ...
+// ... context fills with file contents, analysis ...
+const validation = await swarm_validate_decomposition({ ... });
+```
+
+**✅ Correct Pattern (Context-Lean):**
 
 ```typescript
-// Auto-select strategy and generate decomposition prompt
-const plan = await swarm_plan_prompt({
-  task: "Add user authentication with OAuth",
-  max_subtasks: 5,
-  query_cass: true, // searches history
-  include_skills: true, // lists relevant skills
+// 1. Create planning bead with full context
+await beads_create({
+  title: `Plan: ${taskTitle}`,
+  type: "task",
+  description: `Decompose into subtasks. Context: ${synthesizedContext}`,
 });
 
-// Agent responds with BeadTree JSON, then validate
-const validation = await swarm_validate_decomposition({
-  response: agentResponse,
+// 2. Delegate to swarm/planner subagent
+const planningResult = await Task({
+  subagent_type: "swarm/planner",
+  description: `Decompose task: ${taskTitle}`,
+  prompt: `
+You are a swarm planner. Generate a BeadTree for this task.
+
+## Task
+${taskDescription}
+
+## Synthesized Context
+${synthesizedContext}
+
+## Instructions
+1. Use swarm_plan_prompt(task="...", max_subtasks=5, query_cass=true)
+2. Reason about decomposition strategy
+3. Generate BeadTree JSON
+4. Validate with swarm_validate_decomposition
+5. Return ONLY the validated BeadTree JSON (no analysis, no file contents)
+
+Output format: Valid BeadTree JSON only.
+  `,
 });
 
-// Create epic + subtasks atomically
+// 3. Parse result (subagent already validated)
+const beadTree = JSON.parse(planningResult);
+
+// 4. Create epic + subtasks atomically
 await beads_create_epic({
-  epic_title: "Add OAuth Authentication",
-  epic_description: "...",
-  subtasks: validation.subtasks,
+  epic_title: beadTree.epic.title,
+  epic_description: beadTree.epic.description,
+  subtasks: beadTree.subtasks,
 });
 ```
 
+**Why This Matters:**
+
+- **Main thread context stays clean** - only receives final JSON, not reasoning
+- **Subagent context is disposable** - gets garbage collected after planning
+- **Scales to long swarms** - coordinator can manage 10+ workers without exhaustion
+- **Faster coordination** - less context = faster responses when monitoring workers
+
 ### Phase 4: Reserve Files (via Swarm Mail)
 
 ```typescript
@@ -263,12 +356,17 @@ One blocker affects multiple subtasks.
 
 ## Anti-Patterns
 
-| Anti-Pattern         | Symptom                          | Fix                           |
-| -------------------- | -------------------------------- | ----------------------------- |
-| **Mega-Coordinator** | Coordinator editing files        | Coordinator only orchestrates |
-| **Silent Swarm**     | No communication, late conflicts | Require updates, check inbox  |
-| **Over-Decomposed**  | 10 subtasks for 20 lines         | 2-5 subtasks max              |
-| **Under-Specified**  | "Implement backend"              | Clear goal, files, criteria   |
+| Anti-Pattern                | Symptom                                    | Fix                                  |
+| --------------------------- | ------------------------------------------ | ------------------------------------ |
+| **Decomposing Vague Tasks** | Wrong subtasks, wasted agent cycles        | Ask clarifying questions FIRST       |
+| **Mega-Coordinator**        | Coordinator editing files                  | Coordinator only orchestrates        |
+| **Silent Swarm**            | No communication, late conflicts           | Require updates, check inbox         |
+| **Over-Decomposed**         | 10 subtasks for 20 lines                   | 2-5 subtasks max                     |
+| **Under-Specified**         | "Implement backend"                        | Clear goal, files, criteria          |
+| **Inline Planning** ⚠️      | Context pollution, exhaustion on long runs | Delegate planning to subagent        |
+| **Heavy File Reading**      | Coordinator reading 10+ files              | Subagent reads, returns summary only |
+| **Deep CASS Drilling**      | Multiple cass_search calls inline          | Subagent searches, summarizes        |
+| **Manual Decomposition**    | Hand-crafting subtasks without validation  | Use swarm_plan_prompt + validation   |
 
 ## Shared Context Template
 

package/global-skills/swarm-coordination/references/coordinator-patterns.md

@@ -49,7 +49,7 @@ For each subtask:
 ### 4. Progress Monitoring
 
 - Check `beads_query(status="in_progress")` for active work
-- Check `agentmail_inbox()` for worker messages
+- Check `swarmmail_inbox()` for worker messages
 - Intervene on blockers (see Intervention Patterns below)
 
 ### 5. Completion & Aggregation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -38,6 +38,7 @@ import { structuredTools } from "./structured";
 import { swarmTools } from "./swarm";
 import { repoCrawlTools } from "./repo-crawl";
 import { skillsTools, setSkillsProjectDirectory } from "./skills";
+import { mandateTools } from "./mandates";
 
 /**
  * OpenCode Swarm Plugin
@@ -50,6 +51,7 @@ import { skillsTools, setSkillsProjectDirectory } from "./skills";
  * - swarm:* - Swarm orchestration and task decomposition
  * - repo-crawl:* - GitHub API tools for repository research
  * - skills:* - Agent skills discovery, activation, and execution
+ * - mandate:* - Agent voting system for collaborative knowledge curation
  *
  * @param input - Plugin context from OpenCode
  * @returns Plugin hooks including tools, events, and tool execution hooks
@@ -132,6 +134,7 @@ export const SwarmPlugin: Plugin = async (
      * - agent-mail:init, agent-mail:send, agent-mail:reserve, etc. (legacy MCP)
      * - swarm-mail:init, swarm-mail:send, swarm-mail:reserve, etc. (embedded)
      * - repo-crawl:readme, repo-crawl:structure, etc.
+     * - mandate:file, mandate:vote, mandate:query, etc.
      */
     tool: {
       ...beadsTools,
@@ -140,6 +143,7 @@ export const SwarmPlugin: Plugin = async (
       ...swarmTools,
       ...repoCrawlTools,
       ...skillsTools,
+      ...mandateTools,
     },
 
     /**
@@ -361,6 +365,7 @@ export const allTools = {
   ...swarmTools,
   ...repoCrawlTools,
   ...skillsTools,
+  ...mandateTools,
 } as const;
 
 /**
@@ -473,3 +478,76 @@ export {
   type SkillMetadata,
   type SkillRef,
 } from "./skills";
+
+/**
+ * Re-export mandates module
+ *
+ * Agent voting system for collaborative knowledge curation.
+ *
+ * Includes:
+ * - mandateTools - All mandate tools (file, vote, query, list, stats)
+ * - MandateError - Error class
+ *
+ * Features:
+ * - Submit ideas, tips, lore, snippets, and feature requests
+ * - Vote on entries (upvote/downvote) with 90-day decay
+ * - Semantic search for relevant mandates
+ * - Status transitions based on consensus (candidate → established → mandate)
+ * - Persistent storage with semantic-memory
+ *
+ * Types:
+ * - MandateEntry, Vote, MandateScore - Core data types
+ * - MandateStatus, MandateContentType - Enum types
+ */
+export { mandateTools, MandateError } from "./mandates";
+
+/**
+ * Re-export mandate-storage module
+ *
+ * Includes:
+ * - createMandateStorage - Factory function
+ * - getMandateStorage, setMandateStorage, resetMandateStorage - Global instance management
+ * - updateMandateStatus, updateAllMandateStatuses - Status update helpers
+ * - InMemoryMandateStorage, SemanticMemoryMandateStorage - Storage implementations
+ *
+ * Types:
+ * - MandateStorage - Unified storage interface
+ * - MandateStorageConfig, MandateStorageBackend, MandateStorageCollections - Configuration types
+ */
+export {
+  createMandateStorage,
+  getMandateStorage,
+  setMandateStorage,
+  resetMandateStorage,
+  updateMandateStatus,
+  updateAllMandateStatuses,
+  InMemoryMandateStorage,
+  SemanticMemoryMandateStorage,
+  DEFAULT_MANDATE_STORAGE_CONFIG,
+  type MandateStorage,
+  type MandateStorageConfig,
+  type MandateStorageBackend,
+  type MandateStorageCollections,
+} from "./mandate-storage";
+
+/**
+ * Re-export mandate-promotion module
+ *
+ * Includes:
+ * - evaluatePromotion - Evaluate status transitions
+ * - shouldPromote - Determine new status based on score
+ * - formatPromotionResult - Format promotion result for display
+ * - evaluateBatchPromotions, getStatusChanges, groupByTransition - Batch helpers
+ *
+ * Types:
+ * - PromotionResult - Promotion evaluation result
+ */
+export {
+  evaluatePromotion,
+  shouldPromote,
+  formatPromotionResult,
+  evaluateBatchPromotions,
+  getStatusChanges,
+  groupByTransition,
+  type PromotionResult,
+} from "./mandate-promotion";

package/src/learning.integration.test.ts

@@ -1427,3 +1427,313 @@ describe("Storage Module", () => {
     });
   });
 });
+
+// ============================================================================
+// 3-Strike Detection Tests
+// ============================================================================
+
+import {
+  InMemoryStrikeStorage,
+  addStrike,
+  getStrikes,
+  isStrikedOut,
+  getArchitecturePrompt,
+  clearStrikes,
+  type StrikeStorage,
+} from "./learning";
+
+describe("3-Strike Detection", () => {
+  let storage: StrikeStorage;
+
+  beforeEach(() => {
+    storage = new InMemoryStrikeStorage();
+  });
+
+  describe("addStrike", () => {
+    it("records first strike", async () => {
+      const record = await addStrike(
+        "test-bead-1",
+        "Attempted null check fix",
+        "Still getting undefined errors",
+        storage,
+      );
+
+      expect(record.bead_id).toBe("test-bead-1");
+      expect(record.strike_count).toBe(1);
+      expect(record.failures).toHaveLength(1);
+      expect(record.failures[0].attempt).toBe("Attempted null check fix");
+      expect(record.failures[0].reason).toBe("Still getting undefined errors");
+      expect(record.first_strike_at).toBeDefined();
+      expect(record.last_strike_at).toBeDefined();
+    });
+
+    it("increments strike count on subsequent strikes", async () => {
+      await addStrike("test-bead-2", "Fix 1", "Failed 1", storage);
+      const record2 = await addStrike(
+        "test-bead-2",
+        "Fix 2",
+        "Failed 2",
+        storage,
+      );
+
+      expect(record2.strike_count).toBe(2);
+      expect(record2.failures).toHaveLength(2);
+    });
+
+    it("caps strike count at 3", async () => {
+      await addStrike("test-bead-3", "Fix 1", "Failed 1", storage);
+      await addStrike("test-bead-3", "Fix 2", "Failed 2", storage);
+      await addStrike("test-bead-3", "Fix 3", "Failed 3", storage);
+      const record4 = await addStrike(
+        "test-bead-3",
+        "Fix 4",
+        "Failed 4",
+        storage,
+      );
+
+      expect(record4.strike_count).toBe(3);
+      expect(record4.failures).toHaveLength(4); // Records all attempts
+    });
+
+    it("preserves first_strike_at timestamp", async () => {
+      const record1 = await addStrike(
+        "test-bead-4",
+        "Fix 1",
+        "Failed 1",
+        storage,
+      );
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      const record2 = await addStrike(
+        "test-bead-4",
+        "Fix 2",
+        "Failed 2",
+        storage,
+      );
+
+      expect(record2.first_strike_at).toBe(record1.first_strike_at);
+      expect(record2.last_strike_at).not.toBe(record1.last_strike_at);
+    });
+  });
+
+  describe("getStrikes", () => {
+    it("returns 0 for bead with no strikes", async () => {
+      const count = await getStrikes("no-strikes-bead", storage);
+      expect(count).toBe(0);
+    });
+
+    it("returns correct strike count", async () => {
+      await addStrike("bead-with-strikes", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-with-strikes", "Fix 2", "Failed 2", storage);
+
+      const count = await getStrikes("bead-with-strikes", storage);
+      expect(count).toBe(2);
+    });
+  });
+
+  describe("isStrikedOut", () => {
+    it("returns false for bead with < 3 strikes", async () => {
+      await addStrike("bead-safe", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-safe", "Fix 2", "Failed 2", storage);
+
+      const strikedOut = await isStrikedOut("bead-safe", storage);
+      expect(strikedOut).toBe(false);
+    });
+
+    it("returns true for bead with 3 strikes", async () => {
+      await addStrike("bead-danger", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-danger", "Fix 2", "Failed 2", storage);
+      await addStrike("bead-danger", "Fix 3", "Failed 3", storage);
+
+      const strikedOut = await isStrikedOut("bead-danger", storage);
+      expect(strikedOut).toBe(true);
+    });
+
+    it("returns false for bead with no strikes", async () => {
+      const strikedOut = await isStrikedOut("no-record", storage);
+      expect(strikedOut).toBe(false);
+    });
+  });
+
+  describe("getArchitecturePrompt", () => {
+    it("returns empty string for bead with < 3 strikes", async () => {
+      await addStrike("bead-prompt-1", "Fix 1", "Failed 1", storage);
+
+      const prompt = await getArchitecturePrompt("bead-prompt-1", storage);
+      expect(prompt).toBe("");
+    });
+
+    it("returns empty string for bead with no strikes", async () => {
+      const prompt = await getArchitecturePrompt("no-strikes", storage);
+      expect(prompt).toBe("");
+    });
+
+    it("generates architecture review prompt for struck out bead", async () => {
+      await addStrike(
+        "bead-prompt-2",
+        "Added null checks",
+        "Still crashes on undefined",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-2",
+        "Used optional chaining",
+        "Runtime error persists",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-2",
+        "Wrapped in try-catch",
+        "Error still happening",
+        storage,
+      );
+
+      const prompt = await getArchitecturePrompt("bead-prompt-2", storage);
+
+      expect(prompt).toContain("Architecture Review Required");
+      expect(prompt).toContain("bead-prompt-2");
+      expect(prompt).toContain("Added null checks");
+      expect(prompt).toContain("Still crashes on undefined");
+      expect(prompt).toContain("Used optional chaining");
+      expect(prompt).toContain("Runtime error persists");
+      expect(prompt).toContain("Wrapped in try-catch");
+      expect(prompt).toContain("Error still happening");
+      expect(prompt).toContain("architectural problem");
+      expect(prompt).toContain("DO NOT attempt Fix #4");
+      expect(prompt).toContain("Refactor architecture");
+      expect(prompt).toContain("Continue with Fix #4");
+      expect(prompt).toContain("Abandon this approach");
+    });
+
+    it("lists all failures in order", async () => {
+      await addStrike(
+        "bead-prompt-3",
+        "First attempt",
+        "First failure",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-3",
+        "Second attempt",
+        "Second failure",
+        storage,
+      );
+      await addStrike(
+        "bead-prompt-3",
+        "Third attempt",
+        "Third failure",
+        storage,
+      );
+
+      const prompt = await getArchitecturePrompt("bead-prompt-3", storage);
+
+      const lines = prompt.split("\n");
+      const failureLine1 = lines.find((l) => l.includes("First attempt"));
+      const failureLine2 = lines.find((l) => l.includes("Second attempt"));
+      const failureLine3 = lines.find((l) => l.includes("Third attempt"));
+
+      expect(failureLine1).toBeDefined();
+      expect(failureLine2).toBeDefined();
+      expect(failureLine3).toBeDefined();
+
+      // Check ordering
+      const idx1 = lines.indexOf(failureLine1!);
+      const idx2 = lines.indexOf(failureLine2!);
+      const idx3 = lines.indexOf(failureLine3!);
+
+      expect(idx1).toBeLessThan(idx2);
+      expect(idx2).toBeLessThan(idx3);
+    });
+  });
+
+  describe("clearStrikes", () => {
+    it("clears strikes for a bead", async () => {
+      await addStrike("bead-clear", "Fix 1", "Failed 1", storage);
+      await addStrike("bead-clear", "Fix 2", "Failed 2", storage);
+
+      expect(await getStrikes("bead-clear", storage)).toBe(2);
+
+      await clearStrikes("bead-clear", storage);
+
+      expect(await getStrikes("bead-clear", storage)).toBe(0);
+      expect(await isStrikedOut("bead-clear", storage)).toBe(false);
+    });
+
+    it("handles clearing non-existent bead gracefully", async () => {
+      await expect(clearStrikes("no-bead", storage)).resolves.toBeUndefined();
+    });
+  });
+
+  describe("InMemoryStrikeStorage", () => {
+    it("stores and retrieves strike records", async () => {
+      const storage = new InMemoryStrikeStorage();
+      const record = await addStrike("bead-1", "Fix", "Failed", storage);
+
+      const retrieved = await storage.get("bead-1");
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.bead_id).toBe("bead-1");
+      expect(retrieved!.strike_count).toBe(1);
+    });
+
+    it("returns null for non-existent bead", async () => {
+      const storage = new InMemoryStrikeStorage();
+      const retrieved = await storage.get("non-existent");
+      expect(retrieved).toBeNull();
+    });
+
+    it("lists all strike records", async () => {
+      const storage = new InMemoryStrikeStorage();
+      await addStrike("bead-1", "Fix", "Failed", storage);
+      await addStrike("bead-2", "Fix", "Failed", storage);
+
+      const all = await storage.getAll();
+      expect(all).toHaveLength(2);
+    });
+
+    it("clears specific bead strikes", async () => {
+      const storage = new InMemoryStrikeStorage();
+      await addStrike("bead-1", "Fix", "Failed", storage);
+      await addStrike("bead-2", "Fix", "Failed", storage);
+
+      await storage.clear("bead-1");
+
+      expect(await storage.get("bead-1")).toBeNull();
+      expect(await storage.get("bead-2")).not.toBeNull();
+    });
+  });
+
+  describe("3-Strike Rule Integration", () => {
+    it("follows complete workflow from no strikes to architecture review", async () => {
+      const beadId = "integration-bead";
+
+      // Start: No strikes
+      expect(await getStrikes(beadId, storage)).toBe(0);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+      expect(await getArchitecturePrompt(beadId, storage)).toBe("");
+
+      // Strike 1
+      await addStrike(beadId, "Tried approach A", "Didn't work", storage);
+      expect(await getStrikes(beadId, storage)).toBe(1);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+
+      // Strike 2
+      await addStrike(beadId, "Tried approach B", "Also failed", storage);
+      expect(await getStrikes(beadId, storage)).toBe(2);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+
+      // Strike 3 - STRUCK OUT
+      await addStrike(beadId, "Tried approach C", "Still broken", storage);
+      expect(await getStrikes(beadId, storage)).toBe(3);
+      expect(await isStrikedOut(beadId, storage)).toBe(true);
+
+      // Architecture prompt should now be available
+      const prompt = await getArchitecturePrompt(beadId, storage);
+      expect(prompt).not.toBe("");
+      expect(prompt).toContain("Architecture Review Required");
+
+      // Clear strikes (e.g., after human intervention)
+      await clearStrikes(beadId, storage);
+      expect(await getStrikes(beadId, storage)).toBe(0);
+      expect(await isStrikedOut(beadId, storage)).toBe(false);
+    });
+  });
+});