kimi_subagent_router

---
name: subagent-model-routing
description: Default dispatch posture and model/thinking-tier routing for subagent dispatches. The main agent is an orchestrator — delegate by default, self-serve only trivial glue, and resolve model aliases with route_subagent_model (fast path for k3-planner).
---

# Subagent model routing

When this plugin is enabled, the main agent is an **orchestrator and executor, not the thinker**. The default reaction to any incoming task is "which subagent should handle this?" — never "can I do it myself?". Delegation is the default; self-service is the exception, allowed only for the trivial whitelist below. This keeps the main context lean and spends strong-model tokens only where reasoning actually happens.

## 0. Trivial whitelist — the only self-service cases

Handle a task yourself ONLY when ALL of these hold:

- It is fully specified with no design judgment involved (e.g. `git init`, delete one exact line as literally requested, fix a single obvious typo);
- It touches at most one file and needs at most 1–2 tool calls;
- Or it is a pure lookup answerable with a single read/command (e.g. "what does flag X do", "show the latest commit").

Everything else — exploration, implementation, verification, documentation, and any decision involving trade-offs — gets dispatched. There is deliberately NO "handle it yourself" catch-all row: when in doubt, dispatch.

A second efficiency rule: subagents also absorb bulk reading and searching, so prefer dispatching an explore agent over reading large files into the main context yourself.

User override: when the user explicitly tells you to do something directly yourself, comply — a direct user instruction takes precedence over this skill.

## 1. Plan first, then dispatch

Unless the task is on the trivial whitelist in section 0, do **not** start executing directly. First dispatch `k3-planner` (K3-256k, max) to plan, then execute the plan subtask by subtask.

**Planning brief** must demand a plan that contains, for every subtask:

- **goal and scope** — what to achieve, which files/modules it covers;
- **safety boundary** — what it must not touch (unrelated files, public APIs, user data, secrets), and which operations are off-limits (e.g. no deletions, no force-pushes);
- **concrete details** — relevant paths, interfaces, constraints, and existing conventions to follow;
- **verification steps** — the exact commands or checks that prove the subtask is done.

The planning call must also state the recommended tier per subtask (from the table below) and an overall verification process. Keep the returned plan in your context — it is small — and quote each subtask's boundary and verification steps **verbatim** in the executor brief when you dispatch it.

## 2. Pick a type — first matching row wins

| Task | `subagent_type` | Default alias | Effort |
|---|---|---|---|
| Mechanical, pattern-fixed edits: bulk rename, formatting, boilerplate, trivial test stubs | `cheap-coder` | `k2.8-high` | high |
| Read-only lookup: find files, read structure, search symbols, absorb large-file reading | `cheap-explore` | `k2.8-low` | low |
| Local change scoped to a single file | `k2.8-medium` | `k2.8-high` | high |
| Simple feature, routine tests, debugging where the symptom is already known | `k2.8-debug` | `k2.8-max` | max |
| Complex design, architecture, cross-module refactor, non-obvious bug | `k3-planner` | `k3-256k-max` | max |
| Hardest task **and** the subtask needs more than 256k of context (huge repo sweep, long logs, big files) | `k3-max` | `k3-max` (kimi-code/k3, 1M) | max |
| Documentation: README, API docs, usage guides, comment cleanup | `doc-writer` | `alibaba-cn/qwen3.8-flash` | xhigh (third-party tier) |

If nothing matches and the task is not on the trivial whitelist, escalate upward (usually `k2.8-debug`; design-heavy → `k3-planner`) — still do not self-execute.

Harness fallback: if the `Agent` tool rejects a `subagent_type` as unknown (some CLI versions refuse dotted names like `k2.8-debug`, see README known-limitation 4), escalate to `k3-planner` instead of self-executing.

## 3. Tie-breakers

1. **Decide fast, explore elsewhere.** Picking a tier is one pass over the table. Do not read code deeply or reason at length in your own context first — that is the subagent's job, and `cheap-explore` exists so the searching happens off your context.
2. **K3-256k by default.** `k3-planner` and `k3-max` both think at `max`; they differ only in window (256k vs 1M) and `k3-max` costs roughly double. Upgrade only when *both* conditions hold: the task is the hardest kind **and** you expect >256k of context. Unsure means `k3-planner`.
3. **Debugging splits in two.** Known symptom, bounded scope → `k2.8-debug`. Strange behavior, unknown root cause, deep cross-module interaction → `k3-planner`.
4. **Type names are not tier names.** `k2.8-debug` is K2.8 at `max` (simple features, routine tests, routine debugging); `k2.8-medium` is the same model at `high`.
5. **Cheap first.** When a task could plausibly be done by a cheaper tier and a failure is cheap to detect, prefer the cheaper tier and verify the result; escalate only on failure. Reserve `k3-planner` for work whose failure mode is expensive (wrong design, subtle bug).

## 4. Write the brief to fit the tier

A subagent sees only your `prompt`; none of this conversation carries over. Match the brief to how each tier actually works:

| Tier | Strong at | Brief it like this |
|---|---|---|
| `k2.8-low` | Fast literal lookups | One concrete question, exact scope, named output shape, a tool-call budget. No open-ended judgment and no multi-part asks. |
| `k2.8-high` | Repetitive edits, one-file changes | The exact file list, the exact transformation, and an explicit "change nothing outside this" boundary. |
| `k2.8-max` | Solving a problem you already scoped | Symptom + evidence (error text, failing test, repro command) + acceptance criteria. Ask for the root cause and the verification that was run. |
| `k3-planner` | Design, cross-module reasoning, critical code | Goal, hard constraints, non-goals, and *what decision must be made*. Demand one committed recommendation plus rejected alternatives in one line each — not a menu. |
| `k3-max` | All of the above across a wide corpus | Same as `k3-planner`, plus where to start reading (paths, line ranges) and what "covered" means, so it reads the real surface instead of guessing at it. |
| `doc-writer` | Prose, structure, tone | Target path, audience, the repo's existing doc language and formatting to mirror, and which source files are the ground truth. |

Both K3 agents and `doc-writer` have **no shell**: never ask them to run tests or builds. Ask instead for the exact commands the caller should run afterwards.

Every brief must also carry: the working directory or concrete paths, what you already established (so it does not redo the work), and the deliverable format.

## 5. Dispatch, in this order

1. For **`k3-planner`** — the default thinking layer — use the fast path: dispatch directly with `Agent(subagent_type="k3-planner", model="k3-256k-max", description=..., prompt=...)`. Skip `route_subagent_model`. Only resolve the live alias for `k3-planner` when the user has said they edited the mapping, or a dispatch failed because the alias is unknown.
2. For **all other types**, call `route_subagent_model` with the row's `subagent_type`; it returns the live `model` alias and `effort`. Then call `Agent` with **both** `subagent_type` and `model` (the alias from the routing tool — it must be a pool alias), plus `description` (3-5 words) and `prompt` (the brief). If the routing tool returned `model: null`, omit `model` so `[secondary_model].default_model` takes over.
3. There is no other way to set the thinking tier: the `Agent` tool has **no** `effort` parameter and the tier comes only from the alias's `default_effort`. If the resolved tier clearly does not fit the task, tell the user to fix `subagent-models.json`; do not switch aliases on your own.
4. Batch independent same-tier dispatches with `AgentSwarm` instead of serializing them. If `AgentSwarm` is unavailable, dispatch serially.

## Constraints

- No nested delegation: these agents ship with `Agent`/`AgentSwarm` disabled, so the chain stops at depth 1.
- `route_subagent_model` reporting an unknown type → call `list_subagent_routes` for the live names; the user may have added or renamed entries.
- `doc-writer` points at a third-party model that must be registered in `config.toml`. If routing to it fails, report that to the user instead of silently substituting another tier.