Files

Ryan f7e80dd80c feat: add context optimization features for AI agents (#297 )

* 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.

2025-11-12 10:48:36 -08: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