feat: add model routing strategy to Code Cannon task execution

[sebastientaggart]

Summary

Implement a tiered model routing layer in Code Cannon that assigns the appropriate Claude model to each task type based on complexity, rather than defaulting all execution to Opus.

Background

Current Code Cannon sessions run virtually all task execution on claude-opus-4-7, resulting in high token cost per session. Analysis of usage data shows significant opportunity to route lower-complexity tasks to Sonnet or Haiku without sacrificing output quality.

Goals

• Reduce effective token spend per Code Cannon session by 30–50%
• Maintain Opus for tasks requiring deep reasoning or architectural judgment
• Make routing rules transparent and overridable per-ticket

Proposed Approach

Model Tiers

Tier	Model	Use Cases
Heavy	claude-opus-4-7	Architecture decisions, complex debugging, design-heavy passes, ambiguous specs
Standard	claude-sonnet-4-6	Refactoring, test writing, most feature implementation
Light	claude-haiku-4-5	Scaffolding, boilerplate generation, config file stubs, repetitive file creation

Routing Mechanism

• Add a model field to the ticket schema (optional, defaults to standard)
• Define a routing config in AGENTS.md or a dedicated model-routing.yml that maps task tags or phase types to tiers
• Allow per-ticket override via explicit model: heavy|standard|light declaration
• Log model used per ticket in session summary for tuning feedback

Acceptance Criteria

• Ticket schema supports optional model field
• Default routing applies Sonnet when no model is specified
• Opus is explicitly required for designated task types
• Routing config is documented and editable without code changes
• Session output includes model-per-ticket summary for cost visibility

Notes

• Preserve cache efficiency: stable system prompts and CLAUDE.md content should remain at context top regardless of model tier
• Revisit tier assignments after first 3–5 sessions with real data

[sebastientaggart]

Closing — out of scope for Code Cannon

Thanks for the submission. After thinking it through we're not going to act on this, and the reasoning is worth capturing for future similar suggestions.

Architectural mismatch. Code Cannon is a set of markdown skill files that an interactive agent reads and follows. It has no runtime — there's no orchestrator that could "route" a ticket to a specific model. The model running is determined by the harness (Claude Code, Cursor, Codex, Gemini CLI, etc.) based on the operator's configuration. A "ticket schema with a model field" or a "routing config" would land in a system that has nowhere to read them.

Separation of concerns. Code Cannon skills describe what the agent should do (domain logic). The harness decides how it runs (which model, which permissions, which adapter). Mixing model-selection guidance into skill prompts bleeds infrastructure decisions into the domain layer and ages badly as model names change.

Where this belongs instead. Model preferences belong in operator-level configuration:

• Harness defaults (Claude Code settings, equivalent for other harnesses).
• Project-level CLAUDE.md / AGENTS.md / equivalent.
• Sub-agent overrides at the harness level.

That way one operator decision applies across every Code Cannon project they touch, and it can reflect project-specific judgment (e.g. a security-sensitive review might warrant the heavier tier; a docs repo might not).

Cost / efficiency context. The original proposal cited 30–50% token cost reduction. For Claude Max subscribers (and similar flat-rate plans on other providers) that math doesn't translate to dollars. For per-token plans it might, but the right lever there is also harness configuration, not Code Cannon's skill content.

No code changes resulting from this ticket. If a future submission has a specific concrete pain point that does require Code Cannon participation (e.g. a sub-agent the skills spawn that produces poor output on the harness's default model and the harness can't be configured), we can revisit then with the actual evidence in hand.

[sebastientaggart]

Revisited — conclusion upheld, reasoning updated

Re-examined this after a fresh look at what the supported backends can now do. The decision to decline stands, but the first argument in the close above is no longer true and should not be reused.

What changed

The close argued that Code Cannon has no runtime, so a model field would land in a system with nowhere to read it. That was accurate when written. It isn't now — every supported backend has since shipped project-scoped, file-defined subagents with a model field that defaults to inheriting the parent session:

Backend	Location	Format	model
Claude Code	.claude/agents/*.md	Markdown + YAML frontmatter	aliases, full IDs, or inherit
Gemini CLI	.gemini/agents/*.md	Markdown + YAML frontmatter	model IDs or inherit
Codex CLI	.codex/agents/*.toml	TOML	model ID, inherits parent when omitted
Cursor	.cursor/agents/*.md	Markdown + YAML frontmatter	inherit or model IDs

A reader now exists, and it is the harness. Code Cannon is a project-level file generator, so emitting agent definitions is the same shape of work it already does for skills. The mechanism objection is dead. (Table recorded as a snapshot for the audit trail — see #217 on why it should not be encoded anywhere.)

Why the decision still stands

The second argument in the close — that model preferences belong in operator-level configuration — is sufficient on its own, and is the one to cite going forward.

Scope. Model and token policy is per-operator and per-plan. A flat-rate subscription, a per-token API key, and a remote or hosted harness each imply completely different answers, and none of them is a property of the repository. .codecannon.yaml is per-project and committed. A tier-to-model map there is the wrong scope regardless of how well the mechanism works.

Territory. Generating agent definitions means writing hash-marked, never-edit files into .claude/agents/ and its equivalents. That directory is the developer's own tooling layer, which they very likely already use. It is a meaningfully more invasive place to write than .claude/commands/, where the generated files are the product they installed.

Asymmetric decay. This is the argument the churn actually supports. Guidance that becomes redundant costs nothing. Generated configuration that becomes wrong silently fights a harness that started routing better on its own — no test fails, nothing errors, the behaviour is just quietly worse than the default would have been. Given that this ticket's original premise was overtaken within months, the correct bet is on the cheap failure mode.

The cost note in the original close also holds and is worth restating: on a flat-rate plan the token argument is close to worthless. What a subagent actually buys is isolated context and reduced review burden. Model tier is a distant second, and a feature sold on cost would be judged on a benefit it does not deliver here.

What the research did produce

Two things fell out of it, both filed:

• Stop committing capability claims about specific agent backends; phrase skills conditionally #217 — the fragile thing in the repo was not a missing feature but the capability claims already committed. docs/adapters.md and three adapter notes: blocks assert that Cursor, Codex CLI, and Gemini CLI cannot spawn subagents; all three went stale without anything here changing. The /review skill's conditional phrasing never did. Delete the enumerations, keep the conditionals.
• /delegate should check delegation candidacy before generating a prompt #218 — the delegation judgement is the durable part and is worth keeping: review burden (delegate only where wrong is verifiable in seconds, never invariant-carrying code) and briefing cost (delegation pays only when the spec is cheap relative to the work). Stated in /delegate, in words, naming no model or vendor.

Revisit trigger

Unchanged from the original close, and still unmet: a subagent Code Cannon itself spawns — realistically the reviewer — produces poor output on the harness default model, and the operator cannot fix it at the harness level. That is a concrete pain point requiring Code Cannon's participation. Absent it, this stays closed.