Flows

A Flow is a definition of work you want an agent to carry out, written once and run many times. It lists the steps in order, the inputs it needs, and the points where a person approves before the run continues.

A Flow is a template. Each time you run one, the run is a separate instance you can watch, pause, retry, and resume. Runs appear under Sessions alongside your chats and background tasks. Flows are the unit that makes reviewable autonomy concrete: instead of one open-ended prompt, the work is broken into discrete, inspectable steps with gates you control.

Anatomy of a Flow

A Flow has three parts.

• Steps are the ordered units of work. Each step runs one skill and produces a structured result.
• Parameters are the inputs you supply when you run the Flow. Each parameter has a name, a type (string, number, or boolean), whether it is required, an optional default, and whether it is hidden from the run dialog.
• Defaults set how the Flow runs unless you override them at run time: the checkpoint mode, whether it runs interactively or in the background, optional limits on total turns and time, and an optional model to pin the run to a specific provider.

What a step contains

Most of a Flow's behavior lives in its steps. A step carries the following.

Because each step runs a skill, and a skill can carry its own pinned model, a single Flow can move across models, and even across providers, as it runs. The implement step can use a strong reasoning model while the verify step that follows runs on a different provider, so the work is checked by a model that did not produce it. How the platform settles which model a step uses is covered in Run several providers at once.

Passing results between steps

A step can read what earlier steps produced. A parameter value like $steps.plan.output.planFile pulls a field from the plan step's result, and $input.repo pulls a value the run was started with. You can index into arrays, for example $steps.research.output.files[0].

Resolved references are turned into text before they reach the skill. That is why comparisons against them quote the value, as in the condition example further down: the reference resolves to the string "true", not a boolean.

Run a Flow

The operational walkthrough, starting a run, watching the timeline and transcript, and approving at the checkpoints, is on Run a Flow & manage checkpoints. The short version follows.

You launch a Flow from wherever the work lives: from a plan or an initiative, from the Flows list, or from inside a Chat by asking the agent to start one. A Flow can declare where it is allowed to run, so a plan-scoped Flow shows up on plans and not where it would not make sense.

Starting a run takes three choices, on top of the Flow's parameters:

• A sandbox profile. Every run executes in an isolated sandbox, and the profile sets what that sandbox is: its base image and tools, the repositories it can see, and the AI runtime it uses. Choosing the profile is how you point the same Flow at different stacks.
• Interactive or background. An interactive run is one you watch and approve as it goes. A background run proceeds on its own and surfaces in Sessions and the Command Center, pausing for you only where it must.
• A checkpoint mode. Template pauses at the steps the Flow marks, all pauses before every step, and none runs straight through. This defaults to the Flow's own setting, and you can override it for a single run.

How a Flow runs

A run moves through a clear set of states.

Each step produces a result that is validated against a fixed shape for that skill, with a couple of automatic retries if the agent's first result does not fit. Every result also reports an outcome of success, partial, blocked, or error, and a step that reports itself blocked pauses the run for attention rather than pressing on.

A flow's work lands in your work model, not in a silo. When a plan step runs, it creates a real plan; an initiative step creates a real initiative; a create-a-pull-request step opens a real pull request on your repository, authored as you. Records an agent writes this way are saved as AI-authored, so they sit alongside your team's work with the source marked and kept in version history.

Alongside the result, each step records a transcript of what the agent did, including its file edits, writes, and other tool calls, plus the number of agent turns and the cost in dollars. The transcript is the Sessions record for that step, and it is the right place to read what the agent actually did or to bring up an audit trail row to the matching execution. You can retry a failed or interrupted run, resume a paused one, or cancel a running one at any time.

Run steps only when they apply

Not every step should run on every pass. A step can be set to run only in certain cases, or to be skipped in others, based on what an earlier step found or on the inputs the run started with. The built-in Quick SDLC Flow uses this: its "create a pull request" step runs only once the verify step reports the work is ready.

You write the rule as a short condition that resolves to yes or no. A condition can check whether two values match, combine a few checks with and and or, and read a result from an earlier step or an input. For example, "open the pull request only if verification passed and the run was not told to skip review" looks like this:

$steps.verify.output.readyForPr == true && $input.skipReview != "true"

Conditions stay deliberately simple. They compare and combine values rather than calculate them, which keeps a Flow easy to read and its behavior easy to predict. When a decision needs more than a match, have a step report a plain yes-or-no result in its output and branch on that. The full set of operators, along with every step field and each skill's output fields, is in the automation reference.

Checkpoints

Any step can require a checkpoint. A Flow's checkpoint mode decides which steps actually pause:

• template pauses only at steps that are marked for a checkpoint.
• all pauses before every step.
• none runs straight through.

When you run a Flow in the background, a checkpoint still pauses the run and waits for you, unless its step has been set to auto-approve in the background. See Human checkpoints for how approving, rejecting, and skipping work, and exactly how background runs handle them.

Where Flows come from

Disco Parrot ships built-in Flows that cover the common shapes of work: planning flows that draft and revise initiatives and plans, a quick and a full SDLC flow that take a change from plan to pull request, a flow that fixes pull-request review comments, and the documentation-health and repository-onboarding flows that keep your repository docs in step with the code. Flows resolve in three layers, from most general to most specific:

1. The built-in that ships with the platform.
2. A workspace copy your team has saved.
3. A repository copy scoped to a single repo.

A built-in Flow is read-only. To change one, Customize it, which forks the built-in into an editable workspace copy. Reset to Default removes your copy and restores the built-in, keeping any schedule you had attached. The detail page tells you whether a Flow is a built-in, a customized copy, or a repository copy.

Build your own Flow

The built-in Flows are a starting point. The real value is that your team can write Flows that match how you actually work. The step-by-step authoring guide, the editor tabs, binding skills, wiring parameters, setting checkpoints and conditions, and customizing a built-in, is on Build a Flow.

What a Flow is made of

A Flow is a small thing to assemble:

• Steps, in order. Each step picks a skill (the unit of agent work) and sets the parameters it receives, which can be fixed values or references to an earlier step's output.
• Parameters a person supplies when they run it.
• Defaults for how it runs, such as the checkpoint mode and whether it runs interactively or in the background.

On any step you then layer the controls from this page: a checkpoint to pause for approval, a condition so it runs only when it applies, and a rule for what to do if it fails.

Skills are the building blocks

A step's skill can be one Disco Parrot ships or one your team has written. The built-in skills cover the common moves: research a codebase, draft an initiative, write a plan, implement it, generate test cases, verify the work, and review or create a pull request.

Skills are reusable, versioned instructions for a single kind of work. A skill you author once, say your house style for a code review or a project-specific implementation checklist, becomes a building block any Flow can reuse. This is how a Flow gets tuned to your stack: you keep the orchestration shape and swap in skills that know your conventions.

Where a Flow lives and runs

A Flow you create is saved to your workspace, so the whole team can run it. You can scope a variant to a single repository when one repo needs to work differently, and you can set where a Flow may be launched from: against a plan, against an initiative, or anywhere. Your plan sets how many Flows a workspace can keep.

Start from a built-in

If a built-in is close to what you want, you do not start from a blank page. Customize it to get an editable copy seeded from the built-in, then change the steps.

For example, the built-in Quick SDLC Flow is four steps: plan, implement, verify, and create a pull request, with the last step set to run only when verification reports the work is ready. Fork it, add your own review skill before the pull-request step, and put a checkpoint in front of that step so a person signs off before anything opens.

Triggers

A Flow runs on demand, and it can also fire on its own.

• Scheduled. A cron expression with an optional time zone runs the Flow on a schedule. You can pause and resume a schedule without deleting it.
• On a pull request comment. The Flow fires when a comment arrives, by default for AI findings and human GitHub comments, with optional filters by finding severity.
• On a pull request review. The Flow fires on a review, by default when changes are requested, with an optional filter by review state.

Closing the loop on review feedback

A fix flow can keep working until review feedback is resolved. When it is set to act on review automatically, it dispatches itself for each blocking finding, applies a fix, rechecks, and repeats. It stops when everything is resolved or after a set number of rounds (three by default), at which point any unresolved findings are handed back to a person rather than looped on forever. If a recheck finds that a fix broke something that used to pass, the run pauses instead of charging ahead.