Beads (bd) Usage Rules

First-Time Setup

If
bd
command is not found, tell the user:

Run:
curl -fsSL https://raw.githubusercontent.com/schlenks/superpowers-bd/main/scripts/setup-beads-local.sh | bash
This installs beads, initializes stealth mode, and adds git worktree support. For team use (shared
.beads/
), use
bd init
without
--stealth
.

TL;DR

bash

bd ready                    # What can I work on?
bd update <id> --claim      # I'm starting this
bd close <id>               # I'm done with this
bd sync                     # Save my changes

Critical rules:

Never use semicolons in
```
--acceptance
```
(triggers permission prompts)
Never use
```
bd edit
```
(opens interactive editor)
Always run
```
bd sync
```
before ending a session

Permission Avoidance (Critical)

Never use semicolons in
```
--acceptance
```
:
```
;
```
pattern triggers prompts. Use commas or
```
$'...\n...'
```
Use
```
--body-file
```
for multi-line content: newlines break pattern matching. Write to temp file first
Never delete temp files with
```
rm
```
: triggers permission prompts. Leave for human cleanup

Issue Operations

Create epic:

bd create --silent --type epic "Title" --body-file temp/desc.md -p 1

Create child task:

bd create --silent --parent <epic-id> "Title" --body-file temp/desc.md -p 2

Add dependencies:
```
--deps "id1,id2"
```
(comma-separated, no spaces)
View issue:
```
bd show <id>
```
Update issue:
```
bd update <id> --status=in_progress
```
Claim issue:
```
bd update <id> --claim
```
(sets assignee + in_progress atomically)
Close issue:
```
bd close <id>
```
Close multiple:
```
bd close <id1> <id2> <id3>
```
Close with reason:
```
bd close <id> --reason "explanation"
```
Add comment:
```
bd comments add <id> "comment text"
```
Add comment from file:
```
bd comments add <id> -f temp/comment.md
```

Query Commands

Ready work (no blockers):
```
bd ready
```
Blocked work:
```
bd blocked
```
Search issues:
```
bd search --query "text" --status open
```

List with filters:

bd list --status open --type task --priority-max 2

View dependency graph:
```
bd graph <id>
```
Check stale issues:
```
bd stale --days 14
```
Lint issues:
```
bd lint --status open
```

Maintenance Commands

Health check:
```
bd doctor
```
Auto-fix issues:
```
bd doctor --fix
```
Cleanup old issues:
```
bd cleanup
```
Prime AI context:
```
bd prime
```
Database info:
```
bd info
```

Key Flags

```
--silent
```
: output only ID (for scripting)
```
--json
```
: output in JSON format
```
--quiet
```
: suppress non-essential output
```
--type
```
: bug, feature, task, epic, chore, merge-request, molecule, gate
```
--parent <id>
```
: create as child of epic
```
-d "text"
```
: single-line description (prefer
```
--body-file
```
for multi-line)
```
--body-file <path>
```
: read description from file
```
-p N
```
: priority 0-4 (0=critical, 4=backlog)
```
--deps "id1,id2"
```
: dependencies (blocked by these)
```
--acceptance "..."
```
: acceptance criteria (no semicolons!)
```
--external-ref "ref"
```
: external link (e.g., "sc-1234")
```
-l "label1,label2"
```
: labels (comma-separated)

Session End Protocol

bash

bd create "Remaining work" -d "..." -p 2   # 1. File remaining work
bd close <completed-ids>                    # 2. Close completed (unblocks dependents)
bd sync                                     # 3. Force sync (bypasses 30s debounce)
git status                                  # 4. Check what changed
git add <files>                             # 5. Stage code changes
git commit -m "..."                         # 6. Commit changes

Integration with Skills

```
superpowers-bd:plan2beads
```
: convert markdown plan to epic with child tasks

superpowers-bd:writing-plans

: create plans with

Depends on:

and

Files:

sections

```
superpowers-bd:subagent-driven-development
```
: parallel execution with dependency awareness

Reference Files

```
references/acceptance-and-multiline.md
```
: writing acceptance criteria or multi-line descriptions
```
references/bd-edit-and-sandbox.md
```
: encountering bd edit usage or sandbox errors
```
references/dependency-management.md
```
: creating dependencies, fixing deadlocks, verifying dep structure
```
references/workflow-patterns.md
```
: running autonomous work loops, checking status values
```
references/session-end-details.md
```
: why bd sync matters or ephemeral branch handling
```
references/sync-workflow.md
```
: using sync subcommands, daily maintenance schedule
```
references/troubleshooting.md
```
: database sync issues, worktree limitations, merge conflicts
```
references/parallel-execution-safety.md
```
: dispatching parallel subagents, epic scoping, priority values, ID format

beads

NPX Install

Tags

SKILL.md Content