The Workflow
Follow one issue from raw input to merged PR. The colony’s view on the left, your team’s view on the right.
The pipeline runs in five phases. Most issues move through them in order; some loop back (a review rejection returns the issue to development), and some take recovery paths the colony handles for you. The happy path is what you’ll see most days.
Phase 1: Intake
Section titled “Phase 1: Intake”Author files the issue; Colony picks it up and triages.
What Colony does
- Watches the repository for new issues
- The mayor (Sprint Master) hands the issue to an analyzer worker
- The analyzer reads the issue, the repo conventions, and the relevant code, then proposes an implementation plan
- Either: marks the issue
ready-for-dev, or comments back with clarification questions
What humans do
| Role | Activity |
|---|---|
| Author | Files the issue with context, requirements, acceptance criteria, test criteria, and file references. Responds to clarification questions if the analyzer asks. |
| Reviewer | — |
| Operator | Monitors the analyzer queue. Intervenes only if work stalls. |
| Sponsor | — |
What can go wrong
The analyzer flags missing information
The issue returns to the Author with a comment listing what’s needed. The Author edits the issue or adds context in a comment; the analyzer re-runs automatically. See the Author role for guidance on writing issues the analyzer can act on the first time.
The analyzer is offline or workers are saturated
The Operator sees the queue depth on the dashboard. They can resize the worker pool or wait. See Operator → intervene.
Where to go deeper
- Author role — how to file an issue Colony can act on
- Pipeline States reference — the full state machine
Phase 2: Planning & Dispatch
Section titled “Phase 2: Planning & Dispatch”Analyzer produces a plan; epics decompose; Author confirms scope.
What Colony does
- For non-epic issues: produces a plan, transitions to
ready-for-dev - For epic-scale issues: a planner worker decomposes the epic into subtasks, each filed as its own issue
- The mayor selects the next issue from the ready queue and dispatches it to a free worker
What humans do
| Role | Activity |
|---|---|
| Author | Reviews the analyzer’s proposed plan when present. Comments to refine scope before development starts. |
| Reviewer | — |
| Operator | Monitors capacity. Adjusts worker pool size if dispatch is bottlenecked. |
| Sponsor | — |
What can go wrong
Epic decomposition takes multiple passes
Some epics need iteration. The planner may file a draft decomposition, the Author refines it, and the planner re-runs. This is normal. See Author → accept the plan.
The proposed plan is wrong
The Author comments on the issue with corrections. The analyzer re-runs and produces an updated plan. If the plan is fundamentally misaligned, the Author can close and re-file with clearer scope.
Where to go deeper
Phase 3: Development
Section titled “Phase 3: Development”A worker claims the issue, writes code, opens a PR.
What Colony does
- A developer worker takes the issue, creates a branch, and writes code
- Runs configured CI checks locally before opening the PR
- Opens the PR against the target branch with a description linked to the originating issue
What humans do
| Role | Activity |
|---|---|
| Author | — |
| Reviewer | — (reviewer hasn’t engaged yet — Colony’s reviewer goes first) |
| Operator | Monitors for stuck workers. Intervenes if a worker stalls or hits a recoverable error. |
| Sponsor | — |
What can go wrong
The worker stalls or times out
The mayor’s recovery protocol catches most stalls automatically. If recovery exceeds its retry budget, the issue surfaces on the dashboard with a “needs operator” flag. See Operator → recover.
A dependency conflict appears mid-development
The mayor pauses the issue until the conflicting work merges. The Operator sees the dependency lock on the dashboard and can override if the conflict is spurious.
CI fails on the worker’s first attempt
The worker iterates. If CI fails repeatedly, the issue moves to a recovery state and the Operator is paged.
Where to go deeper
Phase 4: Review
Section titled “Phase 4: Review”Colony’s reviewer judges the PR; humans take over only when needed.
What Colony does
- A reviewer worker reads the PR, the issue, and the diff
- Runs deterministic checks (lint, tests, type-check, security scans)
- Performs an LLM-based review for architectural fit and intent
- Either: approves and transitions to
merge-pending, or transitions tohuman-review-readyfor the Reviewer
What humans do
| Role | Activity |
|---|---|
| Author | Validates the PR against the original acceptance criteria when notified. |
| Reviewer | Reads the LLM review’s output, judges architectural fit, comments or requests changes. May invoke /colony:reimplement to send the PR back for a different approach. |
| Operator | — (unless review loops repeatedly, which signals a configuration problem) |
| Sponsor | — |
What can go wrong
Review-rejection cycles
The Reviewer requests changes; the developer worker re-runs; the reviewer re-judges. Two or three cycles is normal. More than three signals the issue’s scope or the repo’s conventions need refinement. See Operator → configure.
The Reviewer wants to override automerge
A flat-out approval doesn’t always mean “merge now.” The Reviewer can mark the PR as do-not-automerge if they want a human to be the last to merge. See Reviewer → override.
The security scan flags a critical finding
The PR blocks at human-review-ready. The Reviewer evaluates and either accepts the risk, files a follow-up, or requests a different implementation.
Where to go deeper
- Reviewer role — what to look for, how to escalate
- Pipeline States reference — review-state transitions
Phase 5: Merge & Close
Section titled “Phase 5: Merge & Close”PR merges; the issue closes; metrics and attribution land in the dashboard.
What Colony does
- The merger worker rebases the PR against the target branch
- Resolves trivial conflicts; surfaces non-trivial ones for human resolution
- Merges, closes the issue, and writes the cost / attribution / audit record to the Pipeline Store
What humans do
| Role | Activity |
|---|---|
| Author | — |
| Reviewer | Final approval if the PR was on the human-review path. |
| Operator | — |
| Sponsor | Reviews throughput, cost-per-issue, and agent attribution rollups on the dashboard. |
What can go wrong
Non-trivial merge conflict
The merger flags the PR; the Operator (or a delegated developer) resolves the conflict and re-runs. See Operator → recover.
Freeze window in effect
The merger respects branch-freeze configuration. PRs queue until the freeze lifts. See Team Patterns → freeze windows.
Where to go deeper
- Sponsor role — what the rollup metrics mean
- Team Patterns — freeze windows, multi-team merges
Now what?
Section titled “Now what?”If you’ll be the Author on the rollout, read the Author role.
If you’re sponsoring or evaluating Colony, read the Sponsor role for the staffing and budget framing.
If you’ll be the Reviewer on the rollout, read the Reviewer role.
If you’ll be operating the colony, read the Operator role.