How Duun works

The building blocks of Duun: workspaces, projects, factories, workflows, runs, agents, skills, commands and asks, and how they fit together.

On this page

Duun runs teams of AI agents that take issues from Linear, GitHub or Jira through plan, build, test and review to merged pull requests. People stay in charge of the decisions that matter: a run stops and asks before it does anything you haven’t allowed. This page names the parts of the system so the rest of the docs can use them without explanation.

The model at a glance

Everything lives inside a workspace. Work is organised into projects, and factories turn that work into pull requests by running workflows. Each time a workflow starts, you get a run. The steps of a run are done by agents, which load skills and can be started from slash commands. Whenever a run needs a person, it creates an ask in the Inbox.

Workspace (Acme)
├── Projects            PAY, WEB, MOB …       issues, milestones, context
├── Factories           Platform, Growth …    "Work in → workflow → repos → PRs out"
│   ├── Workflows       Base Loop (v5), Docs (v2) …
│   │   └── Runs        PLT-482, PLT-476 …    one branch and worktree each
│   ├── Repos           acme/platform, acme/ledger-sdk
│   └── Guardrails      permission mode, command rules, budgets
├── Agents              builder, tester, operator, writer, reviewer, your own
├── Skills & commands   #stripe-webhooks, /release-notes …
└── Settings            integrations, secrets, computers, billing …

Workspace

A workspace is your organisation in Duun. It holds members and their roles, integrations, API keys and secrets, computers, billing and every setting under Settings → Workspace. Most settings are inherited by everything inside the workspace, and projects or factories can override or tighten them.

Members have one of four roles: Admin, Billing, Member or Viewer. See Members and roles for what each can do.

Project

A project groups related work: a goal, the issues that serve it, milestones, repositories, context documents and the factories allowed to work on it. Each project has a short key, and its issues and runs are numbered with it, like PAY-12.

Project context (docs, trackers and links in the Context tab) is given to every run in the project, so agents start with the same background a new teammate would read first.

Factory

A factory is one team’s pipeline for turning work into reviewed pull requests. Its card on the Factories page reads left to right: Work in → workflow → repos → PRs out. A factory owns:

  • one or more workflows, one of which is the factory default
  • the repos its workflows open pull requests in, each with a sandbox
  • guardrails: the permission mode, command rules, allowed domains and budgets that apply to every run
  • access: who can use, edit or administer it

Read Factories for the tabs and settings, or Build your first factory to make one.

Workflow

A workflow is the list of steps every run goes through, plus what starts it and what it may spend. It has:

PartWhat it is
TriggersWhat starts a run: a schedule, an issue label, an alert, a webhook, a mention, a manual start and more
StepsUp to 24 steps of ten kinds: Agent, Check, Human, Decide, Read, Transform, Repeat for each, Notify, Send to URL, Deliver
LimitsBudget per run, the point where it pauses and asks, a timeout and how many runs may go at once
RulesPlain-language rules every step (or chosen steps) must follow
InputsNamed values a run starts with, such as the issue

Workflows are versioned. Edits collect in a draft, you review the changes, and applying them creates a new version. Steps pass data with typed references such as {{steps.plan.output.summary}}. Start with the Step kinds reference.

Run

A run is one pass of a workflow. It gets its own branch and worktree, so parallel runs never touch each other’s files. A run is bound to the workflow version it started on: applying a new version only affects runs that start afterwards.

A run has a status (queued, running, waiting, succeeded, failed or cancelled), a conversation with the agent, and tabs for its Plan, Changes, Terminal, Preview and Checks. Its header shows what it has spent and which limit caps it.

Agent

An agent wraps a command-line coding runtime (Claude Code, Codex CLI, Gemini CLI or OpenCode) with a model, a system prompt, skills, tools and a permission mode. Duun ships five built-in agents: builder, tester, operator, writer and reviewer. You can create your own. Steps in a workflow name the agent that does the work. See Agents.

Skill

A skill is reusable know-how in a SKILL.md file: when to use it, the steps, and optionally scripts and reference files. Agents read each skill’s description and load the skill when it matches the task. In prompts and instructions you mention a skill as #name, for example #postgres-migrations. See Skills.

Command

A slash command is a saved prompt anyone can run from the composer, such as /release-notes or /triage. A command can bind an agent, skills or a workflow, so typing it starts the right kind of work with the right setup. See Slash commands.

Ask

An ask is anything a run is waiting on a person for. Asks land in the Inbox and in notifications. There are five kinds:

AskPrimary action
Approve the planApprove plan
Allow a commandAllow once
Answer questionsSend answers
Review pull requestApprove & merge
Decide whether it keeps going (budget)Approve once

Every ask also offers Request changes and Hand off. Which actions become asks depends on the agent’s permission mode, the factory’s guardrails and Settings → Action approvals. See Permissions and approvals.

Where to go next

    Type to search the docs, help center and blog.