beads/AGENTS.md
Julian Knutsen 0773e6334e
docs(agents): contributor-only agent instructions and documented-issue intake (#7223)
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>
2026-10-05 08:43:53 +00:00

9.9 KiB
Raw Permalink 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, and every PR links a documented issue. The issue carries the context reviewers and future readers need: for a bug, the reproduction, impact, and evidence; for a change, the motivation, impact, risk, and verification plan.

  1. Find or file the issue 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 whose body says Closes #<issue>, 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

  • Every PR closes a documented issue. If none exists for your change, file one with the bug or feature form fields, filling each from evidence and answering NOT_ENOUGH_INFO where the evidence runs out, then link it from the PR.
  • 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 formatting + lint contract
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