From 3e0853398150c405fc377397d786001f5b0ff1bc Mon Sep 17 00:00:00 2001 From: dan-claude-bot Date: Wed, 22 Jul 2026 14:25:42 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=E2=80=94=20the=20role=20ro?= =?UTF-8?q?uter,=20first=20file=20of=20the=20vendored=20set?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'You are a reviewer here' becomes a sufficient launch prompt: agent harnesses auto-load root AGENTS.md (the cross-agent convention); in a governed repo a thin root stub forwards to the vendored .ceremony/AGENTS.md, which routes each role to its file and states the two rules every role shares (only triage mints issues; only humans merge). Co-Authored-By: Claude Fable 5 --- AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 16 +++++++++++----- 2 files changed, 60 insertions(+), 5 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b8af0fa --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,49 @@ +# AGENTS.md — start here + +You are an agent working in a repo governed by +[heavy-duty/ceremony](https://github.com/heavy-duty/ceremony). This file is +the router: find your role below, read its file, then act. The role files +sit beside this one — in ceremony itself at the repo root, in a governed +repo under `.ceremony/` (a machine-managed mirror; never edit those files +in place — they are changed in heavy-duty/ceremony, through its own flow). + +## Your role + +You were told your role when you were pointed at this repo ("you are a +reviewer here"). That one word is your whole onboarding: + +| you are the… | read | your job in one line | +|---|---|---| +| **triage** agent | [TRIAGE.md](TRIAGE.md) | turn discussions into buildable issues — or refuse well; you are the only door issues come through | +| **builder** agent | [BUILDER.md](BUILDER.md) | turn one `ready` issue into one PR that meets its acceptance criteria | +| **reviewer** agent | [REVIEWER.md](REVIEWER.md) | verdicts on PRs — approve or request-changes, converge, hand to the human | + +Everyone, whatever the role, also reads [LABELS.md](LABELS.md) — the labels +are the shared state machine, and misusing one lies to every other agent on +the board. + +**Not told a role?** Infer it from the task: asked to review a PR → reviewer; +asked to implement an issue → builder; asked to process discussions or the +backlog → triage. Still ambiguous → ask before acting. Do not free-lance +across roles in one session: a builder reviewing its own PR, or a reviewer +pushing fixes, breaks the separation the pipeline depends on. + +## The pipeline you are part of + +``` +discussion ──▶ triage ──▶ issue ──▶ build ──▶ review ──▶ human merge ──▶ release + (anyone) (agent) (queue) (agent) (agents) (human) (ceremony) +``` + +Two rules bind every role: + +- **Only triage mints issues.** Found work? Open or extend a discussion. +- **Only humans merge.** Convergence ends at `state:needs-human`, never at + a merge button. + +## Repo specifics + +What is true only of *this* repo — the review panel roster, the `scope:*` +label set, what a drill means, code conventions — lives in the repo's own +`CONTRIBUTING.md`. Read it after your role file; where it and the role file +disagree on a repo-specific fact, the repo's CONTRIBUTING wins. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa23948..1f021c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,11 +88,11 @@ Two consumption modes, split by what has a runtime: - **Doctrine is consumed as a machine-verified mirror.** A document's only "runtime" is an agent reading the working tree of the repo it stands in — a doc that requires a cross-repo fetch before it governs is a doc that - sometimes goes unread. So the agent-facing set — **TRIAGE.md, BUILDER.md, - REVIEWER.md, LABELS.md** — is vendored into each governed repo at - **`.ceremony/`**, byte-identical to this repo at the pinned ref, by the - sync tool (issue #19). A CI guard diffs the mirror against the pin on - every PR: hand-editing a vendored file, or bumping the pin without + sometimes goes unread. So the agent-facing set — **AGENTS.md, TRIAGE.md, + BUILDER.md, REVIEWER.md, LABELS.md** — is vendored into each governed + repo at **`.ceremony/`**, byte-identical to this repo at the pinned ref, + by the sync tool (issue #19). A CI guard diffs the mirror against the pin + on every PR: hand-editing a vendored file, or bumping the pin without re-syncing, goes red. It is a copy that cannot drift — which is the only kind of copy this org allows. @@ -100,6 +100,12 @@ A governed repo (box, rig, cast, incubator, …) therefore carries: - `.ceremony/` — the vendored doctrine (machine-written; never edited by hand; agents read it from the checkout, no network, no other repo); +- a thin root **`AGENTS.md` stub** — a few lines: "governed by + heavy-duty/ceremony; read `.ceremony/AGENTS.md` first; repo specifics in + CONTRIBUTING". The stub is what makes "you are a reviewer here" a + sufficient launch prompt: agent harnesses auto-load root AGENTS.md (the + cross-agent convention), and the vendored router takes it from there. + Tool-specific files (`CLAUDE.md`, …) reduce to one pointer line at it; - the thin workflow callers (release, labels) pinned to a ceremony tag, plus the `docs-sync --check` guard step in CI; - a short header in its own CONTRIBUTING pointing agents at `.ceremony/`,