agent-docs-upgrader

Run an audit against criteria like routing speed, length, specificity, and freshness, then rewrite the file as a concise operating manual. Keep entry docs around 60-150 lines with decision tables, real commands, and short examples instead of long prose.

A good AGENTS.md contains a project map, common workflow tables, real build/test/lint commands, local rules with reasons, and trigger-based references to large specs. It should route the agent to the right module quickly rather than forcing it to read every document.

Yes, by default keep AGENTS.md and CLAUDE.md identical to reduce drift and prevent different agents from reading different project rules. Only isolate small platform-specific sections when explicitly requested, keeping shared rules synchronized.

Use a root AGENTS.md as a routing document with a workspace map pointing to each sub-repo's entry doc. Before creating or omitting sub-repo docs, choose a strategy: root-only routing, docs for specified sub-repos, or docs for all detected sub-repos.

Long, stale, or contradictory docs force agents to over-read, cause wrong edits, and slow routing. A bad doc is worse than no doc when it contains old paths, obsolete commands, or unconditional instructions to read all documentation first.