@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/tanstack-prefetching/SKILL.md

@@ -0,0 +1,106 @@
+# TanStack Query: Prefetching and SSR
+
+> Hydrate the client cache from server-fetched data using dehydrate/hydrate and HydrationBoundary
+
+## When to Use
+
+- Eliminating loading spinners by pre-populating the cache with server-fetched data
+- Integrating TanStack Query with Next.js App Router Server Components
+- Prefetching data on hover before a user navigates to a page
+- Passing server-rendered data to client-side queries without a separate API round-trip
+
+## Instructions
+
+1. In Next.js App Router, create a `QueryClient` in the Server Component and prefetch data with `queryClient.prefetchQuery()`.
+2. Pass the dehydrated state to a `<HydrationBoundary>` component — it hydrates the client-side `QueryClient` automatically.
+3. Use `dehydrate(queryClient)` from `@tanstack/react-query` to serialize the cache for transport to the client.
+4. In Client Components, call `useQuery()` with the same key used during prefetch — the data is available immediately with no loading state.
+5. Use `queryClient.prefetchQuery()` (not `ensureQueryData`) when you do not need the return value — it avoids an extra await.
+6. Prefetch on hover using `queryClient.prefetchQuery()` in a `onMouseEnter` handler to warm the cache before navigation.
+7. Set `staleTime` to match your revalidation window — data prefetched at render time should not immediately re-fetch on mount.
+
+```typescript
+// app/posts/page.tsx — Server Component with prefetch
+import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
+import { postListOptions } from '@/queries/posts';
+import { PostList } from './post-list';
+
+export default async function PostsPage() {
+  const queryClient = new QueryClient();
+
+  // Prefetch on the server — data is fetched once, not per-component
+  await queryClient.prefetchQuery(postListOptions({}));
+
+  return (
+    // Injects dehydrated cache into the page
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <PostList />
+    </HydrationBoundary>
+  );
+}
+
+// app/posts/post-list.tsx — Client Component, no loading state
+'use client';
+import { useQuery } from '@tanstack/react-query';
+import { postListOptions } from '@/queries/posts';
+
+export function PostList() {
+  // Data is immediately available — cache was hydrated from server
+  const { data: posts } = useQuery(postListOptions({}));
+  return <ul>{posts?.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
+}
+
+// Prefetch on hover — warm cache before navigation
+function PostLink({ id }: { id: string }) {
+  const queryClient = useQueryClient();
+  return (
+    <Link
+      href={`/posts/${id}`}
+      onMouseEnter={() => queryClient.prefetchQuery(postDetailOptions(id))}
+    >
+      View Post
+    </Link>
+  );
+}
+```
+
+## Details
+
+TanStack Query's SSR pattern solves the classic problem: server-rendered HTML contains data, but the client-side React Query cache is empty on mount, causing a flash of loading state as queries re-execute.
+
+**Dehydration/hydration mechanism:** `dehydrate(queryClient)` serializes successful query results into a plain JSON-serializable object. `<HydrationBoundary state={dehydratedState}>` deserializes it into the client's `QueryClient` on mount. The client queries then find their data already in cache and skip the initial fetch.
+
+**`staleTime` is critical for SSR:** Without `staleTime`, TanStack Query considers all queries stale immediately on mount and triggers background refetches — wasting the server prefetch. Set `staleTime` to at least as long as the server render takes (e.g., `Infinity` for fully static data, or a few minutes for semi-fresh data).
+
+**New QueryClient per request:** In Server Components, create a `new QueryClient()` per page render, not a shared singleton. A singleton would leak data between user requests in a server-side Node.js process.
+
+**Multiple prefetches:** Prefetch all queries needed by a page segment at once using `Promise.all`:
+
+```typescript
+await Promise.all([
+  queryClient.prefetchQuery(postListOptions({})),
+  queryClient.prefetchQuery(categoriesOptions()),
+]);
+```
+
+**Router-level prefetch:** For non-Next.js apps, TanStack Router has built-in prefetch integration via `loader` functions that call `ensureQueryData`. This achieves the same effect without manual `dehydrate/hydrate` wiring.
+
+## Source
+
+https://tanstack.com/query/latest/docs/framework/react/guides/prefetching
+
+## 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/tanstack-prefetching/skill.yaml

@@ -0,0 +1,44 @@
+name: tanstack-prefetching
+version: "1.0.0"
+description: prefetchQuery, dehydrate/hydrate, SSR with Next.js, and router-level prefetch
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/queries/**"
+  - "**/queryClient.ts"
+  - "**/query-client.ts"
+  - "**/*query*.ts"
+related_skills:
+  - next-data-fetching
+  - next-caching-strategies
+  - tanstack-cache-management
+  - tanstack-query-keys
+stack_signals:
+  - tanstack-query
+  - react
+  - typescript
+keywords:
+  - prefetch
+  - dehydrate
+  - hydrate
+  - SSR
+  - HydrationBoundary
+  - server-prefetch
+  - initial-data
+metadata:
+  author: community
+  upstream: https://tanstack.com/query/latest/docs/framework/react/guides/prefetching
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/tanstack-query-invalidation/SKILL.md

@@ -0,0 +1,95 @@
+# TanStack Query: Query Invalidation
+
+> Control cache freshness with invalidateQueries, staleTime, gcTime, and refetch strategies
+
+## When to Use
+
+- Refreshing data after a mutation without a full page reload
+- Tuning how long cached data is considered fresh before background refetching
+- Controlling when stale queries are garbage collected from memory
+- Deciding between active refetch (immediate) and background refetch (on next mount/focus)
+
+## Instructions
+
+1. Call `queryClient.invalidateQueries({ queryKey })` after mutations to mark related queries as stale and trigger refetch.
+2. Use hierarchical keys for broad invalidation — `{ queryKey: ['posts'] }` invalidates all queries whose key starts with `['posts']`.
+3. Set `refetchType: 'active'` (default) to refetch only currently mounted queries; use `refetchType: 'all'` to refetch mounted and unmounted cached queries; use `refetchType: 'none'` to mark stale without refetching.
+4. Configure `staleTime` in `queryOptions` or globally in `QueryClient` defaults — this is how long data is considered fresh (no background refetch on mount).
+5. Configure `gcTime` (formerly `cacheTime`) to control how long inactive query data stays in memory — defaults to 5 minutes.
+6. Use `queryClient.refetchQueries()` when you want immediate refetch without going through the stale check.
+7. Prefer `invalidateQueries` over `refetchQueries` for post-mutation refresh — invalidation is more composable with `staleTime`.
+
+```typescript
+// Global defaults in QueryClient setup
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute — queries fresh for 60s after fetch
+      gcTime: 5 * 60 * 1000, // 5 minutes — inactive data stays in memory for 5min
+      retry: 2, // retry failed requests twice
+    },
+  },
+});
+
+// Post-mutation invalidation patterns
+function useCreatePost() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: createPost,
+    onSuccess: () => {
+      // Invalidate all post lists — refetches active ones immediately
+      queryClient.invalidateQueries({ queryKey: postKeys.lists() });
+    },
+  });
+}
+
+// Selective invalidation by refetchType
+queryClient.invalidateQueries({
+  queryKey: postKeys.lists(),
+  refetchType: 'active', // only refetch if component is currently mounted
+});
+
+// Targeted invalidation — only invalidate a specific detail
+queryClient.invalidateQueries({
+  queryKey: postKeys.detail('abc-123'),
+  exact: true, // match exact key, not prefix
+});
+```
+
+## Details
+
+TanStack Query maintains a lifecycle for each cached query: `fresh` → `stale` → `inactive` → `garbage collected`.
+
+**`staleTime`:** While data is `fresh`, queries do not refetch on component mount or window focus. Once data becomes `stale` (after `staleTime` ms), TanStack Query triggers a background refetch on the next mount or focus event. Default is `0` — data is always stale immediately after fetching.
+
+**`gcTime`:** When a query has no active subscribers (no component mounted that uses it), TanStack Query starts a garbage collection timer. After `gcTime` ms, the cached data is removed. If the query mounts again before GC, it still returns the stale cached data immediately while refetching in the background.
+
+**Invalidation vs refetch timing:**
+
+- `invalidateQueries` with `refetchType: 'active'`: marks stale + immediately refetches mounted queries. Non-mounted queries refetch next time they mount.
+- `invalidateQueries` with `refetchType: 'none'`: marks stale only. Next mount or focus triggers refetch.
+- `refetchQueries`: forces immediate refetch regardless of staleTime.
+
+**`exact: true` vs prefix matching:** Without `exact`, `queryKey: ['posts']` matches `['posts', 'list', {}]`, `['posts', 'detail', '1']`, etc. With `exact: true`, it only matches the exact key `['posts']`. Use prefix matching for broad post-mutation invalidation; use `exact` when only a specific entry should be invalidated.
+
+**Combining staleTime with invalidation:** Setting `staleTime: Infinity` is common for reference data that never changes at runtime (static lists, config). Explicitly invalidate these on admin mutations rather than relying on time-based staleness.
+
+## Source
+
+https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation
+
+## 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/tanstack-query-invalidation/skill.yaml

@@ -0,0 +1,43 @@
+name: tanstack-query-invalidation
+version: "1.0.0"
+description: invalidateQueries, refetchType, staleTime, and gcTime tuning
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/queries/**"
+  - "**/queryClient.ts"
+  - "**/query-client.ts"
+  - "**/*query*.ts"
+related_skills:
+  - tanstack-query-keys
+  - tanstack-mutation-patterns
+  - tanstack-cache-management
+  - next-caching-strategies
+stack_signals:
+  - tanstack-query
+  - react
+  - typescript
+keywords:
+  - invalidate
+  - staleTime
+  - gcTime
+  - refetchType
+  - background-refetch
+  - cache-freshness
+metadata:
+  author: community
+  upstream: https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/tanstack-query-keys/SKILL.md

@@ -0,0 +1,94 @@
+# TanStack Query: Query Keys
+
+> Structure query keys as type-safe factories to enable precise cache invalidation and scoped refetching
+
+## When to Use
+
+- Designing the query key structure for a new feature or data domain
+- Implementing cache invalidation after mutations that affects a subset of cached queries
+- Standardizing key shape across a team to avoid cache collisions
+- Co-locating query functions with their keys to prevent drift between key shape and fetcher arguments
+- Debugging cache misses caused by key shape mismatches
+
+## Instructions
+
+1. Define query keys as arrays, never as strings — arrays allow hierarchical matching during invalidation.
+2. Create a query key factory object per domain (entity type) that returns typed arrays.
+3. Co-locate the key factory with the query function in a `queries/posts.ts` file — keys and fetchers evolve together.
+4. Use hierarchical keys: `['posts']` → `['posts', 'list']` → `['posts', 'list', { status: 'published' }]` — invalidating `['posts']` invalidates all descendants.
+5. Include all variables that affect the fetched data in the key — different arguments must produce different keys.
+6. Avoid putting unstable references (functions, class instances) in keys — keys are serialized for comparison.
+7. Use the `queryOptions()` helper from TanStack Query v5 to bundle key and fetcher into one object.
+
+```typescript
+// queries/posts.ts — query key factory pattern
+import { queryOptions } from '@tanstack/react-query';
+
+export const postKeys = {
+  all: ['posts'] as const,
+  lists: () => [...postKeys.all, 'list'] as const,
+  list: (filters: PostFilters) => [...postKeys.lists(), filters] as const,
+  details: () => [...postKeys.all, 'detail'] as const,
+  detail: (id: string) => [...postKeys.details(), id] as const,
+};
+
+// Bundled options using queryOptions() helper (TanStack Query v5)
+export const postListOptions = (filters: PostFilters) =>
+  queryOptions({
+    queryKey: postKeys.list(filters),
+    queryFn: () => fetchPosts(filters),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  });
+
+export const postDetailOptions = (id: string) =>
+  queryOptions({
+    queryKey: postKeys.detail(id),
+    queryFn: () => fetchPost(id),
+  });
+
+// components/post-list.tsx — consuming the options
+import { useQuery } from '@tanstack/react-query';
+import { postListOptions } from '@/queries/posts';
+
+function PostList({ filters }: { filters: PostFilters }) {
+  const { data } = useQuery(postListOptions(filters));
+  return <ul>{data?.map(p => <li key={p.id}>{p.title}</li>)}</ul>;
+}
+
+// After creating a post — invalidate only the list scope
+queryClient.invalidateQueries({ queryKey: postKeys.lists() });
+```
+
+## Details
+
+Query keys are the foundation of TanStack Query's cache — every cached value is keyed by its query key. Getting the key structure right from the start prevents a class of bugs where mutations do not properly invalidate related queries.
+
+**Hierarchical invalidation:** `invalidateQueries({ queryKey: ['posts'] })` invalidates every query whose key starts with `['posts']` — lists, details, filtered views. This is the primary mechanism for "refresh everything related to posts after a mutation."
+
+**Key serialization:** TanStack Query serializes keys for comparison using a deep-equality algorithm. Object keys are compared by value, not reference. `{ status: 'published' }` and `{ status: 'published' }` (different object references) produce the same cache entry.
+
+**`queryOptions()` in v5:** The `queryOptions()` helper was introduced in TanStack Query v5 to improve TypeScript type inference and co-location. Pass the result directly to `useQuery`, `prefetchQuery`, `ensureQueryData`, and `queryClient.fetchQuery` — all accept the same shape. This eliminates key drift between components and cache management code.
+
+**Co-location principle:** When a fetcher function's arguments change, the key must change too — or the cache returns stale data with wrong parameters. Co-locating them in the same file (and ideally the same `queryOptions` call) makes this relationship impossible to miss.
+
+**Stale vs invalid:** A query becomes `stale` after `staleTime` — it will refetch on next mount or focus. An `invalid` query refetches immediately (in the background) regardless of staleTime. `invalidateQueries` marks queries invalid; `staleTime` controls the automatic staleness lifecycle.
+
+## Source
+
+https://tanstack.com/query/latest/docs/framework/react/guides/query-keys
+
+## 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/tanstack-query-keys/skill.yaml

@@ -0,0 +1,43 @@
+name: tanstack-query-keys
+version: "1.0.0"
+description: Query key factories, key hierarchies, colocated keys, and invalidation scope
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/queries/**"
+  - "**/queryClient.ts"
+  - "**/query-client.ts"
+  - "**/*query*.ts"
+related_skills:
+  - tanstack-query-invalidation
+  - tanstack-cache-management
+  - tanstack-mutation-patterns
+  - react-hooks-pattern
+stack_signals:
+  - tanstack-query
+  - react
+  - typescript
+keywords:
+  - query-keys
+  - key-factory
+  - key-hierarchy
+  - invalidation
+  - cache-key
+  - colocated-keys
+metadata:
+  author: community
+  upstream: https://tanstack.com/query/latest/docs/framework/react/guides/query-keys
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/tanstack-suspense-mode/SKILL.md

@@ -0,0 +1,96 @@
+# TanStack Query: Suspense Mode
+
+> Use useSuspenseQuery to integrate React's Suspense and error boundaries with TanStack Query
+
+## When to Use
+
+- Building components that should suspend while data loads rather than rendering a loading state inline
+- Integrating TanStack Query with React 18 concurrent features and streaming SSR
+- Eliminating loading state conditionals (`if (isLoading) return <Spinner />`) from components
+- Coordinating multiple loading states with a single parent Suspense boundary
+- Using TanStack Query with Next.js App Router streaming
+
+## Instructions
+
+1. Use `useSuspenseQuery` instead of `useQuery` to opt into suspense mode — the component suspends instead of returning `isLoading`.
+2. Wrap components using `useSuspenseQuery` in a `<Suspense fallback={...}>` boundary — without it, React throws an error.
+3. Use `useSuspenseQueries` (plural) to run multiple suspense queries in parallel — suspends until all resolve.
+4. Pair each `<Suspense>` with an error boundary (`<ErrorBoundary>` from `react-error-boundary`) to handle query errors.
+5. Prefer `useSuspenseQuery` for data that is always needed — use regular `useQuery` for optional or conditional data.
+6. For Next.js, prefetch data in Server Components and hydrate via `<HydrationBoundary>` — the Client Component suspends only if the cache is empty.
+
+```typescript
+// With useSuspenseQuery — no loading conditional needed
+'use client';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { postDetailOptions } from '@/queries/posts';
+
+// This component either renders with data or suspends — never shows partial state
+function PostContent({ id }: { id: string }) {
+  const { data: post } = useSuspenseQuery(postDetailOptions(id));
+  // data is guaranteed to be defined here — TypeScript knows this
+  return <article>{post.content}</article>;
+}
+
+// Wrapping component manages the Suspense/Error boundaries
+import { Suspense } from 'react';
+import { ErrorBoundary } from 'react-error-boundary';
+
+function PostPage({ id }: { id: string }) {
+  return (
+    <ErrorBoundary fallback={<PostError />}>
+      <Suspense fallback={<PostSkeleton />}>
+        <PostContent id={id} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+// Multiple parallel suspense queries — waits for all
+import { useSuspenseQueries } from '@tanstack/react-query';
+
+function PostWithRelated({ id }: { id: string }) {
+  const [{ data: post }, { data: related }] = useSuspenseQueries({
+    queries: [
+      postDetailOptions(id),
+      relatedPostsOptions(id),
+    ],
+  });
+  // Both are defined — component suspends until both resolve
+  return <PostLayout post={post} related={related} />;
+}
+```
+
+## Details
+
+`useSuspenseQuery` changes TanStack Query's data contract: instead of returning `{ data: T | undefined, isLoading, isError }`, it returns `{ data: T }` — data is always defined when the component renders. The component suspends (pauses rendering) until the data is available, and throws errors to the nearest error boundary.
+
+**Type safety improvement:** With regular `useQuery`, `data` is typed as `T | undefined` — requiring null checks everywhere. With `useSuspenseQuery`, `data` is typed as `T` — no null checks needed because the component cannot render without data.
+
+**Suspense boundary placement:** Multiple `useSuspenseQuery` calls in the same component all contribute to the same Suspense boundary. They suspend sequentially (each waits for the previous before starting) unless you use `useSuspenseQueries` which starts all fetches in parallel.
+
+**Sequential vs parallel suspension:** Two `useSuspenseQuery` calls in one component create a waterfall — the second query does not start until the first resolves (because the component re-renders after each suspension). Use `useSuspenseQueries` to start all in parallel.
+
+**Error handling:** `useSuspenseQuery` throws errors to the nearest React error boundary — unlike regular `useQuery` which catches errors internally and returns them as `{ isError, error }`. Always pair `<Suspense>` with an `<ErrorBoundary>` when using suspense mode.
+
+**Next.js App Router:** Suspense queries work naturally with Next.js streaming — the `<Suspense>` boundary streams its fallback first, then streams the resolved content. Combined with server-side prefetching via `<HydrationBoundary>`, the component only suspends on cold cache misses.
+
+## Source
+
+https://tanstack.com/query/latest/docs/framework/react/guides/suspense
+
+## 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/tanstack-suspense-mode/skill.yaml

@@ -0,0 +1,42 @@
+name: tanstack-suspense-mode
+version: "1.0.0"
+description: useSuspenseQuery, error boundaries, streaming, and React 18 integration
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/queries/**"
+  - "**/queryClient.ts"
+  - "**/*query*.ts"
+related_skills:
+  - next-streaming-suspense
+  - tanstack-prefetching
+  - tanstack-query-keys
+  - react-hooks-pattern
+stack_signals:
+  - tanstack-query
+  - react
+  - typescript
+keywords:
+  - useSuspenseQuery
+  - suspense
+  - error-boundary
+  - streaming
+  - concurrent
+  - React18
+metadata:
+  author: community
+  upstream: https://tanstack.com/query/latest/docs/framework/react/guides/suspense
+state:
+  persistent: false
+  files: []
+depends_on: []