From f472aa9b3da607c5363032f095f69b896791b66a Mon Sep 17 00:00:00 2001 From: John Ogle Date: Thu, 15 Jan 2026 17:01:07 -0800 Subject: [PATCH] feat(skills): add bd-workflow CLI reference skill 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 --- home/roles/development/skills/bd_workflow.md | 230 +++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 home/roles/development/skills/bd_workflow.md diff --git a/home/roles/development/skills/bd_workflow.md b/home/roles/development/skills/bd_workflow.md new file mode 100644 index 0000000..b419e6d --- /dev/null +++ b/home/roles/development/skills/bd_workflow.md @@ -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 # View issue details +bd show --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 --status=in_progress # Start work +bd update --status=blocked # Mark blocked +bd update --claim # Claim atomically +bd update --add-label=urgent # Add label +bd update -d "New description" # Update description +``` + +### Closing Issues + +```bash +bd close # Close issue +bd close --continue # Auto-advance to next step +bd close --suggest-next # Show newly unblocked +``` + +## Finding Work + +```bash +bd ready # Ready issues (no blockers) +bd ready --mol # 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 # Blocked within epic +``` + +## Dependency Management + +### Creating Dependencies + +```bash +bd dep --blocks # A blocks B +bd dep add # Same as above +bd dep relate # Bidirectional link +``` + +### Viewing Dependencies + +```bash +bd dep list # Show dependencies +bd dep tree # Dependency tree +bd dep cycles # Detect cycles +``` + +### Removing Dependencies + +```bash +bd dep remove # Remove dependency +bd dep unrelate # 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 # Show formula details +bd cook # Compile to proto (stdout) +bd cook --var name=auth # With variable substitution +bd cook --dry-run # Preview steps +bd cook --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 --var name=auth + +# Ephemeral molecule (vapor phase) +bd mol wisp --var version=1.0 +bd mol wisp list # List wisps +bd mol wisp gc # Garbage collect +``` + +### Tracking Molecule Progress + +```bash +bd mol show # Show structure +bd mol show --parallel # Parallelizable steps +bd mol current # Where am I? +bd mol current # Status for molecule +bd mol progress # Progress summary + ETA +``` + +### Molecule Lifecycle + +```bash +bd mol squash # Condense to digest +bd mol burn # Delete wisp +bd mol distill # 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 # Close manually +``` + +## Common Patterns + +### Starting Work on a Bead + +```bash +bd update --status=in_progress +# ... do work ... +bd close +``` + +### Creating Related Issues + +```bash +bd create "Main task" --deps "blocks:" +bd dep add +``` + +### Working Through a Molecule + +```bash +bd mol pour my-workflow --var name=feature +bd ready --mol # Find next step +bd update --claim # Claim step +# ... do work ... +bd close --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