@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/xstate-machine-definition/SKILL.md

@@ -0,0 +1,151 @@
+# XState Machine Definition
+
+> Define statecharts with createMachine for explicit states, transitions, context, and events
+
+## When to Use
+
+- Modeling complex UI flows with multiple states (forms, wizards, authentication)
+- Replacing boolean flag soup (`isLoading && !isError && isSubmitted`) with named states
+- Building workflows where illegal state transitions must be prevented
+- Any feature where a state diagram would clarify the logic
+
+## Instructions
+
+1. Define the machine in a `.machine.ts` file. Keep it separate from UI components.
+2. Start with the types: define `Context` (extended state data) and `Events` (a discriminated union of all possible events).
+3. Use `createMachine` with `id`, `initial`, `context`, and `states`. Each state has `on` for transitions.
+4. Name states as nouns or adjectives (`idle`, `loading`, `error`), not verbs.
+5. Name events as past-tense descriptions of what happened (`SUBMITTED`, `LOADED`, `ERRORED`) or imperative commands (`SUBMIT`, `RETRY`).
+6. Use `target` for the destination state. Omit `target` for self-transitions that only run actions.
+7. Keep machines pure — no side effects in the machine definition itself. Use actions and services for effects.
+
+```typescript
+// auth.machine.ts
+import { createMachine, assign } from 'xstate';
+
+interface AuthContext {
+  user: { id: string; name: string } | null;
+  error: string | null;
+  retries: number;
+}
+
+type AuthEvent =
+  | { type: 'LOGIN'; email: string; password: string }
+  | { type: 'LOGOUT' }
+  | { type: 'RETRY' }
+  | { type: 'done.invoke.authenticate'; data: { id: string; name: string } }
+  | { type: 'error.platform.authenticate'; data: Error };
+
+const authMachine = createMachine<AuthContext, AuthEvent>({
+  id: 'auth',
+  initial: 'idle',
+  context: {
+    user: null,
+    error: null,
+    retries: 0,
+  },
+  states: {
+    idle: {
+      on: {
+        LOGIN: 'authenticating',
+      },
+    },
+    authenticating: {
+      invoke: {
+        id: 'authenticate',
+        src: 'authenticateUser',
+        onDone: {
+          target: 'authenticated',
+          actions: assign({ user: (_, event) => event.data, error: null }),
+        },
+        onError: {
+          target: 'error',
+          actions: assign({
+            error: (_, event) => event.data.message,
+            retries: (ctx) => ctx.retries + 1,
+          }),
+        },
+      },
+    },
+    authenticated: {
+      on: {
+        LOGOUT: {
+          target: 'idle',
+          actions: assign({ user: null }),
+        },
+      },
+    },
+    error: {
+      on: {
+        RETRY: {
+          target: 'authenticating',
+          guard: 'canRetry',
+        },
+        LOGIN: 'authenticating',
+      },
+    },
+  },
+});
+
+export { authMachine };
+```
+
+## Details
+
+**Context vs state:** "State" in XState means the finite state node (idle, loading, error). "Context" is the extended state — arbitrary data that travels with the machine. Use finite states for mode/phase, context for data.
+
+**XState v5 changes:** If using XState v5, the API shifts to `setup().createMachine()` with a different structure:
+
+```typescript
+import { setup, assign } from 'xstate';
+
+const machine = setup({
+  types: {} as {
+    context: AuthContext;
+    events: AuthEvent;
+  },
+  guards: { canRetry: ({ context }) => context.retries < 3 },
+  actions: { clearUser: assign({ user: null }) },
+}).createMachine({
+  id: 'auth',
+  initial: 'idle',
+  context: { user: null, error: null, retries: 0 },
+  states: {
+    /* ... */
+  },
+});
+```
+
+**State node types:**
+
+- `atomic` — leaf node, no child states (default)
+- `compound` — has child states (nested)
+- `parallel` — all child states active simultaneously
+- `final` — terminal state, triggers `onDone` in the parent
+- `history` — remembers the last active child state
+
+**Design principles:**
+
+- Every event should be handled in every state, even if the handler is a no-op. Unhandled events are silently ignored, which can mask bugs.
+- Draw the state diagram first, code second. XState machines are visual — use Stately.ai or the VS Code extension.
+- Prefer fewer top-level states with nested substates over many flat states.
+
+## Source
+
+https://stately.ai/docs/machines
+
+## 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/xstate-machine-definition/skill.yaml

@@ -0,0 +1,40 @@
+name: xstate-machine-definition
+version: '1.0.0'
+description: Define statecharts with createMachine for explicit state transitions and context
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.machine.ts'
+  - '**/*.machine.tsx'
+  - '**/machines/**'
+related_skills:
+  - xstate-guards-actions
+  - xstate-invoke-pattern
+  - xstate-react-integration
+stack_signals:
+  - xstate
+  - typescript
+  - react
+keywords:
+  - createMachine
+  - statechart
+  - states
+  - transitions
+  - context
+  - events
+metadata:
+  author: community
+  upstream: 'xstate/docs/machines'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/xstate-parallel-states/SKILL.md

@@ -0,0 +1,130 @@
+# XState Parallel States
+
+> Model concurrent, independent state regions that are active simultaneously within a single machine
+
+## When to Use
+
+- A UI has independent concerns that change independently (e.g., bold AND italic in a text editor)
+- Modeling multiple concurrent processes (upload progress + validation status)
+- Avoiding combinatorial explosion of states when combining orthogonal dimensions
+- A form with independent section-level validation that proceeds in parallel
+
+## Instructions
+
+1. Set `type: 'parallel'` on the parent state node. All direct child states become active simultaneously.
+2. Each child region operates independently — events are processed by all active regions.
+3. Parallel states do not have an `initial` property — all children start in their own `initial` states simultaneously.
+4. Transitions can target states in other regions using the full state ID path.
+5. Use `onDone` on the parallel parent to react when ALL child regions reach their final states.
+6. Keep each parallel region focused on one concern. If regions need heavy coordination, consider using a single compound state instead.
+
+```typescript
+// text-editor.machine.ts
+import { createMachine } from 'xstate';
+
+const textEditorMachine = createMachine({
+  id: 'editor',
+  type: 'parallel',
+  states: {
+    bold: {
+      initial: 'off',
+      states: {
+        off: { on: { TOGGLE_BOLD: 'on' } },
+        on: { on: { TOGGLE_BOLD: 'off' } },
+      },
+    },
+    italic: {
+      initial: 'off',
+      states: {
+        off: { on: { TOGGLE_ITALIC: 'on' } },
+        on: { on: { TOGGLE_ITALIC: 'off' } },
+      },
+    },
+    underline: {
+      initial: 'off',
+      states: {
+        off: { on: { TOGGLE_UNDERLINE: 'on' } },
+        on: { on: { TOGGLE_UNDERLINE: 'off' } },
+      },
+    },
+  },
+});
+
+// State value when bold is on, italic off, underline on:
+// { bold: 'on', italic: 'off', underline: 'on' }
+```
+
+```typescript
+// Multi-step upload with parallel validation
+const uploadMachine = createMachine({
+  id: 'upload',
+  initial: 'preparing',
+  states: {
+    preparing: {
+      on: { START: 'processing' },
+    },
+    processing: {
+      type: 'parallel',
+      states: {
+        upload: {
+          initial: 'uploading',
+          states: {
+            uploading: {
+              invoke: { src: 'uploadFile', onDone: 'done', onError: 'error' },
+            },
+            done: { type: 'final' },
+            error: {},
+          },
+        },
+        validation: {
+          initial: 'validating',
+          states: {
+            validating: {
+              invoke: { src: 'validateFile', onDone: 'done', onError: 'error' },
+            },
+            done: { type: 'final' },
+            error: {},
+          },
+        },
+      },
+      // Fires when BOTH upload and validation reach 'done'
+      onDone: 'complete',
+    },
+    complete: { type: 'final' },
+  },
+});
+```
+
+## Details
+
+**State values:** For parallel states, `state.value` is an object where each key is a region name and each value is that region's current state. For nested parallels, values nest further.
+
+**Event handling:** When an event is received, it is processed by ALL active regions. If both `bold` and `italic` handle `RESET`, both will transition. Be intentional about event naming to avoid unintended cross-region effects.
+
+**onDone completion:** A parallel state's `onDone` fires only when every child region has reached a `final` state. If any region stays active, the parallel state stays active.
+
+**Without parallel states (combinatorial explosion):** Modeling bold + italic + underline without parallel states would require 8 atomic states (off-off-off, on-off-off, ...). With parallel states, you need 6 (2 per region). This scales linearly instead of exponentially.
+
+**Transitions between regions:** A region can target another region's state via a full ID path, but this is generally a code smell. If regions need tight coordination, they may not be truly parallel — consider a compound state instead.
+
+**Testing parallel machines:** Check `state.value` as an object: `expect(state.value).toEqual({ bold: 'on', italic: 'off' })`.
+
+## Source
+
+https://stately.ai/docs/parallel-states
+
+## 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/xstate-parallel-states/skill.yaml

@@ -0,0 +1,39 @@
+name: xstate-parallel-states
+version: '1.0.0'
+description: Model concurrent state regions with parallel state nodes
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.machine.ts'
+  - '**/*.machine.tsx'
+  - '**/machines/**'
+related_skills:
+  - xstate-machine-definition
+  - xstate-guards-actions
+  - xstate-history-states
+stack_signals:
+  - xstate
+  - typescript
+  - react
+keywords:
+  - parallel
+  - concurrent
+  - regions
+  - orthogonal
+  - type-parallel
+metadata:
+  author: community
+  upstream: 'xstate/docs/parallel-states'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/xstate-react-integration/SKILL.md

@@ -0,0 +1,138 @@
+# XState React Integration
+
+> Connect XState machines to React components with useMachine, useActor, and useSelector hooks
+
+## When to Use
+
+- Rendering UI based on the current state of a machine
+- Sending events to a machine from React event handlers
+- Sharing a machine instance across multiple components via context
+- Reading machine context and matching states for conditional rendering
+
+## Instructions
+
+1. Use `useMachine(machine)` to create and interpret a machine instance local to a component.
+2. Destructure `[state, send, actorRef]` from the hook. `state` contains the current state; `send` dispatches events.
+3. Use `state.matches('stateName')` for conditional rendering — never compare `state.value` as a string directly (it can be an object for compound states).
+4. Access machine context via `state.context`.
+5. For shared machines across components, create the actor with `useActorRef` in a parent and pass it down via React context. Children use `useSelector` to read specific state slices.
+6. Use `useSelector` with a comparison function to prevent unnecessary re-renders.
+
+```typescript
+// LoginForm.tsx
+import { useMachine } from '@xstate/react';
+import { authMachine } from './auth.machine';
+
+function LoginForm() {
+  const [state, send] = useMachine(authMachine, {
+    // Provide service implementations
+    services: {
+      authenticateUser: async (ctx, event) => {
+        const res = await fetch('/api/login', {
+          method: 'POST',
+          body: JSON.stringify({ email: event.email, password: event.password }),
+        });
+        if (!res.ok) throw new Error('Invalid credentials');
+        return res.json();
+      },
+    },
+  });
+
+  if (state.matches('authenticated')) {
+    return <div>Welcome, {state.context.user?.name}</div>;
+  }
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const data = new FormData(e.currentTarget);
+        send({ type: 'LOGIN', email: data.get('email') as string, password: data.get('password') as string });
+      }}
+    >
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+      <button disabled={state.matches('authenticating')}>
+        {state.matches('authenticating') ? 'Signing in...' : 'Sign in'}
+      </button>
+      {state.matches('error') && <p>{state.context.error}</p>}
+    </form>
+  );
+}
+```
+
+```typescript
+// Shared machine via React context
+import { createActorContext } from '@xstate/react';
+import { appMachine } from './app.machine';
+
+const AppMachineContext = createActorContext(appMachine);
+
+function App() {
+  return (
+    <AppMachineContext.Provider>
+      <Header />
+      <Content />
+    </AppMachineContext.Provider>
+  );
+}
+
+function Header() {
+  const userName = AppMachineContext.useSelector(
+    (state) => state.context.user?.name
+  );
+  return <header>{userName ?? 'Guest'}</header>;
+}
+```
+
+## Details
+
+**useMachine vs useActorRef:** `useMachine` creates a new actor on mount and re-renders the component on every state change. `useActorRef` creates the actor but does NOT cause re-renders — combine with `useSelector` for surgical updates.
+
+**state.matches deep matching:** For compound states, `state.matches('playing.fastForward')` checks nested states. For parallel states, pass an object: `state.matches({ bold: 'on', italic: 'off' })`.
+
+**useSelector for performance:** Instead of re-rendering on every state change, select only what you need:
+
+```typescript
+const isLoading = AppMachineContext.useSelector((state) => state.matches('loading'));
+// Component only re-renders when isLoading changes
+```
+
+**XState v5 with @xstate/react v4:**
+
+```typescript
+import { useMachine, useActorRef, useSelector } from '@xstate/react';
+
+// useMachine still works the same
+const [snapshot, send] = useMachine(machine);
+
+// snapshot.value, snapshot.context, snapshot.matches() work identically
+```
+
+**Testing components with machines:** Pass a pre-configured machine or use `@xstate/react/lib/test` utilities. Override services to return mock data.
+
+**Common mistakes:**
+
+- Creating a new machine reference on every render (define machines outside components)
+- Using `state.value === 'loading'` instead of `state.matches('loading')` — breaks for compound states
+- Not providing required services to `useMachine` — the machine runs but invocations fail silently
+
+## Source
+
+https://stately.ai/docs/xstate-react
+
+## 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/xstate-react-integration/skill.yaml

@@ -0,0 +1,39 @@
+name: xstate-react-integration
+version: '1.0.0'
+description: Connect XState machines to React components with useMachine and useActor hooks
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.machine.ts'
+  - '**/*.machine.tsx'
+  - '**/machines/**'
+related_skills:
+  - xstate-machine-definition
+  - xstate-actor-pattern
+  - xstate-guards-actions
+stack_signals:
+  - xstate
+  - typescript
+  - react
+keywords:
+  - useMachine
+  - useActor
+  - useSelector
+  - react-integration
+  - state-matching
+metadata:
+  author: community
+  upstream: 'xstate/docs/xstate-react'
+state:
+  persistent: false
+  files: []
+depends_on: []