@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/state-context-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: state-context-pattern
+version: '1.0.0'
+description: Manage shared state with React Context and useReducer for prop-drilling avoidance
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/context/**'
+  - '**/contexts/**'
+  - '**/providers/**'
+related_skills:
+  - state-jotai-atoms
+  - state-zustand-store
+  - state-selection-patterns
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - context
+  - useContext
+  - useReducer
+  - provider
+  - prop-drilling
+metadata:
+  author: community
+  upstream: 'react/docs/context'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/state-jotai-atoms/SKILL.md

@@ -0,0 +1,153 @@
+# Jotai Atoms
+
+> Build bottom-up atomic state with Jotai for granular, composable React state management
+
+## When to Use
+
+- Managing state that is naturally composed of small independent pieces (form fields, toggles, filters)
+- Needing derived/computed state that automatically updates when dependencies change (like Recoil selectors)
+- Wanting React Context-like convenience without re-render performance problems
+- Building components that each need a small piece of global state without subscribing to everything
+
+## Instructions
+
+1. Create primitive atoms with `atom(initialValue)`. These are the smallest units of state.
+2. Create derived (read-only) atoms with `atom((get) => computation)`. They auto-update when dependencies change.
+3. Create writable derived atoms with `atom(readFn, writeFn)` for computed state with custom setters.
+4. Use `useAtom` in components — it returns `[value, setValue]` like `useState`.
+5. Use `useAtomValue` for read-only access and `useSetAtom` for write-only access to minimize subscriptions.
+6. Group related atoms in a file per domain (`atoms/auth.ts`, `atoms/cart.ts`).
+7. No Provider needed for basic usage — Jotai uses a default store. Add `<Provider>` only for scoped state or testing.
+
+```typescript
+// atoms/cart.ts
+import { atom } from 'jotai';
+
+interface CartItem {
+  id: string;
+  name: string;
+  price: number;
+  qty: number;
+}
+
+// Primitive atoms
+export const cartItemsAtom = atom<CartItem[]>([]);
+export const couponCodeAtom = atom<string | null>(null);
+
+// Derived atom (read-only) — auto-updates when cartItemsAtom changes
+export const cartTotalAtom = atom((get) => {
+  const items = get(cartItemsAtom);
+  return items.reduce((sum, item) => sum + item.price * item.qty, 0);
+});
+
+export const cartCountAtom = atom((get) => {
+  return get(cartItemsAtom).reduce((sum, item) => sum + item.qty, 0);
+});
+
+// Derived atom with discount applied
+export const discountedTotalAtom = atom((get) => {
+  const total = get(cartTotalAtom);
+  const coupon = get(couponCodeAtom);
+  return coupon ? total * 0.9 : total;
+});
+
+// Writable derived atom — custom setter
+export const addToCartAtom = atom(
+  null, // read value (null = write-only)
+  (get, set, newItem: Omit<CartItem, 'qty'>) => {
+    const items = get(cartItemsAtom);
+    const existing = items.find((i) => i.id === newItem.id);
+    if (existing) {
+      set(
+        cartItemsAtom,
+        items.map((i) => (i.id === newItem.id ? { ...i, qty: i.qty + 1 } : i))
+      );
+    } else {
+      set(cartItemsAtom, [...items, { ...newItem, qty: 1 }]);
+    }
+  }
+);
+```
+
+```typescript
+// Component usage
+import { useAtomValue, useSetAtom } from 'jotai';
+
+function CartSummary() {
+  const total = useAtomValue(discountedTotalAtom); // Read-only, re-renders only when total changes
+  const count = useAtomValue(cartCountAtom);
+  return <div>{count} items - ${total.toFixed(2)}</div>;
+}
+
+function AddButton({ product }: { product: { id: string; name: string; price: number } }) {
+  const addToCart = useSetAtom(addToCartAtom); // Write-only, never re-renders from this atom
+  return <button onClick={() => addToCart(product)}>Add to Cart</button>;
+}
+```
+
+## Details
+
+**Atom dependency graph:** Derived atoms automatically track which atoms they read via `get()`. When any dependency changes, the derived atom recomputes. This is reactive — no manual subscription management.
+
+**Async atoms:** Atoms can return promises. Jotai integrates with React Suspense:
+
+```typescript
+const userAtom = atom(async () => {
+  const res = await fetch('/api/user');
+  return res.json();
+});
+
+// Component suspends until data loads
+function User() {
+  const user = useAtomValue(userAtom); // Suspends, then returns data
+  return <div>{user.name}</div>;
+}
+```
+
+**atomWithStorage:** Persist atoms to localStorage:
+
+```typescript
+import { atomWithStorage } from 'jotai/utils';
+
+const themeAtom = atomWithStorage('theme', 'light');
+// Automatically reads from and writes to localStorage
+```
+
+**Jotai vs Zustand:** Jotai is bottom-up (compose small atoms into larger state). Zustand is top-down (define a store, select slices). Choose Jotai when state is naturally fragmented across many components. Choose Zustand when state is a cohesive domain object.
+
+**Jotai vs React Context:** Both are Provider-based. But Context re-renders all consumers when any value changes. Jotai only re-renders consumers of the specific atom that changed.
+
+**Testing:** Use `<Provider>` in tests to create isolated atom scopes:
+
+```typescript
+import { Provider, createStore } from 'jotai';
+
+const store = createStore();
+store.set(cartItemsAtom, mockItems);
+
+render(
+  <Provider store={store}>
+    <CartSummary />
+  </Provider>
+);
+```
+
+## Source
+
+https://jotai.org/docs/introduction
+
+## 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/cursor/state-jotai-atoms/skill.yaml

@@ -0,0 +1,40 @@
+name: state-jotai-atoms
+version: '1.0.0'
+description: Build bottom-up atomic state with Jotai atoms for granular React state management
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/atoms/**'
+  - '**/state/**'
+  - '**/store/**'
+related_skills:
+  - state-context-pattern
+  - state-selection-patterns
+  - state-zustand-store
+stack_signals:
+  - jotai
+  - react
+  - typescript
+keywords:
+  - jotai
+  - atom
+  - derived-atom
+  - atomWithStorage
+  - bottom-up-state
+metadata:
+  author: community
+  upstream: 'jotai/docs'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/state-selection-patterns/SKILL.md

@@ -0,0 +1,115 @@
+# State Selection Patterns
+
+> Select and derive state efficiently to minimize component re-renders across any state management library
+
+## When to Use
+
+- Components re-render too frequently due to subscribing to more state than they need
+- Computing derived data (filtered lists, aggregations) from raw state
+- Memoizing expensive computations that depend on state
+- Building a consistent selector strategy across Zustand, Redux, Jotai, or Context
+
+## Instructions
+
+1. **Select the minimum:** Subscribe only to the exact fields a component needs. Never subscribe to the entire store.
+2. **Keep selectors pure:** A selector is a function from state to derived value. No side effects.
+3. **Stabilize references:** Selectors that return new objects/arrays on every call defeat memoization. Use memoized selectors or shallow comparison.
+4. **Colocate simple selectors with the store.** Complex derived selectors go in a dedicated selectors file.
+5. **Compose selectors:** Build complex selectors by combining simpler ones.
+6. **Test selectors as pure functions** — pass state in, assert output.
+
+```typescript
+// Pattern 1: Zustand — inline selector
+const userName = useStore((s) => s.user.name);
+// Only re-renders when user.name changes (reference equality)
+
+// Pattern 2: Zustand — multiple fields with useShallow
+import { useShallow } from 'zustand/react/shallow';
+const { name, email } = useStore(useShallow((s) => ({ name: s.user.name, email: s.user.email })));
+
+// Pattern 3: Redux — createSelector for derived data
+import { createSelector } from '@reduxjs/toolkit';
+
+const selectTodos = (state: RootState) => state.todos.items;
+const selectFilter = (state: RootState) => state.todos.filter;
+
+const selectVisibleTodos = createSelector(
+  [selectTodos, selectFilter],
+  (todos, filter) => {
+    if (filter === 'all') return todos;
+    return todos.filter((t) => (filter === 'completed' ? t.completed : !t.completed));
+  }
+);
+
+// Pattern 4: Jotai — derived atoms
+const visibleTodosAtom = atom((get) => {
+  const todos = get(todosAtom);
+  const filter = get(filterAtom);
+  return filter === 'all' ? todos : todos.filter((t) => t.completed === (filter === 'completed'));
+});
+
+// Pattern 5: useMemo for component-level derivations
+function FilteredList({ filter }: { filter: string }) {
+  const items = useStore((s) => s.items);
+  const filtered = useMemo(
+    () => items.filter((i) => i.category === filter),
+    [items, filter]
+  );
+  return <List items={filtered} />;
+}
+```
+
+## Details
+
+**Why reference equality matters:** React and state libraries use `Object.is` (reference equality) to decide if a component should re-render. If your selector returns `todos.filter(...)`, it creates a new array on every call, even if the contents are identical. The component re-renders every time.
+
+**Memoization strategies by library:**
+
+| Library | Strategy              | Tool                        |
+| ------- | --------------------- | --------------------------- |
+| Redux   | Input memoization     | `createSelector` (Reselect) |
+| Zustand | Shallow equality      | `useShallow`                |
+| Jotai   | Atom dependency graph | Derived atoms               |
+| React   | Component-level memo  | `useMemo`                   |
+
+**Selector composition pattern:**
+
+```typescript
+// Base selectors (simple accessors)
+const selectUsers = (state: RootState) => state.users.items;
+const selectCurrentUserId = (state: RootState) => state.auth.userId;
+
+// Composed selector (derived from base selectors)
+const selectCurrentUser = createSelector([selectUsers, selectCurrentUserId], (users, userId) =>
+  users.find((u) => u.id === userId)
+);
+
+// Further composition
+const selectCurrentUserPosts = createSelector([selectCurrentUser, selectPosts], (user, posts) =>
+  user ? posts.filter((p) => p.authorId === user.id) : []
+);
+```
+
+**When NOT to memoize:** Primitive values (numbers, strings, booleans) are compared by value. `useStore((s) => s.count)` never creates a new reference — no memoization needed. Only memoize when the selector returns objects, arrays, or computes derived data.
+
+**Performance debugging:** Use React DevTools Profiler to identify components that re-render unnecessarily. Check what selector results change between renders. Use `why-did-you-render` for automated detection.
+
+## Source
+
+https://react.dev/reference/react/useMemo
+
+## 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/cursor/state-selection-patterns/skill.yaml

@@ -0,0 +1,40 @@
+name: state-selection-patterns
+version: '1.0.0'
+description: Select and derive state efficiently across stores to minimize component re-renders
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/store/**'
+  - '**/stores/**'
+  - '**/selectors/**'
+  - '**/hooks/**'
+related_skills:
+  - state-zustand-react
+  - state-jotai-atoms
+  - redux-selectors-pattern
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - selectors
+  - memoization
+  - derived-state
+  - re-render-optimization
+  - equality
+metadata:
+  author: community
+  upstream: 'react/docs/hooks'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/state-server-client-sync/SKILL.md

@@ -0,0 +1,148 @@
+# Server-Client State Sync
+
+> Separate server state from client state and synchronize them with TanStack Query and local stores
+
+## When to Use
+
+- Managing data fetched from APIs alongside local UI state
+- Needing stale-while-revalidate caching for server data
+- Avoiding duplicating server data into Redux/Zustand stores
+- Handling optimistic updates that reconcile with server responses
+
+## Instructions
+
+1. **Separate concerns:** Server state (data from APIs) belongs in TanStack Query (React Query). Client state (UI preferences, form drafts, local selections) belongs in Zustand, Jotai, or Context.
+2. Use `useQuery` for read operations. The query key uniquely identifies the data.
+3. Use `useMutation` for write operations. Invalidate related queries on success.
+4. Do NOT copy server data into a client store. Query the cache directly or use the query hook.
+5. When server state and client state must combine (e.g., a list from the API filtered by a local search term), keep them in their respective systems and compose in the component.
+6. Use `queryClient.setQueryData` for optimistic updates. Roll back with `onError`.
+
+```typescript
+// hooks/use-todos.ts — server state via TanStack Query
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+}
+
+export function useTodos() {
+  return useQuery({
+    queryKey: ['todos'],
+    queryFn: async (): Promise<Todo[]> => {
+      const res = await fetch('/api/todos');
+      return res.json();
+    },
+    staleTime: 5 * 60 * 1000, // Consider fresh for 5 minutes
+  });
+}
+
+export function useToggleTodo() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ id, completed }: { id: string; completed: boolean }) => {
+      const res = await fetch(`/api/todos/${id}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ completed }),
+      });
+      return res.json();
+    },
+    // Optimistic update
+    onMutate: async ({ id, completed }) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] });
+      const previous = queryClient.getQueryData<Todo[]>(['todos']);
+      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
+        old?.map((t) => (t.id === id ? { ...t, completed } : t))
+      );
+      return { previous };
+    },
+    onError: (err, vars, context) => {
+      queryClient.setQueryData(['todos'], context?.previous);
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] });
+    },
+  });
+}
+```
+
+```typescript
+// stores/ui-store.ts — client state via Zustand
+import { create } from 'zustand';
+
+interface UIStore {
+  searchTerm: string;
+  filterCompleted: boolean | null;
+  setSearchTerm: (term: string) => void;
+  setFilterCompleted: (filter: boolean | null) => void;
+}
+
+export const useUIStore = create<UIStore>((set) => ({
+  searchTerm: '',
+  filterCompleted: null,
+  setSearchTerm: (searchTerm) => set({ searchTerm }),
+  setFilterCompleted: (filterCompleted) => set({ filterCompleted }),
+}));
+```
+
+```typescript
+// Component — composing server + client state
+function TodoList() {
+  const { data: todos = [], isLoading } = useTodos();
+  const searchTerm = useUIStore((s) => s.searchTerm);
+  const filterCompleted = useUIStore((s) => s.filterCompleted);
+
+  const filtered = useMemo(() => {
+    let result = todos;
+    if (searchTerm) result = result.filter((t) => t.title.includes(searchTerm));
+    if (filterCompleted !== null) result = result.filter((t) => t.completed === filterCompleted);
+    return result;
+  }, [todos, searchTerm, filterCompleted]);
+
+  if (isLoading) return <Spinner />;
+  return filtered.map((todo) => <TodoItem key={todo.id} todo={todo} />);
+}
+```
+
+## Details
+
+**The separation principle:** Server state is async, cached, shared, and can become stale. Client state is synchronous, local, and always fresh. Mixing them (copying API data into Redux) creates synchronization bugs. Let TanStack Query own server state; let your client store own UI state.
+
+**When you need both together:** Compose in the component layer. The component reads from both sources and combines them. This keeps each system simple and avoids double-caching.
+
+**Query invalidation strategy:**
+
+- `invalidateQueries({ queryKey: ['todos'] })` — mark as stale, refetch if mounted
+- `queryClient.setQueryData` — update cache directly (optimistic updates)
+- `refetchQueries` — force immediate refetch regardless of staleness
+
+**Background refetching:** TanStack Query refetches stale data on window focus, on reconnect, and on interval (configurable). This keeps server state fresh without manual polling.
+
+**Anti-patterns:**
+
+- Storing fetched data in Zustand/Redux and using it instead of the query cache
+- Using `useEffect` + `useState` for data fetching (TanStack Query replaces this)
+- Invalidating every query after every mutation (be surgical with query keys)
+
+## Source
+
+https://tanstack.com/query/latest/docs/framework/react/overview
+
+## 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/cursor/state-server-client-sync/skill.yaml

@@ -0,0 +1,41 @@
+name: state-server-client-sync
+version: '1.0.0'
+description: Synchronize server state with client state using React Query patterns and cache coordination
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/hooks/**'
+  - '**/queries/**'
+  - '**/api/**'
+  - '**/store/**'
+related_skills:
+  - state-zustand-store
+  - state-selection-patterns
+  - state-context-pattern
+stack_signals:
+  - react
+  - typescript
+keywords:
+  - server-state
+  - client-state
+  - react-query
+  - tanstack-query
+  - cache-sync
+  - stale-while-revalidate
+metadata:
+  author: community
+  upstream: 'tanstack-query/docs'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/state-zustand-devtools/SKILL.md

@@ -0,0 +1,120 @@
+# Zustand DevTools
+
+> Debug Zustand stores with Redux DevTools integration for time-travel debugging and action inspection
+
+## When to Use
+
+- Debugging state changes in development — seeing what changed and when
+- Tracing which action caused an unexpected state update
+- Time-travel debugging to replay state transitions
+- Inspecting store state without adding console.log statements
+
+## Instructions
+
+1. Wrap the store creator with the `devtools` middleware from `zustand/middleware`.
+2. Pass a `name` option to identify the store in the DevTools panel (especially when using multiple stores).
+3. Name your actions by passing a string as the third argument to `set()` — this shows descriptive action names instead of "anonymous".
+4. When combining with other middleware, `devtools` should be the outermost wrapper.
+5. Disable in production with a conditional or rely on the middleware's built-in `enabled` option.
+
+```typescript
+// stores/todo-store.ts
+import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
+
+interface TodoStore {
+  todos: Array<{ id: string; text: string; done: boolean }>;
+  addTodo: (text: string) => void;
+  toggleTodo: (id: string) => void;
+  removeTodo: (id: string) => void;
+}
+
+export const useTodoStore = create<TodoStore>()(
+  devtools(
+    (set) => ({
+      todos: [],
+      addTodo: (text) =>
+        set(
+          (state) => ({
+            todos: [...state.todos, { id: crypto.randomUUID(), text, done: false }],
+          }),
+          false, // replace: false (default merge behavior)
+          'todos/addTodo' // Action name shown in DevTools
+        ),
+      toggleTodo: (id) =>
+        set(
+          (state) => ({
+            todos: state.todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
+          }),
+          false,
+          'todos/toggleTodo'
+        ),
+      removeTodo: (id) =>
+        set(
+          (state) => ({ todos: state.todos.filter((t) => t.id !== id) }),
+          false,
+          'todos/removeTodo'
+        ),
+    }),
+    { name: 'TodoStore', enabled: process.env.NODE_ENV === 'development' }
+  )
+);
+```
+
+## Details
+
+**Middleware stacking order:** When combining multiple middlewares, order matters. The outermost middleware wraps everything:
+
+```typescript
+// Correct order: devtools > persist > immer (outermost to innermost)
+create<Store>()(
+  devtools(
+    persist(
+      immer((set) => ({
+        /* ... */
+      })),
+      { name: 'storage-key' }
+    ),
+    { name: 'StoreName' }
+  )
+);
+```
+
+**Named actions:** The third argument to `set(state, replace, actionName)` appears in the Redux DevTools action log. Without it, every action shows as "anonymous" which makes debugging difficult. Use a `slice/action` naming convention.
+
+**Multiple stores:** Each store with `devtools` appears as a separate instance in the Redux DevTools dropdown. Use distinct `name` values.
+
+**Time-travel debugging:** Redux DevTools supports jumping to any previous state. This works with Zustand's devtools middleware — clicking a past action restores the store to that point.
+
+**Production safety:** Either use `enabled: false` in production or strip the middleware entirely:
+
+```typescript
+const middlewares = (f: StateCreator<Store>) =>
+  process.env.NODE_ENV === 'development' ? devtools(f, { name: 'Store' }) : f;
+
+export const useStore = create<Store>()(
+  middlewares((set) => ({
+    /* ... */
+  }))
+);
+```
+
+## Source
+
+https://zustand.docs.pmnd.rs/middlewares/devtools
+
+## 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.