opencode-swarm-plugin 0.24.0 → 0.25.1

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 $ bun build ./src/index.ts --outdir ./dist --target node --external @electric-sql/pglite --external swarm-mail && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node --external @electric-sql/pglite --external swarm-mail && tsc
-Bundled 196 modules in 42ms
+Bundled 197 modules in 32ms
 
   index.js  1.16 MB  (entry point)
 
-Bundled 197 modules in 36ms
+Bundled 198 modules in 31ms
 
-  plugin.js  1.13 MB  (entry point)
+  plugin.js  1.14 MB  (entry point)
 

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # opencode-swarm-plugin
 
+## 0.25.1
+
+### Patch Changes
+
+- [`757f4a6`](https://github.com/joelhooks/swarm-tools/commit/757f4a690721b3f04a414e4c1694660862504e54) Thanks [@joelhooks](https://github.com/joelhooks)! - Fix skills_update tool - add `content` parameter as primary (with `body` as backwards-compat alias)
+
+  The tool was only accepting `body` but users expected `content`. Now both work:
+
+  - `skills_update(name="foo", content="new stuff")` - preferred
+  - `skills_update(name="foo", body="new stuff")` - still works for backwards compat
+
+- [`3d619ff`](https://github.com/joelhooks/swarm-tools/commit/3d619ffda78b2e6066491f053e8fad8dac7b5b71) Thanks [@joelhooks](https://github.com/joelhooks)! - Fix swarm_complete failing when bead project doesn't match CWD
+
+  - Use `project_key` as working directory for `bd close` command
+  - Improved error messages with context-specific recovery steps
+  - Added planning guardrails to warn when todowrite is used for parallel work (should use swarm)
+
+## 0.25.0
+
+### Minor Changes
+
+- [`b70ae35`](https://github.com/joelhooks/swarm-tools/commit/b70ae352876515bdfe68511d72bb472c85b7fdfc) Thanks [@joelhooks](https://github.com/joelhooks)! - Add Socratic planning phase and improved worker prompts to swarm setup
+
+  **SWARM_COMMAND template:**
+
+  - Added Phase 0: Socratic Planning - asks clarifying questions before decomposing
+  - Supports `--fast`, `--auto`, `--confirm-only` flags to skip questions
+  - ONE question at a time with concrete options and recommendations
+
+  **Worker agent template:**
+
+  - Reinforces the 9-step survival checklist from SUBTASK_PROMPT_V2
+  - Explicitly lists all steps with emphasis on non-negotiables
+  - Explains WHY skipping steps causes problems (lost work, conflicts, etc.)
+
+  **Agent path consolidation:**
+
+  - Now creates nested paths: `~/.config/opencode/agent/swarm/worker.md`
+  - Matches `Task(subagent_type="swarm/worker")` format
+  - Cleans up legacy flat files (`swarm-worker.md`) on reinstall
+
+  To get the new prompts, run `swarm setup` and choose "Reinstall everything".
+
 ## 0.24.0
 
 ### Minor Changes

package/bin/swarm.ts

@@ -883,7 +883,7 @@ const SWARM_COMMAND = `---
 description: Decompose task into parallel subtasks and coordinate agents
 ---
 
-You are a swarm coordinator. Decompose the task into beads and spawn parallel agents.
+You are a swarm coordinator. Your job is to clarify the task, decompose it into beads, and spawn parallel agents.
 
 ## Task
 
@@ -891,42 +891,84 @@ $ARGUMENTS
 
 ## Workflow
 
-### 1. Initialize
+### Phase 0: Socratic Planning (INTERACTIVE - unless --fast)
+
+**Before decomposing, clarify the task with the user.**
+
+Check for flags in the task:
+- \`--fast\` → Skip questions, use reasonable defaults
+- \`--auto\` → Zero interaction, heuristic decisions
+- \`--confirm-only\` → Show plan, get yes/no only
+
+**Default (no flags): Full Socratic Mode**
+
+1. **Analyze task for ambiguity:**
+   - Scope unclear? (what's included/excluded)
+   - Strategy unclear? (file-based vs feature-based)
+   - Dependencies unclear? (what needs to exist first)
+   - Success criteria unclear? (how do we know it's done)
+
+2. **If clarification needed, ask ONE question at a time:**
+   \`\`\`
+   The task "<task>" needs clarification before I can decompose it.
+
+   **Question:** <specific question>
+
+   Options:
+   a) <option 1> - <tradeoff>
+   b) <option 2> - <tradeoff>
+   c) <option 3> - <tradeoff>
+
+   I'd recommend (b) because <reason>. Which approach?
+   \`\`\`
+
+3. **Wait for user response before proceeding**
+
+4. **Iterate if needed** (max 2-3 questions)
+
+**Rules:**
+- ONE question at a time - don't overwhelm
+- Offer concrete options - not open-ended
+- Lead with recommendation - save cognitive load
+- Wait for answer - don't assume
+
+### Phase 1: Initialize
 \`swarmmail_init(project_path="$PWD", task_description="Swarm: <task>")\`
 
-### 2. Knowledge Gathering (MANDATORY)
+### Phase 2: Knowledge Gathering (MANDATORY)
 
 **Before decomposing, query ALL knowledge sources:**
 
 \`\`\`
 semantic-memory_find(query="<task keywords>", limit=5)   # Past learnings
 cass_search(query="<task description>", limit=5)         # Similar past tasks  
-pdf-brain_search(query="<domain concepts>", limit=5)     # Design patterns
 skills_list()                                            # Available skills
 \`\`\`
 
 Synthesize findings into shared_context for workers.
 
-### 3. Decompose
+### Phase 3: Decompose
 \`\`\`
 swarm_select_strategy(task="<task>")
 swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")
 swarm_validate_decomposition(response="<BeadTree JSON>")
 \`\`\`
 
-### 4. Create Beads
+### Phase 4: Create Beads
 \`beads_create_epic(epic_title="<task>", subtasks=[...])\`
 
-### 5. Reserve Files
+### Phase 5: Reserve Files
 \`swarmmail_reserve(paths=[...], reason="<bead-id>: <desc>")\`
 
-### 6. Spawn Agents (ALL in single message)
+### Phase 6: Spawn Agents (ALL in single message)
 \`\`\`
-swarm_spawn_subtask(bead_id, epic_id, subtask_title, files, shared_context)
+swarm_spawn_subtask(bead_id, epic_id, subtask_title, files, shared_context, project_path="$PWD")
 Task(subagent_type="swarm/worker", prompt="<from above>")
 \`\`\`
 
-### 7. Monitor
+**IMPORTANT:** Pass \`project_path\` to \`swarm_spawn_subtask\` so workers can call \`swarmmail_init\`.
+
+### Phase 7: Monitor
 \`\`\`
 swarm_status(epic_id, project_key)
 swarmmail_inbox()
@@ -934,7 +976,7 @@ swarmmail_inbox()
 
 Intervene if: blocked >5min, file conflicts, scope creep.
 
-### 8. Complete
+### Phase 8: Complete
 \`\`\`
 swarm_complete(...)
 beads_sync()
@@ -949,7 +991,15 @@ beads_sync()
 | risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |
 | research-based | Investigation, discovery | research, investigate, explore, learn  |
 
-Begin with knowledge gathering now.
+## Flag Reference
+
+| Flag | Effect |
+|------|--------|
+| \`--fast\` | Skip Socratic questions, use defaults |
+| \`--auto\` | Zero interaction, heuristic decisions |
+| \`--confirm-only\` | Show plan, get yes/no only |
+
+Begin with Phase 0 (Socratic Planning) unless \`--fast\` or \`--auto\` flag is present.
 `;
 
 const getPlannerAgent = (model: string) => `---
@@ -1017,47 +1067,61 @@ description: Executes subtasks in a swarm - fast, focused, cost-effective
 model: ${model}
 ---
 
-You are a swarm worker agent. Execute your assigned subtask efficiently.
+You are a swarm worker agent. Your prompt contains a **MANDATORY SURVIVAL CHECKLIST** - follow it IN ORDER.
 
-## Context
+## CRITICAL: Read Your Prompt Carefully
 
-Your prompt includes shared_context from the coordinator's knowledge gathering:
-- Relevant patterns from pdf-brain
-- Similar past approaches from CASS
-- Project-specific learnings from semantic-memory
+Your Task prompt contains detailed instructions including:
+- 9-step survival checklist (FOLLOW IN ORDER)
+- File reservations (YOU reserve, not coordinator)
+- Progress reporting requirements
+- Completion protocol
 
-**Use this context** - it contains patterns and prior art relevant to your task.
+**DO NOT skip steps.** The checklist exists because skipping steps causes:
+- Lost work (no tracking)
+- Edit conflicts (no reservations)
+- Wasted time (no semantic memory query)
+- Silent failures (no progress reports)
 
-## Workflow
+## Step Summary (details in your prompt)
 
-1. **Read** assigned files to understand current state
-2. **Check skills** if you need domain guidance: \`skills_use(name="<relevant-skill>")\`
-3. **Implement** changes following patterns from shared_context
-4. **Verify** (typecheck, lint if applicable)
-5. **Complete** with \`swarm_complete\`
+1. **swarmmail_init()** - FIRST, before anything else
+2. **semantic-memory_find()** - Check past learnings
+3. **skills_list() / skills_use()** - Load relevant skills
+4. **swarmmail_reserve()** - YOU reserve your files
+5. **Do the work** - Read, implement, verify
+6. **swarm_progress()** - Report at 25/50/75%
+7. **swarm_checkpoint()** - Before risky operations
+8. **semantic-memory_store()** - Store learnings
+9. **swarm_complete()** - NOT beads_close
 
-## Rules
+## Non-Negotiables
 
-- Focus ONLY on your assigned files
-- Report blockers immediately via Swarm Mail (don't spin)
-- Use beads_update if blocked
-- Call swarm_complete when done - it handles bead closure and file release
+- **Step 1 is MANDATORY** - swarm_complete fails without init
+- **Step 2 saves time** - past agents may have solved this
+- **Step 4 prevents conflicts** - workers reserve, not coordinator
+- **Step 6 prevents silent failure** - report progress
+- **Step 9 is the ONLY way to close** - releases reservations, records learning
 
-## Communication
+## When Blocked
 
 \`\`\`
 swarmmail_send(
   to=["coordinator"],
-  subject="Progress/Blocker",
-  body="...",
-  thread_id="<epic_id>"
+  subject="BLOCKED: <bead-id>",
+  body="<what you need>",
+  importance="high"
 )
+beads_update(id="<bead-id>", status="blocked")
 \`\`\`
 
-## Learning
+## Focus
 
-If you discover a reusable pattern worth preserving:
-\`semantic-memory_store(information="<pattern + why it matters>")\`
+- Only modify your assigned files
+- Don't fix other agents' code - coordinate instead
+- Report scope changes before expanding
+
+Begin by reading your full prompt and executing Step 1.
 `;
 
 // ============================================================================
@@ -1238,14 +1302,20 @@ async function setup() {
 
   const pluginPath = join(pluginDir, "swarm.ts");
   const commandPath = join(commandDir, "swarm.md");
-  const plannerAgentPath = join(agentDir, "swarm-planner.md");
-  const workerAgentPath = join(agentDir, "swarm-worker.md");
+  const swarmAgentDir = join(agentDir, "swarm");
+  const plannerAgentPath = join(swarmAgentDir, "planner.md");
+  const workerAgentPath = join(swarmAgentDir, "worker.md");
+  // Legacy flat paths (for detection/cleanup)
+  const legacyPlannerPath = join(agentDir, "swarm-planner.md");
+  const legacyWorkerPath = join(agentDir, "swarm-worker.md");
 
   const existingFiles = [
     pluginPath,
     commandPath,
     plannerAgentPath,
     workerAgentPath,
+    legacyPlannerPath,
+    legacyWorkerPath,
   ].filter((f) => existsSync(f));
 
   if (existingFiles.length > 0) {
@@ -1302,25 +1372,34 @@ async function setup() {
         process.exit(0);
       }
 
-      // Update model lines in agent files
-      if (existsSync(plannerAgentPath)) {
-        const content = readFileSync(plannerAgentPath, "utf-8");
+      // Update model lines in agent files (check both nested and legacy paths)
+      const plannerPaths = [plannerAgentPath, legacyPlannerPath].filter(existsSync);
+      const workerPaths = [workerAgentPath, legacyWorkerPath].filter(existsSync);
+
+      for (const path of plannerPaths) {
+        const content = readFileSync(path, "utf-8");
         const updated = content.replace(
           /^model: .+$/m,
           `model: ${coordinatorModel}`,
         );
-        writeFileSync(plannerAgentPath, updated);
+        writeFileSync(path, updated);
+      }
+      if (plannerPaths.length > 0) {
         p.log.success("Planner: " + coordinatorModel);
       }
-      if (existsSync(workerAgentPath)) {
-        const content = readFileSync(workerAgentPath, "utf-8");
+
+      for (const path of workerPaths) {
+        const content = readFileSync(path, "utf-8");
         const updated = content.replace(
           /^model: .+$/m,
           `model: ${workerModel}`,
         );
-        writeFileSync(workerAgentPath, updated);
+        writeFileSync(path, updated);
+      }
+      if (workerPaths.length > 0) {
         p.log.success("Worker: " + workerModel);
       }
+
       p.outro("Models updated! Your customizations are preserved.");
       return;
     }
@@ -1556,7 +1635,7 @@ async function setup() {
 
   // Create directories if needed
   const skillsDir = join(configDir, "skills");
-  for (const dir of [pluginDir, commandDir, agentDir, skillsDir]) {
+  for (const dir of [pluginDir, commandDir, agentDir, swarmAgentDir, skillsDir]) {
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
@@ -1568,12 +1647,24 @@ async function setup() {
   writeFileSync(commandPath, SWARM_COMMAND);
   p.log.success("Command: " + commandPath);
 
+  // Write nested agent files (swarm/planner.md, swarm/worker.md)
+  // This is the format used by Task(subagent_type="swarm/worker")
   writeFileSync(plannerAgentPath, getPlannerAgent(coordinatorModel as string));
   p.log.success("Planner agent: " + plannerAgentPath);
 
   writeFileSync(workerAgentPath, getWorkerAgent(workerModel as string));
   p.log.success("Worker agent: " + workerAgentPath);
 
+  // Clean up legacy flat agent files if they exist
+  if (existsSync(legacyPlannerPath)) {
+    rmSync(legacyPlannerPath);
+    p.log.message(dim("  Removed legacy: " + legacyPlannerPath));
+  }
+  if (existsSync(legacyWorkerPath)) {
+    rmSync(legacyWorkerPath);
+    p.log.message(dim("  Removed legacy: " + legacyWorkerPath));
+  }
+
   p.log.success("Skills directory: " + skillsDir);
 
   // Show bundled skills info (and optionally sync to global skills dir)

package/dist/index.d.ts

@@ -301,6 +301,7 @@ export declare const allTools: {
         args: {
             name: import("zod").ZodString;
             description: import("zod").ZodOptional<import("zod").ZodString>;
+            content: import("zod").ZodOptional<import("zod").ZodString>;
             body: import("zod").ZodOptional<import("zod").ZodString>;
             append_body: import("zod").ZodOptional<import("zod").ZodString>;
             tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
@@ -310,6 +311,7 @@ export declare const allTools: {
         execute(args: {
             name: string;
             description?: string | undefined;
+            content?: string | undefined;
             body?: string | undefined;
             append_body?: string | undefined;
             tags?: string[] | undefined;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -26806,7 +26806,8 @@ Use this to refine skills based on experience:
     args: {
       name: tool.schema.string().describe("Name of the skill to update"),
       description: tool.schema.string().max(1024).optional().describe("New description (replaces existing)"),
-      body: tool.schema.string().optional().describe("New body content (replaces existing)"),
+      content: tool.schema.string().optional().describe("New content/body (replaces existing SKILL.md body)"),
+      body: tool.schema.string().optional().describe("Alias for content - new body (replaces existing)"),
       append_body: tool.schema.string().optional().describe("Content to append to existing body"),
       tags: tool.schema.array(tool.schema.string()).optional().describe("New tags (replaces existing)"),
       add_tags: tool.schema.array(tool.schema.string()).optional().describe("Tags to add to existing"),
@@ -26821,8 +26822,9 @@ Use this to refine skills based on experience:
       }
       const newDescription = args.description ?? skill.metadata.description;
       let newBody = skill.body;
-      if (args.body) {
-        newBody = args.body;
+      const bodyContent = args.content ?? args.body;
+      if (bodyContent) {
+        newBody = bodyContent;
       } else if (args.append_body) {
         newBody = `${skill.body}
 
@@ -26849,7 +26851,7 @@ ${args.append_body}`;
           path: skill.path,
           updated: {
             description: args.description ? true : false,
-            body: args.body || args.append_body ? true : false,
+            content: args.content || args.body || args.append_body ? true : false,
             tags: args.tags || args.add_tags ? true : false,
             tools: args.tools ? true : false
           },
@@ -32373,23 +32375,32 @@ Continuing with completion, but this should be fixed for future subtasks.`;
           }, null, 2);
         }
       }
-      const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
+      const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.cwd(args.project_key).quiet().nothrow();
       if (closeResult.exitCode !== 0) {
         const stderrOutput = closeResult.stderr.toString().trim();
+        const stdoutOutput = closeResult.stdout.toString().trim();
+        const isNoDatabaseError = stderrOutput.includes("no beads database found");
+        const isNotFoundError = stderrOutput.includes("not found") || stderrOutput.includes("does not exist");
         return JSON.stringify({
           success: false,
           error: "Failed to close bead",
           failed_step: "bd close",
-          details: stderrOutput || "Unknown error from bd close command",
+          details: stderrOutput || stdoutOutput || "Unknown error from bd close command",
           bead_id: args.bead_id,
+          project_key: args.project_key,
           recovery: {
-            steps: [
+            steps: isNoDatabaseError ? [
+              `1. Verify project_key is correct: "${args.project_key}"`,
+              `2. Check .beads/ exists in that directory`,
+              `3. Bead ID prefix "${args.bead_id.split("-")[0]}" should match project`,
+              `4. Try: beads_close(id="${args.bead_id}", reason="...")`
+            ] : [
               `1. Check bead exists: bd show ${args.bead_id}`,
               `2. Check bead status (might already be closed): beads_query()`,
               `3. If bead is blocked, unblock first: beads_update(id="${args.bead_id}", status="in_progress")`,
               `4. Try closing directly: beads_close(id="${args.bead_id}", reason="...")`
             ],
-            hint: "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing."
+            hint: isNoDatabaseError ? `The project_key "${args.project_key}" doesn't have a .beads/ directory. Make sure you're using the correct project path.` : isNotFoundError ? `Bead "${args.bead_id}" not found. It may have been closed already or the ID is incorrect.` : "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing."
           }
         }, null, 2);
       }
@@ -34362,6 +34373,85 @@ function createMetrics(result, toolName) {
     timestamp: Date.now()
   };
 }
+
+// src/planning-guardrails.ts
+var FILE_MODIFICATION_PATTERNS = [
+  /\bimplement\b/i,
+  /\bcreate\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\badd\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bupdate\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bmodify\b/i,
+  /\brefactor\b/i,
+  /\bextract\b/i,
+  /\bmigrate\b/i,
+  /\bconvert\b/i,
+  /\brewrite\b/i,
+  /\bfix\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bwrite\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /src\//i,
+  /lib\//i,
+  /packages?\//i,
+  /components?\//i
+];
+var TRACKING_PATTERNS = [
+  /\breview\b/i,
+  /\bcheck\b/i,
+  /\bverify\b/i,
+  /\btest\b.*pass/i,
+  /\brun\b.*test/i,
+  /\bdeploy\b/i,
+  /\bmerge\b/i,
+  /\bpr\b/i,
+  /\bpush\b/i,
+  /\bcommit\b/i
+];
+function analyzeTodoWrite(args) {
+  const todos = args.todos;
+  if (!todos || !Array.isArray(todos) || todos.length < 6) {
+    return {
+      looksLikeParallelWork: false,
+      fileModificationCount: 0,
+      totalCount: todos?.length ?? 0
+    };
+  }
+  let fileModificationCount = 0;
+  for (const todo of todos) {
+    if (typeof todo !== "object" || todo === null)
+      continue;
+    const content = todo.content ?? "";
+    const isFileModification = FILE_MODIFICATION_PATTERNS.some((pattern) => pattern.test(content));
+    const isTracking = TRACKING_PATTERNS.some((pattern) => pattern.test(content));
+    if (isFileModification && !isTracking) {
+      fileModificationCount++;
+    }
+  }
+  const ratio = fileModificationCount / todos.length;
+  const looksLikeParallelWork = ratio >= 0.5 && fileModificationCount >= 4;
+  if (looksLikeParallelWork) {
+    return {
+      looksLikeParallelWork: true,
+      fileModificationCount,
+      totalCount: todos.length,
+      warning: `⚠️  This looks like a multi-file implementation plan (${fileModificationCount}/${todos.length} items are file modifications).
+
+Consider using swarm instead:
+  swarm_decompose → beads_create_epic → parallel task spawns
+
+TodoWrite is for tracking progress, not parallelizable implementation work.
+Swarm workers can complete these ${fileModificationCount} tasks in parallel.
+
+(Continuing with todowrite - this is just a suggestion)`
+    };
+  }
+  return {
+    looksLikeParallelWork: false,
+    fileModificationCount,
+    totalCount: todos.length
+  };
+}
+function shouldAnalyzeTool(toolName) {
+  return toolName === "todowrite" || toolName === "TodoWrite";
+}
 // src/storage.ts
 init_learning();
 
@@ -34881,6 +34971,15 @@ var SwarmPlugin = async (input) => {
         await releaseReservations();
       }
     },
+    "tool.execute.before": async (input2, output) => {
+      const toolName = input2.tool;
+      if (shouldAnalyzeTool(toolName)) {
+        const analysis = analyzeTodoWrite(output.args);
+        if (analysis.warning) {
+          console.warn(`[swarm-plugin] ${analysis.warning}`);
+        }
+      }
+    },
     "tool.execute.after": async (input2, output) => {
       const toolName = input2.tool;
       if (output.output && typeof output.output === "string") {

package/dist/planning-guardrails.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Planning Guardrails
+ *
+ * Detects when agents are about to make planning mistakes and warns them.
+ * Non-blocking - just emits warnings to help agents self-correct.
+ *
+ * @module planning-guardrails
+ */
+/**
+ * Result of analyzing todowrite args
+ */
+export interface TodoWriteAnalysis {
+    /** Whether this looks like parallel work that should use swarm */
+    looksLikeParallelWork: boolean;
+    /** Number of todos that look like file modifications */
+    fileModificationCount: number;
+    /** Total number of todos */
+    totalCount: number;
+    /** Warning message if applicable */
+    warning?: string;
+}
+/**
+ * Analyze todowrite args to detect potential planning mistakes
+ *
+ * Triggers warning when:
+ * - 6+ todos created in one call
+ * - Most todos match file modification patterns
+ * - Few todos match tracking patterns
+ *
+ * @param args - The todowrite tool arguments
+ * @returns Analysis result with optional warning
+ */
+export declare function analyzeTodoWrite(args: {
+    todos?: unknown[];
+}): TodoWriteAnalysis;
+/**
+ * Check if a tool call should trigger planning guardrails
+ *
+ * @param toolName - Name of the tool being called
+ * @returns Whether this tool should be analyzed
+ */
+export declare function shouldAnalyzeTool(toolName: string): boolean;
+//# sourceMappingURL=planning-guardrails.d.ts.map

package/dist/planning-guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-guardrails.d.ts","sourceRoot":"","sources":["../src/planning-guardrails.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAyCH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,qBAAqB,EAAE,OAAO,CAAC;IAE/B,wDAAwD;IACxD,qBAAqB,EAAE,MAAM,CAAC;IAE9B,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,EAAE,CAAA;CAAE,GAAG,iBAAiB,CA8D/E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3D"}

package/dist/plugin.js

@@ -26806,7 +26806,8 @@ Use this to refine skills based on experience:
     args: {
       name: tool.schema.string().describe("Name of the skill to update"),
       description: tool.schema.string().max(1024).optional().describe("New description (replaces existing)"),
-      body: tool.schema.string().optional().describe("New body content (replaces existing)"),
+      content: tool.schema.string().optional().describe("New content/body (replaces existing SKILL.md body)"),
+      body: tool.schema.string().optional().describe("Alias for content - new body (replaces existing)"),
       append_body: tool.schema.string().optional().describe("Content to append to existing body"),
       tags: tool.schema.array(tool.schema.string()).optional().describe("New tags (replaces existing)"),
       add_tags: tool.schema.array(tool.schema.string()).optional().describe("Tags to add to existing"),
@@ -26821,8 +26822,9 @@ Use this to refine skills based on experience:
       }
       const newDescription = args.description ?? skill.metadata.description;
       let newBody = skill.body;
-      if (args.body) {
-        newBody = args.body;
+      const bodyContent = args.content ?? args.body;
+      if (bodyContent) {
+        newBody = bodyContent;
       } else if (args.append_body) {
         newBody = `${skill.body}
 
@@ -26849,7 +26851,7 @@ ${args.append_body}`;
           path: skill.path,
           updated: {
             description: args.description ? true : false,
-            body: args.body || args.append_body ? true : false,
+            content: args.content || args.body || args.append_body ? true : false,
             tags: args.tags || args.add_tags ? true : false,
             tools: args.tools ? true : false
           },
@@ -32164,23 +32166,32 @@ Continuing with completion, but this should be fixed for future subtasks.`;
           }, null, 2);
         }
       }
-      const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
+      const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.cwd(args.project_key).quiet().nothrow();
       if (closeResult.exitCode !== 0) {
         const stderrOutput = closeResult.stderr.toString().trim();
+        const stdoutOutput = closeResult.stdout.toString().trim();
+        const isNoDatabaseError = stderrOutput.includes("no beads database found");
+        const isNotFoundError = stderrOutput.includes("not found") || stderrOutput.includes("does not exist");
         return JSON.stringify({
           success: false,
           error: "Failed to close bead",
           failed_step: "bd close",
-          details: stderrOutput || "Unknown error from bd close command",
+          details: stderrOutput || stdoutOutput || "Unknown error from bd close command",
           bead_id: args.bead_id,
+          project_key: args.project_key,
           recovery: {
-            steps: [
+            steps: isNoDatabaseError ? [
+              `1. Verify project_key is correct: "${args.project_key}"`,
+              `2. Check .beads/ exists in that directory`,
+              `3. Bead ID prefix "${args.bead_id.split("-")[0]}" should match project`,
+              `4. Try: beads_close(id="${args.bead_id}", reason="...")`
+            ] : [
               `1. Check bead exists: bd show ${args.bead_id}`,
               `2. Check bead status (might already be closed): beads_query()`,
               `3. If bead is blocked, unblock first: beads_update(id="${args.bead_id}", status="in_progress")`,
               `4. Try closing directly: beads_close(id="${args.bead_id}", reason="...")`
             ],
-            hint: "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing."
+            hint: isNoDatabaseError ? `The project_key "${args.project_key}" doesn't have a .beads/ directory. Make sure you're using the correct project path.` : isNotFoundError ? `Bead "${args.bead_id}" not found. It may have been closed already or the ID is incorrect.` : "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing."
           }
         }, null, 2);
       }
@@ -34099,6 +34110,85 @@ function guardrailOutput(toolName, output, config2 = DEFAULT_GUARDRAIL_CONFIG) {
     truncatedLength
   };
 }
+
+// src/planning-guardrails.ts
+var FILE_MODIFICATION_PATTERNS = [
+  /\bimplement\b/i,
+  /\bcreate\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\badd\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bupdate\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bmodify\b/i,
+  /\brefactor\b/i,
+  /\bextract\b/i,
+  /\bmigrate\b/i,
+  /\bconvert\b/i,
+  /\brewrite\b/i,
+  /\bfix\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bwrite\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /src\//i,
+  /lib\//i,
+  /packages?\//i,
+  /components?\//i
+];
+var TRACKING_PATTERNS = [
+  /\breview\b/i,
+  /\bcheck\b/i,
+  /\bverify\b/i,
+  /\btest\b.*pass/i,
+  /\brun\b.*test/i,
+  /\bdeploy\b/i,
+  /\bmerge\b/i,
+  /\bpr\b/i,
+  /\bpush\b/i,
+  /\bcommit\b/i
+];
+function analyzeTodoWrite(args) {
+  const todos = args.todos;
+  if (!todos || !Array.isArray(todos) || todos.length < 6) {
+    return {
+      looksLikeParallelWork: false,
+      fileModificationCount: 0,
+      totalCount: todos?.length ?? 0
+    };
+  }
+  let fileModificationCount = 0;
+  for (const todo of todos) {
+    if (typeof todo !== "object" || todo === null)
+      continue;
+    const content = todo.content ?? "";
+    const isFileModification = FILE_MODIFICATION_PATTERNS.some((pattern) => pattern.test(content));
+    const isTracking = TRACKING_PATTERNS.some((pattern) => pattern.test(content));
+    if (isFileModification && !isTracking) {
+      fileModificationCount++;
+    }
+  }
+  const ratio = fileModificationCount / todos.length;
+  const looksLikeParallelWork = ratio >= 0.5 && fileModificationCount >= 4;
+  if (looksLikeParallelWork) {
+    return {
+      looksLikeParallelWork: true,
+      fileModificationCount,
+      totalCount: todos.length,
+      warning: `⚠️  This looks like a multi-file implementation plan (${fileModificationCount}/${todos.length} items are file modifications).
+
+Consider using swarm instead:
+  swarm_decompose → beads_create_epic → parallel task spawns
+
+TodoWrite is for tracking progress, not parallelizable implementation work.
+Swarm workers can complete these ${fileModificationCount} tasks in parallel.
+
+(Continuing with todowrite - this is just a suggestion)`
+    };
+  }
+  return {
+    looksLikeParallelWork: false,
+    fileModificationCount,
+    totalCount: todos.length
+  };
+}
+function shouldAnalyzeTool(toolName) {
+  return toolName === "todowrite" || toolName === "TodoWrite";
+}
 // src/storage.ts
 init_learning();
 
@@ -34285,6 +34375,15 @@ var SwarmPlugin = async (input) => {
         await releaseReservations();
       }
     },
+    "tool.execute.before": async (input2, output) => {
+      const toolName = input2.tool;
+      if (shouldAnalyzeTool(toolName)) {
+        const analysis = analyzeTodoWrite(output.args);
+        if (analysis.warning) {
+          console.warn(`[swarm-plugin] ${analysis.warning}`);
+        }
+      }
+    },
     "tool.execute.after": async (input2, output) => {
       const toolName = input2.tool;
       if (output.output && typeof output.output === "string") {

package/dist/skills.d.ts

@@ -233,6 +233,7 @@ export declare const skills_update: {
     args: {
         name: import("zod").ZodString;
         description: import("zod").ZodOptional<import("zod").ZodString>;
+        content: import("zod").ZodOptional<import("zod").ZodString>;
         body: import("zod").ZodOptional<import("zod").ZodString>;
         append_body: import("zod").ZodOptional<import("zod").ZodString>;
         tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
@@ -242,6 +243,7 @@ export declare const skills_update: {
     execute(args: {
         name: string;
         description?: string | undefined;
+        content?: string | undefined;
         body?: string | undefined;
         append_body?: string | undefined;
         tags?: string[] | undefined;
@@ -389,6 +391,7 @@ export declare const skillsTools: {
         args: {
             name: import("zod").ZodString;
             description: import("zod").ZodOptional<import("zod").ZodString>;
+            content: import("zod").ZodOptional<import("zod").ZodString>;
             body: import("zod").ZodOptional<import("zod").ZodString>;
             append_body: import("zod").ZodOptional<import("zod").ZodString>;
             tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
@@ -398,6 +401,7 @@ export declare const skillsTools: {
         execute(args: {
             name: string;
             description?: string | undefined;
+            content?: string | undefined;
             body?: string | undefined;
             append_body?: string | undefined;
             tags?: string[] | undefined;

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/swarm-orchestrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarm-orchestrate.d.ts","sourceRoot":"","sources":["../src/swarm-orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgiBxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;;;;CAuGrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAoFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;CA8GzB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;CA6E1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiiBzB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJ/B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CA6CjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;CAmClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAmB9B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;CAoJ9B,CAAC;AA4BH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqG3B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;CAsGxB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMtB,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc5B,CAAC"}
+{"version":3,"file":"swarm-orchestrate.d.ts","sourceRoot":"","sources":["../src/swarm-orchestrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgiBxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;;;;CAuGrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;CAoFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;CA8GzB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;CA6E1B,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqjBzB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJ/B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;CA6CjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;CAmClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;CAmB9B,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;CAoJ9B,CAAC;AA4BH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqG3B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;CAsGxB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMtB,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.24.0",
+  "version": "0.25.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

@@ -44,6 +44,10 @@ import {
   DEFAULT_GUARDRAIL_CONFIG,
   type GuardrailResult,
 } from "./output-guardrails";
+import {
+  analyzeTodoWrite,
+  shouldAnalyzeTool,
+} from "./planning-guardrails";
 
 /**
  * OpenCode Swarm Plugin
@@ -164,6 +168,24 @@ export const SwarmPlugin: Plugin = async (
       }
     },
 
+    /**
+     * Hook before tool execution for planning guardrails
+     *
+     * Warns when agents are about to make planning mistakes:
+     * - Using todowrite for multi-file implementation (should use swarm)
+     */
+    "tool.execute.before": async (input, output) => {
+      const toolName = input.tool;
+
+      // Check for planning anti-patterns
+      if (shouldAnalyzeTool(toolName)) {
+        const analysis = analyzeTodoWrite(output.args);
+        if (analysis.warning) {
+          console.warn(`[swarm-plugin] ${analysis.warning}`);
+        }
+      }
+    },
+
     /**
      * Hook after tool execution for automatic cleanup and guardrails
      *

package/src/planning-guardrails.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from "bun:test";
+import { analyzeTodoWrite, shouldAnalyzeTool } from "./planning-guardrails";
+
+describe("planning-guardrails", () => {
+  describe("shouldAnalyzeTool", () => {
+    it("returns true for todowrite", () => {
+      expect(shouldAnalyzeTool("todowrite")).toBe(true);
+      expect(shouldAnalyzeTool("TodoWrite")).toBe(true);
+    });
+
+    it("returns false for other tools", () => {
+      expect(shouldAnalyzeTool("beads_create")).toBe(false);
+      expect(shouldAnalyzeTool("swarm_decompose")).toBe(false);
+      expect(shouldAnalyzeTool("read")).toBe(false);
+    });
+  });
+
+  describe("analyzeTodoWrite", () => {
+    it("returns no warning for small todo lists", () => {
+      const result = analyzeTodoWrite({
+        todos: [
+          { content: "Implement feature A", status: "pending" },
+          { content: "Add tests", status: "pending" },
+        ],
+      });
+
+      expect(result.looksLikeParallelWork).toBe(false);
+      expect(result.warning).toBeUndefined();
+      expect(result.totalCount).toBe(2);
+    });
+
+    it("warns for 6+ file modification todos", () => {
+      const result = analyzeTodoWrite({
+        todos: [
+          { content: "Implement src/auth/login.ts", status: "pending" },
+          { content: "Create src/auth/logout.ts", status: "pending" },
+          { content: "Add src/auth/types.ts", status: "pending" },
+          { content: "Update src/auth/index.ts", status: "pending" },
+          { content: "Refactor src/lib/session.ts", status: "pending" },
+          { content: "Modify src/middleware/auth.ts", status: "pending" },
+        ],
+      });
+
+      expect(result.looksLikeParallelWork).toBe(true);
+      expect(result.warning).toBeDefined();
+      expect(result.warning).toContain("multi-file implementation plan");
+      expect(result.warning).toContain("swarm");
+      expect(result.fileModificationCount).toBeGreaterThanOrEqual(4);
+    });
+
+    it("does not warn for tracking/coordination todos", () => {
+      const result = analyzeTodoWrite({
+        todos: [
+          { content: "Review PR #123", status: "pending" },
+          { content: "Check tests pass", status: "pending" },
+          { content: "Verify deployment", status: "pending" },
+          { content: "Run integration tests", status: "pending" },
+          { content: "Merge to main", status: "pending" },
+          { content: "Push to production", status: "pending" },
+        ],
+      });
+
+      expect(result.looksLikeParallelWork).toBe(false);
+      expect(result.warning).toBeUndefined();
+    });
+
+    it("does not warn for mixed todos with few file modifications", () => {
+      const result = analyzeTodoWrite({
+        todos: [
+          { content: "Implement src/feature.ts", status: "pending" },
+          { content: "Review changes", status: "pending" },
+          { content: "Run tests", status: "pending" },
+          { content: "Check linting", status: "pending" },
+          { content: "Deploy to staging", status: "pending" },
+          { content: "Verify in browser", status: "pending" },
+        ],
+      });
+
+      // Only 1 file modification out of 6 - should not trigger
+      expect(result.looksLikeParallelWork).toBe(false);
+      expect(result.warning).toBeUndefined();
+    });
+
+    it("handles empty or missing todos", () => {
+      expect(analyzeTodoWrite({}).looksLikeParallelWork).toBe(false);
+      expect(analyzeTodoWrite({ todos: [] }).looksLikeParallelWork).toBe(false);
+      expect(analyzeTodoWrite({ todos: undefined as any }).looksLikeParallelWork).toBe(false);
+    });
+
+    it("handles malformed todo items", () => {
+      const result = analyzeTodoWrite({
+        todos: [
+          null,
+          undefined,
+          "string instead of object",
+          { noContent: true },
+          { content: "Implement src/valid.ts", status: "pending" },
+          { content: "Create src/another.ts", status: "pending" },
+        ] as any,
+      });
+
+      // Should handle gracefully without crashing
+      expect(result.totalCount).toBe(6);
+    });
+  });
+});

package/src/planning-guardrails.ts

@@ -0,0 +1,149 @@
+/**
+ * Planning Guardrails
+ *
+ * Detects when agents are about to make planning mistakes and warns them.
+ * Non-blocking - just emits warnings to help agents self-correct.
+ *
+ * @module planning-guardrails
+ */
+
+/**
+ * Patterns that suggest file modification work
+ * These indicate the todo is about implementation, not tracking
+ */
+const FILE_MODIFICATION_PATTERNS = [
+  /\bimplement\b/i,
+  /\bcreate\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\badd\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bupdate\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bmodify\b/i,
+  /\brefactor\b/i,
+  /\bextract\b/i,
+  /\bmigrate\b/i,
+  /\bconvert\b/i,
+  /\brewrite\b/i,
+  /\bfix\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /\bwrite\b.*\.(ts|js|tsx|jsx|py|rs|go|java|rb|swift|kt)/i,
+  /src\//i,
+  /lib\//i,
+  /packages?\//i,
+  /components?\//i,
+];
+
+/**
+ * Patterns that suggest this is tracking/coordination work (OK for todowrite)
+ */
+const TRACKING_PATTERNS = [
+  /\breview\b/i,
+  /\bcheck\b/i,
+  /\bverify\b/i,
+  /\btest\b.*pass/i,
+  /\brun\b.*test/i,
+  /\bdeploy\b/i,
+  /\bmerge\b/i,
+  /\bpr\b/i,
+  /\bpush\b/i,
+  /\bcommit\b/i,
+];
+
+/**
+ * Result of analyzing todowrite args
+ */
+export interface TodoWriteAnalysis {
+  /** Whether this looks like parallel work that should use swarm */
+  looksLikeParallelWork: boolean;
+
+  /** Number of todos that look like file modifications */
+  fileModificationCount: number;
+
+  /** Total number of todos */
+  totalCount: number;
+
+  /** Warning message if applicable */
+  warning?: string;
+}
+
+/**
+ * Analyze todowrite args to detect potential planning mistakes
+ *
+ * Triggers warning when:
+ * - 6+ todos created in one call
+ * - Most todos match file modification patterns
+ * - Few todos match tracking patterns
+ *
+ * @param args - The todowrite tool arguments
+ * @returns Analysis result with optional warning
+ */
+export function analyzeTodoWrite(args: { todos?: unknown[] }): TodoWriteAnalysis {
+  const todos = args.todos;
+
+  // Not enough todos to analyze
+  if (!todos || !Array.isArray(todos) || todos.length < 6) {
+    return {
+      looksLikeParallelWork: false,
+      fileModificationCount: 0,
+      totalCount: todos?.length ?? 0,
+    };
+  }
+
+  // Count todos that look like file modifications
+  let fileModificationCount = 0;
+
+  for (const todo of todos) {
+    if (typeof todo !== "object" || todo === null) continue;
+
+    const content = (todo as { content?: string }).content ?? "";
+
+    // Check if it matches file modification patterns
+    const isFileModification = FILE_MODIFICATION_PATTERNS.some((pattern) =>
+      pattern.test(content)
+    );
+
+    // Check if it matches tracking patterns
+    const isTracking = TRACKING_PATTERNS.some((pattern) =>
+      pattern.test(content)
+    );
+
+    if (isFileModification && !isTracking) {
+      fileModificationCount++;
+    }
+    // trackingCount not currently used but kept for future ratio analysis
+  }
+
+  // Trigger warning if most todos look like file modifications
+  const ratio = fileModificationCount / todos.length;
+  const looksLikeParallelWork = ratio >= 0.5 && fileModificationCount >= 4;
+
+  if (looksLikeParallelWork) {
+    return {
+      looksLikeParallelWork: true,
+      fileModificationCount,
+      totalCount: todos.length,
+      warning: `⚠️  This looks like a multi-file implementation plan (${fileModificationCount}/${todos.length} items are file modifications).
+
+Consider using swarm instead:
+  swarm_decompose → beads_create_epic → parallel task spawns
+
+TodoWrite is for tracking progress, not parallelizable implementation work.
+Swarm workers can complete these ${fileModificationCount} tasks in parallel.
+
+(Continuing with todowrite - this is just a suggestion)`,
+    };
+  }
+
+  return {
+    looksLikeParallelWork: false,
+    fileModificationCount,
+    totalCount: todos.length,
+  };
+}
+
+/**
+ * Check if a tool call should trigger planning guardrails
+ *
+ * @param toolName - Name of the tool being called
+ * @returns Whether this tool should be analyzed
+ */
+export function shouldAnalyzeTool(toolName: string): boolean {
+  return toolName === "todowrite" || toolName === "TodoWrite";
+}

package/src/skills.ts

@@ -995,10 +995,14 @@ Use this to refine skills based on experience:
       .max(1024)
       .optional()
       .describe("New description (replaces existing)"),
+    content: tool.schema
+      .string()
+      .optional()
+      .describe("New content/body (replaces existing SKILL.md body)"),
     body: tool.schema
       .string()
       .optional()
-      .describe("New body content (replaces existing)"),
+      .describe("Alias for content - new body (replaces existing)"),
     append_body: tool.schema
       .string()
       .optional()
@@ -1027,10 +1031,11 @@ Use this to refine skills based on experience:
     // Build updated metadata
     const newDescription = args.description ?? skill.metadata.description;
 
-    // Handle body updates
+    // Handle body updates (content is preferred, body is alias for backwards compat)
     let newBody = skill.body;
-    if (args.body) {
-      newBody = args.body;
+    const bodyContent = args.content ?? args.body;
+    if (bodyContent) {
+      newBody = bodyContent;
     } else if (args.append_body) {
       newBody = `${skill.body}\n\n${args.append_body}`;
     }
@@ -1067,7 +1072,7 @@ Use this to refine skills based on experience:
           path: skill.path,
           updated: {
             description: args.description ? true : false,
-            body: args.body || args.append_body ? true : false,
+            content: args.content || args.body || args.append_body ? true : false,
             tags: args.tags || args.add_tags ? true : false,
             tools: args.tools ? true : false,
           },

package/src/swarm-orchestrate.ts

@@ -1189,29 +1189,49 @@ Continuing with completion, but this should be fixed for future subtasks.`;
         }
       }
 
-      // Close the bead
+      // Close the bead - use project_key as working directory to find correct .beads/
+      // This fixes the issue where bead ID prefix (e.g., "pdf-library-g84.2") doesn't match CWD
       const closeResult =
         await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`
+          .cwd(args.project_key)
           .quiet()
           .nothrow();
 
       if (closeResult.exitCode !== 0) {
         const stderrOutput = closeResult.stderr.toString().trim();
+        const stdoutOutput = closeResult.stdout.toString().trim();
+
+        // Check for common error patterns and provide better guidance
+        const isNoDatabaseError = stderrOutput.includes("no beads database found");
+        const isNotFoundError = stderrOutput.includes("not found") || stderrOutput.includes("does not exist");
+
         return JSON.stringify(
           {
             success: false,
             error: "Failed to close bead",
             failed_step: "bd close",
-            details: stderrOutput || "Unknown error from bd close command",
+            details: stderrOutput || stdoutOutput || "Unknown error from bd close command",
             bead_id: args.bead_id,
+            project_key: args.project_key,
             recovery: {
-              steps: [
-                `1. Check bead exists: bd show ${args.bead_id}`,
-                `2. Check bead status (might already be closed): beads_query()`,
-                `3. If bead is blocked, unblock first: beads_update(id="${args.bead_id}", status="in_progress")`,
-                `4. Try closing directly: beads_close(id="${args.bead_id}", reason="...")`,
-              ],
-              hint: "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing.",
+              steps: isNoDatabaseError
+                ? [
+                    `1. Verify project_key is correct: "${args.project_key}"`,
+                    `2. Check .beads/ exists in that directory`,
+                    `3. Bead ID prefix "${args.bead_id.split("-")[0]}" should match project`,
+                    `4. Try: beads_close(id="${args.bead_id}", reason="...")`,
+                  ]
+                : [
+                    `1. Check bead exists: bd show ${args.bead_id}`,
+                    `2. Check bead status (might already be closed): beads_query()`,
+                    `3. If bead is blocked, unblock first: beads_update(id="${args.bead_id}", status="in_progress")`,
+                    `4. Try closing directly: beads_close(id="${args.bead_id}", reason="...")`,
+                  ],
+              hint: isNoDatabaseError
+                ? `The project_key "${args.project_key}" doesn't have a .beads/ directory. Make sure you're using the correct project path.`
+                : isNotFoundError
+                  ? `Bead "${args.bead_id}" not found. It may have been closed already or the ID is incorrect.`
+                  : "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing.",
             },
           },
           null,