@workflow-manager/runner/skills/workflow-author/SKILL.md

CLI runner for in-memory and markdown workflow orchestration using ATEP-like envelopes

---
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. `opencode` runs real by default, so to dry-run an `opencode` step specifically, either set `taskSpec.payload.useRealAdapter: false` (keep `adapterKey: opencode`) or swap `adapterKey: mock`. 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]
  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 | kimi | gemini | qwen | 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 | kimi | gemini | qwen | 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
      timeoutMs: 600000            # per-step subprocess timeout (pi-agent default); SIGTERM on expiry
  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`.

**Step timeouts:** there is no top-level `timeoutSec` (or similar) step field — `StepDefinition` has no such field, and nothing in `src/engine.ts` reads one. The only supported timeout knob is adapter-specific: `taskSpec.payload.timeoutMs`, read by the subprocess-based executors (`pi-agent`, and the deprecated bespoke `claude-code`/`opencode` executors). It's milliseconds, defaults to `600000` (10 min) for `pi-agent`, and controls how long WFM waits before sending `SIGTERM` and failing the step with `timedOut: true` in `mutated_payload`. A long-running real step (an API-backed script, a slow build) should set this explicitly rather than relying on the default.

## 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.

If you're dry-running with `adapterKey: mock`, expect steps to resolve near-instantly: your very first `status` poll may already show several steps succeeded (or the run parked at an approval gate) with no intermediate "running" beat to narrate. That's expected — narrate what you actually observe rather than assuming a step-by-step cadence.

**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.
```