bd prime should be SSOT for agent instructions — init/setup/prime overlap wastes ~300 tokens/session

[miteshashar]

Summary

bd init, bd setup <tool>, and bd prime have overlapping content with no clear ownership, leading to staleness, redundancy, and wasted context window tokens.

Follow-up to #516 which automated Landing the Plane in bd init but didn't address setup commands, content freshness, or the relationship with bd prime.

Problem

1. Content divergence between init and setup

• bd init uses agents.md.tmpl which contains stale references (bd sync, JSONL auto-sync)
• bd setup codex generates current Dolt-native content (no JSONL, bd dolt push/pull)
• Same logical section, different output depending on which command was run

2. Staleness after initial write

• Both commands check for BEGIN BEADS INTEGRATION marker presence
• If the section exists, content is never updated — even if the template has changed
• Projects initialized months ago still carry stale instructions (e.g., bd sync which is now a no-op)
• No mechanism to detect or offer content updates

3. Context window waste from bd prime vs agent file overlap

Both bd prime (loaded via hooks on session start) and the BEADS INTEGRATION section (from CLAUDE.md/AGENTS.md) land in the agent's context. ~300 tokens/session are wasted on duplicated content:

Content	bd prime	AGENTS.md	Redundant?
"Use bd for ALL tracking"	✅	✅	Yes
"No TodoWrite/markdown"	✅	✅	Yes
bd ready/show/close/create	✅ with examples	✅ with examples	Heavy overlap
bd dolt push/pull	✅	✅	Yes
Session close / git push	✅ (detailed)	❌	Unique to prime
Issue types, priorities	Compressed	Full descriptions	Partial
discovered-from, --json	❌	✅	Unique to AGENTS.md

4. Landing the Plane is orphaned

• bd init adds it (with stale bd sync reference)
• bd setup * does not add or manage it
• Once written, it becomes unmanaged content with no upgrade path
• Conceptually it's operational (session workflow), not instructional — belongs in prime

Proposed Solution

A. Separate concerns by surface

Surface	Role	Content type	Update mechanism
bd prime (hooks)	How-to reference	Commands, syntax, workflows, session protocol, Landing the Plane	Dynamic — always current with bd version
Agent instruction files	Static mandate	"Use bd for tracking", rationale, constraints, rules	Versioned — hash-based markers (see below)

Principle: Prime = dynamic SSOT for commands and workflows. Agent files = static what/why (mandate, rationale, rules).

B. Hash-based content markers for freshness

Replace:

<!-- BEGIN BEADS INTEGRATION -->

With:

<!-- BEGIN BEADS INTEGRATION v:a1b2c3d4 -->

Where the hash is derived from the template content (first 8 chars of SHA-256).

Behavior:

• On bd setup or bd init: compute current template hash, compare with marker hash
• If match → skip (idempotent, already current)
• If mismatch → offer to update (replace content between markers, preserve everything outside)
• If no marker → append (current behavior)

C. Single template, used by both init and setup

Eliminate agents.md.tmpl vs bd setup codex divergence. One template, one source of truth for the BEADS INTEGRATION section content.

D. Minimal agent file content where prime handles the rest

For agents that receive bd prime via hooks (Claude, Gemini), the BEADS INTEGRATION section can be reduced to:

<!-- BEGIN BEADS INTEGRATION v:a1b2c3d4 -->
This project uses **bd (beads)** for issue tracking. Run `bd prime` for commands and workflow reference.
<!-- END BEADS INTEGRATION -->

Zero redundancy. Prime is the SSOT. Always current.

For agents without hook support (e.g., Codex), the full content is still needed in the agent file. See #2140 for how each bd setup <tool> should target the right file with the right content level.

Benefits

• No redundancy: prime owns operational content, agent files own mandate
• Always current: prime updates with bd version, no stale agent files
• Context-efficient: ~500 tokens saved per session for hook-enabled agents
• Discoverable: new features reach existing projects via prime (no file update needed)
• Idempotent: hash-based markers make re-running setup safe and convergent
• User content preserved: only content between markers is touched