docs: the agent team flow — CONTRIBUTING, LABELS, and the three role files #17

Merged

dan-claude-bot merged 3 commits from docs/agent-team-flow into main

2026-07-22 14:30:30 +00:00

dan-claude-bot commented

2026-07-22 14:13:01 +00:00

(Migrated from github.com)

What this adds

AGENTS.md — the role router, and the first file of the vendored set. "You are a reviewer here" becomes a sufficient launch prompt: harnesses auto-load root AGENTS.md (the cross-agent convention — CLAUDE.md and friends reduce to a pointer line); in a governed repo a thin root stub forwards to .ceremony/AGENTS.md, which maps role → file (triage/builder/reviewer), states the two rules every role shares (only triage mints issues; only humans merge), and sends repo specifics to the repo's own CONTRIBUTING.
CONTRIBUTING.md — the pipeline (discussion → triage → issue → build → review → human merge → release), the PR flow (ported from the proven box/rig/cast doctrine), this repo's review panel, the code conventions (covers the CONTRIBUTING half of #2), and the "How the other repos use this" section, split by what has a runtime: machinery by reference (GitHub materializes pinned workflows/actions at run time), doctrine as a machine-verified mirror — the agent-facing set (TRIAGE/BUILDER/REVIEWER/LABELS) vendors into each governed repo at .ceremony/, byte-identical to the pinned ref and guarded by docs-sync --check in CI (#19), so agents (incubator's reviewers included) read the rules from the checkout, never from another repo, and drift is unrepresentable. One pin governs machinery and mirror; a bump PR is the pin line + the re-sync, and the guard makes a half-done bump unmergeable.
LABELS.md — the family taxonomy, extended: the PR state machine and blockers as documented in box/rig/cast, plus the new issue-flow labels the pipeline runs on: needs-triage, ready, claimed, epic (+ existing blocked). Invariant: every open issue is needs-triage, epic, or exactly one of ready/claimed/blocked.
TRIAGE.md — the only door issues come through. Five outcomes per discussion (answer / ask / escalate / decline / accept), the issue contract (context with pinned permalinks, decided spec, tasks, acceptance criteria, test plan, deps, labels — "a builder who has read only this issue can succeed", with #1–#16 as the exemplars), epics, backlog hygiene.
BUILDER.md — pick (ready, unblocked, unclaimed, never an epic), claim protocol (abandoning is fine, ghosting is not), acceptance criteria as definition of done, scope discipline (found work goes to a discussion — builders never mint issues), the round rhythm, the handoff.
REVIEWER.md — the verdict doctrine (approve or request-changes, never bare comments; blockingness in the verdict, feedback in the body), review authority order (issue's acceptance criteria → load-bearing constraints → the code), verify-over-opine, no spec re-litigation in rounds, convergence → state:needs-human; only humans merge.

Design points

Single-writer rule for issues, agents included — not just "humans never write issues": nobody but triage does. The issue-quality bar holds because exactly one role is accountable for it; a stray issue gets needs-triage and is normalized or converted back.
Humans decide twice: in the discussion (triage escalates real decisions back there) and at the merge. Everything between is agent work by default.
Doctrine now, machinery next: the PR state machine already has its reconciler (#10). The issue-flow labels are doctrine-enforced until the issue-flow sweep lands (filed as a follow-up issue).

Related: #1 (the epic), #2 (conventions half covered here), #10 (core label set gains the issue-flow rows), #12 (CONSUMERS.md gains the adoption checklist).

🤖 Generated with Claude Code

The agent team flow, baked in as doctrine: this repo is our first try at a coding-agent team working together, so the process gets written down here — once — the same way the release ceremony did. ## What this adds - **AGENTS.md** — the role router, and the first file of the vendored set. "You are a reviewer here" becomes a sufficient launch prompt: harnesses auto-load root AGENTS.md (the cross-agent convention — CLAUDE.md and friends reduce to a pointer line); in a governed repo a thin root stub forwards to `.ceremony/AGENTS.md`, which maps role → file (triage/builder/reviewer), states the two rules every role shares (only triage mints issues; only humans merge), and sends repo specifics to the repo's own CONTRIBUTING. - **CONTRIBUTING.md** — the pipeline (`discussion → triage → issue → build → review → human merge → release`), the PR flow (ported from the proven box/rig/cast doctrine), this repo's review panel, the code conventions (covers the CONTRIBUTING half of #2), and the **"How the other repos use this"** section, split by what has a runtime: **machinery by reference** (GitHub materializes pinned workflows/actions at run time), **doctrine as a machine-verified mirror** — the agent-facing set (TRIAGE/BUILDER/REVIEWER/LABELS) vendors into each governed repo at `.ceremony/`, byte-identical to the pinned ref and guarded by `docs-sync --check` in CI (#19), so agents (incubator's reviewers included) read the rules from the checkout, never from another repo, and drift is unrepresentable. One pin governs machinery and mirror; a bump PR is the pin line + the re-sync, and the guard makes a half-done bump unmergeable. - **LABELS.md** — the family taxonomy, extended: the PR state machine and blockers as documented in box/rig/cast, plus the new **issue-flow labels** the pipeline runs on: `needs-triage`, `ready`, `claimed`, `epic` (+ existing `blocked`). Invariant: every open issue is `needs-triage`, `epic`, or exactly one of `ready`/`claimed`/`blocked`. - **TRIAGE.md** — the only door issues come through. Five outcomes per discussion (answer / ask / escalate / decline / accept), the **issue contract** (context with pinned permalinks, decided spec, tasks, acceptance criteria, test plan, deps, labels — "a builder who has read only this issue can succeed", with #1–#16 as the exemplars), epics, backlog hygiene. - **BUILDER.md** — pick (`ready`, unblocked, unclaimed, never an epic), claim protocol (abandoning is fine, ghosting is not), acceptance criteria as definition of done, scope discipline (found work goes to a discussion — builders never mint issues), the round rhythm, the handoff. - **REVIEWER.md** — the verdict doctrine (approve or request-changes, never bare comments; blockingness in the verdict, feedback in the body), review authority order (issue's acceptance criteria → load-bearing constraints → the code), verify-over-opine, no spec re-litigation in rounds, convergence → `state:needs-human`; only humans merge. ## Design points - **Single-writer rule for issues, agents included** — not just "humans never write issues": *nobody* but triage does. The issue-quality bar holds because exactly one role is accountable for it; a stray issue gets `needs-triage` and is normalized or converted back. - **Humans decide twice**: in the discussion (triage escalates real decisions back there) and at the merge. Everything between is agent work by default. - **Doctrine now, machinery next**: the PR state machine already has its reconciler (#10). The issue-flow labels are doctrine-enforced until the issue-flow sweep lands (filed as a follow-up issue). Related: #1 (the epic), #2 (conventions half covered here), #10 (core label set gains the issue-flow rows), #12 (CONSUMERS.md gains the adoption checklist). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/ceremony#17

No description provided.