AGENTS.md Improver

Audit and improve Codex AGENTS.md guidance files and companion code_map.md navigation maps so future Codex CLI, Codex App, and native subagent sessions receive concise, accurate, scoped project instructions and fast code search entry points.

Default mode is report-first. Output a quality report and proposed diff before writing. If the user explicitly asks to implement an approved plan, continue directly to targeted edits and verification.

Core Semantics

• An AGENTS.md file governs the directory that contains it and every descendant directory.
• A deeper AGENTS.md adds or overrides guidance for its subtree.
• System, developer, and direct user instructions outrank any AGENTS.md content.
• Repository AGENTS.md files are project guidance. User-level ~/.codex/AGENTS.md is global preference guidance and should not be edited unless explicitly requested.
• AGENTS.md carries durable behavioral constraints, commands, and safety rules. code_map.md carries navigational structure, search anchors, entry points, and generated/ignored directory notes.
• Every created or updated AGENTS.md should explicitly name the relative code_map.md path agents must read before broad grep or repo-wide search, for example See ./code_map.md before broad grep or For this subtree, start with platforms/codex/code_map.md.
• Preserve hook-managed marker blocks such as <!-- OMX:RUNTIME:START --> ... <!-- OMX:RUNTIME:END --> and <!-- OMX:TEAM:WORKER:START --> ... <!-- OMX:TEAM:WORKER:END -->.

Workflow

Phase 1: Discovery