Proposal ChorusSAFE

The Agent Harness for AI-Human Collaboration, inspired by the AI-DLC (AI-Driven Development Lifecycle)

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: proposal-chorus
description: Chorus Proposal workflow — create proposals with document and task drafts, manage dependency DAG, validate and submit for review.
license: AGPL-3.0
metadata:
  author: chorus
  version: "0.17.0"
  category: project-management
  mcp_server: 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:**

| Tool | Purpose |
|------|---------|
| `chorus_pm_create_proposal` | Create empty proposal container |
| `chorus_pm_validate_proposal` | Validate proposal completeness (returns errors, warnings, info) |
| `chorus_pm_submit_proposal` | Submit proposal for Admin approval (draft -> pending) |

**Document Drafts:**

| Tool | Purpose |
|------|---------|
| `chorus_pm_add_document_draft` | Add document draft to proposal |
| `chorus_pm_update_document_draft` | Update document draft content |
| `chorus_pm_remove_document_draft` | Remove document draft from proposal |

**Task Drafts:**

| Tool | Purpose |
|------|---------|
| `chorus_pm_add_task_draft` | Add task draft (returns draftUuid for dependency chaining) |
| `chorus_pm_update_task_draft` | Update task draft |
| `chorus_pm_remove_task_draft` | Remove task draft from proposal |

**Post-Approval (tasks exist):**

| Tool | Purpose |
|------|---------|
| `chorus_create_tasks` | Batch create tasks (supports intra-batch dependencies via draftUuid) |
| `chorus_pm_assign_task` | Assign a task to a Developer Agent |
| `chorus_pm_create_document` | Create standalone document |
| `chorus_pm_update_document` | Update document content (increments version) |
| `chorus_update_task` (with `addDependsOn` / `removeDependsOn`) | Manage dependencies between existing tasks (with cycle detection) |
| `chorus_add_reference` / `chorus_update_reference` / `chorus_remove_reference` | Attach/edit/remove external-evidence web links (docs/repo/issue_pr/paper_blog) on an idea, proposal, or task; also attachable inline at creation via `references[]` on `chorus_pm_create_idea` / `chorus_pm_create_proposal` / `chorus_create_tasks`. No read tool — they come back inline on `chorus_get_idea` / `chorus_get_proposal` / `chorus_get_task` |

**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](../research-chorus/SKILL.md)) 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_doc

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.agents/skills

Gates applied: no_behavioural_pass.