arbiter
AGENTS.md0 starsChanged 54 days agoApache-2.0View on GitHub
Canonical cross-tool entrypoint for the arbiter repository. Tool-specific shims are .claude/CLAUDE.md and .agents/CODEX.md. - Stack: TypeScript with strict mode. - Build: npm run build - Test: npm run test - Gate: the pre-push hook runs node scripts/check-all.mjs preflight once; CI runs the full L2 gate on the exact pushed SHA. The full invariant, CI-tier, supply-chain, canon, gate, and debt reference is docs/internal/SYSTEM/INVARIANT-CATALOG.md. Use arbiter explain <ID> for an invariant, and docs/INDEX.md for the documentation map. First list what you need…
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 repository23 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- architect-reviewSkill
- brainstormingSkill
- clean-codeSkill
- close-gold-gapSkill
- codebase-auditSkill
- configureSkill
- context-rot-managementSkill
- epic-decomposeSkill
- gold-auditSkill
- impactSkill
- levelupSkill
- product-acceptanceSkill
- refutationSkill
- senior-surveySkill
- ssot-navigationSkill
- tabletopSkill
- tddSkill
- understand-codeSkill
- verificationSkill
- visual-verificationSkill
- wave-drainSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Commit format: type(scope): imperative lowercase summary, at most 72 characters.
- Distinctive: line 35
Verify the changed behavior end to end before pushing.
- Distinctive: line 38
Test first for behavior changes and preserve strict typing, boundary validation, and error handling.
- Very specific: line 42
Use arbiter explain <ID> for an invariant, and docs/INDEX.md for the documentation map.
≈ “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
arbiter — AGENTS.md
Canonical cross-tool entrypoint for the arbiter repository. Tool-specific shims are
.claude/CLAUDE.md and .agents/CODEX.md.
Project
- Stack: TypeScript with strict mode.
- Build:
npm run build - Test:
npm run test - Gate: the pre-push hook runs
node scripts/check-all.mjs preflightonce; CI runs the full L2 gate on the exact pushed SHA.
Delivery
- Entrypoint:
/ship #NNN. - Done means the PR is merged green to
main, with the gate and delivery evidence recorded. - Branch:
task/#NNN-short-description;mainis protected. - Commit format:
type(scope): imperative lowercase summary, at most 72 characters. Types includefeat,fix,refactor,test,docs,ci,chore, andperf.
Hard rules
- Preserve the check set in
scripts/check-all.mjsand its existing failure behavior. - Verify the changed behavior end to end before pushing; after a failure, read the actual failure and fix its root cause before editing again.
- Parallel writers use isolated worktrees; keep secrets and personal data out of the repository.
- Tracked follow-up comments use
TODO(#NNN); orphan TODOs fail the gate. - Test first for behavior changes and preserve strict typing, boundary validation, and error handling.
The full invariant, CI-tier, supply-chain, canon, gate, and debt reference is
docs/internal/SYSTEM/INVARIANT-CATALOG.md.
Use arbiter explain <ID> for an invariant, and docs/INDEX.md for the documentation map.
Working efficiently
First list what you need next; then request every tool call that does not depend on another's result in the same response. Edit files surgically; do not rewrite a whole file for a small change.
<!-- arbiter:preserve -->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.