Files

Steve Yegge 8efab3df87 chore: Move design/audit docs from cmd/bd to docs/

Relocate documentation files to centralize all .md files in docs/ directory
(except those with historical precedent in specific locations like commands/,
examples/, integrations/, etc.).

Files moved:
- cmd/bd/doctor/claude.md -> docs/CLAUDE_INTEGRATION.md
- cmd/bd/MAIN_TEST_REFACTOR_NOTES.md -> docs/MAIN_TEST_REFACTOR_NOTES.md
- cmd/bd/TEST_SUITE_AUDIT.md -> docs/TEST_SUITE_AUDIT.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-21 20:31:47 -05:00

2.2 KiB

Raw Blame History

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

Redundant with bd prime
- bd prime already provides workflow context (~1-2k tokens)
- Skills would duplicate this information
- More systems = more complexity
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
Editor agnostic
- Skills are Claude-specific
- Breaks beads' editor-agnostic philosophy
- Cursor, Windsurf, Zed, etc. wouldn't benefit
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.

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

2.2 KiB Raw Blame History