@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/claude-code/state-jotai-atoms/skill.yaml

@@ -0,0 +1,39 @@
+name: state-jotai-atoms
+version: '1.0.0'
+description: Build bottom-up atomic state with Jotai atoms for granular React state management
+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/claude-code/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/claude-code/state-selection-patterns/skill.yaml

@@ -0,0 +1,39 @@
+name: state-selection-patterns
+version: '1.0.0'
+description: Select and derive state efficiently across stores to minimize component re-renders
+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/claude-code/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/claude-code/state-server-client-sync/skill.yaml

@@ -0,0 +1,40 @@
+name: state-server-client-sync
+version: '1.0.0'
+description: Synchronize server state with client state using React Query patterns and cache coordination
+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/claude-code/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.

package/dist/agents/skills/claude-code/state-zustand-devtools/skill.yaml

@@ -0,0 +1,38 @@
+name: state-zustand-devtools
+version: '1.0.0'
+description: Debug Zustand stores with Redux DevTools integration via the devtools middleware
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/store/**'
+  - '**/stores/**'
+related_skills:
+  - state-zustand-store
+  - state-zustand-slices
+  - state-zustand-persist
+stack_signals:
+  - zustand
+  - react
+  - typescript
+keywords:
+  - devtools
+  - debugging
+  - redux-devtools
+  - time-travel
+  - action-names
+metadata:
+  author: community
+  upstream: 'zustand/docs/devtools'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/state-zustand-immer/SKILL.md

@@ -0,0 +1,150 @@
+# Zustand Immer
+
+> Write mutable-style state updates in Zustand stores with the Immer middleware for cleaner nested mutations
+
+## When to Use
+
+- Store has deeply nested state that requires verbose spread operators to update
+- Updating items in arrays by index or by ID lookup
+- Teams familiar with Redux Toolkit's Immer integration wanting the same ergonomics
+- Any update where the immutable spread version is hard to read or error-prone
+
+## Instructions
+
+1. Wrap the store creator with the `immer` middleware from `zustand/middleware/immer`.
+2. Inside `set`, mutate the `state` object directly — Immer produces a new immutable state behind the scenes.
+3. Do NOT return a value from the `set` callback when using Immer — just mutate.
+4. The `immer` middleware should be the innermost middleware when combined with others.
+5. Install `immer` as a peer dependency: `npm install immer`.
+
+```typescript
+// stores/kanban-store.ts
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+
+interface Card {
+  id: string;
+  title: string;
+  description: string;
+}
+
+interface Column {
+  id: string;
+  title: string;
+  cards: Card[];
+}
+
+interface KanbanStore {
+  columns: Column[];
+  addCard: (columnId: string, card: Card) => void;
+  moveCard: (fromCol: string, toCol: string, cardId: string) => void;
+  updateCard: (columnId: string, cardId: string, updates: Partial<Card>) => void;
+  removeCard: (columnId: string, cardId: string) => void;
+}
+
+export const useKanbanStore = create<KanbanStore>()(
+  immer((set) => ({
+    columns: [],
+
+    addCard: (columnId, card) =>
+      set((state) => {
+        const column = state.columns.find((c) => c.id === columnId);
+        if (column) column.cards.push(card);
+      }),
+
+    moveCard: (fromCol, toCol, cardId) =>
+      set((state) => {
+        const source = state.columns.find((c) => c.id === fromCol);
+        const target = state.columns.find((c) => c.id === toCol);
+        if (!source || !target) return;
+
+        const cardIndex = source.cards.findIndex((c) => c.id === cardId);
+        if (cardIndex === -1) return;
+
+        const [card] = source.cards.splice(cardIndex, 1);
+        target.cards.push(card);
+      }),
+
+    updateCard: (columnId, cardId, updates) =>
+      set((state) => {
+        const column = state.columns.find((c) => c.id === columnId);
+        const card = column?.cards.find((c) => c.id === cardId);
+        if (card) Object.assign(card, updates);
+      }),
+
+    removeCard: (columnId, cardId) =>
+      set((state) => {
+        const column = state.columns.find((c) => c.id === columnId);
+        if (column) {
+          column.cards = column.cards.filter((c) => c.id !== cardId);
+        }
+      }),
+  }))
+);
+```
+
+## Details
+
+**Without Immer (comparison):** The `moveCard` action without Immer:
+
+```typescript
+moveCard: (fromCol, toCol, cardId) =>
+  set((state) => ({
+    columns: state.columns.map((col) => {
+      if (col.id === fromCol) {
+        return { ...col, cards: col.cards.filter((c) => c.id !== cardId) };
+      }
+      if (col.id === toCol) {
+        const card = state.columns.find((c) => c.id === fromCol)!.cards.find((c) => c.id === cardId)!;
+        return { ...col, cards: [...col.cards, card] };
+      }
+      return col;
+    }),
+  })),
+```
+
+**Middleware stacking with Immer:**
+
+```typescript
+create<Store>()(
+  devtools(
+    persist(
+      immer((set) => ({
+        /* ... */
+      })),
+      { name: 'key' }
+    ),
+    { name: 'Store' }
+  )
+);
+// Order: devtools(persist(immer(...)))
+```
+
+**Immer rules:**
+
+- Either mutate state OR return a new value — never both
+- Do not destructure state at the top level (`const { items } = state; items.push(x)` — this works but is confusing; prefer `state.items.push(x)`)
+- Immer cannot track mutations to `Map`, `Set`, or `Date` objects unless you enable MapSet plugin
+- Immer adds ~5KB to the bundle — only use it when the readability benefit justifies it
+
+**When NOT to use Immer:** For flat state or simple updates (`set({ count: state.count + 1 })`), Immer adds overhead without readability benefit. Use it specifically for nested mutations.
+
+## Source
+
+https://zustand.docs.pmnd.rs/middlewares/immer
+
+## 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.