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.

FieldYAML keyWhat it does
NamenameShown in the graph, runs and reports. The step id is a slug of the name (≤ 56 characters, -2 added on a clash)
RunsenabledTurn a step off without deleting it. Steps after it re-link to whatever it ran after
OwnerownerWho does the work: Duun (orchestrator), an agent and model (agent), PR review (reviewer) or a Human (human)
InstructionsinstructionsWhat the owner does in this step. Supports references
Done criteriadone_criteriaHow the workflow knows this step is complete
SkillsskillsSkills the owner loads for this step, by name
KnowledgeknowledgeContext documents to include
Runs afterdepends_onSteps that must finish first. Default: the step before it, or the start for the first step
GategateA check that must pass before anything after this step runs. See Gates and failure handling
OutputsoutputsNamed fields later steps can reference: key, type (text, number, boolean, enum, list, url, markdown), description, values (enum), required
LimitslimitsPer-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

KindIdDefault ownerWhat it’s for
Agentagentbuilder agentAn agent does the work
CheckcheckDuunCI, QA, review or a judged check
HumanhumanIssue ownerA person approves or does the work
DecidedecideDuun or an agentChoose what happens next
ReadreadDuunRead a document into the run
TransformtransformAn agentShape output into named fields
Repeat for eachforeachDuunRun steps once per item in a list
NotifynotifyDuunTell a channel, a person or the inbox
Send to URLwebhookDuunSend the result to a URL
DeliverdeliverDuunOpen 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: 10

If 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.

    Type to search the docs, help center and blog.