Is your feature request related to a problem?
AGENTS.md is the operating guide for coding agents working in this repo, and it documents structure, commands, architecture, conventions and test layout — but says nothing about how a change is supposed to land. An agent reading it has no way to know that this repo expects issue → branch → PR.
The result is predictable and has already happened in practice:
- work started directly on an already-merged branch instead of a fresh branch off
main, because merged branches linger locally and git branch --show-current looks unremarkable;
- changes made with no issue behind them, so the rejected alternatives are never written down anywhere;
- PRs opened without a
Closes #N keyword, leaving issues to be closed by hand.
CONTRIBUTING.md covers some of this for humans, but it is thin on the points agents actually get wrong: it says "create a feature branch" without specifying the base, does not mention issues at all, does not mention Conventional Commits, and does not mention the label taxonomy. It also is not the file agents are pointed at.
Describe the solution
Add a "Contribution Workflow" section to AGENTS.md covering the six steps the repo already expects in practice:
- Open an issue first, using the
.github/ISSUE_TEMPLATE/ structure, recording the problem with file:line evidence and the alternatives that were rejected.
- Label it —
Type: * required, Status: Break Change for CLI/config/wire changes, Priority: P0–P3 for bugs.
- Branch off
main, never off another feature branch, with feat/… fix/… docs/… spec/… naming, verified against git log origin/main --oneline -1.
- Commit with Conventional Commits — the release pipeline derives version bumps from the type, so it is not cosmetic.
- Open the PR with a
Closes #N keyword and fill in the PR template honestly.
- Verify before marking ready, with pasted evidence rather than claims.
Include the gh invocations for each step, including gh pr view --json closingIssuesReferences to confirm the issue link actually landed.
Describe alternatives
- Put it in
CONTRIBUTING.md only. Rejected: that file is aimed at human contributors and is not what agents are pointed at. The failure being fixed here is an agent-facing one.
- Leave it implicit and correct it in review. Rejected: it recurs every session, since agents start with no memory of the previous correction.
- Duplicate the full text into both files. Rejected: two copies drift.
AGENTS.md gets the operational detail; CONTRIBUTING.md stays the human-facing summary.
Which implementation(s) would this affect?
Documentation only — no implementation code is touched.
Additional context
Split out of #35, which is where the gap surfaced.
Is your feature request related to a problem?
AGENTS.mdis the operating guide for coding agents working in this repo, and it documents structure, commands, architecture, conventions and test layout — but says nothing about how a change is supposed to land. An agent reading it has no way to know that this repo expects issue → branch → PR.The result is predictable and has already happened in practice:
main, because merged branches linger locally andgit branch --show-currentlooks unremarkable;Closes #Nkeyword, leaving issues to be closed by hand.CONTRIBUTING.mdcovers some of this for humans, but it is thin on the points agents actually get wrong: it says "create a feature branch" without specifying the base, does not mention issues at all, does not mention Conventional Commits, and does not mention the label taxonomy. It also is not the file agents are pointed at.Describe the solution
Add a "Contribution Workflow" section to
AGENTS.mdcovering the six steps the repo already expects in practice:.github/ISSUE_TEMPLATE/structure, recording the problem withfile:lineevidence and the alternatives that were rejected.Type: *required,Status: Break Changefor CLI/config/wire changes,Priority: P0–P3for bugs.main, never off another feature branch, withfeat/…fix/…docs/…spec/…naming, verified againstgit log origin/main --oneline -1.Closes #Nkeyword and fill in the PR template honestly.Include the
ghinvocations for each step, includinggh pr view --json closingIssuesReferencesto confirm the issue link actually landed.Describe alternatives
CONTRIBUTING.mdonly. Rejected: that file is aimed at human contributors and is not what agents are pointed at. The failure being fixed here is an agent-facing one.AGENTS.mdgets the operational detail;CONTRIBUTING.mdstays the human-facing summary.Which implementation(s) would this affect?
Documentation only — no implementation code is touched.
Additional context
Split out of #35, which is where the gap surfaced.