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: all 15 states, forward progression, every backward loop, pause/resume rules, the canonical diagram, and the per-executor transition constraints.

States

State	Label	Description
`unlabeled`	(none)	Issue exists but Colony hasn’t picked it up yet
`new`	`colony:new`	Mayor has ingested the issue and enqueued an analyze task
`planning`	`colony:planning`	Planner agent is decomposing an epic-scale issue into subtasks
`analyzing`	`colony:analyzing`	Analyzer agent is triaging the issue (complexity, labels, plan)
`needs-clarification`	`colony:needs-clarification`	Analyzer found ambiguity — waiting for the issue author to respond
`ready-for-dev`	`colony:ready-for-dev`	Analysis complete; the developer agent picks up issues here and implements them
`dependency-blocked`	`colony:dependency-blocked`	Issue depends on another issue that isn’t done yet
`failure-blocked`	`colony:failure-blocked`	Failure or operator-intervention block — needs explicit `/colony:retry` to resume
`changes-requested`	`colony:changes-requested`	Reviewer requested changes — re-queued for the developer agent
`in-review`	`colony:in-review`	Reviewer agent is checking the PR
`merge-pending`	`colony:merge-pending`	Merger agent is rebasing and merging the PR
`human-review-ready`	`colony:human-review-ready`	PR passed automated review — waiting for a human approver
`waiting-for-subtasks`	`colony:waiting-for-subtasks`	Epic parent is waiting for child issues to complete
`done`	`colony:done`	Issue is complete and the PR has been merged
`paused`	`colony:paused`	An operator manually paused the issue

Forward Progression

The happy path moves left-to-right through ISSUE_STATE_ORDER:

unlabeled → new → planning → analyzing → needs-clarification → ready-for-dev
→ dependency-blocked → failure-blocked → changes-requested → in-review
→ merge-pending → human-review-ready → waiting-for-subtasks → done

Any transition where the target state appears later in this order than the current state is automatically valid.

paused is a side-state and is not part of the linear order.

`dependency-blocked` vs `failure-blocked`

Both states are blocked (is_blocked = true) but have different lifecycles:

dependency-blocked — issue is waiting on a known relationship (depends_on edges, file overlap with another in-flight PR). Mayor auto-unblocks it as soon as the dependency resolves.
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). Mayor will not auto-unblock; an operator must investigate and run /colony:retry (or another slash command) to resume.

Backward Loops

The state machine defines 24 explicit backward loop exceptions for real-world scenarios like review cycles, dependency races, and scope overflow.

Review Cycles

From	To	Why
`in-review`	`changes-requested`	Reviewer found issues with the PR
`merge-pending`	`in-review`	Rebase failed or PR not yet approved — return to reviewer

Recovery and Rollback

From	To	Why
`in-review`	`ready-for-dev`	No open PR found — re-queue for development
`merge-pending`	`ready-for-dev`	Close PR, fresh start from ready-for-dev
`human-review-ready`	`ready-for-dev`	PR closed without merge — return to development queue
`dependency-blocked`	`ready-for-dev`	Dependencies resolved — return to development queue
`failure-blocked`	`ready-for-dev`	Operator unblocked the failure — return to development queue (also targets `analyzing` / `planning` / `new` / `in-review` / `changes-requested` / `merge-pending` depending on `blockedFromState`)

Re-analysis

From	To	Why
`needs-clarification`	`analyzing`	Author responded — re-run analysis
`changes-requested`	`analyzing`	Operator-triggered full restart
`human-review-ready`	`analyzing`	Operator-triggered full restart
`in-review`	`analyzing`	Operator-triggered full restart
`ready-for-dev`	`analyzing`	Developer escalates issue back to analyzer for re-triage
`merge-pending`	`analyzing`	Close PR, re-analyze against current main

Dependency and Scope Management

From	To	Why
`analyzing`	`new`	Reset prematurely analyzed issue (dependency recovery)
`needs-clarification`	`new`	Reset prematurely analyzed issue (dependency recovery)
`ready-for-dev`	`dependency-blocked`	Mayor detected a dependency race while developer is active
`ready-for-dev`	`failure-blocked`	Build failure, cost cap, exhausted retries, or other non-dependency block
`ready-for-dev`	`new`	Scope-overflow auto-routing back to New for decomposition
`changes-requested`	`new`	Scope-overflow auto-routing back to New
`ready-for-dev`	`planning`	Scope-overflow direct-to-planning for decomposition
`changes-requested`	`planning`	Scope-overflow direct-to-planning

Planning and Escalation

From	To	Why
`needs-clarification`	`planning`	Epic SI routing for epic-scale self-improvement issues
`analyzing`	`planning`	Analyzer escalates epic-scale issues to Planner
`human-review-ready`	`merge-pending`	Mayor detects PR became dirty — send to merger

Pause and Resume

Any issue in a “pauseable” state can be paused by an operator.

Pauseable states: planning, analyzing, ready-for-dev, changes-requested, in-review, merge-pending

Pause: Any pauseable state → paused (valid)
Resume: paused → any state except paused and unlabeled (valid)

State Machine Diagram

stateDiagram-v2
    direction LR

    unlabeled --> new
    new --> planning
    new --> analyzing
    planning --> analyzing
    analyzing --> needs_clarification : needs info
    analyzing --> ready_for_dev : ready
    analyzing --> planning : epic escalation
    analyzing --> new : dependency reset
    needs_clarification --> analyzing : author responded
    needs_clarification --> new : dependency reset
    needs_clarification --> planning : epic SI routing
    ready_for_dev --> dependency_blocked
    ready_for_dev --> failure_blocked : failure block
    ready_for_dev --> in_review
    ready_for_dev --> analyzing : re-analyze
    ready_for_dev --> new : scope overflow
    ready_for_dev --> planning : scope overflow
    dependency_blocked --> ready_for_dev : deps resolved
    failure_blocked --> ready_for_dev : operator retry
    failure_blocked --> analyzing : operator retry
    failure_blocked --> planning : operator retry
    changes_requested --> in_review
    changes_requested --> analyzing : full restart
    changes_requested --> failure_blocked : failure block
    changes_requested --> new : scope overflow
    changes_requested --> planning : scope overflow
    in_review --> human_review_ready
    in_review --> changes_requested : changes needed
    in_review --> merge_pending
    in_review --> ready_for_dev : no PR found
    in_review --> analyzing : full restart
    in_review --> failure_blocked : failure block
    merge_pending --> done
    merge_pending --> in_review : rebase failed
    merge_pending --> ready_for_dev : reimplement
    merge_pending --> analyzing : re-analyze
    merge_pending --> failure_blocked : auto-merge exhausted
    human_review_ready --> done
    human_review_ready --> merge_pending : PR dirty
    human_review_ready --> ready_for_dev : PR closed
    human_review_ready --> analyzing : full restart
    human_review_ready --> failure_blocked : failure block
    waiting_for_subtasks --> done

    state "paused" as paused
    planning --> paused
    analyzing --> paused
    ready_for_dev --> paused
    changes_requested --> paused
    in_review --> paused
    merge_pending --> paused

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.

Per-Executor Valid Transitions

Each executor type may only request specific target states. Requesting any other state fails validation and moves the issue to failure-blocked.

Analyzer (`taskType: 'analyze'`)

Transition	Meaning
`ReadyForDev`	Analysis complete, issue is ready for development
`NeedsClarification`	Issue is ambiguous, needs author input

Developer (`taskType: 'develop'`)

The developer executor runs on issues in ready-for-dev (initial implementation) and changes-requested (applying reviewer feedback). In both cases the executor opens or updates a PR and transitions to in-review on success.

Transition	Meaning
`InReview`	Implementation complete, ready for review
`NeedsClarification`	Cannot implement without more information

Reviewer (`taskType: 'review'`)

Transition	Meaning
`HumanReviewReady`	Automated review passed, ready for human approval
`ChangesRequested`	PR has issues that need fixing

Merger (`taskType: 'merge'`)

Transition	Meaning
`Done`	PR merged successfully

Planner (`taskType: 'plan'`)

Transition	Meaning
`ReadyForDev`	Planning complete, issue is ready for development
`WaitingForSubtasks`	Epic decomposed into child issues

Invalid Transitions

If an executor returns a requestedTransition that doesn’t match its task type or names an invalid state, the Worker throws a validation error:

A comment is posted on the GitHub issue explaining the invalid result.
The issue is moved to failure-blocked.
The colony:needs-human label is added.
The Worker throws a Blocked: error — the task is not retried.

Transition validity is workflow-snapshot-relative — there is no static isValidTransition() export in @runcolony/sdk. Instead, call allowedTransitionsForState(snapshot, state), which returns the precomputed set of reachable target states for a given state from a WorkflowSnapshot. Check membership with .includes():

import type { WorkflowSnapshot } from '@runcolony/sdk';
import { IssueState, allowedTransitionsForState } from '@runcolony/sdk';

// snapshot is the WorkflowSnapshot for this repo's active workflow,
// provided by the framework at task dispatch time.
const target = IssueState.InReview;
if (allowedTransitionsForState(snapshot, IssueState.ReadyForDev).includes(target)) {
  return { outcome: 'success' };
}