akili-specs 2.7.1 → 2.9.0

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

@@ -56,6 +56,8 @@ docs/specs/archive/2026-05-16-bugfix--login-redirect/
 
 ### Step 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T5 Fast-Cheap** (summarization and bookkeeping). 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 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.
+
 **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.
 
 1. Confirm `docs/specs/$ARGUMENTS/` exists.

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

@@ -19,6 +19,8 @@ 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.
+
 First, read the constitutional documentation baseline in the repository:
 
 1. `docs/prd.md`
@@ -44,6 +46,7 @@ Audit for discrepancies, classifying findings under the following categories:
 * **Visual/Design Token Mismatch:** Colors, typography, spacing, or component structures used in the codebase that violate the styling tokens and design principles declared in `docs/ux-ui/design.md`.
 * **Technical Constraints Violation:** Architectural layout in the codebase that conflicts with patterns (e.g. testing requirements, security rules, file structuring) documented in `docs/trd/trd.md`.
 * **Agent Guide Drift:** Modules whose conventions clearly diverge from the root but lack a child `CLAUDE.md`/`AGENTS.md`, child guides missing from the parent's `## Module Guides` index, guide entries pointing at modules that no longer exist, or root-guide structure descriptions that no longer match the codebase.
+* **Model Registry Drift:** The project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) names models the host tool no longer offers, uses dated model pins where a floating alias exists (violating the alias-first rule) without a recorded reason, is missing tiers or the author ≠ auditor note versus the packaged default in `docs/model-routing.md`, or the Step 8E agent wrappers (`.claude/agents/akili-*.md` / OpenCode agent config) declare models that contradict the registry. Report only — never edit the registry or wrappers during the audit.
 
 ### Step 3: Write Drift Report
 
@@ -87,6 +90,7 @@ A brief overview of the codebase alignment state and major areas of specificatio
 | UX/UI Design / Screen Inventory | [Details] | [Aligned / Drifted] | |
 | TRD (APIs/DB) | [Details] | [Aligned / Drifted] | |
 | Agent Guides (root + `## Module Guides` index) | [Details] | [Aligned / Drifted] | |
+| Model Routing (registry + Step 8E wrappers) | [Details] | [Aligned / Drifted] | |
 
 ## Recommended Next Steps
 Specific actions to resolve the discrepancies (e.g., "Run `/akili-constitution` to enhance baseline", "Update `trd.md` with active REST APIs", or "Schedule a task to implement missing validation tests").

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

@@ -19,6 +19,8 @@ Establish or strengthen the project-wide AKILI-SPECS foundation. This command cr
 
 ### Step 0: Determine Project Mode and Foundation Setup
 
+**Model checkpoint:** This phase runs best on **T4 Context-Ingest** for repository ingestion and **T1 Architect** for baseline synthesis (if no project registry exists yet, use the packaged default in `docs/model-routing.md`). 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. *"Baseline synthesis is T1 — the default 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.
+
 Before classifying the repository, use the `brainstorming` skill to ask the user if this is a new project/MVP starting from 0, or if it is an existing project with an established structure.
 
 Based on the response, classify the repository into one of three modes. The classification is non-destructive — it controls how aggressively the constitution drafts, scans, or preserves existing material.
@@ -34,7 +36,7 @@ For all three modes:
 3. Ensure `docs/specs/general-setup/` exists.
 4. Ensure root `CLAUDE.md` exists or is enhanced.
 5. Ensure root `AGENTS.md` exists or is enhanced.
-6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 7B).
+6. Ensure project-level `.agents/` exists with `leader.md`, `implementer.md`, `reviewer.md`, and `tester.md` (see Step 8B).
 7. Default behavior is to enhance existing project docs in place instead of creating parallel copies.
 
 The constitutional baseline must cover these files:
@@ -210,7 +212,7 @@ When the file already exists, refine it in place instead of replacing establishe
 
 Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 
-**Use skills when relevant:**
+**Use skills when relevant** (stack skills — load only the ones matching the project's stack; the same set feeds the `## Skill Map` in Step 8D):
 
 - `nestjs-expert`
 - `api-design-principles`
@@ -219,6 +221,7 @@ Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 - `shadcn-ui`
 - `tailwind-design-system`
 - `vercel-react-best-practices`
+- `angular-developer`
 
 **Required structure:**
 
@@ -288,9 +291,9 @@ The update should explain briefly:
 - When Claude should consult each one
 - That these documents form the constitutional baseline for future AKILI-SPECS work
 - How module specs should be organized under `docs/specs/`
-- Which skills should be used for common work in the project
+- Which skills should be used for common work in the project (the `## Skill Map` added in Step 8D)
 - Whether CodeGraph is initialized and how agents should use it for existing-project analysis
-- Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 7C)
+- Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 8C)
 
 Preserve the repository's existing `CLAUDE.md` and `AGENTS.md` conventions and extend them.
 
@@ -378,27 +381,114 @@ project guides so the project does not depend on the package's `docs/` after ins
    must differ from the Implementer model. `/akili-test` is likewise split into its Leader (T5,
    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`.
-   Fill the Claude Code column for the user's plan (e.g. PRO: Opus reserved for T1/T3, Sonnet as the
-   T2/T4/T6 workhorse, Haiku for T5). Fill the OpenCode column from the user's confirmed roster; if
-   it is unknown, leave clearly-marked `<CONFIRM SLUG>` placeholders rather than guessing.
-5. The instruction: *"To change models, edit only this registry table. Model selection is guidance
-   only — never add `model:` to command frontmatter."*
-
-**Mode-specific policy (mirror Step 7B):**
+4. The editable model registry table with columns `Tier | Claude Code | OpenCode | Fallback`, plus
+   an `Updated: <YYYY-MM>` stamp. **Alias-first rule:** the Claude Code column uses floating aliases
+   (`opus`, `sonnet`, `haiku`) — they always resolve to the latest generation, so the registry
+   survives model churn with zero edits; pin a dated model ID only when the user deliberately wants
+   to freeze a version, and record why. Fill the OpenCode column from the user's confirmed roster
+   (slugs are concrete — no alias mechanism); if it is unknown, leave clearly-marked
+   `<CONFIRM SLUG>` placeholders rather than guessing.
+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."*
+
+**Mode-specific policy (mirror Step 8B):**
 
 - **Brand-new (Seed Setup):** insert the full `## Model Routing` section using the packaged defaults.
 - **Legacy (Discovery Setup):** insert the section and, where detected, annotate the registry with
   the project's actual tooling (e.g. note if the team already standardizes on a specific model).
 - **Active AKILI-SPECS (Safe Update):** **do not overwrite** an existing customized registry. If the section
   is missing, add it; if it exists, only fill gaps (missing tiers, missing author ≠ auditor note)
-  without changing the user's pinned models.
+  without changing the user's pinned models. Additionally, **flag stale entries**: compare the
+  project registry against the packaged default in `docs/model-routing.md` and list (do not edit)
+  entries that name models the tool no longer offers or dated pins that an alias would now cover —
+  the user decides whether to refresh them.
 
 Confirm the user's available models before writing concrete identifiers: which tier they run in
 Claude Code (and their plan's rate limits) and which models their OpenCode roster exposes.
 
 ---
 
+### Step 8D: Scaffold the Skill Map
+
+Add or upgrade a `## Skill Map` section in the project's root `AGENTS.md` **and** `CLAUDE.md` so the
+project declares which stack-dependent skills apply to it. AKILI binds skills at three levels
+(see the packaged `docs/skills/governance.md`): `core` and `conditional` skills are already wired
+into the command prompts; **`stack` skills are never hard-referenced by commands** — this Skill Map
+is how they reach the agents.
+
+**The scaffolded `## Skill Map` section must contain:**
+
+1. A table `Skill | Applies To | When to load` listing only the stack skills that match the
+   detected or declared stack. Candidates shipped with AKILI: `angular-developer`, `nestjs-expert`,
+   `shadcn-ui`, `tailwind-design-system`, `react-doctor`, `vercel-react-best-practices`,
+   `aws-serverless`, `api-design-principles`, `error-handling-patterns`. Projects may add their own.
+2. The instruction: *"During `/akili-specify`, derive each task's required skills from this map.
+   During `/akili-execute` and `/akili-test`, the Leader assigns these skills and the
+   Implementer/Tester must load them before writing code or tests."*
+
+**Mode-specific policy (mirror Step 8B):**
+
+- **Brand-new (Seed Setup):** build the map from the seed intent's declared stack.
+- **Legacy (Discovery Setup):** build the map from the codebase scan evidence (frameworks, UI
+  library, cloud tooling actually present). Do not list skills for frameworks the repo does not use.
+- **Active AKILI-SPECS (Safe Update):** preserve an existing customized map; only add rows for
+  newly detected stack elements and remove rows the user confirms are obsolete.
+
+---
+
+### Step 8E: Bind Personas to Models (Tool-Native Agent Wrappers)
+
+Offer to generate **tool-native agent definitions** that bind the `.agents/` personas to the models
+in the `## Model Routing` registry (Step 8C). This turns model routing from guidance into
+enforcement for the multi-agent fan-out — where most tokens are spent — and makes
+**author ≠ auditor structural**: the Reviewer wrapper is pinned to a different model than the
+Implementer wrapper in configuration, not by human discipline.
+
+Ask the user first (one question): *"Bind the AKILI personas to models with native agent wrappers,
+so the Implementer/Reviewer/Tester automatically run on their tier's model?"* If declined, skip
+this step — the guidance-only flow keeps working.
+
+**Per tool:**
+
+- **Claude Code:** create project-level `.claude/agents/akili-leader.md`, `akili-implementer.md`,
+  `akili-reviewer.md`, and `akili-tester.md`. Each wrapper is thin:
+
+  ```markdown
+  ---
+  name: akili-implementer
+  description: AKILI Implementer — executes one spec task with strict scope and verification.
+  model: sonnet
+  ---
+  Read `.agents/implementer.md` in the project root and adopt it fully as your persona and
+  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.
+
+- **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`).
+
+- **Google Antigravity:** no per-agent model binding exists — skip wrapper generation and note in
+  the summary that Antigravity stays on guidance-only routing.
+
+**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.
+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).
+3. **Mode policy:** Brand-new/Legacy — create the wrappers when accepted. Active AKILI-SPECS —
+   never overwrite existing wrapper files; create only missing ones and flag model drift between
+   existing wrappers and the current registry.
+
+---
+
 ### Step 9: Present and Confirm
 
 After drafting or enhancing the documents, generate a short, easy-to-understand summary (summary facil de entender de lo que se hizo) covering:
@@ -420,7 +510,7 @@ Ask the user whether to approve or request changes. If changes are requested, re
 
 ## Outcome
 
-At the end of `/akili-constitution`, the repository should have a project-level baseline that future `/akili-specify`, `/akili-execute`, `/akili-validate`, and `/akili-test` work can rely on without guessing the structure or conventions. The `.agents/` personas must be in place so that `/akili-execute` can run the Leader → Implementer → Reviewer rework loop and `/akili-test` can run the Leader → Tester(s) harness without falling back to inline personas. The root guides must also carry a `## Model Routing` registry (Step 8C) so each phase runs on a model matched to its demand, with the Reviewer on a different model than the Implementer.
+At the end of `/akili-constitution`, the repository should have a project-level baseline that future `/akili-specify`, `/akili-execute`, `/akili-validate`, and `/akili-test` work can rely on without guessing the structure or conventions. The `.agents/` personas must be in place so that `/akili-execute` can run the Leader → Implementer → Reviewer rework loop and `/akili-test` can run the Leader → Tester(s) harness without falling back to inline personas. The root guides must also carry a `## Model Routing` registry (Step 8C) so each phase runs on a model matched to its demand, with the Reviewer on a different model than the Implementer, and a `## Skill Map` (Step 8D) so stack-dependent skills reach the agents without being hardcoded into commands.
 
 ---
 

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

@@ -52,8 +52,8 @@ If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not
 
 **Delegation mechanism by tool:**
 
-- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
-- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/`.
+- **Claude Code / OpenCode:** if the project has tool-native AKILI agent wrappers (scaffolded by `/akili-constitution` Step 8E — e.g. `.claude/agents/akili-implementer.md` / `akili-reviewer.md` with `model:` bindings from the `## Model Routing` registry), **spawn those named agents** so each role runs on its tier's model and author ≠ auditor is enforced by configuration. Otherwise, spawn a focused subagent (or sub-prompt context) seeded with the persona file plus the task/diff context.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent workflow primitive) using prompts read from `.agents/` (no per-agent model binding — guidance-only routing).
 
 The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
 
@@ -63,6 +63,8 @@ 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.
+
 **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.
 
 1. Read the project constitutional docs (IN THIS ORDER):
@@ -135,7 +137,7 @@ 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`)
+- 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
 - 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

@@ -55,6 +55,8 @@ Do not create `requirements.md`, `design.md`, or `tasks.md` in this command unle
 
 ### Step 0: Resolve Path And Load Context
 
+**Model checkpoint:** This phase runs best on **T1 Architect** (deep reasoning). 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 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.
 
 1. Resolve `$SPEC_PATH` using the path rules above.

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

@@ -60,6 +60,8 @@ State clearly which criterion failed and which command to run instead. Never sil
 
 ### Step 0: Load Minimal Context
 
+**Model checkpoint:** This phase runs best on **T2 Coder** (small direct edit, light verification). 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 T2 — the registry recommends `/model sonnet`; 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.
+
 Keep context small — this is a trivial change, not a full spec run.
 
 1. Read only what the change needs:

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

@@ -74,6 +74,8 @@ If any prerequisite is missing, stop and report exactly what is missing and how
 
 ### Phase 0: Setup
 
+**Model checkpoint:** This phase runs best on **T3 Auditor** for audit findings and **T5 Fast-Cheap** for setup/formatting. 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 audit phase is T3 — 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.
+
 1. Resolve the spec path. If `$ARGUMENTS` is a bare domain, set `SPEC_PATH = seo/<domain>`. Otherwise treat `$ARGUMENTS` as the literal spec path.
 2. Create directory `docs/specs/$SPEC_PATH/` if it does not exist.
 3. Read the constitutional templates and project context as defined in `akili-specify`:

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

@@ -61,6 +61,8 @@ 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.
+
 **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.
 
 1. Create directory `docs/specs/$ARGUMENTS/` if it does not exist.
@@ -182,7 +184,9 @@ If the work includes meaningful UI/UX impact, use this skill preference:
 - `ui-ux-pro-max` if available
 - otherwise `frontend-design` + `stitch-design`
 
-Use additional technical skills as needed:
+If the work involves animation (scroll effects, transitions, motion design), load `gsap-animation` and read the reference file matching the task.
+
+Use additional stack skills as needed — prefer the project's `## Skill Map` (in root `AGENTS.md`/`CLAUDE.md`) when it exists; otherwise pick from:
 
 - `nestjs-expert`
 - `api-design-principles`
@@ -191,6 +195,7 @@ Use additional technical skills as needed:
 - `vercel-react-best-practices`
 - `error-handling-patterns`
 - `aws-serverless`
+- `angular-developer`
 
 #### Step 2.2 — Write
 
@@ -269,7 +274,7 @@ Each task should include:
 - done criteria
 - relevant skills
 
-Skill inventory should use real, available skills only.
+Skill inventory should use real, available skills only. Derive each task's required skills from the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) plus the conditional skills that match the task (`ui-ux-pro-max`/`frontend-design` for UI, `gsap-animation` for animation).
 
 Task quality rules:
 

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

@@ -50,8 +50,8 @@ If `.agents/tester.md` is missing, run `/akili-constitution` first to scaffold i
 
 **Delegation mechanism by tool:**
 
-- **Claude Code / OpenCode:** spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
-- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md`.
+- **Claude Code / OpenCode:** if the project has a tool-native `akili-tester` agent wrapper (scaffolded by `/akili-constitution` Step 8E with a `model:` binding from the `## Model Routing` registry), **spawn that named agent** so each Tester runs on its tier's model — preferring a model different from the Implementer's (author ≠ tester). Otherwise, spawn a focused subagent (or sub-prompt context) seeded with `tester.md` plus the suite's context slice.
+- **Google Antigravity:** invoke `invoke_subagent` (or the equivalent) using the prompt read from `.agents/tester.md` (no per-agent model binding — guidance-only routing).
 
 **Token discipline — thin context per Tester (this is the core saving):**
 
@@ -76,6 +76,8 @@ 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.
+
 **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.
 
 1. Read project-level context (IN THIS ORDER):

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

@@ -49,6 +49,8 @@ Use these result levels consistently:
 
 ### Phase 0: Load Context
 
+**Model checkpoint:** This phase runs best on **T3 Auditor** — and it MUST resolve to a different model than the one that implemented the work (author ≠ auditor). 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 T3 — the registry recommends `/model opus`; you are on sonnet, which also implemented the spec"* — 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.
 
 1. Read constitutional context (IN THIS ORDER):

package/.claude/skills/angular-developer/SKILL.md

@@ -4,6 +4,10 @@ description: Generates Angular code and provides architectural guidance. Trigger
 license: MIT
 metadata:
   author: Copyright 2026 Google LLC
+  source: https://angular.dev
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
   version: '1.0'
 ---
 

package/.claude/skills/api-design-principles/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: api-design-principles
 description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
+license: MIT
+metadata:
+  author: Seth Hobson (wshobson)
+  source: https://github.com/wshobson/agents
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
+  version: "1.0"
 ---
 
 # API Design Principles

package/.claude/skills/aws-serverless/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: aws-serverless
 description: "Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start optimization."
-source: vibeship-spawner-skills (Apache 2.0)
+license: Apache-2.0
+metadata:
+  author: vibeship
+  source: vibeship-spawner-skills (Apache 2.0)
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
+  version: "1.0"
 ---
 
 # AWS Serverless

package/.claude/skills/brainstorming/SKILL.md

@@ -1,8 +1,32 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. In AKILI-SPECS projects, follow the AKILI-SPECS Integration section first."
+license: MIT
+metadata:
+  author: Jesse Vincent (obra)
+  source: https://github.com/obra/superpowers
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core
+  version: "1.0"
 ---
 
+## AKILI-SPECS Integration
+
+When this skill is loaded inside the AKILI-SPECS methodology, this section overrides the generic flow below:
+
+| AKILI moment | How to use this skill |
+|---|---|
+| `/akili-constitution` Step 0 | Ask the new-vs-existing project question and clarify seed intent |
+| `/akili-propose` | Explore intent, scope, options, and trade-offs before writing `proposal.md` |
+| `/akili-specify` Phases 1–3 | Clarify problem/actors (requirements), explore trade-offs (design), sequence work (tasks) |
+
+Adaptation rules:
+
+- **Artifacts land in AKILI documents** — `proposal.md`, `requirements.md`, `design.md`, `tasks.md` under `docs/specs/`. Do NOT write `docs/plans/*-design.md`.
+- **The terminal state is the AKILI phase you are in**, not the `writing-plans` skill (it is not packaged here). After approval, continue the active AKILI command's next step.
+- The HARD-GATE still applies: no implementation before the user approves the design.
+
 # Brainstorming Ideas Into Designs
 
 ## Overview

package/.claude/skills/cognitive-doc-design/SKILL.md

@@ -4,6 +4,9 @@ description: "Design docs that reduce cognitive load. Trigger: writing guides, R
 license: Apache-2.0
 metadata:
   author: gentleman-programming
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core
   version: "1.0"
 ---
 
@@ -18,6 +21,17 @@ Use it especially for:
 - Architecture, workflow, or onboarding docs.
 - Any doc that currently feels long, dense, or hard to scan.
 
+## AKILI-SPECS Integration
+
+| AKILI moment | Documents written with this skill |
+|---|---|
+| `/akili-constitution` | `docs/prd.md` and the baseline docs |
+| `/akili-specify` | `requirements.md`, `design.md`, `tasks.md` |
+| `/akili-execute` | PR descriptions and review notes (PR and Review Docs section below) |
+| `/akili-archive` | The archive summary and Kaizen log entries |
+
+The AKILI templates in `docs/specs/general-setup/` win over the default Documentation Shape below — apply the Critical Patterns inside their structure.
+
 ## Critical Patterns
 
 | Pattern | Rule |

package/.claude/skills/error-handling-patterns/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: error-handling-patterns
 description: Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability.
+license: MIT
+metadata:
+  author: Seth Hobson (wshobson)
+  source: https://github.com/wshobson/agents
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
+  version: "1.0"
 ---
 
 # Error Handling Patterns

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

@@ -1,7 +1,14 @@
 ---
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboards, or frontend applications.
-license: Complete terms in LICENSE.txt
+license: Complete terms in LICENSE.txt (Apache-2.0)
+metadata:
+  author: Anthropic
+  source: https://github.com/anthropics/skills
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: conditional
+  version: "1.0"
 ---
 
 # Frontend Design (Distinctive, Production-Grade)