docs: add compact AGENT_DECISION_COMMENTS.md convention - #10
Open
dbrattli wants to merge 1 commit into
Open
Conversation
Splits the convention into two documents: - AGENT_DECISION_COMMENTS.md: compact operational rules that agents read on every task (92 lines vs 451 for the full specification). - README.md remains the canonical specification and human reference. Rewires the quick start to copy the compact file from a published release and documents that releases include both documents. SemVer impact: minor (0.3.1 -> 0.4.0) - adds compatible adoption guidance; existing directive semantics are unchanged. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
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.
Motivation
Adopting repositories were expected to copy the full
README.mdinto theirAGENT_DECISION_COMMENTS.mdand have agents read it on every task. Much of thespecification (quick start, versioning policy, ecosystem, RFC/ADR relationship)
is human-oriented and not needed mid-task, so every task in every adopting repo
paid a standing context cost of ~15KB (~4k tokens).
This splits the convention into two documents, as already implied by the quick
start's file name:
AGENT_DECISION_COMMENTS.md(new, 92 lines / ~3.5KB): the compactoperational convention agents read on every task — the four labels, format
rules, one worked example, when-to-write lists, scope/accumulation semantics,
and the active-constraint rules.
README.md: remains the canonical specification and human reference.Affected sections
AGENT_DECISION_COMMENTS.md: new file.README.md: quick start now says to copyAGENT_DECISION_COMMENTS.mdfrom apublished release and to keep the local file compact; versioning notes that
releases include both documents; version bumped to 0.4.0.
AGENTS.md: documents the compact file's role, requires keeping its rules,examples, and version in sync with
README.md, and extends the review andlint commands to cover the new file.
No directive semantics or examples changed. Every rule and example in the
compact file was cross-checked against the specification.
SemVer impact
Minor (0.3.1 → 0.4.0): adds compatible adoption guidance per the spec's
versioning policy; existing directive semantics and adoption requirements are
unchanged.
Verification
npx --yes markdownlint-cli2@0.23.2 --config .markdownlint.jsonc "**/*.md"— 0 issues (same linter version as CI)git diff --check— clean