@snarkipus/opencode-beads 0.8.0

package/vendor/commands/dep.md

@@ -0,0 +1,101 @@
+---
+description: Manage dependencies between issues
+argument-hint: [command] [from-id] [to-id]
+---
+
+Manage dependencies between beads issues.
+
+## Available Commands
+
+- **add**: Add a dependency between issues
+  - $1: "add"
+  - $2: From issue ID
+  - $3: To issue ID
+  - $4: Dependency type (blocks, related, parent-child, discovered-from)
+
+- **remove**: Remove a dependency
+  - $1: "remove"
+  - $2: From issue ID
+  - $3: To issue ID
+
+- **tree**: Show dependency tree for an issue
+  - $1: "tree"
+  - $2: Issue ID
+  - Flags:
+    - `--reverse`: Show dependent tree (what was discovered from this) instead of dependency tree (what blocks this)
+    - `--format mermaid`: Output as Mermaid.js flowchart (renders in GitHub/GitLab markdown)
+    - `--json`: Output as JSON
+    - `--max-depth N`: Limit tree depth (default: 50)
+    - `--show-all-paths`: Show all paths (no deduplication for diamond dependencies)
+
+- **cycles**: Detect dependency cycles
+
+## Dependency Types
+
+- **blocks**: Hard blocker (from blocks to) - affects ready queue
+- **related**: Soft relationship - for context only
+- **parent-child**: Epic/subtask relationship
+- **discovered-from**: Track issues found during work
+
+## Mermaid Format
+
+The `--format mermaid` option outputs the dependency tree as a Mermaid.js flowchart:
+
+**Example:**
+```bash
+bd dep tree bd-1 --format mermaid
+```
+
+Output can be embedded in markdown:
+
+````markdown
+```mermaid
+flowchart TD
+  bd-1["◧ bd-1: Main task"]
+  bd-2["☑ bd-2: Subtask"]
+
+  bd-1 --> bd-2
+```
+````
+
+**Status Indicators:**
+
+Each node includes a symbol indicator for quick visual status identification:
+
+- ☐ **Open** - Not started yet (empty checkbox)
+- ◧ **In Progress** - Currently being worked on (half-filled box)
+- ⚠ **Blocked** - Waiting on something (warning sign)
+- ☑ **Closed** - Completed! (checked checkbox)
+
+The diagram colors are determined by your Mermaid theme (default, dark, forest, neutral, or base). Mermaid diagrams render natively in GitHub, GitLab, VSCode markdown preview, and can be imported to Miro.
+
+## Examples
+
+- `bd dep add bd-10 bd-20 --type blocks`: bd-10 depends on bd-20 (bd-20 blocks bd-10)
+- `bd dep tree bd-20`: Show what blocks bd-20 (dependency tree going UP)
+- `bd dep tree bd-1 --reverse`: Show what was discovered from bd-1 (dependent tree going DOWN)
+- `bd dep tree bd-1 --reverse --max-depth 3`: Show discovery tree with depth limit
+- `bd dep tree bd-20 --format mermaid > tree.md`: Generate Mermaid diagram for documentation
+- `bd dep cycles`: Check for circular dependencies
+
+## Reverse Mode: Discovery Trees
+
+The `--reverse` flag inverts the tree direction to show **dependents** instead of **dependencies**:
+
+**Normal mode** (`bd dep tree ISSUE`):
+- Shows what blocks you (dependency tree)
+- Answers: "What must I complete before I can work on this?"
+- Tree flows **UP** toward prerequisites
+
+**Reverse mode** (`bd dep tree ISSUE --reverse`):
+- Shows what was discovered from you (dependent tree)
+- Answers: "What work was discovered while working on this?"
+- Tree flows **DOWN** from goal to discovered tasks
+- Perfect for visualizing work breakdown and discovery chains
+
+**Use Cases:**
+- Document project evolution and how work expanded from initial goal
+- Share "how we got here" context with stakeholders
+- Visualize work breakdown structure from epics
+- Track discovery chains (what led to what)
+- Show yak shaving journeys in retrospectives

package/vendor/commands/epic.md

@@ -0,0 +1,27 @@
+---
+description: Epic management commands
+argument-hint: [command]
+---
+
+Manage epics (large features composed of multiple issues).
+
+## Available Commands
+
+- **status**: Show epic completion status
+  - Shows progress for each epic
+  - Lists child issues and their states
+  - Calculates completion percentage
+
+- **close-eligible**: Close epics where all children are complete
+  - Automatically closes epics when all child issues are done
+  - Useful for bulk epic cleanup
+
+## Epic Workflow
+
+1. Create epic: `bd create "Large Feature" -t epic -p 1`
+2. Link subtasks: `bd dep add bd-20 bd-10 --type parent-child` (task bd-20 is child of epic bd-10)
+   - Or at creation: `bd create "Subtask title" -t task --parent bd-10`
+3. Track progress: `bd epic status`
+4. Auto-close when done: `bd epic close-eligible`
+
+Epics use parent-child dependencies to track subtasks.

package/vendor/commands/export.md

@@ -0,0 +1,25 @@
+---
+description: Export issues to JSONL format
+argument-hint: [-o output-file]
+---
+
+Export all issues to JSON Lines format (one JSON object per line).
+
+## Usage
+
+- **To stdout**: `bd export`
+- **To file**: `bd export -o issues.jsonl`
+- **Filter by status**: `bd export --status open`
+
+Issues are sorted by ID for consistent diffs, making git diffs readable.
+
+## When to Use
+
+Dolt is the primary storage backend, so manual export is rarely needed. Use `bd export` when you need:
+- A JSONL snapshot of issue records
+- Data migration to another system
+- Sharing issues outside the Dolt workflow
+
+`bd export` is not a full database backup. It does not capture Dolt branches,
+commit history, working-set state, or non-issue tables. Use `bd backup` for a
+restorable Dolt-native database backup.

package/vendor/commands/import.md

@@ -0,0 +1,18 @@
+---
+description: Import issues from JSONL format (removed)
+argument-hint: (removed)
+---
+
+`bd import` has been **removed**.
+
+## Migration
+
+If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag:
+
+```bash
+bd init <prefix> --from-jsonl issues.jsonl
+```
+
+## Note
+
+Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command.

package/vendor/commands/init.md

@@ -0,0 +1,18 @@
+---
+description: Initialize beads in the current project
+argument-hint: [prefix]
+---
+
+Initialize beads issue tracking in the current directory.
+
+If a prefix is provided as $1, use it as the issue prefix (e.g., "myproject" creates issues like myproject-1, myproject-2). If not provided, the default is the current directory name.
+
+Use the beads MCP `init` tool with the prefix parameter (if provided) to set up a new beads database.
+
+After initialization:
+1. Show the database location
+2. Show the issue prefix that will be used
+3. Explain the basic workflow (or suggest running `/beads:workflow`)
+4. Suggest creating the first issue with `/beads:create`
+
+If beads is already initialized, inform the user and show project stats using the `stats` tool.

package/vendor/commands/label.md

@@ -0,0 +1,33 @@
+---
+description: Manage issue labels
+argument-hint: [command] [issue-id] [label]
+---
+
+Manage labels on beads issues. Labels provide flexible cross-cutting metadata beyond structured fields (status, priority, type).
+
+## Available Commands
+
+- **add**: Add a label to an issue
+  - $1: "add"
+  - $2: Issue ID
+  - $3: Label name
+
+- **remove**: Remove a label from an issue
+  - $1: "remove"
+  - $2: Issue ID
+  - $3: Label name
+
+- **list**: List labels on a specific issue
+  - $1: "list"
+  - $2: Issue ID
+
+- **list-all**: Show all labels used across all issues
+
+## Common Label Use Cases
+
+- Technical scope: `backend`, `frontend`, `api`, `database`
+- Quality gates: `needs-review`, `needs-tests`, `security-review`
+- Effort sizing: `quick-win`, `complex`, `spike`
+- Context: `technical-debt`, `documentation`, `performance`
+
+Use `bd label add <issue-id> <label>` to tag issues with contextual metadata.

package/vendor/commands/list.md

@@ -0,0 +1,64 @@
+---
+description: List issues with optional filters
+argument-hint: [--status] [--priority] [--type] [--assignee] [--label]
+---
+
+List beads issues with optional filtering.
+
+## Basic Filters
+
+- **--status, -s**: Filter by status (open, in_progress, blocked, closed)
+- **--priority, -p**: Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)
+- **--type, -t**: Filter by type (bug, feature, task, epic, chore, decision)
+- **--assignee, -a**: Filter by assignee
+- **--label, -l**: Filter by labels (comma-separated, must have ALL labels)
+- **--label-any**: Filter by labels (OR semantics, must have AT LEAST ONE)
+- **--title**: Filter by title text (case-insensitive substring match)
+- **--limit, -n**: Limit number of results
+
+## Advanced Filters
+
+### Pattern Matching
+- **--title-contains**: Search for text in title (case-insensitive)
+- **--desc-contains**: Search for text in description (case-insensitive)
+- **--notes-contains**: Search for text in notes (case-insensitive)
+
+### Date Ranges
+- **--created-after**: Issues created after date (YYYY-MM-DD or ISO 8601)
+- **--created-before**: Issues created before date
+- **--updated-after**: Issues updated after date
+- **--updated-before**: Issues updated before date
+- **--closed-after**: Issues closed after date
+- **--closed-before**: Issues closed before date
+
+### Priority Range
+- **--priority-min**: Minimum priority (inclusive)
+- **--priority-max**: Maximum priority (inclusive)
+
+### Empty/Null Checks
+- **--empty-description**: Find issues with no description
+- **--no-assignee**: Find unassigned issues
+- **--no-labels**: Find issues with no labels
+
+## Examples
+
+### Basic Usage
+- `bd list --status open --priority 1`: High priority open issues
+- `bd list --type bug --assignee alice`: Alice's assigned bugs
+- `bd list --label backend,needs-review`: Backend issues needing review
+- `bd list --title "auth"`: Issues with "auth" in the title
+
+### Advanced Usage
+- `bd list --title-contains "auth" --status open`: Search open issues for auth-related work
+- `bd list --priority-min 0 --priority-max 1`: Critical and high priority issues only
+- `bd list --created-after 2025-01-01 --status open`: Recent open issues
+- `bd list --empty-description --status open`: Open issues missing descriptions
+- `bd list --no-assignee --priority 1`: High priority unassigned work
+- `bd list --desc-contains "TODO" --notes-contains "review"`: Find items needing attention
+
+## Output Formats
+
+- Default: Human-readable table
+- `--json`: JSON format for scripting
+- `--format digraph`: Graph format for golang.org/x/tools/cmd/digraph
+- `--format dot`: Graphviz DOT format

package/vendor/commands/prime.md

@@ -0,0 +1,10 @@
+Load AI-optimized workflow context for beads issue tracking.
+
+Outputs essential beads workflow rules and command reference to help agents remember to use bd instead of markdown TODOs after context compaction.
+
+```bash
+bd prime
+bd prime --memories-only
+```
+
+Use `--memories-only` when a hook should inject durable project memories without the full workflow guide.

package/vendor/commands/quickstart.md

@@ -0,0 +1,13 @@
+---
+description: Quick start guide for bd workflows (deprecated)
+argument-hint: []
+---
+
+**Note:** The `bd quickstart` command is deprecated. See the [Quick Start](https://gastownhall.github.io/beads/getting-started/quickstart) on the documentation site, or the repo pointer [docs/QUICKSTART.md](../docs/QUICKSTART.md).
+
+The quickstart documentation covers:
+- Getting started with bd
+- Common workflow patterns
+- Basic commands
+- Dependency management
+- Git integration

package/vendor/commands/ready.md

@@ -0,0 +1,15 @@
+---
+description: Find ready-to-work tasks with no blockers
+---
+
+Use the beads MCP server to find tasks that are ready to work on (no blocking dependencies).
+
+Call the `ready` tool to get a list of unblocked issues. Then present them to the user in a clear format showing:
+- Issue ID
+- Title
+- Priority
+- Issue type
+
+If there are ready tasks, ask the user which one they'd like to work on. If they choose one, use the `claim` tool to start work atomically.
+
+If there are no ready tasks, suggest checking `blocked` issues or creating a new issue with the `create` tool.

package/vendor/commands/rename-prefix.md

@@ -0,0 +1,24 @@
+---
+description: Rename the issue prefix for all issues
+argument-hint: <new-prefix> [--dry-run]
+---
+
+Rename the issue prefix for all issues in the database.
+
+Updates all issue IDs and all text references across all fields.
+
+## Prefix Rules
+
+- Max length: 8 characters
+- Allowed: lowercase letters, numbers, hyphens
+- Must start with a letter
+- Must end with a hyphen (e.g., 'kw-', 'work-')
+
+## Usage
+
+- **Preview**: `bd rename-prefix kw- --dry-run`
+- **Apply**: `bd rename-prefix kw-`
+
+Example: Rename from 'knowledge-work-' to 'kw-'
+
+All dependencies and text references are automatically updated.

package/vendor/commands/reopen.md

@@ -0,0 +1,22 @@
+---
+description: Reopen closed issues
+argument-hint: [issue-ids...] [--reason]
+---
+
+Reopen one or more closed issues.
+
+Sets status to 'open' and clears the closed_at timestamp. Emits a Reopened event.
+
+## Usage
+
+- **Reopen single**: `bd reopen bd-42`
+- **Reopen multiple**: `bd reopen bd-42 bd-43 bd-44`
+- **With reason**: `bd reopen bd-42 --reason "Found regression"`
+
+More explicit than `bd update --status open` - specifically designed for reopening workflow.
+
+Common reasons for reopening:
+- Regression found
+- Requirements changed
+- Incomplete implementation
+- New information discovered

package/vendor/commands/restore.md

@@ -0,0 +1,27 @@
+---
+description: Restore full history of compacted issue from git
+argument-hint: <issue-id>
+---
+
+Restore full history of a compacted issue from git version control.
+
+When an issue is compacted, the git commit hash is saved. This command:
+
+1. Reads the compacted_at_commit from the database
+2. Retrieves the full issue from Dolt history at that point
+3. Displays the full issue history (description, events, etc.)
+4. Returns to the current state
+
+## Usage
+
+`bd restore bd-42`
+
+This is **read-only** - it does not modify the database or git state.
+
+Useful for:
+- Reviewing old issues after compaction
+- Recovering forgotten context
+- Audit trails
+- Historical research
+
+Requires git repository with issue history.

package/vendor/commands/search.md

@@ -0,0 +1,103 @@
+---
+description: Search issues by text query
+argument-hint: <query> [--status] [--label] [--assignee]
+---
+
+Search issues across title, description, and ID with a simple text query.
+
+**Note:** The `search` command is optimized for quick text searches and uses less context than `list` when accessed via MCP. For advanced filtering options, use `bd list`.
+
+## Basic Usage
+
+```bash
+bd search "authentication bug"
+bd search login --status open
+bd search database --label backend
+bd search "bd-5q"  # Search by partial issue ID
+```
+
+## How It Works
+
+The search command finds issues where your query appears in **any** of:
+- Issue title
+- Issue description
+- Issue ID (supports partial matching)
+
+Unlike `bd list`, which requires you to specify which field to search, `bd search` automatically searches all text fields, making it faster and more intuitive for exploratory searches.
+
+## Filters
+
+- **--status, -s**: Filter by status (open, in_progress, blocked, closed)
+- **--assignee, -a**: Filter by assignee
+- **--type, -t**: Filter by type (bug, feature, task, epic, chore, decision)
+- **--label, -l**: Filter by labels (must have ALL specified labels)
+- **--label-any**: Filter by labels (must have AT LEAST ONE)
+- **--limit, -n**: Limit number of results (default: 50)
+- **--sort**: Sort by field: priority, created, updated, closed, status, id, title, type, assignee
+- **--reverse, -r**: Reverse sort order
+- **--long**: Show detailed multi-line output for each issue
+- **--json**: Output results in JSON format
+
+## Examples
+
+### Basic Search
+```bash
+# Find all issues mentioning "auth" or "authentication"
+bd search auth
+
+# Search for performance issues
+bd search performance --status open
+
+# Find database-related bugs
+bd search database --type bug
+```
+
+### Filtered Search
+```bash
+# Find open backend issues about login
+bd search login --status open --label backend
+
+# Search Alice's tasks for "refactor"
+bd search refactor --assignee alice --type task
+
+# Find recent bugs (limited to 10 results)
+bd search bug --status open --limit 10
+```
+
+### Sorted Output
+```bash
+# Search bugs sorted by priority (P0 first)
+bd search bug --sort priority
+
+# Search features sorted by most recently updated
+bd search feature --sort updated
+
+# Search issues sorted by priority, lowest first
+bd search refactor --sort priority --reverse
+```
+
+### JSON Output
+```bash
+# Get JSON results for programmatic use
+bd search "api error" --json
+
+# Use with jq for advanced filtering
+bd search memory --json | jq '.[] | select(.priority <= 1)'
+```
+
+## Comparison with bd list
+
+| Command | Best For | Default Limit | Context Usage |
+|---------|----------|---------------|---------------|
+| `bd search` | Quick text searches, exploratory queries | 50 | Low (efficient for LLMs) |
+| `bd list` | Advanced filtering, precise queries | None | High (all results) |
+
+**When to use `bd search`:**
+- You want to find issues quickly by keyword
+- You're exploring the issue database
+- You're using an LLM/MCP and want to minimize context usage
+
+**When to use `bd list`:**
+- You need advanced filters (date ranges, priority ranges, etc.)
+- You want all results without a limit
+- You need special output formats (digraph, dot)

package/vendor/commands/show.md

@@ -0,0 +1,17 @@
+---
+description: Show detailed information about an issue
+argument-hint: [issue-id]
+---
+
+Display detailed information about a beads issue.
+
+If an issue ID is provided as $1, use it. Otherwise, ask the user for the issue ID.
+
+Use the beads MCP `show` tool to retrieve issue details and present them clearly, including:
+- Issue ID, title, and description
+- Status, priority, and type
+- Creation and update timestamps
+- Dependencies (what this issue blocks or is blocked by)
+- Related issues
+
+If the issue has dependencies, offer to show the full dependency tree.

package/vendor/commands/stats.md

@@ -0,0 +1,17 @@
+---
+description: Show project statistics and progress
+---
+
+Display statistics about the current beads project.
+
+Use the beads MCP `stats` tool to retrieve project metrics and present them clearly:
+- Total issues by status (open, in_progress, blocked, closed)
+- Issues by priority level
+- Issues by type (bug, feature, task, epic, chore)
+- Completion rate
+- Recently updated issues
+
+Optionally suggest actions based on the stats:
+- High number of blocked issues? Run `/beads:blocked` to investigate
+- No in_progress work? Run `/beads:ready` to find tasks
+- Many open issues? Consider prioritizing with `/beads:update`

package/vendor/commands/sync.md

@@ -0,0 +1,17 @@
+---
+description: Synchronize issues (deprecated — use bd dolt push/pull)
+argument-hint: (deprecated)
+---
+
+`bd sync` is **deprecated** and is now a no-op.
+
+## Use Dolt commands instead
+
+- **Push to remote**: `bd dolt push`
+- **Pull from remote**: `bd dolt pull`
+- **Commit pending changes**: `bd dolt commit`
+- **Check connection**: `bd dolt show`
+
+## Note
+
+Most users should rely on the Dolt server's automatic sync (with `dolt.auto-commit` enabled) instead of running manual sync commands.