The broadest file in the directory. Alongside structure and commands it covers how to spell one domain term, how to classify a security finding, what a newsfragment is for, how the git remotes must be named, and what an agent may put in a commit trailer.
Quoted passages are verbatim. Open one to see it in the source.
01 / House vocabulary
One word, with its exceptions enumerated
The term is written in title case in all prose. The carve-out covers literal code tokens, which keep their original spelling even inside fenced code blocks, and includes a further exception for anti-pattern quotes that show the wrong form in order to teach the rule.
Source excerpt starting at line 8.
8Write **Dag** (title case) in all prose. Keep the all-caps or lowercase9spelling only when reproducing a literal code token — never rewrite these,10even inside fenced code blocks:
02 / From this file
How to classify a security finding
Three categories are defined for anything the agent might flag: actual vulnerabilities that violate the documented security model, known limitations that are already tracked, and deployment hardening that belongs in operator guidance rather than as a code issue. The authoritative document is linked, including its chapter on what is not considered a vulnerability.
03 / Contribution etiquette
Open the pull request, not the issue
When the fix is already known, the file directs the agent past filing an issue. Two reasons are given: the PR already carries the title, description, diff and discussion, and an open issue attracts duplicate submissions. The exception is a workaround whose real fix is deferred, where the issue outlives the PR.
Source excerpt starting at line 368.
368- Open issues attract drive-by submissions, often from other agents, that369 haven't seen the in-flight work. That produces duplicate fixes, low-quality
04 / From this file
Deferred work linked from the code
A workaround, version cap or partial fix requires a tracking issue opened before the PR body is finalised, referenced by number in the PR, and linked at the workaround site in the code. The link is specified as a full URL rather than a bare number, because bare references do not resolve outside GitHub's web interface.
05 / Hard prohibitions
No agent co-author trailer
The commit section ends with a line prohibiting the agent from adding itself as a co-author, with the stated distinction that agents are assistants rather than authors. A separate PR template field discloses the agent by name and version instead.
Source excerpt starting at line 210.
210- NEVER add Co-Authored-By with yourself as co-author of the commit. Agents cannot be authors, humans can be, Agents are assistants.
06 / From this file
Remote names checked rather than assumed
Two remote names are fixed by convention. The agent is told to run git remote -v before any remote command, and where the names do not match, to surface the mismatch and propose the exact rename commands rather than silently working with what is there.
07 / From this file
A coverage target with an upper bound
Tests are to cover exactly what the PR changes: every changed behavior gets a test, every test must fail without the change, and tests for pre-existing logic or third-party functions are excluded.
Source excerpt starting at line 152.
152- Target exactly 100% coverage of what the PR changes — no more, no less. Every changed or added behaviour must have a test; every test must fail without the PR's change. Do not add tests for pre-existing logic that was already present before the PR, and do not test standard-library or third-party functions. The exception is deliberate behaviour or integration tests, which may cross those boundaries by design.
Put it to work
Borrow this for your repo
01If your project has a term people spell three ways, fix the spelling and enumerate the exceptions.
02Tell agents how to classify a security finding, including which categories not to report.
03State whether an agent may add itself as a commit co-author.
04Before any remote command, have the agent verify remote names rather than assume them.
05"Every test must fail without the change" is a sharper instruction than a coverage percentage.
Airflow's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
