§5.7 Agent Context Files — v1.46 - #26
Conversation
AGENTS.md becomes the single harness-neutral source of truth for agent context; CLAUDE.md is reduced to an @AGENTS.md import plus Claude-only content. Five normative rules: write to AGENTS.md, no duplication, both files tracked, no secrets (with a review gate before un-ignoring a previously private file), and generated blocks targeting AGENTS.md only. This inverts the guidance previously carried only in the spacecraft-agentic-cli skill, which mandated CLAUDE.md as a strict superset — a rule that produced duplication by construction. §16 gains a §5.7 checklist bullet; the Skill Cross-References table gains a spacecraft-agentic-cli row. makeinfo --no-split: zero errors, zero warnings. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CLAUDE.md becomes AGENTS.md (the authoritative, harness-neutral file) and a new CLAUDE.md carries the @AGENTS.md import plus Claude-only notes. Both leave .gitignore and become tracked, per the §5.7 rule this repo just published — the standard governs itself (§8 self-applies). The Files table row is updated from "Gitignored / local agent guidance" to two tracked rows. Reviewed for sensitive content before un-ignoring: no credentials, hostnames, or personal filesystem paths. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
§5.7 makes both files tracked artifacts, so reuse lint began failing on them. They carry no inline SPDX tags by design — CLAUDE.md's first non-heading line must be the bare @AGENTS.md import. A REUSE.toml override is the right instrument, matching how the .texi and .md are already handled. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
§5.7 makes both files tracked artifacts, so reuse lint began failing on them. Inline headers rather than a REUSE.toml override: the .texi/.md overrides exist because those files contain *example* SPDX tags in §4.3 that must not be parsed as real ones, which is not true here. A leading HTML comment also costs nothing in context — Claude Code strips block-level comments before injecting a CLAUDE.md — and the @AGENTS.md import only needs to be on its own line, not the first one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a8b80db2f2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <!-- | ||
| SPDX-FileCopyrightText: 2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org> | ||
| SPDX-License-Identifier: CC-BY-SA-4.0 | ||
| --> |
There was a problem hiding this comment.
The SPDX comment is neither the @AGENTS.md import nor Claude-only content, so this repository's canonical CLAUDE.md violates the import-only layout introduced by §5.7. This is especially misleading because REUSE.toml already covers the file and explicitly says it carries no inline tags; projects copying this implementation would reproduce a layout that contradicts the new rule. Remove this preamble and rely on the existing REUSE annotation.
AGENTS.md reference: AGENTS.md:L116-L116
Useful? React with 👍 / 👎.
1 participant
Adds §5.7 — Agent Context Files to the Standard, at v1.46.
§5.2 has enumerated the required root files since the standard's early versions and never named the one file every coding agent actually reads. In that silence each project invented its own arrangement, and a survey of the umbrella found five incompatible conventions running simultaneously across ~39 repositories.
§5.7 makes
AGENTS.mdthe single authority — harness-neutral, required at every project root alongside the §5.2 files.CLAUDE.md, where a project ships one, becomes an@AGENTS.mdimport plus only what is meaningless to a non-Claude harness, and MUST NOT restate or mirror it.Five rules attach: write to
AGENTS.md; no duplication (a "keep these in sync" instruction is evidence the split is wrong); both files tracked; no secrets, with a review required before un-ignoring a previously ignored file; and generated blocks targetAGENTS.mdonly.Full rationale in
CHANGELOG.md.Base of a stack
This is PR 1 of 2 in Standard. The v1.47 §17 PR is based on this branch and should merge after it.
🤖 Generated with Claude Code