Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue. - Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files. - Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup. - ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228). - docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names. Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
4.5 KiB
cmd/bd — contributor notes
cmd/bd is the bd CLI: one Go package (about 340 non-test files) plus the
doctor/, setup/, protocol/, help_supplements/, and winres/
subpackages. Commands decide what to do; storage work belongs below them in
internal/storage/issueops (see the layering rules in
CONTRIBUTING_PR_GUIDELINES.md).
File families
| Pattern | Meaning |
|---|---|
<cmd>.go |
The Cobra command, its flags, and the mode-independent body. Registers itself with rootCmd.AddCommand in its own init() — main.go adds no commands. |
<cmd>_proxied_server.go |
The proxied-server route for the same command. A command that touches the store on a proxied-server workspace needs one. |
capability_registry.go |
One table for every command path: what the pre-provider gate does with it on a proxied-server workspace. |
<cmd>_embedded_test.go |
cgo tests against embedded Dolt. |
<cmd>_integration_test.go |
Integration tests, usually cgo && unix. |
<cmd>_proxied_test.go |
Proxied-server tests. |
<topic>_guard_test.go |
Policy and safety guards. |
Which tier a test belongs in, and which command runs it, is decided by engdocs/TESTING.md.
Adding a command
- Create
cmd/bd/<cmd>.gowith the Cobra command and register it in that file'sinit(). - Add its row to
capability_registry.go.TestProxyCapabilityRegistryCoversCommandTreefails if a command path is missing, andTestProxyCapabilityRegistryHasNoStaleRowsfails on rows for paths that no longer exist. - If the command uses the store on proxied-server workspaces, add
<cmd>_proxied_server.go. - Support
--jsonfor agent use. The--jsonwire surface is pinned by the golden corpus inprotocol/(TestCorpusGolden; regenerate withmake corpus-regenand review the diff — seeprotocol/CATALOG.md). - Add tests in the right tier.
- Regenerate the CLI reference with
scripts/generate-cli-docs.sh;scripts/check-cli-docs-drift.shfails a PR whose command-surface change leaves the generated docs stale.
Prefer a flag on an existing command over a new command, and route
recovery/repair operations to bd doctor --fix; see the CLI design principles
in engdocs/UI_PHILOSOPHY.md.
Boundaries enforced by lint
From .golangci.yml (read the rule comments there before changing scope):
cmd-bd-role-constructors(depguard, all ofcmd/bd/**): "a command reaches the reader role through store.IssueReader(), never through the constructor: the accessor is where each storage decorator adds its layer". The same applies tostore.Counter(),store.WorkspaceConfig(),store.VersionReconciler(),store.StatsReporter(),store.ReadyCounter(), andstore.Querier().cmd-bd-domain-boundary(depguard,label.goandstate.go): "bd label and bd state reach storage through an issueops role accessor, never through the domain use cases - see openIssueLifecycle in cmd/bd/label.go".- forbidigo
LabelUseCase$: "reach the label plane through issueops.Lifecycle (Patch.Labels) and issueops.Reader, never the domain use case". - forbidigo
types.IssueFilter/types.WorkFilter: "do not write a filter here: take one back from a builder in internal/workapi, or pass the whole request to issueops.Reader".cmd/bddenies these by default; the files allowed to build their own filters are listed, with reasons, in.golangci.yml. - forbidigo
fmt.Print*/os.Stdoutin list/graph code: "route format output through the command writer; mark an intentional non-format path locally".
A deliberate exception is marked on its line with
//nolint:forbidigo // <reason>; the reason is expected (review checks it;
no linter enforces it).
Guard tests
TestEveryStoreConstructionActivatesTheEventsJournal— every store construction site activates the events journal; new non-bead-writing sites go in its exemption table with a reason.TestProxyCapabilityRegistryCoversCommandTreeand the otherTestProxyCapabilityRegistry*tests — the registry stays complete and consistent.TestCobraParallelPolicyGuard— a test that callst.Parallel()must not call the Cobra methods incobraParallelUnsafeMethods; dropt.Parallel()or serialize the call understdioMutex.TestCorpusGolden(protocol/) — no unreviewed change to the--jsonwire shapes.
Fresh-workspace command fixtures call isolateBeadsDirForTest(t) before
setup or dispatch and must not use t.Parallel().