Feature: Add --agents flag to switch between named AGENTS.md variants

Summary

Add a --agents <name> CLI flag that allows users to switch between different named [AGENTS.md](<http://AGENTS.md>) files by name, e.g.:

codex --agents review "Review this PR"
codex --agents refactor "Clean up this module"
codex --agents debug "Find the root cause"

This would resolve to a file named AGENTS.<name>.md (or similar convention) in the standard discovery locations, rather than requiring the user to specify a full file path.

Motivation

Currently, Codex has a single [AGENTS.md](<http://AGENTS.md>) per directory level. There is no way to maintain multiple instruction sets for different workflows within the same project without renaming files or manipulating the filesystem each time.

Real-world use cases:

• Code review vs. code generation: A reviewer agent needs different instructions (focus on bugs, security, style) than a feature-building agent (focus on patterns, tests, architecture).
• Debugging vs. refactoring: Different tasks benefit from different system prompts — a debug agent should be methodical and trace-oriented, while a refactor agent should focus on readability and design patterns.
• Team roles: Different team members may want different instruction sets — a frontend dev and a backend dev working on the same monorepo need different context.
• CI/CD pipelines: Different pipeline stages (lint, review, generate tests) each need tailored instructions.

Proposed Behavior

File naming convention

AGENTS.md              # default (no --agents flag)
AGENTS.review.md       # codex --agents review
AGENTS.refactor.md     # codex --agents refactor
AGENTS.debug.md        # codex --agents debug

Discovery

Same directory-traversal logic as today, but at each level look for AGENTS.<name>.md (and AGENTS.<name>.override.md) instead of AGENTS.md:

1. Global: ~/.codex/AGENTS.<name>.override.md → ~/.codex/AGENTS.<name>.md
2. Project: Git root → CWD, checking AGENTS.<name>.override.md → AGENTS.<name>.md
3. Fallback: If no named variant is found at a given level, optionally fall back to the plain AGENTS.md at that level (configurable behavior).

Examples

# Use the "review" instruction set
codex --agents review "Check this PR for security issues"

# Use the "refactor" instruction set
codex --agents refactor "Simplify the authentication module"

# Default behavior (unchanged, no flag)
codex "Implement the new feature"

# In non-interactive mode
codex exec --agents review -q "List all potential bugs" --json

Edge cases

• Named file not found at any level → clear error: No AGENTS.review.md found in discovery path. Available variants: review, debug, refactor
• List available variants: codex --list-agents could scan discovery paths and list all AGENTS.*.md files
• Empty named file → skip silently (consistent with current behavior)

Why Not Just Use --profile?

Profiles (--profile <name>) already exist but control model and config settings (model name, reasoning effort, sandbox mode, etc.). Agent instructions are a separate concern — you may want the same model config but different instructions, or vice versa. Coupling them forces unnecessary duplication.

That said, profiles could also support an agents key:

[profiles.review]
model = "o3"
agents = "review"  # automatically implies --agents review

[profiles.quick-review]
model = "gpt-5-mini"
agents = "review"  # same instructions, cheaper model

Alternatives Considered

• --agents-file <path>: Too low-level; forces users to manage paths rather than names. Doesn't integrate with the existing discovery hierarchy.
• Symlinks / file renaming: Fragile, error-prone, no discoverability.
• project_doc_fallback_filenames: Only controls fallback filenames, doesn't support explicit selection.
• CODEX_HOME switching: Overkill — changes all global config just to swap instructions.

Related Issues

• CLI-1219 — Ability to bypass/disable [AGENTS.md](<http://AGENTS.md>) pipeline (complementary)
• CLI-2772 — CLI fails to read [AGENTS.md](<http://AGENTS.md>) from global location
• CLI-1911 — [AGENTS.md](<http://AGENTS.md>) silently truncated without warning