opencode-swarm-plugin 0.5.0 → 0.6.1

package/dist/plugin.js

@@ -23360,6 +23360,11 @@ var CriterionWeightSchema = exports_external.object({
   last_validated: exports_external.string().optional(),
   half_life_days: exports_external.number().positive().default(90)
 });
+var DecompositionStrategySchema = exports_external.enum([
+  "file-based",
+  "feature-based",
+  "risk-based"
+]);
 var OutcomeSignalsSchema = exports_external.object({
   bead_id: exports_external.string(),
   duration_ms: exports_external.number().int().min(0),
@@ -23367,7 +23372,8 @@ var OutcomeSignalsSchema = exports_external.object({
   retry_count: exports_external.number().int().min(0),
   success: exports_external.boolean(),
   files_touched: exports_external.array(exports_external.string()).default([]),
-  timestamp: exports_external.string()
+  timestamp: exports_external.string(),
+  strategy: DecompositionStrategySchema.optional()
 });
 var ScoredOutcomeSchema = exports_external.object({
   signals: OutcomeSignalsSchema,
@@ -23512,6 +23518,167 @@ function detectInstructionConflicts(subtasks) {
   }
   return conflicts;
 }
+var STRATEGIES = {
+  "file-based": {
+    name: "file-based",
+    description: "Group by file type or directory. Best for refactoring, migrations, and pattern changes across codebase.",
+    keywords: [
+      "refactor",
+      "migrate",
+      "update all",
+      "rename",
+      "replace",
+      "convert",
+      "upgrade",
+      "deprecate",
+      "remove",
+      "cleanup",
+      "lint",
+      "format"
+    ],
+    guidelines: [
+      "Group files by directory or type (e.g., all components, all tests)",
+      "Minimize cross-directory dependencies within a subtask",
+      "Handle shared types/utilities first if they change",
+      "Each subtask should be a complete transformation of its file set",
+      "Consider import/export relationships when grouping"
+    ],
+    antiPatterns: [
+      "Don't split tightly coupled files across subtasks",
+      "Don't group files that have no relationship",
+      "Don't forget to update imports when moving/renaming"
+    ],
+    examples: [
+      "Migrate all components to new API \u2192 split by component directory",
+      "Rename userId to accountId \u2192 split by module (types first, then consumers)",
+      "Update all tests to use new matcher \u2192 split by test directory"
+    ]
+  },
+  "feature-based": {
+    name: "feature-based",
+    description: "Vertical slices with UI + API + data. Best for new features and adding functionality.",
+    keywords: [
+      "add",
+      "implement",
+      "build",
+      "create",
+      "feature",
+      "new",
+      "integrate",
+      "connect",
+      "enable",
+      "support"
+    ],
+    guidelines: [
+      "Each subtask is a complete vertical slice (UI + logic + data)",
+      "Start with data layer/types, then logic, then UI",
+      "Keep related components together (form + validation + submission)",
+      "Separate concerns that can be developed independently",
+      "Consider user-facing features as natural boundaries"
+    ],
+    antiPatterns: [
+      "Don't split a single feature across multiple subtasks",
+      "Don't create subtasks that can't be tested independently",
+      "Don't forget integration points between features"
+    ],
+    examples: [
+      "Add user auth \u2192 [OAuth setup, Session management, Protected routes]",
+      "Build dashboard \u2192 [Data fetching, Chart components, Layout/navigation]",
+      "Add search \u2192 [Search API, Search UI, Results display]"
+    ]
+  },
+  "risk-based": {
+    name: "risk-based",
+    description: "Isolate high-risk changes, add tests first. Best for bug fixes, security issues, and critical changes.",
+    keywords: [
+      "fix",
+      "bug",
+      "security",
+      "vulnerability",
+      "critical",
+      "urgent",
+      "hotfix",
+      "patch",
+      "audit",
+      "review",
+      "investigate"
+    ],
+    guidelines: [
+      "Write tests FIRST to capture expected behavior",
+      "Isolate the risky change to minimize blast radius",
+      "Add monitoring/logging around the change",
+      "Create rollback plan as part of the task",
+      "Audit similar code for the same issue"
+    ],
+    antiPatterns: [
+      "Don't make multiple risky changes in one subtask",
+      "Don't skip tests for 'simple' fixes",
+      "Don't forget to check for similar issues elsewhere"
+    ],
+    examples: [
+      "Fix auth bypass \u2192 [Add regression test, Fix vulnerability, Audit similar endpoints]",
+      "Fix race condition \u2192 [Add test reproducing issue, Implement fix, Add concurrency tests]",
+      "Security audit \u2192 [Scan for vulnerabilities, Fix critical issues, Document remaining risks]"
+    ]
+  }
+};
+function selectStrategy(task) {
+  const taskLower = task.toLowerCase();
+  const scores = {
+    "file-based": 0,
+    "feature-based": 0,
+    "risk-based": 0
+  };
+  for (const [strategyName, definition] of Object.entries(STRATEGIES)) {
+    const name = strategyName;
+    for (const keyword of definition.keywords) {
+      if (taskLower.includes(keyword)) {
+        scores[name] += 1;
+      }
+    }
+  }
+  const entries = Object.entries(scores);
+  entries.sort((a, b) => b[1] - a[1]);
+  const [winner, winnerScore] = entries[0];
+  const [runnerUp, runnerUpScore] = entries[1] || [null, 0];
+  const totalScore = entries.reduce((sum, [, score]) => sum + score, 0);
+  const confidence = totalScore > 0 ? Math.min(0.95, 0.5 + (winnerScore - runnerUpScore) / totalScore) : 0.5;
+  let reasoning;
+  if (winnerScore === 0) {
+    reasoning = `No strong keyword signals. Defaulting to feature-based as it's most versatile.`;
+  } else {
+    const matchedKeywords = STRATEGIES[winner].keywords.filter((k) => taskLower.includes(k));
+    reasoning = `Matched keywords: ${matchedKeywords.join(", ")}. ${STRATEGIES[winner].description}`;
+  }
+  const finalStrategy = winnerScore === 0 ? "feature-based" : winner;
+  return {
+    strategy: finalStrategy,
+    confidence,
+    reasoning,
+    alternatives: entries.filter(([s]) => s !== finalStrategy).map(([strategy, score]) => ({ strategy, score }))
+  };
+}
+function formatStrategyGuidelines(strategy) {
+  const def = STRATEGIES[strategy];
+  const guidelines = def.guidelines.map((g) => `- ${g}`).join(`
+`);
+  const antiPatterns = def.antiPatterns.map((a) => `- ${a}`).join(`
+`);
+  const examples = def.examples.map((e) => `- ${e}`).join(`
+`);
+  return `## Strategy: ${strategy}
+
+${def.description}
+
+### Guidelines
+${guidelines}
+
+### Anti-Patterns (Avoid These)
+${antiPatterns}
+
+### Examples
+${examples}`;
+}
 var DECOMPOSITION_PROMPT = `You are decomposing a task into parallelizable subtasks for a swarm of agents.
 
 ## Task
@@ -23877,6 +24044,155 @@ function formatCassHistoryForPrompt(history) {
   return lines.join(`
 `);
 }
+var swarm_select_strategy = tool({
+  description: "Analyze task and recommend decomposition strategy (file-based, feature-based, or risk-based)",
+  args: {
+    task: tool.schema.string().min(1).describe("Task description to analyze"),
+    codebase_context: tool.schema.string().optional().describe("Optional codebase context (file structure, tech stack, etc.)")
+  },
+  async execute(args) {
+    const result = selectStrategy(args.task);
+    let enhancedReasoning = result.reasoning;
+    if (args.codebase_context) {
+      enhancedReasoning += `
+
+Codebase context considered: ${args.codebase_context.slice(0, 200)}...`;
+    }
+    return JSON.stringify({
+      strategy: result.strategy,
+      confidence: Math.round(result.confidence * 100) / 100,
+      reasoning: enhancedReasoning,
+      description: STRATEGIES[result.strategy].description,
+      guidelines: STRATEGIES[result.strategy].guidelines,
+      anti_patterns: STRATEGIES[result.strategy].antiPatterns,
+      alternatives: result.alternatives.map((alt) => ({
+        strategy: alt.strategy,
+        description: STRATEGIES[alt.strategy].description,
+        score: alt.score
+      }))
+    }, null, 2);
+  }
+});
+var STRATEGY_DECOMPOSITION_PROMPT = `You are decomposing a task into parallelizable subtasks for a swarm of agents.
+
+## Task
+{task}
+
+{strategy_guidelines}
+
+{context_section}
+
+{cass_history}
+
+## MANDATORY: Beads Issue Tracking
+
+**Every subtask MUST become a bead.** This is non-negotiable.
+
+After decomposition, the coordinator will:
+1. Create an epic bead for the overall task
+2. Create child beads for each subtask
+3. Track progress through bead status updates
+4. Close beads with summaries when complete
+
+Agents MUST update their bead status as they work. No silent progress.
+
+## Requirements
+
+1. **Break into 2-{max_subtasks} independent subtasks** that can run in parallel
+2. **Assign files** - each subtask must specify which files it will modify
+3. **No file overlap** - files cannot appear in multiple subtasks (they get exclusive locks)
+4. **Order by dependency** - if subtask B needs subtask A's output, A must come first in the array
+5. **Estimate complexity** - 1 (trivial) to 5 (complex)
+6. **Plan aggressively** - break down more than you think necessary, smaller is better
+
+## Response Format
+
+Respond with a JSON object matching this schema:
+
+\`\`\`typescript
+{
+  epic: {
+    title: string,        // Epic title for the beads tracker
+    description?: string  // Brief description of the overall goal
+  },
+  subtasks: [
+    {
+      title: string,              // What this subtask accomplishes
+      description?: string,       // Detailed instructions for the agent
+      files: string[],            // Files this subtask will modify (globs allowed)
+      dependencies: number[],     // Indices of subtasks this depends on (0-indexed)
+      estimated_complexity: 1-5   // Effort estimate
+    },
+    // ... more subtasks
+  ]
+}
+\`\`\`
+
+Now decompose the task:`;
+var swarm_plan_prompt = tool({
+  description: "Generate strategy-specific decomposition prompt. Auto-selects strategy or uses provided one. Queries CASS for similar tasks.",
+  args: {
+    task: tool.schema.string().min(1).describe("Task description to decompose"),
+    strategy: tool.schema.enum(["file-based", "feature-based", "risk-based", "auto"]).optional().describe("Decomposition strategy (default: auto-detect)"),
+    max_subtasks: tool.schema.number().int().min(2).max(10).default(5).describe("Maximum number of subtasks (default: 5)"),
+    context: tool.schema.string().optional().describe("Additional context (codebase info, constraints, etc.)"),
+    query_cass: tool.schema.boolean().optional().describe("Query CASS for similar past tasks (default: true)"),
+    cass_limit: tool.schema.number().int().min(1).max(10).optional().describe("Max CASS results to include (default: 3)")
+  },
+  async execute(args) {
+    let selectedStrategy;
+    let strategyReasoning;
+    if (args.strategy && args.strategy !== "auto") {
+      selectedStrategy = args.strategy;
+      strategyReasoning = `User-specified strategy: ${selectedStrategy}`;
+    } else {
+      const selection = selectStrategy(args.task);
+      selectedStrategy = selection.strategy;
+      strategyReasoning = selection.reasoning;
+    }
+    let cassContext = "";
+    let cassResult = null;
+    if (args.query_cass !== false) {
+      cassResult = await queryCassHistory(args.task, args.cass_limit ?? 3);
+      if (cassResult && cassResult.results.length > 0) {
+        cassContext = formatCassHistoryForPrompt(cassResult);
+      }
+    }
+    const strategyGuidelines = formatStrategyGuidelines(selectedStrategy);
+    const contextSection = args.context ? `## Additional Context
+${args.context}` : `## Additional Context
+(none provided)`;
+    const prompt = STRATEGY_DECOMPOSITION_PROMPT.replace("{task}", args.task).replace("{strategy_guidelines}", strategyGuidelines).replace("{context_section}", contextSection).replace("{cass_history}", cassContext || "").replace("{max_subtasks}", (args.max_subtasks ?? 5).toString());
+    return JSON.stringify({
+      prompt,
+      strategy: {
+        selected: selectedStrategy,
+        reasoning: strategyReasoning,
+        guidelines: STRATEGIES[selectedStrategy].guidelines,
+        anti_patterns: STRATEGIES[selectedStrategy].antiPatterns
+      },
+      expected_schema: "BeadTree",
+      schema_hint: {
+        epic: { title: "string", description: "string?" },
+        subtasks: [
+          {
+            title: "string",
+            description: "string?",
+            files: "string[]",
+            dependencies: "number[]",
+            estimated_complexity: "1-5"
+          }
+        ]
+      },
+      validation_note: "Parse agent response as JSON and validate with swarm_validate_decomposition",
+      cass_history: cassResult ? {
+        queried: true,
+        results_found: cassResult.results.length,
+        included_in_context: cassResult.results.length > 0
+      } : { queried: false, reason: "disabled or unavailable" }
+    }, null, 2);
+  }
+});
 var swarm_decompose = tool({
   description: "Generate decomposition prompt for breaking task into parallelizable subtasks. Optionally queries CASS for similar past tasks.",
   args: {
@@ -24236,7 +24552,8 @@ var swarm_record_outcome = tool({
     retry_count: tool.schema.number().int().min(0).default(0).describe("Number of retry attempts"),
     success: tool.schema.boolean().describe("Whether the subtask succeeded"),
     files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files that were modified"),
-    criteria: tool.schema.array(tool.schema.string()).optional().describe("Criteria to generate feedback for (default: all default criteria)")
+    criteria: tool.schema.array(tool.schema.string()).optional().describe("Criteria to generate feedback for (default: all default criteria)"),
+    strategy: tool.schema.enum(["file-based", "feature-based", "risk-based"]).optional().describe("Decomposition strategy used for this task")
   },
   async execute(args) {
     const signals = {
@@ -24246,7 +24563,8 @@ var swarm_record_outcome = tool({
       retry_count: args.retry_count ?? 0,
       success: args.success,
       files_touched: args.files_touched ?? [],
-      timestamp: new Date().toISOString()
+      timestamp: new Date().toISOString(),
+      strategy: args.strategy
     };
     const validated = OutcomeSignalsSchema.parse(signals);
     const scored = scoreImplicitFeedback(validated, DEFAULT_LEARNING_CONFIG);
@@ -24256,7 +24574,13 @@ var swarm_record_outcome = tool({
       "patterns",
       "readable"
     ];
-    const feedbackEvents = criteriaToScore.map((criterion) => outcomeToFeedback(scored, criterion));
+    const feedbackEvents = criteriaToScore.map((criterion) => {
+      const event = outcomeToFeedback(scored, criterion);
+      if (args.strategy) {
+        event.context = `${event.context || ""} [strategy: ${args.strategy}]`.trim();
+      }
+      return event;
+    });
     return JSON.stringify({
       success: true,
       outcome: {
@@ -24273,7 +24597,8 @@ var swarm_record_outcome = tool({
         duration_seconds: Math.round(args.duration_ms / 1000),
         error_count: args.error_count ?? 0,
         retry_count: args.retry_count ?? 0,
-        success: args.success
+        success: args.success,
+        strategy: args.strategy
       },
       note: "Feedback events should be stored for criterion weight calculation. Use learning.ts functions to apply weights."
     }, null, 2);
@@ -24493,6 +24818,8 @@ var swarm_init = tool({
 });
 var swarmTools = {
   swarm_init,
+  swarm_select_strategy,
+  swarm_plan_prompt,
   swarm_decompose,
   swarm_validate_decomposition,
   swarm_status,

package/examples/agents/swarm-planner.md

@@ -0,0 +1,138 @@
+---
+name: swarm-planner
+description: Strategic task decomposition for swarm coordination
+model: claude-sonnet-4-5
+---
+
+You are a swarm planner. Your job is to decompose complex tasks into optimal parallel subtasks.
+
+## Your Role
+
+You analyze tasks and create decomposition plans that:
+
+- Maximize parallelization (agents work independently)
+- Minimize conflicts (no file overlap between subtasks)
+- Follow the best strategy for the task type
+
+## Workflow
+
+1. **Analyze** - Call `swarm_select_strategy` to understand the task
+2. **Plan** - Call `swarm_plan_prompt` to get strategy-specific guidance
+3. **Decompose** - Create a BeadTree following the guidelines
+4. **Validate** - Ensure no file conflicts or circular dependencies
+
+## Strategy Selection
+
+The plugin auto-selects strategies based on task keywords:
+
+| Strategy          | Best For                                     | Keywords                               |
+| ----------------- | -------------------------------------------- | -------------------------------------- |
+| **file-based**    | Refactoring, migrations, pattern changes     | refactor, migrate, rename, update all  |
+| **feature-based** | New features, adding functionality           | add, implement, build, create, feature |
+| **risk-based**    | Bug fixes, security issues, critical changes | fix, bug, security, critical, urgent   |
+
+You can override with explicit strategy if the auto-detection is wrong.
+
+## Output Format
+
+Return ONLY valid JSON matching the BeadTree schema:
+
+```json
+{
+  "epic": {
+    "title": "Epic title for beads tracker",
+    "description": "Brief description of the overall goal"
+  },
+  "subtasks": [
+    {
+      "title": "What this subtask accomplishes",
+      "description": "Detailed instructions for the agent",
+      "files": ["src/path/to/file.ts", "src/path/to/file.test.ts"],
+      "dependencies": [],
+      "estimated_complexity": 2
+    }
+  ]
+}
+```
+
+**CRITICAL**: Return ONLY the JSON. No markdown, no explanation, no code blocks.
+
+## Decomposition Rules
+
+1. **2-7 subtasks** - Too few = not parallel, too many = coordination overhead
+2. **No file overlap** - Each file appears in exactly one subtask
+3. **Include tests** - Put test files with the code they test
+4. **Order by dependency** - If B needs A's output, A comes first (lower index)
+5. **Estimate complexity** - 1 (trivial) to 5 (complex)
+
+## Anti-Patterns to Avoid
+
+- Don't split tightly coupled files across subtasks
+- Don't create subtasks that can't be tested independently
+- Don't forget shared types/utilities that multiple files depend on
+- Don't make one subtask do everything while others are trivial
+
+## Example Decomposition
+
+**Task**: "Add user authentication with OAuth"
+
+**Strategy**: feature-based (detected from "add" keyword)
+
+**Result**:
+
+```json
+{
+  "epic": {
+    "title": "Add user authentication with OAuth",
+    "description": "Implement OAuth-based authentication flow with session management"
+  },
+  "subtasks": [
+    {
+      "title": "Set up OAuth provider configuration",
+      "description": "Configure OAuth provider (Google/GitHub), add environment variables, create auth config",
+      "files": ["src/auth/config.ts", "src/auth/providers.ts", ".env.example"],
+      "dependencies": [],
+      "estimated_complexity": 2
+    },
+    {
+      "title": "Implement session management",
+      "description": "Create session store, JWT handling, cookie management",
+      "files": [
+        "src/auth/session.ts",
+        "src/auth/jwt.ts",
+        "src/middleware/auth.ts"
+      ],
+      "dependencies": [0],
+      "estimated_complexity": 3
+    },
+    {
+      "title": "Add protected route wrapper",
+      "description": "Create HOC/middleware for protecting routes, redirect logic",
+      "files": ["src/components/ProtectedRoute.tsx", "src/hooks/useAuth.ts"],
+      "dependencies": [1],
+      "estimated_complexity": 2
+    },
+    {
+      "title": "Create login/logout UI",
+      "description": "Login page, logout button, auth state display",
+      "files": ["src/app/login/page.tsx", "src/components/AuthButton.tsx"],
+      "dependencies": [0],
+      "estimated_complexity": 2
+    }
+  ]
+}
+```
+
+## Usage
+
+The coordinator invokes you like this:
+
+```
+@swarm-planner "Add user authentication with OAuth"
+```
+
+You respond with the BeadTree JSON. The coordinator then:
+
+1. Validates with `swarm_validate_decomposition`
+2. Creates beads with `beads_create_epic`
+3. Spawns worker agents for each subtask