- Add merge driver to bd init workflow in README.md
- Update AGENTS.md with auto-config details
- Document --skip-merge-driver flag
- Provide manual setup instructions
- Clarify beads-merge as alternative external tool
Completes bd-ggbc
- Created comprehensive migration guide at docs/MULTI_REPO_MIGRATION.md
- Covers OSS contributor, team, multi-phase, and persona workflows
- Step-by-step setup instructions with examples
- Configuration reference and troubleshooting
- Implemented bd migrate-issues command
- Move issues between repos with filtering (status/priority/labels/type)
- Dependency preservation with upstream/downstream/closure options
- Dry-run mode and strict validation
- Interactive confirmation with --yes override
- Updated README.md and AGENTS.md with migration guide links
Completes: bd-c3ei, bd-mlcz
Part of epic: bd-8rd (Migration and onboarding for multi-repo)
Amp-Thread-ID: https://ampcode.com/threads/T-c5a7a780-b05e-4cc3-a7c1-5de107821b7e
Co-authored-by: Amp <amp@ampcode.com>
- AGENTS.md: Updated 'landing the plane' section to encourage creative,
methodical conflict resolution instead of rigid step-by-step commands
- README.md: Added 'Configuring Your Own AGENTS.md' section recommending
that project maintainers add session-ending protocols to their own
AGENTS.md files to ensure proper database hygiene
- Add detailed installation steps for Git and Jujutsu users
- Explain 3-way merge algorithm and field-level merging
- Document configuration in .gitattributes and .jjconfig.toml
- Clarify how it prevents conflicts proactively vs resolving after
- Created bd-bzfy to track integration of beads-merge tool
Addresses code review feedback:
✅ P0 (Must Fix):
- Fix JSONL lookup to return LAST match, not FIRST (resurrection.go:160-162)
- Changed from early return to scan all matches and keep last
- Respects JSONL append-only semantics
✅ P1 (Should Fix):
- Add test for multiple JSONL versions
- TestTryResurrectParent_MultipleVersionsInJSONL verifies correct behavior
- Document error message change in CHANGELOG.md
- Old: "parent issue X does not exist"
- New: "parent issue X does not exist and could not be resurrected from JSONL history"
- Marked as breaking change for script parsers
✅ P2/P3 (Nice to Have):
- Add documentation to AGENTS.md explaining auto-resurrection behavior
- Document best-effort dependency resurrection
⏸️ Deferred (P1 - Optimize batch resurrection):
- Caching optimization deferred (no batch use cases currently)
All tests pass:
- Unit tests: internal/storage/sqlite/
- Integration test: TestImportWithDeletedParent
Created complete documentation suite for using beads with protected branches:
1. **docs/PROTECTED_BRANCHES.md** - Comprehensive 600+ line guide covering:
- Quick start and setup
- How git worktrees work
- Daily workflow for agents and humans
- Merging strategies (PR and direct)
- Troubleshooting common issues
- Platform-specific notes (GitHub, GitLab, Bitbucket)
- Advanced topics (CI/CD, multi-clone sync, etc.)
2. **AGENTS.md** - Added "Protected Branch Workflow" section:
- Quick reference for agents
- No changes needed to agent workflows
- Commands for setup and merging
- Link to detailed docs
3. **README.md** - Updated with:
- Protected branch support feature flag
- Quick start instructions with --branch flag
- Link to comprehensive guide
4. **examples/protected-branch/** - Working example with:
- Step-by-step demo
- Multi-clone sync workflow
- GitHub Actions integration example
- Directory structure explanation
- Troubleshooting tips
All commands verified:
- bd init --branch <name>
- bd config get/set sync.branch
- bd sync --status
- bd sync --merge
Documentation is platform-agnostic and works with GitHub, GitLab,
Bitbucket, or any git platform with branch protection.
Closes bd-5ce8
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive guidance for managing AI-generated planning documents
(Claude slop) to the bd onboard command. Addresses GitHub issue #196.
Changes:
- Add Managing AI-Generated Planning Documents section to onboard output
- Recommend using history/ directory for ephemeral planning files
- List common planning doc types (PLAN.md, IMPLEMENTATION.md, etc.)
- Provide .gitignore example and benefits explanation
- Add to Important Rules: Store AI planning docs in history/
- Update AGENTS.md with the same guidance to demonstrate the pattern
- Add comprehensive tests for onboard command
This uses inverted control: bd outputs guidance, AI agents intelligently
integrate it into their project's documentation (AGENTS.md, CLAUDE.md,
.cursorrules, etc.), respecting existing conventions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add bd migrate --inspect and bd info --schema examples to README.md
- Update QUICKSTART.md migration section with AI agent workflow
- Expand AGENTS.md with migration safety invariants explanation
- Clarify when and why to use inspection before migrating
Makes the new AI-supervised migration features discoverable.
Amp-Thread-ID: https://ampcode.com/threads/T-de7e1141-87ac-4b4a-9cea-1b7bc4d51da9
Co-authored-by: Amp <amp@ampcode.com>
- Removed nextSequentialID() and getIDMode() functions
- Removed issue_counters table from schema
- Made SyncAllCounters() a no-op for backward compatibility
- Simplified ID generation to hash-only (adaptive length)
- Removed id_mode config setting
- Removed sequential ID tests and migration code
- Updated CONFIG.md and AGENTS.md to remove sequential ID references
Follow-up bd-2a70 will remove obsolete test files and renumber command.
- Move RELEASING.md and LINTING.md to docs/ (maintainer-only content)
- Delete WORKFLOW.md (agent workflow content belongs in AGENTS.md)
- Delete TEXT_FORMATS.md (technical details belong in ADVANCED.md)
- Update all cross-references to point to new locations
- Keep CLAUDE.md (required by Claude Code)
Reduces root-level docs from 20 to 16 files with clearer organization.
Amp-Thread-ID: https://ampcode.com/threads/T-fe1db4f3-16c6-4a79-8887-c7f4c1f11c43
Co-authored-by: Amp <amp@ampcode.com>
- Implement bd migrate command with detection, version checking, and cleanup
- Update daemon to suggest bd migrate for version mismatches
- Enhance CLI version warnings to recommend bd migrate
- Add comprehensive tests for migration scenarios
- Document migration workflow in QUICKSTART.md and AGENTS.md
Completes bd-164 and epic bd-159
Amp-Thread-ID: https://ampcode.com/threads/T-34ea4682-8c48-44c2-8421-dc40f867773b
Co-authored-by: Amp <amp@ampcode.com>
Implements bd-145. Users can now easily determine which database file bd is using
and check daemon connection status.
Features:
- Shows absolute database path
- Displays daemon status (connected/mode/health/version)
- Shows issue count
- Supports --json output for programmatic use
- Works in both daemon and direct modes
Example output:
bd info # Human-readable
bd info --json # JSON for agents
bd info --no-daemon # Force direct mode
Updated documentation in README.md and AGENTS.md.
Amp-Thread-ID: https://ampcode.com/threads/T-a33c0762-f800-4fea-9510-6a803d8aece8
Co-authored-by: Amp <amp@ampcode.com>
- Added --flush-only flag to bd sync command
- Created pre-commit hook to flush pending changes before commit
- Created post-merge hook to import changes after pull/merge
- Added install script for easy setup
- Updated AGENTS.md with git hooks workflow
- Resolves race condition where daemon auto-flush fires after commit
Amp-Thread-ID: https://ampcode.com/threads/T-00b80d3a-4194-4c75-a60e-25a318cf9f91
Co-authored-by: Amp <amp@ampcode.com>
- New 'bd duplicates' command finds content duplicates across database
- Groups by content hash (title, description, design, acceptance criteria)
- Chooses merge target by reference count or smallest ID
- Supports --auto-merge and --dry-run flags
- Added --dedupe-after flag to 'bd import' for post-import detection
- Comprehensive test coverage for duplicate detection
- Updated AGENTS.md and ADVANCED.md with usage examples
Amp-Thread-ID: https://ampcode.com/threads/T-6f99566f-c979-43ed-bd8f-5aa38b0f6191
Co-authored-by: Amp <amp@ampcode.com>
- Stub out 'bd repos' command with deprecation message
- Remove 140+ lines of global daemon/multi-repo docs from ADVANCED.md
- Add architecture section explaining daemon/MCP/beads roles (LSP model)
- Update AGENTS.md, MCP README, FAQ.md to emphasize per-project daemons
- Update commands/daemon.md and commands/repos.md
Closes#140
Global daemon was removed in v0.16.0 due to cross-project pollution
risks. bd now uses per-project local daemons (one per workspace) for
complete database isolation, following LSP architecture patterns.
Amp-Thread-ID: https://ampcode.com/threads/T-c45147dc-8939-43bf-8fbd-303ed4a8d845
Co-authored-by: Amp <amp@ampcode.com>
Implements automatic daemon version detection and restart when client
and daemon versions are incompatible. Eliminates need for manual
'bd daemon --stop' after upgrades.
Changes:
- Check daemon version during health check in PersistentPreRun
- Auto-restart mismatched daemon or fall back to direct mode
- Check version when starting daemon, auto-stop old daemon if incompatible
- Robust restart logic: sets working dir, cleans stale sockets, reaps processes
- Uses waitForSocketReadiness helper for reliable startup detection
- Updated AGENTS.md with version management documentation
Closes bd-89
Amp-Thread-ID: https://ampcode.com/threads/T-231a3701-c9c8-49e4-a1b0-e67c94e5c365
Co-authored-by: Amp <amp@ampcode.com>
- Implement robust worktree detection using git-dir vs git-common-dir comparison
- Add prominent warning when daemon mode is active in a worktree
- Warn in 3 places: initial connection, auto-start, and daemon start command
- Show shared database path and clarify BEADS_AUTO_START_DAEMON behavior
- Document limitations and solutions in README.md and AGENTS.md
- Add comprehensive tests for detection and path truncation
Fixes#55
Amp-Thread-ID: https://ampcode.com/threads/T-254eb9e3-1a42-42d7-afdf-b7ca2d2dcb8b
Co-authored-by: Amp <amp@ampcode.com>
Prevents agents from creating duplicate low-numbered issues when starting
with a fresh git clone that already has issues.jsonl in git history.
Changes:
- bd init now checks for existing issues in git after DB creation
- Auto-imports with collision resolution if found
- Updates AGENTS.md to simplify onboarding (just 'bd init')
Fixes the scenario where:
1. Fresh clone has .beads/issues.jsonl in git (212 issues)
2. Agent runs bd init (creates empty DB)
3. Agent starts creating bd-1, bd-2, etc (collisions with git)
Now bd init automatically imports all issues from git on first run.
Amp-Thread-ID: https://ampcode.com/threads/T-8a41f14d-d4c3-4c50-a18b-5f112110f138
Co-authored-by: Amp <amp@ampcode.com>
- Remove ~/.beads/bd.sock fallback in getSocketPath()
- Always return local socket path (.beads/bd.sock)
- Add migration warning if old global socket exists
- Update AGENTS.md to remove global daemon references
- Document breaking change in CHANGELOG.md
- Fix test isolation: tests now use temp .beads dir and chdir
Prevents cross-project daemon connections and database pollution.
Each project must use its own local daemon.
Amp-Thread-ID: https://ampcode.com/threads/T-c4454192-39c6-4c67-96a9-675cbfc4db92
Co-authored-by: Amp <amp@ampcode.com>
- Add checkAndAutoImport() that detects empty DB with issues in git
- Automatically imports from git HEAD:.beads/issues.jsonl
- Integrated into list, ready, and stats commands
- Zero cognitive load for agents in fresh clones
- Makes JSONL truly the source of truth
- DB becomes ephemeral cache that auto-rebuilds
Also:
- Update AGENTS.md onboarding section with import instructions
- Merge PR #98 (enhanced .gitignore)
Amp-Thread-ID: https://ampcode.com/threads/T-ffcb5e95-e5a0-486b-a0ae-ce8bd861ab9d
Co-authored-by: Amp <amp@ampcode.com>
- Refactor bd onboard to output instructions instead of doing string replacement
- Leverage agent intelligence to naturally integrate bd into documentation
- Bootstrap via 'BEFORE ANYTHING ELSE: run bd onboard' in AGENTS.md
- Agent receives formatted instructions to update AGENTS.md and CLAUDE.md
- More agentic approach - adapts to existing project structure
- Update README with new bootstrap workflow
Amp-Thread-ID: https://ampcode.com/threads/T-d70fd1bf-8d44-48b6-bb55-5ae49efb23b8
Co-authored-by: Amp <amp@ampcode.com>
Clarify that using multiple MCP servers (beads-adar, beads-wyvern, etc)
causes workspace routing issues where AI may select wrong server.
Recommend single MCP server config that routes via global daemon based on
current working directory.
Fixes bd-164
Amp-Thread-ID: https://ampcode.com/threads/T-b3def94f-e784-4874-b65c-af5b87ad6cdd
Co-authored-by: Amp <amp@ampcode.com>
- Implement shouldUseGlobalDaemon() with multi-repo detection
- Auto-detect 4+ beads repos and prefer global daemon
- Support BEADS_PREFER_GLOBAL_DAEMON env var for explicit control
- Add 'bd daemon --migrate-to-global' migration helper
- Update auto-start logic to use global daemon when appropriate
- Update documentation in AGENTS.md and README.md
Amp-Thread-ID: https://ampcode.com/threads/T-9af9372d-f3f3-4698-920d-e5ad1486d849
Co-authored-by: Amp <amp@ampcode.com>
