AGENTS.md — the hub
Every agent entry point lands here. Claude Code auto-loads CLAUDE.md, which is a one-line @AGENTS.md import; other agent tooling reads this file directly by convention. Either way this is the front door, and its only job is to say what to read and when. The rules themselves live in the files below, on purpose — so that adding a rule doesn't mean growing the thing every session pays for.
Applies equally to human contributors and AI agents.
Synced fleet-wide from Turbo-Client-Systems/Platform (Platform#15) — don't hand-edit it in a consuming repo, a sync PR will overwrite it. See rules/repo-baseline.md for how the sync works and what's local.
Always loaded
@rules/company.md @rules/planning.md @rules/issues.md @REPO.md
Those four lines are eager imports: Claude Code inlines each file into context before your first turn, so they are already in front of you and you do not need to open them. If you are a tool that doesn't resolve @ imports, read those four files now, before anything else.
They're hard-imported because they're needed in essentially every session:
| File | Why it's unconditional |
|---|---|
rules/company.md |
Who we are, how to work alongside the op, and the rules where missing one is expensive. |
rules/issues.md |
All work needs a labeled issue, and CI fails a PR that links none. |
rules/planning.md |
Every issue needs to know how much detail it deserves before it's written. |
REPO.md |
This specific repo's architecture, quirks, and local conventions. |
Read before you act
Everything else is conditional. Read the extender before doing the thing, not after.
| Before you… | Read |
|---|---|
| write or change any code | rules/code.md |
| branch, commit, push, or open/merge a PR | rules/git.md |
| pull from a work list other agents are also pulling from | rules/queues.md |
| touch the org Project board, milestones, or iteration planning | rules/board.md |
add to, fix, or work around a @turbo-client-systems/* package |
rules/packages.md |
| set up a new repo, audit one against the org baseline, or change the shared docs | rules/repo-baseline.md |
| wire up, change, or debug how a repo deploys | rules/deploy.md |
rules/code.md and rules/git.md also have PreToolUse hooks behind them, so your first Edit/Write or first git/gh command in a session gets a nudge here. Hooks are a backstop for forgetting, not the mechanism — a tool that doesn't run our hooks still has this table, and the table is authoritative.
rules/queues.md, rules/board.md, rules/packages.md, rules/repo-baseline.md and rules/deploy.md have no hook and don't need one: you can't stumble into a shared work queue, board grooming, package surgery, a repo audit, or a deployment change without knowing you're doing it.
Why it's split this way
One flat rules document is either too long to stay in context honestly or too short to say anything useful. Splitting on topic would just move that problem around. So the split is on consequence of being missed:
- Hard-imported — needed in nearly every session, or catastrophic to miss. Paid for unconditionally, kept deliberately short.
- Conditional — the elaboration, rationale, and procedure behind a specific activity. Loaded when that activity starts.
rules/company.md carries the bright lines as one-liners and points at the extender that explains each. That's the safety net: missing an extender still can't cost you the rule, only the reasoning behind it.
Adding or changing a rule
Shared files fan out to 14 repos on merge, so before editing one, see rules/repo-baseline.md. The short version:
- Is it true fleet-wide? If it's true of one repo, it belongs in that repo's
REPO.md. - Does it need to be eager? Default to a conditional extender. The hard-imported set is a budget, not a shelf.
- A new extender needs a row in the table above — and a hook, if a tool call can trigger it. A rules file nothing points at is a rules file nobody reads.