Steve Yegge
257ed9bdae
Files from PR #722 were inadvertently removed by a bd sync commit. Restoring: README.md, MOLECULES.md, PATTERNS.md, TROUBLESHOOTING.md, INTEGRATION_PATTERNS.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
110 lines
3.8 KiB
Markdown
110 lines
3.8 KiB
Markdown
# Beads Skill for Claude Code
|
|
|
|
A comprehensive skill for using [beads](https://github.com/steveyegge/beads) (bd) issue tracking with Claude Code.
|
|
|
|
## What This Skill Does
|
|
|
|
This skill teaches Claude Code how to use bd effectively for:
|
|
- **Multi-session work tracking** - Persistent memory across conversation compactions
|
|
- **Dependency management** - Graph-based issue relationships
|
|
- **Session handoff** - Writing notes that survive context resets
|
|
- **Molecules and wisps** (v0.34.0+) - Reusable work templates and ephemeral workflows
|
|
|
|
## Installation
|
|
|
|
Copy the `beads/` directory to your Claude Code skills location:
|
|
|
|
```bash
|
|
# Global installation
|
|
cp -r beads ~/.claude/skills/
|
|
|
|
# Or project-local
|
|
cp -r beads .claude/skills/
|
|
```
|
|
|
|
## When Claude Uses This Skill
|
|
|
|
The skill activates when conversations involve:
|
|
- "multi-session", "complex dependencies", "resume after weeks"
|
|
- "project memory", "persistent context", "side quest tracking"
|
|
- Work that spans multiple days or compaction cycles
|
|
- Tasks too complex for simple TodoWrite lists
|
|
|
|
## File Structure
|
|
|
|
```
|
|
beads/
|
|
├── SKILL.md # Main skill file (Claude reads this first)
|
|
├── README.md # This file (for humans)
|
|
└── references/ # Detailed documentation (loaded on demand)
|
|
├── BOUNDARIES.md # When to use bd vs TodoWrite
|
|
├── CLI_BOOTSTRAP_ADMIN.md # CLI command reference
|
|
├── DEPENDENCIES.md # Dependency semantics (A blocks B vs B blocks A)
|
|
├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration
|
|
├── ISSUE_CREATION.md # When and how to create issues
|
|
├── MOLECULES.md # Protos, mols, wisps (v0.34.0+)
|
|
├── PATTERNS.md # Common usage patterns
|
|
├── RESUMABILITY.md # Writing notes for post-compaction recovery
|
|
├── STATIC_DATA.md # Using bd for reference databases
|
|
├── TROUBLESHOOTING.md # Common issues and fixes
|
|
└── WORKFLOWS.md # Step-by-step workflow guides
|
|
```
|
|
|
|
## Key Concepts
|
|
|
|
### bd vs TodoWrite
|
|
|
|
| Use bd when... | Use TodoWrite when... |
|
|
|----------------|----------------------|
|
|
| Work spans multiple sessions | Single-session tasks |
|
|
| Complex dependencies exist | Linear step-by-step work |
|
|
| Need to resume after weeks | Just need a quick checklist |
|
|
| Knowledge work with fuzzy boundaries | Clear, immediate tasks |
|
|
|
|
### The Dependency Direction Trap
|
|
|
|
`bd dep add A B` means **"A depends on B"** (B must complete before A can start).
|
|
|
|
```bash
|
|
# Want: "Setup must complete before Implementation"
|
|
bd dep add implementation setup # ✓ CORRECT
|
|
# NOT: bd dep add setup implementation # ✗ WRONG
|
|
```
|
|
|
|
### Surviving Compaction
|
|
|
|
When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context:
|
|
|
|
```bash
|
|
bd update issue-123 --notes "COMPLETED: JWT auth with RS256
|
|
KEY DECISION: RS256 over HS256 for key rotation
|
|
IN PROGRESS: Password reset flow
|
|
NEXT: Implement rate limiting"
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- [bd CLI](https://github.com/steveyegge/beads) installed (`brew install steveyegge/beads/bd`)
|
|
- A git repository (bd requires git for sync)
|
|
- Initialized database (`bd init` in project root)
|
|
|
|
## Version Compatibility
|
|
|
|
- **v0.34.0+**: Full support including molecules, wisps, and cross-project dependencies
|
|
- **v0.15.0+**: Core functionality (dependencies, notes, status tracking)
|
|
- **Earlier versions**: Basic functionality but some features may be missing
|
|
|
|
## Contributing
|
|
|
|
This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `skills/beads/` directory.
|
|
|
|
Issues and PRs welcome for:
|
|
- Documentation improvements
|
|
- New workflow patterns
|
|
- Bug fixes in examples
|
|
- Additional troubleshooting scenarios
|
|
|
|
## License
|
|
|
|
MIT (same as beads)
|