From d46177d8853cafe948bfe7fb4acb315c34f7a1c5 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sun, 2 Nov 2025 17:10:41 -0800 Subject: [PATCH] Enhance bd onboard with AI planning docs management guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 30 +++++++++++++++ cmd/bd/onboard.go | 30 +++++++++++++++ cmd/bd/onboard_test.go | 85 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+) create mode 100644 cmd/bd/onboard_test.go diff --git a/AGENTS.md b/AGENTS.md index 9833e83e..c6d68be4 100644 --- a/AGENTS.md +++ b/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. diff --git a/cmd/bd/onboard.go b/cmd/bd/onboard.go index 1d7e28f6..0ef8a44d 100644 --- a/cmd/bd/onboard.go +++ b/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.` diff --git a/cmd/bd/onboard_test.go b/cmd/bd/onboard_test.go new file mode 100644 index 00000000..42503de0 --- /dev/null +++ b/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) + } + } + }) +}