Slash Command Reference

Related concepts

• Slash Commands — Full reference for all /colony: commands

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 colony CLI: The colony CLI (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

1. Comment /colony:<command> (or your configured root) on any GitHub issue that Colony is tracking.
2. Sprint Master detects the comment on its next poll (default: every 30 seconds).
3. Sprint Master reacts with 👍 to acknowledge the command (state reacts with 👎 instead when the target is missing or invalid; other commands such as priority keep the 👍 and post a usage comment on invalid input).
4. 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

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: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: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

/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>

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

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:reopen is only available from: <allowed states>.”
• On success, the issue transitions to the resolved action’s to (e.g. new), bypassing the normal transitions graph. This terminal-exit override is the supported mechanism for bringing a done issue 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

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: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.
• It dies with the item — removing the issue’s pipeline row removes its constraints too.

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 itself is unchanged — it remains the mechanism for triggering a re-review/re-implementation cycle on an open PR.

---

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.root is read at process startup. Changing it requires restarting both sprint-master and webhook-receiver to 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

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).