/idea

name: idea
description: Chorus Idea workflow — claim ideas, run elaboration rounds, and prepare for proposal creation.
license: AGPL-3.0
metadata:
  author: chorus
  version: "0.16.0"
  category: project-management
  mcp_server: chorus

Idea Skill

This skill covers the **Ideation** stage of the AI-DLC workflow: claiming Ideas, running structured elaboration rounds to clarify requirements, and preparing for Proposal creation.

---

Overview

Ideas are the starting point of the AI-DLC pipeline. Humans (or Admin agents) create Ideas describing what they need. The PM Agent claims an Idea, runs elaboration to clarify requirements, and then moves on to `/proposal` to create a Proposal with document and task drafts.

**Idea status lifecycle (3 stored states):**

open --> elaborating --> elaborated

All post-elaboration progress (planning, building, verifying, done) is **derived** from the state of linked Proposals and Tasks. No agent should set Idea status directly beyond elaboration -- all transitions are side-effects of claiming, releasing, or completing elaboration.

---

Tools

**Idea Management:**

| Tool | Purpose | |------|---------| | `chorus_pm_create_idea` | Create a new idea in a project (on behalf of humans). Optional `parentUuid` derives a child idea from an existing same-project idea (single-parent lineage). | | `chorus_edit_idea` | Edit an existing idea's title, description, and/or lineage parent. `parentUuid`: another same-project idea to reparent under, `null` to detach to top-level, omit to leave unchanged (cycle-checked + same-project). Single-parent **weak** lineage — a parent shows a read-only `+N derived` rollup but never blocks either idea's flow. Records an "edited" activity and signals presence. | | `chorus_claim_idea` | Claim an open idea (open -> elaborating) | | `chorus_release_idea` | Release a claimed idea (elaborating -> open) | | `chorus_move_idea` | Move an Idea to a different Project. Cascade-migrates the Idea **and its full lineage subtree** (all descendant Ideas; the moved root is detached from any parent left behind), all linked Proposals (any status), all materialized Documents and Tasks, and all related Activities atomically. Comments, TaskDependency, AcceptanceCriterion, AgentSession, SessionTaskCheckin, Notification history, and Task assignees are NOT modified. Returns `moved: { ideas, proposals, documents, tasks, activities }` counts. Requires `idea:write` only — no project-level checks. |

**Requirements Elaboration:**

| Tool | Purpose | |------|---------| | `chorus_pm_start_elaboration` | Generate an elaboration round (first, follow-up, or appended-after-resolution) | | `chorus_pm_validate_elaboration` | Mark the whole elaboration complete (requires `idea:admin`; requires human confirmation first) | | `chorus_pm_skip_elaboration` | Skip elaboration for trivially clear Ideas | | `chorus_answer_elaboration` | Submit answers for an elaboration round (`roundUuid` optional — auto-locates the active round) | | `chorus_get_elaboration` | Get full elaboration state (rounds, questions, answers) |

**Shared tools** (checkin, query, comment, search, notifications): see `/chorus`

---

Workflow

Step 1: Check In

chorus_checkin()

Review your persona, current assignments, and pending work counts.

Step 2: Find Work

chorus_get_available_ideas({ projectUuid: "<project-uuid>" })

Or check existing assignments:

chorus_get_my_assignments()

Step 3: Claim an Idea

Claiming automatically transitions the Idea to `elaborating` status:

chorus_claim_idea({ ideaUuid: "<idea-uuid>" })

Step 4: Gather Context

Before elaborating, understand the full picture:

1. **Read the idea in detail:**

   chorus_get_idea({ ideaUuid: "<idea-uuid>" })

2. **Read existing project documents** (for context, tech stack, conventions):

   chorus_get_documents({ projectUuid: "<project-uuid>" })
   chorus_get_document({ documentUuid: "<doc-uuid>" })

3. **Review past proposals** (to understand patterns and standards):

   chorus_get_proposals({ projectUuid: "<project-uuid>", status: "approved" })

4. **Check existing tasks** (to avoid duplication):

   chorus_list_tasks({ projectUuid: "<project-uuid>" })

5. **Read comments** on the idea for additional context:

   chorus_get_comments({ targetType: "idea", targetUuid: "<idea-uuid>" })

Step 4.4: Attach External References

**Make attaching external references a reflex, not an afterthought.** While gathering context you will often surface external links that are *evidence* for this Idea — a precedent issue or PR, a reference implementation, official documentation, a paper or blog post. The moment you see one, attach it as a reference artifact. References are read back inline by `chorus_get_idea` / `chorus_get_proposal` / `chorus_get_task`, so they carry the "why" forward to whoever picks up the proposal or task next.

**Prefer attaching at creation time** via the inline `references[]` param on `chorus_pm_create_idea` (and later `chorus_pm_create_proposal` / `chorus_create_tasks`) rather than a post-hoc `chorus_add_reference`. Attaching at create means the evidence is present from the first read; use `chorus_add_reference` only when the link surfaces after the entity already exists.

**Pick the `type` that fits the link:**

| `type` | Use for | |--------|---------| | `docs` | Official documentation — framework / API / library reference | | `repo` | A reference implementation or source repository | | `issue_pr` | An issue or pull-request thread — precedent, prior art, the delivering PR | | `paper_blog` | A paper or blog post — background or design rationale |

**Example** — a new localization Idea, attaching the precedent PR and the framework docs inline at creation:

chorus_pm_create_idea({
  projectUuid: "<project-uuid>",
  title: "Add Portuguese (pt) locale",
  content: "...",
  references: [