Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Wf Yaml Authoring?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/axgord-wf-yaml-authoring)
---
name: wf-yaml-authoring
description: Reference for authoring workflow YAML — state types, skill gates, exec/fetch action states, terminals, routing, and engine gotchas
---
## Workflow Authoring Reference
### When a user asks for a workflow
This is the "ask the agent" path of `docs/getting-started.md`: the user describes a process in their words and you write the workflow. Write the YAML to this reference, save it with `create({ name, scope: "project", definition })` (a project workflow, `.claude/workflows/<name>.yaml`; `scope: "global"` for every project; `create` and `modify` REFUSE a definition with an `exec` or `fetch` state — write that file with your file tools and tell the user to run `wf-trust <project>` in a terminal, see "Exec consent" below), and say what you did NOT run: saving only proves the file loaded, not that its commands work. A saved project workflow is listed in `master`'s routing prompt (Step 1, `Available workflows:`), so a later message that matches its description starts it; the user can also name it (`start({ workflow: "<name>" })`). The other two ways to use the engine are the same page's Mode 1 (`start()` with no arguments opens `master`, which routes to a bundled workflow) and Mode 2 (a queue file plus `batch`, see Task queue below).
### Deployment & reload
- Bundled templates load from `templates/` next to the server's `build/` (i.e. `${CLAUDE_PLUGIN_ROOT}/templates`) — once, at server boot. Editing them does NOT hot-reload a running server.
- Load order (later overrides earlier by workflow name): bundled `templates/` → `~/.claude/workflows/` → project `.claude/workflows/`. The project is the server's cwd — except a session started with `cwd:` in ANOTHER project that has its own `.claude/workflows/` (a worktree counts as its main checkout): that session sees the workflows that project defines itself laid by name over the server's (a server-only name is still found; the home dir is no project) — a queue line's `workflow:` runs in its `repo:`. The SessionStart hook's CLI loads the same three tiers (one owner, `workflow-dirs.ts`).
- `~/.claude/workflows/` and the project dir ARE fs.watch'ed; ANY `.yaml` change there triggers a FULL reload that also re-reads bundled templates. Hot-reload trick after editing bundled templates (no server restart): `echo "# t" > ~/.claude/workflows/_trigger.yaml && sleep 1 && rm ~/.claude/workflows/_trigger.yaml`, then verify via `list` (state counts change).
- Active sessions keep their definition snapshot; only NEW `start()` sessions see reloaded workflows. The snapshot lives in the server's memory (engine.ts `_snapshots`), not the state file: after a server restart a session runs the current YAML. A child session snapshots at its own `start()`, so an old pipeline's new review runs the new slice-review.
- A NEW bundled workflow must also be added to `Engine.GLOBAL_WORKFLOWS` (`src/engine.ts`, a hardcoded name set) — otherwise the route prompt lists it under "Available workflows" as if it were a PROJECT workflow and Step 1 routes it via `project`. That is a code change: `npm run build` + server restart (templates hot-reload, code does not). Before deploying anything, check WHICH tree the running server loads: `ps -axo command | grep build/index.js` — a local-marketplace install can be a symlink straight to the repo, and a copy made into the plugin cache then changes nothing.
### Exec consent: `wf-trust`
A project file (`.claude/workflows/*.yaml`) that declares an `exec` or `fetch` state is NOT loaded in a project the user has not trusted. A project is trusted when the user accepted Claude Code's own folder-trust question for it (the engine reads that answer from Claude Code's config; nothing for the user to do, and an edited file keeps loading), or when the user ran `wf-trust <project>` (the plugin's `scripts/wf-trust`, also a `wf-trust` bin) in a terminal: it prints every command, asks for a typed `yes` and trusts the project directory once; `wf-trust <file.yaml>` approves one file's sha256; `--list` / `--revoke <project dir | hash prefix>` manage it. With `WF_TRUST_STRICT=1` only a file's approved sha256 counts and an edited file needs approval again. Until trusted the file is left out (a same-named bundled workflow runs instead; `list` and `start` say which file, which project and how to trust it) and its exec never runs. You cannot approve for the user: no MCP tool does, `wf-trust` refuses to run without a terminal, and `modify` / `create` refuse exec/fetch states outright. Bundled and global (`~/.claude/workflows/`) files are not gated; a project file with prompt states only needs nothing.
### Inheritance: `extends:`
A project workflow for a complex project should INHERIT the base process, not copy it:
```yaml
# .claude/workflows/testing.yaml
name: testing
extends: testing # same name → the global/bundled testing below this file
states:
project_test: # replaces the base state WHOLE (no key-by-key merge)
type: exec
command: "npm test -- --maxWorkers=$WF_THREADS"
timeout: 600000
resource: { threads: 6 }
on_success: check_integration
on_error: fix_unit
on_timeout: suite_slow
suite_slow: # new states are added
prompt: "Suite timed out. `retry` or report."
transitions: { retry: project_test }
```
- Merge: base states + heir states by name; `initial` / `max_transitions` / `description` / `model_table` / `driver` from the heir when set (a heir inherits the base's `driver:` unless it sets its own whole). Validation (initial, transitions, routes) runs on the MERGED result, so a heir may route to base-only states
- `extends` of its OWN name resolves from the tiers below the file (project → global → bundled); another name resolves from the top tier. Chains work; cycle / missing base / self-extends with nothing below = load error (stderr names it), and a file that fails resolution or validation falls back to the same name one tier down
- Without `extends`, `initial` and `states` are required (strict schema)
- **Extension points** (contract names in the bundled workflows; bundled = the old agent-run prompt or a no-op): `testing.project_test` (run the unit tests: keep `check_integration` / `fix_unit`), `testing.project_build` (build before integration: `integration` / `fix_integration`), `testing.project_gate` (end-of-change gate, bundled `exec true`: `done` / `failed`), `bug-fix.project_build` (build before the visual check: `verify_visual` / `write_fix`). `coding` and `bug-fix` verify through `testing` — one `testing` heir serves both; `batch-task.project_prepare` (the task's worktree, stdout = its path alone: `work` / `prepare_failed`) and `batch-task.project_land` (merge + verify under the repo's land lock: `"0"` → `mark_done`, default → `land_failed`, `on_timeout` → `land_timeout` (an exec: retries twice when the branch is unmerged and the tree clean, else `stop_state`)) — see Task queue below
- Override an extension point with an exec; copy a whole workflow only when the process itself differs
- A gate exec whose verdict must match CI runs the suite in a CI-like clean environment too (`env -i`, an empty `HOME`, no global git identity, another TZ/LANG): a test green only thanks to the local environment then fails before CI. The engine's own `npm run check:ci` (`scripts/check-ci.sh`, inside `npm run check`) is the pattern; its slices run by its project workflow `engine-task` (`extends: batch-task`), a tracked file of that repo (`.claude/workflows/engine-task.yaml`, un-ignored in its `.gitignore`: a workflow a slice must change cannot live only in an ignored directory); a check that lists what a branch changed (a CHANGELOG entry, a reproduction) diffs against the branch's own base (`git merge-base master HEAD`), never the moving `master`.
### State Types
**prompt** (default) — Agent reads the prompt and acts. Standard behavior.
**exec** — Engine runs a shell command automatically. Agent doesn't participate.
```yaml
run_tests:
type: exec
command: "npm test"
cwd: "{{context.cwd}}"
timeout: 30000
env:
CI: "true"
on_success: analyze
on_error: fix
success_prompt: "Tests passed:\n{{stdout}}"
error_prompt: "Tests failed (exit {{exit_code}}):\n{{stderr}}"
context_set:
last_test_output: "{{stdout}}"
```
- `env:` — extra environment variables (map; values are templates), merged over the server's env
- `context_set:` — after the action **succeeds**, render each value with the action result vars and store it in session context (e.g. `last_test_output` above becomes `{{context.last_test_output}}` in later prompts). Skipped entirely on failure.
**fetch** — Engine makes an HTTP request automatically.
```yaml
check_api:
type: fetch
url: "http://localhost:8888/ping"
method: GET
timeout: 5000
headers:
Authorization: "Bearer {{context.token}}"
body: '{"q": "{{context.query}}"}'
retry:
max: 60
interval: 500
on_success: ready
on_error: wait
success_prompt: "API ready: {{body}}"
error_prompt: "Not responding: {{error}}"
```
- `headers:`/`body:` — templated; `body` is sent for all methods except GET/HEAD
- `retry:` is **fetch-only** — it is ignored on exec states
- Retries fire only on network errors/timeouts (connection refused, abort). A non-2xx HTTP **response** does not retry — it returns immediately and routes via `on_error`/`cases`
- `context_set:` works on fetch states too (e.g. `{"api_body": "{{body}}"}`)
**skills** — Skill gate. Checks if skills are loaded; blocks if not, auto-transitions if yes.
```yaml
load_skills:
skills:
- coding-skill-selector
- "?project-skill-selector"
transitions:
continue: work
```
- Engine tracks loaded skills per session with epoch-based freshness
- First visit: prompts agent to call `Skill("X")` for each missing skill
- After loading + transition: skills marked as loaded for current epoch
- Subsequent visits: auto-transitions silently (agent sees nothing)
- After context clear/plan resume: epoch increments, skills reload on next gate
- `?`-prefix marks a skill **optional**: the gate lists it as "load if available, skip if not found" — use for project-local skills that may not be installed
- Skill gate states have `transitions` (unlike action states) — exactly **one**, conventionally named `continue`. The engine auto-takes the *first* transition when all skills are loaded, and its blocking prompt tells the agent "transition to continue", so any other name breaks the instruction
**full_on_revisit** (per-state flag, prompt states): the state delivers its full prompt
on every visit instead of the `Revisit #N` line. Use it when the text carries what the agent
must do THIS time (a fresh session to start, a value that changed), not a rule it can recall
from the first visit. A YAML using it needs an engine that knows the flag, so build and
restart the engine before the YAML goes in.
**revisit_prompt** (per-state template, prompt states): shown on a revisit instead of the
generic `Revisit #N` line, rendered with the same variables as `prompt` (`{{stdout}}` of the
latest exec, `{{context.*}}`). Use it when a revisit must carry per-visit data without
resending the whole prompt. `full_on_revisit` takes precedence; `status()` still returns the
full prompt. Absent = the generic line. Needs an engine that knows the field.
**ask: parent** (per-state tag): the state asks its parent a question. Entering it logs an `ask` event (the state name), leaving it an `answer`; the dashboard's event log (`/api/events`) carries the pair. Needs an engine that knows the key. A question from ANY state: a driver sets the context key `ask_parent` (one `context_set`) at a hand-back — it is OPEN while the key holds text and the session has not moved or ended since that write; the session's next move or end (the parent's own `transition` on it) or the key cleared to `""` is the `answer`. A stale key is ignored.
**station** (per-state flag, any state): the live workflow map groups bands by project, then queue (`context.queue_file`), then workflow (heading `project › queue · workflow`, one lane per queue line) and draws a workflow's band with one
column per *station* — the states on the shortest happy-path route (`transitions`, `on_success`,
`on_complete`, `cases["0"]`) from `initial` to the success terminal; exec states draw as scripts.
The success terminal is the farthest terminal that is not `outcome: fail` (the early exits —
released, closed — are nearer), or the one terminal marked `station: true` (a mark on a failure terminal or on several terminals is ignored; the loader warns). `station: false` keeps a helper
(`prepare`, a `*_route` exec) out of the columns; `station: true` adds a reachable state off the
path. `/api/workflows` returns the result as `stations: [{name, script, terminal}]`.
**digest_on_repeat** (per-state flag, prompt states): after the state's full
prompt was delivered once in the agent's current context, later deliveries send a
2-line digest ("already delivered earlier — status() for the full text")
instead — for large prompts re-delivered every task (routing rubrics,
doc-sync/reflect ceremony). `status()` always returns the full text; a
template reload clears the delivered-set, and so does a context reset —
every SessionStart (`/clear`, `/compact`, `/resume`) rewrites a per-process
marker (`$STATE_DIR/context-epoch-<claude pid>`) that the server checks on
every status render; the same-session Revisit
abbreviation takes precedence. Do NOT flag states whose prompt a FRESH
agent context may hit mid-flow without having seen it (spawned-agent
workflows share the server process — their first delivery may be a digest;
the status() hint is the recovery, but don't rely on it for load-bearing
one-shot instructions).
**stale_after** (per state, seconds; `0` = never): a session whose state saw no engine call
(any write) for longer is STALE — its agent may be dead or stuck. Unset, by type: prompt 1800,
exec/fetch 3600, a `resource:`/`fanout:` exec 14400; an exec's default is never below its own
`timeout` x 4 (the ceiling of a pool-wait stretch) + 300. A load error on a terminal or `sub_workflow` state (never read). Never STALE: an
ended or suspended session, one with an active child (it waits; each child is judged alone), a
`resource:`/`fanout:` exec waiting for its pool lease (no run yet, or `pool_starved`) while its
owner process lives. Clock = the later of the last write and the run's start (`running_exec`, else
`pending_action.run_at`), so a takeover / resume / `context_set` during a run resets it. Marks:
`sessions` → `[STALE: no engine call for 47m (since …), past its state's stale_after 30m]`;
`status` → the STALE sessions BELOW it on top (`STALE: session <id> (<wf @ state>, child of <p>,
agent <a>) — …`) plus one what-to-do line (SendMessage the agent; no answer → abort, or a new agent
continues from `status` — the session holds the step); `transition` appends them. Give a long
single-step prompt state (one agent turn of an hour) its own `stale_after`; a state waiting for the
user `stale_after: 0` (bundled `batch` `paused`).
### Routing Modes
**Simple** — binary success/error:
```yaml
on_success: target_if_ok
on_error: target_if_fail
```
Define **both** routes on every action state. The engine throws at runtime ("Action state has no target for result") the moment an outcome occurs that has no route — an exec that "can't fail" will eventually fail.
**Cases** — route by exit code (exec) or HTTP status (fetch):
```yaml
cases:
"0": all_passed
"1": tests_failed
"2": no_tests_found
default: unknown_error # required with cases
```
Cases overrides on_success/on_error when both are present.
### Template Variables
Available in ALL prompts (not just action states):
- `{{context.cwd}}` — the session's working directory (`start`'s `cwd`, else the server's)
- `{{session_id}}`, `{{parent_session_id}}` (empty at the root)
- `{{context.<key>}}` — any context value set via context_set, or by `transition`'s `set: {key: value, ...}` (written first, in the same call, all or nothing with the move: an agent's `context_set` + `transition` pair is one request, and the entered exec/prompt sees the keys)
- `{{visits.<state>}}` — visit count of `<state>` in the ACTIVE stack frame (empty if never visited) — route on "did the fix loop run?" without an agent turn
- `{{root_workflow}}` — workflow at the stack root (`subagent` = running as a spawned sub-agent)
- `{{stale_sessions}}` — one `STALE:` line per stale session below this one, or `none` (computed only when a template names it; also in `success_prompt` / `error_prompt` / `context_set`) — bundled `batch` `collect` lists the run's stuck agents with it; a `status` whose prompt renders it shows no second copy on top
After exec/fetch, also available:
- `{{stdout}}`, `{{stderr}}`, `{{exit_code}}` — exec results
- `{{status}}`, `{{body}}` — fetch results
- `{{error}}` — error message (both types)
- `{{pid}}` — PID for background exec
- `{{wait_ms}}` — pool wait of a `resource:` exec
These come from the session's LAST action result (`last_action_result`), not
only the action state's own `success_prompt`/`error_prompt`/`context_set`: the
state the action routes into renders them in its own `prompt` (no
`success_prompt` needed), every later prompt state still sees them, and the
next action state reads them in its `command`/`env` — until that action
replaces them. To keep a result past the next action, `context_set` it.
Templates are single-pass, no recursion. `undefined` → empty string.
Exec env always includes `WF_PLUGIN_ROOT` — the plugin root (dir holding
`templates/` and `scripts/`), resolved from the engine's own module location.
Reference bundled scripts as `command: "sh \"$WF_PLUGIN_ROOT/scripts/foo.sh\""`
— portable across install paths, no per-machine setup. A state's own `env:`
key of the same name overrides it. It also carries `WF_SESSION_ID`,
`WF_PARENT_SESSION_ID` (empty at the root), `WF_ROOT_SESSION_ID`,
`WF_PRIORITY` / `WF_PRIORITY_LEVEL` (the session level, below) and
`AGENT_CONTEXT` (tokens of the last turn of the agent linked to the session:
input + cache read + cache write; empty when none is linked or its transcript
is unreadable — test `[ "${AGENT_CONTEXT:-0}" -gt N ]` to hand off to a fresh
agent); a `resource:` exec with threads also gets `WF_THREADS` (below).
An exec without `cwd:` runs in the session's cwd — a sub-agent started with
`start(cwd: <worktree>)` runs its execs in the worktree, not the server's tree;
a relative `cwd:` resolves against it. Each exec's history entry carries
`exit_code` and `duration_ms` (plus `wait_ms`, `threads_granted` and
`step_key` = `<project git root>|<workflow>|<state>` for a `resource:` exec);
every session end appends one line to `$STATE_DIR/ledger.jsonl` with them, plus `spend`: the task's real cost summed from the transcripts of the agents the session ever linked (a respawned worker's earlier agents too) or names (`agent_id_<stage>`, `<role>_agent` context keys), unmeasured (never $0) when one cannot be read; `spend.by_agent` lists it per agent, state and stage the agent was linked at (`link_agent` records each call's time, the parent's state and that state's stage under any parent; a worker linked again for a fix round splits at the call) and `wf-calibration` sums it into the `$` / `$/task` columns of the stage rows; the plan pane (what it draws is `hooks/pane-view.ts`, one pure module the mod and the documentation site's landing both draw) shows it per Landed and Failed row (`—` when unmeasured), as a day sum on each Landed day and in the Failed header (`✗ Failed (28) · $41.20 (parent $6.10)`: every ledger row of the recent failed lines, agents' `spend.usd` plus the row's `parent_spend.usd`, a row nested under a same-task row adding only its parent spend, and how many lines have no row); the Landed heading sums the landed lines' spend and adds `parent $P (S%)`, the top-level session's own spend in the queue repo's conversations. A task's ledger line records that as `parent_spend` (the conversation's own turns since the conversation's previous line, priced by the same table, tiled so a turn is in one line, read from a recorded byte offset so only the new turns are read, with the transcript's `project`; absent when its transcript cannot be read).
A sub-workflow `push` history entry carries `workflow` and `to` (the sub-workflow's first state), so the time spent in every state can be read from the history alone (the dashboard's Timeline tab does: a bar per session that carries a `slice` / `task` id, its agent sessions folded under it); the ledger's `transitions` and `visits` do not count it as a move.
Unknown keys are a LOAD ERROR (strict schema): a typo like `comand:` drops
the whole workflow, and stderr names the file, state, key and nearest known key.
### Background Exec
```yaml
start_build:
type: exec
command: "make build"
background: true
on_success: poll_ready
on_error: build_failed
```
- Process runs detached, PID saved in `session.background_pids`
- stdout/stderr go to a temp log file
- `on_success` fires immediately (process started OK)
- `timeout` is **ignored** on background exec — the process runs until it exits or the session is aborted
- Abort (and a parent's abort cascade) kills each background exec's whole process group — `sh -c` and its children; a timeout on a foreground exec does the same
- Session scope: `start` without `parent_session_id` while this process already has an active root is REFUSED (the reply names the root by workflow @ state, never its id; `force: "<reason>"` starts a second root on purpose) — a sub-agent always passes `parent_session_id`, and reads its own session with `status`. `abort` of a root or of a session with active descendants is refused unless `caller_session_id` (your own session id) is the target or an ancestor of it, or `force: true` + `reason`; `transition` with a `caller_session_id` outside that subtree is refused the same way. A `transition` with no `caller_session_id` stays open on purpose: the engine's own prompts step other sessions without one, and a step ends no session. The abort hints the engine prints name the caller (`abort({ session_id, caller_session_id })`), so following one is not refused. Every cascade abort is logged to stderr with the caller and the session count
- Abort also kills a FOREGROUND exec still running in that session (or a descendant) at once — it does not wait for the exec to finish; the interrupted transition returns an error instead of routing the killed result
### Restart: suspended sessions and execs in flight
- Claude Code exiting SUSPENDS its sessions (and their sub-agents' sessions) — never abandons them; nothing ends, no ledger line. `claude --resume` / `--continue` (same conversation id) PICKS THEM UP in the SessionStart hook: the sessions and their sub-trees belong to the new process, nothing to call — the hook names each (`picked up: <session> @ <workflow @ state>`) and the sub-agent sessions with the `SendMessage` that wakes each agent (the agent calls `status` on its OWN session — no `resume`, never a new `start`); a session with no `agent_id` up to the root is taken for the main agent's own (`no agent linked — yours, unless a sub-agent you spawned runs it`) — so `link_agent` every spawned agent; under a parent of a `driver:` workflow (only there), an agent linked at an earlier visit of the parent's current state (a fix round re-entered it) is named `… an earlier visit's agent — not woken; abort(…) once it is not needed`, with no wake `SendMessage` (so is one linked at another STEP of the parent than its current one: `… an earlier step's agent — not woken …`) — any other parent's agents (a dispatcher looping `dispatch`) are all woken as before. The action step a session stopped in — an exec in flight, finished, killed by the restart, or never started (e.g. waiting for a pool lease) — is finished by the first `status` / `transition` of its session: waited for, its result taken, or run again (that `transition` is not taken — the session moved on). `startup`, another account, `--fork-session`: explicit — `suspended()` lists them by project, `resume({ session_id })` continues one (and lists its sub-agents to wake, each calling `resume` on its own session). Unresumed for `WF_SUSPENDED_TTL_DAYS` (7) → abandoned
- After `/compact` (or `/clear`) the hook output, which lands in the new context, lists the process's active sessions as a tree (id, workflow @ state, nested stack, agent) — the orchestrator knows where it is; `status()` gives the full prompt
- A spawner that wants its sub-agents woken by name after a restart calls `link_agent({ session_id: <child>, agent_id })` once the child session id is known. When the parent is a session of a `driver:` workflow (its states run one agent per visit — opt-in by workflow, no state flag) it also records the parent's step beside the agent (`agent_step`: the parent's workflow, state and that state's visit; linking again re-records it); any other parent records none, and nothing below applies to its agents (every call, under any parent, is still recorded in `agent_links` with its time, the parent's state and that state's stage, for the ledger's per-agent spend). For such a parent `status` lists `LINKED AGENTS at <state> (visit N)` — each child agent linked at the current state: `linked at visit N → current`, or `linked at visit 1, now visit 2 → stale (its session ended)` / `an earlier visit's (its session still runs)`; at a `_spawn` state (`work_spawn`, `plan_spawn`) also the running agent linked at the state before it (routing steps skipped; its session started there), `→ live (its session still runs)`, so a re-spawned driver messages it instead of spawning a second worker (a driver answers a harness `[handback-send-enforce]` prompt mid-run with the WAITING line only, never a hand-back). An agent reused at a later visit (a fix round's SendMessage to the same worker) needs `link_agent` again, else it shows as an earlier visit's — never keep a visit key in the context for this
- A foreground exec running at exit keeps running (detached, own group, output and exit code in files); `resume` waits for it or takes its recorded result, and runs the step again only when neither survived (reboot). So an exec state may be finished by a DIFFERENT server process than the one that started it — keep exec commands self-contained (no reliance on the server's lifetime). A `fanout:` state is re-run, not taken over. Output files are not capped while the command runs (`yes` writes until the `timeout`); `max_output` is the BYTES of tail read back. `--fork-session` (new conversation id) picks nothing up — `suspended()` lists the sessions
- MCP calls longer than ~120 s are moved to a background task of the Claude session, which does not survive its exit — the exec does, and the resumed session's first `status` (or `resume`) picks it up
### Heavy Work: `resource:` and `wf-run`
Light commands (a lint, a grep, a quick build check) run as plain execs — no
queue, they never wait. HEAVY work (a full test suite, a release build, a
corpus run) takes threads from ONE machine-wide pool shared by every session,
project and Claude config dir (`$WF_POOL_DIR`, default `~/.claude/workflow-pool`):
```yaml
run_suite:
type: exec
command: "npm test"
timeout: 600000
resource: { threads: 6, priority: 0, wait_timeout: 900 }
cases:
"0": analyze
"75": machine_busy # no lease within wait_timeout
default: fix
```
- Admission: `held + N <= budget` and, beside a live lease, `held + N + external <= budget` — external load never blocks an EMPTY pool. `budget` defaults to performance cores − 2; `external = max(0, load − own − load_threshold)` is load not taken through the pool (`own`: per lease with threads, the larger of its threads and the busy cpus of its own process tree — a command that spawns more than it leased does not block the queue as "external"; it is flagged `runs ~N (OVERRUN)` instead — and NOT bounded: admission only keeps `held ≤ budget`, so pass `WF_THREADS` on or the machine is oversubscribed), `load` = busy cpus measured from cpu ticks over the window since the pool's previous pass (loadavg1 only before a window exists — it lags a minute), `load_threshold` (default 2) is the noise floor. These settings and `starve_after` (seconds, default 900: a waiter queued that long, or a pool that granted nothing that long, is STARVED — marked in `pool_status`, logged in `<pool dir>/pool.log`, and a starved exec's session shows `POOL STARVED` in its and its ancestors' `status` / `transition`) live in `<pool dir>/config.yaml`
- Queue order: priority descending, then arrival; a lock goes to its waiters in queue order. The first waiter blocked only by threads is the **head** and holds a reservation (starved or not): a later task starts ahead of it (**backfill**) only when its estimate ends before the threads the head waits for (its min; a flexible head inside `wait_full`: its max) are expected free — the running leases' estimated ends in order; a lease with no estimate, past it or over-running ends at an unknown time, and then nothing passes. Estimates: p90 of the step's last successful runs in the ledger on the same threads (≥3 runs, within 30 days; a `fanout:` step has none; a flexible lease carries the estimate of its granted size), or `wf-run --est SEC`; with neither, the p90 of the last 10 runs of the same command (its label with the slice id dropped; ≥3 runs, clean ends only, kept in the pool's `history`) — so a lease or a waiter with no ledger history still takes part. No estimate on either side → strict order. A lease backfilled past a head that runs past 2× its estimate sets `backfill_off` for that head — nothing passes it any more (`backfill:` / `backfill off:` lines in `pool.log`). No preemption. `threads` above the budget counts as the budget: it waits for an empty machine and runs alone
- **`start({ …, reply: "id" })`**: the answer is `SESSION: <id> @ <state>` only (a `driver:` workflow's DRIVER block still follows) — no prompt, TRANSITIONS or rules. Use it where a parent starts a child just to pass the id to that child's own agent, which reads the prompt with `status`; without `reply` the answer is the full prompt
- **Priority = session level + step `priority`**: levels `low` −100, `normal` 0, `high` 100, `urgent` 200 — `start({ priority })`, inherited by child sessions, else the project default, else `normal` (project default: `{ "priority": "urgent" }` in `<project root>/.claude/workflows/settings.json` — a worktree counts as its main checkout, the loader ignores it as it reads only `*.yaml`; applies to a root `start` with no `priority` and to a bare `wf-run` outside a session; a bad file makes `start` fail, never silently ignored; `wf-run --status` / `--usage` never read it); keep a step's own `priority` under ±100 so it only fine-tunes within the level. `set_priority({ session_id, level })` changes a session and its descendants on the fly and re-ranks their WAITING entries at once (running leases keep theirs — no preemption). Every exec gets `WF_PRIORITY` (the sum) and `WF_PRIORITY_LEVEL`; `wf-run` without `--priority` takes them (outside a session: the project default), so a nested `wf-run` queues at its session's level. Old level kept in two windows: an exec between building its context and joining the queue (waits at the old level until granted), and a `wf-run` inside an exec started before the change (its `WF_PRIORITY` is from the spawn). Call `set_priority` only on the user's request — never raise your own session or change another project's
- **Flexible threads**: `threads: { min: A, max: B|budget }` (+ `wait_full: SEC`, default 0) / `wf-run --threads A-B [--wait-full SEC]` — gets B when B fits; otherwise, once `wait_full` has passed (counted from the waiter's arrival; with locks, from the moment they are first free, so time queued behind a lock does not use it up), everything free if it is ≥ A. While it waits (for B inside the window, for A after it) it closes the threads to those behind it like any waiter. **With an estimate for every size A..B** (the ledger's p90 per size, a curve fitted through the sizes that have ≥3 runs, ≥2 of them; or `wf-run --est-by-threads K:SEC,…`) `wait_full` is not used: the pool takes the size whose estimated end is earliest — start (now if it fits, else when the running leases' estimated ends free it) plus its run time — so it starts now on the free room or waits briefly for more, never for a fixed window; a lease with no estimate / past it / over-running is not waited for; no history → the `wait_full` rule. `WF_THREADS` = what was granted — read it, never assume B. For work that scales with cores (test suites, parallel builds) where an earlier start beats a wider one When the history (or `--est-by-threads`) cannot cover every size, the size is still picked by `wait_full`, but the granted lease carries `est_ms` from the measured sizes (nearest size, as is).
- `<pool dir>/pool.log`: one `sample:` line a minute while a lease or waiter exists and some pass runs (a polling waiter, `--status`, `pool_status`, a release) — `sample: load 7.5 external 1.1 held 8/10 runs 11.4 leases 2 waiting 3 [2-8, 4]`: machine load, external load, threads held/budget, busy cpus of the leases' process trees (`-`: unmeasured), the first four waiters' asks (`+N` more) — read it to tell whether the CPUs were busy while a waiter waited on threads; beside it the `orphan:` / `overrun:` / `underuse:` / `starved:` / `backfill:` lines; rotated to `pool.log.1` past 1 MiB; the documentation site replays it: `scripts/export-replay.mjs` cuts the samples of the replay's window (a lease or waiter keeps its label only when it names a slice or session of the replay, every other one is a thread count in one row of leases the log does not name (a sample lists no holders: only an `overrun:` / `underuse:` / `backfill:` line names one, shown from the next sample; the replayed Pool tab marks it `OVERRUN ~N` / `UNDERUSE ~N` like the live pane), and `assertReplayClean` refuses the write on any other label, a path or a pid) into `docs/public/replay/anyparse.json`, and `docs/pool.md` plus the landing's pool strip and Pool tab draw it (the log carries no priority and no age per lease, so the replayed rows show none); the same export keeps the sessions of anyparse and of the engine's own project (`--project`, `--also`; `--workflows DIR` loads the stations of the engine's own `engine-task`, which lives in its project directory) and reads each task's `spend.usd` from `ledger.jsonl` (`--ledger FILE|none`, only the replay's tasks: `ledgerSpend`, and `assertReplayClean` refuses a spend of any other task), so the replayed pane shows `$x.xx` on a Landed row and `—` for a task with no measured spend; it also reads the queue file (`--queue FILE|none`) through the engine's own pick (`planPick`, `describeQueue`) over the file rolled back to the window's start (every line that ran at or after it set back to pending; a line claimed before it and not ended at it is `running` at the start, so a line `after:` it waits `after: X (running)`) and writes the pending lines of those projects as ids, difficulty, priority, kind and a fixed set of reasons (`captureReplayQueue`; never a line's text or notes, and `assertReplayClean` refuses anything else), so the replayed pane's Next and Waiting fill and a line moves Waiting, Next, Running as the lines it waits for end (a line added after the window cannot be rebuilt)
- `wf-run --status` / the `pool_status` tool: one line per lease and waiter — pid, held/wanted threads and locks (`, runs ~N` for a measured lease, `(OVERRUN)` / `(UNDERUSE)` when far above / below its threads for 30 s), priority + level, since when (`STARVED`), project (git root), session, step, label; a `STARVED:` line when the pool granted nothing for `starve_after`
- `wf-run --usage [--since 90m|24h|2d]`: per label key (slice ids and hashes as `*`) over the leases that ended in the window — `n`, mean threads `held` and `used`, `idle thr-min`, `over thr-min`, `sampled` share — from `<pool dir>/usage.jsonl`; use it to right-size a caller's `resource: { threads }` (a lease is the caller's declaration; the pool only reports `underuse:` / `overrun:`)
- `threads: budget` (the only non-number value, strict) asks for the whole budget as `config.yaml` sets it when the request is made (a later raise does not grow a waiting or held lease) — no hardcoded core count; `wf-run --threads budget` is the same
- **The lease counts threads, it does not enforce them**: compilers, test runners and optimizers take every core by default. The command gets `WF_THREADS` = the threads granted (after `budget`/the clamp) — pass it on: `make -j"$WF_THREADS"`, `vitest --maxWorkers="$WF_THREADS"`, `HXCPP_COMPILE_THREADS="$WF_THREADS"`, `APQ_ORACLE_PARALLEL="$WF_THREADS"`. Env only (no template var); absent for a light exec, a lock-only lease and `--efficiency`. A step that empties its environment (`env -i`) drops `WF_THREADS` too: carry it over by name. A serial pipeline with a narrow half and a wide half cannot match held to used with one lease: take a lease per half, one after the other from the command (two `wf-run`, never nested: a lease around a second `wf-run` waits on itself). Size a range's `max` from a measurement of held against used (`LC_ALL=C ps`), not `budget`: a threads-fixed run holds what it does not use.
- `locks: [NAME, …]` (one word each: `port:3000`; a name may template a session value, `"{{context.cwd}}-land"` — rendered whitespace becomes `_`) — machine-wide mutual exclusion by name, for dev servers / bridges / devices on fixed ports. `threads` is optional beside `locks` (at least one of the two; lock-only takes no threads and is never blocked by load). Threads and locks are granted ATOMICALLY (all or nothing, nothing held while waiting → no deadlock); a lock goes to its waiters in queue order, and a waiter blocked by a held lock claims no threads, so a long-held lock does not stall the queue
- `wait_timeout` (seconds) expired → exit **75** (busy), routed through `cases`/`on_error` like any exit; without it the exec waits until granted or aborted (abort withdraws the wait)
- A `transition` / `start` / `resume` / `status` call that waits for an exec (pool lease queue included) sends an MCP progress notification every 60 s (`waiting for pool lease (Ns)` / `running <state> (Ns)`) when the client gave a `progressToken`, so Claude Code's no-response timeout does not cut the call.
- `timeout` counts the run, not the wait: a lease the exec itself waits for is not counted, and neither is the time a `wf-run` inside its command (it carries the session's id) has a waiter queued in the pool — the deadline stretches by that wait (also the part of it that fell in a server restart), capped at 4x the `timeout` so a pool that never grants still ends the exec; the history entry and the ledger record `wait_ms` beside `duration_ms`; `{{wait_ms}}` is a template var
- Foreground exec only: `resource:` with `background: true` (or on a fetch) is a load error
- **Shards: `fanout:`** — `fanout: { count: N | items_command: "<prints one item per line>", threads_each: k, max_parallel?: M }` on an exec runs the command N times (`WF_SHARD=i/N`, 1-based — the `vitest`/`jest --shard` form) or once per non-empty line (`WF_ITEM=<line>`), each instance under its OWN lease of k threads (`WF_THREADS`), started as threads free up, at most M in flight (default: budget / k — what runs side by side). Leases take no `wait_timeout` / `locks` / step `priority`. `timeout` is PER SHARD (default 30s — set it). Exit 0 only if every shard exits 0; else the failing shards' common code (all timed out → 124 → `on_timeout`), or 1 when they differ. `{{stdout}}` = summary (`fanout: 3/4 ok, 1 failed (exit 1)`) + each failed shard's output tail. Abort kills running shards, withdraws waiting ones, starts no more. History/ledger: one `shards` entry per instance. Load error beside `background` or `resource`; a failing `items_command` fails the step without running a shard
- A shell step inside a larger command, or an agent's own Bash call, uses the CLI instead: `"$WF_PLUGIN_ROOT/scripts/wf-run" --threads 6|budget [--lock NAME]… [--priority P] [--wait-timeout SEC] [--est SEC] [--est-by-threads K:SEC,…] [--label TEXT] [--fail-open] -- <cmd> [args…]` — same pool and admission, the child runs in its own process group, SIGINT/SIGTERM/SIGHUP are forwarded, the exit code is the child's (75 = busy), the child gets `WF_THREADS`; `--lock` without `--threads` is lock-only; a SIGKILLed `wf-run` cannot release: the next pool pass kills its detached child's group (SIGTERM, SIGKILL after 3 s; never a group from another boot or with another leader) and frees the lease — an exec's group, by contrast, outlives its server for `adopt`; `--efficiency` (macOS) runs the command on efficiency cores via `taskpolicy -b`, outside the budget
- **Pool gate (agents' own Bash calls)**: the plugin's PreToolUse(Bash) hook rewrites a command the project's `.claude/workflows/pool-gate.yaml` (nearest from the directory the command runs in up to the git root: the call's cwd moved by the command's leading `cd <dir> &&` / `;` segments, not by a later `cd`; a directory with no config falls back to the call's cwd's; the call's cwd's own config keeps its `deny` rules even when the target has a config, a deny in either refuses, heavy routing follows the target) marks heavy into `<plugin>/scripts/wf-run --fail-open --threads <N|MIN-MAX> --label '<cmd>' -- <shell> -c '<cmd>'`; no config / no hit → untouched. Rules: `{ match: "<leading words>" | "/regex/", threads: N | "MIN-MAX", pass?: "--flag=$WF_THREADS" | "env:NAME", deny?: "<reason>", env?: { NAME: true | false | "/regex/" } }` (`env` tests the segment's own leading `NAME=value` assignments, which `match` never sees: `true` set, `false` unset, a regex on the value; first hit per segment wins; a flag goes before `--`, never doubled; `deny` refuses watch modes) + `wrappers: [scripts that call wf-run themselves]`. One `wf-run` for the whole command, the largest share of its hits; `--fail-open` = a pool that cannot be used (read-only / sandboxed dir) runs the command unleased. A segment that runs `wf-run` or a wrapper is never matched against the rules, `deny` included; the other segments of that command still are. Left alone: `WF_THREADS` already set (an exec under a lease), `wf-run` or a wrapper in the command, a background `&`, a heredoc; `WF_POOL_BYPASS=1 WF_POOL_BYPASS_REASON='…' <cmd>` skips it with a stderr note. Any hook failure → the command runs as is. With `rtk` on PATH the body goes through `rtk rewrite` (Claude Code keeps only the last `updatedInput`, i.e. the gate's); RTK's exit 0 → auto-allow. Never add an allow rule for `…/scripts/wf-run` (it would allow any wrapped chain). Not seen: `npx -y …`, `sudo …`, `nice …`, `$( )`; the inner shell has no Bash-tool snapshot (aliases, functions). Do not hand-write `wf-run` around a command the gate already covers — and never start a watch mode it refuses under another spelling
### Task queue: `batch`, `queue_next` / `queue_mark` / `queue_add` / `queue_edit` / `queue_header`, `wf-queue`
A queue is a YAML file the engine admits from: top-level keys are the header — `batch_size: N` (`0` = paused: running tasks finish, nothing new is admitted) with `reason:`, and any other key (`base: [path=sha]`, `land_test:`, `land_branch:` — the branch the queue's lands target, read by the plan pane's Landed tree (absent: the queue repo's checked-out branch, else `main`), `record_file:` — a file `batch-task`'s `mark_done` appends one record line to per landed task; relative = beside the queue; `overlap:`); `tasks:` is a list of `{id, status, difficulty, kind, priority, model, effort, repo, workflow, after: [ids], touches: [paths], owner, exclusive, breaking, parked, ended, restored, base, text_hash, text, notes: [{from, date, text}]}` (`ended` = the day queue_mark moved the line to done or failed; mark-written, queue_add / queue_edit refuse it; `restored` = the day `wf-queue --restore` brought a done / failed line back from the archive: the archive counts the line's age from the later of `ended` and `restored`, it is removed with `ended`, and queue_add / queue_edit refuse it; `base` = HEAD of the line's repo and `text_hash` = short sha256 of text + touches + owner, where the line was written: queue_add writes both, queue_edit rewrites both only when it changes text, touches, owner or the repo (a re-spelling of the same repo keeps them), both refuse them as input; no `base` outside git; a line written before has neither and stays valid; the line's `base` is not the header's `base:` list). `status`: `pending | running | done | failed | backlog` (backlog = never picked). Keys: `model`, `effort` (`model: —` = parent-run, never admitted; so is a repo-bound line whose `touches:` entry git ignores in its repo, e.g. a live `.claude/` workflow — queue_add/queue_edit warn on it), `after:` (waits for done; an unknown id-like token or prose beside the ids = manual, not admitted), `touches:` (prefixes on a `/` boundary must not overlap a running or just-admitted task of the SAME repo; NO `touches:` = overlaps every task of its repo, runs alone there; header `overlap: files` = only FILE entries conflict, on the same file — no glob, and a regular file under the task's repo (`Makefile`), or, not there yet, a last segment holding a `.`; a directory or glob entry is then a hint; default `overlap: paths`; another value refuses the pick only), `owner:` (equal or `.`-prefix = one at a time, across repos too), `exclusive: true` (overlaps every task of its OWN repo, not another repo, in either mode: mass moves, renames, reformats; while it waits only for running lines of its repo it HOLDS the repo — no later line (priority, file order) of that repo is admitted, `--explain` says `held for exclusive <ID>`, other repos are not held; the header key `exclusive_hold: no` turns the hold off), `breaking: true` (a format/protocol change with no compat for running processes: admitted only into an empty window, nothing else admitted while it runs; that picker rule is the engine's — handing the land to the parent (`NEEDS-PARENT reason=breaking land ready`) is a route the project's task workflow must carry, and a line on plain `batch-task` lands as usual), `repo:` (absolute, or a name: the `base:` repo of that basename, else the dir beside the queue's project; default = the queue's project), `workflow:` (the task's own task workflow, found from its repo; default the dispatcher's `task_workflow`; not one word = not admitted), `difficulty:` (1..10, `-` = none; the task workflow's `model_table` maps it to model/effort — prefer it to `model`/`effort`; outside 1..10 = not admitted), `kind:` (`bug|feature|research`, absent or `-` = feature; any other value = not admitted; the pick only reports it, `queue_next` and the exec form's last column carry it, a task workflow reads it as `kind`; the dashboard's Plan tab and live map and the plan pane draw it as one glyph after the difficulty bar: `※` bug, `⚑` research, `◆` feature, GET `/api/queue` lines carry `kind` and `mark`), `priority:` (`urgent|high|normal|low`, default normal: the picker admits ready lines by priority, then file order; the pick's report shows it; GET `/api/queue` gives each pending line its place in that order as `admitOrder`, which the plan pane's Waiting tab sorts by), `parked: true` (skipped until unparked), `text` (the brief, a block scalar). A bad status or a duplicate id refuses every read. A task key this server does not know (written by newer code) is kept on write and inert for the pick; `queue_next` / `queue_mark` name it (`unknown key priority on X: ignored by this server`); `queue_add` / `queue_edit` still refuse it in their input. Writes edit the parsed document in place (key order and comments kept).
- Admission: window = `batch_size` − running; pending tasks by `priority:`, then file order; each admitted task is set `running` under the queue's lock (`<file>.lock`, mkdir — two picks never admit one task).
- Which queue: every queue tool and `wf-queue` takes an optional `queue` NAME beside `file`; neither = the project's `.claude/batch/queue.yaml`, `queue: "<name>"` = `.claude/batch/<name>.yaml` (project = git root of the cwd, a worktree → its main checkout), a full `file` still works; both = error. The dispatcher resolves a name ONCE and `context.queue_file` stays the absolute path task sessions get (never re-resolve a name from a task's own repo). `queue_add` / `--add` on a missing queue addressed by name or by default CREATES it (`batch_size: 1`, `tasks: []`; a full `file` path that does not exist is an error, never created) and says so; the other ops error naming the resolved path.
- MCP: `queue_next({ queue?, file?, dry_run?, explain? })` → id / model / effort / repo / workflow, difficulty (when set), kind, priority (when set) / text per admitted task; `queue_mark({ queue?, file?, id, to: running|done|failed|released|promoted|shelved, note?, from?, retry?, force? })` — pending→running (refused when the picker would not admit the line — overlap, after, exclusive, breaking, parked — naming why; `force: "<reason>"` overrides and is noted), running→done/failed/pending, backlog→pending, pending→backlog only (`retry: true` + `running`: failed→running, its `difficulty:` +1, at most 10); `note` is appended to `notes:` as `{from, date, text}`. `queue_add({ queue?, file?, task: {id, …}, after_id?|before_id? })` (pending or backlog; refused: a known id, an unknown key, an `after:` id that names no task or closes a cycle, `workflow:` not one word, `repo:` unresolved, `difficulty:` outside 1..10 or missing on a pending line (`difficulty: <1-10> is required on a pending line`; backlog, `parked` and `model: —` lines need none; `queue_edit` and `queue_mark` `promoted` refuse the same way when they would leave a pending line without one, a line already without stays editable), `kind:` not bug|feature|research; it writes `base` / `text_hash`), `queue_edit({ queue?, file?, id, set?: {field: value}, append_note?, from? })` (`""`/null removes a field; `after`/`touches` a list or a comma string; not the status; a change of text, touches, owner or repo rewrites `base` / `text_hash`), `queue_header({ queue?, file?, batch_size?, reason?, archive_after_days?, exclusive_hold? })` (the window `batch_size` + `reason` together, and/or `archive_after_days` — a whole number ≥ 1, `null` removes it, and/or `exclusive_hold` — `yes` / `no`, `null` removes it; no other key), no archive tool: the header key `archive_after_days: N` (set by `queue_header` / `wf-queue --header-set archive_after_days=N`; absent = never) makes every pick move the done / failed lines that ended over N days ago to `<queue>.archive.yaml`, under the pick's lock (an `after:` still resolves an archived id, an archived id cannot be added again; a failed line an open line names stays; the CLI forms are manual: `wf-queue --archive --older-than N [--include-unended] [--dry-run]`, `--restore ID`; `--convert --into` refuses an archived id too). A write lands only if the file is unchanged since its read (else re-plan) — change a live queue through these, never a script. Keep the queue file untracked + ignored (a tracked one dirties the tree; the land refuses a dirty tree, exit 3)
- Exec form `"$WF_PLUGIN_ROOT/scripts/wf-queue" [<file>|--queue NAME] [--dry-run] [--explain|--explain-all]` (`--explain` folds the `window full` tasks into one, `--explain-all` lists each): stdout `ID\tmodel\teffort\trepo\tworkflow\tdifficulty\tkind` (`-` = no `workflow:` / `difficulty:`; `kind` is `feature` when the line has none) per admitted task, summary + reasons on stderr; exit **0** admitted · **10** none, running ones still run · **11** none, nothing runs (done) · **12** none, nothing runs, `batch_size: 0` · **2** error. `--done|--failed|--release|--running|--promote|--shelve <ID> [--note T] [--from W]` (`--running <ID> --retry`, `--running <ID> --force REASON`), `--header <key>`, `--path` (the resolved file), `--add '<YAML mapping>' [--after ID|--before ID]`, `--edit <ID> [--set k=v]… [--append-note T]`, `--batch-size <N> --reason T`, `--header-set archive_after_days=N` / `exclusive_hold=yes|no` (`=` empty removes). One-time conversion: `--convert <old.md> [--into <q.yaml>] [--status S]` (prints, writes, or APPENDS the old file's open lines with status S to an existing queue, `--status pending` refused with exit 2 when a line has no `difficulty:`; `⏸` → parked, mark/dated fields → notes), `--convert <config.json> [--into <config.yaml>]` for the JSON configs.
- Bundled `batch` (dispatcher: `plan_queue` → `pick` exec → `dispatch` → `collect` → `slot_free` → `pick` …, `paused`, `cross_check`) starts one child session per admitted line: `context.task_workflow` (default `batch-task`: `claim` → `project_prepare` [worktree `<repo>/../.wt/<repo-name>/<ID>`, branch `batch/<ID>`] → `work` → `work_check` [exec: one clean commit on the branch; the driver has no shell] → `review_scope` [exec: the diff's class] → `review` [FIXES → `work`] → `project_land` [`git merge --no-ff` + the header's `land_test:`, a red test takes the merge back with `reset --keep` only while HEAD is that merge, else exit 4 untouched; lock `{{context.cwd}}-land`] → `mark_done` [exec: done + the `record_file:` line] → `cleanup`). With a `driver:` task workflow (bundled `batch-task`) `dispatch` starts each task with `start({…, context: {task, queue_file, difficulty}})`, spawns the DRIVER block of the answer unchanged and `link_agent`s it; `collect` routes on the drivers' one-line answers (`LANDED` / `CLOSED` / `NEEDS-PARENT`; a `LANDED` / `CLOSED` line ends with `lessons=<phrase (file)>; …|none` — the agents' own follow-ups, copied — and `collect` turns each into a `queue_add` line, a memory note or nothing; a reject or block → SendMessage the driver to take `reject` / `close`), ignores workers and reviewers under a driver (after a restart such a line is relayed to that P's driver), and re-spawns a lost driver from `status({session_id: P, key: "driver_call"})`. A re-spawned driver takes only a `current` agent of P's `LINKED AGENTS` as this visit's; none current → the prompt from its first step. A project heir: `extends: batch` overriding `plan_queue` with an exec that `context_set`s `queue_file` + `task_workflow` (master's `enqueue_plan` finds a heir by `extends: batch` in the project's workflow files, reads its `plan_queue` for the queue it names and `queue_add`s an approved multi-task plan there, header untouched — keep that queue readable from the exec; the bundled `plan_queue` resumes a queue whose `queue_file` is already in the context); its own task workflow (or `extends: batch-task` overriding the two extension points).
- **`driver:`** (workflow level, in the TASK workflow): `{ model, effort, prompt_ref, agent_type? }` — the cheap agent that runs the task session for the dispatcher. `prompt_ref`: a bare name = shipped `templates/drivers/<name>.md` (`task-driver`; unknown name fails the load), else a path (absolute, `~/…`, relative to the session's cwd). The initial state must be a prompt state (else the load fails). `start` of such a workflow ends its answer with a DRIVER block — the exact Agent call (model, effort, background, `subagent_type` = `agent_type`, default `workflow:driver`, prompt filled with session id, `context.task`, `context.queue_file` or the parent's, the instructions path; a missing file → WARNING) + its `link_agent` — and keeps it in the context as `driver_call`. A driver messaged after its last line is NOT finished (P still holds the step): it calls `status` on P and continues. A driver never calls a tool on the dispatcher session: on a terminal prompt it replies with its last line. `start`'s `context` (string map) seeds the session's context (`cwd` / `claude_code_pid` refused; `difficulty` goes through the `model_table`). A transition into a state already visited answers `Revisit #N` without rendering its prompt: the values the agent remembers from that prompt are the FIRST visit's — a prompt that needs current values on a later visit names the context keys to read (`status` with `key`), never `{{visits.…}}` or `{{context.…}}` alone. Declaring `driver:` also opts the workflow's sessions into visit-scoped agent links: `agent_step`, the `LINKED AGENTS` block and the restart wake-skip of an earlier visit's agent (see `link_agent`). The `agent_link` event of such a session records the DRIVER's `model` / `effort` (the block's values), not the task's execute model in its context, so the dashboard's driver chip and the replay's `driver · <model>` show what the driver runs on.
- **Shipped agent types** (`agents/`, after a Claude restart): `workflow:driver` (haiku/medium, the workflow MCP tools `start` / `status` / `transition` / `context_set` / `link_agent` / `queue_mark` / `queue_edit` + Agent/SendMessage/Read, no abort/delete/create/modify, no Edit/Write/Bash — the task-driver rules are its system prompt, so its spawn prompt is `P = <id>`), `workflow:recon` (sonnet/medium) and `workflow:reviewer` (opus/high), read-only by tool list (no Edit; a Write tool that the `read-only-gate` PreToolUse(Write) hook limits to the task's report directory — an absolute path under a `<task>.log` / `<task>-logs` directory in scratch space, outside a git work tree, no `..`) AND by the `read-only-gate` PreToolUse(Bash) hook: those types may run Bash only as an ALLOW list: the first word of every pipeline segment must be a declared reader (built-in: ls, cat, head, tail, wc, rg, grep, jq, find without actions, `sed -n '<n>p'`, git log/show/diff/status/grep/blame…), no `$( )`/backticks, brace expansion, `printf -v` or `$` in a command word, no `NAME=value` prefix unless its name is in the config's `envAllowed` (`GIT_*`, `LD_*`, `DYLD_*`, `PAGER`, `PATH`, `BASH_ENV`, `ENV`, `IFS` never), no redirect outside scratch (nor to a variable or glob), and the write list stays — a guard against ACCIDENTAL writes, not an adversary; the project's `.claude/read-only-commands.yaml` (`read`: extra readers, leading words or `/regex/` — its read-only CLIs; `write`: leading words or `/regex/`; `envAllowed`: variable names a `NAME=value` prefix may set; `env`: exported before the command only when a segment starts with a `read` CLI (the rewrite then carries `permissionDecision: "allow"`, so every other segment must be a project reader, a no-file default or a stdin filter behind a pipe, where a grep/rg flag value such as `-C 3` is not a file operand — else the call is denied, run it in its own call; other allowed calls pass unchanged), e.g. `APQ_READ_ONLY=1`; `agents`: override the type names) extends the built-in lists. A project may extend a type in its own `.claude/agents`.
- **Agents answer in one line, the text is in files**: bundled `batch-task`'s worker writes `report.md` (`handoff.md` when it stops unfinished), in `<worktree>.log` (kept after cleanup); the reviewer is the read-only `workflow:reviewer` (no workflow tools, no session; its Write is limited to scratch space), so its `review.md` is `/tmp/wf-batch-logs/<ID>/review.md`; answers `DONE <sha> report=…` / `BLOCKED …` / `VERDICT MERGE|FIXES|REJECT … review=… design=yes|no`; a fix round sends the line + "read <file> whole", never the text. The files carry named sections the driver copies as `lessons` (up to two): `report.md` / `handoff.md` `## Follow-up not done`, `## Tool defect found`, `## Open`; `review.md` `## Notes (non-blocking)`; a fix round or later review carries the previous file's items forward. Spawn prompts say once that a transition reply IS the next prompt — never `status` after it. The round cap stays: a third FIXES (the Nth by context `max_fixes`) is NEEDS-PARENT, decider or not. An earlier FIXES with `design=yes` goes to a fresh opus decider (context `memory_index`, optional) that writes `decisions.md` in `<worktree>.log` and answers `DECIDED file=…` or `ESCALATE reason=…`; only ESCALATE produces NEEDS-PARENT; the driver's `LANDED` line gains ` decided=<file>` and `batch` `collect` audits it.
- **`model_table:`** (workflow level, in the TASK workflow): `rows: [{ upto, model, effort }]` (ascending `upto`, last = 10; effort `low|medium|high|xhigh|max`) = the execute rows, or `stages: { <name>: rows[] }` (any name `^[a-z][a-z_]*$` except `model`/`effort`/`step`/`reached`, e.g. `recon` for a cheap recon spawn; plan/execute/review/review_verify/fix are the five the bundled workflows use; each stage its own rows; `stages.execute` replaces `rows`, giving both is refused; a malformed or reserved name, a stage short of 10, or a state reading `context.model_<x>` / `effort_<x>` for an undeclared stage fails the load) — `difficulty` then also writes `model_<stage>` / `effort_<stage>` for every declared stage and `model_reached`, while `model` / `effort` stay the execute row; `escalate` moves the execute and fix stages only, `escalate: { <state>: N }`, `review: { <class>: { model, effort } }`. `context_set` of `difficulty` (the claim sets the line's) → the engine writes `model`, `effort`, `model_step`, `escalations` (the answer names them; outside 1..10 refused). Every move into a state recomputes the row = the difficulty's + one per `escalate` entry whose state's visits reached N (capped); a moved row rewrites model/effort (a `model` history line). Escalation is per session: fix rounds, and a blocked re-entry within one session (a workflow whose `blocked` routes back declares `escalate: { blocked: 1 }`); no hidden state crosses sessions — in bundled `batch-task` `blocked` ends the session, and `queue_mark` `retry: true` (`wf-queue --running <ID> --retry`) rewrites the line's `difficulty: N` to `min(N+1, 10)` in the line itself (the answer says `(difficulty 4 → 5)`), so the re-run starts a row up; a line without `difficulty:` is retried unchanged. `review_class` set (an exec: `sh "$WF_PLUGIN_ROOT/scripts/review-class.sh" <base> <tip>` → `light` when every changed path is a test or a doc: root `docs/` / `specs/`, `tests/` / `__tests__/` anywhere, `*.md`/`.rst`/`.adoc`, `*.test.*` / `*Test.*`, CHANGELOG/LICENSE/README; a nested `docs/` package, a `.txt` build file, `docs/**/.vitepress/` or a script/`.vue` under `docs/` is code; else `code`) → `review_model` / `review_effort` (the class's entry, which overrides the review stage; else the review stage's row; without stages the task's own). The nearest table down the stack applies. Bundled `batch-task` is stage-aware (plan 1–3 sonnet/high, 4–8 opus/high, 9–10 opus/xhigh; execute 1–6 sonnet/high, 7–8 opus/high, 9–10 opus/xhigh; review 1–8 opus/high, 9–10 opus/xhigh; review_verify sonnet/high; fix 1–6 sonnet/high, 7–10 opus/high), `escalate: { work: 3 }` (second fix round → a fresh worker on the new model), review `light` sonnet/medium and no `code` entry. Interactive workflows take it too: bundled `coding` and `bug-fix` declare the stage table without `escalate`; `difficulty` set at `start` or by the plan state (`think` / `diagnose`) makes their implementer and reviewer spawns use `model_execute` / `model_review` (+ `effort_*`), no difficulty = the prose rule. **Difficulty rubric** (by the WORK, for a queue line and a plan step alike): 2 one function; 3 one owner; 4 a few files at one owner; 5 a new rule or command on existing parts; 6 a new shared component or config key; 7 cross-file typing or an unknown cause; 8 a contract moving across packages; 9-10 a whole-tree redesign that must be split; +1 when the premise is a stale measurement or a hypothesis. Ledger lines carry `difficulty`, `model`, `effort`, `escalations`, `review_model`, `review_effort`, `claim_difficulty` (the first difficulty; `wf-calibration` bands by the final `difficulty` and counts a claim off by >=2 in its `claim` column), `stages` (model/effort each stage ran on: its row when a state reading it was entered (in a prompt state also the bare `model` / `effort` = execute, `review_model` / `review_effort` = review; an exec's env does not count), first value wins; only those stages, so one absent from the line did not run), `tokens` (`tokens` → total, `tokens_<role>` → role; the driver sets `tokens_worker` / `tokens_review`) — tune the table from them
### Terminal States & Outcomes
```yaml
report:
prompt: "Write the final report per the contract above."
task: "Final report"
transitions:
done: finish
finish:
terminal: true
outcome: complete # or "fail"
```
- **Hard terminal** = `terminal: true` with no transitions. Entering it auto-pops the stack frame (sub-workflow returns to parent; root frame completes the session)
- A hard terminal's `prompt` **is delivered**: the engine renders it and prepends it to the pop/completion status, separated by a `---` divider — use it for final instructions (report contracts, push steps)
- `task:` on a hard terminal is **ignored** (the state is popped before a task op could be emitted). When you need a task op at the end, use the soft-terminal pattern above: a prompt state carrying the `prompt`/`task` with a `done` transition into a bare `finish` terminal
- **Soft terminal** = `terminal: true` WITH transitions: the session is marked finishable but stays in the state; the agent may re-enter/continue via its transitions
- **Outcome collapse on pop**: `outcome: fail` routes the parent to its `on_fail`; anything else (including omitted `outcome`) routes to `on_complete`. If the parent state lacks the needed route, the pop parks as pending (a `modify` adding the route resumes it)
- A ROOT frame ending on `outcome: fail` leaves the session `failed` (shown by `status` / `sessions`); a parent reads a finished child's results via `status(child_session_id)`, which lists its context with each value cut to 200 chars; `status({ session_id, key })` returns that one value whole (a gate table, an edit list)
### Common Patterns
**Review lives with the spawner**: a workflow that spawns code-writing
workers owns the ONE fresh-eyes review of their diff; the worker itself
stops at lint + its own intent re-read (a reviewer spawned inside the
worker re-pays what the spawner already pays, and cannot see seams
between workers). Never both — a worker review plus a parent review of
the same diff is paid twice; and never neither — a parent that assumes
the workers reviewed ships unreviewed code. Only a root session with no
spawner reviews its own writes (reviewer agents; lint-only for a trivial
diff).
**Decide once, flag in context**: when several states share one decision
(is the file user-authored? is the lint report usable?), have ONE state
evaluate it and `context_set` a verdict flag; downstream prompts guard on
`{{context.flag}}`. Re-stating the decision criteria in each consumer
drifts (guards diverge, agents re-evaluate inconsistently) — exactly the
bug class a single flag eliminates.
**Test-before-commit**: `exec(npm test)` → success → `exec(git commit)` → done
**Health check polling**: `fetch(url, retry: 60x500ms)` → success → interact
**Build-and-verify**: `exec(make, bg)` → `fetch(health, retry)` → ready
**Multi-step pipeline**: chain action states — exec → exec → fetch → prompt
(max chain depth: 20, no agent involvement between action states)
**Loop re-entry needs its own state, not a jump into assess**: when a
fix/retry transition routes back into a general decision state, audit that
state's OUTBOUND transitions first — an early-exit there (`skip → done`)
lets the agent end the loop without re-running the verification the loop
exists to guarantee. Give the retry a dedicated re-entry state that offers
only loop-preserving routes. Dual of the inbound rule: adding a gate before
state X requires auditing ALL transitions INTO X for bypasses.
### Gotchas
- stdout/stderr truncated to `max_output` bytes (default 10KB, configurable per state). Truncation keeps the **tail** (last N bytes), not the head — errors at the end of output are preserved. Use higher values for verbose builds (e.g. `max_output: 51200`)
- Default timeout: 30s (exec), 5s (fetch)
- Exec timeout → SIGTERM to the process group (SIGKILL after 5s grace) and **exit code 124**; `{{error}}` is "Process timed out". Route it with `on_timeout: <state>` (foreground exec; wins over `on_error`/`cases`; beside `cases: {"124": …}` = load error) — a heavy gate that timed out must NOT fall into the code-fix loop
- Action states CANNOT have `transitions` or `sub_workflow`
- Action states route via on_success/on_error or cases/default only
- `success_prompt`/`error_prompt` are templates, rendered with action result vars
- If neither prompt template is set, the next prompt state's own prompt is used
- **A chained action state's prompt is DISCARDED**: in an exec→exec→… chain only the LAST state's `success_prompt`/`error_prompt` reaches the agent. The engine renders each state's prompt, then recurses into the next action state without passing it on — every intermediate one is dropped silently. So an intermediate state can never REPORT anything: a check whose whole value is its output (a `--list`, a `--dry-run`, a diff stat) is invisible where it sits. Either make it the chain's last state, have it ACT rather than report (`--write` over `--list`), or gate it on a non-zero exit into its own prompt state — and note that a `--list`-style check usually exits 0 whether or not it found anything, so `cases` never fires and the chain sails past
- Background processes are NOT monitored — use a subsequent fetch/exec to check
- **Template injection**: `{{...}}` values are substituted **unescaped** into `command:` and run via `sh -c`. A context value containing quotes, `$`, `;`, or backticks breaks the command — or executes as shell. Never interpolate untrusted/free-form context into commands; keep interpolated values to known-safe tokens (paths you set, enum-like flags). **Safe channel for everything else — `env:`**: env values are set on the process, never parsed by the shell, so `env: { REVIEW_FILE: "{{context.file_path}}" }` + `command: "script.sh \"$REVIEW_FILE\""` is injection-proof. Any AGENT-set context value (a `context_set` an agent made — e.g. a file path from a reviewed repo, where a hostile `$(cmd).hx` filename would otherwise execute) and even engine-set paths (`{{context.cwd}}` — a `$(payload)`-named directory) must go via `env:`, not into `command:`
- **Guards throw unless routed**: a move past a state's `max_visits` throws (the transition is refused) — unless that state has `on_exhausted: <state>`, which enters that state instead (agent transitions, action-state routes and skill-gate auto-transitions alike; chained routes are followed, a route cycle throws; the history entry's `detail` names the exhausted states; a rerouted action move shows the routed-to state's own prompt, not the action's `success_prompt`/`error_prompt`; `on_exhausted` without `max_visits` or to an unknown state is a load error). `{{visits.<state>}}` in the exhausted-route state's prompt shows how many tries ran. A pop's `on_complete`/`on_fail` move does not check `max_visits`. Hitting `max_transitions` throws, except for a move that only closes the run (into a terminal, or into a state no route leads back to that reaches a terminal); within 5% of the cap the reply carries a `WARNING:` line
- `max_transitions` accounting is **per stack frame** — each sub-workflow push starts a fresh counter checked against that workflow's own `max_transitions` (default 50)
- **Duplicate YAML keys** — parser rejects the entire file with a `YAMLParseError`; the loader logs it to stderr and skips the file (workflow not loaded). Always validate YAML before deploying (no duplicate `success_prompt`, `error_prompt`, etc. on the same state)
- **Long-running commands** (dev servers, log tailers, watchers — anything that doesn't exit) — always use `background: true`. A foreground exec resolves when its `sh -c` exits (output goes to files, not pipes): a command that never exits blocks until its `timeout`; a grandchild it leaves running keeps running in the exec's process group, untracked — and is killed by the next abort of the session. On `timeout` the group gets SIGTERM, then SIGKILL after 5 s, and the step resolves only once the group is gone
- **Foreground build + background deploy** pattern: use foreground `build` (catches errors) then background `test/run` (streams logs), then poll readiness via `fetch` with retry