Workflows
Workflows
Section titled “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.
YAML schema
Section titled “YAML schema”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 fieldsproposal 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.
Station-attempt ceiling
Section titled “Station-attempt ceiling”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:retryresumes it. Only if the workflow has none does it move to the state’sescalate_humantarget, or else itserrorroute. - The issue gets the needs-human label, one explanatory comment per reset period (kind
status:worker:attempt-ceiling), and anattempt ceiling reachedstatus 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:retryor/colony:reimplementis used.
The seven per-loop bounds (max_review_cycles and the others) are unchanged. The ceiling only catches their combined total.
State slugs
Section titled “State slugs”State and action keys must be kebab-case slugs: lowercase letters, digits, and hyphens; 1–64 characters; must start with a letter or digit.
States
Section titled “States”The states key is a record of slug → state definition. Each state has the following fields:
| Field | Required | Description |
|---|---|---|
type | yes | State trait — see State traits |
executor | no | Which executor to run — see ExecutorRef |
recovery | yes (if type: blocked) | How the state recovers: manual or auto |
entry_descriptions | no | Map 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_target | no | Re-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_attempts | no | Positive 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_handling | no | What 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. |
label | no | GitHub label string for this state (cosmetic) |
description | no | One-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. |
model | no | Model 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. |
effort | no | Reasoning effort for this station: low, medium, high or max. Overrides the per-role key and the complexity tier. |
max_turns | no | Turn budget for this station’s agent. Overrides the per-role key and the complexity tier. |
stale_after_minutes | no | Minutes 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. |
on | no | Outcome → route map — see Outcome routing |
transitions | no | Optional 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. |
hooks | no | Terminal-only post-completion hooks — see Hooks |
State traits
Section titled “State traits”The type field controls the lifecycle semantics of a state:
| Trait | Meaning |
|---|---|
active | Worker picks up a task and runs the state’s executor |
blocked | Issue is blocked; must declare recovery: manual or recovery: auto |
awaiting-human | Issue is waiting for human input; no executor runs |
terminal | Issue is complete; must not declare executor, transitions or on: routes |
ExecutorRef
Section titled “ExecutorRef”The executor field takes a reference string in one of two forms:
builtin:<name> # e.g. builtin:analyze, builtin:developplugin:<package>/<name> # e.g. plugin:colony-content/analyzeBuilt-in executors are provided by Colony itself. Plugin executors are declared by a registered plugin — see Plugins.
Outcome routing
Section titled “Outcome routing”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_overflowThe 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 emptyoptional(defaulttrue) is accepted but currently informational: hook enqueueing is fire-and-forget and never reverts the terminal transition, whatever the flag says.once_per_issue(defaulttrue) dedupes on theterminal_hookkey<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 fromcolony-dependabot.
Operator actions
Section titled “Operator actions”The operator_actions key registers named actions that pipeline operators (humans or MCP tools) can trigger via slash commands. Each action has:
| Field | Required | Description |
|---|---|---|
description | yes | Human-readable label for the action |
framework | no | true marks this as a framework-reserved action (no from/to required) |
from | yes (non-framework) | Array of source state slugs from which this action is valid |
to | yes (non-framework) | Target state slug |
side_effects | no | Side effects to execute: close-pr, merge-pr, add-label, remove-label |
intent | no | Slug naming the slash-command intent the action fulfils: reimplement, reanalyze, reopen, approve, or a workflow-specific one such as revise on colony-support |
label | no | Optional display name, e.g. “Accept” for approve |
decision_input | no | What 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.
Runtime semantics
Section titled “Runtime semantics”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:reopenenforcesfromstrictly. If the issue is not in a listed state, Colony posts an error comment (“Cannot reopen: issue is in<state>, but/colony:reopenis only available from:<allowed states>”) and the transition does not happen./colony:reimplementalso enforcesfrom. If the issue is not in a listed state, Colony posts “Cannot reimplement: issue is in<state>, but/colony:reimplementis 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:reanalyzedoes not enforcefromwith a dedicated error comment. Instead, the effective allowed-transition set (states[from].allowedTransitions, derived fromon:,recovery_target, operator action targets, state traits, and any additivetransitions: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.
Triggers
Section titled “Triggers”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).
| Field | Required | Description |
|---|---|---|
task_type | yes | Task type string to enqueue (e.g. ci_repair) |
state | yes | Kebab-case slug of the state this trigger applies to (must be a blocked state that declares on: routes) |
block_reason | no | Predicate matched against the issue’s block_reason column; trigger only fires when the column value equals this string |
executor | no | Executor ref (builtin:<name> or plugin:<pkg>/<name>) whose outcomes the enqueued task will produce |
max_cycles | no | Positive integer cap on re-enqueue attempts (default mirrors today’s value of 2) |
guards | no | Extra 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: trueA 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.
Schema constraints
Section titled “Schema constraints”The schema enforces the following rules at parse time:
intake.initial_statemust 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
blockedmust declarerecovery. recovery_target, if declared, may only appear ontype: blockedstates and must reference a state that declares anexecutor(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
terminalmust not declareexecutorortransitions, noron:routes. max_recovery_attempts, if declared, must be a positive integer and may only appear ontype: blockedstates.workflow.proposal, if declared, needs non-emptykindsandsectionswith no empty strings.workflow.tracks.idmust not equalworkflow.id.noopandretryare reserved outcomes and must not appear as keys in any state’son:map.- Each
rolemay be declared on at most one state. - Every state with an
executorneeds a reachable blocked fallback: anon:outcome, or atransitions:entry, that targets atype: blockedstate. decision_input, if declared, must beoperatorormaterial.- Each trigger’s
statemust be defined, be ablockedstate, and declare a non-emptyon:. - For
builtin:<key>executors, every outcome the builtin can produce must be mapped inon:, and an unknownbuiltin:key is an error. Plugin executors only produce a warning. Seecolony workflow validate. - Redeclaring the
retry/reopenspine actions with different semantics fails validation; see Undeclared actions. hooksmay only be declared onterminalstates.- Every target in
on:, any additivetransitions:entries, and operator actionfrom/tofields must reference a defined state. - Every workflow sub-object (not only states) is strict: authoring and
colony workflow validatereject 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 asrole.) constraint_handling, if declared, must be one ofnothing,reports, orenforces. It is not required on executor-bearing states — workflows also come fromrepo-file,config, andcloud-pushsources, and a required field would fail to parse every customer-authored workflow already in the wild.
Per-station agent configuration
Section titled “Per-station agent configuration”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:
model_routing.override— the global kill-switch, applied regardless of task type, tier orenabled- the station’s declared
model: model_routing.routes- 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.
Built-in workflow: colony-default
Section titled “Built-in workflow: colony-default”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 thenewstate, wherebuiltin:analyzeruns.- 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. Thedependency-blockedpipeline state (IssueState.DependencyBlocked) and thecolony:blockedflag label are unchanged. Dependency blocks are surfaced in GitHub as native blocked by #N relationships (via the issue-dependencies API) rather than acolony:dependency-blockedlabel — the label is no longer projected. - Terminal state:
done— triggers aretrospecthook (optional, once-per-issue). - Operator actions:
retry(framework),reimplement,reanalyze,reopen,approve(“Accept”:human-review-ready → merge-pending,decision_input: material, nomerge-prside effect).colony-contentdeclares the sameapproveaction.
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:
colony workflow show --builtin colony-defaultBuilt-in workflow: colony-content
Section titled “Built-in workflow: colony-content”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).
colony workflow show --builtin colony-contentBuilt-in workflow: colony-dependabot
Section titled “Built-in workflow: colony-dependabot”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:dependabotThe dashboard’s Needs Attention panel groups these issues in a separate Dependabot section.
States
Section titled “States”| State | Meaning |
|---|---|
in-review | Intake enters here directly (single transition). The reviewer checks the Dependabot PR. |
merge-pending | Review approved; the merger merges the PR. A needed rebase sends the issue back to in-review. |
waiting-for-migration | Dependency-blocked, auto-recovering. Entered by /colony:adopt (or /colony:reimplement) while the adopted issue is open. |
human-review-ready | Awaiting a human: failed review, escalation, auto-merge disabled, or a task failure. |
failure-blocked | A task for the PR exhausted its retries; an operator must retry or close it. |
paused | Suspended by an operator. |
done | Terminal: 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.
Decision menu for held updates
Section titled “Decision menu for held updates”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 versionon the PR; Colony never posts Dependabot commands. -
Adopt — option k adopts the update with that option’s instructions, as
/colony:adoptwould. -
🔄 Re-check runs a fresh review and rebuilds the menu.
You can also reply to the menu instead of ticking. Accepted replies:
approvedeclinedecline majororignore majoroption N,adopt Nor a bareNre-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.
Operator actions
Section titled “Operator actions”/colony:retryre-runs the current state’s executor./colony:reopenmoves adoneissue back toin-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 towaiting-for-migrationuntil it completes. Once the adopted issue’s PR merges, Colony comments on the Dependabot PR and finishes the tracking issue asdone, 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:reanalyzeand/colony:feedbackget 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.
Built-in workflow: colony-support
Section titled “Built-in workflow: colony-support”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.
Intake model
Section titled “Intake model”colony-support is designed for a dedicated support repo where every new issue is a support request. To activate it:
- Set
intake_mode: allon the sprint-master so every new issue enters the pipeline automatically (rather than requiring acolony:enqueuelabel). - Add a per-repo
workflowsentry so that issues labeledsupportare routed to thecolony-supportworkflow; all other issues fall through tocolony-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: 1Note: the global
intake_ruleskey is deprecated in favor of the per-reporepos[].workflowskey shown above. Seerepos[].workflowsin the configuration reference for the current mechanism and resolution precedence.
State machine
Section titled “State machine”new ──(answered)──► awaiting-approval ──(approve)──► sending ──(sent)──► awaiting-confirmation ──(confirmed_resolved)──► done ▲ │ │ │◄──────(revise)─────────┘ │ └────────────────────────(confirmed_unresolved)──────────────────────────────┘
new ──(needs_clarification)──► needs-clarification ──(clarification_received)──► newnew ──(escalate)──► escalatednew / sending ──(failure)──► failure-blocked| State | Type | Description |
|---|---|---|
new | active | plugin:colony-support/respond runs a grounding lookup and drafts a reply |
awaiting-approval | awaiting-human | A drafted reply waits for operator approval before it is sent |
sending | active | plugin:colony-support/send sends the approved reply, then moves to awaiting-confirmation |
awaiting-confirmation | awaiting-human | Waits for the user to check the confirmation checkbox or reply |
needs-clarification | awaiting-human | Bot asked a clarifying question; re-enters new when answered |
escalated | awaiting-human | Routed to a human; no automatic resolution |
failure-blocked | blocked (manual) | Executor error; /colony:retry re-enters new |
done | terminal | Issue resolved |
Operator actions
Section titled “Operator actions”awaiting-approval has no executor outcome; it is left only through an operator action.
| Action | Transition | How to invoke |
|---|---|---|
retry | re-runs the current state’s executor | /colony:retry |
approve | awaiting-approval → sending | MCP colony_act with { action: 'invoke', intent: 'approve' }. /colony:approve applies only to epics and does not run this action. |
revise | awaiting-approval → new | /colony:feedback <text> (or colony_act with action: feedback); the text is passed to the redraft as operator_feedback |
reopen | done → 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.
Grounding
Section titled “Grounding”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.
colony workflow show --builtin colony-supportValid --builtin values: colony-default, colony-content, colony-support, colony-dependabot.
Item panel
Section titled “Item panel”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,cancelledorrejected) 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.
Custom workflow example
Section titled “Custom workflow example”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: trueThis 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.
CLI reference
Section titled “CLI reference”colony workflow validate <file>
Section titled “colony workflow validate <file>”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.yamlOK: 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.
colony workflow show
Section titled “colony workflow show”Print a workflow definition as YAML. Two modes:
Built-in workflow (no database required):
colony workflow show --builtin colony-defaultValid --builtin values: colony-default, colony-content, colony-support, colony-dependabot.
Stored workflow (reads from the registry database):
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.