@codihaus/claude-skills 1.6.16 → 1.6.17

package/knowledge/stacks/_index.md

@@ -14,9 +14,10 @@ When skills detect a tech stack (via `stack.md`), they load the relevant stack f
 
 | Stack | Folder | Type | Status |
 |-------|--------|------|--------|
-| Directus | `directus/` | Backend BaaS | Ready |
-| Nuxt.js | `nuxt/` | Vue + SSR Framework | Ready |
+| React | `react/` | UI Library | Ready |
 | Next.js | `nextjs/` | React + SSR Framework | Ready |
+| Nuxt.js | `nuxt/` | Vue + SSR Framework | Ready |
+| Directus | `directus/` | Backend BaaS | Ready |
 | Prisma | `prisma/` | ORM | Planned |
 | Supabase | `supabase/` | Backend BaaS | Planned |
 

package/knowledge/stacks/react/_index.md

@@ -0,0 +1,579 @@
+# React
+
+> JavaScript library for building user interfaces with components
+
+## Overview
+
+**What it is:**
+- Component-based UI library (not a full framework)
+- Virtual DOM for efficient updates
+- Declarative and composable
+- Unidirectional data flow
+- Hooks for state and side effects
+- React 18+ with Concurrent features
+
+**When to use:**
+- Building interactive user interfaces
+- Single-page applications (SPAs)
+- Component-based architecture
+- Projects needing UI flexibility
+- Teams familiar with JavaScript/JSX
+
+**Key concepts:**
+- **Components** = Building blocks (functions returning JSX)
+- **Props** = Data passed down from parent
+- **State** = Component-local data
+- **Hooks** = Functions for state/effects (useState, useEffect, etc.)
+- **JSX** = JavaScript XML syntax
+- **Virtual DOM** = In-memory representation for efficient updates
+- **Reconciliation** = Diffing algorithm for minimal DOM updates
+
+## Best Practices
+
+### Project Structure
+
+```
+react-app/
+├── src/
+│   ├── components/           # Reusable components
+│   │   ├── ui/               # UI primitives (Button, Input)
+│   │   ├── forms/            # Form components
+│   │   └── common/           # Shared components (Header, Footer)
+│   ├── features/             # Feature-based modules
+│   │   └── auth/
+│   │       ├── components/   # Feature-specific components
+│   │       ├── hooks/        # Feature-specific hooks
+│   │       └── utils/        # Feature utilities
+│   ├── hooks/                # Global custom hooks
+│   ├── context/              # Context providers
+│   ├── utils/                # Helper functions
+│   ├── types/                # TypeScript types
+│   ├── constants/            # Constants and configs
+│   └── App.tsx               # Root component
+└── public/                   # Static assets
+```
+
+### Component Patterns
+
+**Functional Components (Modern React):**
+```jsx
+DO:
+✓ Use functional components with hooks
+✓ Keep components small and focused
+✓ Extract reusable logic into custom hooks
+✓ Use descriptive component names
+✓ Separate logic from presentation
+
+DON'T:
+✗ Use class components (legacy pattern)
+✗ Create mega-components (split them)
+✗ Inline complex logic in JSX
+✗ Forget to memoize expensive components
+✗ Nest component definitions
+```
+
+**Component Composition:**
+```jsx
+DO:
+✓ Compose small components into larger ones
+✓ Use children prop for flexible composition
+✓ Pass components as props when needed
+✓ Use render props for advanced patterns
+✓ Implement compound components for related UI
+
+DON'T:
+✗ Prop drill through many levels (use Context)
+✗ Over-abstract too early
+✗ Create deep component hierarchies
+✗ Duplicate logic across components
+```
+
+### Hooks Best Practices
+
+**useState:**
+```jsx
+DO:
+✓ Use separate state variables for unrelated data
+✓ Update state immutably (spread operator, map, filter)
+✓ Use functional updates when referencing previous state
+✓ Initialize state correctly (lazy initialization for expensive ops)
+
+DON'T:
+✗ Mutate state directly (array.push, object.property = value)
+✗ Store derived values in state (calculate from existing state)
+✗ Use one giant state object
+✗ Forget that setState is asynchronous
+```
+
+**useEffect:**
+```jsx
+DO:
+✓ Include all dependencies in dependency array
+✓ Return cleanup function when needed
+✓ Keep effects focused (one concern per effect)
+✓ Use empty array [] for mount-only effects
+✓ Use ESLint exhaustive-deps rule
+
+DON'T:
+✗ Omit dependencies (stale closures)
+✗ Use effects for derived state (use useMemo)
+✗ Create infinite loops (missing deps, setState without condition)
+✗ Forget to cleanup (event listeners, subscriptions, timers)
+✗ Use effects for event handlers (use onClick, etc.)
+```
+
+**useCallback & useMemo:**
+```jsx
+DO:
+✓ Memoize callbacks passed to child components
+✓ Memoize expensive computations
+✓ Include all dependencies
+✓ Use for performance optimization, not default
+
+DON'T:
+✗ Overuse (premature optimization)
+✗ Memoize everything (adds overhead)
+✗ Forget dependencies
+✗ Use for cheap operations
+```
+
+**Custom Hooks:**
+```jsx
+DO:
+✓ Start name with "use" (useAuth, useForm, useFetch)
+✓ Extract reusable logic
+✓ Return arrays [value, setter] or objects {value, actions}
+✓ Keep hooks composable
+✓ Handle cleanup properly
+
+DON'T:
+✗ Call hooks conditionally (breaks Rules of Hooks)
+✗ Call hooks in loops or nested functions
+✗ Make hooks too specific (hard to reuse)
+✗ Return too many values (destructuring nightmare)
+```
+
+### State Management
+
+**Local State (useState):**
+```jsx
+When: Component-specific, not shared
+Example: Form inputs, toggles, counters
+```
+
+**Lifted State:**
+```jsx
+When: Shared between siblings, shallow tree
+Example: Parent managing child states
+```
+
+**Context API:**
+```jsx
+When: Global or feature-level state
+Example: Auth, theme, language
+DO:
+✓ Split contexts by concern (AuthContext, ThemeContext)
+✓ Memoize context values
+✓ Use separate contexts for data and actions
+✓ Provide at appropriate level (not always root)
+
+DON'T:
+✗ Use for all state (performance issues)
+✗ Put frequently changing values in context
+✗ Create one giant context
+```
+
+**External Libraries:**
+```jsx
+When: Complex state logic, advanced needs
+Options:
+- Redux Toolkit: Large apps, complex state, DevTools
+- Zustand: Simple, minimal boilerplate
+- Jotai/Recoil: Atomic state management
+- TanStack Query: Server state (API calls, caching)
+```
+
+### Performance Optimization
+
+**React.memo:**
+```jsx
+DO:
+✓ Memoize expensive components
+✓ Use when props rarely change
+✓ Provide custom comparison function if needed
+
+DON'T:
+✗ Wrap every component (overhead)
+✗ Use without profiling first
+✗ Forget to memoize props (objects, arrays, functions)
+```
+
+**Code Splitting:**
+```jsx
+DO:
+✓ Use React.lazy() for route-based splitting
+✓ Use dynamic import() for large components
+✓ Show Suspense fallback
+✓ Split by routes first, then by features
+
+DON'T:
+✗ Split too aggressively (too many chunks)
+✗ Split small components
+✗ Forget error boundaries
+```
+
+**Lists & Keys:**
+```jsx
+DO:
+✓ Use stable, unique keys (IDs from data)
+✓ Keep key at the mapped element
+✓ Use index only for static lists
+
+DON'T:
+✗ Use array index for dynamic lists (bugs on reorder)
+✗ Use random keys (breaks reconciliation)
+✗ Omit keys (warning + performance issues)
+```
+
+### Forms & Controlled Components
+
+```jsx
+DO:
+✓ Use controlled components (value + onChange)
+✓ Validate on blur or submit (not every keystroke)
+✓ Use form libraries for complex forms (React Hook Form, Formik)
+✓ Debounce expensive validations
+✓ Show clear error messages
+
+DON'T:
+✗ Use uncontrolled components unless necessary
+✗ Validate on every keystroke (performance)
+✗ Forget to prevent default on form submit
+✗ Store all form state in parent (use form libraries)
+```
+
+### Error Handling
+
+```jsx
+DO:
+✓ Use Error Boundaries for component errors
+✓ Implement fallback UI
+✓ Log errors to monitoring service
+✓ Handle async errors in try/catch
+✓ Show user-friendly error messages
+
+DON'T:
+✗ Catch all errors silently
+✗ Show technical errors to users
+✗ Forget to handle promise rejections
+✗ Rely on Error Boundaries for async (they don't catch those)
+```
+
+## Anti-Patterns
+
+### Common Mistakes
+
+```jsx
+❌ Inline object/array in JSX (causes re-renders)
+<Component config={{}} items={[]} />
+
+✅ Define outside or useMemo
+const config = useMemo(() => ({}), [])
+
+❌ Derived state
+const [fullName, setFullName] = useState('')
+// Calculated from firstName + lastName
+
+✅ Compute during render
+const fullName = `${firstName} ${lastName}`
+
+❌ Prop drilling
+<A> → <B prop={x}> → <C prop={x}> → <D prop={x}> → <E prop={x}>
+
+✅ Context or composition
+<Context.Provider value={x}>
+  <A><B><C><D><E /></D></C></B></A>
+</Context.Provider>
+
+❌ Mutating state
+items.push(newItem)
+setItems(items)
+
+✅ Immutable updates
+setItems([...items, newItem])
+
+❌ useEffect for event handlers
+useEffect(() => {
+  button.addEventListener('click', handler)
+}, [])
+
+✅ Direct event handler
+<button onClick={handler}>
+
+❌ Forgetting dependencies
+useEffect(() => {
+  fetchData(userId)
+}, []) // Missing userId
+
+✅ Include all deps
+useEffect(() => {
+  fetchData(userId)
+}, [userId])
+```
+
+## For /dev-specs
+
+When writing specs for React projects:
+
+**Component Specs:**
+- Define component props and types
+- Specify state management approach (local, Context, external)
+- Identify if memoization needed
+- Note if code splitting required
+- Specify form handling approach
+
+**State Management:**
+- Clarify scope (local, feature, global)
+- If Context: specify provider location
+- If external library: specify which one
+
+**Performance Requirements:**
+- List optimization needs (memo, lazy, useMemo)
+- Specify bundle size constraints
+
+**Patterns to Use:**
+- Custom hooks for reusable logic
+- Compound components for related UI
+- Render props for advanced patterns
+
+## For /dev-coding
+
+When implementing React features:
+
+### 1. Component Creation
+
+**Start with:**
+- Read tech-context.md for project's React patterns
+- Check if TypeScript is used
+- Identify state management approach
+- Check for component library (MUI, Chakra, Ant Design, shadcn/ui)
+
+**Structure:**
+```jsx
+// Component.tsx
+import { useState, useEffect } from 'react'
+
+interface ComponentProps {
+  // Props with TypeScript
+}
+
+export function Component({ prop1, prop2 }: ComponentProps) {
+  // 1. Hooks (useState, useEffect, useContext, custom hooks)
+  const [state, setState] = useState(initial)
+
+  // 2. Derived values (useMemo)
+  const derived = useMemo(() => compute(state), [state])
+
+  // 3. Callbacks (useCallback)
+  const handleClick = useCallback(() => {
+    // Handler logic
+  }, [dependencies])
+
+  // 4. Effects (useEffect)
+  useEffect(() => {
+    // Effect logic
+    return () => cleanup()
+  }, [dependencies])
+
+  // 5. Early returns (loading, error)
+  if (loading) return <Spinner />
+  if (error) return <Error />
+
+  // 6. Render
+  return (
+    <div>
+      {/* JSX */}
+    </div>
+  )
+}
+```
+
+### 2. State Management
+
+**Choose based on scope:**
+- **Local UI state** → useState
+- **Shared between siblings** → Lift state
+- **Feature-level** → Context or custom hook
+- **Global** → Context or external library
+- **Server data** → TanStack Query
+
+### 3. Performance
+
+**Profile first, then optimize:**
+- Use React DevTools Profiler
+- Check for unnecessary re-renders
+- Apply React.memo selectively
+- Memoize callbacks and expensive computations
+- Lazy load heavy components
+
+### 4. Hooks Order
+
+**Always call in same order:**
+1. useState
+2. useContext
+3. Custom hooks
+4. useMemo
+5. useCallback
+6. useEffect
+7. useLayoutEffect (rare)
+
+### 5. Common Patterns
+
+**Fetch data:**
+```jsx
+const [data, setData] = useState(null)
+const [loading, setLoading] = useState(true)
+const [error, setError] = useState(null)
+
+useEffect(() => {
+  let cancelled = false
+
+  async function fetchData() {
+    try {
+      const result = await api.get(url)
+      if (!cancelled) setData(result)
+    } catch (err) {
+      if (!cancelled) setError(err)
+    } finally {
+      if (!cancelled) setLoading(false)
+    }
+  }
+
+  fetchData()
+  return () => { cancelled = true }
+}, [url])
+```
+
+**Custom hook:**
+```jsx
+function useAuth() {
+  const [user, setUser] = useState(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    const unsubscribe = auth.onAuthStateChanged(setUser)
+    setLoading(false)
+    return unsubscribe
+  }, [])
+
+  return { user, loading }
+}
+```
+
+## For /dev-review
+
+When reviewing React code:
+
+**Component Quality:**
+- [ ] Components are small and focused (< 300 lines)
+- [ ] Props are typed (TypeScript interfaces)
+- [ ] No prop drilling (max 2-3 levels)
+- [ ] Meaningful component and prop names
+
+**Hooks Usage:**
+- [ ] Hooks follow Rules of Hooks (top level, order)
+- [ ] All dependencies included in arrays
+- [ ] No infinite loops in useEffect
+- [ ] Cleanup functions where needed
+- [ ] Custom hooks for reusable logic
+
+**State Management:**
+- [ ] No derived state (calculate from existing)
+- [ ] State updates are immutable
+- [ ] Appropriate scope (local vs lifted vs global)
+- [ ] Context not overused (performance)
+
+**Performance:**
+- [ ] No inline object/array creation in renders
+- [ ] Expensive operations memoized
+- [ ] Large components lazy loaded
+- [ ] Lists have stable keys
+
+**JSX Quality:**
+- [ ] No complex logic in JSX (extract to functions)
+- [ ] Conditional rendering is clear
+- [ ] Event handlers are memoized if needed
+- [ ] Accessibility attributes present (aria-*, alt, etc.)
+
+**Error Handling:**
+- [ ] Error boundaries implemented
+- [ ] Async errors caught (try/catch)
+- [ ] User-friendly error messages
+- [ ] Loading states shown
+
+**Testing:**
+- [ ] Components are testable (no tight coupling)
+- [ ] Logic extracted to pure functions
+- [ ] Hooks are testable (custom hooks especially)
+
+## Integration with Other Stacks
+
+**React + Next.js:**
+- Follow Next.js App Router conventions
+- Use Server Components by default
+- Add "use client" only when needed
+- Leverage Next.js data fetching
+
+**React + Vite:**
+- Fast dev server
+- Modern build tool
+- Use Vite plugins ecosystem
+
+**React + TypeScript:**
+- Define prop types with interfaces
+- Use React.FC sparingly (prefer typed props)
+- Leverage type inference
+- Use generics for reusable components
+
+**React + Tailwind CSS:**
+- Use utility-first classes
+- Extract components for repeated patterns
+- Use @apply for common combinations
+- Leverage Tailwind's JIT mode
+
+**React + State Libraries:**
+- Redux Toolkit: Use createSlice, RTK Query
+- Zustand: Simple store creation
+- TanStack Query: Server state management, caching
+
+## Common Gotchas
+
+1. **Stale Closures**: Missing dependencies in useEffect/useCallback
+2. **Infinite Loops**: setState in useEffect without deps or condition
+3. **Key Prop**: Using index for dynamic lists
+4. **Object/Array Identity**: Creating new objects in render
+5. **Async setState**: Setting state is asynchronous, not immediate
+6. **Rules of Hooks**: Must call unconditionally, same order every render
+7. **Event Handler Scope**: this binding (use arrow functions)
+8. **useEffect Cleanup**: Not cleaning up subscriptions/listeners
+
+## React 18+ Features
+
+**Concurrent Features:**
+- Automatic batching (multiple setStates batch automatically)
+- Transitions (mark updates as non-urgent with startTransition)
+- Suspense (data fetching, lazy loading)
+- Streaming SSR (progressive HTML rendering)
+
+**New Hooks:**
+- useId (unique IDs for accessibility)
+- useTransition (mark non-urgent updates)
+- useDeferredValue (defer updates for performance)
+- useSyncExternalStore (external store integration)
+
+## Resources
+
+- [React Docs](https://react.dev) - Official documentation
+- [React DevTools](https://react.dev/learn/react-developer-tools) - Browser extension
+- [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks) - Hook constraints
+- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app) - TS patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.16",
+  "version": "1.6.17",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {

package/skills/_registry.md

@@ -180,9 +180,10 @@ Technical knowledge - HOW to build with specific tools:
 
 | Stack | Folder | Type |
 |-------|--------|------|
-| Directus | `stacks/directus/` | Backend BaaS |
-| Nuxt.js | `stacks/nuxt/` | Vue + SSR Framework |
+| React | `stacks/react/` | UI Library |
 | Next.js | `stacks/nextjs/` | React + SSR Framework |
+| Nuxt.js | `stacks/nuxt/` | Vue + SSR Framework |
+| Directus | `stacks/directus/` | Backend BaaS |
 
 **Folder structure:**
 ```

package/skills/dev-coding/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: dev-coding
 description: Implement features as a Principal Engineering Developer
-version: 2.1.1
+version: 2.1.2
 ---
 
 # /dev-coding - Implementation Skill
@@ -67,6 +67,7 @@ You have three layers of knowledge to apply:
 3. **Focus on "For /dev-coding" section** → Note best practices
 
 **Stack file mapping:**
+- "React" → `knowledge/stacks/react/_index.md`
 - "Next.js" → `knowledge/stacks/nextjs/_index.md`
 - "Nuxt" → `knowledge/stacks/nuxt/_index.md`
 - "Directus" → `knowledge/stacks/directus/_index.md`
@@ -176,6 +177,7 @@ Implementation
    ```
 
 2. **Load stack knowledge files:**
+   - If "React" detected → Read `knowledge/stacks/react/_index.md`
    - If "Next.js" detected → Read `knowledge/stacks/nextjs/_index.md`
    - If "Nuxt" detected → Read `knowledge/stacks/nuxt/_index.md`
    - If "Directus" detected → Read `knowledge/stacks/directus/_index.md`
@@ -334,6 +336,7 @@ Implementation successful when:
 - `references/frontend-principles.md` - General UI, component, state principles
 
 **Layer 2 - Framework:**
+- `knowledge/stacks/react/_index.md` - React patterns (Hooks, Context, performance)
 - `knowledge/stacks/nextjs/_index.md` - Next.js patterns (Server Actions, App Router, RSC)
 - `knowledge/stacks/nuxt/_index.md` - Nuxt patterns (composables, Nuxt UI, SSR)
 - `knowledge/stacks/directus/_index.md` - Directus patterns (collections, flows, extensions)