[gantoine]

Problem

• Every agent session in this repo loads the root AGENTS.md in full, so each line added to it costs every task.
• chore(agents): move topic rules out of the root agents file #123122 halves the file to 22,490 bytes, but nothing stops it from growing back.
• /editing-agents-md states a target of under 200 lines, and no check enforces it.

Changes

• A new repo invariant, test_agents_md_size_budget.py, fails when the root AGENTS.md exceeds 23,000 bytes.
• The budget leaves about 500 bytes of headroom over the size after chore(agents): move topic rules out of the root agents file #123122, enough for a small edit but not a new section.
• The failure message says what to do instead: move the rule to a .agents/ guide or a skill, or cut an older line.
• The budget counts bytes, not lines. The file uses semantic line breaks, so line count tracks sentences, not tokens.
• /editing-agents-md now names the test, replaces the 200-line target with it, and asks for a reason in the PR before anyone raises the budget.
• The repo_invariants CI filter already matches AGENTS.md, so an edit to the file runs the test.

Note

Stacked on #123122. That PR comes from a fork, so its head sits in this repo as stack/slim-root-agents to give this PR a clean diff. Retarget to master once #123122 merges.

How did you test this code?

Test rationale: the new test catches the root file growing past its budget. No existing test checks the size. The tag invariant checks only the content.

• The test passes on this branch at 22,490 bytes.
• With the budget lowered to 22,000, it fails with the message above.

Release status

• No feature flag controls this change

Docs update

None. The /editing-agents-md skill carries the budget rule.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: Claude Code, Claude Opus 5.5 (claude-opus-5-5)

• Third of three PRs from a list of token-cost ideas, next to feat(engineering-analytics): list agent llm spend per pr for an author #123368 (hogli agent:usage) and feat(agents): hint on resume when a session's context is large and cold #123369 (SessionStart hint).
• A pre-commit warning was the other option. A warning never blocks, so the file would keep growing one exception at a time. The invariant test blocks, and its budget moves only by a reviewed edit.
• Skills invoked: /editing-agents-md, /writing-tests, /writing-pr-descriptions.
• No duplicate: no open PR adds a size check for AGENTS.md.
• Public artifact: the PR holds no session material.

🤖 Generated with Claude Code

[github-actions]

🤖 CI report

🚨 Trunk lane — universal lane

This PR is assigned to the universal lane. It cannot merge in parallel with other PRs, so it can take longer to merge. Ask dev-ex if you think this is wrong.

✅ Duplication (Python) — clean

New Python code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

✅ Duplication (TypeScript) — clean

New TypeScript code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.