opencode-swarm-plugin 0.57.6 → 0.58.4

package/claude-plugin/dist/index.js

@@ -40378,14 +40378,17 @@ class FlushManager {
   outputPath;
   debounceMs;
   onFlush;
+  onError;
   timer = null;
   flushing = false;
+  lastError = null;
   constructor(options2) {
     this.adapter = options2.adapter;
     this.projectKey = options2.projectKey;
     this.outputPath = options2.outputPath;
     this.debounceMs = options2.debounceMs ?? 30000;
     this.onFlush = options2.onFlush;
+    this.onError = options2.onError;
   }
   scheduleFlush() {
     if (this.timer) {
@@ -40393,7 +40396,11 @@ class FlushManager {
     }
     this.timer = setTimeout(() => {
       this.flush().catch((err) => {
+        this.lastError = err instanceof Error ? err : new Error(String(err));
         console.error("[FlushManager] Flush error:", err);
+        if (this.onError) {
+          this.onError(this.lastError);
+        }
       });
     }, this.debounceMs);
   }
@@ -40455,6 +40462,15 @@ class FlushManager {
       this.flushing = false;
     }
   }
+  hasError() {
+    return this.lastError !== null;
+  }
+  getLastError() {
+    return this.lastError;
+  }
+  clearError() {
+    this.lastError = null;
+  }
   stop() {
     if (this.timer) {
       clearTimeout(this.timer);
@@ -144060,13 +144076,13 @@ Scripts run in the skill's directory with the project directory as an argument.`
       }
       const scriptPath = join23(skill.directory, "scripts", args2.script);
       const scriptArgs = args2.args || [];
+      const TIMEOUT_MS = 60000;
+      const proc = Bun.spawn([scriptPath, skillsProjectDirectory, ...scriptArgs], {
+        cwd: skill.directory,
+        stdout: "pipe",
+        stderr: "pipe"
+      });
       try {
-        const TIMEOUT_MS = 60000;
-        const proc = Bun.spawn([scriptPath, skillsProjectDirectory, ...scriptArgs], {
-          cwd: skill.directory,
-          stdout: "pipe",
-          stderr: "pipe"
-        });
         const timeoutPromise = new Promise((resolve5) => {
           setTimeout(() => resolve5({ timedOut: true }), TIMEOUT_MS);
         });
@@ -144080,7 +144096,6 @@ Scripts run in the skill's directory with the project directory as an argument.`
         })();
         const result = await Promise.race([resultPromise, timeoutPromise]);
         if (result.timedOut) {
-          proc.kill();
           return `Script timed out after ${TIMEOUT_MS / 1000} seconds.`;
         }
         const output = result.stdout + result.stderr;
@@ -144092,6 +144107,8 @@ ${output}`;
         }
       } catch (error47) {
         return `Failed to execute script: ${error47 instanceof Error ? error47.message : String(error47)}`;
+      } finally {
+        proc.kill();
       }
     }
   });
@@ -144994,9 +145011,11 @@ async function execSemanticMemory(args2) {
       stderr: "pipe"
     });
     try {
+      const TIMEOUT_MS = 30000;
+      const timeoutPromise = new Promise((_, reject3) => setTimeout(() => reject3(new Error("Process timed out after 30s")), TIMEOUT_MS));
       const stdout = Buffer.from(await new Response(proc.stdout).arrayBuffer());
       const stderr = Buffer.from(await new Response(proc.stderr).arrayBuffer());
-      const exitCode = await proc.exited;
+      const exitCode = await Promise.race([proc.exited, timeoutPromise]);
       return { exitCode, stdout, stderr };
     } finally {
       proc.kill();
@@ -175327,12 +175346,16 @@ async function runGitCommand(args2) {
     stdout: "pipe",
     stderr: "pipe"
   });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text()
-  ]);
-  const exitCode = await proc.exited;
-  return { exitCode, stdout, stderr };
+  try {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text()
+    ]);
+    const exitCode = await proc.exited;
+    return { exitCode, stdout, stderr };
+  } finally {
+    proc.kill();
+  }
 }
 
 class HiveError extends Error {
@@ -175638,9 +175661,9 @@ var hive_create = tool({
   }
 });
 var hive_create_epic = tool({
-  description: "Create epic with subtasks in one atomic operation",
+  description: "Create epic with subtasks atomically. REQUIRED: epic_title, subtasks (array with {title, files?}). Use after swarm_validate_decomposition confirms your decomposition is valid. Each subtask should list files it will modify to enable parallel work without conflicts.",
   args: {
-    epic_title: tool.schema.string().describe("Epic title"),
+    epic_title: tool.schema.string().describe("Epic title (e.g., 'Implement user auth')"),
     epic_description: tool.schema.string().optional().describe("Epic description"),
     epic_id: tool.schema.string().optional().describe("Custom ID for the epic (e.g., 'phase-0')"),
     subtasks: tool.schema.array(tool.schema.object({
@@ -175659,6 +175682,28 @@ var hive_create_epic = tool({
     }).optional().describe("Recovery context from checkpoint compaction")
   },
   async execute(args2, ctx) {
+    const missing = [];
+    if (!args2.epic_title)
+      missing.push("epic_title");
+    if (!args2.subtasks || args2.subtasks.length === 0)
+      missing.push("subtasks (array of subtask objects)");
+    if (missing.length > 0) {
+      return JSON.stringify({
+        success: false,
+        error: `Missing required parameters: ${missing.join(", ")}`,
+        hint: "hive_create_epic creates an epic with subtasks atomically.",
+        example: {
+          epic_title: "Implement user authentication",
+          epic_description: "Add login, logout, and session management",
+          subtasks: [
+            { title: "Create auth service", files: ["src/auth/service.ts"] },
+            { title: "Add login endpoint", files: ["src/api/login.ts"] },
+            { title: "Add session middleware", files: ["src/middleware/session.ts"] }
+          ]
+        },
+        tip: "Each subtask should have a title and optionally files it will modify. This helps with file reservation and parallel execution."
+      }, null, 2);
+    }
     const validated = EpicCreateArgsSchema.parse(args2);
     const projectKey = getHiveWorkingDirectory();
     const adapter5 = await getHiveAdapter(projectKey);
@@ -176497,13 +176542,17 @@ var toolCheckers = {
         stderr: "pipe"
       });
       const timeout6 = setTimeout(() => proc.kill(), BUNX_TIMEOUT_MS);
-      const exitCode = await proc.exited;
-      clearTimeout(timeout6);
-      return {
-        available: exitCode === 0,
-        checkedAt: new Date().toISOString(),
-        version: "bunx"
-      };
+      try {
+        const exitCode = await proc.exited;
+        return {
+          available: exitCode === 0,
+          checkedAt: new Date().toISOString(),
+          version: "bunx"
+        };
+      } finally {
+        clearTimeout(timeout6);
+        proc.kill();
+      }
     } catch (e) {
       return {
         available: false,
@@ -176576,13 +176625,17 @@ var toolCheckers = {
         stderr: "pipe"
       });
       const timeout6 = setTimeout(() => proc.kill(), BUNX_TIMEOUT_MS);
-      const exitCode = await proc.exited;
-      clearTimeout(timeout6);
-      return {
-        available: exitCode === 0,
-        checkedAt: new Date().toISOString(),
-        version: "bunx-semantic-memory"
-      };
+      try {
+        const exitCode = await proc.exited;
+        return {
+          available: exitCode === 0,
+          checkedAt: new Date().toISOString(),
+          version: "bunx-semantic-memory"
+        };
+      } finally {
+        clearTimeout(timeout6);
+        proc.kill();
+      }
     } catch (e) {
       return {
         available: false,
@@ -176929,17 +176982,20 @@ class SqliteRateLimiter {
     const MAX_BATCHES = 10;
     const cutoff = Date.now() - 7200000;
     let totalDeleted = 0;
+    let batches = 0;
     for (let i = 0;i < MAX_BATCHES; i++) {
-      const result = this.db.run(`DELETE FROM rate_limits 
+      const result = this.db.run(`DELETE FROM rate_limits
          WHERE rowid IN (
-           SELECT rowid FROM rate_limits 
-           WHERE timestamp < ? 
+           SELECT rowid FROM rate_limits
+           WHERE timestamp < ?
            LIMIT ?
          )`, [cutoff, BATCH_SIZE]);
       totalDeleted += result.changes;
+      batches++;
       if (result.changes < BATCH_SIZE)
         break;
     }
+    return { totalDeleted, batches };
   }
   async recordRequest(agentName, endpoint) {
     const now3 = Date.now();
@@ -179413,14 +179469,27 @@ function formatCassHistoryForPrompt(history) {
 `);
 }
 var swarm_decompose = tool({
-  description: "Generate decomposition prompt for breaking task into parallelizable subtasks. Optionally queries CASS for similar past tasks.",
+  description: "Generate decomposition prompt for breaking task into parallelizable subtasks. REQUIRED: task (the work to decompose). Returns a prompt - use it to plan subtasks, then validate with swarm_validate_decomposition, then create with hive_create_epic.",
   args: {
-    task: tool.schema.string().min(1).describe("Task description to decompose"),
+    task: tool.schema.string().min(1).describe("Task description (e.g., 'Add user authentication with login/logout')"),
     context: tool.schema.string().optional().describe("Additional context (codebase info, constraints, etc.)"),
     query_cass: tool.schema.boolean().optional().describe("Query CASS for similar past tasks (default: true)"),
     cass_limit: tool.schema.number().int().min(1).optional().describe("Max CASS results to include (default: 3)")
   },
   async execute(args2) {
+    if (!args2.task) {
+      return JSON.stringify({
+        success: false,
+        error: "Missing required parameter: task",
+        hint: "swarm_decompose generates a decomposition prompt for breaking a task into parallelizable subtasks.",
+        example: {
+          task: "Implement user authentication with login, logout, and session management",
+          context: "This is a Next.js app using Prisma for database access",
+          query_cass: true
+        },
+        tip: "Provide a clear task description. The tool will generate a prompt for decomposition and optionally query past similar tasks for patterns."
+      }, null, 2);
+    }
     const { formatMemoryQueryForDecomposition: formatMemoryQueryForDecomposition2 } = await Promise.resolve().then(() => (init_learning(), exports_learning));
     let cassContext = "";
     let cassResultInfo;
@@ -179473,9 +179542,9 @@ ${fullContext}` : `## Additional Context
   }
 });
 var swarm_validate_decomposition = tool({
-  description: "Validate a decomposition response against CellTreeSchema and capture for eval",
+  description: "Validate decomposition JSON before creating epic. REQUIRED: response (JSON string with {epic: {title, description}, subtasks: [{title, files, dependencies}]}). Checks for file conflicts and valid dependencies. Call after planning, before hive_create_epic.",
   args: {
-    response: tool.schema.string().describe("JSON response from agent (CellTree format)"),
+    response: tool.schema.string().describe("JSON string with epic and subtasks (see example in error hint)"),
     project_path: tool.schema.string().optional().describe("Project path for eval capture"),
     task: tool.schema.string().optional().describe("Original task description for eval capture"),
     context: tool.schema.string().optional().describe("Context provided for decomposition"),
@@ -179483,8 +179552,35 @@ var swarm_validate_decomposition = tool({
     epic_id: tool.schema.string().optional().describe("Epic ID for eval capture")
   },
   async execute(args2) {
+    if (!args2.response) {
+      return JSON.stringify({
+        success: false,
+        valid: false,
+        error: "Missing required parameter: response",
+        hint: "swarm_validate_decomposition validates a decomposition JSON. Pass the decomposition output as the 'response' parameter.",
+        example: {
+          response: JSON.stringify({
+            epic: { title: "Epic title", description: "Epic description" },
+            subtasks: [
+              { title: "Subtask 1", description: "...", files: ["src/file.ts"], dependencies: [] }
+            ]
+          }),
+          project_path: "/path/to/project",
+          task: "Original task description"
+        },
+        tip: "This tool validates the JSON output from your decomposition planning. The 'response' should be a JSON string matching CellTreeSchema."
+      }, null, 2);
+    }
     try {
-      const parsed = JSON.parse(args2.response);
+      let parsed;
+      if (typeof args2.response === "string") {
+        parsed = JSON.parse(args2.response);
+        if (typeof parsed === "string") {
+          parsed = JSON.parse(parsed);
+        }
+      } else {
+        parsed = args2.response;
+      }
       const validated = CellTreeSchema.parse(parsed);
       const conflicts = detectFileConflicts(validated.subtasks);
       if (conflicts.length > 0) {
@@ -182574,17 +182670,41 @@ var swarm_status = tool({
   }
 });
 var swarm_progress = tool({
-  description: "Report progress on a subtask to coordinator",
+  description: "Report progress on a subtask to coordinator. REQUIRED: project_key, agent_name, bead_id, status. Call periodically (every 25% or when blocked) to keep coordinator informed. Use status='blocked' with message explaining the blocker if you're stuck.",
   args: {
-    project_key: tool.schema.string().describe("Project path"),
-    agent_name: tool.schema.string().describe("Your Agent Mail name"),
-    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    project_key: tool.schema.string().describe("Project path (e.g., '/Users/name/project')"),
+    agent_name: tool.schema.string().describe("Your agent name from swarmmail_init"),
+    bead_id: tool.schema.string().describe("Task ID from your spawn prompt or hive cell"),
     status: tool.schema.enum(["in_progress", "blocked", "completed", "failed"]).describe("Current status"),
     message: tool.schema.string().optional().describe("Progress message or blockers"),
     progress_percent: tool.schema.number().min(0).max(100).optional().describe("Completion percentage"),
     files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files modified so far")
   },
   async execute(args2) {
+    const missing = [];
+    if (!args2.bead_id)
+      missing.push("bead_id");
+    if (!args2.project_key)
+      missing.push("project_key");
+    if (!args2.agent_name)
+      missing.push("agent_name");
+    if (!args2.status)
+      missing.push("status");
+    if (missing.length > 0) {
+      return JSON.stringify({
+        success: false,
+        error: `Missing required parameters: ${missing.join(", ")}`,
+        hint: "swarm_progress reports task progress to the coordinator.",
+        example: {
+          project_key: "/path/to/project",
+          agent_name: "your-agent-name",
+          bead_id: "your-task-id from spawn",
+          status: "in_progress",
+          progress_percent: 50,
+          message: "Completed X, working on Y"
+        }
+      }, null, 2);
+    }
     const progress = {
       bead_id: args2.bead_id,
       agent_name: args2.agent_name,
@@ -182710,12 +182830,12 @@ ${args2.files_affected.map((f) => `- \`${f}\``).join(`
   }
 });
 var swarm_complete = tool({
-  description: "Mark subtask complete with Verification Gate. Runs typecheck and tests before allowing completion.",
+  description: "Mark subtask complete with Verification Gate. REQUIRED: project_key, agent_name, bead_id (from your task assignment), summary, start_time (Date.now() from when you started). Before calling: 1) hivemind_store your learnings, 2) list files_touched for verification. Runs typecheck/tests before finalizing.",
   args: {
-    project_key: tool.schema.string().describe("Project path"),
-    agent_name: tool.schema.string().describe("Your Agent Mail name"),
-    bead_id: tool.schema.string().describe("Subtask bead ID"),
-    summary: tool.schema.string().describe("Brief summary of work done"),
+    project_key: tool.schema.string().describe("Project path (e.g., '/Users/name/project')"),
+    agent_name: tool.schema.string().describe("Your agent name from swarmmail_init"),
+    bead_id: tool.schema.string().describe("Task ID from your spawn prompt or hive cell"),
+    summary: tool.schema.string().describe("What you accomplished (1-3 sentences)"),
     evaluation: tool.schema.string().optional().describe("Self-evaluation JSON (Evaluation schema)"),
     files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files modified - will be verified (typecheck, tests)"),
     skip_verification: tool.schema.boolean().optional().describe("Skip ALL verification (typecheck, tests). Use sparingly! (default: false)"),
@@ -182726,6 +182846,33 @@ var swarm_complete = tool({
     skip_review: tool.schema.boolean().optional().describe("Skip review gate check (default: false). Use only for tasks that don't require coordinator review.")
   },
   async execute(args2, _ctx) {
+    const missing = [];
+    if (!args2.bead_id)
+      missing.push("bead_id");
+    if (!args2.project_key)
+      missing.push("project_key");
+    if (!args2.agent_name)
+      missing.push("agent_name");
+    if (!args2.summary)
+      missing.push("summary");
+    if (args2.start_time === undefined)
+      missing.push("start_time");
+    if (missing.length > 0) {
+      return JSON.stringify({
+        success: false,
+        error: `Missing required parameters: ${missing.join(", ")}`,
+        hint: "swarm_complete marks a subtask as done. All parameters are required.",
+        example: {
+          project_key: "/path/to/project",
+          agent_name: "your-agent-name",
+          bead_id: "epic-id.subtask-num OR cell-id from hive",
+          summary: "Brief description of what you completed",
+          start_time: Date.now(),
+          files_touched: ["src/file1.ts", "src/file2.ts"]
+        },
+        tip: "The bead_id comes from swarm_spawn_subtask or hive_create. Check your task assignment for the correct ID."
+      }, null, 2);
+    }
     const epicId = args2.bead_id.includes(".") ? args2.bead_id.split(".")[0] : args2.bead_id;
     if (!args2.skip_review) {
       const reviewStatusResult = getReviewStatus(args2.bead_id);
@@ -184062,6 +184209,26 @@ Before writing code:
 Begin work on your subtask now.`;
 var SUBTASK_PROMPT_V2 = `You are a swarm agent working on: **{subtask_title}**
 
+╔═══════════════════════════════════════════════════════════════════════════════╗
+║                                                                               ║
+║   \uD83D\uDED1  STOP - READ THIS FIRST - BEFORE ANY EDIT OR WRITE  \uD83D\uDED1                  ║
+║                                                                               ║
+║   You MUST do these 3 things BEFORE your first Edit/Write call:              ║
+║                                                                               ║
+║   1️⃣  hivemind_find(query="<your task keywords>", limit=5, expand=true)      ║
+║       → Check if past agents already solved this                              ║
+║       → Find gotchas, patterns, warnings                                      ║
+║                                                                               ║
+║   2️⃣  skills_list() then skills_use(name="<relevant>")                       ║
+║       → testing-patterns, swarm-coordination, system-design                   ║
+║                                                                               ║
+║   3️⃣  swarmmail_send(to=["coordinator"], ...) when blocked                   ║
+║       → Don't spin >5min - ASK FOR HELP                                       ║
+║                                                                               ║
+║   SKIPPING THESE = wasted time repeating solved problems                      ║
+║                                                                               ║
+╚═══════════════════════════════════════════════════════════════════════════════╝
+
 ## [IDENTITY]
 Agent: (assigned at spawn)
 Cell: {bead_id}

package/claude-plugin/hooks/hooks.json

@@ -22,6 +22,73 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude pre-edit"
+          }
+        ]
+      },
+      {
+        "matcher": "swarm_complete",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude pre-complete"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "hivemind_find|mcp__plugin_swarm_swarm-tools__hivemind_find",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude track-tool hivemind_find"
+          }
+        ]
+      },
+      {
+        "matcher": "skills_use|Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude track-tool skills_use"
+          }
+        ]
+      },
+      {
+        "matcher": "swarmmail_init|mcp__plugin_swarm_swarm-tools__swarmmail_init",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude track-tool swarmmail_init"
+          }
+        ]
+      },
+      {
+        "matcher": "hivemind_store|mcp__plugin_swarm_swarm-tools__hivemind_store",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude track-tool hivemind_store"
+          }
+        ]
+      },
+      {
+        "matcher": "swarm_complete",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "swarm claude post-complete"
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "matcher": "",

package/claude-plugin/skills/release/SKILL.md

@@ -0,0 +1,101 @@
+# Release Skill
+
+Handles version bumps and releases for the opencode-swarm-plugin monorepo.
+
+## Version Touchpoints
+
+When bumping versions, ALL of these files must be updated:
+
+### opencode-swarm-plugin
+- `packages/opencode-swarm-plugin/package.json` - npm package version
+- `packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json` - Claude plugin version
+
+### claude-code-swarm-plugin (thin wrapper)
+- `packages/claude-code-swarm-plugin/package.json` - npm package version
+- `packages/claude-code-swarm-plugin/.claude-plugin/plugin.json` - Claude plugin version
+
+### Other packages (if applicable)
+- `packages/swarm-evals/package.json`
+- `packages/swarm-mail/package.json`
+- `packages/swarm-dashboard/package.json`
+
+## Release Process
+
+1. **Create changeset** (for proper changelog generation):
+   ```bash
+   # Interactive (won't work in CI/agent context)
+   bun changeset
+
+   # Manual - create file in .changeset/
+   echo '---
+   "opencode-swarm-plugin": minor
+   "claude-code-swarm-plugin": minor
+   ---
+
+   feat: description of changes' > .changeset/my-change.md
+   ```
+
+2. **Version bump** (applies changesets):
+   ```bash
+   bun run ci:version
+   ```
+   This runs `changeset version` and updates package.jsons
+
+3. **CRITICAL: Sync plugin.json versions manually**:
+   ```bash
+   # Get version from package.json
+   VERSION=$(cat packages/opencode-swarm-plugin/package.json | jq -r '.version')
+
+   # Update both plugin.json files
+   jq ".version = \"$VERSION\"" packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json > /tmp/p1.json && mv /tmp/p1.json packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json
+
+   VERSION=$(cat packages/claude-code-swarm-plugin/package.json | jq -r '.version')
+   jq ".version = \"$VERSION\"" packages/claude-code-swarm-plugin/.claude-plugin/plugin.json > /tmp/p2.json && mv /tmp/p2.json packages/claude-code-swarm-plugin/.claude-plugin/plugin.json
+   ```
+
+4. **Build**:
+   ```bash
+   cd packages/opencode-swarm-plugin && bun run build
+   ```
+
+5. **Publish**:
+   ```bash
+   bun run ci:publish
+   ```
+
+6. **Commit and push**:
+   ```bash
+   git add -A && git commit -m "release: bump versions" && git push
+   ```
+
+## Quick Version Bump Script
+
+Run this to bump all version touchpoints at once:
+
+```bash
+#!/bin/bash
+NEW_VERSION=$1
+
+if [ -z "$NEW_VERSION" ]; then
+  echo "Usage: ./bump-version.sh 0.59.0"
+  exit 1
+fi
+
+# Main package
+jq ".version = \"$NEW_VERSION\"" packages/opencode-swarm-plugin/package.json > /tmp/pkg.json && mv /tmp/pkg.json packages/opencode-swarm-plugin/package.json
+jq ".version = \"$NEW_VERSION\"" packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json > /tmp/plug.json && mv /tmp/plug.json packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json
+
+# Thin wrapper (claude-code-swarm-plugin)
+jq ".version = \"$NEW_VERSION\"" packages/claude-code-swarm-plugin/package.json > /tmp/pkg.json && mv /tmp/pkg.json packages/claude-code-swarm-plugin/package.json
+jq ".version = \"$NEW_VERSION\"" packages/claude-code-swarm-plugin/.claude-plugin/plugin.json > /tmp/plug.json && mv /tmp/plug.json packages/claude-code-swarm-plugin/.claude-plugin/plugin.json
+
+echo "Bumped all packages to $NEW_VERSION"
+git diff --stat
+```
+
+## Gotchas
+
+- **plugin.json is NOT auto-bumped by changesets** - must be done manually
+- **Two separate plugins**: `opencode-swarm-plugin` (full) and `claude-code-swarm-plugin` (thin wrapper)
+- **Claude Code marketplace installs from cache** - users may need to uninstall/reinstall for updates
+- **npm publish needs `--access public`** for scoped packages