akili-specs 2.7.1 → 2.9.0

package/.claude/skills/seo-audit/SKILL.md

@@ -1,7 +1,13 @@
 ---
 name: seo-audit
-description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema. For AI search optimization, see ai-seo.
+description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. In AKILI-SPECS projects, /akili-seo loads this skill in its audit phase.
+license: MIT
 metadata:
+  author: Corey Haines (coreyhaines31)
+  source: https://github.com/coreyhaines31/marketingskills
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core
   version: 2.0.0
 ---
 
@@ -453,7 +459,6 @@ Same format as above
 
 - [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
 - [International SEO](references/international-seo.md): Evidence and sources for hreflang, canonical + i18n, sitemaps, URL structure, and content quality across locales
-- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the **ai-seo** skill
 
 ---
 
@@ -487,11 +492,15 @@ Same format as above
 
 ---
 
-## Related Skills
+## AKILI-SPECS Integration
 
-- **ai-seo**: For optimizing content for AI search engines (AEO, GEO, LLMO)
-- **programmatic-seo**: For building SEO pages at scale
-- **site-architecture**: For page hierarchy, navigation design, and URL structure
-- **schema**: For implementing structured data
-- **cro**: For optimizing pages for conversion (not just ranking)
-- **analytics**: For measuring SEO performance
+| AKILI moment | How to use this skill |
+|---|---|
+| `/akili-seo` audit phase | Required skill — load before starting and apply throughout; the Audit Report Structure above is the finding format |
+| `/akili-validate` | When validating pages with search-visibility requirements, apply the On-Page checklist to the affected routes |
+
+Adaptation rules:
+
+- Findings land in the AKILI report artifacts (`/akili-seo` output), using the Issue / Impact / Evidence / Fix / Priority shape.
+- Fixes that exceed the trivial gate are routed through `/akili-propose` — never applied silently during the audit.
+- Sibling skills mentioned by upstream versions of this skill (programmatic-seo, schema, ai-seo, cro, analytics) are **not packaged** with AKILI-SPECS; when a finding needs them, note the gap in the report instead of loading them.

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

@@ -2,6 +2,12 @@
 name: shadcn-ui
 description: Provides complete shadcn/ui component library patterns including installation, configuration, and implementation of accessible React components. Use when setting up shadcn/ui, installing components, building forms with React Hook Form and Zod, customizing themes with Tailwind CSS, or implementing UI patterns like buttons, dialogs, dropdowns, tables, and complex form layouts.
 allowed-tools: Read, Write, Bash, Edit, Glob
+metadata:
+  author: community (origin unverified)
+  curated-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
+  version: "1.0"
 ---
 
 # shadcn/ui Component Patterns

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

@@ -5,6 +5,13 @@ allowed-tools:
   - "StitchMCP"
   - "Read"
   - "Write"
+metadata:
+  author: Google (google-labs-code)
+  source: https://github.com/google-labs-code/stitch-skills
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: conditional
+  version: "1.0"
 ---
 
 # Stitch Design Expert

package/.claude/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: systematic-debugging
 description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+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"
 ---
 
 # Systematic Debugging
@@ -287,6 +295,19 @@ These techniques are part of systematic debugging and available in this director
 - **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
 - **superpowers:verification-before-completion** - Verify fix worked before claiming success
 
+These `superpowers:*` skills are not packaged with AKILI-SPECS. In AKILI projects, their role is covered by the methodology itself: the regression test comes from `/akili-specify` Bug Mode (red before the fix, green after), and verification comes from each task's verification command plus the Reviewer/Tester gates.
+
+## AKILI-SPECS Integration
+
+| AKILI moment | How to use this skill |
+|---|---|
+| `/akili-propose` Bug Track | Confirm reproduction + root cause and record them in the proposal's **Bug Diagnosis** section — never propose a fix for a guessed cause |
+| `/akili-specify` Bug Mode | If no proposal exists, run root-cause investigation before writing the fix plan |
+| `/akili-test` | When a Tester reports `PRODUCT_BUG`, apply Phases 1–3 to characterize the defect before any fix is planned; the test stays red |
+| `/akili-validate` / `/akili-seo` | Investigate mismatches and failures with this process before recommending corrections |
+
+The root cause and its evidence feed `/akili-archive`'s Kaizen retrospective (5W1H) — a lesson without a confirmed root cause is not recorded.
+
 ## Real-World Impact
 
 From debugging sessions:

package/.claude/skills/tailwind-design-system/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: tailwind-design-system
 description: Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.
+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"
 ---
 
 # Tailwind Design System (v4)

package/.claude/skills/ui-ux-pro-max/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: ui-ux-pro-max
 description: "UI/UX design intelligence. 67 styles, 96 palettes, 57 font pairings, 25 charts, 13 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples."
+license: MIT
+metadata:
+  author: nextlevelbuilder
+  source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: conditional
+  version: "1.0"
 ---
 # UI/UX Pro Max - Design Intelligence
 
@@ -15,6 +23,19 @@ Reference these guidelines when:
 - Building landing pages or dashboards
 - Implementing accessibility requirements
 
+## AKILI-SPECS Integration
+
+This is AKILI's preferred UI/UX skill — commands reference it as "`ui-ux-pro-max` if available" (fallback: `frontend-design` + `stitch-design`).
+
+| AKILI moment | How to use this skill |
+|---|---|
+| `/akili-constitution` Step 4 | Drive `docs/ux-ui/design.md`: design tokens, palettes, typography, accessibility expectations |
+| `/akili-specify` design phase | Shape UI states, responsive behavior, and component architecture in `design.md` |
+| `/akili-execute` UI tasks | The Implementer loads it for UI-heavy tasks listed in `tasks.md` |
+| `/akili-test` / `/akili-validate` | The Tester/validator checks accessibility and UX rules (priority 1–4 categories) against the built screens |
+
+Design-token decisions made with this skill are recorded in `docs/ux-ui/design.md` — the Reviewer audits diffs against that document, not against this skill.
+
 ## Rule Categories by Priority
 
 | Priority | Category | Impact | Domain |

package/.claude/skills/vercel-react-best-practices/SKILL.md

@@ -4,6 +4,9 @@ description: React and Next.js performance optimization guidelines from Vercel E
 license: MIT
 metadata:
   author: vercel
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: stack
   version: "1.0.0"
 ---
 

package/.claude/templates/leader.md

@@ -21,7 +21,7 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
    * 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`).
+   * 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`).
    * 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`.

package/CHANGELOG.md

@@ -10,6 +10,37 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.9.0] - 2026-07-20
+
+### Added
+
+- **Model Routing 2.0 — enforced for subagents, guided for the main loop:**
+  - **Tool-native agent wrappers (`/akili-constitution` Step 8E):** with user approval, the constitution now binds the `.agents/` personas to the Model Routing registry via native agent definitions — `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code (alias-based `model:`) and agent config in OpenCode (provider slugs). `/akili-execute` and `/akili-test` prefer these named agents, so the multi-agent fan-out (where most tokens are spent) routes automatically and **author ≠ auditor becomes structural** — the Reviewer wrapper pins a different model than the Implementer wrapper. Wrappers are thin references to `.agents/`; personas remain the single source of truth. Antigravity stays guidance-only (no per-agent model binding).
+  - **Model checkpoints in every command:** all 10 commands (`propose`, `specify`, `execute`, `test`, `validate`, `archive`, `audit`, `quick`, `seo`, `constitution`) perform a one-line, never-blocking check during setup — if the phase's tier maps to a different model than the current session, the user is told (e.g. "This phase is T1 — the registry recommends `/model opus`") and offered the switch at the first approval pause.
+  - **Model Registry Drift check in `/akili-audit`:** new drift category and Conformance Matrix row — registry entries naming models the tool no longer offers, dated pins where a floating alias exists, missing tiers/author ≠ auditor notes versus the packaged default, and Step 8E wrappers contradicting the registry. Report-only.
+
+### Changed
+
+- **Alias-first model registry (survives model churn):** `docs/model-routing.md` and the Step 8C scaffold now mandate floating aliases (`opus`/`sonnet`/`haiku` in Claude Code — they always resolve to the latest generation, so new model families require zero registry edits); dated model pins require a recorded reason. The default registry was rewritten alias-first with an `Updated:` stamp; OpenCode slugs (no alias mechanism) keep the Fallback column and are covered by the drift check. Safe Update mode now also flags stale registry entries against the packaged default without touching user pins.
+## [2.8.0] - 2026-07-20
+
+### Added
+
+- **Skill governance (binding taxonomy + acceptance checklist):** new `docs/skills/governance.md` establishes the curation rule for the packaged skill set. Every skill now declares `metadata.binding` — `core` (hard-wired to a command step), `conditional` (loaded when the work touches its domain), or `stack` (never referenced in command text; reaches agents via the project Skill Map) — plus original author/license and `adapted-by`. New skills enter only through the acceptance checklist (need + binding + attribution + size + docs/CHANGELOG).
+- **Project Skill Map:** `/akili-constitution` Step 8D scaffolds a `## Skill Map` section into the project's root `AGENTS.md`/`CLAUDE.md` from the detected stack; `/akili-specify` derives each task's required skills from that map, and the `/akili-execute` Leader falls back to it when a task lists no skills.
+- **New unified `gsap-animation` skill** (author GSAP/GreenSock, MIT; adapted for AKILI-SPECS): replaces the 8 sibling `gsap-*` skills with one conditional skill — a compact router `SKILL.md` plus `references/` files (timeline, scrolltrigger, plugins, react, frameworks, performance, utils) following progressive disclosure. Wired into `/akili-specify` and `/akili-execute` for animation work.
+- **AKILI-SPECS Integration sections** added to the deeply-wired skills: `brainstorming` (AKILI artifacts override its generic `docs/plans/` flow), `judgment-day` (ledger persisted as `judgment.md` in the spec folder, author ≠ auditor note), `cognitive-doc-design` (document map per command), `systematic-debugging` (Bug Track / Bug Mode / PRODUCT_BUG / Kaizen 5W1H mapping), `seo-audit` (finding format + escalation rule), and `ui-ux-pro-max` (per-phase usage map).
+
+### Changed
+
+- **Skill attribution normalized across the package:** every kept skill's frontmatter now carries the standard schema (`license`, `metadata.author`, `source`, `adapted-by`, `adapted-for`, `binding`, `version`), preserving original authors — including newly researched attributions: `ui-ux-pro-max` → nextlevelbuilder, `seo-audit` → Corey Haines, `brainstorming` → Jesse Vincent (obra/superpowers), `nestjs-expert` → Daniel Avila, `react-doctor` → Million.dev, `stitch-design` → Google Labs, `product-manager-toolkit` → Alireza Rezvani, `api-design-principles`/`error-handling-patterns`/`tailwind-design-system` → Seth Hobson (wshobson/agents), `frontend-design` → Anthropic — plus the already-attributed Google, Vercel, GSAP, gentleman-programming, and vibeship. Only `shadcn-ui` remains `community (origin unverified)`.
+- **Truthful skill inventory:** `docs/skills/README.md` rebuilt with Binding and Origin columns and command associations that match the real command wiring (the previous table claimed command integrations that did not exist for `angular-developer` and the `gsap-*` family).
+- **`angular-developer` reclassified as a stack skill:** kept in the package, reachable via the project Skill Map and the constitution/specify stack lists (previously packaged but never referenced anywhere).
+- **Dangling references removed:** `seo-audit` no longer points to unpackaged sibling skills (`programmatic-seo`, `schema`, `ai-seo`, `cro`, `analytics`); `judgment-day` documents the fallback for its unpackaged shared-ledger references.
+
+### Removed
+
+- **The 8 `gsap-*` skill directories and their doc pages** (`gsap-core`, `gsap-frameworks`, `gsap-performance`, `gsap-plugins`, `gsap-react`, `gsap-scrolltrigger`, `gsap-timeline`, `gsap-utils`), fused into `gsap-animation`. **Existing installs are migrated automatically:** the installer's legacy cleanup now also removes stale legacy skill directories on every `akili install` run (counted in the `legacy cleaned` summary column, previewed in `--dry-run`), and `akili doctor` reports them as `STALE` with `--fix` removing them. Upgrade path for existing users: `akili update` (or `npm i -g akili-specs`) then `akili install --tool <tool>` — old gsap-* dirs are deleted and `gsap-animation` is installed in the same run.
 ## [2.7.1] - 2026-07-20
 
 ### Added

package/README.md

@@ -82,14 +82,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `cognitive-doc-design`
   - `error-handling-patterns`
   - `frontend-design`
-  - `gsap-core`
-  - `gsap-frameworks`
-  - `gsap-performance`
-  - `gsap-plugins`
-  - `gsap-react`
-  - `gsap-scrolltrigger`
-  - `gsap-timeline`
-  - `gsap-utils`
+  - `gsap-animation`
   - `judgment-day`
   - `kaizen`
   - `nestjs-expert`
@@ -746,6 +739,8 @@ Fallback rule:
 
 - when `ui-ux-pro-max` is unavailable, use `frontend-design` + `stitch-design` for UX/UI design work and `frontend-design` for UI validation/testing support.
 
+**Skill governance:** the skill set is curated, not accumulated. Every packaged skill declares its original author and license plus how AKILI binds it into the flow (`core` — hard-wired to a command step; `conditional` — loaded when the work touches its domain; `stack` — selected per project via the `## Skill Map` that `/akili-constitution` writes into the project guides). New skills enter only through the acceptance checklist in [docs/skills/governance.md](docs/skills/governance.md). Curation and adaptation by [Juan Carlos Cadavid](https://jcadavid.com), always preserving original authorship.
+
 ## Methodology Contract
 
 - **User-Facing Summaries:** All major commands (`/akili-propose`, `/akili-specify`, `/akili-execute`, `/akili-validate`, `/akili-test`, `/akili-constitution`) generate a short, digestible summary on the screen before proceeding to the next step, ensuring developers always understand what the agent just did.

package/bin/akili.js

@@ -14,6 +14,18 @@ const SOURCE_SKILLS = path.join(SOURCE_CLAUDE, "skills");
 const SOURCE_TEMPLATES = path.join(SOURCE_CLAUDE, "templates");
 const AGENT_TEMPLATES = ["leader.md", "implementer.md", "reviewer.md", "tester.md"];
 const RESOURCE_SCRIPTS = ["gsc_verify.py", "parse_tests.js"];
+// Skill directories removed from the package; deleted from installs during legacy cleanup.
+// v2.8.0: the 8 gsap-* skills were fused into the single gsap-animation skill.
+const LEGACY_SKILLS = [
+  "gsap-core",
+  "gsap-frameworks",
+  "gsap-performance",
+  "gsap-plugins",
+  "gsap-react",
+  "gsap-scrolltrigger",
+  "gsap-timeline",
+  "gsap-utils",
+];
 const SOURCE_SCRIPTS = path.join(PACKAGE_ROOT, "scripts");
 const SOURCE_MCP_EXAMPLE = path.join(PACKAGE_ROOT, ".mcp.json.example");
 const BANNER = ` █████╗ ██╗  ██╗██╗██╗     ██╗
@@ -316,6 +328,21 @@ function cleanupLegacyFiles(tool, args) {
     }
   }
 
+  if (shouldInclude("skills", args)) {
+    for (const skillName of LEGACY_SKILLS) {
+      const skillDir = path.join(paths.skills, skillName);
+      if (fs.existsSync(skillDir)) {
+        if (args.dryRun) {
+          console.log(`  ${colors.red}would delete legacy skill${colors.reset} ${skillDir}`);
+        } else {
+          fs.rmSync(skillDir, { recursive: true, force: true });
+          console.log(`  ${colors.red}deleted legacy skill${colors.reset} ${skillDir}`);
+        }
+        cleaned++;
+      }
+    }
+  }
+
   if (shouldInclude("resources", args)) {
     if (paths.legacyResources && fs.existsSync(paths.legacyResources)) {
       if (args.dryRun) {
@@ -677,6 +704,19 @@ function doctorTool(tool, args) {
         }
       }
     }
+    for (const skillName of LEGACY_SKILLS) {
+      const skillDir = path.join(paths.skills, skillName);
+      if (fs.existsSync(skillDir)) {
+        if (args.fix) {
+          fs.rmSync(skillDir, { recursive: true, force: true });
+          console.log(`  ${colors.cyan}REMOVED${colors.reset} ${skillName} (legacy, replaced by gsap-animation)`);
+          fixed += 1;
+        } else {
+          console.log(`  ${colors.red}STALE${colors.reset} ${skillName} (legacy, replaced by gsap-animation — run with --fix or akili update to remove)`);
+          missing += 1;
+        }
+      }
+    }
   }
 
   if (shouldInclude("resources", args)) {

package/docs/cli.md

@@ -58,7 +58,7 @@ akili install --tool both --local
 
 Every command closes with a clear end-of-run summary:
 
-- **`install`** — an **Install Summary** with per-tool `installed | overwritten | skipped` counts (plus legacy cleanup), target paths, totals for multi-tool installs, a dry-run banner when `--dry-run` is used, and contextual next steps (`--force` hint, OpenCode restart, `akili doctor` verification).
+- **`install`** — an **Install Summary** with per-tool `installed | overwritten | skipped` counts (plus legacy cleanup), target paths, totals for multi-tool installs, a dry-run banner when `--dry-run` is used, and contextual next steps (`--force` hint, OpenCode restart, `akili doctor` verification). Legacy cleanup removes artifacts from older versions on every run: `sdd-*` command files, the `sdd-jc` resources directory, and skill directories that were removed from the package (e.g. the 8 `gsap-*` skills replaced by `gsap-animation`); `akili doctor` reports still-present legacy skills as `STALE` and `--fix` deletes them.
 - **`doctor`** — a **Doctor Summary** with a per-tool `HEALTHY | REPAIRED | INCOMPLETE` status, `ok | missing | fixed` counts, and repair suggestions (`--fix` or `akili update`).
 - **`update`** — an **Update Summary** with the version change (`before → after`), install type, and the verification command, after the changelog of what changed.
 - **`list`** — a totals line: commands, skills, resources, and the package version.

package/docs/commands/akili-constitution.md

@@ -63,19 +63,23 @@ The `.agents/` directory is tool-agnostic: pure Markdown + YAML frontmatter, res
 
 ## Model Routing Scaffolding
 
-Step 7C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode). It is guidance only — no `model:` frontmatter is added and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved and only gaps are filled. See [Model Routing](../model-routing.md) for the tiers and the default registry.
-
-- `product-manager-toolkit`
-- `ui-ux-pro-max`
-- `frontend-design`
-- `stitch-design`
-- `nestjs-expert`
-- `api-design-principles`
-- `error-handling-patterns`
-- `aws-serverless`
-- `shadcn-ui`
-- `tailwind-design-system`
-- `vercel-react-best-practices`
+Step 8C adds or upgrades a `## Model Routing` section in the project's root `AGENTS.md` and `CLAUDE.md`: a capability-tier registry that maps each AKILI-SPECS phase to a model **per tool** (Claude Code and OpenCode), following the **alias-first rule** (floating aliases like `opus`/`sonnet`/`haiku` wherever they exist, so the registry survives model generations without edits). No `model:` frontmatter is added to commands and the installer is unchanged. The registry enforces **author ≠ auditor** (the Reviewer runs on a different model than the Implementer) and, in Active-AKILI-SPECS mode, is non-destructive: an existing customized registry is preserved, gaps are filled, and stale entries are flagged against the packaged default without touching user pins. See [Model Routing](../model-routing.md) for the tiers and the default registry.
+
+## Model Binding Scaffolding (Tool-Native Agent Wrappers)
+
+Step 8E (with the user's approval) binds the `.agents/` personas to the registry's models via **tool-native agent definitions**: `.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code (alias-based `model:` frontmatter) and the equivalent agent config in OpenCode (provider slugs). The wrappers are thin — they reference the `.agents/` persona instead of duplicating it — and make model routing **enforced** for the `/akili-execute` and `/akili-test` fan-out, including a structural author ≠ auditor guarantee (the Reviewer wrapper pins a different model than the Implementer wrapper). Antigravity has no per-agent model binding and stays guidance-only. In Active-AKILI-SPECS mode existing wrappers are never overwritten.
+
+## Skill Map Scaffolding
+
+Step 8D adds or upgrades a `## Skill Map` section in the project's root `AGENTS.md` and `CLAUDE.md`: a table of the **stack-bound skills** that apply to this project's detected or declared stack (see [Skill Governance](../skills/governance.md)). Stack skills are never hardcoded into command text — `/akili-specify` derives each task's required skills from this map, and the `/akili-execute` Leader passes them to the Implementer/Tester via dynamic skill loading. In Active-AKILI-SPECS mode an existing customized map is preserved.
+
+Skills the constitution itself draws on:
+
+- `brainstorming` (Step 0 — project mode and intent)
+- `product-manager-toolkit` (Steps 2–3 — interview script and PRD)
+- `cognitive-doc-design` (all baseline documents)
+- `ui-ux-pro-max`, or `frontend-design` + `stitch-design` (Step 4 — UX/UI design)
+- Stack skills matching the repo (Step 5 TRD and the Skill Map): `nestjs-expert`, `api-design-principles`, `error-handling-patterns`, `aws-serverless`, `shadcn-ui`, `tailwind-design-system`, `vercel-react-best-practices`, `angular-developer`
 
 ## Next Step
 

package/docs/flow.md

@@ -303,11 +303,25 @@ T4 Context-Ingest, T5 Fast-Cheap, T6 Multimodal** — map to the phases:
 | `/akili-audit` | T4 + T3 |
 | `/akili-archive` | T5 |
 
-A single editable registry binds each tier to a concrete model **per tool** (Claude Code and
-OpenCode). `/akili-constitution` (Step 7C) scaffolds a `## Model Routing` copy of that registry into
-the project's `AGENTS.md` / `CLAUDE.md`. It is **guidance only** — no `model:` frontmatter, no
-installer changes — and it enforces **author ≠ auditor** (Reviewer model ≠ Implementer model). See
-[model-routing.md](model-routing.md) for the tiers, principles, and the default registry.
+A single editable registry binds each tier to a model **per tool** (Claude Code and OpenCode),
+using **floating aliases** (`opus`/`sonnet`/`haiku`) wherever they exist so the registry survives
+model generations without edits. `/akili-constitution` (Step 8C) scaffolds a `## Model Routing`
+copy into the project's `AGENTS.md` / `CLAUDE.md`.
+
+Routing operates at two levels:
+
+* **Enforced (subagents):** `/akili-constitution` Step 8E can generate tool-native agent wrappers
+  (`.claude/agents/akili-{leader,implementer,reviewer,tester}.md` in Claude Code, agent config in
+  OpenCode) that pin each persona to its tier's model. `/akili-execute` and `/akili-test` prefer
+  those named agents — so **author ≠ auditor** (Reviewer model ≠ Implementer model) holds by
+  configuration on the fan-out where most tokens are spent.
+* **Guided (main loop):** every command emits a one-line, never-blocking **model checkpoint** in
+  its setup step when the phase's tier maps to a different model than the current session.
+
+No `model:` frontmatter on commands and no installer changes. `/akili-audit` reports **Model
+Registry Drift** (stale model names, dated pins where an alias exists, wrappers contradicting the
+registry). See [model-routing.md](model-routing.md) for the tiers, principles, and the default
+registry.
 
 ### 8. The Kaizen Loop
 
@@ -327,3 +341,23 @@ Juan Carlos Cadavid — jcadavid.com). Every archive runs one bounded pass:
 Lessons target either the **Product** (this project) or the **Methodology** itself — Methodology
 lessons are flagged for upstreaming to the AKILI repository, so the methodology learns from every
 tool built with it. The retrospective never blocks the archive.
+
+### 9. Skill Binding (Governance)
+
+The packaged skills are curated under a three-level binding taxonomy (see `docs/skills/governance.md`),
+which answers *when and how each skill loads*:
+
+* **core** — hard-wired to a precise command step: `kaizen` in `/akili-archive`, `judgment-day` in
+  `/akili-specify`'s Review Design gate, `cognitive-doc-design` for every human-facing document,
+  `brainstorming` for exploration, `product-manager-toolkit` in `/akili-constitution`,
+  `systematic-debugging` in bug flows, `seo-audit` in `/akili-seo`.
+* **conditional** — loaded when the work touches its domain: `ui-ux-pro-max` / `frontend-design` /
+  `stitch-design` for UI work, `gsap-animation` for animation work.
+* **stack** — framework/platform skills (`angular-developer`, `nestjs-expert`, `shadcn-ui`,
+  `aws-serverless`, …) are never hardcoded into commands. `/akili-constitution` Step 8D writes a
+  `## Skill Map` into the project's `AGENTS.md`/`CLAUDE.md` from the detected stack;
+  `/akili-specify` derives each task's required skills from that map; the Leader passes them to the
+  Implementer/Tester via dynamic skill loading.
+
+Every skill preserves its original author and license; AKILI adaptation is recorded as `adapted-by`
+in the skill frontmatter. Curation by Juan Carlos Cadavid — jcadavid.com.

package/docs/model-routing.md

@@ -4,8 +4,17 @@ AKILI is model-agnostic: no command, skill, or persona hardcodes a model. This d
 **human-facing guidance** for choosing which model runs which AKILI-SPECS phase, so each phase runs on a
 model matched to its dominant computational demand rather than one model doing everything.
 
-It is **guidance-first**: you switch models yourself per tool (Claude Code `/model`, OpenCode
-model selector). Nothing here is injected into command frontmatter or the installer — see
+Routing operates at two levels:
+
+- **Enforced (subagents):** `/akili-constitution` Step 8E can bind the Implementer / Reviewer /
+  Tester / Leader personas to models via **tool-native agent definitions** (see
+  [Enforced routing](#enforced-routing-tool-native-agent-bindings)). This is where most tokens are
+  spent and where author ≠ auditor becomes structural instead of aspirational.
+- **Guided (main loop):** the session model can only be switched by you (Claude Code `/model`,
+  OpenCode model selector). Commands emit a one-line **model checkpoint** when the phase's tier
+  points to a different model than the current session, so the switch happens at the right moment.
+
+Nothing here is injected into command frontmatter or the installer — see
 [Cross-Tool Safety](#cross-tool-safety).
 
 ## Philosophy: criteria first, model second
@@ -75,25 +84,35 @@ tier (to the deeper reasoner) to preserve independence.
 ## Model registry
 
 This is the single editable source of truth. Phases reference **tiers**; only this table names
-concrete models. When models change, edit only this table.
+models. When models change, edit only this table. *Registry updated: 2026-07.*
 
-| Tier | Claude Code (PRO) | OpenCode Go | Fallback |
+**Alias-first rule: never pin a dated model name where a floating alias exists.** Claude Code's
+`opus` / `sonnet` / `haiku` aliases always resolve to the latest version of each family — when
+Anthropic ships a new generation, an alias-based registry needs **zero edits**. Pin a dated ID only
+when you deliberately need to freeze a version, and record why next to the pin. OpenCode slugs are
+concrete (no alias mechanism), which is why they carry the Fallback column and the drift check
+below.
+
+| Tier | Claude Code | OpenCode Go | Fallback |
 |---|---|---|---|
-| **T1 Architect** | Opus 4.8 | `opencode-go/kimi-k2.6` | `opencode-go/deepseek-v4-pro` / Sonnet 4.6 |
-| **T2 Coder** | Sonnet 4.6 | `opencode-go/glm-5.1` | Haiku 4.5 / `opencode-go/qwen3.7-max` |
-| **T3 Auditor** | Opus 4.8 *(must differ from T2)* | `opencode-go/deepseek-v4-pro` | Sonnet 4.6 / `opencode-go/kimi-k2.6` |
-| **T4 Context-Ingest** | Sonnet 4.6 (1M context) | `opencode-go/deepseek-v4-flash` | Opus 4.8 / `opencode-go/deepseek-v4-pro` |
-| **T5 Fast-Cheap** | Haiku 4.5 | `opencode-go/deepseek-v4-flash` | Sonnet 4.6 / `opencode-go/mimo-v2.5` |
-| **T6 Multimodal** | Sonnet 4.6 (vision) | `opencode-go/qwen3.7-max` *(weak — prefer Claude/Gemini)* | Opus 4.8 |
+| **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` |
+| **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` |
 
 ### Why these models
 
-**Claude Code (PRO).** Opus 4.8 carries the tightest PRO rate limits, so it is **reserved for
-T1 (propose, specify reasoning) and T3 (validate, review)** — the two phases that most reward deep
-reasoning. **Sonnet 4.6 is the workhorse** for coding (T2), large-context ingestion via its 1M
-window (T4), and vision (T6). **Haiku 4.5** handles fast/cheap formatting, orchestration, and
-summarization (T5). This concentrates scarce Opus budget on architecture and audit and avoids
-exhausting it during execution-heavy work.
+**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
+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:
 
@@ -115,20 +134,69 @@ exhausting it during execution-heavy work.
 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.
 
+## Enforced routing (tool-native agent bindings)
+
+The `/akili-execute` and `/akili-test` fan-out (Implementer, Reviewer, Testers) is where most
+tokens are spent — and a generic subagent **inherits the session model**, which silently breaks
+author ≠ auditor when the whole session runs on one model. Both tools support a `model` field on
+**agent definitions** (never on commands), so `/akili-constitution` Step 8E binds the personas
+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`) |
+| 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
+agent to read and fully adopt the corresponding `.agents/<role>.md` persona. The persona files in
+`.agents/` remain the tool-agnostic source of truth; the wrappers only add the model binding.
+`/akili-execute` and `/akili-test` prefer these named agents when they exist and fall back to
+generic subagents seeded with the persona content when they don't.
+
+**author ≠ auditor becomes structural:** `akili-reviewer` is pinned to a different model than
+`akili-implementer` in the wrapper files themselves — no human discipline required.
+
+## Model checkpoints (main loop)
+
+The session model cannot be switched programmatically, but the agent knows which model it is
+running on. Every AKILI command performs a one-line **model checkpoint** during setup: read the
+project's `## Model Routing` registry, compare the phase's tier to the current session model, and
+if they differ, tell the user in one line (e.g. *"This phase is T1 — the registry recommends
+`/model opus`; you are on haiku"*) and offer the switch in the phase's first HITL pause. The user
+can always continue on the current model; the checkpoint never blocks.
+
+## Surviving model churn
+
+Models change constantly; the design absorbs that at three layers:
+
+1. **Tiers are the stable layer.** Phases map to T1–T6 and never change when models do.
+2. **Aliases are the default.** The Claude column uses floating aliases that track the latest
+   generation automatically (see the alias-first rule above).
+3. **Drift is detected, not discovered.** `/akili-audit` includes a **Model Registry Drift** check
+   (registry entries naming models the tool no longer offers, or a project registry older than the
+   packaged default), and `/akili-constitution` in Safe Update mode flags stale entries against the
+   packaged default without overwriting user pins. Each AKILI release refreshes this document's
+   default registry.
+
 ## How to apply per tool
 
-- **Claude Code (PRO):** switch with `/model` before running a phase — e.g. `/model opus` for
+- **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`. For the `/akili-execute` triad, run the
-  Implementer on Sonnet and the Reviewer on Opus so author ≠ auditor holds.
-- **OpenCode:** select the `opencode-go/...` model for each phase per the registry. Keep the
-  Reviewer/validator on a different model (`deepseek-v4-pro`) than the Implementer (`glm-5.1`).
+  `/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`).
+- **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`).
 
 ## Cross-tool safety
 
-- **No `model:` frontmatter.** Command prompts stay `description:`-only. A single frontmatter value
-  cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`; OpenCode expects
-  `provider/model`), so model choice stays out of the prompts.
+- **No `model:` frontmatter on commands.** Command prompts stay `description:`-only. A single
+  frontmatter value cannot serve both tools anyway (Claude Code expects `opus`/`sonnet`/`haiku`;
+  OpenCode expects `provider/model`), so model choice stays out of the prompts. Model bindings live
+  exclusively in **agent definitions**, which are per-tool, per-project files generated with the
+  user's approval in Step 8E.
 - **No installer changes.** Nothing here is force-injected. `/akili-constitution` scaffolds a project
   copy of this registry into `AGENTS.md` / `CLAUDE.md` as plain Markdown — identical handling across
   Claude Code, OpenCode, and Google Antigravity.