opencode-swarm-plugin 0.13.2 → 0.15.0

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,
 };

package/src/skills.test.ts

@@ -357,6 +357,200 @@ describe("ES module compatibility", () => {
   });
 });
 
+// ============================================================================
+// Tests: CSO Validation
+// ============================================================================
+
+import { validateCSOCompliance } from "./skills";
+
+describe("validateCSOCompliance", () => {
+  describe("description validation", () => {
+    it("passes for CSO-compliant description with 'Use when'", () => {
+      const warnings = validateCSOCompliance(
+        "testing-async",
+        "Use when tests have race conditions - replaces arbitrary timeouts with condition polling",
+      );
+
+      expect(warnings.critical).toHaveLength(0);
+      expect(warnings.suggestions).toHaveLength(0);
+    });
+
+    it("warns when missing 'Use when...' pattern", () => {
+      const warnings = validateCSOCompliance(
+        "testing-async",
+        "For async testing patterns",
+      );
+
+      expect(warnings.critical).toContain(
+        "Description should include 'Use when...' to focus on triggering conditions",
+      );
+    });
+
+    it("warns for first-person voice", () => {
+      const warnings = validateCSOCompliance(
+        "testing-async",
+        "I can help you with async tests when I detect race conditions",
+      );
+
+      expect(warnings.critical.some((w) => w.includes("first-person"))).toBe(
+        true,
+      );
+    });
+
+    it("warns for second-person voice", () => {
+      const warnings = validateCSOCompliance(
+        "testing-async",
+        "Use when you need to test async code and your tests have race conditions",
+      );
+
+      expect(warnings.critical.some((w) => w.includes("second-person"))).toBe(
+        true,
+      );
+    });
+
+    it("rejects description > 1024 chars", () => {
+      const longDesc = "a".repeat(1025);
+      const warnings = validateCSOCompliance("test", longDesc);
+
+      expect(
+        warnings.critical.some(
+          (w) => w.includes("1025") && w.includes("max 1024"),
+        ),
+      ).toBe(true);
+    });
+
+    it("suggests improvement for description > 500 chars", () => {
+      const mediumDesc = "Use when testing. " + "a".repeat(490);
+      const warnings = validateCSOCompliance("test", mediumDesc);
+
+      expect(warnings.critical).toHaveLength(0); // Not critical
+      expect(warnings.suggestions.some((w) => w.includes("aim for <500"))).toBe(
+        true,
+      );
+    });
+
+    it("accepts description < 500 chars with no length warnings", () => {
+      const shortDesc =
+        "Use when tests have race conditions - replaces timeouts";
+      const warnings = validateCSOCompliance("testing-async", shortDesc);
+
+      const hasLengthWarning =
+        warnings.critical.some((w) => w.includes("chars")) ||
+        warnings.suggestions.some((w) => w.includes("chars"));
+
+      expect(hasLengthWarning).toBe(false);
+    });
+  });
+
+  describe("name validation", () => {
+    it("accepts gerund-based names", () => {
+      const warnings = validateCSOCompliance(
+        "testing-async",
+        "Use when testing async code",
+      );
+
+      const hasNameWarning = warnings.suggestions.some((w) =>
+        w.includes("verb-first"),
+      );
+      expect(hasNameWarning).toBe(false);
+    });
+
+    it("accepts verb-first names", () => {
+      const warnings = validateCSOCompliance(
+        "validate-schemas",
+        "Use when validating schemas",
+      );
+
+      const hasNameWarning = warnings.suggestions.some((w) =>
+        w.includes("verb-first"),
+      );
+      expect(hasNameWarning).toBe(false);
+    });
+
+    it("accepts action verbs", () => {
+      const actionVerbs = [
+        "test-runner",
+        "debug-tools",
+        "scan-code",
+        "check-types",
+        "build-artifacts",
+      ];
+
+      for (const name of actionVerbs) {
+        const warnings = validateCSOCompliance(name, "Use when testing");
+        const hasNameWarning = warnings.suggestions.some((w) =>
+          w.includes("verb-first"),
+        );
+        expect(hasNameWarning).toBe(false);
+      }
+    });
+
+    it("suggests verb-first for noun-first names", () => {
+      const warnings = validateCSOCompliance(
+        "async-test",
+        "Use when testing async",
+      );
+
+      expect(
+        warnings.suggestions.some((w) =>
+          w.includes("doesn't follow verb-first"),
+        ),
+      ).toBe(true);
+    });
+
+    it("warns for name > 64 chars", () => {
+      const longName = "a".repeat(65);
+      const warnings = validateCSOCompliance(longName, "Use when testing");
+
+      expect(warnings.critical.some((w) => w.includes("64 character"))).toBe(
+        true,
+      );
+    });
+
+    it("warns for invalid name format", () => {
+      const warnings = validateCSOCompliance(
+        "Invalid_Name",
+        "Use when testing",
+      );
+
+      expect(
+        warnings.critical.some((w) =>
+          w.includes("lowercase letters, numbers, and hyphens"),
+        ),
+      ).toBe(true);
+    });
+  });
+
+  describe("comprehensive examples", () => {
+    it("perfect CSO compliance", () => {
+      const warnings = validateCSOCompliance(
+        "testing-race-conditions",
+        "Use when tests have race conditions - replaces arbitrary timeouts with condition polling and retry logic",
+      );
+
+      expect(warnings.critical).toHaveLength(0);
+      expect(warnings.suggestions).toHaveLength(0);
+    });
+
+    it("multiple critical issues", () => {
+      const warnings = validateCSOCompliance(
+        "BadName_123",
+        "I can help you test async code when you need to avoid race conditions. " +
+          "a".repeat(1000),
+      );
+
+      expect(warnings.critical.length).toBeGreaterThan(2);
+      expect(warnings.critical.some((w) => w.includes("first-person"))).toBe(
+        true,
+      );
+      expect(warnings.critical.some((w) => w.includes("second-person"))).toBe(
+        true,
+      );
+      expect(warnings.critical.some((w) => w.includes("lowercase"))).toBe(true);
+    });
+  });
+});
+
 // ============================================================================
 // Tests: Edge Cases
 // ============================================================================

package/src/skills.ts

@@ -628,6 +628,167 @@ Use this to access supplementary skill resources.`,
  */
 const DEFAULT_SKILLS_DIR = ".opencode/skills";
 
+// =============================================================================
+// CSO (Claude Search Optimization) Validation
+// =============================================================================
+
+/**
+ * CSO validation warnings for skill metadata
+ */
+export interface CSOValidationWarnings {
+  /** Critical warnings (strong indicators of poor discoverability) */
+  critical: string[];
+  /** Suggestions for improvement */
+  suggestions: string[];
+}
+
+/**
+ * Validate skill metadata against Claude Search Optimization best practices
+ *
+ * Checks:
+ * - 'Use when...' format in description
+ * - Description length (warn > 500, max 1024)
+ * - Third-person voice (no 'I', 'you')
+ * - Name conventions (verb-first, gerunds, hyphens)
+ *
+ * @returns Warnings object with critical issues and suggestions
+ */
+export function validateCSOCompliance(
+  name: string,
+  description: string,
+): CSOValidationWarnings {
+  const warnings: CSOValidationWarnings = {
+    critical: [],
+    suggestions: [],
+  };
+
+  // Description: Check for 'Use when...' pattern
+  const hasUseWhen = /\buse when\b/i.test(description);
+  if (!hasUseWhen) {
+    warnings.critical.push(
+      "Description should include 'Use when...' to focus on triggering conditions",
+    );
+  }
+
+  // Description: Length checks
+  if (description.length > 1024) {
+    warnings.critical.push(
+      `Description is ${description.length} chars (max 1024) - will be rejected`,
+    );
+  } else if (description.length > 500) {
+    warnings.suggestions.push(
+      `Description is ${description.length} chars (aim for <500 for optimal discoverability)`,
+    );
+  }
+
+  // Description: Third-person check (no 'I', 'you')
+  const firstPersonPattern = /\b(I|I'm|I'll|my|mine|myself)\b/i;
+  const secondPersonPattern = /\b(you|you're|you'll|your|yours|yourself)\b/i;
+
+  if (firstPersonPattern.test(description)) {
+    warnings.critical.push(
+      "Description uses first-person ('I', 'my') - skills are injected into system prompt, use third-person only",
+    );
+  }
+
+  if (secondPersonPattern.test(description)) {
+    warnings.critical.push(
+      "Description uses second-person ('you', 'your') - use third-person voice (e.g., 'Handles X' not 'You can handle X')",
+    );
+  }
+
+  // Name: Check for verb-first/gerund patterns
+  const nameWords = name.split("-");
+  const firstWord = nameWords[0];
+
+  // Common gerund endings: -ing
+  // Common verb forms: -ing, -ize, -ify, -ate
+  const isGerund = /ing$/.test(firstWord);
+  const isVerbForm = /(ing|ize|ify|ate)$/.test(firstWord);
+
+  if (!isGerund && !isVerbForm) {
+    // Check if it's a common action verb
+    const actionVerbs = [
+      "test",
+      "debug",
+      "fix",
+      "scan",
+      "check",
+      "validate",
+      "create",
+      "build",
+      "deploy",
+      "run",
+      "load",
+      "fetch",
+      "parse",
+    ];
+    const startsWithAction = actionVerbs.includes(firstWord);
+
+    if (!startsWithAction) {
+      warnings.suggestions.push(
+        `Name '${name}' doesn't follow verb-first pattern. Consider gerunds (e.g., 'testing-skills' not 'test-skill') or action verbs for better clarity`,
+      );
+    }
+  }
+
+  // Name: Check length
+  if (name.length > 64) {
+    warnings.critical.push(
+      `Name exceeds 64 character limit (${name.length} chars)`,
+    );
+  }
+
+  // Name: Validate format (already enforced by schema, but good to document)
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    warnings.critical.push(
+      "Name must be lowercase letters, numbers, and hyphens only",
+    );
+  }
+
+  return warnings;
+}
+
+/**
+ * Format CSO warnings into a readable message for tool output
+ */
+function formatCSOWarnings(warnings: CSOValidationWarnings): string | null {
+  if (warnings.critical.length === 0 && warnings.suggestions.length === 0) {
+    return null;
+  }
+
+  const parts: string[] = [];
+
+  if (warnings.critical.length > 0) {
+    parts.push("**CSO Critical Issues:**");
+    for (const warning of warnings.critical) {
+      parts.push(`  ⚠️  ${warning}`);
+    }
+  }
+
+  if (warnings.suggestions.length > 0) {
+    parts.push("\n**CSO Suggestions:**");
+    for (const suggestion of warnings.suggestions) {
+      parts.push(`  💡 ${suggestion}`);
+    }
+  }
+
+  parts.push("\n**CSO Guide:**");
+  parts.push(
+    "  • Start description with 'Use when...' (focus on triggering conditions)",
+  );
+  parts.push("  • Keep description <500 chars (max 1024)");
+  parts.push("  • Use third-person voice only (injected into system prompt)");
+  parts.push(
+    "  • Name: verb-first or gerunds (e.g., 'testing-async' not 'async-test')",
+  );
+  parts.push(
+    "\n  Example: 'Use when tests have race conditions - replaces arbitrary timeouts with condition polling'",
+  );
+
+  return parts.join("\n");
+}
+
 /**
  * Quote a YAML scalar if it contains special characters
  * Uses double quotes and escapes internal quotes/newlines
@@ -749,6 +910,9 @@ Good skills have:
       return `Skill '${args.name}' already exists at ${existing.path}. Use skills_update to modify it.`;
     }
 
+    // Validate CSO compliance (advisory warnings only)
+    const csoWarnings = validateCSOCompliance(args.name, args.description);
+
     // Determine target directory
     let skillDir: string;
     if (args.directory === "global") {
@@ -778,21 +942,26 @@ Good skills have:
       // Invalidate cache so new skill is discoverable
       invalidateSkillsCache();
 
-      return JSON.stringify(
-        {
-          success: true,
-          skill: args.name,
-          path: skillPath,
-          message: `Created skill '${args.name}'. It's now discoverable via skills_list.`,
-          next_steps: [
-            "Test with skills_use to verify instructions are clear",
-            "Add examples.md or reference.md for supplementary content",
-            "Add scripts/ directory for executable helpers",
-          ],
-        },
-        null,
-        2,
-      );
+      // Build response with CSO warnings if present
+      const response: Record<string, unknown> = {
+        success: true,
+        skill: args.name,
+        path: skillPath,
+        message: `Created skill '${args.name}'. It's now discoverable via skills_list.`,
+        next_steps: [
+          "Test with skills_use to verify instructions are clear",
+          "Add examples.md or reference.md for supplementary content",
+          "Add scripts/ directory for executable helpers",
+        ],
+      };
+
+      // Add CSO warnings if any
+      const warningsMessage = formatCSOWarnings(csoWarnings);
+      if (warningsMessage) {
+        response.cso_warnings = warningsMessage;
+      }
+
+      return JSON.stringify(response, null, 2);
     } catch (error) {
       return `Failed to create skill: ${error instanceof Error ? error.message : String(error)}`;
     }

package/src/swarm.integration.test.ts

@@ -1231,10 +1231,10 @@ describe("Graceful Degradation", () => {
       mockContext,
     );
 
-    // Check that agent-mail discipline is in the prompt
+    // Check that swarm-mail discipline is in the prompt
     expect(result).toContain("MANDATORY");
-    expect(result).toContain("Agent Mail");
-    expect(result).toContain("agentmail_send");
+    expect(result).toContain("Swarm Mail");
+    expect(result).toContain("swarmmail_send");
     expect(result).toContain("Report progress");
   });
 });
@@ -1243,7 +1243,7 @@ describe("Graceful Degradation", () => {
 // Coordinator-Centric Swarm Tools (V2)
 // ============================================================================
 
-describe("Swarm Prompt V2 (with Agent Mail/Beads)", () => {
+describe("Swarm Prompt V2 (with Swarm Mail/Beads)", () => {
   describe("formatSubtaskPromptV2", () => {
     it("generates correct prompt with all fields", () => {
       const result = formatSubtaskPromptV2({