Skip to content

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.


StateLabelTypeDescriptionRecovery
unlabeled(none)awaiting-humanIssue exists but Colony hasn’t picked it up yet—
newcolony:newactiveMayor has detected the issue and will start analyzing it shortly—
planningcolony:planningactivePlanner agent is creating a step-by-step plan, or decomposing an epic-scale issue into subtasks—
analyzingcolony:analyzingactiveAnalyzer agent is reading the codebase to triage scope and context—
needs-clarificationcolony:needs-clarificationawaiting-humanColony cannot proceed without more information — waiting for the issue author to respond—
ready-for-devcolony:ready-for-devactiveAnalysis complete; the developer agent picks up issues here and implements them—
dependency-blocked(none — shown as the colony:blocked flag)blockedIssue is waiting on another issue or task to finish firstAuto → analyzing
parent-branch-pendingcolony:parent-branch-pendingblockedWaiting for the parent epic to get its own branch before this sub-epic can proceedAuto → analyzing (up to 3 attempts)
failure-blockedcolony:failure-blockedblockedFailure or exhausted retries — an operator must retry or cancelManual → blocked-from state, else analyzing
changes-requestedcolony:changes-requestedactiveReviewer requested changes — the developer agent is addressing the feedback—
in-reviewcolony:in-reviewactiveReviewer agent is checking the open PR—
merge-pendingcolony:merge-pendingactiveReview passed — Merger agent merges once CI completes—
human-review-readycolony:human-review-readyawaiting-humanA PR is open and waiting for a human approver—
waiting-for-subtaskscolony:waiting-for-subtasksactiveEpic parent is waiting for child issues to complete—
donecolony:doneterminalIssue is complete and its PR has been merged or closed—
pausedcolony:pausedawaiting-humanAn 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.


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 an ExecutorOutcome string such as approved or pr_opened, and the state’s on: block maps that outcome to the next state. Executors never name a target state. See the executor contract for how outcomes are declared.
  • recovery_target and operator actions — blocked states declare a recovery mode (auto or manual) and a recovery_target. Operator actions such as reimplement, reanalyze, reopen and approve carry their own from and to states. retry is handled by the framework and declares neither. The workflow’s approve action is the human acceptance that moves human-review-ready to merge-pending; it is not the /colony:approve command, 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.

A selection of the routes in the on: blocks, by task type. The workflow YAML is the exhaustive source.

Task typeStateOutcomeNext state
analyzenew, analyzingsuccessready-for-dev
analyzenew, analyzingneeds_clarificationneeds-clarification
analyzenew, analyzingescalate_to_planningplanning
analyzenew, analyzingdecomposewaiting-for-subtasks
analyzenew, analyzingdependency_blockeddependency-blocked
analyzenew, analyzingparent_branch_pendingparent-branch-pending
planplanningdecomposed_singleready-for-dev
planplanningdecomposed_multiwaiting-for-subtasks
planplanningneeds_clarificationneeds-clarification
developready-for-dev, changes-requestedpr_opened, changes_addressedin-review
developready-for-dev, changes-requestedescalate_to_analyzeranalyzing
developready-for-dev, changes-requestedescalate_to_planningplanning
developready-for-dev, changes-requesteddependency_blockeddependency-blocked
reviewin-reviewapprovedmerge-pending
reviewin-reviewchanges_requestedchanges-requested
reviewin-reviewneeds_rebasemerge-pending
reviewin-reviewno_prready-for-dev
mergemerge-pendingmergeddone
mergemerge-pendingneeds_rebase, not_approvedin-review
mergemerge-pendingreimplement_requestedanalyzing
mergemerge-pendingauto_merge_disabled, escalate_humanhuman-review-ready

Most active states also route failure and error to failure-blocked, and escalate_human to human-review-ready.


Blocked states (is_blocked = true) have different lifecycles:

  • dependency-blocked — issue is waiting on a known relationship (depends_on edges, file overlap with another in-flight PR). It recovers automatically to analyzing once the dependency resolves. Dependency blocks show in GitHub as a native “blocked by #N” relationship plus the colony:blocked flag label. The colony:dependency-blocked label 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 to analyzing.
  • 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 to analyzing if 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.

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 in paused_from_state, and moves the issue into the paused state.
  • Resume: clears is_paused and restores the issue to paused_from_state.

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_state

State 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.


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
}