Repository navigation
docs(adr): defer AGENTS.md to M2, with the harness behaviour measured now - #32
Merged
Merged
Conversation
… now The open spec says nothing about coexisting with tool-specific files, so the behaviour was measured rather than read: AGENTS.md alone is read, AGENTS.md beside a CLAUDE.md is ignored entirely, and a CLAUDE.md containing @AGENTS.md loads both. That kills the pointer option — it would be read by no Claude Code session while looking installed. Two further measurements are recorded so M2 does not re-derive them: the generated CLAUDE.md is ~86% harness-neutral with its Claude-bound lines clustering in three blocks, and CLAUDE.md is referenced 77 times across 10 skills plus 10 templates. Nothing in the plugin changes. The trigger is M2, and ROADMAP points at the ADR so the groundwork is found rather than redone. See CHANGELOG [Unreleased] > Changed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Nothing in the plugin changes. This records a gap, its measurements, and why acting now would be premature.
The gap
AGENTS.mdis an open spec — OpenAI-led, donated to the Linux Foundation, 60k+ repositories — for a single predictable file of project context for AI agents. This plugin had no mention of it anywhere, whiledocs/ROADMAP.mdM2 states the harness-neutral direction outright.The spec does not settle it, so the harness was measured
The spec says nothing about coexisting with tool-specific files. Three throwaway directories, a fresh
claude -pwith read tools disabled so the answer comes from what was loaded rather than what it could open (Claude Code 2.1.280):AGENTS.mdaloneAGENTS.mdAGENTS.mdandCLAUDE.mdCLAUDE.mdonlyCLAUDE.mdcontaining@AGENTS.mdThat kills the cheapest-looking option, which was my own first instinct: a pointer
AGENTS.mdbeside aCLAUDE.mdis read by no Claude Code session, while looking installed to anyone reading the repository. Same failure class as the dead pre-commit hook two days ago.Two measurements recorded so M2 does not redo them
CLAUDE.mdis ~86% harness-neutral; its Claude-bound lines are 9 citing a/groundrules:*command and 18 citing the interface or.claude/, clustered in three identifiable blocks rather than diffused.CLAUDE.mdis referenced 77 times across 10 skills plus 10 templates — which is what makes a rename disproportionate today, and the@AGENTS.mdimport the recommendation to carry forward.One finding that does not need M2
The methodology's entry points are written as commands — decided →
/groundrules:add-adr— which is meaningless to another tool, and to a human reading the repository without the plugin installed. Splitting the file would force the portable half to state the act and the place, with the command as a shorthand beside it. That is a better generated file whatever happens toAGENTS.md, and it would probably never have been noticed without this constraint. Worth doing on its own.Honest limits
One claim from the investigation was not verifiable from this machine and is therefore not load-bearing: that
AGENTS.mdsupport depends on server-side feature flags and is absent on Bedrock and third-party providers. It would argue against makingAGENTS.mdthe sole entry point — which the recommended import pattern does not do, so the recommendation holds either way.And the measured precedence is a product behaviour, not a contract. The ADR says to re-run the three-directory test before acting on it.