Claude-skill-registry beads

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/beads" ~/.claude/skills/majiayu000-claude-skill-registry-beads-14179a && rm -rf "$T"

manifest: skills/data/beads/SKILL.md

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

bd vs TodoWrite

bd (persistent)	TodoWrite (ephemeral)
Multi-session work	Single-session tasks
Complex dependencies	Linear execution
Survives compaction	Conversation-scoped
Git-backed, team sync	Local to session

Decision test: "Will I need this context in 2 weeks?" → YES = bd

When to use bd:

Work spans multiple sessions or days
Tasks have dependencies or blockers
Need to survive conversation compaction
Exploratory/research work with fuzzy boundaries
Collaboration with team (git sync)

When to use TodoWrite:

Single-session linear tasks
Simple checklist for immediate work
All context is in current conversation
Will complete within current session

Prerequisites

bd --version  # Requires v0.34.0+

bd CLI installed and in PATH
Git repository (bd requires git for sync)
Initialization:
```
bd init
```
run once (humans do this, not agents)

CLI Reference

Run

bd prime

for AI-optimized workflow context (auto-loaded by hooks). Run
bd <command> --help
for specific command usage.

Essential commands:

bd ready

bd create

bd show

bd update

bd close

bd sync

Session Protocol

```
bd ready
```
— Find unblocked work
```
bd show <id>
```
— Get full context
```
bd update <id> --status in_progress
```
— Start work
Add notes as you work (critical for compaction survival)
```
bd close <id> --reason "..."
```
— Complete task
```
bd sync
```
— Persist to git (always run at session end)

Advanced Features

Feature	CLI	Resource
Molecules (templates)	`bd mol --help`	MOLECULES.md
Chemistry (pour/wisp)	`bd pour` , `bd wisp`	CHEMISTRY_PATTERNS.md
Agent beads	`bd agent --help`	AGENTS.md
Async gates	`bd gate --help`	ASYNC_GATES.md
Worktrees	`bd worktree --help`	WORKTREES.md

Resources

Resource	Content
BOUNDARIES.md	bd vs TodoWrite detailed comparison
CLI_REFERENCE.md	Complete command syntax
DEPENDENCIES.md	Dependency system deep dive
INTEGRATION_PATTERNS.md	TodoWrite and tool integration
ISSUE_CREATION.md	When and how to create issues
MOLECULES.md	Proto definitions, component labels
PATTERNS.md	Common usage patterns
RESUMABILITY.md	Compaction survival guide
STATIC_DATA.md	Database schema reference
TROUBLESHOOTING.md	Error handling and fixes
WORKFLOWS.md	Step-by-step workflow patterns
AGENTS.md	Agent bead tracking (v0.40+)
ASYNC_GATES.md	Human-in-the-loop gates
CHEMISTRY_PATTERNS.md	Mol vs Wisp decision tree
WORKTREES.md	Parallel development patterns

Full Documentation

bd prime: AI-optimized workflow context
GitHub: github.com/steveyegge/beads