Menu
How to use bd (beads) for issue tracking, ready work, status updates, and comments in this repo.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
How to use the repo-scoped sk CLI to manage Claude Skills in this codebase.
One lifecycle for Lambda repos: choose a bd task, start work, land the PR, and watch GitHub via Dumbwaiter MCP until it merges.
Provider-agnostic wait-for-change skill that uses the Dumbwaiter MCP server to wait on PR events (GitHub first) via wait.start/status/cancel/await, with progress notifications and durable state.
Testing patterns and standards for this codebase, including async effects, fakes vs mocks, and property-based testing.
Based on SOC occupation classification
| name | bd-workflow |
| description | How to use bd (beads) for issue tracking, ready work, status updates, and comments in this repo. |
This document expands the abbreviated rules in AGENTS.md. Read this whenever you interact with task tracking, planning docs, or MCP helpers.
.beads/issues.jsonl, so repos capture task history.--json) plus "ready" filtering.bd ready --json -n 0 # find unblocked work
bd create "Issue title" -t task -p 2 --json
bd update bd-42 --status in_progress --json
bd close bd-42 --reason "Completed" --json
Always run bd with --json. Pipe/parse as needed.
bug, feature, task, epic, chore.0 (critical) through 4 (backlog). Respect existing priority unless the PM/user changes it.bd ready --json -n 0. Do this before asking what to work on.bd update <id> --status in_progress --json (add notes if relevant).bd create "Fix follow-up" -p 1 --deps discovered-from:<parent> --json).bd close <id> --reason "Completed" --json when the PR merges..beads/issues.jsonl alongside code. Never leave tracker changes uncommitted..beads/issues.jsonl automatically (5s debounce) after changes.git pull, bd imports newer JSONL back into the local state. No manual sync needed.pip install beads-mcp.~/.config/claude/config.json:{
"beads": {
"command": "beads-mcp",
"args": []
}
}
mcp__beads__* calls instead of the CLI if your client supports MCP.AI-generated planning/design docs should live under history/ (add it to .gitignore if desired). Keeping the repo root clean avoids confusing ephemeral plans with durable docs.
.beads/issues.jsonl in every relevant commit.history/.--json.See README.md / QUICKSTART.md for broader project background, but treat bd as the authoritative view of work.