grimoire
AGENTS.md1 starsChanged 12 days agoMITView on GitHub
Before you patch anything, read CONTRIBUTING.md — it is the contract for any patch. Read Run the check in a container first, for how to install athanor and when it is safe to run, then run the check with athanor run check by default. A hook in .claude/settings.json enforces that order: while athanor works, it refuses node scripts/check.mjs from you. When athanor is missing (a shim that dangles counts as missing), run the host check as it is. When an…
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,774 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 repository4 other files it gives its agents.
- contractSkill
- eagle-eyeSkill
- groundtrackSkill
- head-chefSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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 3
Before you patch anything, read CONTRIBUTING.md — it is the contract for any patch.
- Very specific: line 6
Read Run the check in a container first, for how to install athanor and when it is safe to run, then run the check with athanor run check …
- Distinctive: line 33
Before adding a rule or a field to either, ask: would this still make sense for any session, under any configuration?
- Very specific: line 55
Before the first edit to a file, assign the issue you take to yourself with gh issue edit <n> --add-assignee @me.
≈ “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
AGENTS.md
Before you patch anything, read CONTRIBUTING.md — it is the
contract for any patch.
Read Run the check in a container
first, for how to install athanor and when it is safe to run, then run the
check with athanor run check by default.
A hook in .claude/settings.json enforces that order: while athanor works, it
refuses node scripts/check.mjs from you. When athanor is missing (a shim that
dangles counts as missing), run the host check as it is. When an athanor run
exits 124, 125 or 137, add --host-fallback=<reason> to the host check, in your
own words with no path, token or pasted error text, and say in your report that
you used the fallback. A sha512 mismatch in the image build also exits 125; it
is not a Docker fault, so stop and tell the owner. An older athanor exits 125 with "must be an array of strings" or an unknown key commands.check.base: install the pinned commit, or use the host check. Read
The agent guard for the rest.
Three directories are called scripts/
scripts/ at the repository root holds this repository's own checks — the one
command, the site build, and the table that says which renderer owns which
artifact — and the two scripts that draw each skill README's sheets, with the kit they
share in scripts/lib/drafting.mjs. skills/groundtrack/scripts/ holds that skill's renderer and the one
module it inlines into the page. skills/contract/scripts/ holds the contract
skill's interview script, the one module it shares with the hiring page, and
the kinds table both read. The path always says which is which.
Head-chef and the rules it runs under
Head-chef manages sessions. How the work inside a session should be done is not its concern; that comes from whatever configuration a person runs. Head-chef and the Brigade pane may read that configuration, but they never assume one, use its terms or need it installed.
Before adding a rule or a field to either, ask: would this still make sense for any session, under any configuration? If not, it comes from configuration.
The Brigade pane and the head chef
A Brigade change that adds data the pane keeps says, in the same change,
whether the lead can read it through a tool; when it can, the same change
updates the head-chef contract and its SKILL.md, and its
docs/security/brigade.md row says where the tool's answer then flows.
The Decisions tab draws only the current lead's own decision log. Drawing anything from another session's log needs the owner's own words.
Threat model
This repository's threat model is docs/security/threat-model.md, which SECURITY.md also links. Hand it to any security review. A change to its scope, its accepted risks or this line is the owner's decision.
Agent skills
Issue tracker
GitHub issues on mephistopheles4/grimoire, driven by the gh CLI. See docs/agents/issue-tracker.md.
Before the first edit to a file, assign the issue you take to yourself with gh issue edit <n> --add-assignee @me. If you stop without finishing, unassign yourself with a comment on where you got to. An assignee is a signal, not a lock: the doc says what that means.
Triage labels
The five canonical roles, each label string equal to its name. See docs/agents/triage-labels.md.
Domain docs
Single-context — CONTEXT.md and docs/adr/ at the repo root. CONTEXT.md does not exist yet; /domain-modeling writes it when a term actually lands, not before. docs/adr/ holds the decisions made so far. Read the ones that touch the code you are about to change: 0003 before changing groundtrack's fold, 0004 before adding or changing a size limit in its renderer. See docs/agents/domain.md.
docs/decisions/ holds kept eagle-eye box files. A box is a working surface, so most stay in scratch and never land here.
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.