refactor: move Claude Code plugin to dedicated subdirectory (GH#985)

Move all plugin content to claude-plugin/ subdirectory for cleaner
separation from core beads functionality:

- claude-plugin/.claude-plugin/plugin.json - plugin manifest
- claude-plugin/commands/ - all slash commands
- claude-plugin/agents/ - task-agent (now in correct location)
- claude-plugin/skills/beads/ - beads skill with resources

Root .claude-plugin/ now only contains marketplace.json pointing
to ./claude-plugin.

Note: After updating, users may need to clear plugin cache:
  rm -rf ~/.claude/plugins/cache/beads-marketplace/

Fixes #985

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Executed-By: beads/crew/dave
Rig: beads
Role: crew

claude-plugin/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 sync` includes `.beads/interactions.jsonl` in the commit allowlist (like `issues.jsonl`).
+
+

claude-plugin/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

claude-plugin/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)

claude-plugin/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

claude-plugin/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, ~95% size reduction)
+
+## 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.

claude-plugin/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)
+- $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).

claude-plugin/commands/daemon.md

@@ -0,0 +1,58 @@
+---
+description: Manage background sync daemon
+argument-hint: [--start] [--stop] [--status] [--health]
+---
+
+Manage the per-project background daemon that handles database connections and syncs with git.
+
+## Per-Project Daemon (LSP Model)
+
+Each project runs its own daemon at `.beads/bd.sock` for complete database isolation.
+
+> On Windows this file stores the daemon's loopback TCP endpoint metadata—leave it in place so bd can reconnect.
+
+**Why per-project daemons?**
+- Complete database isolation between projects
+- No cross-project pollution or git worktree conflicts
+- Simpler mental model: one project = one database = one daemon
+- Follows LSP (Language Server Protocol) architecture
+
+**Note:** Global daemon support was removed in v0.16.0. The `--global` flag is no longer functional.
+
+## When to Use Daemon Mode
+
+**✅ You SHOULD use daemon mode if:**
+- Working in a team with git remote sync
+- Want automatic commit/push of issue changes
+- Need background auto-sync (5-second debounce)
+- Making frequent bd commands (performance benefit from connection pooling)
+
+**❌ You DON'T need daemon mode if:**
+- Solo developer with local-only tracking
+- Working in git worktrees (use --no-daemon to avoid conflicts)
+- Running one-off commands or scripts
+- Debugging database issues (direct mode is simpler)
+
+**Local-only users:** Direct mode (default without daemon) is perfectly fine. The daemon mainly helps with git sync automation. You can still use `bd sync` manually when needed.
+
+**Performance note:** For most operations, the daemon provides minimal performance benefit. The main value is automatic JSONL export (5s debounce) and optional git sync (--auto-commit, --auto-push).
+
+## Common Operations
+
+- **Start**: `bd daemon --start` (or auto-starts on first `bd` command)
+- **Stop**: `bd daemon --stop`
+- **Status**: `bd daemon --status`
+- **Health**: `bd daemon --health` - shows uptime, cache stats, performance metrics
+- **Metrics**: `bd daemon --metrics` - detailed operational telemetry
+
+## Sync Options
+
+- **--auto-commit**: Automatically commit JSONL changes
+- **--auto-push**: Automatically push commits to remote
+- **--interval**: Sync check interval (default: 5m)
+
+The daemon provides:
+- Connection pooling and caching
+- Better performance for frequent operations
+- Automatic JSONL sync (5-second debounce)
+- Optional git sync

claude-plugin/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

claude-plugin/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!

claude-plugin/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

claude-plugin/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.

claude-plugin/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

claude-plugin/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

claude-plugin/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.

claude-plugin/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.

claude-plugin/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

claude-plugin/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
+```

claude-plugin/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 [docs/QUICKSTART.md](../docs/QUICKSTART.md) instead.
+
+The quickstart documentation covers:
+- Getting started with bd
+- Common workflow patterns
+- Basic commands
+- Dependency management
+- Git integration

claude-plugin/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.

claude-plugin/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.

claude-plugin/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

claude-plugin/commands/restore.md

@@ -0,0 +1,28 @@
+---
+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. Checks out that commit temporarily
+3. Reads the full issue from JSONL at that point in history
+4. Displays the full issue history (description, events, etc.)
+5. Returns to the current git 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.

claude-plugin/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)
+- **--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)

claude-plugin/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.

claude-plugin/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`

claude-plugin/commands/sync.md

@@ -0,0 +1,54 @@
+---
+description: Synchronize issues with git remote
+argument-hint: [--dry-run] [--message] [--status] [--merge]
+---
+
+Synchronize issues with git remote in a single operation.
+
+## Sync Steps
+
+1. Export pending changes to JSONL
+2. Commit changes to git
+3. Pull from remote (with conflict resolution)
+4. Import updated JSONL
+5. Push local commits to remote
+
+Wraps the entire git-based sync workflow for multi-device use.
+
+## Usage
+
+- **Basic sync**: `bd sync`
+- **Preview**: `bd sync --dry-run`
+- **Custom message**: `bd sync --message "Closed sprint issues"`
+- **Pull only**: `bd sync --no-push`
+- **Push only**: `bd sync --no-pull`
+- **Flush only**: `bd sync --flush-only` (export to JSONL without git operations)
+- **Import only**: `bd sync --import-only` (import from JSONL without git operations)
+
+## Separate Branch Workflow
+
+When using a separate sync branch (configured via `sync.branch`), additional commands are available:
+
+- **Check status**: `bd sync --status` - Show diff between sync branch and main
+- **Merge to main**: `bd sync --merge` - Merge sync branch back to main branch
+- **Preview merge**: `bd sync --merge --dry-run` - Preview what would be merged
+
+### Merge Workflow
+
+When working with a protected main branch and separate sync branch:
+
+1. Beads commits go to the sync branch (e.g., `beads-metadata`)
+2. Use `bd sync --status` to review pending changes
+3. When ready, use `bd sync --merge` to merge back to main
+4. After merge, run `bd import` to update the database
+5. Run `bd sync` to push changes to remote
+
+The merge command includes safety checks:
+- Verifies you're not on the sync branch
+- Checks for uncommitted changes in working tree
+- Detects and reports merge conflicts with resolution steps
+- Uses `--no-ff` to create a merge commit for clear history
+
+## Note
+
+Most users should rely on the daemon's automatic sync (`bd daemon --auto-commit --auto-push`) instead of running manual sync. This command is useful for one-off syncs or when not using the daemon.

claude-plugin/commands/template.md

@@ -0,0 +1,337 @@
+# bd template
+
+Manage issue templates for streamlined issue creation.
+
+## Synopsis
+
+Templates provide pre-filled structures for common issue types, making it faster to create well-formed issues with consistent formatting.
+
+```bash
+bd template list
+bd template show <template-name>
+bd template create <template-name>
+```
+
+## Description
+
+Templates can be:
+- **Built-in**: Provided by bd (epic, bug, feature)
+- **Custom**: Stored in `.beads/templates/` directory
+
+Each template defines default values for:
+- Description structure with placeholders
+- Issue type (bug, feature, task, epic, chore)
+- Priority (0-4)
+- Labels
+- Design notes structure
+- Acceptance criteria structure
+
+## Commands
+
+### list
+
+List all available templates (built-in and custom).
+
+```bash
+bd template list
+bd template list --json
+```
+
+**Examples:**
+
+```bash
+$ bd template list
+Built-in Templates:
+  epic
+    Type: epic, Priority: P1
+    Labels: epic
+  bug
+    Type: bug, Priority: P1
+    Labels: bug
+  feature
+    Type: feature, Priority: P2
+    Labels: feature
+```
+
+### show
+
+Show detailed structure of a specific template.
+
+```bash
+bd template show <template-name>
+bd template show <template-name> --json
+```
+
+**Examples:**
+
+```bash
+$ bd template show bug
+Template: bug
+Type: bug
+Priority: P1
+Labels: bug
+
+Description:
+## Summary
+
+[Brief description of the bug]
+
+## Steps to Reproduce
+...
+```
+
+### create
+
+Create a custom template in `.beads/templates/` directory.
+
+```bash
+bd template create <template-name>
+```
+
+This creates a YAML file with default structure that you can edit to customize.
+
+**Examples:**
+
+```bash
+$ bd template create performance
+✓ Created template: .beads/templates/performance.yaml
+Edit the file to customize your template.
+
+$ cat .beads/templates/performance.yaml
+name: performance
+description: |-
+    [Describe the issue]
+    
+    ## Additional Context
+    
+    [Add relevant details]
+type: task
+priority: 2
+labels: []
+design: '[Design notes]'
+acceptance_criteria: |-
+    - [ ] Acceptance criterion 1
+    - [ ] Acceptance criterion 2
+
+# Edit the template to customize it
+$ vim .beads/templates/performance.yaml
+```
+
+## Using Templates with `bd create`
+
+Use the `--from-template` flag to create issues from templates:
+
+```bash
+bd create --from-template <template-name> "Issue title"
+```
+
+Template values can be overridden with explicit flags:
+
+```bash
+# Use bug template but override priority
+bd create --from-template bug "Login crashes on special chars" -p 0
+
+# Use epic template but add extra labels
+bd create --from-template epic "Q4 Infrastructure" -l infrastructure,ops
+```
+
+**Examples:**
+
+```bash
+# Create epic from template
+$ bd create --from-template epic "Phase 3 Features"
+✓ Created issue: bd-a3f8e9
+  Title: Phase 3 Features
+  Priority: P1
+  Status: open
+
+# Create bug report from template
+$ bd create --from-template bug "Auth token validation fails"
+✓ Created issue: bd-42bc7a
+  Title: Auth token validation fails
+  Priority: P1
+  Status: open
+
+# Use custom template
+$ bd template create security-audit
+$ bd create --from-template security-audit "Review authentication flow"
+```
+
+## Template File Format
+
+Templates are YAML files with the following structure:
+
+```yaml
+name: template-name
+description: |
+  Multi-line description with placeholders
+  
+  ## Section heading
+  
+  [Placeholder text]
+
+type: bug|feature|task|epic|chore
+priority: 0-4
+labels:
+  - label1
+  - label2
+
+design: |
+  Design notes structure
+
+acceptance_criteria: |
+  - [ ] Acceptance criterion 1
+  - [ ] Acceptance criterion 2
+```
+
+## Built-in Templates
+
+### epic
+
+For large features composed of multiple issues.
+
+**Structure:**
+- Overview and scope
+- Success criteria checklist
+- Background and motivation
+- In-scope / out-of-scope sections
+- Architecture design notes
+- Component breakdown
+
+**Defaults:**
+- Type: epic
+- Priority: P1
+- Labels: epic
+
+### bug
+
+For bug reports with consistent structure.
+
+**Structure:**
+- Summary
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details
+- Root cause analysis (design)
+- Proposed fix
+- Impact assessment
+
+**Defaults:**
+- Type: bug
+- Priority: P1
+- Labels: bug
+
+### feature
+
+For feature requests and enhancements.
+
+**Structure:**
+- Feature description
+- Motivation and use cases
+- Proposed solution
+- Alternatives considered
+- Technical design
+- API changes
+- Testing strategy
+
+**Defaults:**
+- Type: feature
+- Priority: P2
+- Labels: feature
+
+## Custom Templates
+
+Custom templates override built-in templates with the same name. This allows you to customize built-in templates for your project.
+
+**Priority:**
+1. Custom templates in `.beads/templates/`
+2. Built-in templates
+
+**Example - Override bug template:**
+
+```bash
+# Create custom bug template
+$ bd template create bug
+
+# Edit to add project-specific fields
+$ cat > .beads/templates/bug.yaml << 'EOF'
+name: bug
+description: |
+  ## Bug Report
+  
+  **Severity:** [critical|high|medium|low]
+  **Component:** [auth|api|frontend|backend]
+  
+  ## Description
+  [Describe the bug]
+  
+  ## Reproduction
+  1. Step 1
+  2. Step 2
+  
+  ## Impact
+  [Who is affected? How many users?]
+
+type: bug
+priority: 0
+labels:
+  - bug
+  - needs-triage
+
+design: |
+  ## Investigation Notes
+  [Technical details]
+
+acceptance_criteria: |
+  - [ ] Bug fixed and verified
+  - [ ] Tests added
+  - [ ] Monitoring added
+EOF
+
+# Now 'bd create --from-template bug' uses your custom template
+```
+
+## JSON Output
+
+All template commands support `--json` flag for programmatic use:
+
+```bash
+$ bd template list --json
+[
+  {
+    "name": "epic",
+    "description": "## Overview...",
+    "type": "epic",
+    "priority": 1,
+    "labels": ["epic"],
+    "design": "## Architecture...",
+    "acceptance_criteria": "- [ ] All child issues..."
+  }
+]
+
+$ bd template show bug --json
+{
+  "name": "bug",
+  "description": "## Summary...",
+  "type": "bug",
+  "priority": 1,
+  "labels": ["bug"],
+  "design": "## Root Cause...",
+  "acceptance_criteria": "- [ ] Bug no longer..."
+}
+```
+
+## Best Practices
+
+1. **Use templates for consistency**: Establish team conventions for common issue types
+2. **Customize built-ins**: Override built-in templates to match your workflow
+3. **Version control templates**: Commit `.beads/templates/` to share across team
+4. **Keep templates focused**: Create specific templates (e.g., `performance`, `security-audit`) rather than generic ones
+5. **Use placeholders**: Mark sections requiring input with `[brackets]` or `TODO`
+6. **Include checklists**: Use `- [ ]` for actionable items in description and acceptance criteria
+
+## See Also
+
+- [bd create](create.md) - Create issues
+- [bd list](list.md) - List issues
+- [README](../README.md) - Main documentation

claude-plugin/commands/update.md

@@ -0,0 +1,24 @@
+---
+description: Update an issue's status, priority, or other fields
+argument-hint: [issue-id] [status]
+---
+
+Update a beads issue.
+
+If arguments are provided:
+- $1: Issue ID
+- $2: New status (open, in_progress, blocked, closed)
+
+If arguments are missing, ask the user for:
+1. Issue ID
+2. What to update (status, priority, assignee, title, description)
+3. New value
+
+Use the beads MCP `update` tool to apply the changes. Show the updated issue to confirm the change.
+
+**Note:** Comments are managed separately with `bd comments add`. The `update` command is for singular, versioned properties (title, status, priority, etc.), while comments form a discussion thread that's appended to, not updated.
+
+Common workflows:
+- Start work: Update status to `in_progress`
+- Mark blocked: Update status to `blocked`
+- Reprioritize: Update priority (0-4)

claude-plugin/commands/version.md

@@ -0,0 +1,26 @@
+---
+description: Check beads and plugin versions
+---
+
+Check the installed versions of beads components and verify compatibility.
+
+**Note:** The MCP server automatically checks bd CLI version >= 0.9.0 on startup. This command provides detailed version info and update instructions.
+
+Use the beads MCP tools to:
+1. Run `bd version` via bash to get the CLI version
+2. Check the plugin version (0.9.2)
+3. Compare versions and report any mismatches
+
+Display:
+- bd CLI version (from `bd version`)
+- Plugin version (0.9.2)
+- MCP server version (0.9.2)
+- MCP server status (from `stats` tool or connection test)
+- Compatibility status (✓ compatible or ⚠️ update needed)
+
+If versions are mismatched, provide instructions:
+- Update bd CLI: `curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash`
+- Update plugin: `/plugin update beads`
+- Restart Claude Code after updating
+
+Suggest checking for updates if the user is on an older version.

claude-plugin/commands/workflow.md

@@ -0,0 +1,59 @@
+---
+description: Show the AI-supervised issue workflow guide
+---
+
+Display the beads workflow for AI agents and developers.
+
+# Beads Workflow
+
+Beads is an issue tracker designed for AI-supervised coding workflows. Here's how to use it effectively:
+
+## 1. Find Ready Work
+Use `/beads:ready` or the `ready` MCP tool to see tasks with no blockers.
+
+## 2. Claim Your Task
+Update the issue status to `in_progress`:
+- Via command: `/beads:update <id> in_progress`
+- Via MCP tool: `update` with `status: "in_progress"`
+
+## 3. Work on It
+Implement, test, and document the feature or fix.
+
+## 4. Discover New Work
+As you work, you'll often find bugs, TODOs, or related work:
+- Create issues: `/beads:create` or `create` MCP tool
+- Link them: Use `dep` MCP tool with `type: "discovered-from"`
+- This maintains context and work history
+
+## 5. Complete the Task
+Close the issue when done:
+- Via command: `/beads:close <id> "Completed: <summary>"`
+- Via MCP tool: `close` with reason
+
+## 6. Check What's Unblocked
+After closing, check if other work became ready:
+- Use `/beads:ready` to see newly unblocked tasks
+- Start the cycle again
+
+## Tips
+- **Priority levels**: 0=critical, 1=high, 2=medium, 3=low, 4=backlog
+- **Issue types**: bug, feature, task, epic, chore
+- **Dependencies**: Use `blocks` for hard dependencies, `related` for soft links
+- **Auto-sync**: Changes automatically export to `.beads/issues.jsonl` (5-second debounce)
+- **Git workflow**: After `git pull`, JSONL auto-imports if newer than DB
+
+## Available Commands
+- `/beads:ready` - Find unblocked work
+- `/beads:create` - Create new issue
+- `/beads:show` - Show issue details
+- `/beads:update` - Update issue
+- `/beads:close` - Close issue
+- `/beads:workflow` - Show this guide (you are here!)
+
+## MCP Tools Available
+Use these via the beads MCP server:
+- `ready`, `list`, `show`, `create`, `update`, `close`
+- `dep` (manage dependencies), `blocked`, `stats`
+- `init` (initialize bd in a project)
+
+For more details, see the beads README at: https://github.com/steveyegge/beads