accessibility-auditWCAG 2.2 AA audit — semantic HTML, axe-core + eslint-plugin-jsx-a11y, keyboard navigation, ARIA, color contrast, target size, focus-not-obscured, prefers-reduced-motion. Use when completing a new component, after design system changes, or before shipping. Not for form label/aria-describedby patterns
animation-qualityAudit and improve animations for 60fps, prefers-reduced-motion compliance, motion-feel (duration/easing), and accessibility. Use when jank appears in scroll/interaction, INP regresses, an animation auto-plays/loops or flashes, or before shipping. Not for diagnosing broad Core Web Vitals regressions
api-caching-optimizationReduce duplicate/over-fetching requests, tune cache policies by freshness, invalidate caches after mutations, and shape queries. Use when duplicate API requests appear, stale data shows after a write, TTFB exceeds 500ms, or before shipping. Not for route-level rendering strategy (use render-strategy
architecture-improvementReorganize a project into a feature-based folder structure with unidirectional imports. Use when adding a new feature conflicts with existing structure, when teammates can't find files, when circular dependencies appear in build logs, or at the start of a new quarter. Not for changes within a single
async-ux-statesEnsure every async view handles loading, error, and empty states correctly with proper Suspense boundaries and custom 404/500 pages. Use when QA reports blank screens, infinite spinners, or undefined exposure, or before shipping. Not for choosing route render strategy (use render-strategy-decision)
bundle-optimizationReduce initial JS bundle size via Bundle Analyzer, optimizePackageImports, code splitting, and unused-dep removal. Use when bundle exceeds target, after adding a large dependency, when Lighthouse Performance drops, or before shipping. Not for diagnosing runtime Core Web Vitals (use rendering-perform
cicd-pipelineSet up GitHub Actions for Next.js with parallel type-check / lint / test / build, dependency + Next.js caching, concurrency cancellation, Vercel Preview, branch protection, and least-privilege CI security. Use at project start, when manual deploys cause errors, or when the team grows. Coordinates wi
code-refactoringRefactor TypeScript/React code for readability and maintainability — remove `any`, name compound conditions, apply guard clauses, extract magic literals to constants, deduplicate shared logic. Use during PR review, before a feature touches a complex area, or on a weekly cadence. Not for component-le
component-qualityImprove React component design — split Container/Presentational, add useEffect cleanup, extract custom hooks, apply cva + cn() consistently, decide extraction with explicit criteria. Use when a pattern repeats 2+ times, a file exceeds 500 LOC, or PR review flags component complexity. Not for non-com
decision-recordsWrite RFC and ADR documents to capture technical decisions (including rejected alternatives) — Context / Options / Decision / Consequences format. Use before a hard-to-reverse architecture decision, when designing a large feature, when technical choices spark debate, or when PR reviewers request rat
design-system-constructionBuild or audit a Tailwind + cva + shadcn/ui design system with two-tier tokens, variants, theming, and 4-state Storybook stories. Use when starting a new project, addressing UI inconsistency, onboarding a designer, adding dark mode / theming, when arbitrary values (w-[347px]) accumulate, or when com
developer-experienceSet up DX baseline — ESLint + Prettier + husky + lint-staged + commitlint, strict TypeScript, path alias, t3-env for typed env vars, Node/package-manager pinning, .editorconfig, .vscode/extensions.json, CONTRIBUTING.md. Use at project start, during team onboarding, when ESLint warnings pile up, or l
form-uxBuild forms with correct loading, success, and error UX using Server Actions + react-hook-form + Zod. Use when adding a new form, after QA reports form bugs, when errors aren't announced or input is lost on submit, or before shipping. Not for general state-store selection (use state-management-decis
i18n-localizationSet up or audit internationalization — message extraction, locale routing strategy, server/client message split, ICU plurals, date/number/currency formatting, RTL, missing-key fallback, pseudo-localization testing. Use when adding a second locale, when hardcoded strings accumulate, or before going m
new-tech-evaluationEvaluate a new library, framework version, or AI integration with bundle size, TypeScript support, maintenance status, security/supply-chain, and migration + exit cost. POC + benchmark before adoption. Use at quarterly tech review, when a new library could solve a pain point, on a React/Next.js majo
observability-setupSet up Sentry for Next.js (error.tsx integration, Server Action capture), source-map upload for readable traces, PII scrubbing, release tagging, sampling/quota control, useReportWebVitals for CWV, structured logging, console.log replacement. Use before production deploy or when unexplained errors re
render-strategy-decisionChoose the right rendering strategy per Next.js route — SSG / ISR / SSR / CSR / Streaming + Suspense — driven by data shape, not by page type. Use when adding a new route, when a route unexpectedly renders dynamically, when performance issues prompt re-evaluation, or when a code review flags inconsi
rendering-performanceDiagnose and fix Core Web Vitals (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1) with measurement-first methodology. Use when Lighthouse drops, CWV field data fails, users report slowness, or before shipping. Not for when JS payload is the bottleneck (use bundle-optimization) or moving work to the server (use
responsive-designBuild mobile-first responsive layouts — breakpoint strategy, fluid type/space with clamp(), container queries, mobile viewport units (dvh) + overflow robustness, touch-target testing, responsive images. Use when adding a layout, when mobile bugs appear, or before shipping a public page. Not for codi
security-auditOWASP Top 10 audit for frontend — XSS via dangerouslySetInnerHTML, env-var leaks, token storage, CSRF, broken access control (IDOR), open redirect, CSP, Supabase RLS, CORS, Zod env validation. Use when adding auth, after handling external input, before shipping, or quarterly. Not for the initial env
seo-metadataApply Next.js Metadata API per route — title template, og:image, generateMetadata for dynamic pages, JSON-LD structured data, robots, sitemap, canonical, hreflang. Use when adding a new route, when search visibility drops, when rich results are needed, or before shipping. Not for choosing a route's
state-management-decisionsDecision framework for choosing the right state location — URL, server cache, local component, or shared/global store. Use when state-sync bugs appear, prop drilling gets deep (3+ levels), filters/tabs lose state on reload, or quarterly review. Not for form state specifically (use form-ux) or when t
tech-debt-managementInventory and prioritize technical debt — TODO/FIXME/HACK, any usage, deprecated APIs, untested logic — with impact × effort matrix. Use at quarter start, before a refactoring sprint, when a new teammate joins, or when feature velocity slows. Not for actually paying down debt (use code-refactoring)
test-strategyApply the Testing Trophy (mostly integration tests with RTL + MSW, sparing E2E with Playwright) and set coverage thresholds. Use before new feature work, after bug fixes, when CI coverage falls below target, or when tests are flaky or break on every refactor. Not for wiring coverage gates + Playwrig
third-party-scriptsAudit and optimize third-party scripts — analytics, tag managers, chat widgets, embeds — with the right loading strategy, performance budget, facades, and CSP/consent controls. Use when adding a script, when TBT/INP regress, when a GDPR/CCPA consent requirement arises, or before shipping. Not for fi