opencode-swarm-plugin 0.6.0 → 0.6.3

package/README.md

@@ -20,49 +20,151 @@ This plugin provides intelligent, self-improving tools for multi-agent workflows
 - **Graceful degradation** - Works with whatever tools are available, degrades features when tools missing
 - **Swarm discipline** - Enforces beads tracking, aggressive planning, and agent communication
 
-## Installation
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+# OpenCode (plugin host)
+brew install sst/tap/opencode
+
+# Beads CLI (issue tracking)
+npm install -g @joelhooks/beads
+```
+
+### 2. Install Plugin
 
 ```bash
 npm install opencode-swarm-plugin
-# or
-bun add opencode-swarm-plugin
-# or
-pnpm add opencode-swarm-plugin
 ```
 
-Copy the plugin to your OpenCode plugins directory:
+### 3. Create Plugin Wrapper
+
+Create a file at `~/.config/opencode/plugins/swarm.ts`:
+
+```ts
+import { SwarmPlugin } from "opencode-swarm-plugin";
+export default SwarmPlugin;
+```
+
+That's it! OpenCode will load the plugin automatically.
+
+### 4. Copy Examples (Recommended)
+
+```bash
+# Create directories
+mkdir -p ~/.config/opencode/commands ~/.config/opencode/agents
+
+# Copy /swarm command
+cp node_modules/opencode-swarm-plugin/examples/commands/swarm.md ~/.config/opencode/commands/
+
+# Copy @swarm-planner agent
+cp node_modules/opencode-swarm-plugin/examples/agents/swarm-planner.md ~/.config/opencode/agents/
+```
+
+### 5. Initialize Beads in Your Project
 
 ```bash
-cp node_modules/opencode-swarm-plugin/dist/plugin.js ~/.config/opencode/plugin/swarm.js
+cd your-project
+bd init
 ```
 
-Plugins are automatically loaded from `~/.config/opencode/plugin/` - no config file changes needed.
+### Alternative: Direct Copy (No Wrapper)
 
-> **Note:** The package has two entry points:
->
-> - `dist/index.js` - Full library exports (schemas, errors, utilities, learning modules)
-> - `dist/plugin.js` - Plugin entry point that only exports the `plugin` function for OpenCode
+If you prefer not to use the wrapper pattern:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp node_modules/opencode-swarm-plugin/dist/plugin.js ~/.config/opencode/plugins/swarm.js
+```
+
+## Dependencies
+
+### Required
+
+| Dependency                                      | Purpose                   | Install                           |
+| ----------------------------------------------- | ------------------------- | --------------------------------- |
+| [OpenCode](https://opencode.ai)                 | Plugin host               | `brew install sst/tap/opencode`   |
+| [Beads CLI](https://github.com/joelhooks/beads) | Git-backed issue tracking | `npm install -g @joelhooks/beads` |
+
+### Optional (Graceful Degradation)
 
-## Prerequisites
+The plugin works without these, but with reduced functionality:
 
-| Requirement      | Purpose                                     |
-| ---------------- | ------------------------------------------- |
-| OpenCode 1.0+    | Plugin host                                 |
-| Agent Mail MCP   | Multi-agent coordination (`localhost:8765`) |
-| Beads CLI (`bd`) | Git-backed issue tracking                   |
+| Dependency                                            | Purpose                  | Without It                               |
+| ----------------------------------------------------- | ------------------------ | ---------------------------------------- |
+| [Agent Mail](https://github.com/joelhooks/agent-mail) | Multi-agent coordination | No file reservations, no agent messaging |
+| [Redis](https://redis.io)                             | Rate limiting            | Falls back to SQLite                     |
+| [CASS](https://github.com/Dicklesworthstone/cass)     | Historical context       | No "similar past tasks" in decomposition |
+| [UBS](https://github.com/joelhooks/ubs)               | Bug scanning             | No pre-completion validation             |
 
-### Verify Agent Mail is running
+### Verify Installation
 
 ```bash
+# Check OpenCode
+opencode --version
+
+# Check Beads
+bd --version
+
+# Check Agent Mail (if using multi-agent)
 curl http://127.0.0.1:8765/health/liveness
+
+# Check Redis (optional)
+redis-cli ping
 ```
 
-### Verify beads is installed
+## Installation Details
+
+### From npm
 
 ```bash
-bd --version
+npm install opencode-swarm-plugin
+# or
+bun add opencode-swarm-plugin
+# or
+pnpm add opencode-swarm-plugin
+```
+
+### Plugin Setup (Wrapper Pattern)
+
+Create `~/.config/opencode/plugins/swarm.ts`:
+
+```ts
+import { SwarmPlugin } from "opencode-swarm-plugin";
+export default SwarmPlugin;
+```
+
+OpenCode runs on Bun and loads TypeScript directly - no build step needed.
+
+### Plugin Setup (Direct Copy)
+
+Alternatively, copy the pre-built bundle:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+cp node_modules/opencode-swarm-plugin/dist/plugin.js ~/.config/opencode/plugins/swarm.js
+```
+
+### Example Files
+
+Copy the `/swarm` command and `@swarm-planner` agent:
+
+```bash
+# Command
+mkdir -p ~/.config/opencode/commands
+cp node_modules/opencode-swarm-plugin/examples/commands/swarm.md ~/.config/opencode/commands/
+
+# Agent
+mkdir -p ~/.config/opencode/agents
+cp node_modules/opencode-swarm-plugin/examples/agents/swarm-planner.md ~/.config/opencode/agents/
 ```
 
+> **Note:** The package has two entry points:
+>
+> - `dist/index.js` - Full library exports (schemas, errors, utilities, learning modules)
+> - `dist/plugin.js` - Plugin entry point that only exports the `plugin` function for OpenCode
+
 ## Tools Reference
 
 ### Beads Tools

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,

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/package.json

@@ -1,10 +1,13 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "opencode-swarm-setup": "./scripts/setup.ts"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",

package/scripts/setup.ts

@@ -0,0 +1,371 @@
+#!/usr/bin/env bun
+/**
+ * OpenCode Swarm Plugin - Setup Script
+ *
+ * Checks for required dependencies and installs them if missing.
+ * Mac-specific (uses Homebrew).
+ *
+ * Usage:
+ *   bunx opencode-swarm-plugin/scripts/setup.ts
+ *   # or after cloning:
+ *   bun scripts/setup.ts
+ */
+
+import { $ } from "bun";
+import { existsSync, mkdirSync, copyFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// ANSI colors
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
+const blue = (s: string) => `\x1b[34m${s}\x1b[0m`;
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+const CHECK = green("✓");
+const CROSS = red("✗");
+const WARN = yellow("⚠");
+const INFO = blue("→");
+
+interface Dependency {
+  name: string;
+  check: () => Promise<boolean>;
+  install: () => Promise<void>;
+  optional?: boolean;
+  purpose: string;
+}
+
+/**
+ * Check if a command exists
+ */
+async function commandExists(cmd: string): Promise<boolean> {
+  try {
+    const result = await $`which ${cmd}`.quiet().nothrow();
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a URL is reachable
+ */
+async function urlReachable(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { method: "HEAD" });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run a shell command with output
+ */
+async function run(cmd: string, args: string[] = []): Promise<boolean> {
+  try {
+    const proc = Bun.spawn([cmd, ...args], {
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    const exitCode = await proc.exited;
+    return exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+const dependencies: Dependency[] = [
+  {
+    name: "Homebrew",
+    purpose: "Package manager for installing other dependencies",
+    check: async () => commandExists("brew"),
+    install: async () => {
+      console.log(`${INFO} Installing Homebrew...`);
+      const script = await fetch(
+        "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh",
+      ).then((r) => r.text());
+      await $`/bin/bash -c ${script}`;
+    },
+  },
+  {
+    name: "OpenCode",
+    purpose: "AI coding assistant (plugin host)",
+    check: async () => commandExists("opencode"),
+    install: async () => {
+      console.log(`${INFO} Installing OpenCode...`);
+      await run("brew", ["install", "sst/tap/opencode"]);
+    },
+  },
+  {
+    name: "Beads CLI (bd)",
+    purpose: "Git-backed issue tracking",
+    check: async () => commandExists("bd"),
+    install: async () => {
+      console.log(`${INFO} Installing Beads...`);
+      // Try npm global install first
+      const npmResult = await $`npm install -g @joelhooks/beads`
+        .quiet()
+        .nothrow();
+      if (npmResult.exitCode !== 0) {
+        console.log(`${WARN} npm install failed, trying go install...`);
+        await run("go", [
+          "install",
+          "github.com/joelhooks/beads/cmd/bd@latest",
+        ]);
+      }
+    },
+  },
+  {
+    name: "Agent Mail MCP",
+    purpose: "Multi-agent coordination server",
+    check: async () => {
+      // Check if server is running
+      const running = await urlReachable(
+        "http://127.0.0.1:8765/health/liveness",
+      );
+      if (running) return true;
+      // Check if binary exists
+      return commandExists("agent-mail");
+    },
+    install: async () => {
+      console.log(`${INFO} Installing Agent Mail...`);
+      console.log(dim("  Agent Mail requires manual setup:"));
+      console.log(
+        dim("  1. Clone: git clone https://github.com/joelhooks/agent-mail"),
+      );
+      console.log(
+        dim("  2. Build: cd agent-mail && go build -o agent-mail ./cmd/server"),
+      );
+      console.log(dim("  3. Run: ./agent-mail serve"));
+      console.log();
+      console.log(
+        `${WARN} Skipping automatic install - see instructions above`,
+      );
+    },
+    optional: true,
+  },
+  {
+    name: "Redis",
+    purpose: "Rate limiting (optional, falls back to SQLite)",
+    check: async () => {
+      // Check if redis-server is running or installed
+      const running = await $`redis-cli ping`.quiet().nothrow();
+      if (running.exitCode === 0) return true;
+      return commandExists("redis-server");
+    },
+    install: async () => {
+      console.log(`${INFO} Installing Redis...`);
+      await run("brew", ["install", "redis"]);
+      console.log(dim("  Start with: brew services start redis"));
+    },
+    optional: true,
+  },
+  {
+    name: "CASS (cass-memory)",
+    purpose: "Cross-agent session search for historical context",
+    check: async () => commandExists("cass"),
+    install: async () => {
+      console.log(`${INFO} CASS installation...`);
+      console.log(
+        dim("  Install from: https://github.com/Dicklesworthstone/cass"),
+      );
+      console.log(`${WARN} Skipping automatic install - see link above`);
+    },
+    optional: true,
+  },
+  {
+    name: "UBS (bug scanner)",
+    purpose: "Pre-completion bug scanning",
+    check: async () => commandExists("ubs"),
+    install: async () => {
+      console.log(`${INFO} UBS installation...`);
+      console.log(dim("  UBS is bundled with OpenCode plugins"));
+      console.log(
+        `${WARN} Skipping - should be available if OpenCode is installed`,
+      );
+    },
+    optional: true,
+  },
+];
+
+/**
+ * Setup OpenCode directories and copy plugin
+ */
+async function setupOpenCodeDirs(): Promise<void> {
+  const configDir = join(homedir(), ".config", "opencode");
+  const pluginsDir = join(configDir, "plugins");
+  const commandsDir = join(configDir, "commands");
+  const agentsDir = join(configDir, "agents");
+
+  // Create directories
+  for (const dir of [pluginsDir, commandsDir, agentsDir]) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      console.log(`${CHECK} Created ${dir}`);
+    }
+  }
+
+  // Find plugin files (either in node_modules or local)
+  const possiblePaths = [
+    join(process.cwd(), "dist", "plugin.js"),
+    join(
+      process.cwd(),
+      "node_modules",
+      "opencode-swarm-plugin",
+      "dist",
+      "plugin.js",
+    ),
+  ];
+
+  let pluginSrc: string | null = null;
+  for (const p of possiblePaths) {
+    if (existsSync(p)) {
+      pluginSrc = p;
+      break;
+    }
+  }
+
+  if (pluginSrc) {
+    const pluginDest = join(pluginsDir, "swarm.js");
+    copyFileSync(pluginSrc, pluginDest);
+    console.log(`${CHECK} Copied plugin to ${pluginDest}`);
+  } else {
+    console.log(
+      `${WARN} Plugin not found - run 'pnpm build' first or install from npm`,
+    );
+  }
+
+  // Copy example files if they exist
+  const examplesDir = join(process.cwd(), "examples");
+  const nodeModulesExamples = join(
+    process.cwd(),
+    "node_modules",
+    "opencode-swarm-plugin",
+    "examples",
+  );
+
+  const examplesSrc = existsSync(examplesDir)
+    ? examplesDir
+    : nodeModulesExamples;
+
+  if (existsSync(examplesSrc)) {
+    const swarmCmd = join(examplesSrc, "commands", "swarm.md");
+    const plannerAgent = join(examplesSrc, "agents", "swarm-planner.md");
+
+    if (existsSync(swarmCmd)) {
+      copyFileSync(swarmCmd, join(commandsDir, "swarm.md"));
+      console.log(`${CHECK} Copied /swarm command`);
+    }
+
+    if (existsSync(plannerAgent)) {
+      copyFileSync(plannerAgent, join(agentsDir, "swarm-planner.md"));
+      console.log(`${CHECK} Copied @swarm-planner agent`);
+    }
+  }
+}
+
+/**
+ * Main setup function
+ */
+async function main() {
+  console.log();
+  console.log(
+    blue("═══════════════════════════════════════════════════════════"),
+  );
+  console.log(blue("  OpenCode Swarm Plugin - Setup"));
+  console.log(
+    blue("═══════════════════════════════════════════════════════════"),
+  );
+  console.log();
+
+  // Check platform
+  if (process.platform !== "darwin") {
+    console.log(
+      `${WARN} This script is optimized for macOS. Some installs may not work.`,
+    );
+    console.log();
+  }
+
+  // Check dependencies
+  console.log(blue("Checking dependencies...\n"));
+
+  const missing: Dependency[] = [];
+  const optionalMissing: Dependency[] = [];
+
+  for (const dep of dependencies) {
+    const installed = await dep.check();
+    const status = installed ? CHECK : dep.optional ? WARN : CROSS;
+    const suffix = dep.optional ? dim(" (optional)") : "";
+
+    console.log(`${status} ${dep.name}${suffix}`);
+    console.log(dim(`    ${dep.purpose}`));
+
+    if (!installed) {
+      if (dep.optional) {
+        optionalMissing.push(dep);
+      } else {
+        missing.push(dep);
+      }
+    }
+  }
+
+  console.log();
+
+  // Install missing required dependencies
+  if (missing.length > 0) {
+    console.log(blue("Installing missing required dependencies...\n"));
+
+    for (const dep of missing) {
+      try {
+        await dep.install();
+        const nowInstalled = await dep.check();
+        if (nowInstalled) {
+          console.log(`${CHECK} ${dep.name} installed successfully\n`);
+        } else {
+          console.log(`${CROSS} ${dep.name} installation may have failed\n`);
+        }
+      } catch (error) {
+        console.log(`${CROSS} Failed to install ${dep.name}: ${error}\n`);
+      }
+    }
+  }
+
+  // Offer to install optional dependencies
+  if (optionalMissing.length > 0) {
+    console.log(yellow("Optional dependencies not installed:"));
+    for (const dep of optionalMissing) {
+      console.log(`  - ${dep.name}: ${dep.purpose}`);
+    }
+    console.log();
+    console.log(
+      dim("The plugin will work without these, with degraded features."),
+    );
+    console.log();
+  }
+
+  // Setup OpenCode directories
+  console.log(blue("Setting up OpenCode directories...\n"));
+  await setupOpenCodeDirs();
+
+  console.log();
+  console.log(
+    blue("═══════════════════════════════════════════════════════════"),
+  );
+  console.log(blue("  Setup Complete!"));
+  console.log(
+    blue("═══════════════════════════════════════════════════════════"),
+  );
+  console.log();
+  console.log("Next steps:");
+  console.log(
+    `  1. ${dim("Start Agent Mail (if using multi-agent):")} agent-mail serve`,
+  );
+  console.log(`  2. ${dim("Initialize beads in your project:")} bd init`);
+  console.log(`  3. ${dim("Start OpenCode:")} opencode`);
+  console.log(`  4. ${dim("Try the swarm command:")} /swarm "your task here"`);
+  console.log();
+}
+
+main().catch(console.error);