Skip to content

docs: add compact AGENT_DECISION_COMMENTS.md convention - #10

Open
dbrattli wants to merge 1 commit into
mainfrom
docs/compact-agent-convention
Open

docs: add compact AGENT_DECISION_COMMENTS.md convention#10
dbrattli wants to merge 1 commit into
mainfrom
docs/compact-agent-convention

Conversation

@dbrattli

Copy link
Copy Markdown
Owner

Motivation

Adopting repositories were expected to copy the full README.md into their
AGENT_DECISION_COMMENTS.md and have agents read it on every task. Much of the
specification (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 compact
    operational 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 copy AGENT_DECISION_COMMENTS.md from a
    published 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 and
    lint 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
  • Heading hierarchy reviewed across all three Markdown files

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant