Proposal

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 the idea skill, skill_view("chorus:idea")), 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 --> Reviewer --> Admin review

Tools

Proposal Management:

Document Drafts:

Task Drafts:

Post-Approval (tasks exist):

Shared tools (checkin, query, comment, search, notifications): see the overview skill (skill_view("chorus:chorus"))

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 the research skill (skill_view("chorus:research"), 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> via terminal (or, when chorus is not on PATH, the native MCP tool with content set to the exact file contents read via read_file). 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

Resolve the spec mode (Step 1.5) BEFORE this create. In OpenSpec and spec-lite modes the container's description MUST carry a locator line (OpenSpec change slug: <slug> or Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/), and description can only be set at creation — decide the mode + slug/dated-path first and include that line in this single call. Do NOT create a bare container and then realize you needed it. Free-form mode omits any locator line.

Recommended approach: Create the proposal container first (with the mode's locator line in description when applicable), 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 skill, skill_view("chorus:idea").)

Step 1.5: Select spec mode

The spec mode is already computed for you by the Chorus Hermes plugin — do NOT re-derive it. Its pre_llm_call check-in (first turn of each session, and again after /reset or context compression) resolves the mode with the plugin's spec_mode.py (explicit CHORUS_SPEC_MODE wins; otherwise openspec when an openspec/ directory and the openspec CLI are both present in the working directory; otherwise lite) and injects it as the ## Spec Mode section of your context: it states CHORUS_SPEC_MODE=<lite|openspec|off> + a routing note. (No ## Spec Mode in context, e.g. you are a delegate_task child? See openspec-aware §1 manual fallback via skill_view("chorus:openspec-aware") — never hand-roll the rule.) Act on that value:

• If the section says the mode cannot be honored (explicit CHORUS_SPEC_MODE=openspec but OpenSpec unusable — config-conflict or install-hint reason), halt and surface it; do not fall back.

• Otherwise branch on the resolved mode:

• resolved = spec-lite → load the spec-lite skill (skill_view("chorus:spec-lite")) and follow it: pick $SLUG (a capability, not one change). Ensure the durable .chorus/specs/<slug>/spec.md exists (local-only, no Chorus ids; use the spec-lite skill's inline durable-spec template) and update it in place. Create this change's dated folder .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/ with its synced Chorus-typed docs (prd.md primary, optional tech_design.md…; use the spec-lite skill's inline dated-folder document template). Put the literal locator line Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/ in the Step 1 create description, then mirror each dated-folder <type>.md to its persistent Document (chorus_pm_add_document_draft --arg-file first time, chorus_pm_update_document --arg-file after) via chorus mcp call … --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/<type>.md (run through terminal; see skill_view("chorus:chorus-cli")). spec.md is never mirrored. Skip Step 2 below. (Tasks via chorus_pm_add_task_draft; no tasks.md.)

• resolved = OpenSpec (the ## Spec Mode section shows CHORUS_OPENSPEC_ACTIVE=1 — i.e. CHORUS_SPEC_MODE=openspec or unset, with OpenSpec usable) → follow the openspec-aware skill §3 (skill_view("chorus:openspec-aware")). Pick $SLUG, scaffold openspec/changes/<slug>/, author proposal.md / design.md / specs/<capability>/spec.md locally, then put the literal line OpenSpec change slug: <slug> in the Step 1 create description, and mirror each local file into a document draft.

  ⛔ Mandatory in OpenSpec mode: mirror calls fill content from the local file — prefer chorus mcp call … --arg-file content=<file> run via terminal; when chorus is not on PATH, fall back to calling the native MCP tool (mcp__chorus__chorus_pm_add_document_draft / mcp__chorus__chorus_pm_update_document_draft) with content set to the exact bytes of the file as returned by read_file — see openspec-aware §3.6. Do not call chorus_pm_add_document_draft with a hand-typed or paraphrased content field. Re-typing thousands of lines burns 20k+ content tokens per proposal and breaks byte-equality (openspec-aware §2 Rule 1). Skip Step 2 when in OpenSpec mode — the file-fill flow replaces it for documents.

• resolved = free-form (explicit CHORUS_SPEC_MODE=off) → proceed with Step 2 unchanged. Author drafts inline as free-form Markdown via direct MCP chorus_pm_add_document_draft.

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 skill_view("chorus:review")).

Add a comment explaining your reasoning:

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