Authoring reference

The complete workflow schema — every top-level key, every step kind, every field, and the rules the parser enforces before a run ever starts.

This page is the reference. If you want the conceptual tour — what a workflow is, why you would fan out, how runs are launched — start on Workflows and come back here for the exact field names.

Everything below is validated at parse time. Workflow YAML is parsed strictly: unknown keys inside trigger:, inputs:, panel:, branch:, approval:, distribute:, defaults:, contracts:, autoflow: (and each of its sub-blocks), run:, join:, a loop definition, a step, or the document root are rejected outright rather than silently ignored. A typo is a load error, not a surprise at 3 a.m.

Workflow anatomy

A workflow is one YAML document. Only name and a non-empty steps array are required; every other key is optional and has a documented default.

The minimal skeleton, with every optional block shown in position:

name: my-workflow
description: What this pipeline does.

trigger:
  on: manual              # manual | cron | event

inputs:
  target:
    type: string
    required: true

defaults:
  continue_on_error: false

contracts:
  outputs:
    result:
      from_step: handoff
      format: json
      schema: autoflow_outcome_v1

notifyIssue: false

steps:
  - id: handoff
    agent: writer
    actions: []
    prompt: "Work on {{ inputs.target }}."

The trigger: block

The defaults: block

The contracts: block

A step may also carry its own contract: { emits, format } as authoring metadata. If a step's contract disagrees with the workflow-level declaration that points at it, the workflow is invalid — the workflow-level entry is the runtime authority.

The concerns: block

A workflow can declare one coverage catalog for the whole run, in the same shape as an agent’s concerns: frontmatter (catalog includes, with optional overrides, filters and render mode). When it does, every agent step runs with it, and each step agent’s own concerns: is ignored for this run. When it doesn’t, each step uses its agent’s block, if any.

name: payments-review
concerns:
  - include: owasp-top10-2021
  - include: secrets-in-source
steps:
  - id: map
    agent: surface-mapper        # its own concerns: (if any) are ignored here
    actions: []
    prompt: "Map the request handlers under services/payments."
  - id: review
    agent: security-reviewer
    actions: []
    prompt: "Review what map found: {{ steps.map.output }}"

All of a workflow’s steps report into one coverage target, keyed by the workflow’s name, so their file touches, verdicts and findings accumulate in one ledger whichever agent ran each step. The workflow-level block is what makes that ledger coherent: one catalog, one snapshot, one audit. (A workflow launched as an agentiflow unit reports into the agentiflow’s target instead.) See Coverage.

The messaging: key

Every workflow run has one message space, and every agent step and unit joins it as it starts. Messaging is on by default: each step and unit is offered board.claim, board.release, board.post, board.read and msg.send, recorded in its tool_grant as ambient:messaging_default. The top-level messaging: key changes that for the whole workflow:

name: quiet-review
messaging: false         # no messaging tool for any step or unit, or anything they launch
steps:
  - id: review
    agent: reviewer
    prompt: Review crates/rupu-cp.

A placed unit (host: / distribute:) runs on another machine with a space of its own there, and the key reaches it: false is launched as rupu run --no-messaging, and true or { tools: [...] } as one rupu run --messaging-tool per tool. A host whose rupu doesn’t advertise the capability (agent.no_messaging / agent.messaging_tools) is refused the unit rather than run it with messaging on. An agent file’s own messaging: false turns it off for that agent wherever it runs, and off wins over everything else. An autoflow is a workflow with an autoflow: block, so the same key is its opt-out.

The autoflow: block

Optional metadata that lets rupu autoflow run the workflow on its own: which issues or pull requests it may claim, when it wakes, where it works, and which declared output it hands back. The steps: DSL is unchanged. Every key is optional and unknown keys are rejected at every level. This is the field list; the behaviour (claims, leases, worktrees, the outcome loop) is explained on Autoflows.

Durations (reconcile_every, claim.ttl) are digits followed by exactly one of s, m, h, d — 45s, 15m, 6h, 2d. Compound forms and bare numbers are parse errors.

The autoflow.selector: block

The three label lists combine with AND: an item must carry every labels_all label, at least one labels_any label (when that list is non-empty), and no labels_none label. Labels compare as exact, case-sensitive strings.

autoflow:
  enabled: true
  entity: issue
  selector:
    states: [open]
    labels_all: [bot-ready]
    labels_any: [area:parser, area:cli]    # either area will do
    labels_none: [blocked, bot-done]       # drop out once handled
  wake_on: ["github.issue.*"]
  reconcile_every: "30m"
  claim: { key: issue, ttl: "2h" }
  workspace:
    strategy: worktree
    branch: "bot/issue-{{ issue.number }}"
  outcome: { output: result }       # must name a contracts.outputs key

Inputs

Inputs are declared once and supplied at run time with a repeated --input key=value flag. Each declaration is validated at parse time (the default must coerce to the declared type, and must be a member of the enum when one is given), and each supplied value is validated before the first step runs.

inputs:
  diff:
    type: string
    required: true
    description: The unified diff under review.
  retries:
    type: int
    default: 3
  severity:
    type: string
    default: high
    enum: [low, medium, high, critical]
  strict:
    type: bool
    default: true

rupu workflow run code-review-panel \
  --input diff="$(git diff origin/main)" \
  --input severity=high

Step kinds

Every step has a unique id and exactly one execution shape. The shape is inferred from which block is present; the parser rejects any combination of two.

Two more step forms do no work of their own: a split: node forks into named concurrent tracks and a join: node is a barrier that gathers them. They are pure routing and belong to Graph orchestration below.

Linear step

One agent runs one rendered prompt; its final assistant text becomes steps.<id>.output for every later step. This is also the only shape that accepts host:.

Rules. Both agent and prompt are required — a step with neither a block nor both of these fails to parse. host: may not be combined with distribute:.

  - id: investigate
    agent: fix-bug
    actions: []
    prompt: |
      Investigate the bug described by:
      {{ inputs.prompt }}

      Stop without making edits. Report the root cause as text.

for_each: — data fan-out

One agent, one prompt, run once per item of a rendered list. If the rendered value starts with [ it is parsed as a JSON array — and if it doesn’t parse, the step fails with the parse error before any unit runs; otherwise each non-empty line becomes one item. To fan out over a list of objects from another step, render it with | tojson, e.g. for_each: "{{ (steps.tagged.output | fromjson).rows | tojson }}" after an action: findings.query step with all: true.

Published outputs. steps.<id>.results is the list of per-item output strings; steps.<id>.output is the JSON array of those strings; steps.<id>.success is true only if every item succeeded.

  - id: review_each
    agent: code-reviewer
    actions: []
    for_each: "{{ read_file('reports/items.json') }}"
    max_parallel: 4
    prompt: |
      Review {{ item }} ({{ loop.index }} of {{ loop.length }}).

parallel: — agent fan-out

N distinct sub-steps over the same context, each with its own agent and prompt. The parent step carries no agent or prompt of its own.

Rules. A sub-step accepts only id, agent, and prompt — actions: and continue_on_error: belong to the parent and cover the whole block. Duplicate sub-step ids are a parse error, and an empty parallel: list is a parse error.

Published outputs. steps.<id>.sub_results.<sub_id>.output and .success per sub-step, plus the list form steps.<id>.results in declared order.

  - id: review
    actions: []
    max_parallel: 2
    parallel:
      - id: security
        agent: security-reviewer
        prompt: "Review for security issues: {{ inputs.diff }}"
      - id: perf
        agent: performance-reviewer
        prompt: "Review for performance issues: {{ inputs.diff }}"

panel: — structured review

Several reviewer agents run in parallel over one rendered subject and each returns a JSON object containing a findings array. rupu extracts the first parseable object from each panelist's final message (surrounding prose is tolerated); a panelist that emits malformed JSON contributes zero findings and logs a warning.

Rules. panel: is mutually exclusive with for_each:, parallel:, action:, and the top-level agent/prompt. Empty panelists is a parse error.

Published outputs. steps.<id>.findings (each entry carries source, severity, title, body), .max_severity, .iterations, .resolved, and .output as the JSON findings array.

  - id: panel_review
    actions: []
    panel:
      panelists:
        - security-reviewer
        - performance-reviewer
        - maintainability-reviewer
      subject: "{{ inputs.diff }}"
      max_parallel: 3
      gate:
        until_no_findings_at_severity_or_above: high
        fix_with: finding-fixer
        max_iterations: 3

The findings JSON each panelist must return:

{
  "findings": [
    {
      "severity": "low|medium|high|critical",
      "title": "Short title",
      "body": "One sentence of detail"
    }
  ]
}

branch: — conditional routing

A branch step dispatches no agent. It renders condition, records which arm it took, and marks every step id on the other arm as skipped for the rest of the run. Truthiness uses the same rule as when:.

Rules.

• Mutually exclusive with agent/prompt, for_each:, parallel:, panel:, and action:.
• when: is not allowed on a branch step. The runner evaluates when: before the branch block, so a falsy when: would skip the branch without its condition ever running — and then both arms would execute. The parser rejects it outright.
• Every target must name an existing step, and must appear strictly after the branch step in declaration order. Branches route forward only; they are not a loop construct.
• An id may not appear in both then and else, and neither arm may target the branch step itself.
• Each arm is the complete, transitive set of ids in that arm — including the arm steps of any branch nested inside it. A nested branch on a not-taken arm never gets to populate its own skip-set, so its steps must already be listed in the outer arm.

Published output. steps.<id>.output is the literal string then or else. Steps skipped by a branch record skipped = true.

  - id: route
    branch:
      condition: "{{ steps.panel_review.max_severity in ['low', ''] }}"
      then: [open_pr]              # clean review — ship it
      else: [file_issue, escalate]  # complete set of ids on this arm

action: — one tool call, no agent

An action step calls one catalog tool directly — the same tool an agent or the control plane’s /mcp endpoint would call — under the run’s permission mode. No agent runs, no model turn happens, no tokens are spent. Use it whenever the work is "make this one call" rather than "reason about something".

Rules, all enforced at parse time.

• action: must name a real tool in the catalog. An unknown name is a parse error.
• The tool must be one an action step may call: not a core fs/shell tool, not one that starts another run, and needing only the services an action step provides (the SCM registry and the findings ledger). Anything else — bash, dispatch, coverage.mark, assets.mark, board.post, … — is a parse error.
• with: must be a mapping. An unknown key, or a missing required key, is a parse error before the run ever starts.
• Mutually exclusive with agent/prompt, for_each:, parallel:, panel:, and branch:.
• An action step must not carry a non-empty actions: list. actions: narrows an agent’s connector grant; an action step’s call is already explicit, so there is nothing to narrow. An empty or absent actions: is legal, if redundant.
• findings_profile is accepted only on action: findings.record; see Findings profile.

Typed values. A with: value is coerced against the tool’s declared schema type:

• a plain literal against an integer / number / boolean field with stray quotes (number: "7") is rejected at parse time — almost always a typo;
• a whole-leaf template (the entire string is one {{ … }} expression) is rendered, then parsed against the declared type; a render that doesn’t fit is a runtime error;
• a partial template mixed with other text ("issue-{{ n }}") against a numeric field is a runtime error rather than a guess — use a whole-leaf template ("{{ n }}") for a typed parameter.

Published output. steps.<id>.output is the tool’s return value serialized as a JSON string, and steps.<id>.success whether the call succeeded. Because output is a string, pull fields out of it with the fromjson filter — {{ (steps.fetch.output | fromjson).title }}, not {{ steps.fetch.output.title }}. The call is recorded in the run’s transcript as an action_emitted line followed by its tool_audit.

  - id: fetch
    action: issues.get
    with: { project: "acme/widget", number: 41 }

  - id: triage
    agent: triager
    prompt: |
      Issue title: {{ (steps.fetch.output | fromjson).title }}
      Labels: {{ (steps.fetch.output | fromjson)['labels'] | join(', ') }}

  - id: open_pr
    action: scm.prs.create
    with:
      owner: Section9Labs
      repo: rupu
      title: "fix: {{ inputs.title }}"
      body: "{{ steps.triage.output }}"
      head: "rupu/issue-{{ issue.number }}"
      base: main
      draft: false

The findings tools work the same way: findings.query with all: true returns every match unpaged, which a for_each takes as its rows (each item is a slim row with id, title, severity, scope, location, concern_id, tags, declared_at, run_id), and findings.tag adds or removes tags on one or many findings.

  - id: tagged
    action: findings.query
    with: { q: "tag:needs-poc severity>=high", all: true }
  - id: poc
    agent: poc-writer
    for_each: "{{ (steps.tagged.output | fromjson).rows | tojson }}"
    max_parallel: 4
    prompt: |
      Write a proof of concept for finding {{ item.id }}: {{ item.title }}
      ({{ item.location }}). When it works, tag it `has-poc` with findings.tag.
  - id: mark
    action: findings.tag
    with: { finding_ids: ["fnd_01J…"], add: ["needs-poc"] }

run: — deterministic command

A run: step executes a declared command and binds its output. Use it when a step must produce an exact value — scoring, validation, report rendering, a preflight check. No language model is involved, so the step is reproducible, instant, and costs no tokens.

  - id: score
    run:
      cmd: python3
      args: ["tools/score_fixture.py", "{{ item.fixture }}", "{{ item.candidate }}"]
      cwd: "{{ inputs.cybermark_root }}"
      env: { CYBERBENCH_RELEASE_KEY: "{{ inputs.release_key }}" }
      parse: json            # json | lines | raw   (default: raw)
      timeout_seconds: 300
      allow_exit_codes: [0]  # default [0]; anything else fails the step

There is no shell.

cmd and args are handed to the OS as an argv vector. There are no pipes, no redirection, no globbing, and no word splitting. Because each args entry becomes exactly one argument, a rendered value containing ;, &&, or $(...) arrives at the process as literal argument text rather than executing — the step kind is injection-safe by construction, not by escaping.

If you genuinely need shell features, invoke a shell explicitly — cmd: sh with args: ["-c", "..."]. That is your decision to make, visible in the workflow file, rather than something the engine does to every step behind your back.

Parse modes.

Published output.

  - id: report
    run:
      cmd: echo
      args: ["scored {{ steps.score.json.score }} / 100"]

Fan-out.

run: composes with for_each: and max_parallel: — that is how you score N items concurrently. With continue_on_error: true, a failing unit is recorded with success = false and the remaining units still dispatch, so one bad item never costs you the other 199. Without it, any failing unit fails the step.

  - id: score
    for_each: "{{ steps.plan.json.jobs }}"
    max_parallel: 8
    continue_on_error: true
    run:
      cmd: python3
      args: ["score_job.py", "--job-id", "{{ item.job_id }}"]
      parse: json

Rules.

• Mutually exclusive with agent/prompt, parallel:, panel:, branch:, action:, split:, and join:. It is compatible with for_each:, when:, and continue_on_error:.
• run.cmd must not be empty, and run.allow_exit_codes must list at least one code.
• distribute: is not supported on a run: step and is rejected at parse time rather than ignored. A run: step executes on the coordinator, and silently dropping a distribute: would let you believe work was spread across a fleet when it never left the local host. Remove it, or use an agent step.
• Each run: step writes a one-record JSONL transcript (argv, exit code, duration, stdout, stderr) so the control plane and the app have something to render where an agent step would have a conversation.

Enabling it: config gate and allowlist.

run: executes commands, so it is opt-in per workspace and off by default.

[workflow]
run_step_enabled = true
# Optional. Empty (the default) permits any executable.
# Matched on basename, so "/bin/bash" and "bash" gate alike.
run_step_allowlist = ["python3", "make"]

A workflow containing a run: step fails when the toggle is off — it does not skip the step. A benchmark that quietly omitted its scoring step would report a plausible-looking but meaningless number.

Approval gate

A step whose only block is approval: — no agent, prompt, for_each, parallel, panel, branch, or action — is a gate node: a first-class "a human decides here" step with its own id, its own graph node, and its own recorded decision.

The older form — approval: sitting alongside an agent+prompt step — is still supported and unchanged. It is called the legacy inline option below, and it accepts only required, prompt, and timeout_seconds.

Gate lifecycle. when: is evaluated first — a skipped step never asks for approval. Then the prompt renders, then auto_approve. If the gate does not auto-resolve, the notify hooks fire and the run parks as awaiting_approval. Resume with rupu workflow approve <run-id>, or reject with rupu workflow reject <run-id> --reason "...", which runs the on_reject chain and then ends the run.

Notify hooks take the same shape as an action step — an action: name plus with: params — and are validated against the tool catalog at parse time, exactly like a real action step.

on_reject entries are ordinary steps, restricted to plain agent steps and action steps: no nested gates, no for_each, no parallel, no panel, no branch. They also may not set host: or when: — cleanup runs inline and unconditionally. Each failure is logged and the chain continues; their results are recorded under their own ids.

Published output. A gate node writes a JSON decision record to steps.<id>.output — { "decision", "via", "approver", "reason", "decided_at" } — where decision is approved or rejected and via is human, auto or timeout. steps.<id>.decision is the decision string, already parsed — no fromjson needed.

Several gates at once. In a graph workflow more than one gate can park in the same wave. Decisions are path-scoped: approving a gate releases only the path behind it; rejecting one prunes only what is reachable solely through it and runs its on_reject chain, while sibling paths keep going (a reject in a plain chain workflow still ends the run). Target a gate with rupu workflow approve|reject <run-id> --gate <step-id> — required once more than one is parked. The run stays awaiting_approval until every gate is resolved, and a still-parked sibling does not re-fire its notify: hooks. A decision is recorded under the run lock and applied by exactly one runner, wherever it was made.

Timeouts need rupu cp serve. timeout_seconds / on_timeout are acted on by the control plane's background gate sweep ([cp].gate_sweep_enabled, default on, every [cp].gate_sweep_interval_secs = 60). Without it, an on_timeout: approve or reject gate simply stays parked until rupu workflow approve or reject decides it (reject runs the on_reject chain), and an on_reject chain triggered from the control plane’s web UI or rupu workflow cancel is recorded as pending and executed by the sweep, so it too waits for cp serve. rupu workflow runs deliberately resolves no gate and runs no cleanup chain — a read command has no external side effects.

  - id: merge_gate
    approval:
      required: true
      prompt: |
        {{ steps.panel_review.findings | length }} findings,
        max severity {{ steps.panel_review.max_severity }}. Approve to open the PR.
      auto_approve: "{{ steps.panel_review.max_severity in ['low', ''] }}"
      timeout_seconds: 86400
      on_timeout: reject          # approve | reject | fail (default: fail)
      notify:
        - action: issues.comment
          with:
            project: Section9Labs/rupu
            number: "{{ issue.number }}"
            body: "Approval needed at merge_gate."
      on_reject:
        - id: note_rejection
          action: issues.comment
          with:
            project: Section9Labs/rupu
            number: "{{ issue.number }}"
            body: "Rejected at merge gate; no PR opened."

The legacy inline option, unchanged, for pausing an agent step in place:

  - id: deploy
    agent: releaser
    approval:
      required: true
      prompt: "About to deploy {{ inputs.tag }}. Approve?"
      timeout_seconds: 3600
    prompt: "Run the release for {{ inputs.tag }}."

Common step fields

These apply across shapes, subject to the rule in the last column.

Step actions: narrowing connector tools

An agent’s tools: says what it may ever call. A step’s actions: narrows that, for this step only, to a subset of the connector tools — scm.*, issues.*, github.* and gitlab.* (the list is in the action catalog). Every other tool — bash, read_file, the findings and coverage tools, dispatch, … — is governed only by the agent’s own tools: and the run mode. Entries use the same grammar as tools:: an exact connector tool name, a namespace (issues.*) or *.

steps:
  - id: triage
    agent: issue-triager           # tools: ["*"]
    actions: [issues.get, issues.comment]
    prompt: "Triage {{ inputs.issue }} and leave one comment."

Here the agent keeps bash, read_file and every other built-in, can read and comment on issues, and can’t open a PR, dispatch a CI workflow or touch any other connector tool during this step.

The tool_audit trail. Every connector call a step makes — by an agent, or by an action: node — writes one tool_audit event to the step’s transcript. Built-in calls don’t. Four booleans describe it:

{"type":"tool_audit","data":{"tool":"scm.prs.create","declared":false,"granted":true,"blocked":true,"restricted":true}}

That line reads: the agent is allowed to open PRs in general, this step didn’t list it, and the call was blocked. Current lines also carry reason (why the tool was in the grant) and decision (allowed, denied:readonly, denied:tool, not_granted, …). The live run view flags blocked calls, and the control plane’s transcript view badges each audited call. The full event schema is in Transcripts.

Launching children from a step

A step’s agent starts other runs with the launch tools dispatch, join and workflows.generate — the same catalog tools every agent run has (see Agents). dispatch takes a kind of subagent (a task in the step’s own process), agent (its own rupu run) or workflow (its own rupu workflow run --plain), returns at once unless wait: true, and join collects the results. The older names — dispatch_agent, dispatch_agents_parallel, run_workflow, generate_workflow — are aliases of these and keep their old output shapes; the model only ever sees the canonical names. What an agent may launch is its dispatchableAgents: / dispatchableWorkflows: lists, and a workflow child is checked before it starts: it parses, has no approval gate and no host: / distribute: step, and runs only agents the caller may dispatch.

Inside a workflow the step’s settings follow the child selectively: its actions: narrowing does (above), while findings_profile and the step’s skills do not — a child resolves both from its own agent file (a workflow child from its own defaults). A child shares the run’s message space, and a messaging: false reaches it.

Step skills

skills: and preload_skills: give skills to the agents a step launches, on top of each agent’s own. The entries use the same grammar as an agent’s skills:, and they only add — they never remove a skill the agent declares.

steps:
  - id: review
    agent: reviewer
    prompt: Review the PR.
    skills: [pdf, "project:*"]      # the model may load these
    preload_skills: [house-style]   # always in the system prompt

• They reach every agent the step launches: its own agent, each for_each unit, the members of a parallel: block, and a panel’s panelists and its gate’s fix_with fixer. A sub-step has no skills: of its own — it takes its parent step’s.
• Allowed only on a step that runs an agent. A gate, action:, run:, branch:, split: or join: step that names them fails to parse.
• Parsing checks each entry’s syntax only. Whether the skill is installed is checked when the step launches, so a missing skill fails that step before its agent runs, the way a missing agent does. The run’s skill_index records step skills with reason launch.
• A placed step (host: or distribute:) ships its skills with the unit; see Remote placement.
• A child the agent starts with dispatch gets its own agent’s skills, not the step’s.

Permission modes in a workflow

rupu workflow run takes --mode ask | bypass | readonly. ask and bypass behave identically for workflow agent steps, and ask is the default when --mode is omitted — so a run without an explicit mode grants its steps full tool access. A genuinely prompting ask would block on stdin with no operator at the tool layer, so instead each step’s transcript records a permission_mode_degraded notice the first time ask lets a write through, and rupu workflow run prints a warning when no mode was given.

If you want a workflow restricted, pass --mode readonly explicitly — ask will not do it. For human-in-the-loop control over what a workflow does, use a gate node rather than the permission mode: a gate pauses the run at a point you choose, where an operator can actually answer. A placed unit runs under the same mode (see Remote placement).

Findings profile

Steps that record findings do so under one of two contracts: full, a complete structured report (the built-in default), or summary, the lightweight summary / severity / rationale record. The profile resolves most-specific first: the step's findings_profile, then defaults.findings_profile, then the agent's findingsProfile frontmatter, then full.

defaults:
  findings_profile: full          # every agent step records complete reports...
steps:
  - id: sweep
    agent: quick-scanner
    prompt: "Skim {{ inputs.path }} for hard-coded secrets."
    findings_profile: summary     # ...except this cheap first pass

• parallel: sub-steps inherit their parent's profile and can't set their own.
• An action: findings.record step resolves its profile as the step’s own findings_profile → defaults.findings_profile → full (there is no agent frontmatter to consult), and checks its with: keys against it at parse time: full needs scope and report; summary needs scope, summary, severity and rationale (optional code_excerpt / references; an evidence object, the agent tool’s form, works in place of the three). Only key presence is checked, so a value may be a template. A gate’s notify: hooks have no step of their own and use defaults.findings_profile, else full.
• Children started with dispatch resolve only from their own agent file (a workflow child from its own defaults); the dispatching step’s value does not reach them.
• Remote steps follow the same order: the coordinator launches each unit with rupu run --findings-profile from the step’s value, else defaults.findings_profile; when neither is set the host resolves the agent’s findingsProfile from its own copy of the agent file, then full. A host that can't honour the profile refuses the launch — the unit never runs under a different profile.
• The built-in default is full, so an older action: findings.record step that sends summary / severity / rationale fails to parse until it sets findings_profile: summary (or the workflow sets defaults.findings_profile: summary).

Remote placement

By default every step’s agent runs locally, in the same process as the rest of the workflow. host: and distribute: place a step’s work on a different host in your fleet instead. A placed unit runs as rupu run <agent> on its host, and its output feeds downstream steps exactly as a local step’s would.

  - id: edit
    agent: editor
    for_each: "x\ny\nz"
    prompt: "edit {{ item }}.txt"
    max_parallel: 3
    workspace: sync
    distribute:
      hosts: [w1, w2]

What travels with the unit. The coordinator launches each unit (and a fan-out unit’s retry on its fallback host) with everything the step resolved:

• Permission mode — rupu run --mode <mode>, which outranks the agent’s permissionMode and the host’s permission_mode config. readonly and bypass travel as they are; ask, the default, travels as bypass (a detached rupu run --mode ask would refuse to start). --mode readonly is how you keep a placed unit from writing.
• Findings profile — as --findings-profile; see Findings profile. Engagement profile ids travel as --engagement-profile; a host that doesn’t advertise agent.engagement_profile is refused the launch, and the host resolves the ids against its own profiles.
• Skills — the coordinator resolves the unit’s skills the way a local run does (the skills: / preloadSkills: of its own copy of the agent plus the step’s skills: / preload_skills:; * means the coordinator’s global layer), packs each as a tar named by its content hash, asks the host which hashes it lacks and sends only those. The host verifies every archive before keeping it (no absolute or .. paths, no symlink leaving the skill, the tree must hash to its name) and runs the unit with exactly those copies, so it needn’t have them installed; a shipped skill replaces the host’s installed one of the same layer and name. A skill tree is at most 32 MiB and a unit’s bundle 128 MiB — the coordinator refuses a unit over either limit before dispatch. A step skill not installed on the coordinator fails the unit before it is dispatched. A host that doesn’t advertise agent.skill_bundle is sent the unit by name and runs it with its own installed copies, and the run gets a warning naming the host. Only the unit’s own skills ship: children it launches on the host resolve from the host’s installed layers. See Skills.
• Messaging — the workflow’s messaging: switch, as --no-messaging or one --messaging-tool per tool; a host that doesn’t advertise agent.no_messaging / agent.messaging_tools is refused the unit. See the messaging key.
• Not actions: — a non-empty actions: on a host:/distribute: step is rejected at parse time: the tool roster never reaches the remote dispatch payload, so a narrowed list there would be a silent no-op. An empty or absent actions: stays legal.

A unit’s findings and coverage reach the coordinator through the run’s coverage stream; the workspace: sync delta still carries .rupu/coverage/, which the coordinator drops once the unit’s complete stream merged and applies otherwise. A stream that can’t be delivered or merged, or that may be incomplete, shows a StepWarning on the step; the unit is not failed. Every placed-unit error and warning is prefixed host <id>:. On rupu workflow resume a placed step or unit is restarted from its prompt, not continued from its transcript.

Graph orchestration

By default steps run in declaration order. A workflow becomes an explicit graph — scheduled by node readiness instead of list order — as soon as any step uses next:, depends_on:, split: or join:, or the workflow declares loops:. Edges from {{ steps.X.* }} template references count too, and the whole edge set must be acyclic.

max_concurrency: 4                  # whole-graph cap (optional)
steps:
  - id: recon
    split: [api, web, infra]        # three concurrent tracks
  - id: api
    agent: api-reviewer
    prompt: "Review the API surface."
    next: [gathered]
  - id: web
    agent: web-reviewer
    prompt: "Review the web client."
    next: [gathered]
  - id: infra
    agent: infra-reviewer
    prompt: "Review the deploy config."
    next: [gathered]
  - id: gathered
    join: { wait: { count: 2 } }    # all (default) | any | { count: N }
  - id: report
    agent: writer
    prompt: "Summarize {{ steps.gathered.results | length }} reviews."
    depends_on: [gathered]

loops:
  refine:
    nodes: [draft, critique]
    until: "{{ 'APPROVED' in steps.critique.output }}"
    max_iterations: 3
    on_max: proceed

The action catalog

These are the tools an action: step (or a gate's notify:/on_reject: entry) may name: the connector tools, which a step’s actions: can also narrow, and the findings tools, which it can’t. It is the same catalog the MCP endpoint and agents use — one catalog, one permission model. Every SCM tool takes an optional platform key and every issue tool an optional tracker key; omit them and rupu falls back to [scm.default] / [issues.default] from your config.

Two things to know about with::

• Parse-time validation. Keys are checked against the tool's JSON Schema when the workflow loads. An unknown key or a missing required key is a load error, not a runtime surprise. Typed values follow the rules under the action step.
• Permission mode. Action steps run under the same mode as the rest of the run (Permission modes). In readonly mode an external tool — one that acts outside this machine, such as scm.prs.create, issues.comment or github.workflows_dispatch — is refused. ask behaves as bypass: nothing prompts per action step.

Template expressions

Prompts, when: conditions, branch.condition, for_each: lists, panel.subject, approval.prompt, auto_approve, and every value inside with: are rendered with minijinja. Missing variables render as empty strings (autoflow runs render strictly — a missing variable is an error there).

The truthiness rule. when:, branch.condition, and auto_approve all render to a string and then reduce to a boolean. Falsy, case-insensitively, is exactly: the empty string, false, 0, no, off. Everything else is truthy — including the string "None", so guard optional values explicitly.

Validation rules

All of these are checked when the workflow file loads — before any provider is contacted and before any token is spent.

Document level

• steps: must be present and non-empty.
• Step ids must be unique across the workflow.
• Unknown keys anywhere in the document are rejected — typos fail loudly instead of being ignored.

Inputs and triggers

• An input's default must coerce to its declared type, and must be a member of its enum when one is declared.
• on: cron requires a non-empty, well-formed 5-field cron:; on: event requires a non-empty event:.
• Cross-field leftovers are rejected: no cron:/event:/filter: on a manual trigger, no event:/filter: on a cron trigger, no cron: on an event trigger.

Step shape

• The shape blocks are mutually exclusive. branch:, panel:, parallel:, action:, and run: each reject the top-level agent/prompt and each other.
• A step that is none of those must supply both agent: and prompt:.
• max_parallel must be ≥ 1; panel.gate.max_iterations must be ≥ 1.
• panel.panelists must be non-empty; a parallel: block must be non-empty and free of duplicate sub-step ids.
• host: is valid only on a linear step, must be non-empty, and may not be combined with distribute:.
• distribute: is valid only on a for_each: step, and its hosts list must be non-empty.
• distribute: is rejected on a run: step — a run: step executes locally on the coordinator, so a distribute: is refused at parse time rather than silently ignored. Remove it or use an agent step.
• workspace: sync is valid only on a remote step (one with host: or distribute:).

Run steps

• run: is mutually exclusive with agent/prompt, parallel:, panel:, branch:, action:, split:, and join:. It is compatible with for_each:, when:, and continue_on_error:.
• run.cmd must not be empty.
• run.allow_exit_codes must list at least one exit code — an empty list can never be satisfied.
• Execution is additionally gated at run time by [workflow] run_step_enabled and run_step_allowlist, and refused entirely under --mode readonly. A workflow with a run: step fails when the toggle is off; it is never skipped.

Branch

• condition must be non-empty; when: is rejected on a branch step.
• Every then/else target must name an existing step, and must run strictly after the branch step.
• An id may not appear in both arms, and neither arm may name the branch step itself.

Approval gates and actions

• on_timeout requires timeout_seconds.
• auto_approve, on_timeout, notify, and on_reject are rejected on the legacy inline approval option — drop the agent/prompt to make it a gate node.
• on_reject entries must be plain agent or action steps — no nested gate, fan-out, panel, or branch — and may not set host: or when:.
• action: must name a tool that exists in the catalog and is action-eligible (a connector or findings tool — not a core tool, not one that starts a run); with: must be a mapping whose keys are all schema properties, with every required property present, and a quoted literal against a typed field is rejected. Gate notify entries are validated by the same rules.
• A non-empty actions: is rejected on an action: step and on a host:/distribute: step; an actions: entry must name a connector tool (an unknown name, or bash / findings.*, is a parse error).

Skills and messaging

• skills: / preload_skills: are accepted only on a step that runs an agent; each entry must be well-formed (the agent skills: grammar). Whether a skill is installed is checked at launch, not at parse.
• A sub-step of a parallel: block accepts no skills: of its own.
• messaging: { tools: [...] } may name only board.* / msg.* tools.

Graph and findings profile

• Every next / depends_on / split target must name a real step, and a step can't point at itself.
• The full edge set — control edges plus the data edges implied by template references — must be acyclic.
• split: and join: nodes may not carry agent, action, for_each, parallel, panel, branch or approval. A join: needs an inbound edge; wait.count can't exceed its inbound paths.
• loops.*.nodes must name ≥ 2 existing steps, none in two loops; max_iterations and max_concurrency must be ≥ 1.
• findings_profile is rejected on a step that runs no agent (branch, gate, run, split, join) and on any action other than findings.record, whose with: keys must match the resolved profile.

Templates and contracts

• A steps.<id> reference to a step that does not exist is an error.
• A reference to a step that runs later is a forward reference and is rejected — its value is not bound yet.
• A steps.<id>.<field> reference must use a known field: output, success, skipped, results, sub_results, findings, max_severity, iterations, resolved, decision, and the run: step fields json, stdout, stderr, exit_code, duration_ms.
• contracts.outputs.*.from_step must name an existing step, and must agree with that step's own contract: on both schema and format.
• autoflow.outcome.output must name a declared workflow output; autoflow durations must look like <int><s|m|h|d>.

A complete annotated example

One workflow using five shapes together: a linear investigation, a review panel with a fix loop, an approval gate with notify and reject-cleanup hooks, a branch that routes on the outcome, and two deterministic action steps on either arm.

name: review-and-ship
description: Investigate, panel-review, gate on a human, then open a PR or file an issue.

inputs:
  title:
    type: string
    required: true
    description: Short summary of the change under review.
  diff:
    type: string
    required: true

defaults:
  continue_on_error: false   # a failed step aborts the run unless it opts out

steps:
  # 1. Linear step — one agent, one prompt. Output lands in steps.investigate.output.
  - id: investigate
    agent: fix-bug
    actions: []
    skills: ["project:*"]       # the project's skills, on top of the agent's own
    prompt: |
      Summarize what this change does and what could break:
      {{ inputs.diff }}

  # 2. Panel — three reviewers in parallel, then a fix loop until nothing
  #    high-or-worse remains (or three passes, whichever comes first).
  - id: panel_review
    actions: []
    panel:
      panelists: [security-reviewer, performance-reviewer, maintainability-reviewer]
      subject: "{{ inputs.diff }}\n\nContext: {{ steps.investigate.output }}"
      max_parallel: 3
      gate:
        until_no_findings_at_severity_or_above: high
        fix_with: finding-fixer
        max_iterations: 3

  # 3. Approval GATE NODE — no agent, no prompt: just a human decision.
  #    A clean panel auto-approves; otherwise the run parks and pings the issue.
  - id: merge_gate
    approval:
      required: true
      prompt: |
        {{ steps.panel_review.findings | length }} findings
        (max severity: {{ steps.panel_review.max_severity }}). Ship it?
      auto_approve: "{{ steps.panel_review.max_severity in ['low', ''] }}"
      timeout_seconds: 86400
      on_timeout: reject
      notify:
        - action: issues.comment
          with:
            project: Section9Labs/rupu
            number: "{{ issue.number }}"
            body: "Waiting on approval at merge_gate."
      on_reject:
        - id: note_rejection
          action: issues.comment
          with:
            project: Section9Labs/rupu
            number: "{{ issue.number }}"
            body: "Rejected at merge gate — nothing was opened."

  # 4. Branch — routes forward only. Each arm lists EVERY id on that arm.
  #    No `when:` allowed here; the condition is the gate.
  - id: route
    branch:
      condition: "{{ steps.panel_review.resolved }}"
      then: [open_pr]
      else: [file_followup]

  # 5a. Action step — a typed API call. No agent, no tokens, no ambiguity.
  - id: open_pr
    action: scm.prs.create
    with:
      owner: Section9Labs
      repo: rupu
      title: "fix: {{ inputs.title }}"
      body: "{{ steps.investigate.output }}"
      head: "rupu/{{ inputs.title }}"
      base: main

  # 5b. The other arm. continue_on_error keeps a tracker outage from
  #     failing an otherwise-successful run.
  - id: file_followup
    action: issues.create
    continue_on_error: true
    with:
      project: Section9Labs/rupu
      title: "Unresolved review findings: {{ inputs.title }}"
      body: |
        The panel did not clear after {{ steps.panel_review.iterations }} passes.
        {% for f in steps.panel_review.findings %}
        - [{{ f.severity }}] {{ f.title }} ({{ f.source }}): {{ f.body }}
        {% endfor %}
      labels: [review, needs-triage]

Validate it before you run it — rupu workflow show <name> resolves and parses the file, so every rule on this page fires there first:

rupu workflow list
rupu workflow show review-and-ship
rupu workflow run review-and-ship \
  --input title="empty-cart NPE" \
  --input diff="$(git diff origin/main)"

# or run a file that isn't in the catalog yet
rupu workflow run --file ./review-and-ship.yaml --input title="empty-cart NPE"