Drafts
A draft is a proposal: a work idea that has not yet entered the autonomous pipeline. Proposals live in the Proposals band on Work, and each one opens as a proposal at /work?proposal=:id (/dashboard/intake/:id and /drafts/:id redirect there). When a proposal is ready, Authorize files the work item (or items) on the code host and enqueues them for Colony to process.
The proposal opens as a drawer over Work. A shared link with no Work page behind it opens it as a standalone page.
Starting a proposal
Section titled “Starting a proposal”- New proposal — on Work’s Proposals band, choose New proposal. It opens the proposal itself at
/work?proposal=new, repository first. Nothing is saved until a title exists; then it saves into Proposals and the address becomes/work?proposal=:id. The workflow the repository routes to is shown as soon as you choose it. - Import a plan — on the same band, choose Import a plan. It opens the same surface: pick the repository, paste a Markdown plan or tasks JSON, or upload a
.mdor.jsonfile, then choose Import plan. The plan becomes a proposal whose tasks Authorize files as work items. - MCP — the
colony_create_drafttool creates a proposal from your editor or an AI assistant and returns a link to it.
When to use Drafts vs. colony_file_issue
Section titled “When to use Drafts vs. colony_file_issue”| Drafts | colony_file_issue | |
|---|---|---|
| Authoring experience | The proposal with a section editor and AI assists | Single tool call from your editor |
| Human review step | Yes — nothing is filed until someone authorizes | No — issue is created and enqueued immediately |
| Saved across sessions | Yes — persists in your org until authorized or declined | No — fires once and is done |
| Best for | Complex or high-risk changes that benefit from review and refinement | Well-scoped, unambiguous issues ready to process now |
Use Drafts when you want to iterate on the description, get AI writing assistance, or stage work for a teammate to review before it hits the pipeline. Use colony_file_issue when the issue is already well-specified and should enter the queue right away.
Acting on proposals from the Ledger
Section titled “Acting on proposals from the Ledger”The Proposals band on Work lists every proposal that is not yet work. Tick one or more and choose Authorize to file them together; the result reads “X of Y authorized”. Each row shows its repository, where it came from (drafted in a coding session, written in Colony, or an imported plan with its task count) and how long ago, then “Meets standards” or “N standards not met”. Plan rows show no verdict. Click a title or Open to open the proposal. Decline lives in the proposal, not on the band. See Dashboards for the band itself.
The proposal
Section titled “The proposal”The proposal opens in a wide drawer over Work at /work?proposal=:id. Open as a page opens it as a standalone page at /work/proposals/:id, and Back to Work returns. The header holds the title, a neutral “proposal” chip, the provenance and time, the save state (“Saved to Proposals”, then “Saved”), Decline and Authorize. It has two columns.
Left column
- Repository, Kind and Shape — Shape is One item or Split into parts; the pipeline does the splitting after the item starts. The repository can be changed until the proposal is authorized. Kind offers the kinds declared by the workflow the repository routes to. A new proposal has no kind until you choose one.
- Workflow line — the workflow the repository routes to, with its sections, and any routing rule that could send the item elsewhere.
- Assists and sections (below). Edits autosave.
Right column
- Authorize creates — what Authorize will file: the work item in the repository, or for a plan its tasks. It lists the Steward, which is whoever authorizes, the Workflow, and the Estimated cost. The estimate is the median cost of the last 20 completed work items in the repository, and the card states that basis; with no completed items it reads “No estimate yet”. A plan shows the task count times the median.
- Standards — the repository’s proposal standards, each marked “met” or “not met” and re-checked as you type. An unmet blocking standard disables Authorize, which says how many more standards must be met. An unmet criteria checklist offers Convert to checklist.
- Travels with it — the standing constraints set on this proposal, in force from the first station once you authorize.
A plan opens as a plan view: “The plan · N tasks”, each marked “starts now” or “after …”, and Authorize N work items. Plans show no standards verdict.
States
Section titled “States”- Filing was never confirmed — Colony asked the code host to file the item and never heard back, so it may exist already. Look in the repository first, then Retry or choose It was never filed.
- The code host can’t be reached — nothing could be filed. The proposal stays saved; authorize it again once the connection is back.
- No right to authorize — you can write proposals but authorizing needs Work write on the repository. Authorize is disabled and Copy the link shares the proposal with someone who has it.
On a phone
Section titled “On a phone”At the compact width the proposal is read-only: the title, meta and sections as text. A proposal that meets its standards shows Authorize and Decline; one that doesn’t shows only Decline. To edit it, open it on a larger screen.
Sections
Section titled “Sections”The editor shows the sections the routed workflow declares. Title is limited to 255 characters and the body to 64 KB. The default workflow declares these:
| Section | Purpose |
|---|---|
| Problem | What is wrong or missing; the situation that motivates this issue |
| Acceptance criteria | Verifiable conditions that must be true when the work is done |
| Non-goals | Things explicitly out of scope, to prevent scope creep |
| Anchors | File paths and symbols the implementation must touch |
| Verification | How to confirm the solution works (tests, manual steps) |
| Context | Background, prior art, related issues, or external constraints |
| Proposed approach | How to address the problem; the implementation direction |
You do not need to fill every section. Well-specified Problem, Acceptance criteria, and Anchors sections give Colony the strongest signal. Headings in the body that match no declared section are kept as extra fields.
AI assist
Section titled “AI assist”A section with an assist action has a named button beside its heading, shown only when the workflow declares the section the action writes. Each action writes only its named section(s); the rest of the body is left byte-for-byte as it was. The result is autosaved, and a one-step Undo restores the body as it was before the action. While an action is running, the title and section fields are read-only.
| Action | Writes |
|---|---|
| Separate problem from solution | Rewrites Problem to describe the situation and Proposed approach to describe the fix — useful when the two are tangled together |
| Convert to checklist | Rewrites Acceptance criteria as an actionable - [ ] checklist where each item is a specific, verifiable statement |
| Infer non-goals | Generates an explicit Non-goals list — surfaces scope boundaries a reader might otherwise assume are in scope |
An action is applied in full or not at all. If Colony can’t produce a complete result, for example because the reply was cut off or a section came back empty, the editor says “Colony couldn’t produce a usable result from this draft. Your draft is untouched.” Nothing changes, nothing is saved, and no Undo appears. Run the action again.
If your organization routes the Mayor through its own model access (Operations › Settings), assists follow that setting: every assist call goes through your provider and credential and never falls back to Colony’s key. If that route can’t be used, for example because the credential is missing or rejected, the editor names the provider and the reason and says “Your draft is untouched.”
Writing a proposal
Section titled “Writing a proposal”The recommended order:
- Choose the repository.
- Give the proposal a title.
- Choose its Kind and Shape.
- Fill in Problem, Acceptance criteria and Anchors first. They give Colony the strongest signal.
- Run the assists on the sections that need them.
- Clear any unmet standards.
- Add constraints that should hold on this work item.
- Authorize.
Terms used on the proposal:
- Standard — one of the repository’s proposal standards. Each is re-checked as you write and marked “met” or “not met”. An unmet blocking standard holds Authorize.
- Travels with it — the card holding the proposal’s standing constraints, in force from the first station once you authorize.
- Constraint — a standing rule Colony follows on this work item from the first station, for example “Every timeout field refuses zero.”
Lifecycle states
Section titled “Lifecycle states”Every proposal has one of four states. New proposals start as refining, and Authorize moves a proposal to published automatically.
| State | Meaning |
|---|---|
| refining | Being written or edited. All new proposals start here. |
| parking | Set aside for later. The idea is worth keeping. |
| ready | Complete and approved. A signal to yourself or a teammate that it can be authorized. Choosing “It was never filed” on an unconfirmed filing also returns a proposal here. |
| published | Authorized and filed as work items. The item number is recorded, and the proposal cannot be authorized again. |
The proposal does not have a state picker. States other than refining are set through the API.
Authorizing a proposal
Section titled “Authorizing a proposal”Authorize files the work item in the target repository, applies Colony’s enqueue label, and submits it to the pipeline. The proposal moves to published and records the item number.
- Open the proposal and confirm the title, kind, body, and shape look right.
- Check Authorize creates and Standards. A failing blocking standard disables Authorize.
- Click Authorize. Colony Cloud saves pending edits first, then files the item using the card’s contents, with you as its steward. The proposal shows the item number as a link, or for a plan import each filed number.
- Track the work in the Ledger.
Authorize files exactly what the card shows. If a plan import files only some tasks, the proposal lists which were created and which could not be filed. The proposal is kept, and retrying files only the missing tasks.
Role requirements
Section titled “Role requirements”Any verified org member can view and list proposals. Changing them is gated by VCS write on the tenant that owns the proposal’s target repository, not anywhere in the org:
| Action | Capability id |
|---|---|
| Create a proposal (authoring or plan import) | colony-create-draft |
| Edit a proposal, including lifecycle changes | draft-update |
| Decline or delete a proposal | draft-delete |
| Authorize a proposal | draft-publish |
Owner, Admin and Member have VCS write by default. Viewer does not, so a Viewer can read the Proposals band and open a proposal but cannot change anything.
The dashboard checks the grant for Authorize ahead of time: without it, Authorize is disabled and Copy the link appears. It doesn’t check the other actions ahead of time, so a Viewer still sees them as available. When a Viewer uses one, the API refuses it with the standard grant-denied error and the dashboard shows that error.
See Team & Roles for the full org permission matrix.