opencode-beads 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-beads",
-  "version": "0.2.0",
+  "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/vendor.ts

@@ -84,8 +84,7 @@ async function listVendorFiles(relativePath: string): Promise<string[]> {
   }
 }
 
-export const BEADS_GUIDANCE = `<beads-guidance>
-## CLI Usage
+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.
 
@@ -106,17 +105,47 @@ Use the \`bd\` CLI via bash for beads operations:
 
 If a tool is not listed above, try \`bd <tool> --help\`.
 
-Always use \`--json\` flag for structured output.
+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
 
-For multi-step beads work, use the \`task\` tool with \`subagent_type: "beads-task-agent"\`:
-- Finding and completing ready work autonomously
+**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
-- Tasks involving claiming, executing, and closing issues
-- When asked to "work on beads issues", "complete tasks", or similar
+- 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
 
-For single, specific operations (check status, create one issue, query info), use \`bd\` CLI directly.
+**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"]> {
@@ -132,7 +161,7 @@ export async function loadAgent(): Promise<Config["agent"]> {
   return {
     "beads-task-agent": {
       description,
-      prompt: BEADS_GUIDANCE + "\n" + parsed.body,
+      prompt: BEADS_CLI_USAGE + "\n\n" + BEADS_SUBAGENT_CONTEXT + "\n\n" + parsed.body,
       mode: "subagent",
     },
   };