beads/engdocs/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

2.6 KiB

engdocs/ — contributor notes

engdocs/ holds contributor and internals documentation. It is read on GitHub, not published: local links must be exact relative file paths, and TestEngdocsAndRootMarkdownLinks in test/docsync fails on any that do not resolve. User-facing documentation lives in docs/ (the Mintlify site) and follows the beads-docs skill.

What lives where

Path Contents
PROJECT_CHARTER.md Product boundary: what belongs in core, an integration, or the orchestration layer.
TESTING.md, LINTING.md Canonical test and lint policy.
ERROR_HANDLING.md, UI_PHILOSOPHY.md Conventions for errors and CLI output.
ADDING_AN_ISSUEOPS_ROLE.md How to add a storage operation end to end.
EXTENDING.md, INTEGRATION_CHARTER.md Extension and integration boundaries.
AGENT_SIGNING.md Signatures for agent-prepared commits, comments, and reviews.
design/ Design documents for subsystems (Dolt concurrency, bd serve, ownership hand-off, …).
adr/ Architecture decision records, <NNNN>-<slug>.md, each with a ## Status section. Accepted ADRs are superseded by a new ADR, not rewritten.
decisions/ Dated decision records for the docs tooling.
staged-for-removal/ Docs that no longer meet the active-doc bar (see staged-for-removal/MANIFEST.md). Do not link to or update them.

Code orientation

  • cmd/bd/ — the CLI (see cmd/bd/AGENTS.md).
  • internal/workapi/ — the work-query contract shared by every bd frontend: filter construction, defaults, validation, response shaping.
  • internal/httpapi/ — the bd serve HTTP surface (SERVE_RUNBOOK.md).
  • internal/storage/ — shared storage interface and value types, plus HookFiringStore and its hook_*.go decorators, which fire on_create/on_update/on_close hooks after successful mutations.
  • internal/storage/issueops/ — transaction-scoped SQL operations shared by the server-mode (internal/storage/dolt/) and embedded (internal/storage/embeddeddolt/) stores.
  • internal/storage/schema/ — schema and migrations (migrations/README.md).
  • internal/doltserver/ — lifecycle of a local dolt sql-server process.
  • beads.go, backend/, issueops/, journalops/, memoryops/, format/, beadserrors/ — the public Go API for extending bd and for out-of-tree storage backends.

Each package's doc comment (go doc ./internal/<pkg>) is the authoritative description; prefer it over prose here when they disagree, and fix this file.