Model routing: roles, workhorse slots and tiered execution
Overdeck runs every agent in a role. The role decides the model, the model’s provider decides the harness, and tiered execution can staff planned work by difficulty instead of the role’s default.How Overdeck picks a model
resolveModel(role, subRole, config, spawnKey) (src/lib/config-yaml/roles.ts)
resolves a role’s model in this order:
- The sub-role’s own model, if one is set and it is not
parent. - The role’s model. If the role’s model is a distribution (a weighted list), one entry is picked; see Split a role across models.
- The built-in default for that role (see the table in Roles and sub-roles).
- If the result of steps 1 to 3 is a workhorse reference (
workhorse:<slot>), it is then replaced with that slot’s model.
pan start <id> --model <model>
sets the work model for that session and also skips tier selection (see
Tiered execution). pan start --plan-model <model>
overrides the planning model when that start auto-plans, and pan plan <id> --model <model> sets the planning model directly. pan start --tier is
unrelated to any of this: it picks the remote workspace resiliency tier,
ephemeral or durable, not a tiered-execution setting.
Workhorse slots
A workhorse slot is one of three named model slots that roles point at instead of naming a model directly:expensive, mid and cheap. Settings
shows these under Model Routing’s Workhorse Models panel (“Set the three
model slots that roles reference with workhorse:<slot>.”). Only these three
slot names are allowed; another key fails config load with an unknown
workhorse slot error, and a slot cannot point at another slot or at parent.
config.yaml: <field> references workhorse:<slot> but workhorses.<slot> is not defined.
Roles and sub-roles
A role is one kind of agent run in Overdeck. Sub-roles are configuration slots under a role with their own model and effort: review has four,security, correctness, performance and requirements; plan has
one, critic.
roles.review.mode controls how review runs: quick (default, one
reviewer), full (four lanes plus the review parent’s synthesis), or none
(no AI review; the verification gate still runs). Setting
roles.review.model alone does not move the four lanes, because each lane
has its own default; set a lane’s model to parent to have it inherit
roles.review.model.
The plan critic model is roles.plan.sub.critic.model. It has no default and
must come from a different model family than the planner; see
Planning for the critic’s role in finalizing a plan.
In Settings, Role Models shows eight role cards: Plan, Work, Strike,
Review, Test, Ship, Flywheel and Sequencer. knowledge, worker and the plan
critic sub-role have no card; set them directly in config.yaml. Review’s
card has a Show sub-roles toggle that reveals the four lanes, each with its
own model and an Effort select (Inherit, or a level), plus the Review mode select. The Flywheel card adds Flywheel effort, Flywheel max agents
and Flywheel scope. There is no per-role harness control, and no role-level
effort control except Flywheel’s. Every model select groups its options as
Inheritance (sub-roles only: Parent), Workhorse, and specific models by
provider.
Split a role across models
A role’smodel can be a weighted list instead of a single reference, each
entry a positive integer weight:
<role>:<issueId>, so one issue always
gets the same entry across respawns. A sub-role never samples the parent
role’s distribution; it always resolves its own setting. In Settings, the
role card’s button reads Use distribution (and Use single model to go
back to one entry).
Which harness runs a model
A harness is the coding-agent CLI that runs a model.resolveHarness
(src/lib/harness-resolve.ts) picks it in this order:
- An explicit pick wins:
pan start --harness,pan plan --harness,pan strike --harness, or a launch panel or model picker row that names a harness. - Otherwise, the provider default harness set in Settings → Providers
(
models.providers.<provider>.harness). - Otherwise, the provider’s own built-in default.
Default harness control
(Default (<built-in>) plus the allowed harnesses for that provider). A
separate toggle, Show all harness/model permutations (off by default),
makes model pickers show explicit harness and model combinations instead of
only each provider’s default harness. Saving a provider’s harness writes:
pan doctor flags a crew model, or roles.work.model
when tiered execution is off, whose provider is not enabled.
If the chosen harness is denied by policy for the model, an explicit pick
fails loudly. A provider-default pick falls back to claude-code only for
models native to claude-code, and otherwise fails the same way.
roles.<role>.harness is validated when config.yaml loads, but no pipeline
spawn reads it. Its only effect today is that the dashboard Plan dialog
preselects roles.plan.harness for a new planning session. See
#5518.
Tiered execution
Tiered execution is optional staffing that picks the work agent’s model, harness and effort from a plan item’sdifficulty (and optionally its
kind), instead of using roles.work for every item. It is off by default.
Settings calls this page Tiered Execution, and calls one row of the tier
table a crew.
Turn it on
Turn tiered execution on withtiered_execution.enabled: true, or the
Settings switch Route work by difficulty. A plan can override the global
switch for its own issue with plan.metadata.tiered_execution: on or off;
any other value is an error. There is no CLI flag for this switch.
Route work by difficulty switch; an invalid-config banner when the block is invalid;
Who handles each difficulty? (one crew per difficulty); The crews with
+ Add crew; Standing reviewer (model, harness, and a Reviews choice of
all, flagged or sampled); Kind overrides; an Advanced section with
Commit feed, Escalation and Session replay; and What this writes to config.yaml. A crew is labelled with its model’s name, workhorse:<slot> → <model name>
for a workhorse reference, or N-model mix for a distribution. On save, each
crew becomes one tier named after its difficulties joined with a hyphen, for
example simple-medium.
How an item finds its tier
Each of the five difficulties,trivial, simple, medium, complex and
expert, must map to exactly one tier, and a supervisor is required once
any tiers exist. by_kind keys must be item kinds (docs, api, backend,
frontend, infra, test, refactor, design, spike), and their values
must be existing tier names. A distribution can replace a tier’s model
and harness with a weighted list whose integer weights total exactly 100.
A Settings save refuses an invalid block outright. At config load, an
invalid block does not stop Overdeck from starting: tiered staffing is
turned off, a warning is logged, and pan doctor reports “tiered_execution
is invalid and has been disabled.” A workhorse reference to an undefined
slot is invalid the same way.
For one item, resolveTier first checks for a by_kind match on the item’s
kind, then falls back to the item’s difficulty. An item that matches
neither falls through to roles.work instead of any tier. The harness for a
staffed item comes from its tier (or the matching distribution entry), never
from the model’s provider default. An item’s own metadata.model overrides
its tier’s model; the harness still comes from the tier.
Who runs the work
In the normal pipeline, one work agent runs the whole plan, staffed at the tier of the hardest item still open. In swarm mode, each item runs in its own slot agent, staffed at that item’s own tier. Either way,pan start --model skips tier selection entirely and runs on the model you named.
The Standing reviewer and the commit feed
The Standing reviewer (the supervisor inconfig.yaml) is a review-only
agent configured with its own model, harness and subscribe setting. It
runs only in swarm mode, after a slot’s work merges. subscribe: all
reviews every item; flagged reviews only items with
metadata.requiresInspection: true; sampled reviews a fixed 25% of items,
chosen by a hash of the item id.
The reviewer reports what it finds. Its verdict does not stop other work yet (PAN-5517).
In swarm mode only, once a slot merges, every live slot agent gets a
read-only message with that item’s title and diff, through the commit feed.
feed.exclude drops matching paths from the diff it sends, and
feed.max_diff_bytes swaps an oversized diff for a --stat summary instead
(there is no size limit by default). feed.exclude_subjects lists commit
subject prefixes: a commit whose subject starts with one of them is not sent
at all.
Fitness warnings
Overdeck checks whether a tier’s model fits the difficulties it owns, and warns (it never blocks) onunderpowered (the model is below what the
tier’s hardest difficulty needs), overpowered (a frontier model staffed on
a tier that only owns easy difficulties), unknown-model,
provider-not-enabled and supervisor-underpowered. These show in pan doctor, as badges in Settings → Tiered Execution, and as a line in the
spawn log.
pan admin config tiers prints what is actually configured: the resolved
roles.work model, whether tiering is enabled (or invalid, with the
reason), one line per tier with its resolved model, harness and
difficulties, a [overrides roles.work] marker on any tier that launches a
different model, and the note “Planned issues take their tier’s model, not
roles.work.”
Settings saved but not acted on yet
Overdeck checks and saves these settings, but nothing acts on them yet. Do not rely on them to change which model runs an item.escalation.*(enabled,retries_at_tier,max_promotions,effort_first): the function that would act on an escalation has no caller today. See #4512.replay_thresholdandcompaction_reroute(Session replay): the replay code they referred to was removed.- The commit feed’s
feed.calloutsnotifyandcorroborate: the call-out endpoint has no server handler. - The Standing reviewer’s block verdict, described above.
Presets and effort
A preset writes a coherent, explicit lineup intoconfig.yaml in one
step: the workhorse slots, roles, review lanes, effort, any existing tiers’
model and harness, and the conversation and background models. It never
turns tiered execution on or off, and it never creates tiers. Apply one from
Settings → Model Routing or pan models preset list | show | apply | undo;
see Model presets. Every effort a preset
sets is high.
Effort levels are low, medium, high, xhigh and max, and the default
is high; see Reasoning effort for the full
precedence chain. A tiered-execution tier’s own effort sits in that chain
below item and plan effort, and above sub-role and role effort.
Check what will run
pan admin config tiersprints the resolvedroles.workmodel and every configured tier’s resolved model, harness and difficulties. When tiering is off it marks the tiers as unused; when the block is invalid it prints only the reason.GET /api/models/resolvereturns the resolved model for plan, work, strike, review, the four review lanes, test and ship. For a role split across several models it shows the highest-weight entry.pan doctorreports an invalidtiered_executionblock and any fitness warning from the section above.
What Overdeck does not do
Overdeck does not pick a model from an issue’s wording, labels, size or budget. Models come from roles, workhorse slots and, for planned work, tiered execution. Older docs described a Cloister complexity router with amodel_selection block. That router was removed, and Overdeck ignores those keys.
Conversations are not pipeline roles: a new conversation uses
models.default_conversation_model unless you pick a model when you start
it. Background AI calls, such as titles, compaction and memory extraction,
have their own settings in Settings → Background AI, which this page does
not cover.