§5.7 Agent Context Files — v1.46 - #26
Merged
Merged
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>
This was referenced Aug 8, 2026
![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".
Comment on lines
+1
to
+4
| <!-- | ||
| 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 👍 / 👎.
* feat(standard): §17 progress reports become a labelled-row block — v1.47 Rewrite §17.1 and §17.2. Every tracked track now gets its own row, its own 20-cell bar, and its own percentage, in a fixed order: milestone rows M0..Mn ascending, then MVP, then TODO, then PLAN, then PRD. TODO and PLAN are new tracks — the old three-line format had no way to report against a plan document or a task list, so work driven by either was reported against a PRD that did not exist. Only applicable rows are emitted; padding the block with fabricated 0% rows is forbidden, since a reader cannot tell a placeholder from a genuine zero. §17.2 now defines two cell styles. Milestone/TODO/PLAN/PRD rows use U+2588/U+2591 with tight brackets; the MVP row keeps U+25B0/U+25B1 with one space inside each bracket. MVP is the headline figure and the rows around it are its inputs, so it stays findable in a stack of otherwise identical bars. The bracket padding is what holds the columns aligned — the MVP label field is one character narrower and each bracket one character wider, so every bar cell and percentage digit shares a column. Cell count is specified for the first time: the percentage scaled to twenty cells and rounded, with twenty filled only at exactly 100% and zero filled only at exactly 0%. Rounding 99% up to a complete bar reports work as finished that is not. §17.3 cadence is unchanged. §16's §17 checklist bullet is rewritten to match. Regenerated the .md companion. * feat(standard): §17.2 MVP row joins the single cell style — v1.48 The v1.47 ▰/▱ padded-bracket MVP carve-out is retired before it ever reaches main: every row now uses █/░ with tight brackets and a six-character label field. The alignment rules collapse from five bullets to three, and the misalignment-at-100% edge case disappears — the percentage's five-character field absorbs a three-digit value. Construct published the skill at v1.47, so this increments rather than revising v1.47 in place. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.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
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.
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