@chorus-aidlc/chorus-openclaw-plugin 0.4.0 → 0.5.3

package/skills/idea/SKILL.md

@@ -1,37 +1,33 @@
 ---
 name: idea
-description: Chorus Idea workflow — claim ideas, run elaboration, and prepare for proposal.
+description: Chorus Idea workflow — claim ideas, run elaboration rounds, and prepare for proposal creation.
+license: AGPL-3.0
 metadata:
-  openclaw:
-    emoji: "💡"
+  author: chorus
+  version: "0.9.4"
+  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.
 
+> **Tool namespace:** Chorus tools are exposed by the connected MCP server under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_get_idea`). Bare names are used below for readability — prepend `chorus__` when invoking. See `/chorus` for the full rule.
+
 ---
 
 ## 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 Lifecycle
+**Idea status lifecycle (3 stored states):**
 
 ```
-open --> elaborating --> proposal_created --> completed
-                   \--> closed
+open --> elaborating --> elaborated
 ```
 
-| Status | Meaning |
-|--------|---------|
-| `open` | Idea is available for an agent to claim |
-| `elaborating` | An agent has claimed the idea and is gathering requirements |
-| `proposal_created` | A Proposal has been created from this idea |
-| `completed` | The resulting Proposal was approved and work is done |
-| `closed` | Idea was closed without implementation |
-
-Claiming an idea automatically transitions it from `open` to `elaborating`.
+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.
 
 ---
 
@@ -41,40 +37,25 @@ Claiming an idea automatically transitions it from `open` to `elaborating`.
 
 | Tool | Purpose |
 |------|---------|
+| `chorus_pm_create_idea` | Create a new idea in a project (on behalf of humans) |
 | `chorus_claim_idea` | Claim an open idea (open -> elaborating) |
-| `chorus_get_available_ideas` | List open ideas in a project available to claim |
-| `chorus_get_idea` | Get detailed information for a single idea |
-| `chorus_get_ideas` | List ideas in a project with optional status filter |
-| `chorus_pm_create_idea` | Create a new idea in a project |
-| `chorus_move_idea` | Move an idea to a different project (also moves linked draft/pending proposals) |
+| `chorus_release_idea` | Release a claimed idea (elaborating -> open) |
+| `chorus_move_idea` | Move an Idea to a different Project. Cascade-migrates the Idea, 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: { proposals, documents, tasks, activities }` counts. Requires `idea:write` only — no project-level checks. |
 
 **Requirements Elaboration:**
 
 | Tool | Purpose |
 |------|---------|
-| `chorus_start_elaboration` | Start an elaboration round with structured questions |
-| `chorus_validate_elaboration` | Validate answers — empty issues = resolved, with issues = follow-up round |
-| `chorus_answer_elaboration` | Submit answers for an elaboration round |
-| `chorus_get_elaboration` | Get full elaboration state (all rounds, questions, answers) |
+| `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`
 
 ---
 
-## SSE Wake Events (OpenClaw-Specific)
-
-OpenClaw is a single-agent model with SSE-driven wake. The following notification events trigger the agent to wake and act:
-
-| SSE Event | Trigger | Agent Action |
-|-----------|---------|--------------|
-| `idea_claimed` | An idea is assigned to you | Wake, review the idea with `chorus_get_idea`, claim it if not auto-claimed |
-| `elaboration_requested` | Elaboration round started on an idea you own | Wake, review questions with `chorus_get_elaboration` |
-| `elaboration_answered` | Answers submitted for your elaboration round | Wake, review answers, validate or create follow-up round |
-
-When an SSE event fires, the plugin's event router fetches the notification details and triggers the agent with context (ideaUuid, projectUuid, action). You do not need to poll — work arrives via these events.
-
----
-
 ## Workflow
 
 ### Step 1: Check In
@@ -135,168 +116,173 @@ Before elaborating, understand the full picture:
    chorus_get_comments({ targetType: "idea", targetUuid: "<idea-uuid>" })
    ```
 
-### Step 5: Elaborate on the Idea
+### Step 4.5: Brainstorm Mode (Optional Prelude)
+
+If the Idea is fuzzy and you'd struggle to enumerate concrete multi-choice questions, offer the user a brainstorm prelude before structured elaboration.
 
-**Every Idea should go through elaboration.** Elaboration improves Proposal quality and reduces rejection cycles.
+> **OpenClaw note:** there is no `AskUserQuestion` primitive. Ask the user once **as a plain-text prompt** whether they want to brainstorm first or jump straight to structured elaboration, e.g.:
+>
+> > "This idea is still fuzzy. Do you want to (A) brainstorm directions together first, or (B) go straight to structured elaboration? Reply A or B."
 
-#### Elaboration Depth
+- **"Already clear" (B):** Skip to Step 5.
+- **"Brainstorm first" (A):** Invoke the `/brainstorm` skill. See `/brainstorm` for the dialogue cadence and synthesis rules — do NOT re-implement them here.
 
-Determine depth based on idea complexity:
+When `/brainstorm` returns, you own the lifecycle decision (the brainstorm skill deliberately leaves it to you):
 
-- `"minimal"` — 2-4 questions (small features, minor enhancements)
-- `"standard"` — 5-10 questions (typical new features)
-- `"comprehensive"` — 10-15 questions (large features, architectural changes)
+- If the synthesized round answers cover everything → obtain human confirmation, then call `chorus_pm_validate_elaboration` to mark the elaboration complete. (Requires `idea:admin` — see Step 5.6 if your key is `pm_agent`-preset.)
+- If gaps remain → call `chorus_pm_start_elaboration` again to open a structured Round 2. Pick the depth yourself — do NOT re-prompt the user.
 
-#### Question Categories
+Either outcome ends Step 4.5; skip Step 5.
 
-`functional`, `non_functional`, `business_context`, `technical_context`, `user_scenario`, `scope`
+### Step 5: Elaborate on the Idea
+
+**Every Idea should go through elaboration.** Skip only when requirements are completely unambiguous (e.g., bug fix with clear steps). Elaboration improves Proposal quality and reduces rejection cycles.
 
-#### Starting an Elaboration Round
+#### Simple Ideas (skip elaboration)
 
-> **Note:** Do NOT include an "Other" option in your questions. The UI automatically adds a free-text "Other" option to every question.
+You may skip elaboration, but **you MUST ask the user for permission first** before calling `chorus_pm_skip_elaboration`. On OpenClaw, ask as a plain-text prompt (e.g. "This idea has clear reproduction steps. OK to skip elaboration? Reply yes/no."). Never skip on your own judgment alone.
 
 ```
-chorus_start_elaboration({
+chorus_pm_skip_elaboration({
   ideaUuid: "<idea-uuid>",
-  depth: "standard",
-  questions: [
-    {
-      id: "q1",
-      text: "What user roles should have access to this feature?",
-      category: "functional",
-      options: [
-        { id: "a", label: "All users" },
-        { id: "b", label: "Admin only" },
-        { id: "c", label: "Role-based (configurable)" }
-      ]
-    },
-    {
-      id: "q2",
-      text: "What is the expected data volume?",
-      category: "non_functional",
-      options: [
-        { id: "a", label: "Low (<1000 records)" },
-        { id: "b", label: "Medium (1K-100K records)" },
-        { id: "c", label: "High (>100K records)" }
-      ]
-    }
-  ]
+  reason: "Bug fix with clear reproduction steps"
 })
 ```
 
-This triggers an `elaboration_requested` SSE event to stakeholders.
+#### Standard/Complex Ideas (run elaboration)
 
-#### Submitting Answers
+> **Elaboration is a loop, not a straight line.** Steps 2–5 below are **one round**. Keep looping back to `chorus_pm_start_elaboration` (a new round) until every open question is settled, then resolve **once** in Step 6. You re-enter the loop whenever:
+> - the answers to a round **derive new questions** or surface a contradiction/gap, **or**
+> - at the resolve gate (Step 5d / Step 6) the **human raises a new concern or correction** (a plain-text reply on OpenClaw).
+>
+> Each new round is just another `chorus_pm_start_elaboration` call — there is no separate "follow-up" flag, and you do not resolve until the loop is genuinely done. Round cap is 10.
 
-When answers arrive (via `elaboration_answered` SSE wake event or manual flow):
+1. **Determine depth** based on idea complexity:
+   - `"minimal"` — 2-4 questions (small features, minor enhancements)
+   - `"standard"` — 5-10 questions (typical new features)
+   - `"comprehensive"` — 10-15 questions (large features, architectural changes)
 
-```
-chorus_answer_elaboration({
-  ideaUuid: "<idea-uuid>",
-  roundUuid: "<round-uuid>",
-  answers: [
-    { questionId: "q1", selectedOptionId: "c", customText: null },
-    { questionId: "q2", selectedOptionId: null, customText: "Custom hybrid approach" }
-  ]
-})
-```
+2. **Create elaboration questions:**
 
-Answer format:
-- **Select an option**: `selectedOptionId: "a", customText: null`
-- **Select an option + add a note**: `selectedOptionId: "a", customText: "additional context"`
-- **Choose "Other" (free text)**: `selectedOptionId: null, customText: "your answer"` — customText is required when no option is selected
+   > **Note:** Do NOT include an "Other" option in your questions. Treat the free-text path as always available — a user may answer any question with free text instead of picking an option.
 
-#### @Mention Workflow After Answers
+   ```
+   chorus_pm_start_elaboration({
+     ideaUuid: "<idea-uuid>",
+     depth: "standard",
+     questions: [
+       {
+         id: "q1",
+         text: "What user roles should have access to this feature?",
+         category: "functional",
+         options: [
+           { id: "a", label: "All users" },
+           { id: "b", label: "Admin only" },
+           { id: "c", label: "Role-based (configurable)" }
+         ]
+       }
+     ]
+   })
+   ```
 
-After answers are submitted, **@mention the answerer** with a summary of your understanding. This prevents misinterpretation before you validate.
+3. **Present questions to the user as plain text (OpenClaw has no `AskUserQuestion`).** Render each elaboration question and its options as a readable numbered/lettered prompt and ask the user to reply with their selections (and any free-text notes). Example:
 
-1. **Get mentionable info:**
    ```
-   chorus_search_mentionables({ query: "owner-name" })
+   I have a few questions to clarify this idea. Please reply with your choice for each (you can also write a free-text answer):
+
+   1. Which new locales should be prioritized for V1?
+      a) Japanese only — single locale for initial release
+      b) Japanese + Korean — two East Asian locales
+      (or describe your own)
+
+   2. ...
    ```
 
-2. **Post a summary comment** on the idea:
+   After the user replies, map their answers back to option IDs and call `chorus_answer_elaboration`. If the user gave a free-text answer that doesn't match an option, set `selectedOptionId: null` and put their text in `customText`.
+
+4. **Submit answers:**
    ```
-   chorus_add_comment({
-     targetType: "idea",
-     targetUuid: "<idea-uuid>",
-     content: "@[Owner Name](user:owner-uuid) I've reviewed the elaboration answers. Here's my understanding:\n\n- Key requirement 1: ...\n- Key requirement 2: ...\n\nDoes this match your intent?"
+   chorus_answer_elaboration({
+     ideaUuid: "<idea-uuid>",
+     roundUuid: "<round-uuid>",
+     answers: [
+       { questionId: "q1", selectedOptionId: "c", customText: null },
+       { questionId: "q2", selectedOptionId: null, customText: "Custom hybrid approach" }
+     ]
    })
    ```
 
-3. **Wait for confirmation** via comments or a `mentioned` SSE event.
+   Answer format:
+   - **Select an option**: `selectedOptionId: "a", customText: null`
+   - **Select an option + add a note**: `selectedOptionId: "a", customText: "additional context"`
+   - **Free text (no option matched)**: `selectedOptionId: null, customText: "your answer"` — customText is required when no option is selected
 
-4. **Based on the response:**
-   - **Confirmed** — Proceed to validate with empty issues
-   - **Additions/corrections** — Incorporate feedback, optionally start a follow-up round
-   - **Unclear** — Ask clarifying questions via another comment
+   > `roundUuid` is **optional** on `chorus_answer_elaboration`. Omit it and the service auto-locates the Idea's single active (`pending_answers`) round. Pass it explicitly only when you need to target a specific round.
 
-#### Validating the Elaboration
+5. **Review answers and confirm with the owner (@mention flow):**
 
-When answers are satisfactory:
+   After answers are submitted, **@mention the answerer** (typically the agent's owner) with a summary of your understanding. This prevents misinterpretation before you validate.
 
-```
-chorus_validate_elaboration({
-  ideaUuid: "<idea-uuid>",
-  roundUuid: "<round-uuid>",
-  issues: []
-})
-```
+   a. **Get owner info** from checkin response (`agent.owner`) or search:
+      ```
+      chorus_search_mentionables({ query: "owner-name" })
+      ```
 
-If issues are found (contradictions, ambiguities, incomplete answers), include them and provide follow-up questions for a new round:
+   b. **Post a summary comment** on the idea:
+      ```
+      chorus_add_comment({
+        targetType: "idea",
+        targetUuid: "<idea-uuid>",
+        content: "@[Owner Name](user:owner-uuid) I've reviewed the elaboration answers. Here's my understanding:\n\n- Key requirement 1: ...\n- Key requirement 2: ...\n\nDoes this match your intent?"
+      })
+      ```
 
-```
-chorus_validate_elaboration({
-  ideaUuid: "<idea-uuid>",
-  roundUuid: "<round-uuid>",
-  issues: [
-    { questionId: "q1", type: "ambiguity", description: "Role-based access selected but no roles defined" }
-  ],
-  followUpQuestions: [
-    {
-      id: "fq1",
-      text: "Which specific roles should have access?",
-      category: "functional",
-      options: [
-        { id: "a", label: "Admin + Editor" },
-        { id: "b", label: "All authenticated users" }
-      ]
-    }
-  ]
-})
-```
+   c. **Wait for confirmation** via comments.
 
-This starts a new elaboration round, triggering another `elaboration_requested` event. The cycle repeats until all issues are resolved.
+   d. **Based on the response — this is the loop decision point:**
+      - **Confirmed, nothing left to discuss** — Treat this as the human confirmation required to resolve; proceed to Step 6 and call `chorus_pm_validate_elaboration`.
+      - **Human raises a new concern / correction / question** — Do **NOT** resolve. Loop back: open a **new round** with `chorus_pm_start_elaboration` capturing the new questions, collect answers (Steps 2–5 again), and re-confirm. Repeat until the human has no remaining concerns.
+      - **The answers themselves derived new questions or a contradiction** — Same as above: loop back to `chorus_pm_start_elaboration` for another round before resolving.
+      - **Unclear** — Ask clarifying questions via another comment, then continue the loop.
 
-**Validation issue types:** `contradiction`, `ambiguity`, `incomplete`
+6. **Resolve the elaboration (the single commit gate — only when the loop is done):**
 
-#### Multi-Round Elaboration
+   Resolving marks the **whole elaboration phase** complete — it sets `idea.elaborationStatus = "resolved"` (Idea → `elaborated`), which is the gating signal that lets a downstream Proposal be submitted. It is an **Idea-level** action (takes only `ideaUuid`, does not target a round). Resolve **once**, only after the Step 5d loop has fully settled — every derived question answered and the human has no remaining concerns. If anything is still open, go back to `chorus_pm_start_elaboration` instead of resolving.
 
-Complex ideas may require multiple rounds:
+   > **Precondition:** resolve requires the Idea to have at least one round and **every** round to be fully answered (none left in `pending_answers`). If a round still has open questions, answer it (or it'll be rejected).
 
-1. Round 1: Broad scoping questions (functional, scope)
-2. Round 2: Follow-up on ambiguous answers (technical_context)
-3. Round 3: Final confirmation of edge cases (user_scenario)
+   > **⚠️ Human confirmation required.** Outside YOLO automation you MUST obtain explicit human confirmation before resolving (a plain-text yes/no prompt is fine on OpenClaw). The "Confirmed" reply in step 5d above counts as that confirmation. Never resolve on your own judgment alone.
 
-Each round preserves the full history. Use `chorus_get_elaboration` at any time to see all rounds and their status.
+   > **Permission (N1): `chorus_pm_validate_elaboration` requires `idea:admin`.** The `pm_agent` preset only grants `idea:write`, so a PM-preset agent **cannot** resolve — it must hand off to an `admin_agent`-preset agent (or an admin-preset API key) to perform the resolve. If your key lacks `idea:admin`, surface this to the human and request the handoff instead of failing silently.
 
-#### Checking Elaboration Status
+   > **Assignee precondition (N2):** the resolving actor must be the Idea's **assignee**. A separate human reviewer resolving a PM-owned Idea therefore needs **both** `idea:admin` **and** to be assigned the Idea (claim/reassign it first). Admin permission alone is not enough.
 
-```
-chorus_get_elaboration({ ideaUuid: "<idea-uuid>" })
-```
+   ```
+   chorus_pm_validate_elaboration({
+     ideaUuid: "<idea-uuid>"
+   })
+   ```
+
+   **Want a follow-up round instead of resolving?** Just call `chorus_pm_start_elaboration` again — there is no separate "open a round" flag. It works while still `elaborating` (a normal follow-up round) and, after you've already resolved, as an **appended round** (`isAppended: true`) that keeps the Idea `elaborated` and never blocks an in-flight Proposal. Per-question issue tagging no longer exists.
+
+7. **Check elaboration status** at any time:
+   ```
+   chorus_get_elaboration({ ideaUuid: "<idea-uuid>" })
+   ```
+
+**Elaboration as audit trail:** Even if the user discusses requirements with you outside the formal elaboration flow, record key decisions as elaboration rounds so they are persisted and visible to the team.
 
-Returns all rounds, questions, answers, and a progress summary.
+**Question categories:** `functional`, `non_functional`, `business_context`, `technical_context`, `user_scenario`, `scope`
 
 ---
 
 ## Tips
 
 - When combining multiple ideas, explain how they relate in the proposal description
-- Elaboration improves Proposal quality — run it for all non-trivial ideas
+- Elaboration improves Proposal quality — don't skip it unless the requirements are trivially clear
+- Present interactive questions as plain text and collect free-text replies — OpenClaw has no `AskUserQuestion` primitive
 - Record decisions made in conversation as elaboration rounds for auditability
-- Always @mention the owner to confirm understanding before validating
-- SSE events mean you do not need to poll — the plugin wakes you when action is needed
+- Always @mention the owner to confirm understanding before resolving
 
 ---