compound-workflow 1.8.0 → 1.9.1

package/src/.agents/skills/xstate-actor-orchestration/SKILL.md

@@ -1,197 +0,0 @@
----
-name: xstate-actor-orchestration
-description: Implement complex interaction models with XState v5 actor systems, including receptionist-style actor lookup with system IDs, orchestrator/coordinator parent actors, cross-actor messaging, lifecycle management with invoke/spawn, persistence and recovery, runtime inspection, and model-based testing. Use when designing or refactoring state-heavy workflows, async process coordination, retries/timeouts, or multi-actor frontend/backend logic in JavaScript or TypeScript.
----
-
-# XState Actor Orchestration
-
-Execute this workflow to design and implement robust interaction models with XState v5.
-
-## Workflow
-
-1. Model the interaction boundary.
-- Identify external actors (UI, API, queues, timers, humans).
-- Identify internal actors (orchestrator, workers, adapters).
-- Define success, partial success, terminal failure, and compensation behavior.
-
-2. Choose actor topology.
-- Use a root orchestrator actor for cross-step coordination and policy decisions.
-- Use worker actors for isolated tasks (IO, retries, transforms).
-- Use receptionist-style lookup (`systemId` + `system.get`) when actors must be discoverable across branches.
-- Use direct parent-child refs when communication can stay local.
-
-3. Define event contracts before transitions.
-- Create explicit event unions and payload schemas.
-- Use namespaced event types (`checkout.submit`, `payment.authorized`).
-- Plan wildcard routes for orchestration (`payment.*`, `checkout.*`, `*`) with explicit precedence.
-- Keep error events explicit and typed.
-
-4. Compose machine structure before writing actions.
-- Start with nested states to scope events and transitions to relevant regions.
-- Use parallel states when regions are independent and can progress concurrently.
-- Use sequential flow only when one stage must complete before the next starts.
-- Apply tags as stable UI selectors for state intent (`loading`, `error`, `submitting`), not ad-hoc booleans.
-
-5. Implement with typed machine setup.
-- Use `setup({...}).createMachine(...)`.
-- Prefer named actions/guards/actors over inline logic.
-- Use `invoke` for state-scoped lifetimes and `spawn`/`spawnChild` for dynamic long-lived workers.
-- Use `emit(...)` for imperative out-of-band notifications when a fire-and-forget signal is needed.
-
-6. Add reliability policy.
-- Model retries, backoff, and circuit-breaker behavior as explicit states.
-- Persist snapshots for restart/resume flows when required.
-- Model idempotency boundaries for side effects.
-
-7. Add observability.
-- Attach `inspect` at root actor creation for runtime traces.
-- Emit domain-level telemetry from actions, not from random call sites.
-
-8. Prove behavior.
-- Add unit tests for guards/actions and transition paths.
-- Add model/path-based coverage for critical flows.
-- Verify timeout, cancellation, and recovery paths.
-
-9. Produce statechart review artifact and sign-off package.
-- For every proposed or updated machine, generate a Mermaid statechart artifact.
-- Store artifacts under `assets/statecharts/`.
-- Treat the diagram as required for review discussion and final sign-off.
-- Record review notes and approval in a paired sign-off file.
-- Add or update the artifact at the current workflow phase:
-- Brainstorm: create a draft diagram for option discussion.
-- Implementation plan: refine the diagram into the proposed target design.
-- Implementation/delivery: finalize the as-built diagram and complete sign-off.
-
-## Pattern Selection
-
-Use the references selectively:
-- Start with [references/source-map.md](references/source-map.md) to pick source docs.
-- Use [references/actor-system-patterns.md](references/actor-system-patterns.md) for receptionist/orchestrator structures.
-- Use [references/event-contracts.md](references/event-contracts.md) before coding transitions.
-- Use [references/functional-domain-patterns.md](references/functional-domain-patterns.md) for pure transforms and early-return style.
-- Use [references/machine-structure-and-tags.md](references/machine-structure-and-tags.md) for nested/parallel composition and tags.
-- Use [references/react-container-pattern.md](references/react-container-pattern.md) for React integration with containers and pure components.
-- Use [references/reliability-observability.md](references/reliability-observability.md) for persistence/inspection/retry policy.
-- Use [references/testing-strategy.md](references/testing-strategy.md) for verification.
-- Use [references/statechart-review-and-signoff.md](references/statechart-review-and-signoff.md) for required Mermaid artifact workflow.
-- Use [references/skill-validation.md](references/skill-validation.md) to validate skill quality without Python tooling.
-
-## Implementation Rules
-
-- Keep orchestrator context small and policy-focused.
-- Keep domain/entity object transformations in pure functions or dedicated modules, not large inline action bodies.
-- Use immutable transforms (`input -> output`) that are directly unit-testable.
-- Use early returns in actions/guards/transforms instead of deep nested `if/else` trees.
-- Never model machine control flow with booleans; represent control flow with states, substates, and tags.
-- Do not send untyped catch-all events (`{ type: 'ERROR', data: any }`).
-- Route by event namespace first, then by event detail.
-- Keep wildcard transitions as fallback, not primary business routing.
-- Prefer one-way responsibilities: orchestrator decides; workers execute; adapters translate external systems.
-- In React, use container components as controllers that bind actor refs/selectors to presentational components.
-- Keep presentational components pure; they receive props and render only.
-- Use `useSelector` to read actor snapshot/state/context in containers.
-- Use `useEffect` to subscribe to emitted actor events for fire-and-forget UI effects (toasts, navigation, analytics).
-- Do not complete machine review without a Mermaid statechart and a sign-off record.
-
-## Validation (No Python Required)
-
-Run:
-
-```bash
-./scripts/validate-skill.sh .
-```
-
-Validate before proposing completion:
-- Frontmatter includes only `name` and `description`.
-- `name` matches folder naming rules.
-- `agents/openai.yaml` includes a `default_prompt` mentioning `$<skill-name>`.
-- No unresolved TODO placeholders remain.
-- Local references linked from `SKILL.md` exist.
-- `assets/statecharts/` exists for diagram artifacts.
-
-Generate a new artifact bundle:
-
-```bash
-./scripts/create-statechart-artifact.sh . <machine-name> [timestamp] [DRAFT|PLANNED|APPROVED]
-```
-
-## Minimal Starter Skeleton
-
-```ts
-import { setup, assign, sendTo, fromPromise } from 'xstate';
-
-type FlowEvent =
-  | { type: 'flow.start'; input: { orderId: string } }
-  | { type: 'payment.ok'; txnId: string }
-  | { type: 'payment.fail'; reason: string }
-  | { type: 'flow.cancel' };
-
-interface FlowContext {
-  orderId?: string;
-  txnId?: string;
-  error?: string;
-}
-
-const paymentLogic = fromPromise(async ({ input }: { input: { orderId: string } }) => {
-  return { txnId: `txn-${input.orderId}` };
-});
-
-export const flowMachine = setup({
-  types: {
-    context: {} as FlowContext,
-    events: {} as FlowEvent,
-  },
-  actors: {
-    paymentLogic,
-  },
-  actions: {
-    captureInput: assign(({ event }) =>
-      event.type === 'flow.start' ? { orderId: event.input.orderId } : {}
-    ),
-    setError: assign(({ event }) =>
-      event.type === 'payment.fail' ? { error: event.reason } : {}
-    ),
-    notifyWorker: sendTo('payment-worker', ({ context }) => ({
-      type: 'run',
-      orderId: context.orderId,
-    })),
-  },
-}).createMachine({
-  id: 'flow.orchestrator',
-  initial: 'idle',
-  context: {},
-  states: {
-    idle: {
-      on: {
-        'flow.start': {
-          target: 'authorizing',
-          actions: 'captureInput',
-        },
-      },
-    },
-    authorizing: {
-      invoke: {
-        id: 'payment-worker',
-        src: 'paymentLogic',
-        input: ({ context }) => ({ orderId: context.orderId! }),
-        onDone: {
-          target: 'done',
-          actions: assign(({ event }) => ({ txnId: event.output.txnId })),
-        },
-        onError: {
-          target: 'failed',
-          actions: assign(({ event }) => ({ error: String(event.error) })),
-        },
-      },
-      on: {
-        'flow.cancel': 'cancelled',
-      },
-    },
-    done: { type: 'final' },
-    failed: {},
-    cancelled: {},
-  },
-});
-```
-
-Adapt the skeleton to domain events and actor topology; keep contracts and state semantics explicit.

package/src/.agents/skills/xstate-actor-orchestration/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "XState Actor Orchestration"
-  short_description: "Design and implement advanced XState actor systems"
-  default_prompt: "Use $xstate-actor-orchestration to model and implement this interaction flow with receptionist and orchestrator actor patterns."

package/src/.agents/skills/xstate-actor-orchestration/references/actor-system-patterns.md

@@ -1,71 +0,0 @@
-# Actor System Patterns
-
-## 1. Orchestrator pattern
-
-Use one actor as the policy owner for a workflow.
-
-Responsibilities:
-- Accept domain commands/events.
-- Start/stop workers.
-- Enforce timeout/retry/cancel policy.
-- Translate worker outcomes into business states.
-
-Do not put IO logic directly in orchestrator actions unless trivial.
-
-## 2. Receptionist pattern in XState terms
-
-In XState v5, this is implemented through actor-system registration and lookup:
-- Register actors with `systemId`.
-- Resolve actors via `system.get(systemId)` when direct refs are unavailable.
-
-Use this when actors in different branches need late-bound communication.
-
-## 3. Topology decision table
-
-- Parent-child only:
-- Use when communication is local and lifetime is tightly coupled.
-- Receptionist lookup:
-- Use when actor discovery must cross hierarchy boundaries.
-- Event bus adapter actor:
-- Use when integration requires protocol translation or fan-out.
-
-## 4. Lifecycle guidance
-
-- `invoke`:
-- Prefer for state-bound tasks that should stop when exiting a state.
-- `spawn`/`spawnChild`:
-- Prefer for dynamic or longer-lived workers.
-- Root actor:
-- Own system-wide inspection and persistence boundaries.
-
-## 5. Minimal receptionist example
-
-```ts
-import { createMachine, createActor, sendTo } from 'xstate';
-
-const workerMachine = createMachine({
-  id: 'worker',
-  initial: 'idle',
-  states: { idle: {} },
-});
-
-const rootMachine = createMachine({
-  entry: ({ spawnChild }) => {
-    spawnChild(workerMachine, {
-      id: 'worker-local',
-      systemId: 'worker.service',
-    });
-  },
-  on: {
-    'task.dispatch': {
-      actions: sendTo(({ system }) => system.get('worker.service')!, {
-        type: 'task.run',
-      }),
-    },
-  },
-});
-
-createActor(rootMachine).start();
-```
-
-Guard against missing registrations before `sendTo`.

package/src/.agents/skills/xstate-actor-orchestration/references/event-contracts.md

@@ -1,73 +0,0 @@
-# Event Contract Rules
-
-## Event naming
-
-Use namespaced, domain-specific names:
-- `checkout.submit`
-- `payment.authorized`
-- `payment.declined`
-- `fulfillment.timeout`
-
-Avoid generic names unless they are machine-internal and local.
-
-Use consistent namespace depth per bounded context:
-- `<domain>.<action>` for simple flows (`cart.add`).
-- `<domain>.<subdomain>.<action>` for larger systems (`checkout.payment.authorize`).
-
-## Event typing
-
-Define discriminated unions and keep payloads explicit.
-
-```ts
-type CheckoutEvent =
-  | { type: 'checkout.submit'; cartId: string }
-  | { type: 'payment.authorized'; txnId: string }
-  | { type: 'payment.declined'; code: string; reason: string }
-  | { type: 'checkout.cancel' };
-```
-
-For wildcard routing, declare namespace fallback variants in machine transitions and keep explicit types for domain events.
-
-## Command vs fact
-
-- Command events request behavior (`checkout.submit`).
-- Fact events report outcomes (`payment.authorized`).
-
-Keep this distinction explicit to simplify orchestration.
-
-## Wildcard routing patterns
-
-Use wildcard transitions for orchestration and fallback handling:
-- `payment.*` to handle payment namespace events.
-- `checkout.*` to route checkout namespace events.
-- `*` as global fallback.
-
-Use exact matches for business-critical transitions and wildcard matches for coarse routing.
-Exact transitions take precedence over wildcard transitions.
-
-Example:
-
-```ts
-createMachine({
-  on: {
-    'checkout.submit': { target: '.submitting' },
-    'checkout.*': { actions: 'trackCheckoutNamespaceEvent' },
-    'payment.*': { actions: 'routePaymentNamespaceEvent' },
-    '*': { actions: 'trackUnhandledEvent' },
-  },
-});
-```
-
-Avoid putting domain success logic exclusively behind wildcard handlers.
-
-## Error contract
-
-Model expected business errors as typed events/states.
-Use unexpected errors for fault handling paths.
-
-## Versioning
-
-When an event contract changes:
-1. Add new event variant.
-2. Support both versions temporarily in adapters.
-3. Remove old variant after migration.

package/src/.agents/skills/xstate-actor-orchestration/references/functional-domain-patterns.md

@@ -1,53 +0,0 @@
-# Functional Domain and Entity Transform Patterns
-
-Use these rules for domain/entity object transformation code used by machines.
-
-## Core rules
-
-1. Keep transforms pure.
-- Accept input data and return next data.
-- Do not mutate input objects.
-- Do not perform IO in transforms.
-
-2. Keep transforms outside machine config where possible.
-- Prefer `domain/` or `entities/` modules for reusable transform logic.
-- Keep actions/guards small and orchestration-focused.
-
-3. Prefer immutable updates.
-- Return new objects/arrays.
-- Keep output shape predictable and typed.
-
-4. Prefer early returns over nested `if/else`.
-- Exit quickly for invalid or terminal branches.
-- Keep the main success path linear.
-
-## Example
-
-```ts
-type Payment = { amount: number; currency: string; status: 'new' | 'authorized' };
-
-export function authorizePayment(payment: Payment, limit: number): Payment {
-  if (payment.amount <= 0) return payment;
-  if (payment.amount > limit) return payment;
-  if (payment.status === 'authorized') return payment;
-
-  return {
-    ...payment,
-    status: 'authorized',
-  };
-}
-```
-
-## Machine integration pattern
-
-- Use machine actions to call pure transforms.
-- Keep action code thin:
-- Read current context.
-- Call pure transform.
-- Assign returned value.
-
-## Testing expectations
-
-- Unit test transform modules directly without actor runtime.
-- Cover edge conditions first.
-- Keep golden-path and failure-path tests explicit.

package/src/.agents/skills/xstate-actor-orchestration/references/machine-structure-and-tags.md

@@ -1,36 +0,0 @@
-# Machine Structure and Tags
-
-Use structure as the primary control-flow model.
-
-## 1. Scope with nested states
-
-- Use parent/child states to limit where events are handled.
-- Keep transitions local to the smallest valid scope.
-- Move shared transitions to parent states when behavior is intentionally shared.
-
-## 2. Choose parallel vs sequential intentionally
-
-- Use parallel states when regions are independent and can progress concurrently.
-- Use sequential states when one stage must complete before another can start.
-- Do not force sequential flow for unrelated concerns.
-
-## 3. Model flow with states, not booleans
-
-- Do not use boolean flags to represent machine mode (`isLoading`, `isSaving`, `hasError`).
-- Represent each mode with explicit states/substates and tags.
-- Keep booleans only for raw domain facts that do not encode control flow.
-
-## 4. Use tags for declarative UI state selection
-
-- Add tags for stable UI concerns (e.g., `busy`, `error`, `success`, `canRetry`).
-- In React, derive render behavior from `snapshot.hasTag(...)` and selectors.
-- Keep tags semantic and durable across refactors.
-
-## 5. Namespace-aware routing strategy
-
-- Prefer exact event transitions for business-critical behavior.
-- Add namespace wildcards for orchestration routing:
-- `billing.*`
-- `checkout.*`
-- `*` fallback
-- Keep wildcard handlers observability-focused unless intentionally routing.

package/src/.agents/skills/xstate-actor-orchestration/references/react-container-pattern.md

@@ -1,45 +0,0 @@
-# React Container Pattern for XState
-
-Use containers as controllers and components as pure render units.
-
-## 1. Container responsibilities
-
-- Create or receive actor refs.
-- Read state/context via `useSelector`.
-- Map selected values into stable component props.
-- Wire event handlers that send events to actors.
-
-## 2. Presentational component responsibilities
-
-- Receive props only.
-- Render UI only.
-- Avoid actor imports and machine knowledge.
-
-## 3. `useSelector` guidance
-
-- Prefer narrow selectors to limit rerenders.
-- Select tags and derived values, not whole snapshots.
-- Keep selectors deterministic and side-effect free.
-
-## 4. `emit` + `useEffect` for fire-and-forget UI actions
-
-- Use machine `emit(...)` to publish imperative signals (toast, navigation, analytics).
-- Subscribe in container `useEffect`.
-- Trigger UI side effects from emitted events, not from render paths.
-
-Example pattern:
-
-```ts
-useEffect(() => {
-  const sub = actorRef.on('ui.toast', (event) => {
-    toast(event.message);
-  });
-  return () => sub.unsubscribe();
-}, [actorRef]);
-```
-
-## 5. Composition guidance
-
-- Container composes presentational components from selected state/context.
-- Keep props cohesive; avoid passing entire context objects by default.
-- Compose feature UI from multiple containers if actor boundaries differ.

package/src/.agents/skills/xstate-actor-orchestration/references/reliability-observability.md

@@ -1,39 +0,0 @@
-# Reliability and Observability
-
-## Retry and timeout policy
-
-Represent policy as states, not hidden timers.
-
-Common structure:
-- `working`
-- `retry_wait`
-- `failed_transient`
-- `failed_terminal`
-
-Track attempt counts in context and cap retries.
-
-## Persistence
-
-Use persisted snapshots for resumable workflows:
-- Capture via `actor.getPersistedSnapshot()`.
-- Restore via `createActor(logic, { snapshot })`.
-
-Use persistence when workflows must survive reload/restart.
-
-## Inspection
-
-Attach an inspector at root actor creation.
-Listen for:
-- `@xstate.actor`
-- `@xstate.event`
-- `@xstate.snapshot`
-- `@xstate.microstep`
-
-Use inspection for diagnostics and test assertions, not business decisions.
-
-## Recovery design checklist
-
-1. Can the same external side effect run twice safely?
-2. Which state is safe to restore into?
-3. What event can resume the workflow after restart?
-4. Which failures are user-recoverable vs terminal?

package/src/.agents/skills/xstate-actor-orchestration/references/skill-validation.md

@@ -1,33 +0,0 @@
-# Skill Validation Without Python
-
-Use this checklist when Python-based validation tooling is unavailable or undesired.
-
-## Command
-
-Run the shell validator from the skill root:
-
-```bash
-./scripts/validate-skill.sh .
-```
-
-## What the shell validator checks
-
-1. `SKILL.md` exists and has valid frontmatter delimiters.
-2. Frontmatter contains only `name` and `description`.
-3. `name` follows skill naming constraints (`[a-z0-9-]`, max 64 chars).
-4. Skill folder name matches frontmatter `name`.
-5. `agents/openai.yaml` exists.
-6. `default_prompt` exists and mentions `$<skill-name>`.
-7. `assets/statecharts/` exists for Mermaid artifacts.
-8. `scripts/create-statechart-artifact.sh` exists and is executable.
-9. No unresolved TODO placeholders remain in checked files.
-10. Every local `references/*.md` link in `SKILL.md` points to an existing file.
-
-## Additional manual checks
-
-1. Confirm `description` includes clear trigger contexts.
-2. Confirm workflow steps are imperative and actionable.
-3. Confirm references stay one level deep from `SKILL.md`.
-4. Confirm examples reflect XState v5 APIs used by your codebase.
-5. Confirm each proposed/updated machine includes a `.mmd` diagram and `.signoff.md` record.
-6. Confirm sign-off status advances by workflow phase (`DRAFT` -> `PLANNED` -> `APPROVED`).

package/src/.agents/skills/xstate-actor-orchestration/references/source-map.md

@@ -1,44 +0,0 @@
-# Source Map
-
-Use these sources in order, loading only what the task needs.
-
-## Core docs (Mintlify set provided by user)
-
-- Introduction: https://statelyai-xstate.mintlify.app/introduction
-- Actors: https://statelyai-xstate.mintlify.app/concepts/actors
-- Actions: https://statelyai-xstate.mintlify.app/guides/actions
-- Error handling: https://statelyai-xstate.mintlify.app/guides/error-handling
-- Transitions: https://statelyai-xstate.mintlify.app/concepts/transitions
-- Hierarchical composition: https://statelyai-xstate.mintlify.app/guides/parent-child
-- Parallel states: https://statelyai-xstate.mintlify.app/guides/parallel-states
-- TypeScript: https://statelyai-xstate.mintlify.app/advanced/typescript
-- Visualization: https://statelyai-xstate.mintlify.app/advanced/visualization
-- Inspection: https://statelyai-xstate.mintlify.app/advanced/inspection
-- Testing: https://statelyai-xstate.mintlify.app/advanced/testing
-
-## Supplemental official docs (needed for receptionist/system patterns)
-
-- System (actor registration and lookup): https://stately.ai/docs/system
-- Invoke: https://stately.ai/docs/invoke
-- Spawn: https://stately.ai/docs/spawn
-- Transitions (wildcards): https://stately.ai/docs/transitions#wildcard-transitions
-- Parent states: https://stately.ai/docs/parent-states
-- Parallel states: https://stately.ai/docs/parallel-states
-- Tags: https://stately.ai/docs/tags
-- Event emitter (`emit`): https://stately.ai/docs/event-emitter
-- React integration (`@xstate/react`, `useSelector`): https://stately.ai/docs/xstate-react
-- Visualization: https://stately.ai/docs/visualization
-- Persistence: https://stately.ai/docs/persistence
-- Graph/path testing: https://stately.ai/docs/graph
-- Migration notes: https://stately.ai/docs/migration
-
-## Pattern context
-
-- XState v5 launch article (mentions receptionist pattern and actor-system direction):
-  https://stately.ai/blog/2023-12-01-xstate-v5
-
-## Loading guidance
-
-1. Load only one section at a time based on current task.
-2. Prefer API and concept docs over blog content for implementation details.
-3. Use blog content for rationale and pattern naming only.

package/src/.agents/skills/xstate-actor-orchestration/references/statechart-review-and-signoff.md

@@ -1,59 +0,0 @@
-# Statechart Review and Sign-Off
-
-Use this process for every new machine proposal and every machine update.
-
-This artifact is part of the compound workflow. Produce or update it in every phase, not only at the end.
-
-## Required artifact bundle
-
-For each machine change, create both files under `assets/statecharts/`:
-- `<machine-name>-<timestamp>.mmd`
-- `<machine-name>-<timestamp>.signoff.md`
-
-Generate with:
-
-```bash
-./scripts/create-statechart-artifact.sh . <machine-name>
-```
-
-## Mermaid diagram requirements
-
-Represent:
-- Top-level states and nested states.
-- Parallel regions where applicable.
-- Key transitions, including wildcard routing (`domain.*`, `*`) when used.
-- Terminal states and cancellation/failure paths.
-- Tags that UI depends on (capture in sign-off notes if diagram labels become noisy).
-
-## Review discussion checklist
-
-1. Are scopes correct (events handled only where valid)?
-2. Are parallel states used only for independent regions?
-3. Are wildcard transitions fallback-oriented and not hiding core business flow?
-4. Are retry/recovery states explicit?
-5. Are UI-relevant tags represented and consistent with component selectors?
-6. Are emitted imperative events (`emit`) intentional and documented?
-
-## Phase-aware usage
-
-1. Brainstorm phase
-- Produce a draft `.mmd` artifact to compare options.
-- Mark sign-off status as `DRAFT`.
-
-2. Implementation-plan phase
-- Update the same artifact line to the planned machine structure.
-- Mark sign-off status as `PLANNED`.
-- Capture unresolved decisions in review notes.
-
-3. Implementation/delivery phase
-- Update artifact to as-built machine behavior.
-- Mark sign-off status as `APPROVED` when reviewed.
-- Treat missing final artifact/sign-off as incomplete delivery.
-
-## Final sign-off checklist
-
-1. Diagram reflects current machine implementation.
-2. Event namespace and wildcard behavior are reviewed.
-3. Failure/cancel/recovery paths are reviewed.
-4. Reviewer and date are recorded in `.signoff.md`.
-5. Implementation is not marked complete until sign-off is present.