Routing Plans

Routing Plans

Rewrite an existing implementation plan into a cost-aware, model-routed plan. Inspect both the plan and the current codebase, improve the plan's task boundaries and ordering where useful, assign every routed task a primary and fallback model justified by current LLM Stats evidence, and overwrite the original plan file in place.

This skill is advisory only. It must not invoke models, start agents or workers, execute the plan, edit project source code, or manage terminals. Its only write target is the plan file itself.

Inputs and preconditions

Before starting, confirm you have:

1. The path of the plan file to rewrite. If the user did not name one and more than one plausible plan file exists, ask which one - do not guess.
2. Read access to the project or repository the plan targets.
3. Python 3.10+ available to run scripts/llm_stats.py.
4. An LLM Stats API key in the LLM_STATS_API_KEY environment variable.

Credential rules (hard): never embed the key in the plan, the command line, cache files, logs, examples, or any output. Never ask the user to paste the key into the plan or the conversation; if it is missing, stop before rewriting and tell them to set LLM_STATS_API_KEY in their environment. If a key was previously pasted into the conversation, do not copy it anywhere.

Workflow

1. Establish scope

Resolve the exact plan path and the repository root. Read the complete plan, plus repository instruction files (CLAUDE.md, AGENTS.md, CONTRIBUTING, etc.) that constrain how work is done. Note the plan's file format (markdown, checklist, YAML, tracker convention) - the rewrite must round-trip it.

2. Inspect the codebase (read-only)

Look at repository structure, manifests and lockfiles, languages and frameworks, test layout, CI configuration, existing ownership boundaries, and every file the plan names. Read enough implementation context to judge whether the plan's tasks, dependencies, and file boundaries are realistic. Do not modify anything in this phase.

3. Normalize the plan

First build an internal requirement ledger: every goal, constraint, deliverable, and explicit non-goal stated in the plan. This ledger is the contract for the rewrite - nothing in it may be dropped or silently weakened.

Then reshape tasks where it genuinely helps:

• Split tasks that mix unrelated expertise (e.g. "build the API and style the settings page") or that cannot be reviewed independently.
• Merge tiny tasks whose separation adds routing overhead without improving reviewability.
• Reorder to respect dependencies and open up safe parallel groups.
• Add missing verification or integration tasks when the plan ships changes it never checks.
• Retain intentional human approval gates exactly where the plan put them.

4. Profile each task

Assign each task one primary capability profile (secondary profiles allowed):

For each task also estimate: difficulty and risk; required context window; input/output token shape; modality and tool-use needs; whether an open-weight model is acceptable or required; latency sensitivity; and expected cost tier. The full profile-to-benchmark-category mapping and the routing metadata format live in references/routing-contract.md - read it before routing.

5. Fetch LLM Stats evidence

Run the helper to pull current, comparable evidence:

python scripts/llm_stats.py snapshot --categories coding,agentic,reasoning,math --out routing-evidence.json

(Write the output file somewhere temporary, not into the repository.)

The helper queries the documented LLM Stats API (api.llm-stats.com) and emits deterministic JSON containing models with stable identifiers, provider and organization, open-weight/license metadata, context and inference metadata, provider pricing, benchmark definitions and categories, benchmark scores, TrueSkill category rankings with conservative ratings, and the timestamp of every piece of evidence. It handles pagination, bounded timeouts, HTTP 429 Retry-After, and a credential-free local cache. Stale cache data is used only when a live request fails and is labeled "stale": true in the output - carry that label into the plan.

The script never chooses the task/model mapping and never edits the plan. That judgment is yours, in the next step.

6. Build a quality/cost frontier per task

For each task profile:

1. Select the relevant benchmark categories (see the contract reference).
2. Exclude models that fail hard constraints: context window too small, missing modality, no tool support where the task needs tools, license incompatible with the project's requirements.
3. Rank surviving models by evidence-backed capability for the profile, weighting confidence and benchmark coverage.
4. Compute expected cost from provider pricing and the task's estimated token shape.
5. Choose the least expensive model that clears the task's required quality and confidence threshold. Do not pick the cheapest model when it is materially underqualified; do not pick the leaderboard leader when a substantially cheaper model is sufficiently capable.

Any model present in LLM Stats may be recommended, from any vendor, whether or not it is configured in the user's environment. Never route from vendor familiarity or memory - only from the fetched evidence plus repository context. High-risk or hard-to-review tasks justify a stronger model; routine mechanical tasks almost never do.

7. Rewrite the plan

The rewritten plan starts with a routing summary: data source, evidence retrieval timestamp and freshness (live vs. stale cache), global assumptions, any recommended models that would need configuration before execution, and a budget and ETA ledger - projected total token spend (input/output tokens and dollars, computed from the per-task estimates and LLM Stats pricing) plus a running-totals table the executing agent must update as tasks complete.

Every executable task carries the routing metadata block defined in references/routing-contract.md: goal and deliverable, dependencies, file/ownership boundary when discoverable, acceptance checks, primary model (LLM Stats identifier), fallback model, capability profile and cost tier, a concise routing rationale, evidence summary with timestamp, parallel group or sequential requirement, and the escalation condition for switching to the fallback or a stronger model.

Each task also carries a budget and ETA block:

• estimated input and output tokens, and the resulting dollar estimate at the primary model's current per-million-token pricing (show the arithmetic inputs, not just the total);
• fields for actual tokens and dollars, left blank for the executing agent to fill in when the task finishes;
• an ETA estimate (wall-clock duration and projected completion order), with an explicit instruction that the executor must re-forecast the remaining tasks' ETAs and the plan-level totals after every task completes or its scope changes - ETAs are living values, not one-time guesses.

The skill itself only writes the initial estimates; keeping actuals and ETAs current is an obligation the plan imposes on whoever executes it.

Preserve the plan's original format and any useful project-specific conventions (tracker syntax, numbering, checklists).

8. Validate, then overwrite atomically

Before writing anything:

• Recheck the rewritten plan against the requirement ledger - every entry accounted for, none weakened.
• Verify every executable task has complete routing metadata.
• Check dependencies and parallel groups are internally consistent (no cycles, no parallel group containing a dependency edge).
• Confirm you performed no execution or worker-spawning action.
• Confirm every model recommendation cites evidence or is explicitly labeled uncertain.

Then write a temporary file beside the original and atomically replace the original only after validation succeeds. Do not produce a second routed-plan file. If validation or replacement fails, leave the original untouched and report the problem.

Failure behavior

Non-goals

This skill does not call provider APIs to execute tasks, spawn or delegate to workers, configure providers or purchase access, guarantee a recommended model is available in the user's agent, keep a hardcoded list of favored vendors or models, manage terminals, or rewrite application source code.