f7e80dd80c
* feat: add bd prime and setup commands for AI agent integration This commit consolidates context optimization features for AI agents: ## New Commands **bd prime** - AI-optimized workflow context injection - Outputs ~1-2k tokens of workflow context - Context-aware: adapts to MCP vs CLI mode - MCP mode: minimal reminders (~500 tokens) - CLI mode: full command reference (~1-2k tokens) - Warns against TodoWrite tool and markdown TODOs - Designed for SessionStart/PreCompact hooks **bd setup claude** - Claude Code integration installer - Installs hooks via JSON configuration (not file scripts) - Supports --project for project-only installation - Supports --check to verify installation - Supports --remove to uninstall hooks - Idempotent (safe to run multiple times) - Merges with existing settings **bd setup cursor** - Cursor IDE integration installer - Creates .cursor/rules/beads.mdc with workflow rules - Simplified implementation (just overwrites file) ## bd doctor Enhancements - New: CheckClaude() verifies Claude Code integration - Detects plugin, MCP server, and hooks installation - Provides actionable fix suggestions - Extracted legacy pattern detection to doctor/legacy.go - Detects JSONL-only mode and warns about legacy issues.jsonl ## Core Improvements - FindBeadsDir() utility for cross-platform .beads/ discovery - Works in JSONL-only mode (no database required) - Sorted noDbCommands alphabetically (one per line for easy diffs) ## Testing - Unit tests for setup command hook manipulation - Tests for idempotency, adding/removing hooks - All tests passing ## Documentation - cmd/bd/doctor/claude.md - Documents why beads doesn't use Claude Skills - commands/prime.md - Slash command for bd prime - Fixed G304 gosec warnings with nosec comments ## Token Efficiency The bd prime approach reduces AI context usage dramatically: - MCP mode: ~500 tokens (vs ~10.5k for full MCP tool scan) - CLI mode: ~1-2k tokens - 80-99% reduction in standing context overhead * fix: resolve linting errors in setup utils and remove obsolete test - Add error check for tmpFile.Close() in setup/utils.go to fix golangci-lint G104 - Remove TestCheckMultipleJSONLFiles test that referenced deleted checkMultipleJSONLFiles function Fixes golangci-lint errcheck violations introduced in the bd prime/setup feature.
68 lines
2.2 KiB
Markdown
68 lines
2.2 KiB
Markdown
# Claude Code Integration Design
|
|
|
|
This document explains design decisions for Claude Code integration in beads.
|
|
|
|
## Integration Approach
|
|
|
|
Beads uses a simple, universal approach to Claude Code integration:
|
|
- `bd prime` command for context injection
|
|
- Hooks (SessionStart/PreCompact) for automatic context refresh
|
|
- Optional: Plugin for slash commands and enhanced UX
|
|
- Optional: MCP server for native tool access (legacy)
|
|
|
|
## Why Not Claude Skills?
|
|
|
|
**Decision: Beads does NOT use or require Claude Skills (.claude/skills/)**
|
|
|
|
### Reasons
|
|
|
|
1. **Redundant with bd prime**
|
|
- `bd prime` already provides workflow context (~1-2k tokens)
|
|
- Skills would duplicate this information
|
|
- More systems = more complexity
|
|
|
|
2. **Simplicity is core to beads**
|
|
- Workflow fits in simple command set: ready → create → update → close → sync
|
|
- Already well-documented in ~1-2k tokens
|
|
- Complex workflow orchestration not needed
|
|
|
|
3. **Editor agnostic**
|
|
- Skills are Claude-specific
|
|
- Breaks beads' editor-agnostic philosophy
|
|
- Cursor, Windsurf, Zed, etc. wouldn't benefit
|
|
|
|
4. **Maintenance burden**
|
|
- Another system to document and test
|
|
- Another thing that can drift out of sync
|
|
- Another migration path when things change
|
|
|
|
### If Skills were needed...
|
|
|
|
They should be:
|
|
- Provided by the beads plugin (not bd core tool)
|
|
- Complementary (not replacing) bd prime
|
|
- Optional power-user workflows only
|
|
- Opt-in, never required
|
|
|
|
### Current approach is better
|
|
|
|
- ✅ `bd prime` - Universal context injection
|
|
- ✅ Hooks - Automatic context refresh
|
|
- ✅ Plugin - Optional Claude-specific enhancements
|
|
- ✅ MCP - Optional native tool access (legacy)
|
|
- ❌ Skills - Unnecessary complexity
|
|
|
|
Users who want custom Skills can create their own, but beads doesn't ship with or require them.
|
|
|
|
## Related Files
|
|
|
|
- `cmd/bd/prime.go` - Context generation
|
|
- `cmd/bd/setup/claude.go` - Hook installation
|
|
- `cmd/bd/doctor/claude.go` - Integration verification
|
|
- `docs/CLAUDE.md` - General project guidance for Claude
|
|
|
|
## References
|
|
|
|
- [Claude Skills Documentation](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)
|
|
- [Claude Skills Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
|