docs: give coding agents the rules this repository already runs on - #556
Conversation
The conventions an agent needs were nowhere it could read them. The architecture lanes and testing expectations are in CONTRIBUTING; the rest lived in whatever local configuration a maintainer happened to have, so a fresh clone told an agent nothing about backend neutrality, the canonical surface, or which branch work belongs on. AGENTS.md states them, and links CONTRIBUTING and the architecture docs rather than restating them -- a second copy is a second thing to keep true, which is the failure this repository has already had once with the prose describing an engine it no longer has. Three build properties are written down here because they are documented nowhere and each produced a wrong conclusion rather than an error: - Staging by explicit path. The tree collects zero-byte files named by shell quoting accidents; `git add .` commits them, and `git clean -f` removes new sources along with them. - A standalone examples run resolves from ~/.m2, exactly as CONTRIBUTING already warns for qa. Skip the install after a render change and the examples regenerate through the artifacts you last installed, so the output looks unchanged because the change was never in it. - Example output is not byte-comparable: the writers embed timestamps, so a fresh render differs from its committed preview for every example, including ones the change cannot reach. CLAUDE.md is a pointer, since Claude Code reads that name and other tools read AGENTS.md. AgentsGuideGuardTest holds the file to naming things that exist -- every document, package and module it points at -- because it is read by automation that will follow a dead path confidently. Each case was checked against the breakage it exists to catch. AGENTS.md was in .gitignore, listed among scratch files, from when it was one. That line is removed; the file is the deliverable now.
… local A CLAUDE.md in the tree commits this project to carrying one file per agent vendor, each a copy of the same rules and each free to drift from them -- the duplication AGENTS.md exists to avoid, reintroduced by the thing meant to bridge to it. AGENTS.md is tool-independent and ships. A file named for one tool is configuration belonging to whoever runs that tool, so it stays on their machine; .gitignore keeps it there rather than leaving it to be committed by accident. Its guard case goes with it.
The file opened by calling the architecture docs the source of truth and then restated them -- branch policy, the Java baseline, the pipeline, the package roots, module responsibilities, the API tiers. 440 lines, most of them a second copy that goes stale the day the original moves, with nothing to notice: a guard that checks paths exist passes either way, because the packages still exist, they have simply stopped being the ones the guide named. That is the failure this repository already had with the prose describing an engine it no longer has. It links those documents now and answers only what none of them does: release work is not a side effect of a feature branch, stage by path because the tree collects shell-quoting junk, and two commands that return success while reporting the opposite of the truth -- a standalone examples run resolving from ~/.m2, and example output that is never byte-comparable because the writers embed timestamps. 118 lines. The guard promised more than it checked. everyModuleItNamesIsBuilt read the module inventory and asserted only that <module>/pom.xml existed, so a module dropped from the reactor POM left it green while its comment claimed otherwise. That inventory is gone with the rest of the restatement, and the guard now holds exactly three things it can see: the links open, the reactor gate it prescribes is a real command, and it still declines to name package coordinates package-map.md owns -- the last one failing if the duplication comes back. Added to the Architecture and Documentation Guards job, which was not running it.
DemchaAV
commented
Aug 14, 2026
All three fixed, and Major 2 was the one worth stopping for — the file opened by calling the architecture docs the source of truth and then restated them. I wrote the contradiction into the first paragraph and did not see it. Major 2 — 440 lines to 118. Branch policy, Java baseline, pipeline, package roots, module responsibilities, API tiers, POM rules: all of it lives in What is left is what none of them says: release work is not a side effect of a feature branch; stage by path because the tree collects shell-quoting junk; and the two commands that return success while reporting the opposite of the truth — a standalone examples run resolving from Major 1 — the false promise is gone with its subject. You were right that I did not reuse The guard now holds three things it can actually see:
The third is the one that guards your Major 2 against coming back: existence checks cannot see a restatement go stale, because the packages still exist — they have simply stopped being the ones the guide names. Each verified against its own breakage: 2 of 3 red in every case. Minor — added to the Full reactor |
itDoesNotAnswerWhatItDelegates claimed the whole delegation contract while checking one recognisable half of it: package coordinates. The rest -- whether a paragraph has quietly become a copy of the branch policy or the module roles -- is not something a regex can tell from prose, and a name that implies otherwise is the same over-promise the reactor check made before it was removed. Named for what it does. The class javadoc says the same.
DemchaAV
commented
Aug 14, 2026
Both fixed in The name. The PR body is rewritten for what is actually here. Worth doing beyond tidiness: with squash-merge this body becomes the commit message on Full reactor |
Uh oh!
There was an error while loading. Please reload this page.
Why
An agent cloning this repository is told nothing about it.
CONTRIBUTING.mdand the architecture docs carry the lanes, the pipeline and the testing expectations, but the operating rules — what not to touch, which results lie — lived in whatever local configuration a maintainer happened to have. Nothing in the tree.Three build properties are worse than undocumented, because each returns success while reporting the opposite of the truth:
~/.m2. The reactor buildsexamplesfrom source;cd examples && ../mvnw compile exec:java …does not — exactly asCONTRIBUTING.md:37already warns forqa. Skip the install after a render change and the examples regenerate through the artifacts you last installed, so the output looks unchanged because the change was never in it.cmpconcludes the opposite of the truth.$env,b)`,'Current).git add .commits them;git clean -fremoves new sources along with them.What's here
AGENTS.md, 118 lines. It linksCONTRIBUTING.mdand the architecture docs and answers only what none of them does: release work is not a side effect of a feature branch, staging is by path, the two misleading results above, and "never report a test passed unless it was executed".An earlier revision of this branch was 440 lines and restated branch policy, the Java baseline, the pipeline, package ownership, module responsibilities, the API tiers and the POM rules — while opening by calling those documents the source of truth. That is a second copy that goes stale the day the original moves, and this repository has already lost a full release line to exactly that: prose describing an engine it no longer has, green under every guard. Determinism was checked too and delegated, since
overview.mdandpackage-map.mdeach cover it.AgentsGuideGuardTest, three cases, holding only what it can see:everyPathItSendsAReaderToExiststheBuildCommandsItPrescribesCanBeRunmvnwis not at the rootitDoesNotRestateThePackageCoordinatesItLinksTocom.demcha.compose.*coordinate reappearsThe third guards the regression above: existence checks cannot see a restatement go stale, because the packages still exist — they have simply stopped being the ones the guide names.
.gitignore—/AGENTS.mdwas ignored, listed among scratch files (rectangle.pdf,Test.pdf), from when it was one. Removed, or none of this could ship./CLAUDE.mdadded: a file named for one tool is configuration belonging to whoever runs that tool, and committing one would oblige this repository to carry a copy of these rules per vendor — the duplicationAGENTS.mdexists to avoid..github/workflows/ci.yml— the guard joins theArchitecture and Documentation Guardslist, which was not running it.Verification
./mvnw -B -ntp clean verifyover the full reactor —BUILD SUCCESS. The 9-guard fail-fast list runs 50 tests green.Both commands the file prescribes were run before it prescribed them:
./mvnw -B -ntp verify -pl :graph-compose-coreand the bare./mvnw -B -ntp clean verify. Every document it links was checked to open.Each guard case was checked against its own breakage — a moved link, a dropped gate command, a package coordinate added back: 2 of 3 red in every case.
Scope
These are the maintainer's existing practices, not new policy, and nothing here changes how the build works.
Two things were deliberately left out. A commit-attribution rule from an earlier draft governs the maintainer's own commits on their own machine and is not project policy —
CONTRIBUTING.mdhas no DCO, sign-off or co-authorship requirement — so it does not belong in a file addressed to contributors. AndPackageMapGuardTest's reactor-module logic was not reused: the module inventory it would have checked is precisely the restatement this branch removed, and a stronger check on a paragraph that should not exist is still a paragraph that should not exist.