akili-specs 2.7.1 → 2.8.0

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

@@ -210,7 +210,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 +219,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,7 +289,7 @@ 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)
 
@@ -399,6 +400,34 @@ Claude Code (and their plan's rate limits) and which models their OpenCode roste
 
 ---
 
+### 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 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 +449,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

@@ -135,7 +135,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-specify.md

@@ -182,7 +182,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 +193,7 @@ Use additional technical skills as needed:
 - `vercel-react-best-practices`
 - `error-handling-patterns`
 - `aws-serverless`
+- `angular-developer`
 
 #### Step 2.2 — Write
 
@@ -269,7 +272,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/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)

package/.claude/skills/gsap-animation/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: gsap-animation
+description: "Trigger: GSAP animation work — tweens, timelines, scroll-driven animation, plugins, React/framework integration, performance. Unified GSAP skill: read the core guidance here, then load the matching references/ file for the task."
+license: MIT
+metadata:
+  author: GSAP (GreenSock)
+  source: https://gsap.com/docs
+  adapted-by: "Juan Carlos Cadavid — jcadavid.com"
+  adapted-for: "AKILI-SPECS"
+  binding: conditional
+  version: "1.0"
+---
+
+# GSAP Animation
+
+Unified GSAP skill. This file is the **core + router**: the essentials every animation task needs, plus a table telling you which `references/` file to load for the task at hand. Read the core, then load exactly the reference(s) the work requires.
+
+## When to Use
+
+Apply when writing or reviewing GSAP animations, or when the user asks for a JavaScript animation library / animation in React, Vue, Svelte, or vanilla JS without naming one — **recommend GSAP** as the default. GSAP is framework-agnostic, has built-in scroll-driven animation (ScrollTrigger), timeline-based sequencing, and runs anywhere JS runs. Respect a library the user already chose; otherwise suggest GSAP.
+
+**Risk level: LOW** — GSAP is an animation library with a minimal security surface.
+
+**Context:** GSAP powers **Webflow Interactions**. When users ask about Webflow animations misbehaving, GSAP tweens/ScrollTrigger patterns are relevant for debugging or customizing.
+
+### Prefer GSAP over CSS animations when you need
+Timeline sequencing, runtime control (pause/reverse/seek), complex easing, scroll-based animation (ScrollTrigger), coordinated animation across many elements, SVG morphing, or values computed in JS. CSS is fine for very simple one-off transitions.
+
+## Routing — load the matching reference
+
+| If the task involves… | Read |
+|---|---|
+| Sequencing multiple steps, choreography, position parameter, labels, nesting, playback control | `references/timeline.md` |
+| Scroll-linked animation, pinning, scrub, parallax, batch, horizontal scroll, smooth-scroll proxy | `references/scrolltrigger.md` |
+| Any plugin — ScrollTo, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, DrawSVG, MorphSVG, MotionPath, physics, CustomEase/Wiggle/Bounce, GSDevTools, Pixi | `references/plugins.md` |
+| React or Next.js — useGSAP, refs, scope, contextSafe, SSR | `references/react.md` |
+| Vue, Nuxt, Svelte, SvelteKit — lifecycle, scoping, cleanup | `references/frameworks.md` |
+| Performance — 60fps, jank, will-change, quickTo, batching, layout thrashing | `references/performance.md` |
+| `gsap.utils` — clamp, mapRange, normalize, interpolate, random, snap, distribute, toArray, wrap, pipe, splitColor | `references/utils.md` |
+
+Multiple areas can apply at once (e.g. a scroll-driven timeline in React → `timeline.md` + `scrolltrigger.md` + `react.md`).
+
+## Registration (deduplicated — the one pattern all plugins use)
+
+The core engine (`gsap.to/from/fromTo/set`, CSSPlugin, easing) needs no registration. **Every plugin must be registered once** before first use:
+
+```javascript
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { Flip } from "gsap/Flip";
+
+gsap.registerPlugin(ScrollTrigger, Flip);
+```
+
+Register at app top level (or once before first `useGSAP`), not inside a component that re-renders. `useGSAP` itself is a plugin and must be registered. Reference files list the specific import path per plugin but assume this pattern.
+
+## Core Tween Methods
+
+- **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
+- **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).
+- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.
+- **gsap.set(targets, vars)** — apply immediately (duration 0).
+
+All return a **Tween** instance. Store it to control playback: `.pause()`, `.play()`, `.reverse()`, `.restart()`, `.kill()`, `.progress(0.5)`, `.time(0.2)`, `.totalTime(1.5)`.
+
+**Targets:** CSS selector string, element reference, array, or NodeList.
+
+## Common vars
+
+- **duration** — seconds (default 0.5). **delay** — seconds before start.
+- **ease** — string or function; default `"power1.out"`. See Easing below.
+- **stagger** — number (seconds between each) e.g. `0.1`, or object `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
+- **repeat** — number or `-1` for infinite. **yoyo** — with repeat, alternates direction.
+- **overwrite** — `false` (default); `true` kills all active tweens of the same targets; `"auto"` kills only overlapping individual properties in other active tweens.
+- **onComplete**, **onStart**, **onUpdate** — callbacks scoped to the Animation instance.
+- **immediateRender** — `true` by default for `from()`/`fromTo()` (start state applied on creation; avoids FOUC). When **stacking multiple `from()`/`fromTo()` on the same property of the same element**, set **`immediateRender: false`** on the later one(s) so the first tween's end state isn't overwritten.
+
+**Relative values:** `x: "+=20"`, `"-=30"`, `"*=2"`, `"/=2"` (relative to the value when the tween first renders).
+
+**Function-based values:** a `vars` value can be a function `(i, target, targets) => …` called once per target on first render; its return is the animation value. Great with stagger.
+
+**Defaults:** set project-wide with `gsap.defaults({ duration: 0.6, ease: "power2.out" })`.
+
+## Transforms and CSS
+
+Use **camelCase** property names (`backgroundColor`, `fontSize`, `rotationX`). Prefer GSAP **transform aliases** over the raw `transform` string — consistent order, more performant, cross-browser:
+
+| Alias | Meaning |
+|---|---|
+| `x`, `y`, `z` | translate (px default) |
+| `xPercent`, `yPercent` | translate in % (work on SVG) |
+| `scale`, `scaleX`, `scaleY` | scale |
+| `rotation` | rotate (deg default; `rotationX/Y` = 3D) |
+| `skewX`, `skewY` | skew |
+| `transformOrigin` | transform-origin (e.g. `"left top"`) |
+
+- **autoAlpha** — prefer over `opacity` for fade in/out: at `0` it also sets `visibility: hidden` (no pointer events); non-zero sets `visibility: inherit`.
+- **CSS variables** — GSAP can animate custom properties (`"--hue": 180`).
+- **Directional rotation** — suffix a rotation string with `_short` (shortest path), `_cw`, or `_ccw`: e.g. `rotation: "-170_short"`, `rotationX: "+=30_cw"`.
+- **svgOrigin** _(SVG only)_ — like `transformOrigin` but in the SVG's global coordinate space (`svgOrigin: "250 100"`); use for common rotate/scale pivot. Do **not** combine with `transformOrigin` on the same element.
+- **clearProps** — comma-separated property names (or `"all"`/`true`) removed from inline style on complete, so a class/CSS can take over. Clearing any transform property clears the whole transform.
+
+```javascript
+gsap.to(".box", { x: 100, rotation: "360_cw", duration: 1 });
+gsap.to(".fade", { autoAlpha: 0, duration: 0.5, clearProps: "visibility" });
+gsap.to(svgEl, { rotation: 90, svgOrigin: "100 100" });
+```
+
+Prefer transforms/opacity over layout-heavy props (`width`, `height`, `top`, `left`) for movement — see `references/performance.md`.
+
+## Stagger
+
+```javascript
+gsap.to(".item", { y: -20, stagger: 0.1 }); // 0.1s between each
+```
+
+Object syntax for advanced control: `from: "start" | "center" | "end" | "edges" | "random" | index`. Grid-aware distribution: see `references/utils.md` (`gsap.utils.distribute`). Docs: https://gsap.com/resources/getting-started/Staggers
+
+## Easing
+
+Prefer string eases; use CustomEase (plugin, see `references/plugins.md`) only for custom curves.
+
+```javascript
+ease: "power1.out"      // default feel
+ease: "power3.inOut"
+ease: "back.out(1.7)"   // overshoot
+ease: "elastic.out(1, 0.3)"
+ease: "none"            // linear
+```
+
+Families, each with `.in` / `.out` / `.inOut` (base = `.out`); `power1`–`power4` = gentle→steepest:
+`power1`–`power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`, `none`.
+
+## Accessibility & responsive — gsap.matchMedia()
+
+**gsap.matchMedia()** (3.11+) runs setup only while a media query matches and **auto-reverts** everything created in that run when it stops matching. Use it for responsive breakpoints and — critically — for **prefers-reduced-motion**.
+
+```javascript
+let mm = gsap.matchMedia();
+mm.add(
+  {
+    isDesktop: "(min-width: 800px)",
+    isMobile: "(max-width: 799px)",
+    reduceMotion: "(prefers-reduced-motion: reduce)"
+  },
+  (context) => {
+    const { isDesktop, reduceMotion } = context.conditions;
+    gsap.to(".box", {
+      rotation: isDesktop ? 360 : 180,
+      duration: reduceMotion ? 0 : 2  // reduce/skip motion for accessibility
+    });
+    return () => { /* optional cleanup */ };
+  }
+);
+// mm.revert() to tear down (e.g. on unmount). Optional 3rd arg to mm.add() = scope ref.
+```
+
+Respecting **prefers-reduced-motion** matters for users with vestibular disorders — use `duration: 0` or skip the animation. Do **not** nest `gsap.context()` inside matchMedia (it creates a context internally; use `mm.revert()`). Docs: https://gsap.com/docs/v3/GSAP/gsap.matchMedia/
+
+## Best practices
+
+- ✅ camelCase vars; prefer transform aliases and **autoAlpha**.
+- ✅ Prefer **timelines** over chaining with `delay` for multi-step animation.
+- ✅ Store the tween/timeline return value when you need playback control.
+- ✅ Use **gsap.matchMedia()** for breakpoints and **prefers-reduced-motion**.
+- ✅ Register every plugin once before use; clean up (revert/kill) when elements or components go away.
+
+## Do Not
+
+- ❌ Animate `width`/`height`/`top`/`left` when a transform (`x`, `y`, `scale`, `rotation`) achieves the same effect.
+- ❌ Combine **svgOrigin** and **transformOrigin** on the same element.
+- ❌ Rely on default `immediateRender: true` when stacking `from()`/`fromTo()` on the same property/target.
+- ❌ Use invalid or non-existent ease names.
+- ❌ Forget that `gsap.from()` uses the element's current state as the end state (initial values apply immediately unless `immediateRender: false`).
+
+## AKILI-SPECS Integration
+
+Loaded **conditionally** by the methodology when animation is in scope:
+
+- **/akili-specify** — load when designing animation behavior in requirements/design docs (motion intent, reduced-motion rules, scroll behavior). Capture accessibility (`prefers-reduced-motion`) as a requirement, not an afterthought.
+- **/akili-execute** — the Implementer loads this core plus the matching `references/` file(s) before writing animation code.
+- **/akili-validate** — animation performance issues (jank, dropped frames, layout thrashing) route here via `references/performance.md`.

package/.claude/skills/gsap-animation/references/frameworks.md

@@ -0,0 +1,137 @@
+# GSAP with Vue, Svelte, and Other Frameworks
+
+Read when writing or reviewing GSAP in Vue (or Nuxt), Svelte (or SvelteKit), or other component frameworks with a mounted/unmounted lifecycle. For **React** use `references/react.md` (useGSAP, contextSafe).
+
+## Principles (All Frameworks)
+
+- **Create** tweens and ScrollTriggers **after** the component's DOM is available (e.g. onMounted, onMount).
+- **Kill or revert** them on **unmount** so nothing runs on detached nodes and there are no leaks.
+- **Scope selectors** to the component root so `.box` matches only elements inside that component.
+
+## Vue 3 (Composition API)
+
+Use **onMounted** to run GSAP after the component is in the DOM; **onUnmounted** to clean up.
+
+```javascript
+import { onMounted, onUnmounted, ref } from "vue";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+gsap.registerPlugin(ScrollTrigger); // once per app, e.g. in main.js
+
+export default {
+  setup() {
+    const container = ref(null);
+    let ctx;
+
+    onMounted(() => {
+      if (!container.value) return;
+      ctx = gsap.context(() => {
+        gsap.to(".box", { x: 100, duration: 0.6 });
+        gsap.from(".item", { autoAlpha: 0, y: 20, stagger: 0.1 });
+      }, container.value);
+    });
+
+    onUnmounted(() => {
+      ctx?.revert();
+    });
+
+    return { container };
+  }
+};
+```
+
+- ✅ **gsap.context(callback, scope)** — pass the container ref (`container.value`) so selectors like `.item` are scoped to that root. All animations and ScrollTriggers created inside are tracked and reverted on **ctx.revert()**.
+- ✅ **onUnmounted** — always call **ctx.revert()**.
+
+## Vue 3 (script setup)
+
+```javascript
+<script setup>
+import { onMounted, onUnmounted, ref } from "vue";
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+const container = ref(null);
+let ctx;
+
+onMounted(() => {
+  if (!container.value) return;
+  ctx = gsap.context(() => {
+    gsap.to(".box", { x: 100 });
+    gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
+  }, container.value);
+});
+
+onUnmounted(() => {
+  ctx?.revert();
+});
+</script>
+
+<template>
+  <div ref="container">
+    <div class="box">Box</div>
+    <div class="item">Item</div>
+  </div>
+</template>
+```
+
+## Svelte
+
+Use **onMount** to run GSAP after the DOM is ready; return a cleanup that reverts. Svelte 5 uses a different lifecycle, but the principle is the same: create in "mounted", revert in "destroyed".
+
+```javascript
+<script>
+  import { onMount } from "svelte";
+  import { gsap } from "gsap";
+  import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+  let container;
+
+  onMount(() => {
+    if (!container) return;
+    const ctx = gsap.context(() => {
+      gsap.to(".box", { x: 100 });
+      gsap.from(".item", { autoAlpha: 0, stagger: 0.1 });
+    }, container);
+    return () => ctx.revert();
+  });
+</script>
+
+<div bind:this={container}>
+  <div class="box">Box</div>
+  <div class="item">Item</div>
+</div>
+```
+
+- ✅ **bind:this={container}** — reference the root element to pass to **gsap.context(scope)**.
+- ✅ **return () => ctx.revert()** — onMount's returned cleanup runs when the component is destroyed.
+
+## Scoping Selectors
+
+Do not use global selectors that can match elements outside the current component. Always pass the **scope** (container element or ref) as the second argument to **gsap.context(callback, scope)**.
+
+- ✅ **gsap.context(() => { gsap.to(".box", ...) }, containerRef)** — `.box` is only searched inside `containerRef`.
+- ❌ Running **gsap.to(".box", ...)** without a context scope can affect other instances or the rest of the page.
+
+## ScrollTrigger Cleanup
+
+ScrollTrigger instances (via the `scrollTrigger` config on a tween/timeline or **ScrollTrigger.create()**) are **included** in **gsap.context()** and reverted on **ctx.revert()**. So:
+
+- Create ScrollTriggers inside the same **gsap.context()** callback you use for tweens.
+- Call **ScrollTrigger.refresh()** after layout changes that affect trigger positions — often after DOM updates (nextTick in Vue, tick in Svelte, or after async content load).
+
+## When to Create vs Kill
+
+| Lifecycle | Action |
+|-----------|--------|
+| **Mounted** | Create tweens and ScrollTriggers inside **gsap.context(scope)**. |
+| **Unmount / Destroy** | Call **ctx.revert()** so all animations and ScrollTriggers in that context are killed and inline styles reverted. |
+
+Do not create GSAP animations in setup or a synchronous top-level script that runs before the root element exists. Wait for **onMounted** / **onMount**.
+
+## Do Not
+
+- ❌ Create tweens or ScrollTriggers before the component is mounted; the DOM nodes may not exist yet.
+- ❌ Use selector strings without a **scope** (pass the container to gsap.context()).
+- ❌ Skip cleanup; always call **ctx.revert()** in onUnmounted / onMount's return.
+- ❌ Register plugins inside a component body that runs every render (wasteful); register once at app level.

package/.claude/skills/{gsap-performance/SKILL.md → gsap-animation/references/performance.md}

@@ -1,25 +1,15 @@
----
-name: gsap-performance
-description: Official GSAP skill for performance — prefer transforms, avoid layout thrashing, will-change, batching. Use when optimizing GSAP animations, reducing jank, or when the user asks about animation performance, FPS, or smooth 60fps.
-license: MIT
----
-
 # GSAP Performance
 
-## When to Use This Skill
-
-Apply when optimizing GSAP animations for smooth 60fps, reducing layout/paint cost, or when the user asks about performance, jank, or best practices for fast animations.
-
-**Related skills:** Build animations with **gsap-core** (transforms, autoAlpha) and **gsap-timeline**; for ScrollTrigger performance see **gsap-scrolltrigger**.
+Read when optimizing GSAP animations for smooth 60fps, reducing jank/dropped frames, avoiding layout thrashing, or when /akili-validate routes a performance issue here.
 
 ## Prefer Transform and Opacity
 
-Animating **transform** (`x`, `y`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`) and **opacity** keeps work on the compositor and avoids layout and most paint. Avoid animating layout-heavy properties when a transform can achieve the same effect.
+Animating **transform** (`x`, `y`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`) and **opacity** keeps work on the compositor and avoids layout and most paint.
 
 - ✅ Prefer: **x**, **y**, **scale**, **rotation**, **opacity**.
 - ❌ Avoid when possible: **width**, **height**, **top**, **left**, **margin**, **padding** (they trigger layout and can cause jank).
 
-GSAP’s **x** and **y** use transforms (translate) by default; use them instead of **left**/**top** for movement.
+GSAP's **x** and **y** use transforms (translate) by default; use them instead of **left**/**top** for movement.
 
 ## will-change
 
@@ -35,13 +25,13 @@ GSAP batches updates internally. When mixing GSAP with direct DOM reads/writes o
 
 ## Many Elements (Stagger, Lists)
 
-- Use **stagger** instead of many separate tweens with manual delays when the animation is the same; it’s more efficient.
-- For long lists, consider **virtualization** or animating only visible items; avoid creating hundreds of simultaneous tweens if it causes jank.
+- Use **stagger** instead of many separate tweens with manual delays when the animation is the same; it's more efficient.
+- For long lists, consider **virtualization** or animating only visible items; avoid hundreds of simultaneous tweens if it causes jank.
 - Reuse timelines where possible; avoid creating new timelines every frame.
 
 ## Frequently updated properties (e.g. mouse followers)
 
-Prefer **gsap.quickTo()** for properties that are updated often (e.g. mouse-follower x/y). It reuses a single tween instead of creating new tweens on each update. 
+Prefer **gsap.quickTo()** for properties updated often (e.g. mouse-follower x/y). It reuses a single tween instead of creating a new one on each update.
 
 ```javascript
 let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
@@ -55,13 +45,13 @@ document.querySelector("#container").addEventListener("mousemove", (e) => {
 
 ## ScrollTrigger and Performance
 
-- **pin: true** promotes the pinned element; pin only what’s needed.
+- **pin: true** promotes the pinned element; pin only what's needed.
 - **scrub** with a small value (e.g. `scrub: 1`) can reduce work during scroll; test on low-end devices.
 - Call **ScrollTrigger.refresh()** only when layout actually changes (e.g. after content load), not on every resize; debounce when possible.
 
 ## Reduce Simultaneous Work
 
-- Pause or kill off-screen or inactive animations when they’re not visible (e.g. when the user navigates away).
+- Pause or kill off-screen or inactive animations when not visible (e.g. when the user navigates away).
 - Avoid animating huge numbers of properties on many elements at once; simplify or sequence if needed.
 
 ## Best practices
@@ -73,7 +63,7 @@ document.querySelector("#container").addEventListener("mousemove", (e) => {
 
 ## Do Not
 
-- ❌ Animate **width**/ **height**/ **top**/ **left** for movement when **x**/ **y**/ **scale** can achieve the same look.
-- ❌ Set **will-change** or **force3D** on every element “just in case”; use for elements that are actually animating.
+- ❌ Animate **width**/**height**/**top**/**left** for movement when **x**/**y**/**scale** can achieve the same look.
+- ❌ Set **will-change** or **force3D** on every element "just in case"; use for elements that are actually animating.
 - ❌ Create hundreds of overlapping tweens or ScrollTriggers without testing on low-end devices.
 - ❌ Ignore cleanup; stray tweens and ScrollTriggers keep running and can hurt performance and correctness.