RemiMyrsetRemiMyrset/roots/AGENTS.md

roots

AGENTS.md0 starsChanged 41 days agoMITView on GitHub

This file holds the non-negotiable conventions, the commands that define "done", and pointers to where facts live. It is not the architecture handbook. Every fact has one canonical home; this file links to it and never restates it. The one exception is the Commands list below: it restates the done gate verbatim because it is the contract for "done", so keep it in sync when a gate command changes. When this file and a spec or decision record disagree, the…

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 repository21 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- first-runSkill
- fix-ciSkill
- new-adrSkill
- new-packageSkill
- new-specSkill
- prSkill
- releaseSkill
- sync-templateSkill
- update-depsSkill
- verify-docsSkill
- first-runSkill
- fix-ciSkill
- new-adrSkill
- new-packageSkill
- new-specSkill
- prSkill
- releaseSkill
- sync-templateSkill
- update-depsSkill
- verify-docsSkill

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

18 rules. About 0 are common, 4 are distinctive, and 14 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific
could be automatic: a setting could enforce it

Distinctive:
Every fact has one canonical home.
line 8
Very specific:
Test: pnpm test (turbo; single package: pnpm --filter <package> test)
line 51
Very specific:
Test hooks: pnpm test:hooks (agent guard allow/deny fixtures)
line 52
Very specific:
Test sync: pnpm test:sync (template-sync fixtures)
line 53
Very specific:
Test docs: pnpm test:docs (docs checker fixtures)
line 54
Very specific:
Test gates: pnpm test:gates (verify, the workflows, and this list name the same gates.
line 55
Very specific:
Test, watch: pnpm --filter <package> test:watch (vitest in watch mode.
line 75
Very specific:
ALWAYS use pnpm, never npm, yarn, or bun (guard-enforced in Claude Code, Codex, and Gemini CLI once the folder and hooks are trusted, see …
line 88
Very specific:
ALWAYS use TypeScript: no .js/.mjs, erasable syntax only, no class, explicit .ts/.mts on relative imports (tsc erasableSyntaxOnly and …
line 92
Very specific:
ALWAYS write docs as portable markdown (pnpm docs:portability.
line 96
Distinctive:
ALWAYS write Conventional Commits with a lowercase subject of at most 50 characters and body lines under 100 (commitlint), and NEVER bypass …
line 98
Very specific:
ALWAYS give every exported symbol a / */ block saying what it is for and what a caller cannot see from the signature (presence is …
line 101
Very specific:
NEVER push to a protected branch: PROTECTED_BRANCHES in the env block of .claude/settings.json, default main (guard-enforced.
line 104
Very specific:
NEVER hand-edit generated content: automd marker regions and the .agents/skills mirror (run pnpm docs:gen).
line 108
Very specific:
NEVER rewrite an accepted decision record.
line 110
Very specific:
NEVER run dependency build scripts or touch allowBuilds in pnpm-workspace.yaml (the guard blocks the flags.
line 113
Distinctive:
When behavior changes, source, tests, and its spec change in the same PR.
line 125
Distinctive:
If this session did not start at the root, tell the user.
line 162

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Agent rulebook

How this file works

This file holds the non-negotiable conventions, the commands that define "done", and pointers to where facts live. It is not the architecture handbook.

Every fact has one canonical home; this file links to it and never restates it. The one exception is the Commands list below: it restates the done gate verbatim because it is the contract for "done", so keep it in sync when a gate command changes. When this file and a spec or decision record disagree, the spec or decision wins; fix the loser in the same PR.

The budget is 200 lines, enforced by pnpm docs:check. When a section outgrows its space, move the content to its canonical home and leave a link.

Skills, the procedures, live in .claude/skills/ (Codex and Gemini read the generated .agents/skills/ mirror); path-scoped rules live in .claude/rules/ (Claude Code only; this file carries the same pointers).

Topic	Canonical source
What this project is	README.md
Why a decision was made	docs/internal/decisions/
What the system does now	docs/internal/specs/
One fact, one home, three-place sync	spec-discipline
Markdown authoring rules	markdown-portability
Prose rules for every artifact	writing rules
The words every page uses	vocabulary
Docs toolchain, recipes, growth paths	docs-toolchain
Why the conventions are what they are	conventions (template-owned, synced)
Agent guard threat model	guards
How each agent tool reads the rulebook, guards, skills, and writing rules	agent-surfaces
Template sync recipe and contract	sync-template
Setup and install	setup
Branch names and the PR flow	CONTRIBUTING.md

<!-- This table is the canonical-home map. Add one row per fact as homes appear
     (ports, env vars, glossary, deploy runbook, architecture overview, runbooks/,
     design/). A fact with no row gets one home and one row. -->

Commands

A task is complete only when every gate command below that your change can affect passes clean after your last edit. When unsure which apply, run pnpm verify, which runs them all.

Done gate: pnpm verify (the frozen-lockfile install, then the gate commands below, in CI order; stops at the first failure; pnpm verify <gate> resumes there, pnpm verify --only <gate> runs one)
Build: pnpm build (turbo; packages that define build)
Test: pnpm test (turbo; single package: pnpm --filter <package> test)
Test hooks: pnpm test:hooks (agent guard allow/deny fixtures)
Test sync: pnpm test:sync (template-sync fixtures)
Test docs: pnpm test:docs (docs checker fixtures)
Test gates: pnpm test:gates (verify, the workflows, and this list name the same gates; the rules the gates rely on hold in the workflows, ESLint, lint-staged, turbo, package tsconfigs, the install hook, verify's drift gate, the secret scan, and .gitignore; changelogen sends no commit author's email out unless changelog.excludeAuthors lists names, and the release script refuses a dirty tree; the devcontainer's mounts share no volume with another repository's container; each scripts/test-*.mts suite drops the inherited GIT_ variables before it starts a process)
Typecheck: pnpm typecheck
Lint: pnpm lint. Run pnpm lint:fix after making code changes.
Secrets: pnpm lint:secrets (secretlint over every tracked file, a force-added gitignored one included, and every untracked file .gitignore does not exclude; also in lint-staged)
Boundaries: pnpm boundaries (turbo: imports stay inside their package unless by package name, and every imported package is declared)
Docs, regenerate: pnpm docs:gen (the .agents/skills mirror and any automd region)
Docs, validate: pnpm docs:check && pnpm docs:portability
Docs, build (CI-blocking): pnpm docs:internal:build && pnpm docs:public:build

Other commands, never part of done and never run to prove it:

Install: pnpm install (node 24 and pnpm first, as setup says)
Test, watch: pnpm --filter <package> test:watch (vitest in watch mode; it never exits)
Sample app: pnpm --filter @repo/example-app start (runs the sample CLI against the sample package)
Docs, preview: pnpm docs:internal:dev / pnpm docs:public:dev (dev servers; they never exit)
Docs, list: pnpm docs:list (decisions and specs, read from the files; decisions or specs prints one)
Sync: pnpm sync:template (only when asked; stages the template's mechanics; the sync-template skill)
Release: pnpm release (human-run; the push guard denies it to agents)

Non-negotiable rules

<!-- ALWAYS/NEVER imperatives, one or two lines each, mechanism in parentheses, a
     pointer for the rest. Add a rule only after an agent got it wrong; every rule
     dilutes every other rule. Prune rules that stop being true. -->

ALWAYS use pnpm, never npm, yarn, or bun (guard-enforced in Claude Code, Codex, and Gemini CLI once the folder and hooks are trusted, see agent-surfaces; npx passes as a one-off runner, prefer pnpm dlx).
ALWAYS use TypeScript: no .js/.mjs, erasable syntax only, no class, explicit .ts/.mts on relative imports (tsc erasableSyntaxOnly and ESLint; the escape hatches for a dependency that demands a subclass or a JavaScript config are in conventions).
ALWAYS write docs as portable markdown (pnpm docs:portability; rules in markdown-portability).
ALWAYS write Conventional Commits with a lowercase subject of at most 50 characters and body lines under 100 (commitlint), and NEVER bypass a git hook (guard-enforced): fix the failing check.
ALWAYS give every exported symbol a /** */ block saying what it is for and what a caller cannot see from the signature (presence is lint-enforced, a tool config's default export aside; content is on you).
NEVER push to a protected branch: PROTECTED_BRANCHES in the env block of .claude/settings.json, default main (guard-enforced; the GitHub ruleset is the server-side boundary). Feature branches push and open PRs freely; merging is a human action; details in guards.
NEVER hand-edit generated content: automd marker regions and the .agents/skills mirror (run pnpm docs:gen).
NEVER rewrite an accepted decision record; supersede it and link both ways (docs:check verifies the status vocabulary and the supersede link; a rewritten body is caught in review only).
NEVER run dependency build scripts or touch allowBuilds in pnpm-workspace.yaml (the guard blocks the flags; each existing entry is a human verdict).

Judgment calls

For minor implementation choices such as naming, file placement, the shape of a refactor, or which of two equivalent approaches, pick a reasonable option and note it in the PR description. Ask first only for a change in scope, a new dependency, deleting user data or git history, or anything a guard denies.

Spec discipline

When behavior changes, source, tests, and its spec change in the same PR. The spec kinds, the concrete triggers, and generated versus hand-written are all in spec-discipline; read it before touching behavior.

Monorepo map

packages/example-package: @repo/example-package, sample library; replace it with (or rename it to) your first real package.
apps/example-app: @repo/example-app, sample CLI consuming the package over workspace:*; replace it with your first real app.

<!-- One line per package and its purpose, nothing else. A stale map is worse
     than none; agents follow it literally. -->

Placement alone registers a package: the workspace globs cover apps/* and packages/*. Scaffold with the new-package skill.

Unit tests live in <package>/test/, never colocated in src/ (a colocated test is a lint error).

A package with its own conventions gets a scoped AGENTS.md (same 200-line budget) plus a sibling CLAUDE.md holding only @AGENTS.md. The pairing is for Claude Code, which discovers nested CLAUDE.md and never nested AGENTS.md (the import resolves relative to the file holding it). When Codex and Gemini load a nested AGENTS.md is under agent-surfaces.

Gotchas

<!-- What an agent gets wrong on first contact: naming traps, ordering
     constraints, things tests cannot catch. When you hit a failure a future agent
     would repeat, add a one-line entry in the same PR; delete entries that stop
     being true. -->

Claude Code and Gemini CLI load project settings only from the directory they start in: started below the repository root, the guards and writing rules are off (agent-surfaces). If this session did not start at the root, tell the user.
pnpm docs:gen mutates files; never run it inside a pre-commit hook.
automd swallows generator failures: it writes the error into the marker region as a comment, exits 0, and re-runs byte-identical, so the drift gate stays green. pnpm docs:check catches it; never commit a generated region containing a warning comment.
The internal handbook is for the team: if you host it, gate it behind access control (recipe in docs-toolchain).
pnpm install refuses any dependency version published in the last 48 hours (minimumReleaseAge in pnpm-workspace.yaml); the registry is not broken, wait or pin the previous version.

Download now (ZIP)

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

What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free