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 processed by the Sprint Master on each poll cycle (default: 30 seconds).
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. - Sprint Master detects the comment on its next poll (default: every 30 seconds).
- 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 updates within the same poll cycle.
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 to done with closure reason cancelled and closes the GitHub issue. No-op if the issue is already done. |
/colony:pause | Pause pipeline processing for this issue. Saves the current state to paused_from_state, cancels any pending tasks, 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; falls back to redraft if the workflow uses that alias instead). Whether the transition succeeds is governed by the workflow transition graph, not a dedicated from-mismatch check. |
/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. Valid from human-review-ready, merge-pending, or ready-for-dev states. |
/colony:feedback | Send operator feedback to the implementation. Converts the PR to draft and transitions to changes-requested so the developer re-reads review comments and iterates. For issues in needs-clarification or failure-blocked with spec-ambiguity classification, re-enters analysis instead. |
/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). 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: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).
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.
Command 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.
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.
Poll Cadence
Section titled “Poll Cadence”Sprint Master checks for new slash command comments on each poll cycle. The default poll interval is 30 seconds — a command posted right after a poll may take up to 30 seconds to be processed. Configure the interval with agents.sprint_master.poll_interval (minimum: 5).