Sauci/docs/agents/routing.md

# Agent routing and effort

Sol is the primary agent and owns scope, risk classification, acceptance
criteria, task decomposition, progress steering, final diff and evidence review,
and the final answer. Every substantive repository task must delegate to a
project agent. Each substantive implementation must delegate one coherent
execution unit to the Terra `implementation` agent. That handoff normally
combines scoped discovery, implementation, focused tests, and iteration in one
continuous task. Add a `repo_scout`, reviewer, test writer, or verifier only for
separable work or the triggers below. The primary reviews the returned diff and
evidence, but does not repeat the implementation agent's detailed exploration or
checks without a concrete reason. Skip delegation only for trivial conversation,
a single obvious lookup, or a mechanical one-line edit whose coordination cost
exceeds the work.

## 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 | separable read-only ownership, caller, or contract lookup | editing or design decisions |
| `implementation` | Terra | medium, overridable | one continuous scoped discovery, implementation, test, and iteration unit | broad architecture review |
| `test_writer` | Terra | medium | focused regression or missing contract test | rubber-stamping green output |
| `verifier` | Terra | medium | user-facing, cross-boundary, or high-risk runtime behavior | editing implementation or low-risk package-local changes |
| `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.

## Verification routing

Use a fresh Terra `verifier` after implementation when the change has
user-facing runtime behavior, crosses an application, API, data, authentication,
or provider boundary, or is otherwise high risk. The verifier independently
drives the acceptance criteria and returns evidence only. It is not required for
documentation, mechanical configuration, isolated tests, or low-risk
package-local changes with focused deterministic checks. A verifier may still be
added when independent observation would materially increase confidence.

## 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 independently reviews the final
diff and evidence and decides whether acceptance has been met. It should steer
the active implementation agent with targeted feedback rather than restart the
same discovery or verification in another agent unless an independent judgment,
separable workstream, or the verification-routing trigger requires it.

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.