--- name: agents-md-thin-root description: "Use when editing AGENTS.md (package root) or templates/AGENTS.md (consumer) — enforces Thin-Root contract: hard char ceilings, ≥40% pointer ratio, mandatory emergency-triage block." source: package execution: type: assisted handler: internal allowed_tools: [] --- # agents-md-thin-root ## When to use Use when: - Editing `AGENTS.md` at the package root. - Editing `.agent-src.uncompressed/templates/AGENTS.md` (consumer-shipped template). - Reviewing a PR that changes either file. - Running `/optimize/agents`. - A budget meter (`scripts/measure_augment_budget.py`) flags the package-root AGENTS.md as the dominant cost. ## Do NOT - Edit `.github/copilot-instructions.md` with this skill (use `copilot-agents-optimization` instead). - Edit other `.md` files under `.augment/`, `.agent-src.uncompressed/`, or `agents/` with this skill. - Add a section to AGENTS.md without first checking whether an outboard target already exists in `agents/contexts/` or `docs/contracts/`. - Replace prose with a bare link `[label](path)` — every pointer needs a *why*-clause ≥ 60 chars or it does not count toward the 40 % ratio. - Reuse the package-root anatomy in the consumer template — caps and target paths differ. ## Why Thin-Root Augment Code injects `AGENTS.md` verbatim into every workspace prompt. Each kilobyte spent here permanently consumes the 49,512-char workspace-guidelines budget shared with always-rules and auto-rule registry stubs. The Thin-Root pattern keeps the entry point a navigation surface (pointers + intent) and pushes deep detail into files Augment loads on demand via `load_context` or that other tools fetch only when their search retrieves them. Strategic council R2 (2026-05-08, Sonnet 4.5 / Opus 4.1 / gpt-4o / o1) converged on the contract codified below as the minimum guard against AGENTS.md re-bloat. ## Iron Law — Capabilities over Structure Every entry describes **what** the project does or **where** to learn more — never **where** individual files live. Path lists rot every refactor and poison context; capability pointers survive structural churn. Full anatomy with rewrite recipes, monorepo guidance, and multi-tool symlink strategy: [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md). ## The contract — hard caps | File | FAIL above | WARN above | Target | |---|---|---|---| | `AGENTS.md` (package root) | 3,000 chars | 2,800 chars | ≤ 2,800 | | `.agent-src.uncompressed/templates/AGENTS.md` (consumer) | 2,500 chars | 2,300 chars | ≤ 2,300 | Char-count is raw file size (`wc -c`), frontmatter included. Enforcement: `scripts/lint_agents_md.py` (Phase 7), wired into the package's CI pipeline via the `lint-agents-md` task. WARN is a soft signal in CI; FAIL blocks merge. The R2 council originally proposed 2,500 / 2,000 caps. Phase 6.4 empirical refactor demonstrated that the mandatory emergency-triage block (≈ 700 chars) plus operational must-haves (source-of-truth disclaimer, `task` quickstart, six substantive pointers) raise the achievable floor by ≈ 500 chars. The caps above are the post-refactor baseline; the previous numbers stayed unattainable without dropping mandatory content. ## The contract — pointer ratio ≥ 40 % of non-blank lines must be **substantive pointers**. A substantive pointer is a Markdown link `[label](path[#anchor])` whose surrounding sentence carries a *why* clause ≥ 60 chars explaining what the reader will learn there. Decorative links (table-of-contents, badges, repeated cross-refs) do not count. Lint formula: ``` pointer_ratio = (substantive_pointer_lines / non_blank_lines) >= 0.40 ``` ## The contract — pointer anatomy Every substantive pointer specifies, on the same line or the immediately following line: 1. **Target file path** — repo-relative, no leading `./`. 2. **Optional anchor** — `#section-slug` when the linked file's content is large enough that landing in the middle saves the reader. Skip only when the linked file is itself short. 3. ***Why* clause** — ≥ 60 chars, present-tense, names the concrete decision the pointer unblocks. Not "see also", not "more info", not the file's title repeated. ### Wrong vs. right ❌ **Wrong** — bare link, no *why*, no anchor: > See [`commit-policy`](.agent-src/rules/commit-policy.md). ❌ **Wrong** — *why* present but < 60 chars: > Commit rules: [`commit-policy`](.agent-src/rules/commit-policy.md). ✅ **Right** — full anatomy, anchor, *why* ≥ 60 chars: > Commit policy — never auto-commit, four named exceptions, Hard Floor list of bulk-deletion / infra triggers: [`commit-policy § Iron Law`](.agent-src/rules/commit-policy.md#the-iron-law). ✅ **Right** — anchor optional when target is short: > Mirror the user's language every reply, single Iron Law that overrides any momentum: [`language-and-tone`](.agent-src/rules/language-and-tone.md). ## The contract — emergency-triage block Every Thin-Root AGENTS.md MUST contain an **Emergency Triage** section verbatim from `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` (Phase 6.4 will create that file as the canonical source). The block lists the five questions a host agent answers from the root file alone when network / tool access is degraded: 1. What is this repository? 2. What language(s) does this repository accept? 3. Where do I edit (source-of-truth path)? 4. What is the lint / test / sync entry point? 5. Where do the always-active behavior rules live? Each answer must fit on one line. The block exists so the root never silently degrades to "useful only when every linked file is reachable". ## Procedure — apply Thin-Root to AGENTS.md 1. **Measure baseline.** `wc -c AGENTS.md` and `python3 scripts/measure_augment_budget.py`. Record current char-count and the gap to 2,200 / 2,500. 2. **Inventory sections.** List every `## ` heading and its char-count. Mark each as `keep-inline` (Iron-Law-adjacent, ≤ 200 chars, no good outboard target) or `outboard-candidate` (longer-form prose, table-only sections, narrative). 3. **Identify outboard targets.** For each `outboard-candidate`, name the destination — `.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, an existing skill body. Never invent a new top-level directory. 4. **Move content; insert pointer.** Cut the section into the target file. Replace it in AGENTS.md with a single substantive pointer per anatomy above. Verify the *why*-clause length. 5. **Re-measure.** `wc -c AGENTS.md` again. If above 2,200, repeat steps 2–4 on the next-largest section. Above 2,500 = must outboard further before commit. 6. **Validate pointer ratio.** Count non-blank lines and substantive-pointer lines. Ratio < 0.40 = collapse decorative or boilerplate lines into a single pointer or remove. 7. **Verify emergency-triage block.** Diff the in-file block against `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md`. Drift = revert to canonical. 8. **Run lints.** `task lint-agents-md && task check-refs && task lint-skills`. All green before commit. ## Procedure — apply Thin-Root to consumer template Same procedure, applied to `.agent-src.uncompressed/templates/AGENTS.md`. Hard cap shifts to 2,000 / 1,700. The consumer template intentionally lacks the package-self-references — its pointers target files that exist in the **consumer's** repo (`.augment/skills/`, `agents/contexts/`, ...), not this package's authoring tree. ## Gotchas - **Outboarding to a new top-level dir.** Inventing `agents/explainers/` or `docs/notes/` for the moved content silently widens the contract surface. Outboard only into `.agent-src.uncompressed/contexts/`, `docs/contracts/`, an existing rule body, or an existing skill body. - **Pointer-ratio inflation by decoration.** Adding boilerplate "Browse all skills" / "See also" links to lift the ratio above 40 % defeats the purpose. The lint counts only substantive pointers (with a *why*-clause ≥ 60 chars); decorative links get filtered out and the ratio drops back below threshold. - **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync. - **Cap inversion under WARN.** A 2,250-char AGENTS.md (above 2,200 WARN, below 2,500 FAIL) is a yellow signal not a green one — every additional sentence raises the probability of the next FAIL. Treat WARN as the spend boundary, not a buffer. - **Char-count includes frontmatter.** `wc -c` counts every byte including the YAML preamble, blank lines, and the trailing newline. Stripping a section to "look smaller" without re-running `wc -c` understates the true budget impact. - **Path enumeration.** A run of three or more bare `` `path/to/dir/` `` bullets without *why*-clauses is the classic re-bloat pattern. The lint emits a WARN at ≥ 3 such lines. Collapse them into one capability-style pointer — see the recipe in [`agents-md-anatomy § Iron Law`](../../contexts/contracts/agents-md-anatomy.md#iron-law--capabilities-over-structure). - **Tool-specific duplicates.** Copy-pasting AGENTS.md into `CLAUDE.md` / `GEMINI.md` / `.cursorrules` doubles the budget cost across tools. Use the symlink-or-stub pattern in [`agents-md-anatomy § Multi-tool symlink strategy`](../../contexts/contracts/agents-md-anatomy.md#multi-tool-symlink-strategy) instead. ## Output format When invoked as a planning step, produce: 1. Current size + gap to target (one line per file). 2. Inventory table (section, chars, keep-inline / outboard-candidate, target). 3. Pointer ratio before / after (predicted). 4. Specific outboarding edits as a numbered diff plan. 5. The four lint commands the agent must run before claiming completion. ## Cloud Behavior Inert on cloud surfaces. The skill governs the package-root `AGENTS.md` and the consumer-shipped template — both authoring artifacts inside this repository. Cloud agents working on consumer projects never edit those files directly; their copy is delivered by the package install pipeline and refreshed by the package sync pipeline. The Thin-Root contract therefore has no cloud-side procedure to execute, which is why this skill is marked `cloud_safe: noop`. ## See also - [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md) — Capabilities-over-Structure Iron Law, multi-tool symlink strategy, monorepo per-package layout, refactor recipe, full gotcha catalog. - [`copilot-agents-optimization`](../copilot-agents-optimization/SKILL.md) — sibling skill for `.github/copilot-instructions.md`; runs alongside Thin-Root in `/agents optimize`. - [`agent-docs-writing`](../agent-docs-writing/SKILL.md) — broader documentation-structure context for navigating outboard targets. - [`size-enforcement`](../../rules/size-enforcement.md) — covers per-skill / per-rule / per-command size budgets; AGENTS.md caps live in this skill instead. - [`ADR-004-rule-governance-pruning`](../../../docs/decisions/ADR-004-rule-governance-pruning.md) — captures the rule-governance pruning that freed the workspace-guidelines budget; the Thin-Root caps build on that headroom.