Core Concepts

Colony is organized around a small set of first-class concepts. Understanding them gives you a complete mental model for how work flows from a raw issue to a merged pull request — and how to configure Colony to match your team.

Organizational Structure

Tenant

A tenant is Colony’s top-level organizational unit. It is both a security boundary and a configuration boundary: every resource inside a tenant — repositories, workers, API keys, GitHub access — is shared by default across everything within that tenant.

Because repositories inside a tenant implicitly trust each other, Colony can coordinate work across multi-repo projects without per-repo permission negotiation. If your programs span multiple codebases and share resources, a single tenant is the right model. If you need strict isolation between independent groups, use separate tenants.

Repository

A repository (repo) is a codebase hosted in a version control system — GitHub or Azure DevOps today. Each repo belongs to exactly one tenant. The repo is Colony’s source of truth (it reads configuration, file structure, and history from it) and the target of its work (Colony writes code, opens pull requests, and merges changes back into it).

The Pipeline

Pipeline

A pipeline is Colony’s model of your development process. It drives issues through a deterministic state machine — from New, when Colony first ingests an issue, to Done, when the pull request is merged. Each tenant has exactly one pipeline.

The pipeline is opinionated at the state-machine level (Colony defines what states exist and which transitions are valid) but configurable at the behavior level (you control work allocation, required checks, and when human review is required).

Pipeline Store

The Pipeline Store is the per-tenant data layer that backs every pipeline. It is the authoritative record of all issues, their current states, work history, agent transcripts, cost events, and audit logs. GitHub labels reflect Pipeline Store state; they do not drive it.

States

Every issue is in exactly one state at any given time. The state determines what work needs to happen next and which type of agent will claim that work.

The happy-path progression through the pipeline:

stateDiagram-v2
    direction LR

    unlabeled --> new
    new --> analyzing
    analyzing --> ready_for_dev
    ready_for_dev --> in_development
    in_development --> in_review
    in_review --> merge_pending : auto-approved
    in_review --> human_review_ready : needs human
    merge_pending --> done
    human_review_ready --> done

State identifiers above use underscores (a Mermaid requirement); the actual GitHub labels use hyphens — for example, colony:ready-for-dev, colony:in-development. The full state machine — including all 15 states, backward loops for review cycles, dependency races, and recovery paths — is covered in the Pipeline States reference.

Labels and Tags

Colony projects the current pipeline state of each issue into your version control system as a label or tag (for example, colony:in-development in GitHub). This projection is one-way: changing or removing a label in GitHub does not change Colony’s behavior. The labels are a convenience for anyone inspecting pipeline status without logging in to Colony.

Issues

In Colony, an issue is a discrete piece of work — called an issue in GitHub, a work item in Azure DevOps, or a ticket in other systems. Issues are Colony’s primary input: they describe what needs to be done, and Colony’s pipeline drives them to completion autonomously.

The quality of an issue directly affects the reliability of Colony’s output. A well-defined issue includes:

• Context — why the work is needed and what problem it solves
• Requirements — specific, measurable outcomes expected from the implementation
• Acceptance criteria — the conditions under which the work is considered complete
• Test criteria — how correctness should be verified
• File references — relevant files, modules, or APIs within the repository

As with human-powered development, the better you describe an issue the more predictable and reliable the result. See Writing for Colony for guidance on structuring issues Colony can act on.

Agents and Work

Sprint Master

The Sprint Master is the mayor of your colony — the central conductor of the pipeline, on duty around the clock. It runs continuously, monitoring every issue across all repositories in the tenant. Its responsibilities:

• Ingesting newly created issues and enqueuing analysis tasks
• Delegating available work to free workers
• Managing cross-issue dependencies so work proceeds in the right order and avoids conflicts
• Running recovery protocols when work encounters errors, timeouts, or unexpected states

There is one Sprint Master per tenant.

Workers

A worker is an individual unit of work capacity. Technically, a worker is a container running a Colony agent process. Workers listen for tasks enqueued by the Sprint Master, claim one task at a time, execute the work autonomously, and report the result back to the Pipeline Store.

Worker pool size controls how many issues can be actively worked in parallel. Workers handle all task types — a single worker may analyze an issue in one task and develop a different issue in the next.

If the Sprint Master is the mayor, workers are the colony’s labor force — interchangeable, parallelizable, each handling one task at a time before returning to the queue.

Work Types

Workers don’t all do the same job. Each task type calls for a specialist — the colony’s analyst, planner, builder, inspector, and integrator — though any worker can play any role on demand:

Work type	When it runs
Analyze	An analyzer agent triages the issue: estimates complexity, produces an implementation plan, and transitions the issue to ready-for-dev or flags it as needing clarification.
Plan	A planner agent decomposes an epic-scale issue into smaller, actionable subtasks.
Develop	A developer agent implements the issue: writes code, runs configured checks, and opens a pull request.
Review	A reviewer agent inspects the pull request: runs deterministic checks, performs an LLM review, and either approves or requests changes.
Merge	A merger agent rebases and merges an approved pull request into the target branch.

The Humans

Everything above describes what the colony does. The pages that follow describe what you do with it.

Colony work is staffed by four roles. Activity-based, not title-aligned — a single person can wear multiple hats, and on a small team one person may wear all four. The roles are:

• Author — files issues, defines acceptance criteria, validates the result. Typically PMs, product owners, or tech leads briefing work for their teams.
• Reviewer — judges Colony’s pull requests for architectural fit and intent. Typically senior ICs, tech leads, or anyone who’d review a colleague’s PR today.
• Operator — configures the colony, allocates worker capacity, intervenes when work stalls. Typically platform engineers, tech leads, or the person who owns the deployment.
• Sponsor — charters the rollout, sets risk envelopes, tracks throughput and cost. Typically engineering managers, directors, or whoever owns the budget.

If you came here to find out what Colony is, you have. To see how these roles engage with the colony in practice, read The Workflow next.