richlander/dotnet-inspect/update-agents-md

Updating AGENTS.md

Use this skill before every AGENTS.md edit.

Hard constraints

• 120-line cap. Run wc -l AGENTS.md before and after every edit. Never

land growth above 120 or defer extraction.

• 120-line Steward cap. When routing or PR-lifecycle ownership changes,

keep .claude/skills/steward/SKILL.md at or below 120 lines.

• Caps are ceilings. Do not add prose merely to consume available lines.

Acquire guidance progressively: launch rules in AGENTS.md, PR decisions in Steward, and mechanics in focused documents.

• Launch contract only. Keep the repository mission, immediate routing,

universal non-negotiables, and protected operator templates. Detailed mechanics, rationale, examples, edge cases, command inventories, and subsystem rules belong in focused documents.

• No second index. docs/README.md owns curated navigation. AGENTS may

link the small set of entrypoints needed to begin work but never grows a task catalog.

• Protect the root README boundary. When entrypoint guidance changes,

confirm README.md remains a product landing page of at most 120 lines. Featured capabilities require both a runnable CLI command and matching https://dotnet-inspect.net/?w=... packet URL.

• Protect operator templates. Keep the theme/status reminder, post-merge

handoff, tmux command/state block, round report, and their invocation rules directly in AGENTS.md. Do not shorten or move them to satisfy the cap.

Ownership test

Keep a statement in AGENTS only when an unrelated session needs it before it can identify and open the focused owner. Put these elsewhere:

• repository worktrees, history, documentation, engineering, and publication

mechanics: docs/repository-workflow.md;

• development posture: docs/development-practices.md;
• design scope: docs/design-scope.md;
• evidence: docs/evidence-and-validation.md;
• SDK, build, and testing: docs/dev-environment.md;
• PR rounds and state transitions: docs/round-orchestration.md;
• point-of-use PR decisions: the steward skill;
• subsystem behavior: its owning design or implementation guide.

The focused document owns the contract. AGENTS routes to it and may retain only the launch-critical invariant needed before acquisition.

Workflow

1. Record the baseline with wc -l AGENTS.md.
2. Identify the focused owner for every changed claim.
3. Edit the owner first when behavior or policy changes.
4. Keep only the shortest launch-time rule or route in AGENTS.
5. Repair incoming links and ownership statements; never leave a focused

document claiming a removed AGENTS section is normative.

1. Confirm every protected template remains directly usable.
2. Check the AGENTS and root README caps.
3. Run Markdown lint for every changed Markdown file.

When the cap is exceeded, move a whole concern to its focused owner. Never compress by deleting headings, fusing unrelated prose, removing blank lines, or shaving wording solely to save lines.

Validation

wc -l AGENTS.md   # must be <= 120
wc -l .claude/skills/steward/SKILL.md   # must be <= 120
wc -l README.md   # must be <= 120
npx markdownlint-cli AGENTS.md <other-changed-markdown>