Add BEADS_DIR as a replacement for BEADS_DB to point to the .beads
directory instead of the database file directly.
Rationale:
- With --no-db mode, there's no .db file to point to
- The .beads directory is the logical unit (contains config.yaml, db
files, jsonl files)
- More intuitive: point to the beads directory not the database file
Implementation:
- Add BEADS_DIR environment variable support to FindDatabasePath()
- Priority order: BEADS_DIR > BEADS_DB > auto-discovery
- Maintain backward compatibility with BEADS_DB (now deprecated)
- Update --no-db mode to respect BEADS_DIR
- Update MCP integration (config.py, bd_client.py)
- Update documentation to show BEADS_DIR as preferred method
Testing:
- Backward compatibility: BEADS_DB still works
- BEADS_DIR works with regular database mode
- BEADS_DIR works with --no-db mode
- Priority: BEADS_DIR takes precedence over BEADS_DB
Follow-up issues for refactoring:
- bd-efe8: Refactor path canonicalization into helper function
- bd-c362: Extract database search logic into helper function
Closes bd-e16b
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* 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.
Thanks for accepting the original contribution! I've made some updates based on
real-world usage.
Some of the examples in the original were a bit idiosyncratic to my own work,
so I've generalized them to use universal programming scenarios (authentication,
database migrations, API design) that should be more relatable to any developer.
I've also added some broader improvements to the skill. Apologies for not doing
these as two separate pull requests - I hope bundling them together is OK.
These improvements came largely from asking Claude to reflect on what was useful
and difficult about using the skill - in particular, Claude felt that the
post-compaction scenario was a powerful one because normally a context compaction
causes severe loss of state.
Main changes:
- Add comprehensive compaction survival guide with note-taking patterns
- Replace basic TodoWrite integration with temporal layering pattern
- Add bd export/import documentation with collision resolution
- Clarify when to ask before creating issues vs creating directly
- Add database discovery rules for multi-DB scenarios
- Add --max-depth/-d flag with default of 50
- Wire flag through to store.GetDependencyTree()
- Add input validation (must be >= 1)
- Show inline '… [truncated]' markers on truncated nodes
- Update truncation warning to show actual depth used
- Add comprehensive tests (truncation, default depth, boundary cases)
- Update CLI docs and reference
Thanks to @yashwanth-reddy909 for the initial implementation in PR #87.
This commit completes the feature with full wiring, validation, tests, and docs.
Amp-Thread-ID: https://ampcode.com/threads/T-c439b09c-cff2-48d9-8988-cf9353f0d32e
Co-authored-by: Amp <amp@ampcode.com>
- Provides comprehensive workflow patterns and decision criteria
- Includes quick reference (SKILL.md) and detailed references
- Teaches when to use bd vs markdown/TodoWrite
- Covers dependency types and issue lifecycle management
- Complements existing plugin with usage philosophy
