Workflows

A Workflow is the status machine a piece of work moves through: backlog, in progress, in review, done, cancelled, the lanes you would draw on a whiteboard if you were writing them down. Each kind of work, an initiative, a plan, a bug, a flow, or a test case, has its own workflow with its own statuses, the transitions allowed between them, and an initial status new records land in. Disco Parrot ships sensible defaults, and you customize them to the way your team actually runs.

One status machine per work type

Five kinds of work have their own workflow today:

• Initiative. The goal-sized piece of work that holds the plans.
• Plan. The change-sized piece that an agent can implement.
• Bug. The defect that gets triaged and fixed.
• Flow. The agent run itself, which moves through states the platform manages for it.
• Test case. The spec a verification step writes against.

Each workflow has its own statuses, its own transitions, and its own display defaults you can adjust per workspace.

Statuses and transitions

A status is a labeled bucket a record can sit in. It carries an id (the stable string the rest of the system uses), a label (what you read), a color from a small palette (informative, brand, success, danger, warning, subtle), and a description.

A transition is an arrow between two statuses. You declare which moves are allowed, and the workflow does the rest.

The server checks every status change against the transition list. A request to move from "In progress" to "Done" succeeds if your workflow allows it and is rejected with an error if it does not. Moves to the current status pass through as a no-op. This is enforced for initiatives, plans, and bugs today; flow status moves are driven by the platform's run scheduler instead, so a flow does not pause because someone disagreed with its next step.

A status can be marked not creatable, which means a new record cannot start its life there. Records can still arrive through a transition, but they cannot be born in that status. That is how "In review" stays a place items end up rather than a place where someone files them by hand.

If you create a record without specifying a status, it lands on the workflow's initial status. The editor will not save a workflow whose initial status is missing or marked not creatable, so you cannot accidentally orphan new records by editing the workflow underneath them.

Status changes happen one record at a time. There is no bulk-transition API today, which is a deliberate constraint: a workflow that could be swept across hundreds of records in one call would not be the same kind of guardrail it is when each transition is a considered move.

The Flow and Test case workflows behave a little differently. A flow run's status is set entirely by the platform's run scheduler as it works through the steps, and people cannot edit it directly. The workflow's statuses and colors decide how a run shows up on a board or a list, but the transitions are not gated, because the platform owns the moves. A test case can be in draft, active, or obsolete by direct edit, but its passing or failing outcome is only ever recorded through the verification result endpoint, never by editing the record. That keeps the outcome on the run that produced it rather than something someone can flip by hand.

Customize a workflow

You edit a workflow at Platform → Workflows, on the page's per-entity tabs (one for initiatives, one for plans, one for bugs, one for flows, one for test cases). When you save, your edited workflow replaces the shipped default for your workspace; the platform reads your version from then on. There is no separate "fork": you customize in place. The planner-facing operational guide at Customizing workflows walks through the actual edit flow, the propagation map, and the test-case workflow's special opinionated shape.

If you change the labels and colors of statuses you already use, your records keep their ids and pick up the new look automatically. If you change the transition list, the new rules apply on the next save. If you remove a status, records that were sitting in it are left where they are with the removed status id still attached; they will not transition out cleanly until you give them somewhere to go, so a removal is best done after you have already moved its records elsewhere.

Editing a workflow is an admin job. The change is recorded in the audit trail, so the history of who tightened the bug workflow last quarter is there to look up. The audit row names the entity type whose workflow changed and the actor; it does not snapshot the full prior and new lists of statuses and transitions, so the workspace's own change-management process is the right place to keep an annotated record of why the workflow moved.

How a workflow shapes the UI

A workflow does more than enforce transitions. It also decides what your team sees while they work.

• Card fields. The fields shown on a record's card on a board. You pick from a per-entity catalog and order them.
• Grid fields. The columns shown for the record type in the list view, drawn from the same kind of catalog.
• Roadmap defaults. On the initiative workflow, the default zoom level and the fields shown when you hover a bar on the roadmap.

A few rules about how the field catalog actually works:

• Fields come from a fixed per-entity catalog, not free-form keys. You cannot accidentally request a field the record does not actually have.
• A small set of identity fields is always required and auto-prepended on save, so a card always reads like a card no matter what else you pick.
• The catalog is capped at fifty fields per surface to keep a card from turning into a wall of text.
• You choose how empty fields render. On a card, an empty field can be hidden or shown with a faint placeholder; on the grid, the equivalent toggle decides whether an empty cell renders a placeholder dash or the field's label.

Setting these on the workflow means the look of "a plan" or "an initiative" is a one-place decision: edit the workflow, every board and grid that shows that record type updates with it.

Tied to skills

A workflow is also where skills plug in. A status binding maps an entity type and a status to the ordered set of skills the action launcher offers there: a plan in "In progress" might offer the implement and verify skills, while a bug in "Triage" offers the set you use to assess and route it. The bindings live on their own records, so changing a workflow does not edit a skill, and changing a skill does not silently rewrite a workflow. The two are joined by the status id.

When you delete a status from a workflow, the bindings that named it are cleaned up for you. New statuses arrive with no bindings, and the built-in defaults cover them, so a workspace that has never configured a binding still does something sensible.

You edit bindings on the Skills tab of the same Workflows page, alongside the statuses they apply to. The Skills page walks through curating them per status and per skill, including the bulk moves for changing many statuses at once.

Permissions

A workflow has two scopes: the read scope, which lets a person see how the workflow is set up, and the manage scope, which lets a person change it. The shipped admin roles (Admin, Owner, Workspace Operator) carry both; everyone else can read but not edit. Workflow edits, like other admin changes, are recorded in the audit trail.

Why it matters

For your team, a workflow is how the way you already work shows up in the product. The statuses are yours, the transitions are yours, the fields on a card are yours, and the skills offered at each status are yours. The system stops asking your team to remember the rules because it knows them.

For prospects and enterprise buyers, that customization is governed. Statuses cannot be created on a whim by anyone with a keyboard, transitions are enforced, edits are audited, and the look of a board is decided by an admin instead of being a wild west of per-team conventions. The same configuration is what binds a status to the skills an agent will run there, so the work and the agent both follow the same rules.

Every status these machines ship with, and the exact moves between them, is laid out on the statuses and status machines reference.