Skip to content

Workflows

Colony pipelines are defined as workflows — YAML state machines that control how issues move through the pipeline. Colony ships four built-in workflows: colony-default (the standard analyze → develop → review → merge lifecycle), colony-content, colony-support and colony-dependabot. You can replace the default with a custom workflow per-tenant.

Every workflow file must satisfy schema_version: 1. The top-level keys are:

schema_version: 1
workflow:
id: my-workflow # kebab-case slug, unique identifier
name: 'My pipeline' # human-readable label
version: 1 # positive integer, incremented on each change
description: '...' # optional
unit: # optional; names the item type moving through this workflow
singular: issue # default: "issue"
plural: issues # default: "issues"
max_station_attempts: 30 # optional positive integer; default 30 — see Station-attempt ceiling
proposal: # optional; kinds and sections of a proposal for this workflow
kinds: [feature, bug]
sections: [problem, acceptance-criteria]
tracks: # optional; the workflow this one was cloned from
id: colony-default
version: 1
intake:
initial_state: new # slug of the first state issues enter
trigger_label: colony:enqueue # optional GitHub label that seeds an issue
states:
<slug>:
# ... per-state fields
operator_actions:
<slug>:
# ... per-action fields

proposal declares the item kinds and section names a proposal uses. If you declare it, both kinds and sections are required and must be non-empty, with no empty strings. Without it the defaults apply: kinds feature, bug, refactor, chore; sections problem, acceptance-criteria, non-goals, anchors, verification, context, proposed-approach. colony-content declares kinds: [article, correction] and sections: [summary, outline, draft].

tracks records which workflow this one was cloned from, as a sync baseline. The engine never branches on it, and tracks.id must not equal the workflow’s own id.

workflow.max_station_attempts is an optional positive integer, defaulting to 30 (DEFAULT_MAX_STATION_ATTEMPTS). It caps the total number of station attempts one issue may spend, across every loop.

What counts. Every agent_runs row for the issue — one per station attempt: analyze, plan, develop, review, merge, ci_repair, and any plugin or non-code station — except the task types sweep, retrospect, converse and review-external. Runs that did no station work are skipped too: runs tagged with one of the INFRASTRUCTURE_REQUEUE_REASONS (quota, transient provider errors, GitHub rate limit, deadline abort, unknown-failure escalation, token expiry, executor retry polling, lease reclaim, and runs the monitor closed after their worker died), and runs still marked running. Counting is per issue id: a subtask’s attempts do not count toward its epic, and each subtask has its own ceiling.

What resets it. /colony:retry, /colony:reimplement, the dashboard retry and unblock actions, CLI colony unblock, and MCP retry. Each records cycle_reset_at, and the count runs from the last reset, or from creation if the issue was never reset.

What happens at the ceiling. The ceiling is checked once, at dispatch, before the task runs:

  • The task is not run.
  • The issue moves to the first reachable manual-recovery blocked state with block reason attempt_ceiling, recording the tripping state so /colony:retry resumes it. Only if the workflow has none does it move to the state’s escalate_human target, or else its error route.
  • The issue gets the needs-human label, one explanatory comment per reset period (kind status:worker:attempt-ceiling), and an attempt ceiling reached status event. The status event fires on every refusal that escalates the issue; when nothing changes (the issue was already blocked, or every escalation transition failed and it was only flagged blocked) it fires once per reset period, alongside the comment.
  • Other commands hit the ceiling again until /colony:retry or /colony:reimplement is used.

The seven per-loop bounds (max_review_cycles and the others) are unchanged. The ceiling only catches their combined total.

State and action keys must be kebab-case slugs: lowercase letters, digits, and hyphens; 1–64 characters; must start with a letter or digit.

The states key is a record of slug → state definition. Each state has the following fields:

FieldRequiredDescription
typeyesState trait — see State traits
executornoWhich executor to run — see ExecutorRef
recoveryyes (if type: blocked)How the state recovers: manual or auto
entry_descriptionsnoMap of source-state slug to display text. When an item enters this state from that source state, the item panel shows this text instead of description (e.g. merge-pending entered from waiting-for-subtasks). Each key must be a declared state.
recovery_targetnoRe-entry state for retries/auto-unblocks (only valid on type: blocked; must reference a declared executor-bearing state). When omitted, the engine falls back to the analyze/develop heuristic.
max_recovery_attemptsnoPositive integer bound on automatic recoveries; declarable only on type: blocked states. Defaults to 3. Today only the analyzer reads it, for parent-branch-pending; once the bound is used up the issue is blocked permanently with reason failure.
constraint_handlingnoWhat this station does with a standing constraint attached to the item moving through it: nothing, reports, or enforces. Absent resolves to nothing — a station never gets credit for a promise it didn’t declare.
labelnoGitHub label string for this state (cosmetic)
descriptionnoOne-line, human-readable explanation of what this state means, for display next to a work item. Ships with the workflow; distinct from label, which is the GitHub label projection.
modelnoModel this station’s agent runs on, e.g. claude-opus-5-5. Overrides the per-role key and the complexity tier. model_routing.override still outranks it — that is a global kill-switch, applied regardless of task type, tier or enabled.
effortnoReasoning effort for this station: low, medium, high or max. Overrides the per-role key and the complexity tier.
max_turnsnoTurn budget for this station’s agent. Overrides the per-role key and the complexity tier.
stale_after_minutesnoMinutes an item may sit in this state before sprint-master reports it as stale (the stale label plus an operational-signal comment — never a human-obligation label). Absent means the state is not watched; there is no static fallback list.
onnoOutcome → route map — see Outcome routing
transitionsnoOptional additive array of state slugs that expand the effective allowed-transition set. The effective set is derived from on: targets, recovery_target, operator action to-targets, and state traits (paused, blocked, unlabeled); transitions: declares any edges that are genuinely additive and not otherwise derivable.
hooksnoTerminal-only post-completion hooks — see Hooks

The type field controls the lifecycle semantics of a state:

TraitMeaning
activeWorker picks up a task and runs the state’s executor
blockedIssue is blocked; must declare recovery: manual or recovery: auto
awaiting-humanIssue is waiting for human input; no executor runs
terminalIssue is complete; must not declare executor, transitions or on: routes

The executor field takes a reference string in one of two forms:

builtin:<name> # e.g. builtin:analyze, builtin:develop
plugin:<package>/<name> # e.g. plugin:colony-content/analyze

Built-in executors are provided by Colony itself. Plugin executors are declared by a registered plugin — see Plugins.

The on key maps executor outcome names to state transitions. Each value is either a plain slug (shorthand) or an explicit route object:

on:
success: ready-for-dev # shorthand: target state slug
escalate_to_planning:
target: planning # explicit object form
outputs: # optional metadata forwarded to the next state
upstream_outcome: scope_overflow

The outcome keys noop and retry are reserved and must not appear in on:. The framework handles them without routing through on: (noop leaves the issue where it is). This is the reserved outcome retry; it is unrelated to the retry operator action, which is unaffected.

All target slugs in on: must reference states defined in the same workflow definition.

hooks may only be declared on terminal states. They trigger out-of-band tasks after the issue reaches the terminal state:

done:
type: terminal
hooks:
- task_type: retrospect
executor: builtin:retrospect
optional: true # default true; accepted but currently informational
once_per_issue: true # default true; fire at most once per issue
if_visited: [human-review-ready, waiting-for-migration] # default []; unconditional when empty
  • optional (default true) is accepted but currently informational: hook enqueueing is fire-and-forget and never reverts the terminal transition, whatever the flag says.
  • once_per_issue (default true) dedupes on the terminal_hook key <task_type>:<issueNumber>, so reruns do not enqueue the hook twice.
  • if_visited (default []) restricts the hook to issues whose state history includes at least one of the listed states. An empty list means the hook fires unconditionally. The example above is taken from colony-dependabot.

The operator_actions key registers named actions that pipeline operators (humans or MCP tools) can trigger via slash commands. Each action has:

FieldRequiredDescription
descriptionyesHuman-readable label for the action
frameworknotrue marks this as a framework-reserved action (no from/to required)
fromyes (non-framework)Array of source state slugs from which this action is valid
toyes (non-framework)Target state slug
side_effectsnoSide effects to execute: close-pr, merge-pr, add-label, remove-label
intentnoSlug naming the slash-command intent the action fulfils: reimplement, reanalyze, reopen, approve, or a workflow-specific one such as revise on colony-support
labelnoOptional display name, e.g. “Accept” for approve
decision_inputnoWhat forming the decision consumes: operator (the person’s own judgement) or material (the rendered change itself)

Non-framework operator actions must declare both from and to. Framework actions (e.g. retry) are handled by the engine and do not require routing fields.

operator_actions:
retry:
description: "Re-enqueue current state's executor after failure."
framework: true
reimplement:
description: 'Discard PR; return to development.'
from: [in-review, merge-pending]
to: ready-for-dev
side_effects: [close-pr]

All from and to slugs in operator actions must reference defined states.

At runtime, operator_actions is the single source of truth for how slash commands (/colony:reimplement, /colony:reanalyze, /colony:reopen) behave. The workflow snapshot is read on every invocation — changes to operator_actions take effect the next time the workflow is loaded.

to — target state

to is the state the issue transitions to when the slash command runs. For example, reimplement.to: analyzing means /colony:reimplement sends the issue back to the analyzing state.

from — valid source states

from declares the states an action may be invoked from. Its enforcement differs by command:

  • /colony:reopen enforces from strictly. If the issue is not in a listed state, Colony posts an error comment (“Cannot reopen: issue is in <state>, but /colony:reopen is only available from: <allowed states>”) and the transition does not happen.
  • /colony:reimplement also enforces from. If the issue is not in a listed state, Colony posts “Cannot reimplement: issue is in <state>, but /colony:reimplement is only available from: <allowed states>” and returns before any PR, branch or worktree cleanup. The check is skipped for Dependabot items (routed to adopt first) and when no workflow snapshot is loaded.
  • /colony:reanalyze does not enforce from with a dedicated error comment. Instead, the effective allowed-transition set (states[from].allowedTransitions, derived from on:, recovery_target, operator action targets, state traits, and any additive transitions: entries) governs whether the target state is reachable from the current state.

Undeclared actions

retry and reopen are the operator-action spine — the framework guarantees both are available even when a workflow declares neither. If a workflow omits them, they are supplied automatically from trait-derived defaults (retry: framework-supplied, no from/to; reopen: from the workflow’s terminal states, to intake.initial_state). A workflow may rename a spine action (reopen is resolved by intent: reopen as well as by name), but it cannot redeclare one with different semantics — that fails validation at publish time, naming the action.

For any other action (e.g. reimplement, reanalyze), if a workflow does not declare it at all, the corresponding slash command replies with “This workflow does not support /colony:<action>” and returns without making any changes.

side_effects: [close-pr]

When close-pr appears in a non-framework action’s side_effects, the sprint-master closes any open PR for the issue before the state transition. Without close-pr, the PR is left open. For reimplement in colony-default the PR is always closed; for a workflow that omits side_effects, the PR stays open.

side_effects: [merge-pr]

merge-pr is declarable only on operator actions — never on a state transition — because merging on its own is a distinct question from autonomous acceptance, which is already governed by the sprint-master’s auto-merge gate. When merge-pr appears in an action’s side_effects, it is attempted before the state transition commits: a merge the code host refuses aborts the transition entirely, leaving the issue in its prior state and surfacing the host’s failure message to the operator. merge-pr carries no merge-method option — the host’s repo-level policy (default merge method on GitHub, squash on ADO) always applies.

merge-pr fails closed. It is operator-action-only, and the action is refused before any transition when no code-host connection is available, or when the host refuses the merge (the host’s message is surfaced). After a successful merge the item moves to the action’s to state. If that state runs builtin:merge, no merge task is enqueued; the sprint-master’s merged-change finalization moves the item to done (closure_reason completed), posts the merge comment, cleans up branches and runs the dependency and parent-completion checks exactly once. If finalization commits first, the action reports the resulting state.

decision_input

decision_input declares what a person must see in order to form the decision an action carries out — operator when the act consumes only a decision the person already holds (e.g. re-enqueueing after a failure, reopening a completed issue), or material when the act is formed by the material being rendered (e.g. discarding a change requires seeing the change). It is purely declarative: no resolver reads it today, and an action that omits it behaves exactly as it did before this field existed. It exists so a host that cannot render the underlying material (a constrained surface, a notification, a CLI without diff support) has something to read before deciding whether to offer the action at all.

Slash-command alias resolution

Slash commands resolve to an operator action by intent. If any action in the workflow declares intent, only actions with a matching intent are candidates. That is how colony-content’s redraft (intent: reimplement) is found when the operator types /colony:reimplement. The legacy name alias (['reimplement', 'redraft']) applies only to workflows that declare no intent on any action; the first declared candidate wins. If the lookup finds nothing, the spine fallback supplies reopen.

Terminal-state exit for reopen

reopen is the supported mechanism for operators to exit a terminal state (done). Terminal states have no outgoing transitions in the workflow graph, so a normal state transition would be rejected. The runtime uses allowTerminalExit: true specifically for reopen to bypass this check. Because reopen is a spine action, a workflow does not need to declare it — the framework supplies a default targeting intake.initial_state from every state of trait terminal. A workflow only needs to declare reopen explicitly in order to rename it (via intent: reopen), attach side_effects, or narrow which terminal states support it; the declared to must still match intake.initial_state, and the declared from must be a non-empty subset of the workflow’s terminal-trait states (a workflow with two terminal states, e.g. done and cancelled, may declare reopen with from: [done] to support reopening only from done) — declaring from with a state that is not terminal, or an empty from, fails publishing with a message naming the action. A workflow with no terminal-trait state at all is exempt — there is no terminal-state set to derive from: from, so the spine does not supply reopen in that case, and /colony:reopen resolves to not-declared.

The optional top-level triggers array declares out-of-band task enqueues that the engine should initiate for issues in specific states. This is the data-driven equivalent of hardcoded sweep logic (e.g. enqueuing ci_repair whenever an issue is blocked with block_reason: ci_hard_failure).

FieldRequiredDescription
task_typeyesTask type string to enqueue (e.g. ci_repair)
stateyesKebab-case slug of the state this trigger applies to (must be a blocked state that declares on: routes)
block_reasonnoPredicate matched against the issue’s block_reason column; trigger only fires when the column value equals this string
executornoExecutor ref (builtin:<name> or plugin:<pkg>/<name>) whose outcomes the enqueued task will produce
max_cyclesnoPositive integer cap on re-enqueue attempts (default mirrors today’s value of 2)
guardsnoExtra enqueue conditions: check_filter: true applies the review.ci_repair allow/deny check-name filter (and review.ci_repair.max_cycles then overrides max_cycles); require_no_human_approval: true skips the enqueue when the PR has a non-bot APPROVED review
triggers:
- task_type: ci_repair
state: failure-blocked
block_reason: ci_hard_failure
executor: builtin:ci_repair
max_cycles: 2
guards:
check_filter: true
require_no_human_approval: true

A trigger’s state is validated at parse time: it must be a defined state, must be type: blocked, and must declare a non-empty on:. The executor is only format-checked (builtin:<name> or plugin:<pkg>/<name>); it is not cross-checked against the workflow at parse time. The triggers block is optional and backward-compatible — existing workflows without it are unaffected.

The schema enforces the following rules at parse time:

  • intake.initial_state must reference a defined state.
  • workflow.max_station_attempts, if declared, must be a positive integer (0, negatives, fractions and strings are rejected).
  • States of type blocked must declare recovery.
  • recovery_target, if declared, may only appear on type: blocked states and must reference a state that declares an executor (i.e. a claimable/active-executor state). When omitted, retry and auto-unblock routing falls back to the built-in analyze/develop heuristic.
  • States of type terminal must not declare executor or transitions, nor on: routes.
  • max_recovery_attempts, if declared, must be a positive integer and may only appear on type: blocked states.
  • workflow.proposal, if declared, needs non-empty kinds and sections with no empty strings.
  • workflow.tracks.id must not equal workflow.id.
  • noop and retry are reserved outcomes and must not appear as keys in any state’s on: map.
  • Each role may be declared on at most one state.
  • Every state with an executor needs a reachable blocked fallback: an on: outcome, or a transitions: entry, that targets a type: blocked state.
  • decision_input, if declared, must be operator or material.
  • Each trigger’s state must be defined, be a blocked state, and declare a non-empty on:.
  • For builtin:<key> executors, every outcome the builtin can produce must be mapped in on:, and an unknown builtin: key is an error. Plugin executors only produce a warning. See colony workflow validate.
  • Redeclaring the retry/reopen spine actions with different semantics fails validation; see Undeclared actions.
  • hooks may only be declared on terminal states.
  • Every target in on:, any additive transitions: entries, and operator action from/to fields must reference a defined state.
  • Every workflow sub-object (not only states) is strict: authoring and colony workflow validate reject unrecognised keys (e.g. a misspelled field name) rather than silently ignoring them. Workflows already stored in a repo or config (.colony/workflow.yaml, inline config) are parsed in warn mode: the unknown key is dropped and reported. (The field table above covers the operator-facing keys; the schema additionally accepts a small number of internal keys not documented here, such as role.)
  • constraint_handling, if declared, must be one of nothing, reports, or enforces. It is not required on executor-bearing states — workflows also come from repo-file, config, and cloud-push sources, and a required field would fail to parse every customer-authored workflow already in the wild.

model, effort and max_turns let two stations that run the same executor differ in cost and quality — a first-pass review on a cheap model and a final review on an expensive one, for instance. Declaring nothing keeps today’s behaviour exactly: the value resolves from the per-role key (executors.<role>, falling back to agents.<role>) and then the complexity tier (claude.scaling[small|medium|large]).

Precedence for a station’s model, highest first:

  1. model_routing.override — the global kill-switch, applied regardless of task type, tier or enabled
  2. the station’s declared model:
  3. model_routing.routes
  4. the per-role key, then the complexity tier

At the planner and reviewer call sites, which resolve a model without a complexity tier, a route table cannot be indexed and 3 and 4 swap: an explicitly configured executors.<role>.model is used rather than deferring to a route entry that may not exist for this issue’s tier. Declaring model: on the state wins at every call site regardless — see model_routing for the full account.

effort and max_turns have no routing layer, so a declared value simply beats the per-role key and the tier.

Because the tier is chosen per issue from its analysed complexity, the effective value of a field a station does not declare depends on the issue in flight — it is not a property of the workflow on its own.

Colony ships with colony-default, the standard analyze → develop → review → merge pipeline. It is the default workflow for all tenants unless overridden.

Key properties:

  • intake.trigger_label: colony:enqueue — adding this label to a GitHub issue seeds it into the pipeline. See First Issue for details.
  • intake.initial_state: new — issues enter the new state, where builtin:analyze runs.
  • States: new, planning, analyzing, needs-clarification, ready-for-dev, dependency-blocked, parent-branch-pending, failure-blocked, changes-requested, in-review, merge-pending, human-review-ready, waiting-for-subtasks, done, paused, unlabeled. The dependency-blocked pipeline state (IssueState.DependencyBlocked) and the colony:blocked flag label are unchanged. Dependency blocks are surfaced in GitHub as native blocked by #N relationships (via the issue-dependencies API) rather than a colony:dependency-blocked label — the label is no longer projected.
  • Terminal state: done — triggers a retrospect hook (optional, once-per-issue).
  • Operator actions: retry (framework), reimplement, reanalyze, reopen, approve (“Accept”: human-review-ready → merge-pending, decision_input: material, no merge-pr side effect). colony-content declares the same approve action.

Accept records a verdict (who accepted, which head commit they judged, and whether it came through the API or a code-host approval) and moves the item to merge-pending; the builtin:merge station then merges the accepted commit, pinned to that head. Accept returns before the merge happens, so callers should watch the item’s state. A head that moves other than through the station’s own base update lapses the verdict and returns the item to human-review-ready. Clients should key off the approve intent, not the merge-pr side effect, to detect an Accept.

To view the full YAML:

Terminal window
colony workflow show --builtin colony-default

colony-content is an analyze → draft → review → merge pipeline for documentation and content issues. Its unit is article/articles. It requires the colony-content plugin to be registered — see Plugins.

Flow: new (plugin:colony-content/analyze) → drafting (plugin:colony-content/draft) → review-ready (builtin:review) → merge-pending (builtin:merge) → done. Side states: changes-requested (revises the draft), needs-clarification, human-review-ready, and failure-blocked (manual recovery, recovery_target: new).

Operator actions: redraft (intent: reimplement, so /colony:reimplement closes the PR and returns to drafting), retry, reanalyze (→ new), reopen (→ new) and approve (“Accept”, which records a verdict and hands the merge to the merge station).

Terminal window
colony workflow show --builtin colony-content

Dependabot owns its PR branches, so Colony does not run analyze or develop for them. Every Dependabot tracking issue is pinned to colony-dependabot in code at intake (no match rules or repo_workflows rows are involved, so a human issue titled chore(deps): … never routes here). Colony only reviews and merges the Dependabot PR.

Each tracking issue also carries the colony:dependabot label (projected alongside the state label). To hide these issues in GitHub’s issue list, use the search filter:

is:issue is:open -label:colony:dependabot

The dashboard’s Needs Attention panel groups these issues in a separate Dependabot section.

StateMeaning
in-reviewIntake enters here directly (single transition). The reviewer checks the Dependabot PR.
merge-pendingReview approved; the merger merges the PR. A needed rebase sends the issue back to in-review.
waiting-for-migrationDependency-blocked, auto-recovering. Entered by /colony:adopt (or /colony:reimplement) while the adopted issue is open.
human-review-readyAwaiting a human: failed review, escalation, auto-merge disabled, or a task failure.
failure-blockedA task for the PR exhausted its retries; an operator must retry or close it.
pausedSuspended by an operator.
doneTerminal: PR merged, or closed without merging (the decline is recorded).

A failed review posts the findings to the tracking issue and the Dependabot PR and never converts the PR to draft. Colony never posts @dependabot ... commands (Dependabot refuses commands from GitHub Apps). A PR that is behind its base branch is updated by Colony merging the base into the Dependabot branch with a [dependabot skip] merge commit; CI on that merge commit runs with the Colony App as github.actor, not dependabot[bot]. A conflicted PR is left for Dependabot, which rebases it itself by default; if it will not, an operator comments @dependabot rebase or @dependabot recreate on the PR. The issue waits in human-review-ready and re-queues review when the PR head changes, unless the update itself is unchanged (same PR title and same non-lockfile diff, ignoring hunk line numbers), in which case the existing review stands. /colony:review forces a re-review when something outside the PR diff changed, for example a peer dependency upgraded on the base branch. With dependabot.auto_migrate_breaking, a review whose recommendation is an Adopt option adopts that option automatically, and the tracking issue moves to waiting-for-migration; it never approves or declines on its own. A merged or closed PR goes to done (at review time or while in merge-pending), never back for reimplementation; a closed PR records a decline. failure-blocked is declared for Colony’s own failure paths (retry cap exhausted); an operator retries or closes it.

When a Dependabot item is held in human-review-ready, Colony posts one decision comment on the tracking issue and edits it in place on every later verdict (new options reset the ticks). It replaces the separate migration notice and “Review Round” comments. The comment holds:

  • A short summary, with the recommendation first.
  • Checkboxes, the recommended one first and marked:
    • Approve as-is
    • Decline this release
    • Decline and ignore this major line
    • Adopt — option k (one per option the reviewer proposes)
    • 🔄 Re-check
  • The evidence, collapsed in <details>.

A pick edits the comment to Selected: <choice> by @<user>.

A tick acts immediately. Ticking another user’s comment needs write access on GitHub.

  • Approve as-is merges the linked PR, even a major update, but only on green CI for the current head. Colony first submits an APPROVED review on that head (replacing its own changes-requested review). A new head invalidates the approval.

  • Decline this release closes the PR, and the tracking issue finishes as done (rejected).

  • Decline and ignore this major line closes the PR and files an already enqueued issue that adds this to the matching updates: entry in .github/dependabot.yml:

    ignore:
    - dependency-name: '<dependency>'
    update-types: ['version-update:semver-major']

    When no updates: entry matches the ecosystem and directory, Colony does not create one (that would turn on version updates). The option instead tells you to post @dependabot ignore this major version on the PR; Colony never posts Dependabot commands.

  • Adopt — option k adopts the update with that option’s instructions, as /colony:adopt would.

  • 🔄 Re-check runs a fresh review and rebuilds the menu.

You can also reply to the menu instead of ticking. Accepted replies:

  • approve
  • decline
  • decline major or ignore major
  • option N, adopt N or a bare N
  • re-check

The first authorized reply after the current menu wins. An unparseable reply gets one help comment listing the accepted replies, and the item stays held. A reply that is a slash command (for example /colony:adopt <instructions> for custom work) is handled as a command only.

An API client can pick without the code host: colony_act with action: "pick", choice (one of approve, decline-release, decline-major, recheck, adopt:<k>), request_id, and optionally actor and round_id. A pick takes the same first-wins claims as a tick, so whichever of the pick, a tick or a reply arrives first acts and the others do nothing. It records actor as who selected. A pick is refused before any write as no_menu (nothing open), stale_round (round_id is not the open round), unknown_choice (the message lists the valid ids) or already_picked.

The workflow also has an approve operator action (human-review-ready → merge-pending), available through colony_act; it records the human approval before the transition, so the merger merges the linked PR.

  • /colony:retry re-runs the current state’s executor.
  • /colony:reopen moves a done issue back to in-review, only while the issue’s most recent Dependabot PR is still open (this also clears the decline recorded when the tracking issue was closed with the PR open, so head-change re-review resumes); if that PR is closed or merged it is refused with an explanation. Reopening the issue on GitHub is handled the same way by the sprint-master sweep.
  • /colony:adopt <instructions> creates a linked issue branched from the Dependabot PR head so your change and the bump merge together; the tracking issue moves to waiting-for-migration until it completes. Once the adopted issue’s PR merges, Colony comments on the Dependabot PR and finishes the tracking issue as done, but leaves the Dependabot PR open: Dependabot closes it once the base branch has that version, otherwise close it by hand.
  • /colony:followup <instructions> creates a linked follow-up issue that starts after the bump merges; the tracking issue’s state is unchanged. It is refused once the tracking issue is done (the bump has already merged); open a normal issue instead.
  • /colony:reanalyze and /colony:feedback get a Dependabot-specific refusal pointing to /colony:adopt, /colony:followup, or handling the PR manually (push a fix to the Dependabot PR or close it).

A retrospective runs only for issues that passed through human-review-ready (or adoption); routine merges get none, including from the missing-retrospective sweep.

colony-dependabot cannot be used as default_workflow or as a repos[].workflows member: config validation rejects it.

Colony ships with colony-support, a first-line support responder for handling customer or user questions. It drafts a reply, an operator approves the draft, and only then is it sent. It also requests clarification and confirms resolution. It produces no PR.

colony-support is designed for a dedicated support repo where every new issue is a support request. To activate it:

  1. Set intake_mode: all on the sprint-master so every new issue enters the pipeline automatically (rather than requiring a colony:enqueue label).
  2. Add a per-repo workflows entry so that issues labeled support are routed to the colony-support workflow; all other issues fall through to colony-default.
agents:
sprint_master:
intake_mode: all
repos:
- owner: your-org
repo: your-support-repo
# ...
workflows:
- workflow_id: colony-default
default: true
- workflow_id: colony-support
match:
- labels: [support]
priority: 1

Note: the global intake_rules key is deprecated in favor of the per-repo repos[].workflows key shown above. See repos[].workflows in the configuration reference for the current mechanism and resolution precedence.

new ──(answered)──► awaiting-approval ──(approve)──► sending ──(sent)──► awaiting-confirmation ──(confirmed_resolved)──► done
▲ │ │
│◄──────(revise)─────────┘ │
└────────────────────────(confirmed_unresolved)──────────────────────────────┘
new ──(needs_clarification)──► needs-clarification ──(clarification_received)──► new
new ──(escalate)──► escalated
new / sending ──(failure)──► failure-blocked
StateTypeDescription
newactiveplugin:colony-support/respond runs a grounding lookup and drafts a reply
awaiting-approvalawaiting-humanA drafted reply waits for operator approval before it is sent
sendingactiveplugin:colony-support/send sends the approved reply, then moves to awaiting-confirmation
awaiting-confirmationawaiting-humanWaits for the user to check the confirmation checkbox or reply
needs-clarificationawaiting-humanBot asked a clarifying question; re-enters new when answered
escalatedawaiting-humanRouted to a human; no automatic resolution
failure-blockedblocked (manual)Executor error; /colony:retry re-enters new
doneterminalIssue resolved

awaiting-approval has no executor outcome; it is left only through an operator action.

ActionTransitionHow to invoke
retryre-runs the current state’s executor/colony:retry
approveawaiting-approval → sendingMCP colony_act with { action: 'invoke', intent: 'approve' }. /colony:approve applies only to epics and does not run this action.
reviseawaiting-approval → new/colony:feedback <text> (or colony_act with action: feedback); the text is passed to the redraft as operator_feedback
reopendone → new/colony:reopen

The confirmation-reply loop in the sprint-master polls awaiting-confirmation issues (skipping paused and blocked issues), detects a checked “Yes, this resolved my issue” checkbox or a positive reply, and transitions to done. An unchecked or negative reply transitions back to new for another attempt. After 2 re-answers (MAX_REANSWERS = 2), the next negative reply adds the needs-human label, posts an escalation comment and moves the issue to escalated.

Place FAQ and policy documents in a .colony/support/ directory inside the support repo. The respond executor picks up all Markdown files in that directory as grounding context before generating an answer.

An optional read-only reference submodule can be pinned in the support repo at the operator level to bring in documentation from another repository (e.g. product docs, an internal knowledge base). This submodule is used as static grounding content: it is checked out inside agent worktrees — initializeWorktree() runs git submodule update --init --recursive whenever .gitmodules exists in the repo, and there is no config option to exclude it.

colony-support does not create branches or pull requests. Every transition is a comment or label change on the original issue.

Terminal window
colony workflow show --builtin colony-support

Valid --builtin values: colony-default, colony-content, colony-support, colony-dependabot.

Each item gets one standing comment, the item panel, that says where it stands. It shows:

  • Status: the current state’s description.
  • Progress: one line per transition (time, station, resulting state), most recent 20, with a count of earlier events omitted.
  • Standing constraints: the constraints in force for the item. The section is absent when there are none.
  • Closed: for a finished item, the closure reason (completed, cancelled or rejected) as the last line.

The sprint-master writes the panel from the store: it posts the comment once and then edits it in place, so the item does not collect a new notification for every change. A sweep with no change makes no write. Panels are not backfilled: only items with a transition after the feature was first enabled get one.

Asks, clarification questions, approvals, escalations, alerts and the Dependabot decision menu stay separate comments.

The following is a trimmed-down version of the built-in colony-content workflow (renamed content-lite so it does not collide with the built-in id). It illustrates a lean pipeline for content/documentation issues using two plugin executors. This is the minimal workflow that covers all outcomes declared by the @colony/plugin-colony-content executors (analyze: success, needs_clarification, failure; draft: draft_created, needs_clarification, failure).

schema_version: 1
workflow:
id: content-lite
version: 1
name: 'Content pipeline (lite)'
description: 'Lean workflow for content/docs. No planning, no CI gating.'
intake:
initial_state: new
trigger_label: colony:enqueue
states:
new:
type: active
executor: plugin:colony-content/analyze
on:
success: drafting
needs_clarification: needs-clarification
failure: failure-blocked
drafting:
type: active
executor: plugin:colony-content/draft
on:
draft_created: human-review-ready
needs_clarification: needs-clarification
failure: failure-blocked
needs-clarification:
type: awaiting-human
on:
clarification_received: new
transitions: [drafting] # additive: drafting not covered by on: or trait rules
human-review-ready:
type: awaiting-human
transitions: [drafting, done, failure-blocked] # no on: entries; all edges are additive
failure-blocked:
type: blocked
recovery: manual
recovery_target: new # retry/auto-unblock re-enters at 'new' instead of the analyze/develop heuristic
# transitions: omitted — blocked/manual trait rule derives all reachable states automatically
done:
type: terminal
operator_actions:
retry:
description: 'Retry the last failed step.'
framework: true

This workflow uses plugin:colony-content/analyze and plugin:colony-content/draft — executors provided by the colony-content plugin. See Plugins for how to author and register a plugin.

Parse and validate a workflow YAML file against the schema. Exits 0 on success, 2 on parse or validation error.

$ colony workflow validate ./my-workflow.yaml
OK: my-workflow v1
states: 9
operator_actions: 2
content_hash: a3f1...

validate checks the Zod schema and all cross-reference constraints (target states exist, blocked states declare recovery, etc.). For a state whose executor: is a builtin:<key>, it also checks that every outcome the builtin declares (BUILTIN_EXECUTOR_OUTCOMES, exported from @runcolony/sdk) appears as a key in that state’s on: block — a missing one is a validation error naming the state and the outcome. It does not verify outcome coverage for a plugin:<pkg>/<key> executor: validation has no loaded manifest to check a plugin’s outcomes against, so a plugin executor state is surfaced as a warning (never an error) by checkOutcomeCoverage, and an unhandled plugin outcome is still only caught at workflow-load time when the worker starts.

Print a workflow definition as YAML. Two modes:

Built-in workflow (no database required):

Terminal window
colony workflow show --builtin colony-default

Valid --builtin values: colony-default, colony-content, colony-support, colony-dependabot.

Stored workflow (reads from the registry database):

Terminal window
colony workflow show \
--workflow-id my-workflow \
--version 2 \
--tenant-id 42 \
[--database-url postgres://...]

All three of --workflow-id, --version, and --tenant-id are required for registry reads. The database URL is read from --database-url or the $DATABASE_URL environment variable. The command exits 2 if neither mode is fully specified.