@yuaone/core 0.3.2 → 0.4.0

package/plugins/react/skills/ssr.md

@@ -0,0 +1,256 @@
+# React SSR/Hydration Expert Skill
+
+## Identity
+- domain: react
+- type: ssr
+- confidence: 0.85
+- persona: Senior full-stack React engineer with deep expertise in server-side rendering, Next.js App Router and Pages Router, React Server Components, streaming SSR, and hydration debugging. Understands the React fiber reconciliation process during hydration and the boundary between server and client execution.
+
+## Known Error Patterns
+
+### 1. Hydration Mismatch — Client-Only APIs
+- **symptoms**:
+  - "Text content does not match server-rendered HTML"
+  - "Hydration failed because the initial UI does not match"
+  - Content flickers on page load
+  - Different content shown before and after JavaScript loads
+  - "There was an error while hydrating" with full client re-render
+- **causes**:
+  - Direct access to `window`, `document`, `navigator`, `localStorage` in render
+  - `typeof window !== 'undefined'` check causing different output on server vs client
+  - `Date.now()`, `new Date().toLocaleString()` producing different values
+  - `Math.random()` in render path
+  - `navigator.userAgent` conditional rendering
+  - Third-party scripts/components that assume browser environment
+- **strategy**:
+  1. Move client-only code into `useEffect`: renders null/placeholder on server, real content on client
+  2. Create `useIsClient` hook:
+     ```
+     function useIsClient() {
+       const [isClient, setIsClient] = useState(false);
+       useEffect(() => setIsClient(true), []);
+       return isClient;
+     }
+     ```
+  3. Use `next/dynamic` with `{ ssr: false }` for entire components that need browser APIs
+  4. Use `suppressHydrationWarning` only for intentional mismatches (timestamps, user-specific content)
+  5. For dates, render a stable format on server and enhance on client
+  6. Wrap browser-API-dependent libraries in a client-only wrapper component
+- **tools**: grep, file_read, file_edit, shell_exec
+- **pitfalls**:
+  - `typeof window` checks in render cause hydration mismatches -- the check itself produces different branches
+  - `suppressHydrationWarning` only works on the direct element, not children
+  - Over-using `ssr: false` defeats the purpose of SSR -- only for truly client-only components
+
+### 2. useEffect vs useLayoutEffect in SSR
+- **symptoms**:
+  - "useLayoutEffect does nothing on the server" warning
+  - Flash of unstyled content (FOUC)
+  - Layout shift after hydration
+  - Measurements (getBoundingClientRect) returning 0 on server
+- **causes**:
+  - `useLayoutEffect` runs synchronously after DOM mutations -- not possible on server
+  - Using `useLayoutEffect` for client-side layout measurements
+  - CSS-in-JS libraries using `useLayoutEffect` for style injection
+  - Animation libraries using `useLayoutEffect` for initial measurements
+- **strategy**:
+  1. Use `useEffect` for most cases -- runs after paint, works on server
+  2. Create `useIsomorphicLayoutEffect`:
+     ```
+     const useIsomorphicLayoutEffect =
+       typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+     ```
+  3. Only use `useLayoutEffect` when you need synchronous DOM measurement before paint
+  4. For CSS-in-JS, ensure server-side style extraction is configured (styled-components: `ServerStyleSheet`)
+  5. Accept minor layout shift vs. blocking paint -- `useEffect` is usually better for UX
+- **tools**: grep, file_read, file_edit
+- **pitfalls**:
+  - The `useIsomorphicLayoutEffect` pattern is a workaround, not a solution -- consider if you really need layout effect
+  - `useLayoutEffect` blocks paint -- use sparingly, even on client
+  - Most "layout" needs can be handled with CSS (grid, flexbox) without JS measurement
+
+### 3. Server Components vs Client Components (Next.js 13+)
+- **symptoms**:
+  - "You're importing a component that needs useState/useEffect. It only works in a Client Component"
+  - "async/await is not yet supported in Client Components"
+  - Props serialization errors ("only plain objects can be passed to Client Components")
+  - "Functions cannot be passed directly to Client Components unless you explicitly expose it"
+  - Import errors when mixing server and client components
+- **causes**:
+  - Using hooks (`useState`, `useEffect`, `useContext`) in a Server Component
+  - Using event handlers (`onClick`, `onChange`) in a Server Component
+  - Using browser-only APIs in a Server Component
+  - Passing non-serializable props (functions, classes, Dates) from Server to Client Component
+  - Importing a Client Component into a Server Component without `'use client'` boundary
+- **strategy**:
+  1. Add `'use client'` directive at the top of files that need hooks, events, or browser APIs
+  2. Keep Server Components as the default -- only add `'use client'` when needed
+  3. Push `'use client'` boundary as low as possible in the tree
+  4. For non-serializable props, restructure: pass IDs instead of objects, use server actions
+  5. Use the "donut pattern": Server Component wraps Client Component which wraps Server Component (via children)
+  6. Server Components can import Client Components, but not vice versa (except via children)
+  7. Fetch data in Server Components, pass serializable data to Client Components
+- **tools**: grep, file_read, file_edit
+- **pitfalls**:
+  - `'use client'` does NOT make it client-only -- it creates a boundary. The component still renders on server for SSR
+  - Do NOT add `'use client'` to a layout file unless absolutely necessary -- it opts out all children from Server Components
+  - `'use server'` is for Server Actions (mutations), NOT for making a Server Component
+
+### 4. Dynamic Imports and Code Splitting
+- **symptoms**:
+  - Large initial bundle size
+  - Slow Time to Interactive (TTI)
+  - Components that only show on interaction loaded upfront
+  - SSR errors from client-only libraries
+  - Flash of loading state on navigation
+- **causes**:
+  - All components loaded eagerly in the initial bundle
+  - Heavy libraries (charts, editors, maps) included in server bundle
+  - No code splitting for route-level or feature-level components
+  - Client-only libraries imported at top level
+- **strategy**:
+  1. Use `next/dynamic` for heavy or client-only components:
+     ```
+     const Chart = dynamic(() => import('./Chart'), {
+       loading: () => <ChartSkeleton />,
+       ssr: false,
+     });
+     ```
+  2. Use `React.lazy` + `Suspense` for CSR-only apps:
+     ```
+     const LazyComponent = React.lazy(() => import('./Heavy'));
+     <Suspense fallback={<Skeleton />}><LazyComponent /></Suspense>
+     ```
+  3. Route-level code splitting is automatic in Next.js App Router
+  4. Use `loading.tsx` files for route-level loading UI in App Router
+  5. For shared layouts, use route groups `(group)` to avoid unnecessary re-renders
+  6. Analyze bundle with `@next/bundle-analyzer` to identify split opportunities
+- **tools**: file_read, file_edit, shell_exec, grep
+- **pitfalls**:
+  - `React.lazy` does NOT work with SSR -- use `next/dynamic` in Next.js
+  - Do NOT lazy-load components that appear above the fold -- they should be in the initial bundle
+  - `ssr: false` means the component renders nothing until JS loads -- bad for SEO-critical content
+
+### 5. Streaming SSR Patterns
+- **symptoms**:
+  - Slow Time to First Byte (TTFB)
+  - Entire page blocks on slowest data fetch
+  - Users see blank page until all data loads
+  - Waterfall data fetching pattern
+  - Long server response times
+- **causes**:
+  - All data fetched before any HTML is sent (`getServerSideProps` blocking pattern)
+  - No Suspense boundaries to enable streaming
+  - Monolithic page component that needs all data at once
+  - Database queries running sequentially instead of in parallel
+- **strategy**:
+  1. Use Suspense boundaries to stream parts of the page:
+     ```
+     <Suspense fallback={<HeaderSkeleton />}>
+       <Header />
+     </Suspense>
+     <Suspense fallback={<ContentSkeleton />}>
+       <SlowContent />  <!-- Streams in when ready -->
+     </Suspense>
+     ```
+  2. In App Router, use `async` Server Components with Suspense for streaming
+  3. Run independent data fetches in parallel with `Promise.all`
+  4. Use `loading.tsx` for route-level streaming boundaries
+  5. Critical content (header, hero) should be fast -- wrap slow content in Suspense
+  6. Use `generateStaticParams` for static generation when data is known at build time
+  7. Consider ISR (Incremental Static Regeneration) with `revalidate` for semi-static pages
+- **tools**: file_read, file_edit, shell_exec
+- **pitfalls**:
+  - Streaming only works with Node.js runtime, not Edge runtime for all cases
+  - Too many Suspense boundaries can cause visual "popcorn" effect -- group related content
+  - `loading.tsx` applies to the entire route segment -- be intentional about placement
+
+### 6. Data Fetching in Server Components
+- **symptoms**:
+  - Using `useEffect` for data fetching in App Router
+  - Unnecessary client-side waterfalls
+  - Duplicate requests (server + client fetching same data)
+  - Stale data issues with client-side caching
+  - N+1 query patterns
+- **causes**:
+  - Migrating Pages Router patterns to App Router without adaptation
+  - Not leveraging Server Component data fetching
+  - Missing Request Memoization (same URL fetched multiple times in same request)
+  - Not using `cache()` for database queries
+- **strategy**:
+  1. Fetch data directly in Server Components (no hooks needed):
+     ```
+     async function UserPage({ params }) {
+       const user = await getUser(params.id);  // runs on server
+       return <UserProfile user={user} />;
+     }
+     ```
+  2. Use `cache()` from React for request-level deduplication:
+     ```
+     const getUser = cache(async (id: string) => {
+       return db.user.findUnique({ where: { id } });
+     });
+     ```
+  3. Parallel fetching: `const [user, posts] = await Promise.all([getUser(id), getPosts(id)])`
+  4. Use Server Actions for mutations (forms, button clicks)
+  5. Revalidate with `revalidatePath` or `revalidateTag` after mutations
+  6. Use `unstable_cache` for cross-request caching (with tags for invalidation)
+- **tools**: file_read, file_edit, grep
+- **pitfalls**:
+  - `fetch` in Server Components is auto-memoized in Next.js -- manual dedup may not be needed
+  - `cache()` is request-scoped -- it does NOT cache across requests
+  - Do NOT use `getServerSideProps` in App Router -- use Server Components instead
+  - Server Actions are NOT GET requests -- do not use them for data fetching
+
+### 7. Metadata and SEO in SSR
+- **symptoms**:
+  - Missing or incorrect meta tags in page source
+  - Social media previews not working (Open Graph)
+  - Search engines not indexing dynamic content
+  - Duplicate title tags
+  - Missing canonical URLs
+- **causes**:
+  - Using client-side `document.title` instead of framework metadata
+  - Not using `generateMetadata` in App Router
+  - Missing `Head` component in Pages Router
+  - Dynamic OG images not configured
+- **strategy**:
+  1. App Router: export `metadata` or `generateMetadata` from page/layout:
+     ```
+     export async function generateMetadata({ params }) {
+       const post = await getPost(params.id);
+       return { title: post.title, description: post.excerpt };
+     }
+     ```
+  2. Pages Router: use `next/head` in every page
+  3. Configure OG images with `opengraph-image.tsx` or `generateImageMetadata`
+  4. Use `robots.txt` and `sitemap.xml` (App Router: `app/robots.ts`, `app/sitemap.ts`)
+  5. Add structured data (JSON-LD) in Server Components
+- **tools**: file_read, file_edit, grep
+- **pitfalls**:
+  - `<title>` in client components does not affect SSR HTML -- crawlers may not see it
+  - `generateMetadata` runs on the server -- do not use hooks or browser APIs in it
+  - Test with `curl` or "View Source" to verify server-rendered HTML, not browser DevTools
+
+## Tool Sequence
+1. **grep** -- Search for hydration-related errors, `'use client'` directives, and SSR patterns
+2. **file_read** -- Read the problematic component and its parent chain
+3. **grep** -- Search for `window`, `document`, `localStorage`, `navigator` usage in render paths
+4. **grep** -- Search for `useEffect`, `useLayoutEffect`, `useState` to understand client/server split
+5. **file_read** -- Read Next.js config (`next.config.js`) and layout files
+6. **file_edit** -- Apply SSR-safe fixes (useEffect wrapping, dynamic imports, use client directive)
+7. **shell_exec** -- Run `next build` to verify no build errors
+8. **shell_exec** -- Run `next dev` and check browser console for hydration warnings
+9. **grep** -- Verify no remaining hydration mismatches in build output
+
+## Validation Checklist
+- [ ] No hydration mismatch warnings in browser console
+- [ ] `next build` passes without errors
+- [ ] Server-rendered HTML contains expected content (check with `curl` or View Source)
+- [ ] Client-only components properly wrapped with `dynamic({ ssr: false })` or `useEffect`
+- [ ] `'use client'` directives are at the lowest possible level
+- [ ] No `useLayoutEffect` warnings on server
+- [ ] SEO meta tags present in server-rendered HTML
+- [ ] Page loads meaningfully without JavaScript (progressive enhancement)
+- [ ] Streaming Suspense boundaries placed around slow content
+- [ ] No unnecessary client-side data fetching that could be done on server

package/plugins/react/skills/test.md

@@ -0,0 +1,273 @@
+# React Test Generator Skill
+
+## Identity
+- domain: react
+- type: testing
+- confidence: 0.85
+- persona: Senior test engineer specializing in React Testing Library, MSW for API mocking, and user-centric testing philosophy. Expert in writing tests that resemble how users interact with software, avoiding implementation detail testing.
+
+## Known Error Patterns
+
+### 1. Testing Implementation Details
+- **symptoms**:
+  - Tests break when refactoring internal component structure
+  - Tests use `wrapper.instance()` or access internal state
+  - Tests assert on class names, CSS properties, or DOM structure
+  - Tests mock internal hooks or child component rendering
+  - Tests break from renaming internal variables
+- **causes**:
+  - Using Enzyme-style testing patterns with RTL
+  - Testing "how" instead of "what" the component does
+  - Excessive mocking of internal modules
+  - Selecting elements by class name or test ID instead of role
+- **strategy**:
+  1. Query by role: `getByRole('button', { name: /submit/i })`
+  2. Query by label: `getByLabelText(/email/i)`
+  3. Query by text: `getByText(/welcome/i)`
+  4. Use `getByTestId` only as last resort
+  5. Assert on visible output, not internal state
+  6. Test user interactions, not method calls
+- **tools**: file_read, file_edit, shell_exec
+- **pitfalls**:
+  - If you need `getByTestId` often, your component may lack proper accessibility
+  - Do NOT test that `setState` was called -- test that the UI changed
+  - Do NOT snapshot test frequently-changing components
+
+### 2. Async Testing Failures
+- **symptoms**:
+  - "not wrapped in act(...)" warnings
+  - Tests pass/fail intermittently (flaky tests)
+  - Assertion runs before async operation completes
+  - `waitFor` times out unexpectedly
+  - State updates after test cleanup
+- **causes**:
+  - Not awaiting async operations
+  - Using `getBy*` for elements that appear asynchronously (should use `findBy*`)
+  - Missing `await` on `userEvent` calls (v14+)
+  - Timer-dependent code without fake timers
+  - Missing MSW handlers causing real network requests
+- **strategy**:
+  1. Use `findBy*` for elements that appear after async work: `await screen.findByText(/loaded/i)`
+  2. Use `waitFor` for assertions that need retrying: `await waitFor(() => expect(...).toBe(...))`
+  3. Always `await` userEvent calls: `await user.click(button)`
+  4. Use `vi.useFakeTimers()` for timer-dependent code
+  5. Set up MSW handlers for all API calls in tests
+  6. Clean up with `afterEach` -- reset handlers, clear timers
+- **tools**: file_read, file_edit, shell_exec
+- **pitfalls**:
+  - `waitFor` should contain only assertions, not side effects
+  - Do NOT use `waitFor` with a `timeout` > 5000ms -- your test is probably wrong
+  - `findBy*` already wraps `waitFor` -- do not nest them
+
+### 3. Improper Mocking
+- **symptoms**:
+  - Tests pass but component fails in production
+  - Mocks do not match real API shape (type mismatch)
+  - Every test has extensive mock setup boilerplate
+  - Changing API requires updating dozens of mock files
+  - Tests do not catch real integration issues
+- **causes**:
+  - Manual mocking of `fetch`/`axios` instead of using MSW
+  - Mock data not matching actual API response types
+  - Over-mocking (mocking things that should be tested)
+  - Not using TypeScript-typed mock factories
+- **strategy**:
+  1. Use MSW for API mocking -- intercepts at network level
+  2. Define handlers per API endpoint: `rest.get('/api/users', (req, res, ctx) => ...)`
+  3. Create typed mock factories: `function createMockUser(overrides?: Partial<User>): User`
+  4. Share handlers across tests with a `handlers.ts` file
+  5. Override individual handlers per test: `server.use(rest.get('/api/users', errorHandler))`
+  6. Use `msw/node` for Vitest/Jest, `msw/browser` for Storybook
+- **tools**: file_read, file_edit, grep
+- **pitfalls**:
+  - MSW v2 uses a different API than v1 -- check which version is installed
+  - Do NOT mock `React.useState` or `React.useEffect` -- test the behavior they produce
+  - Mock at the highest appropriate level (network > module > function)
+
+### 4. Missing Edge Case Coverage
+- **symptoms**:
+  - Tests only cover the happy path
+  - No tests for loading states, error states, empty states
+  - No tests for boundary conditions (empty list, max length, special characters)
+  - No tests for keyboard navigation or screen reader
+  - Bugs found in production that should have been caught
+- **causes**:
+  - Rushing to meet coverage targets with superficial tests
+  - Not thinking about failure modes during test design
+  - No test plan or checklist
+  - Only testing what was explicitly specified
+- **strategy**:
+  1. For each component, test: render, interaction, loading, error, empty, edge
+  2. Test error boundaries: what happens when child throws
+  3. Test with empty data, null data, maximum data
+  4. Test keyboard interactions: Tab, Enter, Escape, Arrow keys
+  5. Test responsive behavior if component adapts to screen size
+  6. Test with slow network (MSW delay) for loading states
+- **tools**: file_read, file_edit, shell_exec
+- **pitfalls**:
+  - 100% code coverage does not mean 100% bug coverage -- focus on behavior coverage
+  - Do NOT write tests just to increase coverage numbers
+  - Edge cases are where most production bugs live
+
+### 5. Snapshot Testing Misuse
+- **symptoms**:
+  - Snapshot files are massive (1000+ lines)
+  - Developers blindly update snapshots with `--update`
+  - Snapshots break on every style change
+  - Snapshots do not catch meaningful regressions
+  - PR reviews skip snapshot diffs
+- **causes**:
+  - Snapshotting entire page/component trees
+  - Using snapshots as primary testing strategy
+  - Not combining with behavioral assertions
+  - Snapshot of dynamic content (dates, random IDs)
+- **strategy**:
+  1. Use inline snapshots for small, stable output: `expect(result).toMatchInlineSnapshot()`
+  2. Snapshot only the relevant portion, not the entire tree
+  3. Combine with behavioral tests -- snapshots supplement, not replace
+  4. Use `toMatchSnapshot` only for pure/stable components (icons, static layouts)
+  5. Review every snapshot update carefully in PRs
+  6. Prefer explicit assertions over snapshots for logic-heavy components
+- **tools**: file_read, file_edit
+- **pitfalls**:
+  - If you update snapshots without reviewing, you may be locking in a bug
+  - Snapshots with dynamic data (timestamps, UUIDs) will always fail -- mock or exclude
+  - Large snapshot files are a code smell -- your component may be too big
+
+## Test Structure Template
+
+### Basic Component Test
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect } from 'vitest';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('renders with label text', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
+  });
+
+  it('calls onClick when clicked', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<Button onClick={handleClick}>Click</Button>);
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click</Button>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+});
+```
+
+### Async Component Test with MSW
+```typescript
+import { render, screen } from '@testing-library/react';
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import { UserList } from './UserList';
+
+const server = setupServer(
+  http.get('/api/users', () => {
+    return HttpResponse.json([
+      { id: '1', name: 'Alice' },
+      { id: '2', name: 'Bob' },
+    ]);
+  })
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+describe('UserList', () => {
+  it('shows loading then users', async () => {
+    render(<UserList />);
+    expect(screen.getByText(/loading/i)).toBeInTheDocument();
+    expect(await screen.findByText('Alice')).toBeInTheDocument();
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+  });
+
+  it('shows error on API failure', async () => {
+    server.use(
+      http.get('/api/users', () => {
+        return HttpResponse.json({ message: 'Server Error' }, { status: 500 });
+      })
+    );
+    render(<UserList />);
+    expect(await screen.findByText(/error/i)).toBeInTheDocument();
+  });
+
+  it('shows empty message when no users', async () => {
+    server.use(
+      http.get('/api/users', () => {
+        return HttpResponse.json([]);
+      })
+    );
+    render(<UserList />);
+    expect(await screen.findByText(/no users/i)).toBeInTheDocument();
+  });
+});
+```
+
+### Custom Hook Test
+```typescript
+import { renderHook, act } from '@testing-library/react';
+import { useCounter } from './useCounter';
+
+describe('useCounter', () => {
+  it('initializes with default value', () => {
+    const { result } = renderHook(() => useCounter(0));
+    expect(result.current.count).toBe(0);
+  });
+
+  it('increments', () => {
+    const { result } = renderHook(() => useCounter(0));
+    act(() => result.current.increment());
+    expect(result.current.count).toBe(1);
+  });
+
+  it('resets to initial value', () => {
+    const { result } = renderHook(() => useCounter(5));
+    act(() => result.current.increment());
+    act(() => result.current.reset());
+    expect(result.current.count).toBe(5);
+  });
+});
+```
+
+## RTL Query Priority (Use in This Order)
+1. `getByRole` -- accessible role (button, heading, textbox, etc.)
+2. `getByLabelText` -- form elements with labels
+3. `getByPlaceholderText` -- input placeholders
+4. `getByText` -- visible text content
+5. `getByDisplayValue` -- current input value
+6. `getByAltText` -- images
+7. `getByTitle` -- title attribute
+8. `getByTestId` -- last resort, data-testid attribute
+
+## Tool Sequence
+1. **file_read** -- Read the target component to understand its behavior and props
+2. **grep** -- Search for existing test patterns in the project (test runner, assertion style)
+3. **grep** -- Check for MSW setup, test utilities, custom render wrappers
+4. **file_read** -- Read related hooks/stores that the component depends on
+5. **file_edit** -- Create the test file following project conventions
+6. **file_edit** -- Add MSW handlers if the component makes API calls
+7. **shell_exec** -- Run tests: `pnpm test` or `vitest run <file>`
+8. **shell_exec** -- Check coverage: `vitest run --coverage <file>`
+
+## Validation Checklist
+- [ ] Tests use `getByRole` or `getByLabelText` as primary queries (not `getByTestId`)
+- [ ] All async operations are properly awaited
+- [ ] Loading, success, error, and empty states are tested
+- [ ] User interactions are tested with `userEvent` (not `fireEvent`)
+- [ ] API calls are mocked with MSW (not manual fetch/axios mocks)
+- [ ] No "act(...)" warnings in test output
+- [ ] Tests do not depend on implementation details (class names, internal state)
+- [ ] All tests pass: `pnpm test`
+- [ ] No flaky tests (run 3x to verify)
+- [ ] Edge cases covered (empty input, max length, special characters)

package/plugins/react/strategies/build-fix.json

@@ -0,0 +1,43 @@
+{
+  "id": "build-fix",
+  "name": "React/Next.js Build Error Fix",
+  "description": "Four-phase strategy to collect, categorize, fix, and verify React/Next.js build errors",
+  "problemClass": "build_error",
+  "phases": [
+    {
+      "name": "Collect Build Errors",
+      "tools": ["shell_exec"],
+      "maxIterations": 2,
+      "successCriteria": "Full build output captured from 'pnpm build' or 'next build'. All error messages, file paths, and line numbers extracted. Error count documented."
+    },
+    {
+      "name": "Categorize Errors",
+      "tools": ["file_read", "grep"],
+      "maxIterations": 5,
+      "successCriteria": "Each error categorized as one of: (1) TypeScript type error — missing type, wrong type, generic inference failure, (2) Module not found — missing dependency, wrong import path, missing barrel export, (3) ESLint error — hooks rules, unused vars, import order, (4) Next.js specific — server/client boundary violation, metadata export error, route config issue, (5) Runtime error during SSG/ISR — data fetching failure, env var missing. Fix priority established (blocking errors first)."
+    },
+    {
+      "name": "Apply Fixes",
+      "tools": ["file_read", "file_edit", "shell_exec", "grep"],
+      "maxIterations": 10,
+      "successCriteria": "All categorized errors addressed. TypeScript errors fixed with proper types (no 'any' escape hatches). Missing modules installed or import paths corrected. ESLint errors fixed at source (not disabled). Next.js boundary issues resolved with 'use client'/'use server' directives. Each fix verified with incremental tsc --noEmit check."
+    },
+    {
+      "name": "Verify Clean Build",
+      "tools": ["shell_exec"],
+      "maxIterations": 3,
+      "successCriteria": "Full 'pnpm build' or 'next build' passes with zero errors. No new warnings introduced. Build output size is reasonable (no accidental bundle bloat). All existing tests pass. TypeScript strict mode passes (tsc --noEmit)."
+    }
+  ],
+  "exitCriteria": [
+    "pnpm build (or next build) passes with zero errors",
+    "tsc --noEmit passes",
+    "No new ESLint warnings or errors",
+    "All existing tests pass",
+    "No 'any' type escape hatches introduced",
+    "Bundle size has not increased significantly"
+  ],
+  "fallback": null,
+  "estimatedTokens": 4000,
+  "confidence": 0.80
+}

package/plugins/react/strategies/hook-loop-fix.json

@@ -0,0 +1,36 @@
+{
+  "id": "hook-loop-fix",
+  "name": "useEffect Infinite Loop Fix",
+  "description": "Three-phase strategy to identify, fix, and verify useEffect infinite loop / maximum update depth issues",
+  "problemClass": "infinite_render_loop",
+  "phases": [
+    {
+      "name": "Identify Loop Source",
+      "tools": ["grep", "file_read"],
+      "maxIterations": 5,
+      "successCriteria": "Specific useEffect identified that causes the loop. Dependency array analyzed. Root cause classified as one of: (1) missing dependency array, (2) object/array reference in deps creating new reference each render, (3) state setter in effect body with that state in deps, (4) function reference in deps recreated each render, (5) mutual state updates between multiple effects. Call stack or component name identified."
+    },
+    {
+      "name": "Fix Dependencies",
+      "tools": ["file_read", "file_edit"],
+      "maxIterations": 5,
+      "successCriteria": "Fix applied using appropriate technique: (a) add missing dependency array, (b) stabilize object/array deps with useMemo, (c) use functional state updater to remove state from deps, (d) wrap function deps in useCallback, (e) extract primitive values from objects for deps, (f) refactor mutual updates into useReducer. No eslint-disable comments added for react-hooks/exhaustive-deps. No TypeScript errors."
+    },
+    {
+      "name": "Verify Stability",
+      "tools": ["shell_exec", "grep"],
+      "maxIterations": 3,
+      "successCriteria": "Build passes. No 'Maximum update depth exceeded' errors. No 'Too many re-renders' errors. Component renders expected number of times (verify with React DevTools Profiler or console.log count). All existing tests pass. No new ESLint warnings from react-hooks/exhaustive-deps."
+    }
+  ],
+  "exitCriteria": [
+    "No infinite loop or maximum update depth errors",
+    "Build passes without errors",
+    "Component renders correct number of times",
+    "eslint react-hooks/exhaustive-deps passes without disable comments",
+    "All existing tests pass"
+  ],
+  "fallback": null,
+  "estimatedTokens": 2000,
+  "confidence": 0.85
+}

package/plugins/react/strategies/hydration-fix.json

@@ -0,0 +1,42 @@
+{
+  "id": "hydration-fix",
+  "name": "Hydration Mismatch Fix",
+  "description": "Multi-phase strategy to diagnose and resolve React hydration mismatches in SSR/Next.js applications",
+  "problemClass": "hydration_error",
+  "phases": [
+    {
+      "name": "Reproduce & Collect Evidence",
+      "tools": ["shell_exec", "grep", "file_read"],
+      "maxIterations": 3,
+      "successCriteria": "Hydration error message identified with specific component and line reference. Build output collected showing the exact mismatch text."
+    },
+    {
+      "name": "Diagnose Root Cause",
+      "tools": ["grep", "file_read"],
+      "maxIterations": 5,
+      "successCriteria": "Root cause identified: one of (1) browser API in render path, (2) date/random in render, (3) conditional rendering based on typeof window, (4) third-party component accessing browser globals, (5) data mismatch between server and client. Affected files and line numbers documented."
+    },
+    {
+      "name": "Apply Fix",
+      "tools": ["file_edit", "file_read"],
+      "maxIterations": 5,
+      "successCriteria": "Fix applied using appropriate strategy: (a) useEffect wrapper for client-only code, (b) next/dynamic with ssr:false for client-only components, (c) useIsClient hook for conditional rendering, (d) suppressHydrationWarning for intentional mismatches. No new TypeScript errors introduced."
+    },
+    {
+      "name": "Verify Fix",
+      "tools": ["shell_exec", "grep"],
+      "maxIterations": 3,
+      "successCriteria": "next build passes without errors. Dev server shows zero hydration warnings in console. Server-rendered HTML verified with curl to contain expected content. Existing tests pass."
+    }
+  ],
+  "exitCriteria": [
+    "next build completes successfully",
+    "Zero hydration mismatch warnings in browser console",
+    "Server-rendered HTML contains expected content",
+    "All existing tests pass",
+    "No new TypeScript errors"
+  ],
+  "fallback": "ssr-disable-component",
+  "estimatedTokens": 3000,
+  "confidence": 0.90
+}