Strategy & Self-Improvement Tracks

Related concepts

• Strategy — Charters, snapshots, and the weekly strategize cycle

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 (goals + risk envelope), Colony collects pipeline signals, runs a single LLM call once a week, and proposes a snapshot that you approve from the dashboard.

---

Concepts

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 for fair-share seeding under the max_open_issues cap — tracks are seeded proportional to weight (0 treated as 1 for scheduling)
active_version	number	Which prompt version is currently active

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 (deprecated) colony tracks CLI command.

Charter

The charter defines the operator’s strategic intent for a repository. It has two parts:

Goals — a free-text description of what you want Colony to accomplish (e.g. “Reduce CI flakiness, increase test coverage on the auth layer, and fix the backlog of small bugs in the payments module”).

Risk envelope — constraints on what the Strategist may propose autonomously:

Field	Type	Valid values	Description
max_auto_size	string	small, medium, large, epic	Largest issue size the Strategist may enqueue without escalation
prefer	string[]	any	Work types the Strategist should favour (e.g. ["test coverage", "small bugs"])
avoid	string[]	any	Work types the Strategist should avoid (e.g. ["breaking changes"])
escalate_when	string[]	any	Conditions that require human review (e.g. ["block rate above 20%"])

max_auto_size is a hard gate enforced at snapshot approval time, not during the LLM proposal cycle. If the Strategist proposes work larger than the envelope allows, approval fails with STRATEGY_APPLY_FAILED.

A repository must have an active charter before the Strategist can run.

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

Snapshots move through a lifecycle: proposed → active (previous active becomes superseded), or proposed → rejected (terminal, with an optional reason and audit attribution). An intermediate approved status may appear briefly between operator approval and the apply step completing. A rejected snapshot is a permanent, auditable record of an operator decision; it cannot be re-proposed or transitioned.

---

The Strategize Cycle

When the Strategist runs (either on the configured schedule or triggered manually), it executes the following sequence:

1. Load active charter. If no charter exists, the cycle fails immediately with “no active charter”.
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 charter goals, risk envelope (as a hint to the LLM), 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.

The cycle runs weekly by default. On startup, Colony reads the last-persisted next_due_at from the database: if the time has already passed (or no prior run exists), a catch-up cycle fires promptly rather than waiting a full week. This means restarts do not reset or delay the schedule. You can also trigger a cycle on demand with colony strategize.

Cadence Configuration

Add a strategy block to your config to change how often the strategize cycle fires:

# Default: weekly interval (604800000 ms = 7 days)
strategy:
  cadence:
    kind: interval
    interval_ms: 604800000

# Alternatively, use a cron expression (always evaluated in UTC):
strategy:
  cadence:
    kind: cron
    expr: '0 0 * * 0'   # Every Sunday at midnight UTC

Cadence changes are read at startup. To apply a new cadence, restart the sprint-master after updating the config.

---

Getting Started

1. Create a charter

Prepare a charter file (charter.yaml):

goals: |
  Reduce the backlog of small bugs in the payments module.
  Increase test coverage for the auth layer.
  Avoid breaking changes — focus on incremental improvements.

envelope:
  max_auto_size: medium
  prefer:
    - small bugs
    - test coverage
  avoid:
    - breaking changes
    - large refactors
  escalate_when:
    - block rate above 20%
    - cost per issue exceeds $10

Apply it:

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

Optional: 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/repo

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

2. Wait for a snapshot (or trigger one manually)

Colony runs the strategize cycle weekly. To trigger one immediately:

colony strategize -r owner/repo

On success:

Strategize succeeded: proposed snapshot version 1

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

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

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 proposed track size exceeds max_auto_size, or the snapshot’s parent version no longer matches the active snapshot), the dashboard shows the error from STRATEGY_APPLY_FAILED (HTTP 422). In that case, trigger a fresh colony strategize -r owner/repo cycle to produce a new proposal that reflects the current state.

---

CLI Reference

colony strategize

Run one strategize cycle on demand and print the proposed snapshot version.

colony strategize -r owner/repo [-c colony.config.yaml]

Option	Required	Description
-r, --repo <owner/repo>	Yes	Target repository
-c, --config <path>	No	Path to colony.config.yaml

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 string and an envelope object. See the charter file format below.

colony strategy charter show

Print the active charter for a repository.

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 tracks (deprecated)

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. Use the dashboard Tracks tab for Postgres-backed track management instead.

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

goals: |
  Free-text description of your strategic goals.
  Multiple lines are fine.

envelope:
  max_auto_size: small    # one of: small, medium, large, epic
  prefer:
    - small bugs           # one string per line when using the dashboard
    - test coverage
  avoid:
    - breaking changes
  escalate_when:
    - block rate above 20%

Valid max_auto_size values: small, medium, large, epic. These correspond to the same size taxonomy used by the analyzer and planner.

All three array fields (prefer, avoid, escalate_when) are required but may be empty ([]).

---

Dashboard Entry Points

Tab	What it shows
Strategy	Snapshot list (proposed + active by default) with portfolio diff and Approve button
Charter	Form to create or update the active charter (goals, max_auto_size, prefer/avoid/escalate_when)
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

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

Security note: The three mutating endpoints (POST .../approve, POST .../reject, and PUT .../charter) 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.

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 with an optional reason
GET	/api/strategy/:owner/:repo/charter	Get the active charter
PUT	/api/strategy/:owner/:repo/charter	Create or replace the charter

The list endpoint returns only proposed and active snapshots by default. Pass ?status=superseded 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.