@skilly-hand/skilly-hand 0.25.3 → 0.26.1

package/CHANGELOG.md

@@ -16,6 +16,38 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.26.1] - 2026-05-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.1)
+
+### Added
+- Added portable `gsap-animation` skill with official-source GSAP guidance for timelines, ScrollTrigger, React `useGSAP`, plugin selection, performance, cleanup, and reduced-motion patterns.
+- Added GSAP project detection so installs recommend `gsap-animation` when `gsap` or `@gsap/react` is present.
+
+### Changed
+- Updated `frontend-design` to route advanced motion work through `gsap-animation` and include the new critique workflow in catalog metadata.
+- Updated selected skill installation to include portable skill dependencies automatically.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.26.0] - 2026-05-01
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.0)
+
+### Added
+- Added dedicated performance-reviewer modes for the Angular and React guideline skills.
+
+### Changed
+- Expanded Angular and React guideline routing, review checklists, and catalog descriptions for performance optimization workflows.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.25.3] - 2026-05-01
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.25.3)
 

package/catalog/README.md

@@ -6,13 +6,14 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | ----- | ----------- | ---- | ------------ |
 | `accessibility-audit` | Audit web accessibility against W3C WCAG 2.2 Level AA using framework-agnostic checks, remediation patterns, and portable command-line scanning. | frontend, accessibility, workflow, quality | all |
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
-| `angular-guidelines` | Guide Angular code generation and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | all |
+| `angular-guidelines` | Guide Angular code generation, review, and performance tuning using latest stable Angular verification, official Angular skill guidance, and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
-| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases. | frontend, design, workflow, ui, motion, greenfield | all |
+| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and GSAP-aware motion polish. | frontend, design, workflow, ui, motion, greenfield | all |
+| `gsap-animation` | Guide GSAP animation implementation using only official GSAP documentation and the official greensock/gsap-skills source material. Trigger: implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation. | frontend, animation, motion, gsap, workflow | all |
 | `output-optimizer` | Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness. | core, workflow, efficiency, communication | all |
 | `project-security` | Scan project configuration and release surfaces for leak and security risks, and enforce security gates on commit, push, and publish workflows across GitHub, GitLab, npm, pnpm, yarn, and generic CI. Trigger: validating repository security posture, preventing secret leaks, or hardening delivery pipelines. | security, workflow, quality, core | all |
 | `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |
-| `react-guidelines` | Guide React code generation and review using latest stable React verification and modern framework best practices. | react, frontend, workflow, best-practices | all |
+| `react-guidelines` | Guide React and Next.js code generation, review, and performance tuning using latest stable React verification and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing React code artifacts in React projects. | react, frontend, workflow, best-practices | all |
 | `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
 | `roaster` | Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind. | core, workflow, planning, quality | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |

package/catalog/catalog-index.json

@@ -4,6 +4,7 @@
   "angular-guidelines",
   "figma-mcp-0to1",
   "frontend-design",
+  "gsap-animation",
   "output-optimizer",
   "project-security",
   "project-teacher",

package/catalog/skills/angular-guidelines/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "angular-guidelines"
-description: "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices."
+description: "Guide Angular code generation, review, and performance tuning using latest stable Angular verification, official Angular skill guidance, and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-03"
+  last-edit: "2026-05-01"
   license: "Apache-2.0"
-  version: "1.1.1"
-  changelog: "Added allowed-modes metadata to declare angular-guidelines sub-agent routing targets; improves discoverability of component-creator and angular-tester delegation modes; affects angular-guidelines manifest metadata"
-  auto-invoke: "Generating, reviewing, or refactoring Angular code artifacts in Angular projects"
+  version: "1.2.0"
+  changelog: "Added curated official Angular skill and performance guidance with a dedicated performance-reviewer mode; improves SSR, hydration, reactivity, testing, and runtime optimization coverage; affects angular-guidelines routing, review checklists, and catalog discovery"
+  auto-invoke: "Generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects"
   allowed-tools:
     - "Read"
     - "Edit"
@@ -29,6 +29,7 @@ Use this skill when:
 - You are generating Angular components, directives, pipes, services, or supporting files.
 - You are refactoring existing Angular code to current framework patterns.
 - You are reviewing Angular code quality and framework-alignment in an Angular workspace.
+- You are optimizing Angular performance, SSR/hydration, reactivity/data flow, forms, routing, accessibility, or CLI-aligned generation.
 
 Do not use this skill for:
 
@@ -46,6 +47,7 @@ Choose sub-agents by intent:
 | --- | --- |
 | Create, refactor, or review Angular components | [agents/component-creator.md](agents/component-creator.md) |
 | Write or review Angular tests | [agents/angular-tester.md](agents/angular-tester.md) |
+| Optimize or review Angular performance, SSR, or hydration | [agents/performance-reviewer.md](agents/performance-reviewer.md) |
 
 ---
 
@@ -53,7 +55,8 @@ Choose sub-agents by intent:
 
 1. Run latest stable Angular preflight checks.
 2. Route to the smallest matching sub-agent by task intent.
-3. Apply the sub-agent checklist before finalizing generated code or review output.
+3. If the request mentions performance, SSR, hydration, routing, data fetching, bundle size, change detection, or zoneless behavior, include the performance priority checklist.
+4. Apply the sub-agent checklist before finalizing generated code or review output.
 
 ---
 
@@ -85,13 +88,34 @@ Use these defaults unless project constraints explicitly prevent them:
 | Forms | Typed reactive forms |
 | Rendering strategy | OnPush-friendly patterns and deferred/lazy rendering where appropriate |
 
-### Pattern 3: Generation and Review Guardrails
+### Pattern 3: Modern Reactivity Guardrails
+
+- Use `computed` for derived state rather than duplicating or propagating state manually.
+- Avoid `effect` for state propagation; reserve it for logging, browser storage sync, non-template DOM work, canvas/chart integrations, or other non-reactive APIs.
+- Use `resource` for async signal-based data when the project Angular version supports it and it fits existing data patterns.
+- Use `linkedSignal` for dependent writable state when the project Angular version supports it.
+- Read signals before `await` inside reactive contexts so dependencies are tracked synchronously.
+
+### Pattern 4: Performance Review Priority
+
+Use this official-Angular-aligned priority order for performance review. Measure first when possible, then choose the smallest applicable optimization.
+
+| Priority | Review Focus | Default Action |
+| --- | --- | --- |
+| 1 | Measurement | Use Angular DevTools or Chrome DevTools Angular profiling to identify specific load, change detection, or rendering bottlenecks. |
+| 2 | Loading performance | Prefer lazy routes, `@defer` for non-critical/heavy UI, image optimization, and SSR/hydration where they improve Core Web Vitals. |
+| 3 | Runtime performance | Check zoneless change detection support, slow template/lifecycle computations, OnPush-friendly state, and zone pollution from timers or third-party code. |
+| 4 | SSR/hydration correctness | Avoid server/client template divergence, prefer platform-specific providers, keep per-request state out of shared providers, and use factory providers for request-specific values. |
+| 5 | Advanced loading | Use incremental hydration and advanced deferrable-view strategies only when the project version and UX constraints justify them. |
+
+### Pattern 5: Generation and Review Guardrails
 
 - Keep generated files focused and minimal for the requested artifact.
 - Prefer framework-native patterns over custom abstractions unless required by repo conventions.
 - Call out deprecated patterns in reviewed code and suggest modern Angular replacements.
 - For component-specific work, apply [agents/component-creator.md](agents/component-creator.md).
 - For testing-specific work, apply [agents/angular-tester.md](agents/angular-tester.md).
+- For performance-specific work, apply [agents/performance-reviewer.md](agents/performance-reviewer.md).
 
 ---
 
@@ -111,8 +135,12 @@ Is this a refactor task?
   NO  -> Continue
 
 Is this a review task?
-  YES -> Validate latest-stable alignment + best-practice checklist
+  YES -> Validate latest-stable alignment + best-practice/performance checklist
   NO  -> Apply the minimal Angular guidance needed for the request
+
+Does the task mention performance, SSR, hydration, routing, data fetching, bundles, change detection, or zoneless behavior?
+  YES -> Route through performance-reviewer before finalizing
+  NO  -> Keep the existing component/test route
 ```
 
 ---
@@ -168,6 +196,7 @@ export class ProfileService {
 - Template control flow uses modern block syntax.
 - DI and forms follow modern typed Angular practices.
 - Output avoids deprecated Angular APIs unless needed for compatibility.
+- Performance work follows measurement-first guidance and avoids speculative optimization.
 
 ---
 
@@ -196,3 +225,10 @@ ng update @angular/core @angular/cli
 - Angular update guide: https://angular.dev/update-guide
 - Angular blog (official releases): https://blog.angular.dev
 - Angular GitHub releases: https://github.com/angular/angular/releases
+- Angular Agent Skills: https://angular.dev/ai/agent-skills
+- Official Angular skills repo: https://github.com/angular/skills
+- Angular style guide: https://angular.dev/style-guide
+- Angular performance guide: https://angular.dev/best-practices/performance
+- Angular signals guide: https://angular.dev/guide/signals
+- Angular testing guide: https://angular.dev/guide/testing
+- Angular HTTP testing guide: https://angular.dev/guide/http/testing

package/catalog/skills/angular-guidelines/agents/angular-tester.md

@@ -29,8 +29,11 @@ Do not use this sub-agent for:
 - Test signal and computed behavior directly when possible.
 - Test signal inputs/outputs using component instance APIs and DOM-triggered events.
 - Cover async behavior with `fakeAsync`/`tick`/`flush` or `waitForAsync`/`whenStable`.
-- For HTTP paths, use `HttpClientTestingModule`/`HttpTestingController` and verify requests.
+- For HTTP paths, use `provideHttpClient()` before `provideHttpClientTesting()`, then verify requests with `HttpTestingController`.
+- Use component DOM tests when template behavior, user interaction, or child integration matters.
+- Use router testing harnesses when navigation, guards, resolvers, or routed components are the behavior under test.
 - For services, prefer explicit DI setup and clear mocking boundaries.
+- Avoid assertions on incidental implementation details unless they are part of the public contract.
 
 ---
 
@@ -99,12 +102,17 @@ describe("CounterComponent", () => {
 
 ```typescript
 import { TestBed } from "@angular/core/testing";
-import { HttpClientTestingModule, HttpTestingController } from "@angular/common/http/testing";
+import { provideHttpClient } from "@angular/common/http";
+import { provideHttpClientTesting, HttpTestingController } from "@angular/common/http/testing";
 
 describe("ProfileService", () => {
   it("requests profile", () => {
     TestBed.configureTestingModule({
-      imports: [HttpClientTestingModule]
+      providers: [
+        ProfileService,
+        provideHttpClient(),
+        provideHttpClientTesting()
+      ]
     });
     const service = TestBed.inject(ProfileService);
     const httpMock = TestBed.inject(HttpTestingController);
@@ -127,4 +135,6 @@ describe("ProfileService", () => {
 - Standalone Angular artifacts are tested with appropriate TestBed setup.
 - Signal/input/output behavior is asserted explicitly.
 - Async and HTTP behavior use deterministic Angular testing utilities.
+- HTTP tests use provider-based setup with `provideHttpClient()` before `provideHttpClientTesting()` for new code.
+- Router behavior uses harness-style tests where the workspace supports them.
 - Assertions verify user-visible behavior or contract-level outcomes, not incidental internals.

package/catalog/skills/angular-guidelines/agents/component-creator.md

@@ -27,6 +27,18 @@ Do not use this sub-agent for:
 
 ---
 
+## Style and Reactivity Checklist
+
+- Prefer feature-based organization and one primary Angular concept per file.
+- Use `protected` for class members that are only read by the template.
+- Mark Angular-managed properties `readonly`, including `input`, `model`, `output`, and query values.
+- Prefer `[class]` and `[style]` bindings over `ngClass` and `ngStyle`.
+- Move complex template logic into TypeScript, usually as a `computed`.
+- Use `computed` for derived state and avoid `effect` for state propagation.
+- Use `resource` or `linkedSignal` only when the project Angular version supports them and they fit existing data patterns.
+
+---
+
 ## Template Snippets
 
 ### Minimal Standalone Component
@@ -122,3 +134,4 @@ export class CardComponent {
 - Templates use native control flow blocks, not legacy structural directives.
 - Host interaction includes required ARIA and keyboard semantics for interactive UI.
 - Change detection and state flow are OnPush-friendly and predictable.
+- Template-only members are `protected`, Angular-managed fields are `readonly`, and complex template logic is moved into `computed` values.

package/catalog/skills/angular-guidelines/agents/performance-reviewer.md

@@ -0,0 +1,62 @@
+# Angular Performance Reviewer
+
+## When to Use
+
+Use this sub-agent when:
+
+- Reviewing or improving Angular loading, runtime, change detection, or rendering performance.
+- Working on SSR, hydration, incremental hydration, `@defer`, lazy routes, image optimization, or bundle size.
+- Investigating slow interactions, excessive change detection, zone pollution, slow template expressions, or lifecycle bottlenecks.
+
+Do not use this sub-agent for:
+
+- Pure test-only tasks without performance behavior.
+- Non-Angular frontend performance work.
+- Speculative rewrites where no user-visible or measured bottleneck exists.
+
+---
+
+## Priority Checklist
+
+Work from highest signal to lowest. Stop once the request is solved; do not add unrelated optimizations.
+
+| Priority | Focus | Checks |
+| --- | --- | --- |
+| 1 | Measurement | Use Angular DevTools or Chrome DevTools Angular profiling to identify load, change detection, rendering, or lifecycle bottlenecks before changing code when practical. |
+| 2 | Loading performance | Prefer lazy routes for route-level splitting, `@defer` for non-critical or heavy UI, image optimization for visual content, and SSR/hydration for content-heavy or SEO-sensitive pages. |
+| 3 | Runtime performance | Check zoneless change detection support, OnPush-friendly state flow, slow template expressions, expensive lifecycle hooks, and zone pollution from timers or third-party libraries. |
+| 4 | SSR/hydration correctness | Keep server and client rendered content consistent, avoid browser-only conditionals in templates, use platform-specific providers, and prevent shared module/provider state from leaking across requests. |
+| 5 | Advanced loading | Use incremental hydration, custom `@defer` triggers, prefetching, or worker offloading only when the project version, bottleneck, and UX constraints justify them. |
+
+---
+
+## SSR and Hydration Guardrails
+
+- Avoid rendering different template content on server and client; mismatches can hurt hydration and layout stability.
+- Use `afterNextRender` or platform-specific providers for browser-only initialization instead of template-level platform checks.
+- Use factory providers for request-specific values on the server; avoid shared `useValue` objects for per-request data.
+- Keep `@defer` placeholders accessible and avoid deferring initially visible content unless incremental hydration and layout constraints are handled.
+- Avoid nested `@defer` blocks with identical eager triggers that cause cascading loads.
+
+---
+
+## Reactivity and Change Detection Guardrails
+
+- Use signals and `computed` values for local derived state.
+- Avoid `effect` for propagating state changes; reserve it for side effects against non-reactive APIs.
+- Read signals before `await` inside reactive contexts.
+- Prefer OnPush-friendly inputs and immutable data flow in zone-based apps.
+- In zoneless-ready apps, avoid assumptions that depend on ZoneJS side effects.
+
+---
+
+## Review Output
+
+When reviewing performance, report:
+
+1. Highest-impact issue first, tied to the priority checklist.
+2. Concrete code-level recommendation using existing project patterns.
+3. Expected user-visible or measurable benefit.
+4. Verification path: Angular DevTools, Chrome DevTools Angular profiling, bundle output, Core Web Vitals, targeted test, or existing project command.
+
+If no meaningful performance issue is found, say so and avoid inventing speculative work.

package/catalog/skills/angular-guidelines/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "angular-guidelines",
   "title": "Angular Guidelines",
-  "description": "Guide Angular code generation and review using latest stable Angular verification and modern framework best practices.",
+  "description": "Guide Angular code generation, review, and performance tuning using latest stable Angular verification, official Angular skill guidance, and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects.",
   "portable": true,
   "tags": ["angular", "frontend", "workflow", "best-practices"],
   "detectors": ["angular"],
@@ -10,14 +10,15 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-03",
+    "last-edit": "2026-05-01",
     "license": "Apache-2.0",
-    "version": "1.1.1",
-    "changelog": "Added allowed-modes metadata to declare angular-guidelines sub-agent routing targets; improves discoverability of component-creator and angular-tester delegation modes; affects angular-guidelines manifest metadata",
-    "auto-invoke": "Generating, reviewing, or refactoring Angular code artifacts in Angular projects",
+    "version": "1.2.0",
+    "changelog": "Added curated official Angular skill and performance guidance with a dedicated performance-reviewer mode; improves SSR, hydration, reactivity, testing, and runtime optimization coverage; affects angular-guidelines routing, review checklists, and catalog discovery",
+    "auto-invoke": "Generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects",
     "allowed-modes": [
       "component-creator",
-      "angular-tester"
+      "angular-tester",
+      "performance-reviewer"
     ],
     "allowed-tools": [
       "Read",
@@ -35,7 +36,8 @@
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "agents/component-creator.md", "kind": "instruction" },
-    { "path": "agents/angular-tester.md", "kind": "instruction" }
+    { "path": "agents/angular-tester.md", "kind": "instruction" },
+    { "path": "agents/performance-reviewer.md", "kind": "instruction" }
   ],
   "dependencies": []
 }

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

@@ -1,13 +1,13 @@
 ---
 name: "frontend-design"
-description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, and includes post-generation motion and visual refinement phases."
+description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and GSAP-aware motion polish."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-05"
+  last-edit: "2026-05-03"
   license: "Apache-2.0"
-  version: "1.1.0"
-  changelog: "v1.1.0: Added design-context-setter agent for greenfield/DESIGN.md workflow; added visual-refiner agent for post-generation quality evaluation; added motion-designer agent for stack-aware micro-interactions; added aesthetic-archetypes reference asset; expanded SKILL.md routing map with optional motion and refinement phases; upgraded component-designer with interaction states checklist and aesthetic principles"
-  auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
+  version: "1.3.0"
+  changelog: "Added GSAP-aware motion routing through gsap-animation while preserving critique workflow; improves advanced frontend animation handoffs with official-source GSAP guidance; affects frontend-design motion sequencing, metadata, and catalog dependencies"
+  auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
   allowed-tools:
     - "Read"
     - "Grep"
@@ -15,6 +15,8 @@ skillMetadata:
     - "Bash"
     - "Edit"
     - "Write"
+    - "Task"
+    - "SubAgent"
 ---
 # Frontend Design Guide
 
@@ -45,8 +47,9 @@ Always run stack detection first. Never skip to design.
 | 0 (always first) | Detect framework, UI library, CSS approach, tokens, and existing patterns | [agents/stack-detector.md](agents/stack-detector.md) |
 | 0b (if no DESIGN.md and no existing components) | Gather design intent and create DESIGN.md | [agents/design-context-setter.md](agents/design-context-setter.md) |
 | 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
-| 2 (optional) | Add motion and micro-interactions | [agents/motion-designer.md](agents/motion-designer.md) |
-| 3 (optional) | Evaluate quality and refine the output | [agents/visual-refiner.md](agents/visual-refiner.md) |
+| 2 (mandatory after generation) | Challenge the output for AI slop, weak hierarchy, heuristic failures, and unclear product fit | [agents/critique.md](agents/critique.md) |
+| 3 (after critique) | Apply visual quality refinements routed by critique | [agents/visual-refiner.md](agents/visual-refiner.md) |
+| 4 (optional) | Add motion and micro-interactions, preferring GSAP handoff for advanced motion | [agents/motion-designer.md](agents/motion-designer.md) |
 
 ---
 
@@ -58,8 +61,9 @@ Always run stack detection first. Never skip to design.
 4. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
 5. **Scan existing tokens and components** — read what already exists before proposing anything.
 6. **Design with confirmed context only** — hand off to `component-designer` only after steps 2–4 are complete.
-7. **Optionally add motion** — invoke `motion-designer` if the component needs micro-interactions.
-8. **Optionally refine** — invoke `visual-refiner` for a quality pass before handoff.
+7. **Critique after generation** — invoke `critique` for a frontend-only challenge pass before polish.
+8. **Refine from critique** — invoke `visual-refiner` for visual fixes routed by critique.
+9. **Optionally add motion** — invoke `motion-designer` if critique, refinement, or the user identifies a motion need. For timelines, scroll reveals, richer micro-interactions, lifecycle-safe framework animation, or plugin decisions, route through `gsap-animation`.
 
 ---
 
@@ -190,8 +194,12 @@ Ready to implement?
   YES -> Hand off to component-designer with full confirmed context
 
 After generation:
+  -> Invoke critique to challenge design quality and route fixes
+  -> Invoke visual-refiner for critique-routed visual fixes
   -> Does the component need motion? -> Invoke motion-designer
-  -> Does the output need a quality pass? -> Invoke visual-refiner
+       -> Does motion need timelines, ScrollTrigger, framework cleanup, or plugins?
+            YES -> Use gsap-animation for official-source GSAP guidance
+            NO  -> Use confirmed stack primitives
 ```
 
 ---
@@ -275,7 +283,8 @@ find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
 - Stack detection procedure: [agents/stack-detector.md](agents/stack-detector.md)
 - Design context setup (greenfield): [agents/design-context-setter.md](agents/design-context-setter.md)
 - Component design rules: [agents/component-designer.md](agents/component-designer.md)
-- Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.md)
+- Frontend design critique: [agents/critique.md](agents/critique.md)
 - Visual quality refinement: [agents/visual-refiner.md](agents/visual-refiner.md)
+- Motion and micro-interactions: [agents/motion-designer.md](agents/motion-designer.md)
 - Full scan checklist: [assets/stack-scan-checklist.md](assets/stack-scan-checklist.md)
 - Aesthetic archetypes reference: [assets/aesthetic-archetypes.md](assets/aesthetic-archetypes.md)

package/catalog/skills/frontend-design/agents/critique.md

@@ -0,0 +1,190 @@
+# Critique
+
+## Precondition
+
+**Run only after `component-designer` has produced or proposed a concrete UI.**
+
+This agent is the frontend-design challenge gate. It acts like a frontend-only roaster: direct, skeptical, and useful. Its job is to decide whether the design feels intentional or like generic AI output before `visual-refiner` applies polish.
+
+Before critiquing:
+
+1. Confirm stack detection has completed and the user accepted the stack summary.
+2. Read `DESIGN.md` if it exists.
+3. Inspect the generated/proposed UI source and, when available, the rendered page.
+4. Compare against sampled project components, tokens, and interaction patterns.
+
+Do not use this agent when:
+
+- No concrete UI exists yet.
+- The request is only stack discovery or design brief creation.
+- The user explicitly asks to skip critique.
+
+---
+
+## Critique Principles
+
+- Challenge the design, not the user.
+- Name the strongest weakness first.
+- Prefer evidence from the codebase, `DESIGN.md`, or rendered UI over taste alone.
+- Keep the roast constructive: a sharp sentence that exposes the gap, followed by a fix path.
+- Do not apply changes in this agent. Route fixes to the right follow-up agent or skill.
+
+---
+
+## Evaluation Protocol
+
+Run all six passes. Do not skip a pass because the UI "mostly works."
+
+### Pass 1 - Anti-Slop Detection
+
+Flag visible tells of generic AI design. Use project evidence to decide whether a pattern is intentional or sloppy.
+
+| Area | Patterns to Challenge |
+| --- | --- |
+| Visual details | Glassmorphism everywhere, generic rounded rectangles with shadows, thick side accent borders, decorative tiny charts, unexplained glow effects |
+| Typography | Flat type hierarchy, overused default fonts, single font for every role, monospace as "technical" shorthand, all-caps body text |
+| Color and contrast | Purple/violet gradients by reflex, neon-on-dark by reflex, gradient text, pure black or pure white, gray text on colored backgrounds, low contrast |
+| Layout and space | Everything centered, hero metric blocks by default, identical card grids, monotonous spacing, nested cards, wrapping every section in cards, long line length |
+| Motion | Bounce/elastic easing, motion without state meaning, animated layout properties |
+| Interaction | Every button styled as primary, hidden actions, redundant labels, missing focus/disabled/loading states |
+| Responsive | Critical features hidden on mobile, touch targets too small, desktop layout merely squeezed |
+| General quality | Cramped padding, skipped heading levels, tiny body text, tight line height, wide tracking on body text, justified screen text |
+
+For each finding, include:
+
+- `what`: the pattern.
+- `why`: why it weakens this specific interface.
+- `fix`: the project-derived correction or the agent that should handle it.
+
+### Pass 2 - Design Intent Fit
+
+Check whether the UI serves the actual product context.
+
+- Audience: Does the visual language match who uses it?
+- Job: Does the layout prioritize the user's real task?
+- Brand: Does it follow `DESIGN.md` personality and anti-references?
+- Mode: Is this a brand surface where design is the product, or a product surface where design serves repeated use?
+- Distinction: Would this still be recognizable if the logo and copy were removed?
+
+### Pass 3 - Nielsen Heuristics
+
+Score only what can be judged from the current UI. Use `0` to `4`.
+
+| Heuristic | Score Meaning |
+| --- | --- |
+| Visibility of status | Loading, progress, saved, empty, and error states are clear |
+| Match with real world | Labels, groupings, and controls use language the audience recognizes |
+| User control | Escape, undo, cancel, back, and destructive action safety are available where needed |
+| Consistency and standards | Component patterns match the project and platform expectations |
+| Error prevention | The UI prevents likely mistakes before they happen |
+| Recognition over recall | Available actions and context are visible without guessing |
+| Flexibility and efficiency | Frequent users are not slowed by decorative friction |
+| Aesthetic and minimalist design | Every visible element earns its place |
+
+### Pass 4 - Cognitive Load
+
+Count failures. A good interface reduces decisions, not just pixels.
+
+- Too many equally weighted actions.
+- Too many containers or borders.
+- Too many text styles.
+- Repeated explanatory copy.
+- Competing focal points.
+- Unclear next action.
+- Dense controls without grouping.
+- Decorative elements that look interactive.
+
+### Pass 5 - Persona Pressure Tests
+
+Use three personas unless `DESIGN.md` defines better ones:
+
+- `The new user`: understands the first meaningful action in under five seconds.
+- `The returning user`: can complete the repeated task quickly without rereading the page.
+- `The skeptic`: has seen generic AI/SaaS layouts and needs proof this is specific.
+
+Score each `0` to `4` and name the failure if the score is below `3`.
+
+### Pass 6 - Route the Fixes
+
+Every priority issue must name the next tool to use:
+
+| Issue Type | Route To |
+| --- | --- |
+| Visual hierarchy, spacing, color, typography, card depth | `visual-refiner` |
+| Missing or excessive motion, easing, reduced-motion coverage | `motion-designer` |
+| Component API, structure, state model, or markup contract | `component-designer` |
+| Missing product/design intent or unresolved brand direction | `design-context-setter` |
+| Accessibility, semantics, keyboard, contrast, screen-reader behavior | `accessibility-audit` |
+| Security-sensitive UI flows, release gates, unsafe forms | `project-security` |
+| Test coverage for states, responsiveness, or interaction behavior | stack-specific tester or `test-driven-development` |
+
+If a fix needs another sub-agent or skill, call that out explicitly. Do not silently merge responsibilities.
+
+When the user or host workflow asks to continue after critique, invoke the routed agent that matches the highest-priority fix. Use one follow-up agent at a time so ownership stays clear. Do not fix issues inside `critique`; delegate to `visual-refiner`, `motion-designer`, `component-designer`, `design-context-setter`, or the named external skill.
+
+---
+
+## Output Format
+
+Use this compact report:
+
+```text
+FRONTEND DESIGN CRITIQUE
+------------------------
+Verdict: [pass / watch / fail] - [strongest reason]
+Roast: [one constructive jab at the weakest design decision]
+
+Scores:
+- Anti-slop: [0-4] ([specific tells])
+- Heuristics: [0-4 average] ([lowest heuristic])
+- Cognitive load: [N/8 failures]
+- Persona fit: [0-4 average] ([weakest persona])
+
+Priority Fixes:
+1. [what] - [why] - Fix: [specific change] - Use next: [agent/skill]
+2. [what] - [why] - Fix: [specific change] - Use next: [agent/skill]
+3. [what] - [why] - Fix: [specific change] - Use next: [agent/skill]
+
+Questions:
+- [only questions the interface cannot answer from project context]
+```
+
+Keep priority fixes to three to five items. If everything is acceptable, still name the one highest-leverage improvement before passing the work to `visual-refiner`.
+
+---
+
+## Severity Rules
+
+Use these verdicts:
+
+| Verdict | Meaning |
+| --- | --- |
+| `pass` | No slop tells or blockers; only minor polish remains |
+| `watch` | Direction is viable, but one or two design decisions need correction |
+| `fail` | The UI reads as generic, incoherent, inaccessible, or mismatched to product intent |
+
+Raise severity when:
+
+- The same slop pattern appears in multiple sections.
+- The issue affects comprehension, conversion, task completion, or accessibility.
+- The design contradicts `DESIGN.md` or sampled project components.
+- The UI hides critical function on mobile.
+
+Lower severity when:
+
+- The pattern is established elsewhere in the project and works for the audience.
+- The issue is isolated and easy for `visual-refiner` to correct.
+- The user explicitly requested the aesthetic and it does not harm usability.
+
+---
+
+## Finished Work
+
+This agent is done when it has:
+
+- Given a verdict.
+- Named the weakest design decision.
+- Scored anti-slop, heuristics, cognitive load, and persona fit.
+- Listed three to five prioritized fixes.
+- Routed each fix to the exact next agent or skill.
+- Asked only unresolved product/design questions.