/write-area-brief — many small briefs, not one large file

One large AGENTS.md is loaded in full on every turn whether or not it is relevant. A routing table plus scoped leaves loads detail only where work happens.

0. Check there is a spine, and ask before the first write

If there is no root AGENTS.md, stop and hand off to /write-context-docs. Every leaf opens by pointing up at the root, and step 3 wires a routing table into it — both need a root that exists. Do not improvise one here: /write-context-docs owns the templates, the never-clobber rules and the post-write verification, and duplicating that logic is exactly what /setup-repo step 6 forbids. Say plainly that the leaves are deferred until the spine exists, then run the handoff.

If .cortex/ does not exist, ask before writing anything — including the index. This skill is reachable on a repo where no Cortex ritual has ever run, so it can be the first thing to create that directory, which is the write ADR 0005 gates. Generated and gitignored is not the same as invisible: these are files appearing in someone's project on a run they did not ask for. The .gitignore entry is written for you at creation time — the asking is still yours.

1. Pick the areas

If the user named a directory, use it — they have already done the picking. Confirm it, then go to step 2.

Otherwise propose from evidence. Read .cortex/index/index.json. If it is missing or older than the working tree, re-run:

node "${CLAUDE_PLUGIN_ROOT}/index/cortex-index.mjs" .

The index ranks candidate directories by size, churn and absence of tests, and skips anything declared linguist-vendored or linguist-generated in .gitattributes — nobody edits vendored code, so a brief for it is context every session pays for and no one uses. If a vendored tree ranks anyway, it has not been declared: say so and offer the one-line .gitattributes entry rather than briefing it. On one repo the top three candidates were a plugin cache, a generated server and another tool's instruction files, with the application fourth.

Present the top candidates with the reason each was surfaced — never a bare list. A user cannot consent to a proposal they cannot evaluate.

Then wait. The user picks which areas get a brief. Some will be declined; that is a correct outcome, not a failure.

2. Write one leaf per accepted area

<area>/AGENTS.md, opening with a line that points up to the root — a leaf adds depth to the spine, it never replaces it:

Scoped brief. Read the root /AGENTS.md first for stack and conventions; this adds depth for <area>.

Keep the body narrow. A leaf earns its place by holding what the root cannot:

• What this area is responsible for, in two or three sentences.
• The invariants — the things that must stay true, that an agent could plausibly break.
• The gotchas: the non-obvious coupling, the thing that looks wrong but is deliberate.
• How to run just this area's tests.

Do not restate the stack, the conventions or anything already in the root. Duplication is how these files rot: two copies drift and neither is trusted.

Everything in a leaf must be observed, not assumed. Read the code. If you cannot name a real invariant, the area does not need a brief yet — say so and move on.

Head the two lists ## Invariants and ## Gotchas, one list item per rule. Those are the headings the root template uses, and the ones cortex-review.mjs --rules reads.

When a test already fails if an invariant breaks, name that test file in the item. Look for it before writing the item: a rule that names its test tells the next agent what to run, and one that names nothing rests on this sentence alone. Name only a test you opened and read. Never write one to have something to name, and never name one that merely sits in the same directory.

3. Wire the routing table

The root AGENTS.md gets a table, and nothing else changes:

## Where to look

| Working in | Read first |
|---|---|
| `billing/` | [`billing/AGENTS.md`](billing/AGENTS.md) |
| `auth/` | [`auth/AGENTS.md`](auth/AGENTS.md) |

An agent reads the root, matches its work to a row, opens exactly one leaf. No hook, no engine — the routing table is prose an agent follows.

Then move, don't duplicate: a fact that now lives in a leaf comes out of the root, leaving the routing row as its pointer. Root holds the global, leaves hold the local, and no fact lives in two places — that is where drift starts. The root gets shorter as leaves appear.

Format what you wrote. Write LF line endings. Run the repo's declared formatter (state.formatters in cortex-loop.mjs . --json) on exactly the files you wrote: each leaf and the root you edited. Never run it on .. Then run the repo's own lint/format check. A leaf that fails the repo's prettier --check breaks that repo's CI on the PR that adds it. If the check still fails on a file you wrote, report it with the output in step 4.

4. Report

List the files written and show the routing table you added. Suggest committing them together — a leaf without its routing row is invisible.

Then say what the rules you wrote rest on. Re-index, and read the ledger:

node "${CLAUDE_PLUGIN_ROOT}/index/cortex-index.mjs" .
node "${CLAUDE_PLUGIN_ROOT}/index/cortex-review.mjs" --rules --json

For the leaves written in this run, report how many rules name a test file, how many name other files only, and list the ones that name no test, each with its doc:line. Report it as it is. A gotcha states a limit no test could pin, so a rule in that list is not a defect and needs no fix here. It is the list the user reads to decide which invariant deserves a test next.

Gotchas

• One filename, AGENTS.md. Never a sprawl of per-topic files in a directory (architecture.md / conventions.md / …) — that was the retired engine's shape.
• Ship a leaf in the same PR as the code it covers. That is what keeps it true; a leaf updated later is a leaf updated never.
• One repo's leaves never reference another repo. Cross-project knowledge belongs in the vault.
• Split where an invariant lives, not where the file count is high. A 40-file directory of similar components needs one line in the root; a 6-file payment module may need a full brief.
• A leaf that only says "this is the auth directory" is worse than no leaf: it costs context and teaches nothing. Delete it.
• Re-run after big refactors — a brief describing a module that moved is actively misleading.