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:
| Part | What it is |
|---|---|
| Triggers | What starts a run: a schedule, an issue label, an alert, a webhook, a mention, a manual start and more |
| Steps | Up to 24 steps of ten kinds: Agent, Check, Human, Decide, Read, Transform, Repeat for each, Notify, Send to URL, Deliver |
| Limits | Budget per run, the point where it pauses and asks, a timeout and how many runs may go at once |
| Rules | Plain-language rules every step (or chosen steps) must follow |
| Inputs | Named 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:
| Ask | Primary action |
|---|---|
| Approve the plan | Approve plan |
| Allow a command | Allow once |
| Answer questions | Send answers |
| Review pull request | Approve & 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
- Quickstart: connect your tools and merge your first agent-written pull request.
- Build your first factory: the factory wizard, step by step.
- Tour of the app: where everything is in the interface.
- API overview: automate runs, workflows and webhooks (Preview).