@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/react-dynamic-import/SKILL.md

@@ -0,0 +1,65 @@
+# React Dynamic Import
+
+> Load modules on demand to reduce initial bundle size and improve startup performance
+
+## When to Use
+
+- A component is only needed after user interaction (modal, drawer, tab panel)
+- A route's components should not be in the initial bundle (route-based splitting)
+- A large library is only used in a specific feature
+- Below-fold content that users may never scroll to
+
+## Instructions
+
+1. Use `React.lazy` with a dynamic `import()` for component splitting:
+   ```typescript
+   const Modal = React.lazy(() => import('./Modal'));
+   ```
+2. Always wrap lazy components in `<Suspense>` with a fallback.
+3. For non-component modules, use `import()` directly:
+   ```typescript
+   const { heavyComputation } = await import('./heavy-utils');
+   ```
+4. Add webpack/vite magic comments for named chunks:
+   ```typescript
+   const Chart = React.lazy(() => import(/* webpackChunkName: "chart" */ './Chart'));
+   ```
+5. Preload on hover for likely interactions:
+   ```typescript
+   const preload = () => import('./Modal');
+   <button onMouseEnter={preload} onClick={openModal}>Open</button>
+   ```
+
+## Details
+
+Dynamic import is a JavaScript language feature (Stage 4). Bundlers create separate "chunks" for dynamically imported modules, loaded via `<script>` tags at runtime.
+
+**Chunk naming strategy:**
+
+- Route-based: one chunk per top-level route
+- Feature-based: one chunk per large feature (chart library, editor, admin panel)
+- Vendor splitting: separate chunks for node_modules (better long-term caching)
+
+**Preloading:** `<link rel="preload">` or `import()` on hover/route-change triggers network fetch before the user needs it, hiding latency. Framework routers (Next.js, React Router) do this automatically for adjacent routes.
+
+**Measurement:** Analyze bundle with `vite build --report` or `webpack-bundle-analyzer` before and after splitting.
+
+## Source
+
+https://patterns.dev/react/dynamic-import
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/react-dynamic-import/skill.yaml

@@ -0,0 +1,40 @@
+name: react-dynamic-import
+version: '1.0.0'
+description: Load modules on demand to reduce initial bundle size and improve startup performance
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.ts'
+related_skills:
+  - react-static-import
+  - react-suspense-pattern
+  - react-progressive-hydration
+stack_signals:
+  - react
+  - typescript
+  - webpack
+  - vite
+keywords:
+  - dynamic-import
+  - code-splitting
+  - lazy-loading
+  - bundle-size
+  - on-demand
+metadata:
+  author: patterns.dev
+  upstream: 'PatternsDev/skills/react/dynamic-import'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/react-hoc-pattern/SKILL.md

@@ -0,0 +1,71 @@
+# React HOC Pattern
+
+> Extend component behavior by wrapping in a higher-order component
+
+## When to Use
+
+- Adding cross-cutting concerns (logging, authentication gating, analytics) to multiple components without modifying each
+- Working with class components that cannot use hooks
+- Integrating with third-party libraries that use HOC APIs (Redux `connect`, React Router `withRouter`)
+- You want to enhance a component's props without the consumer being aware of the enhancement
+
+## Instructions
+
+1. Create a function that accepts a component and returns a new component.
+2. The wrapper component renders the wrapped component, forwarding all props.
+3. Add the enhancement (extra props, lifecycle behavior, conditional rendering) in the wrapper.
+4. Name the HOC `with<Behavior>` by convention.
+5. Forward refs using `React.forwardRef` if the wrapped component uses refs.
+6. Set `displayName` on the HOC result for debugging: `WrappedComponent.displayName = \`withAuth(\${Component.displayName})\``.
+
+```typescript
+function withAuthentication<P extends object>(
+  WrappedComponent: React.ComponentType<P>
+) {
+  const WithAuth = (props: P) => {
+    const { isAuthenticated } = useAuth();
+    if (!isAuthenticated) return <Redirect to="/login" />;
+    return <WrappedComponent {...props} />;
+  };
+  WithAuth.displayName = `withAuthentication(${WrappedComponent.displayName ?? WrappedComponent.name})`;
+  return WithAuth;
+}
+```
+
+## Details
+
+HOCs are a functional composition pattern borrowed from functional programming. They were the primary code-reuse mechanism before hooks.
+
+**When to prefer hooks over HOCs:**
+
+- Hooks are simpler, avoid prop name collisions, and are easier to type in TypeScript
+- "Wrapper hell" — stacking multiple HOCs creates deeply nested component trees in DevTools
+- HOC prop injection can clash if two HOCs inject the same prop name
+
+**Valid HOC use cases in modern React:**
+
+- HOC-based library APIs (Redux, styled-components `withTheme`)
+- Class components that cannot use hooks
+- Performance optimization with `React.memo` and custom comparison
+
+**TypeScript note:** HOC generic typing requires careful handling of `ComponentProps` and `Omit` to correctly type the enhanced component's props.
+
+## Source
+
+https://patterns.dev/react/hoc-pattern
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/react-hoc-pattern/skill.yaml

@@ -0,0 +1,35 @@
+name: react-hoc-pattern
+version: '1.0.0'
+description: Extend component behavior by wrapping in a higher-order component
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+related_skills:
+  - react-hooks-pattern
+  - react-render-props-pattern
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - hoc
+  - higher-order-component
+  - component-composition
+  - cross-cutting-concerns
+metadata:
+  author: patterns.dev
+  upstream: 'PatternsDev/skills/react/hoc-pattern'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/react-hooks-pattern/SKILL.md

@@ -0,0 +1,74 @@
+# React Hooks Pattern
+
+> Reuse stateful logic across components via custom hooks
+
+## When to Use
+
+- Multiple components share the same stateful logic (e.g., data fetching, form state, media queries)
+- You want to extract complex logic from a component to improve readability
+- You need to compose behaviors without inheritance or render props
+- You are using React 16.8+ (hooks are unavailable in class components)
+
+## Instructions
+
+1. Identify repeated stateful logic across two or more components.
+2. Extract it into a function prefixed with `use` (e.g., `useWindowSize`, `useFetch`, `useForm`).
+3. The custom hook must call at least one built-in hook (`useState`, `useEffect`, `useCallback`, etc.).
+4. Return only what the consumer needs — avoid over-exposing internal state.
+5. Name the hook descriptively after its behavior, not its implementation (`useMediaQuery` not `useEventListener`).
+6. Keep hooks pure and side-effect-free at the call site — effects belong inside `useEffect`.
+7. Document the hook's return type with TypeScript interfaces.
+8. Co-locate the hook file with its primary consumer or in a `hooks/` directory.
+
+```typescript
+// Good: descriptive name, typed return, minimal surface area
+function useWindowSize(): { width: number; height: number } {
+  const [size, setSize] = useState({ width: window.innerWidth, height: window.innerHeight });
+  useEffect(() => {
+    const handler = () => setSize({ width: window.innerWidth, height: window.innerHeight });
+    window.addEventListener('resize', handler);
+    return () => window.removeEventListener('resize', handler);
+  }, []);
+  return size;
+}
+```
+
+## Details
+
+Custom hooks were introduced in React 16.8 to solve the code reuse problem that previously required higher-order components or render props. The key insight: hooks are just functions, and the `use` prefix is a convention that enables lint rules (react-hooks/rules-of-hooks) to enforce hook semantics.
+
+**Trade-offs:**
+
+- Hooks compose easily but debugging deep hook stacks can be harder than class-based patterns
+- The `use` naming convention is enforced by ESLint, not the runtime — calling a hook outside a component or another hook will cause runtime errors, not type errors
+- React DevTools shows custom hook names in the component tree when they follow the `use` prefix convention
+
+**When NOT to use:**
+
+- Logic that does not involve state or effects — extract as a plain utility function instead
+- Logic specific to a single component that will never be reused
+
+**Related patterns:**
+
+- Provider Pattern — hooks often expose context via a `useXxx()` wrapper
+- Compound Pattern — hooks can manage shared state for compound component groups
+
+## Source
+
+https://patterns.dev/react/hooks-pattern
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/react-hooks-pattern/skill.yaml

@@ -0,0 +1,37 @@
+name: react-hooks-pattern
+version: '1.0.0'
+description: Reuse stateful logic across components via custom hooks
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+related_skills:
+  - react-compound-pattern
+  - react-provider-pattern
+  - react-context-pattern
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - hooks
+  - custom-hooks
+  - stateful-logic
+  - composition
+  - use-prefix
+metadata:
+  author: patterns.dev
+  upstream: 'PatternsDev/skills/react/hooks-pattern'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/react-islands-pattern/SKILL.md

@@ -0,0 +1,67 @@
+# React Islands Pattern
+
+> Hydrate only interactive UI islands, leaving static content as HTML
+
+## When to Use
+
+- Content-heavy pages where most HTML is static but a few widgets need interactivity
+- Performance-critical pages where full React hydration is too expensive
+- Using Astro, Fresh, or Next.js with `'use client'` directives
+- You want Time to Interactive (TTI) improvements by deferring non-essential JS
+
+## Instructions
+
+1. Identify which page regions are interactive (search bar, shopping cart, comments) vs static (header, article body).
+2. Mark interactive regions as client-side islands using your framework's mechanism:
+   - **Astro:** `client:load`, `client:idle`, `client:visible` on components
+   - **Next.js App Router:** `'use client'` at the top of the component file
+3. Keep islands as small as possible — each island is an independent React root.
+4. Static content between islands is plain HTML — no React overhead.
+5. Use `client:visible` (Astro) or lazy hydration for below-fold islands.
+
+```tsx
+// Astro example: only the interactive widget is hydrated
+---
+import StaticHeader from './StaticHeader.astro'; // no JS
+import InteractiveSearch from './InteractiveSearch';  // React island
+---
+<StaticHeader />
+<InteractiveSearch client:load />
+<article>...static content...</article>
+```
+
+## Details
+
+The islands pattern was popularized by Jason Miller (Preact creator) and Ethan Marcotte. The core insight: most web pages are "mostly static" — only specific regions need event handlers and state. Hydrating the entire page as a React app is wasteful.
+
+**Trade-offs:**
+
+- Islands cannot share React state directly — use URL parameters, localStorage, or a micro-frontend event bus for cross-island communication
+- More complex architecture than a simple SPA
+- Best suited for content-driven sites (docs, marketing, e-commerce) not dashboards
+
+**React Server Components (RSC) vs islands:**
+
+- RSC is React's first-party answer to the same problem in Next.js / frameworks
+- The conceptual model is the same (server = static, client = interactive)
+- RSC allows data co-location without the multi-root complexity
+
+## Source
+
+https://patterns.dev/react/islands-architecture
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/react-islands-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: react-islands-pattern
+version: '1.0.0'
+description: Hydrate only interactive UI islands, leaving static content as HTML
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+related_skills:
+  - react-progressive-hydration
+  - react-server-components
+  - react-server-rendering
+stack_signals:
+  - react
+  - typescript
+  - astro
+  - next
+keywords:
+  - islands
+  - partial-hydration
+  - performance
+  - static-html
+  - interactive-components
+metadata:
+  author: patterns.dev
+  upstream: 'PatternsDev/skills/react/islands-pattern'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/react-memoization-pattern/SKILL.md

@@ -0,0 +1,64 @@
+# React Memoization Pattern
+
+> Prevent expensive re-renders and recomputations with React memoization APIs
+
+## When to Use
+
+- A child component re-renders with the same props because the parent re-renders (use `React.memo`)
+- A derived value is computationally expensive and its inputs rarely change (use `useMemo`)
+- A callback function reference must be stable to avoid breaking `React.memo` on child components (use `useCallback`)
+- You have profiled the component with React DevTools and confirmed unnecessary renders
+
+## Instructions
+
+1. **Profile first.** Do not memoize without evidence of a problem — premature memoization adds code complexity and can hurt performance if used incorrectly.
+2. Wrap a component with `React.memo` to skip re-render when props are shallowly equal:
+   ```typescript
+   const ExpensiveList = React.memo(function ExpensiveList({ items }: { items: Item[] }) {
+     return <ul>{items.map((i) => <li key={i.id}>{i.name}</li>)}</ul>;
+   });
+   ```
+3. Use `useMemo` for expensive computations:
+   ```typescript
+   const sortedItems = useMemo(() => [...items].sort(compareFn), [items]);
+   ```
+4. Use `useCallback` for stable callback references:
+   ```typescript
+   const handleClick = useCallback(() => onSelect(id), [id, onSelect]);
+   ```
+5. With React 19 Compiler: memoization may be inserted automatically — avoid manual `React.memo`/`useMemo` until you verify the compiler does not handle it.
+
+## Details
+
+Memoization trades memory for computation. React's memoization hooks cache values between renders when dependency arrays are unchanged.
+
+**Shallow equality:** `React.memo` uses shallow comparison — object/array props created inline always produce new references, breaking memoization. Pass stable references or memoize the props themselves.
+
+**`useMemo` vs `useCallback`:**
+
+- `useMemo` memoizes a computed value: `useMemo(() => compute(), [dep])`
+- `useCallback` memoizes a function: `useCallback(() => fn(), [dep])` — equivalent to `useMemo(() => () => fn(), [dep])`
+
+**React 19 Compiler:** The React compiler automatically memoizes components and hooks. Manual `React.memo`, `useMemo`, and `useCallback` may become unnecessary in codebases using the compiler.
+
+**Anti-pattern:** Wrapping every component in `React.memo` without profiling. Memo has overhead — the cost of comparison must be less than the cost of re-rendering.
+
+## Source
+
+https://patterns.dev/react/memoization-pattern
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/react-memoization-pattern/skill.yaml

@@ -0,0 +1,37 @@
+name: react-memoization-pattern
+version: '1.0.0'
+description: Prevent expensive re-renders and recomputations with React memoization APIs
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+related_skills:
+  - react-hooks-pattern
+  - react-concurrent-ui
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - memoization
+  - memo
+  - useMemo
+  - useCallback
+  - performance
+  - re-render
+metadata:
+  author: patterns.dev
+  upstream: 'PatternsDev/skills/react/memoization'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/react-progressive-hydration/SKILL.md

@@ -0,0 +1,74 @@
+# React Progressive Hydration
+
+> Delay hydration of below-fold or non-critical components to improve TTI
+
+## When to Use
+
+- SSR pages where hydrating all components at once creates a long TTI
+- Below-fold components that users will not interact with on page load
+- Low-priority widgets (cookie banners, chat widgets, footer interactions)
+- You need fast initial page interactivity without deferring all JS
+
+## Instructions
+
+1. Identify components that are not needed for initial interactivity.
+2. Wrap them in a lazy-hydration wrapper that triggers hydration on:
+   - **Viewport entry** (`IntersectionObserver`)
+   - **User idle** (`requestIdleCallback`)
+   - **First user interaction** (mousemove, touchstart)
+3. Render the component's HTML from SSR immediately (for SEO and visual), but defer event handler attachment.
+4. Use `React.lazy` + `Suspense` for code-splitting alongside hydration deferral.
+
+```typescript
+function LazyHydrate({ children }: { children: React.ReactNode }) {
+  const [hydrated, setHydrated] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(([entry]) => {
+      if (entry.isIntersecting) {
+        setHydrated(true);
+        observer.disconnect();
+      }
+    });
+    if (ref.current) observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div ref={ref}>
+      {hydrated ? children : <div dangerouslySetInnerHTML={{ __html: '' }} />}
+    </div>
+  );
+}
+```
+
+## Details
+
+Progressive hydration is distinct from islands: islands prevent hydration entirely for static regions, while progressive hydration defers hydration of React components that will eventually be interactive.
+
+**React 18 selective hydration:** `React.lazy` with Suspense boundaries already enables selective hydration in React 18 with `hydrateRoot`. React prioritizes hydrating components the user interacts with first.
+
+**Libraries:** `react-lazy-hydration`, `react-intersection-observer` provide production-ready utilities for this pattern.
+
+**Measurement:** Use Lighthouse TTI, Chrome DevTools Performance tab, and WebPageTest to verify improvements. Premature optimization without measurement is counterproductive.
+
+## Source
+
+https://patterns.dev/react/progressive-hydration
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/react-progressive-hydration/skill.yaml

@@ -0,0 +1,37 @@
+name: react-progressive-hydration
+version: '1.0.0'
+description: Delay hydration of below-fold or non-critical components to improve TTI
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+related_skills:
+  - react-islands-pattern
+  - react-suspense-pattern
+  - react-dynamic-import
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - hydration
+  - progressive
+  - lazy-hydration
+  - tti
+  - performance
+metadata:
+  author: patterns.dev
+  upstream: 'PatternsDev/skills/react/progressive-hydration'
+state:
+  persistent: false
+  files: []
+depends_on: []