agent-skill-kit 3.9.135

package/.agent/skills/react-pro/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: react-pro
+description: >-
+  React component architecture, hooks, state management, and performance patterns.
+  Use when creating components, fixing hooks, managing state, or working with .tsx/.jsx files.
+  NOT for Next.js routing (use nextjs-pro) or CSS styling (use design-system/tailwind-kit).
+category: frontend-specialist
+triggers: ["React", "component", "hooks", "state management", "Redux", "Zustand", "TypeScript", "TanStack Query", "MUI", "frontend"]
+coordinates_with: ["nextjs-pro", "typescript-expert", "design-system", "tailwind-kit", "problem-checker", "knowledge-compiler"]
+success_metrics: ["Component Render Efficiency", "Accessibility Score", "Core Web Vitals"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# React Architect — Component & State Architecture
+
+> 4 component types. 4 state levels. Composition over inheritance. Profile before memoizing.
+
+---
+
+## 5 Must-Ask Questions (Before Architecture Decision)
+
+| # | Question | Options |
+|---|----------|---------|
+| 1 | Target Framework? | React SPA / Next.js App Router / Vite / Vue |
+| 2 | Styling Approach? | Tailwind / CSS Modules / Styled Components / MUI |
+| 3 | State Complexity? | Local only / Shared subtree / Server state / Global |
+| 4 | Render Strategy? | CSR / SSR / SSG / Streaming |
+| 5 | Accessibility Needs? | Standard WCAG / Enhanced (screen reader, focus mgmt) |
+
+---
+
+## When to Use
+
+| Situation | Approach |
+|-----------|----------|
+| Component design | Check component type classification |
+| State management | Use complexity → solution routing |
+| Hook reuse | Check extraction criteria |
+| Performance issues | Use signal → action mapping |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| Component classification (4 types) | Next.js patterns (→ nextjs-pro) |
+| State management routing (4 levels) | TypeScript patterns (→ typescript-expert) |
+| Hook extraction criteria | UI design (→ design-system) |
+| Performance signal→action | Code implementation |
+
+**Expert decision skill:** Produces architecture decisions. Does not write code.
+
+---
+
+## Component Types (4 — Deterministic)
+
+| Type | Use For | State Model |
+|------|---------|-------------|
+| **Server** | Data fetching, static content | None |
+| **Client** | Interactivity, browser APIs | useState, effects |
+| **Presentational** | UI display | Props only |
+| **Container** | Logic/orchestration | Heavy state |
+
+**Design Rules:**
+- One responsibility per component (≤ 150 lines)
+- Props down, events up
+- Composition over inheritance
+
+---
+
+## State Management Routing (Deterministic)
+
+| Complexity | Solution |
+|------------|----------|
+| Simple (single component) | `useState`, `useReducer` |
+| Shared local (subtree) | `Context` |
+| Server state (API data) | React Query, SWR |
+| Complex global (app-wide) | Zustand, Redux Toolkit |
+
+## State Placement (4 Scopes)
+
+| Scope | Where |
+|-------|-------|
+| Single component | `useState` |
+| Parent-child | Lift state up |
+| Subtree | Context |
+| App-wide | Global store |
+
+---
+
+## Hook Patterns
+
+### When to Extract Custom Hook
+
+| Pattern | Extract When |
+|---------|-------------|
+| `useLocalStorage` | Same storage logic in 2+ components |
+| `useDebounce` | Multiple debounced values |
+| `useFetch` | Repeated fetch patterns |
+| `useForm` | Complex form state reused |
+
+### Hook Rules (Non-Negotiable)
+
+- Hooks at top level only (no conditionals)
+- Same order every render
+- Custom hooks prefix with `use`
+- Clean up effects on unmount
+
+---
+
+## Performance Signals (4 — Fixed)
+
+| Signal | Action |
+|--------|--------|
+| Slow renders | Profile first (DevTools) |
+| Large lists (> 100 items) | Virtualize |
+| Expensive calculation | `useMemo` |
+| Unstable callbacks causing re-renders | `useCallback` |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_UNKNOWN_COMPLEXITY` | Yes | State complexity not one of 4 |
+| `ERR_UNKNOWN_SCOPE` | Yes | State scope not one of 4 |
+
+**Zero internal retries.** Same context = same recommendation.
+
+---
+
+## Audit Logging (OpenTelemetry)
+
+| Event | Metadata Payload | Severity |
+|-------|------------------|----------|
+| `architecture_started` | `{"framework": "...", "component_count": 0}` | `INFO` |
+| `component_type_classified` | `{"type": "Server", "reason": "..."}` | `INFO` |
+| `state_management_selected` | `{"solution": "zustand", "complexity": "global"}` | `INFO` |
+| `performance_signal_detected` | `{"signal": "slow_renders", "action": "profile"}` | `WARN` |
+| `architecture_completed` | `{"components_designed": 5, "hooks_extracted": 2}` | `INFO` |
+
+All architecture outputs MUST emit `architecture_started` and `architecture_completed` events.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Use global state for local concerns | Start with useState, escalate as needed |
+| Prop drill > 3 levels | Use Context or state library |
+| Memoize everything | Profile first, memoize measured bottlenecks |
+| Mix data fetching with UI | Separate server/container from presentational |
+| Create God components (> 300 lines) | Split into focused components (≤ 150 lines) |
+
+---
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | React 19 Patterns | HIGH | `react19-` |
+| 2 | Composition | HIGH | `composition-` |
+| 3 | State Management | HIGH | `state-` |
+| 4 | Error Handling | HIGH | `error-` |
+| 5 | Component Patterns | HIGH | `component-` |
+| 6 | Data Fetching | HIGH | `data-` |
+| 7 | Performance | HIGH | `performance-` |
+| 8 | Custom Hooks | MEDIUM | `hooks-` |
+| 9 | Testing | MEDIUM | `testing-` |
+| 10 | File Organization | MEDIUM | `file-` |
+| 11 | MUI Styling | MEDIUM | `mui-` |
+| 12 | Engineering Spec | MEDIUM | `engineering-` |
+
+## Quick Reference
+
+### Architecture & Patterns (HIGH)
+
+- `react19-hooks` - useActionState & useOptimistic
+- `composition-compound` - Compound components with context
+- `state-management` - Zustand (global) & React Query (server)
+- `error-boundary` - Error boundary with fallback UI
+- `component-patterns` - Component type classification
+- `data-fetching` - TanStack Query patterns
+
+### Optimization (HIGH-MEDIUM)
+
+- `performance-optimization` - Waterfalls, bundle, re-renders, virtualization
+- `hooks-custom` - useDebounce, useLocalStorage, extraction criteria
+- `testing-patterns` - React Testing Library + userEvent
+
+### Structure (MEDIUM)
+
+- `file-organization` - Project file structure
+- `mui-styling` - MUI v7 styling patterns
+- `engineering-spec` - Full architecture specification
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/react19-hooks.md
+rules/state-management.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Code examples with correct patterns
+- Anti-patterns to avoid
+
+**Selective reading:** Read ONLY the category relevant to current task.
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: AGENTS.md\n
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `nextjs-pro` | Skill | Next.js patterns |
+| `typescript-expert` | Skill | TypeScript |
+| `design-system` | Skill | UI design |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/_sections.md

@@ -0,0 +1,40 @@
+# 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. General (general)
+
+**Impact:** LOW  
+**Description:** General patterns and best practices.
+
+## 2. Component Architecture (component)
+
+**Impact:** HIGH  
+**Description:** Proper component structure ensures maintainability and reusability.
+
+## 3. Data Management (data)
+
+**Impact:** HIGH  
+**Description:** Efficient data handling, fetching, and state management patterns.
+
+## 4. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 5. File (file)
+
+**Impact:** LOW  
+**Description:** File patterns and best practices.
+
+## 6. Mui (mui)
+
+**Impact:** LOW  
+**Description:** Mui patterns and best practices.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/_template.md

@@ -0,0 +1,32 @@
+---
+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)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/component-patterns.md

@@ -0,0 +1,145 @@
+---
+name: component-patterns
+description: React.FC with TypeScript — Suspense-first, useCallback rules, props patterns, named/default exports
+title: "React.FC with TypeScript, useCallback for handlers, default export."
+impact: HIGH
+impactDescription: "Important architectural or correctness impact"
+tags: component, patterns
+---
+
+# Component Patterns
+
+> React.FC with TypeScript, useCallback for handlers, default export.
+
+---
+
+## Standard Component Structure
+
+```typescript
+import React, { useState, useCallback } from 'react';
+import { Box, Paper, Typography, Button } from '@mui/material';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { featureApi } from '../api/featureApi';
+import type { FeatureData } from '~types/feature';
+
+interface MyComponentProps {
+  id: number;
+  title?: string;
+  onAction?: (id: number) => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ 
+  id, 
+  title = 'Default Title',
+  onAction 
+}) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const { data } = useSuspenseQuery({
+    queryKey: ['feature', id],
+    queryFn: () => featureApi.getById(id),
+  });
+
+  const handleToggle = useCallback(() => {
+    setIsOpen(prev => !prev);
+  }, []);
+
+  const handleAction = useCallback(() => {
+    onAction?.(id);
+  }, [id, onAction]);
+
+  return (
+    <Box sx={{ p: 2 }}>
+      <Paper sx={{ p: 3 }}>
+        <Typography variant="h6">{title}</Typography>
+        <Typography>{data.content}</Typography>
+        <Button onClick={handleAction}>Action</Button>
+      </Paper>
+    </Box>
+  );
+};
+
+export default MyComponent;
+```
+
+---
+
+## Key Patterns
+
+| Pattern | Rule |
+|---------|------|
+| Props Interface | Explicit, named `ComponentNameProps` |
+| Default Props | Destructure with defaults |
+| Event Handlers | `useCallback` if passed to children |
+| Named Export | `export const Component` |
+| Default Export | At bottom for lazy loading |
+
+---
+
+## useCallback Rules
+
+```typescript
+// ✅ USE - Handler passed to child component
+const handleClick = useCallback(() => {
+  doSomething();
+}, []);
+<ChildComponent onClick={handleClick} />
+
+// ✅ USE - Handler depends on props/state
+const handleSubmit = useCallback(() => {
+  onSubmit(formData);
+}, [onSubmit, formData]);
+
+// ❌ SKIP - Handler used inline only
+<Button onClick={() => setOpen(true)}>
+```
+
+---
+
+## Props Patterns
+
+```typescript
+// Required vs Optional
+interface Props {
+  id: number;           // Required
+  title?: string;       // Optional
+  onChange?: () => void; // Optional callback
+}
+
+// Children
+interface Props {
+  children: React.ReactNode;
+}
+
+// Render Props
+interface Props {
+  renderItem: (item: Item) => React.ReactNode;
+}
+```
+
+---
+
+## Exports
+
+```typescript
+// Named export (for direct imports)
+export const MyComponent: React.FC<Props> = () => { ... };
+
+// Default export (for lazy loading)
+export default MyComponent;
+```
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [data-fetching.md](data-fetching.md) | useSuspenseQuery for data layer |
+| [mui-styling.md](mui-styling.md) | MUI v7 sx prop patterns |
+| [file-organization.md](file-organization.md) | Where to place components |
+| [../SKILL.md](../SKILL.md) | Core rules and anti-patterns |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/composition-compound.md

@@ -0,0 +1,82 @@
+---
+title: "Compound Components Pattern"
+impact: HIGH
+impactDescription: "Compound components eliminate prop drilling and provide flexible APIs"
+tags: composition, compound, context, slots
+---
+
+# Compound Components Pattern
+
+> Context-based compound components for flexible, slot-based APIs.
+
+---
+
+## Implementation
+
+```tsx
+import { createContext, useContext, useState, type ReactNode } from 'react'
+
+// Context for internal state
+const TabsContext = createContext<{
+  active: string
+  setActive: (id: string) => void
+} | null>(null)
+
+function useTabs() {
+  const ctx = useContext(TabsContext)
+  if (!ctx) throw new Error('Tabs components must be used within <Tabs>')
+  return ctx
+}
+
+// Parent — provides context
+function Tabs({ defaultTab, children }: { defaultTab: string; children: ReactNode }) {
+  const [active, setActive] = useState(defaultTab)
+  return (
+    <TabsContext.Provider value={{ active, setActive }}>
+      <div className="tabs">{children}</div>
+    </TabsContext.Provider>
+  )
+}
+
+// Child — consumes context
+function TabList({ children }: { children: ReactNode }) {
+  return <div className="tab-list" role="tablist">{children}</div>
+}
+
+function Tab({ id, children }: { id: string; children: ReactNode }) {
+  const { active, setActive } = useTabs()
+  return (
+    <button role="tab" aria-selected={active === id} onClick={() => setActive(id)}>
+      {children}
+    </button>
+  )
+}
+
+function TabPanel({ id, children }: { id: string; children: ReactNode }) {
+  const { active } = useTabs()
+  if (active !== id) return null
+  return <div role="tabpanel">{children}</div>
+}
+
+// Attach sub-components
+Tabs.List = TabList
+Tabs.Tab = Tab
+Tabs.Panel = TabPanel
+```
+
+## Usage
+
+```tsx
+<Tabs defaultTab="overview">
+  <Tabs.List>
+    <Tabs.Tab id="overview">Overview</Tabs.Tab>
+    <Tabs.Tab id="settings">Settings</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel id="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel id="settings">Settings content</Tabs.Panel>
+</Tabs>
+```
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/react-pro/rules/data-fetching.md

@@ -0,0 +1,133 @@
+---
+name: data-fetching
+description: TanStack Query patterns — useSuspenseQuery, mutations, query keys, API service layer
+title: "Data Fetching with TanStack Query"
+impact: HIGH
+impactDescription: "Important architectural or correctness impact"
+tags: data, fetching
+---
+
+# Data Fetching with TanStack Query
+
+> Use `useSuspenseQuery` - data is guaranteed, no null checks.
+
+---
+
+## Primary Pattern: useSuspenseQuery
+
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query';
+
+// Inside component
+const { data } = useSuspenseQuery({
+  queryKey: ['posts', { status: 'published' }],
+  queryFn: () => postsApi.getPosts({ status: 'published' }),
+});
+
+// data is GUARANTEED defined (no null checks needed)
+```
+
+---
+
+## Query Key Patterns
+
+```typescript
+// Simple key
+queryKey: ['posts']
+
+// With parameters
+queryKey: ['posts', { status, page }]
+
+// Nested resource
+queryKey: ['posts', postId, 'comments']
+
+// User-specific
+queryKey: ['user', userId, 'settings']
+```
+
+---
+
+## Mutations
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+const queryClient = useQueryClient();
+
+const createPost = useMutation({
+  mutationFn: (data: CreatePostData) => postsApi.create(data),
+  onSuccess: () => {
+    // Invalidate and refetch
+    queryClient.invalidateQueries({ queryKey: ['posts'] });
+    showSnackbar('Post created!', 'success');
+  },
+  onError: (error) => {
+    showSnackbar(error.message, 'error');
+  },
+});
+
+// Usage
+createPost.mutate({ title: 'New Post', content: '...' });
+```
+
+---
+
+## API Service Layer
+
+```typescript
+// src/features/posts/api/postsApi.ts
+import { apiClient } from '@/lib/apiClient';
+import type { Post, CreatePostData } from '../types';
+
+export const postsApi = {
+  getAll: async (): Promise<Post[]> => {
+    const { data } = await apiClient.get('/posts');
+    return data;
+  },
+
+  getById: async (id: number): Promise<Post> => {
+    const { data } = await apiClient.get(`/posts/${id}`);
+    return data;
+  },
+
+  create: async (payload: CreatePostData): Promise<Post> => {
+    const { data } = await apiClient.post('/posts', payload);
+    return data;
+  },
+
+  update: async (id: number, payload: Partial<Post>): Promise<Post> => {
+    const { data } = await apiClient.patch(`/posts/${id}`, payload);
+    return data;
+  },
+
+  delete: async (id: number): Promise<void> => {
+    await apiClient.delete(`/posts/${id}`);
+  },
+};
+```
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| `const { data, isLoading }` + early return | `useSuspenseQuery` + Suspense |
+| Inline fetch in component | API service layer |
+| `useEffect` + `fetch` | `useSuspenseQuery` |
+| Manual loading states | Suspense boundaries |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [component-patterns.md](component-patterns.md) | Component structure using useSuspenseQuery |
+| [performance.md](performance.md) | Lazy loading and memoization |
+| [file-organization.md](file-organization.md) | Where to place api/ services |
+| [../SKILL.md](../SKILL.md) | No early returns rule |
+
+---
+
+⚡ PikaKit v3.9.134