Fixes#1049 - AGENTS.md referenced CLAUDE.md which doesn't exist on main.
Changes:
- "Key Sections in CLAUDE.md" -> "Key Sections"
- "See CLAUDE.md..." -> "See AGENT_INSTRUCTIONS.md..."
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The bd edit command opens an interactive editor ($EDITOR) which AI agents
cannot use. Added warnings to AGENTS.md, AGENT_INSTRUCTIONS.md, and
cmd/bd/AGENTS.md directing agents to use bd update with flags instead.
Fixes: bd-3ft33
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements bd mol distill to reverse the spawn operation:
- molecule → proto (spawn is proto → molecule)
Features:
- --as flag for custom proto title
- --var value=variable to replace concrete values with placeholders
- --dry-run to preview the distilled structure
- Preserves full subgraph structure and dependencies
- Adds template label to all cloned issues
Also updates AGENTS.md with landing checklist.
Closes: bd-iq19
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Move all agent instructions from AGENTS.md into CLAUDE.md, which
Claude Code reads automatically. AGENTS.md now just redirects.
Also remove MCP server from plugin.json - the plugin now uses
hooks-only mode for better token efficiency.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove the external MCP Agent Mail server integration that required
running a separate HTTP server and configuring environment variables.
The native `bd mail` system (stored as git-synced issues) remains
unchanged and is the recommended approach for inter-agent messaging.
Files removed:
- cmd/bd/message.go - Legacy `bd message` command
- integrations/beads-mcp/src/beads_mcp/mail.py, mail_tools.py
- lib/beads_mail_adapter.py - Python adapter library
- examples/go-agent/ - Agent Mail-focused example
- examples/python-agent/agent_with_mail.py, AGENT_MAIL_EXAMPLE.md
- docs/AGENT_MAIL*.md, docs/adr/002-agent-mail-integration.md
- tests/integration/test_agent_race.py, test_mail_failures.py, etc.
- tests/benchmarks/ - Agent Mail benchmarks
Updated documentation to remove Agent Mail references while keeping
native `bd mail` documentation intact.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add bd cleanup --ephemeral flag for transient message cleanup (bd-kwro.9)
- Add Ephemeral filter to IssueFilter type
- Add ephemeral filtering to SQLite storage queries
Tests (bd-kwro.10):
- Add internal/hooks/hooks_test.go for hook system
- Add cmd/bd/mail_test.go for mail commands
- Add internal/storage/sqlite/graph_links_test.go for graph links
Documentation (bd-kwro.11):
- Add docs/messaging.md for full messaging reference
- Add docs/graph-links.md for graph link types
- Update AGENTS.md with inter-agent messaging section
- Update CHANGELOG.md with all bd-kwro features
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Refine ExtractIssuePrefix to better distinguish hash IDs from English
words in multi-part issue IDs. Hash suffixes now require digits or be
exactly 3 chars, preventing "test", "gate", "part" from being treated
as hashes. This fixes prefix extraction for IDs like "vc-baseline-test".
Also updates git hooks to use -q flag and adds AGENTS.md documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24)
* docs: update Go version requirement to 1.24+ across docs
* docs: fix broken links to docs/ in npm-package/README.md
* docs: fix QUICKSTART.md path reference in AGENTS.md
Add section explaining the cognitive trap where temporal language
("Phase 1", "Step 1", "before") causes inverted dependency direction.
Includes examples of correct vs incorrect dependency setup and
verification using bd blocked.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Completes the deletion propagation epic (bd-imj) with all 9 subtasks:
- Cross-clone deletion propagation via deletions.jsonl
- bd deleted command for audit trail
- Auto-compact during sync (opt-in)
- Git history fallback with timeout and regex escaping
- JSON output for pruning results
- Integration tests for deletion scenarios
- Documentation in AGENTS.md, README.md, and docs/DELETIONS.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Move detailed event-driven daemon documentation to docs/DAEMON.md.
Keep only brief mention in AGENTS.md with reference to full docs.
Reduces duplication and improves documentation organization.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This implements the ability to separate bd-specific instructions from
project-specific instructions by generating a canonical BD_GUIDE.md file.
## Changes
1. Added `--output` flag to `bd onboard` command
- Generates version-stamped BD_GUIDE.md at specified path
- Includes both agentsContent and copilotInstructionsContent
- Auto-generated header warns against manual editing
2. Version tracking integration
- checkAndSuggestBDGuideUpdate() detects outdated BD_GUIDE.md
- Suggests regeneration when bd version changes
- Integrated with maybeShowUpgradeNotification()
3. Comprehensive test coverage
- Tests for BD_GUIDE.md generation
- Tests for version stamp validation
- Tests for content inclusion
4. Documentation updates
- Updated AGENTS.md with BD_GUIDE.md workflow
- Added regeneration instructions to upgrade workflow
## Benefits
- Clear separation of concerns (bd vs project instructions)
- Deterministic updates (no LLM involved)
- Git-trackable diffs show exactly what changed
- Progressive disclosure (agents read when needed)
## Usage
\`\`\`bash
# Generate BD_GUIDE.md
bd onboard --output .beads/BD_GUIDE.md
# After upgrading bd
bd onboard --output .beads/BD_GUIDE.md # Regenerate
\`\`\`
Closes bd-woro
Implements bd-hwmp and bd-5otr (part of epic bd-nxgk) to help AI agents
automatically detect and adapt to bd upgrades.
## Changes
### Documentation (bd-hwmp)
- Added "After Upgrading bd" section to AGENTS.md with step-by-step workflow
- Enhanced "Pro Tips for Agents" with upgrade detection guidance
- Documents bd info --whats-new and bd hooks install commands
- References GitHub Discussion #239
### Startup Hook (bd-5otr)
- Created examples/startup-hooks/bd-version-check.sh
- Auto-detects bd version changes via .beads/metadata.json
- Shows bd info --whats-new when upgrade detected
- Auto-updates outdated git hooks
- Handles edge cases (no jq, not in beads project, etc.)
- Created examples/startup-hooks/README.md with integration examples
- Claude Code, GitHub Copilot, Cursor integration patterns
- Comprehensive usage and troubleshooting guide
- Updated examples/README.md with new startup-hooks section
## Impact
Agents can now:
- Automatically detect bd upgrades at session start
- See what changed without re-reading all documentation
- Keep git hooks in sync automatically
- Adapt workflows based on new features
Works today with zero bd code changes required!
Related: #239🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes#340
Created AGENT_INSTRUCTIONS.md to house detailed operational instructions,
reducing AGENTS.md from 963 to 626 lines (~35% reduction).
Changes:
- New AGENT_INSTRUCTIONS.md with development, testing, and release procedures
- AGENTS.md now serves as quick overview with references to detailed docs
- Updated README.md link to "Landing the Plane" section
- Fixed broken team-workflow README links
Benefits:
- Prevents context pollution when multiple tools add instructions
- Better separation: quick reference vs detailed operations
- Enables tool-specific instruction files
- Maintains all content, just reorganized
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added prominent warning at the top of the Agent Mail section in AGENTS.md
to prevent AI agents from attempting to use mcp-agent-mail tools when the
server is not set up.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The previous instructions mentioned sync carefully but didn't emphasize that
git push is absolutely required for the plane to actually land. Multiple agents
have failed to push, leaving work uncommitted on the runway.
Changes:
- Added explicit 'git push' step with CRITICAL emphasis
- Added verification step to check 'up to date with origin/main'
- Updated example workflow to show push as mandatory step
- Added clear statement: 'The plane has NOT landed until git push completes'
The metaphor is obvious - if you don't push, the plane is still on the ground!
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add AGENT_MAIL_QUICKSTART.md: 5-minute setup guide
- Add examples/python-agent/AGENT_MAIL_EXAMPLE.md: working code examples
- Add examples/python-agent/agent_with_mail.py: runnable multi-agent demo
- Update README.md: add Agent Mail to features and docs index
- Update AGENTS.md: enhance with quickstart/example references
- Update examples README: add Agent Mail example to index
Amp-Thread-ID: https://ampcode.com/threads/T-5d5e711d-7b5f-42ca-b75a-5b6cd843ad98
Co-authored-by: Amp <amp@ampcode.com>
- Add --whats-new flag to bd info command
- Display agent-relevant changes from last 3 versions
- Support both human-readable and JSON output
- Add version changelog data structure with workflow-impacting changes
- Add comprehensive tests for version changes structure
- Update AGENTS.md with whats-new documentation
Helps agents efficiently learn what changed between bd versions without
re-reading full documentation. Addresses weekly major version releases
requiring workflow adaptations.
Closes bd-eiz9
Amp-Thread-ID: https://ampcode.com/threads/T-5fe7e93d-7398-41c5-94bf-e914f2b331dd
Co-authored-by: Amp <amp@ampcode.com>
- Add --analyze mode to export candidates without API key
- Add --apply mode to accept agent-provided summaries
- Move --auto mode for legacy AI-powered compaction
- Update documentation for new workflow
- Addresses GH #243 complaint about API key requirement
Implements bd-jx90: simple cleanup command without API key requirement.
Features:
- Delete all closed issues with --force
- Filter by age with --older-than N (days)
- Preview with --dry-run
- Cascade deletion with --cascade
- JSON output support
Usage:
bd cleanup --force # Delete all closed
bd cleanup --older-than 30 --force # Delete >30 days old
bd cleanup --dry-run # Preview
Closes bd-jx90
Amp-Thread-ID: https://ampcode.com/threads/T-8d905db0-4ec7-411e-95de-1f044219dc9c
Co-authored-by: Amp <amp@ampcode.com>
* bd sync: 2025-10-30 12:12:27
* Working on frontend
* bd sync: 2025-11-06 16:55:55
* feat: finish bd monitor human viewer
* Merge conflicts resolved and added tests
* bd sync: 2025-11-06 17:23:41
* bd sync: 2025-11-06 17:34:52
* feat: Add reload button and multiselect status filter to monitor
- Changed status filter from single select to multiselect with 'Open' selected by default
- Added reload button with visual feedback (hover/active states)
- Updated filterIssues() to handle multiple selected statuses
- Added reloadData() function that reloads both stats and issues
- Improved responsive design for mobile devices
- Filter controls now use flexbox layout with better spacing
* fix: Update monitor statistics to show Total, In Progress, Open, Closed
- Replaced 'Ready to Work' stat with 'In Progress' stat
- Reordered stats to show logical progression: Total -> In Progress -> Open -> Closed
- Updated loadStats() to fetch in-progress count from stats API
- Removed unnecessary separate API call for ready count
* fix: Correct API field names in monitor stats JavaScript
The JavaScript was using incorrect field names (stats.total, stats.by_status)
that don't match the actual types.Statistics struct which uses flat fields
with underscores (total_issues, in_progress_issues, etc).
Fixed by updating loadStats() to use correct field names:
- stats.total -> stats.total_issues
- stats.by_status?.['in-progress'] -> stats.in_progress_issues
- stats.by_status?.open -> stats.open_issues
- stats.by_status?.closed -> stats.closed_issues
Fixes beads-9
* bd sync: 2025-11-06 17:51:24
* bd sync: 2025-11-06 17:56:09
* fix: Make monitor require daemon to prevent SQLite locking
Implemented Option 1 from beads-eel: monitor now requires daemon and never
opens direct SQLite connection.
Changes:
- Added 'monitor' to noDbCommands list in main.go to skip normal DB initialization
- Added validateDaemonForMonitor() PreRun function that:
- Finds database path using beads.FindDatabasePath()
- Validates daemon is running and healthy
- Fails gracefully with clear error message if no daemon
- Only uses RPC connection, never opens SQLite directly
Benefits:
- Eliminates SQLite locking conflicts between monitor and daemon
- Users can now close/update issues via CLI while monitor runs
- Clear error messages guide users to start daemon first
Fixes beads-eel
* bd sync: 2025-11-06 18:03:50
* docs: Add bd daemons restart subcommand documentation
Added documentation for the 'bd daemons restart' subcommand across all documentation files:
- commands/daemons.md: Added full restart subcommand section with synopsis, description, arguments, flags, and examples
- README.md: Added restart examples to daemon management section
- AGENTS.md: Added restart examples with --json flag for agents
The restart command gracefully stops and starts a specific daemon by workspace path or PID,
useful after upgrading bd or when a daemon needs refreshing.
Fixes beads-11
* bd sync: 2025-11-06 18:13:16
* Separated the web ui from the general monitoring functionality
---------
Co-authored-by: Steve Yegge <stevey@sourcegraph.com>
- Changed all test commands to 'go test -short ./...'
- Clarified that full tests run in CI
- Updated: Code Standards, Before Committing, Landing the Plane, Building and Testing, Release Process
- Agents should only run short tests; CI runs full suite
- 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>
