opencode-swarm-plugin 0.5.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                                              |
@@ -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/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

package/examples/commands/swarm.md

@@ -2,49 +2,276 @@
 description: Decompose task into parallel subtasks and coordinate agents
 ---
 
-You are a swarm coordinator. Break down the following task into parallel subtasks.
+You are a swarm coordinator. Take a complex task, break it into beads, and unleash parallel agents.
 
-## Task
+## Usage
 
-$ARGUMENTS
+```
+/swarm <task description or bead-id>
+/swarm --to-main <task>  # Skip PR, push directly to main (use sparingly)
+/swarm --no-sync <task>  # Skip mid-task context sync (for simple independent tasks)
+```
 
-## Instructions
+**Default behavior: Feature branch + PR with context sync.** All swarm work goes to a feature branch, agents share context mid-task, and creates a PR for review.
 
-1. Use `swarm_decompose` to generate a decomposition prompt for the task
-2. Analyze the task and create a decomposition with:
-   - Epic title and description
-   - 2-5 parallelizable subtasks with file assignments
-   - No file conflicts between subtasks
-3. Create the epic using `beads_create_epic`
-4. For each subtask:
-   - Mark bead in_progress with `beads_start`
-   - Use `swarm_spawn_subtask` to generate a prompt (includes Agent Mail/beads instructions)
-   - Spawn a Task agent with that prompt
-5. Monitor progress via Agent Mail inbox
-6. After all subtasks complete:
-   - Close the epic with `beads_close`
-   - Sync to git with `beads_sync`
+## Step 1: Initialize Session
 
-## Subagent Capabilities
+Use the plugin's agent-mail tools to register:
 
-Subagents have FULL access to:
+```
+agentmail_init with project_path=$PWD, task_description="Swarm coordinator: <task>"
+```
 
-- **Agent Mail** - `agentmail_send`, `agentmail_inbox`, etc.
-- **Beads** - `beads_update`, `beads_create`, `swarm_complete`
-- All standard tools (Read, Write, Edit, Bash, etc.)
+This returns your agent name and session state. Remember it.
 
-The prompts generated by `swarm_spawn_subtask` tell agents to:
+## Step 2: Create Feature Branch
 
-- Report progress via Agent Mail
-- Update bead status if blocked
-- Create new beads for discovered issues
-- Use `swarm_complete` when done
+**CRITICAL: Never push directly to main.**
 
-## Coordination
+```bash
+# Create branch from bead ID or task name
+git checkout -b swarm/<bead-id>  # e.g., swarm/trt-buddy-d7d
+# Or for ad-hoc tasks:
+git checkout -b swarm/<short-description>  # e.g., swarm/contextual-checkins
 
-- Use the epic ID as the `thread_id` for all Agent Mail messages
-- Agents communicate with each other and with you (coordinator)
-- Check `agentmail_inbox` periodically for updates
-- Use `agentmail_summarize_thread` to get thread overview
+git push -u origin HEAD
+```
 
-Begin decomposition now.
+## Step 3: Understand the Task
+
+If given a bead-id:
+
+```
+beads_query with id=<bead-id>
+```
+
+If given a description, analyze it to understand scope.
+
+## Step 4: Select Strategy & Decompose
+
+### Option A: Use the Planner Agent (Recommended)
+
+Spawn the `@swarm-planner` agent to handle decomposition:
+
+```
+Task(
+  subagent_type="general",
+  description="Plan swarm decomposition",
+  prompt="You are @swarm-planner. Decompose this task: <task description>. Use swarm_select_strategy and swarm_plan_prompt to guide your decomposition. Return ONLY valid BeadTree JSON."
+)
+```
+
+### Option B: Manual Decomposition
+
+1. **Select strategy**:
+
+```
+swarm_select_strategy with task="<task description>"
+```
+
+2. **Get planning prompt**:
+
+```
+swarm_plan_prompt with task="<task description>", strategy="<selected or auto>"
+```
+
+3. **Create decomposition** following the prompt guidelines
+
+4. **Validate**:
+
+```
+swarm_validate_decomposition with response="<your BeadTree JSON>"
+```
+
+### Create Beads
+
+Once you have a valid BeadTree:
+
+```
+beads_create_epic with epic_title="<parent task>", subtasks=[{title, description, files, priority}...]
+```
+
+**Decomposition rules:**
+
+- Each bead should be completable by one agent
+- Beads should be independent (parallelizable) where possible
+- If there are dependencies, order them in the subtasks array
+- Aim for 3-7 beads per swarm (too few = not parallel, too many = coordination overhead)
+
+## Step 5: Reserve Files
+
+For each subtask, reserve the files it will touch:
+
+```
+agentmail_reserve with paths=[<files>], reason="<bead-id>: <brief description>"
+```
+
+**Conflict prevention:**
+
+- No two agents should edit the same file
+- If overlap exists, merge beads or sequence them
+
+## Step 6: Spawn the Swarm
+
+**CRITICAL: Spawn ALL agents in a SINGLE message with multiple Task calls.**
+
+Use the prompt generator for each subtask:
+
+```
+swarm_spawn_subtask with bead_id="<bead-id>", epic_id="<epic-id>", subtask_title="<title>", subtask_description="<description>", files=[<files>], shared_context="Branch: swarm/<id>, sync_enabled: true"
+```
+
+Then spawn agents with the generated prompts:
+
+```
+Task(
+  subagent_type="general",
+  description="Swarm worker: <bead-title>",
+  prompt="<output from swarm_spawn_subtask>"
+)
+```
+
+Spawn ALL agents in parallel in a single response.
+
+## Step 7: Monitor Progress (unless --no-sync)
+
+Check swarm status:
+
+```
+swarm_status with epic_id="<parent-bead-id>"
+```
+
+Monitor inbox for progress updates:
+
+```
+agentmail_inbox
+```
+
+**When you receive progress updates:**
+
+1. **Review decisions made** - Are agents making compatible choices?
+2. **Check for pattern conflicts** - Different approaches to the same problem?
+3. **Identify shared concerns** - Common blockers or discoveries?
+
+**If you spot incompatibilities, broadcast shared context:**
+
+```
+agentmail_send with to=["*"], subject="Coordinator Update", body="<guidance>", thread_id="<epic-id>", importance="high"
+```
+
+## Step 8: Collect Results
+
+When agents complete, they send completion messages. Summarize the thread:
+
+```
+agentmail_summarize_thread with thread_id="<epic-id>"
+```
+
+## Step 9: Complete Swarm
+
+Use the swarm completion tool:
+
+```
+swarm_complete with project_key=$PWD, agent_name=<YOUR_NAME>, bead_id="<epic-id>", summary="<what was accomplished>", files_touched=[<all files>]
+```
+
+This:
+
+- Runs UBS bug scan on touched files
+- Releases file reservations
+- Closes the bead
+- Records outcome for learning
+
+Then sync beads:
+
+```
+beads_sync
+```
+
+## Step 10: Create PR
+
+```bash
+gh pr create --title "feat: <epic title>" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points from swarm results>
+
+## Beads Completed
+- <bead-id>: <summary>
+- <bead-id>: <summary>
+
+## Files Changed
+<aggregate list>
+
+## Testing
+- [ ] Type check passes
+- [ ] Tests pass (if applicable)
+EOF
+)"
+```
+
+Report summary:
+
+```markdown
+## Swarm Complete: <task>
+
+### PR: #<number>
+
+### Agents Spawned: N
+
+### Beads Closed: N
+
+### Work Completed
+
+- [bead-id]: [summary]
+
+### Files Changed
+
+- [aggregate list]
+```
+
+## Failure Handling
+
+If an agent fails:
+
+- Check its messages: `agentmail_inbox`
+- The bead remains in-progress
+- Manually investigate or re-spawn
+
+If file conflicts occur:
+
+- Agent Mail reservations should prevent this
+- If it happens, one agent needs to wait
+
+## Direct-to-Main Mode (--to-main)
+
+Only use when explicitly requested. Skips branch/PR:
+
+- Trivial fixes across many files
+- Automated migrations with high confidence
+- User explicitly says "push to main"
+
+## No-Sync Mode (--no-sync)
+
+Skip mid-task context sharing when tasks are truly independent:
+
+- Simple mechanical changes (find/replace, formatting, lint fixes)
+- Tasks with zero integration points
+- Completely separate feature areas with no shared types
+
+In this mode:
+
+- Agents skip the mid-task progress message
+- Coordinator skips Step 7 (monitoring)
+- Faster execution, less coordination overhead
+
+**Default is sync ON** - prefer sharing context. Use `--no-sync` deliberately.
+
+## Strategy Reference
+
+| Strategy          | Best For                    | Auto-Detected Keywords                         |
+| ----------------- | --------------------------- | ---------------------------------------------- |
+| **file-based**    | Refactoring, migrations     | refactor, migrate, rename, update all, convert |
+| **feature-based** | New features, functionality | add, implement, build, create, feature, new    |
+| **risk-based**    | Bug fixes, security         | fix, bug, security, critical, urgent, hotfix   |
+
+Use `swarm_select_strategy` to see which strategy is recommended and why.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -254,6 +254,12 @@ export {
  * - swarmTools - Swarm orchestration tools
  * - SwarmError, DecompositionError - Error classes
  * - formatSubtaskPrompt, formatEvaluationPrompt - Prompt helpers
+ * - selectStrategy, formatStrategyGuidelines - Strategy selection helpers
+ * - STRATEGIES - Strategy definitions
+ *
+ * Types:
+ * - DecompositionStrategy - Strategy type union
+ * - StrategyDefinition - Strategy definition interface
  *
  * NOTE: Prompt template strings (DECOMPOSITION_PROMPT, etc.) are NOT exported
  * to avoid confusing the plugin loader which tries to call all exports as functions
@@ -266,6 +272,12 @@ export {
   formatSubtaskPromptV2,
   formatEvaluationPrompt,
   SUBTASK_PROMPT_V2,
+  // Strategy exports
+  STRATEGIES,
+  selectStrategy,
+  formatStrategyGuidelines,
+  type DecompositionStrategy,
+  type StrategyDefinition,
 } from "./swarm";
 
 /**

package/src/learning.ts

@@ -64,6 +64,16 @@ export const CriterionWeightSchema = z.object({
 });
 export type CriterionWeight = z.infer<typeof CriterionWeightSchema>;
 
+/**
+ * Decomposition strategies for tracking which approach was used
+ */
+export const DecompositionStrategySchema = z.enum([
+  "file-based",
+  "feature-based",
+  "risk-based",
+]);
+export type DecompositionStrategy = z.infer<typeof DecompositionStrategySchema>;
+
 /**
  * Outcome signals from a completed subtask
  *
@@ -85,6 +95,8 @@ export const OutcomeSignalsSchema = z.object({
   files_touched: z.array(z.string()).default([]),
   /** Timestamp when outcome was recorded */
   timestamp: z.string(), // ISO-8601
+  /** Decomposition strategy used for this task */
+  strategy: DecompositionStrategySchema.optional(),
 });
 export type OutcomeSignals = z.infer<typeof OutcomeSignalsSchema>;
 
@@ -435,4 +447,5 @@ export const learningSchemas = {
   CriterionWeightSchema,
   OutcomeSignalsSchema,
   ScoredOutcomeSchema,
+  DecompositionStrategySchema,
 };