Build a Flow

The built-in Flows are a strong starting point, and most teams outgrow them the moment they have an opinion. You want a review step that runs your house style. You want a checkpoint in front of the step that opens a pull request, so a person signs off before anything reaches GitHub. You want a verification skill that knows your fixtures. Build a Flow is where you shape agent work to match how your team actually works: you lay out the steps in order, bind a skill to each one, declare the inputs, set the checkpoints, and decide what happens when a step fails.

A Flow is a template you write once and run many times. This page is about writing the template. Running it, watching the steps, and approving at the checkpoints is the sibling surface, Run a Flow & manage checkpoints.

Where Flows are built

Flows live in the Platform area, under Flows. The list page shows every Flow your workspace can run, with a search box and a source filter so you can separate the built-ins from the copies your team has saved. Create Flow opens a short dialog: a title, a Flow ID derived from the title (the title is lower-cased and hyphenated, and a clash with an existing ID gets a numeric suffix; you can edit the ID before you commit), and a description. It drops you into the editor with a new Flow ready to fill in.

The editor itself is a detail page with three tabs:

• Overview carries the Flow's identity and its run defaults.
• Steps is where the real work lives: the ordered list of steps and the editor for each one.
• Parameters declares the inputs a person supplies when they run the Flow.

Built-in Flows open in the same editor in a read-only state, with a Customize action that forks an editable copy. The whole authoring surface is gated by the flows.manage scope; a teammate with only flows.read can open a Flow and read it but cannot save changes.

The shape of a Flow

A Flow is a small thing to assemble. Three parts carry all of it, and the Flows concept page covers each in depth; here is the shape you are filling in as you build.

• Steps, in order. Each step runs one skill and produces a structured result the next step can read.
• Parameters, the inputs a person supplies at run time.
• Defaults, the run settings (checkpoint mode and interactive-versus-background) that apply unless someone overrides them when they start a run.

The Overview tab holds the identity and the defaults; the Steps and Parameters tabs hold the rest.

The Overview tab

The Overview tab is the Flow's front matter.

The two defaults (checkpoint mode and mode) are exactly that: defaults. The person starting a run sees both in the run dialog and can change them for that run without touching the template, which is covered on the Run a Flow page.

The Steps tab

Most of a Flow's behavior lives in its steps, and the Steps tab is where you spend your time. Each step is a row in an accordion; expand one and you get its editor. Add Step appends a new step at the end; the up and down controls reorder; the delete control removes one. The order of the steps in the list is the order they run.

A single step carries the following.

Bind a skill to each step

A step does its work by running one skill. You pick the skill from a dropdown sourced from your tenant's resolved command registry, the same registry that powers the action launcher and the chat slash menu. The dropdown shows the skill's title and its slug, so /implement and /review read the way they do everywhere else in the product.

This is the lever that tunes a Flow to your stack. The orchestration shape (plan, then implement, then review, then open a pull request) stays constant; the skill bound to each step is where your conventions live. A team that writes a review-house-style skill once can drop it into the review step of every Flow, and the Flow inherits the house style without any change to its structure. Skills are reusable, versioned, and authored on their own Skills surface; a Flow step is one of the places they get used.

Pass values between steps

A step rarely runs in isolation. Its parameters are how you feed it the run's inputs and the results of earlier steps. The step parameter editor gives you three kinds of value without making you write reference syntax by hand:

• A literal. A fixed string, number, or boolean you type in.
• A run input. A value the person supplied when they started the Flow, written $input.<name>.
• An earlier step's output. A field from a step that already ran, written $steps.<stepId>.output.<field>.

For the core SDLC skills (research, initiative, plan, implement, verify, create-pr, generate-test-cases), the editor surfaces that skill's output fields in a dropdown, so binding the implement step's plan file into the review step is a pick, not a guess. For any other skill, you type the field name; every skill's result also carries the shared summary, status, and artifacts fields you can always reference. The full grammar, including array indexing like $steps.research.output.files[0], is on the concept page.

Mark the steps that need a checkpoint

A checkpoint is a pause before a step runs, where a person approves, rejects, or skips before the agent continues. On the step editor it is a single checkbox ("pause before this step for approval") plus an optional message that explains what the reviewer is signing off on.

Whether a checked step actually pauses depends on the Flow's checkpoint mode, which you set on the Overview tab and a run can override:

• template pauses only at the steps you marked.
• all pauses before every step, marked or not.
• none runs straight through.

So the per-step checkbox and the Flow-level mode work together: the checkbox says "this step is worth a look," and the mode decides whether that intent is honored on a given run. The full mechanics of what a person does at a paused checkpoint, and how a background run handles one, are on the Run a Flow page and in Human checkpoints.

Decide when a step runs and what happens if it fails

Two controls keep a Flow from being a rigid straight line.

A condition is a short expression that must be true for the step to run. If it is false, the step is marked skipped and the run moves on. The built-in Quick SDLC Flow uses this on its create-a-pull-request step, which runs only once the verify step reports the work is ready:

$steps.verify.output.readyForPr == true

You can combine checks with && and || when a step should run only under more than one condition, for example a step that runs only when verification passed and the run was told not to skip review:

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

Conditions compare and combine rather than calculate, on purpose. They use == and != to compare, && and || to combine, parentheses to group, and a null check for a value an earlier step left unset; they do not do arithmetic or < and > comparisons. A condition a reader can predict at a glance is a condition a team can trust, and when a decision needs more than a match, the right move is to have a step report a plain yes-or-no field in its output and branch on that. The agent decides; the condition reads the decision. The complete grammar, every step field, and each skill's output fields are catalogued in the automation reference.

On failure decides what happens when a step's skill fails outright. The dropdown offers three answers:

• Abort flow stops the run (the default, and the safe one).
• Skip step marks the failed step skipped and continues.
• Jump to fallback step routes to a fallback step, for a recovery path (the fallback target is named in the Flow definition).

The fallback branch is where recovery becomes part of the Flow. A verify step set to jump to a summarize-failure step on failure can have that step write a plain-language note onto the plan describing what went wrong, so a run that hit a problem leaves a trace a person can pick up rather than a dead end. The recovery is part of the design, not something a person pieces together after the fact.

Each step's result is also checked against a fixed shape for its skill (a summary, a status, and any artifacts the skill declares); the platform gives the agent another pass when the result does not fit, so a malformed result is corrected rather than passed downstream. You get this for free; it is the skill's contract doing its job.

Max turns caps how many agent turns the step may take, and Context chooses between handing the step the full prior context or only the run's parameters. Both give the occasional step that needs a tighter leash or a cleaner slate exactly that.

The Parameters tab

The Parameters tab declares the inputs a person fills in when they start the Flow. Each parameter is a row.

A parameter named repositoryId gets a repository picker in the run dialog rather than a plain text box, and a boolean parameter gets a checkbox. Required parameters with no value block the run until they are filled. This is the contract between the person starting a Flow and the steps that consume what they entered.

Start from a built-in

You rarely start from a blank page. Disco Parrot ships a set of built-in Flows covering the common shapes of work, from drafting an initiative to taking a change all the way to a pull request.

The documentation-health and repository-onboarding Flows are covered in depth on their own page.

A built-in is read-only. To change one, Customize it: the platform forks the built-in into an editable workspace copy seeded from the original, and the editor unlocks. A customized Flow carries a Customized badge and a Reset to Default action that removes your copy and restores the built-in, keeping any schedule you attached. Flows resolve in layers, from most general to most specific, so the workspace copy you save shadows the built-in for your whole team.

The detail page tells you which layer a Flow is. Customizing never overwrites the built-in; it adds a more specific copy that shadows it, so a reset always has the original to fall back to. (A repository can hold a copy that diverges from the workspace one for a single repo; that finer layer is set in the Flow definition rather than the editor.)

Fork a built-in, end to end

Maya leads a backend team that wants every agent-opened pull request reviewed against the team's house style before it reaches GitHub. She does not want to build a Flow from scratch; she wants the Quick SDLC Flow with one step added. Here is the whole authoring session.

1. She opens the Quick SDLC Flow from the Flows list and reads its four steps: plan, implement, verify, create a pull request, with the last step set to run only when verify reports the work ready.
2. She clicks Customize. The editor unlocks on an editable copy that now carries a Customized badge.
3. On the Steps tab she clicks Add Step, names it "Review (house style)," gives it the step ID review, and picks her team's /review-house-style skill from the Skill dropdown.
4. She gives the review step the implemented work to look at by binding a planRef parameter to $steps.implement.output.planFile, picked from the editor's output-field list rather than typed.
5. She reorders the review step above Create PR with the up control, so the review runs before anything opens.
6. She checks the Checkpoint box on the review step and types the message "Sign off before the PR opens," so a person approves after the review and before the PR.
7. She leaves On failure on Abort flow, and clicks Save.

Maya has not written a line of orchestration code. She picked a skill her team already owns, dropped it into a step, ordered it, and put a person in front of the PR. The Flow she saved is now the one her whole team runs, and the next time anyone implements a plan with it, the house-style review and the human sign-off happen on every pass.

Make a Flow run on its own

A Flow runs on demand, and a Flow can also carry a trigger that fires it automatically. A trigger is the platform turning an event into agent work that still flows through the same checkpoints, the same audit trail, and the same sandbox isolation as a run a person started by hand. The Flow model supports three trigger shapes.

• Scheduled. A cron expression with an optional time zone runs the Flow on a cadence. The schedule can be paused and resumed without being deleted, and a scheduled run always executes in the background against a sandbox profile the schedule names.
• On a pull-request comment. The Flow fires when a comment lands on a pull request, with optional filters by finding severity (blocking, suggestion, nit, question) and by source (an AI finding, a GitHub comment, or an in-app comment).
• On a pull-request review. The Flow fires when a review is submitted, by default when changes are requested, with an optional filter by review sentiment.

The pull-request triggers are what let the built-in review and fix Flows respond to activity on a pull request, and they come pre-wired on those Flows: you do not assemble the trigger, you turn the behavior on. The clearest place to see a trigger you set yourself is the documentation-health schedule: on a repository's settings, under Documentation Health, you choose a cadence (presets from every six hours through daily, weekly, and biweekly, or a custom cron expression), a time of day, and a time zone, plus how far back to look and whether to auto-apply high-confidence updates. An enable toggle pauses and resumes the schedule without losing the configuration. That writes a scheduled trigger onto the documentation-health Flow; the repository documentation page covers it in context.

A triggered run is governed exactly like one a person started by hand. It runs through the same checkpoints, writes the same audit trail, and executes in the same isolated sandbox. Automation does not buy a Flow out of the oversight model; it just removes the click that started it.

Save, and test by running

Save writes the Flow; it lights up the moment you have an unsaved change and a browser warning catches an accidental tab close with edits pending. A Flow saves once it has at least one step and each step has an ID and a bound skill, so a half-built step (a skill you have not chosen yet) is flagged rather than saved into a Flow that would not run. There is no separate publish step: a saved Flow is immediately runnable by anyone with flows.run.

The way you test a Flow is to run it. The Run Flow action on the editor opens the same run dialog described on the Run a Flow page, collecting the parameter values, a sandbox profile, the execution mode, and the checkpoint mode. Running with the checkpoint mode set to all is the natural way to step through a new Flow one stage at a time and confirm each step does what you meant before you let it run straight through. A test run is a real run: it produces the same Session, the same transcript, and the same auditable record as a run your team relies on, so there is no separate "draft mode" that behaves differently from the real thing.

How many Flows a workspace can keep

The number of Flows your workspace can hold (the built-ins are free; this counts the copies you create and customize) depends on your plan.

This is the cap you hit when a save is refused; it counts your tenant-created and customized templates at one time, not your runs. The per-day cap on how many times you can run Flows is covered on the Run a Flow page.

Permissions

flows.manage is the authoring scope, and it is separate from flows.run: a workspace can let many people start the Flows the team has built while keeping the authoring of those Flows in fewer hands. The editor hides the Create, Save, Customize, Reset, and Delete affordances when you lack flows.manage, and hides Run Flow when you lack flows.run.

Why building a Flow looks like this

Most automation tools make you choose between two shapes, and neither is good for serious engineering work. A no-code builder gives you boxes and arrows that cannot express "run this only if verification passed," so the interesting logic leaks into prose the runtime ignores. A code-first pipeline expresses anything but lives in a YAML file no product manager will ever open, so the people who own the work cannot shape the automation that does it.

Build a Flow is the path between them. The orchestration is a first-class artifact a planner can read: an ordered list of steps, each one a named skill, with checkpoints where a person decides and conditions that compare rather than compute. The depth lives in the skills, which are versioned and reusable and authored by whoever owns that kind of work, so a Flow stays legible while the expertise it carries gets arbitrarily deep. The conditions stay simple on purpose, because a Flow you cannot predict is a Flow you cannot trust. And the same three-layer resolution that lets you customize a built-in lets a single repository diverge without forking the whole library.

For a senior PM, Build a Flow is the answer to "can I shape how the agent works on my team's terms, or am I stuck with what shipped?" For an engineer, it is the place where the review skill that encodes the team's standards becomes a step every Flow runs. For a lead, it is where the checkpoint in front of the pull-request step turns "the agent opened a PR" into "the agent opened a PR after a person signed off." You write the shape once; the team runs it forever.