beads/AGENTS.md
Julian Knutsen a4509deb2d
ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341)
* 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>
2026-10-07 05:17:22 +00:00

10 KiB
Raw Blame History

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.

  1. 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.
  2. Work on a branch, open a PR against main (its body says Closes #<issue> when there is one), and let CI and review run.
  3. Maintainers triage issues with status/needs-triage, status/needs-info, status/needs-repro, status/needs-design, and status/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_INFO where 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:
    scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads
    scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads
    
    The preflight is the agent gate for PR handling; do not rely on auto-discovery of CONTRIBUTING.md.
  • Use gh for GitHub issues and PRs, not browser tools. Write PR, issue, comment, and review bodies to a file, run scripts/gh-body-lint <body-file>, and pass the file with gh ... --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:

  1. Review it first — read the diff, understand the approach.
  2. Build on their work, don't rewrite it — check out their branch, fix/adapt as needed.
  3. Preserve their tests — keep them unless they're wrong.
  4. Attribute properly — Co-authored-by: in commits, reference their PR.
  5. 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 raw go run ./cmd/bd ...: they bypass the canonical build path, leave stale binaries, and raw go run misses the gms_pure_go tag. Use make install, ./bd, or go 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 manual bd experiments.
  • make ci-pr-lint must pass with zero issues; see engdocs/LINTING.md.
  • Optional shared Bazel cache (opt-in). --config=fork-cache reads 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 adding build --config=fork-cache to .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 the beads-docs skill) 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. Use unknown-model or unknown-reasoning when reliable runtime metadata is unavailable.
  • Maintainers working from the internal ledger may also end the subject with the bead ID, e.g. (bd-abc), so bd doctor can detect orphaned issues.
  • Work on a feature branch and open a PR against main; direct pushes to main are 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:

  1. Run the quality gates your change needs (make ci-pr-lint, the tests engdocs/TESTING.md selects). If gates are broken on main, report it as a P0 issue.
  2. Record follow-up work as GitHub issues (or ledger beads, for maintainers).
  3. 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