Workflow Blueprints

A workflow blueprint is a skeleton for a multi-agent job: named stages, a role with a reasoning class, a gate that must pass before the next stage can start, and a budget. It does not contain the actual child prompts. The parent session reads the stage intent and writes those prompts itself, with the real task in front of it.

vord ships seven of these (version 2.0.0). You can turn any of them off, copy them, or write your own. A parent with child sessions and the separate workflow gate turned on drives the run through six MCP tools — workflow_list, workflow_start, workflow_gate, workflow_status, workflow_abort, workflow_resume — and binds each child it starts to a stage.

Fan-out blueprints (many children over disjoint file clusters) are vord-only.

How a run works

1. The lead starts either an enabled template from workflow_list or a custom flow for this session via workflow_start. The run is stored under <project>/.vord/workflows/<run-id>/state.json.
2. For each stage it spawns a child with spawn_agent, passing workflow_run_id and workflow_stage_id. vord refuses that spawn until the gates of the previous step have passed, the run is still live, and the run budget still has room.
3. The parent (or you) then records the gate. Until that happens, the next step cannot start. A child’s “I finished” report is not a gate — the app checks evidence, not self-report.
4. Children of a workflow are always siblings of the parent (child-session depth is 1). Stages are not a nested tree.

Workflow blueprints are an option for top-level hosted sessions in both vord Code and vord Cowork when work is larger and multi-stage: two or more packages, or work in a risk class such as auth, payments, data migration, wire protocol, or release (for example, building a new subsystem). They are not required for small fixes or a single package. At session start, the parent receives a one-line list of blueprint names with the same short note that they are an option for larger multi-stage work, not small fixes. workflow_list adds a short description for each enabled blueprint that has one. Stage intent files (stages/*.md) stay on disk; the parent reads them when that stage is due, the same way it reads a skill.

Steps: parallel stages, packages, optional stages

Stages do not have to run one after another.

• Parallel stages form a step. A stage marked “parallel with previous” (parallelWithPrevious) forms one step together with the stage before it. All stages of a step start at the same time; the next step begins only when every stage of the step has passed or been skipped. The first stage of a flow cannot be parallel.
• Packages. A stage can be built by several children at once: the parent starts multiple children into the same stage so the work splits into packages that run in parallel. spawn_agent takes an optional workflow_package label (1–80 characters) naming the package; it is accepted only together with workflow_run_id and workflow_stage_id.
• Handover. Every stage child automatically receives the results of the stages of earlier steps — status, summary, report paths — plus its own package label.
• Optional stages. An optional non-human stage can be skipped by the parent through workflow_gate with decision: skip and a reason. Human stages are never optional.
• Side children. While a run is active, the parent may still start children with no run binding at all — for example a research child alongside the run. They do not count against the run’s spawn budget.
• Stall notice. If a stage child produces no output at all for 15 minutes, the parent is messaged once per episode. The run does not halt.
• Parallel capacity. As many children run at once as the max children per session setting allows (1–20, default 3); workflow_start and workflow_status name that number for the parent.

Having a flow created just for this session

You can tell the AI, for example: “Build a custom workflow for this task with analysis, implementation, independent review, and my approval.” The AI passes the roles, steps, and respective instructions directly at start as custom_workflow. No persistent template is created for this.

The flow belongs to the starting session. Its definition is stored with the run, even if you reopen the same session after an app restart. Other sessions cannot take over this run; it does not appear in the global or project template list. If you end or archive the owning session, the normal completion of its active runs still applies.

All gates, checks, and budgets apply to such a flow as well. An approval required by you cannot be granted by the AI itself. You continue to create reusable flows as a global or project template.

Four gate types

The app enforces every gate. Prompt-only “please review this” is not a gate.

Gate	What actually passes it	Who decides
Auto	The parent names a test or build command; vord starts it in the app, returns immediately, and later passes the stage only if the process exits 0 and writes a log. Non-zero exit or missing log fails the stage; a timeout stops the command and fails the stage too, but it is reported as a timeout, not as a test failure. The command is killed after 30 minutes by default (its whole process group) — per stage configurable (testTimeoutMinutes, 1–240) and per gate overridable (timeout_minutes). The limit counts from the start of the command, so time a command spends waiting for a shared build slot counts too; give such commands a longer limit. The parent’s message then says TIMED OUT after N min instead of a test failure. A stored stage command from a repo-provided blueprint additionally needs your one-time confirmation (see below).	The mechanics
Orchestrator	The parent has read the stage’s artefact and written gate: passed with a non-empty summary.	The parent (usually your strongest model)
Skeptic	A skeptic child has written an approved verdict. Using the same provider as the referenced builder, or leaving that role unstaffed, is recorded as a visible diversity warning rather than blocking the gate.	That skeptic child
Human	You click Approve on the parent tile, in the Workflows panel, or in Team view. The parent cannot pass this through workflow_gate; the tool always refuses. While the run waits for you, the parent is free to do other work — only the run is paused, not your agent.	You

Each stage also carries parentInvolvement: none, notify, or decide. That field is independent of the gate type. None does not ask the parent when the stage completes. Notify sends an informative message and the run continues. Decide treats the parent (or your UI approval) as the gate: later stages stay blocked until that decision exists. Older blueprints without the field keep the previous behaviour: human and orchestrator stages decide, auto stages notify, skeptic stages none. Unknown values fail to load.

In the guided editor that is a plaintext radio list — Involve the team lead: No / Notify / Let them decide — with the chosen option’s explanation underneath. The engine values stay none, notify, and decide; existing stages keep their stored value when you open them.

In the app these four gates carry plain-language labels — Self-check, Team lead reviews, Independent review, and My approval — with the technical name kept in the explanation sentence (for example, “Team lead reviews … (Orchestrator gate)”). The engine values auto, orchestrator, skeptic, and human stay unchanged; the labels are a UI rename only.

A skeptic gate is the structural reason these runs span agents: the blueprint names the builder role used for a provider-diversity check, and vord checks the real child sessions rather than what the parent claims. For the verdict, vord reads the final WORKFLOW_VERDICT: line from the child report file in the project and verifies that the child is bound to the stage. A same-provider or unknown comparison stays visible in the gate record and Team view; it does not replace the required verdict. It does not prove who wrote the file; another process with project write access could still tamper with it.

Reviewers mark non-blocking suggestions as FOLLOW-UP: lines in their report. They do not block the verdict; vord stores them with the gate as follow-up points. In round 2 of a loop, the reviewer sees the blocking findings of the previous round.

Loops: bounded rework after a failed gate

A stage can carry a loop: “when this gate fails, go back to an earlier stage and try again.” In the file that is onFail on the stage — a target stage id plus maxRounds, the total number of allowed rounds including the first pass. The target must be an earlier stage and cannot be a human gate; the editor checks both live. All shipped blueprints allow two rounds.

When the gate fails and rounds remain, vord archives the discarded round, reopens the loop target as the running stage and resets the target plus every stage after it up to and including the step that contains the failing stage (round counter +1), then hands control back to the parent at the target stage. Evidence of the discarded round stays in the run’s history as attempts. When the rounds are used up, the run halts instead: you get two buttons where the progress strip shows the halt — One more round grants exactly one extra round, Abort ends the run.

One more round is a human continuation, not just a counter change. In one saved operation it adds two role starts, resets the parent’s three self-resumes, opens the loop target and records one wake for that stage. If delivery is interrupted, the wake remains visible and is retried; repeating the same phone request after a reconnect or restart does not add a second round, budget grant or wake. Only the person in the app or on their authorized paired phone can grant it — the parent and its MCP tools cannot grant themselves another round.

A rejected human gate uses the same machinery: rejecting requires a reason (1–500 characters), which travels to the parent as part of the evidence. With a loop configured the rejection loops back; without one it halts the run as “rejected”.

You never have to relay any of this by hand: whenever a gate resolves — human decision, auto-gate result, loop-back, or halt — vord messages the parent session itself. See the agent is notified.

You are notified as well. Whenever a run needs you — it reached your approval, or it halted because rounds or budget ran out or you rejected a stage — vord writes an entry into the notification inbox and, as it is created, shows a macOS banner and pushes it to your paired iPhone or iPad. The inbox entry is the durable record (exactly one per decision point, kept across restarts); banner and push are sent once when the entry is created. The notification tells you where to act (the session tile or the Workflows panel). With a paired iPhone or iPad on the same release you can also decide right there — see workflow decisions from the phone; the Mac stays the single truth and re-checks the run before applying anything.

The seven shipped blueprints (v2.0.0)

All seven ship with the app (layer Bundled), version 2.0.0. In the flows below, → is the next step, ∥ marks a stage that runs in the same step as the one before it (parallel), ? marks an optional stage, and ×N is a package hint — start N children into that stage.

Id	What it sequences	Default spawn budget
plan-and-build (new, the recommended default)	plan → build ×4 → verify ∥ review ∥ security? → acceptance	24
spec-first-feature	spec → spec-review → build ×3 → test-gate ∥ skeptic-review ∥ security-check? → human-approval	22
parallel-migration (vord-only)	cluster-workers ×8 → merge → auto-gate ∥ skeptic-review → human-approval	16
adversarial-review	maker-pass → skeptic-pass ∥ critic-pass → human-approval	11
bugfix-tdd	repro-test → fix → auto-gate ∥ skeptic-review → human-approval	9
judge-panel	candidates ×3 → judge → skeptic-review → human-approval	9
security-audit-gate	scan → skeptic-security-lens → human-approval	6

Roles use Fast, Standard, or Strong reasoning classes — in the shipped set, builders run on Standard, cluster workers on Fast, and review, judge, security, and spec roles on Strong. For the current allowed child-model catalog and its supported thinking levels and quotas, the parent calls get_delegation_context; it chooses the concrete provider, model, and thinking level for the actual task. A global or project copy may deliberately pin one provider/model choice. Bundled blueprints remain neutral and read-only. A missing live catalog does not invent a model: the parent is told to validate its choice at spawn time. A skeptic stage reports whether its actual provider differs from its referenced role, but an approved verdict remains valid either way.

Fan-out blueprints (parallel cluster workers) stay vord-only, because the dynamic fan-out needs spawn_agent-driven parallel spawning.

Older global or project-specific copies also remain dynamic: the former fields agentHint, modelHint, and thinkingHint no longer create a binding model choice when loaded. Only an explicitly saved pin binds the role to a provider and model. For older templates, the thinking class continues to be derived from the previous thinking effort. Workflows that have already started keep their saved state; the change applies to new runs.

Folder format

Each blueprint is a folder:

spec-first-feature/
  blueprint.json          # id, name, class, roles, stages, budget defaults
  stages/
    spec.md               # intent and success criteria — no child prompt
    spec-review.md
    …

blueprint.json names the stages (id, title, role, gate type, path to that stage’s markdown, and for a skeptic gate the builder role used for the provider-diversity comparison). The markdown files are English on purpose: they are read by the parent agent.

A stage file says what this stage is for and what done looks like. The parent writes the child task from that plus the actual work.

Layers, copies, and turning one off

vord looks in three places, later winning:

Layer	Where	Who edits it
Bundled	Shipped with the app	Read-only. Edit makes a global copy first.
Global	~/.vord/blueprint-templates/	Via Create global template; available in all projects.
Project	<project>/.vord/blueprint-templates/	Via Create project template; available only in this project.

Project beats global beats bundled. A disabled id is stored in the global disabled.json; that template then disappears from workflow_list and from the parent’s injected list — the agent never sees it. A global copy under ~/.vord/blueprint-templates/<id> shadows the bundled blueprint of the same id; if you want the new bundled version of a blueprint you copied earlier, remove or move your copy.

Repo-provided templates: stored test commands need your confirmation

The project layer lives inside a repository you may not trust. A blueprint shipped that way can carry a stored test command for an auto gate — and without protection, cloning a hostile repo would be enough to run an attacker’s shell command on your machine the first time an agent passes that gate. vord therefore treats stored commands by origin:

• Bundled and global blueprints run their stored command as before. Bundled ships with the app; global is your own home folder.
• Project blueprints are repo content. Their stored command does not run until you have confirmed it once: the Workflows panel shows every such stage loudly, with the layer it came from and the full, untruncated command, plus a Trust command button. The confirmation is bound to this project (the real folder path, and the Git remote when vord knows it) plus the exact command text. Confirming the same-looking command in another repository does not count here, and editing the file afterwards un-trusts it until you confirm again. Confirmations stored by older versions without a project binding are ignored and you will see the warning card again.
• Until then, an agent calling workflow_gate without its own test_command gets a refusal telling it to ask you to confirm the command in the Workflows panel, or to pass an explicit command instead. An explicit test_command in the tool call always works — it is the agent’s own visible choice.
• Saving a project template inside vord counts as your confirmation for that project and records the trust automatically. Global copies are not a project confirmation.
• Project blueprint folders must sit inside <project>/.vord/blueprint-templates/. A symlink on .vord, on blueprint-templates, or on a template/stages folder that points outside the project is rejected: the scan skips it (and shows it as failed-to-load), the editor will not write through it, and workflow_start will not hand the agent those outside paths.

Two more hardenings ride along: workflow_list and the session-start context now name each blueprint’s origin (bundled, global, project) so agents can tell repo-provided templates apart, and a project blueprint that shadows a bundled id of the same name is flagged in the panel. Stored test commands are capped at 500 characters and may not contain control characters — longer ones are rejected by validation and flagged live in the editor. A broken template no longer takes the whole scan down: it shows up as failed-to-load in the panel and workflow_list, while healthy blueprints stay usable. Finally, auto-gate commands run in a reduced environment (only PATH-augmented basics like HOME, LANG, TMPDIR, TERM, SHELL, USER, and CI flags pass through) and with zsh -f, so app-level secrets and your shell startup files never reach the gate process. The shared runner also turns on fail-fast (set -e) and pipeline status (pipefail): if a stored command lists several steps, the gate stops at the first failing one and reports that exit — a later success cannot make the gate look green. Both apps log the exact command, working directory, exit code, and timeout flag in the gate log header.

The on/off switch and the editor live in the Workflows window, which you open from the flowchart button in the main toolbar. Two tabs in the window toolbar separate the concerns: Runs and Templates. Like the board, it has a native title bar and toolbar — close it with ⌘W or the red button and reopen it the same way; size and position are remembered by the system. The window never shrinks below 780 × 640 and defaults to 1100 × 860. When it opens, it lands on Runs as soon as an active run exists, otherwise on Templates.

Runs

The Runs tab opens with an overview row: counts for Running, Waiting for you, Stalled, and Halted, plus a legend for the step bar (done, running, reworked, skipped, waiting). Below that, runs are grouped into three sections. Empty sections stay hidden.

• Awaiting approval — the run is still going, and every unfinished stage is a human gate waiting for you.
• Active — running, stalled, or halted runs, newest first.
• Recently finished — the last 10 completed or aborted runs.

A run card

Each run is one card.

• Header: blueprint name, project · parent, and a status badge. While a stage child is held back because memory pressure is critical, the one-minute load average reaches 12 per CPU core, or the Mac is in serious thermal state or hotter (the build queue’s thresholds), the run card shows a clock with the number of parked starts; the child starts automatically and only then counts for its stage.
• Status line in plain language. While several stages of the open step are running, the line names them together.
• Step bar: one segment per step. Stages of the same step stack. Packages of a stage are sub-segments, with a count such as “3/4 packages done”.
• Budget line: “Children 9 of 24”, and “up to N at once” for the max-children setting. The bar carries a limit mark. Child budget opens a slider. Releasing it above the current limit resumes the run with that many additional children. The control is offered while the run is running or halted on its budget.
• Footer: only the actions that apply — Approve, Reject, Resume (+2 children), Abort, Open parent.
• Follow-ups expand under the card when a review stored any.

A halt after the review rounds are used up is not a budget resume. Resume is not offered. One more round is on the parent tile.

Templates

The Templates tab shows one card per template.

• An origin badge: Built-in, Global, or Project.
• The description.
• Chain chips. “∥” means the stage runs with the previous one, “×N” is a package hint, and “?” means optional.
• The worst-case child budget.
• The test-command state, with Confirm when a project command still needs your confirmation.
• A defect count when the template failed to load or still needs attention.
• The enable switch.
• Edit, Duplicate, and Delete. Delete is only on your own templates (global or project), not on built-in ones.

Delete asks for confirmation, then moves the template into an archive folder: ~/.vord/blueprint-templates-archive/ for a global template, <project>/.vord/blueprint-templates-archive/ for a project template. You can move the folder back. Delete is refused while a running or halted run uses that template.

Global – all projects is the first section. Create global template opens the choice between an empty template and an editable copy of a shipped template. Both paths save globally. Templates from the focused project follow under Only in project: …. A project template with the same id still takes precedence there. Create project template stays available even when the project has no templates yet.

The guided editor

The editor opens inside the panel, with a ‹ Back button that keeps the overview alive (leaving with unsaved changes asks first). It is a guided form, not a canvas: on the left a vertical chain outline keeps the whole flow visible — numbered steps with title, role, gate name, fan-out hints, loop-back badges, and a colored badge when the live check found problems (red = errors, yellow = warnings). On the right, the selected stage is edited top to bottom:

• Title (required) and Role, with a New role… shortcut.
• When is this stage done? as a radio list with the plain-language names — Self-check, Team lead reviews, Independent review, My approval; the chosen option shows its explanation sentence, including the technical gate name.
• Involve the team lead: No / Notify / Let them decide.
• Parallel to previous stage. Not on the first stage; that switch stays off.
• Optional. Not on human stages; that switch stays off.
• Test timeout (min) on auto stages only. The value is 1–240. An empty field means 30 minutes.
• On failure go back to with a rounds stepper (2–9, only earlier non-human stages offered).
• Advanced folded away: stage id, intent markdown in monospace, test command for auto gates, provider-diversity role for skeptics, parallelism.

There is no class picker: the blueprint class (roster/fan-out) is derived from the data — a stage with parallelism above one makes it a fan-out, everything else is a roster — and shown as a meta line only. The chain outline carries two fixed entries around the numbered steps: Template at the top opens the template settings — name, description, and the budget in plain words (“max agents total”) — and a Roles entry sits below Add stage; New role… jumps to the same place. New templates open directly on the template settings so you name yours first. Add stage appends a step at the chain end; hovering the connector between two rows shows a quiet “+” that inserts a stage right there; hover arrows move a stage, deleting asks for confirmation, and ⌘Z/⇧⌘Z undo and redo — every change is one undo step. Roles referenced by a stage cannot be deleted until you reassign it.

A compact logic-check line runs after every edit: duplicate ids, stages without a role, impossible loops, empty intents, budget below parallelism, and more. It stays collapsed when everything passes and counts errors and warnings otherwise; clicking a finding jumps to the stage. Each finding names both the problem and the fix. Errors block saving; warnings do not. Saving bumps the version automatically — a patch bump for 1.2.3-style versions, otherwise a -edited suffix — so edited copies stay traceable.

Under Only in project: …, Create project template opens a draft of its own. The section stays visible even without existing project templates. Choose Empty template or a global template under From template. A project copy receives its own id; the global template remains unchanged. Only Save stores the draft in the project shown.

Turning workflows on and off

Child sessions and workflows are enabled by default. Saved opt-outs are preserved; the default starts no run itself. When an agent is only waiting for results of a running stage, it ends its turn and receives the child reports automatically. Repeated status polling is not needed for that.

Settings → Agents → Helpers & Workflows has two independent stored switches: Agents may spawn child sessions and Enable workflows. A workflow can start or advance only while both are on. Turning child sessions off does not erase the workflow choice.

The Workflows window only opens while Enable workflows is on: turning the switch off closes an open window, and no entry point reopens it until you turn it back on. Static MCP tool schemas stay registered, and existing runs are not deleted: workflow_status, workflow_abort, and Abort remain available. vord stops advertising workflow instructions at session start, and refuses workflow_start, workflow_gate, workflow_resume, workflow-tagged spawn_agent, and UI continuation actions with the deterministic error workflows_disabled until you turn both switches back on.

Watching a run, and approving a human gate

Approve and Reject on a run card act on the human gate that is waiting. Reject always requires a reason (1–500 characters). Abort from the card, the parent tile, or workflow_abort ends the run, clears the halt reason, and drops any in-flight auto-gate marker — workflow_status then shows [aborted] with no halted: line. A budget halt, including an older halt that stored no reason, offers Resume (+2 children). A halt because the review rounds are used up does not: use One more round on the parent tile.

A run belongs to the parent session that started it. Closing that session, marking it done, or letting its process end aborts its unfinished runs and stops any active auto-gate command. Removing its project from this app instance does the same. Aborted runs remain in history and are not reactivated when the session is restored. After a normal app restart, resumable sessions stay linked to their runs. Startup cleanup only acts on locally known owners that have since been archived or moved to another project. Unknown owners may belong to another app instance, so their runs and pending notifications remain unchanged.

The parent tile

The parent tile in the cockpit carries a stage strip. Stages that share a step stack in one column. A skipped stage reads “skipped”. A stalled child shows a line such as “UI” has shown no activity for 17 min. and the tile offers no buttons for that stall. Passed, current, and future stages stay visible; this is observed progress, never a guessed percentage or ETA. Click the strip to focus the run in the Workflows panel. When the run needs you or hits an exception, the same space becomes an action banner. One more round is one of those tile actions when the review rounds are used up. A child tile shows which stage it works on; children replaced by a loop-back read “Round 1 · replaced”.

Open the Team density (View Densities) for the same strip above the parent and child grid, with actions embedded when needed. Whichever surface you use, only you can pass a human gate — the parent agent never gets a button that means yes.

Permission and plan boxes on the children still wait for you, as always — a workflow does not let the parent click those. See Child Sessions.

The agent is notified when a gate resolves

You do not need to relay gate outcomes to the parent, and the parent does not need to poll. Whenever a gate resolves — you approve or reject a human gate, an auto gate finishes, a loop jumps back, or the run halts or resumes — vord messages the parent session itself, with the concrete next step in the text (workflow_status, then continue with the pending stage). Duplicate deliveries of the same event are suppressed by construction: each notification carries a deterministic id derived from the run, stage, event kind, round, and second. workflow_status remains available for anything the parent wants to check on its own.

Workflow budget

A run has no overall time limit. The shipped blueprints set a spawn budget and nothing else, so an overnight job that legitimately takes eleven hours simply runs. What is limited is always a single piece of work, never the job as a whole: every auto-gate command is killed after 30 minutes by default with its whole process group (per stage configurable via testTimeoutMinutes, 1–240, per gate overridable via timeout_minutes), and the spawn budget caps how many children the run may start.

The start budget is the largest of three numbers: the blueprint’s default, an explicitly requested max_spawns, and a worst-case estimate. The worst case sums one start for every non-human stage (package hints count, at least one each) plus, for every review stage with a loop-back, (rounds − 1) × the starts the loop would spend again, plus a 2-spawn reserve.

When the spawn limit is exhausted, vord refuses further spawns of that run. Children that are already attached keep working, and their gates still pass — using the last spawn on the skeptic of the final stage is fine. The run is marked Halted in the Team progress strip only when it cannot go on without another child: the open stage has no child yet. The run does not quietly continue. A gate that is already running is never cut off. If a test command is in flight when the spawn budget runs out, it runs to its own end and its result is stored; only then does the run halt. Only Abort stops a running command and clears its marker; Resume clears a marker left behind by an older halted run.

Finished work is never thrown away by a budget. Recording a gate is bookkeeping about work that is already done, not new work, so a result that arrived is always evaluated, stored and applied first. Only then does the run stop in front of the next step. A skeptic report that arrives as the spawn budget runs out is accepted and kept; the run halts before the next child, not before your evidence.

At a budget halt you get Resume, which adds two spawns — no minutes are added, because a run has no time limit to extend. You continue a halted run with workflow_resume (additional_spawns); aborting and starting over is not the way out — finished stages, evidence, and rounds are preserved by a resume and lost by a restart. Resume is only for a budget halt (including older halted runs that have no stored reason); Abort is offered next to it. A human gate still waits for you — the budget is a stop, not a skip. Aborting a halted run clears the halt reason so status no longer claims the run is halted.

This is separate from the concurrent child-session cap under Helpers & Workflows (1–20, default 3; a note appears above 8). The cap is how many children one parent may run at once. The workflow budget is how many that run may start.

Tools the parent uses

These six tools live in the same vord-mcp server as the child-session tools.

Tool	What it does
workflow_list	Enabled blueprints for this project, one compact line each with a short description (id — name [class] origin=… N stages — description). Disabled templates are omitted.
workflow_start	Starts a run from an enabled template (blueprint_id) or from a session-bound definition (custom_workflow). Exactly one source is required. max_spawns overrides the default spawn budget; there is no duration parameter, because a run has no time limit. An agent that passes max_duration_minutes anyway has it ignored and gets the note Note: workflows have no run time limit; max_duration_minutes was ignored. The answer contains run_id, the paths of the stage instructions, the role requirements, and the number of children that may run in parallel (the max children per session setting).
workflow_gate	Record evidence for the current stage’s gate — out-of-order gates are refused. Human gates are always refused here. An optional non-human stage can instead be skipped with decision: skip plus a reason. For an auto gate the parent passes a test_command (or vord uses the stage’s stored command, which repo-provided templates only run after you trusted it — see above); vord starts it and immediately answers that the gate is running — when it finishes, vord messages the parent with pass/fail, exit code, and log path, so no polling is needed. Orchestrator gates need a non-empty parent summary. Skeptic gates read the final WORKFLOW_VERDICT: line from the stage-bound skeptic child’s report file and record any provider-diversity warning against the real sessions. A failed gate with a loop configured loops the run back automatically.
workflow_status	Compact run state: stage statuses, child count, remaining budget, and the number of children that may run in parallel. An auto gate in progress is shown with how many seconds it has been running. A halt reason is printed only while the run is actually halted. A stage with failed start attempts shows their count and the reason for the most recent one.
workflow_abort	End a run early (status aborted), clear the halt reason, drop any in-flight auto-gate marker, and stop a test command that is already running (the process group is sent SIGTERM, then SIGKILL). Needed before spawning children outside a run while one is active.
workflow_resume	Continue the parent’s own budget-halted run with a required reason and an additional_spawns count — a resume adds starts, not minutes. There is no duration_headroom_minutes parameter, because a run has no time limit; an agent that passes it anyway has it ignored and gets the note Note: workflows have no run time limit; duration_headroom_minutes was ignored. Bounded on purpose: three self-resumes between human ones. An optional resume_request_id makes a retry safe: repeating it unchanged returns the original result and sends no second message; repeating it with different arguments is refused instead of silently swallowed. A run that is still running with an exhausted spawn budget but a current non-human stage with at least one attached child and a gate that is not in flight can also request a bounded extension — child evidence, stage status, and round are preserved and the same quota applies.

spawn_agent gains three optional fields when it is part of a run: workflow_run_id and workflow_stage_id, plus workflow_package — a 1–80 character label naming the package when several children build one stage in parallel. The label is accepted only together with workflow_run_id and workflow_stage_id. With no run active, spawns are ordinary children, unchanged. While a run is active, an untagged spawn starts as an ordinary side child: it does not count against the run’s budget, and the answer notes that the child is not attached to the run. For a tagged spawn, vord checks the gate and budget before starting the child. A skeptic provider match or missing referenced role is returned to the parent as a warning and stored with the gate evidence; it is not a spawn block. Passed stages and human gates do not accept children.

If the gate and budget check passes but the actual start then fails (no license, no matching account, the agent binary is missing, or a native start error) the attempt does not count against the spawn budget — no work happened, so nothing is charged for it — but it stays visible: the stage keeps a capped list of its last 20 failed attempts (timestamp, agent, model, error code) plus a running total, shown in workflow_status and as a tooltip on the stage strip.

Failed stages stay visible and can be retried by running their gate again. While a run is active, resume_agent is limited to children already attached to one of that run’s stages; resume anything else only after workflow_abort. Runs belong to the parent session that started them; other sessions and child sessions cannot gate or abort them.

Related

• Child Sessions — spawning and steering the children a blueprint runs.
• View Densities — Team view, where run progress and Approve live.
• Child Sessions — the shared settings page and always-available run panel.