# AGENTS.md

This file provides guidance to coding agents working in this repository.

## What this repository is

<One paragraph. Project purpose, current baseline, what the artefacts in
this repo represent.>

## Picking up this repo

<!-- Bootstrap GENERATES this list from the recorded artefact root, the
optional layers this repo actually has, and the coordination mode: drop
every line whose file was not written, renumber what remains, and
resolve each path against the artefact root (e.g.
`.docflow/CONVENTIONS.md`). This section is the repo's only read order —
no separate hand-off file is written. -->

Read these, in order, before any tool calls:

1. `AGENTS.md` (this file) — the hard rules. Read in full.
2. `CONVENTIONS.md` — authoring rules, ADR status semantics, the git
   contract.
<!-- If plan folder skipped (Q4a): drop lines 3, 4 and 8. -->
3. `plan/README.md` — how the work queue is used.
4. The newest `plan/done/` entries and
   `git log --first-parent --oneline -n 20` — the shipped-work record.
5. `INDEX.md` — the ADR catalogue: an ADR's filename and its dependency
   chain. Sorted by number, not by work order.
<!-- Coordination lines: keep 6 in shared-checkout and separate-worktree
modes; keep 7 in shared-checkout mode only; drop both for a single
writer. -->
6. `_agent/ROLES.md` — who writes what.
7. `_agent/LOCKS.md` — which files are currently claimed; claim yours
   here before editing.
8. The queue item you are about to work, `plan/todo/NNNN-<slug>.md`, and
   the ADR(s) it names — both in full.

## Repository structure

- `adr/0000-template.md` — canonical ADR template.
<!-- If two ADR shapes (Q2): also include `adr/0000-template-technology.md` for technology ADRs. -->
- `adr/NNNN-<kebab-slug>.md` — one ADR per decision, contiguous
  numbering, no gaps.
- `INDEX.md` — table regenerated from every ADR's metadata block.
- `CONVENTIONS.md` — authoring rules (read before editing anything).
<!-- If plan folder skipped (Q4a): drop the two plan/ lines and the
"Plan folder" section below. -->
- `plan/todo/NNNN-<slug>.md` — pending work, lower numbers run first.
- `plan/done/<YYYY-MM-DD>-<slug>.md` — shipped work, chronological.
<!-- `_agent/` line — list the members the coordination mode (Q5) writes,
and drop the line entirely when no `_agent/` exists (a single writer
without both a verify gate and a plan queue):
  single writer:       `prompts/autonomous.md`
  shared checkout:     `ROLES.md`, `LOCKS.md`, `prompts/autonomous.md`
  separate worktrees:  `ROLES.md`, `prompts/autonomous.md`
`prompts/autonomous.md` appears only where a verify gate was recorded
(Q8) AND the plan queue it walks exists (Q4a); drop it from the list
otherwise. -->
- `_agent/` — the agent operating contract: who writes what, the one
  real mutex, and how an unattended run behaves. Here: `ROLES.md`,
  `LOCKS.md`, `prompts/autonomous.md`. It holds nothing git already
  records.
<!-- If GLOSSARY.md (Q7): also include `GLOSSARY.md` — shared terms. -->
<!-- If domains/ (Q7): also include `domains/<slug>/README.md`. -->

## Hard rules when editing ADRs

These come from `CONVENTIONS.md` and override default behaviour:

- **One decision per ADR.** Splits become new ADRs that supersede;
  never expand scope inside an existing one.
- **Status lifecycle:** `<from Q3>`.
- **Capability ADR section order:** metadata → Context → Capability
  statement → User stories / scenarios → Acceptance criteria → Out of
  scope → Open questions → References → Revision History → Approvals.
<!-- If two ADR shapes (Q2): keep the NEXT TWO bullets. A single-shape repo
drops both — it writes no `shape:` field at all. -->
- **Technology ADR section order:** metadata → Context → Decision →
  Rationale → Consequences → Acceptance criteria → Out of scope → Open
  questions → References → Revision History → Approvals. Rationale must
  name alternatives considered with specific rejection reasons.
- **Shape is declared, never numbered.** Each ADR's `shape:` field says
  which order applies (`capability` — the default when the field is
  absent — or `technology`). Every ADR takes the next contiguous number
  whatever its shape.
<!-- End of the two-shape bullets. -->
- **Acceptance criteria are testable and numbered.**
- **ADRs are internal artefacts — never user-visible.** ADR numbers,
  ADR titles, and the existence of the ADR catalogue must NEVER appear
  in any string the product emits to users: UI copy, API response
  bodies, error messages, customer-visible log lines, public
  documentation, release notes, marketing copy, or support
  communications. The catalogue is a builder's tool, not a user-facing
  surface. References ARE allowed in: code comments
  (`// see adr/0042-foo.md`), commit messages, PR descriptions,
  internal docs, `AGENTS.md`, `CONVENTIONS.md`, `INDEX.md`, and the
  `plan/` queue. Rule of thumb: if a non-builder could ever see the
  string, the ADR reference comes out.
<!-- Insert any Q10 domain-specific hard rules here as additional bullets. -->

## Implementation work

- Start from the ADRs. Identify which ADRs a code change implements or
  affects before changing behaviour.
- If implementation reveals a capability gap or changed decision, update
  the relevant ADR rather than silently diverging.
- Add or update tests for implemented behaviour. Map tests back to ADR
  acceptance criteria where practical.
- **Do not leak ADR identifiers into user-visible surfaces.** When
  writing error messages, UI copy, API responses, log lines that ship
  to customers, public docs, or release notes, refer to the behaviour
  by its product-level name — never by ADR number, ADR title, or
  phrases like "per the ADR catalogue". The ADR link belongs in the
  commit message and (optionally) an inline code comment, not in the
  string the user reads.

## Audit trail and revision discipline

- Substantive ADR changes append a row to the Revision History table.
  Editorial changes (typos, formatting, link fixes) are excluded but
  flagged `editorial` in the commit message.
- Approvals table populates when an ADR is Accepted and updates on each
  later substantive revision.
- Regenerate `INDEX.md` from ADR metadata after any ADR status change
  or new ADR.

## Multi-agent workflow

<!-- Keep the ONE block matching the coordination mode (Q5); delete the
others. `_agent/` holds contracts only — no mode writes a log, a
dashboard, or a snapshot of what git already records. -->

<!-- Single writer. Keep this block. -->
A single writer owns this repo — one human/agent integrates at a time,
so there is nothing to serialise. What happened is in git history and
`plan/done/`; what is in flight is the branch you are on and any open
pull request.
<!-- If a verify gate was recorded (Q8) AND the plan queue exists (Q4a),
add: The one coordination file is `_agent/prompts/autonomous.md`, the
contract for an unattended run. Without both — the prompt walks
`plan/todo/` and ships through the gate — there is no `_agent/`
directory at all. -->

<!-- Several writers, one shared checkout. Replace the block above with: -->
<!--
Named actors answer for areas (see `_agent/ROLES.md`); work is assigned
by claim.
Coordination rules:
- One working tree means no branch per item: claim a queue item **on the
  item itself** — the actor and the date, in its own status section where
  it has one — before you start it.
- Before editing a file, claim it in `_agent/LOCKS.md` by appending
  `<agent-id> | <path> | <ISO-8601 timestamp>`. Remove the line on
  commit. LOCKS is the one real mutex — it prevents simultaneous
  writes to the same file in this shared checkout.
- The shipped record is git history and `plan/done/`.
-->

<!-- Several writers, separate worktrees / PR branches. Replace the
block above with: -->
<!--
Named actors answer for areas (see `_agent/ROLES.md`); work is assigned
by claim. Each writer works in its own git worktree or PR branch.
Coordination rules:
- **The claim on a queue item is the branch `claim/<item-key>` pushed
  for it** — the queue file name without its extension, e.g.
  `claim/0007-rate-limit` — plus its draft pull request where
  integration is PR-based. Commit, then push: the push is what excludes
  the second writer, because one item maps to one ref. There is no lock
  ledger: worktrees cannot collide on the filesystem, and an advisory
  ledger nobody can rely on is noise. What has to be guarded against is
  duplicated work and contradictory merges — see the guardrails below.
- **State what you own** in the pull-request description, or the
  branch's first commit message under direct-to-main: the identifier
  block reserved for you and the artefacts you are the single writer of.
- What is in flight is **derived** — `git worktree list`, the remote
  `claim/*` branches, and the open draft pull requests — not read from a
  file; what shipped is git history and `plan/done/`.
-->

<!-- Concurrency guardrails hard rule — bootstrap INCLUDES this bullet
ONLY for several-writer (shared-checkout / worktree) OR PR-based repos
(omit for a single writer on direct-to-main). See CONVENTIONS.md
§Concurrency Guardrails.

- **Before integrating, check for number collisions (G2/G3).** Sync onto
  the current `main` and run the audit skill; if your ADR or `plan/todo`
  number now clashes with what landed on `main`, renumber locally before
  integrating. The single-threaded merge gate rejects a duplicate as the
  backstop. Numbers are immutable once merged. (G1 — landing the ADR
  before implementation — is recommended guidance, in CONVENTIONS.md.)
- **Claim a queued item before implementing it (G4).** In separate
  worktrees / PR branches, commit and then push `claim/<item-key>` — the
  queue file name without its extension — and open a draft PR from it
  where integration is PR-based; the push is the exclusion, so a rejected
  push means someone else holds the item. In a shared checkout, claim the
  item on the item itself. A single writer claims nothing. Never start a
  queued item you have not claimed.
-->

## Plan folder

- A pending item gets a `plan/todo/NNNN-<slug>.md` file BEFORE work
  starts, naming the owning ADR(s), scope, and exit criteria.
- The completion event is: `<from Q4 — e.g. merge to main, deploy +
  smoke passes, release tag>`. Under direct-to-main integration, the
  completion commit moves the file to
  `plan/done/<YYYY-MM-DD>-<slug>.md` with a footer naming the HEAD SHA
  and any artefact id, then pushes. Under pull-request integration,
  the move, any plan-item Status removal, ADR advance, and INDEX
  regeneration are the final branch commit before the pull request is
  marked ready; the footer names the pull request, and the merge is
  the completion event.
- The owning ADR(s) advance `Accepted → Implemented` on the same
  commit. Regenerate `INDEX.md`.

## Git contract

- Commit messages follow **Conventional Commits**.
- Mandatory `Rationale:` footer on any commit touching an ADR.
- <Signed commits: yes/no per Q6.>
- <ADR-revision tags `adr-NNNN-rN`: yes/no per Q6.>
- <Co-Authored-By trailer: yes/no per Q6 — default no.>
- Cross-references between ADRs use relative paths (`adr/NNNN-*.md`).

<!-- Integration model per Q4b — keep one block. -->

<!-- Direct-to-main (if no verify gate was recorded (Q8), drop the
gate sentence):
- **Integration:** direct-to-main, **fast-forward only**. No merge
  commits on `main`. The verify gate (`<command from Q8>`) runs
  locally and must pass before push. Completion event:
  fast-forwarded to `main` + remote push succeeded.
-->

<!-- PR-based:
- **Integration:** every change ships via a pull request. CI must be
  green before merge — the verify gate (`<command from Q8>`) runs in
  CI on the PR, not (only) locally. Merge strategy:
  <squash | merge | rebase>. Completion event: PR merged to `main`
  with CI green. Completion changes are committed on the pull-request
  branch before it is marked ready; no follow-up commit is made on the
  integration branch after merge.
-->