Customizing workflows

A workflow is the status machine each kind of work moves through. The shipped defaults are sensible, but every organization eventually wants to bend the shape of its statuses, transitions, colors, and labels to the way its teams already think about the work. This guide is the operational reference for that customization: what knobs you have, what each one moves, and what stays template-fixed.

The concept page covers what a workflow is. This page covers what to do with one, and what to expect when you change it.

The shipped workflows

Disco Parrot ships workflows for initiatives, plans, bugs, flow runs, and test cases. They are not symmetric; each is tuned to the shape of its work.

The initiative workflow adds an explicit approved gate between planning and in-progress, reflecting the executive sign-off most teams want before scoped work begins. Its six statuses and fourteen transitions give it the most movement among the planning workflows. The plan workflow is the leanest: five statuses (draft, in progress, complete, blocked, cancelled) and twelve transitions covering the conventional path plus the side states. The bug workflow is the loosest, with nine statuses and twenty-one transitions covering triage, in-review, fixed, verified, and closed. The flow workflow is driven by the orchestration engine, not by user gestures, so customizing it is mostly relabeling and recoloring; the statuses themselves are runtime states like pending, running, paused, completed, failed. The test case workflow is the most opinionated of the five and the only one with a permanent constraint baked in: the passing and failing statuses cannot be set by editing the record. They are only ever written by the verification result endpoint when a test actually runs.

A sixth workflow record exists in the system for the mixed-entity sprint backlog, but it has only one status and exists to provide a configuration home for the sprint backlog's grid fields. The editor filters its tab out; the sprint board's columns are derived from the underlying Plan and Bug statuses through a fixed mapping rather than from a workflow you edit. The test case workflow tab does render in the editor on every entity tab list, but the route that accepts workflow customizations rejects writes for it, so planning your team's verification surface today means picking the verification plan's own status set rather than editing the underlying test case workflow.

The customization surface

Workflows are managed at Platform → Workflows. Each customizable work type gets its own tab; the editor surfaces four sub-tabs on the initiative workflow and two on the others.

• Configure: statuses, transitions, the initial status, and the rules each status follows. Available on every workflow.
• Card Fields: what the entity's record looks like on a board or in a hover card. Initiative only today.
• Grid Fields: what the entity's record looks like in the data grid. Initiative only today.
• Skills: which skills the action launcher offers at each status. Available on every workflow. The Skills page covers binding them per status and per skill, and the default-skill rules behind the menu.

Configure, Card Fields, and Grid Fields share one Save Workflow button at the bottom of the page; edits to any of the three are dirty-tracked together and committed in one PUT when you save. The Skills sub-tab is autosaved: each binding edit commits about four hundred milliseconds after the last change, with a short "Saving…" caption while the request is in flight and a "Saved." toast on success. If the same row's autosave fails three times in a row, the platform pauses autosave on that row and surfaces an "(autosave paused)" badge until you mutate the row again.

What you can change on each status

For every status, you can edit:

• The label, the human-readable name your team uses, edited on the row's inline edit form.
• The id, the stable string the rest of the system uses, also edited on the inline edit form. The platform rewrites every transition that referenced the old id, so renaming is safe inside the editor.
• The color, picked from a fixed palette of six Fluent tokens. Use danger for terminal-failure states (cancelled, failing); warning for states that block progress; success for terminal-good states; brand for the in-flight state your team most often opens at; informative for backlog and intake states; subtle for archived or merged-away states.
• The description, a short caption that shows in the editor and in hover tooltips on the kanban.

The creatable flag is a per-row Switch that lives outside the inline edit form, beside the Edit pencil. It says whether a new record of this type can start its life in this status. The initial status is always creatable; the toggle is disabled on its row so you cannot turn it off without changing the initial status first. The test case workflow uses this flag to lock passing and failing as outcomes that records can only arrive at through verification.

What you can change at the workflow level

• The initial status: the bucket new records of this type land in.
• The transitions: which moves between statuses are allowed, and what to call each one. The label shows up in the alt-flow action menu and in the bulk-status toolbar.

The transitions list is where you encode your team's policy. If your engineering team treats Complete as terminal and would rather create a follow-up plan than reopen a finished one, remove the complete → in-progress transition. The server enforces the change the moment you save; an attempt to reopen a complete plan fails on the API and shows the reason in the UI.

The initiative workflow on the same Configure sub-tab also carries a roadmapDefaults block (default zoom level and hover fields for the roadmap timeline). It is edited from the Roadmap's Options drawer rather than from this page, but it lives on the same workflow record and saves through the same persistence path. Card Fields and Grid Fields share a server-side cap of fifty fields per surface; the required fields (title, owner, status) are auto-prepended on save with a console warning if a stored configuration ever loses them, so a malformed config self-heals on the next write.

The cascade: status to skill to launcher to AI tool

What makes Disco Parrot's workflow surface different is the cascade. A workflow edit moves through four surfaces because all four read the same registry; one save on the Skills sub-tab on a Wednesday changes what an engineer's launcher shows on Thursday and what the agent reaches for in chat on Friday, with no one having to push or repeat the change.

Status as the registry

The workflow record holds the source of truth: status ids, labels, colors, descriptions, transition rules, and the creatable flag. Every consumer in the platform reads this record through the workflow service rather than holding its own copy. Save once, and every reader sees the new shape on its next render.

Skill bindings on the registry

The Skills sub-tab attaches an ordered list of skills to each (entity type, status) pair on a separate StatusSkillBinding record. A plan in "In progress" can have "Implement", "Refine spec", and "Open PR review" bound to it in that order, with "Implement" marked the Default skill. The binding lives on its own record, so changing the workflow does not edit a skill, and changing a skill does not silently rewrite a workflow. The two are joined by the status id, and when you remove a status from the workflow the bindings on the dropped status are cleaned up for you.

There is a governance angle here that is easy to miss. By default, the action launcher and the agent's tool surface offer every user-visible skill at every status; the moment you add a single skill to a binding for (plan, in-progress), the launcher and the agent narrow to only the bound skills at that status. Binding a skill is therefore not "adding one option" but "restricting to a specific set"; the in-product empty state on the Skills sub-tab spells this out plainly: "All skills are available at this status. Add skills below to limit what appears in chat."

Action launcher reads at open time

When an engineer on a record hits the action launcher, the platform asks the workflow service which status the record is in, asks the skill resolver which skills are bound to that (entity, status) pair, and renders them in the order you set with the Default selected. A skill bound to a status is the one a human reaches for there; a tenant-wide "always available" set (managed on the Skills page) is appended below the bound list so a small handful of cross-cutting skills are present everywhere regardless of status.

AI chat tools scope to the same registry

When that same engineer asks the agent in chat to "help me wrap up this plan", the agent's tool surface for the plan scopes to the bound skills at the plan's current status. The same registry that decides what the human sees in the launcher decides what the agent reaches for. An admin renaming a Plan status to a custom label (e.g. "In implementation") propagates the new wording to the agent's tool descriptions automatically; no one has to re-tune the agent for the new vocabulary.

The result is that one edit on the Skills sub-tab propagates to four surfaces in seconds. Because the workflow is one record per work type for the whole tenant, every team reads the same vocabulary; the leader scanning the cross-project roadmap reads the same "In progress" chip on every initiative without translating between teams, and the audit row for "who reopened the Q3 launch plan" is one query against one workflow rather than a federation across team-scoped variants.

What customization moves, and what stays template-fixed

What propagates

• Status dropdowns everywhere. Grid filters, card metadata, detail-page status pickers, the bulk-status toolbar, the alt-flow action menu, the action launcher, and the AI chat tools all read the live workflow. A new status appears in every dropdown the moment the save returns.
• Transition enforcement on the API. The server re-validates the transition list on every Plan, Initiative, and Bug status write. Any transition you removed is rejected with a clear error; any new transition you allowed becomes available immediately.
• The bulk-status toolbar. When a user selects ten initiatives on the grid and opens the status menu, the toolbar lists only the statuses every selected row can transition to. The intersection is computed against the live workflow.
• Skill bindings. When the action launcher opens on a record, it asks the workflow which status the record is in and renders the skills bound to that status. Editing the binding on the Skills sub-tab takes effect on the next open of the launcher.
• AI tool surface. The same binding scopes the skills the agent reaches for in chat against the record.
• Status colors and labels. Cards, badges, kanban headers, the roadmap bars, and the activity feed all read from the workflow. A relabel from "In progress" to "In implementation" lands everywhere the next time the page renders.

Where the status id is load-bearing

Most teams who add a status (think "Code review" between In progress and Complete) find the trade-off works for them: the new status is fully usable in dropdowns, the alt-flow menu, the bulk-status toolbar, the action launcher, and the AI tools; the kanban stays focused on the five or six movements that matter for scanning; the rollups continue to measure against the shipped ids. Records in the new status remain visible on grids and detail pages.

Status deletion cascades to skill bindings

Removing a status from a workflow is a one-click action with two non-obvious consequences. First, any skill bindings attached to the deleted status are deleted with it; the platform cleans up the orphan (entityType, statusId) rows automatically and silently. Second, existing records sitting in that status are not migrated forward; they keep the now-unknown status id on the record itself, and the next status write against any of them is rejected by validateTransition with an "Unknown current status" error until an admin manually re-saves the record with a known status. The deletion does not warn you about either consequence before it lands; treat removing a status as a two-step move (re-status the affected records first, delete the status second) rather than a one-step one.

What is not customizable today

A few things planners sometimes look for that the platform does not expose. We list them so you can plan around them.

• Per-team or per-project workflows. Workflows are tenant-wide. The shared vocabulary is the design.
• A "restore to defaults" button. Customization is saved in place. The shipped default is not preserved as a separate snapshot; if you want to revert, re-create the shipped statuses and transitions by hand from the values in the load-bearing-ids table above.
• Editing the test case workflow. The test case status machine is opinionated by design: passing and failing are outcomes recorded only by verification, never set by editing. The Configure sub-tab on the Test Case tab opens but a save returns HTTP 400 with invalid_workflow_entity_type. The error message includes sprint-backlog in its list of valid entity types, which can read oddly to an admin who has no UI access to that surface; it is correct, just terse.
• Custom badge colors. The six Fluent tokens are the palette.

When customization goes wrong

The cascade is powerful but it has sharp edges. A planner about to make a workflow change should run through this list before saving.

• Renaming a shipped status id silently breaks rollups. Rename complete on the Plan workflow to merged and the plans-progress numerator on every initiative drops to zero (the rollup is looking for complete). Rename done on the Initiative workflow and goal key results in boolean auto mode flip back to 0 the next time their subscriber fires. Edit the label, not the id, when the surface that depends on it is one you care about.
• Removing a shipped status leaves records in limbo. Drop the in-review Bug status and any bug currently sitting in that status will reject its next write with "Unknown current status." The PR webhook will also still try to write in-review on PR open, which now lands as an explicit-bypass status the editor does not recognize. Re-status the affected records first, then remove the status.
• A new status does not get a kanban column. Add code-review to the Plan workflow and the Plans kanban renders its existing five columns; cards in code-review remain visible on the grid and detail page but do not appear on the board. This is usually the right trade-off, but plan for it.
• A new status is not counted by the rollups. A plan sitting in your custom code-review is uncounted by plans-progress, so a planner reading the rollup will see fewer plans than the team actually has. Often what your team wants; verify the implication.
• Removing a transition does not affect the Bug PR webhook. GitHub's PR-open event still writes the bug to in-review, GitHub's merge event still writes the bug to fixed, and a PR-closed-unmerged event writes the bug back to backlog, regardless of your workflow's transition rules. The webhook is the authoritative event from a system of record the platform trusts; the bypass is documented behavior, not a bug.

Customize a workflow

The flow is the same across all four customizable workflow types.

1. Open Platform → Workflows. Sign in as an admin (the workflows.manage scope is on Admin and Owner by default; Member, Viewer, Planner, Lead, and Workspace Operator can read but not edit; Billing Manager has no workflow scope).
2. Pick the entity tab. Initiative, Plan, Bug, or Flow. The currently loaded workflow opens in the Configure sub-tab.
3. Make your edits. Add a status, edit a label, recolor, reorder, change the initial status, add transitions, remove transitions, or any combination. The tab label gets an asterisk when the editor is dirty.
4. Save. The PUT lands at the server, the platform validates the shape (rejects an empty status set, an initial status that does not exist, an initial status with creatable: false, a card-field set above the fifty-per-surface cap, a duplicate field id, or a grid-only field on a card surface), the workflow record updates, a workflow.updated SSE event broadcasts to every connected client in the tenant, and the new workflow is live across grids, dropdowns, the action launcher, the AI tools, and the audit log. A connected client's open dropdowns update on the next render without a reload.

The Skills sub-tab is separate. There is no Save button there; each binding edit autosaves about four hundred milliseconds after the last change, with the "Saving…" / "Saved." indicators flagging in-flight and successful writes. You can switch tabs while a save is in flight without losing it.

Power users can also reach the Card Fields and Grid Fields surfaces without leaving the board: every initiative grid and kanban carries a "Customize view" drawer that opens the same field-set editor as the workflow page's tabs and saves through the same PUT. The two surfaces (the page and the in-board drawer) share the workflow record, share the workflows.manage scope, and share the same fifty-field cap.

Two worked examples

Sarah's team adds a Code review status

Sarah's Analytics team has reached the point where the existing Plan workflow does not quite match the way they actually work. They want to add a "Code review" status between In progress and Complete, because their team policy is that every implementation plan must be approved on a pull request before the plan itself is marked Complete. They also want to bind a Disco Parrot skill, "Open PR review", to the new status so engineers can launch the agent's review tooling from the action launcher when a plan lands there.

Because the workflow is tenant-wide, this edit will affect Marcus's launches team too. Sarah confirms with Marcus that he is fine with the new status; he sees the change as a tightening of his own team's policy, not a divergence from it. The shared vocabulary is the point.

Sarah opens Platform → Workflows, picks the Plan tab, and works through the change.

1. On the Configure sub-tab, she clicks Add Status. She enters code-review as the id, "Code review" as the label, warning as the color, and a description ("Awaiting reviewer approval on the linked pull request").
2. She uses the up-arrow on the new row to move "Code review" between "In progress" and "Complete" in the list.
3. In the Transitions section, she expands the "In progress" row and adds two new transitions: in-progress → code-review ("Submit for review") and code-review → complete ("Approve and merge"). She removes the existing in-progress → complete transition; her team's policy is that you do not skip review.
4. She clicks Save Workflow. The save returns; the tab loses its dirty asterisk; the workflow is live.
5. On the Skills sub-tab, she expands the "Code review" status row and adds the "Open PR review" skill. The autosave fires; the "Saving…" caption appears for a moment and then "Saved." flashes at the bottom of the panel. The binding now restricts the Code review status to just that one skill plus the tenant-wide always-available strip.

What lands across the tenant the moment she saves.

• The Plans grid status filter, the kanban's alt-flow menu, the bulk-status toolbar, the detail-page status picker, and the AI chat tools all show "Code review" as a status option.
• The Plans kanban renders its existing five columns (Draft, In progress, Blocked, Complete, Cancelled). Plans in "Code review" remain visible on the grid and accessible from the detail page; the team uses the grid as their working view for the plans in review and the kanban for the higher-level flow.
• The sprint board renders its existing four columns. Plans in "Code review" are filtered off the sprint kanban (the column mapping does not yet know the new status) but stay on the sprint backlog grid, where the team still tracks them by sprint.
• The plans-progress rollup on every initiative continues to count the same denominator (Draft, In progress, Complete, Blocked). A plan sitting in "Code review" is uncounted by the rollup, which the team agrees is the right answer: it is not yet complete and the progress percentage should reflect that.
• The action launcher on a plan in "Code review" now shows "Open PR review" first.
• An audit log entry records the workflow save with Sarah as the actor and workflow as the entity type. The Skills sub-tab autosave does not write a separate audit row; the binding change is not in the audit trail today.

Tom on Marcus's team meets the new status a week later

A week after Sarah's save, Tom on Marcus's launches team finishes implementation on a plan in the Onboarding initiative and hits the action launcher. The launcher offers him "Submit for review" as a new status transition; he picks it and the plan moves to Code review. The launcher refreshes and now shows "Open PR review" at the top with the Default Switch on, alongside the tenant-always-available strip below.

Tom has never met Sarah and has not been briefed on the workflow change. He uses the bound skill anyway because the launcher made it the obvious thing to reach for. He then opens chat against the same plan and asks the agent to "help me wrap up this review"; the agent's tool surface scopes to the same one bound skill plus the always-available strip, and the agent reaches for the review tooling without needing instruction. The cascade closed the loop without anyone teaching Tom or the agent that the rule had changed. The shared vocabulary did the work.

Reading the workflow audit row

Every workflow save writes one audit row. Filter the audit log to entityType = workflow and you get the trail of every workflow change in your tenant.

The row carries the actor (user id and display name at the time of the save), the timestamp, an entityId of the entity-type-name whose workflow changed (plan, initiative, bug, flow, or sprint-backlog), and a short summary string ("Plan workflow updated by Sarah Chen, 2026-06-01 14:32 UTC"). A row looks roughly like:

2026-06-01T14:32:18Z   workflow   plan   Sarah Chen   update   Plan workflow updated

The row records that the workflow changed and who changed it. It does not snapshot the prior or new shape of the statuses and transitions on the row itself; the workspace's own change-management notes are the right place to keep the annotated history of why a workflow moved. Skill-binding edits do not produce audit rows today; if you need to know who attached which skill to which status, capture that out-of-band until skill-binding auditing ships.

Who sees the change

A workflow save is visible to everyone in the tenant. The workflow.updated SSE event broadcasts to every connected client, so dropdowns, kanban headers, the action launcher, and the AI tools on every team in the tenant pick up the new shape on their next render. Customers on the receiving end of a workflow change (Tom on Marcus's team meeting Sarah's new Code review status) do not get a notification today; the cascade is silent by design, on the theory that a status change is a vocabulary change rather than a per-record event worth a notification. If the workspace's own change-management process is the right place to broadcast a workflow change to humans, the audit log is the place to find it after the fact.

Permissions

Two scopes govern workflow access. workflows.read lets a person open the editor and read the configured shape; it ships on every content-facing built-in role (Member, Admin, Owner, Viewer, Lead, Planner, Workspace Operator). workflows.manage lets a person save changes; it ships on Admin and Owner only. Billing Manager has neither scope and does not see the editor at all.

Why the shape is what it is

For prospects evaluating Disco Parrot against Linear, Jira, or Azure DevOps, the customization story to weigh is the cascade. Status machines are real, transitions are enforced server-side, and skill bindings tie agent behavior to workflow stages through the same registry the action launcher reads. The trade-off the platform recommends is one shared vocabulary across teams, with the per-team flexibility expressed through fields, views, and per-status skill bindings rather than through divergent status sets. The shared vocabulary is what makes the cross-project rollup honest.

For your team day to day, the contract is straightforward. You pick the words and the moves; the platform enforces them on every write, surfaces the right skill at the right status, scopes the agent's tool surface to the same registry, and keeps the audit trail honest about who changed what when. The customization surface is wide on the parts that affect how your team thinks (statuses, transitions, labels, colors, skill bindings) and narrow on the parts that affect how the platform reasons across teams (rollup denominators, kanban columns, sprint board mappings). Edit your team's vocabulary freely; keep the load-bearing ids stable, and the cross-tenant cascade will keep paying off without anyone having to push, repeat, or re-tune.