opencode-swarm-plugin 0.14.0 → 0.15.0

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

@@ -95,30 +95,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
-// 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
+// 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
+// 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 +309,16 @@ 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                                  |
+| ------------------------ | ------------------------------------------ | ------------------------------------ |
+| **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.15.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

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);
+    });
+  });
+});

package/src/learning.ts

@@ -524,6 +524,203 @@ export class InMemoryFeedbackStorage implements FeedbackStorage {
   }
 }
 
+// ============================================================================
+// 3-Strike Detection
+// ============================================================================
+
+/**
+ * Strike record for a bead
+ *
+ * Tracks consecutive fix failures to detect architectural problems.
+ * After 3 strikes, the system should STOP and question the architecture
+ * rather than attempting Fix #4.
+ */
+export const StrikeRecordSchema = z.object({
+  /** The bead ID */
+  bead_id: z.string(),
+  /** Number of consecutive failures */
+  strike_count: z.number().int().min(0).max(3),
+  /** Failure descriptions for each strike */
+  failures: z.array(
+    z.object({
+      /** What fix was attempted */
+      attempt: z.string(),
+      /** Why it failed */
+      reason: z.string(),
+      /** When it failed */
+      timestamp: z.string(), // ISO-8601
+    }),
+  ),
+  /** When strikes were recorded */
+  first_strike_at: z.string().optional(), // ISO-8601
+  last_strike_at: z.string().optional(), // ISO-8601
+});
+export type StrikeRecord = z.infer<typeof StrikeRecordSchema>;
+
+/**
+ * Storage interface for strike records
+ */
+export interface StrikeStorage {
+  /** Store a strike record */
+  store(record: StrikeRecord): Promise<void>;
+  /** Get strike record for a bead */
+  get(beadId: string): Promise<StrikeRecord | null>;
+  /** Get all strike records */
+  getAll(): Promise<StrikeRecord[]>;
+  /** Clear strikes for a bead */
+  clear(beadId: string): Promise<void>;
+}
+
+/**
+ * In-memory strike storage
+ */
+export class InMemoryStrikeStorage implements StrikeStorage {
+  private strikes: Map<string, StrikeRecord> = new Map();
+
+  async store(record: StrikeRecord): Promise<void> {
+    this.strikes.set(record.bead_id, record);
+  }
+
+  async get(beadId: string): Promise<StrikeRecord | null> {
+    return this.strikes.get(beadId) ?? null;
+  }
+
+  async getAll(): Promise<StrikeRecord[]> {
+    return Array.from(this.strikes.values());
+  }
+
+  async clear(beadId: string): Promise<void> {
+    this.strikes.delete(beadId);
+  }
+}
+
+/**
+ * Add a strike to a bead's record
+ *
+ * Records a failure attempt and increments the strike count.
+ *
+ * @param beadId - Bead ID
+ * @param attempt - Description of what was attempted
+ * @param reason - Why it failed
+ * @param storage - Strike storage (defaults to in-memory)
+ * @returns Updated strike record
+ */
+export async function addStrike(
+  beadId: string,
+  attempt: string,
+  reason: string,
+  storage: StrikeStorage = new InMemoryStrikeStorage(),
+): Promise<StrikeRecord> {
+  const existing = await storage.get(beadId);
+  const now = new Date().toISOString();
+
+  const record: StrikeRecord = existing ?? {
+    bead_id: beadId,
+    strike_count: 0,
+    failures: [],
+  };
+
+  record.strike_count = Math.min(3, record.strike_count + 1);
+  record.failures.push({ attempt, reason, timestamp: now });
+  record.last_strike_at = now;
+
+  if (!record.first_strike_at) {
+    record.first_strike_at = now;
+  }
+
+  await storage.store(record);
+  return record;
+}
+
+/**
+ * Get strike count for a bead
+ *
+ * @param beadId - Bead ID
+ * @param storage - Strike storage
+ * @returns Strike count (0-3)
+ */
+export async function getStrikes(
+  beadId: string,
+  storage: StrikeStorage = new InMemoryStrikeStorage(),
+): Promise<number> {
+  const record = await storage.get(beadId);
+  return record?.strike_count ?? 0;
+}
+
+/**
+ * Check if a bead has struck out (3 strikes)
+ *
+ * @param beadId - Bead ID
+ * @param storage - Strike storage
+ * @returns True if bead has 3 strikes
+ */
+export async function isStrikedOut(
+  beadId: string,
+  storage: StrikeStorage = new InMemoryStrikeStorage(),
+): Promise<boolean> {
+  const count = await getStrikes(beadId, storage);
+  return count >= 3;
+}
+
+/**
+ * Generate architecture review prompt for a struck-out bead
+ *
+ * When a bead hits 3 strikes, this generates a prompt that forces
+ * the human to question the architecture instead of attempting Fix #4.
+ *
+ * @param beadId - Bead ID
+ * @param storage - Strike storage
+ * @returns Architecture review prompt
+ */
+export async function getArchitecturePrompt(
+  beadId: string,
+  storage: StrikeStorage = new InMemoryStrikeStorage(),
+): Promise<string> {
+  const record = await storage.get(beadId);
+
+  if (!record || record.strike_count < 3) {
+    return "";
+  }
+
+  const failuresList = record.failures
+    .map((f, i) => `${i + 1}. **${f.attempt}** - Failed: ${f.reason}`)
+    .join("\n");
+
+  return `## Architecture Review Required
+
+This bead (\`${beadId}\`) has failed 3 consecutive fix attempts:
+
+${failuresList}
+
+This pattern suggests an **architectural problem**, not a bug.
+
+**Questions to consider:**
+- Is the current approach fundamentally sound?
+- Should we refactor the architecture instead?
+- Are we fixing symptoms instead of root cause?
+
+**Options:**
+1. **Refactor architecture** (describe new approach)
+2. **Continue with Fix #4** (explain why this time is different)
+3. **Abandon this approach entirely**
+
+**DO NOT attempt Fix #4 without answering these questions.**
+`;
+}
+
+/**
+ * Clear strikes for a bead (e.g., after successful fix)
+ *
+ * @param beadId - Bead ID
+ * @param storage - Strike storage
+ */
+export async function clearStrikes(
+  beadId: string,
+  storage: StrikeStorage = new InMemoryStrikeStorage(),
+): Promise<void> {
+  await storage.clear(beadId);
+}
+
 // ============================================================================
 // Error Accumulator
 // ============================================================================
@@ -772,4 +969,5 @@ export const learningSchemas = {
   DecompositionStrategySchema,
   ErrorTypeSchema,
   ErrorEntrySchema,
+  StrikeRecordSchema,
 };