@workflow-manager/runner 0.7.0 → 0.8.0

package/dist/manPage.js

@@ -21,25 +21,36 @@ List the agent skills bundled with the npm package.
 .B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]
 Install bundled agent skills into an agent skill directory. Defaults to the workflow-manager-cli skill and the project-level Claude Code directory (./.claude/skills). Existing skills are not overwritten unless --force is passed.
 .TP
-.B scaffold [path] [--format markdown|json]
+.B scaffold [path] [--format markdown|json] [--template default|agent-validated]
 Create a starter workflow file. Format defaults to markdown unless the output
-path ends in .json.
+path ends in .json. Template defaults to default (the general multi-step example);
+agent-validated scaffolds a compact pipeline demonstrating first-class agent
+validation (validation.mode: agent with a validator agent and criteria).
 .TP
 .B validate <workflow.md|workflow.json>
 Validate workflow structure and report schema errors.
 .TP
-.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json] [--ui]
+.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--session-file path] [--verbose] [--json] [--ui]
 Run the workflow with live CLI progress and optional JSON output.
 .TP
-.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B approve [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Approve the current waiting runner step through the local attach API.
 .TP
-.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B resume [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Alias for approve, intended for external resume flows.
 .TP
-.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]
+.B cancel [--url value] [--token value] [--session-file path] [--run-id value] [--step value] [--actor value] [--note text]
 Cancel the current waiting runner step through the local attach API.
 .TP
+.B status [--url value] [--token value] [--session-file path] [--run-id value] [--step key]
+Print the current run snapshot (or one step detail with --step) as JSON on stdout.
+.TP
+.B logs [--url value] [--token value] [--session-file path] [--run-id value] [--step key] [--limit number] [--cursor value]
+Print buffered agent stdout/stderr chunks as JSON on stdout.
+.TP
+.B events [--url value] [--token value] [--session-file path] [--run-id value] [--since sequence] [--include-logs]
+Print run events as JSON on stdout in a single poll (no streaming). Log events are excluded unless --include-logs is passed.
+.TP
 .B auth <login|whoami|logout> [--token value]
 Manage remote registry authentication for CLI publish and pull flows.
 .TP
@@ -77,6 +88,9 @@ Bypass confirmation gating for all steps.
 .B --port <number>
 Bind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.
 .TP
+.B --session-file <path>
+Write attach connection details (base URL, bearer token, run id, pid, timestamps) to a JSON file with mode 0600 when the run starts, and rewrite it with endedAt and the final status when the run finishes. Attach commands (approve, resume, cancel, status, logs, events) accept the same flag to read those details back.
+.TP
 .B --verbose
 Stream per-step agent output and execution updates to stderr while the workflow runs.
 .TP
@@ -89,16 +103,28 @@ Full-screen terminal UI (requires a TTY; falls back to standard output).
 Human approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.
 .TP
 .B --url <value>
-Runner attach API base URL for approve, resume, or cancel commands.
+Runner attach API base URL for approve, resume, cancel, status, logs, or events commands.
 .TP
 .B --token <value>
-Runner attach API bearer token for approve, resume, or cancel commands.
+Runner attach API bearer token for approve, resume, cancel, status, logs, or events commands.
 .TP
 .B --run-id <value>
 Runner id to control. If omitted, the CLI reads it from /session.
 .TP
 .B --step <value>
-Optional step key when controlling a specific waiting step.
+Optional step key when controlling a specific waiting step, or when scoping status and logs output.
+.TP
+.B --limit <number>
+Maximum number of log chunks returned by the logs command. Defaults to 200.
+.TP
+.B --cursor <value>
+Pagination cursor for the logs command, taken from a previous nextCursor value.
+.TP
+.B --since <sequence>
+Only return events with a sequence greater than this value in the events command.
+.TP
+.B --include-logs
+Include agent.stdout and agent.stderr events in the events command output.
 .TP
 .B --actor <value>
 Actor name recorded in approval audit events.
@@ -116,6 +142,9 @@ Validate json workflow:
 Scaffold json workflow file:
 .B wfm scaffold ./new-workflow.json --format json
 .TP
+Scaffold an agent-validated pipeline example:
+.B wfm scaffold ./agent-validated.md --template agent-validated
+.TP
 Authenticate with a CLI token:
 .B wfm auth login --token wm_exampletoken
 .TP
@@ -131,6 +160,12 @@ Search the remote registry:
 Run with explicit confirmations:
 .B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human
 .TP
+Run with a session file for attach clients:
+.B wfm run ./example-workflow.json --session-file ./run-session.json
+.TP
+Observe and control the run through the session file:
+.B wfm status --session-file ./run-session.json && wfm approve --session-file ./run-session.json --step qa_gate
+.TP
 Inspect host setup:
 .B wfm doctor
 .TP

package/dist/parser.js

@@ -185,9 +185,18 @@ export function validateWorkflow(def) {
             errors.push(`Unsupported adapter for ${step.key}: ${adapter}`);
         }
         const mode = step.validation?.mode ?? step.approvalSpec?.validation?.mode;
-        if (mode && !["none", "human", "external"].includes(mode)) {
+        if (mode && !["none", "human", "external", "agent"].includes(mode)) {
             errors.push(`Invalid validation mode for ${step.key}: ${mode}`);
         }
+        if (step.approvalSpec?.validation?.mode === "agent") {
+            errors.push(`Approval step ${step.key} cannot use agent validation`);
+        }
+        if (step.validation?.mode === "agent" && step.validation.agent?.adapterKey) {
+            const validatorAdapter = step.validation.agent.adapterKey;
+            if (!SUPPORTED_ADAPTERS.includes(validatorAdapter)) {
+                errors.push(`Unsupported validator adapter for ${step.key}: ${validatorAdapter}`);
+            }
+        }
     }
     const cycle = findDependencyCycle(def);
     if (cycle) {

package/dist/runnerApi.js

@@ -136,6 +136,20 @@ export async function startRunnerApiServer(store, requestedPort) {
                 });
                 return;
             }
+            const eventsListMatch = pathname.match(/^\/runs\/([^/]+)\/events\/list$/);
+            if (method === "GET" && eventsListMatch) {
+                const runId = decodeURIComponent(eventsListMatch[1] ?? "");
+                if (!store.isKnownRun(runId)) {
+                    errorResponse(res, 404, "not_found", `Unknown run: ${runId}`);
+                    return;
+                }
+                const sinceSequence = Number.parseInt(url.searchParams.get("sinceSequence") ?? "0", 10) || undefined;
+                const includeLogs = parseBoolean(url.searchParams.get("includeLogs"), true);
+                const items = store.events(sinceSequence, includeLogs);
+                const nextSequence = items.reduce((max, event) => Math.max(max, event.sequence), sinceSequence ?? 0);
+                jsonResponse(res, 200, { items, nextSequence });
+                return;
+            }
             const eventsMatch = pathname.match(/^\/runs\/([^/]+)\/events$/);
             if (method === "GET" && eventsMatch) {
                 const runId = decodeURIComponent(eventsMatch[1] ?? "");

package/dist/sessionFile.d.ts

@@ -0,0 +1,11 @@
+export interface RunnerSessionFile {
+    baseUrl: string;
+    attachToken: string;
+    runId: string;
+    pid: number;
+    startedAt: string;
+    endedAt?: string;
+    status?: string;
+}
+export declare function writeSessionFile(filePath: string, session: RunnerSessionFile): void;
+export declare function readSessionFile(filePath: string): RunnerSessionFile | string;

package/dist/sessionFile.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+export function writeSessionFile(filePath, session) {
+    const resolvedPath = path.resolve(filePath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, `${JSON.stringify(session, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    // writeFileSync only applies the mode on creation; enforce it on rewrites too.
+    fs.chmodSync(resolvedPath, 0o600);
+}
+export function readSessionFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    let raw;
+    try {
+        raw = fs.readFileSync(resolvedPath, "utf-8");
+    }
+    catch (error) {
+        return `Could not read session file ${resolvedPath}: ${error.message}`;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return `Session file ${resolvedPath} is not valid JSON`;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return `Session file ${resolvedPath} must contain a JSON object`;
+    }
+    const record = parsed;
+    for (const field of ["baseUrl", "attachToken", "runId", "startedAt"]) {
+        if (typeof record[field] !== "string" || record[field] === "") {
+            return `Session file ${resolvedPath} is missing required field: ${field}`;
+        }
+    }
+    if (typeof record.pid !== "number" || !Number.isInteger(record.pid)) {
+        return `Session file ${resolvedPath} is missing required field: pid`;
+    }
+    if (record.endedAt !== undefined && typeof record.endedAt !== "string") {
+        return `Session file ${resolvedPath} has an invalid endedAt field`;
+    }
+    if (record.status !== undefined && typeof record.status !== "string") {
+        return `Session file ${resolvedPath} has an invalid status field`;
+    }
+    const session = {
+        baseUrl: record.baseUrl,
+        attachToken: record.attachToken,
+        runId: record.runId,
+        pid: record.pid,
+        startedAt: record.startedAt,
+    };
+    if (typeof record.endedAt === "string") {
+        session.endedAt = record.endedAt;
+    }
+    if (typeof record.status === "string") {
+        session.status = record.status;
+    }
+    return session;
+}

package/dist/tui/tuiRunRenderer.js

@@ -38,6 +38,17 @@ function buildEventMetaText(event) {
         const feedbackReason = readString(payload, "feedbackReason");
         return `execution finished: ${status}${action ? ` action=${action}` : ""}${feedbackReason ? ` reason=${feedbackReason}` : ""}`;
     }
+    if (event.type === "step.validation_started") {
+        const adapter = readString(payload, "adapter");
+        const criteria = readString(payload, "criteria");
+        return `agent validation started${adapter ? ` (${adapter})` : ""}${criteria ? ` criteria=${criteria}` : ""}`;
+    }
+    if (event.type === "step.validation_finished") {
+        const status = readString(payload, "status") ?? "unknown";
+        const action = readString(payload, "action");
+        const feedbackReason = readString(payload, "feedbackReason");
+        return `agent validation: ${status}${action ? ` action=${action}` : ""}${feedbackReason ? ` reason=${feedbackReason}` : ""}`;
+    }
     if (event.type === "step.retried") {
         const attempt = typeof payload.attempt === "number" ? payload.attempt : undefined;
         return attempt !== undefined ? `retry scheduled (attempt ${attempt})` : "retry scheduled";

package/dist/types.d.ts

@@ -4,17 +4,11 @@ export type StepKind = "task" | "approval" | "system";
 export type NodeType = "AGENT" | "HUMAN" | "SYSTEM";
 export type ExecutionStatus = "SUCCESS" | "QA_REJECTED" | "YIELD_EXTERNAL" | "FAILED";
 export type QaAction = "PROCEED" | "RETRY_CURRENT" | "ROLLBACK_PREVIOUS" | "RESTART_ALL";
-export type ValidationMode = "none" | "human" | "external";
+export type ValidationMode = "none" | "human" | "external" | "agent";
 export type AdapterKey = "pi-agent" | "mock" | "opencode" | "codex" | "claude-code" | "acp";
 export interface RetryPolicy {
     maxAttempts?: number;
 }
-export interface ValidationSpec {
-    mode?: ValidationMode;
-    required?: boolean;
-    autoConfirm?: boolean;
-    confirmerPolicy?: string;
-}
 export interface TaskInitConfig {
     context?: Record<string, unknown> | string;
     skills?: string[];
@@ -22,6 +16,19 @@ export interface TaskInitConfig {
     systemPrompts?: string[];
     model?: string;
 }
+export interface AgentValidationSpec {
+    adapterKey?: AdapterKey;
+    init?: TaskInitConfig;
+    criteria?: string;
+    payload?: Record<string, unknown>;
+}
+export interface ValidationSpec {
+    mode?: ValidationMode;
+    required?: boolean;
+    autoConfirm?: boolean;
+    confirmerPolicy?: string;
+    agent?: AgentValidationSpec;
+}
 export interface StepDefinition {
     key: string;
     kind: StepKind;
@@ -260,7 +267,7 @@ export interface RunEvent {
     id: string;
     runId: string;
     stepRunId?: string;
-    type: "run.created" | "run.started" | "run.waiting_for_approval" | "step.runnable" | "step.claimed" | "step.execution_started" | "step.execution_finished" | "step.waiting_for_approval" | "approval.resolved" | "step.retried" | "step.confirmed" | "agent.started" | "agent.stdout" | "agent.stderr" | "agent.finished" | "run.completed" | "run.failed" | "run.cancelled";
+    type: "run.created" | "run.started" | "run.waiting_for_approval" | "step.runnable" | "step.claimed" | "step.execution_started" | "step.execution_finished" | "step.validation_started" | "step.validation_finished" | "step.waiting_for_approval" | "approval.resolved" | "step.retried" | "step.confirmed" | "agent.started" | "agent.stdout" | "agent.stderr" | "agent.finished" | "run.completed" | "run.failed" | "run.cancelled";
     sequenceNumber: number;
     occurredAt: string;
     actor: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-manager/runner",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes",
   "repository": {
     "type": "git",
@@ -23,6 +23,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "generate:skills": "node ./scripts/generate-bundled-skills.mjs",
     "build:bin": "node ./scripts/build-binary.mjs --outfile ./dist/wfm",
     "build:bin:macos": "node ./scripts/build-binary.mjs --target bun-darwin-arm64 --outfile ./dist/wfm-macos-arm64",
     "build:bin:linux": "node ./scripts/build-binary.mjs --target bun-linux-x64 --outfile ./dist/wfm-linux-x64",

package/skills/workflow-author/README.md

@@ -0,0 +1,18 @@
+# workflow-author skill
+
+Teaches a host coding agent (Claude Code, opencode, pi) how to turn a natural-language
+task description into a repeatable `wfm` workflow, validate it, run it, and narrate
+progress — including approval gates — back to the user.
+
+This skill ships inside the root `@workflow-manager/runner` npm package alongside
+`workflow-manager-cli`. Install it into an agent's skill directory with:
+
+```bash
+wfm skill install workflow-author                    # -> ./.claude/skills/
+wfm skill install workflow-author --agent opencode    # -> ./.opencode/skill/
+wfm skill install workflow-author --global            # -> ~/.claude/skills/
+```
+
+See `SKILL.md` for the full operating manual, and `doc/guide/workflow-schema.md` /
+`doc/guide/runner-api.md` for the underlying schema and attach-API contract this
+skill is built on.

package/skills/workflow-author/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: workflow-author
+description: >
+  Author repeatable wfm workflows from a task description, validate them, run
+  them, and narrate progress as the workflow executes. Load this skill when a
+  user describes a multi-step task that should run the same way every time —
+  turn it into a wfm workflow file, validate it, and then drive `wfm run`
+  while translating status polls and approval gates into plain-language
+  updates for the user.
+type: core
+library: "@workflow-manager/runner"
+sources:
+  - "navio/workflow-manager:src/parser.ts"
+  - "navio/workflow-manager:src/types.ts"
+  - "navio/workflow-manager:src/engine.ts"
+  - "navio/workflow-manager:src/index.ts"
+  - "navio/workflow-manager:src/sessionFile.ts"
+  - "navio/workflow-manager:doc/guide/workflow-schema.md"
+  - "navio/workflow-manager:doc/guide/runner-api.md"
+---
+
+# workflow-author
+
+Turn a natural-language task description into a `wfm` workflow file: a static, reviewable, re-runnable artifact instead of a one-off chat session. This skill is the authoring + operating counterpart to `workflow-manager-cli` — read that skill for the general command reference; this one is about *deciding what to build* and *narrating a run to a human*.
+
+## 1. When to use
+
+Use this skill when the user has a task that:
+
+- has more than one meaningful step, with a clear order or dependency between steps
+- should produce the **same shape of result** every time it runs — not a bespoke plan improvised fresh each session
+- benefits from an explicit quality gate (an objective check, a human sign-off, or both) before moving on
+- is worth sharing: a teammate, a CI job, or a future session should be able to run it unchanged
+
+Do **not** reach for a workflow file for a single ad-hoc question, a one-shot investigation, or a task whose steps genuinely can't be known in advance. Ad-hoc orchestration (just doing the work directly) is cheaper than authoring a workflow when there is nothing to repeat. The signal to watch for: the user says some version of "every time we do X" or "we need a repeatable way to Y."
+
+## 2. The authoring loop
+
+Follow this sequence; do not skip validation.
+
+1. **Elicit the task and success criteria.** Ask (or infer from context) what "done" looks like for the overall task, and for each step you expect to need. Concrete, checkable criteria beat vague ones — "the change satisfies the objective and includes tests" is checkable; "does a good job" is not.
+2. **Decompose into chronological steps.** Every step gets a stable, kebab-case `key` (`implement-fix`, not `Step 1`). Wire `dependsOn` to express strict order — the engine resolves dependencies deterministically and rejects cycles, so an explicit `dependsOn: [previous-step]` is safer than relying on array order.
+3. **Choose a quality gate per step.** For each step's `validation` (or an `approval` step's `approvalSpec.validation`), pick one:
+   - `mode: agent` with concrete `criteria` — an objective, checkable condition a second agent call can verify against the step's output (tests pass, files changed match scope, no TODOs left). Prefer this whenever the check can be phrased as a fact about the artifact.
+   - a dedicated `kind: approval` step — a human judgment call (does this look right, is this the right tradeoff, are we comfortable shipping this). Use for genuinely subjective or high-stakes decisions.
+   - `mode: external` — an outside system resolves the step (a webhook, a deploy pipeline finishing).
+   - `mode: none` — mechanical steps with no interesting failure mode (formatting, a fixed notification).
+4. **Write the workflow.** Prefer the Markdown frontmatter format — humans (and you, later) can read the body notes alongside the machine-readable frontmatter; use JSON only for machine-generated definitions. Start from a scaffold:
+   ```bash
+   wfm scaffold --template agent-validated my-flow.md
+   ```
+   This drops a working three-step example (agent-validated task → approval → finalize) that you edit in place rather than writing from a blank file.
+5. **Validate, and keep validating.** `wfm validate my-flow.md` — fix every reported line, one at a time, until it prints `Validation OK`. Never hand a workflow to the user (or run it) with unresolved validation errors.
+6. **Dry-run adapter-heavy workflows with mocks.** If steps use real adapters (`pi-agent`, `claude-code`, `opencode`, `acp`), set `taskSpec.payload.mockResult: success` (or `retry` / `rollback` / `fail` to test routing) and `taskSpec.adapterKey: mock` temporarily, or `wfm doctor my-flow.md` to check host requirements without executing. This confirms dependency wiring and approval gating before spending a real adapter call.
+7. **Done.** The file *is* the reusable artifact — no further "session state" to preserve. Re-running it later reproduces the same step sequence.
+
+## 3. Schema cheat-sheet
+
+Everything here matches `src/types.ts` on this branch — do not invent fields.
+
+**Top level** (required: `key`, `title`, `steps`):
+
+```yaml
+key: my-workflow            # stable external identifier
+title: My Workflow          # default run objective
+description: optional summary
+objectives: [optional, run-level, objectives]
+defaultRetryPolicy: { maxAttempts: 2 }
+skills:                     # named skills resolvable by taskSpec.init.skills
+  my-skill:
+    source: ./skills/my-skill/SKILL.md   # must match skills/**/SKILL.md under the workflow dir
+steps: [ ... ]
+```
+
+**Step** (required: `key`, `kind`):
+
+```yaml
+- key: my-step                     # stable, kebab-case
+  kind: task                       # task | approval | system
+  title: optional display title
+  objective: optional step-level objective
+  dependsOn: [other-step-key]
+  timeoutSec: optional
+  retryPolicy: { maxAttempts: 2 }
+  validation:                      # gates confirmation for THIS step's own record
+    mode: none | human | external | agent
+    required: true
+    autoConfirm: false
+    agent:                         # only when mode: agent
+      adapterKey: pi-agent | mock | opencode | codex | claude-code | acp   # default: this step's adapter
+      criteria: "plain-language acceptance criteria the validator checks against"
+      init: { model, skills, mcps, systemPrompts, context }
+      payload: { mockResult: success }   # lets mock drive the validator in tests
+  taskSpec:                        # required when kind: task
+    adapterKey: pi-agent | mock | opencode | codex | claude-code | acp    # omit -> pi-agent
+    init:
+      model: openrouter/anthropic/claude-sonnet-4
+      skills: [skill-name]
+      mcps: [mcp://endpoint]
+      systemPrompts: [Focus on X]
+      context: { any: json }
+    payload:
+      mockResult: success | retry | rollback | restart | yield | fail   # mock adapter only
+  approvalSpec:                    # required when kind: approval
+    autoApprove: false
+    validation: { mode: human, required: true, autoConfirm: false }
+```
+
+**Critical gotcha** (verified on this branch, `src/parser.ts`): the parser fills an *unset* step-level `validation` with `{ mode: "none", required: false, autoConfirm: true }` by default — **even on `approval` steps**. `canConfirm` in `src/engine.ts` checks `step.validation?.autoConfirm` *before* `step.approvalSpec?.validation?.autoConfirm`. If you only set `approvalSpec.validation` and leave the step's own top-level `validation` unset, the default `autoConfirm: true` wins and the gate **silently auto-approves** instead of waiting for a human. Always set both `validation` and `approvalSpec.validation` on an approval step with matching `mode`/`required`/`autoConfirm` — see the worked example below.
+
+**Validation rules the CLI enforces:** unique step keys; every `dependsOn` references an existing step; no dependency cycles; `kind` is `task | approval | system`; `taskSpec.adapterKey` (if set) is one of the supported adapters; `validation.mode` is `none | human | external | agent`; `mode: agent` is **not allowed** on approval steps (`approvalSpec.validation`).
+
+**Agent validation routing:** a validator agent's verdict becomes a QA action — `PROCEED` (continue), `RETRY_CURRENT` (rerun this step with feedback), `ROLLBACK_PREVIOUS` (rerun an earlier step), or `RESTART_ALL` (restart the run) — bounded by the step's `retryPolicy.maxAttempts`.
+
+## 4. Running and narrating (the agent-as-UI protocol)
+
+Once a workflow validates, you are the UI for the run: start it detached, poll its state, and turn each transition into a short update instead of dumping raw JSON at the user.
+
+**Start it detached, with a session file:**
+
+```bash
+wfm run my-flow.md --session-file .wfm/session.json &
+```
+
+The session file is written the moment the attach API is listening — `{ baseUrl, attachToken, runId, pid, startedAt }` — and rewritten with `endedAt` + `status` when the run finishes. It is never deleted, so it doubles as your "is this still running" signal. Every attach command below accepts `--session-file .wfm/session.json` instead of separate `--url`/`--token`.
+
+**Poll on a cadence and narrate transitions**, not raw payloads:
+
+```bash
+wfm status --session-file .wfm/session.json
+```
+
+Read `status` and `currentStepKey` off the JSON, and translate: `"running"` + `currentStepKey: "implement-fix"` becomes something like *"step 1/3 (implement-fix) is running, attempt 1..."*. Don't re-poll faster than the work can plausibly progress — a few seconds between polls is usually plenty; back off further once a step has been running a while.
+
+**Use `events` for incremental detail** between polls instead of re-reading the whole snapshot:
+
+```bash
+wfm events --session-file .wfm/session.json --since 4
+```
+
+Track the last `nextSequence` you saw and pass it back as `--since` next time. Add `--include-logs` only when you actually want `agent.stdout`/`agent.stderr` chunks inline.
+
+**Use `logs` when the user asks what a step is doing right now:**
+
+```bash
+wfm logs --session-file .wfm/session.json --step implement-fix --limit 50
+```
+
+**Detect and handle `waitingForApproval`.** When `status`'s top-level `status` is `"waiting_for_approval"`, the JSON includes a `waitingForApproval` object with `stepKey`, `reason`, and a `preview` (`summary` plus `items` describing what's being reviewed, including dependency outputs). Summarize that preview for the user in plain language. Then either:
+
+- relay the decision the user gives you, or
+- if the user has explicitly delegated authority for this gate ("auto-approve the review steps," "you decide"), decide yourself and act:
+
+```bash
+wfm approve --session-file .wfm/session.json --step review-gate --note "why you approved"
+wfm cancel  --session-file .wfm/session.json --step review-gate --note "why you're stopping the run"
+```
+
+Never approve on the user's behalf without either their live input or a standing delegation they gave you for that specific gate — it is a QA checkpoint, not decoration.
+
+**On terminal status, report the outcome** by reading `endedAt` and `status` back from the session file (the run process has exited by then, so the attach API is gone — the session file is the only source left):
+
+```bash
+cat .wfm/session.json   # { ..., "endedAt": "...", "status": "succeeded" }
+```
+
+**Exit codes** (for the `wfm run` process itself, if you're waiting on it directly rather than polling): `0` — run succeeded; `2` — run finished but not successfully (failed, cancelled, or ended waiting); `1` — validation or runtime error before/during execution, not a normal terminal status.
+
+## 5. Repeatability rules
+
+- Never rename or remove a published workflow's step keys — other automation and history may reference them. Add new steps or a new workflow `key`/version instead of mutating shape in place.
+- `key` (workflow) and step `key`s are stable external identifiers; change them only deliberately, and treat it as a breaking change for anything that depends on them.
+- Keep `taskSpec.payload` deterministic — avoid embedding timestamps, random IDs, or environment-specific paths that would make two runs diverge for reasons unrelated to the actual task.
+- Prefer `validation.mode: agent` criteria that a validator can check as a fact about the output (tests pass, a file exists, a diff touches only expected paths) over criteria that require taste. Save taste calls for `approval` steps.
+
+## 6. Install/share
+
+```bash
+wfm skill install workflow-author                    # this skill -> ./.claude/skills/
+wfm skill install workflow-author --agent opencode    # -> ./.opencode/skill/
+wfm skill install workflow-author --global            # -> ~/.claude/skills/
+```
+
+To share the workflow *file* itself (not this skill) with teammates, use the remote registry — `wfm publish my-flow.md` / `wfm pull owner/slug`; see the `workflow-manager-cli` skill and `doc/guide/` for the full registry contract.
+
+## Worked example
+
+A repeatable "fix a flaky test" workflow: an agent-validated implementation step, a human sign-off gate, then a finalize step. Validated on this branch with `wfm validate` (`Validation OK`) and executed end-to-end with the mock adapter.
+
+```yaml
+---
+key: fix-flaky-login-test
+title: Fix Flaky Login Test
+description: Diagnose and fix an intermittently failing login test, with a human sign-off before landing the fix
+objectives:
+  - the login test passes reliably and the fix is reviewed before merge
+defaultRetryPolicy:
+  maxAttempts: 2
+steps:
+  - key: implement-fix
+    kind: task
+    objective: Reproduce the flake in tests/login.test.ts, diagnose the root cause, and fix it
+    dependsOn: []
+    retryPolicy:
+      maxAttempts: 2
+    validation:
+      mode: agent
+      required: true
+      autoConfirm: false
+      agent:
+        criteria: >-
+          tests/login.test.ts passes 20 consecutive local runs, the fix
+          addresses a root cause (not a retry/sleep workaround), and no
+          unrelated files changed.
+        init:
+          model: openrouter/anthropic/claude-sonnet-4
+          systemPrompts:
+            - Check the diff against the criteria; call out any retry/sleep workaround explicitly
+    taskSpec:
+      adapterKey: mock
+      init:
+        context:
+          repo: example/webapp
+        skills: [debugging, testing]
+        systemPrompts: [Find the root cause before writing a fix; add a regression test]
+      payload:
+        mockResult: success
+  - key: review-gate
+    kind: approval
+    objective: Human sign-off on the fix before it merges
+    dependsOn: [implement-fix]
+    # validation must be set here too, not just under approvalSpec — an unset
+    # step.validation defaults to autoConfirm: true, which would silently skip
+    # this gate. See the schema cheat-sheet above.
+    validation:
+      mode: human
+      required: true
+      autoConfirm: false
+    approvalSpec:
+      autoApprove: false
+      validation:
+        mode: human
+        required: true
+        autoConfirm: false
+  - key: finalize
+    kind: task
+    objective: Open a PR with the fix, the regression test, and a summary of the root cause
+    dependsOn: [review-gate]
+    validation:
+      mode: none
+      required: false
+      autoConfirm: true
+    taskSpec:
+      adapterKey: mock
+      init:
+        systemPrompts: [Open a PR summarizing the root cause, the fix, and the new regression test]
+      payload:
+        mockResult: success
+---
+
+# Fix Flaky Login Test
+
+Repeatable workflow for chasing down a flaky test: implement a fix (agent-validated
+against explicit, checkable criteria), get a human sign-off, then finalize.
+```
+
+### Simulated narration transcript
+
+```
+$ wfm run fix-flaky-login-test.md --session-file .wfm/session.json &
+Attach API: http://127.0.0.1:43121 (token b354...)
+
+[agent] Started the workflow in the background — I'll check in as it progresses.
+
+$ wfm status --session-file .wfm/session.json
+{"status":"running","currentStepKey":"implement-fix", ...}
+
+[agent] step 1/3 (implement-fix) is running, attempt 1 — reproducing the flake and writing a fix.
+
+$ wfm status --session-file .wfm/session.json
+{"status":"waiting_for_approval","currentStepKey":"review-gate",
+ "waitingForApproval":{"stepKey":"review-gate",
+   "reason":"confirmation required for review-gate",
+   "preview":{"summary":"Approve this gate to continue after implement-fix.",
+     "items":[{"title":"Dependency implement-fix","status":"succeeded",
+       "summary":"Reproduce the flake in tests/login.test.ts, diagnose the root cause, and fix it"}]}}}
+
+[agent] implement-fix passed agent validation (tests green, real root-cause fix,
+no unrelated files touched) and is now waiting on you: review-gate wants a
+human sign-off before finalize runs. Want me to look at the diff summary, or
+are you approving as-is?
+
+[user] approve it
+
+$ wfm approve --session-file .wfm/session.json --step review-gate --note "Fix looks correct, root cause addressed"
+approved review-gate
+
+[agent] Approved review-gate. finalize is running now (opening the PR)...
+
+$ cat .wfm/session.json
+{ ..., "endedAt": "2026-07-11T13:35:40.756Z", "status": "succeeded" }
+
+[agent] Done — the workflow succeeded. implement-fix and finalize both ran
+clean, and your sign-off on review-gate is recorded in the run's approval
+audit trail.
+```