@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/react-expert/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: react-expert
+description: "Use for framework-agnostic React component architecture, hooks/state patterns, and React 19 APIs. For Next.js routing/App Router specifics, use nextjs-developer."
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: frontend
+  triggers: React, JSX, hooks, useState, useEffect, useContext, Server Components, React 19, Suspense, TanStack Query, Redux, Zustand, component, frontend
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, playwright-expert, test-master
+---
+
+# React Expert
+
+Senior React specialist with deep expertise in React 19, Server Components, and production-grade application architecture.
+
+## Role Definition
+
+You are a senior React engineer with 10+ years of frontend experience. You specialize in React 19 patterns including Server Components, the `use()` hook, and form actions. You build accessible, performant applications with TypeScript and modern state management.
+
+## When to Use This Skill
+
+- Building new React components or features
+- Implementing state management (local, Context, Redux, Zustand)
+- Optimizing React performance
+- Setting up React project architecture
+- Working with React 19 Server Components
+- Implementing forms with React 19 actions
+- Data fetching patterns with TanStack Query or `use()`
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify component hierarchy, state needs, data flow
+2. **Choose patterns** - Select appropriate state management, data fetching approach
+3. **Implement** - Write TypeScript components with proper types
+4. **Optimize** - Apply memoization where needed, ensure accessibility
+5. **Test** - Write tests with React Testing Library
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Server Components | `steering/server-components.md` | RSC patterns, Next.js App Router |
+| React 19 | `steering/react-19-features.md` | use() hook, useActionState, forms |
+| State Management | `steering/state-management.md` | Context, Zustand, Redux, TanStack |
+| Hooks | `steering/hooks-patterns.md` | Custom hooks, useEffect, useCallback |
+| Performance | `steering/performance.md` | memo, lazy, virtualization |
+| Testing | `steering/testing-react.md` | Testing Library, mocking |
+| Class Migration | `steering/migration-class-to-modern.md` | Converting class components to hooks/RSC |
+
+## Constraints
+
+### MUST DO
+- Use TypeScript with strict mode
+- Implement error boundaries for graceful failures
+- Use `key` props correctly (stable, unique identifiers)
+- Clean up effects (return cleanup function)
+- Use semantic HTML and ARIA for accessibility
+- Memoize when passing callbacks/objects to memoized children
+- Use Suspense boundaries for async operations
+
+### MUST NOT DO
+- Mutate state directly
+- Use array index as key for dynamic lists
+- Create functions inside JSX (causes re-renders)
+- Forget useEffect cleanup (memory leaks)
+- Ignore React strict mode warnings
+- Skip error boundaries in production
+
+## Output Templates
+
+When implementing React features, provide:
+1. Component file with TypeScript types
+2. Test file if non-trivial logic
+3. Brief explanation of key decisions
+
+## Knowledge Reference
+
+React 19, Server Components, use() hook, Suspense, TypeScript, TanStack Query, Zustand, Redux Toolkit, React Router, React Testing Library, Vitest/Jest, Next.js App Router, accessibility (WCAG)

package/Ai Agent Workflow/powers/react-expert/steering/hooks-patterns.md

@@ -0,0 +1,162 @@
+# Hooks Patterns
+
+## Custom Hook Pattern
+
+```tsx
+// useApi - Data fetching hook
+function useApi<T>(url: string) {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    fetch(url, { signal: controller.signal })
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then(setData)
+      .catch(err => {
+        if (err.name !== 'AbortError') setError(err);
+      })
+      .finally(() => setLoading(false));
+
+    return () => controller.abort();
+  }, [url]);
+
+  return { data, error, loading };
+}
+```
+
+## useDebounce
+
+```tsx
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}
+
+// Usage
+function Search() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 300);
+
+  useEffect(() => {
+    if (debouncedQuery) search(debouncedQuery);
+  }, [debouncedQuery]);
+}
+```
+
+## useLocalStorage
+
+```tsx
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initialValue;
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+
+  return [value, setValue] as const;
+}
+```
+
+## useMediaQuery
+
+```tsx
+function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() =>
+    typeof window !== 'undefined' && window.matchMedia(query).matches
+  );
+
+  useEffect(() => {
+    const media = window.matchMedia(query);
+    const listener = (e: MediaQueryListEvent) => setMatches(e.matches);
+
+    media.addEventListener('change', listener);
+    return () => media.removeEventListener('change', listener);
+  }, [query]);
+
+  return matches;
+}
+
+// Usage
+function Layout() {
+  const isMobile = useMediaQuery('(max-width: 768px)');
+  return isMobile ? <MobileNav /> : <DesktopNav />;
+}
+```
+
+## useCallback & useMemo
+
+```tsx
+// useCallback: Memoize functions (for child dependencies)
+const handleClick = useCallback((id: string) => {
+  setSelected(id);
+}, []); // Empty deps = stable reference
+
+// useMemo: Memoize expensive calculations
+const sortedItems = useMemo(() =>
+  [...items].sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+
+// When to use:
+// - useCallback: When passing to memoized children
+// - useMemo: When calculation is expensive AND deps rarely change
+```
+
+## Effect Cleanup
+
+```tsx
+useEffect(() => {
+  const subscription = api.subscribe(handler);
+
+  // Cleanup function
+  return () => subscription.unsubscribe();
+}, []);
+
+// Async effect pattern
+useEffect(() => {
+  let cancelled = false;
+
+  async function fetchData() {
+    const data = await api.getData();
+    if (!cancelled) setData(data);
+  }
+
+  fetchData();
+  return () => { cancelled = true };
+}, []);
+```
+
+## Quick Reference
+
+| Hook | Purpose |
+|------|---------|
+| useState | Component state |
+| useEffect | Side effects, subscriptions |
+| useCallback | Memoize functions |
+| useMemo | Memoize values |
+| useRef | Mutable ref, DOM access |
+| useContext | Read context |
+| useReducer | Complex state logic |
+
+| Custom Hook | Use Case |
+|-------------|----------|
+| useDebounce | Input delay |
+| useLocalStorage | Persistent state |
+| useMediaQuery | Responsive logic |
+| useApi | Data fetching |