opencode-swarm-plugin 0.55.0 → 0.56.0

package/claude-plugin/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "swarm-tools": {
+      "command": "bun",
+      "args": ["run", "${CLAUDE_PLUGIN_ROOT}/bin/swarm-mcp-server.ts"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}",
+      "description": "Swarm multi-agent coordination tools"
+    }
+  }
+}

package/claude-plugin/agents/background-worker.md

@@ -0,0 +1,36 @@
+---
+name: background-worker
+description: Runs background-only tasks without MCP tool access.
+model: haiku
+skills:
+  - swarm-coordination
+  - testing-patterns
+tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Background Worker Agent
+
+Background workers are for tasks that **do not require MCP tools** (summaries, doc edits, light refactors).
+
+## Constraints
+
+- **No MCP tools** are available in background subagents.
+- Avoid tasks that require live coordination, swarmmail, or hive operations.
+- If MCP tools are needed, request a foreground worker instead.
+
+## Safe Use Cases
+
+- Documentation updates
+- Static file edits
+- Copy edits and formatting
+- Notes, summaries, and small refactors
+
+## Usage Guidance
+
+If a task needs tool coordination or swarmmail calls, switch to a foreground worker.

package/claude-plugin/agents/coordinator.md

@@ -0,0 +1,39 @@
+---
+name: coordinator
+description: Orchestrates swarm coordination and supervises worker agents.
+model: opus
+skills:
+  - swarm-coordination
+  - system-design
+  - testing-patterns
+  - cli-builder
+tools:
+  - "*"
+---
+
+# Swarm Coordinator Agent
+
+Orchestrates swarm work: decomposes tasks, spawns workers, monitors progress, and reviews results.
+
+## Operating Rules
+
+- **Always initialize Swarm Mail first** with `swarmmail_init` before any coordination.
+- **Never reserve files** as the coordinator. Workers reserve their own files.
+- **Decompose with intent** using `swarm_plan_prompt` + `swarm_validate_decomposition`.
+- **Review every worker completion** via `swarm_review` + `swarm_review_feedback`.
+- **Record outcomes** with `swarm_complete` for learning signals.
+
+## Tool Access
+
+This agent is configured with `tools: ["*"]` to allow full tool access per user choice.
+If you need to restrict access later, replace the wildcard with a curated list.
+
+## Foreground Requirement
+
+MCP tools are **foreground-only**. Keep the coordinator in the foreground if it must call MCP tools.
+
+## Output Expectations
+
+- Produce clear decomposition plans and worker prompts.
+- Provide milestone updates, risks, and decisions to the user.
+- Escalate blockers quickly via Swarm Mail.

package/claude-plugin/agents/worker.md

@@ -0,0 +1,42 @@
+---
+name: worker
+description: Executes a single subtask with file reservations and progress reporting.
+model: sonnet
+skills:
+  - swarm-coordination
+  - testing-patterns
+  - system-design
+tools:
+  - "*"
+---
+
+# Swarm Worker Agent
+
+Executes a scoped subtask and reports progress to the coordinator.
+
+## Mandatory Checklist (Condensed)
+
+1. `swarmmail_init` first
+2. `hivemind_find` before coding
+3. `skills_use` for relevant skills
+4. `swarmmail_reserve` assigned files
+5. Implement changes
+6. `swarm_progress` at 25/50/75%
+7. `swarm_checkpoint` before risky ops
+8. `hivemind_store` learnings
+9. `swarm_complete` to finish
+
+## Tool Access
+
+This agent is configured with `tools: ["*"]` to allow full tool access per user choice.
+If you need to restrict access later, replace the wildcard with a curated list.
+
+## Foreground Requirement
+
+MCP tools are **foreground-only**. Keep this worker in the foreground when MCP tools are required.
+
+## Expectations
+
+- Follow TDD: red → green → refactor.
+- Respect file reservations and coordinate conflicts via Swarm Mail.
+- Provide clear progress updates and blockers.

package/claude-plugin/bin/swarm-mcp-server.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { allTools } from "../../dist/index.js";
+
+type ToolContext = {
+  sessionID: string;
+  messageID: string;
+  agent: string;
+  abort: AbortSignal;
+};
+
+type ToolDefinition = {
+  description?: string;
+  args?: Record<string, unknown>;
+  execute: (args: Record<string, unknown>, context: ToolContext) => Promise<unknown> | unknown;
+};
+
+/**
+ * Build a tool execution context for MCP tool calls.
+ */
+function createToolContext(): ToolContext {
+  const sessionId =
+    process.env.CLAUDE_SESSION_ID ||
+    process.env.OPENCODE_SESSION_ID ||
+    `mcp-${Date.now()}`;
+  const messageId =
+    process.env.CLAUDE_MESSAGE_ID ||
+    process.env.OPENCODE_MESSAGE_ID ||
+    `msg-${Date.now()}`;
+  const agent =
+    process.env.CLAUDE_AGENT_NAME || process.env.OPENCODE_AGENT || "claude";
+
+  return {
+    sessionID: sessionId,
+    messageID: messageId,
+    agent,
+    abort: new AbortController().signal,
+  };
+}
+
+/**
+ * Normalize tool execution results into text output.
+ */
+function formatToolOutput(result: unknown): string {
+  if (typeof result === "string") {
+    return result;
+  }
+
+  try {
+    return JSON.stringify(result, null, 2);
+  } catch {
+    return String(result);
+  }
+}
+
+/**
+ * Register all swarm tools with the MCP server.
+ */
+function registerTools(server: McpServer): void {
+  const tools = allTools as Record<string, ToolDefinition>;
+
+  for (const [toolName, toolDef] of Object.entries(tools)) {
+    server.registerTool(
+      toolName,
+      {
+        description: toolDef.description ?? `Swarm tool: ${toolName}`,
+        inputSchema: toolDef.args ?? {},
+      },
+      async (args) => {
+        const result = await toolDef.execute(
+          (args ?? {}) as Record<string, unknown>,
+          createToolContext(),
+        );
+
+        return {
+          content: [{ type: "text", text: formatToolOutput(result) }],
+        };
+      },
+    );
+  }
+}
+
+/**
+ * Start the MCP server over stdio for Claude Code auto-launch.
+ */
+async function main(): Promise<void> {
+  const server = new McpServer({
+    name: "swarm-tools",
+    version: process.env.SWARM_VERSION || "dev",
+  });
+
+  registerTools(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[swarm-mcp] Server started");
+}
+
+main().catch((error) => {
+  console.error("[swarm-mcp] Server failed", error);
+  process.exit(1);
+});

package/claude-plugin/commands/handoff.md

@@ -0,0 +1,17 @@
+---
+description: Properly end a swarm session - release reservations, sync state, generate continuation prompt
+---
+
+# /swarm:handoff
+
+Wrap up a swarm session cleanly.
+
+## Workflow
+1. Summarize completed work and open blockers.
+2. `swarmmail_release()` to free reservations (if any).
+3. Update cells with `hive_update()` or `hive_close()`.
+4. `hive_sync()` to persist state to git.
+5. Provide a concise handoff note for the next session.
+
+## Usage
+`/swarm:handoff`

package/claude-plugin/commands/hive.md

@@ -0,0 +1,19 @@
+---
+description: Query and manage swarm tasks (cells)
+---
+
+# /swarm:hive
+
+Manage Hive cells with the `hive_*` tools (never the deprecated `bd` CLI).
+
+## Common actions
+- List ready work: `hive_ready()`
+- Query by status: `hive_query({ status: "open" })`
+- Create a task: `hive_create({ title, type, priority })`
+- Update status/description: `hive_update(id, { status, description })`
+- Close a cell: `hive_close(id, "Done")`
+
+## Usage
+- `/swarm:hive`
+- `/swarm:hive create "Fix auth bug"`
+- `/swarm:hive close <cell-id> "Done"`

package/claude-plugin/commands/inbox.md

@@ -0,0 +1,15 @@
+---
+description: Check swarm mail inbox for messages from other agents
+---
+
+# /swarm:inbox
+
+Review Swarm Mail without blowing context.
+
+## Workflow
+1. `swarmmail_inbox()` for headers (max 5).
+2. `swarmmail_read_message(message_id)` for details.
+3. `swarmmail_ack(message_id)` when handled.
+
+## Usage
+`/swarm:inbox`

package/claude-plugin/commands/status.md

@@ -0,0 +1,15 @@
+---
+description: Check swarm coordination status - workers, messages, reservations
+---
+
+# /swarm:status
+
+Summarize active swarm state.
+
+## Workflow
+1. `swarm_status({ epic_id, project_key })` for progress and workers.
+2. `swarmmail_inbox()` to surface new messages.
+3. `hive_query({ status: "in_progress" })` for active cells.
+
+## Usage
+`/swarm:status`

package/claude-plugin/commands/swarm.md

@@ -0,0 +1,19 @@
+---
+description: Decompose a task into parallel subtasks and coordinate execution
+---
+
+# /swarm:swarm
+
+Use this command to kick off a multi-agent swarm.
+
+## Workflow
+1. Clarify scope and success criteria if needed.
+2. `swarmmail_init()` to register the session.
+3. `swarm_decompose()` → `swarm_validate_decomposition()` for a safe plan.
+4. `hive_create_epic()` to create the epic + subtasks.
+5. `swarm_spawn_subtask()` for each subtask (workers reserve files).
+6. Monitor with `swarm_status()` and `swarmmail_inbox()`.
+7. Review workers with `swarm_review()` + `swarm_review_feedback()`.
+
+## Usage
+`/swarm:swarm Add OAuth authentication with Google and GitHub`

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,48 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude session-start"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude user-prompt"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude pre-compact"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude session-end"
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-plugin/skills/swarm-coordination/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: swarm-coordination
+description: Multi-agent coordination patterns for OpenCode swarm workflows. Use when work benefits from parallelization or coordination.
+tags:
+  - swarm
+  - multi-agent
+  - coordination
+tools:
+  - "*"
+related_skills:
+  - testing-patterns
+  - system-design
+  - cli-builder
+---
+
+# Swarm Coordination
+
+This skill guides multi-agent coordination for OpenCode swarm workflows.
+
+## When to Use
+
+- Tasks touching 3+ files
+- Parallelizable work (frontend/backend/tests)
+- Work requiring specialized agents
+- Time-to-completion matters
+
+Avoid swarming for 1–2 file changes or tightly sequential work.
+
+## Tool Access (Wildcard)
+
+This skill is configured with `tools: ["*"]` per user choice. If you need curated access later, replace the wildcard with explicit tool lists.
+
+## Foreground vs Background
+
+- **Foreground agents** can access MCP tools.
+- **Background agents** do **not** have MCP tools.
+- Use foreground workers for `swarmmail_*`, `swarm_*`, `hive_*`, and MCP calls.
+- Use background workers for doc edits and static work only.
+
+## MCP Lifecycle Mitigation
+
+Claude Code auto-launches MCP servers from `mcpServers` configuration. Do **not** require manual `swarm mcp-serve` except for debugging.
+
+## Coordinator Protocol (High-Level)
+
+1. Initialize Swarm Mail (`swarmmail_init`).
+2. Query past learnings (`hivemind_find`).
+3. Decompose (`swarm_plan_prompt` + `swarm_validate_decomposition`).
+4. Spawn workers with explicit file lists.
+5. Review worker output (`swarm_review` + `swarm_review_feedback`).
+6. Record outcomes (`swarm_complete`).
+
+## Worker Protocol (High-Level)
+
+1. Initialize Swarm Mail (`swarmmail_init`).
+2. Reserve files (`swarmmail_reserve`).
+3. Work within scope and report progress.
+4. Complete with `swarm_complete`.
+
+## File Reservations
+
+Workers must reserve files **before** editing and release via `swarm_complete`.
+Coordinators never reserve files.
+
+## Progress Reporting
+
+Use `swarm_progress` at 25%, 50%, and 75% completion to trigger auto-checkpoints.
+
+## Skill Loading Guidance
+
+Workers should load skills based on task type:
+
+- Tests or fixes → `testing-patterns`
+- Architecture → `system-design`
+- CLI work → `cli-builder`
+- Coordination → `swarm-coordination`