Codex AGENTS.md

AGENTS.md

Codex Agent Rules

Model and effort routing (GPT-5.6)

Pick the cheapest model/effort that can do the job well. Do not default upward.

Model	Role	Cost	Default use
Luna	Everyday coding	Cheapest	Default for most work
Terra	Workhorse	Mid	Multi-file / repo-scale work
Sol	Judgment	Highest	Planning, hard bugs, architecture, final review

Effort map

Luna

• Low: search
• Medium: small fixes
• High (default): normal everyday coding; fast, capable, not wasteful
• XHigh: better quality without the price jump of Sol/Terra Max
• Max: n/a

Terra

• Low: quick work
• Medium: bigger features (multi-file, balanced)
• High: big repo / repo-wide changes
• XHigh: mixed reports
• Max: multi-agent; burns quota (avoid for routine work)

Sol

• Low: mechanical work (wasteful; prefer Luna)
• Medium: serious daily work (prefer Terra when possible)
• High: the hard stuff: planning, hard bugs, architecture, reviewing final work
• XHigh: very hard cases only
• Max: essentially never for subagents (parallel multi-agent; fans out and burns quota)

Defaults (in order of preference)

1. Luna High: all-day default
2. Luna XHigh: when quality matters but Sol is not justified
3. Terra Medium / High: bigger or repo-wide work
4. Sol High: only when the task genuinely needs judgment

---

Subagent rules

These rules apply whenever you spawn, plan, or configure subagents.

Never use Sol Max for subagents

• Sol Max is banned for subagents unless the user explicitly requests it by name.
• Max is a parallel multi-agent mode that can burn through usage extremely quickly.
• Prefer a single Sol High (or lower) agent over Sol Max fan-out.

Prefer cheaper models for subagents

When choosing a model/effort for a subagent, default down:

Subagent task	Prefer
Search, skim, small fixes, mechanical edits	Luna High (or Luna Medium)
Quality-sensitive single-file or focused work	Luna XHigh
Multi-file features, balanced implementation	Terra Medium
Repo-wide refactors / broad changes	Terra High
Planning, hard debugging, architecture, final review	Sol High
Very hard edge cases	Sol XHigh (rare)
Parallel multi-agent Max (any model)	Do not use unless user opts in

Do not put Sol on exploratory, mechanical, or straightforward implementation subagents.

Agent count limits

• Stick to 1-3 subagents by default.
• Ask before spawning more than 3.
• Sol (and especially Max) can fan out into more agents than expected; every extra agent chews quota.
• Prefer fewer, well-scoped agents over broad fan-out.
• Parallelize only when subtasks are independent; otherwise run sequentially on one agent.

Before spawning

1. Confirm the work actually needs a subagent (not just a single turn on the parent).
2. Assign the lowest model/effort that fits the task (table above).
3. Give each agent a tight scope, clear success criteria, and a hard stop.
4. Cap concurrency; do not auto-expand the swarm.
5. If Max or >3 agents seems necessary, stop and ask the user first.

Max (any model)

• Treat Terra Max and Sol Max as quota burners.
• Do not enable Max modes for subagent workflows without explicit user approval.
• If the user asks for parallel work, still prefer 1-3 normal-effort agents over Max.