opencode-swarm-plugin 0.12.2 → 0.12.6

package/README.md

@@ -108,12 +108,11 @@ The `/swarm` command is defined in `~/.config/opencode/command/swarm.md`:
 description: Decompose task into parallel subtasks and coordinate agents
 ---
 
-You are a swarm coordinator. Take a complex task, break it into beads,
-and unleash parallel agents.
+You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
 
-## Usage
+## Task
 
-/swarm <task description or bead-id>
+$ARGUMENTS
 
 ## Workflow
 
@@ -136,125 +135,131 @@ and unleash parallel agents.
 Begin decomposition now.
 ```
 
-### @swarm-planner Agent
+> **Note**: The `$ARGUMENTS` placeholder captures everything you type after `/swarm`. This is how your task description gets passed to the agent.
+
+### Agents
+
+The setup wizard creates two agents with your chosen models:
 
-The `@swarm-planner` agent is defined in `~/.config/opencode/agent/swarm-planner.md`:
+**@swarm-planner** (`~/.config/opencode/agent/swarm-planner.md`) - Coordinator that decomposes tasks:
 
-````markdown
+```yaml
 ---
 name: swarm-planner
 description: Strategic task decomposition for swarm coordination
-model: claude-sonnet-4-5
+model: anthropic/claude-sonnet-4-5 # Your chosen coordinator model
 ---
+```
 
-You are a swarm planner. Decompose tasks into optimal parallel subtasks.
-
-## Workflow
+**@swarm-worker** (`~/.config/opencode/agent/swarm-worker.md`) - Fast executor for subtasks:
 
-1. Call `swarm_select_strategy` to analyze the task
-2. Call `swarm_plan_prompt` to get strategy-specific guidance
-3. Create a BeadTree following the guidelines
-4. Return ONLY valid JSON - no markdown, no explanation
-
-## Output Format
-
-```json
-{
-  "epic": { "title": "...", "description": "..." },
-  "subtasks": [
-    {
-      "title": "...",
-      "description": "...",
-      "files": ["src/..."],
-      "dependencies": [],
-      "estimated_complexity": 2
-    }
-  ]
-}
+```yaml
+---
+name: swarm-worker
+description: Executes subtasks in a swarm - fast, focused, cost-effective
+model: anthropic/claude-haiku-4-5 # Your chosen worker model
+---
 ```
-````
-
-## Rules
 
-- 2-7 subtasks (too few = not parallel, too many = overhead)
-- No file overlap between subtasks
-- Include tests with the code they test
-- Order by dependency (if B needs A, A comes first)
+### Decomposition Rules
 
-````
+- **2-7 subtasks** - Too few = not parallel, too many = coordination overhead
+- **No file overlap** - Each file appears in exactly one subtask
+- **Include tests** - Put test files with the code they test
+- **Order by dependency** - If B needs A's output, A comes first (lower index)
 
 Edit these files to customize behavior. Run `swarm setup` to regenerate defaults.
 
 ## Dependencies
 
-| Dependency | Purpose | Required |
-|------------|---------|----------|
-| [OpenCode](https://opencode.ai) | Plugin host | Yes |
-| [Beads](https://github.com/steveyegge/beads) | Git-backed issue tracking | Yes |
-| [Go](https://go.dev) | Required for Agent Mail | No |
-| [Agent Mail](https://github.com/joelhooks/agent-mail) | Multi-agent coordination, file reservations | No |
-| [CASS](https://github.com/Dicklesworthstone/cass) | Historical context from past sessions | No |
-| [UBS](https://github.com/joelhooks/ubs) | Pre-completion bug scanning | No |
-| [semantic-memory](https://github.com/joelhooks/semantic-memory) | Learning persistence | No |
-| [Redis](https://redis.io) | Rate limiting (SQLite fallback available) | No |
+| Dependency                                                                                             | Purpose                                                      | Required |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
+| [OpenCode](https://opencode.ai)                                                                        | Plugin host                                                  | Yes      |
+| [Beads](https://github.com/steveyegge/beads)                                                           | Git-backed issue tracking                                    | Yes      |
+| [Go](https://go.dev)                                                                                   | Required for Agent Mail                                      | No       |
+| [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail)                                  | Multi-agent coordination, file reservations                  | No       |
+| [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions                        | No       |
+| [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner)                | Pre-completion bug scanning using AI-powered static analysis | No       |
+| [semantic-memory](https://github.com/joelhooks/semantic-memory)                                        | Learning persistence                                         | No       |
+| [Redis](https://redis.io)                                                                              | Rate limiting (SQLite fallback available)                    | No       |
 
 All dependencies are checked and can be installed via `swarm setup`.
 
+### Installing Optional Dependencies
+
+**UBS (Ultimate Bug Scanner)** - Scans code for bugs before task completion:
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh" | bash
+```
+
+**CASS (Coding Agent Session Search)** - Indexes and searches AI coding agent history:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode
+```
+
+**MCP Agent Mail** - Multi-agent coordination and file reservations:
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh" | bash -s -- --yes
+```
+
 ## Tools Reference
 
 ### Swarm
 
-| Tool | Description |
-|------|-------------|
-| `swarm_init` | Initialize swarm session |
-| `swarm_select_strategy` | Analyze task, recommend decomposition strategy (file/feature/risk-based) |
-| `swarm_plan_prompt` | Generate strategy-specific planning prompt with CASS history |
-| `swarm_decompose` | Generate decomposition prompt |
-| `swarm_validate_decomposition` | Validate response, detect file conflicts |
-| `swarm_spawn_subtask` | Generate worker agent prompt with Agent Mail/beads instructions |
-| `swarm_status` | Get swarm progress by epic ID |
-| `swarm_progress` | Report subtask progress to coordinator |
-| `swarm_complete` | Complete subtask - runs UBS scan, releases reservations |
-| `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
+| Tool                           | Description                                                               |
+| ------------------------------ | ------------------------------------------------------------------------- |
+| `swarm_init`                   | Initialize swarm session                                                  |
+| `swarm_select_strategy`        | Analyze task, recommend decomposition strategy (file/feature/risk-based)  |
+| `swarm_plan_prompt`            | Generate strategy-specific planning prompt with CASS history              |
+| `swarm_decompose`              | Generate decomposition prompt                                             |
+| `swarm_validate_decomposition` | Validate response, detect file conflicts                                  |
+| `swarm_spawn_subtask`          | Generate worker agent prompt with Agent Mail/beads instructions           |
+| `swarm_status`                 | Get swarm progress by epic ID                                             |
+| `swarm_progress`               | Report subtask progress to coordinator                                    |
+| `swarm_complete`               | Complete subtask - runs UBS (Ultimate Bug Scanner), releases reservations |
+| `swarm_record_outcome`         | Record outcome for learning (duration, errors, retries)                   |
 
 ### Beads
 
-| Tool | Description |
-|------|-------------|
-| `beads_create` | Create bead with type-safe validation |
-| `beads_create_epic` | Create epic + subtasks atomically |
-| `beads_query` | Query beads with filters (status, type, ready) |
-| `beads_update` | Update status/description/priority |
-| `beads_close` | Close bead with reason |
-| `beads_start` | Mark bead as in-progress |
-| `beads_ready` | Get next unblocked bead |
-| `beads_sync` | Sync to git and push |
-| `beads_link_thread` | Link bead to Agent Mail thread |
+| Tool                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `beads_create`      | Create bead with type-safe validation          |
+| `beads_create_epic` | Create epic + subtasks atomically              |
+| `beads_query`       | Query beads with filters (status, type, ready) |
+| `beads_update`      | Update status/description/priority             |
+| `beads_close`       | Close bead with reason                         |
+| `beads_start`       | Mark bead as in-progress                       |
+| `beads_ready`       | Get next unblocked bead                        |
+| `beads_sync`        | Sync to git and push                           |
+| `beads_link_thread` | Link bead to Agent Mail thread                 |
 
 ### Agent Mail
 
-| Tool | Description |
-|------|-------------|
-| `agentmail_init` | Initialize session, register agent |
-| `agentmail_send` | Send message to agents |
-| `agentmail_inbox` | Fetch inbox (max 5, no bodies - context safe) |
-| `agentmail_read_message` | Fetch single message body by ID |
+| Tool                         | Description                                    |
+| ---------------------------- | ---------------------------------------------- |
+| `agentmail_init`             | Initialize session, register agent             |
+| `agentmail_send`             | Send message to agents                         |
+| `agentmail_inbox`            | Fetch inbox (max 5, no bodies - context safe)  |
+| `agentmail_read_message`     | Fetch single message body by ID                |
 | `agentmail_summarize_thread` | Summarize thread (preferred over fetching all) |
-| `agentmail_reserve` | Reserve file paths for exclusive editing |
-| `agentmail_release` | Release file reservations |
-| `agentmail_ack` | Acknowledge message |
-| `agentmail_search` | Search messages by keyword |
-| `agentmail_health` | Check if Agent Mail server is running |
+| `agentmail_reserve`          | Reserve file paths for exclusive editing       |
+| `agentmail_release`          | Release file reservations                      |
+| `agentmail_ack`              | Acknowledge message                            |
+| `agentmail_search`           | Search messages by keyword                     |
+| `agentmail_health`           | Check if Agent Mail server is running          |
 
 ### Structured Output
 
-| Tool | Description |
-|------|-------------|
-| `structured_extract_json` | Extract JSON from markdown/text (multiple strategies) |
-| `structured_validate` | Validate response against schema |
-| `structured_parse_evaluation` | Parse self-evaluation response |
-| `structured_parse_decomposition` | Parse task decomposition response |
-| `structured_parse_bead_tree` | Parse bead tree for epic creation |
+| Tool                             | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `structured_extract_json`        | Extract JSON from markdown/text (multiple strategies) |
+| `structured_validate`            | Validate response against schema                      |
+| `structured_parse_evaluation`    | Parse self-evaluation response                        |
+| `structured_parse_decomposition` | Parse task decomposition response                     |
+| `structured_parse_bead_tree`     | Parse bead tree for epic creation                     |
 
 ## Decomposition Strategies
 
@@ -292,32 +297,32 @@ Best for: bug fixes, security issues
 
 The plugin learns from outcomes:
 
-| Mechanism | How It Works |
-|-----------|--------------|
-| Confidence decay | Criteria weights fade unless revalidated (90-day half-life) |
-| Implicit feedback | Fast + success = helpful signal, slow + errors = harmful |
-| Pattern maturity | candidate → established → proven (or deprecated) |
-| Anti-patterns | Patterns with >60% failure rate auto-invert |
+| Mechanism         | How It Works                                                |
+| ----------------- | ----------------------------------------------------------- |
+| Confidence decay  | Criteria weights fade unless revalidated (90-day half-life) |
+| Implicit feedback | Fast + success = helpful signal, slow + errors = harmful    |
+| Pattern maturity  | candidate → established → proven (or deprecated)            |
+| Anti-patterns     | Patterns with >60% failure rate auto-invert                 |
 
 ## Context Preservation
 
 Hard limits to prevent context exhaustion:
 
-| Constraint | Default | Reason |
-|------------|---------|--------|
-| Inbox limit | 5 messages | Prevents token burn |
-| Bodies excluded | Always | Fetch individually when needed |
-| Summarize preferred | Yes | Key points, not raw dump |
+| Constraint          | Default    | Reason                         |
+| ------------------- | ---------- | ------------------------------ |
+| Inbox limit         | 5 messages | Prevents token burn            |
+| Bodies excluded     | Always     | Fetch individually when needed |
+| Summarize preferred | Yes        | Key points, not raw dump       |
 
 ## Rate Limiting
 
 Client-side limits (Redis primary, SQLite fallback):
 
 | Endpoint | Per Minute | Per Hour |
-|----------|------------|----------|
-| send | 20 | 200 |
-| reserve | 10 | 100 |
-| inbox | 60 | 600 |
+| -------- | ---------- | -------- |
+| send     | 20         | 200      |
+| reserve  | 10         | 100      |
+| inbox    | 60         | 600      |
 
 Configure via `OPENCODE_RATE_LIMIT_{ENDPOINT}_PER_MIN` env vars.
 
@@ -328,7 +333,7 @@ bun install
 bun run typecheck
 bun test
 bun run build
-````
+```
 
 ## License
 

package/bin/swarm.ts

@@ -346,7 +346,7 @@ const DEPENDENCIES: Dependency[] = [
     description: "Required for Agent Mail",
   },
   {
-    name: "Agent Mail",
+    name: "MCP Agent Mail",
     command: "curl",
     checkArgs: [
       "-s",
@@ -363,25 +363,26 @@ const DEPENDENCIES: Dependency[] = [
     required: false,
     install: "https://github.com/Dicklesworthstone/mcp_agent_mail",
     installType: "manual",
-    description: "Multi-agent coordination & file reservations",
+    description:
+      "Multi-agent coordination & file reservations (like Gmail for coding agents)",
   },
   {
-    name: "CASS",
+    name: "CASS (Coding Agent Session Search)",
     command: "cass",
     checkArgs: ["--help"],
     required: false,
-    install: "https://github.com/Dicklesworthstone/cass",
+    install: "https://github.com/Dicklesworthstone/coding_agent_session_search",
     installType: "manual",
-    description: "Cross-agent session search",
+    description: "Indexes and searches AI coding agent history for context",
   },
   {
-    name: "UBS",
+    name: "UBS (Ultimate Bug Scanner)",
     command: "ubs",
     checkArgs: ["--help"],
     required: false,
-    install: "https://github.com/joelhooks/ubs",
+    install: "https://github.com/Dicklesworthstone/ultimate_bug_scanner",
     installType: "manual",
-    description: "Pre-commit bug scanning",
+    description: "AI-powered static analysis for pre-completion bug scanning",
   },
   {
     name: "semantic-memory",
@@ -488,11 +489,11 @@ const SWARM_COMMAND = `---
 description: Decompose task into parallel subtasks and coordinate agents
 ---
 
-You are a swarm coordinator. Take a complex task, break it into beads, and unleash parallel agents.
+You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
 
-## Usage
+## Task
 
-/swarm <task description or bead-id>
+$ARGUMENTS
 
 ## Workflow
 
@@ -500,14 +501,12 @@ You are a swarm coordinator. Take a complex task, break it into beads, and unlea
 2. **Decompose**: Use \`swarm_select_strategy\` then \`swarm_plan_prompt\` to break down the task
 3. **Create beads**: \`beads_create_epic\` with subtasks and file assignments
 4. **Reserve files**: \`agentmail_reserve\` for each subtask's files
-5. **Spawn agents**: Use Task tool with \`swarm_spawn_subtask\` prompts (or use @swarm-worker for sequential/single-file tasks)
+5. **Spawn agents**: Use Task tool with \`swarm_spawn_subtask\` prompts
 6. **Monitor**: Check \`agentmail_inbox\` for progress, use \`agentmail_summarize_thread\` for overview
 7. **Complete**: \`swarm_complete\` when done, then \`beads_sync\` to push
 
 ## Strategy Selection
 
-The plugin auto-selects decomposition strategy based on task keywords:
-
 | Strategy      | Best For                | Keywords                               |
 | ------------- | ----------------------- | -------------------------------------- |
 | file-based    | Refactoring, migrations | refactor, migrate, rename, update all  |