opencode-beads 0.1.2 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-beads",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "type": "module",
   "description": "A plugin for OpenCode that provides integration with the beads issue tracker.",
   "author": "Josh Thomas <josh@joshthomas.dev>",

package/src/plugin.ts

@@ -10,7 +10,7 @@
  */
 
 import type { Plugin, PluginInput } from "@opencode-ai/plugin";
-import { CLI_GUIDANCE, loadAgent, loadCommands } from "./vendor";
+import { BEADS_GUIDANCE, loadAgent, loadCommands } from "./vendor";
 
 type OpencodeClient = PluginInput["client"];
 
@@ -70,7 +70,7 @@ async function injectBeadsContext(
 ${primeOutput.trim()}
 </beads-context>
 
-${CLI_GUIDANCE}`;
+${BEADS_GUIDANCE}`;
 
     // Inject content via noReply + synthetic
     // Must pass model and agent to prevent mode/model switching

package/src/vendor.ts

@@ -84,26 +84,69 @@ async function listVendorFiles(relativePath: string): Promise<string[]> {
   }
 }
 
-export const CLI_GUIDANCE = `<beads-cli-guidance>
-Beads MCP tools are not available. Use the \`bd\` CLI via bash instead:
-
-- \`init\` → \`bd init [prefix]\`
-- \`ready\` → \`bd ready --json\`
-- \`show\` → \`bd show <id> --json\`
-- \`create\` → \`bd create "title" -t bug|feature|task -p 0-4 --json\`
-- \`update\` → \`bd update <id> --status in_progress --json\`
-- \`close\` → \`bd close <id> --reason "message" --json\`
-- \`reopen\` → \`bd reopen <id> --json\`
-- \`dep\` → \`bd dep add <from> <to> --type blocks|discovered-from --json\`
-- \`list\` → \`bd list --status open --json\`
-- \`blocked\` → \`bd blocked --json\`
-- \`stats\` → \`bd stats --json\`
-- \`sync\` → \`bd sync\`
-
-MCP tools map directly to bd CLI commands. If a tool is not listed above, try \`bd <tool> --help\`.
-
-Always use \`--json\` flag for structured output.
-</beads-cli-guidance>`;
+const BEADS_CLI_USAGE = `## CLI Usage
+
+**Note:** Beads MCP tools are not available in this environment. Use the \`bd\` CLI via bash instead. MCP tool names map directly to \`bd\` commands.
+
+Use the \`bd\` CLI via bash for beads operations:
+
+- \`bd init [prefix]\` - Initialize beads
+- \`bd ready --json\` - List ready tasks
+- \`bd show <id> --json\` - Show task details
+- \`bd create "title" -t bug|feature|task -p 0-4 --json\` - Create issue
+- \`bd update <id> --status in_progress --json\` - Update status
+- \`bd close <id> --reason "message" --json\` - Close issue
+- \`bd reopen <id> --json\` - Reopen issue
+- \`bd dep add <from> <to> --type blocks|discovered-from --json\` - Add dependency
+- \`bd list --status open --json\` - List issues
+- \`bd blocked --json\` - Show blocked issues
+- \`bd stats --json\` - Show statistics
+- \`bd sync\` - Sync with git
+
+If a tool is not listed above, try \`bd <tool> --help\`.
+
+Always use \`--json\` flag for structured output.`;
+
+const BEADS_SUBAGENT_CONTEXT = `## Subagent Context
+
+You are called as a subagent. Your **final message** is what gets returned to the calling agent - make it count.
+
+**Your purpose:** Handle both status queries AND autonomous task completion.
+
+**For status/overview requests** ("what's next", "show me blocked work"):
+- Run the necessary \`bd\` commands to gather data
+- Process the JSON output internally
+- Return a **concise, human-readable summary** with key information
+- Use tables or lists to organize information clearly
+- Example: "You have 3 ready tasks (2 P0, 1 P1), 5 in-progress, and 8 blocked by Epic X"
+
+**For task completion requests** ("complete ready work", "work on issues"):
+- Find ready work, claim it, execute it, close it
+- Report progress as you work
+- End with a summary of what was accomplished
+
+**Critical:** Do NOT dump raw JSON in your final response. Parse it, summarize it, make it useful.`;
+
+export const BEADS_GUIDANCE = `<beads-guidance>
+${BEADS_CLI_USAGE}
+
+## Agent Delegation
+
+**Default to the agent.** For ANY beads work involving multiple commands or context gathering, use the \`task\` tool with \`subagent_type: "beads-task-agent"\`:
+- Status overviews ("what's next", "what's blocked", "show me progress")
+- Exploring the issue graph (ready + in-progress + blocked queries)
+- Finding and completing ready work
+- Working through multiple issues in sequence
+- Any request that would require 2+ bd commands
+
+**Use CLI directly ONLY for single, atomic operations:**
+- Creating exactly one issue: \`bd create "title" ...\`
+- Closing exactly one issue: \`bd close <id> ...\`
+- Updating one specific field: \`bd update <id> --status ...\`
+- When user explicitly requests a specific command
+
+**Why delegate?** The agent processes multiple commands internally and returns only a concise summary. Running bd commands directly dumps hundreds of lines of raw JSON into context, wasting tokens and making the conversation harder to follow.
+</beads-guidance>`;
 
 export async function loadAgent(): Promise<Config["agent"]> {
   const content = await readVendorFile("agents/task-agent.md");
@@ -118,7 +161,7 @@ export async function loadAgent(): Promise<Config["agent"]> {
   return {
     "beads-task-agent": {
       description,
-      prompt: CLI_GUIDANCE + "\n" + parsed.body,
+      prompt: BEADS_CLI_USAGE + "\n\n" + BEADS_SUBAGENT_CONTEXT + "\n\n" + parsed.body,
       mode: "subagent",
     },
   };