compound-workflow 0.1.7 → 0.1.9

package/README.md

@@ -131,7 +131,9 @@ Full detail: [src/AGENTS.md](src/AGENTS.md), [src/.agents/commands/](src/.agents
 
 Commands are the public API. Skills and agents are invoked by commands; you don’t call them directly.
 
-- **Workflow skills:** `brainstorming`, `file-todos`, `compound-docs`, `document-review`, `technical-review`, `git-worktree`, `agent-browser`, `process-metrics`.
+- **Workflow skills:** `brainstorming`, `file-todos`, `compound-docs`, `document-review`, `technical-review`, `git-worktree`, `agent-browser`, `process-metrics`, `xstate-actor-orchestration`.
+- **XState orchestration trigger:** Use `xstate-actor-orchestration` when complexity exceeds simple local state—UI container-as-orchestrator flows, backend/internal actor orchestration, receptionist/child-actor patterns, retries/timeouts/cancellation, or boolean-flag sprawl.
+- **Skill-local metadata:** Some skills may include tool-specific metadata under `src/.agents/skills/<skill>/agents/` (for example `openai.yaml`) when required by skill validation/runtime.
 - **Guardrail standards:** `data-foundations`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability` — applied when work touches multi-tenant data, PII, money, or audit.
 - **Agents:** Used by plan, review, and work for research, lint, and validation (e.g. `repo-research-analyst`, `learnings-researcher`, `git-history-analyzer`, `agent-native-reviewer`).
 
@@ -153,7 +155,7 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 **Skills not showing in Cursor?** Cursor discovers skills from (1) the plugin’s `skills/` directory when you load the plugin from this repo, or (2) the project’s `.cursor/skills/` when you use npm: ensure the project has a `.cursor` directory and run `npx compound-workflow install`—Install creates the full structure (`.cursor/skills/<skill>`, `.cursor/agents`, `.cursor/commands`, `.cursor/references`). If skills still don’t appear, check Cursor Settings → Rules and any `permission.skill` settings.
 
-**Skills not showing in OpenCode?** OpenCode uses the `.agents/compound-workflow-skills` symlink and `opencode.json` `skills.paths`. Run Install from the project root (`npx compound-workflow install`).
+**Skills not showing in OpenCode?** OpenCode uses the `.agents/compound-workflow-skills` symlink and `opencode.json` `skills.paths`. Run Install from the project root (`npx compound-workflow install`). The learnings-capture skill is named **compound-docs** (hyphen, plural); **compound_doc** (underscore) is an alias that resolves to the same skill.
 
 ---
 

package/package.json

@@ -1 +1 @@
-{"name":"compound-workflow","version":"0.1.7","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"engines":{"node":">=18"}}
+{"name":"compound-workflow","version":"0.1.9","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"engines":{"node":">=18"}}

package/src/.agents/commands/workflow/brainstorm.md

@@ -61,6 +61,18 @@ Use **AskQuestion** to suggest:
 > planning. Should I run `/workflow:plan` instead, or would you like to
 > explore the idea further?"
 
+**State orchestration candidate signals (detection only):**
+
+- Multi-step async flow with branching or compensation
+- More than one boolean/flag controlling the same flow
+- Retries, timeouts, cancellation, or recovery requirements
+- Cross-component or cross-service coordination
+- Planned spawned-child actors or receptionist-style actor lookup
+
+If these signals appear, note that `/workflow:plan` should evaluate
+`xstate-actor-orchestration`. Do not force architecture decisions in
+brainstorm.
+
 ---
 
 ### Phase 1: Understand the Idea

package/src/.agents/commands/workflow/plan.md

@@ -83,10 +83,26 @@ Refine the idea through collaborative dialogue using **AskQuestion**:
 - **User's intent**: Speed vs thoroughness? Exploration vs execution?
 - **Topic risk**: Security, payments, external APIs warrant more caution
 - **Uncertainty level**: Is the approach clear or open-ended?
+- **State complexity**: Multi-step async branching, retries/timeouts/cancellation, receptionist/child actors, cross-component/service coordination, or boolean-flag sprawl.
 
 **Skip option:** If the feature description is already detailed, offer:
 "Your description is clear. Should I proceed with research, or would you like to refine it further?"
 
+### 0.5. State-Orchestration Fit Check (Decision in planning)
+
+Before finalizing architecture, decide whether to load
+`xstate-actor-orchestration`.
+
+Load it when complexity exceeds simple local state, especially for:
+
+- UI flows where a React container should orchestrate context/state and
+  compose presentational components
+- Backend/internal workflows with hidden state complexity, lifecycle
+  management, retries/timeouts/cancellation, or actor coordination
+- Cases where more than one boolean/flag currently controls flow
+
+If not selected, document why simpler state management is sufficient.
+
 ## Main Tasks
 
 ### 1. Local Research (Always Runs - Parallel)

package/src/.agents/commands/workflow/work.md

@@ -41,6 +41,19 @@ The input must be a plan file path.
    - Get user approval to proceed
    - **Do not skip this** - better to ask questions now than build the wrong thing
 
+1.1. **Apply state-orchestration trigger (enforcement)**
+
+   If the plan or implementation involves XState/state-machine
+   orchestration, load `xstate-actor-orchestration` before coding.
+
+   Trigger examples:
+
+   - React container-as-orchestrator composition for complex UI flows
+   - Backend/internal workflow orchestration with hidden complexity
+   - Spawned children or receptionist-style actor lookup
+   - Retries/timeouts/cancellation/recovery state handling
+   - More than one boolean/flag controlling one workflow
+
 1.25. **Resolve Repo Defaults (ALWAYS FIRST)**
 
    Read `AGENTS.md` and look for the "Repo Config Block" YAML.

package/src/.agents/scripts/sync-opencode.mjs

@@ -250,9 +250,16 @@ function main() {
   const existing = readJsonMaybeJsonc(opencodeAbs) ?? {};
   const next = structuredClone(existing);
 
+  const SKILLS_COMPOUND_PATH = ".agents/compound-workflow-skills";
   next.$schema = next.$schema || "https://opencode.ai/config.json";
   next.skills = ensureObject(next.skills);
   next.skills.paths = Array.isArray(next.skills.paths) ? next.skills.paths : [".agents/skills"];
+  const hasCompoundWorkflow =
+    fs.existsSync(path.join(rootAbs, "node_modules", "compound-workflow")) ||
+    fs.existsSync(path.join(rootAbs, SKILLS_COMPOUND_PATH));
+  if (hasCompoundWorkflow && !next.skills.paths.includes(SKILLS_COMPOUND_PATH)) {
+    next.skills.paths.unshift(SKILLS_COMPOUND_PATH);
+  }
   next.command = ensureObject(next.command);
   next.agent = ensureObject(next.agent);
 

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

@@ -0,0 +1,197 @@
+---
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,73 @@
+# 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

@@ -0,0 +1,53 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,39 @@
+# 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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,44 @@
+# 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

@@ -0,0 +1,59 @@
+# 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.

package/src/.agents/skills/xstate-actor-orchestration/references/testing-strategy.md

@@ -0,0 +1,35 @@
+# Testing Strategy
+
+## Test layers
+
+1. Unit tests:
+- Actions, guards, pure transition logic.
+
+2. Actor tests:
+- Start actors, send events, assert snapshots and outputs.
+
+3. Integration tests:
+- Orchestrator plus real or fake worker actors.
+
+4. Model/path tests:
+- Generate critical paths from machine model.
+
+## Priority scenarios
+
+- Happy path completion.
+- Cancellation at each in-flight stage.
+- Retry exhaustion and terminal failure.
+- Recovery from persisted snapshot.
+- Out-of-order or duplicate events.
+
+## Assertions to include
+
+- Current state value.
+- Context data invariants.
+- Emitted events to collaborators.
+- Invoked actor lifecycle (started/stopped as expected).
+
+## Simulated time
+
+Use simulated clocks for deterministic timeout testing.
+Avoid wall-clock sleeps in tests.

package/src/.agents/skills/xstate-actor-orchestration/scripts/create-statechart-artifact.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+skill_dir="${1:-.}"
+machine_name_raw="${2:-}"
+timestamp="${3:-$(date '+%Y%m%d-%H%M%S')}"
+phase="${4:-DRAFT}"
+
+if [[ -z "$machine_name_raw" ]]; then
+  echo "Usage: $0 <skill-dir> <machine-name> [timestamp] [phase]" >&2
+  exit 1
+fi
+
+machine_name="$(echo "$machine_name_raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+if [[ -z "$machine_name" ]]; then
+  echo "ERROR: machine-name must contain at least one alphanumeric character" >&2
+  exit 1
+fi
+
+artifact_dir="$skill_dir/assets/statecharts"
+mkdir -p "$artifact_dir"
+
+artifact_base="${machine_name}-${timestamp}"
+diagram_file="$artifact_dir/${artifact_base}.mmd"
+signoff_file="$artifact_dir/${artifact_base}.signoff.md"
+
+if [[ -e "$diagram_file" || -e "$signoff_file" ]]; then
+  echo "ERROR: Artifact already exists for ${artifact_base}" >&2
+  exit 1
+fi
+
+cat > "$diagram_file" <<EOF
+stateDiagram-v2
+  [*] --> "TODO: initial"
+  "TODO: initial" --> "TODO: next": "TODO: event"
+  "TODO: next" --> [*]
+EOF
+
+cat > "$signoff_file" <<EOF
+# Statechart Sign-Off
+
+- Machine: ${machine_name_raw}
+- Artifact: ${artifact_base}
+- Diagram: ./$(basename "$diagram_file")
+- Source machine file: TODO:
+
+## Change summary
+
+TODO:
+
+## Review discussion points
+
+1. Scope and event visibility:
+2. Parallel vs sequential structure:
+3. Wildcard routing behavior:
+4. Retry/cancel/recovery paths:
+5. Tags used by UI selectors:
+6. Emitted imperative events:
+
+## Sign-off
+
+- Status: ${phase}
+- Reviewer:
+- Date:
+- Notes:
+EOF
+
+echo "Created:"
+echo "- $diagram_file"
+echo "- $signoff_file"

package/src/.agents/skills/xstate-actor-orchestration/scripts/validate-skill.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+skill_dir="${1:-.}"
+skill_md="$skill_dir/SKILL.md"
+openai_yaml="$skill_dir/agents/openai.yaml"
+statecharts_dir="$skill_dir/assets/statecharts"
+statechart_script="$skill_dir/scripts/create-statechart-artifact.sh"
+
+fail=0
+
+ok() {
+  echo "OK: $1"
+}
+
+err() {
+  echo "ERROR: $1" >&2
+  fail=1
+}
+
+if [[ ! -f "$skill_md" ]]; then
+  err "Missing SKILL.md at $skill_md"
+fi
+
+if [[ ! -f "$openai_yaml" ]]; then
+  err "Missing agents/openai.yaml at $openai_yaml"
+fi
+
+if [[ ! -d "$statecharts_dir" ]]; then
+  err "Missing statechart asset directory at $statecharts_dir"
+else
+  ok "Statechart asset directory exists"
+fi
+
+if [[ ! -f "$statechart_script" ]]; then
+  err "Missing statechart artifact script at $statechart_script"
+elif [[ ! -x "$statechart_script" ]]; then
+  err "Statechart artifact script is not executable: $statechart_script"
+else
+  ok "Statechart artifact script exists and is executable"
+fi
+
+if [[ -f "$skill_md" ]]; then
+  first_line="$(head -n 1 "$skill_md" || true)"
+  if [[ "$first_line" != "---" ]]; then
+    err "SKILL.md must start with frontmatter delimiter '---'"
+  fi
+
+  fm_end_line="$(awk 'NR > 1 && $0 == "---" { print NR; exit }' "$skill_md")"
+  if [[ -z "${fm_end_line:-}" ]]; then
+    err "SKILL.md is missing closing frontmatter delimiter '---'"
+  else
+    ok "Frontmatter delimiters found"
+
+    frontmatter="$(sed -n "2,$((fm_end_line - 1))p" "$skill_md")"
+
+    if ! grep -qE '^name:[[:space:]]*[^[:space:]].*$' <<<"$frontmatter"; then
+      err "Frontmatter must include non-empty 'name'"
+    fi
+
+    if ! grep -qE '^description:[[:space:]]*[^[:space:]].*$' <<<"$frontmatter"; then
+      err "Frontmatter must include non-empty 'description'"
+    fi
+
+    extra_keys="$(sed '/^[[:space:]]*$/d' <<<"$frontmatter" | sed 's/:.*$//' | grep -Ev '^(name|description)$' || true)"
+    if [[ -n "$extra_keys" ]]; then
+      err "Frontmatter contains unsupported key(s): $(tr '\n' ',' <<<"$extra_keys" | sed 's/,$//')"
+    else
+      ok "Frontmatter keys are limited to name and description"
+    fi
+
+    skill_name="$(sed -n 's/^name:[[:space:]]*//p' <<<"$frontmatter" | head -n 1)"
+    if [[ ! "$skill_name" =~ ^[a-z0-9-]{1,64}$ ]]; then
+      err "name must match ^[a-z0-9-]{1,64}$ (found '$skill_name')"
+    else
+      ok "Skill name format is valid"
+    fi
+
+    skill_dir_basename="$(basename "$skill_dir")"
+    if [[ "$skill_name" != "$skill_dir_basename" ]]; then
+      err "Folder name '$skill_dir_basename' must match frontmatter name '$skill_name'"
+    else
+      ok "Folder name matches frontmatter name"
+    fi
+  fi
+fi
+
+if [[ -f "$openai_yaml" ]]; then
+  if ! grep -qE '^[[:space:]]*default_prompt:[[:space:]]*".*"$' "$openai_yaml"; then
+    err "agents/openai.yaml must include quoted default_prompt"
+  else
+    ok "default_prompt exists"
+  fi
+
+  if [[ -n "${skill_name:-}" ]] && ! grep -q '\$'"${skill_name}" "$openai_yaml"; then
+    err "default_prompt must mention \$${skill_name}"
+  elif [[ -n "${skill_name:-}" ]]; then
+    ok "default_prompt mentions $skill_name"
+  fi
+fi
+
+if command -v rg >/dev/null 2>&1; then
+  set +e
+  rg -n '\[TODO|TODO:' \
+    "$skill_dir/SKILL.md" \
+    "$skill_dir/agents/openai.yaml" \
+    "$skill_dir/references" >/dev/null
+  todo_rc=$?
+  set -e
+  if [[ "$todo_rc" -eq 0 ]]; then
+    err "Unresolved TODO placeholders found in skill files"
+  elif [[ "$todo_rc" -eq 1 ]]; then
+    ok "No TODO markers found"
+  else
+    err "Failed to run TODO marker check with ripgrep"
+  fi
+
+  if [[ -f "$skill_md" ]]; then
+    while IFS= read -r rel_path; do
+      clean_path="${rel_path#references/}"
+      full_path="$skill_dir/references/$clean_path"
+      if [[ ! -f "$full_path" ]]; then
+        err "Missing reference file linked from SKILL.md: $rel_path"
+      fi
+    done < <(rg -o '\]\((references/[^)]+)\)' "$skill_md" | sed -E 's/.*\((references\/[^)]+)\).*/\1/' | sort -u)
+    ok "Reference links resolved"
+  fi
+else
+  err "ripgrep (rg) is required for TODO and reference-link checks"
+fi
+
+if [[ "$fail" -ne 0 ]]; then
+  echo "Validation failed." >&2
+  exit 1
+fi
+
+echo "Validation passed."

package/src/AGENTS.md

@@ -136,13 +136,14 @@ worktree_bootstrap_notes:
 
 - Commands: `.agents/commands/*.md` and `.agents/commands/workflow/*.md` (workflow namespace)
 - Skills: `.agents/skills/*/SKILL.md`
+- Skills may optionally include tool-specific agent metadata under `.agents/skills/*/agents/` (for example `openai.yaml`) when required by that skill's validator/runtime.
 - References: `.agents/references/**`
 - Agents: `.agents/agents/**/*.md`
 
 ## Implemented Components (Current Scope)
 
 - Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:work`, `workflow:triage`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
-- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
+- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs` (alias: `compound_doc`), `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `xstate-actor-orchestration`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
 - Agents:
   - `repo-research-analyst`
   - `learnings-researcher`
@@ -197,11 +198,12 @@ Maintenance:
 | `brainstorming` | You need structured idea exploration and clarification without writing code. |
 | `document-review` | You need to review a document/spec and extract issues, gaps, and concrete next actions. |
 | `technical-review` | A plan or feature approach has passed document review and must be checked for technical correctness before build. |
-| `compound-docs` | A durable learning (solved problem or implementation insight) should be captured as institutional knowledge. |
+| `compound-docs` (alias: `compound_doc`) | A durable learning (solved problem or implementation insight) should be captured as institutional knowledge. |
 | `file-todos` | You need a file-backed todo workflow for iterative multi-step changes. |
 | `agent-browser` | You need to inspect available agents/skills and route deterministically. |
 | `git-worktree` | You need isolated parallel work (review/feature) using git worktrees. |
 | `process-metrics` | You want to log and assess session performance and process improvements. |
+| `xstate-actor-orchestration` | You are evaluating complexity and need explicit state orchestration: React container-as-orchestrator for UI flows, or actor/state-machine orchestration for backend/internal workflows (especially multi-step async branching, retries/timeouts/cancellation, receptionist/child-actor coordination, or boolean-flag sprawl). |
 
 ### Reference standards (guardrails)