Skip to content

Self-Improvement Tracks

Self-improvement tracks are recurring jobs Colony runs against a repository on a schedule — analyzing the codebase and filing issues proactively. For a conceptual overview of track anatomy, cadence and cooldown semantics, and how proactive work is proposed, see Self-Improvement.

Each track has the following configurable properties:

FieldDescription
NameUnique identifier for the track within the repository. Used as a stable key (e.g., test-coverage, type-tightening). Immutable after creation.
LabelCode-host label applied to the seeded issue (for example, si:code-quality). Colony resolves tracks by this label. It is not a separate display title.
Cadence kindcooldown or cron. A cooldown track becomes eligible again a fixed interval after its latest seed or latest completion, whichever is later; a cron track runs on a fixed schedule given by a cron expression (cronExpr).
CooldownFor cooldown tracks, the minimum interval after the latest seed or completion before the track becomes eligible again. A track can also have only one open linked issue at a time. Stored as cooldown_minutes — for example, Daily = 1440 minutes. See Cooldown presets.
Owneroperator or strategy, shown as a plain label on each track. Operator tracks are yours. Strategy tracks are created, changed and retired by approved strategy versions.
WeightNumeric weight used by strategy portfolio decisions and ranking. On a strategy track it is the track’s share of the strategy pool. It does not move an issue ahead in the shared task queue.
PromptThe versioned prompt Colony runs against the repository. Consists of a seedTitle, seedBody, and instructions field (see Prompt authoring below).
EnabledToggle to allow or pause the track. Disabled tracks are visible in the dashboard but will not run.
Autonomy modehuman, auto:first or auto:preferred. It is never wider than the repository’s autonomy grant.

Track configuration lives on the Tracks tab, not in org-level settings.

  1. Open Autonomy, then the Tracks tab (/autonomy/tracks).
  2. Pick a repository with the repository control in the region’s header. The page scopes to it through the ?repo=owner/name query parameter, so /autonomy/tracks?repo=owner/name opens that repository directly.
  3. Click Add track to create a new track, or click Edit on an existing track.
  4. Set the code-host Label, choose the cadence (a Cooldown preset, or a cron expression), and toggle whether the track should start enabled.
  5. Save the track and then click Manage Prompts to author or update the track’s prompt.

The track Name is a stable key and cannot be changed after creation. Label, cadence, weight and enabled state can be edited at any time.

The cooldown dropdown offers seven presets. The value stored in cooldownMinutes on the track record is shown alongside each label:

LabelStored value
Instant1 minute
Hourly60 minutes
Every 2 hours120 minutes
Every 4 hours240 minutes
Every 8 hours480 minutes
Daily1,440 minutes
Weekly10,080 minutes

A track becomes eligible once cooldown_minutes have passed since its latest seed or completion. See Workers & SI Tracks in the Metrics reference for the cadence / cooldown and SI Tracks count definitions.

Dashboard edits apply immediately. The same operations are available through the API at /api/repos/{owner}/{repo}/si-tracks. self_improvement.tracks entries in colony.config.yaml are deprecated and ignored at runtime, so manage tracks in the dashboard or via the API, and run colony config migrate to remove stale entries.

Each track’s active prompt has three fields:

FieldPurpose
Seed titleThe GitHub issue title Colony files when the track produces a candidate, used exactly as written.
Seed bodyThe GitHub issue body, used as written apart from any attribution footer. Should describe the work and acceptance criteria clearly enough for the pipeline’s analyzer to plan against.
InstructionsDirective Colony follows when scanning the repo. This is what Colony actually reads and executes — it controls what Colony looks for and how it decides whether to file an issue.

Prompts are versioned. Each save creates a new version; you can view history and activate a prior version from the Prompt drawer. Only the active version runs.

Open Autonomy, then the Tracks tab (/autonomy/tracks) for an org-wide view of every configured track.

The table shows one row per track, across all repositories:

ColumnWhat it shows
TrackThe repository (links to its work on Work), the track label and its holder line.
CadenceA cron track shows its expression. For a cooldown track, admins see an editable number input (minutes) and others see “every N min”.
PriorityThe track’s weight.
Last runTimestamp of the most recent run, or “Never” if the track has not run yet.
StatusOverdue badge appears when now - last_run_at > cooldown_minutes. Check Worker availability if tracks are consistently overdue.
PromptManage button opens the prompt drawer to view and edit prompt versions.
EnabledAdmin-only toggle (Enable / Disable). A confirmation dialog appears before disabling an active track.

The SI Tracks count metric counts the total number of configured tracks across all repos in the org. The metric definition is:

Number of self-improvement tracks configured across all repos in the org. A track is overdue if now - last_run_at > cooldown_minutes. Source: count summed across the per-repo GET /api/repos/{owner}/{repo}/si-tracks responses.

If the Tracks table is empty, no tracks have been configured yet, and the page points you to turn on self-improvement in Standards → Settings. To add your first track, pick a repository on this page and use Add track.

A track whose owner is strategy is held by the active strategy version. Its prompt, share (weight), cadence, menu mix, label and enabled state are read-only, and the holder line reads Held by strategy v<N> · change it in Strategy, linking to the Strategy tab. You can’t delete it; the API refuses edits to those fields, prompt changes and deletion with a TRACK_STRATEGY_OWNED conflict (409). It can’t be governed by a portfolio either; that request is refused with a 400. The cooldown floor and the selection mode stay editable, and applying a strategy never overwrites them. To change the rest, approve a new strategy version or revert.

Every track declares who holds its configuration, and each track row shows that as its holder line:

Holder lineMeaning
Managed hereThe track is independent. Its cadence, weight, prompt version and enabled state are edited on the track itself.
Governed by portfolio vNThe track takes its values from version N of the repo’s active portfolio.
Governed; not in the active portfolio, so it does not runThe track is governed, but the active portfolio has no entry for it, so it stays disabled.

A governed track’s controls are disabled and the holder line is the reason. Its label stays editable, and its prompt versions stay readable.

Independent is the default. New tracks are independent, and nothing moves a track into governance on its own. Governance changes one track at a time, by an explicit act, from the track’s Govern by portfolio or Manage here button. That button needs the Autonomy grant.

  • Govern by portfolio is allowed only when the repo’s active portfolio has an entry for the track. Otherwise it is refused, so a track never goes dark by being adopted. Add the track to a portfolio version and activate it first; see Portfolio.
  • Manage here releases the track. Its current values are written onto the track itself, so it keeps running exactly as before and is now managed here.

A portfolio is the set of track settings one repo runs on. A portfolio belongs to one repo. Each version moves Draft → Published → Active, and when a new version is activated the previous active version becomes Superseded. An edit made elsewhere never changes a repo’s active portfolio.

The Portfolio panel sits below the track list on the Tracks tab, for the selected repository. It lists every version with its status, author and dates.

  • New draft copies the active version’s entries. With no active version it copies every track’s current values, so activating a first version changes nothing that runs.
  • What a draft can change: which tracks are in it, and each entry’s enabled state, weight, cadence (cooldown or cron) and pinned prompt version. It can also change each entry’s autonomy mode (selection_mode). Only the proposal settings are carried unchanged.
  • Publish registers the version and runs nothing. Its entries are then fixed.
  • Activation applies a published version to the repo’s governed tracks. Independent tracks are untouched, and activating never changes a track’s governed or independent declaration. You activate from the diff: open a published version and the panel shows what activating it would change against the current active version, or against nothing when none is active. The diff lists governed tracks that enter or leave the program, changes to weight, cadence and prompt pin, and, in a separate region, changes to autonomy mode. Independent tracks are listed once as not governed by the portfolio. Activate sits at the end of the diff, with no confirm step. A later activation reverts the program, not the work it has already started, and a superseded version cannot be activated again. The API route stays available as an alternative: POST /api/repos/{owner}/{repo}/si-portfolio/versions/{version}/activate.
  • Only drafts can be edited or deleted. A published, active or superseded version is refused with a PORTFOLIO_VERSION_STATUS conflict.

Conformance. With a repository selected, each track row on this tab says whether the program is running what the active version declares. Every new origination records the portfolio version and prompt pin it was seeded under, and the ledger compares those recorded facts with the active version over the later of its activation and the last 7 days. It reads “Conforms to v7”, or names the dimension that differs (enabled, cadence, weight or prompt) with the item count and both values. Independent tracks read “Not governed by the portfolio”; a repo with no active version reads “Not yet configured”; items created before the facts were recorded read “Not reporting”. Next to it sits the track’s observed share of items and its declared weight share. The share is stated, never judged: the scheduler’s fair share runs over 30 days and depends on capacity. Conformance reports nothing about outcomes; Reporting does.

The Conformance cell compares what a track has actually done against the active portfolio. It reports recorded facts and makes no claim about outcomes. It shows one status, in this order of precedence:

LineMeaning
Not governed by the portfolioThe track is managed here, so the portfolio does not judge it.
Not yet configuredThe track is governed, but no portfolio is active yet.
Not reportingEvery item the track originated has no recorded portfolio version, so Colony cannot compare it.
Diverged: …The track ran in a way the active portfolio does not describe. One line appears per divergence.
Conforms to vNThe track’s work matches active portfolio version N.

A divergence line names one of four dimensions:

  • enabled: items ran, but the active version does not enable the track.
  • cadence: items ran under an earlier version’s cadence, and the active version says something different.
  • weight: items ran under an earlier version’s weight, and the active version says something different.
  • prompt: items ran on a prompt version other than the one the active version pins.

Two extra lines can follow the status:

  • A note such as “2 items recorded as independent, not judged” counts items on a governed track that were recorded as independent, which the comparison skips.
  • A share line such as “3 of 12 items (25%) · weight share 40%” gives the track’s share of all items originated in the window. The weight share appears when the portfolio declares one. The share line is absent when the window has no originations.

When the conformance read fails for that repo, the cell reads “Conformance unavailable”. A failed read never hides the table or the other rows.

Each act needs the Autonomy grant: si-portfolio-draft-write to create, edit or delete a draft, si-portfolio-publish to publish, and si-portfolio-activate to activate. Without the grant the control is shown but inert.

A template is a published, active or superseded portfolio version marked for reuse. It is not a second object: it has no lifecycle and no editor, and it cannot be edited. Template names are unique within a tenant.

  • Use Mark as template on a version in a repo’s Portfolio panel. A draft cannot be marked; publish it first.
  • Marking and unmarking need the Autonomy grant, capability si-portfolio-template-write. Without it the control is shown but inert.
  • Unmark removes the template only. Drafts already seeded from it, and every repo’s published and active versions, are unchanged.

Pick up to 25 repos in the template’s tenant and choose Push. Each repo gets one new draft, and nothing is activated. Eight repos give eight drafts to review, not one hidden decision; each repo publishes and activates its own, and divergence afterward is expected.

The response is 201 when every repo was drafted, and 207 with a per-repo outcome otherwise. A repo that is not in the template’s tenant is reported as failed, and the rest are still drafted.

  • Tracks are matched by name.
  • Template tracks the repo lacks are skipped and reported, never created.
  • Repo tracks the template lacks are left out of the draft, so they show as leaving in the activation diff.
  • Each seeded entry takes the template’s enabled state, weight, cadence and proposal settings.
  • It keeps the repo track’s own prompt pin (active_version) and autonomy mode, so a push never changes either.

A seeded draft shows “Seeded from template” followed by the template’s name in the version list and in the draft editor.

EndpointPurpose
POST /api/repos/{owner}/{repo}/si-portfolio/versions/{version}/templateMark a non-draft version, with { name }
GET /api/si-portfolio/templatesList the org’s templates
DELETE /api/si-portfolio/templates/{id}Unmark a template
POST /api/si-portfolio/templates/{id}/pushSeed a draft in each repo, with { repos }

The /colony:track command is listed in the /colony:help output with the description “manage self-improvement track assignment (limited support)”. In the current release, issuing /colony:track on a GitHub issue acknowledges the command with a thumbs-up reaction and takes no further action.

Use the Colony Cloud dashboard to manage track configuration and enable/disable state instead.

  1. Create one track in a low-activity repository with a long cooldown (1440 minutes = 24 hours).
  2. Author a focused prompt — for example, “identify up to three public functions missing unit tests and file a single issue listing them.”
  3. Enable the track and wait for the first run.
  4. Review the candidate slate and selected work in the pipeline. If the evidence and scope look right after completion, consider reducing the cooldown. If Colony over-proposed, tighten the instructions.
  5. Once the first track is tuned, add a second track for a different improvement category.

Avoid enabling multiple tracks simultaneously before you have reviewed at least one full cycle. Tracks share the same Worker pool as your pipeline; too many concurrent track-filed issues can crowd out human-filed work.