akili-specs 2.10.1 → 2.12.0

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

@@ -19,7 +19,7 @@ Detect and report drift between the project's specifications (PRD, UX/UI Design,
 
 ### Step 0: Read Project Specifications
 
-**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for the scan and **T3 Auditor** for judging drift. 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. *"This phase is T4+T3 — the registry recommends `/model sonnet`; 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 **T4 Context-Ingest** for the scan and **T3 Auditor** for judging drift — recommend the deeper tier's model since the judging is where quality is decided. If the project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) maps those tiers to a model different from the current session model, tell the user in one line — e.g. *"This phase is T4+T3 — the registry recommends `/model opus` (T3 judging; `sonnet` suffices for the scan); 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.
 
 First, read the constitutional documentation baseline in the repository:
 
@@ -50,7 +50,7 @@ Audit for discrepancies, classifying findings under the following categories:
 
 ### Step 3: Write Drift Report
 
-Create or update:
+Create or update (writing per `cognitive-doc-design`: lead with the verdict, tables over prose):
 
 ```text
 docs/specs/drift-report.md

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
@@ -397,6 +401,15 @@ project guides so the project does not depend on the package's `docs/` after ins
 5. The instruction: *"To change models, edit only this registry table. Never pin a dated model name
    where a floating alias exists. Model selection is guidance only in command prompts — never add
    `model:` to command frontmatter; enforced bindings live only in the Step 8E agent wrappers."*
+6. A compact **Effort dial** subsection (mirroring the packaged `docs/model-routing.md` → *Effort
+   dial*): effort is the second, **per-task** routing dimension, orthogonal to the tier — the tier
+   picks the model, effort picks how hard it thinks on *this* task. Include: (a) the effort-by-signal
+   table (trivial/mechanical → `low`; standard scope → `medium`; complex — algorithm, concurrency,
+   security, ambiguity → `xhigh`; correctness-critical → `max`); (b) default effort by role (T1
+   propose/specify/Leader `high`; T2 Implementer/Tester `medium`, flex by task; T3 Reviewer `high`;
+   T5 archive `low`); (c) the rework rule (*bump effort one level on every retry*); and (d) the
+   tier↔effort rule (*never `max` a cheaper tier — escalate the tier instead*). The
+   `/akili-execute` and `/akili-test` Leaders read this subsection to set each worker's effort.
 
 **Mode-specific policy (mirror Step 8B):**
 
@@ -470,14 +483,16 @@ 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),
+  tester `opencode-go/deepseek-v4-flash` — the T2 fallback rather than the T2 primary, so the
+  Tester lands on a **different model than the Implementer** (author ≠ tester)).
 
 - **Google Antigravity:** no per-agent model binding exists — skip wrapper generation and note in
   the summary that Antigravity stays on guidance-only routing.
@@ -485,7 +500,9 @@ this step — the guidance-only flow keeps working.
 **Rules:**
 
 1. The Reviewer wrapper's model MUST differ from the Implementer wrapper's model. If the registry
-   collapses them, escalate the Reviewer one tier before writing the wrappers.
+   collapses them, escalate the Reviewer one tier before writing the wrappers. The Tester wrapper
+   should also **prefer** a model different from the Implementer's (author ≠ tester — a preference,
+   not a hard rule); if they collapse, note it in the summary rather than blocking.
 2. Wrappers reference `.agents/<role>.md`; they never duplicate persona content. Editing a persona
    requires no wrapper change; changing a model requires editing only the wrapper (or re-running
    this step).

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-propose.md

@@ -133,7 +133,7 @@ Ask focused questions only when the proposal would otherwise depend on unstable
 
 ### Step 2: Write `proposal.md`
 
-Create a concise proposal with this structure:
+Create a concise proposal following `cognitive-doc-design` (lead with the answer, progressive disclosure, tables over prose) with this structure:
 
 1. Document Control (include `Type: Bug | Change | Trivial`)
 2. Intent

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

@@ -41,7 +41,7 @@ Before making any edit, confirm the change qualifies as trivial. A change is eli
 - **No behavior change:** no new or modified logic, control flow, conditionals, state, or side effects.
 - **No data / API / auth / contract change:** no schema, endpoint, request/response shape, permission, or shared-package surface change.
 - **Small and local:** roughly **≤ ~20 LOC** and confined to **one component/file** (or a couple of tightly related files).
-- **Design-token safe:** any color/spacing/typography change uses an existing approved token from `docs/ux-ui/design.md` — not a new hardcoded value.
+- **Design-token safe:** any color/spacing/typography change uses an existing approved token from `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`) — not a new hardcoded value.
 
 ### Automatic Escalation
 
@@ -66,7 +66,7 @@ Keep context small — this is a trivial change, not a full spec run.
 
 1. Read only what the change needs:
    - the target file(s) for the change
-   - `docs/ux-ui/design.md` **only if** the change involves a color, spacing, typography, or other design token (to use the approved token)
+   - `docs/ux-ui/design.md` (legacy fallback: `docs/system-design/design.md`) **only if** the change involves a color, spacing, typography, or other design token (to use the approved token)
    - root `CLAUDE.md` / `AGENTS.md` only if repo conventions are unclear for the edit
 2. **CodeGraph over full reads:** if `.codegraph/` exists, use `codegraph_search` to locate the exact symbol/component instead of scanning files.
 3. Do **not** read the full constitution set, `docs/prd.md`, or `docs/trd/trd.md` for a trivial edit.

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

@@ -23,6 +23,8 @@ No arguments required. The command scans `docs/specs/` automatically.
 
 ### Step 0: Scan Active Specs
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** — file scanning and summarization; reasoning depth is not the bottleneck. 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. *"Resume is T5 — the registry recommends `/model haiku`; you are on opus"* — and offer to switch (`/model …` in Claude Code, the model selector in OpenCode). Never block on this; continuing on the current model is always allowed (and switching is rarely worth it for a single scan).
+
 1. List all directories under `docs/specs/` (excluding `archive/`).
 2. For each spec directory, read available files to determine current phase:
    - `proposal.md` exists → proposed

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

@@ -214,7 +214,7 @@ Record each failure as a finding using the skill's Issue / Impact / Evidence / F
 
 ### Phase 3: Write `seo-audit-report.md`
 
-Generate `docs/specs/$SPEC_PATH/seo-audit-report.md` using `docs/specs/general-setup/validation-report.md` as the format source where it fits.
+Generate `docs/specs/$SPEC_PATH/seo-audit-report.md` using `docs/specs/general-setup/validation-report.md` as the format source where it fits, writing per `cognitive-doc-design` (lead with the verdict, tables over prose).
 
 Required sections:
 

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.
 
@@ -101,10 +101,8 @@ The Leader decides the count from the spec's depth and the independence of the s
 1. Partition the work into concrete **suites**: backend unit, frontend unit, integration, E2E — only those the spec actually needs.
 2. For each suite, assemble a **context slice**: the target requirements + scenarios, the negative/strict rules to assert, the repo test command, and the relevant skills.
 3. Apply the **Deployment Rule** to decide inline vs delegated, and parallel vs sequential.
-4. Assign skills per suite as needed:
-   - `nestjs-expert`, `systematic-debugging` — backend
-   - `vercel-react-best-practices`, `react-doctor` — frontend
-   - `ui-ux-pro-max` (fallback `frontend-design`) — UI-heavy E2E
+4. **Select each suite's skills as Leader — you own the decision, not a fixed list.** The spec's task skills and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) are your **defaults, not a pass-through**: judge each suite's actual nature and augment, narrow, or override them (conditional skills like `systematic-debugging` for failure-heavy suites or `ui-ux-pro-max` for UI-heavy E2E; stack skills come from the Skill Map). When you deviate from the spec's list, record a one-line reason in the test report's Summary.
+5. **Set each suite's effort** (the *Effort dial* in `## Model Routing`, orthogonal to the tier): default `medium` for a T2 Tester, `low` for a trivial single-assertion suite, `xhigh` for complex integration/concurrency suites, `max` for correctness-critical coverage. Where the tool exposes a per-spawn effort knob, set it; otherwise steer depth in the suite's context slice. Never `max` a cheaper tier — escalate the tier instead.
 
 ### Phase 2: Execute Suites (Tester per suite)
 
@@ -115,7 +113,8 @@ For each suite, the assigned Tester (or the Leader inline) must:
 - Map every test back to its requirement and scenario.
 - Run the suite and apply the **bounded self-correction inner loop** (max 3 attempts):
   - fix genuine **test defects** and re-run;
-  - keep a failing test that reveals a genuine **product defect** red, and report it as `STATUS: PRODUCT_BUG` instead of rewriting it to pass.
+  - keep a failing test that reveals a genuine **product defect** red, and report it as `STATUS: PRODUCT_BUG` instead of rewriting it to pass;
+  - on each retry, **bump the effort one level** (`medium` → `high` → `xhigh`) — a fix that failed is usually under-thinking, not missing instructions.
 - Prefer unit tests for internal logic, integration tests for cross-module/API behavior, and E2E only for critical user journeys — not every small component state.
 
 Each Tester concludes with exactly one status — `PASS`, `FAIL`, or `PRODUCT_BUG` — plus a per-scenario coverage slice, per `.agents/tester.md`.
@@ -131,7 +130,7 @@ Recommended matrix columns:
 
 ### Phase 4: Generate Test Report (Leader)
 
-Create `docs/specs/$ARGUMENTS/test-report.md`.
+Create `docs/specs/$ARGUMENTS/test-report.md`. Write it following `cognitive-doc-design`: lead with the answer (overall status first), progressive disclosure, tables over prose.
 
 **Automated Test Parsing Option:** If the repository uses standard testing frameworks (like Jest or Vitest) and has a AKILI test parsing helper installed (e.g. `akili/scripts/parse_tests.js`), you may run the tests outputting to JSON (e.g. `jest --json --outputFile=jest-results.json` or `vitest --reporter=json --outputFile=test-results.json`) and run:
 `node <path-to-akili>/scripts/parse_tests.js jest-results.json`

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

@@ -108,13 +108,8 @@ For every requirement in `requirements.md`, verify:
 
 Use skills as needed:
 
-- `nestjs-expert`
-- `react-doctor`
-- `api-design-principles`
-- `tailwind-design-system`
-- `frontend-design`
-- `ui-ux-pro-max` if available for UX/UI-heavy validation
-- `systematic-debugging` when failures or inconsistencies appear
+- **Stack skills come from the project's `## Skill Map`** (root `AGENTS.md`/`CLAUDE.md`) — load the entries matching the code under validation; do not assume a fixed list.
+- Conditional skills by situation: `ui-ux-pro-max` (fallback `frontend-design`) for UX/UI-heavy validation; `systematic-debugging` when failures or inconsistencies appear.
 
 Check for:
 
@@ -139,7 +134,7 @@ If `proposal.md` exists, also verify that final behavior remains aligned with th
 
 ### Phase 7: Generate Validation Report
 
-Create `docs/specs/$ARGUMENTS/validation-report.md`.
+Create `docs/specs/$ARGUMENTS/validation-report.md`. Write it following `cognitive-doc-design`: lead with the verdict, progressive disclosure, tables over prose.
 
 The report must include:
 

package/.claude/skills/react-doctor/SKILL.md

@@ -5,6 +5,7 @@ version: 1.0.0
 metadata:
   author: Million.dev (millionco)
   source: https://github.com/millionco/react-doctor
+  license: MIT
   adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: stack

package/.claude/skills/shadcn-ui/SKILL.md

@@ -4,7 +4,8 @@ description: Provides complete shadcn/ui component library patterns including in
 allowed-tools: Read, Write, Bash, Edit, Glob
 metadata:
   author: community (origin unverified)
-  curated-by: "Juan Carlos Cadavid — jcadavid.com"
+  license: "unverified — no upstream source to check; treat as all-rights-reserved until origin is identified"
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: stack
   version: "1.0"

package/.claude/skills/stitch-design/SKILL.md

@@ -8,6 +8,7 @@ allowed-tools:
 metadata:
   author: Google (google-labs-code)
   source: https://github.com/google-labs-code/stitch-skills
+  license: Apache-2.0
   adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: conditional

package/.claude/templates/implementer.md

@@ -12,7 +12,8 @@ Your sole responsibility is to implement the technical scope of the active task
 
 1.  **Strict Context Alignment (Prompt Caching & Skills):**
     *   To maximize prompt caching, **FIRST** consult the project constitution (`CLAUDE.md`, `AGENTS.md`, `docs/trd/trd.md`, `docs/ux-ui/design.md`) in a consistent order before reading task-specific files.
-    *   **Skill Loading:** If the Leader assigns you specific skills (e.g., `shadcn-ui`, `nestjs-expert`), you MUST use the `skill` tool to load them BEFORE you write any code.
+    *   **Skill Loading:** If the Leader assigns you specific skills (e.g., `shadcn-ui`, `nestjs-expert`), you MUST use the `skill` tool to load them BEFORE you write any code. **The Leader's skill assignment supersedes the task's recommended list** — the Leader actively selects skills per task; load what it assigns, not what the task file says.
+    *   **Effort:** Honor the Leader's effort/depth instruction for this task (the *Effort dial* in `## Model Routing`) — think as hard as the brief asks: quick and mechanical for trivial work, deep and careful when the brief flags the task as complex or correctness-critical.
     *   Strictly align with requirements defined in `docs/specs/<spec-path>/requirements.md`.
     *   Follow the technical blueprint in `docs/specs/<spec-path>/design.md`.
 2.  **Incremental Focus (No Scope Creep):**

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.
 
@@ -63,6 +64,20 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 
 ---
 
+## 🧪 When Orchestrating `/akili-test` (Leader → Tester harness)
+
+The same Leader judgment applies when you orchestrate testing — only the workers change:
+
+1. **Partition** the spec's testing into concrete suites (backend unit, frontend unit, integration, E2E — only those the spec needs) and apply `/akili-test`'s Deployment Rule (inline vs delegated).
+2. **Select each Tester's skills and effort** exactly as you do for Implementers (Instruction #3): the spec's list and the `## Skill Map` are defaults you may override; set per-suite effort (`medium` default, flex by suite difficulty) and record deviations in the test report's Summary.
+3. **author ≠ tester:** prefer spawning each Tester on a **different model than the Implementer** that wrote the production code (reduces confirmation bias). A preference, not a hard rule — note it when they collapse.
+4. **Adjudicate results:** a `PRODUCT_BUG` from a Tester is evidence, not noise — carry it through as a failure with remediation; never let a Tester rewrite a red test to pass.
+5. You write no tests yourself except where `/akili-test`'s Deployment Rule says to run a trivial suite inline.
+
+The full test-orchestration contract (phases, Deployment Rule, report format) lives in `/akili-test`; this section makes your authority consistent across both harnesses.
+
+---
+
 ## 📝 Reporting To The User
 
 After each task completes (whether on first pass or after self-correction), report:

package/.claude/templates/reviewer.md

@@ -4,7 +4,7 @@ You are the specialized **Specification Reviewer** agentic team member in the AK
 
 Your sole responsibility is to perform an independent, objective audit of the git diff produced by the **Implementer**. You act as a strict gatekeeper to ensure code matches specifications, conforms to design tokens, and preserves repository stability.
 
-> **Recommended model tier:** T3 Auditor (deep, independent review). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. You **MUST** run on a **different model than the Implementer** — author ≠ auditor is a correctness constraint, not a preference. If only one model is available, escalate to the deepest-reasoning model for this audit.
+> **Recommended model tier:** T3 Auditor (deep, independent review) at **default effort `high`** — auditor thoroughness is the point; do not skim (see the *Effort dial* in `## Model Routing`). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. You **MUST** run on a **different model than the Implementer** — author ≠ auditor is a correctness constraint, not a preference. If only one model is available, escalate to the deepest-reasoning model for this audit.
 
 ---
 

package/.claude/templates/tester.md

@@ -13,7 +13,8 @@ Your sole responsibility is to author and execute the **one test suite** assigne
 1.  **Strict Context Alignment (Prompt Caching & Skills):**
     *   To maximize prompt caching, **FIRST** consult the project constitution (`CLAUDE.md`, `AGENTS.md`, `docs/trd/trd.md`, `docs/ux-ui/design.md`) in a consistent order before reading task-specific files.
     *   Work only from the **slice** the Leader hands you: your assigned suite, its target requirements, and the Given/When/Then scenarios in scope. Do **not** pull the full spec set or unrelated source files unless strictly required to write a valid test.
-    *   **Skill Loading:** If the Leader assigns skills (e.g. `nestjs-expert`, `react-doctor`, `vercel-react-best-practices`, `systematic-debugging`, `ui-ux-pro-max`), load them with the `skill` tool **before** writing tests.
+    *   **Skill Loading:** If the Leader assigns skills (e.g. `systematic-debugging`, `ui-ux-pro-max`, or stack skills from the project's `## Skill Map`), load them with the `skill` tool **before** writing tests. The Leader's assignment supersedes any list in the spec.
+    *   **Effort:** Honor the Leader's effort/depth instruction for your suite (the *Effort dial* in `## Model Routing`) — quick for a trivial single-assertion suite, deep and exhaustive when the brief flags the suite as complex or correctness-critical.
 2.  **Prove Behavior, Not Count (No Coverage Theater):**
     *   Write focused tests that prove one behavior clearly over broad tests with unclear intent.
     *   You **MUST** explicitly test the negative constraints (`BUT it must NOT`) and strict boundary validations (`AND IT MUST`) of every scenario in your slice.

package/CHANGELOG.md

@@ -10,6 +10,30 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.12.0] - 2026-07-24
+
+### Changed
+
+- **Methodology audit — effort dial and Leader authority propagated to their remaining surfaces.** A four-front audit (commands, personas, skills governance, docs coherence) after v2.11.0 found the new capabilities had landed in `/akili-execute` but not its siblings. Fixed: **(a)** `/akili-constitution` Step 8C now scaffolds the **Effort dial** into each project's `## Model Routing` (item 6: effort-by-signal table, per-role defaults, rework escalation, tier↔effort rule) — previously `/akili-execute` referenced a section fresh projects never had; **(b)** `/akili-test` gains per-suite **effort selection** (Phase 1), **effort escalation on the Tester inner loop**, and the same active skill-selection authority as execute; **(c)** worker personas now acknowledge the dial — `implementer.md`/`tester.md` honor the Leader's effort brief (and state the Leader's skill assignment supersedes the task list), `reviewer.md` states its default effort `high`; **(d)** `leader.md` gains a **"When Orchestrating `/akili-test`"** section (was execute-only — never mentioned Testers or author ≠ tester); **(e)** Step 8E adds the missing **OpenCode tester wrapper default** (`opencode-go/deepseek-v4-flash` — the T2 *fallback* rather than the primary, so the Tester lands on a different model than the Implementer) plus a soft author ≠ tester guard in Rule 1.
+- **Command-consistency fixes from the audit.** `/akili-resume` gains the standardized model checkpoint every sibling has, and joins the phase→tier table as an explicit T5 row; `/akili-audit`'s checkpoint now surfaces `opus` for the T3 drift-judging portion (it only named the T4 scan model); `cognitive-doc-design` is now cited by all five report-producing commands that lacked it (`propose`/`audit`/`seo`/`validate`/`test`); `/akili-quick` gains the `docs/system-design/design.md` legacy fallback every other design-reader carries.
+- **Skills governance: rule-vs-practice contradiction resolved with documented carve-outs.** The absolute "stack skills never hard-referenced in command text" rule contradicted four command sites. `governance.md` now distinguishes **load-directing** (violation) from three carve-outs: the constitution's candidate-pool/bootstrap lists, no-map fallback lists that defer to the Skill Map first, and Skill-Map-deferring illustrative examples. The two genuine violations were purged: `/akili-validate` and `/akili-test` now point stack-skill selection at the project `## Skill Map` instead of fixed lists. `docs/skills/README.md` aligned.
+- **Skill attribution completed.** `react-doctor` (`license: MIT`) and `stitch-design` (`license: Apache-2.0`) — both verified against their upstream repositories; `shadcn-ui`'s off-schema `curated-by` normalized to `adapted-by` with an explicit unverified-license warning.
+- **Stale docs corrected.** `README.md` no longer claims fast/cheap models handle the tasks split (the exact belief v2.11.0 reversed — now: deep reasoning for propose/specify incl. `tasks.md`/validate/Leader, fast/cheap only for archive+formatting, plus the Effort dial); README and `docs/cli.md` now document the v2.10.1 installer **auto-detect** behavior (bare `install`/`update`/`doctor` act on all installed targets); README's Contents lists all 22 skills (added `caveman`, `software-architect`); `docs/commands/README.md` includes Antigravity; `model-routing.md` wording fix ("the strongest open models").
+## [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/README.md

@@ -79,6 +79,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `api-design-principles`
   - `aws-serverless`
   - `brainstorming`
+  - `caveman`
   - `cognitive-doc-design`
   - `error-handling-patterns`
   - `frontend-design`
@@ -90,6 +91,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `react-doctor`
   - `seo-audit`
   - `shadcn-ui`
+  - `software-architect`
   - `stitch-design`
   - `systematic-debugging`
   - `tailwind-design-system`
@@ -138,7 +140,9 @@ npx akili-specs init
 
 **Manual Installation via Flags:**
 
-Install globally for Claude (default):
+Install without `--tool` — the installer **auto-detects targets already installed on disk**
+(`~/.claude`, `~/.config/opencode`, `~/.gemini`) and acts on all of them; on a first-time run with
+nothing installed it defaults to Claude:
 
 ```bash
 npx akili-specs install
@@ -810,7 +814,9 @@ selector), and `/akili-constitution` scaffolds a `## Model Routing` registry int
 
 Key principles: **ARCHITECT = BUILDER** (the model that designs also builds), **author ≠ auditor**
 (the Reviewer runs on a different model than the Implementer), reserve deep-reasoning models for
-`/akili-propose` and `/akili-validate`, and use fast/cheap models for the tasks split and `/akili-archive`.
+`/akili-propose`, `/akili-specify` (including the `tasks.md` decomposition), `/akili-validate`, and
+the `/akili-execute`/`/akili-test` Leader, and use fast/cheap models only for `/akili-archive` and
+pure setup/formatting steps. An **Effort dial** adds a second, per-task dimension on top of the tier.
 
 See **[docs/model-routing.md](docs/model-routing.md)** for the tiers, the full phase→tier mapping,
 and the default registry for Claude Code (PRO) and OpenCode Go.

package/docs/cli.md

@@ -26,7 +26,10 @@ npx akili-specs install --tool both
 npx akili-specs install --tool all
 ```
 
-Claude is the default target:
+When `--tool` is omitted, `install`, `update`, and `doctor` **auto-detect already-installed
+targets** on disk (`~/.claude`, `~/.config/opencode`, `~/.gemini`) and act on all of them — so a
+bare `akili update` refreshes every installed tool, not just Claude. A first-time run with nothing
+installed defaults to Claude. An explicit `--tool <name>` always wins:
 
 ```bash
 npx akili-specs install
@@ -67,6 +70,7 @@ Every command closes with a clear end-of-run summary:
 
 | Option | Applies To | Purpose |
 |---|---|---|
+| *(no `--tool`)* | install, update, doctor | **Auto-detect installed targets** and act on all of them; default to Claude when none found |
 | `--tool claude` | install, update, doctor | Target Claude Code config |
 | `--tool opencode` | install, update, doctor | Target OpenCode config |
 | `--tool antigravity` | install, update, doctor | Target Google Antigravity config |

package/docs/commands/README.md

@@ -1,6 +1,6 @@
 # Command Reference
 
-AKILI commands are installed as slash-command prompts for Claude Code and OpenCode. The installable source files live in `.claude/commands/`.
+AKILI commands are installed as slash-command prompts for Claude Code, OpenCode, and Google Antigravity (as workflows). The installable source files live in `.claude/commands/`.
 
 ## Command Map
 

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,16 +77,17 @@ 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. |
 | `/akili-archive` | T5 | Cheap, fast summarization of closed work. (Kaizen Learn sub-step: T3 optional.) |
+| `/akili-resume` | T5 | File scanning + dashboard summarization — reasoning depth is not the bottleneck. |
 | `/akili-seo` | T3 + T5 | Audit findings (T3) plus setup/formatting steps (T5). |
 
 **author ≠ auditor enforcement.** In the registry, T2 (Coder) and T3 (Auditor) must resolve to
@@ -95,45 +108,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.
-
-**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.
+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 strongest open models anchor the highest-leverage tiers:
+
+- **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 +254,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 +288,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/docs/skills/README.md

@@ -10,7 +10,7 @@ The skill set is **curated, not accumulated**: every skill declares its original
 |---|---|
 | `core` | Hard-wired to a precise command step — the command loads it by name |
 | `conditional` | Loaded when the work touches its domain (UI, animation) |
-| `stack` | Selected per project via the `## Skill Map` scaffolded by `/akili-constitution`; never hardcoded in command text |
+| `stack` | Selected per project via the `## Skill Map` scaffolded by `/akili-constitution`; never load-directed in command text (candidate-pool lists in the Skill Map builder and Skill-Map-deferring examples are documented carve-outs — see `governance.md`) |
 
 ## Skill Inventory
 

package/docs/skills/governance.md

@@ -26,7 +26,7 @@ Rules of thumb:
 
 - A skill earns `core` only when a command step would be *wrong* without it (a retrospective without `kaizen` is not the AKILI archive).
 - `conditional` skills are stack-agnostic capabilities that many but not all specs need (UI, animation).
-- `stack` skills must never be hard-referenced in command text — commands stay tool- and framework-agnostic. They reach the agent through the project Skill Map and per-task skill lists.
+- `stack` skills must never be **load-directed** in command text (a command step telling the agent to load a named stack skill) — commands stay tool- and framework-agnostic. They reach the agent through the project Skill Map and per-task skill lists. **Three documented carve-outs:** (1) the Skill Map *builder* in `/akili-constitution` (Step 8D, and the Step 5 TRD bootstrap that feeds it — constitution runs *before* the map exists) may enumerate the packaged stack skills as the candidate pool it selects from; (2) an explicit **no-map fallback list** that defers to the Skill Map first ("prefer the `## Skill Map` when it exists; otherwise pick from: …") is acceptable; (3) purely *illustrative* examples ("e.g. `nestjs-expert`") that explicitly defer to the task list / Skill Map are acceptable. A step that says "use these skills:" followed by stack-skill names, with **no** Skill Map deferral, is a violation.
 
 ## Frontmatter Schema
 

package/package.json

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