worktrail-routing-config
Configure Worktrail's agent routing table (`~/.worktrail/routing.yaml`, or a repo-local `routing:` policy block) — which harness/model executes each role and tier, and how fallback between them works. Use when the operator wants to add or remove a harness/adapter (claude/codex/opencode), add a model to an existing harness (e.g. adding a DeepSeek model to opencode), pin or change who does code review, add a new tier or purpose mapping, change the default tier, or is confused about which harness actually served a spawn (e.g. "why did this use Codex when I only configured Claude"). Trigger phrases: "routing.yaml", "add a harness", "disable a harness", "add an adapter", "remove an adapter", "add a model", "add deepseek to opencode", "change the reviewer", "pin the reviewer", "routing tiers", "routing targets", "default_tier", "independent reviewer", "why did codex get called". This skill is about *editing the config file*; it does not cover `/go`'s own dispatch mechanics (see `worktrail-go`'s SKILL.md Phase 7 for how `tier_for()`/`select_cell()` resolve it at runtime).
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- worktrail-routing-config
- description
- Configure Worktrail's agent routing table (`~/.worktrail/routing.yaml`, or a repo-local `routing:` policy block) — which harness/model executes each role and tier, and how fallback between them works. Use when the operator wants to add or remove a harness/adapter (claude/codex/opencode), add a model to an existing harness (e.g. adding a DeepSeek model to opencode), pin or change who does code review, add a new tier or purpose mapping, change the default tier, or is confused about which harness actually served a spawn (e.g. "why did this use Codex when I only configured Claude"). Trigger phrases: "routing.yaml", "add a harness", "disable a harness", "add an adapter", "remove an adapter", "add a model", "add deepseek to opencode", "change the reviewer", "pin the reviewer", "routing tiers", "routing targets", "default_tier", "independent reviewer", "why did codex get called". This skill is about *editing the config file*; it does not cover `/go`'s own dispatch mechanics (see `worktrail-go`'s SKILL.md Phase 7 for how `tier_for()`/`select_cell()` resolve it at runtime).
- allowed-tools
- Read, Edit, Write, Bash
02 资源文件 2
- 参考文档references/gotchas.md10.9 KB
- 参考文档references/how-to.md11.3 KB
03 SKILL.md 正文
Routing Configuration
Overview
Worktrail spawns headless agent workers (implement/fix/cleanup/review/...) through one
resolved routing table: targets (which harness/pool each named target uses) crossed with
tiers (which model/effort each target runs at, per tier row), plus roles/purposes that
pick a tier for a given task. This skill is the operator's cookbook for editing that table —
adding/removing harnesses and models, pinning the reviewer, adding tiers — and the gotchas that
bite when two settings interact non-obviously.
File location: ~/.worktrail/routing.yaml (machine-wide, WORKTRAIL_ROUTING_FILE env var
overrides the path) is read whenever a repo's own policy has no routing: block. A repo-local
routing: block in that repo's .worktrail/policy.yaml replaces the machine-wide file
entirely for that repo — it is not merged key-by-key. A non-empty repo-local block means the
machine-wide file is never read for that repo at all.
Where the actual resolution logic lives (read only if you need to verify behavior, not to
edit routing): src/worktrail/router/policy.py (resolve_routing, validation/legacy-key
rejection), src/worktrail/runtime/selection.py (select_cell — the fallback walk),
src/worktrail/orchestrator/dispatch.py (tier_for — role → tier resolution). The formal
behavioral contract is openspec/specs/model-tier-routing/spec.md and
openspec/specs/drain-operator-config/spec.md.
Concepts, briefly
| Key | What it is |
|---|---|
targets |
Named launch targets, each {harness: claude|codex|opencode, pool: subscription|free|api, api_opt_in?, auth?}. File order is the fallback order for any tier row that doesn't reorder it via prefer. |
env_profiles |
Named environment sources a target's auth.profile points at: {from: <json file>, keys: [...], expect?: {...}}. Names where values live and which to copy — never stores a value. See "point a harness at a custom endpoint" in references/how-to.md. |
tiers |
{tier_name: {target_name: {model, effort?}}}. A target with no cell in a row cannot serve that tier — the walk skips straight past it. |
roles |
Per-role override (review/resolve/ci-fix/assembly-resolve/implement/fix/cleanup): {tier, prefer?, independent?}. |
purposes |
{purpose_value: tier_name} — routes implement/fix/cleanup tasks by their purpose frontmatter instead of complexity. |
default_tier |
The tier used when nothing more specific matches. |
drain |
Drain-loop-only settings: max_workers (concurrent drain-worker slots) and exclude_repos (repo directory names never drained unattended, as discover_repo_names() reports them — e.g. worktrail, not /home/you/projects/worktrail or owner/worktrail). exclude_repos is machine-wide only — a repo-local routing: block declaring it is ignored with a warning — and it reaches the drain's repo sweeps and codex sandbox roots, both pre-passes, the ready-brief count, and automatic brief selection (skip reason repo-excluded); --go-repo/--auto-repo beat it, and an entry matching no repo is inert and reported. No agent/fallback_agents keys — those are retired, rejected loudly with a migrate hint. |
Full mechanics (precedence order, prefer vs independent, purpose vs complexity) are in
worktrail-go's SKILL.md Phase 7 — this skill won't restate them, only the parts you need to
make a specific edit safely.
How-tos
See references/how-to.md for the specific recipes:
- Add a new harness/adapter (target)
- Disable a harness/adapter without deleting its config
- Add a new model to an existing harness (including adding e.g. a DeepSeek model to
opencode) - Point a harness at a custom Anthropic-compatible endpoint with an env profile
- Add or remove a tier
- Route a purpose to a tier
- Pin, change, or unpin the code reviewer
- Change
default_tier - Validate a change before trusting it
Gotchas
See references/gotchas.md for the non-obvious interactions this table produces, especially:
worktrail-routing --checkis a spawn readiness probe, not a schema linter: after the schema/legacy-key pass it builds each cell's command and child environment from the resolved table in the checking shell, so a cell whose auth lane cannot resolve there (e.g. a claudeapicell whoseauth.envvariable isn't exported in that shell) reportsFAILand exits non-zero on an otherwise valid YAML file. A drain now runs the same probe before spawning and refuses to start (exit 2, naming the cell and the routing file) instead of routing around the cell — only a capacity-gated cell (model_unavailablein~/.worktrail/agent-capacity.json) is still walked past. Fix the config or export the variable in the environment that spawns; this is not a condition to wait out.independent: truesilently overridespreferwhen the preferred target shares a harness with whichever harness implemented the task — this is the #1 cause of "I only configured Claude, why did Codex just get spawned."preferonly reorders a tier row; the entire row (in target file order) is the fallback chain — there is no separate fallback list to also check.- Legacy top-level keys (
routing.agents,routing.fallback,routing.purpose_tiers,drain.agent,drain.fallback_agents) are rejected outright, not silently ignored — a ruleset written against an older Worktrail version needsworktrail-routing --migrate. api-pool targets (openrouter/api) are dropped from selection unless the target setsapi_opt_in: true— this is deliberate, not a bug, to keep subscription-first spend honest.- Effort vocabulary differs per harness:
claude/codextakelow/medium/high(codexalso acceptsminimal);opencodehas none — itseffortfield is ignored and model selection is the only lever. - A cell can be stuck
unavailablein~/.worktrail/agent-capacity.jsonafter a stale billing gate outlives itsretry_after— check that file before assuming a routing-table edit didn't take effect. - A worker never sees your user-level
~/.claude/settings.json: every claude spawn carries--setting-sources project,local, which excludes it. That is deliberate (a user-level Stop hook corrupts a worker's report-back JSON), but it also drops that file'senvblock — so a provider configured only there reaches no worker, and the spawn makes zero API calls while exiting 0. Reach for anenv_profilesentry instead of editing--setting-sources.
Verify a change took effect
Any already-running drain loop or long-lived orchestrator process loaded routing.yaml
into memory at startup — it will not see an edit until restarted. A one-off /go invocation
picks up the current file on its next run with no restart needed.
worktrail-routing --check # schema + legacy keys + spawn readiness of every cell
worktrail-policy --repo <repo> --resolve-routing "x:x" --json # prints the fully resolved table
04 同仓库更多 Skills
worktrail-sdd-workflow
Internal SDD workflow executor invoked by /go only. Do not call directly. Executes classified routes A–J: feature planning, implementation (parallel orchestration, PR generation), defect repair, refactoring, spec changes, investigation, and workflow evolution.
worktrail-repo-init
Bootstrap a new repo, or migrate an existing single-branch repo, onto the workspace's repo-standards doctrine (~/rules/CLAUDE.repo.md): the AGENTS.md-is-truth/CLAUDE.md-imports-it split, a dev/prd, dev/stg/prd, or main-only (trunk) branch model with matching GitHub rulesets, an OpenSpec scaffold, an auto-merge workflow, and a seeded .worktrail/policy.yaml. Trigger phrases: "onboard this repo", "apply repo standards", "initialize repo standards", "set up this repo like the rest of the fleet", "bring this repo into line with the repo standards doctrine".
worktrail-help
Show the Worktrail front-door commands and accepted positional arguments. Use when the user asks how to invoke worktrail-go, wants the available handoff, spec, pr, repo, or route forms, invokes worktrail-go with help or with a bare noun, or asks how to answer a filed product decision (worktrail-decision).
worktrail-handoff
Capture a discovered problem, gap, tech debt, or deferred work into a local work queue so a future agent session can pick it up cold. Use mid-session whenever you set work aside instead of doing it now — a fix you judge out of scope for this PR, work that belongs in a follow-up or a separate/later PR, an item you're deferring, or something worth fixing you won't tackle now — so the outstanding item isn't lost without derailing current work; can be called multiple times per session. Trigger phrases: "defer this", "item deferred", "out of scope for this PR", "follow-up work", "leave for another PR", "capture for later", "outstanding item". This skill captures only. Picking a brief back up is the front door's job: worktrail-go <brief-id>.
worktrail-go
Use when the user invokes worktrail-go, asks to pick up queued work, resume active specs, implement or fix a spec, route engineering work, or orient across repositories. Renders the orientation dashboard, classifies free-text requests, claims/resumes handoff briefs, and dispatches SDD work without requiring the user to know sdd-workflow. Grammar: worktrail-go [REPO] <noun> <verb>, nouns handoff / spec / pr / decision. Triggers: worktrail-go, worktrail-go help, worktrail-go spec fix, worktrail-go spec implement, worktrail-go spec route F, worktrail-go handoff new, worktrail-go handoff auto, worktrail-go decision answer, worktrail-go BRIEF-ID, bare worktrail-go, multi-repo orientation.
openspec-update-change
Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.