Step kinds reference
Every workflow step kind (Agent, Check, Human, Decide, Read, Transform, Repeat for each, Notify, Send to URL, Deliver) with fields, owners, outputs and examples.
On this page
A workflow is a list of up to 24 steps. Each step has a kind that decides what it does and which extra fields it has, plus a set of common fields every step shares. This page is the reference for both. Examples use the YAML workflow file format (snake_case keys), which matches the Workflows API.
Adding steps
In the factory’s Workflows tab, add a step with the + between two steps, Add step, or the graph’s context menu (Add a step after, before or beside). A step added beside another has the same Runs after as it, so both run in parallel; the Summary view says “At the same time”. You can also describe the step in the chat pane and apply the agent’s proposal to your draft.
Duun places some kinds for you: a new Read step goes before the first Decide, and a new Decide goes before trailing Notify, Send to URL and Deliver steps.
Common fields
Every step has these fields in the inspector.
| Field | YAML key | What it does |
|---|---|---|
| Name | name | Shown in the graph, runs and reports. The step id is a slug of the name (≤ 56 characters, -2 added on a clash) |
| Runs | enabled | Turn a step off without deleting it. Steps after it re-link to whatever it ran after |
| Owner | owner | Who does the work: Duun (orchestrator), an agent and model (agent), PR review (reviewer) or a Human (human) |
| Instructions | instructions | What the owner does in this step. Supports references |
| Done criteria | done_criteria | How the workflow knows this step is complete |
| Skills | skills | Skills the owner loads for this step, by name |
| Knowledge | knowledge | Context documents to include |
| Runs after | depends_on | Steps that must finish first. Default: the step before it, or the start for the first step |
| Gate | gate | A check that must pass before anything after this step runs. See Gates and failure handling |
| Outputs | outputs | Named fields later steps can reference: key, type (text, number, boolean, enum, list, url, markdown), description, values (enum), required |
| Limits | limits | Per-step budget_usd, timeout_min and retries. See Limits and budgets |
Human owners are one of Issue owner (issue_owner), CODEOWNERS (codeowners), Project lead (project_lead) or Anyone on the project (anyone).
Summary of kinds
| Kind | Id | Default owner | What it’s for |
|---|---|---|---|
| Agent | agent | builder agent | An agent does the work |
| Check | check | Duun | CI, QA, review or a judged check |
| Human | human | Issue owner | A person approves or does the work |
| Decide | decide | Duun or an agent | Choose what happens next |
| Read | read | Duun | Read a document into the run |
| Transform | transform | An agent | Shape output into named fields |
| Repeat for each | foreach | Duun | Run steps once per item in a list |
| Notify | notify | Duun | Tell a channel, a person or the inbox |
| Send to URL | webhook | Duun | Send the result to a URL |
| Deliver | deliver | Duun | Open a PR, merge on green |
Agent
An agent does the work: plan, implement, write tests, review. Pick the agent and model as the owner, and optionally a permission mode that is stricter than the agent’s own (all, writes or auto in files, matching Ask for everything, Ask for writes and Autonomous in sandbox). A new Agent step declares a summary output (markdown, “What it did”).
- id: implement
kind: agent
name: Implement in isolated worktree
owner: { kind: agent, agent: builder, model: opus-5.5 }
permission: writes
instructions: |
Implement the approved plan: {{steps.plan.output.summary}}
Follow #payments for anything that moves money.
done_criteria: Tests for every changed branch pass locally.
skills: [payments, postgres]
outputs:
- { key: summary, type: markdown, description: What it did }
limits: { budget_usd: 4, timeout_min: 60 }Check
A Check runs a command or a review and gates what follows. Its gate type is required: CI green, QA check, Review check, Judgment or Fact check. CI green and QA check need a command (““CI checks”: which command should the check run?”); Judgment and Fact check need criteria.
- id: ci
kind: check
name: CI and contract tests
owner: { kind: orchestrator }
instructions: Run the checks and report each failure with its log.
done_criteria: Every check is green.
gate:
type: ci_green
command: pnpm ci
on_fail: { return_to: implement, policy: retry_with_feedback, max_attempts: 3 }Human
A Human step pauses the run until a person approves, or does the work themselves. It creates an ask in the Inbox. Fields: the approver (owner), SLA hours and who to escalate to when the SLA passes. The default gate is User approval.
- id: approve-plan
kind: human
name: Approve plan
owner: { kind: human, who: issue_owner }
instructions: Review the result and approve, or send it back with a note.
gate: { type: user_approval, on_fail: { return_to: plan, policy: retry_with_feedback, max_attempts: 3 } }
sla_hours: 4
escalate_to: "#platform-oncall"Decide
A Decide step picks which steps run next. It holds a list of outcomes, each with a condition and target steps, and an Otherwise fallback. Mode is First match or All matches. Decide doesn’t need instructions, but a judged outcome needs a question. See Decide and outcomes.
- id: size
kind: decide
name: Size & route
owner: { kind: agent, agent: architect, model: opus-5.5 }
instructions: Estimate PR count and blast radius of {{input.issue}}.
outputs:
- { key: prs, type: number }
control:
mode: first_match
cases:
- id: small
label: Small
when: { name: expression, expr: "{{steps.size.output.prs}} <= 1" }
activate: [implement]
otherwise: { activate: [spec] }Read
A Read step loads a document into the run’s context so later steps can use it. Source types: a document from the knowledge base (doc), a URL (url), a file in the repo (repo_file) or the issue that started the run (issue). A new Read step declares a doc output (markdown).
- id: runbook
kind: read
name: Read the payments runbook
owner: { kind: orchestrator }
instructions: Load the document into the run's context.
source: { type: repo_file, path: docs/runbooks/payments.md }
outputs:
- { key: doc, type: markdown }Errors you may see: “Add the URL to read.”, “Add the file path to read.”, “Choose a document.”
Transform
A Transform turns free text into named fields that later steps and decisions can rely on. Set the input (usually a reference to an earlier output) and at least one output field. The inspector previews the JSON shape.
- id: triage-fields
kind: transform
name: Turn the input into fields
owner: { kind: agent, agent: builder, model: sonnet-5.5 }
instructions: Extract the fields below from the input.
input: "{{trigger.alert.title}}"
outputs:
- { key: severity, type: enum, values: [low, medium, high], required: true }
- { key: service, type: text, required: true }
- { key: files, type: list }A Transform needs an input (““Turn the input into fields” needs an input to shape.”) and at least one field. An enum with no values is a problem: “Output “severity” is an enum with no values.”
Repeat for each
Runs a set of body steps once per item in a list output. Fields: items (a reference to a list output), body (the steps to repeat), concurrency (1–8) and max items. Inside the body, {{item}} and {{item.index}} refer to the current item. A Decide outcome can use Child runs roll up to check that every repetition succeeded.
- id: per-package
kind: foreach
name: Upgrade each package group
owner: { kind: orchestrator }
instructions: Run the body once per item.
items: "{{steps.scan.output.groups}}"
body: [upgrade, test-group]
concurrency: 2
max_items: 10If the reference isn’t a list: ”“{{steps.scan.output.summary}}” is a markdown, not a list.” Concurrency outside 1–8: “Concurrency must be between 1 and 8.”
Notify
Tells someone the result. Channel types: a Slack channel (slack), a person (person) or the Inbox (inbox). The message supports references and defaults to the previous step’s first output.
- id: tell-team
kind: notify
name: Post the result in Slack
owner: { kind: orchestrator }
instructions: Post the result to the channel.
channel: { type: slack, channel: "#factory-platform" }
message: "Merged: {{steps.ship.status}} · {{steps.implement.output.summary}}"Errors: “Choose a channel.”, “Choose a person to notify.”, ““Post the result in Slack” needs a message.”
Send to URL
Sends a JSON body to an https:// URL, for example a status page or deploy hook. Fields: URL, method (POST or PUT), headers, body (JSON with references) and an optional signing secret. This is the only place {{secrets.NAME}} references are allowed; they’re shown masked. Use Send test in the inspector to check the endpoint.
- id: deploy-hook
kind: webhook
name: Send the result to a webhook
owner: { kind: orchestrator }
instructions: Send the result to the URL.
url: https://deploy.acme.dev/hooks/duun
method: POST
headers:
- { key: Content-Type, value: application/json }
- { key: Authorization, value: "Bearer {{secrets.DEPLOY_HOOK_TOKEN}}" }
payload: |
{
"factory": "{{factory.name}}",
"pr": "{{steps.ship.status}}",
"summary": "{{steps.implement.output.summary}}"
}Errors: “Add a URL.”, “Use an https:// URL.”, “The body isn’t valid JSON.” (references are replaced before the JSON is checked).
Deliver
Opens a pull request from the run branch and, depending on the mode, merges it. Modes: Merge on green (merge_on_green: squash once checks and reviews pass), Open PR only (open_pr: a human merges) or Draft PR (draft_pr: for early feedback). Optionally post a changelog line to a Slack channel.
- id: ship
kind: deliver
name: Open PR & merge on green
owner: { kind: orchestrator }
instructions: Open a PR from the run branch; merge when checks and reviews pass.
mode: merge_on_green
changelog: { channel: "#releases" }Workspace and factory guardrails still apply: if a factory requires human review to merge, Merge on green waits for a Review pull request ask.
Ordering and parallel steps
By default steps run in list order. Set Runs after to run a step after several others, or after an earlier step so it runs alongside its neighbours. Duun refuses orders that can’t run:
- ““Implement” depends on itself. Pick another step for Runs after.”
- ““Implement” depends on “spec”, which no longer exists.”
- ““Implement” sits in a dependency cycle — no step on it can run first.”
- “A workflow can have up to 24 steps.”
When you delete a step that another step returns to on failure, or that is the only target of an outcome, Duun asks you to change those first.