Strategy & Self-Improvement Tracks
Strategy & Self-Improvement Tracks
Section titled “Strategy & Self-Improvement Tracks”Colony’s Strategist subsystem lets you define high-level goals for a repository and delegate the tactical week-by-week work allocation to an LLM. You set a charter (ordered goals plus free-text guidance), grant the repository a separate autonomy ceiling, Colony collects pipeline signals, runs a single LLM call once a week, and proposes a snapshot that you approve from the dashboard.
Concepts
Section titled “Concepts”Tracks
Section titled “Tracks”A track is a named category of self-improvement work. Each track describes:
| Field | Type | Description |
|---|---|---|
name | string | Track identifier (e.g. code-quality, test-coverage) |
label | string | GitHub label applied to issues seeded from this track |
enabled | boolean | Whether the track is active |
cadence_kind | cooldown|cron | How the track schedules new issues |
cooldown_minutes | number | Minutes to wait between seeds (when cadence_kind is cooldown) |
cron_expr | string (optional) | Cron expression (when cadence_kind is cron) |
weight | number | Relative weight within the track’s pool. Must be ≥ 1 on an enabled track. Sets the track’s share and slots; see Seeding: pools, shares and menus |
owner | operator|strategy | Which capacity pool the track belongs to. Set at insert and never changed. The CLI, YAML and API create operator tracks; strategy apply inserts strategy tracks with the label <prefix>:strategy-<name>, strategy.default_cooldown_minutes and strategy.default_selection_mode |
selection_mode | human|auto:first|auto:preferred | Who picks from the candidate menu. Default human. Settable on track create and update (API and dashboard). It is operator authority: a snapshot cannot set it, and a governed track changes only through a portfolio version. See Candidate selection |
active_version | number | Which prompt version is currently active |
An enabled track needs weight ≥ 1 (and, if it has a proposal, at least one slate entry). To idle a track, pause it (disable it) rather than setting its weight to 0.
Each track has one or more prompt versions. A prompt version contains:
seed_title— issue title templateseed_body— issue body templateinstructions— agent instructions for implementing the work
Tracks and their prompts are stored in Postgres and managed through the dashboard Tracks tab or the monitor tracks API (POST /api/tracks and /api/tracks/:owner/:repo/:name/*, see API Reference); the MCP colony_tracks tool can list tracks but not edit them. The deprecated colony tracks CLI does not manage them: it writes to a file store that is imported into Postgres only once (when Postgres has no tracks for the repo) and is otherwise ignored.
Charter (statement)
Section titled “Charter (statement)”The charter is the operator’s statement of strategic intent for a repository. It has two parts:
- Goals. An ordered list of
{ id, statement, done_when? }. Array order is priority. The system assigns eachidin the formg<N>, where N is one more than the highest N used in any version of the repository’s charter. An id is kept when a goal is edited, and is never reused: removing a goal ends its history, and a goal added later gets a new id.done_whenis an optional completion criterion. - Guidance. Free text on what to favour and what to avoid. The Strategist reads it as prose, and it is never assessed against.
A charter with zero goals is valid as long as it has guidance. A charter with neither is rejected (EMPTY_CHARTER). Existing charters moved to this shape with their old text as guidance and no goals. A charter carries no permissions and each save creates a new version. Saving carries over any part you leave out: send only guidance and the goals (with their ids) stay.
A repository must have an active charter before the Strategist can run.
Autonomy grant
Section titled “Autonomy grant”The autonomy grant is what the Strategist is allowed to do on its own. It is stored separately from the charter, as repo_autonomy, with one grant per repository:
| Field | Valid values | Description |
|---|---|---|
max_auto_size | small, medium, large, epic | Largest issue size a snapshot may contain |
max_auto_select_size | none, small, medium, large, epic | Enforced at selection: largest candidate size Colony may auto-select; none keeps every selection human |
max_auto_size is checked at proposal time (so the Strategist can repair) and enforced again when a snapshot is approved, against the grant in force at that moment. If the snapshot contains work larger than the grant allows, the snapshot is marked invalid with a GRANT_EXCEEDED violation (the monitor route returns 422). Narrowing the grant therefore binds the next approval, and widening it lets an already-proposed snapshot apply.
A repository with no grant uses the default: max_auto_size: small and max_auto_select_size: none. Changing the grant does not create a new charter version, and editing the charter does not change the grant.
Strategy Snapshot
Section titled “Strategy Snapshot”A snapshot is a point-in-time proposal for how tracks should be configured. The Strategist produces a new snapshot each week (or on demand). A snapshot contains:
| Field | Description |
|---|---|
intent | One-sentence strategic intent for this cycle |
rationale | Explanation of why the Strategist made these recommendations |
portfolio | Directives for existing tracks (adjust weight, cadence, prompt, or pause) |
creates | New tracks to create |
retires | Track names to retire |
Directive schema
Section titled “Directive schema”portfolio entries update existing strategy tracks; creates entries insert new ones. Both use the same directive shape:
| Field | Description |
|---|---|
name | Track name, matching ^[a-z0-9][a-z0-9-]{0,47}$ |
weight | Integer 0–100. An active track needs weight ≥ 1 |
cadence | { kind: "cooldown", minutes } or { kind: "cron", expr }. expr is allowed only when kind is cron |
proposal | The menu: 1–10 slate entries, each a size and count, with no duplicate sizes. An active directive needs a non-empty slate. To idle a track, set it paused |
prompt | Structured prompt: { pin } (an existing version of that track) or { seed_title, seed_body, instructions }. Required on creates. { new: string } is removed |
serves | Charter goal ids the track serves (at least one on a proposal). Optional in the schema because operator edit and revert snapshots carry none |
rationale | Why this directive, citing at least one prefixed evidence item (for example scorecard:bug-fixes). Optional in the schema for the same reason |
Besides the directive lists, a Strategist proposal may carry two more keys. goal_assessments is one { goal_id, state, evidence } entry per charter goal, where state is met, partly, unmet or unknown and each evidence item starts with scorecard:, signal:, memory:, intel: or file: (a path relative to the checkout). no_change: true is a run outcome rather than a review item: it comes with assessments and empty portfolio, creates and retires. Assessments and no_change are not stored on the snapshot.
Every snapshot object is strict: an unknown key is a SCHEMA violation, not silently dropped. selection_mode is not a directive field (it is operator authority), so a directive that carries it fails with SCHEMA. Strategy-created tracks get strategy.default_selection_mode.
Prompt text is stored verbatim in the three prompt columns, with no markdown round-trip, so a seed_body containing ## headings survives intact.
Bounds (SNAPSHOT_BOUNDS)
Section titled “Bounds (SNAPSHOT_BOUNDS)”| Value | Bound |
|---|---|
| Track name | ^[a-z0-9][a-z0-9-]{0,47}$ |
| Weight | 0–100 |
| Menu count (per size) | 1–10, no duplicate sizes |
| Directives per list | At most 20 |
intent, rationale | At most 4,000 characters |
seed_title | At most 200 characters |
seed_body, instructions | At most 8,000 characters |
Validation codes
Section titled “Validation codes”One shared validator, validateSnapshot, runs at proposal time (the Strategist gets up to two repair turns, each with the exact code at path: message lines) and again inside the apply transaction against live state. It returns a list of violations, each { code, path, message }.
Rules are filtered by phase (proposal or apply, default apply) and author (strategist or operator, default operator). The goal-assessment, serves and file: rules run at proposal time only, because apply rebuilds the candidate from the stored snapshot fields, with no checkout and no assessments. DWELL runs in both phases but only for Strategist-authored snapshots; operator edit and revert snapshots are exempt.
| Code | Rule |
|---|---|
SCHEMA | Strict parse failed, including unknown keys |
GRANT_EXCEEDED | A menu size is above the repository grant’s max_auto_size |
OPERATOR_TRACK | A list names an operator-owned track |
UNKNOWN_TRACK | A portfolio or retires name is not an existing strategy track |
TRACK_EXISTS | A creates name already exists |
DUPLICATE_TRACK | A name appears twice, in one list or across lists |
INVALID_CRON | The cron expression does not parse (same parser the seeder uses) |
UNKNOWN_PIN | The pin is not a version of that track |
PROMPT_REQUIRED | A creates entry has no structured prompt |
PROMPT_INVALID | A prompt breaks its bounds |
OUT_OF_BOUNDS | A value is outside SNAPSHOT_BOUNDS |
INVALID_DIRECTIVE | An active directive has weight < 1 or an empty slate |
STALE | The snapshot’s parent is not the active snapshot |
CHARTER_CHANGED | The snapshot’s charter version is not the active charter |
GOAL_COVERAGE | A charter goal is not assessed exactly once (proposal, Strategist) |
UNKNOWN_GOAL | A goal_id in goal_assessments or serves is not a charter goal (proposal) |
EVIDENCE_MISSING | An assessment has no evidence, or an item lacks an allowed prefix (proposal) |
FILE_NOT_FOUND | A file: path is absolute, escapes the checkout with .., or does not exist (proposal) |
SERVES_REQUIRED | A portfolio or creates directive has no serves, or its rationale is empty or cites no prefixed evidence (proposal) |
MET_GOAL_TRACK | A directive serves only goals assessed met; retire the track instead (proposal) |
DWELL | A strategy track is retired or paused within 14 days of its creation or last status change, unless its last 3 outcomes were all no-work or cancelled (both phases, Strategist only) |
NO_CHANGE_DIRECTIVES | no_change: true with a non-empty portfolio, creates or retires (proposal) |
If the Strategist’s output still fails after the repair turns, the run fails and { violations, attempts } is stored on the run (strategy_runs.failure_detail) with a one-line failure_reason.
Snapshot lifecycle
Section titled “Snapshot lifecycle”Statuses: proposed, active, superseded, rejected, invalid. No path commits approved; the legacy value remains legal in the database but is never written.
- One
proposedrow per repository. A partial unique index enforces it. - Supersession. Inserting a new proposal supersedes the existing
proposedrow. A charter edit supersedes aproposedrow whose charter version is no longer active (status reason “charter vN replaced vM”), whoever wrote the charter: the sprint-master reconciles this each poll, and apply re-checks it asCHARTER_CHANGED. Activating a snapshot supersedes the previous active snapshot and every otherproposedrow.superseded_byrecords the replacing version; for a stale-parent or charter supersession it records the snapshot active at the time (null when there is none). - Atomic approve-and-apply. Approval is one transaction that locks the row (it must be
proposed), re-validates against live state, applies the directives, sets the snapshotactivewithapproved_by/approved_at, supersedes the previous active and other proposed rows, and recordsapplied_pool(the post-apply config and prompt pin of every strategy track). Approving a snapshot that is notproposedreturnsNOT_PROPOSED. - Failure outcomes.
STALEorCHARTER_CHANGED: the row becomessuperseded, withstatus_reason. Run a fresh cycle.- Any other violation: the row becomes
invalid, withstatus_reasonand theviolationslist. - Any other (transient) error: the transaction rolls back, no track is touched, and the row stays
proposedwithapply_errorandapply_error_atso it can be retried.
- Reject needs a non-empty reason and works only on a
proposedrow; it is terminal and auditable. - Approve with edits. An operator can approve with edited
intent,rationale,portfolio,createsorretires. In one transaction Colony inserts an operator-authored snapshot with the same parent, supersedes the original, validates and applies it. Invalid edits returnINVALIDand write nothing. - Generate.
generaterecords a durable request on the repository (it needs an active charter, elseNO_ACTIVE_CHARTER). The sprint-master’s per-repo poll claims it and runs a cycle, so a restart does not lose it.
Snapshot rows expose the lifecycle columns superseded_by, status_reason, violations, apply_error, apply_error_at and applied_pool, alongside the existing approved_by, rejected_by and reject_reason. A rejected snapshot cannot be re-proposed or transitioned.
Migration cleanup
Section titled “Migration cleanup”The migration that introduced this lifecycle (188) cleans up the backlog once, idempotently:
- A
proposedrow whose parent is not the active snapshot becomessupersededby the active version. - Of the rest, all but the newest
proposedrow per repository becomesupersededby the newest. - Every
approvedrow becomesinvalidwith the reason “approved but never applied; cleaned up by migration”.
Upgrade note: the surviving
proposedrow is not re-validated by the migration. A proposal written before this release that usesprompt: { new }or carries a directiveselection_modefails the strict schema when approved and becomesinvalidwith aSCHEMAviolation, and nothing regenerates it. After upgrading, inspect each repository’s pending proposal; if it uses either field, reject it (or approve it with editedportfolio/creates) and rungeneratefor a fresh one.
Approval mode
Section titled “Approval mode”strategy.approval is human (default) or auto; see configuration. Under auto, a valid proposal is approved and applied immediately as actor auto and a strategy_snapshot event (auto_applied) is written. An invalid proposal applies nothing. A transient failure leaves the row proposed for a human. The grant (max_auto_size) still binds.
Revert
Section titled “Revert”revert builds an operator-authored snapshot that restores the parent snapshot’s applied_pool: strategy-controlled fields and prompt pins, and it retires strategy tracks created since. It applies through the same transaction and writes a reverted event. It refuses with NO_REVERT_TARGET when the parent has no applied_pool, which is true of any snapshot applied before this lifecycle shipped, and with NO_ACTIVE_CHARTER when the repository has no active charter. Revert works in both approval modes. A pooled track that cannot run as an active directive (empty menu, weight 0, or cron without an expression) is restored paused, a pin is restored only if that prompt version still exists, and tracks that are disabled both in the pool and now are left out. A legacy weight above 100 is clamped to 100. Each list holds at most 20 entries: restores that enable or disable a track come first, then tracks enabled in the pool; tracks past the cap keep their current config, and the revert result and the reverted event list them in truncated_tracks. A transient revert failure is recorded as apply_error (prefixed revert failed:) on the active snapshot.
Strategy tracks are never governed
Section titled “Strategy tracks are never governed”Strategy applies write track rows directly and never touch portfolio versions. A strategy-owned track can never be governed: setTrackGovernance(…, 'governed') refuses it, a portfolio version that names it is refused, and a database CHECK on si_tracks enforces it. Operator tracks can still be governed through portfolio versions, which strategy apply does not modify.
Seeding: pools, shares and menus
Section titled “Seeding: pools, shares and menus”Colony seeds new self-improvement issues from enabled tracks while the repository is below its self_improvement.max_open_issues cap (M, default 5).
Tracks are split by owner into two pools:
- Strategy pool:
S = round(capacity_share × M), wherecapacity_shareisstrategy.capacity_share(default0.5, so 5 × 0.5 → 3).Sis non-zero only when the repository has an active charter and at least one enabled strategy track; otherwise it is 0, and no strategy track seeds. - Clamp: when both pools have an enabled track and
M ≥ 2,Sis clamped to[1, M − 1], so neither pool takes every slot. WhenM = 1the slot goes to the operator pool unless it has no enabled track. - Operator pool:
M − S. - Total cap: a pool seeds only while the total open self-improvement issues across both pools is below
M, as well as under its own capacity. - No lending between pools. A pool never uses capacity the other leaves idle.
A pool’s open count is its si_issues rows with completed_at IS NULL, whether or not the track is still enabled.
Shares and slots
Section titled “Shares and slots”Within a pool, over its enabled tracks:
share = weight / Σweightslots = max(1, round(share × pool capacity)). A track never has more open issues than its slots.
Weights {6, 1, 1} at pool capacity 4 give slots {3, 1, 1}.
Which track seeds next
Section titled “Which track seeds next”- Under-share first. A track is under-share when it has no seeds in the last 30 days across the pool, or its share of the pool’s 30-day seeds is below its
share. The eligible under-share track with the lowestseeds / weightseeds first (ties by name). - Over-share lending. An over-share track seeds only when no under-share track is eligible, and either no under-share track has a free slot (whatever blocks it: cooldown, cron or menu phase), or a pool slot has been free for more than 30 minutes (
SI_SLOT_LEND_AFTER_MINUTES). A slot counts as free for that long when the pool’s k-th most recent SI completion is more than 30 minutes old, where k is the pool’s number of free slots.
Eligibility and pacing
Section titled “Eligibility and pacing”A track is eligible when it is enabled, has fewer open issues than its slots, has no issue in the menu phase, and its pacing floor has passed. The floor is measured from max(last seed, last completion): for cooldown tracks at least cooldown_minutes ago, for cron tracks before the previous fire. With one slot this is the classic one-open-issue-per-track rule.
Menu phase
Section titled “Menu phase”An issue is in the menu phase from seeding until the first human or auto selection writes selected_at. That covers analysis, roll-again and the candidates menu. Only one issue per track may be in the menu phase, so a track shows one menu at a time. After selection the issue is a pick: it keeps holding a slot until it completes, but the track can seed again, subject to pacing. The sub-item menu after a large pick is not a menu phase.
Legacy selected rows with a NULL selected_at (selected before the column existed, or whose provenance write failed) count as menu phase until they complete, so the track behaves like the old one-open rule.
The DO-NOT-OVERLAP prompt section
Section titled “The DO-NOT-OVERLAP prompt section”The analysis prompt for an SI issue includes ## In-Flight and Recent SI Work (DO NOT OVERLAP), after the “Previously Offered Options” section. It lists:
- every open pick in the repository, from both pools, excluding the issue being analysed, marked
(in flight); - this track’s non-cancelled picks completed in the last 14 days, newest first and at most 25, marked
(landed YYYY-MM-DD).
Each entry is the issue title and the first non-empty body line (up to 200 characters). The section is omitted when empty. File-level clashes are still caught by the existing file-overlap check at selection.
Candidate selection
Section titled “Candidate selection”When the analyzer posts a menu of candidates for a track item, the item waits in needs-clarification for a choice. Normally a human picks. A track can instead let Colony pick, within a ceiling that the repository grant sets.
The resolution rule
Section titled “The resolution rule”The effective mode is the narrower of the track’s mode and the repository ceiling:
max_auto_select_size: nonemakes the effective modehuman, whatever the track says. This is the default for every repository without a grant, and dials the whole repository back to human in one act.- Otherwise the track’s effective
selection_modeapplies. - In either auto mode, a candidate qualifies only if its size is at most
max_auto_select_size, in the ordersmall < medium < large < epic.
A track’s setting can never widen the ceiling.
The two auto modes
Section titled “The two auto modes”-
auto:firstpicks the first candidate in menu order that is within the ceiling. -
auto:preferredpicks the first candidate within the ceiling that carries the low-risk value on all six risk dimensions:Dimension Low-risk value reversibilityreversibleblast_radiuslocalizedormoderatecontract_impactinternal-onlydata_impactno-data-changedependency_impactnoneverifiabilitywell-verifiableA missing dimension disqualifies the candidate.
change_kindis ignored.
When it runs
Section titled “When it runs”Auto-selection runs only while the item waits in needs-clarification with no checked box and no authorized reply, so a human choice always wins. Values are read at decision time, not cached: narrowing the grant, or activating a portfolio version that sets the track to human, binds the next pass, even for an item seeded earlier. The pick goes through the same path as a human selection, so size routing is unchanged.
The fallback notice
Section titled “The fallback notice”For an auto:* track that cannot pick, Colony posts one notice per candidates comment, then keeps waiting for a human choice. The notice leads with the outcome, states the track’s rule in words (naming the mode and the repository’s max_auto_select_size), and explains why nothing was chosen. For over-ceiling and no-qualifying-candidate it lists every option with its size and why it wasn’t picked: above the limit, the failing risk checks in plain words, or both. The other reasons get one plain sentence each. It ends with a “What you can do” line, and carries the reason code in an HTML marker, <!-- colony:auto-select-fallback:<reason> -->.
| Reason | Meaning |
|---|---|
grant-none | The repository’s max_auto_select_size is none |
over-ceiling | Every candidate is larger than the ceiling |
no-qualifying-candidate | No candidate within the ceiling is low-risk (auto:preferred) |
no-candidates-record | The candidates record for the round is missing |
Risk checks read as: hard to reverse, wide impact, changes a public contract, changes stored data, adds or changes a dependency, hard to verify, and risk not assessed (a check is missing).
Example, with auto:preferred and a small limit:
Colony · Mayor — Colony didn’t choose an option, so this one is yours.
This track picks automatically only when an option is small or smaller and low-risk on every check (
auto:preferred). None of these qualifies:
Option Size Why it wasn’t picked 1. Bind docker-compose ports to localhost small Changes a public contract 2. Make host-side .env loading consistent medium Above the small limit 3. Publish prebuilt container images large Above the small limit; wide impact, changes a public contract, hard to verify What you can do: tick an option above or reply with its number, tick 🔄 None — roll again for new options, or change Max auto select size or the track’s selection mode in the repository’s autonomy and track settings.
A human track posts nothing.
Selecting by colony_act pick
Section titled “Selecting by colony_act pick”An operator or API client can answer a candidate menu without the code host:
colony_act pick choice=option:<n> request_id=<id> selects the n-th candidate (1-based, as the menu shows it), and choice=roll-again rolls again. actor and round_id are optional; a round_id that is not the open round is refused stale_round. The valid ids are option:1 … option:<k> and roll-again; anything else is refused unknown_choice with the valid ids listed, and an item with no open menu is refused no_menu.
A pick runs the same selection (or roll-again) body as a tick and takes the same first-wins round claim as a tick, a reply and auto-selection. Whichever acts first wins; a pick that loses is refused already_picked and changes nothing, and a tick, reply or auto-selection arriving after a pick does nothing. The actor is named in the selection comment (“selected by …”) and recorded as an operator status event with that actorId. A plain colony_act answer on a candidate round is refused (self_improvement_selection) and points to pick.
Provenance
Section titled “Provenance”Four columns on si_issues record how an item was selected:
selection_mode: the resolved mode at the moment of selection.selected_by:humanorauto.selected_at: when the selection was recorded.selection_portfolio_version_id: the active portfolio version that supplied the track’s mode;NULLfor independent tracks. It is distinct from the originationportfolio_version_id, because a version can be activated between seeding and selection.
Existing rows stay NULL.
Rollout note: this is a behaviour change for any repository that already stores
selection_modevalues. Values stored before this release start to apply. A track already set toauto:*, in a repository whose grant is notnone, auto-selects from the first sweep after the upgrade. Checkcolony autonomy show/GET /api/autonomy/:owner/:repoand the tracks list before upgrading.
The Strategize Cycle
Section titled “The Strategize Cycle”When the Strategist runs (on schedule, on a charter change, or on request), it executes the following sequence:
- Load active charter. Repos without an active charter are never scheduled.
- Load active snapshot. Used as context for what the current configuration looks like. On the first cycle, this is absent.
- Collect signals. In parallel: list all tracks, collect pipeline signals (repo intelligence, open findings by severity, pipeline outcomes — issues stalled in non-terminal state for >3 days by state, return-to-dev transitions in the last 30 days, and cycle-time/throughput for issues completed in the last 30 days — cost concentration, activity by area).
- Build prompt. Combines the charter goals, the grant’s
max_auto_size(described as enforced at apply time), the active snapshot, the track list, and the signals. - Single LLM call. One call with
maxTurns: 1. - Validate output. Parses the response and validates against
SnapshotProposalSchema. - Persist proposed snapshot. Writes a new snapshot with status
proposed.
Scheduling
Section titled “Scheduling”Sprint-master runs a scheduler (60 s tick) that only enqueues strategize tasks; a worker runs them. Sprint-master makes no strategy LLM call. A repository with no active charter gets no task and no run row.
Each run has one of three triggers:
| Trigger | Fires when |
|---|---|
schedule | A cron anchor (plus the repo’s stagger offset) has passed since the last scheduled run. |
generate | An operator requested a run: the sprint-master handle, MCP generate, or colony strategize. |
charter_change | The active charter version is newer than the latest run’s charter_version and has been unchanged for 10 minutes. |
Anchor and stagger. schedule runs follow a fixed UTC cron anchor, Mondays 03:00 UTC (0 3 * * 1) by default. The next due time comes from the anchor, never from when the previous run finished, so a slow run does not shift the schedule. Each repo gets an offset of hash(repo_id) mod stagger_window_minutes minutes (default 60) so repos do not all fire at once. next_due_at on the run record holds the next anchor plus offset.
Catch-up. After downtime, all missed anchors collapse into one run, fired at its staggered time, with missed_anchors set to the count.
Debounce. charter_change waits until the charter has been unchanged for 10 minutes, so several edits in a row produce one run.
Generate requests. Every source records a durable request (requestGenerate) and sends a colony_wake notification. The scheduler claims it on the next tick and enqueues a generate run. A request made while a run is already pending is absorbed by that run. generate works regardless of strategy.enabled.
strategy.enabled. Set globally or per repo (default true). false stops schedule and charter_change runs; generate still works. It hot-reloads.
Failures. The task and the pending run are inserted in one transaction. If that fails, a failed run with enqueue failed: … is written and the anchor is retried on the next tick. A task that ends failed or cancelled without a terminal run is closed as failed within one tick.
Run record. Each run carries trigger, scheduled_for, missed_anchors, next_due_at, charter_version, task_id, started_at, finished_at, model and outcome (pending, proposal, no_change or failed).
Cadence Configuration
Section titled “Cadence Configuration”Add a strategy block to your config to change the anchor. The cadence is read on every scheduler tick, so a change takes effect on the next tick without a restart. It is cron-only (5-field expression, evaluated in UTC):
strategy: cadence: kind: cron expr: '0 3 * * 1' # default: Mondays 03:00 UTC stagger_window_minutes: 60The interval cadence kind is no longer supported and is rejected by config validation. See configuration.md for the full strategy block.
Getting Started
Section titled “Getting Started”1. Create a charter
Section titled “1. Create a charter”Prepare a charter file (charter.yaml) with goals and guidance:
guidance: | Avoid breaking changes — focus on incremental improvements.goals: - statement: Reduce the backlog of small bugs in the payments module. done_when: No open payments bugs older than 30 days. - statement: Increase test coverage for the auth layer.Apply it:
colony strategy charter set -r owner/repo -f charter.yamlOptional: record the author:
colony strategy charter set -r owner/repo -f charter.yaml --author "alice"Inspect the active charter:
colony strategy charter show -r owner/repoYou can also create and edit the charter directly in the dashboard Charter tab without writing a file.
2. Set the autonomy grant
Section titled “2. Set the autonomy grant”Without a grant the repository uses small / none. Raise it to let the Strategist propose larger work:
colony autonomy set -r owner/repo --max-auto-size mediumcolony autonomy show -r owner/repoThe dashboard Charter tab has an Autonomy card for the same grant.
3. Wait for a snapshot (or trigger one manually)
Section titled “3. Wait for a snapshot (or trigger one manually)”Colony schedules a strategize run weekly by default (see Scheduling). To trigger one immediately:
colony strategize -r owner/repo --waitThe command only enqueues a generate request; a worker runs the strategist. Without --wait it prints the request time and returns:
Strategize requested at 2026-10-20T10:00:00.000ZWith --wait it polls every 5 seconds for the first generate run created at or after the request, then prints Strategize produced proposal v1 (exit 0), the no-change reason or goal-assessment summary (exit 0), or the failure reason (exit 1). --timeout <seconds> (default 1800) bounds the wait; on timeout it exits 1. A run already in flight when you request absorbs the request, so no new run appears and --wait times out by design.
On failure (no active charter):
Error: no active charter found for owner/repo. Create a charter before running strategize.colony strategize requires:
-r/--repo(required) — the target repo inowner/repoformat- A Postgres database configured (
database.urlin config orDATABASE_URLenv var) - An active charter for the repo
4. Review and approve in the dashboard
Section titled “4. Review and approve in the dashboard”Open the dashboard at http://localhost:9106 and go to the Strategy tab.
The tab shows:
- A list of proposed and active snapshots in the left panel
- The Strategy Detail panel on the right, showing the snapshot’s intent, rationale, and a diff of portfolio changes vs. the currently active snapshot
For a proposed snapshot, an Approve button appears. Clicking it:
- Calls
POST /api/strategy/:owner/:repo/snapshots/:version/approve - Applies the snapshot to tracks (creates new tracks, updates existing ones, retires removed ones)
- Transitions the snapshot to
active; the previous active snapshot becomessuperseded
If approval fails (e.g. a slate size exceeds max_auto_size at approval time, or the snapshot’s parent no longer matches the active snapshot), the dashboard shows the violation code (HTTP 422); see Snapshot lifecycle for the resulting status. For STALE or CHARTER_CHANGED, trigger a fresh colony strategize -r owner/repo cycle to produce a new proposal that reflects the current state.
CLI Reference
Section titled “CLI Reference”colony strategize
Section titled “colony strategize”Request a strategize run (processed by a worker). Enqueue-only: it records a generate request and wakes the scheduler; exit code is 1 when the repo has no active charter.
colony strategize -r owner/repo [--wait] [--timeout <seconds>] [-c colony.config.yaml]| Option | Required | Description |
|---|---|---|
-r, --repo <owner/repo> | Yes | Target repository |
-c, --config <path> | No | Path to colony.config.yaml |
--wait | No | Wait for the requested run; exit 0 on proposal/no change, 1 on failure or timeout |
--timeout <seconds> | No | Max seconds to wait with --wait (default: 1800) |
colony strategy charter set
Section titled “colony strategy charter set”Create a new charter version from a YAML or JSON file.
colony strategy charter set -r owner/repo -f charter.yaml [--author name] [-c config]| Option | Required | Description |
|---|---|---|
-r, --repo <owner/repo> | Yes | Target repository |
-f, --from <file> | Yes | Path to charter file (.yaml, .yml, or .json) |
--author <name> | No | Author recorded on the charter (default: operator) |
-c, --config <path> | No | Path to colony.config.yaml |
The file must be a YAML or JSON object with a goals list, a guidance string, or both. A legacy goals: "<string>" is treated as guidance. A file with an envelope key is rejected. Size caps belong to the autonomy grant (see colony autonomy set). See the charter file format below.
colony strategy charter show
Section titled “colony strategy charter show”Print the active charter for a repository: version, author and creation time, the numbered goals with their [id] and done when, then the guidance.
colony strategy charter show -r owner/repo [-c config]| Option | Required | Description |
|---|---|---|
-r, --repo <owner/repo> | Yes | Target repository |
-c, --config <path> | No | Path to colony.config.yaml |
colony autonomy show
Section titled “colony autonomy show”Print the repository autonomy grant and whether it is configured or the default.
colony autonomy show -r owner/repo [-c config]| Option | Required | Description |
|---|---|---|
-r, --repo <owner/repo> | Yes | Target repository |
-c, --config <path> | No | Path to colony.config.yaml |
colony autonomy set
Section titled “colony autonomy set”Set the repository autonomy grant.
colony autonomy set -r owner/repo --max-auto-size <size> [--max-auto-select-size <size|none>] [--author name] [-c config]| Option | Required | Description |
|---|---|---|
-r, --repo <owner/repo> | Yes | Target repository |
--max-auto-size <size> | Yes | small, medium, large, or epic |
--max-auto-select-size <size> | No | small, medium, large, epic, or none; omitted keeps the stored value |
--author <name> | No | Author recorded as updated_by (default: operator) |
-c, --config <path> | No | Path to colony.config.yaml |
colony tracks (deprecated)
Section titled “colony tracks (deprecated)”Deprecated. The
colony tracksCLI command manages file-backed tracks stored under.colony/in the target repo directory. It prints a deprecation notice before every action. Its edits are imported into Postgres only once, when Postgres has no tracks for the repo, and are otherwise ignored at runtime. Use the dashboard Tracks tab or the monitor tracks API (POST /api/tracksand/api/tracks/:owner/:repo/:name/*, see API Reference) instead; the MCPcolony_trackstool can list tracks but not edit them.
colony tracks list [-r owner/repo] [-a]colony tracks add <name> -l <label> --cooldown <minutes> [--prompt-file <path>] [-r owner/repo]colony tracks remove <name> [-r owner/repo]colony tracks enable <name> [-r owner/repo]colony tracks disable <name> [-r owner/repo]colony tracks set <name> [--cooldown <minutes>] [--label <label>] [-r owner/repo]colony tracks prompt <name> [--history] [--new] [--file <path>] [--notes <text>] [--activate <version>] [-r owner/repo]Charter File Format
Section titled “Charter File Format”guidance: | Free-text direction: what to favour, what to avoid.goals: - id: g1 # optional; only an id that exists in the active charter is accepted statement: Raise test coverage on the auth layer done_when: Line coverage above 80% - statement: Cut CI time # no id: the system assigns the next unused oneBoth keys are optional, but one is required. Omit goals to keep the active goals; omit guidance to keep the active guidance. Goals are replaced as a whole list: a goal left out of the list is removed, and its id is never reused. A goal with an id that is not in the active charter is rejected (UNKNOWN_GOAL_ID), as are duplicate ids (DUPLICATE_GOAL_ID), a blank statement (INVALID_GOAL), and a result with no goals and no guidance (EMPTY_CHARTER). A legacy goals: "<string>" is accepted as guidance.
The file holds goals and guidance only. A file with an envelope key is rejected; set size caps with colony autonomy set instead.
Dashboard Entry Points
Section titled “Dashboard Entry Points”| Tab | What it shows |
|---|---|
| Strategy | Snapshot list (proposed + active by default) with portfolio diff and Approve button |
| Charter | Two cards, saved separately: Charter (guidance; goals are kept) and Autonomy (max_auto_size, max_auto_select_size) |
| Tracks | Postgres-backed track management (create, enable/disable, manage prompt versions) |
The Strategy tab auto-selects the first proposed snapshot when the list loads. Snapshots auto-refresh every 30 seconds.
API Quick Reference
Section titled “API Quick Reference”All strategy endpoints require authentication. See API Reference for full request/response schemas.
Security note: The mutating endpoints (
POST .../approve,POST .../reject,PUT .../charter, andPUT /api/autonomy/:owner/:repo) fail closed — they return HTTP 503AUTH_NOT_CONFIGUREDwhenagents.monitor.authis not set in your config. They cannot be reached at all on a default install without an auth block. Approval, rejection, and authorship identity is bound to the configuredauth.usernameand cannot be overridden by the request body.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/strategy/:owner/:repo/snapshots | List proposed + active snapshots |
GET | /api/strategy/:owner/:repo/snapshots/:version | Get a single snapshot by version |
POST | /api/strategy/:owner/:repo/snapshots/:version/approve | Approve and apply a proposed snapshot |
POST | /api/strategy/:owner/:repo/snapshots/:version/reject | Reject a proposed snapshot (non-empty reason required) |
GET | /api/strategy/:owner/:repo/charter | Get the active charter (goals and guidance) |
PUT | /api/strategy/:owner/:repo/charter | Create a charter version (body: { goals?, guidance? }) |
GET | /api/autonomy/:owner/:repo | Get the autonomy grant ({ autonomy, configured }) |
PUT | /api/autonomy/:owner/:repo | Set the autonomy grant |
The list endpoint returns only proposed and active snapshots by default. Pass ?status=superseded, ?status=invalid or ?status=rejected to retrieve older snapshots.
Breaking change (SDK): The
review_byfield has been removed from theStrategySnapshottype. This field was alwaysnull(hardcoded, never populated) and has been dropped from the DB schema as well.
Breaking change (SDK):
StrategyCharterandStrategyCharterUpsertRequestno longer have anenvelopefield. NewRepoAutonomy,RepoAutonomyResponse,RepoAutonomyUpdateRequestandRepoAutonomyUpdateResponsetypes andgetRepoAutonomy/updateRepoAutonomyclient methods cover the grant.RiskEnvelopeis still exported but deprecated, and will be removed in a later release.
Migration note: charter split
Section titled “Migration note: charter split”preferandavoidnow live in the charter’s goals text.- The size caps moved to the repository autonomy grant, which was backfilled from the active charter. Repositories with no grant use
small/none. Manage the grant from the dashboard Autonomy card, withcolony autonomy set, or withPUT /api/autonomy/:owner/:repo. escalate_whenhas been removed. Its values no longer reach the Strategist and trigger nothing. They stay in the legacystrategy_charters.envelopecolumn, which Colony no longer reads or writes. Therepo_autonomymigration logs each repository that had them.- The charter API, CLI and SDK charter types no longer carry
envelope. APUT …/charterwith anenvelopekey returns 400. - The SDK still exports
RiskEnvelope, deprecated, for one release.