@wooksjs/event-wf 0.6.2 → 0.6.4

package/README.md

@@ -62,10 +62,9 @@ app.flow('adding-parametric', [
     },
 ])
 
-app.run()
-
 // Run the 'adding' workflow
-app.start('adding', { result: 0 })
+const output = await app.start('adding', { result: 0 })
+console.log(output.state.context) // { result: 14 }
 ```
 
 ## Documentation
@@ -76,6 +75,30 @@ For more detailed documentation, please visit [wooks.moost.org](https://wooks.mo
 
 Contributions to the `@wooksjs/event-wf` project are welcome. If you find any bugs or have a feature request, please open an issue on [the GitHub repository](https://github.com/wooksjs/wooksjs).
 
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx @wooksjs/event-wf setup-skills
+
+# Global (available across all your projects)
+npx @wooksjs/event-wf setup-skills --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx @wooksjs/event-wf setup-skills --postinstall"
+  }
+}
+```
+
+This ensures the skill files are refreshed whenever dependencies are installed, without needing a separate command.
+
 ## License
 
 `@wooksjs/event-wf` is licensed under the [MIT license](https://github.com/wooksjs/wooksjs/blob/main/LICENSE).

package/dist/index.cjs

@@ -26,6 +26,7 @@ const __prostojs_wf = __toESM(require("@prostojs/wf"));
 const wooks = __toESM(require("wooks"));
 
 //#region packages/event-wf/src/event-wf.ts
+/** Creates a new async event context for a fresh workflow execution. */
 function createWfContext(data, options) {
 	return (0, __wooksjs_event_core.createAsyncEventContext)({
 		event: {
@@ -36,6 +37,7 @@ function createWfContext(data, options) {
 		options
 	});
 }
+/** Creates an async event context for resuming a paused workflow. */
 function resumeWfContext(data, options) {
 	return (0, __wooksjs_event_core.createAsyncEventContext)({
 		event: {
@@ -57,6 +59,15 @@ function useWFContext() {
 
 //#endregion
 //#region packages/event-wf/src/composables/wf-state.ts
+/**
+* Composable that provides access to the current workflow execution state.
+* @example
+* ```ts
+* const { ctx, input, schemaId, stepId } = useWfState()
+* const context = ctx<MyContext>()
+* const stepInput = input<MyInput>()
+* ```
+*/
 function useWfState() {
 	const { store, getCtx } = useWFContext();
 	const event = store("event");
@@ -72,6 +83,7 @@ function useWfState() {
 
 //#endregion
 //#region packages/event-wf/src/workflow.ts
+/** Workflow engine that resolves steps via Wooks router lookup. */
 var WooksWorkflow = class extends __prostojs_wf.Workflow {
 	constructor(wooks$1) {
 		super([]);
@@ -86,7 +98,7 @@ var WooksWorkflow = class extends __prostojs_wf.Workflow {
 				store.set("stepId", stepIdNorm);
 				return found.handlers[0]();
 			}
-		} catch (error) {
+		} catch {
 			const router = this.wooks.getRouter();
 			const found = router.lookup("WF_STEP", stepIdNorm);
 			if (found?.route?.handlers.length) return found.route.handlers[0]();
@@ -97,10 +109,12 @@ var WooksWorkflow = class extends __prostojs_wf.Workflow {
 
 //#endregion
 //#region packages/event-wf/src/wf-adapter.ts
+/** Shortcut mappings for workflow event methods. */
 const wfShortcuts = {
 	flow: "WF_FLOW",
 	step: "WF_STEP"
 };
+/** Wooks adapter for defining and executing workflow schemas with step-based routing. */
 var WooksWf = class extends wooks.WooksAdapterBase {
 	logger;
 	wf;
@@ -110,16 +124,20 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 		this.logger = opts?.logger || this.getLogger(`[wooks-wf]`);
 		this.wf = new WooksWorkflow(this.wooks);
 	}
+	/** Attaches a spy function to observe workflow step execution. */
 	attachSpy(fn) {
 		return this.wf.attachSpy(fn);
 	}
+	/** Removes a previously attached workflow spy function. */
 	detachSpy(fn) {
 		this.wf.detachSpy(fn);
 	}
+	/** Registers a workflow step with the given id and handler. */
 	step(id, opts) {
 		const step = (0, __prostojs_wf.createStep)(id, opts);
 		return this.on("WF_STEP", id, () => step);
 	}
+	/** Registers a workflow flow schema with the given id. */
 	flow(id, schema, prefix, init) {
 		this.wf.register(id, schema, prefix);
 		return this.on("WF_FLOW", id, () => ({
@@ -127,9 +145,11 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 			id
 		}));
 	}
+	/** Starts a new workflow execution from the beginning. */
 	start(schemaId, inputContext, input, spy, cleanup) {
 		return this._start(schemaId, inputContext, void 0, input, spy, cleanup);
 	}
+	/** Resumes a previously paused workflow from saved state. */
 	resume(state, input, spy, cleanup) {
 		return this._start(state.schemaId, state.context, state.indexes, input, spy, cleanup);
 	}
@@ -200,16 +220,29 @@ var WooksWf = class extends wooks.WooksAdapterBase {
 	}
 };
 /**
-* Factory for WooksWf App
-* @param opts TWooksWfOptions
-* @param wooks Wooks | WooksAdapterBase
-* @returns WooksWf
+* Creates a new WooksWf application instance for workflow execution.
+* @param opts - Workflow adapter configuration options
+* @param wooks - Optional existing Wooks or adapter instance to attach to
+* @returns A new WooksWf instance
+* @example
+* ```ts
+* const app = createWfApp()
+* app.step('process', { handler: (ctx) => ctx })
+* app.flow('my-flow', [{ step: 'process' }])
+* await app.start('my-flow', { data: 'hello' })
+* ```
 */
 function createWfApp(opts, wooks$1) {
 	return new WooksWf(opts, wooks$1);
 }
 
 //#endregion
+Object.defineProperty(exports, 'StepRetriableError', {
+  enumerable: true,
+  get: function () {
+    return __prostojs_wf.StepRetriableError;
+  }
+});
 exports.WooksWf = WooksWf;
 exports.createWfApp = createWfApp;
 exports.createWfContext = createWfContext;

package/dist/index.d.ts

@@ -4,8 +4,17 @@ import * as wooks from 'wooks';
 import { Wooks, TWooksHandler, TWooksOptions, WooksAdapterBase } from 'wooks';
 import { TConsoleBase } from '@prostojs/logger';
 import { Workflow, Step, TWorkflowSpy, TStepHandler, TWorkflowSchema, TFlowOutput } from '@prostojs/wf';
-export { TStepHandler, TWorkflowSchema } from '@prostojs/wf';
+export { StepRetriableError, TStepHandler, TWorkflowSchema } from '@prostojs/wf';
 
+/**
+ * Composable that provides access to the current workflow execution state.
+ * @example
+ * ```ts
+ * const { ctx, input, schemaId, stepId } = useWfState()
+ * const context = ctx<MyContext>()
+ * const stepInput = input<MyInput>()
+ * ```
+ */
 declare function useWfState(): {
     ctx: <T>() => T;
     input: <I>() => I | undefined;
@@ -15,6 +24,7 @@ declare function useWfState(): {
     resume: boolean;
 };
 
+/** Event data describing a workflow execution instance. */
 interface TWFEventData {
     schemaId: string;
     stepId: string | null;
@@ -23,11 +33,14 @@ interface TWFEventData {
     input?: unknown;
     type: 'WF';
 }
+/** Context store for workflow events, tracking resume state. */
 interface TWFContextStore {
     resume: boolean;
 }
 
+/** Creates a new async event context for a fresh workflow execution. */
 declare function createWfContext(data: Omit<TWFEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: any[]) => T) => T;
+/** Creates an async event context for resuming a paused workflow. */
 declare function resumeWfContext(data: Omit<TWFEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: any[]) => T) => T;
 /**
  * Wrapper on top of useEventContext that provides
@@ -36,16 +49,19 @@ declare function resumeWfContext(data: Omit<TWFEventData, 'type'>, options: TEve
  */
 declare function useWFContext<T extends TEmpty>(): _wooksjs_event_core.TCtxHelpers<TWFContextStore & T & _wooksjs_event_core.TGenericContextStore<TWFEventData>>;
 
+/** Workflow engine that resolves steps via Wooks router lookup. */
 declare class WooksWorkflow<T, IR> extends Workflow<T, IR> {
     protected wooks: Wooks;
     constructor(wooks: Wooks);
     protected resolveStep<I, IR2>(stepId: string): Step<T, I, IR2>;
 }
 
+/** Shortcut mappings for workflow event methods. */
 declare const wfShortcuts: {
     flow: string;
     step: string;
 };
+/** Configuration options for the WooksWf adapter. */
 interface TWooksWfOptions {
     onError?: (e: Error) => void;
     onNotFound?: TWooksHandler;
@@ -54,19 +70,26 @@ interface TWooksWfOptions {
     eventOptions?: TEventOptions;
     router?: TWooksOptions['router'];
 }
+/** Wooks adapter for defining and executing workflow schemas with step-based routing. */
 declare class WooksWf<T = any, IR = any> extends WooksAdapterBase {
     protected opts?: TWooksWfOptions | undefined;
     protected logger: TConsoleBase;
     protected wf: WooksWorkflow<T, IR>;
     constructor(opts?: TWooksWfOptions | undefined, wooks?: Wooks | WooksAdapterBase);
+    /** Attaches a spy function to observe workflow step execution. */
     attachSpy<I>(fn: TWorkflowSpy<T, I, IR>): () => void;
+    /** Removes a previously attached workflow spy function. */
     detachSpy<I>(fn: TWorkflowSpy<T, I, IR>): void;
+    /** Registers a workflow step with the given id and handler. */
     step<I = any>(id: string, opts: {
         input?: I;
         handler: string | TStepHandler<T, I, IR>;
     }): wooks.TProstoRouterPathHandle<Record<string, string | string[]>>;
+    /** Registers a workflow flow schema with the given id. */
     flow(id: string, schema: TWorkflowSchema<T>, prefix?: string, init?: () => void | Promise<void>): wooks.TProstoRouterPathHandle<Record<string, string | string[]>>;
+    /** Starts a new workflow execution from the beginning. */
     start<I>(schemaId: string, inputContext: T, input?: I, spy?: TWorkflowSpy<T, I, IR>, cleanup?: () => void): Promise<TFlowOutput<T, I, IR>>;
+    /** Resumes a previously paused workflow from saved state. */
     resume<I>(state: {
         schemaId: string;
         indexes: number[];
@@ -77,11 +100,19 @@ declare class WooksWf<T = any, IR = any> extends WooksAdapterBase {
     protected error(e: string | Error): void;
 }
 /**
- * Factory for WooksWf App
- * @param opts TWooksWfOptions
- * @param wooks Wooks | WooksAdapterBase
- * @returns WooksWf
+ * Creates a new WooksWf application instance for workflow execution.
+ * @param opts - Workflow adapter configuration options
+ * @param wooks - Optional existing Wooks or adapter instance to attach to
+ * @returns A new WooksWf instance
+ * @example
+ * ```ts
+ * const app = createWfApp()
+ * app.step('process', { handler: (ctx) => ctx })
+ * app.flow('my-flow', [{ step: 'process' }])
+ * await app.start('my-flow', { data: 'hello' })
+ * ```
  */
 declare function createWfApp<T>(opts?: TWooksWfOptions, wooks?: Wooks | WooksAdapterBase): WooksWf<T, any>;
 
-export { type TWFContextStore, type TWFEventData, type TWooksWfOptions, WooksWf, createWfApp, createWfContext, resumeWfContext, useWFContext, useWfState, wfShortcuts };
+export { WooksWf, createWfApp, createWfContext, resumeWfContext, useWFContext, useWfState, wfShortcuts };
+export type { TWFContextStore, TWFEventData, TWooksWfOptions };

package/dist/index.mjs

@@ -1,8 +1,9 @@
 import { createAsyncEventContext, useAsyncEventContext } from "@wooksjs/event-core";
-import { Workflow, createStep } from "@prostojs/wf";
+import { StepRetriableError, Workflow, createStep } from "@prostojs/wf";
 import { WooksAdapterBase } from "wooks";
 
 //#region packages/event-wf/src/event-wf.ts
+/** Creates a new async event context for a fresh workflow execution. */
 function createWfContext(data, options) {
 	return createAsyncEventContext({
 		event: {
@@ -13,6 +14,7 @@ function createWfContext(data, options) {
 		options
 	});
 }
+/** Creates an async event context for resuming a paused workflow. */
 function resumeWfContext(data, options) {
 	return createAsyncEventContext({
 		event: {
@@ -34,6 +36,15 @@ function useWFContext() {
 
 //#endregion
 //#region packages/event-wf/src/composables/wf-state.ts
+/**
+* Composable that provides access to the current workflow execution state.
+* @example
+* ```ts
+* const { ctx, input, schemaId, stepId } = useWfState()
+* const context = ctx<MyContext>()
+* const stepInput = input<MyInput>()
+* ```
+*/
 function useWfState() {
 	const { store, getCtx } = useWFContext();
 	const event = store("event");
@@ -49,6 +60,7 @@ function useWfState() {
 
 //#endregion
 //#region packages/event-wf/src/workflow.ts
+/** Workflow engine that resolves steps via Wooks router lookup. */
 var WooksWorkflow = class extends Workflow {
 	constructor(wooks) {
 		super([]);
@@ -63,7 +75,7 @@ var WooksWorkflow = class extends Workflow {
 				store.set("stepId", stepIdNorm);
 				return found.handlers[0]();
 			}
-		} catch (error) {
+		} catch {
 			const router = this.wooks.getRouter();
 			const found = router.lookup("WF_STEP", stepIdNorm);
 			if (found?.route?.handlers.length) return found.route.handlers[0]();
@@ -74,10 +86,12 @@ var WooksWorkflow = class extends Workflow {
 
 //#endregion
 //#region packages/event-wf/src/wf-adapter.ts
+/** Shortcut mappings for workflow event methods. */
 const wfShortcuts = {
 	flow: "WF_FLOW",
 	step: "WF_STEP"
 };
+/** Wooks adapter for defining and executing workflow schemas with step-based routing. */
 var WooksWf = class extends WooksAdapterBase {
 	logger;
 	wf;
@@ -87,16 +101,20 @@ var WooksWf = class extends WooksAdapterBase {
 		this.logger = opts?.logger || this.getLogger(`[wooks-wf]`);
 		this.wf = new WooksWorkflow(this.wooks);
 	}
+	/** Attaches a spy function to observe workflow step execution. */
 	attachSpy(fn) {
 		return this.wf.attachSpy(fn);
 	}
+	/** Removes a previously attached workflow spy function. */
 	detachSpy(fn) {
 		this.wf.detachSpy(fn);
 	}
+	/** Registers a workflow step with the given id and handler. */
 	step(id, opts) {
 		const step = createStep(id, opts);
 		return this.on("WF_STEP", id, () => step);
 	}
+	/** Registers a workflow flow schema with the given id. */
 	flow(id, schema, prefix, init) {
 		this.wf.register(id, schema, prefix);
 		return this.on("WF_FLOW", id, () => ({
@@ -104,9 +122,11 @@ var WooksWf = class extends WooksAdapterBase {
 			id
 		}));
 	}
+	/** Starts a new workflow execution from the beginning. */
 	start(schemaId, inputContext, input, spy, cleanup) {
 		return this._start(schemaId, inputContext, void 0, input, spy, cleanup);
 	}
+	/** Resumes a previously paused workflow from saved state. */
 	resume(state, input, spy, cleanup) {
 		return this._start(state.schemaId, state.context, state.indexes, input, spy, cleanup);
 	}
@@ -177,14 +197,21 @@ var WooksWf = class extends WooksAdapterBase {
 	}
 };
 /**
-* Factory for WooksWf App
-* @param opts TWooksWfOptions
-* @param wooks Wooks | WooksAdapterBase
-* @returns WooksWf
+* Creates a new WooksWf application instance for workflow execution.
+* @param opts - Workflow adapter configuration options
+* @param wooks - Optional existing Wooks or adapter instance to attach to
+* @returns A new WooksWf instance
+* @example
+* ```ts
+* const app = createWfApp()
+* app.step('process', { handler: (ctx) => ctx })
+* app.flow('my-flow', [{ step: 'process' }])
+* await app.start('my-flow', { data: 'hello' })
+* ```
 */
 function createWfApp(opts, wooks) {
 	return new WooksWf(opts, wooks);
 }
 
 //#endregion
-export { WooksWf, createWfApp, createWfContext, resumeWfContext, useWFContext, useWfState, wfShortcuts };
+export { StepRetriableError, WooksWf, createWfApp, createWfContext, resumeWfContext, useWFContext, useWfState, wfShortcuts };

package/package.json

@@ -1,54 +1,63 @@
 {
   "name": "@wooksjs/event-wf",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "@wooksjs/event-wf",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
+  "keywords": [
+    "app",
+    "composables",
+    "framework",
+    "http",
+    "prostojs",
+    "wooks",
+    "workflow"
   ],
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.ts"
-    }
+  "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-wf#readme",
+  "bugs": {
+    "url": "https://github.com/wooksjs/wooksjs/issues"
   },
+  "license": "MIT",
+  "author": "Artem Maltsev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-wf"
   },
-  "keywords": [
-    "http",
-    "wooks",
-    "composables",
-    "framework",
-    "app",
-    "workflow",
-    "prostojs"
+  "bin": {
+    "setup-skills": "scripts/setup-skills.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts"
   ],
-  "author": "Artem Maltsev",
-  "license": "MIT",
-  "peerDependencies": {
-    "@prostojs/logger": "^0.4.3",
-    "@wooksjs/event-core": "^0.6.2",
-    "wooks": "^0.6.2"
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    }
   },
   "dependencies": {
     "@prostojs/wf": "^0.0.18"
   },
-  "bugs": {
-    "url": "https://github.com/wooksjs/wooksjs/issues"
-  },
-  "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-wf#readme",
   "devDependencies": {
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@wooksjs/event-core": "^0.6.4",
+    "wooks": "^0.6.4"
+  },
+  "peerDependencies": {
+    "@prostojs/logger": "^0.4.3",
+    "@wooksjs/event-core": "^0.6.4",
+    "wooks": "^0.6.4"
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs"
+    "build": "rolldown -c ../../rolldown.config.mjs",
+    "postinstall": "node scripts/setup-skills.js",
+    "setup-skills": "node scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/* prettier-ignore */
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+
+const SKILL_NAME = 'wooksjs-event-wf'
+const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
+
+if (!fs.existsSync(SKILL_SRC)) {
+  console.error(`No skills found at ${SKILL_SRC}`)
+  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
+  process.exit(1)
+}
+
+const AGENTS = {
+  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
+  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
+  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
+  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
+  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
+}
+
+const args = process.argv.slice(2)
+const isGlobal = args.includes('--global') || args.includes('-g')
+const isPostinstall = args.includes('--postinstall')
+let installed = 0, skipped = 0
+const installedDirs = []
+
+for (const [agentName, cfg] of Object.entries(AGENTS)) {
+  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
+  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
+
+  // In postinstall mode: silently skip agents that aren't set up globally
+  if (isPostinstall || isGlobal) {
+    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
+  }
+
+  const dest = path.join(targetBase, SKILL_NAME)
+  try {
+    fs.mkdirSync(dest, { recursive: true })
+    fs.cpSync(SKILL_SRC, dest, { recursive: true })
+    console.log(`✅  ${agentName}: installed to ${dest}`)
+    installed++
+    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
+  } catch (err) {
+    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
+  }
+}
+
+// Add locally-installed skill dirs to .gitignore
+if (!isGlobal && installedDirs.length > 0) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore')
+  let gitignoreContent = ''
+  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
+  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
+  if (linesToAdd.length > 0) {
+    const hasHeader = gitignoreContent.includes('# AI agent skills')
+    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
+      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
+      + linesToAdd.join('\n') + '\n'
+    fs.appendFileSync(gitignorePath, block)
+    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
+  }
+}
+
+if (installed === 0 && isPostinstall) {
+  // Silence is fine — no agents present, nothing to do
+} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
+  console.log('No agent directories detected. Try --global or run without it for project-local install.')
+} else if (installed === 0) {
+  console.log('Nothing installed. Run without --global to install project-locally.')
+} else {
+  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
+}

package/skills/wooksjs-event-wf/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: wooksjs-event-wf
+description: Wooks Workflow framework — composable, step-based workflow engine for Node.js. Load when building workflow/process automation with wooks; defining workflow steps and flows; using workflow composables (useWfState, useRouteParams); working with @wooksjs/event-core context store (init, get, set, hook); creating conditional and looping flows; resuming paused workflows; handling user input requirements; using string-based step handlers; attaching workflow spies; working with StepRetriableError; creating custom event context composables for workflows.
+---
+
+# @wooksjs/event-wf
+
+A composable workflow framework for Node.js built on async context (AsyncLocalStorage) and `@prostojs/wf`. Define steps and flows as composable units — steps execute sequentially with conditional branching, loops, pause/resume, and user input handling. Context is scoped per workflow execution.
+
+## How to use this skill
+
+Read the domain file that matches the task. Do not load all files — only what you need.
+
+| Domain | File | Load when... |
+|--------|------|------------|
+| Event context (core machinery) | [event-core.md](event-core.md) | Understanding the context store API (`init`/`get`/`set`/`hook`), creating custom composables, lazy evaluation and caching, building your own `use*()` functions |
+| Workflow app setup | [core.md](core.md) | Creating a workflow app, `createWfApp`, starting/resuming workflows, error handling, spies, testing, logging |
+| Steps & flows | [workflows.md](workflows.md) | Defining steps (`app.step`), defining flows (`app.flow`), workflow schemas, conditions, loops, user input, parametric steps, `useWfState`, `StepRetriableError`, string-based handlers |
+
+## Quick reference
+
+```ts
+import { createWfApp } from '@wooksjs/event-wf'
+
+const app = createWfApp<{ result: number }>()
+
+app.step('add', {
+  input: 'number',
+  handler: 'ctx.result += input',
+})
+
+app.flow('calculate', [
+  { id: 'add', input: 5 },
+  { id: 'add', input: 2 },
+  { condition: 'result < 10', steps: [{ id: 'add', input: 3 }] },
+])
+
+const output = await app.start('calculate', { result: 0 })
+console.log(output.state.context) // { result: 10 }
+```
+
+Key exports: `createWfApp()`, `useWfState()`, `useWFContext()`, `useRouteParams()`, `StepRetriableError`.