Add Claude Code skill for beads usage
- Provides comprehensive workflow patterns and decision criteria - Includes quick reference (SKILL.md) and detailed references - Teaches when to use bd vs markdown/TodoWrite - Covers dependency types and issue lifecycle management - Complements existing plugin with usage philosophy
This commit is contained in:
spm1001
365
examples/claude-code-skill/references/CLI_REFERENCE.md
Normal file
365
examples/claude-code-skill/references/CLI_REFERENCE.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# CLI Reference
|
||||
|
||||
Complete command reference for bd (beads) CLI tool. All commands support `--json` flag for structured output.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Quick Reference](#quick-reference)
|
||||
- [Global Flags](#global-flags)
|
||||
- [Core Commands](#core-commands)
|
||||
- [bd ready](#bd-ready) - Find unblocked work
|
||||
- [bd create](#bd-create) - Create new issues
|
||||
- [bd update](#bd-update) - Update issue status, priority, assignee
|
||||
- [bd close](#bd-close) - Close completed work
|
||||
- [bd show](#bd-show) - Show issue details
|
||||
- [bd list](#bd-list) - List issues with filters
|
||||
- [Dependency Commands](#dependency-commands)
|
||||
- [bd dep add](#bd-dep-add) - Create dependencies
|
||||
- [bd dep tree](#bd-dep-tree) - Visualize dependency trees
|
||||
- [bd dep cycles](#bd-dep-cycles) - Detect circular dependencies
|
||||
- [Monitoring Commands](#monitoring-commands)
|
||||
- [bd stats](#bd-stats) - Project statistics
|
||||
- [bd blocked](#bd-blocked) - Find blocked work
|
||||
- [Setup Commands](#setup-commands)
|
||||
- [bd init](#bd-init) - Initialize database
|
||||
- [bd quickstart](#bd-quickstart) - Show quick start guide
|
||||
- [Common Workflows](#common-workflows)
|
||||
- [JSON Output](#json-output)
|
||||
- [Database Auto-Discovery](#database-auto-discovery)
|
||||
- [Git Integration](#git-integration)
|
||||
- [Tips](#tips)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Purpose | Key Flags |
|
||||
|---------|---------|-----------|
|
||||
| `bd ready` | Find unblocked work | `--priority`, `--assignee`, `--limit`, `--json` |
|
||||
| `bd list` | List all issues with filters | `--status`, `--priority`, `--type`, `--assignee` |
|
||||
| `bd show` | Show issue details | `--json` |
|
||||
| `bd create` | Create new issue | `-t`, `-p`, `-d`, `--design`, `--acceptance` |
|
||||
| `bd update` | Update existing issue | `--status`, `--priority`, `--design` |
|
||||
| `bd close` | Close completed issue | `--reason` |
|
||||
| `bd dep add` | Add dependency | `--type` (blocks, related, parent-child, discovered-from) |
|
||||
| `bd dep tree` | Visualize dependency tree | (no flags) |
|
||||
| `bd dep cycles` | Detect circular dependencies | (no flags) |
|
||||
| `bd stats` | Get project statistics | `--json` |
|
||||
| `bd blocked` | Find blocked issues | `--json` |
|
||||
| `bd init` | Initialize bd in directory | `--prefix` |
|
||||
| `bd quickstart` | Show quick start guide | (no flags) |
|
||||
|
||||
## Global Flags
|
||||
|
||||
Available for all commands:
|
||||
|
||||
```bash
|
||||
--json # Output in JSON format
|
||||
--db /path/to/db # Specify database path (default: auto-discover)
|
||||
--actor "name" # Actor name for audit trail
|
||||
--no-auto-flush # Disable automatic JSONL sync
|
||||
--no-auto-import # Disable automatic JSONL import
|
||||
```
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bd ready
|
||||
|
||||
Find tasks with no blockers - ready to be worked on.
|
||||
|
||||
```bash
|
||||
bd ready # All ready work
|
||||
bd ready --json # JSON format
|
||||
bd ready --priority 0 # Only priority 0 (critical)
|
||||
bd ready --assignee alice # Only assigned to alice
|
||||
bd ready --limit 5 # Limit to 5 results
|
||||
```
|
||||
|
||||
**Use at session start** to see available work.
|
||||
|
||||
---
|
||||
|
||||
### bd create
|
||||
|
||||
Create a new issue with optional metadata.
|
||||
|
||||
```bash
|
||||
bd create "Title"
|
||||
bd create "Title" -t bug -p 0
|
||||
bd create "Title" -d "Description"
|
||||
bd create "Title" --design "Design notes"
|
||||
bd create "Title" --acceptance "Definition of done"
|
||||
bd create "Title" --assignee alice
|
||||
```
|
||||
|
||||
**Flags**:
|
||||
- `-t, --type`: task (default), bug, feature, epic, chore
|
||||
- `-p, --priority`: 0-3 (default: 2)
|
||||
- `-d, --description`: Issue description
|
||||
- `--design`: Design notes
|
||||
- `--acceptance`: Acceptance criteria
|
||||
- `--assignee`: Who should work on this
|
||||
|
||||
---
|
||||
|
||||
### bd update
|
||||
|
||||
Update an existing issue's metadata.
|
||||
|
||||
```bash
|
||||
bd update issue-123 --status in_progress
|
||||
bd update issue-123 --priority 0
|
||||
bd update issue-123 --design "Decided to use Redis"
|
||||
bd update issue-123 --acceptance "Tests passing"
|
||||
```
|
||||
|
||||
**Status values**: open, in_progress, blocked, closed
|
||||
|
||||
---
|
||||
|
||||
### bd close
|
||||
|
||||
Close (complete) an issue.
|
||||
|
||||
```bash
|
||||
bd close issue-123
|
||||
bd close issue-123 --reason "Implemented in PR #42"
|
||||
bd close issue-1 issue-2 issue-3 --reason "Bulk close"
|
||||
```
|
||||
|
||||
**Note**: Closed issues remain in database for history.
|
||||
|
||||
---
|
||||
|
||||
### bd show
|
||||
|
||||
Show detailed information about a specific issue.
|
||||
|
||||
```bash
|
||||
bd show issue-123
|
||||
bd show issue-123 --json
|
||||
```
|
||||
|
||||
Shows: all fields, dependencies, dependents, audit history.
|
||||
|
||||
---
|
||||
|
||||
### bd list
|
||||
|
||||
List all issues with optional filters.
|
||||
|
||||
```bash
|
||||
bd list # All issues
|
||||
bd list --status open # Only open
|
||||
bd list --priority 0 # Critical
|
||||
bd list --type bug # Only bugs
|
||||
bd list --assignee alice # By assignee
|
||||
bd list --status closed --limit 10 # Recent completions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Commands
|
||||
|
||||
### bd dep add
|
||||
|
||||
Add a dependency between issues.
|
||||
|
||||
```bash
|
||||
bd dep add from-issue to-issue # blocks (default)
|
||||
bd dep add from-issue to-issue --type blocks
|
||||
bd dep add from-issue to-issue --type related
|
||||
bd dep add epic-id task-id --type parent-child
|
||||
bd dep add original-id found-id --type discovered-from
|
||||
```
|
||||
|
||||
**Dependency types**:
|
||||
1. **blocks**: from-issue blocks to-issue (hard blocker)
|
||||
2. **related**: Soft link (no blocking)
|
||||
3. **parent-child**: Epic/subtask hierarchy
|
||||
4. **discovered-from**: Tracks origin of discovery
|
||||
|
||||
---
|
||||
|
||||
### bd dep tree
|
||||
|
||||
Visualize full dependency tree for an issue.
|
||||
|
||||
```bash
|
||||
bd dep tree issue-123
|
||||
```
|
||||
|
||||
Shows all dependencies and dependents in tree format.
|
||||
|
||||
---
|
||||
|
||||
### bd dep cycles
|
||||
|
||||
Detect circular dependencies.
|
||||
|
||||
```bash
|
||||
bd dep cycles
|
||||
```
|
||||
|
||||
Finds dependency cycles that would prevent work from being ready.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Commands
|
||||
|
||||
### bd stats
|
||||
|
||||
Get project statistics.
|
||||
|
||||
```bash
|
||||
bd stats
|
||||
bd stats --json
|
||||
```
|
||||
|
||||
Returns: total, open, in_progress, closed, blocked, ready, avg lead time.
|
||||
|
||||
---
|
||||
|
||||
### bd blocked
|
||||
|
||||
Get blocked issues with blocker information.
|
||||
|
||||
```bash
|
||||
bd blocked
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
Use to identify bottlenecks when ready list is empty.
|
||||
|
||||
---
|
||||
|
||||
## Setup Commands
|
||||
|
||||
### bd init
|
||||
|
||||
Initialize bd in current directory.
|
||||
|
||||
```bash
|
||||
bd init # Auto-detect prefix
|
||||
bd init --prefix api # Custom prefix
|
||||
```
|
||||
|
||||
Creates `.beads/` directory and database.
|
||||
|
||||
---
|
||||
|
||||
### bd quickstart
|
||||
|
||||
Show comprehensive quick start guide.
|
||||
|
||||
```bash
|
||||
bd quickstart
|
||||
```
|
||||
|
||||
Displays built-in reference for command syntax and workflows.
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Session Start
|
||||
|
||||
```bash
|
||||
bd ready --json
|
||||
bd show issue-123
|
||||
bd update issue-123 --status in_progress
|
||||
```
|
||||
|
||||
### Discovery During Work
|
||||
|
||||
```bash
|
||||
bd create "Found: bug in auth" -t bug
|
||||
bd dep add current-issue new-issue --type discovered-from
|
||||
```
|
||||
|
||||
### Completing Work
|
||||
|
||||
```bash
|
||||
bd close issue-123 --reason "Implemented with tests passing"
|
||||
bd ready # See what unblocked
|
||||
```
|
||||
|
||||
### Planning Epic
|
||||
|
||||
```bash
|
||||
bd create "OAuth Integration" -t epic
|
||||
bd create "Set up credentials" -t task
|
||||
bd create "Implement flow" -t task
|
||||
|
||||
bd dep add oauth-epic oauth-creds --type parent-child
|
||||
bd dep add oauth-epic oauth-flow --type parent-child
|
||||
bd dep add oauth-creds oauth-flow # creds blocks flow
|
||||
|
||||
bd dep tree oauth-epic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## JSON Output
|
||||
|
||||
All commands support `--json` for structured output:
|
||||
|
||||
```bash
|
||||
bd ready --json
|
||||
bd show issue-123 --json
|
||||
bd list --status open --json
|
||||
bd stats --json
|
||||
```
|
||||
|
||||
Use when parsing programmatically or extracting specific fields.
|
||||
|
||||
---
|
||||
|
||||
## Database Auto-Discovery
|
||||
|
||||
bd finds database in this order:
|
||||
|
||||
1. `--db` flag: `bd ready --db /path/to/db.db`
|
||||
2. `$BEADS_DB` environment variable
|
||||
3. `.beads/*.db` in current directory or ancestors
|
||||
4. `~/.beads/default.db` as fallback
|
||||
|
||||
**Project-local** (`.beads/`): Project-specific work, git-tracked
|
||||
|
||||
**Global fallback** (`~/.beads/`): Cross-project tracking, personal tasks
|
||||
|
||||
---
|
||||
|
||||
## Git Integration
|
||||
|
||||
bd automatically syncs with git:
|
||||
|
||||
- **After each operation**: Exports to JSONL (5s debounce)
|
||||
- **After git pull**: Imports from JSONL if newer than DB
|
||||
|
||||
**Files**:
|
||||
- `.beads/*.jsonl` - Source of truth (git-tracked)
|
||||
- `.beads/*.db` - Local cache (gitignored)
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Use JSON for parsing**:
|
||||
```bash
|
||||
bd ready --json | jq '.[0].id'
|
||||
```
|
||||
|
||||
**Bulk operations**:
|
||||
```bash
|
||||
bd close issue-1 issue-2 issue-3 --reason "Sprint complete"
|
||||
```
|
||||
|
||||
**Quick filtering**:
|
||||
```bash
|
||||
bd list --status open --priority 0 --type bug
|
||||
```
|
||||
|
||||
**Built-in help**:
|
||||
```bash
|
||||
bd quickstart # Comprehensive guide
|
||||
bd create --help # Command-specific help
|
||||
```
|
||||
Reference in New Issue
Block a user