A cost-conscious multi-agent workflow for GPT-5.6 Codex.
This repository is not intended to be a universal “best configuration.” It is an opinionated starting point for teams that want strong architecture and implementation quality without running every task at the highest reasoning effort or passing an entire repository and conversation history to every agent.
The workflow was designed around five goals:
- Reduce unnecessary token and quota consumption.
- Preserve strong planning and review for consequential changes.
- Keep implementation workers narrowly scoped.
- Escalate reasoning based on observed evidence rather than task size alone.
- Prevent persistence, parallelism, or broad permissions from turning a normal coding task into an uncontrolled agent run.
| Stage | Agent | Model and effort |
|---|---|---|
| Root coordination | default | Sol Medium |
| Normal planning | sol_architect |
Sol Medium |
| Difficult architecture | sol_architect_deep |
Sol High |
| Tiny mechanical edit | luna_worker_lite |
Luna Medium |
| Normal implementation | luna_worker |
Luna High |
| Blocked implementation | luna_escalation |
Luna Max |
| Final review | sol_reviewer |
Sol High, read-only |
The root agent mostly routes work, maintains task state, and chooses the next specialist. Those actions do not usually require deep architectural reasoning.
Medium gives the root enough reasoning capacity to preserve the complete task model, route bounded work, and integrate evidence without promoting every task to a high-effort specialist. Deeper reasoning remains isolated to the specific planning, implementation, or review task that needs it.
Planning benefits from stronger reasoning than routine coordination because it must identify dependencies, define task boundaries, and choose interfaces.
Medium is the default because most repository planning should be solvable by:
- targeted code inspection;
- recognition of existing patterns;
- a few connected design decisions;
- explicit acceptance criteria and validation.
Starting every plan at High would spend more quota before there is evidence that the problem is genuinely difficult.
Sol High is reserved for planning problems that remain unresolved after a normal architecture pass, such as:
- conflicting requirements;
- consequential architectural tradeoffs;
- cross-system coupling;
- data migration or compatibility risk;
- concurrency, security, or persistence concerns.
The deep architect refuses to run unless a concrete escalation trigger and supporting evidence are recorded. This makes reasoning escalation an auditable decision rather than an instinctive reaction to a large task.
Most implementation work becomes substantially easier after the architect has produced a bounded task with exact files, constraints, and validation.
Luna High is intended to handle normal bounded execution without paying Sol rates for every file edit. Luna Medium is available for tiny mechanical changes, while Luna Max is reserved for a bounded task that produces a concrete local blocker or unexplained validation failure.
Parallel workers can each complete their own task while still introducing integration problems between modules.
The final reviewer receives the plan, handoff, diff, and validation evidence. It uses Sol High because integration review may require checking assumptions across worker boundaries, public interfaces, regressions, and unsupported completion claims.
The reviewer is read-only so review does not silently turn into another implementation pass.
This workflow intentionally routes work between Luna and Sol rather than using Terra as an intermediate tier.
Current cost-versus-capability analysis indicates that Terra may be dominated by some combination of Luna and Sol reasoning levels: Luna handles bounded, repeatable work at substantially lower cost, while Sol handles ambiguous or high-value reasoning.
Do not introduce Terra merely because a task is more difficult than a normal Luna task. First:
- improve or narrow the context packet;
- increase Luna reasoning for a bounded implementation problem; or
- return an architectural problem to Sol.
Consider Terra only when repository-specific evaluation shows that it produces a better completion rate, latency, or total cost than both:
- Luna at the appropriate higher reasoning effort; and
- Sol at the appropriate lower reasoning effort.
Record that evaluation before adding Terra to an agent definition.
AGENTS.md is automatically relevant to many sessions, so every temporary
detail placed there becomes recurring context cost.
It contains only rules that should apply to almost every task:
- routing and escalation policy;
- context discipline;
- scope and authorization boundaries;
- validation expectations;
- documentation lifecycle.
Project architecture belongs in docs/ai/PROJECT_CONTEXT.md. Current work
belongs in plans/ACTIVE_PLAN.md. Session continuity belongs in
plans/HANDOFF.md.
Each implementation task lists the exact files, symbols, documentation, and constraints the worker should begin with.
This prevents every worker from:
- scanning the entire repository;
- rediscovering the same architecture;
- reading unrelated documentation;
- inheriting the full architect transcript;
- carrying completed investigative history.
A worker may perform a targeted search when a listed file reveals a necessary dependency, but it must stop when the task requires materially broader scope.
plans/ACTIVE_PLAN.md is an executable contract, not a transcript of planner
reasoning. Every task records bounded context, fixed decisions, ordered steps,
acceptance criteria, validation commands and expected evidence, authorization
boundaries, and stop or escalation conditions.
Task status is exactly one of Not started, In progress, Blocked, or
Complete. Criteria are checked only from direct evidence. Ordinary incomplete
or yielded work remains In progress; Blocked means an explicit stop or
escalation condition occurred. Sol/root keeps the active plan and
plans/HANDOFF.md synchronized with exactly one global coordinator action.
An explicitly delegated architect may initialize or amend the contract before
implementation. During implementation, only Sol/root writes
plans/ACTIVE_PLAN.md and plans/HANDOFF.md; Luna workers return provisional
packets and never mutate these shared artifacts.
Before dispatch, Sol records one task, or at most two explicitly parallel-safe
tasks with disjoint implementation-file ownership, as In progress in one
execution group. The group holds live worker identities, root-accepted evidence
and statuses, and an exact task-local resume point per member. After dispatch
begins, its one global action is Reconcile execution group {task IDs} for every
nonterminal group, including one with no live workers. A failed dispatch records
direct evidence and one exact task-local retry or environment remedy.
After dispatch begins, Reconcile remains the sole global action for a
nonterminal group, even when zero workers are live. Each member separately
records dispatch pending, live, retry pending, yielded, blocked, or
complete, plus its spawn evidence and exact remedy. With two successful spawns
both become live; with one failure only that member becomes retry pending; and
with two failures reconciliation selects the first nonterminal member in plan
order while retaining both remedies. A peer retry is never a second global
action.
Sol first accepts or rejects a paused checkpoint, then records terminal packets
or spawn results, then applies the first plan-order retry or yielded
continuation. A continuing checkpoint carries a packet ID, is marked
paused awaiting acknowledgment, and stops every owned-file mutation until Sol
accepts or rejects that ID. Without in-turn acknowledgment the worker sends a
stopped yield, exits, remains In progress, and resumes by re-delegation.
Completion, yield, and block packets are stable only after stop; continuing
messages are telemetry and cannot advance evidence, status, or resume state.
The group closes only when every member is complete or has a recorded blocker.
During compaction recovery, the sole action is
Recover execution group {task IDs} until Sol re-establishes membership and
task-local resume state, then returns to Reconcile.
Long conversations accumulate repeated exploration, superseded plans, command output, and unrelated decisions.
Before compaction or changing features, the active session writes a concise handoff that projects the active plan and contains only:
- objective and current task;
- decisions already made;
- changed files;
- directly observed validation results;
- authorization boundaries;
- blockers and exactly one next action.
The next session reads that handoff rather than the full transcript.
Large build logs and test output can dominate context even when only one error line matters.
The root configuration limits retained tool output, and the instructions require agents to record concise outcomes rather than carrying full logs forward.
Compaction preserves requirements, decisions, relevant files, direct validation evidence, authorization boundaries, the synchronized plan/handoff checkpoint, one allowed status, and exactly one next action while dropping repeated exploration and superseded material.
The configuration permits the root plus at most two worker threads:
[agents]
max_depth = 1
max_threads = 3Parallelism is useful only when tasks are truly independent. Every extra worker may repeat prompt context, repository discovery, tool calls, and validation.
Two workers provide useful parallelism without encouraging large uncontrolled fan-out.
max_depth = 1 prevents implementation workers from recursively spawning
additional workers.
The architect decides task boundaries once. The root performs delegation. Workers execute their assigned task. This keeps ownership and token use predictable.
Workers receive only:
- their assigned task;
- the explicit context packet;
- the current handoff entry;
- ordered steps;
- fixed decisions and constraints;
- authorization boundaries;
- acceptance criteria;
- validation commands;
- expected evidence;
- stop or escalation conditions;
- the packet schema: task ID, packet ID, kind and proposed status, stability declaration, owned and changed files, completed steps, validation commands and observed outcomes, criterion evidence mapping, exact local continuation or blocker, assumptions, risks, and integration notes.
The architect’s complete conversation is deliberately excluded because its raw exploration is usually not required for implementation.
The workflow treats escalation as appropriate only when the problem is reasoning-limited.
Valid signals include:
- unresolved design tradeoffs;
- contradictory constraints;
- hidden cross-component coupling;
- repeated incorrect hypotheses despite new evidence;
- an implementation failure with an unclear root cause;
- high-impact uncertainty involving data, APIs, security, concurrency, migrations, or compatibility.
These are not reasoning-escalation signals:
- missing or irrelevant context;
- vague acceptance criteria;
- missing permissions or credentials;
- tool, dependency, or environment failures;
- very large logs;
- excessive conversation history;
- several unrelated tasks combined into one request.
Those problems should be repaired directly instead of spending more reasoning tokens.
The trigger and evidence are recorded in plans/ACTIVE_PLAN.md, and only the
affected task is escalated. Later bounded tasks return to their normal tier.
The instructions avoid phrases such as:
- “never stop”;
- “do whatever it takes”;
- “find another way at all costs”;
- “complete the task without asking.”
Those instructions can encourage an agent to widen scope, bypass safeguards, or keep consuming quota after meaningful progress has stopped.
Agents instead continue only within explicit scope and stop when progress requires new permissions, credentials, targets, destructive actions, or a material scope change.
Agents may not silently substitute a different:
- environment;
- account;
- machine;
- service;
- branch;
- database;
- resource;
- credential source.
A failed action against the named target is reported as a blocker. It is not treated as permission to find a different target.
A test, build, migration, calculation, or behavior may be described as successful only when the agent has direct evidence that it ran and observed the result.
Plans and handoffs contain separate fields for validation commands and observed evidence so assumptions do not become recorded facts.
The root config enables sandbox Auto-review for eligible permission-boundary requests:
approval_policy = "on-request"
approvals_reviewer = "auto_review"Auto-review evaluates whether an eligible sandbox-boundary action should be approved. It does not grant unlimited access and does not review the completed code.
sol_reviewer performs the final integration review of the diff and validation
evidence.
.codex/
├── config.toml
└── agents/
├── sol-architect.toml
├── sol-architect-deep.toml
├── sol-reviewer.toml
├── luna-worker-lite.toml
├── luna-worker.toml
└── luna-escalation.toml
AGENTS.md
CODEX_WORKFLOW.md
docs/ai/
├── PROJECT_CONTEXT.md
└── INSTRUCTION_AUDIT.md
plans/
├── ACTIVE_PLAN.md
├── HANDOFF.md
├── TASK_TEMPLATE.md
└── completed/
Copy the repository contents into the root of a trusted Codex project.
Complete docs/ai/PROJECT_CONTEXT.md with:
- the stable architecture map;
- module and data boundaries;
- formatting and build commands;
- focused and full test commands;
- static-analysis commands;
- the final integration check;
- production-sensitive or destructive operations.
Do not add project history or completed task logs to AGENTS.md.
Use sol_architect to investigate this request and create
plans/ACTIVE_PLAN.md. Do not implement code.
Use targeted repository searches. Define exact context packets,
ordered steps, authorization boundaries, expected validation evidence, stop
conditions, and an initial checkpoint synchronized with plans/HANDOFF.md.
Request:
<paste request>
Use sol_architect_deep only when the normal architect records a concrete
reasoning-limited blocker and supporting evidence.
For a tiny mechanical edit:
Implement Task 1 with luna_worker_lite.
Pass only Task 1, its context packet, current handoff, ordered steps,
constraints, authorization boundaries, acceptance criteria, validation
commands, expected evidence, and stop conditions. Return structured packets to
Sol; do not edit plans/ACTIVE_PLAN.md or plans/HANDOFF.md. Stop if the work is
not mechanical.
For a normal task:
Implement Task 1 with luna_worker.
Pass only Task 1, its context packet, current handoff entry, constraints,
ordered steps, authorization boundaries, acceptance criteria, expected
evidence, validation commands, and stop conditions. Return structured packets
to Sol; do not edit plans/ACTIVE_PLAN.md or plans/HANDOFF.md.
For two independent tasks:
Tasks 1 and 2 are explicitly marked parallel-safe.
For each worker, pass only its task, context packet, current handoff, ordered
steps, constraints, authorization boundaries, acceptance criteria, validation
commands, expected evidence, and stop conditions. Verify disjoint
implementation-file ownership, spawn one Luna worker for each, and reconcile
their structured packets. Workers must not edit plans/ACTIVE_PLAN.md or
plans/HANDOFF.md. Do not spawn additional agents.
Every checkpoint, completion, yield, or block packet contains the task ID;
task-scoped monotonically ordered packet ID; packet kind and proposed status;
stability declaration (paused awaiting acknowledgment or stopped); owned
and changed files; completed steps; validation commands and outcomes; criterion
evidence mapping; exact local continuation or blocker; assumptions; risks; and
integration notes. A continuing checkpoint pauses all owned-file mutations until
Sol accepts or rejects that packet ID; without an in-turn acknowledgment, send a
stopped yield and exit. Continuing messages are telemetry only.
Task 2 has a recorded reasoning-limited blocker.
Use luna_escalation with only:
- Task 2;
- its context packet;
- the current handoff and previous worker packet;
- its ordered steps;
- its expected evidence;
- its stop conditions;
- the failed validation and concise evidence;
- the recorded escalation trigger.
Return structured packets to Sol; do not edit plans/ACTIVE_PLAN.md or
plans/HANDOFF.md. Do not repeat broad exploration or widen scope.
Return to the normal reasoning tier after the blocked task is resolved.
Use sol_reviewer to review:
- the original request;
- plans/ACTIVE_PLAN.md;
- plans/HANDOFF.md;
- the final diff;
- validation evidence.
Check for unsupported completion claims, authorization overreach,
regressions, interface mismatches, missing tests, invalid task statuses,
plan/handoff drift, unauthorized shared-artifact writers, execution-group
transition errors, and missing or multiple global actions.
Run the process in docs/ai/INSTRUCTION_AUDIT.md after adopting the workflow,
changing models, or importing older personal or project instructions.
The audit looks for:
- unbounded persistence language;
- broad delegation triggers;
- oversized persistent context;
- missing authorization boundaries;
- reasoning tiers that start unnecessarily high.
Move the finished plan to:
plans/completed/YYYY-MM-DD-short-feature-name.md
Reset plans/ACTIVE_PLAN.md and plans/HANDOFF.md.
Keep their reusable checkpoints synchronized with exactly one next action.
Do not copy completed feature history into AGENTS.md.