opencode-beads 0.1.0

package/vendor/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.

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)
+- **--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 `/bd-blocked` to investigate
+- No in-progress work? Run `/bd-ready` to find tasks
+- Many open issues? Consider prioritizing with `/bd-update`

package/vendor/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.

package/vendor/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

package/vendor/commands/update.md

@@ -0,0 +1,22 @@
+---
+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.
+
+Common workflows:
+- Start work: Update status to `in_progress`
+- Mark blocked: Update status to `blocked`
+- Reprioritize: Update priority (0-4)

package/vendor/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/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.

package/vendor/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 `/bd-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: `/bd-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: `/bd-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: `/bd-close <id> "Completed: <summary>"`
+- Via MCP tool: `close` with reason
+
+## 6. Check What's Unblocked
+After closing, check if other work became ready:
+- Use `/bd-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
+- `/bd-ready` - Find unblocked work
+- `/bd-create` - Create new issue
+- `/bd-show` - Show issue details
+- `/bd-update` - Update issue
+- `/bd-close` - Close issue
+- `/bd-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