* Update skill installation path and document new features Installation path changes: - Update from ~/.claude/skills/bd to bd-issue-tracking - Matches internal skill name for consistency with other skills Documentation additions: - Add 3 new reference files to documentation list - Document compaction survival patterns (critical for Claude Code) - Mention self-check checklists and quality guidelines This prepares the README for upcoming skill content improvements. * Add new reference files for enhanced skill guidance New reference documentation: 1. ISSUE_CREATION.md - When to ask vs create issues - Decision criteria for knowledge work vs technical work - Issue quality guidelines and best practices - Design vs acceptance criteria guidance - Self-check questions for well-scoped issues 2. RESUMABILITY.md - Making issues resumable across sessions - Patterns for complex technical work with APIs - Working code examples and API response samples - When enhanced documentation matters vs simple descriptions - Critical for multi-session work and crash recovery 3. STATIC_DATA.md - Using bd for reference databases - Alternative use case beyond work tracking - Glossaries and terminology management - Dual format patterns (database + markdown) - When bd helps vs when simpler formats suffice These additions emerged from real-world usage patterns and enable Claude to make better decisions about issue structure and resumability. * Enhance existing skill files with real-world usage patterns SKILL.md major enhancements (~194 net lines added): - Add "Test Yourself" decision framework with self-check questions - Document compaction survival patterns (critical for Claude Code) - Add Notes Quality Self-Check (future-me test, stranger test) - Session Start Checklist with copy-paste templates - Field Usage Reference table (when to use each bd field) - Progress Checkpointing triggers and patterns - Issue Creation Checklist with quality self-checks - Enhanced session handoff protocols WORKFLOWS.md enhancements (~114 lines added): - Session handoff workflow with detailed checklists - Collaborative handoff between Claude and user - Compaction survival workflow - Notes format guidelines (current state, not cumulative) - Session start checklist expansion BOUNDARIES.md updates (~49 lines removed): - Streamlined content (moved detailed workflows to WORKFLOWS.md) - Retained core decision criteria - Improved examples and integration patterns CLI_REFERENCE.md minor updates: - Additional command examples - Clarified flag usage These improvements emerged from extensive real-world usage, particularly around crash recovery, compaction events, and multi-session workflows. The additions make the skill more practical for autonomous agent use.
2 KiB
2 KiB
Using bd for Static Reference Data
bd is primarily designed for work tracking, but can also serve as a queryable database for static reference data with some adaptations.
Work Tracking (Primary Use Case)
Standard bd workflow:
- Issues flow through states (open → in_progress → closed)
- Priorities and dependencies matter
- Status tracking is essential
- IDs are sufficient for referencing
Reference Databases / Glossaries (Alternative Use)
When using bd for static data (terminology, glossaries, reference information):
Characteristics:
- Entities are mostly static (typically always open)
- No real workflow or state transitions
- Names/titles more important than IDs
- Minimal or no dependencies
Recommended approach:
- Use separate database (not mixed with work tracking) to avoid confusion
- Consider dual format: maintain markdown version alongside database for name-based lookup
- Example: A terminology database could use both
terms.db(queryable via bd) andGLOSSARY.md(browsable by name)
Key difference: Work items have lifecycle; reference entities are stable knowledge.
When to Use This Pattern
Good fit:
- Technical glossaries or terminology databases
- Reference documentation that needs dependency tracking
- Knowledge bases with relationships between entries
- Structured data that benefits from queryability
Poor fit:
- Data that changes frequently (use work tracking pattern)
- Simple lists (markdown is simpler)
- Data that needs complex queries (use proper database)
Limitations
bd show requires IDs, not names:
bd show term-42worksbd show "API endpoint"doesn't work- Workaround:
bd list | grep -i "api endpoint"to find ID first - This is why dual format (bd + markdown) is recommended for reference data
No search by content:
- bd searches by ID, title filters, status, labels
- For full-text search across descriptions/notes, use grep on the JSONL file
- Example:
grep -i "authentication" .beads/issues.jsonl