Pipeline States
Every Colony issue is in exactly one state at any given time. The state determines what work happens next and which executor type will claim it. For a conceptual introduction, see Core Concepts — States. This page covers the complete state machine of the built-in workflow: all 16 states, how transitions and outcome routing work, pause and resume rules, recovery from blocked states, and the diagram.
States
Section titled “States”| State | Label | Type | Description | Recovery |
|---|---|---|---|---|
unlabeled | (none) | awaiting-human | Issue exists but Colony hasn’t picked it up yet | — |
new | colony:new | active | Mayor has detected the issue and will start analyzing it shortly | — |
planning | colony:planning | active | Planner agent is creating a step-by-step plan, or decomposing an epic-scale issue into subtasks | — |
analyzing | colony:analyzing | active | Analyzer agent is reading the codebase to triage scope and context | — |
needs-clarification | colony:needs-clarification | awaiting-human | Colony cannot proceed without more information — waiting for the issue author to respond | — |
ready-for-dev | colony:ready-for-dev | active | Analysis complete; the developer agent picks up issues here and implements them | — |
dependency-blocked | (none — shown as the colony:blocked flag) | blocked | Issue is waiting on another issue or task to finish first | Auto → analyzing |
parent-branch-pending | colony:parent-branch-pending | blocked | Waiting for the parent epic to get its own branch before this sub-epic can proceed | Auto → analyzing (up to 3 attempts) |
failure-blocked | colony:failure-blocked | blocked | Failure or exhausted retries — an operator must retry or cancel | Manual → blocked-from state, else analyzing |
changes-requested | colony:changes-requested | active | Reviewer requested changes — the developer agent is addressing the feedback | — |
in-review | colony:in-review | active | Reviewer agent is checking the open PR | — |
merge-pending | colony:merge-pending | active | Review passed — Merger agent merges once CI completes | — |
human-review-ready | colony:human-review-ready | awaiting-human | A PR is open and waiting for a human approver | — |
waiting-for-subtasks | colony:waiting-for-subtasks | active | Epic parent is waiting for child issues to complete | — |
done | colony:done | terminal | Issue is complete and its PR has been merged or closed | — |
paused | colony:paused | awaiting-human | An operator paused the issue; work resumes when they click Resume | — |
State types: active states have an executor that claims work, blocked states stop the issue until recovery, awaiting-human states wait for a person, and terminal states end the lifecycle.
Transitions and routing
Section titled “Transitions and routing”The workflow definition, not the executor, decides where an issue goes next. Three pieces of the definition work together:
transitions:— each state’s allowed-target list. Moves outside it (and outside the routes below) are illegal.on:— outcome routing. An executor returns anExecutorOutcomestring such asapprovedorpr_opened, and the state’son:block maps that outcome to the next state. Executors never name a target state. See the executor contract for how outcomes are declared.recovery_targetand operator actions — blocked states declare arecoverymode (autoormanual) and arecovery_target. Operator actions such asreimplement,reanalyze,reopenandapprovecarry their ownfromandtostates.retryis handled by the framework and declares neither. The workflow’sapproveaction is the human acceptance that moveshuman-review-readytomerge-pending; it is not the/colony:approvecommand, which only records acceptance of an epic’s findings.
The set of legal targets from a state is the union of all of these. To author your own states, outcomes and routes, see Author and register a custom workflow.
Common outcome routes
Section titled “Common outcome routes”A selection of the routes in the on: blocks, by task type. The workflow YAML is the exhaustive source.
| Task type | State | Outcome | Next state |
|---|---|---|---|
| analyze | new, analyzing | success | ready-for-dev |
| analyze | new, analyzing | needs_clarification | needs-clarification |
| analyze | new, analyzing | escalate_to_planning | planning |
| analyze | new, analyzing | decompose | waiting-for-subtasks |
| analyze | new, analyzing | dependency_blocked | dependency-blocked |
| analyze | new, analyzing | parent_branch_pending | parent-branch-pending |
| plan | planning | decomposed_single | ready-for-dev |
| plan | planning | decomposed_multi | waiting-for-subtasks |
| plan | planning | needs_clarification | needs-clarification |
| develop | ready-for-dev, changes-requested | pr_opened, changes_addressed | in-review |
| develop | ready-for-dev, changes-requested | escalate_to_analyzer | analyzing |
| develop | ready-for-dev, changes-requested | escalate_to_planning | planning |
| develop | ready-for-dev, changes-requested | dependency_blocked | dependency-blocked |
| review | in-review | approved | merge-pending |
| review | in-review | changes_requested | changes-requested |
| review | in-review | needs_rebase | merge-pending |
| review | in-review | no_pr | ready-for-dev |
| merge | merge-pending | merged | done |
| merge | merge-pending | needs_rebase, not_approved | in-review |
| merge | merge-pending | reimplement_requested | analyzing |
| merge | merge-pending | auto_merge_disabled, escalate_human | human-review-ready |
Most active states also route failure and error to failure-blocked, and escalate_human to human-review-ready.
dependency-blocked vs failure-blocked
Section titled “dependency-blocked vs failure-blocked”Blocked states (is_blocked = true) have different lifecycles:
dependency-blocked— issue is waiting on a known relationship (depends_onedges, file overlap with another in-flight PR). It recovers automatically toanalyzingonce the dependency resolves. Dependency blocks show in GitHub as a native “blocked by #N” relationship plus thecolony:blockedflag label. Thecolony:dependency-blockedlabel is no longer projected onto issues; label sync only removes it if it finds one.parent-branch-pending— a sub-epic is waiting for its parent epic to get its own branch. It also recovers automatically toanalyzing.failure-blocked— issue hit a failure or operator-intervention block (build failure, cost cap, exhausted retries, parse failure, review-cycle limit, identical repeated failure, manual block). Most blocks wait for an operator to investigate and run/colony:retry(or another slash command), which returns the issue to the state it was blocked from, or toanalyzingif that state has no executor. Transient failures and quota blocks are re-queued automatically by default, and CI hard failures get automatic repair attempts first.
Pause and Resume
Section titled “Pause and Resume”An operator can pause an issue. The CLI and MCP pause actions accept the colony-default type: active states: new, planning, analyzing, ready-for-dev, changes-requested, in-review, merge-pending and waiting-for-subtasks. /colony:pause, the colony:paused label and the monitor dashboard do not check the state.
Pause and resume are not workflow transitions: they never appear in a state’s transitions: list.
- Pause: sets
is_paused, records the current state inpaused_from_state, and moves the issue into thepausedstate. - Resume: clears
is_pausedand restores the issue topaused_from_state.
State Machine Diagram
Section titled “State Machine Diagram”stateDiagram-v2 direction LR
unlabeled --> new new --> analyzing new --> planning : escalate analyzing --> ready_for_dev : success analyzing --> needs_clarification : needs clarification analyzing --> planning : escalate to planning analyzing --> waiting_for_subtasks : decompose analyzing --> dependency_blocked : dependency blocked analyzing --> parent_branch_pending : parent branch pending analyzing --> human_review_ready : PR already open analyzing --> done : no work needed planning --> ready_for_dev : decomposed single planning --> waiting_for_subtasks : decomposed multi planning --> needs_clarification : needs clarification needs_clarification --> analyzing : clarification received ready_for_dev --> in_review : PR opened ready_for_dev --> analyzing : escalate to analyzer ready_for_dev --> planning : scope overflow ready_for_dev --> dependency_blocked : dependency blocked ready_for_dev --> failure_blocked : failure dependency_blocked --> analyzing : auto recovery parent_branch_pending --> analyzing : auto recovery failure_blocked --> analyzing : manual retry failure_blocked --> in_review : CI repaired in_review --> merge_pending : approved in_review --> changes_requested : changes requested in_review --> ready_for_dev : no PR in_review --> human_review_ready : escalate in_review --> failure_blocked : failure changes_requested --> in_review : changes addressed changes_requested --> analyzing : escalate to analyzer changes_requested --> failure_blocked : failure merge_pending --> done : merged merge_pending --> in_review : needs rebase merge_pending --> analyzing : reimplement merge_pending --> human_review_ready : auto-merge disabled human_review_ready --> merge_pending : approve human_review_ready --> done waiting_for_subtasks --> done : subtasks complete waiting_for_subtasks --> in_review : epic pending merge done --> new : reopen
planning --> paused : pause analyzing --> paused : pause ready_for_dev --> paused : pause in_review --> paused : pause merge_pending --> paused : pause paused --> analyzing : resume to paused_from_stateState identifiers in the diagram use underscores (a Mermaid requirement). The actual GitHub labels use hyphens — for example, colony:ready-for-dev, colony:changes-requested.
The diagram shows the common path drawn from the main edges of the workflow YAML, not every route. The States table and the workflow definition are exhaustive. Pause is shown from a few representative states, and resume restores whichever state the issue was paused from (the paused_from_state), not only analyzing.
Illegal Transitions
Section titled “Illegal Transitions”A transition outside the legal set for the current state is rejected. Colony throws an IllegalTransitionError and the issue does not move. When an executor returns an outcome that the state’s on: block does not map, the outcome has no route (UnmappedOutcomeError), so the Worker treats the run as a failed task. It retries until the failure count reaches agents.workers.max_task_retries within the hour, then blocks the issue.
Transition validity is workflow-snapshot-relative. Use allowedTransitions(snapshot, fromState) from @runcolony/sdk. It returns a Set that includes the transitions: list as well as on: targets, recovery targets and operator-action targets. Terminal and unknown states return an empty set. Check membership with .has():
import { allowedTransitions } from '@runcolony/sdk';
// snapshot is the WorkflowSnapshot for this repo's active workflow,// provided by the framework at task dispatch time.if (allowedTransitions(snapshot, 'in-review').has('merge-pending')) { // merge-pending is a legal next state from in-review}