@snarkipus/opencode-beads 0.8.0

package/src/vendor.ts

@@ -0,0 +1,297 @@
+/**
+ * Vendor file loaders for beads plugin.
+ *
+ * The vendor directory contains beads command definitions and agent prompts
+ * synced from the upstream beads repository via scripts/sync-beads.sh.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentConfig, Config } from "@opencode-ai/sdk";
+import { adaptVendorPrompt } from "./vendor-adaptations";
+
+function getVendorDir(): string {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(__dirname, "..", "vendor");
+}
+
+async function getPackageIdentity(): Promise<string> {
+  const packagePath = path.join(getVendorDir(), "..", "package.json");
+  const value = JSON.parse(await fs.readFile(packagePath, "utf8")) as {
+    name?: unknown;
+    version?: unknown;
+  };
+  if (typeof value.name !== "string") {
+    throw new Error("Invalid package artifact package.json: name must be a string");
+  }
+  if (typeof value.version !== "string") {
+    throw new Error("Invalid package artifact package.json: version must be a string");
+  }
+  return `${value.name}@${value.version}`;
+}
+
+interface ParsedMarkdown {
+  frontmatter: Record<string, string>;
+  body: string;
+}
+
+const DOCUMENT_ONLY_COMMANDS = new Set(["commands/prime.md", "commands/template.md"]);
+const COMMAND_FRONTMATTER_FIELDS = new Set([
+  "agent",
+  "argument-hint",
+  "description",
+  "model",
+  "subtask",
+]);
+const AGENT_FRONTMATTER_FIELDS = new Set([
+  "color",
+  "description",
+  "disable",
+  "maxSteps",
+  "mode",
+  "model",
+  "temperature",
+  "top_p",
+]);
+
+function vendorError(relativePath: string, reason: string): Error {
+  return new Error(`Invalid vendor artifact ${relativePath}: ${reason}`);
+}
+
+function parseMarkdownWithFrontmatter(content: string, relativePath: string): ParsedMarkdown {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) throw vendorError(relativePath, "missing or malformed frontmatter delimiters");
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+
+  if (frontmatterStr === undefined || body === undefined) {
+    throw vendorError(relativePath, "missing frontmatter or body");
+  }
+
+  const frontmatter: Record<string, string> = {};
+
+  for (const line of frontmatterStr.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex <= 0) throw vendorError(relativePath, `malformed frontmatter line: ${trimmed}`);
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    let value = trimmed.slice(colonIndex + 1).trim();
+    if (Object.hasOwn(frontmatter, key)) {
+      throw vendorError(relativePath, `duplicate frontmatter field: ${key}`);
+    }
+
+    // Handle quoted strings
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    } else if (value.startsWith('"') || value.startsWith("'")) {
+      throw vendorError(relativePath, `unterminated quoted value for ${key}`);
+    }
+
+    // Handle empty array syntax like []
+    if (value === "[]") {
+      value = "";
+    }
+
+    frontmatter[key] = value;
+  }
+
+  const trimmedBody = body.trim();
+  if (!trimmedBody) throw vendorError(relativePath, "body must not be empty");
+  return { frontmatter, body: trimmedBody };
+}
+
+async function readVendorFile(vendorDirectory: string, relativePath: string): Promise<string> {
+  try {
+    const fullPath = path.join(vendorDirectory, relativePath);
+    return await fs.readFile(fullPath, "utf-8");
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw vendorError(relativePath, `cannot read file: ${reason}`);
+  }
+}
+
+async function manifestPaths(vendorDirectory: string): Promise<string[]> {
+  const content = await readVendorFile(vendorDirectory, "manifest.json");
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(content);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw vendorError("manifest.json", `invalid JSON: ${reason}`);
+  }
+
+  if (
+    typeof manifest !== "object" ||
+    manifest === null ||
+    !("files" in manifest) ||
+    !Array.isArray(manifest.files)
+  ) {
+    throw vendorError("manifest.json", "files must be an array");
+  }
+  const paths = manifest.files.map((file, index) => {
+    if (
+      typeof file !== "object" ||
+      file === null ||
+      !("path" in file) ||
+      typeof file.path !== "string"
+    ) {
+      throw vendorError("manifest.json", `files[${index}].path must be a string`);
+    }
+    return file.path;
+  });
+  if (new Set(paths).size !== paths.length) {
+    throw vendorError("manifest.json", "file paths must be unique");
+  }
+  return paths.sort();
+}
+
+function requiredString(
+  frontmatter: Record<string, string>,
+  field: string,
+  relativePath: string
+): string {
+  const value = frontmatter[field];
+  if (!value?.trim()) throw vendorError(relativePath, `${field} must be a non-empty string`);
+  return value;
+}
+
+function parseBoolean(value: string, field: string, relativePath: string): boolean {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw vendorError(relativePath, `${field} must be true or false`);
+}
+
+function parseNumber(value: string, field: string, relativePath: string): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw vendorError(relativePath, `${field} must be a number`);
+  return parsed;
+}
+
+function rejectUnsupportedFields(
+  frontmatter: Record<string, string>,
+  supported: ReadonlySet<string>,
+  relativePath: string
+): void {
+  const unsupported = Object.keys(frontmatter).find((field) => !supported.has(field));
+  if (unsupported) throw vendorError(relativePath, `unsupported frontmatter field: ${unsupported}`);
+}
+
+const BEADS_HOST_GUIDANCE = `## CLI Safety
+
+There is no native \`bd\` or Beads MCP tool in OpenCode. Run \`bd\` through \`bash\`.
+Treat the injected \`bd prime\` output as the canonical workflow reference. Use \`bd --help\` to discover commands, \`bd <command> --help\` for current syntax, and \`--json\` when structured output improves reliability. Distinguish command failures from output parsing failures.`;
+
+const BEADS_DELEGATION_GUIDANCE = `## Delegation
+
+Delegate multi-command Beads work and issue-graph analysis to the \`beads-task-agent\`; perform only single atomic operations directly.`;
+
+const BEADS_SUBAGENT_CONTEXT = `## Beads Task Agent
+
+Full \`bd prime\` workflow context is injected at start and after compaction. Use \`bd\` via \`bash\`; rerun prime if context is missing or stale.
+
+For status or graph analysis, never claim, update, close, or modify a bead. Return the analysis and stop.
+
+For completion, process exactly one bead. Use a caller-supplied ID; otherwise choose one highest-priority ready bead. First run \`bd show <id> --json\`; confirm it is open, actionable, and appropriate; then claim with \`bd update <id> --claim --json\`. If an assigned bead is closed, blocked, unsuitable, missing, or otherwise not actionable, report and return without mutation or substitution.
+
+Implement and validate it. Create discoveries with \`discovered-from:<current-id>\` and a parent only when structurally obvious. Never claim or implement work created this invocation; it may be eligible later. Close or block the current bead, report discoveries, and return without seeking more work. Return concise results, not raw JSON.`;
+
+/** Build the single shared guidance layer for one injected audience. */
+export function beadsGuidance(
+  audience: "primary" | "task-agent"
+): string {
+  const sections = [BEADS_HOST_GUIDANCE];
+  if (audience === "primary") sections.push(BEADS_DELEGATION_GUIDANCE);
+  return `<beads-guidance>\n${sections.join("\n\n")}\n</beads-guidance>`;
+}
+
+export async function loadAgent(vendorDirectory = getVendorDir()): Promise<Config["agent"]> {
+  const relativePath = "agents/task-agent.md";
+  const paths = await manifestPaths(vendorDirectory);
+  if (!paths.includes(relativePath)) {
+    throw vendorError("manifest.json", `missing required file record: ${relativePath}`);
+  }
+  const content = await readVendorFile(vendorDirectory, relativePath);
+  const parsed = parseMarkdownWithFrontmatter(content, relativePath);
+  const { frontmatter } = parsed;
+  rejectUnsupportedFields(frontmatter, AGENT_FRONTMATTER_FIELDS, relativePath);
+  if (frontmatter.mode !== undefined && frontmatter.mode !== "subagent") {
+    throw vendorError(relativePath, "mode must be subagent when provided");
+  }
+
+  const agent: AgentConfig = {
+    description: requiredString(frontmatter, "description", relativePath),
+    prompt: BEADS_SUBAGENT_CONTEXT,
+    mode: "subagent",
+  };
+  // Keep upstream adaptation validation as a publish-time compatibility gate.
+  adaptVendorPrompt(relativePath, parsed.body);
+  if (frontmatter.model) agent.model = frontmatter.model;
+  if (frontmatter.temperature) {
+    agent.temperature = parseNumber(frontmatter.temperature, "temperature", relativePath);
+  }
+  if (frontmatter.top_p) agent.top_p = parseNumber(frontmatter.top_p, "top_p", relativePath);
+  if (frontmatter.disable) {
+    agent.disable = parseBoolean(frontmatter.disable, "disable", relativePath);
+  }
+  if (frontmatter.color) agent.color = frontmatter.color;
+  if (frontmatter.maxSteps) {
+    agent.maxSteps = parseNumber(frontmatter.maxSteps, "maxSteps", relativePath);
+  }
+
+  return { "beads-task-agent": agent };
+}
+
+export async function loadCommands(vendorDirectory = getVendorDir()): Promise<Config["command"]> {
+  const paths = await manifestPaths(vendorDirectory);
+  const commandPaths = paths.filter((file) => file.startsWith("commands/") && file.endsWith(".md"));
+  if (commandPaths.length === 0) {
+    throw vendorError("manifest.json", "no command Markdown files are recorded");
+  }
+  const commands: Config["command"] = {};
+
+  for (const relativePath of commandPaths) {
+    const content = await readVendorFile(vendorDirectory, relativePath);
+    if (DOCUMENT_ONLY_COMMANDS.has(relativePath)) continue;
+    const parsed = parseMarkdownWithFrontmatter(content, relativePath);
+    const { frontmatter } = parsed;
+    rejectUnsupportedFields(frontmatter, COMMAND_FRONTMATTER_FIELDS, relativePath);
+    const file = path.basename(relativePath);
+    const name = `beads:${file.replace(".md", "")}`;
+
+    const argHint = frontmatter["argument-hint"];
+    const baseDescription = requiredString(frontmatter, "description", relativePath);
+    const description = argHint
+      ? `${baseDescription} (${argHint})`
+      : baseDescription;
+
+    const command: NonNullable<Config["command"]>[string] = {
+      description,
+      template: adaptVendorPrompt(relativePath, parsed.body),
+    };
+    if (frontmatter.agent) command.agent = frontmatter.agent;
+    if (frontmatter.model) command.model = frontmatter.model;
+    if (frontmatter.subtask) {
+      command.subtask = parseBoolean(frontmatter.subtask, "subtask", relativePath);
+    }
+    commands[name] = command;
+  }
+
+  const packageIdentity = await getPackageIdentity();
+  const cli = `bunx ${packageIdentity}`;
+  commands["beads:setup"] = {
+    description: "Install or manage the OpenCode Beads skill",
+    template: `The package CLI is canonical for the OpenCode Beads skill lifecycle. Use exact version-matched commands: \`${cli} init\`, \`${cli} init --global\`, \`${cli} check\`, \`${cli} update\`, and \`${cli} remove\`. Add \`--global\` to check, update, or remove for global scope. \`/beads:init\` is DB-only: it initializes a Beads database and does not install the skill.`,
+  };
+
+  return commands;
+}

package/vendor/agents/task-agent.md

@@ -0,0 +1,61 @@
+---
+description: Autonomous agent that finds and completes ready tasks
+---
+
+You are a task-completion agent for beads. Your goal is to find ready work and complete it autonomously.
+
+# Agent Workflow
+
+1. **Find Ready Work**
+   - Use the `ready` MCP tool to get unblocked tasks
+   - Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)
+   - If no ready tasks, report completion
+
+2. **Claim the Task**
+   - Use the `show` tool to get full task details
+   - Use the `claim` tool for atomic start-work semantics
+   - Report what you're working on
+
+3. **Execute the Task**
+   - Read the task description carefully
+   - Use available tools to complete the work
+   - Follow best practices from project documentation
+   - Run tests if applicable
+
+4. **Track Discoveries**
+   - If you find bugs, TODOs, or related work:
+     - Use `create` tool to file new issues
+     - Use `dep` tool with `discovered-from` to link them
+   - This maintains context for future work
+
+5. **Complete the Task**
+   - Verify the work is done correctly
+   - Use `close` tool with a clear completion message
+   - Report what was accomplished
+
+6. **Continue**
+   - Check for newly unblocked work with `ready`
+   - Repeat the cycle
+
+# Important Guidelines
+
+- Always claim before working (MCP: `claim`; CLI: `--claim`) and close when done
+- Link discovered work with `discovered-from` dependencies
+- Don't close issues unless work is actually complete
+- If blocked, use `update` to set status to `blocked` and explain why
+- Communicate clearly about progress and blockers
+
+# Available Tools
+
+Via beads MCP server:
+- `ready` - Find unblocked tasks
+- `show` - Get task details
+- `claim` - Atomically claim task for work
+- `update` - Update task status/fields
+- `create` - Create new issues
+- `dep` - Manage dependencies
+- `close` - Complete tasks
+- `blocked` - Check blocked issues
+- `stats` - View project stats
+
+You are autonomous but should communicate your progress clearly. Start by finding ready work!

package/vendor/commands/audit.md

@@ -0,0 +1,28 @@
+---
+description: Log and label agent interactions (append-only JSONL)
+argument-hint: record|label
+---
+
+Append-only audit logging for agent interactions (prompts, responses, tool calls) in `.beads/interactions.jsonl`.
+
+Each line is one event. Labeling is done by appending a new `"label"` event referencing a previous entry.
+
+## Usage
+
+- **Record an interaction**:
+  - `bd audit record --kind llm_call --model "claude-3-5-haiku" --prompt "..." --response "..."`
+  - `bd audit record --kind tool_call --tool-name "go test" --exit-code 1 --error "..." --issue-id bd-42`
+
+- **Pipe JSON via stdin**:
+  - `cat event.json | bd audit record`
+
+- **Label an entry**:
+  - `bd audit label int-a1b2 --label good --reason "Worked perfectly"`
+  - `bd audit label int-a1b2 --label bad --reason "Hallucinated a file path"`
+
+## Notes
+
+- Audit entries are **append-only** (no in-place edits).
+- `bd dolt push` includes `.beads/interactions.jsonl` in the commit allowlist.
+
+

package/vendor/commands/blocked.md

@@ -0,0 +1,15 @@
+---
+description: Show blocked issues
+argument-hint: []
+---
+
+Show all issues that are blocked by dependencies.
+
+Use `bd blocked` to see which issues have blockers preventing them from being worked on. This is the inverse of `bd ready` - it shows what's NOT ready.
+
+Blocked issues have one or more dependencies with type "blocks" that are still open. Once all blocking dependencies are closed, the issue becomes ready and will appear in `bd ready`.
+
+Useful for:
+- Understanding why work is stuck
+- Identifying critical path items
+- Planning dependency resolution

package/vendor/commands/close.md

@@ -0,0 +1,18 @@
+---
+description: Close a completed issue
+argument-hint: [issue-id] [reason]
+---
+
+Close a beads issue that's been completed.
+
+If arguments are provided:
+- $1: Issue ID
+- $2+: Completion reason (optional)
+
+If the issue ID is missing, ask for it. Optionally ask for a reason describing what was done.
+
+Use the beads MCP `close` tool to close the issue. Show confirmation with the issue details.
+
+After closing, suggest checking for:
+- Dependent issues that might now be unblocked (use `ready` tool)
+- New work discovered during this task (use `create` tool with `discovered-from` link)

package/vendor/commands/comments.md

@@ -0,0 +1,30 @@
+---
+description: View or manage comments on an issue
+argument-hint: [issue-id]
+---
+
+View or add comments to a beads issue.
+
+Comments are separate from issue properties (title, description, etc.) because they serve a different purpose: they're a **discussion thread** rather than **singular editable fields**. Use `bd comments` for threaded conversations and `bd edit` for core issue metadata.
+
+## View Comments
+
+To view all comments on an issue:
+- $1: Issue ID (e.g., bd-123)
+
+Use the beads CLI `bd comments <issue-id>` to list all comments. Show them to the user with timestamps and authors.
+
+## Add Comment
+
+To add a comment:
+- $1: "add"
+- $2: Issue ID
+- $3: Comment text (or use -f flag for file input)
+
+Use `bd comments add <issue-id> "comment text"` to add a comment. Confirm the comment was added successfully.
+
+Comments are useful for:
+- Progress updates during work
+- Design notes or technical decisions
+- Links to related resources
+- Questions or blockers

package/vendor/commands/compact.md

@@ -0,0 +1,31 @@
+---
+description: Compact old closed issues using semantic summarization
+argument-hint: [--all] [--id issue-id] [--dry-run]
+---
+
+Reduce database size by summarizing closed issues no longer actively referenced.
+
+## Compaction Tiers
+
+- **Tier 1**: Semantic compression (30+ days closed, ~70% size reduction)
+- **Tier 2**: Ultra compression (90+ days closed) — planned, not yet implemented
+
+## Usage
+
+- **Preview candidates**: `bd admin compact --dry-run`
+- **Compact all eligible**: `bd admin compact --all`
+- **Compact specific issue**: `bd admin compact --id bd-42`
+- **Force compact**: `bd admin compact --id bd-42 --force` (bypass age checks)
+- **View statistics**: `bd admin compact --stats`
+
+## Options
+
+- **--tier**: Choose compaction tier (1 or 2, default: 1)
+- **--workers**: Parallel workers (default: 5)
+- **--batch-size**: Issues per batch (default: 10)
+
+## Important
+
+This is **permanent graceful decay** - original content is discarded. Use `bd restore <id>` to view full history from git if needed.
+
+Useful for long-running projects to keep database size manageable.

package/vendor/commands/create.md

@@ -0,0 +1,19 @@
+---
+description: Create a new issue interactively
+argument-hint: [title] [type] [priority]
+---
+
+Create a new beads issue. If arguments are provided:
+- $1: Issue title
+- $2: Issue type (bug, feature, task, epic, chore, decision)
+- $3: Priority (0-4, where 0=critical, 4=backlog)
+
+If arguments are missing, ask the user for:
+1. Issue title (required)
+2. Issue type (default: task)
+3. Priority (default: 2)
+4. Description (optional)
+
+Use the beads MCP `create` tool to create the issue. Show the created issue ID and details to the user.
+
+Optionally ask if this issue should be linked to another issue (discovered-from, blocks, parent-child, related).

package/vendor/commands/decision.md

@@ -0,0 +1,111 @@
+---
+description: Record, list, and manage project decisions with rationale tracking
+argument-hint: record|list|show|supersede
+---
+
+Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.
+
+Decisions use `--type decision`. The description field holds the structured decision record.
+
+## Record a Decision
+
+When the user wants to record a decision (or you invoke `bd decision record`):
+
+1. Gather the following (ask if not provided):
+   - **Title**: Short summary of what was decided (required)
+   - **Rationale**: Why this was chosen (required)
+   - **Alternatives**: What else was considered (optional but encouraged)
+   - **Affects**: Issue IDs this decision impacts (optional)
+   - **Priority**: How important (default P2)
+
+2. Create the issue with structured description:
+
+```bash
+bd create "<title>" --type decision \
+  --description "$(cat <<'EOF'
+## Decision
+
+<one-sentence summary of what was decided>
+
+## Rationale
+
+<why this was chosen>
+
+## Alternatives Considered
+
+- **<alt 1>**: <why rejected>
+- **<alt 2>**: <why rejected>
+
+## Affects
+
+- <issue IDs or area descriptions>
+EOF
+)"
+```
+
+3. If `--affects` issue IDs were provided, link them:
+```bash
+bd dep add <decision-id> <affected-id> --type related
+```
+
+4. Show the created decision to the user.
+
+## List Decisions
+
+```bash
+bd list --type decision
+```
+
+To see all decisions including closed/superseded:
+```bash
+bd list --type decision --all
+```
+
+## Show a Decision
+
+```bash
+bd show <decision-id>
+```
+
+Include comments for discussion history:
+```bash
+bd comments <decision-id>
+```
+
+## Supersede a Decision
+
+When a decision is replaced by a new one:
+
+1. Record the new decision (as above)
+2. Link the new decision to the old one:
+   ```bash
+   bd dep add <new-id> <old-id> --type related
+   ```
+3. Add a comment on the old decision:
+   ```bash
+   bd comments add <old-id> "Superseded by <new-id>: <brief reason>"
+   ```
+4. Close the old decision:
+   ```bash
+   bd close <old-id> --reason "Superseded by <new-id>"
+   ```
+
+## Add Context to an Existing Decision
+
+Use comments to append discussion, implementation notes, or revisit rationale:
+```bash
+bd comments add <decision-id> "Implementation note: ..."
+```
+
+## Search Decisions
+
+```bash
+bd search "keyword" --type decision
+```
+
+## Conventions
+
+- **Status**: `open` = active decision, `closed` = superseded or reversed
+- **Description format**: Use the structured template above for consistency
+- **Linking**: Use `related` dependency type to connect decisions to affected issues
+- **Labels**: Use labels for categorizing decisions (e.g., `architecture`, `tooling`, `process`)

package/vendor/commands/delete.md

@@ -0,0 +1,32 @@
+---
+description: Delete issues and clean up references
+argument-hint: [issue-ids...] [--force]
+---
+
+Delete one or more issues and clean up all references.
+
+## Safety Features
+
+- **Preview mode**: Default shows what would be deleted
+- **--force**: Required to actually delete
+- **--dry-run**: Preview collision detection
+- **Dependency checks**: Fails if issue has dependents (unless --cascade or --force)
+
+## Batch Deletion
+
+- Delete multiple: `bd delete bd-1 bd-2 bd-3 --force`
+- Delete from file: `bd delete --from-file deletions.txt --force`
+
+## Dependency Handling
+
+- **Default**: Fails if issue has dependents not in deletion set
+- **--cascade**: Recursively delete all dependent issues
+- **--force**: Delete and orphan dependents
+
+## What Gets Deleted
+
+1. All dependency links (any type, both directions)
+2. Text references updated to "[deleted:ID]" in connected issues
+3. Issue removed from database
+
+This operation cannot be undone. Use with caution!