Workflows & transitions

What a workflow is in CompanyOS

Every work item in CompanyOS moves through a workflow: a row of statuses you drag it across, like Backlog, Todo, In Progress, In Review, Done, and Cancelled. That part is yours to shape. Underneath those labels sits a smaller, fixed structure, a set of five categories that never change. The statuses are the words your team reads. The categories are the spine the system reads. Keeping the two separate is what lets you rename a column to whatever your team actually calls it without breaking a single chart, progress bar, or AI summary.

On top of statuses you can layer transitions (which moves are allowed), conditions (what must be true before a move goes through), and a workspace rule about moving work backward. Together these turn a free-form board into a workflow with guardrails. And because agents operate the very same board over the company-brain MCP, every guardrail you set applies to them exactly as it applies to a person.

Statuses and the five immutable categories

A work item always has a status. Out of the box CompanyOS ships seven: Backlog, Todo, In Progress, In Review, Done, Cancelled, and Duplicate. The first six appear as columns on the board. Duplicate is a resolution applied from triage rather than a board column, so it never shows up as a lane you drag into.

Each status maps to exactly one of five categories, and that mapping is fixed in code. You can rename a status, recolor it, move it, or add new ones, but you can never move a status into a different category. The category is the stable meaning behind the label.

The categories are also ranked, from Backlog through Unstarted, Started, Completed, with Cancelled sitting outside that forward line. That ranking is what lets CompanyOS tell a forward move from a backward one, which matters for regression handling further down this page.

Customizing your statuses

The default six-column workflow is a starting point, not a cage. An org admin or owner can reshape it: rename statuses to your team's vocabulary, recolor them, reorder the columns, and add brand-new statuses inside any category. Adding a status is how you split a band into the steps you actually run, for example an In QA status inside the Started category, sitting between In Progress and In Review.

Org-level workflow vs per-team overrides

Every org gets one default workflow, seeded automatically the first time it is created, with Backlog as its default landing status. That org-level workflow applies to every team that has not defined its own. A team can override it by creating its own set of statuses, and from that point its projects follow the team workflow instead of the org default. Until a team adds at least one status of its own, it inherits the org-level workflow untouched.

Allow new items

Each status carries an allow new items toggle. When it is on (the default), people and agents can create work directly into that status. When it is off, that status is a transit-only state: items can move into it through a transition, but a brand-new item cannot be born there. Turn it off on statuses like In Review or Done, where an item should only ever arrive after passing through earlier work, not appear from nothing. Triage intake is exempt, so capturing raw inbound items is never blocked by this rule.

Deleting a status

You can remove a status you no longer need, but CompanyOS will not strand the work sitting in it. If the status is empty, it deletes immediately. If any items are in it, you must name a transfer-to status, and every item moves to that target as part of the delete.

1. 1
   Check the count

   CompanyOS reports how many work items currently sit in the status you want to remove.
2. 2
   Pick a transfer-to status

   If the count is above zero, choose another status in the same scope to receive those items. You cannot transfer items into the status you are deleting.
3. 3
   Confirm

   The items move to the transfer-to status, taking on the category of that target, and the old status is removed.

Transitions as guardrails

A transition is a rule that says "from this status, an item may move to that status". Defining transitions turns your board from a place where anything can go anywhere into a workflow with a real shape, where work follows the path you intend. A transition rule lives at the org level and always connects two of the org's workflow statuses.

The behavior follows one simple, forgiving rule:

A transition rule has three parts. The required pair, plus two optional refinements:

• From and to: the source status and the allowed target status. A transition must always connect two different statuses.
• Work-item kind (optional): scope the rule to one type of work, Task, Bug, Story, or Epic. A typed rule applies only to items of that kind. Leave it blank and the rule applies to every kind.
• Required role (optional): gate the transition behind a minimum project role, so only people (or agents) at or above that role can make this particular move.

Scoping a transition to a work-item kind

Sometimes a move should be legal for one kind of work but not another. Scoping by kind lets you express that. When you add transitions for a specific kind out of a status, those typed rules take precedence for that kind: only the typed targets apply to items of that kind. If you have not added any typed rules for a kind, it falls back to the kind-agnostic rules. This means you can write a tight path for Bugs out of a review status while leaving ordinary Tasks on the general rules.

Gating a transition behind a project role

Attach a required role to a transition and CompanyOS checks the mover's project role before letting it through. Project roles run, from least to most, Viewer, Commenter, Member, Admin. Setting a required role of Admin on the move into Done, for example, means only project admins can mark work complete, while anyone can still progress it through the earlier statuses. If the mover lacks the role, the move is refused.

Transition conditions

Where a transition decides whether a move is allowed at all, a condition decides whether the item is ready for it. Conditions are blocking pre-checks attached to a specific from-status to to-status pair. Before the move goes through, CompanyOS evaluates them in order, and if any one fails, the move is blocked and the reason is shown.

There are four condition types, each a small, declarative check against the item:

When a condition fails, the move is rejected with a message of the form "Cannot move to this status: <reason>." so the person or agent knows exactly what to fix. Conditions are evaluated in order and the first failure stops the move, so the reason you see is the first unmet requirement on that transition. The Require DoD complete check is satisfied automatically when an item has no Definition-of-Done items at all, so it only bites when a checklist actually exists and is unfinished.

Moving work backward

Work does not only move forward. Sometimes an item in review needs to go back to in progress, or a done item reopens. CompanyOS treats these backward moves as meaningful, not silent. A move counts as backward when the target sits in an earlier category than the current one, for example In Review (Started) back to Todo (Unstarted). Moves into the Cancelled category are never treated as backward, since cancelling is a resolution, not a regression.

Automatic regression comments

When an item moves backward across categories, CompanyOS automatically posts a comment on it recording the regression, noting which status it moved back from and to. Nobody has to remember to explain it. The history of why an item slipped is captured on the item itself, where the next person looking at it will see it.

Blocking backward moves entirely

If your team would rather never let work regress, the workspace has a single setting, block backward transitions, that an admin can turn on at the org level. With it enabled, any move into an earlier category is refused outright with a clear message, and items can only ever progress forward or be cancelled. It is off by default, so backward moves are allowed (and commented) unless you deliberately lock them down.

Auditing how work flows

Because every status change is recorded as an activity event, each work item carries its own transition history. CompanyOS turns that history into a readable timeline with dwell times, so you can see not just where an item is, but how long it lingered at each step along the way.

• Transition history: each status change in order, with the status it moved from, the status it moved to, when it happened, and who made the move.
• Dwell time per step: for each transition, the number of seconds the item spent in the previous status before moving on.
• Time in current status: the number of seconds the item has been sitting in its present status, counting up to now.

Dwell times are where bottlenecks show themselves. If items routinely spend days in In Review before reaching Done, the per-step durations make that visible across the team rather than leaving it to anecdote. The first segment is measured from when the item was created, so the timeline accounts for the whole life of the item, not just the moves after the first one.

How agents respect this

CompanyOS is Jira for your agents, and agents are first-class members of the org. An agent moving a work item over the company-brain MCP, with the transition_task_status tool, goes through the exact same service path a person does in the web app. There is no separate, looser door for automation.

That means every guardrail on this page applies identically to agents:

• Transition rules are checked, so an agent cannot move an item along a path you have not allowed.
• Required-role gates are enforced against the agent's project role, just as they are for a human.
• Conditions run first, so an agent trying to close an unassigned item, or one with an unfinished Definition of Done, is blocked with the same reason a person would see.
• Backward moves trigger the same automatic regression comment, and are refused if the workspace blocks backward transitions.