route-models-hvn

Files (3)

• SKILL.md
• openai.yaml · agents/
• routing-research.md · references/

SKILL.md (first lines)

# Route Models-HVN

Optimize expected total usage to verified completion, not the price of an individual turn. Apply this routing contract at the start of every task and again at every meaningful phase boundary.

## Always-on routing contract

1. Preserve an explicit user-requested model or effort unless it is unavailable or unsafe for the task. Explain a material tradeoff; do not silently override it.
2. Inspect the model and reasoning combinations exposed by the destination host or task tool. Callable capability is execution truth; a remembered model matrix is not.
3. Classify the work as orchestration and planning, bounded implementation, deterministic evidence, or high-risk judgment before dispatching it.
4. When creating or continuing a Codex task, pass the selected `model` and `thinking` or reasoning effort explicitly when task creation or model management is authorized. An agent that starts a new task owns this classification and must set the route in the creation call.
5. If the destination cannot accept the selected model or effort, choose the strongest supported fallback, record the fallback and reason in the task handoff, and continue only if the quality boundary remains safe.
6. Do not create replacement tasks merely to change a model. Apply a route change at the next natural turn or phase boundary unless the current route is unsafe.

The preferred operating split is `gpt-5.6-sol` with `xhigh` for orchestration, planning, architecture, high-risk diagnosis, and final synthesis, and `gpt-5.6-luna` with `max` for bounded implementation workers whose scope, files, tests, and acceptance evidence are explicit. This is a quality-and-usage hypothesis, not a universal benchmark result; measure rework, proof completeness, latency, and total usage in the actual workload.

## Routing matrix

| Phase or task | Model and effort | Route rationale | Escalate when |
| --- | --- | --- | --- |
| Orchestration, planning, graph design, architecture, or final synthesis | `gpt-5.6-sol` `xhigh` | Ambiguity, cross-system dependencies, and missed evidence are expensive. | Evidence conflicts, scope expands, or the decision becomes security, release, destructive, or irreversible. |
| High-risk implementation or diagnosis | `gpt-5.6-sol` `high` or `xhigh` | Subtle correctness, data, security, compatibility, or ownership semantics dominate token savings. | One material attempt fails, the root cause is architectural, or proof cannot be produced. |
| Bounded implementation worker | `gpt-5.6-luna` `max` | Scope and acceptance evidence are explicit, so capacity can be spent on complete execution. | Requirements become ambiguous, the patch crosses a protected boundary, or rework begins. |
| Deterministic test rerun, formatting, extraction, or evidence collection | `gpt-5.6-luna` `low` or the lowest supported effort | The action is mechanical and recovery is cheap. | Interpretation, exploratory testing, or consequential judgment appears. |
| Release, destructive, production, security, privacy, payment, or account decision | `gpt-5.6-sol` `xhigh` | The cost of an incorrect judgment exceeds the model-cost saving. | Stop and escalate when authority or external truth is missing. |

Never use Luna for an ambiguous release decision, destructive process ownership, production mutation, security or privacy judgment, payment or account deletion, or unresolved repository state. Do not use the cheapest route when predictable redo costs more than the initial saving.

## Graph engineering

Represent substantial work as a directed acyclic graph of evidence-producing nodes before dispatch:

`discover -> classify -> plan -> fan-out -> implement -> verify -> integrate -> decide`

Each node has an owner, selected model and effort, inputs, output contract, files or environment it may touch, evidence requirement, dependency edges, and a stop condition. Fan out only independent lanes. Fan in through one integrator on Sol xhigh after checking duplicate findings, incompatible assumptions, dirty-state preservation, and exact candidate identity. Preserve rejected alternatives and their reasons so the graph remains auditable.

Use a cycle only when it is an explicitly bounded improvement loop with a measurable exit condition. A graph edge should carry the artifact that justifies the next node, not merely a statement that a previous agent ran. If a node cannot produce its required evidence, mark it `UNVERIFIED` or escalate; do not advance it by optimistic inference.

## Loop engineering

Every remediation or quality loop follows:

`observe -> reproduce -> diagnose -> act -> verify -> classify -> escalate or de-escalate`

Before entering the loop, set the objective, owner, budget, iteration limit, evidence threshold, and stop conditions. After each iteration, record what changed, what evidence improved, what remains uncertain, and whether the selected route still matches the phase. A failed attempt is new information, not permission for blind repetition.

Use Sol xhigh for the loop controller, root-cause synthesis, and final decision. Use Luna max for a bounded action node only after the controller has made the action and acceptance criteria explicit. Return to Sol when the action fails, the evidence conflicts, the diff crosses a protected boundary, or the loop has not converged within its budget. Close the loop only after the original reproduction, regression coverage, adjacent checks, and delivery evidence agree.

## Safe task dispatch

For Codex task tools, use explicit fields equivalent to:

```text
orchestrator: model="gpt-5.6-sol", thinking="xhigh"
implementation worker: model="gpt-5.6-luna", thinking="max"
```

The actual task tool or host may expose a different set of models or effort names. Inspect it first and use its accepted values. Put the route, task objective, repository, branch or worktree, permissions, evidence contract, and escalation trigger in the handoff. Never assume a child task inherited the intended model; verify the created task’s effective settings when the tool provides them.

## Re-route and measure

Escalate one tier or one reasoning level when a material attempt fails, evidence conflicts, the work becomes security-sensitive or destructive, the repository or external state is ambiguous, or the proof burden cannot be met. De-escalate when scope is stable, implementation is frozen, failures are understood, and verification is deterministic.

Track total usage, wall-clock latency, rework, number of route changes, proof completeness, and external or human gates. Keep the split only when it improves verified completion for the workload. Current official model descriptions and graph/loop research are summarized in `references/routing-research.md`.

From henryvn27/agent-skills, MIT.

More from henryvn27/agent-skills