.codex/Actors and limits
Project config chooses root Sol, caps depth and threads, and defines Terra, Luna, and a read-only Sol reviewer.
Field dossier / Codex systemsVerified
How to Build an Automated Sol–Terra Review Loop in Codex
Let GPT-5.6 Sol plan and judge, let Terra or Luna produce the bulk work, and send evidence-based feedback back to the same worker until the result passes—or needs a human.
ZIP includes project-scoped agent files, the workflow skill, contracts, AGENTS.md rules, installer, and verifier. Review every file before merging it into a repository.
§ 01 / The answerVerified
One planner. One worker. One independent judge.
Codex supports project-scoped custom agents, skills, AGENTS.md instructions, configurable thread limits, and model-specific reasoning settings. Those primitives are enough to express this workflow; the discipline comes from the contract around them. OpenAI subagent docs
| Role | Responsibility | Model / effort | Writes? | Best fit |
|---|---|---|---|---|
| sol | Coordinator + final gate | gpt-5.6-sol / xhigh | Root only | Plans the contract, chooses a worker, and owns the final decision. |
| terra | Default worker | gpt-5.6-terra / high | Yes | Multi-file coding, tool use, reports, recovery, and moderate ambiguity. |
| luna | Mechanical worker | gpt-5.6-luna / medium | Yes | Clear extraction, transformation, formatting, classification, and routine edits. |
| sol | Independent reviewer | gpt-5.6-sol / xhigh | No / read-only | Checks criteria, evidence, regressions, and scope without defending the plan. |
Model-name check: the downloadable setup uses the slugs exposed by the verified local Codex model catalog. Codex evolves quickly, so confirm the current model picker or catalog before installation.
§ 02 / ArchitectureBest effort
The return path is the design.
A second answer is not automatically a review. The useful loop keeps an explicit contract, assigns one writer, gives an independent reviewer read-only access, and returns failed criteria to the same worker so it can revise with context intact.
solterraluna
- sol01
Plan
Inspect context. Write deliverables, constraints, tests, and pass/fail criteria.
- sol02
Route
Choose one worker: Terra for ambiguity and tools; Luna for mechanical work.
- terra03
Produce
The single write-capable worker makes the artifact and reports evidence.
- sol04
Review
A separate read-only Sol checks every criterion against the real artifact.
- sol05
Final gate
Root Sol independently accepts, requests revision, or escalates.
Revise → return to the same worker thread / ID
123attempts
Sol sends concrete failed criteria and reproduction evidence back to the original Terra or Luna worker. It does not replace the worker just to start with a clean context.
Back to stage 03
Human escalation rail
After attempt three—or when authority, evidence, or required input is missing—the run stops as needs_human_review with its evidence preserved.
Important limitation: public Codex documentation describes the primitives, not a guaranteed native state machine for every transition. Treat the skill-driven sequence as best effort and inspect the run. Use a controller when transition enforcement is mandatory.
§ 03 / Three surfacesVerified
Put each rule where Codex actually reads it.
The setup splits model configuration, reusable process instructions, and repository rules across the Codex surfaces intended for each job. AGENTS.md guide
.agents/skills/The repeatable loop
The skill owns planning, worker routing, reviewer handoff, the same-worker revision rule, round cap, and terminal states.
AGENTS.mdRepository guardrails
The addendum makes scope, single-writer safety, evidence, permission boundaries, and human escalation part of the project contract.
§ 04 / InstallationVerified
Merge carefully, verify mechanically, pilot safely.
The ZIP is a native, project-scoped starter. It does not install globally, publish anything, or grant new permissions. Read the included manifest and copy only what fits your repository.
01
Extract
Unzip the package outside the target repository and review its manifest, files, and instructions.
02
Merge
Run the installer against a backed-up repository. Review conflicts instead of overwriting project guidance blindly.
03
Verify
Run the included verifier to check required files, TOML structure, model settings, and key workflow rules.
04
Pilot
Use a reversible task with precise acceptance criteria. Inspect the real thread sequence before trusting the loop.
Do not create a second [agents] table. TOML tables cannot be duplicated. If the repository already has an [agents] section, merge max_threads, max_depth, and the other keys into the existing table.
§ 05 / Native filesVerified
Copy the exact setup—or inspect it line by line.
These panels reproduce the key files and commands included in the downloadable package. Tab controls support arrow keys, Home, and End; every panel has a real clipboard control.
TOML / sol
.codex/config.toml
# Root task is the Sol coordinator and final gate.
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
[agents]
# Root + one worker + one reviewer, with one spare thread.
max_threads = 4
# Root may spawn children; children may not spawn grandchildren.
max_depth = 1
job_max_runtime_seconds = 1800
interrupt_message = true
§ 06 / First runBest effort
Invoke the skill with a task you can prove.
Start with a small repository change whose success can be checked by tests, file inspection, or a deterministic command. The first run is an architecture test, not a high-stakes production trial.
Codex prompt
$coordinator-worker-reviewer Add the requested feature, include tests, and keep changes scoped.A good pilot has four properties.
- Reversible changes
- No external side effects
- Explicit pass/fail checks
- Enough substance to trigger review
Watch for one worker, one separate reviewer, exact evidence, a same-worker follow-up when revision is required, and a final root gate. If the observed sequence differs, stop and inspect rather than assuming the written skill was enforced.
§ 07 / Illustrative traceIllustrative
What a healthy run should leave behind.
This trace explains the intended control flow. It is not a transcript of an authenticated run and should not be read as evidence that native Codex guarantees every transition.
- 1
Sol coordinator
Writes AC-1 through AC-4, selects Terra because the task spans several files and tests, then records the worker ID.
- 2
Terra worker / attempt 1
Implements the feature, runs safe checks, and returns paths, results, evidence, and limitations.
- 3
Sol reviewer
Marks AC-1, AC-2, and AC-4 pass; marks AC-3 fail with a reproduction path and exact requested fix.
- 4
Same Terra worker / attempt 2
Receives that feedback in the existing worker context, makes the scoped correction, and reruns the relevant check.
- 5
Sol reviewer + root gate
Reviewer accepts every criterion. Root Sol independently checks the current artifact and evidence, then returns complete.
§ 08 / Project-wide effectBest effort
The root model setting is not scoped to the skill.
This is the most important installation caveat. The agent files stay dormant until they are spawned; the top-level project model setting does not.
Fully automatic variation
Keep the supplied top-level model = "gpt-5.6-sol" and model_reasoning_effort = "xhigh". Root prompts in that repository will default to Sol Extra High, including prompts that do not invoke this workflow.
Opt-in variation
Remove those two top-level lines, choose Sol Extra High in Codex only for the coordinator run, and then invoke the skill. The role files and workflow remain available, but selection is less automatic and must be checked each time.
If you install the downloadable config unchanged, you are changing the default root model for the entire project—not only this one skill.
§ 09 / Routing rubricVerified
Route by ambiguity and verifiability, not by output length.
Give one point for each risk below. A total of 0–1 goes to Luna; 2–5 goes to Terra. If the coordinator is still unsure, use Terra.
- Material ambiguity+1
- Several dependent steps or files+1
- Tool use or environment inspection+1
- Recovery from partial failure+1
- Judgment-heavy synthesis or regression risk+1
luna
0–1
Clear and mechanical
terra
2–5
Ambiguous or tool-heavy
Luna / 1
Rename 80 files from a supplied map
High volume, but fixed inputs and a mechanical check.
Terra / 4
Build an authenticated settings page
Several files, tools, integration risk, and recovery.
Luna / 1
Convert a CSV into a fixed JSON schema
Clear transformation with schema validation.
Terra / 3
Research and draft a source-backed report
Tool use, source judgment, and synthesis matter.
§ 10 / Tokens and costVerified
Spend Sol tokens on contracts and gates.
Keep plans and reviewer feedback compact; let the worker produce most of the output. API prices below were published with GPT-5.6 and are per one million tokens. ChatGPT plan usage is not the same accounting system. GPT-5.6 launch
| Model | Input | Output |
|---|---|---|
| Sol | $5.00 | $30.00 |
| Terra | $2.50 | $15.00 |
| Luna | $1.00 | $6.00 |
Make criteria atomic
A reviewer should answer pass or fail without rewriting the task.
Send only failed findings
Return concrete evidence and requested changes, not a second essay.
Reuse the worker context
Avoid paying to reconstruct the task on every revision.
Cap attempts at three
Bound both token use and the cost of repeated mistakes.
Prices can change. Cached-input, batch, regional, plan, and tool charges may differ; check the current official pricing before budgeting.
§ 11 / Failure registerBest effort
Every failure mode needs a mechanical response.
The workflow is valuable only when it makes weak evidence and unsafe transitions visible. These pairs turn common agent-loop failures into explicit operating rules.
01
The plan is vague
Give every acceptance criterion an ID and a verification method before delegation.
02
The worker reviews itself
Use a separate read-only Sol reviewer and let root Sol make the final gate.
03
A revision starts from zero
Retain the worker thread or agent ID and steer the same worker with exact feedback.
04
Two writers collide
Run exactly one write-capable worker in a shared working tree.
05
Luna gets an ambiguous job
Escalate uncertainty and route multi-step, tool-heavy work to Terra.
06
The loop runs forever
Cap the workflow at three total worker attempts.
07
Confidence replaces proof
Require commands, artifacts, source checks, or reproduction evidence.
08
A blocked run claims success
Return needs_human_review when authority, evidence, or input is missing.
09
Project config changes every prompt
Use the scoped variation described below when Sol should not be the project default.
10
A model slug drifts
Confirm the current model picker or catalog before installing the files.
§ 12 / Deterministic alternativeUntested prototype
Use the SDK when the sequence must be code, not convention.
A controller can enforce role order, parse structured decisions, retain the worker thread, count attempts, persist artifacts, and stop on terminal states. That is a stronger guarantee than asking a native skill to follow the same lifecycle.
Required disclosure
The deterministic package passed syntax, schema, dry-run, and controller-guard checks, but the beta SDK was not installed and no authenticated, usage-consuming end-to-end run was completed. Treat it as an implementation-ready prototype, not production-proven software.
What the controller adds
- Structured plan, worker report, review, and final-gate schemas
- An explicit same-worker thread handle
- A hard three-attempt counter
- Terminal complete, needs_human_review, and failed states
- Persisted evidence for inspection and recovery
§ 13 / PreflightVerified
Ten checks before the first serious run.
This checklist protects the repository, confirms the configuration, and tests the parts of the workflow that natural-language instructions alone cannot guarantee.
- 01Back up or commit the target repository before installation.
- 02Confirm the current Codex model slugs for Sol, Terra, and Luna.
- 03Merge—not duplicate—an existing [agents] block in .codex/config.toml.
- 04Keep max_depth at 1 so workers cannot spawn descendants.
- 05Keep the reviewer read-only and the worker workspace-write.
- 06Copy the skill, its contracts reference, and the AGENTS.md addendum.
- 07Run the included verifier before the first real task.
- 08Start with a safe, reversible pilot and objective checks.
- 09Inspect whether review feedback returns to the same worker ID.
- 10Stop at three attempts and escalate unresolved work to a human.
§ 14 / Community signalAnecdotal
Useful field notes, not product guarantees.
These posts point to recurring operator concerns: pin the worker model, conserve strong-model tokens, distrust unverified native orchestration, and isolate risky work. They are experience reports, not official documentation.
Field note 1Pin the worker explicitlyDan McInerney on explicitly pinning worker modelsField note 2Reserve expensive reasoning for gatesDivine Machine on token-parsimonious agent rolesField note 3Inspect native harness behaviorgreco on native harness reliability concernsField note 4Use isolation and review for risky workoscar gabriel on worktrees, review, and remaining rough edges
§ 15 / FAQVerified
The questions that change how you install it.
The short answers preserve the important distinctions: dormant agent definitions versus project-wide root defaults, best-effort native control versus deterministic code, and completion versus escalation.
Q 01
Does this workflow affect every prompt?
The coordinator-worker-reviewer loop runs only when you explicitly invoke the skill or when a request clearly matches its description. The custom Terra, Luna, and reviewer definitions stay dormant until spawned. However, the supplied .codex/config.toml sets root Sol xhigh and agent limits at the project level, so those defaults also affect ordinary root prompts in that repository. If you want Sol only for selected runs, omit the top-level model and model_reasoning_effort lines and choose Sol Extra High manually before invoking the skill; that variation is less automatic.
Q 02
Why is Terra the default worker?
Most real coding and report tasks combine tool use, several steps, moderate ambiguity, and regression risk. Terra is the safer everyday worker for that shape of work. If the coordinator is uncertain after applying the routing score, it should choose Terra.
Q 03
When should Luna be used?
Use Luna when the contract is clear, repeatable, high-volume, and mechanically checkable: extraction, formatting, transformation, classification, or routine edits. Long output alone is not enough; long but ambiguous or tool-heavy work still belongs to Terra.
Q 04
Why not use Sol Ultra?
Ultra is designed around parallel subagent fan-out. This workflow is a sequential, bounded review loop with one writer and a specific same-worker return path. Sol Extra High keeps the coordinator and reviewer strong without automatically creating a broad parallel run that can use more tokens.
Q 05
Is the native sequence guaranteed?
No. Native Codex provides the actors and can follow the skill from one prompt, but the public documentation does not guarantee every transition, same-thread revision, or round cap as a contractual state machine. Use the deterministic SDK controller when those transitions must be enforced by code.
Q 06
Why use another Sol thread as the reviewer?
A separate read-only Sol thread reduces anchoring to the planner's approach and avoids letting the writer edit while it judges its own work. The reviewer checks the task, plan, current artifact, and evidence; root Sol still owns the final acceptance gate.
Q 07
How many review rounds are allowed?
The setup allows three total worker attempts, including the first pass. If the third attempt still fails, evidence is missing, or authority is unavailable, the workflow stops with needs_human_review instead of looping forever or pretending completion.
Q 08
Can this create reports and non-coding deliverables?
Yes. Replace code tests with source checks, required-section audits, schema validation, numerical reconciliation, link checks, or format verification. Terra is usually the report worker; Luna is appropriate for fixed-template transformations.
Q 09
Are hooks required?
No. Start with the custom agents, skill, and AGENTS.md rules. Add a hook only after a repeated real failure shows which lifecycle check needs mechanical enforcement, and always include a loop guard.
Q 10
What happens when the agents cannot prove completion?
They should stop with needs_human_review and preserve the plan, worker report, review, evidence, and exact blocker. The workflow does not expand permissions or invent missing facts just to reach a complete state.
§ 16 / SourcesVerified
Receipts, limits, and further reading.
Official documentation supports the product primitives and current model facts. Research supports tool-assisted feedback loops but also warns against assuming self-correction works without evidence. Community links are labeled anecdotal.
Official
OpenAI: GPT-5.6 launch, availability, Ultra, and API pricingOpenAI Codex: subagents and project-scoped custom agentsOpenAI Codex: build skillsOpenAI Codex: AGENTS.md discovery and precedenceOpenAI Codex: configuration referenceOpenAI Codex: SDK overviewOpenAI Codex: Python SDK API referenceOpenAI Codex: model and reasoning guidanceOpenAI Codex: hooksOpenAI Codex: what's new
Native path
Fastest to try; inspect whether the requested lifecycle actually occurs.
Evidence rule
Tests and artifacts outrank every model's confidence statement.
Human stop
Missing proof is a reason to escalate, not a reason to invent success.
Work with Matt
Need a review loop designed around your real workflow?
Matt helps teams turn advanced AI models into clear operating systems—with scoped roles, evidence gates, cost controls, and human escalation built in.