akili-specs 2.7.1 → 2.8.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,25 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [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

@@ -65,17 +65,17 @@ The `.agents/` directory is tool-agnostic: pure Markdown + YAML frontmatter, res
 
 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`
+## 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

@@ -327,3 +327,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/skills/README.md

@@ -4,41 +4,44 @@ AKILI ships Claude/OpenCode skills alongside the slash commands. Skills are load
 
 The installable source files live in `.claude/skills/*/SKILL.md`. These pages are the human-facing reference.
 
+The skill set is **curated, not accumulated**: every skill declares its original author/license and a binding level that says when and how it loads. The rules — binding taxonomy, frontmatter schema, and the acceptance checklist for new skills — live in [governance.md](governance.md). Curation and AKILI adaptation by Juan Carlos Cadavid — jcadavid.com, always preserving original authorship.
+
+| Binding | Meaning |
+|---|---|
+| `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 |
+
 ## Skill Inventory
 
-| Skill | Use For | Common Commands |
-|---|---|---|
-| [`angular-developer`](angular-developer.md) | Angular architecture, components, services, signals, forms, routing, testing, CLI | `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
-| [`api-design-principles`](api-design-principles.md) | REST and GraphQL API design and review | `/akili-constitution`, `/akili-specify`, `/akili-validate` |
-| [`aws-serverless`](aws-serverless.md) | Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK | `/akili-constitution`, `/akili-specify`, `/akili-execute` |
-| [`brainstorming`](brainstorming.md) | Clarifying ideas, scope, options, and trade-offs before implementation | `/akili-propose`, `/akili-specify` |
-| [`cognitive-doc-design`](cognitive-doc-design.md) | Writing human-facing docs that reduce cognitive load (lead with the answer, progressive disclosure, tables over prose) | `/akili-constitution`, `/akili-specify`, `/akili-execute` (PR docs), `/akili-archive` |
-| [`error-handling-patterns`](error-handling-patterns.md) | Exceptions, Result patterns, graceful degradation, reliability | `/akili-specify`, `/akili-execute`, `/akili-validate` |
-| [`frontend-design`](frontend-design.md) | Distinctive frontend UI and UX implementation | `/akili-constitution`, `/akili-specify`, `/akili-execute`, `/akili-test` |
-| [`gsap-core`](gsap-core.md) | Core GSAP tweens, easing, stagger, responsive and reduced-motion animation | `/akili-specify`, `/akili-execute` |
-| [`gsap-frameworks`](gsap-frameworks.md) | GSAP in Vue, Nuxt, Svelte, SvelteKit, and other non-React frameworks | `/akili-specify`, `/akili-execute` |
-| [`gsap-performance`](gsap-performance.md) | Smooth animation, transform-first motion, jank reduction | `/akili-execute`, `/akili-validate` |
-| [`gsap-plugins`](gsap-plugins.md) | GSAP plugins such as ScrollTo, Flip, Draggable, SplitText, SVG plugins | `/akili-specify`, `/akili-execute` |
-| [`gsap-react`](gsap-react.md) | GSAP in React and Next.js with cleanup and scoping | `/akili-specify`, `/akili-execute` |
-| [`gsap-scrolltrigger`](gsap-scrolltrigger.md) | Scroll-driven animation, pinning, scrub, parallax | `/akili-specify`, `/akili-execute` |
-| [`gsap-timeline`](gsap-timeline.md) | Sequenced animations and playback control | `/akili-specify`, `/akili-execute` |
-| [`gsap-utils`](gsap-utils.md) | GSAP utilities such as clamp, mapRange, random, snap, wrap | `/akili-execute` |
-| [`kaizen`](kaizen.md) | Bounded continuous-improvement retrospective (Measure → Learn → Standardize → Record); authored by Juan Carlos Cadavid — jcadavid.com | `/akili-archive` |
-| [`nestjs-expert`](nestjs-expert.md) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
-| [`product-manager-toolkit`](product-manager-toolkit.md) | Product discovery, PRDs, prioritization, customer interview analysis (AKILI-adapted: canonical PRD structure, RICE for scope-chunk ordering) | `/akili-constitution`, `/akili-propose`, `/akili-specify` |
-| [`react-doctor`](react-doctor.md) | React diagnostics after changes | `/akili-test`, `/akili-validate` |
-| [`seo-audit`](seo-audit.md) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo`, `/akili-validate` |
-| [`shadcn-ui`](shadcn-ui.md) | shadcn/ui components, forms, themes, Tailwind integration | `/akili-specify`, `/akili-execute`, `/akili-validate` |
-| [`stitch-design`](stitch-design.md) | Stitch prompt enhancement and design generation workflows | `/akili-constitution`, `/akili-specify` |
-| [`systematic-debugging`](systematic-debugging.md) | Bugs, test failures, unexpected behavior, root-cause investigation | `/akili-execute`, `/akili-test`, `/akili-validate`, `/akili-seo` |
-| [`tailwind-design-system`](tailwind-design-system.md) | Tailwind CSS v4 tokens, component systems, responsive patterns | `/akili-constitution`, `/akili-specify`, `/akili-execute` |
-| [`ui-ux-pro-max`](ui-ux-pro-max.md) | UI/UX design intelligence, palettes, typography, accessibility, stacks | `/akili-constitution`, `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
-| [`vercel-react-best-practices`](vercel-react-best-practices.md) | React and Next.js performance and architecture guidance | `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate` |
+| Skill | Binding | Origin | Use For | Wired In |
+|---|---|---|---|---|
+| [`angular-developer`](angular-developer.md) | stack | Google LLC (MIT) | Angular architecture, components, services, signals, forms, routing, testing, CLI | Skill Map; constitution/specify stack lists |
+| [`api-design-principles`](api-design-principles.md) | stack | Seth Hobson (MIT) | REST and GraphQL API design and review | Skill Map; constitution/specify stack lists |
+| [`aws-serverless`](aws-serverless.md) | stack | vibeship (Apache-2.0) | Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK | Skill Map; constitution/specify stack lists |
+| [`brainstorming`](brainstorming.md) | core | Jesse Vincent — obra (MIT) | Clarifying ideas, scope, options, and trade-offs before implementation | `/akili-constitution` Step 0, `/akili-propose`, `/akili-specify` phases 1–3 |
+| [`cognitive-doc-design`](cognitive-doc-design.md) | core | gentleman-programming (Apache-2.0) | Human-facing docs that reduce cognitive load (lead with the answer, progressive disclosure, tables over prose) | `/akili-constitution`, `/akili-specify`, `/akili-execute` (PR docs), `/akili-archive` |
+| [`error-handling-patterns`](error-handling-patterns.md) | stack | Seth Hobson (MIT) | Exceptions, Result patterns, graceful degradation, reliability | Skill Map; constitution/specify stack lists |
+| [`frontend-design`](frontend-design.md) | conditional | Anthropic (Apache-2.0) | Distinctive frontend UI and UX implementation (fallback when `ui-ux-pro-max` is unavailable) | UI steps of `/akili-constitution`, `/akili-specify`, `/akili-test`, `/akili-validate`, `/akili-seo` |
+| [`gsap-animation`](gsap-animation.md) | conditional | GSAP/GreenSock (MIT) | All GSAP animation work — router SKILL.md + references (timeline, scrolltrigger, plugins, react, frameworks, performance, utils) | `/akili-specify` and `/akili-execute` animation work |
+| [`judgment-day`](judgment-day.md) | core | gentleman-programming (Apache-2.0) | Blind adversarial dual review of designs with bounded fix rounds | `/akili-specify` Review Design gate; findings feed `/akili-archive` Kaizen |
+| [`kaizen`](kaizen.md) | core | Juan Carlos Cadavid — jcadavid.com (MIT) | Bounded continuous-improvement retrospective (Measure → Learn → Standardize → Record) | `/akili-archive`; its Active Lessons digest is read by propose/specify/execute/resume |
+| [`nestjs-expert`](nestjs-expert.md) | stack | Daniel Avila (MIT) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | Skill Map; constitution/specify stack lists; persona examples |
+| [`product-manager-toolkit`](product-manager-toolkit.md) | core | Alireza Rezvani (MIT) | Product discovery, PRDs, prioritization, interview analysis (AKILI-adapted: canonical PRD structure, RICE for scope-chunk ordering) | `/akili-constitution` Steps 2–3, `/akili-propose`, `/akili-specify` scope chunking |
+| [`react-doctor`](react-doctor.md) | stack | Million.dev | React diagnostics after changes | Skill Map; `/akili-test`, `/akili-validate`, `/akili-execute` React work |
+| [`seo-audit`](seo-audit.md) | core | Corey Haines (MIT) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo` audit phase (required) |
+| [`shadcn-ui`](shadcn-ui.md) | stack | community (origin unverified) | shadcn/ui components, forms, themes, Tailwind integration | Skill Map; constitution/specify stack lists; persona examples |
+| [`stitch-design`](stitch-design.md) | conditional | Google — google-labs-code | Stitch prompt enhancement and design generation workflows (fallback UI chain with `frontend-design`) | UI steps of `/akili-constitution`, `/akili-propose`, `/akili-specify` |
+| [`systematic-debugging`](systematic-debugging.md) | core | Jesse Vincent — obra (MIT) | Root-cause investigation for bugs, test failures, unexpected behavior | `/akili-propose` Bug Track, `/akili-specify` Bug Mode, `/akili-test`, `/akili-validate`, `/akili-seo` |
+| [`tailwind-design-system`](tailwind-design-system.md) | stack | Seth Hobson (MIT) | Tailwind CSS v4 tokens, component systems, responsive patterns | Skill Map; constitution/specify stack lists |
+| [`ui-ux-pro-max`](ui-ux-pro-max.md) | conditional | nextlevelbuilder (MIT) | UI/UX design intelligence, palettes, typography, accessibility — AKILI's preferred UI/UX skill | UI steps of `/akili-constitution`, `/akili-specify`, `/akili-execute`, `/akili-test`, `/akili-validate`, `/akili-seo` |
+| [`vercel-react-best-practices`](vercel-react-best-practices.md) | stack | Vercel (MIT) | React and Next.js performance and architecture guidance | Skill Map; constitution/specify/test stack lists |
 
 ## Usage Rules
 
-- Use the task-specific skills listed in `tasks.md` during `/akili-execute`.
-- Use UI/UX skills when specs affect screens, flows, interactions, or accessibility.
+- Use the task-specific skills listed in `tasks.md` during `/akili-execute`; when a task lists none, derive them from the project's `## Skill Map`.
+- Use UI/UX skills when specs affect screens, flows, interactions, or accessibility (`ui-ux-pro-max` preferred; `frontend-design` + `stitch-design` as fallback).
+- Use `gsap-animation` for animation work, reading only the `references/` file matching the task.
 - Use `systematic-debugging` before proposing fixes for failures or unexpected behavior.
-- Use framework skills only when the repository or task actually uses that framework.
+- Use stack skills only when the repository or task actually uses that framework — the project Skill Map is the source of truth.
 - If a skill is unavailable in the host tool, fall back to the documented alternative and note the gap in the relevant report.

package/docs/skills/brainstorming.md

@@ -4,6 +4,8 @@
 
 Clarifies ideas before implementation by exploring intent, scope, constraints, options, trade-offs, and approval points.
 
+AKILI-adapted: its generic `docs/plans/` flow is overridden — outputs land in AKILI artifacts (`proposal.md`, `requirements.md`, `design.md`, `tasks.md`) and the terminal state is the active AKILI phase. Binding: `core`.
+
 ## Use When
 
 - A feature or behavior change is still ambiguous.

package/docs/skills/cognitive-doc-design.md

@@ -4,6 +4,8 @@
 
 Designs documentation that reduces cognitive load, using six patterns: lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, and review empathy. AKILI generates many human-facing documents (PRD, TRD, requirements, reports, summaries) — this skill defines how to write them so readers scan, understand, and verify quickly. Authored by gentleman-programming (Apache-2.0).
 
+AKILI-adapted: a per-command document map (constitution → PRD/baseline, specify → spec docs, execute → PR docs, archive → summaries/Kaizen log); the `general-setup` templates win over its default Documentation Shape. Binding: `core`.
+
 ## Use When
 
 - Writing or upgrading any human-facing AKILI document: PRD, UX/UI design, TRD, requirements, design, reports, archive summaries.

package/docs/skills/governance.md

@@ -0,0 +1,77 @@
+# Skill Governance
+
+**The rule in one line:** every skill in this package declares who wrote it, how AKILI binds it into the flow, and why its size is justified — or it does not ship.
+
+AKILI-SPECS is a curated methodology, not a skill dump. Skills are admitted through the analysis below, adapted to the methodology, and attributed to their original authors. Curation and adaptation by Juan Carlos Cadavid — jcadavid.com.
+
+## Binding Taxonomy
+
+Every skill declares `metadata.binding` in its `SKILL.md` frontmatter. The binding level answers the question: *when and how does this skill get loaded?*
+
+| Binding | When it loads | Mechanism |
+|---|---|---|
+| `core` | Always, at a precise step of a command | The command text hard-loads it ("load the `X` skill") |
+| `conditional` | When the work touches its domain | A conditional line in the command ("if the work involves X, load `Y`") |
+| `stack` | Depends on the project's technology stack | `/akili-constitution` writes a **`## Skill Map`** into the project's `AGENTS.md`/`CLAUDE.md`; `/akili-specify` derives per-task required skills in `tasks.md`; the Leader assigns them to Implementer/Tester via dynamic skill loading |
+
+### Current assignment
+
+| Binding | Skills |
+|---|---|
+| `core` | `kaizen` (archive), `judgment-day` (specify), `cognitive-doc-design` (all human-facing docs), `brainstorming` (constitution, propose), `product-manager-toolkit` (constitution), `systematic-debugging` (bug flows), `seo-audit` (seo) |
+| `conditional` | `ui-ux-pro-max`, `frontend-design`, `stitch-design` (UI work), `gsap-animation` (animation work) |
+| `stack` | `angular-developer`, `nestjs-expert`, `shadcn-ui`, `tailwind-design-system`, `react-doctor`, `vercel-react-best-practices`, `aws-serverless`, `api-design-principles`, `error-handling-patterns` |
+
+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.
+
+## Frontmatter Schema
+
+Every packaged skill carries this frontmatter (original fields are preserved, never overwritten):
+
+```yaml
+---
+name: <skill-name>
+description: "<trigger keywords + what it does>"
+license: <original license — never altered>
+metadata:
+  author: <original author, or "community (origin unverified)">
+  source: <URL or collection of origin, when known>
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: core | conditional | stack
+  version: "<preserved or 1.0>"
+---
+```
+
+Attribution is non-negotiable: MIT and Apache-2.0 licenses require preserving the original copyright and license notices. `adapted-by` records curation and AKILI adaptation — it never replaces the original `author`.
+
+## Adaptation Levels
+
+| Level | Who gets it | What it is |
+|---|---|---|
+| 1 — Attribution | All skills | The standard frontmatter above |
+| 2 — Integration | `core` and deeply-used `conditional` skills only | An `## AKILI-SPECS Integration` section in the body: a table mapping the skill's tools to exact moments in the AKILI flow, plus adaptation rules |
+
+`stack` skills deliberately get **no** integration section — they are loaded per task and extra methodology prose in them is token waste (MUDA).
+
+## Acceptance Checklist for New Skills
+
+A skill enters `.claude/skills/` only when all of these hold. If any box fails, the skill stays out.
+
+1. **Need** — a real AKILI phase or supported stack needs it; name the command step or Skill Map slot it will occupy.
+2. **Binding declared** — `core`, `conditional`, or `stack`, with the exact integration point. A `core`/`conditional` skill must actually be wired into command text in the same change; a skill referenced by no command and no Skill Map is dead weight and does not ship.
+3. **Attribution complete** — original author, source, and license identified and preserved; `adapted-by` added. If the origin cannot be verified after a genuine search, mark `author: community (origin unverified)`.
+4. **Size justified** — prefer one skill with `references/` (progressive disclosure) over families of sibling skills; large data/scripts payloads need a stated reason.
+5. **Docs + CHANGELOG** — a `docs/skills/<name>.md` page, a truthful row in `docs/skills/README.md` (Binding column included), and a `CHANGELOG.md` entry.
+
+The same checklist applies in reverse: when a skill loses its integration points, remove it or re-bind it — do not let the inventory drift from the commands.
+
+## Removal / Fusion Log
+
+| Date | Change | Reason |
+|---|---|---|
+| 2026-07-20 | `gsap-core`, `gsap-timeline`, `gsap-scrolltrigger`, `gsap-plugins`, `gsap-react`, `gsap-frameworks`, `gsap-performance`, `gsap-utils` → fused into `gsap-animation` | 8 sibling skills, ~104 KB, zero command wiring; one `conditional` skill with `references/` preserves the content and is actually loaded |

package/docs/skills/gsap-animation.md

@@ -0,0 +1,29 @@
+# `gsap-animation`
+
+## Purpose
+
+Unified GSAP animation skill — the fusion of the former 8 `gsap-*` sibling skills into one conditional skill with progressive disclosure. The `SKILL.md` is a compact core + router (tweens, easing, stagger, registration, reduced-motion rules) and a routing table pointing to `references/` files: `timeline`, `scrolltrigger`, `plugins`, `react`, `frameworks`, `performance`, `utils`.
+
+Original content by GSAP (GreenSock), MIT. Adapted for AKILI-SPECS by Juan Carlos Cadavid — jcadavid.com.
+
+## Use When
+
+- A spec or task involves animation: tweens, timelines, scroll-driven effects, motion design, SVG animation.
+- Working with GSAP in React/Next.js, Vue, Nuxt, Svelte, or vanilla JS.
+- Diagnosing janky animation or animation performance issues.
+
+Load the skill, then read only the reference file(s) matching the task — never all of them.
+
+## Binding
+
+`conditional` — `/akili-specify` and `/akili-execute` load it when the work involves animation. It is not stack-bound: it applies to any frontend stack using GSAP.
+
+## Best Paired Commands
+
+- `/akili-specify` for designing animation behavior in `requirements.md`/`design.md`.
+- `/akili-execute` for Implementer tasks that write animation code (plus the matching reference).
+- `/akili-validate` for animation performance findings (via `references/performance.md`).
+
+## Source
+
+- `../../.claude/skills/gsap-animation/SKILL.md`

package/docs/skills/judgment-day.md

@@ -4,6 +4,8 @@
 
 Provides a blind adversarial dual-review framework for design decisions. Two independent "judges" evaluate a design without seeing each other's feedback, then findings are reconciled. Supports up to two scoped fix/re-judgment rounds.
 
+AKILI-adapted: the findings ledger persists as `docs/specs/<spec-path>/judgment.md`, judges should run on a model different from the design author (author ≠ auditor), and severe findings feed the Kaizen retrospective. Authored by gentleman-programming (Apache-2.0). Binding: `core`.
+
 ## Use When
 
 - Reviewing design decisions during `/akili-specify` before proceeding to tasks.

package/docs/skills/product-manager-toolkit.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Supports product management work, including PRDs, customer interview analysis, RICE prioritization, discovery frameworks, requirements, and go-to-market thinking. Adapted for AKILI-SPECS: its **AKILI-SPECS Integration** section maps each tool to one precise moment in the flow, and the AKILI 9-section PRD structure is canonical over the toolkit's own templates.
+Supports product management work, including PRDs, customer interview analysis, RICE prioritization, discovery frameworks, requirements, and go-to-market thinking. Original by Alireza Rezvani (MIT, [claude-skills](https://github.com/alirezarezvani/claude-skills)). Adapted for AKILI-SPECS by Juan Carlos Cadavid: its **AKILI-SPECS Integration** section maps each tool to one precise moment in the flow, and the AKILI 9-section PRD structure is canonical over the toolkit's own templates. Binding: `core`.
 
 ## Use When