agy-superpowers 5.0.7 → 5.0.9

package/template/agent/skills/frontend-developer/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: frontend-developer
+description: Use when building web UI, designing component architecture, or reviewing frontend code — regardless of framework (React, Vue, Svelte, etc.)
+---
+
+# Frontend Developer Lens
+
+> **Philosophy:** Component-first. User-perception-first. Accessibility is not optional.
+> Performance is felt by users, not measured in isolation.
+
+---
+
+## ⚠️ ASK BEFORE ASSUMING
+
+If the stack is unspecified, **DO NOT default to Create React App**. Ask:
+
+| What | Why it matters |
+|------|----------------|
+| **Framework?** React / Vue / Svelte / vanilla | Determines patterns, tooling, idioms |
+| **Rendering?** CSR / SSR / SSG / ISR | SEO and performance strategy |
+| **Design system?** Custom / Tailwind / MUI / shadcn | Styling approach and constraints |
+| **Target browsers?** Modern / IE support? | Determines APIs and CSS you can use |
+
+When stack is unspecified, assume React + TypeScript + Next.js (App Router).
+
+---
+
+## Core Instincts
+
+- **User perception is reality** — loading states, micro-animations, and feedback loops matter as much as the happy path
+- **Accessibility is load-bearing** — keyboard nav, screen readers, and contrast ratios affect real users
+- **Render cost is real** — unnecessary re-renders degrade UX; measure before optimizing
+- **Web Vitals are felt** — LCP, CLS, INP directly impact user satisfaction and SEO
+- **Mobile is primary** — design mobile-first; test at real viewport sizes on real devices
+
+---
+
+## Web Vitals Thresholds (Google Standard)
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| **LCP** (Largest Contentful Paint) | < 2.5s | 2.5–4s | > 4s |
+| **INP** (Interaction to Next Paint) | < 200ms | 200–500ms | > 500ms |
+| **CLS** (Cumulative Layout Shift) | < 0.1 | 0.1–0.25 | > 0.25 |
+| **FCP** (First Contentful Paint) | < 1.8s | 1.8–3s | > 3s |
+| **TTFB** (Time to First Byte) | < 800ms | 800ms–1.8s | > 1.8s |
+
+---
+
+## Bundle Size Guidelines
+
+| Bundle | Target | Action needed |
+|--------|--------|---------------|
+| Main JS (gzipped) | < 200KB | > 400KB: audit imports, code-split |
+| Per-route chunk | < 50KB | > 100KB: lazy load heavy deps |
+| CSS (gzipped) | < 50KB | > 100KB: purge unused styles |
+| Images (hero) | < 200KB | Use `next/image` or WebP + lazy load |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Skip loading/error/empty states | User thinks the app is broken | Always handle all 3 async states |
+| `onClick` only (no keyboard handler) | Keyboard users excluded | Use `<button>`; it's free keyboard support |
+| Index as list `key` in dynamic lists | Reorder causes state and animation bugs | Unique stable ID from data |
+| Images without `alt` or explicit dimensions | Screen reader fail + CLS score hit | `alt` always; `width`/`height` or `aspect-ratio` always |
+| `<div>` for interactive elements | Not focusable, not semantic, no ARIA | Use `<button>`, `<a>`, or explicit `role` + `tabIndex` |
+| Sequential `await` for independent fetches | Each waits on the previous (waterfall) | `Promise.all([fetchA(), fetchB()])` |
+| Barrel exports in app code (`index.ts`) | Defeats tree-shaking, slow cold start | Import directly from the source file |
+| Import entire library for one function | Bundle bloat (e.g., `import _ from 'lodash'`) | Named import or specific entry (`lodash/debounce`) |
+| Client fetch where SSR/SSG would work | Slower FCP, worse SEO | Server-render or static-generate whenever possible |
+
+---
+
+## Accessibility Quick Rules
+
+| Rule | Detail |
+|------|--------|
+| Color contrast (normal text) | ≥ 4.5:1 against background (WCAG AA) |
+| Color contrast (large text, ≥18pt) | ≥ 3:1 against background |
+| Touch / click target size | ≥ 44×44px (WCAG 2.5.5, Level AAA) |
+| Focus indicator | Must be visible; `outline: none` without replacement is a violation |
+| Form inputs | Must have `<label>` (associated via `for`/`id` or wrapping) |
+| Images | Decorative → `alt=""`, informative → descriptive `alt` |
+| Interactive elements order | DOM order must match visual order for keyboard users |
+
+---
+
+## Questions You Always Ask
+
+**When planning UI:**
+- What's the loading state? The error state? The empty state?
+- Is this accessible to keyboard and screen reader users?
+- What does this look like at 375px? At 1440px?
+- Is this content crawlable by search engines (SSR or SSG)?
+
+**When reviewing components:**
+- Does this cause layout shift (CLS)? Are image dimensions declared?
+- Can a user complete this entire flow using only the keyboard?
+- Is every form input associated with a visible `<label>`?
+- What's the bundle size delta from this new dependency?
+
+---
+
+## Red Flags in Code Review
+
+**Must fix:**
+- [ ] No loading/error/empty states for async data
+- [ ] Interactive elements unreachable by keyboard
+- [ ] Images without `alt` text or explicit dimensions (CLS risk)
+- [ ] Form inputs without associated `<label>` elements
+- [ ] Color contrast below 4.5:1 for body text
+
+**Should fix:**
+- [ ] Missing unique identifiers for list items
+- [ ] Large dependencies added without bundle size justification
+- [ ] Client-side fetch where server-rendering would work
+- [ ] `outline: none` without visible focus replacement
+
+---
+
+## Performance Debugging Checklist
+
+```
+Slow initial load  → Check bundle size, server render, remove unused deps
+Layout shift (CLS) → Set image dimensions, avoid injecting content above fold
+Janky interaction  → Use CSS transforms, avoid forced layout (getBoundingClientRect in loops)
+Too many re-renders → React DevTools Profiler → memo, useMemo, useCallback
+Slow data fetch    → Parallel with Promise.all(), SWR/React Query for cache
+Large images       → WebP format, srcset for responsive, lazy loading
+```
+
+---
+
+## Platform References
+
+When this skill is invoked, detect the project's framework and read
+the matching reference file(s) from `references/` before proceeding:
+
+| Stack indicator                         | Reference file                  |
+|-----------------------------------------|---------------------------------|
+| `next.config.js/ts` or `react` in deps  | `references/react-nextjs.md`    |
+| `nuxt.config.ts` or `vue` in deps       | `references/vue-nuxt.md`        |
+| `svelte.config.js` or `svelte` in deps  | `references/svelte-sveltekit.md`|
+| No framework deps / plain HTML          | `references/vanilla.md`         |
+
+If the stack is unclear, ask the user which framework they're using.
+
+### Granular Rules (React)
+
+For React/Next.js projects, `references/react-rules/` contains 66
+individual rule files from [Vercel's agent-skills](https://github.com/vercel-labs/agent-skills).
+Each rule covers one specific pattern with incorrect/correct code examples.
+
+Read `references/react-rules/_sections.md` for the full index
+organized by priority (CRITICAL → LOW). Reference individual rules
+when working on specific areas (waterfalls, bundle size, re-renders, SSR, etc.).
+
+### Granular Rules (Vue)
+
+For Vue/Nuxt projects, `references/vue-rules/` contains 44 individual
+rule files from [antfu/skills](https://github.com/antfu/skills)
+(sourced from [vuejs-ai/skills](https://github.com/vuejs-ai/skills)),
+organized into three sub-directories:
+
+- `best-practices/` — Components, reactivity, composables, performance (22 files)
+- `router/` — Vue Router guards, navigation, lifecycle gotchas (8 files)
+- `testing/` — Vitest, composable testing, Pinia setup, async patterns (11 files)
+
+Read the `_index.md` in each sub-directory for an overview.

package/template/agent/skills/frontend-developer/references/react-nextjs.md

@@ -0,0 +1,343 @@
+# React + Next.js (App Router) Reference
+
+> **Philosophy:** Server-first. Components render on the server by default.
+> Client components are opt-in. React Server Components change everything.
+
+---
+
+## Project Setup & Detection
+
+**Stack indicators:** `next.config.js` / `next.config.ts`, `package.json` with `next` dependency.
+
+**Key config files:**
+
+| File | Purpose |
+|------|---------|
+| `next.config.js` / `.ts` | Next.js configuration (redirects, rewrites, images) |
+| `tsconfig.json` | TypeScript configuration |
+| `tailwind.config.ts` | TailwindCSS configuration (if used) |
+| `.env.local` | Local environment variables |
+| `middleware.ts` | Edge middleware (auth, redirects) |
+
+**Recommended project structure (App Router):**
+
+```
+app/
+  layout.tsx                  # Root layout (Server Component)
+  page.tsx                    # Home page
+  loading.tsx                 # Loading UI (Suspense boundary)
+  error.tsx                   # Error boundary
+  not-found.tsx               # 404 page
+  (auth)/
+    login/page.tsx
+    register/page.tsx
+  (dashboard)/
+    layout.tsx                # Dashboard layout with sidebar
+    page.tsx
+    settings/page.tsx
+  api/
+    route.ts                  # API route handlers
+components/
+  ui/                         # Reusable UI components (shadcn, etc.)
+  forms/                      # Form-specific components
+lib/
+  db.ts                       # Database client
+  auth.ts                     # Auth configuration
+  utils.ts                    # Utility functions
+  actions/                    # Server Actions
+hooks/                        # Custom React hooks (client-side)
+```
+
+---
+
+## Architecture Patterns
+
+### Server vs Client Components
+
+```
+Server Components (default)    | Client Components ('use client')
+-------------------------------|----------------------------------
+Fetch data directly            | useState, useEffect, event handlers
+Access backend resources       | Browser APIs (localStorage, etc.)
+Keep secrets server-side       | Interactivity (onClick, onChange)
+Reduce bundle size             | Third-party client libraries
+```
+
+**Rules of thumb:**
+- Start everything as Server Component
+- Add `'use client'` only when you need interactivity or browser APIs
+- Push `'use client'` boundary as low as possible in the component tree
+- Server Components can render Client Components (not vice versa)
+
+### Data Fetching
+
+| Pattern | Use When |
+|---------|----------|
+| **Server Components + `fetch`** | Default — data fetched at request or build time |
+| **Server Actions** | Mutations (forms, button clicks) |
+| **Route Handlers** (`app/api/`) | External API clients, webhooks |
+| **`use` hook + Suspense** | Streaming data to client |
+| **React Query / SWR** | Client-side caching, polling, optimistic updates |
+
+**Server Actions** replace API routes for mutations:
+
+```tsx
+// lib/actions/user.ts
+'use server'
+
+export async function updateProfile(formData: FormData) {
+  const name = formData.get('name') as string
+  await db.user.update({ where: { id: userId }, data: { name } })
+  revalidatePath('/profile')
+}
+```
+
+### State Management
+
+| Approach | Use When |
+|----------|----------|
+| **Server state** (fetch in Server Components) | Most data — no client state needed |
+| **React Context** | Theme, locale, auth — infrequently changing |
+| **Zustand** | Complex client-side state |
+| **URL state** (`useSearchParams`) | Filters, pagination, shareable state |
+| **React Query / SWR** | Client-side server state cache |
+
+---
+
+## Performance Optimization
+
+### Core Web Vitals (Target)
+
+| Metric | Good | Poor |
+|--------|------|------|
+| **LCP** | < 2.5s | > 4s |
+| **INP** | < 200ms | > 500ms |
+| **CLS** | < 0.1 | > 0.25 |
+
+### Key Optimizations
+
+1. **Eliminate waterfalls** — parallel data fetching is critical.
+
+```tsx
+// ❌ Bad: sequential (waterfall)
+const user = await getUser(id)
+const posts = await getPosts(user.id)
+
+// ✅ Good: parallel
+const [user, posts] = await Promise.all([getUser(id), getPosts(id)])
+```
+
+2. **`next/image`** — automatic optimization, lazy loading, responsive sizes.
+
+3. **Dynamic imports** — code-split heavy components.
+
+```tsx
+const HeavyChart = dynamic(() => import('@/components/Chart'), {
+  loading: () => <ChartSkeleton />,
+  ssr: false, // client-only if needed
+})
+```
+
+4. **Streaming with Suspense** — show content progressively.
+
+```tsx
+export default function Page() {
+  return (
+    <main>
+      <Header />  {/* instant */}
+      <Suspense fallback={<PostsSkeleton />}>
+        <Posts />  {/* streams when ready */}
+      </Suspense>
+    </main>
+  )
+}
+```
+
+5. **Route segment config** — control caching behavior.
+
+```tsx
+export const dynamic = 'force-dynamic' // or 'auto', 'force-static'
+export const revalidate = 3600 // ISR: revalidate every hour
+```
+
+---
+
+## Common Libraries Ecosystem
+
+| Category | Recommended | Alternative |
+|----------|-------------|-------------|
+| **UI** | `shadcn/ui` (copy-paste) | `radix-ui`, `headless-ui` |
+| **Styling** | `tailwindcss` | `css modules`, `vanilla-extract` |
+| **Forms** | `react-hook-form` + `zod` | `formik` |
+| **Auth** | `next-auth` / `clerk` | `lucia`, `supabase auth` |
+| **Database** | `prisma` / `drizzle` | `kysely` |
+| **Server State** | `@tanstack/react-query` | `swr` |
+| **Tables** | `@tanstack/react-table` | `ag-grid` |
+| **Email** | `react-email` + `resend` | `nodemailer` |
+| **Testing** | `vitest` + `@testing-library/react` | `jest` |
+| **E2E** | `playwright` | `cypress` |
+| **Analytics** | `@vercel/analytics` | `posthog` |
+| **Icons** | `lucide-react` | `heroicons`, `phosphor` |
+| **Date** | `date-fns` | `dayjs` |
+
+---
+
+## Anti-Patterns & Gotchas
+
+| ❌ Don't | Why | ✅ Do Instead |
+|----------|-----|---------------|
+| `'use client'` on every component | Bloats bundle, loses RSC benefits | Default to Server Components |
+| `useEffect` for data fetching | Waterfall, no SSR, loading state | Fetch in Server Components |
+| Sequential `await` for independent data | Each waits on previous (waterfall) | `Promise.all()` |
+| `localStorage` in Server Component | Doesn't exist on server, hydration mismatch | Move to Client Component |
+| Barrel exports (`index.ts`) | Defeats tree-shaking, slow cold start | Import directly from source file |
+| `next/router` (Pages Router) | Legacy | `next/navigation` (App Router) |
+| Missing `loading.tsx` | No loading UI, blank screen | Add `loading.tsx` per route segment |
+| Missing `error.tsx` | Unhandled errors crash entire page | Add `error.tsx` error boundaries |
+| Fetch in Client Component for initial data | Extra round trip, no SSR | Pass data from Server Component as props |
+| `console.log` in Server Components | Logs on server, not browser | Use proper logging (pino, winston) |
+
+---
+
+## Testing
+
+| Layer | Tool | Purpose |
+|-------|------|---------|
+| **Unit** | Vitest + Testing Library | Components, hooks, utils |
+| **Integration** | Vitest + MSW | API mocking, server actions |
+| **E2E** | Playwright | Full user flows |
+| **Visual** | Chromatic / Percy | Visual regression |
+
+---
+
+## Deployment & Distribution
+
+### Vercel (recommended for Next.js)
+
+```bash
+# Deploy
+vercel deploy          # Preview
+vercel --prod          # Production
+
+# Environment variables
+vercel env add         # Add env var
+```
+
+### Self-hosted
+
+```bash
+# Build
+next build
+
+# Start (requires Node.js server)
+next start
+
+# Docker
+FROM node:20-alpine
+COPY . .
+RUN npm ci && npm run build
+CMD ["npm", "start"]
+```
+
+### Static Export
+
+```js
+// next.config.js
+module.exports = { output: 'export' }
+```
+
+Generates static HTML — deployable to any CDN (Cloudflare Pages, Netlify, S3).
+
+---
+
+## Quick Reference — Granular Rules
+
+Individual rule files in `react-rules/` with detailed incorrect/correct
+code examples. Read the specific rule when working in that area.
+
+> Source: [Vercel agent-skills](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices)
+
+### CRITICAL — Eliminating Waterfalls
+
+- [async-parallel.md](react-rules/async-parallel.md) — Parallel data fetching
+- [async-suspense-boundaries.md](react-rules/async-suspense-boundaries.md) — Suspense for streaming
+- [async-defer-await.md](react-rules/async-defer-await.md) — Defer non-critical awaits
+- [async-dependencies.md](react-rules/async-dependencies.md) — Minimize async dependencies
+- [async-api-routes.md](react-rules/async-api-routes.md) — API route optimization
+
+### CRITICAL — Bundle Size
+
+- [bundle-dynamic-imports.md](react-rules/bundle-dynamic-imports.md) — Dynamic imports for code splitting
+- [bundle-barrel-imports.md](react-rules/bundle-barrel-imports.md) — Avoid barrel exports
+- [bundle-conditional.md](react-rules/bundle-conditional.md) — Conditional imports
+- [bundle-defer-third-party.md](react-rules/bundle-defer-third-party.md) — Defer third-party scripts
+- [bundle-preload.md](react-rules/bundle-preload.md) — Preload critical resources
+
+### HIGH — Server-Side Performance
+
+- [server-parallel-fetching.md](react-rules/server-parallel-fetching.md) — Parallel server fetching
+- [server-cache-react.md](react-rules/server-cache-react.md) — React cache for dedup
+- [server-cache-lru.md](react-rules/server-cache-lru.md) — LRU cache for hot data
+- [server-hoist-static-io.md](react-rules/server-hoist-static-io.md) — Hoist static I/O
+- [server-dedup-props.md](react-rules/server-dedup-props.md) — Dedup prop fetching
+- [server-after-nonblocking.md](react-rules/server-after-nonblocking.md) — Non-blocking after()
+- [server-auth-actions.md](react-rules/server-auth-actions.md) — Auth in server actions
+- [server-serialization.md](react-rules/server-serialization.md) — Serialization optimization
+
+### MEDIUM-HIGH — Client-Side Data
+
+- [client-swr-dedup.md](react-rules/client-swr-dedup.md) — SWR deduplication
+- [client-event-listeners.md](react-rules/client-event-listeners.md) — Event listener cleanup
+- [client-localstorage-schema.md](react-rules/client-localstorage-schema.md) — localStorage versioning
+- [client-passive-event-listeners.md](react-rules/client-passive-event-listeners.md) — Passive listeners
+
+### MEDIUM — Re-render Optimization
+
+- [rerender-memo.md](react-rules/rerender-memo.md) — React.memo usage
+- [rerender-derived-state.md](react-rules/rerender-derived-state.md) — Derived state pattern
+- [rerender-derived-state-no-effect.md](react-rules/rerender-derived-state-no-effect.md) — No useEffect for derived state
+- [rerender-functional-setstate.md](react-rules/rerender-functional-setstate.md) — Functional setState
+- [rerender-lazy-state-init.md](react-rules/rerender-lazy-state-init.md) — Lazy state initialization
+- [rerender-no-inline-components.md](react-rules/rerender-no-inline-components.md) — No inline components
+- [rerender-transitions.md](react-rules/rerender-transitions.md) — useTransition for heavy updates
+- [rerender-use-deferred-value.md](react-rules/rerender-use-deferred-value.md) — useDeferredValue
+- [rerender-use-ref-transient-values.md](react-rules/rerender-use-ref-transient-values.md) — useRef for transient values
+- [rerender-split-combined-hooks.md](react-rules/rerender-split-combined-hooks.md) — Split combined hooks
+- [rerender-defer-reads.md](react-rules/rerender-defer-reads.md) — Defer expensive reads
+- [rerender-dependencies.md](react-rules/rerender-dependencies.md) — Dependency optimization
+- [rerender-memo-with-default-value.md](react-rules/rerender-memo-with-default-value.md) — Memo with defaults
+- [rerender-move-effect-to-event.md](react-rules/rerender-move-effect-to-event.md) — Move effects to events
+- [rerender-simple-expression-in-memo.md](react-rules/rerender-simple-expression-in-memo.md) — Simple expressions
+
+### MEDIUM — Rendering Performance
+
+- [rendering-conditional-render.md](react-rules/rendering-conditional-render.md) — Conditional rendering
+- [rendering-hoist-jsx.md](react-rules/rendering-hoist-jsx.md) — Hoist static JSX
+- [rendering-content-visibility.md](react-rules/rendering-content-visibility.md) — CSS content-visibility
+- [rendering-resource-hints.md](react-rules/rendering-resource-hints.md) — Resource hints
+- [rendering-script-defer-async.md](react-rules/rendering-script-defer-async.md) — Script defer/async
+- [rendering-hydration-no-flicker.md](react-rules/rendering-hydration-no-flicker.md) — No hydration flicker
+- [rendering-hydration-suppress-warning.md](react-rules/rendering-hydration-suppress-warning.md) — Suppress hydration warnings
+- [rendering-usetransition-loading.md](react-rules/rendering-usetransition-loading.md) — useTransition loading
+- [rendering-activity.md](react-rules/rendering-activity.md) — Activity API
+- [rendering-animate-svg-wrapper.md](react-rules/rendering-animate-svg-wrapper.md) — SVG animation
+- [rendering-svg-precision.md](react-rules/rendering-svg-precision.md) — SVG precision
+
+### LOW — JavaScript & Advanced
+
+- [js-early-exit.md](react-rules/js-early-exit.md) — Early exit patterns
+- [js-set-map-lookups.md](react-rules/js-set-map-lookups.md) — Set/Map for lookups
+- [js-index-maps.md](react-rules/js-index-maps.md) — Index maps
+- [js-cache-function-results.md](react-rules/js-cache-function-results.md) — Cache function results
+- [js-flatmap-filter.md](react-rules/js-flatmap-filter.md) — flatMap over filter+map
+- [js-combine-iterations.md](react-rules/js-combine-iterations.md) — Combine iterations
+- [js-hoist-regexp.md](react-rules/js-hoist-regexp.md) — Hoist RegExp
+- [js-length-check-first.md](react-rules/js-length-check-first.md) — Length check first
+- [js-tosorted-immutable.md](react-rules/js-tosorted-immutable.md) — toSorted immutable
+- [js-min-max-loop.md](react-rules/js-min-max-loop.md) — Min/max in loops
+- [js-cache-property-access.md](react-rules/js-cache-property-access.md) — Cache property access
+- [js-cache-storage.md](react-rules/js-cache-storage.md) — Cache Storage API
+- [js-batch-dom-css.md](react-rules/js-batch-dom-css.md) — Batch DOM/CSS updates
+- [advanced-event-handler-refs.md](react-rules/advanced-event-handler-refs.md) — Event handler refs
+- [advanced-init-once.md](react-rules/advanced-init-once.md) — Init once pattern
+- [advanced-use-latest.md](react-rules/advanced-use-latest.md) — useLatest pattern

package/template/agent/skills/frontend-developer/references/react-rules/_sections.md

@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL  
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH  
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH  
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM  
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM  
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM  
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW  
+**Description:** Advanced patterns for specific cases that require careful implementation.

package/template/agent/skills/frontend-developer/references/react-rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

package/template/agent/skills/frontend-developer/references/react-rules/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

package/template/agent/skills/frontend-developer/references/react-rules/advanced-init-once.md

@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)