opencode-swarm-plugin 0.14.0 → 0.16.0

package/src/schemas/mandate.ts

@@ -0,0 +1,232 @@
+/**
+ * Mandate schemas for voting system
+ *
+ * Agents file and vote on ideas, tips, lore, snippets, and feature requests.
+ * High-consensus items become "mandates" that influence future behavior.
+ *
+ * Vote decay and scoring patterns match learning.ts (90-day half-life).
+ */
+import { z } from "zod";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * Content types for mandate entries
+ */
+export const MandateContentTypeSchema = z.enum([
+  "idea",
+  "tip",
+  "lore",
+  "snippet",
+  "feature_request",
+]);
+export type MandateContentType = z.infer<typeof MandateContentTypeSchema>;
+
+/**
+ * Mandate status lifecycle
+ *
+ * - candidate: New entry, collecting votes
+ * - established: Has some consensus but not enough for mandate status
+ * - mandate: High consensus (net_votes >= 5 AND vote_ratio >= 0.7)
+ * - rejected: Strong negative consensus or explicitly rejected
+ */
+export const MandateStatusSchema = z.enum([
+  "candidate",
+  "established",
+  "mandate",
+  "rejected",
+]);
+export type MandateStatus = z.infer<typeof MandateStatusSchema>;
+
+/**
+ * Vote type
+ */
+export const VoteTypeSchema = z.enum(["upvote", "downvote"]);
+export type VoteType = z.infer<typeof VoteTypeSchema>;
+
+// ============================================================================
+// Entry Schema
+// ============================================================================
+
+/**
+ * A mandate entry represents a proposal from an agent
+ *
+ * Entries can be ideas, tips, lore, code snippets, or feature requests.
+ * Other agents vote on entries to reach consensus.
+ */
+export const MandateEntrySchema = z.object({
+  /** Unique ID for this entry */
+  id: z.string(),
+  /** The actual content of the mandate */
+  content: z.string().min(1, "Content required"),
+  /** Type of content */
+  content_type: MandateContentTypeSchema,
+  /** Agent that created this entry */
+  author_agent: z.string(),
+  /** When this entry was created (ISO-8601) */
+  created_at: z.string().datetime({ offset: true }),
+  /** Current status */
+  status: MandateStatusSchema.default("candidate"),
+  /** Optional tags for categorization and search */
+  tags: z.array(z.string()).default([]),
+  /** Optional metadata (e.g., code language for snippets) */
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type MandateEntry = z.infer<typeof MandateEntrySchema>;
+
+// ============================================================================
+// Vote Schema
+// ============================================================================
+
+/**
+ * A vote on a mandate entry
+ *
+ * Each agent can vote once per entry (upvote or downvote).
+ * Votes decay with 90-day half-life matching learning.ts patterns.
+ */
+export const VoteSchema = z.object({
+  /** Unique ID for this vote */
+  id: z.string(),
+  /** The mandate entry this vote applies to */
+  mandate_id: z.string(),
+  /** Agent that cast this vote */
+  agent_name: z.string(),
+  /** Type of vote */
+  vote_type: VoteTypeSchema,
+  /** When this vote was cast (ISO-8601) */
+  timestamp: z.string().datetime({ offset: true }),
+  /** Raw vote weight before decay (default: 1.0) */
+  weight: z.number().min(0).max(1).default(1.0),
+});
+export type Vote = z.infer<typeof VoteSchema>;
+
+// ============================================================================
+// Score Schema
+// ============================================================================
+
+/**
+ * Calculated score for a mandate entry
+ *
+ * Scores are recalculated periodically with decay applied.
+ * Uses same decay formula as learning.ts (90-day half-life).
+ */
+export const MandateScoreSchema = z.object({
+  /** The mandate entry this score applies to */
+  mandate_id: z.string(),
+  /** Net votes (upvotes - downvotes) with decay applied */
+  net_votes: z.number(),
+  /** Vote ratio: upvotes / (upvotes + downvotes) */
+  vote_ratio: z.number().min(0).max(1),
+  /** Final decayed score for ranking */
+  decayed_score: z.number(),
+  /** When this score was last calculated (ISO-8601) */
+  last_calculated: z.string().datetime({ offset: true }),
+  /** Raw vote counts (before decay) */
+  raw_upvotes: z.number().int().min(0),
+  raw_downvotes: z.number().int().min(0),
+  /** Decayed vote counts */
+  decayed_upvotes: z.number().min(0),
+  decayed_downvotes: z.number().min(0),
+});
+export type MandateScore = z.infer<typeof MandateScoreSchema>;
+
+// ============================================================================
+// Decay Configuration
+// ============================================================================
+
+/**
+ * Configuration for mandate decay calculation
+ *
+ * Matches learning.ts decay patterns.
+ */
+export interface MandateDecayConfig {
+  /** Half-life for vote decay in days */
+  halfLifeDays: number;
+  /** Net votes threshold for mandate status */
+  mandateNetVotesThreshold: number;
+  /** Vote ratio threshold for mandate status */
+  mandateVoteRatioThreshold: number;
+  /** Net votes threshold for established status */
+  establishedNetVotesThreshold: number;
+  /** Negative net votes threshold for rejected status */
+  rejectedNetVotesThreshold: number;
+}
+
+export const DEFAULT_MANDATE_DECAY_CONFIG: MandateDecayConfig = {
+  halfLifeDays: 90,
+  mandateNetVotesThreshold: 5,
+  mandateVoteRatioThreshold: 0.7,
+  establishedNetVotesThreshold: 2,
+  rejectedNetVotesThreshold: -3,
+};
+
+// ============================================================================
+// API Schemas
+// ============================================================================
+
+/**
+ * Arguments for creating a mandate entry
+ */
+export const CreateMandateArgsSchema = z.object({
+  content: z.string().min(1, "Content required"),
+  content_type: MandateContentTypeSchema,
+  tags: z.array(z.string()).default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CreateMandateArgs = z.infer<typeof CreateMandateArgsSchema>;
+
+/**
+ * Arguments for casting a vote
+ */
+export const CastVoteArgsSchema = z.object({
+  mandate_id: z.string(),
+  vote_type: VoteTypeSchema,
+  weight: z.number().min(0).max(1).default(1.0),
+});
+export type CastVoteArgs = z.infer<typeof CastVoteArgsSchema>;
+
+/**
+ * Arguments for querying mandates
+ */
+export const QueryMandatesArgsSchema = z.object({
+  status: MandateStatusSchema.optional(),
+  content_type: MandateContentTypeSchema.optional(),
+  tags: z.array(z.string()).optional(),
+  author_agent: z.string().optional(),
+  limit: z.number().int().positive().default(20),
+  min_score: z.number().optional(),
+});
+export type QueryMandatesArgs = z.infer<typeof QueryMandatesArgsSchema>;
+
+/**
+ * Result of score calculation
+ */
+export const ScoreCalculationResultSchema = z.object({
+  mandate_id: z.string(),
+  previous_status: MandateStatusSchema,
+  new_status: MandateStatusSchema,
+  score: MandateScoreSchema,
+  status_changed: z.boolean(),
+});
+export type ScoreCalculationResult = z.infer<
+  typeof ScoreCalculationResultSchema
+>;
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export const mandateSchemas = {
+  MandateContentTypeSchema,
+  MandateStatusSchema,
+  VoteTypeSchema,
+  MandateEntrySchema,
+  VoteSchema,
+  MandateScoreSchema,
+  CreateMandateArgsSchema,
+  CastVoteArgsSchema,
+  QueryMandatesArgsSchema,
+  ScoreCalculationResultSchema,
+};

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({