feat: support claude.local.md for local-only documentation

Add support for claude.local.md and .claude/claude.local.md as local-only
alternatives to CLAUDE.md. These files are intended to be gitignored for
personal customizations that should not be committed to the repo.

Changes:
- Update CheckAgentDocumentation to detect claude.local.md files
- Update CheckLegacyBeadsSlashCommands to check claude.local.md files
- Update CheckDocumentationBdPrimeReference to check claude.local.md files
- Add fix message mentioning claude.local.md as an option
- Add test cases for claude.local.md support

Closes #488

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

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

cmd/bd/doctor/claude.go

@@ -296,11 +296,15 @@ func CheckBdInPath() DoctorCheck {
 // CheckDocumentationBdPrimeReference checks if AGENTS.md or CLAUDE.md reference 'bd prime'
 // and verifies the command exists. This helps catch version mismatches where docs
 // reference features not available in the installed version.
+// Also supports local-only variants (claude.local.md) that are gitignored.
 func CheckDocumentationBdPrimeReference(repoPath string) DoctorCheck {
 	docFiles := []string{
 		filepath.Join(repoPath, "AGENTS.md"),
 		filepath.Join(repoPath, "CLAUDE.md"),
 		filepath.Join(repoPath, ".claude", "CLAUDE.md"),
+		// Local-only variants (not committed to repo)
+		filepath.Join(repoPath, "claude.local.md"),
+		filepath.Join(repoPath, ".claude", "claude.local.md"),
 	}
 
 	var filesWithBdPrime []string

cmd/bd/doctor/claude_test.go

@@ -72,6 +72,22 @@ func TestCheckDocumentationBdPrimeReference(t *testing.T) {
 			expectedStatus: "ok",
 			expectDetail:   true,
 		},
+		{
+			name: "claude.local.md references bd prime (local-only)",
+			fileContent: map[string]string{
+				"claude.local.md": "Run bd prime for context.",
+			},
+			expectedStatus: "ok",
+			expectDetail:   true,
+		},
+		{
+			name: ".claude/claude.local.md references bd prime (local-only)",
+			fileContent: map[string]string{
+				".claude/claude.local.md": "Use bd prime for workflow context.",
+			},
+			expectedStatus: "ok",
+			expectDetail:   true,
+		},
 		{
 			name: "multiple files reference bd prime",
 			fileContent: map[string]string{

cmd/bd/doctor/legacy.go

@@ -22,6 +22,9 @@ func CheckLegacyBeadsSlashCommands(repoPath string) DoctorCheck {
 		filepath.Join(repoPath, "AGENTS.md"),
 		filepath.Join(repoPath, "CLAUDE.md"),
 		filepath.Join(repoPath, ".claude", "CLAUDE.md"),
+		// Local-only variants (not committed to repo)
+		filepath.Join(repoPath, "claude.local.md"),
+		filepath.Join(repoPath, ".claude", "claude.local.md"),
 	}
 
 	var filesWithLegacyCommands []string
@@ -71,11 +74,15 @@ func CheckLegacyBeadsSlashCommands(repoPath string) DoctorCheck {
 
 // CheckAgentDocumentation checks if agent documentation (AGENTS.md or CLAUDE.md) exists
 // and recommends adding it if missing, suggesting bd onboard or bd setup claude.
+// Also supports local-only variants (claude.local.md) that are gitignored.
 func CheckAgentDocumentation(repoPath string) DoctorCheck {
 	docFiles := []string{
 		filepath.Join(repoPath, "AGENTS.md"),
 		filepath.Join(repoPath, "CLAUDE.md"),
 		filepath.Join(repoPath, ".claude", "CLAUDE.md"),
+		// Local-only variants (not committed to repo)
+		filepath.Join(repoPath, "claude.local.md"),
+		filepath.Join(repoPath, ".claude", "claude.local.md"),
 	}
 
 	var foundDocs []string
@@ -103,6 +110,10 @@ func CheckAgentDocumentation(repoPath string) DoctorCheck {
 			"  • Run 'bd onboard' to create AGENTS.md with workflow guidance\n" +
 			"  • Or run 'bd setup claude' to add Claude-specific documentation\n" +
 			"\n" +
+			"For local-only documentation (not committed to repo):\n" +
+			"  • Create claude.local.md or .claude/claude.local.md\n" +
+			"  • Add 'claude.local.md' to your .gitignore\n" +
+			"\n" +
 			"Recommended: Include bd workflow in your project documentation so\n" +
 			"AI agents understand how to track issues and manage dependencies",
 	}

cmd/bd/doctor/legacy_test.go

@@ -39,6 +39,18 @@ func TestCheckAgentDocumentation(t *testing.T) {
 			expectedStatus: "ok",
 			expectFix:      false,
 		},
+		{
+			name:           "claude.local.md exists (local-only)",
+			files:          []string{"claude.local.md"},
+			expectedStatus: "ok",
+			expectFix:      false,
+		},
+		{
+			name:           ".claude/claude.local.md exists (local-only)",
+			files:          []string{".claude/claude.local.md"},
+			expectedStatus: "ok",
+			expectFix:      false,
+		},
 		{
 			name:           "multiple docs",
 			files:          []string{"AGENTS.md", "CLAUDE.md"},
@@ -127,6 +139,22 @@ func TestCheckLegacyBeadsSlashCommands(t *testing.T) {
 			expectedStatus: "warning",
 			expectWarning:  true,
 		},
+		{
+			name: "legacy slash command in claude.local.md",
+			fileContent: map[string]string{
+				"claude.local.md": "Use /beads:show to see an issue.",
+			},
+			expectedStatus: "warning",
+			expectWarning:  true,
+		},
+		{
+			name: "legacy slash command in .claude/claude.local.md",
+			fileContent: map[string]string{
+				".claude/claude.local.md": "Use /beads:ready to see ready issues.",
+			},
+			expectedStatus: "warning",
+			expectWarning:  true,
+		},
 		{
 			name: "multiple files with legacy commands",
 			fileContent: map[string]string{