opencode-swarm-plugin 0.5.0 → 0.6.1

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.1",
   "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,
 };

package/src/swarm.integration.test.ts

@@ -16,6 +16,8 @@ import {
   swarm_complete,
   swarm_subtask_prompt,
   swarm_evaluation_prompt,
+  swarm_select_strategy,
+  swarm_plan_prompt,
   formatSubtaskPromptV2,
   SUBTASK_PROMPT_V2,
 } from "./swarm";
@@ -119,6 +121,288 @@ describe("swarm_decompose", () => {
   });
 });
 
+// ============================================================================
+// Strategy Selection Tests
+// ============================================================================
+
+describe("swarm_select_strategy", () => {
+  it("selects feature-based for 'add' tasks", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Add user authentication with OAuth",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.strategy).toBe("feature-based");
+    expect(parsed.confidence).toBeGreaterThan(0.5);
+    expect(parsed.reasoning).toContain("add");
+    expect(parsed.guidelines).toBeInstanceOf(Array);
+    expect(parsed.anti_patterns).toBeInstanceOf(Array);
+  });
+
+  it("selects file-based for 'refactor' tasks", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Refactor all components to use new API",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.strategy).toBe("file-based");
+    expect(parsed.confidence).toBeGreaterThanOrEqual(0.5);
+    expect(parsed.reasoning).toContain("refactor");
+  });
+
+  it("selects risk-based for 'fix security' tasks", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Fix security vulnerability in authentication",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.strategy).toBe("risk-based");
+    expect(parsed.confidence).toBeGreaterThan(0.5);
+    // Should match either 'fix' or 'security'
+    expect(
+      parsed.reasoning.includes("fix") || parsed.reasoning.includes("security"),
+    ).toBe(true);
+  });
+
+  it("defaults to feature-based when no keywords match", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Something completely unrelated without keywords",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.strategy).toBe("feature-based");
+    // Confidence should be lower without keyword matches
+    expect(parsed.confidence).toBeLessThanOrEqual(0.6);
+    expect(parsed.reasoning).toContain("Defaulting to feature-based");
+  });
+
+  it("includes confidence score and reasoning", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Implement new dashboard feature",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed).toHaveProperty("strategy");
+    expect(parsed).toHaveProperty("confidence");
+    expect(parsed).toHaveProperty("reasoning");
+    expect(parsed).toHaveProperty("description");
+    expect(typeof parsed.confidence).toBe("number");
+    expect(parsed.confidence).toBeGreaterThanOrEqual(0);
+    expect(parsed.confidence).toBeLessThanOrEqual(1);
+    expect(typeof parsed.reasoning).toBe("string");
+    expect(parsed.reasoning.length).toBeGreaterThan(0);
+  });
+
+  it("includes alternative strategies with scores", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Build new payment processing module",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed).toHaveProperty("alternatives");
+    expect(parsed.alternatives).toBeInstanceOf(Array);
+    expect(parsed.alternatives.length).toBe(2); // 3 strategies - 1 selected = 2 alternatives
+
+    for (const alt of parsed.alternatives) {
+      expect(alt).toHaveProperty("strategy");
+      expect(alt).toHaveProperty("description");
+      expect(alt).toHaveProperty("score");
+      expect(["file-based", "feature-based", "risk-based"]).toContain(
+        alt.strategy,
+      );
+      expect(typeof alt.score).toBe("number");
+    }
+  });
+
+  it("includes codebase context in reasoning when provided", async () => {
+    const result = await swarm_select_strategy.execute(
+      {
+        task: "Add new API endpoint",
+        codebase_context: "Using Express.js with TypeScript and PostgreSQL",
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.reasoning).toContain("Express.js");
+  });
+});
+
+// ============================================================================
+// Planning Prompt Tests
+// ============================================================================
+
+describe("swarm_plan_prompt", () => {
+  it("auto-selects strategy when not specified", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Add user settings page",
+        max_subtasks: 3,
+        query_cass: false, // Disable CASS to isolate test
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed).toHaveProperty("prompt");
+    expect(parsed).toHaveProperty("strategy");
+    expect(parsed.strategy).toHaveProperty("selected");
+    expect(parsed.strategy).toHaveProperty("reasoning");
+    expect(parsed.strategy.selected).toBe("feature-based"); // 'add' keyword
+  });
+
+  it("uses explicit strategy when provided", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Do something",
+        strategy: "risk-based",
+        max_subtasks: 3,
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.strategy.selected).toBe("risk-based");
+    expect(parsed.strategy.reasoning).toContain("User-specified strategy");
+  });
+
+  it("includes strategy guidelines in prompt", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Refactor the codebase",
+        max_subtasks: 4,
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    // Prompt should contain strategy-specific guidelines
+    expect(parsed.prompt).toContain("## Strategy:");
+    expect(parsed.prompt).toContain("### Guidelines");
+    expect(parsed.prompt).toContain("### Anti-Patterns");
+    expect(parsed.prompt).toContain("### Examples");
+  });
+
+  it("includes anti-patterns in output", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Build new feature",
+        max_subtasks: 3,
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.strategy).toHaveProperty("anti_patterns");
+    expect(parsed.strategy.anti_patterns).toBeInstanceOf(Array);
+    expect(parsed.strategy.anti_patterns.length).toBeGreaterThan(0);
+  });
+
+  it("returns expected_schema and validation_note", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Some task",
+        max_subtasks: 5,
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed).toHaveProperty("expected_schema", "BeadTree");
+    expect(parsed).toHaveProperty("validation_note");
+    expect(parsed.validation_note).toContain("swarm_validate_decomposition");
+    expect(parsed).toHaveProperty("schema_hint");
+    expect(parsed.schema_hint).toHaveProperty("epic");
+    expect(parsed.schema_hint).toHaveProperty("subtasks");
+  });
+
+  it("reports CASS status in output (queried flag)", async () => {
+    // Test with CASS disabled
+    const resultDisabled = await swarm_plan_prompt.execute(
+      {
+        task: "Add feature",
+        max_subtasks: 3,
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsedDisabled = JSON.parse(resultDisabled);
+
+    expect(parsedDisabled).toHaveProperty("cass_history");
+    expect(parsedDisabled.cass_history.queried).toBe(false);
+
+    // Test with CASS enabled (may or may not be available)
+    const resultEnabled = await swarm_plan_prompt.execute(
+      {
+        task: "Add feature",
+        max_subtasks: 3,
+        query_cass: true,
+      },
+      mockContext,
+    );
+    const parsedEnabled = JSON.parse(resultEnabled);
+
+    expect(parsedEnabled).toHaveProperty("cass_history");
+    expect(parsedEnabled.cass_history).toHaveProperty("queried");
+    // If CASS is unavailable, queried will be false with reason
+    if (!parsedEnabled.cass_history.queried) {
+      expect(parsedEnabled.cass_history).toHaveProperty("reason");
+    }
+  });
+
+  it("includes context in prompt when provided", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Add user profile",
+        max_subtasks: 3,
+        context: "We use Next.js App Router with server components",
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.prompt).toContain("Next.js App Router");
+    expect(parsed.prompt).toContain("server components");
+  });
+
+  it("includes max_subtasks in prompt", async () => {
+    const result = await swarm_plan_prompt.execute(
+      {
+        task: "Build something",
+        max_subtasks: 7,
+        query_cass: false,
+      },
+      mockContext,
+    );
+    const parsed = JSON.parse(result);
+
+    expect(parsed.prompt).toContain("2-7 independent subtasks");
+  });
+});
+
 describe("swarm_validate_decomposition", () => {
   it("validates correct BeadTree", async () => {
     const validBeadTree = JSON.stringify({