opencode-beads 0.1.0

package/vendor/commands/daemons.md

@@ -0,0 +1,242 @@
+# bd daemons - Daemon Management
+
+Manage bd daemon processes across all repositories and worktrees.
+
+## Synopsis
+
+```bash
+bd daemons <subcommand> [flags]
+```
+
+## Description
+
+The `bd daemons` command provides tools for discovering, monitoring, and managing multiple bd daemon processes across your system. This is useful when working with multiple repositories or git worktrees.
+
+## Subcommands
+
+### list
+
+List all running bd daemons with metadata.
+
+```bash
+bd daemons list [--search DIRS] [--json] [--no-cleanup]
+```
+
+**Flags:**
+- `--search` - Directories to search for daemons (default: home, /tmp, cwd)
+- `--json` - Output in JSON format
+- `--no-cleanup` - Skip auto-cleanup of stale sockets
+
+**Example:**
+```bash
+bd daemons list
+bd daemons list --search /Users/me/projects --json
+```
+
+### health
+
+Check health of all bd daemons and report issues.
+
+```bash
+bd daemons health [--search DIRS] [--json]
+```
+
+Reports:
+- Stale sockets (dead processes)
+- Version mismatches between daemon and CLI
+- Unresponsive daemons
+
+**Flags:**
+- `--search` - Directories to search for daemons
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons health
+bd daemons health --json
+```
+
+### stop
+
+Stop a specific daemon gracefully.
+
+```bash
+bd daemons stop <workspace-path|pid> [--json]
+```
+
+**Arguments:**
+- `<workspace-path|pid>` - Workspace path or PID of daemon to stop
+
+**Flags:**
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons stop /Users/me/projects/myapp
+bd daemons stop 12345
+bd daemons stop /Users/me/projects/myapp --json
+```
+
+### restart
+
+Restart a specific daemon gracefully.
+
+```bash
+bd daemons restart <workspace-path|pid> [--search DIRS] [--json]
+```
+
+Stops the daemon gracefully, then starts a new one in its place. Useful after upgrading bd or when a daemon needs to be refreshed.
+
+**Arguments:**
+- `<workspace-path|pid>` - Workspace path or PID of daemon to restart
+
+**Flags:**
+- `--search` - Directories to search for daemons
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons restart /Users/me/projects/myapp
+bd daemons restart 12345
+bd daemons restart /Users/me/projects/myapp --json
+```
+
+### logs
+
+View logs for a specific daemon.
+
+```bash
+bd daemons logs <workspace-path|pid> [-f] [-n LINES] [--json]
+```
+
+**Arguments:**
+- `<workspace-path|pid>` - Workspace path or PID of daemon
+
+**Flags:**
+- `-f, --follow` - Follow log output (like tail -f)
+- `-n, --lines INT` - Number of lines to show from end (default: 50)
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons logs /Users/me/projects/myapp
+bd daemons logs 12345 -n 100
+bd daemons logs /Users/me/projects/myapp -f
+bd daemons logs 12345 --json
+```
+
+### killall
+
+Stop all running bd daemons.
+
+```bash
+bd daemons killall [--search DIRS] [--force] [--json]
+```
+
+Uses escalating shutdown strategy:
+1. RPC shutdown (2 second timeout)
+2. SIGTERM (3 second timeout)
+3. SIGKILL (1 second timeout)
+
+**Flags:**
+- `--search` - Directories to search for daemons
+- `--force` - Use SIGKILL immediately if graceful shutdown fails
+- `--json` - Output in JSON format
+
+**Example:**
+```bash
+bd daemons killall
+bd daemons killall --force
+bd daemons killall --json
+```
+
+## Common Use Cases
+
+### Version Upgrade
+
+After upgrading bd, restart all daemons to use the new version:
+
+```bash
+bd daemons health  # Check for version mismatches
+bd daemons killall # Stop all old daemons
+# Daemons will auto-start with new version on next bd command
+
+# Or restart a specific daemon
+bd daemons restart /path/to/workspace
+```
+
+### Debugging
+
+Check daemon status and view logs:
+
+```bash
+bd daemons list
+bd daemons health
+bd daemons logs /path/to/workspace -n 100
+```
+
+### Cleanup
+
+Remove stale daemon sockets:
+
+```bash
+bd daemons list  # Auto-cleanup happens by default
+bd daemons list --no-cleanup  # Skip cleanup
+```
+
+### Multi-Workspace Management
+
+Discover daemons in specific directories:
+
+```bash
+bd daemons list --search /Users/me/projects
+bd daemons health --search /Users/me/work
+```
+
+## Troubleshooting
+
+### Stale Sockets
+
+If you see stale sockets (dead process but socket file exists):
+
+```bash
+bd daemons list  # Auto-cleanup removes stale sockets
+```
+
+### Version Mismatch
+
+If daemon version != CLI version:
+
+```bash
+bd daemons health  # Identify mismatched daemons
+bd daemons killall # Stop all daemons
+# Next bd command will auto-start new version
+```
+
+### Daemon Won't Stop
+
+If graceful shutdown fails:
+
+```bash
+bd daemons killall --force  # Force kill with SIGKILL
+```
+
+### Can't Find Daemon
+
+If daemon isn't discovered:
+
+```bash
+bd daemons list --search /path/to/workspace
+```
+
+Or check the socket manually:
+
+```bash
+ls -la /path/to/workspace/.beads/bd.sock
+```
+
+## See Also
+
+- [bd daemon](daemon.md) - Start a daemon manually
+- [AGENTS.md](../AGENTS.md) - Agent workflow guide
+- [README.md](../README.md) - Main documentation

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!

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 blocks bd-20
+- `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,26 @@
+---
+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-10 bd-20 --type parent-child` (epic bd-10 is parent of task bd-20)
+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,24 @@
+---
+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.
+
+## Automatic Export
+
+The daemon automatically exports to `.beads/issues.jsonl` after any CRUD operation (5-second debounce). Manual export is rarely needed unless you need a custom output location or filtered export.
+
+Export is used for:
+- Git version control
+- Backup
+- Sharing issues between repositories
+- Data migration

package/vendor/commands/import.md

@@ -0,0 +1,36 @@
+---
+description: Import issues from JSONL format
+argument-hint: [-i input-file]
+---
+
+Import issues from JSON Lines format (one JSON object per line).
+
+## Usage
+
+- **From stdin**: `bd import` (reads from stdin)
+- **From file**: `bd import -i issues.jsonl`
+- **Preview**: `bd import -i issues.jsonl --dry-run`
+
+## Behavior
+
+- **Existing issues** (same ID): Updated with new data
+- **New issues**: Created
+- **Same-ID scenarios**: With hash-based IDs (v0.20.1+), same ID = same issue being updated (not a collision)
+
+## Preview Changes
+
+Use `--dry-run` to see what will change before importing:
+
+```bash
+bd import -i issues.jsonl --dry-run
+# Shows: new issues, updates, exact matches
+```
+
+## Automatic Import
+
+The daemon automatically imports from `.beads/issues.jsonl` when it's newer than the database (e.g., after `git pull`). Manual import is rarely needed.
+
+## Options
+
+- **--skip-existing**: Skip updates to existing issues
+- **--strict**: Fail on dependency errors instead of warnings

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 `/bd-workflow`)
+4. Suggest creating the first issue with `/bd-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)
+- **--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,7 @@
+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
+```

package/vendor/commands/quickstart.md

@@ -0,0 +1,17 @@
+---
+description: Quick start guide for bd workflows
+argument-hint: []
+---
+
+Display a quick start guide showing common bd workflows and patterns.
+
+Use `bd quickstart` to see:
+- Getting started with bd
+- Common workflow patterns
+- Basic commands
+- Dependency management
+- Git integration
+
+This is an interactive tutorial that walks through the essential bd commands and concepts for new users.
+
+No arguments needed - just run `bd quickstart` to see the full guide.

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 `update` tool to set its status to `in_progress`.
+
+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