Build your first factory

Walk through the New factory wizard step by step, then edit the workflow it creates and see the same factory as a workflow file.

On this page

A factory is a workflow, at least one trigger and a set of guardrails, pointed at your repositories. The New factory wizard builds all of that in six steps. This page explains every field so you can make informed choices, then shows what to change afterwards.

Before you start, connect your repository host (GitHub, Bitbucket or Azure DevOps), where factories open pull requests, and, if you want issue triggers, Linear, GitHub Issues or Jira. See Connecting integrations.

Open the wizard

Open Factories in the sidebar and choose New factory, or press ⌘ K and type “New factory”. The wizard shows a live preview of the factory as you go, and you can step back at any point without losing what you entered.

1. Template

“Factories are a workflow, a trigger and guardrails. Start from a proven one or build from scratch.”

TemplateWhat it doesDefault triggerDefault steps
Ship featuresIssue in Ready → plan, approve, build, test, review, mergeLinear labelSize & route, Plan, Human approval, Implement, CI checks, Agent review, Ship
Fix bugs from SentryNew Sentry issue → reproduce, fix with a regression test, draft PRSentry alertReproduce from the stack trace, Plan the fix, Implement, Add regression test, CI checks, Open draft PR
Dependency upgradesWeekly: group upgrades, fix breakages, merge when greenSchedule, Mondays 06:00Scan and group upgrades, Upgrade and fix breakages, CI checks, Agent review, Ship
Docs & changelogFriday: gather merged PRs, draft docs and changelog, ask for reviewSchedule, Fridays 16:00, plus GitHub label docsGather merged PRs and diffs, Draft docs and changelog, Review copy, Open PR
BlankOne implement step and a PR. Build the rest yourselfNoneImplement, Ship

More templates, from Duun and the community, are on Explore. Templates installed from Explore open this same wizard with the fields filled in.

2. Basics

“What it’s called, where it works and which project its runs belong to.”

  • Name: shows in the sidebar as “Name factory”. Required.
  • Description: shown on the factory’s card.
  • Repositories: pick at least one. Agents read these for context and open pull requests against them.
  • Base branch: the branch pull requests target, usually main.
  • Project: runs from this factory land in this project. Choose No project (workspace) to keep runs at the workspace level.

3. Workflow

“The steps every run goes through, in order. Each agent step picks who does it.”

The wizard shows the template’s steps as a simple list. Add steps from the menu (Plan, Implement, Test, Agent review, CI checks, Human approval, Size & route, Ship), reorder them, or remove them. For each step you choose:

  • Agent for agent steps, such as builder for planning and implementing, tester for tests, reviewer for a first-pass review.
  • Approver for Human approval: Issue owner, CODEOWNERS, Project lead or Anyone on the project.
  • Command for CI checks, such as pnpm ci. The check retries, then hands back.
  • When done for Ship: Merge on green (squash once checks and reviews pass), Open PR only (a human merges) or Draft PR (for early feedback).

The workflow needs at least one agent step: “Add at least one agent step: someone has to do the work.” You get the full editor, with branching, gates and typed references, once the factory exists.

4. Triggers

“What starts a run. Manual runs from New run, ⌘K and Slack /build always work when manual is on.”

TriggerFields
Linear labelTeam, Label (for example ready)
GitHub issueLabel, in the selected repos
Sentry alertSentry project, Threshold (events per hour)
ScheduleCron, with presets such as Weekdays 09:00 or Nightly 02:00
ManualOn by default: New run dialog, ⌘K, Slack /build and the API

Turn on at least one trigger, or nothing will ever start a run. The workflow editor offers more kinds later, including webhooks and events. See Triggers.

5. Guardrails

“What agents may do without asking, and what a run may spend.”

  • Approval policy: the permission mode. Ask for everything (every write and command becomes an ask, best for new factories), Ask for writes (reads and allow-listed commands run freely, recommended) or Autonomous in sandbox (no asks inside a disposable sandbox with no network; merge still gated).
  • Approve plans before implementing: the run pauses after planning and asks the issue owner.
  • Require human review to merge: when off, small, green PRs outside protected paths merge on their own.
  • Budget per run: pauses and asks at 80%.
  • Daily cap: across all runs of this factory.
  • Max concurrent runs: extra runs queue.
  • Protected paths: agents can read these, but any edit becomes an ask and needs CODEOWNERS review. Defaults include .github/workflows/**, infra/prod/** and **/*.pem.

Guardrails can only tighten workspace settings, never loosen them. See Permissions and approvals.

6. Review & create

Check the summary and choose Create factory. “The factory starts paused until its first run, so nothing happens the moment you create it.” Start that first run with C, or wait for a trigger once you resume the workflow.

Edit the workflow

The wizard creates version 1 of the factory’s default workflow. To change it, open the factory and go to Workflows:

  1. Pick the workflow in the toolbar and switch between Summary and Graph.
  2. Select a step to edit it in the inspector, or describe a change in the chat pane, for example “Add a security review after Implement”.
  3. Fix anything listed under problems: problems block applying.
  4. Choose Review changes, check each step’s before and after, then Apply changes.

Applying creates version 2. Runs already in progress keep version 1. See Versions and rollback.

The same factory as a file

Every workflow can also be read and written as YAML with the Preview CLI (duun workflows pull and duun workflows apply). The Ship features template looks roughly like this:

platform-features.yaml
# duun.workflow/v1
id: wf_9c1d
revision: 1
name: Features
factory: fac_platform
description: Runs the Platform team's work through to reviewed PRs.
triggers:
  - kind: issue
    provider: linear
    team: Platform
    label: ready
  - kind: manual
limits:
  budget_usd: 5
  pause_at_pct: 80
  timeout_min: 120
  max_concurrent_runs: 4
inputs:
  - key: issue
    type: markdown
    description: The issue that started the run
steps:
  - id: size-route
    kind: decide
    name: Size & route
    owner: { kind: agent, agent: builder, model: opus-5.5 }
    instructions: Estimate PR count and blast radius of {{input.issue}}.
    control:
      mode: first_match
      cases:
        - id: small
          label: Small
          when: { name: judged, question: "Is this one PR or less, with a low blast radius?" }
          activate: [implement]
      otherwise: { activate: [plan] }
  - id: plan
    kind: agent
    name: Plan with repo context
    owner: { kind: agent, agent: builder, model: opus-5.5 }
    instructions: Read {{trigger.issue.url}} and the repo. Write a plan with steps, risks and what's out of scope.
    outputs:
      - { key: summary, type: markdown, description: What it did }
  - id: approve
    kind: human
    name: Approve plan
    owner: { kind: human, who: issue_owner }
    instructions: Review and approve, or send it back with a note.
    gate: { type: user_approval }
  - id: implement
    kind: agent
    name: Implement in isolated worktree
    owner: { kind: agent, agent: builder, model: opus-5.5 }
    depends_on: [approve, size-route]
    instructions: Implement {{steps.plan.output.summary}} with tests.
    outputs:
      - { key: summary, type: markdown }
  - id: ci
    kind: check
    name: CI and contract tests
    owner: { kind: orchestrator }
    instructions: Run the checks and report each failure with its log.
    gate:
      type: ci_green
      command: pnpm ci
      on_fail: { return_to: implement, policy: retry_with_feedback, max_attempts: 3 }
  - id: review
    kind: agent
    name: First-pass review
    owner: { kind: reviewer, agent: reviewer }
    instructions: Review the diff against CODEOWNERS rules.
    gate: { type: review_check }
  - 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

The Step kinds reference explains every key. To keep a workflow in version control, see Versions and rollback.

    Type to search the docs, help center and blog.