Replace all fatih/color usages with internal/ui package that provides:
- Semantic color tokens (Pass, Warn, Fail, Accent, Muted)
- Adaptive light/dark mode support via Lipgloss AdaptiveColor
- Ayu theme colors for consistent, accessible output
- Tufte-inspired data-ink ratio principles
Files migrated: 35 command files in cmd/bd/
Add docs/ui-philosophy.md documenting:
- Semantic token usage guidelines
- Light/dark terminal optimization rationale
- Tufte and perceptual UI/UX theory application
- When to use (and not use) color in CLI output
Fix two CI failures that were blocking main:
1. Lint error in cmd/bd/onboard.go:126
- Unchecked fmt.Fprintf return value
- Fixed by explicitly ignoring with _, _
2. Test failures in internal/storage/sqlite
- TestCreateIssues/duplicate_ID_error was passing but
TestCreateIssuesRollback/rollback_on_conflict_with_existing_ID failed
- Root cause: CreateIssues used INSERT OR IGNORE which silently
ignored duplicate IDs instead of returning an error
- Fixed by adding duplicate ID detection in EnsureIDs():
a) Check for duplicates within the batch
b) Check for conflicts with existing database IDs
Both fixes are minimal and targeted to unblock CI.
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>
Adds "Dependencies: Think Needs, Not Before" section with the
WRONG/RIGHT example pair to help agents avoid the temporal
language trap that inverts dependency direction.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds a "Writing Self-Contained Issues" section to the onboarding output
that instructs AI agents to create fully context-independent issues.
Includes required elements (summary, files, steps, examples) and shows
good vs bad examples.
Closes#618🤖 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.
- Fix doctor to treat empty deletions.jsonl as valid (0 entries OK status)
- Fix HydrateDeletionsManifest to create empty file when no deletions found
- Add --parent flag documentation to onboard command
- Add CLI --help tip throughout onboard documentation
🤖 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
- Add #nosec directives with explanations for all gosec warnings in worktree operations
- Tighten directory permissions from 0755 to 0750 for better security
- Fix misspellings: archaeological -> archeological, cancelled -> canceled
- Remove unused jsonlPath parameter from syncBranchCommitAndPush
- Change branchExists to return bool instead of (bool, error) - error was never used
All changes maintain backward compatibility and improve code quality.
🤖 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 a new step to the onboarding workflow reminding AI agents to commit
the `.beads/issues.jsonl` file together with code changes. This ensures
issue state stays synchronized with code state, which is critical for
maintaining accurate project history and making issues meaningful when
reviewing past commits.
- 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>
