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.
Track fields
Section titled “Track fields”Each track has the following configurable properties:
| Field | Description |
|---|---|
| Name | Unique identifier for the track within the repository. Used as a stable key (e.g., test-coverage, type-tightening). Immutable after creation. |
| Label | Code-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 kind | cooldown 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). |
| Cooldown | For 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. |
| Owner | operator 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. |
| Weight | Numeric 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. |
| Prompt | The versioned prompt Colony runs against the repository. Consists of a seedTitle, seedBody, and instructions field (see Prompt authoring below). |
| Enabled | Toggle to allow or pause the track. Disabled tracks are visible in the dashboard but will not run. |
| Autonomy mode | human, auto:first or auto:preferred. It is never wider than the repository’s autonomy grant. |
Configure tracks per repository
Section titled “Configure tracks per repository”Track configuration lives on the Tracks tab, not in org-level settings.
- Open Autonomy, then the Tracks tab (
/autonomy/tracks). - Pick a repository with the repository control in the region’s header. The page scopes to it through the
?repo=owner/namequery parameter, so/autonomy/tracks?repo=owner/nameopens that repository directly. - Click Add track to create a new track, or click Edit on an existing track.
- Set the code-host Label, choose the cadence (a Cooldown preset, or a cron expression), and toggle whether the track should start enabled.
- 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.
Cooldown presets
Section titled “Cooldown presets”The cooldown dropdown offers seven presets. The value stored in cooldownMinutes on the track record is shown alongside each label:
| Label | Stored value |
|---|---|
| Instant | 1 minute |
| Hourly | 60 minutes |
| Every 2 hours | 120 minutes |
| Every 4 hours | 240 minutes |
| Every 8 hours | 480 minutes |
| Daily | 1,440 minutes |
| Weekly | 10,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.
Prompt authoring
Section titled “Prompt authoring”Each track’s active prompt has three fields:
| Field | Purpose |
|---|---|
| Seed title | The GitHub issue title Colony files when the track produces a candidate, used exactly as written. |
| Seed body | The 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. |
| Instructions | Directive 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.
Monitor tracks — Tracks dashboard
Section titled “Monitor tracks — Tracks dashboard”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:
| Column | What it shows |
|---|---|
| Track | The repository (links to its work on Work), the track label and its holder line. |
| Cadence | A cron track shows its expression. For a cooldown track, admins see an editable number input (minutes) and others see “every N min”. |
| Priority | The track’s weight. |
| Last run | Timestamp of the most recent run, or “Never” if the track has not run yet. |
| Status | Overdue badge appears when now - last_run_at > cooldown_minutes. Check Worker availability if tracks are consistently overdue. |
| Prompt | Manage button opens the prompt drawer to view and edit prompt versions. |
| Enabled | Admin-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-repoGET /api/repos/{owner}/{repo}/si-tracksresponses.
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.
Strategy-owned tracks
Section titled “Strategy-owned tracks”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.
Governed and independent tracks
Section titled “Governed and independent tracks”Every track declares who holds its configuration, and each track row shows that as its holder line:
| Holder line | Meaning |
|---|---|
| Managed here | The track is independent. Its cadence, weight, prompt version and enabled state are edited on the track itself. |
| Governed by portfolio vN | The track takes its values from version N of the repo’s active portfolio. |
| Governed; not in the active portfolio, so it does not run | The 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.
Portfolio
Section titled “Portfolio”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_STATUSconflict.
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:
| Line | Meaning |
|---|---|
| Not governed by the portfolio | The track is managed here, so the portfolio does not judge it. |
| Not yet configured | The track is governed, but no portfolio is active yet. |
| Not reporting | Every 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 vN | The 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.
Templates
Section titled “Templates”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.
Marking
Section titled “Marking”- 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.
Pushing
Section titled “Pushing”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.
How entries map
Section titled “How entries map”- 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.
Provenance
Section titled “Provenance”A seeded draft shows “Seeded from template” followed by the template’s name in the version list and in the draft editor.
| Endpoint | Purpose |
|---|---|
POST /api/repos/{owner}/{repo}/si-portfolio/versions/{version}/template | Mark a non-draft version, with { name } |
GET /api/si-portfolio/templates | List the org’s templates |
DELETE /api/si-portfolio/templates/{id} | Unmark a template |
POST /api/si-portfolio/templates/{id}/push | Seed a draft in each repo, with { repos } |
/colony:track slash command
Section titled “/colony:track slash command”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.
Recommended starting point
Section titled “Recommended starting point”- Create one track in a low-activity repository with a long cooldown (1440 minutes = 24 hours).
- Author a focused prompt — for example, “identify up to three public functions missing unit tests and file a single issue listing them.”
- Enable the track and wait for the first run.
- 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.
- 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.