Enhance bd onboard with AI planning docs management guidance

Add comprehensive guidance for managing AI-generated planning documents
(Claude slop) to the bd onboard command. Addresses GitHub issue #196.

Changes:
- Add Managing AI-Generated Planning Documents section to onboard output
- Recommend using history/ directory for ephemeral planning files
- List common planning doc types (PLAN.md, IMPLEMENTATION.md, etc.)
- Provide .gitignore example and benefits explanation
- Add to Important Rules: Store AI planning docs in history/
- Update AGENTS.md with the same guidance to demonstrate the pattern
- Add comprehensive tests for onboard command

This uses inverted control: bd outputs guidance, AI agents intelligently
integrate it into their project's documentation (AGENTS.md, CLAUDE.md,
.cursorrules, etc.), respecting existing conventions.

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

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

AGENTS.md

@@ -950,15 +950,45 @@ Add to MCP config (e.g., `~/.config/claude/config.json`):
 
 Then use `mcp__beads__*` functions instead of CLI commands.
 
+### Managing AI-Generated Planning Documents
+
+AI assistants often create planning and design documents during development:
+- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
+- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
+- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
+
+**Best Practice: Use a dedicated directory for these ephemeral files**
+
+**Recommended approach:**
+- Create a `history/` directory in the project root
+- Store ALL AI-generated planning/design docs in `history/`
+- Keep the repository root clean and focused on permanent project files
+- Only access `history/` when explicitly asked to review past planning
+
+**Example .gitignore entry (optional):**
+```
+# AI planning documents (ephemeral)
+history/
+```
+
+**Benefits:**
+- ✅ Clean repository root
+- ✅ Clear separation between ephemeral and permanent documentation
+- ✅ Easy to exclude from version control if desired
+- ✅ Preserves planning history for archaeological research
+- ✅ Reduces noise when browsing the project
+
 ### Important Rules
 
 - ✅ Use bd for ALL task tracking
 - ✅ Always use `--json` flag for programmatic use
 - ✅ Link discovered work with `discovered-from` dependencies
 - ✅ Check `bd ready` before asking "what should I work on?"
+- ✅ Store AI planning docs in `history/` directory
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT use external issue trackers
 - ❌ Do NOT duplicate tracking systems
+- ❌ Do NOT clutter repo root with planning documents
 
 For more details, see README.md and QUICKSTART.md.
 <!-- /bd onboard section -->

cmd/bd/onboard.go

@@ -95,15 +95,45 @@ Add to MCP config (e.g., ` + "`~/.config/claude/config.json`" + `):
 
 Then use ` + "`mcp__beads__*`" + ` functions instead of CLI commands.
 
+### Managing AI-Generated Planning Documents
+
+AI assistants often create planning and design documents during development:
+- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
+- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
+- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
+
+**Best Practice: Use a dedicated directory for these ephemeral files**
+
+**Recommended approach:**
+- Create a ` + "`history/`" + ` directory in the project root
+- Store ALL AI-generated planning/design docs in ` + "`history/`" + `
+- Keep the repository root clean and focused on permanent project files
+- Only access ` + "`history/`" + ` when explicitly asked to review past planning
+
+**Example .gitignore entry (optional):**
+` + "```" + `
+# AI planning documents (ephemeral)
+history/
+` + "```" + `
+
+**Benefits:**
+- ✅ Clean repository root
+- ✅ Clear separation between ephemeral and permanent documentation
+- ✅ Easy to exclude from version control if desired
+- ✅ Preserves planning history for archaeological research
+- ✅ Reduces noise when browsing the project
+
 ### Important Rules
 
 - ✅ Use bd for ALL task tracking
 - ✅ Always use ` + "`--json`" + ` flag for programmatic use
 - ✅ Link discovered work with ` + "`discovered-from`" + ` dependencies
 - ✅ Check ` + "`bd ready`" + ` before asking "what should I work on?"
+- ✅ Store AI planning docs in ` + "`history/`" + ` directory
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT use external issue trackers
 - ❌ Do NOT duplicate tracking systems
+- ❌ Do NOT clutter repo root with planning documents
 
 For more details, see README.md and QUICKSTART.md.`
 

cmd/bd/onboard_test.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestOnboardCommand(t *testing.T) {
+	// Save original stdout
+	oldStdout := os.Stdout
+	defer func() { os.Stdout = oldStdout }()
+
+	t.Run("onboard output contains key sections", func(t *testing.T) {
+		// Create a pipe to capture output
+		r, w, err := os.Pipe()
+		if err != nil {
+			t.Fatalf("Failed to create pipe: %v", err)
+		}
+		os.Stdout = w
+
+		// Run onboard command
+		onboardCmd.Run(onboardCmd, []string{})
+
+		// Close writer and read output
+		w.Close()
+		var buf bytes.Buffer
+		buf.ReadFrom(r)
+		output := buf.String()
+
+		// Verify output contains expected sections
+		expectedSections := []string{
+			"bd Onboarding Instructions",
+			"Update AGENTS.md",
+			"Update CLAUDE.md",
+			"BEGIN AGENTS.MD CONTENT",
+			"END AGENTS.MD CONTENT",
+			"Issue Tracking with bd (beads)",
+			"Managing AI-Generated Planning Documents",
+			"history/",
+		}
+
+		for _, section := range expectedSections {
+			if !strings.Contains(output, section) {
+				t.Errorf("Expected output to contain '%s', but it was missing", section)
+			}
+		}
+	})
+
+	t.Run("agents content includes slop management", func(t *testing.T) {
+		// Verify the agentsContent constant includes the new slop management section
+		if !strings.Contains(agentsContent, "Managing AI-Generated Planning Documents") {
+			t.Error("agentsContent should contain 'Managing AI-Generated Planning Documents' section")
+		}
+		if !strings.Contains(agentsContent, "history/") {
+			t.Error("agentsContent should mention the 'history/' directory")
+		}
+		if !strings.Contains(agentsContent, "PLAN.md") {
+			t.Error("agentsContent should mention example files like 'PLAN.md'")
+		}
+		if !strings.Contains(agentsContent, "Do NOT clutter repo root with planning documents") {
+			t.Error("agentsContent should include rule about not cluttering repo root")
+		}
+	})
+
+	t.Run("agents content includes bd workflow", func(t *testing.T) {
+		// Verify essential bd workflow content is present
+		essentialContent := []string{
+			"bd ready",
+			"bd create",
+			"bd update",
+			"bd close",
+			"discovered-from",
+			"--json",
+			"MCP Server",
+		}
+
+		for _, content := range essentialContent {
+			if !strings.Contains(agentsContent, content) {
+				t.Errorf("agentsContent should contain '%s'", content)
+			}
+		}
+	})
+}