Proposal Chorus

Proposal Skill

This skill covers the Planning stage of the AI-DLC workflow: creating Proposals that contain document drafts (PRD, tech design) and task drafts with dependency DAGs, then submitting them for Admin review.

Overview

After an Idea's elaboration is resolved (see idea-chorus skill at <BASE_URL>/skill/idea-chorus/SKILL.md), the PM Agent creates a Proposal — a container that holds document drafts and task drafts. On Admin approval, these drafts materialize into real Documents and Tasks.

Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit --> Admin review

Tools

Proposal Management:

Document Drafts:

Task Drafts:

Post-Approval (tasks exist):

Shared tools (checkin, query, comment, search, notifications): see chorus skill at <BASE_URL>/skill/chorus/SKILL.md

Workflow

Step 0: Reuse Evidence and Check New Factual Gaps

Read the confirmed input Idea(s) or Documents, current specifications, References and recent context before drafting. Reuse existing findings first; invoke research-chorus (<BASE_URL>/skill/research-chorus/SKILL.md) (shared rules) only for a new factual design gap or explicit user request, subject to explicit skip. Supply the Proposal stage, focused question, existing evidence and budget. Do not automatically repeat Idea research, including on a resumed planning wake; this route also applies to form/MCP-created inputs without a research flag.

If the Proposal does not exist yet, retain candidate source URLs/titles/types in the current context, then include them in references[] on the Step 1 chorus_pm_create_proposal call when possible. Read chorus_get_proposal afterward to obtain actual references[].uuid; inline creation returns the container UUID, not individual evidence UUIDs. If it already exists, reuse its evidence or attach new sources via chorus_add_reference and take the returned reference uuid. Only then write citations such as [1](ref:<actual-reference-uuid>) beside supported statements in the design/specifications. Never invent UUIDs or substitute the Proposal UUID.

In OpenSpec/spec-lite modes, resolve the existing spec mode and locator as below, update authoritative local files with findings and real citations, then mirror file bytes using chorus mcp call … --arg-file content=<file> (or the port's existing file-reading wrapper). No hand-typed MCP document content; spec-lite's durable spec.md remains local-only. Free-form mode keeps its normal draft-saving path. Empty/partial results preserve unknowns and continue preparation. Research does not submit, approve, or bypass revision restrictions; pending/approved proposals retain their existing revision gates. A Tracker research-only instruction returns through the Idea route instead of entering this drafting workflow.

Step 1: Create an Empty Proposal

It is generally best to create the proposal container first without any drafts, then incrementally add document and task drafts one by one.

chorus_pm_create_proposal({
  projectUuid: "<project-uuid>",
  title: "Implement <feature name>",
  description: "Analysis and implementation plan for Idea #xxx",
  inputType: "idea",
  inputUuids: ["<idea-uuid>"]
})

Multiple Ideas: You can combine multiple ideas into one proposal by passing multiple UUIDs in inputUuids.

A theme cannot be a proposal input — chorus_pm_create_proposal rejects any input idea with isContainer = true. Derive a child idea from the theme and write the proposal on the child instead. (See the theme-ideas section of the idea-chorus skill.)

Step 2: Add Document Drafts

Add document drafts one at a time:

# Add PRD
chorus_pm_add_document_draft({
  proposalUuid: "<proposal-uuid>",
  type: "prd",
  title: "PRD: <Feature Name>",
  content: "# PRD: <Feature Name>\n\n## Background\n...\n## Requirements\n..."
})

# Add Tech Design
chorus_pm_add_document_draft({
  proposalUuid: "<proposal-uuid>",
  type: "tech_design",
  title: "Tech Design: <Feature Name>",
  content: "# Technical Design\n\n## Architecture\n...\n## Implementation\n..."
})

Document types: prd, tech_design, adr, spec, guide

Step 3: Add Task Drafts

Add task drafts one at a time. The response returns the new draft's draftUuid — use it directly for dependsOnDraftUuids in subsequent drafts.

acceptanceCriteriaItems is required — every task draft must include at least one item with a non-blank description, or the call is rejected. Use the structured acceptanceCriteriaItems array (the legacy acceptanceCriteria Markdown string does not satisfy the requirement).

# First task -> response includes { draftUuid, draftTitle }
chorus_pm_add_task_draft({
  proposalUuid: "<proposal-uuid>",
  title: "Implement <component>",
  description: "Detailed description of what to build...",
  priority: "high",
  storyPoints: 3,
  acceptanceCriteriaItems: [
    { description: "Criteria 1", required: true },
    { description: "Criteria 2", required: true }
  ]
})

# Second task — depends on first
chorus_pm_add_task_draft({
  proposalUuid: "<proposal-uuid>",
  title: "Write tests for <component>",
  description: "Unit and integration tests...",
  priority: "medium",
  storyPoints: 2,
  acceptanceCriteriaItems: [
    { description: "Test coverage > 80%", required: true }
  ],
  dependsOnDraftUuids: ["<draftUuid-from-first-task>"]
})

To edit a draft's criteria later via chorus_pm_update_task_draft, pass a non-empty acceptanceCriteriaItems to replace them; omit the field to leave them unchanged. The field cannot be used to clear criteria.

Task priority: low, medium, high

Step 4: Review and Refine Drafts

# Review current state. chorus_get_proposal defaults to section:"basic"
# (metadata + a lightweight draft index, no bodies). Use section:"full" to
# see every draft's content, or section:"documents"/"tasks" for one kind.
chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })

# Update a document draft
chorus_pm_update_document_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>",
  content: "Updated content..."
})

# Update a task draft
chorus_pm_update_task_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>",
  description: "Updated description...",
  dependsOnDraftUuids: ["<other-draft-uuid>"]
})

# Remove a draft
chorus_pm_remove_task_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>"
})

Step 5: Validate and Submit

Before submitting, validate to preview issues:

chorus_pm_validate_proposal({ proposalUuid: "<proposal-uuid>" })

Returns { valid, issues } with error, warning, and info levels. Fix errors before submitting.

When validation passes:

chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })

This changes the status from draft to pending. An Admin will review it (see review-chorus skill at <BASE_URL>/skill/review-chorus/SKILL.md).

Consider adding a comment explaining your reasoning:

chorus_add_comment({
  targetType: "proposal",
  targetUuid: "<proposal-uuid>",
  content: "This proposal covers... Key decisions: ..."
})

Step 6: Handle Feedback

If the proposal is rejected, check the review note:

chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })
chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })

Revise the drafts and resubmit.