Always-loaded AGENTS.md size (~92KB / ~21K tokens): what must stay inline vs. move to skills/docs?

[e-jung]

The problem

AGENTS.md — the always-loaded orchestrator instruction file that CLAUDE.md symlinks to — has grown to 795 lines / 92,527 bytes / ~21,255 cl100k_base tokens (measured with gpt-tokenizer).

That token cost is paid by every session of every fleet member (the primary firstmate and every secondmate home), every turn, whether or not that session ever hits the situations the file describes. A secondmate home running nothing but a watcher still loads all ~21K tokens.

This is not abstract. Claude Code now emits context warnings against the current size, and long high-context supervision sessions have already produced malformed tool-call leakage to the captain (#95). The global user ~/.claude/CLAUDE.md is ~1.3KB and is not the cause — the project AGENTS.md is.

Note: this is intentionally a design discussion, not a finished rewrite. I'm bringing the question here rather than landing a unilateral change.

The design question

How much of AGENTS.md genuinely must live in the always-loaded file, versus what can move to:

• progressively-loaded skill SKILL.md files under .agents/skills/ (loaded only when a named trigger fires), or
• docs/ (human/reference narratives), or
• owning script headers / --help (exact commands, flags, schemas, mechanics)?

The file has already been slimmed twice — the #79 restructure and the #447 "centralize operating contracts" sweep — both following the same proven pattern: move conditional blocks to existing skills/docs and leave a one-line trigger stub inline. #447 is the template to copy.

Evidence: where the bytes live

Per-section token budget from a recent audit:

Section	Lines	Tokens	%
§7 Task lifecycle	177	5,170	24%
§8 Supervision protocol	104	3,029	14%
§6 Project management	103	1,963	9%
§2 Layout and state	63	1,880	9%
§3 Session start	50	1,709	8%
§4 Harness adapters	64	1,399	7%
§10 Backlog format	56	1,483	7%
§1 Identity / prime directives	43	1,073	5%
§11 Briefs / §5 Recovery / §9 Escalation / §13 Skills / §14 X mode / §12	…	…	17%

§7 + §8 alone = 38% of the file. Any serious slim has to cut there; everything else is rounding.

Evidence: much of the bulk restates contracts already owned elsewhere

Each row below is a contract stated substantively in AGENTS.md and already owned in full by another file. The "owner" column is where the full contract lives per the one-owner rule:

Inline in AGENTS.md	Already owned by
§7 Validate run-step state table	bin/fm-crew-state.sh header (verbatim mapping logic)
§7 Spawn resolution mechanics	bin/fm-spawn.sh header
§1 teardown landed-work definition	bin/fm-teardown.sh header (full landed-work + pr= fallback)
§10 tasks-axi verb catalog	tasks-axi --help
§2 state/ watcher internals	docs/architecture.md ("Event-driven supervision")
§5 restart inventory	docs/architecture.md ("Restart-proof")
§4 dispatch-profile schema	docs/configuration.md ("Crew dispatch profiles")

And the existing skill/doc owners that already hold most of the conditional contracts: bootstrap-diagnostics, harness-adapters, secondmate-provisioning, stuck-crewmate-recovery, afk, fmx-respond, firstmate-orca, docs/architecture.md, docs/configuration.md, and the bin/* headers.

The firstmate-coding-guidelines skill already codifies the rules that would keep this from regrowing after a diet pass: a knowledge-placement decision tree, a one-owner rule (every contract stated fully exactly once; all other mentions are one-line pointers), and an inline-stub pattern (keep only the trigger condition + the one safety fact that must survive with no skill loaded). §8's "Away-mode stub" is the named gold-standard model for that pattern.

What I explored (reference, not a proposal to merge)

I did a local exploratory pass converting AGENTS.md into a compact operating index — keeping the 14-section numbering and every safety invariant (captain address, never-write-to-projects, merge authority, no-discard teardown, the six sanctioned write exceptions, single session-start entry + read-once rule, project/secondmate scope resolution, dispatch-profile consultation + unverified-harness refusal, one-owner supervision + no-turn-ends-blind, wake-drain ordering, away-mode ownership transfer, skill-load triggers, captain-facing outcome language) while routing conditional procedures to the existing skills, narratives to docs, and mechanics to script headers.

It reached roughly half the original size (92KB → ~42KB) before I paused to bring the design question here instead of landing a unilateral rewrite. The exploratory diff is viewable here for reference:

main...e-jung:firstmate:fm/agents-slim-ship-r8

Invitation

I'd value the maintainer's and community's read on the right target and structure:

• Is a ~40KB / ~10K-token ceiling right for the always-loaded file, or should it be tighter (~30KB)?
• Are there contracts currently inline that you'd consider safe to move behind a trigger stub?
• Conversely, are there owners you'd rather keep duplicated inline for safety reasons (because the fact fires on a wake where no skill is loaded)?

Happy to refine the exploratory branch into a proper PR against whatever structure we agree on. Not looking to merge anything unilaterally.