@cubis/foundry 0.3.32 → 0.3.33

package/workflows/powers/react-best-practices/POWER.md

@@ -1,139 +1,56 @@
 ````markdown
 ---
 inclusion: manual
-name: react-best-practices
-description: "Performance-focused React/Next.js review checklist from Vercel. Use for optimization/refactor passes, not as the primary implementation skill."
+name: "react-best-practices"
+description: "Performance-focused React/Next.js review checklist. Use for audits and optimization passes, not as primary implementation skill."
 license: MIT
 metadata:
   author: vercel
-  version: "1.0.0"
+  version: "2.0.0"
+  domain: "frontend"
+  role: "review-checklist"
 ---
 
-# Vercel React Best Practices
+# React Best Practices
 
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+## Purpose
 
-## When to Apply
+Use this skill to run structured optimization reviews on React/Next.js code. Pair it with implementation skills (`react-expert`, `nextjs-developer`) when code changes are required.
 
-Reference these guidelines when:
-- Writing new React components or Next.js pages
-- Implementing data fetching (client or server-side)
-- Reviewing code for performance issues
-- Refactoring existing React/Next.js code
-- Optimizing bundle size or load times
+## Review order
 
-## Rule Categories by Priority
+1. Async waterfalls and request parallelization.
+2. Bundle and hydration footprint.
+3. Server rendering and serialization overhead.
+4. Client data-fetching and rerender churn.
+5. JS/runtime hot paths.
 
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
+## High-impact checks
 
-## Quick Reference
+- Parallelize independent async work.
+- Eliminate unnecessary client components.
+- Remove heavy modules from critical path.
+- Avoid unstable props that trigger deep rerenders.
+- Keep server-to-client payloads minimal.
 
-### 1. Eliminating Waterfalls (CRITICAL)
+## Output format
 
-- `async-defer-await` - Move await into branches where actually used
-- `async-parallel` - Use Promise.all() for independent operations
-- `async-dependencies` - Use better-all for partial dependencies
-- `async-api-routes` - Start promises early, await late in API routes
-- `async-suspense-boundaries` - Use Suspense to stream content
+Return prioritized findings with:
 
-### 2. Bundle Size Optimization (CRITICAL)
+1. Issue and impact.
+2. Minimal safe change.
+3. Verification method (profile metric or test).
 
-- `bundle-barrel-imports` - Import directly, avoid barrel files
-- `bundle-dynamic-imports` - Use next/dynamic for heavy components
-- `bundle-defer-third-party` - Load analytics/logging after hydration
-- `bundle-conditional` - Load modules only when feature is activated
-- `bundle-preload` - Preload on hover/focus for perceived speed
+## Rule catalog
 
-### 3. Server-Side Performance (HIGH)
+Detailed rules are under `rules/` and grouped by prefix:
 
-- `server-auth-actions` - Authenticate server actions like API routes
-- `server-cache-react` - Use React.cache() for per-request deduplication
-- `server-cache-lru` - Use LRU cache for cross-request caching
-- `server-dedup-props` - Avoid duplicate serialization in RSC props
-- `server-serialization` - Minimize data passed to client components
-- `server-parallel-fetching` - Restructure components to parallelize fetches
-- `server-after-nonblocking` - Use after() for non-blocking operations
-
-### 4. Client-Side Data Fetching (MEDIUM-HIGH)
-
-- `client-swr-dedup` - Use SWR for automatic request deduplication
-- `client-event-listeners` - Deduplicate global event listeners
-- `client-passive-event-listeners` - Use passive listeners for scroll
-- `client-localstorage-schema` - Version and minimize localStorage data
-
-### 5. Re-render Optimization (MEDIUM)
-
-- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
-- `rerender-memo` - Extract expensive work into memoized components
-- `rerender-memo-with-default-value` - Hoist default non-primitive props
-- `rerender-dependencies` - Use primitive dependencies in effects
-- `rerender-derived-state` - Subscribe to derived booleans, not raw values
-- `rerender-derived-state-no-effect` - Derive state during render, not effects
-- `rerender-functional-setstate` - Use functional setState for stable callbacks
-- `rerender-lazy-state-init` - Pass function to useState for expensive values
-- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
-- `rerender-move-effect-to-event` - Put interaction logic in event handlers
-- `rerender-transitions` - Use startTransition for non-urgent updates
-- `rerender-use-ref-transient-values` - Use refs for transient frequent values
-
-### 6. Rendering Performance (MEDIUM)
-
-- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
-- `rendering-content-visibility` - Use content-visibility for long lists
-- `rendering-hoist-jsx` - Extract static JSX outside components
-- `rendering-svg-precision` - Reduce SVG coordinate precision
-- `rendering-hydration-no-flicker` - Use inline script for client-only data
-- `rendering-hydration-suppress-warning` - Suppress expected mismatches
-- `rendering-activity` - Use Activity component for show/hide
-- `rendering-conditional-render` - Use ternary, not && for conditionals
-- `rendering-usetransition-loading` - Prefer useTransition for loading state
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-- `js-batch-dom-css` - Group CSS changes via classes or cssText
-- `js-index-maps` - Build Map for repeated lookups
-- `js-cache-property-access` - Cache object properties in loops
-- `js-cache-function-results` - Cache function results in module-level Map
-- `js-cache-storage` - Cache localStorage/sessionStorage reads
-- `js-combine-iterations` - Combine multiple filter/map into one loop
-- `js-length-check-first` - Check array length before expensive comparison
-- `js-early-exit` - Return early from functions
-- `js-hoist-regexp` - Hoist RegExp creation outside loops
-- `js-min-max-loop` - Use loop for min/max instead of sort
-- `js-set-map-lookups` - Use Set/Map for O(1) lookups
-- `js-tosorted-immutable` - Use toSorted() for immutability
-
-### 8. Advanced Patterns (LOW)
-
-- `advanced-event-handler-refs` - Store event handlers in refs
-- `advanced-init-once` - Initialize app once per app load
-- `advanced-use-latest` - useLatest for stable callback refs
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/async-parallel.md
-rules/bundle-barrel-imports.md
-```
-
-Each rule file contains:
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`
+- `async-*`
+- `bundle-*`
+- `server-*`
+- `client-*`
+- `rerender-*`
+- `rendering-*`
+- `js-*`
+- `advanced-*`
 ````

package/workflows/powers/react-best-practices/SKILL.md

@@ -1,136 +1,53 @@
 ---
-name: react-best-practices
-description: "Performance-focused React/Next.js review checklist from Vercel. Use for optimization/refactor passes, not as the primary implementation skill."
+name: "react-best-practices"
+description: "Performance-focused React/Next.js review checklist. Use for audits and optimization passes, not as primary implementation skill."
 license: MIT
 metadata:
   author: vercel
-  version: "1.0.0"
+  version: "2.0.0"
+  domain: "frontend"
+  role: "review-checklist"
 ---
 
-# Vercel React Best Practices
+# React Best Practices
 
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+## Purpose
 
-## When to Apply
+Use this skill to run structured optimization reviews on React/Next.js code. Pair it with implementation skills (`react-expert`, `nextjs-developer`) when code changes are required.
 
-Reference these guidelines when:
-- Writing new React components or Next.js pages
-- Implementing data fetching (client or server-side)
-- Reviewing code for performance issues
-- Refactoring existing React/Next.js code
-- Optimizing bundle size or load times
+## Review order
 
-## Rule Categories by Priority
+1. Async waterfalls and request parallelization.
+2. Bundle and hydration footprint.
+3. Server rendering and serialization overhead.
+4. Client data-fetching and rerender churn.
+5. JS/runtime hot paths.
 
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
+## High-impact checks
 
-## Quick Reference
+- Parallelize independent async work.
+- Eliminate unnecessary client components.
+- Remove heavy modules from critical path.
+- Avoid unstable props that trigger deep rerenders.
+- Keep server-to-client payloads minimal.
 
-### 1. Eliminating Waterfalls (CRITICAL)
+## Output format
 
-- `async-defer-await` - Move await into branches where actually used
-- `async-parallel` - Use Promise.all() for independent operations
-- `async-dependencies` - Use better-all for partial dependencies
-- `async-api-routes` - Start promises early, await late in API routes
-- `async-suspense-boundaries` - Use Suspense to stream content
+Return prioritized findings with:
 
-### 2. Bundle Size Optimization (CRITICAL)
+1. Issue and impact.
+2. Minimal safe change.
+3. Verification method (profile metric or test).
 
-- `bundle-barrel-imports` - Import directly, avoid barrel files
-- `bundle-dynamic-imports` - Use next/dynamic for heavy components
-- `bundle-defer-third-party` - Load analytics/logging after hydration
-- `bundle-conditional` - Load modules only when feature is activated
-- `bundle-preload` - Preload on hover/focus for perceived speed
+## Rule catalog
 
-### 3. Server-Side Performance (HIGH)
+Detailed rules are under `rules/` and grouped by prefix:
 
-- `server-auth-actions` - Authenticate server actions like API routes
-- `server-cache-react` - Use React.cache() for per-request deduplication
-- `server-cache-lru` - Use LRU cache for cross-request caching
-- `server-dedup-props` - Avoid duplicate serialization in RSC props
-- `server-serialization` - Minimize data passed to client components
-- `server-parallel-fetching` - Restructure components to parallelize fetches
-- `server-after-nonblocking` - Use after() for non-blocking operations
-
-### 4. Client-Side Data Fetching (MEDIUM-HIGH)
-
-- `client-swr-dedup` - Use SWR for automatic request deduplication
-- `client-event-listeners` - Deduplicate global event listeners
-- `client-passive-event-listeners` - Use passive listeners for scroll
-- `client-localstorage-schema` - Version and minimize localStorage data
-
-### 5. Re-render Optimization (MEDIUM)
-
-- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
-- `rerender-memo` - Extract expensive work into memoized components
-- `rerender-memo-with-default-value` - Hoist default non-primitive props
-- `rerender-dependencies` - Use primitive dependencies in effects
-- `rerender-derived-state` - Subscribe to derived booleans, not raw values
-- `rerender-derived-state-no-effect` - Derive state during render, not effects
-- `rerender-functional-setstate` - Use functional setState for stable callbacks
-- `rerender-lazy-state-init` - Pass function to useState for expensive values
-- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
-- `rerender-move-effect-to-event` - Put interaction logic in event handlers
-- `rerender-transitions` - Use startTransition for non-urgent updates
-- `rerender-use-ref-transient-values` - Use refs for transient frequent values
-
-### 6. Rendering Performance (MEDIUM)
-
-- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
-- `rendering-content-visibility` - Use content-visibility for long lists
-- `rendering-hoist-jsx` - Extract static JSX outside components
-- `rendering-svg-precision` - Reduce SVG coordinate precision
-- `rendering-hydration-no-flicker` - Use inline script for client-only data
-- `rendering-hydration-suppress-warning` - Suppress expected mismatches
-- `rendering-activity` - Use Activity component for show/hide
-- `rendering-conditional-render` - Use ternary, not && for conditionals
-- `rendering-usetransition-loading` - Prefer useTransition for loading state
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-- `js-batch-dom-css` - Group CSS changes via classes or cssText
-- `js-index-maps` - Build Map for repeated lookups
-- `js-cache-property-access` - Cache object properties in loops
-- `js-cache-function-results` - Cache function results in module-level Map
-- `js-cache-storage` - Cache localStorage/sessionStorage reads
-- `js-combine-iterations` - Combine multiple filter/map into one loop
-- `js-length-check-first` - Check array length before expensive comparison
-- `js-early-exit` - Return early from functions
-- `js-hoist-regexp` - Hoist RegExp creation outside loops
-- `js-min-max-loop` - Use loop for min/max instead of sort
-- `js-set-map-lookups` - Use Set/Map for O(1) lookups
-- `js-tosorted-immutable` - Use toSorted() for immutability
-
-### 8. Advanced Patterns (LOW)
-
-- `advanced-event-handler-refs` - Store event handlers in refs
-- `advanced-init-once` - Initialize app once per app load
-- `advanced-use-latest` - useLatest for stable callback refs
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/async-parallel.md
-rules/bundle-barrel-imports.md
-```
-
-Each rule file contains:
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`
+- `async-*`
+- `bundle-*`
+- `server-*`
+- `client-*`
+- `rerender-*`
+- `rendering-*`
+- `js-*`
+- `advanced-*`

package/workflows/powers/react-expert/POWER.md

@@ -1,87 +1,59 @@
 ````markdown
 ---
 inclusion: manual
-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."
+name: "react-expert"
+description: "Use for framework-agnostic React architecture with React 19 patterns, state design, and performance tuning."
 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
+  version: "2.0.0"
+  domain: "frontend"
+  role: "specialist"
+  stack: "react"
+  baseline: "React 19"
 ---
 
 # React Expert
 
-Senior React specialist with deep expertise in React 19, Server Components, and production-grade application architecture.
+## Scope
 
-## Role Definition
+- Use this for React component and state architecture.
+- Use `nextjs-developer` for Next.js routing/App Router specifics.
 
-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
 
-## When to Use This Skill
+- Building reusable component systems.
+- Designing local/shared/remote state boundaries.
+- Refactoring for rendering performance.
+- Implementing robust form and async UI flows.
 
-- 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
 
-## Core Workflow
+1. Model component responsibilities and ownership boundaries.
+2. Decide state location and mutation strategy.
+3. Implement with accessible markup and predictable effects.
+4. Measure rerender behavior before applying memoization.
+5. Validate with component and interaction tests.
 
-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
+## Baseline standards
 
-## Reference Guide
+- Prefer pure render logic and explicit side-effect boundaries.
+- Use transitions/suspense intentionally for UX.
+- Keep effects idempotent and cleanup-safe.
+- Derive state instead of duplicating it.
+- Keep mutation logic centralized when state grows.
 
-Load detailed guidance based on context:
+## Avoid
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Server Components | `references/server-components.md` | RSC patterns, Next.js App Router |
-| React 19 | `references/react-19-features.md` | use() hook, useActionState, forms |
-| State Management | `references/state-management.md` | Context, Zustand, Redux, TanStack |
-| Hooks | `references/hooks-patterns.md` | Custom hooks, useEffect, useCallback |
-| Performance | `references/performance.md` | memo, lazy, virtualization |
-| Testing | `references/testing-react.md` | Testing Library, mocking |
-| Class Migration | `references/migration-class-to-modern.md` | Converting class components to hooks/RSC |
+- Blanket memoization without profiling evidence.
+- Effect-driven derived state loops.
+- Hidden shared mutable module state.
 
-## Constraints
+## Reference files
 
-### 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)
+- `references/react-19-features.md`
+- `references/hooks-patterns.md`
+- `references/state-management.md`
+- `references/performance.md`
+- `references/testing-react.md`
+- `references/server-components.md`
 ````

package/workflows/powers/react-expert/SKILL.md

@@ -1,84 +1,56 @@
 ---
-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."
+name: "react-expert"
+description: "Use for framework-agnostic React architecture with React 19 patterns, state design, and performance tuning."
 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
+  version: "2.0.0"
+  domain: "frontend"
+  role: "specialist"
+  stack: "react"
+  baseline: "React 19"
 ---
 
 # React Expert
 
-Senior React specialist with deep expertise in React 19, Server Components, and production-grade application architecture.
+## Scope
 
-## Role Definition
+- Use this for React component and state architecture.
+- Use `nextjs-developer` for Next.js routing/App Router specifics.
 
-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
 
-## When to Use This Skill
+- Building reusable component systems.
+- Designing local/shared/remote state boundaries.
+- Refactoring for rendering performance.
+- Implementing robust form and async UI flows.
 
-- 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
 
-## Core Workflow
+1. Model component responsibilities and ownership boundaries.
+2. Decide state location and mutation strategy.
+3. Implement with accessible markup and predictable effects.
+4. Measure rerender behavior before applying memoization.
+5. Validate with component and interaction tests.
 
-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
+## Baseline standards
 
-## Reference Guide
+- Prefer pure render logic and explicit side-effect boundaries.
+- Use transitions/suspense intentionally for UX.
+- Keep effects idempotent and cleanup-safe.
+- Derive state instead of duplicating it.
+- Keep mutation logic centralized when state grows.
 
-Load detailed guidance based on context:
+## Avoid
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Server Components | `references/server-components.md` | RSC patterns, Next.js App Router |
-| React 19 | `references/react-19-features.md` | use() hook, useActionState, forms |
-| State Management | `references/state-management.md` | Context, Zustand, Redux, TanStack |
-| Hooks | `references/hooks-patterns.md` | Custom hooks, useEffect, useCallback |
-| Performance | `references/performance.md` | memo, lazy, virtualization |
-| Testing | `references/testing-react.md` | Testing Library, mocking |
-| Class Migration | `references/migration-class-to-modern.md` | Converting class components to hooks/RSC |
+- Blanket memoization without profiling evidence.
+- Effect-driven derived state loops.
+- Hidden shared mutable module state.
 
-## Constraints
+## Reference files
 
-### 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)
+- `references/react-19-features.md`
+- `references/hooks-patterns.md`
+- `references/state-management.md`
+- `references/performance.md`
+- `references/testing-react.md`
+- `references/server-components.md`