bd onboard now outputs a ~10 line snippet for AGENTS.md that points to
"bd prime" for full workflow context. This replaces the previous ~200
line static content that:
- Bloated AGENTS.md with instructions that loaded every session
- Got stale when bd was upgraded
- Wasted tokens when beads was not actively being used
The new approach:
- AGENTS.md gets minimal pointer (~20 tokens vs ~2000)
- bd prime provides dynamic, always-current workflow details
- Hooks auto-inject bd prime at session start
Also removes the --output flag for BD_GUIDE.md generation (obsolete).
Closes bd-gxq
Addresses GH#604
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The copilotInstructionsContent in onboard.go contained content specific to
developing the beads project itself (Go tech stack, SQLite, Cobra, project
structure, release scripts, etc.). This content doesn't make sense when
running bd onboard in other repositories that use bd for issue tracking.
Removed:
- Tech Stack section (Go, SQLite, Cobra, etc.)
- Coding Guidelines section (beads development instructions)
- Project Structure section (beads directory tree)
- Scripts section (bump-version.sh, release.sh, etc.)
- Key Documentation section (beads-specific docs)
- Beads-specific rules (BEADS_DB testing, test issues in production DB)
Kept:
- All bd command examples and workflow (unchanged)
- Priorities and issue types
- MCP server instructions
- Generic rules applicable to any project using bd
The beads repo's own .github/copilot-instructions.md is manually maintained
and still contains the beads-specific development instructions.
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
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>
