Claude-skill-registry bd-workflow

How to use bd (beads) for issue tracking, ready work, status updates, and comments in this repo.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/bd" ~/.claude/skills/majiayu000-claude-skill-registry-bd-workflow && rm -rf "$T"

manifest: skills/data/bd/SKILL.md

bd (beads) Workflow Guide

This document expands the abbreviated rules in

AGENTS.md

. Read this whenever you interact with task tracking, planning docs, or MCP helpers.

Why bd?

Dependency-aware: track blockers, dependents, and discovered-from links.
Git-friendly: bd auto-syncs to
```
.beads/issues.jsonl
```
, so repos capture task history.
Agent-optimized: machine-readable JSON output (
```
--json
```
) plus "ready" filtering.
Single source of truth: prevents duplicate trackers, markdown TODOs, or ad-hoc spreadsheets.

Quick Start Commands

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.

Issue Types & Priorities

Types:
```
bug
```
,
```
feature
```
,
```
task
```
,
```
epic
```
,
```
chore
```
.
Priorities:
```
0
```
(critical) through
```
4
```
(backlog). Respect existing priority unless the PM/user changes it.

Workflow for AI Agents

Check ready work with
```
bd ready --json -n 0
```
. Do this before asking what to work on.

Claim the task:

bd update <id> --status in_progress --json

(add notes if relevant).

Implement / test / document the change.

Discover new work? Create a linked issue (e.g.,

bd create "Fix follow-up" -p 1 --deps discovered-from:<parent> --json

Complete the task via

bd close <id> --reason "Completed" --json

when the PR merges.

Commit
.beads/issues.jsonl
alongside code. Never leave tracker changes uncommitted.

Auto-Sync Behavior

bd exports to
```
.beads/issues.jsonl
```
automatically (5s debounce) after changes.
After
```
git pull
```
, bd imports newer JSONL back into the local state. No manual sync needed.

MCP Integration (Optional)

Install:
```
pip install beads-mcp
```
.
Add to
```
~/.config/claude/config.json
```
:

{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

Use
```
mcp__beads__*
```
calls instead of the CLI if your client supports MCP.

Planning Document Hygiene

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.

Important Rules (Do & Don't)

✅ Use bd for all task tracking.
✅ Include discovered-from dependencies to show provenance.
✅ Keep
```
.beads/issues.jsonl
```
in every relevant commit.
✅ Store planning docs in
```
history/
```
.
❌ No markdown TODO lists or alternative trackers.
❌ No forgetting
```
--json
```
.
❌ No cluttering the repo root with temporary planning files.

Need More Context?

See

README.md

QUICKSTART.md

for broader project background, but treat bd as the authoritative view of work.