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) <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
This commit is contained in:
Julian Knutsen 2026-10-19 05:19:28 +00:00 • committed by GitHub
commit eb5ab48950
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 2589 additions and 1 deletions

View file

@ -136,6 +136,7 @@
100 54 TestEmbeddedDiscoveryPinsEnvFileReadonly
100 54 TestEmbeddedFormatJSONAliasMatchesJSON
100 54 TestEmbeddedInitAgentArtifactsGolden
100 54 TestEmbeddedSearchConcurrent
100 55 TestEmbeddedUndefer

View file

@ -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",

View file

@ -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 = "<!-- END BEADS INTEGRATION -->\n"
begin := strings.Index(content, "<!-- BEGIN BEADS INTEGRATION")
if begin < 0 {
return content
}
rel := strings.Index(content[begin:], endMarker)
if rel < 0 {
return content
}
end := begin + rel + len(endMarker)
section := content[begin:end]
for _, v := range agentArtifactManagedSections {
if section == agents.RenderSectionWithOpts(v.profile, v.opts) {
marker, _, _ := strings.Cut(section, "\n")
return content[:begin] + marker + "\n[managed section body: byte-identical to internal/templates/agents/testdata/" + v.golden + "]\n" + endMarker + content[end:]
}
}
return content
}
// runAgentArtifactCommand runs bd in dir with HOME at home and returns its
// stdout, stderr and exit code.
func runAgentArtifactCommand(t *testing.T, bd, dir, home string, args ...string) (stdout, stderr string, exitCode int) {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
cmd.Env = agentArtifactEnv(dir, home)
outBuf, errBuf, err := runCommandBuffers(t, cmd)
if err != nil {
var exitErr *exec.ExitError
if !errors.As(err, &exitErr) {
t.Fatalf("bd %s: %v", strings.Join(args, " "), err)
}
exitCode = exitErr.ExitCode()
}
return outBuf.String(), errBuf.String(), exitCode
}
// agentArtifactEnv is bdEnv(dir) with HOME at home and without the caller's
// BD_OTEL_* and OTEL_* variables: bd warns on stderr about a legacy BD_OTEL_*
// one whether or not telemetry is on, and the transcript pins stderr byte for
// byte. (clearTelemetryEnv cannot be used: it calls t.Setenv, and these tests
// run in parallel.)
func agentArtifactEnv(dir, home string) []string {
var env []string
for _, e := range bdEnv(dir) {
if strings.HasPrefix(e, "BD_OTEL_") || strings.HasPrefix(e, "OTEL_") || strings.HasPrefix(e, "HOME=") {
continue
}
env = append(env, e)
}
return append(env, "HOME="+home)
}
// writeAgentArtifactChanges appends every artifact created, modified or
// deleted since previous (which it then updates), with its contents.
func writeAgentArtifactChanges(t *testing.T, b *strings.Builder, dir, home string, previous map[string]string) {
t.Helper()
roots := strings.NewReplacer("$PROJECT", dir, "$HOME", home)
changed := false
for _, path := range agentArtifactPaths {
data, err := os.ReadFile(filepath.FromSlash(roots.Replace(path)))
before, existed := previous[path]
switch {
case os.IsNotExist(err):
if existed {
fmt.Fprintf(b, "--- files: deleted %s\n", path)
delete(previous, path)
changed = true
}
case err != nil:
t.Fatalf("read %s: %v", path, err)
case !existed || before != string(data):
verb := "created"
if existed {
verb = "modified"
}
shown := string(data)
if strings.HasSuffix(path, ".md") {
shown = elideAgentArtifactManagedSection(shown)
}
writeAgentArtifactBlock(b, fmt.Sprintf("files: %s %s", verb, path), shown)
previous[path] = string(data)
changed = true
}
}
if !changed {
b.WriteString("--- files: unchanged\n")
}
}
// writeAgentArtifactBlock appends a titled block, marking empty content and a
// missing trailing newline so neither is lost in the golden.
func writeAgentArtifactBlock(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)
}
}
// normalizeAgentArtifactOutput replaces the project and home directories (as
// given and with symlinks resolved, since bd reports the paths it sees) with
// $PROJECT and $HOME and uses forward slashes, so the transcript is the same
// on every host.
func normalizeAgentArtifactOutput(s, dir, home string) string {
for _, root := range []struct{ path, label string }{{dir, "$PROJECT"}, {home, "$HOME"}} {
if resolved, err := filepath.EvalSymlinks(root.path); err == nil && resolved != root.path {
s = strings.ReplaceAll(s, resolved, root.label)
}
s = strings.ReplaceAll(s, root.path, root.label)
}
if filepath.Separator != '/' {
s = strings.ReplaceAll(s, string(filepath.Separator), "/")
}
return s
}
// assertAgentArtifactGolden compares got with the golden file at path, or
// rewrites the file when BD_UPDATE_GOLDEN=1.
func assertAgentArtifactGolden(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("bd init 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)
}

View file

@ -37,6 +37,7 @@ go_test(
srcs = [
"agents_marker_test.go",
"aider_test.go",
"claude_artifacts_golden_test.go",
"claude_test.go",
"codex_test.go",
"cursor_test.go",
@ -49,7 +50,7 @@ go_test(
"project_output_test.go",
"utils_test.go",
],
data = [
data = glob(["testdata/**"]) + [
"//:.claude-plugin/marketplace.json",
"//plugins/beads:plugin_files",
],

View file

@ -0,0 +1,494 @@
package setup
import (
"bytes"
"fmt"
"os"
"path/filepath"
"sort"
"strings"
"testing"
"github.com/steveyegge/beads/internal/templates/agents"
)
// The tests in this file pin the agent artifacts `bd setup claude` writes, and
// what its --check and --remove report and leave behind: the hook events and
// commands in the Claude settings files, the CLAUDE.md / AGENTS.md files with
// their managed section, and the output of each step. Each scenario is a
// transcript golden under testdata/, so a change to any of them (a new hook
// event, a changed hook command, new template text, a different --check or
// --remove outcome) 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. A template change therefore shows up once, as that golden's diff,
// and here as the new marker hash in every file it lands in. A section that
// matches no rendered variant is shown in full. The `bd init` side of the same
// artifacts is pinned by TestEmbeddedInitAgentArtifactsGolden in cmd/bd.
//
// Regenerate with
//
// BD_UPDATE_GOLDEN=1 go test ./cmd/bd/setup/ -run TestClaudeSetupArtifactsGolden
// claudeArtifactPaths are the files bd setup claude can create, change or
// delete, relative to the root holding the test's project and home dirs.
var claudeArtifactPaths = []string{
"home/.claude/settings.json",
"project/.claude/settings.json",
"project/.claude/settings.local.json",
"project/AGENTS.md",
"project/CLAUDE.md",
}
// managedSectionGoldens maps each managed section bd renders to the
// internal/templates/agents golden file that pins its bytes.
var managedSectionGoldens = []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{}},
}
// elideManagedSection 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 END marker.
func elideManagedSection(content string) string {
const endMarker = "<!-- END BEADS INTEGRATION -->\n"
begin := strings.Index(content, "<!-- BEGIN BEADS INTEGRATION")
if begin < 0 {
return content
}
rel := strings.Index(content[begin:], endMarker)
if rel < 0 {
return content
}
end := begin + rel + len(endMarker)
section := content[begin:end]
for _, v := range managedSectionGoldens {
if section == agents.RenderSectionWithOpts(v.profile, v.opts) {
marker, _, _ := strings.Cut(section, "\n")
return content[:begin] + marker + "\n[managed section body: byte-identical to internal/templates/agents/testdata/" + v.golden + "]\n" + endMarker + content[end:]
}
}
return content
}
type claudeArtifactStep struct {
title string
run func(env claudeEnv) error
}
func claudeInstallStep(global, stealth bool) claudeArtifactStep {
title := "bd setup claude"
if global {
title += " --global"
}
if stealth {
title += " --stealth"
}
return claudeArtifactStep{title: title, run: func(env claudeEnv) error { return installClaude(env, global, stealth) }}
}
func claudeCheckStep() claudeArtifactStep {
return claudeArtifactStep{title: "bd setup claude --check", run: checkClaude}
}
func claudeRemoveStep(global bool) claudeArtifactStep {
title := "bd setup claude --remove"
if global {
title += " --global"
}
return claudeArtifactStep{title: title, run: func(env claudeEnv) error { return removeClaude(env, global) }}
}
func TestClaudeSetupArtifactsGolden(t *testing.T) {
// The managed section's `bd dolt push` lines depend on whether a Dolt
// remote is configured; these scenarios render the with-remote variant
// (TestEmbeddedInitAgentArtifactsGolden pins the no-remote one).
stubDetectRenderOpts(t)
userSettings := `{
"permissions": {
"allow": [
"Bash(go test:*)"
]
},
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo session started"
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send done"
}
]
}
]
}
}
`
// What an older bd wrote to settings.local.json, before hooks moved to
// settings.json and to the SessionStart JSON envelope.
legacyLocalSettings := `{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bd prime"
}
]
}
],
"PreCompact": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bd prime"
}
]
}
]
}
}
`
// The settings.json a current install writes.
installedSettings := `{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"command": "bd prime --hook-json",
"type": "command"
}
],
"matcher": ""
}
]
}
}
`
scenarios := []struct {
name string
seed map[string]string
steps []claudeArtifactStep
}{
{
name: "project",
steps: []claudeArtifactStep{
claudeInstallStep(false, false),
claudeCheckStep(),
claudeInstallStep(false, false),
claudeRemoveStep(false),
claudeCheckStep(),
},
},
{
name: "project-stealth",
steps: []claudeArtifactStep{
claudeInstallStep(false, true),
claudeCheckStep(),
claudeRemoveStep(false),
claudeCheckStep(),
},
},
{
name: "global",
steps: []claudeArtifactStep{
claudeInstallStep(true, false),
claudeCheckStep(),
claudeRemoveStep(true),
claudeCheckStep(),
},
},
{
// User-owned settings and instructions: install merges into
// them and --remove takes back only what bd added.
name: "existing-user-files",
seed: map[string]string{
"project/.claude/settings.json": userSettings,
"project/CLAUDE.md": "# My Project\n\nHouse rules live here.\n",
},
steps: []claudeArtifactStep{
claudeInstallStep(false, false),
claudeCheckStep(),
claudeRemoveStep(false),
claudeCheckStep(),
},
},
{
// A section written by an older bd (its hash no longer matches
// the template): --check reports it stale and install rewrites
// it in place.
name: "stale-section",
seed: map[string]string{
"project/.claude/settings.json": installedSettings,
"project/CLAUDE.md": "# My Project\n\n<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:00000000 -->\nOlder beads guidance.\n<!-- END BEADS INTEGRATION -->\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)
}

View file

@ -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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
=== 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

View file

@ -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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
=== 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

View file

@ -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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
## 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

View file

@ -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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
## 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_

View file

@ -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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
## 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

View file

@ -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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
## 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

View file

@ -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
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:00000000 -->
Older beads guidance.
<!-- END BEADS INTEGRATION -->
## 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
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal.md]
<!-- END BEADS INTEGRATION -->
## 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

View file

@ -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 <id> # View issue details
bd update <id> --claim # Claim work atomically
bd close <id> # 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
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:9c890b20 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-full-no-remote.md]
<!-- END BEADS INTEGRATION -->
<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
## 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 <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # 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.
<!-- END BEADS CODEX SETUP -->
--- files: created $PROJECT/CLAUDE.md
# Project Instructions for AI Agents
This file provides instructions and context for AI coding agents working on this project.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:cdcea925 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md]
<!-- END BEADS INTEGRATION -->
## 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

View file

@ -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 <id> # View issue details
bd update <id> --claim # Claim work atomically
bd close <id> # 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
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:cdcea925 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md]
<!-- END BEADS INTEGRATION -->
<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
## 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 <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # 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.
<!-- END BEADS CODEX SETUP -->
--- files: created $PROJECT/CLAUDE.md
# Project Instructions for AI Agents
This file provides instructions and context for AI coding agents working on this project.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:cdcea925 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md]
<!-- END BEADS INTEGRATION -->
## 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_
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:cdcea925 -->
[managed section body: byte-identical to internal/templates/agents/testdata/managed-section-minimal-no-remote.md]
<!-- END BEADS INTEGRATION -->
=== 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

View file

@ -20,8 +20,10 @@ go_test(
name = "agents_test",
srcs = [
"agents_test.go",
"golden_test.go",
"render_test.go",
],
data = glob(["testdata/**"]),
embed = [":agents"],
)

View file

@ -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 <agent>` 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 <agent> --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 := "<!-- BEGIN BEADS INTEGRATION v:1 profile:" + string(v.profile) + " hash:" + want[v.name] + " -->\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"
}

View file

@ -0,0 +1,129 @@
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:9c890b20 -->
## 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 <id> --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 <id> --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:<parent-id>`
5. **Complete**: `bd close <id> --reason "Done"`
### Quality
- Use `--acceptance` and `--design` fields when creating issues
- Use `--validate` to check description completeness
### Lifecycle
- `bd defer <id>` / `bd supersede <id>` for issue management
- `bd stale` / `bd orphans` / `bd lint` for hygiene
- `bd human <id>` to flag for human decisions
- `bd formula list` / `bd mol pour <name>` 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.
<!-- END BEADS INTEGRATION -->

View file

@ -0,0 +1,131 @@
<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:bacef91e -->
## 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 <id> --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 <id> --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:<parent-id>`
5. **Complete**: `bd close <id> --reason "Done"`
### Quality
- Use `--acceptance` and `--design` fields when creating issues
- Use `--validate` to check description completeness
### Lifecycle
- `bd defer <id>` / `bd supersede <id>` for issue management
- `bd stale` / `bd orphans` / `bd lint` for hygiene
- `bd human <id>` to flag for human decisions
- `bd formula list` / `bd mol pour <name>` 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.
<!-- END BEADS INTEGRATION -->

View file

@ -0,0 +1,54 @@
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:cdcea925 -->
## 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 <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # 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.
<!-- END BEADS INTEGRATION -->

View file

@ -0,0 +1,55 @@
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:6ffdf896 -->
## 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 <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # 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.
<!-- END BEADS INTEGRATION -->