Sauci/docs/agents/routing.md

Agent routing and effort

The primary agent owns scope, acceptance criteria, task decomposition, and the final answer. Use one implementation agent when a bounded handoff will keep noisy execution out of the primary context. Do not pay the coordination cost for a trivial one-file edit. Add other agents only for separable work or a risk trigger.

Implementation and integration

Implementation starts in a dedicated task worktree created from the current staging branch. Keep the shared staging checkout clean and use it only as the integration target. Complete the scoped change, review its diff, and run the required verification in the task worktree. Merge the task branch back into local staging only after that evidence passes; an unverified or partially complete branch does not belong in staging.

Completion includes publishing the work: commit only the scoped task changes, merge the verified commit into local staging, push staging, then fetch or read back the remote ref and prove HEAD equals origin/staging. Do not report an implementation complete while its commits exist only in a task worktree or the local integration checkout. A blocked or ambiguous push is a blocker, not a successful publish; preserve the commit, do not retry blindly, and report the exact remote state. Pushing and deployment remain subject to applicable branch protection, release, and production-safety rules.

Before implementation, map the change to every deployed consumer it can affect, including supported mobile builds, web and admin clients, the API and worker, and internal MCP integrations. Preserve their current interfaces, configuration, authentication and data expectations. Verification must cover the affected contracts and cross-application path, not only the edited package. If the change can alter live production, first establish the actual deployed versions, configuration, dependencies, interfaces, and behavior; after deployment, independently verify the affected end-to-end behavior. A local test, repository state, or successful deployment record is not proof that deployed apps remain functional.

Cost ladder

Project Codex defaults live in .codex/config.toml; task profiles live in .codex/agents/. An explicit task handoff may raise or lower reasoning effort.

Role	Codex model	Default effort	Trigger	Do not use for
repo_scout	Luna	low	locate ownership, callers, contracts	editing or design decisions
implementation	Terra	medium, overridable	bounded product or harness change	broad architecture review
test_writer	Terra	medium	focused regression or missing contract test	rubber-stamping green output
verifier	Terra	medium	independently drive implemented behavior	editing implementation
database_reviewer	Terra	high	migrations, RLS, function/query boundaries	ordinary UI changes
security_reviewer	Sol	high	auth, RLS, crypto, secrets, payments, destructive operations	every routine change
architecture_reviewer	Sol	high	cross-cutting or hard-to-reverse decisions	local refactors

Claude profiles under .claude/agents/ provide equivalent roles when Claude is explicitly requested. They are not part of the normal Codex routing path.

Implementation effort

Keep implementation on Terra and choose effort from the task shape:

• low: mechanical, fully specified, narrow change with an obvious check.
• medium: normal feature or bug fix with a few files and known contracts.
• high: ambiguous behavior, several interacting modules, concurrency, or difficult debugging.
• xhigh: exceptional Terra implementation where high effort has already proved insufficient or the change has a large but non-security blast radius.

Security and architecture risk are different jobs, not reasons to silently turn the implementation agent into a premium generalist. Add the matching read-only Sol reviewer and keep implementation on Terra unless the user explicitly asks for a different model.

Handoff contract

Every delegated task includes the objective, owned files or surface, acceptance criteria, applicable AGENTS.md and skill, allowed side effects, required checks, and the evidence to return. The agent must report changed files, commands and results, assumptions, and blockers. The primary agent independently reviews the diff and decides whether acceptance has been met.

Parallel agents are for independent read-heavy work or non-overlapping ownership. Avoid concurrent edits to the same files, shared database state, fixed local ports, or one simulator. Subagents consume additional tokens, so parallelism must buy meaningful time or independent judgment.

Procedures belong in deterministic skills rather than agent prompts. Agents read the nearest AGENTS.md and the applicable repository skill, then operate only within the task's authorization. Verification agents return evidence and a verdict; they do not fix implementation.