In examples/codex/code_modernization.md, Phase 0 says to create AGENTS.md and PLANS.md “placed in a .agent folder,” suggests using /init for the repository AGENTS.md, and later references refining .agent/AGENTS.md and .agent/PLANS.md.
However, Codex’s documented discovery rules say it walks from repo root down to the current working directory and only checks AGENTS.override.md, then AGENTS.md, then configured fallback filenames in each directory along that path. Also /init generates AGENTS.md in the current directory.
As written, the cookbook implies .agent/AGENTS.md is a “repo-level” instructions file created by /init, but if you run Codex from the repository root (the doc also uses “Example prompt from the repository root”), .agent/AGENTS.md won’t be automatically loaded.
Suggested doc fix options:
- Leave repo-root AGENTS.md and keep .agent/PLANS.md in .agent/
- Describe or link to instructions for using the .agent/ folder as a fallback location in ~/.codex/config.toml (project_doc_fallback_filenames=[".agent/AGENTS.md"]). Instruct the reader to move the AGENTS.md to this location. This worked for me.
Thank you!
In examples/codex/code_modernization.md, Phase 0 says to create AGENTS.md and PLANS.md “placed in a .agent folder,” suggests using /init for the repository AGENTS.md, and later references refining .agent/AGENTS.md and .agent/PLANS.md.
However, Codex’s documented discovery rules say it walks from repo root down to the current working directory and only checks AGENTS.override.md, then AGENTS.md, then configured fallback filenames in each directory along that path. Also /init generates AGENTS.md in the current directory.
As written, the cookbook implies .agent/AGENTS.md is a “repo-level” instructions file created by /init, but if you run Codex from the repository root (the doc also uses “Example prompt from the repository root”), .agent/AGENTS.md won’t be automatically loaded.
Suggested doc fix options:
Thank you!