Skip to content

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.


A track is a named category of self-improvement work. Each track describes:

FieldTypeDescription
namestringTrack identifier (e.g. code-quality, test-coverage)
labelstringGitHub label applied to issues seeded from this track
enabledbooleanWhether the track is active
cadence_kindcooldown|cronHow the track schedules new issues
cooldown_minutesnumberMinutes to wait between seeds (when cadence_kind is cooldown)
cron_exprstring (optional)Cron expression (when cadence_kind is cron)
weightnumberRelative 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
owneroperator|strategyWhich 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_modehuman|auto:first|auto:preferredWho 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_versionnumberWhich 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 template
  • seed_body — issue body template
  • instructions — 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.

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 each id in the form g<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_when is 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.

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:

FieldValid valuesDescription
max_auto_sizesmall, medium, large, epicLargest issue size a snapshot may contain
max_auto_select_sizenone, small, medium, large, epicEnforced 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.

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:

FieldDescription
intentOne-sentence strategic intent for this cycle
rationaleExplanation of why the Strategist made these recommendations
portfolioDirectives for existing tracks (adjust weight, cadence, prompt, or pause)
createsNew tracks to create
retiresTrack names to retire

portfolio entries update existing strategy tracks; creates entries insert new ones. Both use the same directive shape:

FieldDescription
nameTrack name, matching ^[a-z0-9][a-z0-9-]{0,47}$
weightInteger 0–100. An active track needs weight ≥ 1
cadence{ kind: "cooldown", minutes } or { kind: "cron", expr }. expr is allowed only when kind is cron
proposalThe 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
promptStructured prompt: { pin } (an existing version of that track) or { seed_title, seed_body, instructions }. Required on creates. { new: string } is removed
servesCharter goal ids the track serves (at least one on a proposal). Optional in the schema because operator edit and revert snapshots carry none
rationaleWhy 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.

ValueBound
Track name^[a-z0-9][a-z0-9-]{0,47}$
Weight0–100
Menu count (per size)1–10, no duplicate sizes
Directives per listAt most 20
intent, rationaleAt most 4,000 characters
seed_titleAt most 200 characters
seed_body, instructionsAt most 8,000 characters

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.

CodeRule
SCHEMAStrict parse failed, including unknown keys
GRANT_EXCEEDEDA menu size is above the repository grant’s max_auto_size
OPERATOR_TRACKA list names an operator-owned track
UNKNOWN_TRACKA portfolio or retires name is not an existing strategy track
TRACK_EXISTSA creates name already exists
DUPLICATE_TRACKA name appears twice, in one list or across lists
INVALID_CRONThe cron expression does not parse (same parser the seeder uses)
UNKNOWN_PINThe pin is not a version of that track
PROMPT_REQUIREDA creates entry has no structured prompt
PROMPT_INVALIDA prompt breaks its bounds
OUT_OF_BOUNDSA value is outside SNAPSHOT_BOUNDS
INVALID_DIRECTIVEAn active directive has weight < 1 or an empty slate
STALEThe snapshot’s parent is not the active snapshot
CHARTER_CHANGEDThe snapshot’s charter version is not the active charter
GOAL_COVERAGEA charter goal is not assessed exactly once (proposal, Strategist)
UNKNOWN_GOALA goal_id in goal_assessments or serves is not a charter goal (proposal)
EVIDENCE_MISSINGAn assessment has no evidence, or an item lacks an allowed prefix (proposal)
FILE_NOT_FOUNDA file: path is absolute, escapes the checkout with .., or does not exist (proposal)
SERVES_REQUIREDA portfolio or creates directive has no serves, or its rationale is empty or cites no prefixed evidence (proposal)
MET_GOAL_TRACKA directive serves only goals assessed met; retire the track instead (proposal)
DWELLA 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_DIRECTIVESno_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.

Statuses: proposed, active, superseded, rejected, invalid. No path commits approved; the legacy value remains legal in the database but is never written.

  • One proposed row per repository. A partial unique index enforces it.
  • Supersession. Inserting a new proposal supersedes the existing proposed row. A charter edit supersedes a proposed row 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 as CHARTER_CHANGED. Activating a snapshot supersedes the previous active snapshot and every other proposed row. superseded_by records 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 snapshot active with approved_by/approved_at, supersedes the previous active and other proposed rows, and records applied_pool (the post-apply config and prompt pin of every strategy track). Approving a snapshot that is not proposed returns NOT_PROPOSED.
  • Failure outcomes.
    • STALE or CHARTER_CHANGED: the row becomes superseded, with status_reason. Run a fresh cycle.
    • Any other violation: the row becomes invalid, with status_reason and the violations list.
    • Any other (transient) error: the transaction rolls back, no track is touched, and the row stays proposed with apply_error and apply_error_at so it can be retried.
  • Reject needs a non-empty reason and works only on a proposed row; it is terminal and auditable.
  • Approve with edits. An operator can approve with edited intent, rationale, portfolio, creates or retires. In one transaction Colony inserts an operator-authored snapshot with the same parent, supersedes the original, validates and applies it. Invalid edits return INVALID and write nothing.
  • Generate. generate records a durable request on the repository (it needs an active charter, else NO_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.

The migration that introduced this lifecycle (188) cleans up the backlog once, idempotently:

  1. A proposed row whose parent is not the active snapshot becomes superseded by the active version.
  2. Of the rest, all but the newest proposed row per repository become superseded by the newest.
  3. Every approved row becomes invalid with the reason “approved but never applied; cleaned up by migration”.

Upgrade note: the surviving proposed row is not re-validated by the migration. A proposal written before this release that uses prompt: { new } or carries a directive selection_mode fails the strict schema when approved and becomes invalid with a SCHEMA violation, and nothing regenerates it. After upgrading, inspect each repository’s pending proposal; if it uses either field, reject it (or approve it with edited portfolio/creates) and run generate for a fresh one.

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

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), where capacity_share is strategy.capacity_share (default 0.5, so 5 × 0.5 → 3). S is 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, S is clamped to [1, M − 1], so neither pool takes every slot. When M = 1 the 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.

Within a pool, over its enabled tracks:

  • share = weight / Σweight
  • slots = 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}.

  1. 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 lowest seeds / weight seeds first (ties by name).
  2. 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.

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.

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


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 effective mode is the narrower of the track’s mode and the repository ceiling:

  • max_auto_select_size: none makes the effective mode human, 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_mode applies.
  • In either auto mode, a candidate qualifies only if its size is at most max_auto_select_size, in the order small < medium < large < epic.

A track’s setting can never widen the ceiling.

  • auto:first picks the first candidate in menu order that is within the ceiling.

  • auto:preferred picks the first candidate within the ceiling that carries the low-risk value on all six risk dimensions:

    DimensionLow-risk value
    reversibilityreversible
    blast_radiuslocalized or moderate
    contract_impactinternal-only
    data_impactno-data-change
    dependency_impactnone
    verifiabilitywell-verifiable

    A missing dimension disqualifies the candidate. change_kind is ignored.

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.

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

ReasonMeaning
grant-noneThe repository’s max_auto_select_size is none
over-ceilingEvery candidate is larger than the ceiling
no-qualifying-candidateNo candidate within the ceiling is low-risk (auto:preferred)
no-candidates-recordThe 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:

OptionSizeWhy it wasn’t picked
1. Bind docker-compose ports to localhostsmallChanges a public contract
2. Make host-side .env loading consistentmediumAbove the small limit
3. Publish prebuilt container imageslargeAbove 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.

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.

Four columns on si_issues record how an item was selected:

  • selection_mode: the resolved mode at the moment of selection.
  • selected_by: human or auto.
  • selected_at: when the selection was recorded.
  • selection_portfolio_version_id: the active portfolio version that supplied the track’s mode; NULL for independent tracks. It is distinct from the origination portfolio_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_mode values. Values stored before this release start to apply. A track already set to auto:*, in a repository whose grant is not none, auto-selects from the first sweep after the upgrade. Check colony autonomy show / GET /api/autonomy/:owner/:repo and the tracks list before upgrading.


When the Strategist runs (on schedule, on a charter change, or on request), it executes the following sequence:

  1. Load active charter. Repos without an active charter are never scheduled.
  2. Load active snapshot. Used as context for what the current configuration looks like. On the first cycle, this is absent.
  3. 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).
  4. 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.
  5. Single LLM call. One call with maxTurns: 1.
  6. Validate output. Parses the response and validates against SnapshotProposalSchema.
  7. Persist proposed snapshot. Writes a new snapshot with status proposed.

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:

TriggerFires when
scheduleA cron anchor (plus the repo’s stagger offset) has passed since the last scheduled run.
generateAn operator requested a run: the sprint-master handle, MCP generate, or colony strategize.
charter_changeThe 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).

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

The interval cadence kind is no longer supported and is rejected by config validation. See configuration.md for the full strategy block.


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:

Terminal window
colony strategy charter set -r owner/repo -f charter.yaml

Optional: record the author:

Terminal window
colony strategy charter set -r owner/repo -f charter.yaml --author "alice"

Inspect the active charter:

Terminal window
colony strategy charter show -r owner/repo

You can also create and edit the charter directly in the dashboard Charter tab without writing a file.

Without a grant the repository uses small / none. Raise it to let the Strategist propose larger work:

Terminal window
colony autonomy set -r owner/repo --max-auto-size medium
colony autonomy show -r owner/repo

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

Terminal window
colony strategize -r owner/repo --wait

The 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.000Z

With --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 in owner/repo format
  • A Postgres database configured (database.url in config or DATABASE_URL env var)
  • An active charter for the repo

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:

  1. Calls POST /api/strategy/:owner/:repo/snapshots/:version/approve
  2. Applies the snapshot to tracks (creates new tracks, updates existing ones, retires removed ones)
  3. Transitions the snapshot to active; the previous active snapshot becomes superseded

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.


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]
OptionRequiredDescription
-r, --repo <owner/repo>YesTarget repository
-c, --config <path>NoPath to colony.config.yaml
--waitNoWait for the requested run; exit 0 on proposal/no change, 1 on failure or timeout
--timeout <seconds>NoMax seconds to wait with --wait (default: 1800)

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]
OptionRequiredDescription
-r, --repo <owner/repo>YesTarget repository
-f, --from <file>YesPath to charter file (.yaml, .yml, or .json)
--author <name>NoAuthor recorded on the charter (default: operator)
-c, --config <path>NoPath 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.

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]
OptionRequiredDescription
-r, --repo <owner/repo>YesTarget repository
-c, --config <path>NoPath to colony.config.yaml

Print the repository autonomy grant and whether it is configured or the default.

colony autonomy show -r owner/repo [-c config]
OptionRequiredDescription
-r, --repo <owner/repo>YesTarget repository
-c, --config <path>NoPath to colony.config.yaml

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]
OptionRequiredDescription
-r, --repo <owner/repo>YesTarget repository
--max-auto-size <size>Yessmall, medium, large, or epic
--max-auto-select-size <size>Nosmall, medium, large, epic, or none; omitted keeps the stored value
--author <name>NoAuthor recorded as updated_by (default: operator)
-c, --config <path>NoPath to colony.config.yaml

Deprecated. The colony tracks CLI 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/tracks and /api/tracks/:owner/:repo/:name/*, see API Reference) instead; the MCP colony_tracks tool can list tracks but not edit them.

Terminal window
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]

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 one

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


TabWhat it shows
StrategySnapshot list (proposed + active by default) with portfolio diff and Approve button
CharterTwo cards, saved separately: Charter (guidance; goals are kept) and Autonomy (max_auto_size, max_auto_select_size)
TracksPostgres-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.


All strategy endpoints require authentication. See API Reference for full request/response schemas.

Security note: The mutating endpoints (POST .../approve, POST .../reject, PUT .../charter, and PUT /api/autonomy/:owner/:repo) fail closed — they return HTTP 503 AUTH_NOT_CONFIGURED when agents.monitor.auth is 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 configured auth.username and cannot be overridden by the request body.

MethodEndpointDescription
GET/api/strategy/:owner/:repo/snapshotsList proposed + active snapshots
GET/api/strategy/:owner/:repo/snapshots/:versionGet a single snapshot by version
POST/api/strategy/:owner/:repo/snapshots/:version/approveApprove and apply a proposed snapshot
POST/api/strategy/:owner/:repo/snapshots/:version/rejectReject a proposed snapshot (non-empty reason required)
GET/api/strategy/:owner/:repo/charterGet the active charter (goals and guidance)
PUT/api/strategy/:owner/:repo/charterCreate a charter version (body: { goals?, guidance? })
GET/api/autonomy/:owner/:repoGet the autonomy grant ({ autonomy, configured })
PUT/api/autonomy/:owner/:repoSet 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_by field has been removed from the StrategySnapshot type. This field was always null (hardcoded, never populated) and has been dropped from the DB schema as well.

Breaking change (SDK): StrategyCharter and StrategyCharterUpsertRequest no longer have an envelope field. New RepoAutonomy, RepoAutonomyResponse, RepoAutonomyUpdateRequest and RepoAutonomyUpdateResponse types and getRepoAutonomy / updateRepoAutonomy client methods cover the grant. RiskEnvelope is still exported but deprecated, and will be removed in a later release.


  • prefer and avoid now 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, with colony autonomy set, or with PUT /api/autonomy/:owner/:repo.
  • escalate_when has been removed. Its values no longer reach the Strategist and trigger nothing. They stay in the legacy strategy_charters.envelope column, which Colony no longer reads or writes. The repo_autonomy migration logs each repository that had them.
  • The charter API, CLI and SDK charter types no longer carry envelope. A PUT …/charter with an envelope key returns 400.
  • The SDK still exports RiskEnvelope, deprecated, for one release.