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:, 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.

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.

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. The list source can be a JSON/YAML array or a newline-delimited block; if the rendered value starts with [ it is parsed as an array, otherwise each non-empty line becomes one item.

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: — deterministic connector call

An action step calls one SCM / issue-tracker / CI tool directly through the same in-process MCP tool catalog agents use. No agent runs, no tokens are spent, and the result is deterministic. Use it whenever the work is "make this one API call" rather than "reason about something".

Rules.

• Mutually exclusive with agent/prompt, for_each:, parallel:, panel:, and approval:.
• with: must be a mapping. An unknown parameter key, or a missing required parameter, is a parse error — validated against the static catalog, so linting a workflow needs no credentials.
• Parameter values are not checked at parse time (they may be templates); they are re-validated after rendering, immediately before dispatch.
• when: and continue_on_error: behave exactly as on any other step. A template-render failure in with: always aborts, even under continue_on_error, because that is an authoring error rather than a runtime one. There is no built-in retry.
• The executed call is recorded in the run's audit trail as an action envelope, unified with the agent action protocol.

Published output. The connector's JSON response, bound to steps.<id>.output.

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

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", "reason", "decided_at" } — where decision is approved or rejected and via is human or auto. The convenience shortcut steps.<id>.decision exposes the decision string directly.

  - id: merge_gate
    approval:
      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.

The action catalog

These are the tools an action: step (or a gate's notify:/on_reject: entry) may name. It is the same catalog the embedded MCP server exposes to agents — one catalog, one permission model.

Three things to know about with::

• Parse-time validation. Keys are checked against the tool's schema when the workflow loads. An unknown key or a missing required key is a load error, not a runtime surprise — and the check needs no credentials.
• Platform defaults. 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, exactly as the MCP tools do.
• Permission mode. Action steps run under the same mode as the rest of the run. In readonly mode a write-class action fails with an explicit permission error before the connector is ever called. ask mode does not prompt per action step — the workflow author declared the call deliberately.

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; with: must be a mapping whose keys are all schema properties, with every required property present. Gate notify entries are validated by the same rules.

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: []
    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:
      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)"