From eb5ab48950d9ab73aa0766e0105933ec2611586c Mon Sep 17 00:00:00 2001 From: Julian Knutsen Date: Mon, 19 Oct 2026 05:19:28 +0000 Subject: [PATCH] test(setup): pin the Claude agent artifacts bd init and bd setup claude write (#7678) * test(setup): pin the Claude agent artifacts bd init and bd setup claude write Before-parity pin P11. Nothing pinned the agent artifacts byte for byte, so a change to them -- a new hook event in .claude/settings.json, new text in the minimal CLAUDE.md/AGENTS.md template and with it a new marker hash that marks every installed section stale -- could land without anyone seeing the user-visible diff. These goldens make any such change a reviewed diff. - internal/templates/agents: TestManagedSectionGolden pins each managed section (minimal and full profile, with and without a Dolt remote) markers included; TestManagedSectionHashes pins their marker hashes as hand-maintained literals; NoPush is pinned to render the no-remote bytes. - cmd/bd/setup: TestClaudeSetupArtifactsGolden records transcripts of bd setup claude, --check and --remove (project, --stealth, --global, a user's own settings and CLAUDE.md, a stale section, a legacy settings.local.json install, a CLAUDE.md that imports AGENTS.md): each step's result and output, and the settings and instruction files it creates, changes or deletes. TestClaudePluginManifestHookEvents pins the hook events and commands the beads Claude plugin declares. - cmd/bd: TestEmbeddedInitAgentArtifactsGolden runs a real bd init (default and --agents-profile full) and then bd setup claude --check, --remove and a reinstall through the binary, with exit codes. A managed section in a transcript is shown by its marker line and a pointer to the template golden it is checked to match byte for byte, so a template change shows up once in full and as a hash bump wherever it lands. Regenerate with BD_UPDATE_GOLDEN=1. CI companions: the new test files and testdata in BUILD.bazel (bd_test gains its internal/templates/agents dep), and the new TestEmbedded* in the 100-shard embedded cmd manifest (incremental --write). Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) * test(setup): drop BD_OTEL_* and split HOME in the agent artifact golden TestEmbeddedInitAgentArtifactsGolden pins bd's stderr byte for byte, but bdEnv passes the caller's BD_OTEL_* variables through, and bd prints a deprecation warning on stderr for a legacy one (BD_OTEL_METRICS_URL, BD_OTEL_LOGS_URL, BD_OTEL_STDOUT=true) before it checks whether telemetry is on. On a host that exports them (agent hosts do; CI does not), both scenarios failed at the first stderr block with no code drift. The test now runs bd init and every bd setup claude step with agentArtifactEnv: bdEnv(dir) without BD_OTEL_* and OTEL_*. It filters the env slice instead of calling clearTelemetryEnv, which uses t.Setenv and so cannot run in these parallel tests. The same helper gives bd a HOME of its own instead of bdEnv's HOME == project. With the two equal, a bd that wrote the hook and CLAUDE.md into the home directory instead of the project passed every pin. The transcript now also records $HOME/.claude/settings.json and $HOME/CLAUDE.md, and output paths under HOME read $HOME. bd init runs the steps bdInit does (git repo, seeded schema) with that env. The test doc now names what it does not pin: a proxied-server bd init (no Codex section, HasRemote from its own remote URL), a bd init with a remote, and the Cursor files. It also says a change to AGENTS.md's wrapper text or Codex section can fail only here. The goldens are unchanged. Validation (env -i, go1.26.7, GOFLAGS=-mod=readonly, GOPROXY=off, BEADS_TEST_EMBEDDED_DOLT=1, -tags gms_pure_go): - the golden passes in a clean env; with BD_OTEL_METRICS_URL=x BD_OTEL_LOGS_URL=y; with every legacy selector plus BD_OTEL_ENABLED and OTEL_EXPORTER_OTLP_ENDPOINT; and under -race; - the previous test with BD_OTEL_METRICS_URL=x BD_OTEL_LOGS_URL=y fails at golden line 132 on the deprecation warning; - swapping homeDir and projectDir in setup's defaultClaudeEnv passes the previous test and fails this one at golden line 5 (the transcript shows created $HOME/.claude/settings.json). Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 (1M context) Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com> --- .github/scripts/embedded-cmd-test-shards.txt | 1 + cmd/bd/BUILD.bazel | 2 + cmd/bd/agent_artifacts_embedded_test.go | 306 +++++++++++ cmd/bd/setup/BUILD.bazel | 3 +- cmd/bd/setup/claude_artifacts_golden_test.go | 494 ++++++++++++++++++ .../claude-setup-agents-import-stub.golden | 84 +++ .../claude-setup-existing-user-files.golden | 174 ++++++ .../setup/testdata/claude-setup-global.golden | 122 +++++ .../claude-setup-legacy-local-settings.golden | 157 ++++++ .../claude-setup-project-stealth.golden | 122 +++++ .../testdata/claude-setup-project.golden | 142 +++++ .../claude-setup-stale-section.golden | 72 +++ .../init-agents-profile-full.golden | 133 +++++ .../agent_artifacts/init-default.golden | 274 ++++++++++ internal/templates/agents/BUILD.bazel | 2 + internal/templates/agents/golden_test.go | 133 +++++ .../managed-section-full-no-remote.md | 129 +++++ .../agents/testdata/managed-section-full.md | 131 +++++ .../managed-section-minimal-no-remote.md | 54 ++ .../testdata/managed-section-minimal.md | 55 ++ 20 files changed, 2589 insertions(+), 1 deletion(-) create mode 100644 cmd/bd/agent_artifacts_embedded_test.go create mode 100644 cmd/bd/setup/claude_artifacts_golden_test.go create mode 100644 cmd/bd/setup/testdata/claude-setup-agents-import-stub.golden create mode 100644 cmd/bd/setup/testdata/claude-setup-existing-user-files.golden create mode 100644 cmd/bd/setup/testdata/claude-setup-global.golden create mode 100644 cmd/bd/setup/testdata/claude-setup-legacy-local-settings.golden create mode 100644 cmd/bd/setup/testdata/claude-setup-project-stealth.golden create mode 100644 cmd/bd/setup/testdata/claude-setup-project.golden create mode 100644 cmd/bd/setup/testdata/claude-setup-stale-section.golden create mode 100644 cmd/bd/testdata/agent_artifacts/init-agents-profile-full.golden create mode 100644 cmd/bd/testdata/agent_artifacts/init-default.golden create mode 100644 internal/templates/agents/golden_test.go create mode 100644 internal/templates/agents/testdata/managed-section-full-no-remote.md create mode 100644 internal/templates/agents/testdata/managed-section-full.md create mode 100644 internal/templates/agents/testdata/managed-section-minimal-no-remote.md create mode 100644 internal/templates/agents/testdata/managed-section-minimal.md diff --git a/.github/scripts/embedded-cmd-test-shards.txt b/.github/scripts/embedded-cmd-test-shards.txt index 95d0ef0f0..7b45f7915 100644 --- a/.github/scripts/embedded-cmd-test-shards.txt +++ b/.github/scripts/embedded-cmd-test-shards.txt @@ -136,6 +136,7 @@ 100 54 TestEmbeddedDiscoveryPinsEnvFileReadonly 100 54 TestEmbeddedFormatJSONAliasMatchesJSON +100 54 TestEmbeddedInitAgentArtifactsGolden 100 54 TestEmbeddedSearchConcurrent 100 55 TestEmbeddedUndefer diff --git a/cmd/bd/BUILD.bazel b/cmd/bd/BUILD.bazel index 3ac61dc7c..680301167 100644 --- a/cmd/bd/BUILD.bazel +++ b/cmd/bd/BUILD.bazel @@ -547,6 +547,7 @@ go_test( "actor_test.go", "ado_roundtrip_test.go", "ado_test.go", + "agent_artifacts_embedded_test.go", "agent_hook_test.go", "assign_fence_embedded_test.go", "assign_fence_proxied_test.go", @@ -1407,6 +1408,7 @@ go_test( "//internal/storage/uow", "//internal/storage/versioncontrolops", "//internal/telemetry", + "//internal/templates/agents", "//internal/testutil", "//internal/testutil/bazeltest", "//internal/testutil/credentialcmd", diff --git a/cmd/bd/agent_artifacts_embedded_test.go b/cmd/bd/agent_artifacts_embedded_test.go new file mode 100644 index 000000000..9636f9429 --- /dev/null +++ b/cmd/bd/agent_artifacts_embedded_test.go @@ -0,0 +1,306 @@ +//go:build cgo + +package main + +import ( + "errors" + "fmt" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/steveyegge/beads/internal/templates/agents" +) + +// TestEmbeddedInitAgentArtifactsGolden pins the Claude agent artifacts a real +// `bd init` writes — .claude/settings.json with its hook events and commands, +// CLAUDE.md and AGENTS.md with their managed sections — and what +// `bd setup claude --check`, `--remove` and a reinstall then report and leave +// behind, through the bd binary. Each scenario is a transcript golden under +// testdata/agent_artifacts/, so a change to any artifact or outcome (a new +// hook event, a changed command, new template text and its hash) shows up as +// a reviewed golden diff. +// +// A managed section is shown by its BEGIN marker line (profile and hash) and a +// pointer to the internal/templates/agents golden that pins its bytes +// (TestManagedSectionGolden), after checking the file holds exactly that +// section; one that matches no rendered variant is shown in full. The +// in-process `bd setup claude` scenarios are pinned by +// TestClaudeSetupArtifactsGolden in cmd/bd/setup. +// +// The scenarios run a direct (embedded) bd init with no Dolt remote. Not +// pinned here: a proxied-server bd init, which installs no Codex section and +// decides HasRemote from its own remote URL; a bd init with a remote, which +// renders the managed section's with-remote variant; and the Cursor files. +// AGENTS.md is shown in full apart from its managed section, so a change to +// its wrapper text or its Codex section can pass the cmd/bd/setup and +// internal/templates/agents tests and fail only here. +// +// bd runs with HOME outside the project, so an artifact written to the home +// directory instead of the project shows up under $HOME. +// +// Regenerate with +// +// BEADS_TEST_EMBEDDED_DOLT=1 BD_UPDATE_GOLDEN=1 go test -tags gms_pure_go ./cmd/bd/ -run TestEmbeddedInitAgentArtifactsGolden +func TestEmbeddedInitAgentArtifactsGolden(t *testing.T) { + if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" { + t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests") + } + t.Parallel() + + bd := buildEmbeddedBD(t) + + scenarios := []struct { + name string + initArgs []string + steps [][]string + }{ + { + name: "init-default", + initArgs: []string{"--prefix", "aa"}, + steps: [][]string{ + {"setup", "claude", "--check"}, + {"setup", "claude"}, + {"setup", "claude", "--remove"}, + {"setup", "claude", "--check"}, + {"setup", "claude"}, + {"setup", "claude", "--check"}, + }, + }, + { + name: "init-agents-profile-full", + initArgs: []string{"--prefix", "ab", "--agents-profile", "full"}, + steps: [][]string{ + {"setup", "claude", "--check"}, + }, + }, + } + + for _, sc := range scenarios { + t.Run(sc.name, func(t *testing.T) { + t.Parallel() + // bdInit, with HOME in a directory of its own. + dir, home := t.TempDir(), t.TempDir() + initGitRepoAt(t, dir) + database, seeded := seededInitDatabase(sc.initArgs) + if seeded { + seedEmbeddedSchema(t, dir, database) + } + initArgs := append([]string{"init", "--quiet"}, sc.initArgs...) + if stdout, stderr, exitCode := runAgentArtifactCommand(t, bd, dir, home, initArgs...); exitCode != 0 { + t.Fatalf("bd %s: exit %d\nstdout:\n%s\nstderr:\n%s", strings.Join(initArgs, " "), exitCode, stdout, stderr) + } + if seeded { + requireSeededEmbeddedInit(t, filepath.Join(dir, ".beads"), database) + } + + var transcript strings.Builder + fmt.Fprintf(&transcript, "# bd init agent artifact transcript: %s\n", sc.name) + fmt.Fprintf(&transcript, "# Regenerate with BEADS_TEST_EMBEDDED_DOLT=1 BD_UPDATE_GOLDEN=1 go test -tags gms_pure_go ./cmd/bd/ -run TestEmbeddedInitAgentArtifactsGolden\n") + fmt.Fprintf(&transcript, "\n=== bd %s\n", strings.Join(initArgs, " ")) + previous := map[string]string{} + writeAgentArtifactChanges(t, &transcript, dir, home, previous) + + for _, args := range sc.steps { + stdout, stderr, exitCode := runAgentArtifactCommand(t, bd, dir, home, args...) + fmt.Fprintf(&transcript, "\n=== bd %s\n", strings.Join(args, " ")) + fmt.Fprintf(&transcript, "exit: %d\n", exitCode) + writeAgentArtifactBlock(&transcript, "stdout", normalizeAgentArtifactOutput(stdout, dir, home)) + writeAgentArtifactBlock(&transcript, "stderr", normalizeAgentArtifactOutput(stderr, dir, home)) + writeAgentArtifactChanges(t, &transcript, dir, home, previous) + } + + assertAgentArtifactGolden(t, filepath.Join("testdata", "agent_artifacts", sc.name+".golden"), transcript.String()) + }) + } +} + +// agentArtifactPaths are the Claude agent artifacts bd init and bd setup +// claude write in a project ($PROJECT), and the two a global install writes +// in the home directory ($HOME) instead. +var agentArtifactPaths = []string{ + "$PROJECT/.claude/settings.json", + "$PROJECT/.claude/settings.local.json", + "$PROJECT/AGENTS.md", + "$PROJECT/CLAUDE.md", + "$HOME/.claude/settings.json", + "$HOME/CLAUDE.md", +} + +// agentArtifactManagedSections maps each managed section bd renders to the +// internal/templates/agents golden file that pins its bytes. +var agentArtifactManagedSections = []struct { + golden string + profile agents.Profile + opts agents.RenderOpts +}{ + {golden: "managed-section-minimal.md", profile: agents.ProfileMinimal, opts: agents.RenderOpts{HasRemote: true}}, + {golden: "managed-section-minimal-no-remote.md", profile: agents.ProfileMinimal, opts: agents.RenderOpts{}}, + {golden: "managed-section-full.md", profile: agents.ProfileFull, opts: agents.RenderOpts{HasRemote: true}}, + {golden: "managed-section-full-no-remote.md", profile: agents.ProfileFull, opts: agents.RenderOpts{}}, +} + +// elideAgentArtifactManagedSection replaces the body of a managed section +// that is byte-identical to a rendered variant with a pointer to that +// variant's golden, keeping the BEGIN marker line (profile and hash) and the +// END marker. +func elideAgentArtifactManagedSection(content string) string { + const endMarker = "\n" + begin := strings.Index(content, "\n" + begin := strings.Index(content, "\nOlder beads guidance.\n\n\n## Notes\n", + }, + steps: []claudeArtifactStep{ + claudeCheckStep(), + claudeInstallStep(false, false), + claudeCheckStep(), + }, + }, + { + // A legacy install in settings.local.json: install migrates + // its hook to settings.json. + name: "legacy-local-settings", + seed: map[string]string{ + "project/.claude/settings.local.json": legacyLocalSettings, + }, + steps: []claudeArtifactStep{ + claudeCheckStep(), + claudeInstallStep(false, false), + claudeCheckStep(), + claudeRemoveStep(false), + }, + }, + { + // CLAUDE.md imports AGENTS.md: the managed section goes to + // AGENTS.md, and --remove leaves that shared section in place. + name: "agents-import-stub", + seed: map[string]string{ + "project/AGENTS.md": "# Agent Instructions\n\nShared by every agent.\n", + "project/CLAUDE.md": "@AGENTS.md\n", + }, + steps: []claudeArtifactStep{ + claudeInstallStep(false, false), + claudeCheckStep(), + claudeRemoveStep(false), + claudeCheckStep(), + }, + }, + } + + for _, sc := range scenarios { + t.Run(sc.name, func(t *testing.T) { + env, _, _ := newClaudeTestEnv(t) + root := filepath.Dir(env.projectDir) + for rel, content := range sc.seed { + path := filepath.Join(root, filepath.FromSlash(rel)) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatalf("mkdir for seed %s: %v", rel, err) + } + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + t.Fatalf("seed %s: %v", rel, err) + } + } + + var transcript strings.Builder + fmt.Fprintf(&transcript, "# bd setup claude artifact transcript: %s\n", sc.name) + fmt.Fprintf(&transcript, "# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden\n") + previous := map[string]string{} + writeClaudeArtifactChanges(t, &transcript, "seed", root, previous) + for _, step := range sc.steps { + out, errOut, err := runClaudeArtifactStep(t, env, step.run) + fmt.Fprintf(&transcript, "\n=== %s\n", step.title) + fmt.Fprintf(&transcript, "result: %s\n", claudeStepResult(err)) + writeTranscriptBlock(&transcript, "stdout", normalizeArtifactOutput(out, root)) + writeTranscriptBlock(&transcript, "stderr", normalizeArtifactOutput(errOut, root)) + writeClaudeArtifactChanges(t, &transcript, "files", root, previous) + } + + assertArtifactGolden(t, filepath.Join("testdata", "claude-setup-"+sc.name+".golden"), transcript.String()) + }) + } +} + +// TestClaudePluginManifestHookEvents pins the hook events and commands the +// beads Claude Code plugin declares. With the plugin enabled bd setup claude +// writes no hooks of its own (GH#3192), so these are the hooks such a user +// runs. +func TestClaudePluginManifestHookEvents(t *testing.T) { + var manifest struct { + Hooks map[string][]struct { + Matcher string `json:"matcher"` + Hooks []struct { + Type string `json:"type"` + Command string `json:"command"` + } `json:"hooks"` + } `json:"hooks"` + } + readJSONFile(t, filepath.Join("..", "..", "..", "plugins", "beads", ".claude-plugin", "plugin.json"), &manifest) + + var got []string + for event, entries := range manifest.Hooks { + for _, entry := range entries { + for _, hook := range entry.Hooks { + got = append(got, fmt.Sprintf("%s matcher=%q %s: %s", event, entry.Matcher, hook.Type, hook.Command)) + } + } + } + sort.Strings(got) + want := []string{ + `PreCompact matcher="" command: bd prime`, + `SessionStart matcher="" command: bd prime`, + } + if strings.Join(got, "\n") != strings.Join(want, "\n") { + t.Errorf("Claude plugin hooks changed:\ngot:\n %s\nwant:\n %s", strings.Join(got, "\n "), strings.Join(want, "\n ")) + } +} + +// runClaudeArtifactStep runs one step with env.stdout and the process stdout +// sent to the same file, so the transcript keeps the order a user sees: the +// hook helpers (addHookCommand, removeHookCommand) print with fmt.Printf +// rather than to env.stdout. Swapping os.Stdout is why these tests must not +// run in parallel. +func runClaudeArtifactStep(t *testing.T, env claudeEnv, run func(claudeEnv) error) (stdout, stderr string, err error) { + t.Helper() + capture, createErr := os.CreateTemp(t.TempDir(), "stdout-*") + if createErr != nil { + t.Fatalf("create stdout capture: %v", createErr) + } + errBuf := &bytes.Buffer{} + env.stdout, env.stderr = capture, errBuf + + origStdout := os.Stdout + os.Stdout = capture + func() { + defer func() { os.Stdout = origStdout }() + err = run(env) + }() + + if closeErr := capture.Close(); closeErr != nil { + t.Fatalf("close stdout capture: %v", closeErr) + } + data, readErr := os.ReadFile(capture.Name()) + if readErr != nil { + t.Fatalf("read stdout capture: %v", readErr) + } + return string(data), errBuf.String(), err +} + +func claudeStepResult(err error) string { + if err == nil { + return "ok" + } + return "error: " + err.Error() +} + +// writeClaudeArtifactChanges appends every artifact file created, modified or +// deleted since previous (which it then updates), with its full contents. +func writeClaudeArtifactChanges(t *testing.T, b *strings.Builder, label, root string, previous map[string]string) { + t.Helper() + changed := false + for _, rel := range claudeArtifactPaths { + data, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(rel))) + before, existed := previous[rel] + switch { + case os.IsNotExist(err): + if existed { + fmt.Fprintf(b, "--- %s: deleted $ROOT/%s\n", label, rel) + delete(previous, rel) + changed = true + } + case err != nil: + t.Fatalf("read %s: %v", rel, err) + case !existed || before != string(data): + verb := "created" + if existed { + verb = "modified" + } + shown := string(data) + if strings.HasSuffix(rel, ".md") { + shown = elideManagedSection(shown) + } + writeTranscriptBlock(b, fmt.Sprintf("%s: %s $ROOT/%s", label, verb, rel), shown) + previous[rel] = string(data) + changed = true + } + } + switch { + case changed: + case label == "seed": + fmt.Fprintf(b, "--- %s: none\n", label) + default: + fmt.Fprintf(b, "--- %s: unchanged\n", label) + } +} + +// writeTranscriptBlock appends a titled block, marking empty content and a +// missing trailing newline so neither is lost in the golden. +func writeTranscriptBlock(b *strings.Builder, title, content string) { + fmt.Fprintf(b, "--- %s\n", title) + switch { + case content == "": + b.WriteString("(empty)\n") + case !strings.HasSuffix(content, "\n"): + b.WriteString(content) + b.WriteString("\n(no newline at end of file)\n") + default: + b.WriteString(content) + } +} + +// normalizeArtifactOutput replaces the test's temporary root with $ROOT and +// uses forward slashes, so the transcript is the same on every host. +func normalizeArtifactOutput(s, root string) string { + s = strings.ReplaceAll(s, root, "$ROOT") + if filepath.Separator != '/' { + s = strings.ReplaceAll(s, string(filepath.Separator), "/") + } + return s +} + +// assertArtifactGolden compares got with the golden file at path, or rewrites +// the file when BD_UPDATE_GOLDEN=1. +func assertArtifactGolden(t *testing.T, path, got string) { + t.Helper() + if os.Getenv("BD_UPDATE_GOLDEN") == "1" { + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatalf("mkdir %s: %v", filepath.Dir(path), err) + } + if err := os.WriteFile(path, []byte(got), 0o644); err != nil { + t.Fatalf("write golden %s: %v", path, err) + } + t.Logf("updated golden %s", path) + return + } + want, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read golden %s (regenerate with BD_UPDATE_GOLDEN=1): %v", path, err) + } + if got == string(want) { + return + } + wantLines, gotLines := strings.Split(string(want), "\n"), strings.Split(got, "\n") + line := func(lines []string, i int) string { + if i >= len(lines) { + return "(end of output)" + } + return fmt.Sprintf("%q", lines[i]) + } + i := 0 + for i < len(wantLines) && i < len(gotLines) && wantLines[i] == gotLines[i] { + i++ + } + t.Errorf("Claude agent artifacts drifted from %s (regenerate with BD_UPDATE_GOLDEN=1 if intended)\nfirst difference at line %d:\n want: %s\n got: %s\n--- got ---\n%s", path, i+1, line(wantLines, i), line(gotLines, i), got) +} diff --git a/cmd/bd/setup/testdata/claude-setup-agents-import-stub.golden b/cmd/bd/setup/testdata/claude-setup-agents-import-stub.golden new file mode 100644 index 000000000..9b4337a80 --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-agents-import-stub.golden @@ -0,0 +1,84 @@ +# bd setup claude artifact transcript: agents-import-stub +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: created $ROOT/project/AGENTS.md +# Agent Instructions + +Shared by every agent. +--- seed: created $ROOT/project/CLAUDE.md +@AGENTS.md + +=== bd setup claude +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Registered SessionStart hook +Installing Claude Code integration... +✓ Added beads section to existing AGENTS.md + +✓ Claude Code integration installed + File: $ROOT/project/AGENTS.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: created $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: modified $ROOT/project/AGENTS.md +# Agent Instructions + +Shared by every agent. + + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + +=== bd setup claude --check +result: ok +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/AGENTS.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove +result: ok +--- stdout +Removing Claude hooks from project... +✓ Removed SessionStart hook + Leaving shared beads section in AGENTS.md untouched (project-authoritative, not Claude-specific) +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $ROOT/project/.claude/settings.json +{ + "hooks": {} +} + +=== bd setup claude --check +result: error: claude hooks not installed +--- stdout +✗ No hooks installed + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/setup/testdata/claude-setup-existing-user-files.golden b/cmd/bd/setup/testdata/claude-setup-existing-user-files.golden new file mode 100644 index 000000000..d81091fb8 --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-existing-user-files.golden @@ -0,0 +1,174 @@ +# bd setup claude artifact transcript: existing-user-files +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: created $ROOT/project/.claude/settings.json +{ + "permissions": { + "allow": [ + "Bash(go test:*)" + ] + }, + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "echo session started" + } + ] + } + ], + "Stop": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "notify-send done" + } + ] + } + ] + } +} +--- seed: created $ROOT/project/CLAUDE.md +# My Project + +House rules live here. + +=== bd setup claude +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Registered SessionStart hook +Installing Claude Code integration... +✓ Added beads section to existing CLAUDE.md + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: modified $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "echo session started", + "type": "command" + } + ], + "matcher": "" + }, + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ], + "Stop": [ + { + "hooks": [ + { + "command": "notify-send done", + "type": "command" + } + ], + "matcher": "" + } + ] + }, + "permissions": { + "allow": [ + "Bash(go test:*)" + ] + } +} +--- files: modified $ROOT/project/CLAUDE.md +# My Project + +House rules live here. + + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + +=== bd setup claude --check +result: ok +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove +result: ok +--- stdout +Removing Claude hooks from project... +✓ Removed SessionStart hook +Removing Claude Code integration... +✓ Removed beads section from CLAUDE.md +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "echo session started", + "type": "command" + } + ], + "matcher": "" + } + ], + "Stop": [ + { + "hooks": [ + { + "command": "notify-send done", + "type": "command" + } + ], + "matcher": "" + } + ] + }, + "permissions": { + "allow": [ + "Bash(go test:*)" + ] + } +} +--- files: modified $ROOT/project/CLAUDE.md +# My Project + +House rules live here. + + + +=== bd setup claude --check +result: error: claude hooks not installed +--- stdout +✗ No hooks installed + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/setup/testdata/claude-setup-global.golden b/cmd/bd/setup/testdata/claude-setup-global.golden new file mode 100644 index 000000000..da63d077c --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-global.golden @@ -0,0 +1,122 @@ +# bd setup claude artifact transcript: global +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: none + +=== bd setup claude --global +result: ok +--- stdout +Installing Claude hooks globally... +✓ Registered SessionStart hook +Installing Claude Code integration... +✓ Created new CLAUDE.md with beads integration + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/home/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: created $ROOT/home/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: created $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: ok +--- stdout +✓ Global hooks installed: $ROOT/home/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove --global +result: ok +--- stdout +Removing Claude hooks globally... +✓ Removed SessionStart hook +Removing Claude Code integration... +✓ Removed beads section from CLAUDE.md +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $ROOT/home/.claude/settings.json +{ + "hooks": {} +} +--- files: modified $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: error: claude hooks not installed +--- stdout +✗ No hooks installed + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/setup/testdata/claude-setup-legacy-local-settings.golden b/cmd/bd/setup/testdata/claude-setup-legacy-local-settings.golden new file mode 100644 index 000000000..1e17ea55a --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-legacy-local-settings.golden @@ -0,0 +1,157 @@ +# bd setup claude artifact transcript: legacy-local-settings +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: created $ROOT/project/.claude/settings.local.json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bd prime" + } + ] + } + ], + "PreCompact": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "bd prime" + } + ] + } + ] + } +} + +=== bd setup claude --check +result: error: agents file not found +--- stdout +✓ Project hooks installed (legacy): $ROOT/project/.claude/settings.local.json + Consider running 'bd setup claude' to migrate to .claude/settings.json +✗ CLAUDE.md not found + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Registered SessionStart hook +✓ Removed SessionStart hook +✓ Removed PreCompact hook +✓ Migrated hooks from $ROOT/project/.claude/settings.local.json +Installing Claude Code integration... +✓ Created new CLAUDE.md with beads integration + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: created $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: modified $ROOT/project/.claude/settings.local.json +{ + "hooks": {} +} +--- files: created $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: ok +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove +result: ok +--- stdout +Removing Claude hooks from project... +✓ Removed SessionStart hook +Removing Claude Code integration... +✓ Removed beads section from CLAUDE.md +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $ROOT/project/.claude/settings.json +{ + "hooks": {} +} +--- files: modified $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ diff --git a/cmd/bd/setup/testdata/claude-setup-project-stealth.golden b/cmd/bd/setup/testdata/claude-setup-project-stealth.golden new file mode 100644 index 000000000..71d62d8e6 --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-project-stealth.golden @@ -0,0 +1,122 @@ +# bd setup claude artifact transcript: project-stealth +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: none + +=== bd setup claude --stealth +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Registered SessionStart hook +Installing Claude Code integration... +✓ Created new CLAUDE.md with beads integration + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: created $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --stealth --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: created $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: ok +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove +result: ok +--- stdout +Removing Claude hooks from project... +✓ Removed SessionStart hook +Removing Claude Code integration... +✓ Removed beads section from CLAUDE.md +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $ROOT/project/.claude/settings.json +{ + "hooks": {} +} +--- files: modified $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: error: claude hooks not installed +--- stdout +✗ No hooks installed + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/setup/testdata/claude-setup-project.golden b/cmd/bd/setup/testdata/claude-setup-project.golden new file mode 100644 index 000000000..aa307d08f --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-project.golden @@ -0,0 +1,142 @@ +# bd setup claude artifact transcript: project +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: none + +=== bd setup claude +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Registered SessionStart hook +Installing Claude Code integration... +✓ Created new CLAUDE.md with beads integration + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: created $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: created $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: ok +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Hook already registered: SessionStart +Installing Claude Code integration... +✓ Updated existing beads section in CLAUDE.md + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove +result: ok +--- stdout +Removing Claude hooks from project... +✓ Removed SessionStart hook +Removing Claude Code integration... +✓ Removed beads section from CLAUDE.md +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $ROOT/project/.claude/settings.json +{ + "hooks": {} +} +--- files: modified $ROOT/project/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +result: error: claude hooks not installed +--- stdout +✗ No hooks installed + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/setup/testdata/claude-setup-stale-section.golden b/cmd/bd/setup/testdata/claude-setup-stale-section.golden new file mode 100644 index 000000000..c6be8e135 --- /dev/null +++ b/cmd/bd/setup/testdata/claude-setup-stale-section.golden @@ -0,0 +1,72 @@ +# bd setup claude artifact transcript: stale-section +# Regenerate with BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden +--- seed: created $ROOT/project/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- seed: created $ROOT/project/CLAUDE.md +# My Project + + +Older beads guidance. + + +## Notes + +=== bd setup claude --check +result: error: beads section is stale +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +⚠ Claude Code integration installed but stale: $ROOT/project/CLAUDE.md + Run: bd setup claude (to update) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude +result: ok +--- stdout +Installing Claude hooks for this project... +✓ Hook already registered: SessionStart +Installing Claude Code integration... +✓ Updated existing beads section in CLAUDE.md + +✓ Claude Code integration installed + File: $ROOT/project/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $ROOT/project/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: modified $ROOT/project/CLAUDE.md +# My Project + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md] + + +## Notes + +=== bd setup claude --check +result: ok +--- stdout +✓ Project hooks installed: $ROOT/project/.claude/settings.json +✓ Claude Code integration installed: $ROOT/project/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/testdata/agent_artifacts/init-agents-profile-full.golden b/cmd/bd/testdata/agent_artifacts/init-agents-profile-full.golden new file mode 100644 index 000000000..e7abe0511 --- /dev/null +++ b/cmd/bd/testdata/agent_artifacts/init-agents-profile-full.golden @@ -0,0 +1,133 @@ +# bd init agent artifact transcript: init-agents-profile-full +# Regenerate with BEADS_TEST_EMBEDDED_DOLT=1 BD_UPDATE_GOLDEN=1 go test -tags gms_pure_go ./cmd/bd/ -run TestEmbeddedInitAgentArtifactsGolden + +=== bd init --quiet --prefix ab --agents-profile full +--- files: created $PROJECT/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: created $PROJECT/AGENTS.md +# Agent Instructions + +This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context. + +> **Architecture in one line:** Issues live in a local Dolt database +> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a +> git-compatible protocol), stored under `refs/dolt/data` on your git +> remote — separate from `refs/heads/*` where your code lives. +> `.beads/issues.jsonl` is a passive export, not the wire protocol. +> +> See [sync-concepts](https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md) +> for the one-screen overview and anti-patterns (don't treat JSONL as the +> source of truth; don't `bd import` during normal operation; don't +> reach for third-party Dolt hosting before trying the default). + +## Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work atomically +bd close # Complete work +bd dolt push # Push beads data to remote +``` + +## Non-Interactive Shell Commands + +**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts. + +Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input. + +**Use these forms instead:** +```bash +# Force overwrite without prompting +cp -f source dest # NOT: cp source dest +mv -f source dest # NOT: mv source dest +rm -f file # NOT: rm file + +# For recursive operations +rm -rf directory # NOT: rm -r directory +cp -rf source dest # NOT: cp -r source dest +``` + +**Other commands that may prompt:** +- `scp` - use `-o BatchMode=yes` for non-interactive +- `ssh` - use `-o BatchMode=yes` to fail instead of prompting +- `apt-get` - use `-y` flag +- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-full-no-remote.md] + + + +## Beads Issue Tracker + +Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +bd prime # Refresh Beads context +``` + +### Rules + +- Use `bd` for all task tracking; do not create markdown TODO lists. +- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them. +- Keep durable project facts in Beads via `bd remember` rather than in per-tool memory files, which fragment across accounts; per-operator preferences belong in your harness's own memory. + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +--- files: created $PROJECT/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md] + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +exit: 0 +--- stdout +✓ Project hooks installed: $PROJECT/.claude/settings.json +✓ Claude Code integration installed: $PROJECT/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged diff --git a/cmd/bd/testdata/agent_artifacts/init-default.golden b/cmd/bd/testdata/agent_artifacts/init-default.golden new file mode 100644 index 000000000..6d3929882 --- /dev/null +++ b/cmd/bd/testdata/agent_artifacts/init-default.golden @@ -0,0 +1,274 @@ +# bd init agent artifact transcript: init-default +# Regenerate with BEADS_TEST_EMBEDDED_DOLT=1 BD_UPDATE_GOLDEN=1 go test -tags gms_pure_go ./cmd/bd/ -run TestEmbeddedInitAgentArtifactsGolden + +=== bd init --quiet --prefix aa +--- files: created $PROJECT/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: created $PROJECT/AGENTS.md +# Agent Instructions + +This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context. + +> **Architecture in one line:** Issues live in a local Dolt database +> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a +> git-compatible protocol), stored under `refs/dolt/data` on your git +> remote — separate from `refs/heads/*` where your code lives. +> `.beads/issues.jsonl` is a passive export, not the wire protocol. +> +> See [sync-concepts](https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md) +> for the one-screen overview and anti-patterns (don't treat JSONL as the +> source of truth; don't `bd import` during normal operation; don't +> reach for third-party Dolt hosting before trying the default). + +## Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work atomically +bd close # Complete work +bd dolt push # Push beads data to remote +``` + +## Non-Interactive Shell Commands + +**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts. + +Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input. + +**Use these forms instead:** +```bash +# Force overwrite without prompting +cp -f source dest # NOT: cp source dest +mv -f source dest # NOT: mv source dest +rm -f file # NOT: rm file + +# For recursive operations +rm -rf directory # NOT: rm -r directory +cp -rf source dest # NOT: cp -r source dest +``` + +**Other commands that may prompt:** +- `scp` - use `-o BatchMode=yes` for non-interactive +- `ssh` - use `-o BatchMode=yes` to fail instead of prompting +- `apt-get` - use `-y` flag +- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md] + + + +## Beads Issue Tracker + +Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +bd prime # Refresh Beads context +``` + +### Rules + +- Use `bd` for all task tracking; do not create markdown TODO lists. +- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them. +- Keep durable project facts in Beads via `bd remember` rather than in per-tool memory files, which fragment across accounts; per-operator preferences belong in your harness's own memory. + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +--- files: created $PROJECT/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md] + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +exit: 0 +--- stdout +✓ Project hooks installed: $PROJECT/.claude/settings.json +✓ Claude Code integration installed: $PROJECT/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude +exit: 0 +--- stdout +Installing Claude hooks for this project... +✓ Hook already registered: SessionStart +Installing Claude Code integration... +✓ Updated existing beads section in CLAUDE.md + +✓ Claude Code integration installed + File: $PROJECT/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $PROJECT/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude --remove +exit: 0 +--- stdout +Removing Claude hooks from project... +✓ Removed SessionStart hook +Removing Claude Code integration... +✓ Removed beads section from CLAUDE.md +✓ Claude hooks removed +--- stderr +(empty) +--- files: modified $PROJECT/.claude/settings.json +{ + "hooks": {} +} +--- files: modified $PROJECT/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + +=== bd setup claude --check +exit: 1 +--- stdout +✗ No hooks installed + Run: bd setup claude +--- stderr +(empty) +--- files: unchanged + +=== bd setup claude +exit: 0 +--- stdout +Installing Claude hooks for this project... +✓ Registered SessionStart hook +Installing Claude Code integration... +✓ Added beads section to existing CLAUDE.md + +✓ Claude Code integration installed + File: $PROJECT/CLAUDE.md +No additional configuration needed! + +✓ Claude Code integration installed + Settings: $PROJECT/.claude/settings.json + +Restart Claude Code for changes to take effect. +--- stderr +(empty) +--- files: modified $PROJECT/.claude/settings.json +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "command": "bd prime --hook-json", + "type": "command" + } + ], + "matcher": "" + } + ] + } +} +--- files: modified $PROJECT/CLAUDE.md +# Project Instructions for AI Agents + +This file provides instructions and context for AI coding agents working on this project. + + + +## Build & Test + +_Add your build and test commands here_ + +```bash +# Example: +# npm install +# npm test +``` + +## Architecture Overview + +_Add a brief overview of your project architecture_ + +## Conventions & Patterns + +_Add your project-specific conventions here_ + + + +[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md] + + +=== bd setup claude --check +exit: 0 +--- stdout +✓ Project hooks installed: $PROJECT/.claude/settings.json +✓ Claude Code integration installed: $PROJECT/CLAUDE.md (current) +--- stderr +(empty) +--- files: unchanged diff --git a/internal/templates/agents/BUILD.bazel b/internal/templates/agents/BUILD.bazel index c51ae9c90..8ad3255df 100644 --- a/internal/templates/agents/BUILD.bazel +++ b/internal/templates/agents/BUILD.bazel @@ -20,8 +20,10 @@ go_test( name = "agents_test", srcs = [ "agents_test.go", + "golden_test.go", "render_test.go", ], + data = glob(["testdata/**"]), embed = [":agents"], ) diff --git a/internal/templates/agents/golden_test.go b/internal/templates/agents/golden_test.go new file mode 100644 index 000000000..e49b0acf8 --- /dev/null +++ b/internal/templates/agents/golden_test.go @@ -0,0 +1,133 @@ +package agents + +import ( + "fmt" + "os" + "path/filepath" + "strings" + "testing" +) + +// The tests in this file pin the exact managed sections `bd init` and +// `bd setup ` write between the BEGIN/END BEADS INTEGRATION markers of +// CLAUDE.md, AGENTS.md and the other instruction files. A change to a template +// (new guidance, a reworded rule, an added section) changes the bytes every +// user's instruction file receives and, through the marker hash, marks every +// section already installed as stale: `bd setup claude --check` then fails and +// the next `bd init` or `bd setup` rewrites the user's file. Such a change must +// therefore arrive as a reviewed golden diff, never as a side effect. +// +// Regenerate the golden files with +// +// BD_UPDATE_GOLDEN=1 go test ./internal/templates/agents/ -run TestManagedSectionGolden +// +// and update the literal hashes in TestManagedSectionHashes by hand. + +// managedSectionVariant is one managed section bd can render. +type managedSectionVariant struct { + name string + profile Profile + opts RenderOpts +} + +// managedSectionVariants lists every managed section bd renders: both +// profiles, each with and without the `bd dolt push` lines that depend on a +// configured Dolt remote. NoPush renders the no-remote bytes +// (TestManagedSectionNoPushMatchesNoRemote), so it needs no variant of its own. +var managedSectionVariants = []managedSectionVariant{ + {name: "minimal", profile: ProfileMinimal, opts: RenderOpts{HasRemote: true}}, + {name: "minimal-no-remote", profile: ProfileMinimal, opts: RenderOpts{}}, + {name: "full", profile: ProfileFull, opts: RenderOpts{HasRemote: true}}, + {name: "full-no-remote", profile: ProfileFull, opts: RenderOpts{}}, +} + +// TestManagedSectionGolden pins each managed section byte for byte, markers +// included. +func TestManagedSectionGolden(t *testing.T) { + for _, v := range managedSectionVariants { + t.Run(v.name, func(t *testing.T) { + assertGoldenFile(t, filepath.Join("testdata", "managed-section-"+v.name+".md"), RenderSectionWithOpts(v.profile, v.opts)) + }) + } +} + +// TestManagedSectionHashes pins the marker hash of each managed section. The +// hash is what `bd setup --check` compares against an installed +// section, so changing it marks every existing install stale. It is a literal +// that BD_UPDATE_GOLDEN does not rewrite: a template change has to bump it by +// hand. +func TestManagedSectionHashes(t *testing.T) { + want := map[string]string{ + "minimal": "6ffdf896", + "minimal-no-remote": "cdcea925", + "full": "bacef91e", + "full-no-remote": "9c890b20", + } + for _, v := range managedSectionVariants { + got := CurrentHashWithOpts(v.profile, v.opts) + if got != want[v.name] { + t.Errorf("%s managed section hash = %q, want %q: the template changed, so every installed %s section is now stale", v.name, got, want[v.name], v.profile) + } + marker := "\n" + if section := RenderSectionWithOpts(v.profile, v.opts); !strings.HasPrefix(section, marker) { + first, _, _ := strings.Cut(section, "\n") + t.Errorf("%s managed section marker = %q, want %q", v.name, first, strings.TrimSuffix(marker, "\n")) + } + } +} + +// TestManagedSectionNoPushMatchesNoRemote pins that a local-only workspace +// (no-push: true) gets the same managed section as one with no Dolt remote, +// whatever the remote state. +func TestManagedSectionNoPushMatchesNoRemote(t *testing.T) { + for _, profile := range []Profile{ProfileMinimal, ProfileFull} { + want := RenderSectionWithOpts(profile, RenderOpts{}) + for _, hasRemote := range []bool{false, true} { + if got := RenderSectionWithOpts(profile, RenderOpts{HasRemote: hasRemote, NoPush: true}); got != want { + t.Errorf("%s profile with NoPush (HasRemote=%v) differs from the no-remote section", profile, hasRemote) + } + } + } +} + +// assertGoldenFile compares got with the golden file at path, or rewrites the +// file when BD_UPDATE_GOLDEN=1. +func assertGoldenFile(t *testing.T, path, got string) { + t.Helper() + if os.Getenv("BD_UPDATE_GOLDEN") == "1" { + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatalf("mkdir %s: %v", filepath.Dir(path), err) + } + if err := os.WriteFile(path, []byte(got), 0o644); err != nil { + t.Fatalf("write golden %s: %v", path, err) + } + t.Logf("updated golden %s", path) + return + } + want, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read golden %s (regenerate with BD_UPDATE_GOLDEN=1): %v", path, err) + } + if got == string(want) { + return + } + t.Errorf("rendered output drifted from %s (regenerate with BD_UPDATE_GOLDEN=1 if intended)\n%s", path, firstGoldenDifference(string(want), got)) +} + +// firstGoldenDifference describes the first line on which want and got differ. +func firstGoldenDifference(want, got string) string { + wantLines := strings.Split(want, "\n") + gotLines := strings.Split(got, "\n") + line := func(lines []string, i int) string { + if i >= len(lines) { + return "(end of output)" + } + return fmt.Sprintf("%q", lines[i]) + } + for i := 0; i < len(wantLines) || i < len(gotLines); i++ { + if i >= len(wantLines) || i >= len(gotLines) || wantLines[i] != gotLines[i] { + return fmt.Sprintf("first difference at line %d:\n want: %s\n got: %s", i+1, line(wantLines, i), line(gotLines, i)) + } + } + return "outputs differ" +} diff --git a/internal/templates/agents/testdata/managed-section-full-no-remote.md b/internal/templates/agents/testdata/managed-section-full-no-remote.md new file mode 100644 index 000000000..526550030 --- /dev/null +++ b/internal/templates/agents/testdata/managed-section-full-no-remote.md @@ -0,0 +1,129 @@ + +## Issue Tracking with bd (beads) + +**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. + +### Why bd? + +- Dependency-aware: Track blockers and relationships between issues +- Git-friendly: Dolt-powered version control with native sync +- Agent-optimized: JSON output, ready work detection, discovered-from links +- Prevents duplicate tracking systems and confusion + +### Quick Start + +**Check for ready work:** + +```bash +bd ready --json +``` + +**Create new issues:** + +```bash +bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json +bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json +``` + +**Claim and update:** + +```bash +bd update --claim --json +bd update bd-42 --priority 1 --json +``` + +**Complete work:** + +```bash +bd close bd-42 --reason "Completed" --json +``` + +### Issue Types + +- `bug` - Something broken +- `feature` - New functionality +- `task` - Work item (tests, docs, refactoring) +- `epic` - Large feature with subtasks +- `chore` - Maintenance (dependencies, tooling) + +### Priorities + +- `0` - Critical (security, data loss, broken builds) +- `1` - High (major features, important bugs) +- `2` - Medium (default, nice-to-have) +- `3` - Low (polish, optimization) +- `4` - Backlog (future ideas) + +### Workflow for AI Agents + +1. **Check ready work**: `bd ready` shows unblocked issues +2. **Claim your task atomically**: `bd update --claim` +3. **Work on it**: Implement, test, document +4. **Discover new work?** Create linked issue: + - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:` +5. **Complete**: `bd close --reason "Done"` + +### Quality +- Use `--acceptance` and `--design` fields when creating issues +- Use `--validate` to check description completeness + +### Lifecycle +- `bd defer ` / `bd supersede ` for issue management +- `bd stale` / `bd orphans` / `bd lint` for hygiene +- `bd human ` to flag for human decisions +- `bd formula list` / `bd mol pour ` for structured workflows + +### Sync + +bd stores issue history in Dolt: + +- Each write auto-commits to Dolt history +- Do not treat `.beads/issues.jsonl` as the sync protocol + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +### 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?" +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT use external issue trackers +- ❌ Do NOT duplicate tracking systems + +For more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. + + diff --git a/internal/templates/agents/testdata/managed-section-full.md b/internal/templates/agents/testdata/managed-section-full.md new file mode 100644 index 000000000..831c2b736 --- /dev/null +++ b/internal/templates/agents/testdata/managed-section-full.md @@ -0,0 +1,131 @@ + +## Issue Tracking with bd (beads) + +**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods. + +### Why bd? + +- Dependency-aware: Track blockers and relationships between issues +- Git-friendly: Dolt-powered version control with native sync +- Agent-optimized: JSON output, ready work detection, discovered-from links +- Prevents duplicate tracking systems and confusion + +### Quick Start + +**Check for ready work:** + +```bash +bd ready --json +``` + +**Create new issues:** + +```bash +bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json +bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json +``` + +**Claim and update:** + +```bash +bd update --claim --json +bd update bd-42 --priority 1 --json +``` + +**Complete work:** + +```bash +bd close bd-42 --reason "Completed" --json +``` + +### Issue Types + +- `bug` - Something broken +- `feature` - New functionality +- `task` - Work item (tests, docs, refactoring) +- `epic` - Large feature with subtasks +- `chore` - Maintenance (dependencies, tooling) + +### Priorities + +- `0` - Critical (security, data loss, broken builds) +- `1` - High (major features, important bugs) +- `2` - Medium (default, nice-to-have) +- `3` - Low (polish, optimization) +- `4` - Backlog (future ideas) + +### Workflow for AI Agents + +1. **Check ready work**: `bd ready` shows unblocked issues +2. **Claim your task atomically**: `bd update --claim` +3. **Work on it**: Implement, test, document +4. **Discover new work?** Create linked issue: + - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:` +5. **Complete**: `bd close --reason "Done"` + +### Quality +- Use `--acceptance` and `--design` fields when creating issues +- Use `--validate` to check description completeness + +### Lifecycle +- `bd defer ` / `bd supersede ` for issue management +- `bd stale` / `bd orphans` / `bd lint` for hygiene +- `bd human ` to flag for human decisions +- `bd formula list` / `bd mol pour ` for structured workflows + +### Sync + +bd stores issue history in Dolt: + +- Each write auto-commits to Dolt history +- Use `bd dolt push`/`bd dolt pull` for remote sync +- Do not treat `.beads/issues.jsonl` as the sync protocol + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +### 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?" +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT use external issue trackers +- ❌ Do NOT duplicate tracking systems + +For more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + bd dolt push + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. + + diff --git a/internal/templates/agents/testdata/managed-section-minimal-no-remote.md b/internal/templates/agents/testdata/managed-section-minimal-no-remote.md new file mode 100644 index 000000000..1ab497bff --- /dev/null +++ b/internal/templates/agents/testdata/managed-section-minimal-no-remote.md @@ -0,0 +1,54 @@ + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +``` + +### Rules + +- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists +- Run `bd prime` for detailed command reference and session close protocol +- Use `bd remember` for durable project facts — not per-tool memory files, which fragment across accounts; keep per-operator preferences in your harness's own memory + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. + diff --git a/internal/templates/agents/testdata/managed-section-minimal.md b/internal/templates/agents/testdata/managed-section-minimal.md new file mode 100644 index 000000000..22c48412a --- /dev/null +++ b/internal/templates/agents/testdata/managed-section-minimal.md @@ -0,0 +1,55 @@ + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +``` + +### Rules + +- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists +- Run `bd prime` for detailed command reference and session close protocol +- Use `bd remember` for durable project facts — not per-tool memory files, which fragment across accounts; keep per-operator preferences in your harness's own memory + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + bd dolt push + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. +