Drafts

Drafts is a three-pane authoring surface in Colony Cloud at /drafts. Use it to write and refine issue descriptions before they enter the autonomous pipeline. Once a draft is ready, publishing it creates a GitHub issue and immediately enqueues it for Colony to process.

When to use Drafts vs. colony_file_issue

	Drafts	colony_file_issue
Authoring experience	Full three-pane editor with AI assists	Single tool call from your editor
Human review step	Yes — moves through lifecycle states before publish	No — issue is created and enqueued immediately
Saved across sessions	Yes — persists in your org until published or deleted	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 issue description, get AI writing assistance, or stage work for a teammate to review before it hits the pipeline. Use colony_file_issue (or its MCP equivalent colony_file_issue) when the issue is already well-specified and should enter the queue right away.

The MCP tool colony_create_draft writes into this same surface — useful when an AI assistant produces a draft from a conversation that needs a human review pass before submission.

The three panes

Draft list (left pane)

The left pane lists all drafts for your organization, sorted by last updated. Click any draft to open it in the editor. A New draft button at the top creates a blank draft and opens it immediately.

Each entry shows the draft title, target repository, lifecycle state, and last-updated time. Use the list to navigate between drafts in progress, review parked ideas, and see which drafts are ready to publish.

Editor (center pane)

The center pane is where you write the issue. It contains:

• Title — a short one-line summary of the issue (max 255 characters).
• Issue type — one of bug, feature, refactor, or spike. Used to tag the issue on publish.
• Body — a Markdown editor for the full issue description (max 64 KB).
• Lifecycle selector — move the draft through its states manually.
• Publish button — converts the draft to a live GitHub issue and enqueues it.

The body editor recognizes the canonical section headings that Colony’s agents use when reading issue bodies:

Section	Purpose
Problem	What is wrong or missing; the situation that motivates this issue
Proposed approach	How to address the problem; the implementation direction
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

You do not need to include every section — include the ones that are useful for the issue at hand. Well-specified Problem, Acceptance criteria, and Anchors sections give Colony the strongest signal.

AI assist (right pane)

The right pane offers five AI writing actions that operate on the current draft body. Each action returns one or more improved sections — review the suggestions and paste them back into the editor where useful. The assist actions do not modify the draft automatically.

Action	What it produces
Separate problem / solution	Rewrites the body into a clean Problem section (describing the situation) and a Proposed approach section (describing the fix) — useful when the two are tangled together
Convert to checklist	Rewrites the acceptance criteria as an actionable - [ ] checklist where each item is a specific, verifiable statement
Infer non-goals	Generates an explicit Non-goals list from the body — surfaces scope boundaries a reader might otherwise assume are in scope
Suggest from goal	Expands a single high-level goal sentence into a full Problem, Proposed approach, and Acceptance criteria — useful for seeding a draft from a rough idea
Find anchors	Searches the target repository for file paths and symbols the issue is likely to touch and returns a formatted Anchors section; falls back to best-effort estimates when a codebase search is unavailable

Note

AI assists require a platform LLM key to be configured. If the assist panel is unavailable in your organization, contact your org owner to verify the LLM integration is active.

Lifecycle states

Every draft moves through four states. You can change the state manually using the lifecycle selector in the editor, or it advances automatically when you publish.

State	Meaning
refining	The draft is actively being written or edited. All new drafts start here.
parking	The draft is set aside temporarily — the idea is worth keeping but not being actively worked on.
ready	The draft is complete and approved for publication. Use this as a signal to yourself or a teammate that the issue is ready to publish.
published	The draft has been published as a GitHub issue. The issue number is recorded and shown as a link, and the draft can no longer be re-published (a second publish returns a 409).

Tip

parking is useful for capturing ideas quickly without cluttering the active list. Filter the draft list by lifecycle to focus on ready or refining drafts.

Publishing a draft

Publishing converts the draft into a GitHub issue in the target repository, applies Colony’s enqueue label, and submits it to the pipeline. The draft transitions to published and records the issue number.

1. Open the draft in the editor and confirm the title, body, and issue type look correct.
2. Move the lifecycle to ready — a final review signal, not a hard requirement.
3. Click Publish. Colony Cloud creates the GitHub issue using the draft title and body.
4. After publishing, the draft shows the issue number as a link. The issue is now active in the pipeline and can be tracked in Pipeline Live.

Publish as epic: To publish the draft as a Colony epic (attaches the colony:epic label), use the asEpic option. This is available via the API or the colony_create_draft + publish flow; the dashboard publish button creates a standard issue by default.

Note

Publishing is idempotent — if you publish a draft that is already published, the API returns a 409 with the existing issue number rather than creating a duplicate.

Role requirements

Draft routes are gated by org membership only — any verified org member can view, create, edit, change lifecycle, publish, and delete drafts regardless of their role. This applies to Owner, Admin, Member, and Viewer roles alike.

See Team & Roles for the full org permission matrix.