@@ -0,0 +1 @@
+2
@@ -0,0 +1,9 @@
+---
+name: "storyteller"
+description: "Storyteller"
+tools:
+  - "read-only"
+  - "plan"
+---
+
+You are a Storyteller. Create imaginative and engaging stories for the user.
@@ -0,0 +1,207 @@
+# Multi-Model Routing, Refinement & Panel Deliberation — Design
+
+**Status:** Design for a future release, scope confirmed (build all three tracks
+plus a combined `auto` mode). No implementation code written yet.
+**Date:** 2026-07-05
+
+## 1. The ask
+
+Route different parts of an agent session to different models based on which
+model is good at that kind of work, for two payoffs at once: lower cost and
+higher per-task quality. Two products were named as inspiration —
+OpenRouter's "Fusion" and Sakana AI's multi-model work — plus the
+cost-focused academic pattern (RouteLLM/FrugalGPT). Decision: build all
+three, composed into one adaptive `auto` mode rather than three disconnected
+toggles.
+
+## 2. What the named prior art actually does
+
+### OpenRouter Fusion — deliberation, not routing
+`openrouter/fusion` sends one prompt to a **panel** of models in parallel,
+then a **judge** model reads every panel response, identifies consensus,
+contradictions, and blind spots, and produces one synthesized answer.
+OpenRouter's own docs scope it to "scenarios where accuracy and thoroughness
+are critical and the cost of being wrong outweighs the higher latency and
+cost," and call it "overkill for simple, tactical prompts." Billing is the
+**sum** of every panel completion plus the judge — strictly more expensive
+than one model call. Quality-maximizing, not cost-saving.
+
+### Sakana AI — Multi-LLM AB-MCTS / "Fugu"
+Treats several frontier models as a collaborative pool and runs Monte Carlo
+Tree Search with adaptive branching: at each node, go "wider" (try a
+different model for a fresh candidate) or "deeper" (refine the current
+candidate using external feedback, e.g. execute code and check the result),
+balanced via Thompson sampling. Explicitly an inference-time-scaling
+technique — spends more compute per query for a better answer on hard,
+scorable benchmarks (SWE-bench-class). Productized as "Sakana Fugu," a
+single endpoint that conducts/routes/verifies/synthesizes internally.
+[reported per sakana.ai and third-party coverage, not independently
+re-verified against a primary paper]
+
+Full MCTS assumes many rollouts scored against a numeric reward — that setup
+fits competitive-programming/math-style tasks with a clean pass/fail signal.
+Most day-to-day dev tasks either have a *weaker* verifiable signal (tests,
+build, lint — binary-ish, not a smooth reward) or *no* verifiable signal at
+all (design judgment calls). The design below adapts the wider/deeper
+**idea** without building literal MCTS.
+
+### RouteLLM / FrugalGPT — the actual cost-saving pattern
+RouteLLM trains a classifier on preference data to predict whether a "weak"
+model matches a "strong" model on a given query and routes accordingly.
+FrugalGPT cascades: cheap model first, a judge/verifier checks the answer,
+escalate to a stronger model only on failure. Both are reported to cut cost
+40–85% while retaining roughly 95% of frontier-model quality.
+
+Both of Sakana/OpenRouter's patterns spend *more* for a *better* answer;
+RouteLLM/FrugalGPT spend *less* by not over-using frontier models. They are
+opposite levers — the design below keeps them as separate mechanisms and
+lets a third policy (`auto`) decide when to use which, rather than merging
+them into one setting.
+
+## 3. Zero's existing substrate (grounds every "reuse" claim below)
+
+| Piece | File | Relevance |
+|---|---|---|
+| Per-specialist model override, wired end-to-end | `internal/specialist/manifest.go:30` (`Metadata.Model`), applied in `internal/specialist/exec.go:693-705` (`appendModelArgs`) | Direct substrate for **Route**. Empty inherits parent; set value is passed to the spawned subprocess today. |
+| Per-swarm-member model override | `internal/swarm/definition.go:33`, resolved in `internal/swarm/team.go:209-214` | Same override pattern, swarm side. |
+| Coarse manual mode presets | `internal/modelregistry/modes.go:30-63` | `smart`/`deep`/`fast`/`large`/`precise`. **`smart` stays as-is — do not repurpose or rename.** |
+| Tiered, cache-aware cost computation | `internal/modelregistry/cost.go` | Feeds `zero usage`; reused as-is for Route's savings telemetry. |
+| Live pricing/context-limit catalog | `internal/modelregistry/modelsdev.go` | Keeps routing cost data fresh without hardcoding. |
+| Model-family prompt tuning | `internal/agent/system_prompt_models.go` | Precedent for "different models get different treatment," at the prompt layer. |
+| **Post-edit verify + corrective feedback loop, already shipped** | `internal/agent/selfcorrect.go` (`SelfCorrector.AfterEdit`, `Outcome` enum: `Disabled`/`Passed`/`Correcting`/`Reported`/`Aborted`) | This **is** the "deeper" half of Refine. Runs LSP diagnostics + `verify.Run`, synthesizes feedback, retries same-model, bounded at `defaultSelfCorrectMaxAttempts = 3`. |
+| **The exact gap**, precisely located | `internal/agent/loop.go:602`: `if feedback, _ := options.SelfCorrect.AfterEdit(ctx, ...); feedback != "" { … }` | The `Outcome` return value is discarded. `OutcomeAborted` (still failing after budget) currently just... ends up wherever the run's normal stop condition takes it. No escalation policy reads this signal today. **This is the hook point for "wider."** |
+| No fan-one-task-to-N-models primitive | Checked `internal/swarm/coordinator.go` | Confirmed absent. Swarm decomposes into distinct per-member sub-tasks; it does not broadcast one identical task to N members. **Panel needs new dispatch code**, though it can reuse `exec.go`'s subprocess-launch-with-model-override underneath. |
+
+## 4. Design: three mechanisms plus one policy that composes them
+
+### Naming
+`modelregistry.Mode`'s existing `"smart"` preset (fixed `claude-sonnet-4.5`,
+balanced daily driver) is unchanged — renaming or repurposing it would
+silently change behavior for anyone currently running `/mode smart`. The new
+adaptive/combined mode is named **`auto`**: it more precisely says "the
+system is choosing for you" than "smart" would, and it doesn't collide.
+
+### 4.1 Route (cost-saving — RouteLLM/FrugalGPT pattern)
+
+- New `modelRouting.roles` config block (user or project config): role name
+  → model id/alias, e.g. `{"roles": {"explorer": "haiku-4.5", "code-review":
+  "gpt-5.5", "worker": ""}}` (empty = inherit, matching existing manifest
+  semantics). Resolved through the existing `modelregistry.Resolve` — same
+  resolver every other model input already goes through, so aliases and
+  deprecation fallbacks are handled for free.
+- Ship sensible defaults directly on the three builtins in
+  `internal/specialist/builtin.go`: `explorer` (read-only enumeration) to a
+  small/fast tier, `code-review` to a strong reasoning tier, `worker` stays
+  inherit/balanced. This is close to a one-line-per-specialist change given
+  the field and its wiring already exist.
+- Classification signal: the specialist/role name at the `Task` call site.
+  This is a free, reliable signal — Zero already knows which role is being
+  invoked because the calling model names it explicitly. No text classifier
+  needed, which sidesteps RouteLLM's hardest problem (it has no such label
+  in a raw chat stream; Zero's architecture already segments work by role).
+- Savings telemetry: extend `zero usage` with a comparison line — "routing
+  saved $X vs. running every call on your primary model" — by reusing
+  `internal/usage`'s existing per-model `CostBreakdown` aggregation.
+
+### 4.2 Refine + Escalate (Sakana-inspired "wider vs. deeper," pragmatic)
+
+**Deeper (already shipped, no new work required):** `SelfCorrector.AfterEdit`
+verifies, synthesizes feedback, retries the same model, gives up after 3
+attempts (`OutcomeAborted`).
+
+**Wider (new):**
+1. Stop discarding the `Outcome` at `loop.go:602`; branch on it.
+2. On `OutcomeAborted`, for a **verifiable** task (tests/build/lint exist to
+   check against):
+   - Simplest correct version: retry once more on a stronger single model
+     (classic FrugalGPT-style cascade escalation), carrying the same
+     corrective feedback `SelfCorrector` already synthesized.
+   - Stronger version (follow-up, not required for first ship): fan the
+     still-failing task to a small panel (2 models) and let the *existing
+     verifier* pick whichever candidate actually passes — cheap because the
+     test suite is the judge; no extra judge-model call needed.
+3. For an **unverifiable** task with no tests/build to check against, Refine
+   has nothing to referee an escalation with — hand off to Panel instead
+   (§4.3), don't try to force a verify-loop where none is meaningful.
+
+This keeps "deeper" exactly as it already works and adds "wider" as a
+genuinely new but narrowly-scoped escalation policy sitting on top of an
+existing, tested signal.
+
+### 4.3 Panel (quality-maximizing — OpenRouter Fusion pattern)
+
+- New dispatch primitive: fan one prompt to N diverse models in parallel
+  (reusing `exec.go`'s subprocess-launch-with-model-override underneath),
+  collect N responses, synthesize with a judge call that surfaces consensus,
+  contradictions, and blind spots (mirroring Fusion's actual synthesis
+  shape, not just picking one response).
+- Explicit opt-in only: a `/panel <question>` command, or a `panel: true`
+  flag on a `Task` call. Never automatic or default — it's billed as the sum
+  of every panel completion plus the judge, same cost shape OpenRouter
+  itself documents.
+- Primary use: unverifiable, high-stakes, or ambiguous judgment calls —
+  architecture decisions, "should I use X or Y," irreversible/security-
+  sensitive changes — where being wrong is expensive enough to justify
+  paying for multiple opinions up front.
+
+### 4.4 `auto` mode — the combination
+
+A policy, not a fourth execution mechanism. Sequences the three above:
+
+1. **Route** picks the cheapest-sufficient model for the task's role.
+2. Mutating edits run through **Refine**'s existing verify-loop unchanged.
+3. On `OutcomeAborted`: if verifiable, escalate **wider** (stronger model,
+   or verifier-arbitrated mini-panel). If unverifiable and either
+   low-confidence or explicitly flagged high-stakes, escalate straight to
+   **Panel**.
+4. Otherwise, stay on the cheap path.
+
+Net effect: the cheap model absorbs the routine majority of turns (where
+most token volume actually sits); Panel's multi-model cost is only paid on
+the minority of cases that demonstrably need it. This is the concrete
+mechanism behind "both at once" — cost savings and quality aren't competing
+settings, they're different rungs of one cascade.
+
+## 5. Build sequencing
+
+Route and Panel do not depend on each other and can be built in parallel;
+`auto` depends on all three existing first.
+
+1. **Route** — foundational, lowest risk, mostly config + defaults on
+   already-wired plumbing. Also required as `auto`'s first tier regardless
+   of sequencing.
+2. **Wire the discarded `Outcome`** at `loop.go:602` and define the
+   escalation-policy interface — small, mechanical, unlocks the extension
+   point cleanly before the escalation mechanics themselves exist.
+3. **Refine's "wider" escalation** for verifiable tasks — ship the
+   stronger-single-model fallback first; verifier-arbitrated mini-panel is a
+   follow-up enhancement, not required for first ship.
+4. **Panel** — new fan-out dispatch + judge synthesis, its own opt-in
+   command; independent of step 3, can proceed in parallel.
+5. **`auto` mode** — composes 1+3+4 once all three exist. Pure policy/config,
+   no new execution machinery of its own.
+
+## 6. Risks
+
+- **Silent quality regression on Route.** A cheap model can silently
+  underperform on a harder-than-expected task. Mitigated by Refine's
+  escalate-wider path once §4.2/step 2-3 exist — don't ship Route's defaults
+  as a dead end with no escalation path for long.
+- **Surprise.** A session should not silently feel like multiple different
+  models without the user knowing. Surface "ran on {model}" per specialist
+  call in the TUI (`internal/tui` already renders specialist tool-call
+  dispatch — this is a display change, not new infra).
+- **Provider/quota sprawl.** Routing across more of the 25+ supported
+  providers within one session raises concurrent auth/rate-limit surface.
+  Not a new problem class (credstore already handles multi-provider auth),
+  but exercise it under real routing load before shipping.
+- **Panel cost blowup if scope creeps.** The single biggest risk to the
+  whole feature paying off is letting Panel's per-query cost multiplier leak
+  into default behavior. Keep it opt-in-only, and keep `auto`'s escalation
+  criteria to Panel deliberately narrow (unverifiable + low-confidence, or
+  explicitly flagged high-stakes) — not "whenever unsure."
+- **`OutcomeAborted` today has no escalation consumer.** Until step 2 of the
+  build sequence lands, `SelfCorrector` exhausting its budget is a dead end
+  that surfaces `abortedSelfCorrectNotice` and stops. Refine's value only
+  materializes once wider-escalation is wired — don't consider Refine
+  "shipped" with only the deeper half.