@workflow-manager/runner 0.3.0 → 0.4.1

package/README.md

@@ -9,7 +9,7 @@ The core ideas:
 - **The envelope protocol.** Every step execution returns a structured result: an execution status (`SUCCESS`, `FAILED`, `QA_REJECTED`, `YIELD_EXTERNAL`) plus a QA routing action (`PROCEED`, `RETRY_CURRENT`, `ROLLBACK_PREVIOUS`, `RESTART_ALL`). That's what lets the engine retry a step, roll back to the previous one, or restart the whole run based on what the agent reported.
 - **Human-in-the-loop control.** While a run is active, wfm starts a local HTTP attach API (token-protected, with SSE event streaming), so a waiting step can be resolved either in the terminal prompt or from another shell with `wfm approve` / `wfm resume` / `wfm cancel`.
 - **A registry.** `wfm publish` / `pull` / `search` / `auth` talk to a Supabase-backed remote registry (the `apps/remote-registry` web app in this repo) for sharing workflows, with skills bundled and SHA-256 verified. Runs also emit opt-in telemetry there.
-- **Supporting commands.** `wfm scaffold` writes a starter workflow, `wfm validate` checks the schema and dependency cycles, `wfm doctor` verifies the host has the needed CLIs and API keys before a run, `wfm agent` drops an AGENTS.md rules file, and `wfm man` shows the man page.
+- **Supporting commands.** `wfm scaffold` writes a starter workflow, `wfm validate` checks the schema and dependency cycles, `wfm doctor` verifies the host has the needed CLIs and API keys before a run, `wfm skill install` installs the bundled agent skills into Claude Code or opencode skill directories, and `wfm man` shows the man page.
 
 Install the latest prebuilt CLI with:
 
@@ -31,7 +31,7 @@ If `wfm` is not available immediately in the same terminal, run the shell reload
 
 ## Architecture
 
-- `src/index.ts`: CLI commands (`doctor`, `agent`, `scaffold`, `validate`, `run`)
+- `src/index.ts`: CLI commands (`doctor`, `skill`, `scaffold`, `validate`, `run`)
 - `src/parser.ts`: parsing + validation
 - `src/engine.ts`: execution loop, confirmations, retries, rollback/restart
 - `src/piAgentExecutor.ts`: default executor driving the `pi` coding agent CLI
@@ -51,7 +51,7 @@ bun run build
 bun link
 
 wfm doctor
-wfm agent ./AGENTS.md
+wfm skill install
 wfm scaffold ./example-workflow.md
 wfm validate ./example-workflow.md
 wfm doctor ./example-workflow.md
@@ -214,10 +214,11 @@ Manual help:
 wfm man
 ```
 
-Agent rules:
+Agent skills:
 
 ```bash
-wfm agent ./AGENTS.md
+wfm skill list
+wfm skill install
 ```
 
 Remote registry commands:
@@ -230,13 +231,20 @@ wfm remote info alice/remote-bunny
 
 ## Agent skills
 
-The published `@workflow-manager/runner` npm package now ships the CLI runner and the bundled agent skills together.
+The published `@workflow-manager/runner` npm package ships the CLI runner and the bundled agent skills together. The primary skill is `skills/workflow-manager-cli/SKILL.md`, which teaches an agent how to configure, author, run, and publish workflows with `wfm`.
 
-- bundled skill: `skills/workflow-manager-cli/SKILL.md`
-- discovery keyword: `tanstack-intent`
-- install flow: install `@workflow-manager/runner`, then run `npx @tanstack/intent@latest list` and `npx @tanstack/intent@latest install`
+Install skills with the CLI:
 
-Example usage:
+```bash
+wfm skill list                       # show bundled skills
+wfm skill install                    # workflow-manager-cli -> ./.claude/skills/
+wfm skill install --global           # -> ~/.claude/skills/
+wfm skill install --agent opencode   # -> ./.opencode/skill/
+wfm skill install --all              # install every bundled skill
+wfm skill install doc-sync --dir ./my/skills
+```
+
+TanStack Intent discovery is also supported (package keyword `tanstack-intent`):
 
 ```bash
 npm install @workflow-manager/runner

package/dist/engine.js

@@ -6,7 +6,7 @@ import { executeClaudeCodeStep, shouldUseRealClaudeCode } from "./claudeCodeExec
 import { executeMockStep } from "./mockExecutor.js";
 import { executeOpencodeStep, shouldUseRealOpencode } from "./opencodeExecutor.js";
 import { executePiAgentStep } from "./piAgentExecutor.js";
-import { validateRuntimeRequirements } from "./runtimePreflight.js";
+import { adapterMockFallbackReason, validateRuntimeRequirements } from "./runtimePreflight.js";
 function nodeType(step) {
     if (step.kind === "approval")
         return "HUMAN";
@@ -302,6 +302,10 @@ async function executeStep(step, input, attempt, workflow, workflowFilePath, hoo
     if (adapterKey === "claude-code" && shouldUseRealClaudeCode(step)) {
         return executeClaudeCodeStep(step, input, attempt, workflow, workflowFilePath, hooks);
     }
+    const fallbackReason = adapterMockFallbackReason(step);
+    if (fallbackReason) {
+        hooks?.onStderr?.(`[wfm] ${step.key}: ${fallbackReason}\n`);
+    }
     return executeMockStep(step, input, attempt, hooks);
 }
 export async function runWorkflow(definition, options) {

package/dist/index.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import matter from "gray-matter";
 import { CliRunRenderer } from "./cliRunRenderer.js";
 import { startRunnerApiServer } from "./runnerApi.js";
 import { RunnerSessionStore } from "./runnerSession.js";
@@ -13,7 +14,7 @@ import { MAN_PAGE_SOURCE } from "./manPage.js";
 import { promptForApprovalDecision, runWorkflow } from "./engine.js";
 import { cmdAuth, cmdPublish, cmdPull, cmdRemoteInfo, cmdSearch } from "./remote/commands.js";
 import { emitRunTelemetryBestEffort } from "./remote/telemetry.js";
-import { adapterImplementationStatuses, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
+import { adapterImplementationStatuses, adapterMockFallbackWarnings, runtimeDoctorChecks, validateRuntimeRequirements, } from "./runtimePreflight.js";
 function cliDisplayName() {
     const invokedAs = path.basename(process.argv[1] ?? "");
     if (invokedAs === "workflow-manager" || invokedAs === "wfm") {
@@ -25,7 +26,8 @@ function usage() {
     const cli = cliDisplayName();
     console.log(`${cli} commands:
   doctor [workflow.md|workflow.json] [--json]
-  agent [path] [--force]
+  skill list
+  skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]
   scaffold [path] [--format markdown|json]
   validate <workflow.md|workflow.json>
   run <workflow.md|workflow.json> [--input input.json] [--objective "string"] [--confirm stepA,stepB:human] [--auto-confirm-all] [--port 43121] [--verbose] [--json]
@@ -248,36 +250,6 @@ steps:
 
 Edit frontmatter to configure orchestration behavior.
 `;
-const AGENT_RULES_TEMPLATE = `# WFM Agent Rules
-
-Use these rules when creating, validating, running, or publishing workflow-manager workflows with the \`wfm\` CLI.
-
-## Core Flow
-
-1. Start with \`wfm doctor\` to inspect local adapter and API key setup.
-2. Create a starter workflow with \`wfm scaffold ./workflow.md\` or \`wfm scaffold ./workflow.json --format json\`.
-3. Edit stable workflow keys, step objectives, dependencies, validation modes, and adapter initialization.
-4. Run \`wfm validate <workflow>\` before every run or publish.
-5. Run \`wfm doctor <workflow>\` before using real host-backed adapters.
-6. Run with \`wfm run <workflow>\`; use \`--verbose\` when agent logs are needed.
-7. Publish only after validation succeeds with \`wfm publish <workflow>\`.
-
-## Workflow Authoring
-
-- Keep workflow, step, and adapter keys stable; external tools and tests may reference them.
-- Omit \`taskSpec.adapterKey\` for the default \`pi-agent\` adapter.
-- Use \`adapterKey: mock\` for deterministic tests and examples.
-- Put skills, MCP endpoints, system prompts, model, and context under \`taskSpec.init\`.
-- Model-backed steps should declare required environment variables through provider-specific model names or \`taskSpec.payload.requiredEnv\`.
-- Human or external validation should be explicit in the workflow file.
-
-## Running Safely
-
-- Do not use \`--auto-confirm-all\` unless the workflow is intentionally non-interactive.
-- Prefer \`wfm doctor <workflow>\` before runs that use \`pi-agent\`, real \`opencode\`, or real \`claude-code\`.
-- Use the attach API output from \`wfm run\` for approval, resume, and cancel commands.
-- Preserve Markdown workflows when humans will review notes; use JSON for generated or machine-edited workflows.
-`;
 function resolveScaffoldFormat(targetPath, explicitFormat) {
     if (explicitFormat === "markdown" || explicitFormat === "json") {
         return explicitFormat;
@@ -300,29 +272,138 @@ function parseScaffoldArgs(args) {
     }
     return { targetPath, format };
 }
-function parseAgentArgs(args) {
-    let targetPath;
-    let force = false;
-    for (const arg of args) {
+const DEFAULT_INSTALL_SKILL = "workflow-manager-cli";
+const SKILL_INSTALL_TARGETS = {
+    claude: {
+        projectDir: path.join(".claude", "skills"),
+        globalDir: path.join(os.homedir(), ".claude", "skills"),
+    },
+    opencode: {
+        projectDir: path.join(".opencode", "skill"),
+        globalDir: path.join(os.homedir(), ".config", "opencode", "skill"),
+    },
+};
+function packagedSkillsDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "skills");
+}
+function listPackagedSkills() {
+    const root = packagedSkillsDir();
+    if (!fs.existsSync(root)) {
+        return [];
+    }
+    const skills = [];
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        const skillFile = path.join(dir, "SKILL.md");
+        if (!fs.existsSync(skillFile))
+            continue;
+        let description = "";
+        try {
+            const parsed = matter(fs.readFileSync(skillFile, "utf-8"));
+            if (typeof parsed.data.description === "string") {
+                description = parsed.data.description.replace(/\s+/g, " ").trim();
+            }
+        }
+        catch {
+            // skills without parseable frontmatter are still installable
+        }
+        skills.push({ name: entry.name, dir, description });
+    }
+    return skills;
+}
+function cmdSkillList() {
+    const skills = listPackagedSkills();
+    if (skills.length === 0) {
+        console.error(`No bundled skills found at ${packagedSkillsDir()}.`);
+        return 1;
+    }
+    console.log("Bundled skills:\n");
+    for (const skill of skills) {
+        console.log(`  ${skill.name}`);
+        if (skill.description) {
+            console.log(`      ${skill.description}`);
+        }
+    }
+    console.log(`\nInstall with: ${cliDisplayName()} skill install <name> [--agent claude|opencode] [--global]`);
+    return 0;
+}
+function parseSkillInstallArgs(args) {
+    const parsed = { names: [], agent: "claude", global: false, force: false, all: false };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--agent") {
+            parsed.agent = args[i + 1] ?? "";
+            i += 1;
+            continue;
+        }
+        if (arg === "--dir") {
+            parsed.dir = args[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === "--global" || arg === "-g") {
+            parsed.global = true;
+            continue;
+        }
         if (arg === "--force" || arg === "-f") {
-            force = true;
+            parsed.force = true;
             continue;
         }
-        if (!arg.startsWith("-") && !targetPath) {
-            targetPath = arg;
+        if (arg === "--all") {
+            parsed.all = true;
+            continue;
         }
+        if (!arg.startsWith("-")) {
+            parsed.names.push(arg);
+        }
+    }
+    return parsed;
+}
+function resolveSkillInstallRoot(args) {
+    if (args.dir) {
+        return path.resolve(args.dir);
     }
-    return { targetPath, force };
+    const target = SKILL_INSTALL_TARGETS[args.agent];
+    if (!target) {
+        return undefined;
+    }
+    return args.global ? target.globalDir : path.resolve(target.projectDir);
 }
-function cmdAgent(targetPath, force = false) {
-    const resolvedPath = path.resolve(targetPath ?? "./AGENTS.md");
-    if (fs.existsSync(resolvedPath) && !force) {
-        console.error(`Agent rules already exist at ${resolvedPath}. Pass --force to overwrite.`);
+function cmdSkillInstall(args) {
+    const parsed = parseSkillInstallArgs(args);
+    const targetRoot = resolveSkillInstallRoot(parsed);
+    if (!targetRoot) {
+        console.error(`Unknown --agent value: ${parsed.agent}. Supported agents: ${Object.keys(SKILL_INSTALL_TARGETS).join(", ")}. Use --dir for any other destination.`);
         return 1;
     }
-    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
-    fs.writeFileSync(resolvedPath, AGENT_RULES_TEMPLATE, "utf-8");
-    console.log(`Wrote WFM agent rules: ${resolvedPath}`);
+    const available = listPackagedSkills();
+    const names = parsed.all
+        ? available.map((skill) => skill.name)
+        : parsed.names.length > 0
+            ? parsed.names
+            : [DEFAULT_INSTALL_SKILL];
+    for (const name of names) {
+        const skill = available.find((candidate) => candidate.name === name);
+        if (!skill) {
+            console.error(`Unknown skill: ${name}. Run \`${cliDisplayName()} skill list\` to see bundled skills.`);
+            return 1;
+        }
+        const destDir = path.join(targetRoot, name);
+        const destFile = path.join(destDir, "SKILL.md");
+        if (fs.existsSync(destFile) && !parsed.force) {
+            console.error(`Skill already installed at ${destFile}. Pass --force to overwrite.`);
+            return 1;
+        }
+        fs.mkdirSync(destDir, { recursive: true });
+        for (const entry of fs.readdirSync(skill.dir, { withFileTypes: true })) {
+            if (!entry.isFile() || entry.name === "README.md")
+                continue;
+            fs.copyFileSync(path.join(skill.dir, entry.name), path.join(destDir, entry.name));
+        }
+        console.log(`Installed skill ${name} -> ${destDir}`);
+    }
     return 0;
 }
 function cmdScaffold(targetPath, format) {
@@ -405,12 +486,14 @@ function cmdDoctor(args) {
     let workflow = null;
     let workflowErrors = [];
     let runtimeErrors = [];
+    let adapterWarnings = [];
     if (workflowPath) {
         try {
             workflow = parseWorkflowFile(path.resolve(workflowPath));
             workflowErrors = validateWorkflow(workflow);
             if (workflowErrors.length === 0) {
                 runtimeErrors = validateRuntimeRequirements(workflow);
+                adapterWarnings = adapterMockFallbackWarnings(workflow);
             }
         }
         catch (err) {
@@ -434,6 +517,7 @@ function cmdDoctor(args) {
                     title: workflow.title,
                     errors: workflowErrors,
                     runtimeErrors,
+                    adapterWarnings,
                 }
                 : null,
             baselineErrors,
@@ -467,6 +551,12 @@ function cmdDoctor(args) {
         else {
             console.log("- OK workflow schema and runtime requirements");
         }
+        if (adapterWarnings.length > 0) {
+            console.log("\nAdapter warnings:");
+            for (const warning of adapterWarnings) {
+                console.log(`- ${warning.stepKey}: ${warning.message}`);
+            }
+        }
     }
     return exitCode;
 }
@@ -548,6 +638,9 @@ async function cmdRun(filePath) {
             });
             return 1;
         }
+        for (const warning of adapterMockFallbackWarnings(workflow)) {
+            process.stderr.write(`⚠ ${warning.stepKey}: ${warning.message}\n`);
+        }
         const objective = getFlag("--objective");
         const inputRaw = getFlag("--input");
         let input = {};
@@ -677,9 +770,16 @@ async function main() {
     if (cmd === "doctor") {
         process.exit(cmdDoctor(process.argv.slice(3)));
     }
-    if (cmd === "agent") {
-        const { targetPath, force } = parseAgentArgs(process.argv.slice(3));
-        process.exit(cmdAgent(targetPath, force));
+    if (cmd === "skill") {
+        const sub = process.argv[3];
+        if (sub === "list") {
+            process.exit(cmdSkillList());
+        }
+        if (sub === "install") {
+            process.exit(cmdSkillInstall(process.argv.slice(4)));
+        }
+        usage();
+        process.exit(1);
     }
     if (cmd === "scaffold") {
         const { targetPath, format } = parseScaffoldArgs(process.argv.slice(3));

package/dist/manPage.d.ts

@@ -1 +1 @@
-export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B agent [path] [--force]\nCreate WFM-focused agent rules. The default path is ./AGENTS.md. Existing files are not overwritten unless --force is passed.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nCreate agent rules:\n.B wfm agent ./AGENTS.md\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";
+export declare const MAN_PAGE_SOURCE = ".TH WFM 1 \"April 2026\" \"@workflow-manager/runner\" \"User Commands\"\n.SH NAME\nwfm \\- run markdown or json workflows from the CLI\n.SH SYNOPSIS\n.B wfm\n.I command\n[options]\n.SH DESCRIPTION\nwfm parses a workflow definition file, validates it, and executes\nit with deterministic in-memory orchestration.\n\nWorkflow files can be Markdown with YAML frontmatter or JSON.\n.SH COMMANDS\n.TP\n.B doctor [workflow.md|workflow.json] [--json]\nInspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.\n.TP\n.B skill list\nList the agent skills bundled with the npm package.\n.TP\n.B skill install [name ...] [--agent claude|opencode] [--global] [--dir path] [--all] [--force]\nInstall 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.\n.TP\n.B scaffold [path] [--format markdown|json]\nCreate a starter workflow file. Format defaults to markdown unless the output\npath ends in .json.\n.TP\n.B validate <workflow.md|workflow.json>\nValidate workflow structure and report schema errors.\n.TP\n.B run <workflow.md|workflow.json> [--input input.json] [--objective text] [--confirm list] [--auto-confirm-all] [--port number] [--verbose] [--json]\nRun the workflow with live CLI progress and optional JSON output.\n.TP\n.B approve [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nApprove the current waiting runner step through the local attach API.\n.TP\n.B resume [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nAlias for approve, intended for external resume flows.\n.TP\n.B cancel [--url value] [--token value] [--run-id value] [--step value] [--actor value] [--note text]\nCancel the current waiting runner step through the local attach API.\n.TP\n.B auth <login|whoami|logout> [--token value]\nManage remote registry authentication for CLI publish and pull flows.\n.TP\n.B publish <workflow.md|workflow.json> [--slug slug] [--title text] [--description text] [--visibility public|private] [--version label] [--tag a,b] [--draft]\nPublish a validated local workflow to the remote registry.\n.TP\n.B pull <owner/slug> [--version label] [--output path]\nDownload a remote workflow and write it to a local file.\n.TP\n.B search [query]\nSearch public workflows from the remote registry.\n.TP\n.B remote info <owner/slug>\nShow metadata and source information for a remote workflow.\n.TP\n.B man\nOpen this man page.\n.SH RUN OPTIONS\n.TP\n.B --input <path>\nJSON file merged into global workflow input state.\n.TP\n.B --objective <text>\nOverride the default run objective.\n.TP\n.B --confirm <stepA,stepB:human,...>\nProvide explicit confirmations for steps that require validation.\n.TP\n.B --auto-confirm-all\nBypass confirmation gating for all steps.\n.TP\n.B --port <number>\nBind the local attach API to a specific port. If omitted, the OS assigns a free port on 127.0.0.1.\n.TP\n.B --verbose\nStream per-step agent output and execution updates to stderr while the workflow runs.\n.TP\n.B --json\nPrint the final run result as JSON on stdout while keeping live progress on stderr.\n.TP\nHuman approval steps in an interactive terminal show an inline review prompt so they can be approved or cancelled without a separate HTTP client.\n.TP\n.B --url <value>\nRunner attach API base URL for approve, resume, or cancel commands.\n.TP\n.B --token <value>\nRunner attach API bearer token for approve, resume, or cancel commands.\n.TP\n.B --run-id <value>\nRunner id to control. If omitted, the CLI reads it from /session.\n.TP\n.B --step <value>\nOptional step key when controlling a specific waiting step.\n.TP\n.B --actor <value>\nActor name recorded in approval audit events.\n.TP\n.B --note <text>\nOptional approval or cancellation note recorded in the event payload.\n.SH EXAMPLES\n.TP\nValidate markdown workflow:\n.B wfm validate ./example-workflow.md\n.TP\nValidate json workflow:\n.B wfm validate ./example-workflow.json\n.TP\nScaffold json workflow file:\n.B wfm scaffold ./new-workflow.json --format json\n.TP\nAuthenticate with a CLI token:\n.B wfm auth login --token wm_exampletoken\n.TP\nPublish a workflow:\n.B wfm publish ./example-workflow.json --visibility public --tag example,automation\n.TP\nPull a remote workflow:\n.B wfm pull alice/remote-bunny --output ./remote-bunny.json\n.TP\nSearch the remote registry:\n.B wfm search bunny\n.TP\nRun with explicit confirmations:\n.B wfm run ./example-workflow.json --confirm discover:human,qa_gate:human\n.TP\nInspect host setup:\n.B wfm doctor\n.TP\nCheck a workflow before running it:\n.B wfm doctor ./example-workflow.json\n.TP\nInstall the bundled CLI skill for Claude Code:\n.B wfm skill install\n.TP\nInstall every bundled skill globally:\n.B wfm skill install --all --global\n.SH FILES\n.TP\n.B man/wfm.1\nThe manual page source shipped with this repository.\n.SH EXIT STATUS\n.TP\n.B 0\nSuccessful command execution.\n.TP\n.B 1\nValidation or runtime error.\n.TP\n.B 2\nRun completed in non-success terminal status.\n";

package/dist/manPage.js

@@ -15,8 +15,11 @@ Workflow files can be Markdown with YAML frontmatter or JSON.
 .B doctor [workflow.md|workflow.json] [--json]
 Inspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.
 .TP
-.B agent [path] [--force]
-Create WFM-focused agent rules. The default path is ./AGENTS.md. Existing files are not overwritten unless --force is passed.
+.B skill list
+List the agent skills bundled with the npm package.
+.TP
+.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]
 Create a starter workflow file. Format defaults to markdown unless the output
@@ -128,8 +131,11 @@ Inspect host setup:
 Check a workflow before running it:
 .B wfm doctor ./example-workflow.json
 .TP
-Create agent rules:
-.B wfm agent ./AGENTS.md
+Install the bundled CLI skill for Claude Code:
+.B wfm skill install
+.TP
+Install every bundled skill globally:
+.B wfm skill install --all --global
 .SH FILES
 .TP
 .B man/wfm.1

package/dist/runtimePreflight.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterKey, WorkflowDefinition } from "./types.js";
+import type { AdapterKey, StepDefinition, WorkflowDefinition } from "./types.js";
 export interface RuntimeDoctorCheck {
     key: string;
     label: string;
@@ -13,4 +13,19 @@ export interface AdapterImplementationStatus {
 }
 export declare function validateRuntimeRequirements(definition: WorkflowDefinition, env?: NodeJS.ProcessEnv): string[];
 export declare function runtimeDoctorChecks(env?: NodeJS.ProcessEnv): RuntimeDoctorCheck[];
+export interface AdapterMockFallbackWarning {
+    stepKey: string;
+    adapter: AdapterKey;
+    message: string;
+}
+/**
+ * Detects a step that explicitly selects a host-backed adapter whose real
+ * execution path is gated behind opt-in payload flags that are not set. Without
+ * those flags the engine routes the step to the mock executor; returning a
+ * message here lets callers warn instead of silently mocking. Returns null when
+ * the step will run as the user expects (default pi-agent, an enabled real
+ * adapter, or an intentional mock/codex selection).
+ */
+export declare function adapterMockFallbackReason(step: StepDefinition): string | null;
+export declare function adapterMockFallbackWarnings(definition: WorkflowDefinition): AdapterMockFallbackWarning[];
 export declare function adapterImplementationStatuses(): AdapterImplementationStatus[];

package/dist/runtimePreflight.js

@@ -158,6 +158,37 @@ export function runtimeDoctorChecks(env = process.env) {
         envCheck("anthropic-key", "Anthropic API key", "ANTHROPIC_API_KEY", env),
     ];
 }
+/**
+ * Detects a step that explicitly selects a host-backed adapter whose real
+ * execution path is gated behind opt-in payload flags that are not set. Without
+ * those flags the engine routes the step to the mock executor; returning a
+ * message here lets callers warn instead of silently mocking. Returns null when
+ * the step will run as the user expects (default pi-agent, an enabled real
+ * adapter, or an intentional mock/codex selection).
+ */
+export function adapterMockFallbackReason(step) {
+    if (step.kind !== "task" || !step.taskSpec?.adapterKey) {
+        return null;
+    }
+    const adapter = resolveTaskAdapter(step.taskSpec.adapterKey);
+    if (adapter === "claude-code" && !shouldUseRealClaudeCode(step)) {
+        return "adapterKey 'claude-code' is set, but the real Claude Code CLI path is off, so the step runs as a mock. Set taskSpec.payload.useRealAdapter: true to drive the real `claude` CLI.";
+    }
+    if (adapter === "opencode" && !shouldUseRealOpencode(step)) {
+        return "adapterKey 'opencode' is set, but the real OpenCode CLI path is off, so the step runs as a mock. Set taskSpec.payload.useRealAdapter: true and taskSpec.payload.opencodeSmokeTest: true to drive the real `opencode` CLI.";
+    }
+    return null;
+}
+export function adapterMockFallbackWarnings(definition) {
+    const warnings = [];
+    for (const step of definition.steps) {
+        const message = adapterMockFallbackReason(step);
+        if (message) {
+            warnings.push({ stepKey: step.key, adapter: resolveTaskAdapter(step.taskSpec?.adapterKey), message });
+        }
+    }
+    return warnings;
+}
 export function adapterImplementationStatuses() {
     return [
         {

package/man/wfm.1

@@ -15,8 +15,11 @@ Workflow files can be Markdown with YAML frontmatter or JSON.
 .B doctor [workflow.md|workflow.json] [--json]
 Inspect host adapter setup, LLM access keys, and current adapter implementation status. When a workflow path is provided, also validate schema and runtime requirements without executing steps.
 .TP
-.B agent [path] [--force]
-Create WFM-focused agent rules. The default path is ./AGENTS.md. Existing files are not overwritten unless --force is passed.
+.B skill list
+List the agent skills bundled with the npm package.
+.TP
+.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]
 Create a starter workflow file. Format defaults to markdown unless the output
@@ -128,8 +131,11 @@ Inspect host setup:
 Check a workflow before running it:
 .B wfm doctor ./example-workflow.json
 .TP
-Create agent rules:
-.B wfm agent ./AGENTS.md
+Install the bundled CLI skill for Claude Code:
+.B wfm skill install
+.TP
+Install every bundled skill globally:
+.B wfm skill install --all --global
 .SH FILES
 .TP
 .B man/wfm.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-manager/runner",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes",
   "repository": {
     "type": "git",

package/skills/README.md

@@ -18,7 +18,21 @@ Install the main package in the project where you want the CLI and skill availab
 npm install @workflow-manager/runner
 ```
 
-Then use TanStack Intent to discover and map the shipped skill into your agent configuration:
+Then install bundled skills into an agent's skill directory with the CLI:
+
+```bash
+wfm skill list                       # list bundled skills
+wfm skill install                    # workflow-manager-cli -> ./.claude/skills/
+wfm skill install --global           # -> ~/.claude/skills/
+wfm skill install --agent opencode   # -> ./.opencode/skill/
+wfm skill install --all              # install every bundled skill
+wfm skill install <name> --dir path  # install into any directory
+```
+
+`wfm skill install` copies the skill directory (`SKILL.md` plus any assets) into the
+target so the agent loads it on demand; pass `--force` to overwrite an existing install.
+
+Alternatively, use TanStack Intent to discover and map the shipped skills into your agent configuration:
 
 ```bash
 npx @tanstack/intent@latest list

package/skills/workflow-manager-cli/SKILL.md

@@ -1,116 +1,181 @@
 ---
-name: @workflow-manager/runner/cli
+name: workflow-manager-cli
 description: >
-  Load this skill when working with the wfm CLI from @workflow-manager/runner, authoring or
-  validating workflow definitions, configuring step skills and adapters, or
-  publishing workflows to the remote registry. Covers doctor, agent, scaffold,
-  validate, run, auth, publish, pull, search, and remote info.
+  Load this skill when working with the wfm CLI from @workflow-manager/runner:
+  authoring, validating, or running workflow definitions, configuring adapters
+  and step skills, controlling runs through the attach API, or publishing
+  workflows to the remote registry. Covers doctor, skill, scaffold, validate,
+  run, approve, resume, cancel, auth, publish, pull, search, and remote info.
 type: core
-library: @workflow-manager/runner
-library_version: "0.1.0"
+library: "@workflow-manager/runner"
 sources:
   - "navio/workflow-manager:README.md"
   - "navio/workflow-manager:src/index.ts"
   - "navio/workflow-manager:src/parser.ts"
   - "navio/workflow-manager:src/engine.ts"
+  - "navio/workflow-manager:src/runtimePreflight.ts"
+  - "navio/workflow-manager:src/skillResolver.ts"
   - "navio/workflow-manager:src/remote/commands.ts"
+  - "navio/workflow-manager:doc/guide/runner-api.md"
 ---
 
 # wfm CLI
 
-Use this skill when you need to create or operate `workflow-manager` workflows from the terminal with `wfm`.
+`wfm` (also installed as `workflow-manager`) parses a workflow definition file (Markdown frontmatter or JSON), validates it, and executes its steps through pluggable agent adapters with deterministic dependency ordering, approvals, retries, and rollback routing.
 
-## When to use this skill
+## Core flow
 
-Use it when the user wants to:
+Follow this sequence unless the user asks for a narrower task:
 
-- scaffold a new workflow definition
-- create local agent rules for WFM usage
-- validate or run a workflow file
-- configure approvals, retry policy, or adapter initialization
-- publish a workflow to the remote registry
-- search for or pull a shared workflow
-- understand the difference between Markdown and JSON workflow formats
+1. `wfm doctor` — inspect host adapter binaries and provider API keys.
+2. `wfm scaffold ./workflow.md` (or `--format json`) — generate a starter definition.
+3. Edit step keys, objectives, `dependsOn`, validation modes, and `taskSpec.init`.
+4. `wfm validate ./workflow.md` — always validate before running or publishing.
+5. `wfm doctor ./workflow.md` — preflight the specific workflow before real adapter runs.
+6. `wfm run ./workflow.md` — execute with live progress; add `--verbose` for agent output.
+7. `wfm publish ./workflow.md` — only after validation succeeds.
 
-## Core workflow
+## Command reference
 
-Use this sequence unless the user asks for a narrower task:
+```bash
+wfm doctor [workflow] [--json]        # host + per-workflow preflight checks
+wfm skill list                        # list skills bundled with the npm package
+wfm skill install [name ...]          # install bundled skills for an agent (see below)
+wfm scaffold [path] [--format markdown|json]
+wfm validate <workflow>
+wfm run <workflow> [--input input.json] [--objective "text"] [--confirm stepA,stepB:human] [--auto-confirm-all] [--port 43121] [--verbose] [--json]
+wfm approve|resume|cancel [--url ...] [--token ...] [--run-id ...] [--step ...] [--actor ...] [--note ...]
+wfm auth <login|whoami|logout> [--token <token>]
+wfm publish <workflow> [--slug s] [--title t] [--description d] [--visibility public|private] [--version v] [--tag a,b] [--draft]
+wfm pull <owner/slug> [--version v] [--output path]
+wfm search [query]
+wfm remote info <owner/slug>
+wfm man
+```
 
-1. Inspect local setup with `wfm doctor`
-2. Create project agent rules with `wfm agent` when local agent guidance is useful
-3. Scaffold a starter file with `wfm scaffold`
-4. Edit the workflow definition
-5. Validate the file with `wfm validate`
-6. Execute it with `wfm run`
-7. If needed, authenticate and publish with the remote registry commands
+Exit codes: `0` success, `1` validation or runtime error, `2` run finished in a non-success terminal status.
 
-## Local workflow commands
+## Host configuration
 
-```bash
-wfm doctor
-wfm agent ./AGENTS.md
+Adapters (set per step via `taskSpec.adapterKey`; omit for the default):
 
-wfm scaffold ./example-workflow.md
-wfm scaffold ./example-workflow.json --format json
+| Adapter | Kind | Notes |
+| --- | --- | --- |
+| `pi-agent` | real (default) | Drives the host `pi` coding agent CLI in print mode. `pi` must be on `PATH`; its auth lives in `~/.pi`, not env vars. |
+| `opencode` | real (opt-in) | Requires the `opencode` CLI on `PATH`. |
+| `claude-code` | real (opt-in) | Requires the `claude` CLI on `PATH`. |
+| `codex` | mock-routed | Deterministic simulation. |
+| `mock` | mock | Deterministic simulation for tests and examples. |
 
-wfm validate ./example-workflow.md
-wfm validate ./example-workflow.json
+Provider API keys are inferred from `taskSpec.init.model` and checked by `wfm doctor` / run preflight:
 
-wfm run ./example-workflow.md --confirm discover,qa_gate:human
-wfm run ./example-workflow.json --auto-confirm-all
-```
+- `openrouter/...` → `OPENROUTER_API_KEY`
+- `openai/...`, `gpt-...` → `OPENAI_API_KEY`
+- `anthropic/...`, `claude-...` → `ANTHROPIC_API_KEY`
 
-## Remote registry commands
+Steps can also declare extra required env vars in `taskSpec.payload.requiredEnv`.
 
-```bash
-wfm auth login --token <token>
-wfm auth whoami
-wfm auth logout
+For custom `pi-agent` commands, the run directory exposes `input.json` / `output.json` envelopes through the `WFM_PI_INPUT_FILE` and `WFM_PI_OUTPUT_FILE` env vars.
 
-wfm search bunny
-wfm remote info alice/remote-bunny
-wfm publish ./example-workflow.json --visibility public --tag storytelling,example
-wfm pull alice/remote-bunny --output ./remote-bunny.json
+## Workflow anatomy
+
+Both formats describe the same schema; Markdown holds it in YAML frontmatter (body text is free-form notes), JSON holds it directly. Required top-level fields: `key`, `title`, `steps`. Optional: `description`, `objectives`, `inputSchema`, `outputSchema`, `defaultRetryPolicy`, `skills`.
+
+```yaml
+---
+key: my-workflow                # stable external identifier — change cautiously
+title: My Workflow
+objectives: [deliver a working implementation]
+defaultRetryPolicy:
+  maxAttempts: 2
+steps:
+  - key: discover               # stable step key
+    kind: task                  # task | approval
+    objective: Understand requirements and constraints
+    dependsOn: []
+    validation:                 # mode: none | human | external
+      mode: human
+      required: true
+      autoConfirm: false
+    taskSpec:
+      # adapterKey omitted -> pi-agent
+      init:
+        context: { repo: example/repo }
+        skills: [architecture, planning]      # resolved step skills, see below
+        mcps: [mcp://github]
+        systemPrompts: [Focus on architecture trade-offs]
+        model: openrouter/anthropic/claude-sonnet-4
+      payload: {}
+  - key: qa_gate
+    kind: approval              # human checkpoint, no adapter
+    dependsOn: [discover]
+    approvalSpec:
+      autoApprove: false
+      validation: { mode: human, required: true, autoConfirm: false }
+---
 ```
 
-## Skill guidance
+Authoring rules:
+
+- Workflow keys, step keys, and status strings are stable external identifiers; prefer additive, backward-compatible changes.
+- Make `dependsOn` explicit; the engine resolves dependencies deterministically and rejects cycles.
+- Keep validation modes explicit per step. `human` pauses for approval (inline terminal prompt or attach API); `external` expects an outside system to resume the run.
+- Use `adapterKey: mock` for deterministic examples and tests; use Markdown when humans will review notes, JSON for machine-generated definitions.
+
+Steps communicate via ATEP-like envelopes: an `InputEnvelope` (global/step context plus priming config) goes in, an `OutputEnvelope` comes out carrying execution status and a QA routing action — `PROCEED`, `RETRY_CURRENT`, `ROLLBACK_PREVIOUS`, or `RESTART_ALL` — which the engine uses to advance, retry, roll back, or restart the run.
 
-- Prefer `validate` before `run` or `publish`
-- Keep `runWorkflow(...)` behavior registry-agnostic; registry operations belong in the CLI remote commands
-- Use Markdown workflows when the user wants editable frontmatter plus notes
-- Use JSON workflows when the user wants machine-generated or strongly structured files
-- Use `--auto-confirm-all` only when the workflow is intentionally non-interactive
-- When publishing, preserve the source format the user authored
+## Step skills
 
-## Workflow authoring checklist
+`taskSpec.init.skills` names are resolved per step in this order:
 
-- Set stable `key` and `title` values
-- Define clear step `objective` text
-- Add `dependsOn` relationships explicitly
-- Set validation mode per step (`none`, `human`, `external`)
-- Configure adapter initialization under `taskSpec.init`
-- Use stable step keys because tests and docs may refer to them
+1. Embedded `skills.<name>.content` in the workflow file (how published workflows ship skills).
+2. `skills.<name>.source` — a relative path that must match `skills/**/SKILL.md` under the workflow directory.
+3. `<workflow-dir>/skills/<name>/SKILL.md` (project-local).
+4. `~/.workflow-manager/skills/<name>/SKILL.md` (user-global).
+5. The npm-packaged skills under `node_modules`.
 
-## Adapter and validation notes
+`wfm publish` inlines resolved skill markdown into `skills[*].content` with a `contentSha256` integrity hash; pulled workflows are rejected when declared skill content is missing or tampered.
 
-- Supported adapters include default `pi-agent` plus explicit `mock`, `opencode`, `codex`, and `claude-code`
-- Omit `taskSpec.adapterKey` to run a task with the `pi` coding agent CLI
-- Put skills, MCP endpoints, system prompts, model, and context under `taskSpec.init`
-- Human approvals should stay explicit in workflow definitions
-- External validation should be deterministic where possible
-- Use the mock adapter for fast tests and scaffolding flows
+## Running and controlling runs
 
-## Recommended project references
+`wfm run` shows live progress on stderr and starts a local attach API on `127.0.0.1` for the lifetime of the run (OS-assigned port, or `--port`). The base URL and a per-run bearer token are printed to stderr before execution starts; every endpoint except `/health` requires `Authorization: Bearer <token>`. The API serves the session (`/session`), run snapshots, per-step detail, logs, an SSE event stream, and approve/resume/cancel endpoints (contract: `doc/guide/runner-api.md`).
 
-- `src/index.ts`: CLI command entrypoint
-- `src/parser.ts`: Markdown and JSON parsing plus validation
-- `src/engine.ts`: orchestration loop
-- `src/remote/commands.ts`: auth, publish, pull, search, and remote info commands
-- `tests/`: unit and e2e coverage for workflow behavior
+- Interactive human approvals show an inline terminal prompt; non-interactive waits are resolved via `wfm approve` / `wfm resume` / `wfm cancel` using the printed URL and token.
+- `--confirm stepA,stepB:human` pre-supplies confirmations for specific steps.
+- Never use `--auto-confirm-all` unless the workflow is intentionally non-interactive — it bypasses every approval gate.
+- `--json` prints the final result (including a `session` object) on stdout while progress stays on stderr.
+- `--input input.json` merges a JSON file into global input state; `--objective` overrides the run objective.
+
+## Remote registry
+
+```bash
+wfm auth login --token <token>     # token created in the registry web app
+wfm auth whoami
+wfm search <query>
+wfm remote info <owner/slug>
+wfm publish ./workflow.md --visibility public --tag automation
+wfm pull <owner/slug> --output ./pulled-workflow.json
+```
+
+If `publish` fails, check login state with `wfm auth whoami`. Preserve the author's source format when publishing.
+
+## Installing these skills for agents
+
+`wfm skill install` copies bundled skills into an agent's skill directory so the agent loads this guidance on demand:
+
+```bash
+wfm skill list                                   # see what ships with the package
+wfm skill install                                # workflow-manager-cli -> ./.claude/skills/
+wfm skill install --global                       # -> ~/.claude/skills/
+wfm skill install --agent opencode               # -> ./.opencode/skill/
+wfm skill install --all --force                  # every bundled skill, overwrite existing
+wfm skill install doc-sync --dir ./my/skills     # any other destination
+```
 
-## Typical troubleshooting
+## Troubleshooting
 
-- If validation fails, inspect the reported schema or dependency error before running again
-- If `publish` fails, confirm the user is logged in with `wfm auth whoami`
-- If remote calls fail in the browser, verify the remote registry app has valid Supabase `VITE_*` environment variables
-- If a real adapter test fails, confirm the underlying external CLI is installed and available on `PATH`
+- Validation failure: fix the reported schema or dependency-cycle error before re-running; ordinary input errors are reported as messages, not stack traces.
+- `doctor` failure for a real adapter: install the missing CLI (`pi`, `opencode`, `claude`) or export the missing provider API key.
+- Run stuck `waiting_for_approval`: approve inline in the terminal, or use `wfm approve` with the attach URL/token printed at run start.
+- Non-zero exit `2`: the run completed but not successfully — re-run with `--json` or `--verbose` to inspect step output.
+- Publish/pull failures: verify `wfm auth whoami`; for skill integrity errors, confirm the declared skill files exist and match their `contentSha256`.