Strategy
The Strategy tab (/repos/<owner>/<name>/charter) is the Colony Cloud interface for managing the per-repository strategy charter and reviewing Strategist proposals. Owners and administrators can read and update the charter; Members and Viewers see a read-only view.
For the conceptual model behind charters and the Strategist cycle, see Strategy.
Charter editor
Section titled “Charter editor”The charter is the operator-authored policy document that constrains what the Strategist may do autonomously. Each repository has at most one active charter at a time. When no charter exists yet, a notice explains that strategic goals and a risk envelope are needed before the Strategist can propose weekly work.
Data source: GET /api/strategy/:owner/:repo/charter (returns { charter: null } when no charter exists). Save via PUT /api/strategy/:owner/:repo/charter (owner/admin only, gated by requireRole).
A free-text textarea where you describe what the repository’s strategy should achieve. The Strategist reads this field when generating proposals.
Risk envelope
Section titled “Risk envelope”The risk envelope constrains which track sizes the Strategist may apply autonomously and which focus areas it should weight or avoid.
| Field | Description |
|---|---|
| Max auto size | The largest track size the Strategist may apply without operator approval. Values: small, medium, large, or epic. Anything above this threshold requires manual approval before the snapshot becomes active. See Charter risk envelope (max_auto_size) for the metric definition. |
| Prefer | List of focus areas the Strategist should weight toward when proposing work (one entry per line). |
| Avoid | List of focus areas the Strategist should not propose autonomously. |
| Escalate when | Conditions under which the Strategist must escalate to an operator rather than acting. |
Metadata
Section titled “Metadata”When an existing charter is loaded, the editor shows read-only metadata below the form fields:
- Version — integer version of the charter. Increments on each save.
- Author — identifier of the operator who last saved the charter.
- Date — when this version was created.
Access control
Section titled “Access control”The Save button is visible only to owners and administrators. Members and Viewers see the charter fields in read-only mode with no save control. If no charter has been set and the user does not have write access, the tab shows an explanatory message only.
Current strategy
Section titled “Current strategy”The Current strategy card shows the active snapshot — the Strategist-generated plan that is currently guiding autonomous work for this repository.
| Field | Description |
|---|---|
| Version | Integer version of the active snapshot, displayed as v<N>. |
| Intent | Short description of what this strategy aims to achieve. |
| Rationale | Explanation of why this strategy was proposed. |
Empty state: “No active strategy yet.” — shown when no snapshot has been approved and promoted to active status.
Data source: GET /api/strategy/:owner/:repo/snapshots?status=proposed,approved,active,superseded, filtered to status === 'active'.
Proposal history
Section titled “Proposal history”The Proposal history timeline lists all strategy snapshots for this repository in reverse-chronological order. Each entry shows its version number and lifecycle status.
Snapshot lifecycle
Section titled “Snapshot lifecycle”proposed → approved → active → superseded| Status | Meaning |
|---|---|
proposed | The Strategist has generated a snapshot; it is awaiting operator review. |
approved | An operator has approved the snapshot; it is staged to become active. |
active | The snapshot is the current active strategy guiding autonomous work. |
superseded | A newer snapshot has become active; this one is retained for historical reference. |
See Strategy snapshot status for the metric definition.
Snapshot portfolio detail
Section titled “Snapshot portfolio detail”Click any entry in the timeline to expand its portfolio detail below the timeline. The portfolio panel shows:
- Intent and rationale for the snapshot.
- Creates — new tracks or items this snapshot introduces.
- Retires — track identifiers this snapshot retires.
- Review by — optional deadline by which the snapshot should be reviewed (ISO 8601, if set).
- Author — either
strategist(Strategist-generated) oroperator(manually authored).
Other key snapshot fields:
| Field | Description |
|---|---|
version | Integer version of this snapshot. |
parent_version | Version of the snapshot this one supersedes, or null for the first snapshot. |
charter_version | The charter version under which this snapshot was generated. |
Empty state: “No strategy proposals yet — the Strategist proposes work once a charter is set.” Links to the charter section (for non-write users) or to the Generate proposal action (for owners/admins).
Actions
Section titled “Actions”Approve strategy
Section titled “Approve strategy”The Approve strategy button appears below the portfolio detail panel when the selected snapshot has status proposed and the current user is an owner or administrator.
Clicking Approve strategy opens a confirmation dialog that summarises how many tracks will be created or updated and how many will be retired. Confirming sends POST /api/strategy/:owner/:repo/snapshots/:version/approve. On success, the snapshot transitions from proposed to approved and then to active; the previously active snapshot (if any) moves to superseded.
Generate proposal
Section titled “Generate proposal”The Generate proposal button appears in the Proposal history section header for owners and administrators.
Clicking Generate proposal opens a confirmation dialog with the message: “This queues one Strategist cycle. The result will appear as a proposed snapshot — it does not apply automatically.” Confirming sends POST /api/strategy/:owner/:repo/snapshots/generate.
The API call queues one Strategist run. The Strategist reads the active charter, the repository’s current SI tracks, and recent pipeline data to produce a new proposed snapshot. The snapshot does not apply automatically — an operator must approve it before it becomes active.