opencode-swarm-plugin 0.5.0 → 0.6.1

package/README.md

@@ -131,6 +131,8 @@ Client-side, per-agent rate limits prevent abuse and ensure fair resource usage
 | Tool                           | Description                                                              |
 | ------------------------------ | ------------------------------------------------------------------------ |
 | `swarm_init`                   | Check tool availability, report degraded features                        |
+| `swarm_select_strategy`        | Analyze task and recommend decomposition strategy                        |
+| `swarm_plan_prompt`            | Generate strategy-specific planning prompt with CASS integration         |
 | `swarm_decompose`              | Generate decomposition prompt, optionally queries CASS for similar tasks |
 | `swarm_validate_decomposition` | Validate decomposition response, detect instruction conflicts            |
 | `swarm_status`                 | Get swarm status by epic ID                                              |
@@ -152,6 +154,80 @@ Client-side, per-agent rate limits prevent abuse and ensure fair resource usage
 | `structured_parse_decomposition` | Parse and validate task decomposition                    |
 | `structured_parse_bead_tree`     | Parse and validate bead tree for epic creation           |
 
+## Decomposition Strategies
+
+The plugin supports three decomposition strategies, auto-selected based on task keywords:
+
+### File-Based Strategy
+
+Best for: Refactoring, migrations, pattern changes across codebase
+
+**Keywords**: refactor, migrate, rename, update all, convert, upgrade
+
+**Guidelines**:
+
+- Group files by directory or type
+- Handle shared types/utilities first
+- Minimize cross-directory dependencies
+
+### Feature-Based Strategy
+
+Best for: New features, adding functionality
+
+**Keywords**: add, implement, build, create, feature, new
+
+**Guidelines**:
+
+- Each subtask is a complete vertical slice
+- Start with data layer, then logic, then UI
+- Keep related components together
+
+### Risk-Based Strategy
+
+Best for: Bug fixes, security issues, critical changes
+
+**Keywords**: fix, bug, security, critical, urgent, hotfix
+
+**Guidelines**:
+
+- Write tests FIRST
+- Isolate risky changes
+- Audit similar code for same issue
+
+### Strategy Selection
+
+Use `swarm_select_strategy` to see the recommended strategy:
+
+```typescript
+swarm_select_strategy({ task: "Add user authentication" });
+// Returns: { strategy: "feature-based", confidence: 0.85, reasoning: "..." }
+```
+
+Or let `swarm_plan_prompt` auto-select:
+
+```typescript
+swarm_plan_prompt({ task: "Refactor all components to use hooks" });
+// Auto-selects file-based strategy
+```
+
+## Example Planner Agent
+
+The plugin includes an example planner agent at `examples/agents/swarm-planner.md`.
+
+Copy to your OpenCode agents directory:
+
+```bash
+cp examples/agents/swarm-planner.md ~/.config/opencode/agents/
+```
+
+Then invoke with:
+
+```
+@swarm-planner "Add user authentication with OAuth"
+```
+
+The planner uses `swarm_select_strategy` and `swarm_plan_prompt` internally to create optimal decompositions.
+
 ### Schemas (for structured outputs)
 
 The plugin exports Zod schemas for validated agent responses:

package/dist/index.js

@@ -23386,6 +23386,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),
@@ -23393,7 +23398,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,
@@ -23553,6 +23559,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
@@ -23926,6 +24093,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: {
@@ -24285,7 +24601,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 = {
@@ -24295,7 +24612,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);
@@ -24305,7 +24623,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: {
@@ -24322,7 +24646,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);
@@ -24542,6 +24867,8 @@ var swarm_init = tool({
 });
 var swarmTools = {
   swarm_init,
+  swarm_select_strategy,
+  swarm_plan_prompt,
   swarm_decompose,
   swarm_validate_decomposition,
   swarm_status,
@@ -25027,6 +25354,7 @@ export {
   swarmTools,
   structuredTools,
   setStorage,
+  selectStrategy,
   resetToolCache,
   resetStorage,
   requireTool,
@@ -25040,6 +25368,7 @@ export {
   formatToolAvailability,
   formatSubtaskPromptV2,
   formatSubtaskPrompt,
+  formatStrategyGuidelines,
   formatEvaluationPrompt,
   extractJsonFromText,
   src_default as default,
@@ -25072,6 +25401,7 @@ export {
   SpawnedAgentSchema,
   SemanticMemoryStorage,
   SUBTASK_PROMPT_V2,
+  STRATEGIES,
   InMemoryStorage,
   FileReservationConflictError,
   EvaluationSchema,