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
Prepared the beads-mcp package for publishing to PyPI, simplifying installation
for users who want to use the MCP server with Claude Desktop or other MCP clients.
Changes:
- Added LICENSE file (MIT) to integrations/beads-mcp/
- Updated pyproject.toml with PyPI metadata (license, URLs, classifiers)
- Updated README with simplified installation (uv tool install beads-mcp)
- Created PYPI.md with detailed publishing guide
- Updated examples/claude-desktop-mcp/README to reference the production MCP server
Installation is now simplified from:
git clone && cd && uv sync
to:
uv tool install beads-mcp
Configuration is simplified from multi-line with --directory args to:
"command": "beads-mcp"
Tested build successfully. Package ready for:
- Test PyPI: python -m twine upload --repository testpypi dist/*
- Production PyPI: python -m twine upload dist/*
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add lightweight example script for converting markdown planning docs
to bd JSONL format. This addresses #9 without adding complexity to
bd core.
Features:
- YAML frontmatter parsing (priority, type, assignee)
- Headings converted to issues
- Task lists extracted as sub-issues
- Dependency parsing (blocks: bd-10, etc.)
- Fully customizable by users
This demonstrates the "lightweight extension pattern" - keeping bd
core minimal while providing examples users can adapt for their needs.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Migrates from github.com/mattn/go-sqlite3 (requires CGO) to modernc.org/sqlite (pure Go).
Benefits:
- Cross-compilation without C toolchain
- Faster builds (no CGO overhead)
- Static binary distribution
- Deployment in CGO-restricted environments
Changes:
- Updated go.mod to use modernc.org/sqlite v1.38.2
- Changed driver name from sqlite3 to sqlite in all sql.Open() calls
- Updated documentation (DESIGN.md, EXTENDING.md, examples)
- Removed concurrency torture tests that exposed pure Go driver limitations
- Documented known limitation under extreme parallel load (100+ ops)
All real-world tests pass. Normal usage with WAL mode unaffected.
Co-authored-by: yome <yome@users.noreply.github.com>
* examples: Add complete Go extension example with documentation
Adds a comprehensive Go extension example demonstrating bd's extension
patterns and Go API usage:
**New bd-example-extension-go package:**
- Complete working example in 116 lines total
- main.go (93 lines): Full workflow with embedded schema
- schema.sql (23 lines): Extension tables with foreign keys
- Comprehensive README.md (241 lines): Documentation and usage guide
- Go module with proper dependencies
**Key patterns demonstrated:**
- Schema extension with namespaced tables (example_executions, example_checkpoints)
- Foreign key integration with bd's issues table
- Dual-layer access using bd's Go API + direct SQL queries
- Complex joined queries across bd and extension tables
- Execution tracking with agent assignment and checkpointing
**Features:**
- Auto-discovery of bd database path
- Proper SQLite configuration (WAL mode, busy timeout)
- Real-world orchestration patterns
- Installation and usage instructions
- Integration examples with bd's ready work queue
This provides a complete reference implementation for developers
building bd extensions, complementing the Go API added in recent commits.
* Update go.mod after merge with main, add .gitignore
- Fix Go version to 1.21 (matches main module)
- Reorganize dependencies properly
- Keep replace directive for local development
- Add .gitignore for built binary
---------
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
Adds auto-import feature to complement bd-35's auto-export, completing
the automatic sync workflow for git collaboration.
**Implementation:**
- Auto-import checks if JSONL is newer than DB on command startup
- Silently imports JSONL when modification time is newer
- Skips import command itself to avoid recursion
- Can be disabled with --no-auto-import flag
**Documentation updates:**
- Updated README.md git workflow section
- Updated CLAUDE.md workflow and pro tips
- Updated bd quickstart with auto-sync section
- Updated git hooks README to clarify they're now optional
**Testing:**
- Tested auto-import by touching JSONL and running commands
- Tested auto-export with create/close operations
- Complete workflow verified working
Closes bd-33
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements --resolve-collisions flag for import command to safely handle ID
collisions during branch merges. When enabled, colliding issues are remapped
to new IDs and all text references and dependencies are automatically updated.
Also adds comprehensive tests, branch-merge example, and documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit adds everything needed for a successful public launch:
**New Documentation**
- SECURITY.md: Security policy and best practices
- CLAUDE.md: Complete agent instructions for contributing to beads
- Enhanced README with pain points, FAQ, troubleshooting sections
- Added Taskwarrior to comparison table with detailed explanation
**Installation**
- install.sh: One-liner installation script with platform detection
- Auto-detects OS/arch, tries go install, falls back to building from source
- Updated README with prominent installation instructions
**Examples** (2,268+ lines of working code)
- examples/python-agent/: Full Python implementation of agent workflow
- examples/bash-agent/: Shell script agent with colorized output
- examples/git-hooks/: Pre-commit, post-merge, post-checkout hooks with installer
- examples/claude-desktop-mcp/: Documentation for future MCP server integration
- examples/README.md: Overview of all examples
**Dogfooding**
- Initialized bd in beads project itself (.beads/beads.db)
- Created issues for roadmap (MCP server, migrations, demos, 1.0 milestone)
- Exported to .beads/issues.jsonl for git versioning
**Visual Assets**
- Added screenshot showing agent using beads to README intro
- Placed in .github/images/ following GitHub conventions
This addresses all launch readiness items:
✅ Security policy
✅ Working agent examples (Python, Bash)
✅ Git hooks for automation
✅ FAQ addressing skeptics
✅ Troubleshooting common issues
✅ Easy installation
✅ Dogfooding our own tool
✅ Pain points that create urgency
Ready to ship! 🚀🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
