Slash Command Reference
Slash Command Reference
Section titled “Slash Command Reference”Slash commands are Colony’s primary operator control surface for in-flight issues. They are posted as GitHub issue comments and delivered to the Sprint Master by the webhook receiver, so webhooks must be enabled (see Webhook Setup).
vs. the
colonyCLI: ThecolonyCLI (colony start,colony why,colony check, etc.) runs on your machine and manages the pipeline infrastructure. Slash commands are posted to GitHub issues and control individual issues in the running pipeline. See the CLI Reference for CLI commands.
How Slash Commands Work
Section titled “How Slash Commands Work”- Comment
/colony:<command>(or your configured root) on any GitHub issue that Colony is tracking. - The webhook receiver gets the
issue_commentevent (or the pull request review / review comment event for commands posted on a PR) and forwards the command to Sprint Master, which runs it immediately. - Sprint Master reacts with 👍 to acknowledge the command (
statereacts with 👎 instead when the target is missing or invalid; other commands such asprioritykeep the 👍 and post a usage comment on invalid input). - The command executes. For state-changing commands, the GitHub label update goes through the outbox; Sprint Master drains it as soon as the transition commits (via Postgres NOTIFY), with a periodic drain every 60 seconds as a fallback.
Prose messages. A message addressed to Colony without a slash command (for example
@colony please rename foo) gets an immediate 👀 reaction as soon as Sprint Master claims it, before the Mayor’s in-thread reply.
Webhooks required. Slash commands are not read by polling. Without the webhook receiver, commands are ignored; use
colony_act(MCP) or dashboard actions instead. See the slash-command equivalents table for thecolony_actaction behind each command.
Commands are idempotent where possible. If the same command comment is processed twice (e.g., after a Sprint Master restart), Colony detects the dedup timestamp and skips the second execution.
Command Reference
Section titled “Command Reference”All commands use the colony prefix by default. See Command Root if you’ve configured a custom prefix.
| Syntax | Description |
|---|---|
/colony:retry [small|medium|large] | Retry the current pipeline stage. Optionally pass a size override (small, medium, or large) to pin the complexity tier for this retry — useful when the issue stalled due to insufficient model capacity. |
/colony:skip-planning | Skip the planning step and proceed directly to implementation. Use when an issue is blocked on a planning budget limit and you want the developer to implement from the current analysis without a planning session. |
/colony:decompose | Route the issue to the planner for epic decomposition into sub-issues. Adds the colony:epic label and transitions to planning. |
/colony:cancel | Cancel the issue and close it. Transitions the issue to its workflow’s terminal state (done for builtin workflows, otherwise the workflow’s first type: terminal state) with closure reason cancelled, fails any claimed in-flight task, and closes the GitHub issue. No-op if the issue is already in a terminal state, or if the workflow defines no terminal state (a warning is logged). |
/colony:pause | Pause pipeline processing for this issue. Saves the current state to paused_from_state, deletes pending tasks, stops any run in progress (its claimed task is cancelled and the executor aborted), and sets the issue to paused. |
/colony:resume | Resume a paused issue, returning it to the state it was in before it was paused. Sprint Master re-enqueues the appropriate task on its next poll. |
/colony:reimplement | Discard the current implementation and restart. Deletes the colony/issue-N branch and removes the local worktree (before the state transition). Closes the open PR only when the workflow declares side_effects: [close-pr] for this action. Target state is workflow-defined (via operator_actions.reimplement.to; resolved by the action’s intent: reimplement, e.g. colony-content’s redraft). It is refused with a from-mismatch comment, before any cleanup, when the current state isn’t in the action’s from list (on colony-default: in-review, merge-pending, human-review-ready, changes-requested, failure-blocked); this check is skipped for Dependabot items and when no workflow snapshot is loaded. On colony-dependabot tracking issues it behaves as /colony:adopt instead: no branch deletion, PR closure or worktree removal. |
/colony:state <target-state> | Force a manual state transition. The target is validated against the workflow snapshot — Colony replies with 👎 and a list of valid targets if the transition is not allowed. |
/colony:priority <high|normal|low> | Set manual scheduling priority for this issue: high (+500), normal (0), or low (−200). Takes effect on the next scheduler poll. |
/colony:review | Re-trigger deterministic checks and LLM review. Sends the item to the workflow’s review state (in-review on colony-default, review-ready on colony-content). Valid from a non-terminal, non-blocked state that can move to the review state and is a judgement (awaiting-human) state, the merge station, or the primary develop station: colony-default human-review-ready, merge-pending, ready-for-dev; colony-content human-review-ready, merge-pending; colony-dependabot human-review-ready. Workflows with no review state (e.g. colony-support) reply “This workflow does not support /colony:review”. On a Dependabot item it always re-reviews, even when the update is unchanged; use it when something outside the PR diff changed (for example a peer dependency upgraded on the base branch). |
/colony:feedback | Send rework feedback: on a PR awaiting review or merge it converts the PR to draft and requests changes; otherwise it is stored for the agent’s current or next run; refused on done. For needs-clarification or failure-blocked with spec-ambiguity classification, re-enters analysis instead. Uses the full message text (above and below the command line). Refused on colony-dependabot tracking issues (see /colony:adopt and /colony:followup). |
/colony:reanalyze | Re-run issue analysis from scratch. Target state is workflow-defined (via operator_actions.reanalyze.to). Whether the transition succeeds is governed by the workflow transition graph. Posts an error comment when the workflow does not declare this action. Not available on done issues (use /colony:reopen first) or paused issues (use /colony:resume first). |
/colony:reopen | Reopen a completed issue and return it to the pipeline. reopen is a framework spine action: it is available even when the workflow declares no reopen entry — the framework supplies a default with from: the workflow’s terminal states and to: intake.initial_state. When the workflow declares it, the target is workflow-defined (via operator_actions.reopen.to). For colony-dependabot, the target is in-review and the command is refused unless its most recent Dependabot PR is still open. Only a workflow with no terminal-trait state has no reopen; there Colony posts a guidance comment suggesting a fresh issue with colony:enqueue. |
/colony:track | Manage self-improvement track assignment. No handler implemented — posting this command produces a 👍 reaction but takes no action. See Per-Command Notes. |
/colony:enqueue [high|normal|low] | Add an untracked issue to the Colony pipeline. Optionally pass a priority level (high, normal, or low). If the issue is already in the pipeline, Colony replies with the current state and suggests /colony:priority instead. |
/colony:constrain <text> | Record a standing constraint on this item that every station reads on every run. Recording does not require an open change and does not gate on pipeline state. Posts an ack comment listing all current constraints, numbered. |
/colony:unconstrain <n|all> | Remove a standing constraint by number, or all to remove every constraint. Bare /colony:unconstrain removes nothing and re-posts the numbered list. |
/colony:release #<child> | On a parent issue: release a cancelled subtask so the parent can finalize without it. Refused if #<child> is not a subtask of this parent or is not cancelled; releasing an already-released subtask changes nothing. The parent finalizes on its next sweep if nothing else is outstanding. |
/colony:adopt <instructions> | Dependabot tracking issues only: create a linked issue whose branch starts from the Dependabot PR head, so your change and the bump merge together; the tracking issue waits on it. Allowed from in-review, merge-pending and human-review-ready; creates an adopted-from linked issue branched from the Dependabot PR head; the tracking issue enters waiting-for-migration; one active adoption at a time. The decision menu’s Adopt checkbox does the same with the reviewer’s option instructions; a reply starting with /colony:adopt is handled as a command only. On other workflows, the generic unsupported-command reply. |
/colony:followup [instructions] | Dependabot tracking issues: <instructions> required — create a linked follow-up issue that starts after the bump merges. The followup-of linked issue is dependency-blocked until the tracking issue is done; the tracking issue’s state is unchanged. Multiple follow-ups are allowed. Refused once the tracking issue is done (the bump has already merged): open a normal issue instead. Epics: no text needed — files the polish follow-up issue listing the epic’s open, not-yet-filed polish findings (not enqueued, linked from the epic by a polish-followup link). Running it again replies with the existing issue, or appends only newly found findings as a comment. Other issues get the generic unsupported-command reply. |
/colony:approve [followup|no-followup] [note] | Epics in human-review-ready only: record that you accept every open blocking epic-review finding: the findings the latest escalation comment lists, plus any blocking finding still open from an unfinished remediation (dismissed with reason accepted_by_human, recording your note). Escalations raised because the review tooling or LLM failed offer only retry/cancel. followup / no-followup overrides epic.review.polish_followup for this epic (file / log). Does not merge, transition, approve the PR, or remove needs-human — approve the pull request to merge, or use the API Accept (colony_act invoke intent=approve). |
/colony:help | Post a comment listing all available operator slash commands with syntax and descriptions. Deduped — if a help comment is already present on the issue, a second /colony:help is suppressed. |
Per-Command Notes
Section titled “Per-Command Notes”/colony:retry [small|medium|large]
Section titled “/colony:retry [small|medium|large]”The optional size argument pins the complexity tier for this retry:
| Size | Effect |
|---|---|
small | Lower model tier, fewer turns — fastest and cheapest |
medium | Mid-tier model and turn budget |
large | Highest model tier, maximum turns — use when a prior attempt stalled due to insufficient capacity |
Without a size argument, Colony uses the complexity tier that was already set for the issue (derived from the analyzer’s assessment).
On an epic, retry also resets the epic review budget (remediation_cycle and auto_fix_attempts back to 0), so the next epic review runs as cycle 1 instead of re-escalating at the cap. This applies to every route: an epic in in-review, a failure-blocked epic, and an epic parked in human-review-ready (which retry moves back to in-review). Colony records an epic_review_budget_reset status with the prior values and notes the reset in the retry marker comment. If the retry is refused or fails, the prior counter values are restored. Non-epic issues are unaffected.
When retrying a quota-blocked issue, Colony posts a warning noting that Sprint Master auto-recovers at the reset time — manual retry forces an earlier attempt that may re-fail if the quota has not yet reset.
/colony:state <target-state>
Section titled “/colony:state <target-state>”The target state is validated against the workflow snapshot. If the transition is not in the snapshot graph, Colony replies with a 👎 reaction and a comment listing valid targets from the current state. Valid state values include new, analyzing, ready-for-dev, in-review, human-review-ready, changes-requested, merge-pending, done, paused, failure-blocked, dependency-blocked, needs-clarification, planning, and any custom workflow states.
/colony:reopen
Section titled “/colony:reopen”reopen is guaranteed by the framework: it is one of the operator-action spine members (see Operator Actions in the Workflows guide), so it is available even for a workflow that declares no reopen entry in operator_actions at all. The framework supplies a default of from: the workflow’s terminal-trait states, to: intake.initial_state. A workflow only needs to declare reopen explicitly to rename it (via intent: reopen) or to attach side_effects — a declared from/to must still match the trait-derived default, or the workflow fails validation at publish time.
Resolving and applying reopen (whether spine-supplied or workflow-declared, e.g. colony-default with from: [done], to: new):
- The issue must be in a state listed in the resolved action’s
from. Invoking the command from any other state results in an error comment: “Cannot reopen: issue is in<state>, but/colony:reopenis only available from:<allowed states>.” - On success, the issue transitions to the resolved action’s
to(e.g.new), bypassing the normaltransitionsgraph. This terminal-exit override is the supported mechanism for bringing adoneissue back into the pipeline. If the issue is closed on GitHub, Colony also reopens it.
When the workflow has no terminal state (the spine cannot supply reopen):
A workflow with no terminal-trait state has no terminal states to derive from: from, so the spine does not supply reopen in that case. Colony posts a guidance comment explaining the workaround: open a fresh GitHub issue describing what you want re-done, then apply the colony:enqueue label or comment /colony:enqueue to add it to the pipeline.
/colony:track
Section titled “/colony:track”The track command appears in /colony:help output (it is registered in the command descriptor map), but has no handler in the Sprint Master’s command dispatch. Posting /colony:track produces a 👍 reaction but no action — it silently no-ops. This is a known gap; the handler is not yet implemented.
/colony:release #<child>
Section titled “/colony:release #<child>”A cancelled subtask blocks its parent from auto-finalizing, so the operator must act deliberately. /colony:release #<child> on the parent marks that one subtask edge released (recording who and when); the parent then finalizes through the normal path on its next sweep if nothing else is outstanding. It does not reopen or retry the child. Only cancelled subtasks can be released; paused, failed or open children, and depends_on edges, cannot. The parent’s cancelled-subtasks payload lists the cancelled children not yet released.
/colony:constrain <text> and /colony:unconstrain <n|all>
Section titled “/colony:constrain <text> and /colony:unconstrain <n|all>”A standing constraint is an operator instruction — “don’t touch the migrations,” “match the existing error handling” — that is bound to the work item rather than to a single run:
- It is added and retracted only by the operator, via these two commands.
- It is read by every core station (analyzer, developer planning, developer implementation and its changes-requested cycle, and reviewer) on every run, not just the run immediately following the comment.
- Colony records a standing constraint only from this command; an addressed message that reads like one gets a reply pointing here, and nothing is recorded.
- It dies with the item — removing the issue’s pipeline row removes its constraints too.
- A constraint on a parent item also applies to each of its subtasks, labelled
From #<parent>; removing it from the parent releases them.
Numbered ack. Every /colony:constrain and /colony:unconstrain posts a comment listing the current constraints, numbered from 1. The ordinal shown in that list is exactly what /colony:unconstrain <n> expects — the number to remove is always freshly visible directly above the command you’d type next. /colony:unconstrain all removes every constraint on the issue. The bare form, /colony:unconstrain with no argument, removes nothing — it just re-posts the numbered list, useful for checking ordinals before removing one.
Constraining an item that isn’t in the pipeline yet. The natural moment to record a constraint is often when the issue is filed, before Colony has started working it. Running /colony:constrain <text> on such an issue creates its pipeline row in the pre-pipeline state without starting any work — no executor runs, no task is enqueued. Colony replies noting the issue isn’t queued yet. Run /colony:enqueue when you’re ready to start; enqueue succeeds normally from a pre-pipeline row.
Surfaced, not enforced. The constraint text is rendered verbatim into the prompt at every station listed above, so the agent sees it. This is not a guarantee that the station honors it — whether a given state’s executor merely reports the constraint or actually enforces it is that state’s own constraint_handling declaration, and a station with no declaration surfaces the constraint without any promise about it.
Relationship to /colony:feedback. Standing constraints are the durable successor to ad hoc /colony:feedback comments: feedback is a one-shot instruction consumed by the very next development run, while a constraint persists and is read by every station until explicitly retracted. /colony:feedback is an explicit “this is rework” shortcut: it uses the full message text (lines above and below the command line included) and routes by issue state. In human-review-ready, in-review, merge-pending and failure-blocked it converts the PR to draft and transitions to changes-requested with the text as operator_feedback; in needs-clarification (or spec-ambiguity failure-blocked) it re-enters analysis; in any other judgement state whose workflow declares a revise action (for example colony-support’s awaiting-approval) it claims the pending decision and moves the item to that action’s target state with the text as operator_feedback, and a judgement state that declares no revise action is refused with no_rework_path and nothing is stored; in every other non-terminal state (ready-for-dev, changes-requested, analyzing, …) the text is stored in the issue’s mailbox for the agent’s current run or, failing that, its next run. On done it is refused (use /colony:reopen), and when mailbox.enabled is false the mailbox route is refused and nothing is stored.
MCP twins. Hosts that cannot post slash commands (bot identities are ignored) can use colony_act with action: constrain or action: feedback; see colony_act.
/colony:approve [followup|no-followup] [note]
Section titled “/colony:approve [followup|no-followup] [note]”Records your acceptance of an epic’s remaining blocking review findings.
- Availability: epics only (epic branch
epic/<n>), inhuman-review-ready, and not paused. Anywhere else it is refused with a comment. - What it records: every open blocking
integration_gapfinding from the epic reviewer is dismissed with reasonaccepted_by_human. That covers the findings the latest escalation comment lists, plus any blocking finding still open from an unfinished remediation. Each escalation persists the blocking findings it shows, and a newer escalation supersedes earlier escalation rows it no longer lists. Escalations raised because the review tooling or LLM failed offer only retry/cancel, not approve. Your note,humanAcceptance.actor(the commenting user’s login, or null if the code host did not report an author) andviaset to the approve command are stored in the finding’s metadata (humanAcceptance). A later epic review does not treat those findings as blocking, even if it raises them again. - The optional first word:
followuporno-followupsets this epic’s polish follow-up mode, overridingepic.review.polish_followup.followupfiles a follow-up issue on merge;no-followuponly lists the polish findings, which stay resolvable. Omitted, the setting is left unchanged. - API equivalent:
colony_actwithaction: invoke,intent: approveaccepts the epic the same way and merges as well, with no code-host approval; see Accepting an epic. Once an API Accept (or a Reject or code-host approval) has won the epic’s judgement ask,/colony:approveis refusedalready_decided. - What it does not do: it does not merge, change state, approve the PR, or remove
needs-human. Approve the pull request on the code host; Colony auto-merges once an authorized approval is present. If an authorized approval already exists, the command triggers the merge check immediately.
Examples:
/colony:approve/colony:approve no-followup/colony:approve followup race note acknowledged, tracked separatelyCommand Root
Section titled “Command Root”By default, all commands use the colony prefix. You can change this with the commands.root config option:
commands: root: pipeline # /pipeline:retry, /pipeline:help, etc.This replaces the prefix across all agent-posted comments and the webhook receiver’s command parser. The original colony prefix stops working — it is an override, not an alias. GitHub labels (e.g., colony:analyzing, colony:enqueue) are not affected by commands.root. See GitHub Labels for the full label vocabulary.
Restart required.
commands.rootis read at process startup. Changing it requires restarting bothsprint-masterandwebhook-receiverto take effect. Hot-reload (POST /api/config/reload) does not apply to this field.
See Configuration Reference — commands for full details and validation rules.
Delivery and Replay
Section titled “Delivery and Replay”The webhook receiver forwards each slash command to Sprint Master over Postgres NOTIFY, and the command runs right away rather than waiting for a poll cycle. This requires the Issue comments webhook event (plus Pull request reviews and Pull request review comments for commands posted on PRs).
A replay sweep runs every 2 minutes as a safety net. It re-runs forwarded commands that never executed: older than 60 seconds, younger than 24 hours, up to 3 attempts. It only replays commands the receiver already stored, so it does not replace the webhook receiver.