agy-superpowers 5.0.8 → 5.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.0.8",
+  "version": "5.0.9",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/rules/superpowers.md

@@ -14,6 +14,8 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 
 ## Available Skills
 
+### Development Workflow
+
 | Skill | When to Use |
 |---|---|
 | `brainstorming` | Before ANY creative work — adding features, building components, modifying behavior |
@@ -29,6 +31,57 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 | `finishing-a-development-branch` | When tasks complete — merge / PR / discard |
 | `dispatching-parallel-agents` | When running concurrent subagent workflows |
 | `writing-skills` | When creating new skills |
+| `using-superpowers` | When starting any conversation — find and use skills |
+
+### Technical Roles
+
+| Skill | When to Use |
+|---|---|
+| `frontend-developer` | Web UI, component architecture, React/Vue/Svelte/Vanilla. Has `react-rules/` (66 Vercel rules) and `vue-rules/` (44 antfu rules) |
+| `backend-developer` | APIs, server-side logic, database schemas |
+| `mobile-developer` | Mobile apps — React Native, Flutter, iOS, Android. Has `react-native-rules/` (38), `flutter-rules/` (8), `android-rules/` (17), `ios-rules/` (19) |
+| `game-developer` | Mobile game features, architecture decisions |
+| `game-design` | Game mechanics, core loops, progression, monetization |
+| `cto-architect` | System design, tech debt, scaling, architecture |
+| `saas-architect` | Multi-tenant SaaS architecture, tenant isolation |
+| `devops-engineer` | CI/CD, infrastructure, deployment, monitoring |
+| `security-engineer` | App security, auth, GDPR, security audits |
+
+### Business & Growth
+
+| Skill | When to Use |
+|---|---|
+| `product-manager` | Product requirements, feature prioritization, roadmap |
+| `data-analyst` | Metrics, funnels, cohort analysis, A/B tests |
+| `growth-hacker` | User acquisition, viral loops, activation funnels |
+| `monetization-strategist` | Pricing, freemium, IAP, unit economics |
+| `conversion-optimizer` | Landing pages, trial-to-paid, onboarding, CRO |
+| `retention-specialist` | Onboarding flows, churn reduction, re-engagement |
+| `customer-success-manager` | User support, feedback loops, NPS/CSAT |
+| `app-store-optimizer` | ASO, keyword strategy, screenshots, ratings |
+| `ux-designer` | UI design, wireframes, user research, IA |
+| `copywriter` | Landing copy, app descriptions, email sequences |
+
+### Marketing & Content
+
+| Skill | When to Use |
+|---|---|
+| `content-marketer` | Content strategy, SEO content, social media |
+| `seo-specialist` | Technical SEO, keywords, backlinks, organic search |
+| `community-manager` | Discord, Reddit, Slack community management |
+| `influencer-marketer` | UGC, creator partnerships, affiliate programs |
+| `paid-acquisition-specialist` | Meta Ads, Google Ads, Apple Search Ads, ROAS |
+
+### Infrastructure & Integration
+
+| Skill | When to Use |
+|---|---|
+| `api-design` | REST/GraphQL APIs, versioning, rate limiting |
+| `auth-and-identity` | Auth, SSO/SAML/OIDC, RBAC, session management |
+| `subscription-billing` | Stripe, IAP, trials, dunning flows |
+| `email-infrastructure` | Transactional email, SPF/DKIM/DMARC, deliverability |
+| `real-time-features` | WebSockets, SSE, live collaboration, presence |
+| `i18n-localization` | Internationalization, translations, localized ASO |
 
 ## How to Read a Skill (Antigravity)
 
@@ -50,3 +103,4 @@ Example: `.agent/skills/brainstorming/SKILL.md`
 - **TDD always**: Write failing tests first, then code
 - **Systematic over ad-hoc**: Follow the skill process, don't guess
 - **Evidence over claims**: Verify before declaring success
+

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

@@ -131,3 +131,42 @@ 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)

package/template/agent/skills/frontend-developer/references/react-rules/advanced-use-latest.md

@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```