Merge bd-bscs-driller: GH#403 doctor --fix

cmd/bd/doctor.go

@@ -404,7 +404,11 @@ func applyFixList(path string, fixes []doctorCheck) {
 		if err != nil {
 			errorCount++
 			color.Red("  ✗ Error: %v\n", err)
-			fmt.Printf("  Manual fix: %s\n", check.Fix)
+			// GH#403: Don't suggest "bd doctor --fix" when we're already running --fix
+			manualFix := extractManualFix(check.Fix)
+			if manualFix != "" {
+				fmt.Printf("  Manual fix: %s\n", manualFix)
+			}
 		} else {
 			fixedCount++
 			color.Green("  ✓ Fixed\n")
@@ -418,6 +422,53 @@ func applyFixList(path string, fixes []doctorCheck) {
 	}
 }
 
+// extractManualFix extracts the manual fix portion from a Fix message.
+// GH#403: When running "bd doctor --fix", suggesting "Run 'bd doctor --fix'" is circular.
+// This function extracts just the manual command when available.
+//
+// Examples:
+//   - "Run 'bd doctor --fix' to ..., or manually: git config ..." -> "git config ..."
+//   - "Run 'bd doctor --fix' or bd init" -> "bd init"
+//   - "Run: bd init or bd doctor --fix" -> "bd init"
+//   - "Run 'bd doctor --fix'" -> "" (no alternative)
+func extractManualFix(fix string) string {
+	// Pattern 1: "..., or manually: <command>" - extract everything after "manually:"
+	if idx := strings.Index(strings.ToLower(fix), "manually:"); idx != -1 {
+		manual := strings.TrimSpace(fix[idx+len("manually:"):])
+		return manual
+	}
+
+	// Pattern 2: "Run 'bd doctor --fix' or <alternative>" - extract the alternative
+	// Also handles "Run: bd init or bd doctor --fix"
+	fixLower := strings.ToLower(fix)
+	if strings.Contains(fixLower, "bd doctor --fix") {
+		// Try to find " or " and extract the other option
+		if idx := strings.Index(fixLower, " or "); idx != -1 {
+			before := fix[:idx]
+			after := fix[idx+4:] // len(" or ") = 4
+
+			// Check which side has "bd doctor --fix"
+			if strings.Contains(strings.ToLower(before), "bd doctor --fix") {
+				// "bd doctor --fix or <alternative>" - return alternative
+				return strings.TrimSpace(after)
+			}
+			// "<alternative> or bd doctor --fix" - return alternative
+			// Remove any "Run:" or "Run " prefix
+			result := strings.TrimSpace(before)
+			result = strings.TrimPrefix(result, "Run:")
+			result = strings.TrimPrefix(result, "Run ")
+			return strings.TrimSpace(result)
+		}
+
+		// No " or " found - the whole fix is just "bd doctor --fix"
+		// Return empty string to indicate no manual alternative
+		return ""
+	}
+
+	// No "bd doctor --fix" in the message - return as-is
+	return fix
+}
+
 // runCheckHealth runs lightweight health checks for git hooks.
 // Silent on success, prints a hint if issues detected.
 // Respects hints.doctor config setting.

cmd/bd/doctor_test.go

@@ -1265,3 +1265,62 @@ func TestCheckSyncBranchHookQuick(t *testing.T) {
 		})
 	}
 }
+
+// TestExtractManualFix tests the extractManualFix function (GH#403)
+func TestExtractManualFix(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "manually pattern with git config",
+			input:    "Run 'bd doctor --fix' to update to correct config, or manually: git config merge.beads.driver \"bd merge %A %O %A %B\"",
+			expected: "git config merge.beads.driver \"bd merge %A %O %A %B\"",
+		},
+		{
+			name:     "manually pattern with newline",
+			input:    "Run 'bd doctor --fix' to auto-migrate, or manually:\nbd init && bd import",
+			expected: "bd init && bd import",
+		},
+		{
+			name:     "or alternative after bd doctor --fix",
+			input:    "Run 'bd doctor --fix' or bd init",
+			expected: "bd init",
+		},
+		{
+			name:     "or alternative before bd doctor --fix",
+			input:    "Run: bd init (safe to re-run) or bd doctor --fix",
+			expected: "bd init (safe to re-run)",
+		},
+		{
+			name:     "just bd doctor --fix",
+			input:    "Run 'bd doctor --fix'",
+			expected: "",
+		},
+		{
+			name:     "no bd doctor --fix at all",
+			input:    "Run 'bd init' to initialize the database",
+			expected: "Run 'bd init' to initialize the database",
+		},
+		{
+			name:     "empty input",
+			input:    "",
+			expected: "",
+		},
+		{
+			name:     "update configuration suggestion",
+			input:    "Run 'bd doctor --fix' to update the configuration",
+			expected: "",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := extractManualFix(tc.input)
+			if result != tc.expected {
+				t.Errorf("extractManualFix(%q) = %q, expected %q", tc.input, result, tc.expected)
+			}
+		})
+	}
+}

docs/CLI_REFERENCE.md

@@ -11,6 +11,7 @@
 - [Filtering & Search](#filtering--search)
 - [Advanced Operations](#advanced-operations)
 - [Database Management](#database-management)
+- [Setup & Integration](#setup--integration)
 
 ## Basic Operations
 
@@ -550,10 +551,29 @@ bd sync  # Force immediate sync, bypass debounce
 
 **ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
 
+## Setup & Integration
+
+Configure beads integration with AI coding tools:
+
+```bash
+# Setup integration
+bd setup claude    # Claude Code hooks (SessionStart/PreCompact)
+bd setup cursor    # Cursor IDE rules file
+bd setup aider     # Aider configuration
+
+# Check/remove integration
+bd setup claude --check      # Verify installation
+bd setup claude --remove     # Remove hooks
+bd setup claude --project    # Project-only (not global)
+```
+
+See [SETUP.md](SETUP.md) for detailed documentation on each integration.
+
 ## See Also
 
 - [AGENTS.md](../AGENTS.md) - Main agent workflow guide
 - [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
 - [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
-- [LABELS.md](LABELS.md) - Label system guide
+- [LABELS.md](../LABELS.md) - Label system guide
+- [SETUP.md](SETUP.md) - AI tool integration setup
 - [README.md](../README.md) - User documentation

docs/SETUP.md

@@ -0,0 +1,241 @@
+# Setup Command Reference
+
+**For:** Setting up beads integration with AI coding tools
+**Version:** 0.29.0+
+
+## Overview
+
+The `bd setup` command configures beads integration with AI coding tools. It supports three integrations:
+
+| Tool | Command | Integration Type |
+|------|---------|-----------------|
+| [Claude Code](#claude-code) | `bd setup claude` | SessionStart/PreCompact hooks |
+| [Cursor IDE](#cursor-ide) | `bd setup cursor` | Rules file (.cursor/rules/beads.mdc) |
+| [Aider](#aider) | `bd setup aider` | Config file (.aider.conf.yml) |
+
+## Quick Start
+
+```bash
+# Install integration for your tool
+bd setup claude    # For Claude Code
+bd setup cursor    # For Cursor IDE
+bd setup aider     # For Aider
+
+# Verify installation
+bd setup claude --check
+bd setup cursor --check
+bd setup aider --check
+```
+
+## Claude Code
+
+Claude Code integration uses hooks to automatically inject beads workflow context at session start and before context compaction.
+
+### Installation
+
+```bash
+# Global installation (recommended)
+bd setup claude
+
+# Project-only installation
+bd setup claude --project
+
+# With stealth mode (flush only, no git operations)
+bd setup claude --stealth
+```
+
+### What Gets Installed
+
+**Global installation** (`~/.claude/settings.json`):
+- `SessionStart` hook: Runs `bd prime` when a new session starts
+- `PreCompact` hook: Runs `bd prime` before context compaction
+
+**Project installation** (`.claude/settings.local.json`):
+- Same hooks, but only active for this project
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--check` | Check if integration is installed |
+| `--remove` | Remove beads hooks |
+| `--project` | Install for this project only (not globally) |
+| `--stealth` | Use `bd prime --stealth` (flush only, no git operations) |
+
+### Examples
+
+```bash
+# Check if hooks are installed
+bd setup claude --check
+# Output: ✓ Global hooks installed: /Users/you/.claude/settings.json
+
+# Remove hooks
+bd setup claude --remove
+
+# Install project-specific hooks with stealth mode
+bd setup claude --project --stealth
+```
+
+### How It Works
+
+The hooks call `bd prime` which:
+1. Outputs workflow context for Claude to read
+2. Syncs any pending changes
+3. Ensures Claude always knows how to use beads
+
+This is more context-efficient than MCP tools (~1-2k tokens vs 10-50k for MCP schemas).
+
+## Cursor IDE
+
+Cursor integration creates a rules file that provides beads workflow context to the AI.
+
+### Installation
+
+```bash
+bd setup cursor
+```
+
+### What Gets Installed
+
+Creates `.cursor/rules/beads.mdc` with:
+- Core workflow rules (track work in bd, not markdown TODOs)
+- Quick command reference
+- Workflow pattern (ready → claim → work → close → sync)
+- Context loading instructions
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--check` | Check if integration is installed |
+| `--remove` | Remove beads rules file |
+
+### Examples
+
+```bash
+# Check if rules are installed
+bd setup cursor --check
+# Output: ✓ Cursor integration installed: .cursor/rules/beads.mdc
+
+# Remove rules
+bd setup cursor --remove
+```
+
+### How It Works
+
+Cursor reads `.cursor/rules/*.mdc` files and includes them in the AI's context. The beads rules file teaches the AI:
+- To use `bd ready` for finding work
+- To use `bd create` for tracking new issues
+- To use `bd sync` at session end
+- The basic workflow pattern
+
+## Aider
+
+Aider integration creates configuration files that teach the AI about beads, while respecting Aider's human-in-the-loop design.
+
+### Installation
+
+```bash
+bd setup aider
+```
+
+### What Gets Installed
+
+| File | Purpose |
+|------|---------|
+| `.aider.conf.yml` | Points Aider to read the instructions file |
+| `.aider/BEADS.md` | Workflow instructions for the AI |
+| `.aider/README.md` | Quick reference for humans |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--check` | Check if integration is installed |
+| `--remove` | Remove beads configuration |
+
+### Examples
+
+```bash
+# Check if config is installed
+bd setup aider --check
+# Output: ✓ Aider integration installed: .aider.conf.yml
+
+# Remove configuration
+bd setup aider --remove
+```
+
+### How It Works
+
+Unlike Claude Code, Aider requires explicit command execution. The AI will **suggest** bd commands, which the user runs via `/run`:
+
+```
+You: What issues are ready to work on?
+
+Aider: Let me check. Run:
+/run bd ready
+
+You: [runs the command]
+
+Aider: Great! To claim bd-42, run:
+/run bd update bd-42 --status in_progress
+```
+
+This respects Aider's philosophy of keeping humans in control while still leveraging beads for issue tracking.
+
+## Comparison
+
+| Feature | Claude Code | Cursor | Aider |
+|---------|-------------|--------|-------|
+| Command execution | Automatic | Automatic | Manual (/run) |
+| Context injection | Hooks | Rules file | Config file |
+| Global install | Yes | No (per-project) | No (per-project) |
+| Stealth mode | Yes | N/A | N/A |
+
+## Best Practices
+
+1. **Install globally for Claude Code** - You'll get beads context in every project automatically
+
+2. **Install per-project for Cursor/Aider** - These tools expect project-local configuration
+
+3. **Use stealth mode in CI/CD** - `bd setup claude --stealth` avoids git operations that might fail in automated environments
+
+4. **Run `bd doctor` after setup** - Verifies the integration is working:
+   ```bash
+   bd doctor | grep -i claude
+   # Claude Integration: Hooks installed (CLI mode)
+   ```
+
+## Troubleshooting
+
+### "Hooks not working"
+
+1. Restart your AI tool after installation
+2. Verify with `bd setup <tool> --check`
+3. Check `bd doctor` output for integration status
+
+### "Context not appearing"
+
+For Claude Code, ensure `bd prime` works standalone:
+```bash
+bd prime
+```
+
+If this fails, fix the underlying beads issue first.
+
+### "Want to switch from global to project hooks"
+
+```bash
+# Remove global hooks
+bd setup claude --remove
+
+# Install project hooks
+bd setup claude --project
+```
+
+## Related Documentation
+
+- [CLAUDE_INTEGRATION.md](CLAUDE_INTEGRATION.md) - Design decisions for Claude Code integration
+- [AIDER_INTEGRATION.md](AIDER_INTEGRATION.md) - Detailed Aider workflow guide
+- [QUICKSTART.md](QUICKSTART.md) - Getting started with beads
+- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Full command reference