Tips & Tricks

Beads cheat sheet

The commands this workflow leans on day-to-day. Everything else - housekeeping, recovery, coordination - lives in the upstream reference linked below.

Command	Does
bd ready / --parent <epic> / --explain	Unblocked work / epic remainder / why (not) ready
bd blocked	Beads waiting on dependencies
bd show <id>	Full details for one bead
bd query "status=open AND priority<=1"	Compound query - replaces bd list + jq
bd count --by-status	Grouped counts (--by-priority / --by-type)
bd epic status <id> / --eligible-only	Completion status for that epic / only epics eligible to close
bd create "Epic: name" -t epic -p 2	New epic at priority 2
bd create "Task: title" -t task --parent <epic>	Task under an epic
bd worktree create .worktrees/<name>	Worktree at a set path - a bare <name> lands at ./<name>, sibling to your files. Resolves relative to your current directory, so run it from the repo root
bd import -	Create many rich issues at once from JSONL on stdin - round-trips with bd export, so the format is always discoverable
bd q "quick title"	Quick capture - log a thought without breaking stride
bd update <id> --claim	Claim as in-progress
bd close <id> --reason "..."	Complete with evidence
bd dep add <child> <depends-on>	Add dependency
bd note <id> "context"	Append evidence to a bead
bd remember "insight" / bd memories <kw> / bd forget <id>	Persist / search / remove learnings
bd list --label <topic> --status all / bd search "<kw>" --status all	Search the knowledge base - deferred research/design/decision beads labeled kb (body terms: --desc-contains "<kw>"; then read hits with bd show <id1> <id2> or --flat --long -n 10).
bd dolt push / pull	Sync beads DB to/from your beads remote

Go deeper - upstream Beads docs

• CLI reference - every bd command and flag, including the housekeeping and coordination commands trimmed from this sheet (list, stats, doctor, lint, stale, find-duplicates, defer, human, swarm, batch, merge-slot, github, -C)
• Recovery guides - diverged Dolt history, failed syncs

Land the Plane: Every session ends with bd close → bd dolt push (to your beads remote) → git push (to your code repo). The finishing-a-development-branch skill enforces this.

Skill routing

I need to…	Invoke
Orient at session start	getting-up-to-speed
Design before coding	brainstorming
Stress-test a design	stress-test
Write a task plan	writing-plans
Execute tasks with review per task	subagent-driven-development
Execute a plan in one session	executing-plans
Write a feature or bugfix	test-driven-development
Debug a failure	systematic-debugging
Claim work is done	verification-before-completion
Get code reviewed	requesting-code-review
Respond to review feedback	receiving-code-review
Merge or close a branch	finishing-a-development-branch
Run independent tasks in parallel	dispatching-parallel-agents
Update docs after shipping	document-release
Research a topic	research-driven-development
Write human-facing prose	write-documentation
Consolidate or dedup memories	memory-curator

The using-superpowers bootstrap skill (auto-loaded at session start) has the full routing logic; if unsure, ask Claude to read it.

Common issues

See Getting Started - Troubleshooting for installation and configuration problems. Quick fixes for the most frequent ones:

Skills not loading - /plugins should list beads-superpowers, /skills should show 21 skills. If not, reinstall.

bd: command not found - brew install beads or npm install -g @beads/bd.

Double context injection - The plugin detects bd setup claude hooks and skips its own beads-context section; same-event double-firing is suppressed by a dedup marker. If you still see duplicates, run bd setup claude --remove.

bd dolt push fails - No beads remote configured. Harmless if you don’t need remote sync.

Windows

The SessionStart hook (hooks/session-start) is bash. On Windows, the polyglot wrapper hooks/run-hook.cmd calls it via Git Bash. The .cmd file is valid as both a batch file and a bash script: on Windows, cmd.exe finds Git Bash and re-executes; on Unix, the : command is a no-op and bash runs the rest. It works without WSL as long as Git for Windows is installed.

Skills are pure Markdown with no platform-specific code. Only the hook wrapper handles platform differences.

Upstream tracking

Source	Baseline	Tracking
obra/superpowers	v6.1.1	Skill content, new skills, hooks
gastownhall/beads	v1.1.0	CLI commands, bd prime format