* ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) Lint and vet now run as nogo inside the Bazel build, so they gate wherever the Bazel lanes execute (rbe-west), and the golangci-lint and go vet jobs leave pr.yml and main.yml. - //tools/nogo (own go.mod, joined to beads' for go_deps only through gazelle.go.work): go test's vet checks (cmd/go's defaultVetFlags, the set scripts/ci/go-test-vet.sh ran) plus the eight linters .golangci.yml enables, each a wrapper over the library version golangci-lint v2.10.1 uses (depguard, errcheck, forbidigo, gosec, misspell, sloglint, unconvert, unparam). - .golangci.yml stays the single lint policy: Bazel embeds it and tools/nogo/internal/golangci applies it as golangci-lint does (enabled set, settings, run.tests: false as library-unit-only analysis, lax generated-file detection, path/path-except/text exclusion rules), with strict decoding so an unimplemented key fails the build. - gascity's rules_go //nolint-range patch and x/tools ctrlflow patch, byte-identical. - Windows/darwin: cross-configured, not a golangci leg. The pure lane's release cross-compile (//tools/bazel:release_cross, every library and binary for all eight release platforms, cgo off) runs nogo on every compile, a superset of golangci-lint's windows and darwin legs. scripts/pr-lint (make ci-pr-lint, bd preflight) runs `bazel build --config=nogo //...` plus release_cross for windows_amd64,darwin_arm64. release_cross skips tools/nogo, a separate Go module `go build ./...` never compiled. - pr.yml: scripts-go-checks (vet) and pr-lint-wrapper (x3) are gone, with their ci-gate entries; main.yml: pr-lint-wrapper (x6) and go-vet-cache. scripts/ci/go-test-vet.sh and install-golangci-lint.sh are deleted. - pre-commit hook and .pre-commit-config.yaml run `make lint-changed LINT_CHANGED_SCOPE=staged` (nogo over the staged packages); Makefile adds lint, vet and lint-changed. pr-lint.sh no longer runs gofmt (//scripts/repochecks:fmt_test owns it; ga-96smfk.41). - internal/testutil/integration: five gosec findings in integration-tagged library files golangci-lint never built, now linted by the integration lanes, carry reasoned //nolint directives. Parity: with the exclusion rules removed, golangci-lint and nogo report the same 3,916 findings natively and 3,859 each for windows and darwin (file, line, linter, text); with .golangci.yml as committed both report none. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * ci(bazel): equivalence.py leaves nested Go modules' tests out of go test's set tools/nogo is its own Go module, so `go test ./...` in the root never runs its tests; Bazel's unit lane does. Its packages are neither expected nor extra. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
10 KiB
Beads — Contributor Agent Instructions
This file is for agents and humans developing beads (bd). If you are
using bd to track work in your own project, read the user docs instead:
docs site and
IDE and agent setup.
Nested AGENTS.md files hold area-specific rules; the routing table at the
end lists them. CLAUDE.md files are symlinks to their sibling AGENTS.md.
How work flows here
GitHub Issues is the public tracker. Use an issue when it adds context reviewers need: a user-visible bug, a behavior or design change worth discussing, or work that spans several PRs. The issue carries the reproduction, impact, and evidence for a bug, or the motivation, impact, risk, and verification plan for a change. Small, self-explanatory changes (typos, flaky tests, refactors, CI or docs tweaks) can go straight to a PR whose body explains the why.
- If the change warrants an issue, find or file one with the bug or feature form. It does not need maintainer approval first; file it before or alongside the PR.
- Work on a branch, open a PR against
main(its body saysCloses #<issue>when there is one), and let CI and review run. - Maintainers triage issues with
status/needs-triage,status/needs-info,status/needs-repro,status/needs-design, andstatus/accepted(confirmed); see CONTRIBUTING.md.
Maintainers also keep an internal bd ledger. It is optional for contributors and not a substitute for the GitHub issue.
Agent contribution policy
- File an issue when the change warrants one (see above). When you do, use
the bug or feature form fields, fill each from evidence, and answer
NOT_ENOUGH_INFOwhere the evidence runs out. - A human reviews and stands behind every issue and PR an agent drafts. Evidence that the change works end-to-end is required; "unit tests pass" alone is not evidence.
- Before implementing work, opening a PR, or merging/closing a PR, run the PR
preflight:
The preflight is the agent gate for PR handling; do not rely on auto-discovery of CONTRIBUTING.md.scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads - Use
ghfor GitHub issues and PRs, not browser tools. Write PR, issue, comment, and review bodies to a file, runscripts/gh-body-lint <body-file>, and pass the file withgh ... --body-file. Sign agent-written GitHub comments and reviews per engdocs/AGENT_SIGNING.md.
Contributor protection
External contributor PRs have priority. Read CONTRIBUTING.md — it contains promises we've made to contributors — and, before triaging, reviewing, landing, closing, or otherwise maintaining PRs, PR_MAINTAINER_GUIDELINES.md. The maintainer policy is to maximize community throughput: find useful contributor value, absorb or transform it locally when practical, preserve attribution, and use request-changes only as a last resort.
Before implementing any feature or fix, check for existing open PRs on the same topic. If one exists:
- Review it first — read the diff, understand the approach.
- Build on their work, don't rewrite it — check out their branch, fix/adapt as needed.
- Preserve their tests — keep them unless they're wrong.
- Attribute properly —
Co-authored-by:in commits, reference their PR. - Never close or supersede their PR silently. If a rewrite is unavoidable, explain why on the original PR and credit their design/tests.
Scope: where a change belongs
Read engdocs/PROJECT_CHARTER.md before adding feature surface area. Beads owns issue tracking primitives and should not encode orchestration-layer policy, become a storage engine, or casually expand the database schema when metadata would work. Prefer, in order: issue metadata over new fields, a flag on an existing command over a new command, an integration or plugin over core, and leave orchestration policy to the orchestration layer.
Storage boundary. Beads talks to storage through a driver interface
(dolthub/driver for Dolt). Do not add beads-side flocks, engine
introspection, storage-specific retry or crash-recovery logic, or public SDK
return types that leak driver internals. If the boundary is too narrow, widen
the interface or route the issue to the driver instead of patching around it
in beads. bd doctor support for embedded mode is enabled one subcommand at a
time, each human-vetted (GH#3794): do not lift the embedded-mode gate in
cmd/bd/doctor.go wholesale, and keep database-layer checks and fixes
server-gated until the driver interface covers them.
Layering. Schema → internal/storage/issueops → cmd/bd. Add new
primitives at the lowest layer first, one layer per PR, stacked when a fix
spans layers. See
CONTRIBUTING_PR_GUIDELINES.md.
Build, test, lint
make install # build and install bd to ~/.local/bin (canonical)
make test # unit tests with the right build tags
make ci-pr-lint # required zero-finding lint + vet contract (nogo under Bazel)
make check-docs # doc flag, freshness, and docsync checks
make bazel-sync # after adding/removing/renaming Go files or changing imports/go.mod
- Do NOT use
go build -o bd ./cmd/bd,go install ./cmd/bd, or rawgo run ./cmd/bd ...: they bypass the canonical build path, leave stale binaries, and rawgo runmisses thegms_pure_gotag. Usemake install,./bd, orgo run -tags gms_pure_go ./cmd/bd .... - All new features need tests. Choose them with engdocs/TESTING.md; it is the canonical source for commands, test design, and PR-readiness gates.
- Never pollute a production database with test issues. Use
t.TempDir()in Go tests and a disposable working directory for manualbdexperiments. make ci-pr-lintmust pass with zero issues; see engdocs/LINTING.md.- Optional shared Bazel cache (opt-in).
--config=fork-cachereads the project's anonymous, read-only cache, so results CI already computed are hits and nothing is uploaded. It is off by default; when setting up a dev environment, ask your human before addingbuild --config=fork-cacheto.bazelrc.local. - Without Bazel, let CI sync BUILD files: on same-repo PRs the bazel-autofix workflow pushes the fix to your branch (pull before pushing again); fork PRs get a comment with an apply recipe.
- If you changed behavior, update the user docs (
docs/, via thebeads-docsskill) or README in the same PR.
Commits and PRs
- Conventional Commits:
type(scope): summary(fix,feat,docs,test,refactor,chore,ci,perf). - For agent-prepared commits, include the
Agent-Signature:trailer described in engdocs/AGENT_SIGNING.md. Useunknown-modelorunknown-reasoningwhen reliable runtime metadata is unavailable. - Maintainers working from the internal ledger may also end the subject with
the bead ID, e.g.
(bd-abc), sobd doctorcan detect orphaned issues. - Work on a feature branch and open a PR against
main; direct pushes tomainare reserved for releases and narrow operational fixes. - When the user asks to bump the version, use
./scripts/bump-version.sh; the full release process is in RELEASING.md.
Ending a session
Do not push to main. Before handing off:
- Run the quality gates your change needs (
make ci-pr-lint, the tests engdocs/TESTING.md selects). If gates are broken onmain, report it as a P0 issue. - Record follow-up work as GitHub issues (or ledger beads, for maintainers).
- Commit, push, or open a PR only when the person you are working for asked you to. Report changed files, validation run, and anything left open.
CLI output
NEVER use emoji-style icons (🔴🟠🟡🔵⚪) in CLI output. ALWAYS use small
Unicode symbols with semantic colors: status ○ ◐ ● ✓ ❄; priority as a
P0–P4 label with color (no status glyph). The full visual design system
and CLI design principles are in
engdocs/UI_PHILOSOPHY.md.
Non-interactive shell commands
Agents cannot answer prompts. Use cp -f, mv -f, rm -f, rm -rf,
cp -rf (these may be aliased to -i); scp/ssh -o BatchMode=yes;
apt-get -y; HOMEBREW_NO_AUTO_UPDATE=1 brew. DO NOT use bd edit — it
opens $EDITOR; use bd update <id> --title/--description/--design/--acceptance/--append-notes
(pipe text with special characters via --description=-).
Routing table
| When you are touching… | Read first |
|---|---|
cmd/bd/ (commands, output, proxied-server routes) |
cmd/bd/AGENTS.md |
engdocs/ (contributor and internals docs) |
engdocs/AGENTS.md |
docs/ (the published user docs) |
.claude/skills/beads-docs/SKILL.md |
| Any Go test | engdocs/TESTING.md |
Lint failures or .golangci.yml |
engdocs/LINTING.md |
| A new storage operation or issueops role | engdocs/ADDING_AN_ISSUEOPS_ROLE.md |
| Schema migrations | internal/storage/schema/migrations/README.md |
| Dolt concurrency, server vs embedded mode | engdocs/design/dolt-concurrency.md |
| Errors returned to users | engdocs/ERROR_HANDLING.md |
The bd serve HTTP surface |
engdocs/SERVE_RUNBOOK.md |
A new example under examples/ |
examples/README.md — give the example its own README and link it there |
| Releases and version bumps | RELEASING.md |
| Scope questions | engdocs/PROJECT_CHARTER.md |
| Planned work and priorities | ROADMAP.md |