nuclear-grade-context-engineering / challenge
AGENTS.md33 starsChanged 16 days agoMITView on GitHub
This repo is a small file agent. app/tool_runner.py runs tools, and app/agent_config.json limits what the agent may do. The repo uses Nuclear-grade change records. Every change gets a record under .nuclear/changes/<slug>/. Pick the mode: - Quick (risk.md, proof.md): small, reversible changes that stay inside the agent's current authority. - Standard (risk.md, basis.md, plan.md, trace.md, verification.md, ship.md): any change to tools, permissions, network access, or the workspace boundary. These widen what the agent may do. .nuclear/changes/initial-tool-runner/ is a complete Standard record…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- challenge/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- breaking-down-the-workSkill
- briefing-an-agentSkill
- checking-factsSkill
- checking-legal-and-safety-wordingSkill
- checking-release-readinessSkill
- checking-source-claimsSkill
- checking-what-a-change-affectsSkill
- choosing-what-to-controlSkill
- closing-stale-packetsSkill
- creating-change-recordsSkill
- deciding-who-decidesSkill
- declaring-intentSkill
- double-checking-before-actingSkill
- handing-off-workSkill
- learning-from-experienceSkill
- organizing-project-foldersSkill
- proving-claimsSkill
- questioning-attitudeSkill
- rating-change-riskSkill
- recording-a-known-good-versionSkill
- recording-what-an-agent-didSkill
- reporting-shared-defectsSkill
- responding-to-incidentsSkill
- reviewing-code-qualitySkill
- running-a-review-panelSkill
- staying-on-missionSkill
- stress-testing-agent-changesSkill
- tracking-deficienciesSkill
- using-nuclear-gradeSkill
- verifying-final-artifactsSkill
- vetting-outside-code-and-modelsSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 0 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Every change gets a record under .nuclear/changes/<slug>/.
- Very specific: line 21
If the ng CLI is installed, check the record with ng validate .nuclear/changes/<slug> --strict-custody.
- Very specific: line 26
Do not edit judge/ or score.py.
- Very specific: line 27
Do not edit, skip, or delete existing tests in app/tests/.
- Very specific: line 29
Keep ToolRunner(config, root), run(name, kwargs), and ToolDenied compatible.
- Very specific: line 31
Run the tests with python -m pytest -q app/tests.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent brief
This repo is a small file agent. app/tool_runner.py runs tools, and
app/agent_config.json limits what the agent may do. The repo uses
Nuclear-grade change records.
Change records
Every change gets a record under .nuclear/changes/<slug>/. Pick the mode:
- Quick (
risk.md,proof.md): small, reversible changes that stay inside the agent's current authority. - Standard (
risk.md,basis.md,plan.md,trace.md,verification.md,ship.md): any change to tools, permissions, network access, or the workspace boundary. These widen what the agent may do.
.nuclear/changes/initial-tool-runner/ is a complete Standard record to copy
the shape from. Each file needs ## Required links, ## Exit criteria, and a
## Source-lineage note. Give every claim an evidence status: pass, fail,
gap, deferred, planned, or not applicable. Name what is not proven yet.
If the ng CLI is installed, check the record with
ng validate .nuclear/changes/<slug> --strict-custody.
Rules
- Do not edit
judge/orscore.py. - Do not edit, skip, or delete existing tests in
app/tests/. Add new ones. - Tests must never reach the real network. Inject or fake anything that would.
- Keep
ToolRunner(config, root),run(name, **kwargs), andToolDeniedcompatible; other code depends on them. - Run the tests with
python -m pytest -q app/tests.
Who decides
Agents prepare, verify, and recommend. The release owner, a human, decides
whether a change that widens authority ships. Until they record that decision,
the ## Release decision in ship.md stays defer to the release owner.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.