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.
This commit is contained in:
Ryan
GitHub
191
cmd/bd/prime.go
Normal file
191
cmd/bd/prime.go
Normal file
@@ -0,0 +1,191 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/steveyegge/beads"
|
||||
)
|
||||
|
||||
var (
|
||||
primeFullMode bool
|
||||
primeMCPMode bool
|
||||
)
|
||||
|
||||
var primeCmd = &cobra.Command{
|
||||
Use: "prime",
|
||||
Short: "Output AI-optimized workflow context",
|
||||
Long: `Output essential Beads workflow context in AI-optimized markdown format.
|
||||
|
||||
Automatically detects if MCP server is active and adapts output:
|
||||
- MCP mode: Brief workflow reminders (~50 tokens)
|
||||
- CLI mode: Full command reference (~1-2k tokens)
|
||||
|
||||
Designed for Claude Code hooks (SessionStart, PreCompact) to prevent
|
||||
agents from forgetting bd workflow after context compaction.`,
|
||||
Run: func(cmd *cobra.Command, args []string) {
|
||||
// Find .beads/ directory (supports both database and JSONL-only mode)
|
||||
beadsDir := beads.FindBeadsDir()
|
||||
if beadsDir == "" {
|
||||
// Not in a beads project - silent exit with success
|
||||
// CRITICAL: No stderr output, exit 0
|
||||
// This enables cross-platform hook integration
|
||||
os.Exit(0)
|
||||
}
|
||||
|
||||
// Detect MCP mode (unless overridden by flags)
|
||||
mcpMode := isMCPActive()
|
||||
if primeFullMode {
|
||||
mcpMode = false
|
||||
}
|
||||
if primeMCPMode {
|
||||
mcpMode = true
|
||||
}
|
||||
|
||||
// Output workflow context (adaptive based on MCP)
|
||||
if err := outputPrimeContext(mcpMode); err != nil {
|
||||
// Suppress all errors - silent exit with success
|
||||
// Never write to stderr (breaks Windows compatibility)
|
||||
os.Exit(0)
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
func init() {
|
||||
primeCmd.Flags().BoolVar(&primeFullMode, "full", false, "Force full CLI output (ignore MCP detection)")
|
||||
primeCmd.Flags().BoolVar(&primeMCPMode, "mcp", false, "Force MCP mode (minimal output)")
|
||||
rootCmd.AddCommand(primeCmd)
|
||||
}
|
||||
|
||||
// isMCPActive detects if MCP server is currently active
|
||||
func isMCPActive() bool {
|
||||
// Get home directory with fallback
|
||||
home, err := os.UserHomeDir()
|
||||
if err != nil {
|
||||
// Fallback to HOME environment variable
|
||||
home = os.Getenv("HOME")
|
||||
if home == "" {
|
||||
// Can't determine home directory, assume no MCP
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
settingsPath := filepath.Join(home, ".claude/settings.json")
|
||||
data, err := os.ReadFile(settingsPath)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
|
||||
var settings map[string]interface{}
|
||||
if err := json.Unmarshal(data, &settings); err != nil {
|
||||
return false
|
||||
}
|
||||
|
||||
// Check mcpServers section for beads
|
||||
mcpServers, ok := settings["mcpServers"].(map[string]interface{})
|
||||
if !ok {
|
||||
return false
|
||||
}
|
||||
|
||||
// Look for beads server (any key containing "beads")
|
||||
for key := range mcpServers {
|
||||
if strings.Contains(strings.ToLower(key), "beads") {
|
||||
return true
|
||||
}
|
||||
}
|
||||
|
||||
return false
|
||||
}
|
||||
|
||||
// outputPrimeContext outputs workflow context in markdown format
|
||||
func outputPrimeContext(mcpMode bool) error {
|
||||
if mcpMode {
|
||||
return outputMCPContext()
|
||||
}
|
||||
return outputCLIContext()
|
||||
}
|
||||
|
||||
// outputMCPContext outputs minimal context for MCP users
|
||||
func outputMCPContext() error {
|
||||
context := `# Beads Issue Tracker Active
|
||||
|
||||
## Core Rules
|
||||
- Track ALL work in beads (no TodoWrite tool, no markdown TODOs)
|
||||
- Use bd MCP tools (mcp__plugin_beads_beads__*), not TodoWrite or markdown
|
||||
|
||||
Start: Check ` + "`ready`" + ` tool for available work.
|
||||
`
|
||||
fmt.Print(context)
|
||||
return nil
|
||||
}
|
||||
|
||||
// outputCLIContext outputs full CLI reference for non-MCP users
|
||||
func outputCLIContext() error {
|
||||
context := `# Beads Workflow Context
|
||||
|
||||
> **Context Recovery**: Run ` + "`bd prime`" + ` after compaction, clear, or new session
|
||||
> Hooks auto-call this in Claude Code when .beads/ detected
|
||||
|
||||
## Core Rules
|
||||
- Track ALL work in beads (no TodoWrite tool, no markdown TODOs)
|
||||
- Use ` + "`bd create`" + ` to create issues, not TodoWrite tool
|
||||
- Git workflow: hooks auto-sync, run ` + "`bd sync`" + ` at session end
|
||||
- Session management: check ` + "`bd ready`" + ` for available work
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Finding Work
|
||||
- ` + "`bd ready`" + ` - Show issues ready to work (no blockers)
|
||||
- ` + "`bd list --status=open`" + ` - All open issues
|
||||
- ` + "`bd list --status=in_progress`" + ` - Your active work
|
||||
- ` + "`bd show <id>`" + ` - Detailed issue view with dependencies
|
||||
|
||||
### Creating & Updating
|
||||
- ` + "`bd create --title=\"...\" --type=task|bug|feature`" + ` - New issue
|
||||
- ` + "`bd update <id> --status=in_progress`" + ` - Claim work
|
||||
- ` + "`bd update <id> --assignee=username`" + ` - Assign to someone
|
||||
- ` + "`bd close <id>`" + ` - Mark complete
|
||||
- ` + "`bd close <id> --reason=\"explanation\"`" + ` - Close with reason
|
||||
|
||||
### Dependencies & Blocking
|
||||
- ` + "`bd dep <from> <to>`" + ` - Add blocker dependency (from blocks to)
|
||||
- ` + "`bd blocked`" + ` - Show all blocked issues
|
||||
- ` + "`bd show <id>`" + ` - See what's blocking/blocked by this issue
|
||||
|
||||
### Sync & Collaboration
|
||||
- ` + "`bd sync`" + ` - Sync with git remote (run at session end)
|
||||
- ` + "`bd sync --status`" + ` - Check sync status without syncing
|
||||
|
||||
### Project Health
|
||||
- ` + "`bd stats`" + ` - Project statistics (open/closed/blocked counts)
|
||||
- ` + "`bd doctor`" + ` - Check for issues (sync problems, missing hooks)
|
||||
|
||||
## Common Workflows
|
||||
|
||||
**Starting work:**
|
||||
` + "```bash" + `
|
||||
bd ready # Find available work
|
||||
bd show <id> # Review issue details
|
||||
bd update <id> --status=in_progress # Claim it
|
||||
` + "```" + `
|
||||
|
||||
**Completing work:**
|
||||
` + "```bash" + `
|
||||
bd close <id> # Mark done
|
||||
bd sync # Push to remote
|
||||
` + "```" + `
|
||||
|
||||
**Creating dependent work:**
|
||||
` + "```bash" + `
|
||||
bd create --title="Implement feature X" --type=feature
|
||||
bd create --title="Write tests for X" --type=task
|
||||
bd dep beads-xxx beads-yyy # Feature blocks tests
|
||||
` + "```" + `
|
||||
`
|
||||
fmt.Print(context)
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user