Move the agent instructions to AGENTS.md - #38
Open
timlichtenberg wants to merge 11 commits into
Open
timlichtenberg wants to merge 11 commits into
timlichtenberg wants to merge 11 commits into
Conversation
AGENTS.md is the instruction file that coding agents read by default. CLAUDE.md now only imports it, because an agent that reads CLAUDE.md ignores AGENTS.md when both exist. The root file states the escape physics contract (units, the already-diluted XUV flux from PROTEUS, the radius scaling, the tidal domain guard) and the review points; tests/AGENTS.md carries the test rules and loads when an agent works in tests/. Both start with the blocks shared across the PROTEUS ecosystem, whose canonical text lives in PROTEUS tools/agents/. .github/copilot-instructions.md is cut to the commands and the review checklist, and the review detail moves to .github/agent-rules/code-review.md. Corrections against the code: collision.py is a physics source next to escape.py; update_coverage_threshold.py updates the full gate unless given --target fast; both coverage gates are already at 90 %; constants.py and planets_parameters.py keep hand-aligned tables, so ruff format runs on changed files only.
tools/agents/check_agents_md.py, the same file as in PROTEUS, replaces the line-count hook on copilot-instructions.md: it checks the shared-block hashes, the byte caps of the AGENTS.md files, the CLAUDE.md import and the length of copilot-instructions.md, and runs in the PR test workflow.
…/CLAUDE.md The shared blocks now name the PROTEUS config values in lowercase with their config keys, state the unit conventions of hf_row, and require one tier marker per test. An agent that reads CLAUDE.md, with one at the repository root, loads a nested AGENTS.md only through a CLAUDE.md in the same directory, so tests/CLAUDE.md imports it; check_agents_md.py, updated from PROTEUS, requires that import next to every AGENTS.md.
PROTEUS calls EL_escape with scaling=3 and the tests pass scaling explicitly, so a change of the default reaches only callers that omit it; the rules now name the docstring and the validation page as the places to update. mass_loss returns the lost fraction of the atmosphere, clipped to [0, 1], and gets its own review section. The MORS conversion divides the luminosity by 4 pi a**2 in cm before ergcm2stoWm2. PROTEUS caps the escape of one step through limit_escape_step, and a dropped K_tide lowers the rate rather than raising it. The EL_escape signature, the coverage flags of the PR test command, the ruff exception for the two hand-aligned tables and the nightly data-cache test are stated; the config-mutability section, which has no counterpart in this repository, is removed.
The review checklist now says that PROTEUS and the tests pass scaling explicitly, so a change of the default updates the EL_escape docstring and the validation page, and that the MORS luminosity is divided by 4 pi a**2 and multiplied by ergcm2stoWm2.
An inline comment block stays at 2 lines or fewer and never exceeds 4, because a long block drifts from the code it describes; a longer explanation goes in the docstring, the commit message or the pull-request description. The rule sits in tools/agents/core.md, so every repository gets it through sync_core.py.
test_earth.py and test_mors_coupling.py call EL_escape with the default scaling, so a change of the default updates the docstring, docs/Validation/escape.md and docs/Explanations/model.md and needs a check of those two tests. PROTEUS caps the mass escaped in one step through limit_escape_step, the collision guards also reject a non-finite collision speed, zensical serve serves the docs, and test_nightly_data_cache.py skips when mors or fwl_io is missing. The review notes keep only what AGENTS.md does not say: the escape efficiency range, the scaling references, escape in the coupled model, the collision guards and the star-import rule. The Copilot checklist gains the collision guards and the text rules and is named as the copy of the Review section. tests/AGENTS.md states the docstring and naming rules again. check_agents_md.py and the shared blocks are updated from PROTEUS.
No test fails when the default radius scaling changes: every pinned test passes scaling explicitly and test_earth.py uses Rp equal to Rxuv, where both branches agree. The instructions now say so and ask for a test that pins the default and an update of every docs page that names it. tests/AGENTS.md states that validate_test_structure.sh accepts exactly one of the tier markers and skip, and that only the MORS coupling test mocks mors. The Copilot checklist says which parts of AGENTS.md and tests/AGENTS.md it repeats. The checker's sync error names the sync_core.py repository argument.
test_earth.py uses the default with Rp equal to Rxuv, where both branches agree, and the escape pins pass scaling explicitly; the instructions and the test_escape.py comment now say so. The epsilon bound stays in code-review.md and the step cap in AGENTS.md.
A dropped K_tide lowers the escape rate, so it never reaches the step cap; the review note now names both effects. The Copilot checklist also names test_mors_coupling.py among the tests that use the default scaling.
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The validator does not detect a missing required tests/AGENTS.md file.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
Open (1)
What changed in this PR
Migrates repository agent guidance to AGENTS.md files and adds automated consistency validation.
Changes:
- Adds root and test-specific agent instructions.
- Replaces the file-size checker with Python validation integrated into pre-commit and CI.
- Updates guidance references and removes superseded rule files.
| File | Summary |
|---|---|
tools/check_file_sizes.sh |
Removes the obsolete size checker. |
tools/agents/check_agents_md.py |
Adds instruction validation; must also verify required files exist. |
tests/test_escape.py |
Clarifies scaling-test coverage. |
tests/CLAUDE.md |
Imports test instructions. |
tests/AGENTS.md |
Adds test-specific guidance. |
AGENTS.md |
Adds repository-wide guidance. |
.pre-commit-config.yaml |
Integrates the new validator. |
.github/workflows/tests.yaml |
Runs validation in CI. |
.github/copilot-instructions.md |
Provides a concise entry point. |
.github/agent-rules/code-review.md |
Adds detailed review guidance. |
.github/.claude/rules/zephyrus-tests.md |
Removes superseded test rules. |
.github/.claude/rules/zephyrus-code-review.md |
Removes superseded review rules. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
8 tasks
The checker passed a repository whose tests/AGENTS.md was missing, because it only checks the AGENTS.md files it finds. It now reports the missing file whenever tests/ exists, and a test covers it.
This branch has not been deployed
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.
Description
The instructions for coding agents move from
.github/copilot-instructions.mdand.github/.claude/rules/toAGENTS.mdat the repository root andtests/AGENTS.md, the file format that most coding agents read.CLAUDE.mdandtests/CLAUDE.mdimport theAGENTS.mdnext to them, so every tool loads the same rules.The rules shared by all PROTEUS modules (units at module boundaries, physics tests that fail for the most plausible wrong formula, commit and pull-request text, inline comment length) come from one canonical block in PROTEUS,
tools/agents/core.md, copied here with its sha256.tools/agents/check_agents_md.pyfails when a shared block no longer matches its hash, when a file exceeds its size limit (16,000 B at the root, 12,000 B intests/), or when aCLAUDE.mddoes not import itsAGENTS.md. It runs in pre-commit and in the test workflow and replacestools/check_file_sizes.sh.I checked the ZEPHYRUS section against the code and corrected what was out of date, among others the statements on the default radius scaling:
scaling=2is the default, PROTEUS passesscaling=3, and no test pins the default. The comment intests/test_escape.pynow says the same.copilot-instructions.mdkeeps a short checklist and points toAGENTS.md; the longer review notes are in.github/agent-rules/code-review.md.PROTEUS gets the same structure in FormingWorlds/PROTEUS#798, and the other modules follow.
Validation of changes
python tools/agents/check_agents_md.py .passes; deleting the shared block or changing its text makes it fail.pytest tests: 50 passed on macOS with Python 3.12, against the branch source.bash tools/validate_test_structure.shpasses.scalingchanged from 2 to 3, all 50 tests still pass, as the new text states.Checklist
Relevant people
@EmmaPostolec @egpbos