Agents

Colony separates coordination from execution. The Mayor decides what work should exist and keeps pipeline records moving; Workers claim queued tasks and run executors.

Mayor

The Mayor is the long-running coordinator for a tenant’s pipeline. Depending on the deployment and enabled features, it:

• ingests eligible issues and assigns their workflow ID and version
• applies workflow transitions and enqueues the executor configured for a state
• checks declared and detected dependencies before work proceeds
• reacts to clarification replies, pull-request events, check results, and slash commands
• reconciles pipeline records with code-host state and retries recoverable work
• schedules self-improvement seeds and strategy runs when those subsystems are enabled

The Mayor does not hand a task directly to a particular free Worker. It writes a task to the shared queue; an eligible Worker claims it.

Workers

A Worker is a task-execution process, commonly deployed in a container. It polls the task queue, claims one compatible task, invokes the registered executor, reports the result, and then returns to polling. Each Worker handles one claimed task at a time, while multiple Workers allow independent tasks to run concurrently.

Workers are not permanently specialized as “analyzer Workers” or “reviewer Workers.” A standard Worker registers the built-in executors and can run different task types over its lifetime. Eligibility still matters: repository assignment, task requirements, configuration, and installed plugins can restrict which Worker may claim a task.

The execution engine for each agent role is configurable. By default, Workers invoke the Claude Code CLI for all roles. Individual roles can be switched to the OpenAI Codex CLI by setting agents.<role>.engine: codex in the pipeline configuration — for example, to use an OpenAI model such as codex-1 or o4-mini for development tasks. When Codex is active for a role, the codex top-level config section sets the CLI path, invocation timeouts, and per-role model IDs. Engine selection takes effect after a Worker redeploy.

Work Types

The five headline executors describe the main issue-to-PR path:

Task type	What it does
Analyze	Interprets the issue and repository, estimates complexity, asks for clarification, sends epic work to planning, or prepares ordinary work for development.
Plan	Decomposes epic-scale work into child issues and records their relationships.
Develop	Works on a branch, implements the issue, performs self-validation, and creates or updates a pull request.
Review	Runs configured deterministic checks and an LLM review, then approves, requests changes, or surfaces work that needs attention.
Merge	Attempts to merge an approved pull request when automatic merging is enabled and provider rules allow it.

They are not the complete task catalog. The standard runtime also includes tasks for waiting-parent sweeps, CI repair, retrospection, external PR review, and code-map scanning. Plugins and custom workflows can add more executors.

States enqueue tasks

In the built-in workflow, entering an active state invokes its configured executor. For example:

• analyzing enqueues Analyze
• planning enqueues Plan
• ready-for-dev and changes-requested enqueue Develop
• in-review enqueues Review
• merge-pending enqueues Merge
• waiting-for-subtasks enqueues Sweep
• entering terminal done runs the Retrospect hook

This mapping belongs to the workflow definition, not to the state names themselves. A custom workflow can attach different executors or hooks.

Going deeper

• The Workflow — the built-in lifecycle and its branches
• Pipeline States — states and transitions in the built-in workflow
• Operator — configuration, observation, and recovery