feat(skills): add bd-workflow CLI reference skill
All checks were successful
CI / check (push) Successful in 3m23s
All checks were successful
CI / check (push) Successful in 3m23s
Comprehensive bd CLI reference covering: - Core commands (create, update, close, show, list) - Dependency management (bd dep add, bd blocked) - Formula/molecule workflow (pour, wisp, cook, gates) - When to use bd vs TodoWrite Complements existing beads_workflow.md which covers philosophy and humanlayer integration patterns. Closes: nixos-configs-6pk Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
230
home/roles/development/skills/bd_workflow.md
Normal file
230
home/roles/development/skills/bd_workflow.md
Normal file
@@ -0,0 +1,230 @@
|
||||
---
|
||||
description: How to use the bd (beads) CLI for issue tracking, dependencies, and workflow orchestration
|
||||
---
|
||||
|
||||
# BD Workflow
|
||||
|
||||
The `bd` CLI is a git-backed issue tracker with first-class dependency support. Use it for multi-session work, blocking relationships, and persistent memory across conversation compaction.
|
||||
|
||||
## When to Use BD vs TodoWrite
|
||||
|
||||
| Use BD | Use TodoWrite |
|
||||
|--------|---------------|
|
||||
| Work spans multiple sessions | Single-session tasks |
|
||||
| Dependencies between tasks | Independent subtasks |
|
||||
| Need audit trail in git | Ephemeral tracking |
|
||||
| Cross-repo coordination | Local project only |
|
||||
| Resuming after compaction | Simple task lists |
|
||||
|
||||
## Core Commands
|
||||
|
||||
### Creating Issues
|
||||
|
||||
```bash
|
||||
bd create "Issue title" # Basic task
|
||||
bd create "Bug title" --type=bug --priority=1 # P1 bug
|
||||
bd create "Feature" --type=feature -d "Details" # With description
|
||||
bd q "Quick capture" # Output only ID
|
||||
```
|
||||
|
||||
### Managing Issues
|
||||
|
||||
```bash
|
||||
bd show <id> # View issue details
|
||||
bd show <id> --children # View children of epic
|
||||
bd list # List open issues (default 50)
|
||||
bd list --all # Include closed
|
||||
bd list -s in_progress # Filter by status
|
||||
bd list -t bug -p 0 # P0 bugs
|
||||
bd list --pretty # Tree format
|
||||
```
|
||||
|
||||
### Updating Issues
|
||||
|
||||
```bash
|
||||
bd update <id> --status=in_progress # Start work
|
||||
bd update <id> --status=blocked # Mark blocked
|
||||
bd update <id> --claim # Claim atomically
|
||||
bd update <id> --add-label=urgent # Add label
|
||||
bd update <id> -d "New description" # Update description
|
||||
```
|
||||
|
||||
### Closing Issues
|
||||
|
||||
```bash
|
||||
bd close <id> # Close issue
|
||||
bd close <id> --continue # Auto-advance to next step
|
||||
bd close <id> --suggest-next # Show newly unblocked
|
||||
```
|
||||
|
||||
## Finding Work
|
||||
|
||||
```bash
|
||||
bd ready # Ready issues (no blockers)
|
||||
bd ready --mol <mol-id> # Ready steps in molecule
|
||||
bd ready -n 5 # Limit to 5
|
||||
bd ready --assignee me # Assigned to me
|
||||
bd blocked # Show blocked issues
|
||||
bd blocked --parent <id> # Blocked within epic
|
||||
```
|
||||
|
||||
## Dependency Management
|
||||
|
||||
### Creating Dependencies
|
||||
|
||||
```bash
|
||||
bd dep <blocker> --blocks <blocked> # A blocks B
|
||||
bd dep add <blocked> <blocker> # Same as above
|
||||
bd dep relate <id1> <id2> # Bidirectional link
|
||||
```
|
||||
|
||||
### Viewing Dependencies
|
||||
|
||||
```bash
|
||||
bd dep list <id> # Show dependencies
|
||||
bd dep tree <id> # Dependency tree
|
||||
bd dep cycles # Detect cycles
|
||||
```
|
||||
|
||||
### Removing Dependencies
|
||||
|
||||
```bash
|
||||
bd dep remove <blocked> <blocker> # Remove dependency
|
||||
bd dep unrelate <id1> <id2> # Remove relation
|
||||
```
|
||||
|
||||
## Sync Workflow
|
||||
|
||||
BD syncs issues via git. The daemon handles this automatically, but manual sync is available:
|
||||
|
||||
```bash
|
||||
bd sync # Full sync (pull, merge, push)
|
||||
bd sync --flush-only # Export to JSONL only
|
||||
bd sync --import-only # Import from JSONL only
|
||||
bd sync --status # Show sync branch diff
|
||||
bd sync --squash # Accumulate without commit
|
||||
```
|
||||
|
||||
## Formula and Molecule Workflow
|
||||
|
||||
Formulas are reusable workflow templates. Molecules are instantiated workflows.
|
||||
|
||||
### Formulas
|
||||
|
||||
```bash
|
||||
bd formula list # List available formulas
|
||||
bd formula list --type=workflow # Filter by type
|
||||
bd formula show <name> # Show formula details
|
||||
bd cook <formula> # Compile to proto (stdout)
|
||||
bd cook <formula> --var name=auth # With variable substitution
|
||||
bd cook <formula> --dry-run # Preview steps
|
||||
bd cook <formula> --persist # Save to database
|
||||
```
|
||||
|
||||
### Molecules: Pour vs Wisp
|
||||
|
||||
| pour (persistent) | wisp (ephemeral) |
|
||||
|-------------------|------------------|
|
||||
| Feature implementations | Release workflows |
|
||||
| Multi-session work | Patrol cycles |
|
||||
| Audit trail needed | Health checks |
|
||||
| Git-synced | Local only |
|
||||
|
||||
```bash
|
||||
# Persistent molecule (liquid phase)
|
||||
bd mol pour <proto> --var name=auth
|
||||
|
||||
# Ephemeral molecule (vapor phase)
|
||||
bd mol wisp <proto> --var version=1.0
|
||||
bd mol wisp list # List wisps
|
||||
bd mol wisp gc # Garbage collect
|
||||
```
|
||||
|
||||
### Tracking Molecule Progress
|
||||
|
||||
```bash
|
||||
bd mol show <mol-id> # Show structure
|
||||
bd mol show <mol-id> --parallel # Parallelizable steps
|
||||
bd mol current # Where am I?
|
||||
bd mol current <mol-id> # Status for molecule
|
||||
bd mol progress <mol-id> # Progress summary + ETA
|
||||
```
|
||||
|
||||
### Molecule Lifecycle
|
||||
|
||||
```bash
|
||||
bd mol squash <mol-id> # Condense to digest
|
||||
bd mol burn <mol-id> # Delete wisp
|
||||
bd mol distill <epic-id> # Extract formula from epic
|
||||
```
|
||||
|
||||
## Gates and Human Checkpoints
|
||||
|
||||
Gates are async wait conditions that block workflow steps:
|
||||
|
||||
| Gate Type | Wait Condition |
|
||||
|-----------|---------------|
|
||||
| human | Manual `bd close` |
|
||||
| timer | Timeout expires |
|
||||
| gh:run | GitHub workflow completes |
|
||||
| gh:pr | PR merges |
|
||||
| bead | Cross-rig bead closes |
|
||||
|
||||
```bash
|
||||
bd gate list # Show open gates
|
||||
bd gate list --all # Include closed
|
||||
bd gate check # Evaluate all gates
|
||||
bd gate check --type=bead # Check bead gates only
|
||||
bd gate resolve <id> # Close manually
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Starting Work on a Bead
|
||||
|
||||
```bash
|
||||
bd update <id> --status=in_progress
|
||||
# ... do work ...
|
||||
bd close <id>
|
||||
```
|
||||
|
||||
### Creating Related Issues
|
||||
|
||||
```bash
|
||||
bd create "Main task" --deps "blocks:<other-id>"
|
||||
bd dep add <new-id> <blocker-id>
|
||||
```
|
||||
|
||||
### Working Through a Molecule
|
||||
|
||||
```bash
|
||||
bd mol pour my-workflow --var name=feature
|
||||
bd ready --mol <mol-id> # Find next step
|
||||
bd update <step-id> --claim # Claim step
|
||||
# ... do work ...
|
||||
bd close <step-id> --continue # Close and advance
|
||||
```
|
||||
|
||||
### Quick Status Check
|
||||
|
||||
```bash
|
||||
bd ready -n 3 # Top 3 ready items
|
||||
bd list -s in_progress # What's in flight?
|
||||
bd blocked # What's stuck?
|
||||
```
|
||||
|
||||
## Useful Flags
|
||||
|
||||
| Flag | Effect |
|
||||
|------|--------|
|
||||
| `--json` | JSON output for scripting |
|
||||
| `--quiet` | Suppress non-essential output |
|
||||
| `--dry-run` | Preview without executing |
|
||||
| `--pretty` | Tree format display |
|
||||
|
||||
## Integration Notes
|
||||
|
||||
- BD auto-syncs via daemon (check with `bd info`)
|
||||
- Issues stored in `.beads/` directory
|
||||
- JSONL files sync through git
|
||||
- Use `bd doctor` if something seems wrong
|
||||
Reference in New Issue
Block a user