akili-specs 2.10.1 → 2.11.0

package/.claude/commands/akili-constitution.md

@@ -379,12 +379,16 @@ project guides so the project does not depend on the package's `docs/` after ins
 
 1. A one-line statement of the criteria-first philosophy and the guiding principles
    (match the dominant demand; ARCHITECT = BUILDER; **author ≠ auditor**; reserve deep-reasoning for
-   propose/verify; fast & cheap for tasks/archive).
+   propose/specify/verify **and the orchestrating Leader**; fast & cheap for archive/formatting only
+   — **`tasks.md` decomposition is T1, not cheap formatting**).
 2. The six capability tiers (T1 Architect, T2 Coder, T3 Auditor, T4 Context-Ingest, T5 Fast-Cheap,
-   T6 Multimodal) with one-line definitions.
+   T6 Multimodal) with one-line definitions — T1 covers architecture reasoning, **task decomposition**,
+   **and live orchestration judgment** (decomposition in flight, runtime skill selection, FAIL
+   adjudication, pivot).
 3. The phase→tier mapping for the real AKILI phases, with the `/akili-execute` triad split into
-   Leader (T5), Implementer (T2), and Reviewer (T3), and an explicit note that the Reviewer model
-   must differ from the Implementer model. `/akili-test` is likewise split into its Leader (T5,
+   Leader (T1, orchestration judgment — writes no code but selects skills, adjudicates FAILs, and
+   decides pivots), Implementer (T2), and Reviewer (T3), and an explicit note that the Reviewer model
+   must differ from the Implementer model. `/akili-test` is likewise split into its Leader (T1,
    orchestration) and Tester(s) (T2, test authoring), with a note to prefer a Tester model different
    from the Implementer (author ≠ tester).
 4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`, plus
@@ -470,14 +474,14 @@ this step — the guidance-only flow keeps working.
   operating contract before doing anything else.
   ```
 
-  Models come from the registry's Claude Code column as **aliases** (default: leader `haiku`,
-  implementer `sonnet`, reviewer `opus`, tester `sonnet`). Never copy the persona body into the
-  wrapper — `.agents/` stays the single source of truth.
+  Models come from the registry's Claude Code column as **aliases** (default: leader `opus` (T1 —
+  orchestration judgment), implementer `sonnet`, reviewer `opus`, tester `sonnet`). Never copy the
+  persona body into the wrapper — `.agents/` stays the single source of truth.
 
 - **OpenCode:** create the equivalent project agent definitions (`.opencode/agent/akili-*.md` or
   the `agent` block of `opencode.json`, matching the user's OpenCode version) with `model:` set to
-  the registry's OpenCode slugs (default: implementer `opencode-go/glm-5.1`, reviewer
-  `opencode-go/deepseek-v4-pro`, leader `opencode-go/deepseek-v4-flash`).
+  the registry's OpenCode slugs (default: implementer `opencode-go/glm-5.2`, reviewer
+  `opencode-go/deepseek-v4-pro`, leader `opencode-go/kimi-k3` (T1 — orchestration judgment)).
 
 - **Google Antigravity:** no per-agent model binding exists — skip wrapper generation and note in
   the summary that Antigravity stays on guidance-only routing.

package/.claude/commands/akili-execute.md

@@ -65,7 +65,7 @@ The Leader does not write production code itself unless the rework loop is exhau
 
 ### Step 0: Load Context
 
-**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** for you as Leader — the Implementer/Reviewer route through the Step 8E agent wrappers (their own tier models) when present. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"The Leader loop is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+**Model checkpoint:** As Leader you run best on **T1** — orchestration here is judgment, not dispatch: you decompose in flight, **select each Implementer's skills**, adjudicate Reviewer FAILs, and decide pivots. You write no code, but these calls gate the whole run (low volume, high leverage). The Implementer/Reviewer route through the Step 8E agent wrappers (their own tier models — Implementer T2, Reviewer T3) when present. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps T1 to a model different from the current session model, tell the user in one line — e.g. *"The Leader loop is T1 — the registry recommends `/model opus`; you are on sonnet"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
 
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 
@@ -120,6 +120,7 @@ loop:
       HALT, mark task [~], present audit trail (Step 4)
       exit loop
     feedback = Reviewer issues
+    effort = bump one level (medium → high → xhigh)   # a failed fix is usually under-thinking
     attempt += 1
     continue loop
 ```
@@ -139,7 +140,8 @@ Delegate to the Implementer with:
 - the active task ID, title, and scope from `tasks.md`
 - the relevant slices of `requirements.md`, `design.md`, and `trd.md`
 - the project constitution references (`CLAUDE.md`, `AGENTS.md`, `docs/ux-ui/design.md`)
-- the recommended skill list from the task (e.g. `ui-ux-pro-max`, `react-doctor`, `nestjs-expert`), falling back to the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) when the task lists none; if the task involves animation, include `gsap-animation` and its matching reference file
+- the skill set **you select for this task as Leader**. The task's recommended list (e.g. `ui-ux-pro-max`, `react-doctor`, `nestjs-expert`) and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) are your **defaults, not a fixed pass-through**: judge the task's actual nature and augment, narrow, or override them — add a skill the task missed, drop one that does not fit, swap in the better match (e.g. include `gsap-animation` and its matching reference file when the work touches animation even if unlisted). When you deviate from the task's list, record a one-line reason in `execution.md`. Fall back to the Skill Map only when the task lists none and you see no better fit
+- the **effort you select for this task** (the *Effort dial* in `## Model Routing`, orthogonal to the tier): default `medium`, flexed to `low` for trivial/mechanical work, `xhigh` for complex (algorithm, concurrency, security, ambiguity), `max` for correctness-critical. Where the tool exposes a per-spawn effort knob, set it; otherwise steer depth in the brief. Never `max` a cheaper tier — if a task wants `max`, escalate the tier instead
 - any prior Reviewer feedback when this is a rework attempt
 - any Active Lessons from `docs/specs/kaizen-log.md` relevant to the task's domain (pass only the matching rows, never the full log)
 - the verification command to run before reporting completion

package/.claude/commands/akili-specify.md

@@ -61,7 +61,7 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
 
 ### Step 0: Setup
 
-**Model checkpoint:** This phase runs best on **T1 Architect** for requirements/design (re-check at Phase 3: **T5 Fast-Cheap** for the tasks split, **T6 Multimodal** when visual design is in scope). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"Phases 1–2 are T1 — the registry recommends `/model opus`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+**Model checkpoint:** This phase runs best on **T1 Architect** for requirements/design **and for the Phase 3 `tasks.md` decomposition** — breaking the design into executable tasks with correct boundaries and dependencies is reasoning, not cheap formatting; a bad decomposition poisons every downstream Implementer (re-check at Phase 3 only to switch to **T6 Multimodal** when visual design is in scope). If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"Phases 1–3 are T1 — the registry recommends `/model opus`; you are on haiku"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
 
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 

package/.claude/commands/akili-test.md

@@ -11,7 +11,7 @@ Run automated and, when needed, manual tests against a spec path's implementatio
 
 In this command you act as the **Leader** (Orchestrator). You partition testing into per-suite units, delegate each unit to a focused **Tester** subagent, aggregate their structured reports, and assemble the final `test-report.md`. Testing should prove the behavior promised in `requirements.md`, not only increase test count.
 
-> **Recommended model tier:** Leader on T5 Fast-Cheap (orchestration — writes no tests), each Tester on T2 Coder (test authoring + verification). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. Prefer a Tester model that differs from the Implementer that wrote the code (author ≠ tester reduces confirmation bias).
+> **Recommended model tier:** Leader on T1 (orchestration judgment — partitions suites, selects each Tester's skills, adjudicates results; writes no tests), each Tester on T2 Coder (test authoring + verification). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. Prefer a Tester model that differs from the Implementer that wrote the code (author ≠ tester reduces confirmation bias).
 
 ## Usage
 
@@ -77,7 +77,7 @@ The Leader decides the count from the spec's depth and the independence of the s
 
 ### Phase 0: Load Context (Leader)
 
-**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** for you as Leader — Testers route through the `akili-tester` wrapper (T2) when present. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps that tier to a model different from the current session model, tell the user in one line — e.g. *"The Leader loop is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
+**Model checkpoint:** As Leader you run best on **T1** — orchestration here is judgment, not dispatch: you partition suites, **select each Tester's skills**, and adjudicate results. You write no tests, but these calls gate the whole run (low volume, high leverage). Testers route through the `akili-tester` wrapper (T2) when present. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps T1 to a model different from the current session model, tell the user in one line — e.g. *"The Leader loop is T1 — the registry recommends `/model opus`; you are on sonnet"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode) at the first approval pause. Never block on this; continuing on the current model is always allowed.
 
 **Token Optimization (Prompt Caching):** To maximize prompt caching, always read the constitutional baseline documents FIRST and in the exact same order across all sessions before reading task-specific files.
 

package/.claude/templates/leader.md

@@ -4,7 +4,7 @@ You are the specialized **Software Leader** agentic team member in the AKILI-SPE
 
 Your sole responsibility is to coordinate execution of an approved spec by orchestrating two subordinate agents — the **Implementer** and the **Reviewer** — and to maintain a faithful, traceable execution record. You do not write production code yourself, and you do not perform the independent audit yourself; you delegate.
 
-> **Recommended model tier:** T5 Fast-Cheap (orchestration and instruction-following — you write no code). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. Spawn the Implementer and Reviewer on **different models** (author ≠ auditor).
+> **Recommended model tier:** T1 (deep-reasoning orchestration — you write no code, but this is judgment, not dispatch: you decompose in flight, **select each worker's skills**, adjudicate Reviewer FAILs, and decide pivots — the highest-leverage calls in the run). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. Spawn the Implementer and Reviewer on **different models** (author ≠ auditor).
 
 ---
 
@@ -20,8 +20,9 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
    * If a task is `[~]`, resume it using `execution.md` context.
    * If no tasks are eligible, report completion or the blocking condition and stop.
 
-3. **Delegation Discipline (Dynamic Skill Loading):**
-   * Extract any recommended skills listed in the task (e.g., `shadcn-ui`, `nestjs-expert`). If the task lists none, derive them from the project's `## Skill Map` in root `AGENTS.md`/`CLAUDE.md` (stack skills) plus the conditional skills matching the work (UI → `ui-ux-pro-max`, animation → `gsap-animation`).
+3. **Delegation Discipline (Active Skill + Effort Selection):**
+   * **You own the skill decision, not the task file.** Judge the task's actual nature and select the optimal skill set for *this* task. The task's recommended skills (e.g., `shadcn-ui`, `nestjs-expert`) and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`, stack skills) are **defaults you may augment, narrow, or override** — add a skill the task missed, drop one that does not fit, or swap in the better match (UI → `ui-ux-pro-max`, animation → `gsap-animation`, etc.). When you deviate from the task's list, record a one-line reason in `execution.md`. Fall back to the Skill Map only when the task lists none and you see no better fit.
+   * **You also set the effort per task** (the second dimension in `## Model Routing` → *Effort dial* — orthogonal to the tier). Default `medium` for a T2 Implementer, then flex by the task's difficulty: `low` for trivial/mechanical work, `xhigh` for complex (algorithm, concurrency, security, ambiguity), `max` for correctness-critical. Where the tool exposes a per-spawn effort knob, pass it; otherwise instruct the Implementer's depth in-brief ("think carefully — this is a hard task" / "keep it quick, this is mechanical"). Don't `max` a cheaper tier — if a task wants `max`, escalate the tier instead.
    * Spawn the **Implementer** subagent with: the active task scope, the relevant spec sections, the verification command, and the contents of `.agents/implementer.md`.
    * **Crucial:** Explicitly instruct the Implementer: "You MUST use the `skill` tool to load these skills: [skill names] BEFORE you begin writing code."
    * After the Implementer reports completion, extract the git diff and spawn the **Reviewer** subagent with: the diff, the relevant spec sections, and the contents of `.agents/reviewer.md`.
@@ -30,7 +31,7 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 4. **Rework Loop Guardrails (Anti-Looping & Rollback):**
    * Enforce a hard ceiling of **3 rework attempts** per task.
    * **Fail-Fast:** If the Reviewer issues `STATUS: FATAL_FAIL`, immediately abort the loop and trigger the Pivot Protocol to conserve tokens.
-   * On `FAIL`, spawn a fresh Implementer passing *only* the Reviewer's structured feedback, the prior diff context, AND an **Attempt History** summary (e.g., "In attempt 1 you tried X and it failed with Y. Do not repeat approach X.").
+   * On `FAIL`, spawn a fresh Implementer passing *only* the Reviewer's structured feedback, the prior diff context, AND an **Attempt History** summary (e.g., "In attempt 1 you tried X and it failed with Y. Do not repeat approach X."). **Bump the effort one level on the retry** (e.g. `medium` → `high` → `xhigh`) — a fix that failed is usually under-thinking, not missing instructions.
    * On `PASS`, finalize the task.
    * After 3 consecutive `FAIL` results (or a `FATAL_FAIL`), **HALT**. Before marking the task `[~]`, execute an **Automatic Rollback** (`git restore .` and `git clean -fd`) to return the working tree to a clean state. Then record the full audit trail in `execution.md`, and present the blocker to the user for guidance.
 

package/CHANGELOG.md

@@ -10,6 +10,21 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.11.0] - 2026-07-24
+
+### Changed
+
+- **`/akili-specify` → `tasks.md` decomposition promoted T5 → T1.** Task decomposition was mapped to T5 Fast-Cheap ("fast structured partitioning into tickets") — the same category error as the old T5 Leader: it treats *not writing prose* as *not requiring reasoning*. Breaking a design into executable tasks with correct boundaries, dependencies, and scope is where the spec becomes executable; a bad decomposition poisons every downstream Implementer (the master builder's blueprint). It is now **T1**, consistent with `requirements.md`/`design.md` (already T1) — low-volume, high-leverage, deep-reasoner work. Updated `docs/model-routing.md` (phase mapping, guiding principles, "Why these models", effort dial, per-tool apply), `docs/flow.md`, the `/akili-specify` Phase-3 model checkpoint, and the `/akili-constitution` scaffold description. `haiku`/T5 now scopes to `/akili-archive` and pure setup/formatting only.
+- **Registry refreshed against current benchmark data.** T2 Coder (OpenCode) bumped `opencode-go/glm-5.1` → `opencode-go/glm-5.2` (A-tier, 753B, GPQA 91.2) — a second worked example of the *Replacing a model* runbook; T2's cheap fallback set to `opencode-go/deepseek-v4-flash` (A-tier, $0.14/$0.28, SWE-bench 79.0). "Why these models" now cites real numbers (Kimi K3 S-tier but ~33 tok/s — fine for the low-volume T1 Leader/architect, never T2; DeepSeek V4 Pro SWE 80.6 / Terminal-Bench 67.9; Qwen3.7 Max ~46 intelligence, kept as the best-effort T6 open option with external Gemini 3.1 Pro / Claude Sonnet preferred for real vision). Updated `docs/model-routing.md` and the `/akili-constitution` Step 8E OpenCode implementer wrapper default.
+- **OpenCode T1 Architect re-mapped to Kimi K3.** The OpenCode Go column now anchors T1 (Architect + the execute/test Leader) on `opencode-go/kimi-k3`, with the previous `opencode-go/kimi-k2.6` demoted to the T1 fallback — a worked application of the *Replacing a model* runbook (edit the registry row → reconcile the Step 8E OpenCode leader wrapper default → `/akili-audit`). Updated `docs/model-routing.md` (registry table, "Why these models", per-tool apply guidance) and the `/akili-constitution` Step 8E OpenCode wrapper default. Kimi K3 is a concrete slug with no alias — confirm it against your own OpenCode roster.
+- **Leader/orchestrator promoted to the deep-reasoning tier (T1), with runtime skill-selection authority.** Model Routing previously mapped the `/akili-execute` and `/akili-test` **Leader** to **T5 Fast-Cheap** (`haiku`) on the rationale "orchestration / instruction-following — writes no code." That conflated *not producing an artifact* with *not requiring reasoning*: the orchestrator makes the run's highest-leverage calls — how to decompose, which skill each worker loads, whether a Reviewer FAIL means rework or escalation, and when to pivot. These are low-volume, high-leverage decisions (the master builder directing the site), so a frontier model there is cheap insurance. The Leader is now **T1** across `docs/model-routing.md` (tier definition, phase→tier mapping, model-selection rationale, and per-tool apply guidance for Claude Code and OpenCode), the `/akili-execute` and `/akili-test` **model checkpoints** (which now recommend `/model opus` for the Leader session instead of `/model haiku`), and the `.agents/leader.md` persona. `haiku`/T5 stays scoped to the genuinely mechanical steps — the `tasks.md` partition and `/akili-archive` — and the Implementer (T2) / Reviewer (T3) tiers and `author ≠ auditor` rule are unchanged. No new tier was added: T1's definition was broadened to include live orchestration judgment (per the registry's anti-proliferation rule).
+- **Leader skill selection is now active, not pass-through.** The Leader's delegation discipline (`.agents/leader.md` Instruction #3 and `/akili-execute` Spawn-Implementer step) changed from "extract the task's recommended skills, fall back to the `## Skill Map` when none" to **the Leader selecting the optimal skill set for each task at runtime** — treating the task's list and the Skill Map as defaults it may augment, narrow, or override with a one-line reason recorded in `execution.md`. Task-time skill assignment still stands; this adds Leader authority to act on it during execution.
+
+### Added
+
+- **Effort dial — second routing dimension in `docs/model-routing.md`, with Leader authority.** The registry picks the *tier* (which model); effort is the orthogonal, **per-task** dial for how hard that model thinks. New "Effort dial" section documents: the empirically steep intelligence↔cost curve (a representative ladder shows `max` → `medium` loses ~8% intelligence for ~70% cost — so `medium`/`high` is the value sweet spot, `xhigh`/`max` reserved for genuinely hard work); an effort policy by task signal (trivial → `low`, complex → `xhigh`, correctness-critical → `max`); default effort by role; **escalate effort one level on every rework attempt**; the **tier ↔ effort interaction** (don't `max` a cheaper tier — Sonnet 5 at `max` approaches Opus 4.8's price for less intelligence; escalate the tier instead); and Sonnet specifics (respects effort strictly — raise it rather than prompt around shallow reasoning; give `max_tokens` headroom at `xhigh`/`max`). Wired into the Leader's authority: `.agents/leader.md` (Instruction #3 now "Active Skill + Effort Selection" plus effort-bump on rework in the guardrails) and `/akili-execute` (Spawn-Implementer effort selection + effort bump in the rework loop).
+- **Frontier escalation tier (Fable 5 / Mythos 5) in `docs/model-routing.md`.** A new opt-in section documents pinning a frontier model *above* Opus (`claude-fable-5`, or `claude-mythos-5` on Project Glasswing) for the highest-leverage slots — **T1 (Architect + the execute/test Leader) and T3 (Auditor)** — as a ceiling for genuinely hard specs. Explicitly **never a default and never in T2** (~2× Opus pricing, $10/$50 vs $5/$25, only pays where volume is low and the decision gates the run). Records the operational contract: it is a **dated pin with a required reason** (no floating alias, so it re-inherits concrete-slug drift maintenance — watched by `/akili-audit`); **always fall back to `opus`** for its refusal classifier (bio/cyber false-positives on security-adjacent specs), no-ZDR requirement, minutes-long turns, and less-prescriptive prompting; and it enables **cross-family `author ≠ auditor`** (Fable implementer/leader + Kimi/DeepSeek reviewer, or vice-versa) for stronger independent review.
+- **"Replacing a model" developer runbook in `docs/model-routing.md`.** A first-class section that turns the previously-scattered model-swap mechanism into a followable procedure for when newer models ship after a project is scaffolded. Covers the three cases (floating alias → zero edits; concrete slug like OpenCode `opencode-go/*` or a `claude-fable-5` pin → edit; re-mapping a tier → promotion to evaluate), the 3-step procedure (edit the one `## Model Routing` table → reconcile the Step 8E agent wrappers → run `/akili-audit`'s Model Registry Drift check), and the package-default-vs-project-copy distinction (editing the packaged registry only affects new projects; the project's `AGENTS.md`/`CLAUDE.md` copy governs, and `/akili-constitution` Safe Update mode flags drift without overwriting pins).
 ## [2.10.1] - 2026-07-23
 
 ### Changed

package/docs/flow.md

@@ -293,12 +293,11 @@ T4 Context-Ingest, T5 Fast-Cheap, T6 Multimodal** — map to the phases:
 | Phase / Role | Tier |
 |---|---|
 | `/akili-constitution` | T4 + T1 |
-| `/akili-propose`, `/akili-specify` (requirements/design) | T1 |
+| `/akili-propose`, `/akili-specify` (requirements/design/tasks) | T1 |
 | `/akili-quick` | T2 |
-| `/akili-specify` (tasks) | T5 |
 | `/akili-specify` (UX/UI design) | T6 |
-| `/akili-execute` Leader / Implementer / Reviewer | T5 / T2 / T3 |
-| `/akili-test` Leader / Tester(s) | T5 / T2 |
+| `/akili-execute` Leader / Implementer / Reviewer | T1 / T2 / T3 |
+| `/akili-test` Leader / Tester(s) | T1 / T2 |
 | `/akili-validate` | T3 |
 | `/akili-audit` | T4 + T3 |
 | `/akili-archive` | T5 |

package/docs/model-routing.md

@@ -32,11 +32,17 @@ from the need, not the reverse. The registry lists a principal model plus a fall
   is lost between design and code.
 - **author ≠ auditor.** The Reviewer / validator MUST run on a **different model** than the
   Implementer. An independent auditor catches what the author rationalized away.
-- **Reserve deep-reasoning for propose & verify.** The most expensive reasoning models earn their
-  cost on architecture (`/akili-propose`) and final audit (`/akili-validate`, Reviewer), not on
-  bookkeeping.
-- **Fast & cheap for tasks & archive.** Partitioning a spec into tickets and summarizing closed
-  work are format-following jobs — speed and cost dominate; raw intelligence adds little.
+- **Reserve deep-reasoning for propose, specify, verify & orchestrate.** The most expensive reasoning
+  models earn their cost on architecture (`/akili-propose`), the spec artifacts including **task
+  decomposition** (`/akili-specify` → requirements / design / `tasks.md`), final audit
+  (`/akili-validate`, Reviewer), and **live orchestration** (the `/akili-execute` / `/akili-test`
+  Leader — skill selection, FAIL adjudication, pivot) — not on bookkeeping. The Leader and the task
+  decomposer qualify because they *decide* (how to break the work down, who does what), even though
+  they write no production code; both are low-volume, so the deep model there is cheap insurance.
+- **Fast & cheap for formatting & archive.** Summarizing closed work (`/akili-archive`) and pure
+  setup/formatting steps are format-following jobs — speed and cost dominate; raw intelligence adds
+  little. **Note:** partitioning a spec into `tasks.md` is *not* one of these — it is decomposition
+  judgment (T1), not formatting.
 
 ## Capability tiers
 
@@ -45,7 +51,7 @@ tier per phase (which would defeat the abstraction and churn on every model rele
 
 | Tier | Definition |
 |---|---|
-| **T1 Architect** | Deep reasoning for architecture, trade-offs, and intent — "think hard before code." |
+| **T1 Architect** | Deep reasoning for architecture, trade-offs, and intent — "think hard before code." Also covers **live orchestration judgment**: task decomposition in flight, runtime skill selection for each worker, Reviewer-FAIL adjudication, result synthesis, and escalation/pivot calls. |
 | **T2 Coder** | Maximum coding throughput and instruction-following for writing and editing code and tests. |
 | **T3 Auditor** | Independent critical review — conformance, bug-finding, drift; must differ from the author model. |
 | **T4 Context-Ingest** | Large-context absorption of legacy codebases and baseline docs — window size over depth. |
@@ -56,8 +62,14 @@ tier per phase (which would defeat the abstraction and churn on every model rele
 
 The `/akili-execute` triad is split because each role has a different demand — and because
 author ≠ auditor makes the Implementer/Reviewer split a **correctness constraint**, not a
-preference. `/akili-test` is split the same way: a cheap Leader orchestrates while T2 Testers author
-the suites, and a Tester ideally runs on a different model than the Implementer (author ≠ tester).
+preference. The **Leader runs on the deep-reasoning tier (T1), not a cheap one**: it writes no code,
+but it makes the highest-leverage calls in the run — how to decompose, **which skill each Implementer
+loads**, whether a Reviewer FAIL means rework or escalation, and when to pivot. Those are low-volume,
+high-leverage decisions (the master builder directing the site, choosing each worker's tool), so a
+frontier model there is cheap insurance, not waste — a weak orchestrator with strong workers
+poisons the whole run. `/akili-test` is split the same way: a T1 Leader orchestrates and selects
+each Tester's skills while T2 Testers author the suites, and a Tester ideally runs on a different
+model than the Implementer (author ≠ tester).
 
 | Phase / Role | Tier(s) | Why |
 |---|---|---|
@@ -65,12 +77,12 @@ the suites, and a Tester ideally runs on a different model than the Implementer
 | `/akili-propose` | T1 | Architecture and trade-offs — reserve the deep reasoner. |
 | `/akili-quick` | T2 | A small, direct edit + light verification — no deep reasoning needed. |
 | `/akili-specify` → requirements.md / design.md | T1 | Heavy reasoning + technical writing. |
-| `/akili-specify` → tasks.md | T5 | Fast structured partitioning into tickets. |
+| `/akili-specify` → tasks.md | T1 | **Task decomposition is where the design becomes executable** — bad boundaries, missing dependencies, or a vague scope poison every downstream Implementer (the master builder's blueprint: if the plan is wrong, no worker saves it). Reasoning, not formatting. |
 | `/akili-specify` → UX/UI design | T6 | Only when visual design is in scope. |
-| `/akili-execute` → **Leader** | T5 | Orchestration / instruction-following — writes no code. |
+| `/akili-execute` → **Leader** | T1 | Orchestration judgment — decomposition in flight, **runtime skill selection for each Implementer**, FAIL adjudication, synthesis, pivot. Writes no code, but this is reasoning, not dispatch. |
 | `/akili-execute` → **Implementer** | T2 | Maximum coding. Shares the workhorse family with propose (ARCHITECT = BUILDER). |
 | `/akili-execute` → **Reviewer** | T3 | Independent audit. **MUST resolve to a different model than the Implementer.** |
-| `/akili-test` → **Leader** | T5 | Orchestration — partitions suites and delegates; writes no tests. |
+| `/akili-test` → **Leader** | T1 | Orchestration judgment — partitions suites, **selects each Tester's skills**, adjudicates results; writes no tests. |
 | `/akili-test` → **Tester(s)** | T2 | Test authoring + verification per suite. Prefer a different model than the Implementer (author ≠ tester). |
 | `/akili-validate` | T3 | Deep conformance audit. |
 | `/akili-audit` | T4 + T3 | Drift detection over large context, judged critically. |
@@ -95,45 +107,141 @@ below.
 
 | Tier | Claude Code | OpenCode Go | Fallback |
 |---|---|---|---|
-| **T1 Architect** | `opus` *(alias — always latest)* | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / `sonnet` |
-| **T2 Coder** | `sonnet` | `opencode-go/glm-5.1` | `haiku` / `opencode-go/qwen3.7-max` |
+| **T1 Architect** | `opus` *(alias — always latest)* | `opencode-go/kimi-k3` | `opencode-go/kimi-k2.6` / `opencode-go/deepseek-v4-pro` / `sonnet` |
+| **T2 Coder** | `sonnet` | `opencode-go/glm-5.2` | `haiku` / `opencode-go/deepseek-v4-flash` |
 | **T3 Auditor** | `opus` *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | `sonnet` / `opencode-go/kimi-k2.6` |
 | **T4 Context-Ingest** | `sonnet` (long context) | `opencode-go/deepseek-v4-flash` | `opus` / `opencode-go/deepseek-v4-pro` |
 | **T5 Fast-Cheap** | `haiku` | `opencode-go/deepseek-v4-flash` | `sonnet` / `opencode-go/mimo-v2.5` |
-| **T6 Multimodal** | `sonnet` (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | `opus` |
+| **T6 Multimodal** | `sonnet` (vision) | `opencode-go/qwen3.7-max` *(weak — prefer external Gemini 3.1 Pro / Claude Sonnet vision)* | `opus` |
 
 ### Why these models
 
 **Claude Code.** The top-family alias (`opus`) carries the tightest plan rate limits, so it is
-**reserved for T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that
-most reward deep reasoning. **`sonnet` is the workhorse** for coding (T2), large-context ingestion
-(T4), and vision (T6). **`haiku`** handles fast/cheap formatting, orchestration, and summarization
-(T5). This concentrates the scarce top-tier budget on architecture and audit and avoids exhausting
-it during execution-heavy work. Because these are aliases, the mapping survives model generations
+**reserved for T1 (propose, specify reasoning, and the `/akili-execute` / `/akili-test` Leader) and
+T3 (validate, review)** — the phases that most reward deep reasoning. The Leader sits here despite
+writing no code: it *delegates*, so its opus token volume is small, but its calls (skill selection,
+FAIL adjudication, pivot) gate the whole run — low volume, high leverage. **`sonnet` is the
+workhorse** for coding (T2), large-context ingestion (T4), and vision (T6). **`haiku`** handles
+fast/cheap formatting and summarization (T5) — `/akili-archive` and pure setup steps, **not** the
+live orchestrator and **not** task decomposition. This concentrates the scarce top-tier budget on
+architecture, task decomposition, orchestration judgment, and audit — the low-volume, high-leverage
+decisions — while the high-volume execution (Implementers, Testers) stays on the `sonnet` workhorse. Because these are aliases, the mapping survives model generations
 unchanged (e.g. when the top family moves from one generation to the next, `opus` follows it).
-Users on plans that expose additional tiers (e.g. a Mythos-class model above Opus) can pin it for
-T1/T3 in their project registry.
+Users on plans that expose a frontier model above Opus (Fable 5 / Mythos 5) can pin it for T1/T3 —
+see **Frontier escalation tier** below.
 
 **OpenCode Go.** The two strongest open models anchor the two highest-leverage tiers:
 
-- **GLM-5.1 → T2 Coder.** The highest-rated open-source model overall (58.4% SWE-Pro, ahead of
-  GPT-5.4 and Claude Opus 4.6) and purpose-built for long autonomous coding runs. It is the
-  recommended **default OpenCode workhorse** and universal fallback when no specialized model is
-  preferred.
-- **Kimi K2.6 → T1 Architect.** One of the best open models (58.6% SWE-Pro, tied with GPT-5.5); its
-  Agent Swarm is built for multi-step decomposition — ideal for architectural trade-off reasoning
-  and `/akili-explore`-style impact analysis.
-- **DeepSeek V4 Pro → T3 Auditor.** 1M context + a "Think Max" reasoning mode, and crucially a
-  *different* model than the GLM-5.1 coder — satisfying author ≠ auditor for `/akili-validate` and the
-  Reviewer.
-- **DeepSeek V4 Flash → T4 / T5.** 1M context, fastest and cheapest, highest rate limit — right for
-  bulk ingestion and high-frequency formatting.
-- **Qwen3.7 Max → T6.** Best-effort only. Open-source multimodal is weak; for real UI/UX design work
-  prefer Claude Sonnet (vision) or an external Gemini model.
+- **GLM-5.2 → T2 Coder.** A-tier open coder (753B, GPQA 91.2), successor to GLM-5.1, purpose-built
+  for long autonomous coding runs — the recommended **default OpenCode workhorse**. (This row was
+  bumped 5.1 → 5.2 as a worked example of the *Replacing a model* runbook below.)
+- **Kimi K3 → T1 Architect.** S-tier open coder and the current-generation successor to K2.6 (which
+  drops to the T1 fallback), continuing the Kimi line's Agent Swarm lineage built for multi-step
+  decomposition — ideal for architectural trade-off reasoning and `/akili-explore`-style impact
+  analysis. It is the **slowest of the pack (~33 tok/s)**, which is fine for T1 (Leader/architect =
+  low-volume, latency-tolerant) but is exactly why it must **never** sit in the T2 fan-out. Concrete
+  slug, no alias: confirm it against your own OpenCode roster and follow the runbook when a newer
+  Kimi ships.
+- **DeepSeek V4 Pro → T3 Auditor.** A-tier (SWE-bench 80.6, Terminal-Bench 67.9), 1M context, and
+  crucially a *different* model than the GLM-5.2 coder — satisfying author ≠ auditor for
+  `/akili-validate` and the Reviewer.
+- **DeepSeek V4 Flash → T4 / T5 (and the T2 fallback).** 1M context, A-tier yet cheapest of the set
+  ($0.14 / $0.28 per 1M, SWE-bench 79.0), highest rate limit — right for bulk ingestion,
+  high-frequency formatting, and as a strong cheap coder fallback.
+- **Qwen3.7 Max → T6.** Best-effort only (Alibaba's flagship, the most likely open multimodal
+  option — Intelligence ~46, but pricey at ~$1.03/task). Open multimodal is weak; for real UI/UX
+  design work prefer an external **Gemini 3.1 Pro** (A-tier vision) or **Claude Sonnet** (vision).
 
 All OpenCode Go slugs are taken from the [OpenCode Go model list](https://opencode.ai/docs/go).
 Confirm them against your own OpenCode configuration and adjust if your roster differs.
 
+### Frontier escalation tier (opt-in — pin, not alias)
+
+A frontier model *above* Opus — Claude **Fable 5** (`claude-fable-5`), or **Mythos 5**
+(`claude-mythos-5`) on Project Glasswing — can be pinned for the highest-leverage slots as an
+**opt-in ceiling for genuinely hard specs**. It is **never a default** and **never in T2** (the
+high-volume fan-out): at ~2× Opus pricing (**$10 / $50** per 1M in/out vs `opus` at $5 / $25), it
+only earns its cost where token volume is low and the decision gates the whole run — T1 (Architect +
+the execute/test Leader) and T3 (Auditor).
+
+| Slot | Default (alias) | Frontier escalation pin | Fallback |
+|---|---|---|---|
+| **T1 Architect / Leader** | `opus` | `claude-fable-5` *(pin — record the reason)* | `opus` |
+| **T3 Auditor** | `opus` *(≠ T2)* | `claude-fable-5`, or a different-lab slug | `opus` / `sonnet` |
+
+Two things follow from Fable having **no floating alias**:
+
+- **It is a dated pin — record the reason** (per the alias-first rule), and it re-inherits the
+  concrete-slug maintenance the aliases spare you. `/akili-audit`'s drift check watches it; the
+  *Replacing a model* runbook below is how you swap it when a newer frontier model ships.
+- **Always give it a Fallback to `opus`**, because Fable carries operational constraints Opus does
+  not: a **refusal classifier** on bio/cyber that can false-positive on legitimate security-adjacent
+  specs (a Fable Implementer/Reviewer may decline valid work); **no zero-data-retention** (requires
+  30-day retention — unavailable to ZDR projects); **minutes-long turns** (budget HITL gates and
+  progress narration accordingly); and **less prescriptive prompting** (over-prescribed `.agents/*`
+  personas can *reduce* Fable output quality — loosen them when routing a role to Fable).
+
+**Cross-family author ≠ auditor.** Fable pairs well with a *different-lab* auditor — pin the
+Implementer/Leader on `claude-fable-5` and the Reviewer on a Kimi/DeepSeek OpenCode slug (or
+vice-versa). Different training lineages mean different blind spots, making the independent review
+genuinely stronger than same-family-different-size.
+
+## Effort dial (second dimension — tune within a tier)
+
+The registry picks the **tier** (which model). **Effort** is the orthogonal dial for *how hard that
+model thinks on a given task*. The tier is per-phase/role and stable; effort is **per-task and
+dynamic** — the same T2 `sonnet` should run a trivial rename at `low` and a concurrency fix at
+`xhigh`. Whoever spawns the worker sets it: in `/akili-execute` and `/akili-test` that is the
+**Leader**, alongside its skill selection (same master-builder judgment — which tier, which skill,
+how hard it thinks).
+
+**Why it matters — the intelligence↔cost curve is steeply diminishing at the top.** Measured on a
+representative model (GPT-5.6 Sol, Artificial Analysis Intelligence Index):
+
+| Effort | Intelligence | Cost/task | vs. `max` |
+|---|---|---|---|
+| `max` | 59 | $1.04 | — |
+| `xhigh` | 58 | $0.68 | −1 pt, −35% cost |
+| `high` | 56 | $0.45 | −3 pts, −57% cost |
+| `medium` | 54 | $0.31 | **−5 pts (−8%), −70% cost** |
+
+`medium`/`high` captures ~90–95% of the intelligence at ~30–45% of the cost; running everything at
+`max`/`xhigh` pays a large premium for a few points. Reserve `xhigh`/`max` for genuinely hard work.
+
+**Effort policy — by task signal:**
+
+| Signal | Effort |
+|---|---|
+| Trivial / mechanical (copy, rename, style) | `low` |
+| Standard task, clear scope | `medium` |
+| Complex (algorithm, concurrency, security, ambiguity) | `xhigh` |
+| Correctness-critical (can't be wrong, hard to revert) | `max` |
+
+**Default effort by role** (starting point before flexing):
+
+| Role / Phase | Default effort |
+|---|---|
+| T1 `/akili-propose` / `/akili-specify` (incl. `tasks.md` decomposition) / **Leader** | `high` (`xhigh` if architecturally significant) |
+| T2 **Implementer / Tester** | `medium` — flex by task |
+| T3 **Reviewer** / `/akili-validate` | `high` (auditor thoroughness) |
+| T5 `/akili-archive` / setup steps | `low` |
+
+**Escalate effort on rework.** In the `/akili-execute` rework loop, a Reviewer `FAIL` bumps effort
+one level on the retry (attempt 1 `medium` → attempt 2 `high` → attempt 3 `xhigh`) — cheap (only
+when it already failed) and it targets the usual cause (under-thinking, not missing instructions).
+
+**Tier ↔ effort interaction — don't `max` a cheaper tier.** Maxing a lower tier erodes its cost
+advantage: Sonnet 5 at `max` (53 intel / $1.53) approaches Opus 4.8 at `max` (56 intel / $1.80) —
+near-Opus price for below-Opus intelligence. If you find yourself wanting a cheaper tier at `max`,
+escalate the **tier** (to `opus` at `high`/`medium`) instead of the effort.
+
+**Sonnet specifics.** Sonnet respects effort strictly, especially at the low end — at `low`/`medium`
+it scopes work to exactly what was asked. If you see shallow reasoning on a hard problem, **raise
+the effort, don't prompt around it**. `high` is the default sweet spot; give `max_tokens` headroom
+at `xhigh`/`max` (thinking consumes the budget — too tight truncates with `stop_reason: max_tokens`).
+On Opus/frontier the nuance inverts slightly: start at `high` and iterate — more effort up front
+often *reduces* total turns and cost on agentic work.
+
 ## Enforced routing (tool-native agent bindings)
 
 The `/akili-execute` and `/akili-test` fan-out (Implementer, Reviewer, Testers) is where most
@@ -145,7 +253,7 @@ there:
 | Tool | Native agent location | Model value |
 |---|---|---|
 | Claude Code | `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` (project-level) | Alias from the registry (`model: sonnet`, `model: opus`, `model: haiku`) |
-| OpenCode | Project agent config (`.opencode/agent/*.md` or the `agent` block of `opencode.json`, per your OpenCode version) | Provider slug from the registry (`model: opencode-go/glm-5.1`) |
+| OpenCode | Project agent config (`.opencode/agent/*.md` or the `agent` block of `opencode.json`, per your OpenCode version) | Provider slug from the registry (`model: opencode-go/glm-5.2`) |
 | Antigravity | Not supported — `invoke_subagent` has no per-agent model binding | Guidance-only fallback |
 
 Each wrapper is thin: frontmatter (`name`, `description`, `model`) plus a body that instructs the
@@ -179,16 +287,51 @@ Models change constantly; the design absorbs that at three layers:
    packaged default without overwriting user pins. Each AKILI release refreshes this document's
    default registry.
 
+## Replacing a model (developer runbook)
+
+You started the project on 2026's models; it is now 2027 and better ones exist. What you do depends
+on **what kind of entry** you put in the registry. Tiers never change — you only ever touch the
+model column.
+
+| Your registry entry | What to do when a newer model ships |
+|---|---|
+| **Floating alias** (`opus` / `sonnet` / `haiku`, Claude Code) | **Nothing.** The alias auto-resolves to the latest generation of that family — this is exactly what alias-first buys you. Zero edits. |
+| **Concrete slug** (OpenCode `opencode-go/...`, a dated Claude pin, or `claude-fable-5`) | **Edit it** — no alias mechanism absorbs the change. Follow the 3 steps below. |
+| **You want to re-map a tier** (promote a new model into T1/T2/T3, e.g. Kimi K3 → T1) | Edit the tier's row, then reconcile wrappers — same 3 steps. Treat it as a *promotion to evaluate*, not an auto-swap (does it fit the tier? does it keep author ≠ auditor?). |
+
+**The 3 steps (concrete-slug or re-map case):**
+
+1. **Edit ONE table** — the `## Model Routing` block in your **project's** root `AGENTS.md` /
+   `CLAUDE.md` (not this packaged default; see below). Change the slug(s), bump the
+   `Updated: <YYYY-MM>` stamp, and record a one-line reason next to any dated pin.
+2. **Reconcile the Step 8E wrappers** — `.claude/agents/akili-*.md` and `.opencode/agent/*.md`
+   hard-code `model:` per role, so their value must match the new registry. Alias-based Claude
+   wrappers (`model: opus`) usually need no change; concrete OpenCode slugs do.
+3. **Run `/akili-audit`** — its **Model Registry Drift** check confirms the registry and wrappers
+   agree and flags any slug the tool no longer offers.
+
+**Which file do I edit — the package default or the project copy?**
+
+- `docs/model-routing.md` (this file) is the **default new projects inherit**. Editing it does *not*
+  change projects already scaffolded.
+- The `## Model Routing` block inside each project's root `AGENTS.md` / `CLAUDE.md` is **what
+  actually governs that project** — that is where a downstream developer edits. When you upgrade the
+  AKILI package and its default registry moves ahead of your project copy, `/akili-constitution` in
+  **Safe Update mode** flags the difference without overwriting your pins; you decide what to adopt.
+
 ## How to apply per tool
 
 - **Claude Code:** switch with `/model` before running a phase — e.g. `/model opus` for
-  `/akili-propose` and `/akili-validate`, `/model sonnet` for `/akili-execute` and `/akili-test`,
-  `/model haiku` for the tasks split and `/akili-archive` — or simply respond to each command's
-  model checkpoint. With Step 8E bindings in place, the execute/test triad routes itself
-  (Implementer on `sonnet`, Reviewer on `opus`).
+  `/akili-propose`, `/akili-validate`, and the `/akili-execute` / `/akili-test` **Leader session**
+  (you orchestrate on the deep reasoner; the triad's Implementer/Tester subagents route to `sonnet`
+  via their Step 8E wrappers), plus the full `/akili-specify` run (including `tasks.md` decomposition);
+  `/model haiku` only for `/akili-archive` and pure setup/formatting steps — or simply respond to each
+  command's model checkpoint. With Step 8E bindings in place, the execute/test triad
+  routes itself (Implementer on `sonnet`, Reviewer on `opus`, Leader = your session).
 - **OpenCode:** select the `opencode-go/...` model for each phase per the registry, or use the
-  Step 8E agent bindings. Keep the Reviewer/validator on a different model (`deepseek-v4-pro`)
-  than the Implementer (`glm-5.1`).
+  Step 8E agent bindings. Run the **Leader session on the T1 slug** (`opencode-go/kimi-k3`), and
+  keep the Reviewer/validator on a different model (`deepseek-v4-pro`) than the Implementer
+  (`glm-5.2`).
 
 ## Cross-tool safety
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {