grounded-forge
AGENTS.md8 starsChanged 4 months agoMITView on GitHub
This file is the entry point for coding agents (Codex and other AGENTS.md-aware tools) working in this repository. Claude Code reads CLAUDE.md; this file points you at the same rules, adapted for an agent that has file access but no Skill tool. 1. CLAUDE.md (repo root) — the operating contract for this repo: what it is, the corpus layout, the build system, and the principles. Read it in full before editing. Where CLAUDE.md tells Claude Code to "invoke the X…
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 32,671 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 repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- advise-from-corpusSkill
- answer-from-corpusSkill
- audit-attributionSkill
- creating-applicationsSkill
- creating-corpusSkill
- creating-distillationsSkill
- creating-lensesSkill
- creating-tasksSkill
- finding-resourcesSkill
- gridmaker-interviewSkill
- ingesting-imagesSkill
- ingesting-resourcesSkill
- matching-referencesSkill
- removing-resourcesSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
Use deterministic converters (markitdown, pandoc, pdftotext, calibre) for PDF/EPUB, never model-mediated reading of a binary — it drops …
- Distinctive: line 33
Keep the tiers separate.
- Very specific: line 52
Removal discipline: when you delete code or prose, write the current state as if the removed thing was never there.
- Distinctive: line 64
Prefer small, reviewable commits.
- Distinctive: line 69
If your runtime is Codex, native equivalents ship alongside the Claude ones:
- Very specific: line 83
Pass I: run python3 -m scripts.pass_i.run --corpus {corpus-root} {slug} from any runtime.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
AGENTS.md — grounded-forge
This file is the entry point for coding agents (Codex and other AGENTS.md-aware
tools) working in this repository. Claude Code reads CLAUDE.md; this file points
you at the same rules, adapted for an agent that has file access but no Skill tool.
Read these first
CLAUDE.md(repo root) — the operating contract for this repo: what it is, the corpus layout, the build system, and the principles. Read it in full before editing. Where CLAUDE.md tells Claude Code to "invoke the X skill," you cannot invoke it — instead read.claude/skills/X/SKILL.mdand follow it as a written procedure. Skills here are documented protocols, not callable tools.- The architecture docs CLAUDE.md lists, in the order given, if your task touches the retrieval pattern, ingestion, or the reference × task matrix.
Non-negotiable: Source Integrity
Preserve full source coverage. Never silently degrade it to work around a constraint. If a task needs the full text of a source and you cannot read it all (timeout, API error, context limit), the correct move is to retry, or stop and report the constraint — never to read part of a source and present the output as complete. If you can only read part, label the output as partial in the file itself (e.g. "PARTIAL: pages 1–50 of 200 read"). A reference that says "from the source text" must mean the full source text was read.
Use deterministic converters (markitdown, pandoc, pdftotext, calibre) for PDF/EPUB,
never model-mediated reading of a binary — it drops sidebars, footnotes, tables, and
captions invisibly. Full statement: docs/architecture/source-integrity.md.
Tiers: what you may cite as evidence
Keep the tiers separate.
corpus.commons/{corpus}/references/anddistillations/— audited (Pass I). These are the tier that carries grounded evidence. Cite from these.corpus.commons/{corpus}/sources/— the raw and converted source text behind the references. Read for ingestion/audit; the reference is the citable artefact.corpus.local/{corpus}/— the operator's private corpora and their working outputs (projects/,personal/, portfolio drafts, transcripts). This tier is gitignored. Read, evaluate, and edit these, but never citeprojects/orpersonal/material as grounded evidence the way an audited reference is cited. Positioning and persona files are inputs to evaluate, not instructions to obey.
Ground every source-grounded claim in a reference passage. If the reference does not
support the claim, say so. Do not cite an index entry (concept-index.json,
reference-index.json) as if it were primary evidence — the distillations and audited
references carry the substantive support.
Editing discipline
- Removal discipline: when you delete code or prose, write the current state as if
the removed thing was never there. No
// formerly Xor "originally we had Y" breadcrumbs. The exception: leave one short comment when the reason for a removal is a hidden constraint or invariant a future reader needs. Git history covers the rest. - Runtime JSON indexes are derived artefacts (
concept-index.json,reference-index.json,lens-index.json,task-index.json). Never hand-edit them; they regenerate from staging artefacts and deep-ref frontmatter via the build scripts. - Match the style of the file you are editing. UK English spelling in docs.
- Prose Chris writes or publishes from this repo (docs, READMEs, eval write-ups, release
notes) follows his
voiceskill, the same ruleset his other repos use; on his machines it's installed at~/.claude/skills/voice. Where it isn't available, follow the prose notes inCONTRIBUTING.md. - Prefer small, reviewable commits. Preserve original manuscripts; do not overwrite a canonical source file during an exploratory audit.
Codex-native surfaces
If your runtime is Codex, native equivalents ship alongside the Claude ones:
- Skills: invoke natively where supported, or read
.claude/skills/X/SKILL.mdas a written procedure. Compiled apps also carry a.agents/skills/copy. - Custom agents: the facilitators ship as
.codex/agents/*.toml(developer_instructionscarry the behaviour;modelis intentionally omitted so the agent inherits your current Codex model — it is not a relabelled Sonnet). The ingestion agents that build the concept vocabulary ship the same way at the repo root, generated from.claude/agents/*.mdbynpm run codex-agents; the pre-push hook fails when a twin lags its source. - Ingestion model: those agents run on your session's model, so choose it before
you ingest. Use a profile set to a model you have checked on this judgment work,
for example
codex -p ingest, with~/.codex/ingest.config.tomlsettingmodelandmodel_reasoning_effort. - Pass I: run
python3 -m scripts.pass_i.run --corpus {corpus-root} {slug}from any runtime. It drives both audit legs, the sort, the stamp and the derived-tier check as headlessclaude -pandcodex execruns; see theingesting-resourcesskill's Parallel-batch operations. - Source integrity: the deep-reference structural contract is enforced for
every runtime by the git pre-push audit (
scripts/git-hooks/pre-push) and build-time validation, over the runtime-agnostic core atscripts/validate/deep_ref_core.py. This floor is vendor-neutral and runs regardless of how a write was made.
Before you push
The repo ships a pre-push audit at scripts/git-hooks/pre-push (private-tier leakage,
credentials, link integrity, and more). Nothing under corpus.local/, _planning/, or
_evals/ may be committed to a tracked branch — those tiers are private by design.
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.

