diff --git a/.beads/BD_GUIDE.md b/.beads/BD_GUIDE.md new file mode 100644 index 00000000..a053b9d8 --- /dev/null +++ b/.beads/BD_GUIDE.md @@ -0,0 +1,291 @@ + + + +# BD (Beads) Guide for AI Agents + +This file contains canonical bd (beads) workflow instructions for AI agents. +It is auto-generated and version-stamped to track bd upgrades. + +> **For project-specific instructions**, see AGENTS.md in the repository root. +> This file only covers bd tool usage, not project-specific workflows. + +--- + +## Issue Tracking with bd (beads) + +**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. + +### Why bd? + +- Dependency-aware: Track blockers and relationships between issues +- Git-friendly: Auto-syncs to JSONL for version control +- Agent-optimized: JSON output, ready work detection, discovered-from links +- Prevents duplicate tracking systems and confusion + +### Quick Start + +**Check for ready work:** +```bash +bd ready --json +``` + +**Create new issues:** +```bash +bd create "Issue title" -t bug|feature|task -p 0-4 --json +bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json +``` + +**Claim and update:** +```bash +bd update bd-42 --status in_progress --json +bd update bd-42 --priority 1 --json +``` + +**Complete work:** +```bash +bd close bd-42 --reason "Completed" --json +``` + +### Issue Types + +- `bug` - Something broken +- `feature` - New functionality +- `task` - Work item (tests, docs, refactoring) +- `epic` - Large feature with subtasks +- `chore` - Maintenance (dependencies, tooling) + +### Priorities + +- `0` - Critical (security, data loss, broken builds) +- `1` - High (major features, important bugs) +- `2` - Medium (default, nice-to-have) +- `3` - Low (polish, optimization) +- `4` - Backlog (future ideas) + +### Workflow for AI Agents + +1. **Check ready work**: `bd ready` shows unblocked issues +2. **Claim your task**: `bd update --status in_progress` +3. **Work on it**: Implement, test, document +4. **Discover new work?** Create linked issue: + - `bd create "Found bug" -p 1 --deps discovered-from:` +5. **Complete**: `bd close --reason "Done"` +6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state + +### Auto-Sync + +bd automatically syncs with git: +- Exports to `.beads/issues.jsonl` after changes (5s debounce) +- Imports from JSONL when newer (e.g., after `git pull`) +- No manual export/import needed! + +### GitHub Copilot Integration + +If using GitHub Copilot, also create `.github/copilot-instructions.md` for automatic instruction loading. +Run `bd onboard` to get the content, or see step 2 of the onboard instructions. + +### MCP Server (Recommended) + +If using Claude or MCP-compatible clients, install the beads MCP server: + +```bash +pip install beads-mcp +``` + +Add to MCP config (e.g., `~/.config/claude/config.json`): +```json +{ + "beads": { + "command": "beads-mcp", + "args": [] + } +} +``` + +Then use `mcp__beads__*` functions instead of CLI commands. + +### Managing AI-Generated Planning Documents + +AI assistants often create planning and design documents during development: +- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md +- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md +- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files + +**Best Practice: Use a dedicated directory for these ephemeral files** + +**Recommended approach:** +- Create a `history/` directory in the project root +- Store ALL AI-generated planning/design docs in `history/` +- Keep the repository root clean and focused on permanent project files +- Only access `history/` when explicitly asked to review past planning + +**Example .gitignore entry (optional):** +``` +# AI planning documents (ephemeral) +history/ +``` + +**Benefits:** +- ✅ Clean repository root +- ✅ Clear separation between ephemeral and permanent documentation +- ✅ Easy to exclude from version control if desired +- ✅ Preserves planning history for archeological research +- ✅ Reduces noise when browsing the project + +### Important Rules + +- ✅ Use bd for ALL task tracking +- ✅ Always use `--json` flag for programmatic use +- ✅ Link discovered work with `discovered-from` dependencies +- ✅ Check `bd ready` before asking "what should I work on?" +- ✅ Store AI planning docs in `history/` directory +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT use external issue trackers +- ❌ Do NOT duplicate tracking systems +- ❌ Do NOT clutter repo root with planning documents + +For more details, see README.md and QUICKSTART.md. + +--- + +# GitHub Copilot Instructions for Beads + +## Project Overview + +**beads** (command: `bd`) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking. + +**Key Features:** +- Dependency-aware issue tracking +- Auto-sync with Git via JSONL +- AI-optimized CLI with JSON output +- Built-in daemon for background operations +- MCP server integration for Claude and other AI assistants + +## Tech Stack + +- **Language**: Go 1.21+ +- **Storage**: SQLite (internal/storage/sqlite/) +- **CLI Framework**: Cobra +- **Testing**: Go standard testing + table-driven tests +- **CI/CD**: GitHub Actions +- **MCP Server**: Python (integrations/beads-mcp/) + +## Coding Guidelines + +### Testing +- Always write tests for new features +- Use `BEADS_DB=/tmp/test.db` to avoid polluting production database +- Run `go test -short ./...` before committing +- Never create test issues in production DB (use temporary DB) + +### Code Style +- Run `golangci-lint run ./...` before committing +- Follow existing patterns in `cmd/bd/` for new commands +- Add `--json` flag to all commands for programmatic use +- Update docs when changing behavior + +### Git Workflow +- Always commit `.beads/issues.jsonl` with code changes +- Run `bd sync` at end of work sessions +- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency) + +## Issue Tracking with bd + +**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists. + +### Essential Commands + +```bash +# Find work +bd ready --json # Unblocked issues +bd stale --days 30 --json # Forgotten issues + +# Create and manage +bd create "Title" -t bug|feature|task -p 0-4 --json +bd update --status in_progress --json +bd close --reason "Done" --json + +# Search +bd list --status open --priority 1 --json +bd show --json + +# Sync (CRITICAL at end of session!) +bd sync # Force immediate export/commit/push +``` + +### Workflow + +1. **Check ready work**: `bd ready --json` +2. **Claim task**: `bd update --status in_progress` +3. **Work on it**: Implement, test, document +4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from: --json` +5. **Complete**: `bd close --reason "Done" --json` +6. **Sync**: `bd sync` (flushes changes to git immediately) + +### Priorities + +- `0` - Critical (security, data loss, broken builds) +- `1` - High (major features, important bugs) +- `2` - Medium (default, nice-to-have) +- `3` - Low (polish, optimization) +- `4` - Backlog (future ideas) + +## Project Structure + +``` +beads/ +├── cmd/bd/ # CLI commands (add new commands here) +├── internal/ +│ ├── types/ # Core data types +│ └── storage/ # Storage layer +│ └── sqlite/ # SQLite implementation +├── integrations/ +│ └── beads-mcp/ # MCP server (Python) +├── examples/ # Integration examples +├── docs/ # Documentation +└── .beads/ + ├── beads.db # SQLite database (DO NOT COMMIT) + └── issues.jsonl # Git-synced issue storage +``` + +## Available Resources + +### MCP Server (Recommended) +Use the beads MCP server for native function calls instead of shell commands: +- Install: `pip install beads-mcp` +- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc. +- See `integrations/beads-mcp/README.md` + +### Scripts +- `./scripts/bump-version.sh --commit` - Update all version files atomically +- `./scripts/release.sh ` - Complete release workflow +- `./scripts/update-homebrew.sh ` - Update Homebrew formula + +### Key Documentation +- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features) +- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases +- **README.md** - User-facing documentation +- **docs/CLI_REFERENCE.md** - Complete command reference + +## Important Rules + +- ✅ Use bd for ALL task tracking +- ✅ Always use `--json` flag for programmatic use +- ✅ Run `bd sync` at end of sessions +- ✅ Test with `BEADS_DB=/tmp/test.db` +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT create test issues in production DB +- ❌ Do NOT commit `.beads/beads.db` (JSONL only) + +--- + +**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)** + +--- + +**Generated by bd v0.24.2** + +To regenerate this file after upgrading bd: +```bash +bd onboard --output .beads/BD_GUIDE.md +``` diff --git a/.beads/beads.jsonl b/.beads/beads.jsonl index 08cf5eb2..0b5a8497 100644 --- a/.beads/beads.jsonl +++ b/.beads/beads.jsonl @@ -22,7 +22,7 @@ {"id":"bd-0fvq","content_hash":"6fb6e394efe3010fd5d9213669417e5f6376017de4187988d5a6fd0d36c80b40","title":"bd doctor should recommend bd prime migration for existing repos","description":"bd doctor should detect old beads integration patterns and recommend migrating to bd prime approach.\n\n## Current behavior\n- bd doctor checks if Claude hooks are installed globally\n- Doesn't check project-level integration (AGENTS.md, CLAUDE.md)\n- Doesn't recommend migration for repos using old patterns\n\n## Desired behavior\nbd doctor should detect and suggest:\n\n1. **Old slash command pattern detected**\n - Check for /beads:* references in AGENTS.md, CLAUDE.md\n - Suggest: These slash commands are deprecated, use bd prime hooks instead\n \n2. **No agent documentation**\n - Check if AGENTS.md or CLAUDE.md exists\n - Suggest: Run 'bd onboard' or 'bd setup claude' to document workflow\n \n3. **Old MCP-only pattern**\n - Check for instructions to use MCP tools but no bd prime hooks\n - Suggest: Add bd prime hooks for better token efficiency\n\n4. **Migration path**\n - Show: 'Run bd setup claude to add SessionStart/PreCompact hooks'\n - Show: 'Update AGENTS.md to reference bd prime instead of slash commands'\n\n## Example output\n\n⚠ Warning: Old beads integration detected in CLAUDE.md\n Found: /beads:* slash command references (deprecated)\n Recommend: Migrate to bd prime hooks for better token efficiency\n Fix: Run 'bd setup claude' and update CLAUDE.md\n\n💡 Tip: bd prime + hooks reduces token usage by 80-99% vs slash commands\n MCP mode: ~50 tokens vs ~10.5k for full MCP scan\n CLI mode: ~1-2k tokens with automatic context recovery\n\n## Benefits\n- Helps existing repos adopt new best practices\n- Clear migration path for users\n- Better token efficiency messaging","status":"open","priority":2,"issue_type":"feature","created_at":"2025-11-12T03:20:25.567748-08:00","updated_at":"2025-11-12T03:20:25.567748-08:00","source_repo":"."} {"id":"bd-0kz8","content_hash":"b641c9c097cdeaa44b090d632eac2f89d89a5c3579f0ea58c8b02320b0fa49f7","title":"Fix default .beads/.gitignore to ignore merge artifacts (GH #274)","description":"Updated the default .gitignore template created by `bd init` to properly ignore merge artifacts and fix overly broad patterns.\n\nChanges:\n- Added `*.db?*` pattern for database files with query strings\n- Added explicit patterns for merge artifacts: beads.{base,left,right}.{jsonl,meta.json}\n- Changed `!*.jsonl` to `!issues.jsonl` to avoid including merge artifact JSONL files\n\nThis fixes GitHub issue #274 reported by rscorer.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-09T11:23:25.595551-08:00","updated_at":"2025-11-09T11:23:28.780095-08:00","closed_at":"2025-11-09T11:23:28.780095-08:00","source_repo":"."} {"id":"bd-0qeg","content_hash":"50f35dcc442b133e766668f3201f5e4820a66dd05cfac1c5d30595d11806f98e","title":"Fix bd doctor hash ID detection for short all-numeric hashes","description":"bd doctor incorrectly flags hash-based IDs as sequential when they are short (3-4 chars) and all-numeric (e.g., pf-158).\n\nRoot cause: isHashID() in cmd/bd/migrate_hash_ids.go:328-358 uses faulty heuristic:\n- For IDs \u003c 5 chars, only returns true if contains letters\n- But base36 hash IDs can be 3+ chars and all-numeric (MinLength: 3)\n- Example: pf-158 is valid hash ID but flagged as sequential\n\nFix: Check multiple IDs (10-20 samples) instead of single-ID pattern matching:\n- Sample IDs across database \n- Check majority pattern (sequential vs hash format)\n- Sequential: 1-4 digits (bd-1, bd-2...)\n- Hash: 3-8 chars base36 (pf-158, pf-3s9...)\n\nImpact: False positive warnings in bd doctor output","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-11-16T13:45:20.733761-08:00","updated_at":"2025-11-16T14:27:48.143485-08:00","closed_at":"2025-11-16T14:27:48.143485-08:00","source_repo":"."} -{"id":"bd-0tr0","content_hash":"6bcdf8cba6934e0d8b703a2c5a35297db3bf31c83513d78cdd633c05a737973d","title":"Claude Code frequently creates issues with empty descriptions","description":"## Problem\n\nUsers report that Claude Code creates beads issues with titles but no descriptions when asked to analyze code and create issues. Discussion #366 on GitHub highlights this.\n\n## Evidence\n\nAnalysis of our own projects shows significant rates of empty descriptions:\n- ~/src/beads: 110 empty / 630 total (17.5%)\n- ~/wyvern: 8 empty / 119 total (6.7%)\n- ~/src/vc: 3 empty / 170 total (1.8%)\n\nExamples of real issues with no description:\n- [deleted:bd-5qim]: Optimize GetReadyWork performance\n- bd-ge7/vc-7kln: Improve test coverage (appears in multiple projects)\n- Package-specific test coverage tasks (bd-m0w, bd-4h3, bd-t3b, bd-e92)\n- Wyvern testing tasks (wy-3hx, wy-qc9, wy-66)\n\nMany date from Nov 20-21, suggesting batch creation operations.\n\n## Impact\n\n- Issues lack context for future work\n- Harder to prioritize without understanding scope\n- Need manual follow-up to add details\n- Poor workflow experience for users\n\n## Related\n\n- GitHub Discussion #366: https://github.com/steveyegge/beads/discussions/366","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-23T13:59:45.931488-08:00","updated_at":"2025-11-23T20:22:04.259399-08:00","source_repo":"."} +{"id":"bd-0tr0","content_hash":"6bcdf8cba6934e0d8b703a2c5a35297db3bf31c83513d78cdd633c05a737973d","title":"Claude Code frequently creates issues with empty descriptions","description":"## Problem\n\nUsers report that Claude Code creates beads issues with titles but no descriptions when asked to analyze code and create issues. Discussion #366 on GitHub highlights this.\n\n## Evidence\n\nAnalysis of our own projects shows significant rates of empty descriptions:\n- ~/src/beads: 110 empty / 630 total (17.5%)\n- ~/wyvern: 8 empty / 119 total (6.7%)\n- ~/src/vc: 3 empty / 170 total (1.8%)\n\nExamples of real issues with no description:\n- [deleted:bd-5qim]: Optimize GetReadyWork performance\n- bd-ge7/vc-7kln: Improve test coverage (appears in multiple projects)\n- Package-specific test coverage tasks (bd-m0w, bd-4h3, bd-t3b, bd-e92)\n- Wyvern testing tasks (wy-3hx, wy-qc9, wy-66)\n\nMany date from Nov 20-21, suggesting batch creation operations.\n\n## Impact\n\n- Issues lack context for future work\n- Harder to prioritize without understanding scope\n- Need manual follow-up to add details\n- Poor workflow experience for users\n\n## Related\n\n- GitHub Discussion #366: https://github.com/steveyegge/beads/discussions/366","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-23T13:59:45.931488-08:00","updated_at":"2025-11-23T21:11:04.522351-08:00","closed_at":"2025-11-23T21:11:04.522351-08:00","source_repo":"."} {"id":"bd-0vfe","content_hash":"e142bd97d91f70e50e8fea0681d8cdcffb17f17fdbd4c106d56607e243005d21","title":"Blocked issue","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-07T19:07:17.105974-08:00","updated_at":"2025-11-07T22:07:17.342098-08:00","closed_at":"2025-11-07T21:55:09.425545-08:00","source_repo":"."} {"id":"bd-1022","content_hash":"0b712a337844711597d2dd950d27d4c032a3b746a27f44326d62db740f5944e9","title":"Use external_ref as primary matching key for import updates","description":"Enable re-syncing from external systems (Jira, GitHub, Linear) by using external_ref as the primary matching key during imports. Currently imports treat any content change as a collision, making it impossible to sync updates from external systems without creating duplicates.\n\nSee GH #142 for detailed proposal and implementation plan.\n\nKey changes needed:\n1. Add findByExternalRef() query function\n2. Update DetectCollisions() to match by external_ref first\n3. Update import_shared.go to update existing issues when external_ref matches\n4. Add index on external_ref for performance\n5. Preserve local issues (no external_ref) from being overwritten\n\nThis enables hybrid workflows: import external backlog, break down with local tasks, re-sync anytime.","notes":"## Code Review Complete ✅\n\n**Overall Assessment**: EXCELLENT - Production ready\n\n### Implementation Quality\n- ✓ Clean architecture with proper interface extension\n- ✓ Dual backend support (SQLite + Memory)\n- ✓ Smart matching priority: external_ref → ID → content hash\n- ✓ O(1) lookups with database index\n- ✓ Timestamp-based conflict resolution\n- ✓ Comprehensive test coverage (11 test cases)\n\n### Follow-up Issues Filed\nHigh Priority (P2):\n- bd-897a: Add UNIQUE constraint on external_ref column\n- bd-7315: Add validation for duplicate external_ref in batch imports\n\nMedium Priority (P3):\n- bd-f9a1: Add index usage verification test\n- bd-3f6a: Add concurrent import race condition tests\n\nLow Priority (P4):\n- bd-e166: Improve timestamp comparison readability\n- bd-9e23: Optimize Memory backend with index\n- bd-537e: Add external_ref change tracking\n- bd-df11: Add import metrics\n- bd-9f4a: Document external_ref in content hash\n\n### Key Features\n✅ External systems (Jira, GitHub, Linear) can re-sync without duplicates\n✅ Hybrid workflows: import external backlog, add local tasks, re-sync anytime\n✅ Local issues protected from being overwritten\n✅ Timestamp checking ensures only newer updates applied\n✅ Performance optimized with database index\n\n**Confidence Level**: 95% - Ship it! 🚀","status":"closed","priority":0,"issue_type":"feature","created_at":"2025-11-02T14:55:56.355813-08:00","updated_at":"2025-11-02T15:34:56.634126-08:00","closed_at":"2025-11-02T15:27:44.810375-08:00","source_repo":"."} {"id":"bd-1048","content_hash":"1a889d79a98f8c0919f99094736ee7c856c6d8a2ee062a0add49ce2c06c40174","title":"Daemon crashes silently on RPC query after startup","description":"The daemon fails to handle 'show' RPC commands when:\n1) JSONL is newer than database (needs import)\n2) git pull fails due to uncommitted changes\n\nSymptoms:\n- Daemon appears to run (ps shows process)\n- 'bd list' and other commands work fine \n- 'bd show \u003cid\u003e' returns \"failed to read response: EOF\"\n- No panic or error logged in daemon.log\n\nRoot cause likely: auto-import deadlock or state corruption when import is blocked by git conflicts.\n\nWorkaround: \n- Restart daemon after syncing git state (commit/push changes)\n- OR use --no-daemon flag for all commands\n\nThe panic recovery added in server_lifecycle_conn.go:183 didn't catch any panics, confirming this isn't a panic-based crash.","notes":"Root cause found and fixed: Two bugs - (1) nil pointer check missing in handleShow causing panic, (2) double JSON encoding in show.go ID resolution. Both fixed. bd show now works with daemon.","status":"closed","priority":0,"issue_type":"bug","created_at":"2025-11-02T17:05:03.658333-08:00","updated_at":"2025-11-03T12:08:12.947672-08:00","closed_at":"2025-11-03T12:08:12.947676-08:00","source_repo":"."} @@ -647,7 +647,7 @@ {"id":"bd-wfmw","content_hash":"21706f1701be9fb51fa9e17d1dded6343bc2585e4bdb608239a20c5853d00220","title":"Integration Layer Implementation","description":"Build the adapter layer that makes Agent Mail optional and non-intrusive.","notes":"Progress: bd-m9th (Python adapter library) completed with full test coverage. Next: bd-fzbg (update python-agent example with Agent Mail integration).","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-11-07T22:42:09.356429-08:00","updated_at":"2025-11-08T00:20:30.888756-08:00","closed_at":"2025-11-08T00:20:30.888756-08:00","source_repo":".","dependencies":[{"issue_id":"bd-wfmw","depends_on_id":"bd-spmx","type":"blocks","created_at":"2025-11-07T22:42:09.357488-08:00","created_by":"daemon"}]} {"id":"bd-wgu4","content_hash":"31cf5cc105fee5de26f4c2756b8368c90b18eb5f65c656eb0d90f96b23daf21d","title":"Standardize daemon detection: use tryDaemonLock probe before RPC","description":"Before attempting RPC connection, call tryDaemonLock() to check if lock is held:\n- If lock NOT held: skip RPC attempt (no daemon running)\n- If lock IS held: proceed with RPC + short timeout\n\nThis is extremely cheap and eliminates unnecessary connection attempts.\n\nApply across all client entry points that probe for daemon.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-07T16:42:12.709802-08:00","updated_at":"2025-11-07T20:15:23.282181-08:00","closed_at":"2025-11-07T20:15:23.282181-08:00","source_repo":".","dependencies":[{"issue_id":"bd-wgu4","depends_on_id":"bd-ndyz","type":"discovered-from","created_at":"2025-11-07T16:42:12.710564-08:00","created_by":"daemon"}]} {"id":"bd-wh24","content_hash":"86122b8c5ab2eae17b7d6ab92f0f21a40f2c3ad733f6a1ee40376018d792ff99","title":"Fix Windows test failure: File permissions in TestAtomicWriteFile","description":"On Windows, file permissions work differently. The test expects 0600 but gets 0666. Windows doesn't support Unix-style file permissions in the same way. Need to either skip this check on Windows or adjust expectations.\n\nTest failure: utils_test.go:39: file permissions mismatch: got 666, want 600\n\nRoot cause: Windows filesystem doesn't support Unix-style permission bits. Need to use runtime.GOOS check or skip permission validation on Windows.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-23T20:16:14.190555-08:00","updated_at":"2025-11-23T20:16:14.190555-08:00","source_repo":"."} -{"id":"bd-woro","content_hash":"c638f71927d96ea8e8f8aeeb9f8bcd236241124fbaf1589d2b62977b64db3ebb","title":"Separate canonical BD_GUIDE.md from AGENTS.md","description":"Create architectural separation between bd-specific instructions and project-specific instructions.\n\n## Problem\nCurrently AGENTS.md mixes:\n- bd tool documentation (changes with bd upgrades)\n- Project-specific workflow (stable, manually maintained)\n\nThis makes it hard to update bd instructions without touching project docs.\n\n## Solution\n1. Generate .beads/BD_GUIDE.md from 'bd onboard' output\n2. Mark it as auto-generated (never manually edit)\n3. Version-stamp header with bd version\n4. AGENTS.md references it instead of duplicating content\n5. Auto-update BD_GUIDE.md when bd version changes\n\n## Implementation\n- Add 'bd onboard --output .beads/BD_GUIDE.md' option\n- Detect version changes and offer to regenerate\n- Add header: '\u003c!-- Auto-generated by bd v0.24.2 - DO NOT EDIT --\u003e'\n- Update AGENTS.md to reference BD_GUIDE.md\n\n## Benefits\n- Clear separation of concerns\n- Deterministic updates (no agent LLM involved)\n- Git-trackable diffs show exactly what changed\n- Progressive disclosure (agents read when needed)\n\n## Acceptance Criteria\n- BD_GUIDE.md auto-generated and version-stamped\n- AGENTS.md references it appropriately\n- Upgrade workflow auto-updates BD_GUIDE.md\n- Git diffs clearly show bd instruction changes\n","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-23T16:21:55.451925-08:00","updated_at":"2025-11-23T16:21:55.451925-08:00","source_repo":".","dependencies":[{"issue_id":"bd-woro","depends_on_id":"bd-nxgk","type":"parent-child","created_at":"2025-11-23T16:21:55.453758-08:00","created_by":"daemon"}]} +{"id":"bd-woro","content_hash":"ea0cffdac7fcc712387fbeece501de3e8d6be739822141bd48ea8a5b953be156","title":"Separate canonical BD_GUIDE.md from AGENTS.md","description":"Create architectural separation between bd-specific instructions and project-specific instructions.\n\n## Problem\nCurrently AGENTS.md mixes:\n- bd tool documentation (changes with bd upgrades)\n- Project-specific workflow (stable, manually maintained)\n\nThis makes it hard to update bd instructions without touching project docs.\n\n## Solution\n1. Generate .beads/BD_GUIDE.md from 'bd onboard' output\n2. Mark it as auto-generated (never manually edit)\n3. Version-stamp header with bd version\n4. AGENTS.md references it instead of duplicating content\n5. Auto-update BD_GUIDE.md when bd version changes\n\n## Implementation\n- Add 'bd onboard --output .beads/BD_GUIDE.md' option\n- Detect version changes and offer to regenerate\n- Add header: '\u003c!-- Auto-generated by bd v0.24.2 - DO NOT EDIT --\u003e'\n- Update AGENTS.md to reference BD_GUIDE.md\n\n## Benefits\n- Clear separation of concerns\n- Deterministic updates (no agent LLM involved)\n- Git-trackable diffs show exactly what changed\n- Progressive disclosure (agents read when needed)\n\n## Acceptance Criteria\n- BD_GUIDE.md auto-generated and version-stamped\n- AGENTS.md references it appropriately\n- Upgrade workflow auto-updates BD_GUIDE.md\n- Git diffs clearly show bd instruction changes\n","status":"in_progress","priority":3,"issue_type":"feature","created_at":"2025-11-23T16:21:55.451925-08:00","updated_at":"2025-11-23T21:11:28.757382-08:00","source_repo":".","dependencies":[{"issue_id":"bd-woro","depends_on_id":"bd-nxgk","type":"parent-child","created_at":"2025-11-23T16:21:55.453758-08:00","created_by":"daemon"}]} {"id":"bd-wpkz","content_hash":"58003aaff85c85ba5c314fb5b253e0b79094484059a8fecedb9474ea4f984458","title":"Run tests to ensure refactoring didn't break anything","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-23T18:08:17.264759-08:00","updated_at":"2025-11-23T18:15:22.990153-08:00","closed_at":"2025-11-23T18:15:22.990153-08:00","source_repo":".","dependencies":[{"issue_id":"bd-wpkz","depends_on_id":"bd-9csf","type":"blocks","created_at":"2025-11-23T18:08:30.928086-08:00","created_by":"daemon"},{"issue_id":"bd-wpkz","depends_on_id":"bd-wrfz","type":"blocks","created_at":"2025-11-23T18:08:31.009873-08:00","created_by":"daemon"},{"issue_id":"bd-wpkz","depends_on_id":"bd-x2ba","type":"blocks","created_at":"2025-11-23T18:08:31.080663-08:00","created_by":"daemon"},{"issue_id":"bd-wpkz","depends_on_id":"bd-t596","type":"blocks","created_at":"2025-11-23T18:08:31.153866-08:00","created_by":"daemon"}]} {"id":"bd-wrfz","content_hash":"a03a18ee69cedc5e7e9c7553d27168fd1935b8d77c863b4888a2b73fec9531bf","title":"Create queries.go with core issue CRUD methods","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-23T18:08:13.46714-08:00","updated_at":"2025-11-23T18:12:55.233765-08:00","closed_at":"2025-11-23T18:12:55.233765-08:00","source_repo":"."} {"id":"bd-wta","content_hash":"eee40bbe4e00af632ad46e1461a25e4b0e5508bea115422aea0772381eec0d84","title":"Add performance benchmarks for multi-repo hydration","description":"The contributor-workflow-analysis.md asserts sub-second queries (line 702) and describes smart caching via file mtime tracking (Decision #4, lines 584-618), but doesn't provide concrete performance benchmarks.\n\nVC's requirement (from VC feedback section):\n- Executor polls GetReadyWork() every 5-10 seconds\n- Queries must be sub-second (ideally \u003c100ms)\n- Smart caching must avoid re-parsing JSONLs on every query\n\nSuggested performance targets to validate:\n- File stat overhead: \u003c1ms per repo\n- Hydration (when needed): \u003c500ms for typical JSONL (\u003c25k)\n- Query (from cache): \u003c10ms\n- Total GetReadyWork(): \u003c100ms (VC's requirement)\n\nAlso test at scale:\n- N=1 repo (baseline)\n- N=3 repos (typical)\n- N=10 repos (edge case)\n\nThese benchmarks are critical for library consumers like VC that run automated polling loops.","acceptance_criteria":"- Performance benchmark suite created for multi-repo hydration\n- Benchmarks cover file stat, hydration, and query times\n- Tests at N=1, N=3, N=10 repo scales\n- Results documented in contributor-workflow-analysis.md\n- Performance targets met or issues filed for optimization","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-03T20:24:39.331528-08:00","updated_at":"2025-11-05T14:17:15.079226-08:00","closed_at":"2025-11-05T14:17:15.079226-08:00","source_repo":"."} diff --git a/AGENTS.md b/AGENTS.md index 74c5180d..d8944f36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,12 +38,17 @@ bd info --whats-new # 2. Update git hooks to match new bd version bd hooks install -# 3. Check for any outdated hooks (optional) +# 3. Regenerate BD_GUIDE.md if it exists (optional but recommended) +bd onboard --output .beads/BD_GUIDE.md + +# 4. Check for any outdated hooks (optional) bd info # Shows warnings if hooks are outdated ``` **Why update hooks?** Git hooks (pre-commit, post-merge, pre-push) are versioned with bd. Outdated hooks may miss new auto-sync features or bug fixes. Running `bd hooks install` ensures hooks match your bd version. +**About BD_GUIDE.md:** This is an optional auto-generated file that separates bd-specific instructions from project-specific ones. If your project uses this file (in `.beads/BD_GUIDE.md`), regenerate it after upgrades to get the latest bd documentation. The file is version-stamped and should never be manually edited. + **Related:** See GitHub Discussion #239 for background on agent upgrade workflows. ## Human Setup vs Agent Usage diff --git a/cmd/bd/onboard.go b/cmd/bd/onboard.go index 84a7ab59..bd954dde 100644 --- a/cmd/bd/onboard.go +++ b/cmd/bd/onboard.go @@ -415,6 +415,66 @@ func renderOnboardInstructions(w io.Writer) error { return nil } +// bdGuideContent generates the canonical BD_GUIDE.md content +const bdGuideHeader = ` + + +# BD (Beads) Guide for AI Agents + +This file contains canonical bd (beads) workflow instructions for AI agents. +It is auto-generated and version-stamped to track bd upgrades. + +> **For project-specific instructions**, see AGENTS.md in the repository root. +> This file only covers bd tool usage, not project-specific workflows. + +--- + +` + +// generateBDGuide creates a version-stamped BD_GUIDE.md file +func generateBDGuide(outputPath string) error { + // Create output file + f, err := os.Create(outputPath) + if err != nil { + return fmt.Errorf("failed to create output file: %w", err) + } + defer f.Close() + + // Write header with version stamp + if _, err := fmt.Fprintf(f, bdGuideHeader, Version); err != nil { + return fmt.Errorf("failed to write header: %w", err) + } + + // Write AGENTS.md content (bd-specific instructions) + if _, err := f.WriteString(agentsContent); err != nil { + return fmt.Errorf("failed to write agents content: %w", err) + } + + // Write separator + if _, err := f.WriteString("\n\n---\n\n"); err != nil { + return fmt.Errorf("failed to write separator: %w", err) + } + + // Write Copilot instructions content (comprehensive technical guide) + if _, err := f.WriteString(copilotInstructionsContent); err != nil { + return fmt.Errorf("failed to write copilot content: %w", err) + } + + // Write footer with regeneration instructions + footer := fmt.Sprintf("\n\n---\n\n"+ + "**Generated by bd v%s**\n\n"+ + "To regenerate this file after upgrading bd:\n"+ + "```bash\n"+ + "bd onboard --output .beads/BD_GUIDE.md\n"+ + "```\n", Version) + + if _, err := f.WriteString(footer); err != nil { + return fmt.Errorf("failed to write footer: %w", err) + } + + return nil +} + var onboardCmd = &cobra.Command{ Use: "onboard", Short: "Display instructions for configuring AGENTS.md", @@ -422,8 +482,29 @@ var onboardCmd = &cobra.Command{ This command outputs instructions that AI agents should follow to integrate bd into the project's agent documentation. The agent will intelligently merge the -content into AGENTS.md and update CLAUDE.md if present.`, +content into AGENTS.md and update CLAUDE.md if present. + +Use --output to generate a canonical BD_GUIDE.md file instead: + bd onboard --output .beads/BD_GUIDE.md + +The generated BD_GUIDE.md is version-stamped and auto-generated - it should +never be manually edited. This separates bd-specific instructions (which change +with bd upgrades) from project-specific instructions in AGENTS.md.`, Run: func(cmd *cobra.Command, args []string) { + outputPath, _ := cmd.Flags().GetString("output") + + if outputPath != "" { + // Generate BD_GUIDE.md instead of onboarding instructions + if err := generateBDGuide(outputPath); err != nil { + fmt.Fprintf(cmd.ErrOrStderr(), "Error generating BD_GUIDE.md: %v\n", err) + os.Exit(1) + } + fmt.Printf("✓ Generated %s (bd v%s)\n", outputPath, Version) + fmt.Println(" This file is auto-generated - do not edit manually") + fmt.Println(" Update your AGENTS.md to reference this file instead of duplicating bd instructions") + return + } + if err := renderOnboardInstructions(cmd.OutOrStdout()); err != nil { if _, writeErr := fmt.Fprintf(cmd.ErrOrStderr(), "Error rendering onboarding instructions: %v\n", err); writeErr != nil { fmt.Fprintf(os.Stderr, "Error rendering onboarding instructions: %v (stderr write failed: %v)\n", err, writeErr) @@ -434,5 +515,6 @@ content into AGENTS.md and update CLAUDE.md if present.`, } func init() { + onboardCmd.Flags().String("output", "", "Generate BD_GUIDE.md at the specified path (e.g., .beads/BD_GUIDE.md)") rootCmd.AddCommand(onboardCmd) } diff --git a/cmd/bd/onboard_test.go b/cmd/bd/onboard_test.go index 0fe310bf..39c24d6e 100644 --- a/cmd/bd/onboard_test.go +++ b/cmd/bd/onboard_test.go @@ -2,6 +2,8 @@ package main import ( "bytes" + "os" + "path/filepath" "strings" "testing" ) @@ -68,3 +70,120 @@ func TestOnboardCommand(t *testing.T) { } }) } + +func TestGenerateBDGuide(t *testing.T) { + t.Run("generates BD_GUIDE.md with version stamp", func(t *testing.T) { + // Create temp directory + tmpDir := t.TempDir() + outputPath := filepath.Join(tmpDir, "BD_GUIDE.md") + + // Generate BD_GUIDE.md + if err := generateBDGuide(outputPath); err != nil { + t.Fatalf("generateBDGuide() error = %v", err) + } + + // Read generated file + content, err := os.ReadFile(outputPath) + if err != nil { + t.Fatalf("Failed to read generated file: %v", err) + } + + output := string(content) + + // Verify version stamp in header + if !strings.Contains(output, "Auto-generated by bd v"+Version) { + t.Error("Generated file should contain version stamp in header") + } + + if !strings.Contains(output, "DO NOT EDIT MANUALLY") { + t.Error("Generated file should contain DO NOT EDIT warning") + } + + // Verify regeneration instructions + if !strings.Contains(output, "bd onboard --output") { + t.Error("Generated file should contain regeneration instructions") + } + }) + + t.Run("includes agents content", func(t *testing.T) { + tmpDir := t.TempDir() + outputPath := filepath.Join(tmpDir, "BD_GUIDE.md") + + if err := generateBDGuide(outputPath); err != nil { + t.Fatalf("generateBDGuide() error = %v", err) + } + + content, err := os.ReadFile(outputPath) + if err != nil { + t.Fatalf("Failed to read generated file: %v", err) + } + + output := string(content) + + // Verify key sections from agentsContent are present + expectedSections := []string{ + "Issue Tracking with bd (beads)", + "bd ready", + "bd create", + "MCP Server", + } + + for _, section := range expectedSections { + if !strings.Contains(output, section) { + t.Errorf("Generated file should contain '%s'", section) + } + } + }) + + t.Run("includes copilot instructions content", func(t *testing.T) { + tmpDir := t.TempDir() + outputPath := filepath.Join(tmpDir, "BD_GUIDE.md") + + if err := generateBDGuide(outputPath); err != nil { + t.Fatalf("generateBDGuide() error = %v", err) + } + + content, err := os.ReadFile(outputPath) + if err != nil { + t.Fatalf("Failed to read generated file: %v", err) + } + + output := string(content) + + // Verify key sections from copilotInstructionsContent are present + expectedSections := []string{ + "GitHub Copilot Instructions", + "Project Structure", + "Tech Stack", + "Coding Guidelines", + } + + for _, section := range expectedSections { + if !strings.Contains(output, section) { + t.Errorf("Generated file should contain '%s'", section) + } + } + }) + + t.Run("has proper structure with separators", func(t *testing.T) { + tmpDir := t.TempDir() + outputPath := filepath.Join(tmpDir, "BD_GUIDE.md") + + if err := generateBDGuide(outputPath); err != nil { + t.Fatalf("generateBDGuide() error = %v", err) + } + + content, err := os.ReadFile(outputPath) + if err != nil { + t.Fatalf("Failed to read generated file: %v", err) + } + + output := string(content) + + // Count separators (should have at least 3: after header, between sections, before footer) + separatorCount := strings.Count(output, "---") + if separatorCount < 3 { + t.Errorf("Expected at least 3 separators (---), got %d", separatorCount) + } + }) +} diff --git a/cmd/bd/version_tracking.go b/cmd/bd/version_tracking.go index c1875af2..ab8dae13 100644 --- a/cmd/bd/version_tracking.go +++ b/cmd/bd/version_tracking.go @@ -114,9 +114,67 @@ func maybeShowUpgradeNotification() { // Display notification fmt.Printf("🔄 bd upgraded from v%s to v%s since last use\n", previousVersion, Version) fmt.Println("💡 Run 'bd upgrade review' to see what changed") + + // Check if BD_GUIDE.md exists and needs updating + checkAndSuggestBDGuideUpdate() + fmt.Println() } +// checkAndSuggestBDGuideUpdate checks if .beads/BD_GUIDE.md exists and suggests regeneration if outdated. +// bd-woro: Auto-update BD_GUIDE.md on version changes +func checkAndSuggestBDGuideUpdate() { + beadsDir := beads.FindBeadsDir() + if beadsDir == "" { + return + } + + guidePath := beadsDir + "/BD_GUIDE.md" + + // Check if BD_GUIDE.md exists + if _, err := os.Stat(guidePath); os.IsNotExist(err) { + // File doesn't exist - no suggestion needed + return + } + + // Read first few lines to check version stamp + content, err := os.ReadFile(guidePath) + if err != nil { + return // Silent failure + } + + // Look for version in the first 200 bytes (should be in the header) + header := string(content) + if len(header) > 200 { + header = header[:200] + } + + // Check if the file has the old version stamp + oldVersionStamp := fmt.Sprintf("bd v%s", previousVersion) + currentVersionStamp := fmt.Sprintf("bd v%s", Version) + + if containsSubstring(header, oldVersionStamp) && !containsSubstring(header, currentVersionStamp) { + // BD_GUIDE.md is outdated + fmt.Printf("📄 BD_GUIDE.md is outdated (v%s → v%s)\n", previousVersion, Version) + fmt.Printf("💡 Run 'bd onboard --output .beads/BD_GUIDE.md' to regenerate\n") + } +} + +// containsSubstring checks if haystack contains needle (case-sensitive) +func containsSubstring(haystack, needle string) bool { + return len(haystack) >= len(needle) && findSubstring(haystack, needle) >= 0 +} + +// findSubstring returns the index of needle in haystack, or -1 if not found +func findSubstring(haystack, needle string) int { + for i := 0; i <= len(haystack)-len(needle); i++ { + if haystack[i:i+len(needle)] == needle { + return i + } + } + return -1 +} + // autoMigrateOnVersionBump automatically migrates the database when CLI version changes. // This function is best-effort - failures are silent to avoid disrupting commands. // Called from PersistentPreRun after daemon check but before opening DB for main operation.