opencode-swarm-plugin 0.4.0 → 0.6.0

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                                              |
@@ -138,7 +140,7 @@ Client-side, per-agent rate limits prevent abuse and ensure fair resource usage
 | `swarm_complete`               | Mark subtask complete with UBS bug scan, release reservations            |
 | `swarm_record_outcome`         | Record outcome for implicit feedback (duration, errors, retries)         |
 | `swarm_subtask_prompt`         | Generate prompt for spawned subtask agent (V1 - includes coordination)   |
-| `swarm_spawn_subtask`          | Generate V2 prompt for coordinator use (simplified, no coordination)     |
+| `swarm_spawn_subtask`          | Generate V2 prompt with Agent Mail/beads instructions for subagents      |
 | `swarm_complete_subtask`       | Handle subtask completion: close bead, create issue beads                |
 | `swarm_evaluation_prompt`      | Generate self-evaluation prompt                                          |
 
@@ -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:
@@ -429,24 +505,43 @@ The plugin enforces these limits regardless of input:
 - Thread summaries use LLM mode for concise output
 - File reservations auto-track for cleanup
 
-## Integration with /swarm Command
+## Custom Commands
+
+This plugin provides tools that work with OpenCode's [custom commands](https://opencode.ai/docs/commands). Create a `/swarm` command to orchestrate multi-agent work.
+
+### Setup /swarm Command
 
-This plugin provides the primitives used by OpenCode's `/swarm` command:
+Copy the example command to your OpenCode config:
+
+```bash
+cp examples/commands/swarm.md ~/.config/opencode/command/
+```
+
+### Usage
 
 ```
 /swarm "Add user authentication with OAuth providers"
 ```
 
-The `/swarm` command uses this plugin to:
+### How It Works
+
+1. **Decompose** - `swarm_decompose` breaks task into subtasks with file assignments
+2. **Create beads** - `beads_create_epic` creates epic + subtasks atomically
+3. **Spawn agents** - `swarm_spawn_subtask` generates prompts WITH Agent Mail/beads instructions
+4. **Parallel work** - Subagents use Agent Mail to communicate, beads to track progress
+5. **Coordination** - Agents report progress, ask questions, announce blockers via Agent Mail
+6. **Completion** - Agents use `swarm_complete` when done
+7. **Cleanup** - `beads_sync` pushes to git
+
+### Subagent Capabilities
+
+Spawned subagents have **full access** to all plugin tools:
+
+- **Agent Mail** - `agentmail_send`, `agentmail_inbox`, `agentmail_reserve`, etc.
+- **Beads** - `beads_update`, `beads_create`, `swarm_complete`
+- All standard OpenCode tools
 
-1. **Decompose** - Break task into subtasks using `TaskDecompositionSchema`
-2. **Create beads** - Use `beads_create_epic` for atomic issue creation
-3. **Initialize agents** - Each agent calls `agentmail_init`
-4. **Reserve files** - Prevent conflicts with `agentmail_reserve`
-5. **Coordinate** - Agents communicate via `agentmail_send`
-6. **Track status** - Use `SwarmStatusSchema` for progress
-7. **Evaluate** - Validate work with `EvaluationSchema`
-8. **Cleanup** - Release reservations and sync beads
+The prompts tell agents to actively communicate and coordinate.
 
 ## Error Handling
 

package/dist/index.js

@@ -23701,61 +23701,57 @@ Before writing code:
 4. **Communicate your plan** via Agent Mail if non-trivial
 
 Begin work on your subtask now.`;
-var SUBTASK_PROMPT_V2 = `You are working on a subtask as part of a larger project.
+var SUBTASK_PROMPT_V2 = `You are a swarm agent working on: **{subtask_title}**
 
-## Your Task
-**Title**: {subtask_title}
+## Identity
+- **Bead ID**: {bead_id}
+- **Epic ID**: {epic_id}
 
+## Task
 {subtask_description}
 
-## Files to Modify
+## Files (exclusive reservation)
 {file_list}
 
-**IMPORTANT**: Only modify the files listed above. Do not create new files unless absolutely necessary for the task.
+Only modify these files. Need others? Message the coordinator.
 
 ## Context
 {shared_context}
 
-## Instructions
+## MANDATORY: Use These Tools
 
-1. **Read first** - Understand the current state of the files before making changes
-2. **Plan your approach** - Think through what changes are needed
-3. **Make the changes** - Implement the required functionality
-4. **Verify** - Check that your changes work (run tests/typecheck if applicable)
+### Agent Mail - communicate with the swarm
+\`\`\`typescript
+// Report progress, ask questions, announce blockers
+agentmail_send({
+  to: ["coordinator"],
+  subject: "Progress update",
+  body: "What you did or need",
+  thread_id: "{epic_id}"
+})
+\`\`\`
 
-## When Complete
+### Beads - track your work
+- **Blocked?** \`beads_update({ id: "{bead_id}", status: "blocked" })\`
+- **Found bug?** \`beads_create({ title: "Bug description", type: "bug" })\`
+- **Done?** \`swarm_complete({ bead_id: "{bead_id}", summary: "What you did", files_touched: [...] })\`
 
-After finishing your work, provide a summary in this format:
+## Workflow
 
-\`\`\`json
-{
-  "success": true,
-  "summary": "Brief description of what you accomplished",
-  "files_modified": ["list", "of", "files", "you", "changed"],
-  "files_created": ["any", "new", "files"],
-  "issues_found": ["any problems or concerns discovered"],
-  "tests_passed": true,
-  "notes": "Any additional context for the coordinator"
-}
-\`\`\`
+1. **Read** the files first
+2. **Plan** your approach (message coordinator if complex)
+3. **Implement** the changes
+4. **Verify** (typecheck, tests)
+5. **Report** progress via Agent Mail
+6. **Complete** with swarm_complete when done
 
-If you encounter a blocker you cannot resolve, return:
+**Never work silently.** Communicate progress and blockers immediately.
 
-\`\`\`json
-{
-  "success": false,
-  "summary": "What you attempted",
-  "blocker": "Description of what's blocking you",
-  "files_modified": [],
-  "suggestions": ["possible", "solutions"]
-}
-\`\`\`
-
-Begin work now.`;
+Begin now.`;
 function formatSubtaskPromptV2(params) {
   const fileList = params.files.length > 0 ? params.files.map((f) => `- \`${f}\``).join(`
-`) : "(no specific files assigned - use your judgment)";
-  return SUBTASK_PROMPT_V2.replace("{subtask_title}", params.subtask_title).replace("{subtask_description}", params.subtask_description || "(see title)").replace("{file_list}", fileList).replace("{shared_context}", params.shared_context || "(none provided)");
+`) : "(no specific files - use judgment)";
+  return SUBTASK_PROMPT_V2.replace(/{bead_id}/g, params.bead_id).replace(/{epic_id}/g, params.epic_id).replace("{subtask_title}", params.subtask_title).replace("{subtask_description}", params.subtask_description || "(see title)").replace("{file_list}", fileList).replace("{shared_context}", params.shared_context || "(none)");
 }
 var EVALUATION_PROMPT = `Evaluate the work completed for this subtask.
 
@@ -24357,9 +24353,10 @@ var swarm_subtask_prompt = tool({
   }
 });
 var swarm_spawn_subtask = tool({
-  description: "Prepare a subtask for spawning with Task tool. Returns prompt and metadata for coordinator to use.",
+  description: "Prepare a subtask for spawning. Returns prompt with Agent Mail/beads instructions.",
   args: {
     bead_id: tool.schema.string().describe("Subtask bead ID"),
+    epic_id: tool.schema.string().describe("Parent epic bead ID"),
     subtask_title: tool.schema.string().describe("Subtask title"),
     subtask_description: tool.schema.string().optional().describe("Detailed subtask instructions"),
     files: tool.schema.array(tool.schema.string()).describe("Files assigned to this subtask"),
@@ -24367,6 +24364,8 @@ var swarm_spawn_subtask = tool({
   },
   async execute(args) {
     const prompt = formatSubtaskPromptV2({
+      bead_id: args.bead_id,
+      epic_id: args.epic_id,
       subtask_title: args.subtask_title,
       subtask_description: args.subtask_description || "",
       files: args.files,
@@ -24375,6 +24374,7 @@ var swarm_spawn_subtask = tool({
     return JSON.stringify({
       prompt,
       bead_id: args.bead_id,
+      epic_id: args.epic_id,
       files: args.files
     }, null, 2);
   }

package/dist/plugin.js

@@ -23660,61 +23660,57 @@ Before writing code:
 4. **Communicate your plan** via Agent Mail if non-trivial
 
 Begin work on your subtask now.`;
-var SUBTASK_PROMPT_V2 = `You are working on a subtask as part of a larger project.
+var SUBTASK_PROMPT_V2 = `You are a swarm agent working on: **{subtask_title}**
 
-## Your Task
-**Title**: {subtask_title}
+## Identity
+- **Bead ID**: {bead_id}
+- **Epic ID**: {epic_id}
 
+## Task
 {subtask_description}
 
-## Files to Modify
+## Files (exclusive reservation)
 {file_list}
 
-**IMPORTANT**: Only modify the files listed above. Do not create new files unless absolutely necessary for the task.
+Only modify these files. Need others? Message the coordinator.
 
 ## Context
 {shared_context}
 
-## Instructions
+## MANDATORY: Use These Tools
 
-1. **Read first** - Understand the current state of the files before making changes
-2. **Plan your approach** - Think through what changes are needed
-3. **Make the changes** - Implement the required functionality
-4. **Verify** - Check that your changes work (run tests/typecheck if applicable)
+### Agent Mail - communicate with the swarm
+\`\`\`typescript
+// Report progress, ask questions, announce blockers
+agentmail_send({
+  to: ["coordinator"],
+  subject: "Progress update",
+  body: "What you did or need",
+  thread_id: "{epic_id}"
+})
+\`\`\`
 
-## When Complete
+### Beads - track your work
+- **Blocked?** \`beads_update({ id: "{bead_id}", status: "blocked" })\`
+- **Found bug?** \`beads_create({ title: "Bug description", type: "bug" })\`
+- **Done?** \`swarm_complete({ bead_id: "{bead_id}", summary: "What you did", files_touched: [...] })\`
 
-After finishing your work, provide a summary in this format:
+## Workflow
 
-\`\`\`json
-{
-  "success": true,
-  "summary": "Brief description of what you accomplished",
-  "files_modified": ["list", "of", "files", "you", "changed"],
-  "files_created": ["any", "new", "files"],
-  "issues_found": ["any problems or concerns discovered"],
-  "tests_passed": true,
-  "notes": "Any additional context for the coordinator"
-}
-\`\`\`
+1. **Read** the files first
+2. **Plan** your approach (message coordinator if complex)
+3. **Implement** the changes
+4. **Verify** (typecheck, tests)
+5. **Report** progress via Agent Mail
+6. **Complete** with swarm_complete when done
 
-If you encounter a blocker you cannot resolve, return:
+**Never work silently.** Communicate progress and blockers immediately.
 
-\`\`\`json
-{
-  "success": false,
-  "summary": "What you attempted",
-  "blocker": "Description of what's blocking you",
-  "files_modified": [],
-  "suggestions": ["possible", "solutions"]
-}
-\`\`\`
-
-Begin work now.`;
+Begin now.`;
 function formatSubtaskPromptV2(params) {
   const fileList = params.files.length > 0 ? params.files.map((f) => `- \`${f}\``).join(`
-`) : "(no specific files assigned - use your judgment)";
-  return SUBTASK_PROMPT_V2.replace("{subtask_title}", params.subtask_title).replace("{subtask_description}", params.subtask_description || "(see title)").replace("{file_list}", fileList).replace("{shared_context}", params.shared_context || "(none provided)");
+`) : "(no specific files - use judgment)";
+  return SUBTASK_PROMPT_V2.replace(/{bead_id}/g, params.bead_id).replace(/{epic_id}/g, params.epic_id).replace("{subtask_title}", params.subtask_title).replace("{subtask_description}", params.subtask_description || "(see title)").replace("{file_list}", fileList).replace("{shared_context}", params.shared_context || "(none)");
 }
 var EVALUATION_PROMPT = `Evaluate the work completed for this subtask.
 
@@ -24308,9 +24304,10 @@ var swarm_subtask_prompt = tool({
   }
 });
 var swarm_spawn_subtask = tool({
-  description: "Prepare a subtask for spawning with Task tool. Returns prompt and metadata for coordinator to use.",
+  description: "Prepare a subtask for spawning. Returns prompt with Agent Mail/beads instructions.",
   args: {
     bead_id: tool.schema.string().describe("Subtask bead ID"),
+    epic_id: tool.schema.string().describe("Parent epic bead ID"),
     subtask_title: tool.schema.string().describe("Subtask title"),
     subtask_description: tool.schema.string().optional().describe("Detailed subtask instructions"),
     files: tool.schema.array(tool.schema.string()).describe("Files assigned to this subtask"),
@@ -24318,6 +24315,8 @@ var swarm_spawn_subtask = tool({
   },
   async execute(args) {
     const prompt = formatSubtaskPromptV2({
+      bead_id: args.bead_id,
+      epic_id: args.epic_id,
       subtask_title: args.subtask_title,
       subtask_description: args.subtask_description || "",
       files: args.files,
@@ -24326,6 +24325,7 @@ var swarm_spawn_subtask = tool({
     return JSON.stringify({
       prompt,
       bead_id: args.bead_id,
+      epic_id: args.epic_id,
       files: args.files
     }, null, 2);
   }

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