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

package/skills/proposal/SKILL.md

@@ -1,15 +1,20 @@
 ---
 name: proposal
-description: Chorus Proposal workflow — create proposals with document & task drafts, manage DAG, submit for review.
+description: Chorus Proposal workflow — create proposals with document and task drafts, manage dependency DAG, validate and submit for review.
+license: AGPL-3.0
 metadata:
-  openclaw:
-    emoji: "📋"
+  author: chorus
+  version: "0.9.4"
+  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.
 
+> **Tool namespace:** Chorus tools are exposed by the connected MCP server under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_pm_create_proposal`). Bare names are used below for readability — prepend `chorus__` when invoking. See `/chorus` for the full rule.
+
 ---
 
 ## Overview
@@ -17,25 +22,9 @@ This skill covers the **Planning** stage of the AI-DLC workflow: creating Propos
 After an Idea's elaboration is resolved (see `/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 --> Admin review
-```
-
-### Proposal Lifecycle
-
-```
-draft --> pending --> approved
-                \--> rejected --> (revise drafts) --> pending  (resubmit cycle)
+Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit --> Reviewer --> Admin /review
 ```
 
-| Status | Meaning |
-|--------|---------|
-| `draft` | Proposal is being built — add/edit document and task drafts |
-| `pending` | Submitted for Admin review |
-| `approved` | Admin approved — drafts materialized into real Documents and Tasks |
-| `rejected` | Admin rejected with feedback — revise drafts and resubmit |
-
-A rejected proposal returns to `draft` status. Fix issues based on the review note, then validate and resubmit.
-
 ---
 
 ## Tools
@@ -44,60 +33,48 @@ A rejected proposal returns to `draft` status. Fix issues based on the review no
 
 | Tool | Purpose |
 |------|---------|
-| `chorus_create_proposal` | Create an empty proposal container linked to input ideas |
-| `chorus_get_proposal` | Get full proposal details including all document and task drafts |
-| `chorus_validate_proposal` | Validate proposal completeness (returns errors, warnings, info) |
-| `chorus_submit_proposal` | Submit proposal for Admin approval (draft -> pending) |
+| `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_add_document_draft` | Add a document draft to the proposal |
-| `chorus_update_document_draft` | Update document draft title, type, or content |
-| `chorus_remove_document_draft` | Remove a document draft from the proposal |
+| `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_add_task_draft` | Add a task draft (returns draftUuid for dependency chaining) |
-| `chorus_update_task_draft` | Update task draft fields or dependencies |
-| `chorus_remove_task_draft` | Remove a task draft from the proposal |
+| `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 with intra-batch dependencies (also supports Quick Task mode) |
-| `chorus_update_task` | Update task fields, dependencies, or status |
+| `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`) | Add or remove task dependencies (with cycle detection) |
 
 **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 on proposals:
-
-| SSE Event | Trigger | Agent Action |
-|-----------|---------|--------------|
-| `proposal_rejected` | Admin rejected your proposal | Wake, read review note, revise drafts, resubmit |
-| `proposal_approved` | Admin approved your proposal | Wake, update idea status, check new tasks ready for work |
-
-When a proposal is rejected, the event router provides the review note and instructs the agent to fix issues. When approved, it notifies that documents and tasks have been created.
-
----
-
 ## Workflow
 
 ### Step 1: Create an Empty Proposal
 
-Create the proposal container first, then incrementally add drafts.
+**Recommended approach:** Create the proposal container first without any drafts, then incrementally add document and task drafts one by one.
 
 ```
-chorus_create_proposal({
+chorus_pm_create_proposal({
   projectUuid: "<project-uuid>",
   title: "Implement <feature name>",
   description: "Analysis and implementation plan for Idea #xxx",
@@ -108,15 +85,27 @@ chorus_create_proposal({
 
 **Multiple Ideas:** You can combine multiple ideas into one proposal by passing multiple UUIDs in `inputUuids`.
 
-### Step 2: Add Document Drafts
+### Step 1.5: Detect OpenSpec mode
 
-Add document drafts one at a time.
+Before authoring document drafts, **load the `openspec-aware` skill** and run its **§1 inline detection** (three checks — `CHORUS_OPENSPEC_MODE != "off"`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`).
 
-**Document types:** `prd`, `tech_design`, `adr`, `spec`, `guide`
+> **OpenClaw note:** there is no Claude Code SessionStart hook to precompute `CHORUS_OPENSPEC_ACTIVE`. You must run the three checks yourself, inline, every time you reach this step. See `openspec-aware` §1.
+
+Branch on the result:
+
+- **OpenSpec active (all three checks pass)** → follow `openspec-aware` §3. Pick `$SLUG`, scaffold `openspec/changes/<slug>/`, author `proposal.md` / `design.md` / `specs/<capability>/spec.md` locally, then create the proposal container (Step 1 above) with the literal line `OpenSpec change slug: <slug>` in `description`, and mirror each local file into a document draft.
+
+  > **⛔ Mandatory in OpenSpec mode:** mirror calls go through the `chorus-api.sh` wrapper with `content` produced by `json_encode_file` — see `openspec-aware` §3.6. Do **not** call `chorus_pm_add_document_draft` directly from the MCP harness with a hand-typed `content` field. Re-typing thousands of lines through the LLM burns 20k+ content tokens per proposal and breaks byte-equality with the local source of truth (`openspec-aware` §2 Rule 1 explains the full reasoning). Skip Step 2 below when in OpenSpec mode — the wrapper-based flow in `openspec-aware` §3.6 replaces it for documents.
+
+- **OpenSpec inactive (any check fails, or `CHORUS_OPENSPEC_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_add_document_draft({
+chorus_pm_add_document_draft({
   proposalUuid: "<proposal-uuid>",
   type: "prd",
   title: "PRD: <Feature Name>",
@@ -124,7 +113,7 @@ chorus_add_document_draft({
 })
 
 # Add Tech Design
-chorus_add_document_draft({
+chorus_pm_add_document_draft({
   proposalUuid: "<proposal-uuid>",
   type: "tech_design",
   title: "Tech Design: <Feature Name>",
@@ -132,94 +121,71 @@ chorus_add_document_draft({
 })
 ```
 
-#### Document Type Guidelines
+**Document types:** `prd`, `tech_design`, `adr`, `spec`, `guide`
 
-| Type | Focus | When to Use |
-|------|-------|-------------|
-| `prd` | What and why — requirements, user stories, scope | Every feature proposal |
-| `tech_design` | How — architecture, data model, API design | Features with non-trivial implementation |
-| `adr` | Architecture Decision Record — decision context, options, outcome | Significant architectural choices |
-| `spec` | Detailed specification — protocols, formats, interfaces | API contracts, data formats |
-| `guide` | How-to guide — setup, usage, runbooks | Operational procedures |
+### Step 3: Add Task Drafts
 
-### Step 3: Add Task Drafts with Dependency DAG
+Add task drafts one at a time. The response returns the new draft's `draftUuid` — use it directly for `dependsOnDraftUuids` in subsequent drafts.
 
-Add task drafts one at a time. Each response returns the new draft's `draftUuid` — use it in `dependsOnDraftUuids` for subsequent drafts to build the dependency DAG.
+**`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 (no dependencies) -> response includes { draftUuid, draftTitle }
-chorus_add_task_draft({
+# First task -> response includes { draftUuid, draftTitle }
+chorus_pm_add_task_draft({
   proposalUuid: "<proposal-uuid>",
-  title: "Create database schema",
-  description: "Add new tables for ...",
+  title: "Implement <component>",
+  description: "Detailed description of what to build...",
   priority: "high",
-  storyPoints: 2,
+  storyPoints: 3,
   acceptanceCriteriaItems: [
-    { description: "Migration runs without errors", required: true },
-    { description: "Rollback migration works", required: true }
+    { description: "Criteria 1", required: true },
+    { description: "Criteria 2", required: true }
   ]
 })
 
 # Second task — depends on first
-chorus_add_task_draft({
+chorus_pm_add_task_draft({
   proposalUuid: "<proposal-uuid>",
-  title: "Implement API endpoints",
-  description: "REST endpoints for ...",
-  priority: "high",
-  storyPoints: 4,
-  acceptanceCriteriaItems: [
-    { description: "All endpoints return correct responses", required: true },
-    { description: "Input validation covers edge cases", required: true },
-    { description: "OpenAPI spec updated", required: false }
-  ],
-  dependsOnDraftUuids: ["<draftUuid-from-first-task>"]
-})
-
-# Third task — depends on second
-chorus_add_task_draft({
-  proposalUuid: "<proposal-uuid>",
-  title: "Write integration tests",
-  description: "End-to-end tests covering ...",
+  title: "Write tests for <component>",
+  description: "Unit and integration tests...",
   priority: "medium",
   storyPoints: 2,
   acceptanceCriteriaItems: [
     { description: "Test coverage > 80%", required: true }
   ],
-  dependsOnDraftUuids: ["<draftUuid-from-second-task>"]
+  dependsOnDraftUuids: ["<draftUuid-from-first-task>"]
 })
 ```
 
-**Task priority:** `low`, `medium`, `high`
+> 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.
 
-**Dependency DAG rules:**
-- `dependsOnDraftUuids` references other task drafts *within the same proposal*
-- Dependencies form a Directed Acyclic Graph (DAG) — no circular dependencies allowed
-- Tasks without dependencies are assumed parallelizable
-- On approval, draft dependencies become real task dependencies
+**Task priority:** `low`, `medium`, `high`
 
 ### Step 4: Review and Refine Drafts
 
 ```
-# Review current state
-chorus_get_proposal({ proposalUuid: "<proposal-uuid>" })
+# 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_update_document_draft({
+chorus_pm_update_document_draft({
   proposalUuid: "<proposal-uuid>",
   draftUuid: "<draft-uuid>",
   content: "Updated content..."
 })
 
-# Update a task draft (including changing dependencies)
-chorus_update_task_draft({
+# 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 that is no longer needed
-chorus_remove_task_draft({
+# Remove a draft
+chorus_pm_remove_task_draft({
   proposalUuid: "<proposal-uuid>",
   draftUuid: "<draft-uuid>"
 })
@@ -227,24 +193,21 @@ chorus_remove_task_draft({
 
 ### Step 5: Validate and Submit
 
-**Always validate before submitting.** Validation catches errors that would block approval.
+Before submitting, validate to preview issues:
 
 ```
-chorus_validate_proposal({ proposalUuid: "<proposal-uuid>" })
+chorus_pm_validate_proposal({ proposalUuid: "<proposal-uuid>" })
 ```
 
-Returns `{ valid, issues }` where issues have levels:
-- **error** — Must fix before submitting (e.g., missing required fields, circular dependencies)
-- **warning** — Should fix but won't block submission (e.g., missing story points)
-- **info** — Suggestions (e.g., consider adding acceptance criteria)
+Returns `{ valid, issues }` with error, warning, and info levels. Fix errors before submitting.
 
-When validation passes (no errors):
+When validation passes:
 
 ```
-chorus_submit_proposal({ proposalUuid: "<proposal-uuid>" })
+chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })
 ```
 
-This changes the status from `draft` to `pending`. An Admin will review it.
+This changes the status from `draft` to `pending`. An Admin will review it (see `/review`).
 
 Add a comment explaining your reasoning:
 
@@ -252,74 +215,106 @@ Add a comment explaining your reasoning:
 chorus_add_comment({
   targetType: "proposal",
   targetUuid: "<proposal-uuid>",
-  content: "This proposal addresses Idea #xxx. Key decisions: ..."
+  content: "This proposal covers... Key decisions: ..."
 })
 ```
 
-### Step 6: Handle Rejection (SSE-Driven)
+### Step 5.5: Run the Proposal Reviewer (inline — no hook on OpenClaw)
+
+> **OpenClaw difference:** the Claude Code plugin relies on a PostToolUse hook to inject a "spawn the reviewer" reminder after `chorus_pm_submit_proposal`. **OpenClaw has no such hook.** Run the reviewer step **inline**, right here, immediately after submitting. Do not wait for an injected reminder — it will never come.
 
-If the proposal is rejected, the `proposal_rejected` SSE event wakes the agent with the review note. To handle:
+Obtain an independent VERDICT before considering the proposal ready for Admin approval:
 
-1. **Read the feedback:**
+1. **Preferred — spawn a reviewer sub-agent.** Use the OpenClaw `sessions_spawn` tool to spawn a sub-agent whose `task` tells it to **invoke the `/proposal-reviewer` skill** (bundled with this plugin) against the proposal, then wait for it (poll the `subagents` tool or use `sessions_yield` — do NOT detach; you need its VERDICT before proceeding). The sub-agent inherits the plugin skills, so `/proposal-reviewer` is available to it; that skill is read-only and posts a `VERDICT:` comment on the proposal. Example task prompt:
+   > `Run the /proposal-reviewer skill to review proposalUuid <uuid>. Read the proposal, its documents, the idea, and the elaboration; classify findings BLOCKER/NOTE; post your VERDICT comment on the proposal when done.`
+
+2. **Fallback — review it yourself.** If `sessions_spawn` is unavailable on your host (spawning disabled by policy), perform the review yourself as a **focused, read-only pass** following the `/proposal-reviewer` skill's procedure: read `chorus_get_proposal`, `chorus_get_comments`, the linked idea, and the elaboration; check document completeness, task granularity, AC ↔ requirement coverage, the dependency DAG, and integration checkpoints; then record the result yourself via `chorus_add_comment` ending with a `VERDICT:` line (PASS / PASS WITH NOTES / FAIL). Do NOT modify any drafts during this pass — it is review-only. Use the same BLOCKER vs NOTE classification the `/proposal-reviewer` skill defines.
+
+3. **Read the VERDICT and act:**
    ```
-   chorus_get_proposal({ proposalUuid: "<proposal-uuid>" })
    chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
    ```
+   Find the most recent comment containing `VERDICT:`:
+   - **PASS** / **PASS WITH NOTES** — proceed; an Admin can approve (notes are non-blocking).
+   - **FAIL** — go to Step 6 and fix the BLOCKERs before resubmitting.
+
+If you spawned a sub-agent and no new `VERDICT:` comment appears after it returns, it likely exhausted its turn budget. Respawn it ONCE with a concise-budget hint: *"Stay within turn budget. Skip deep verification. Fetch proposal + comments + idea only, skim for obvious BLOCKERs, and post your VERDICT within the first 10 turns."* If still no VERDICT, fall back to reviewing manually (Step 5.5 fallback) and post the VERDICT yourself.
+
+### Step 6: Handle Feedback
+
+After the reviewer runs (or an Admin reviews), if the VERDICT is **FAIL** or the Admin rejects, you need to revise and resubmit.
 
-2. **Revise the drafts** based on feedback:
+**IMPORTANT:** A proposal in `pending` status cannot be edited. You **must** reject it first to return it to `draft` status before editing any drafts.
+
+1. **Read feedback:**
    ```
-   chorus_update_task_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<draft-uuid>", ... })
-   chorus_update_document_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<draft-uuid>", ... })
+   chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })
+   chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
    ```
+   Identify BLOCKERs from the reviewer VERDICT or rejection note.
 
-3. **Validate and resubmit:**
+2. **Reject the proposal** (self-reject your own, or ask admin to reject someone else's):
    ```
-   chorus_validate_proposal({ proposalUuid: "<proposal-uuid>" })
-   chorus_submit_proposal({ proposalUuid: "<proposal-uuid>" })
+   chorus_pm_reject_proposal({
+     proposalUuid: "<proposal-uuid>",
+     reviewNote: "Reviewer FAIL. Fixing BLOCKERs: <list>"
+   })
    ```
+   This returns the proposal to `draft` status. PM agents can only reject their own proposals; admin agents can reject any proposal.
 
-### Step 7: Post-Approval (SSE-Driven)
+3. **Revise the drafts:**
+   ```
+   chorus_pm_update_document_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<uuid>", content: "..." })
+   chorus_pm_update_task_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<uuid>", ... })
+   ```
 
-When the `proposal_approved` SSE event fires:
-- Document drafts have become real Documents
-- Task drafts have become real Tasks (status: `open`, ready for developers)
+4. **Resubmit and re-run the reviewer** (Step 5 → Step 5.5 again):
+   ```
+   chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })
+   ```
 
-You can now assign tasks to developer agents:
+### Step 7: Post-Approval
 
-```
-chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uuid>" })
-```
+When the Admin approves:
+- Document drafts become real Documents
+- Task drafts become real Tasks (status: `open`, ready for developers)
+- The Idea's displayed status is automatically derived from Proposal and Task progress -- no manual update needed
 
-- Task must be `open` or `assigned`
-- Target agent must have `developer` or `developer_agent` role
-- Use `chorus_search_mentionables` to find the agent UUID
+### Step 8: Manage Task Dependencies (Optional)
 
-### Step 8: Manage Post-Approval Dependencies (Optional)
+After tasks are created, you can manage dependencies:
 
-After tasks are created, you can manage dependencies on existing tasks:
-
-```
-chorus_update_task({
-  taskUuid: "<task-uuid>",
-  addDependsOn: ["<other-task-uuid>"],
-  removeDependsOn: ["<old-dependency-uuid>"]
-})
-```
-
-Or batch create additional tasks with intra-batch dependencies:
+**Batch create tasks with intra-batch dependencies:**
 
 ```
 chorus_create_tasks({
   projectUuid: "<project-uuid>",
   tasks: [
     { draftUuid: "draft-db", title: "Create database schema", priority: "high", storyPoints: 2 },
-    { draftUuid: "draft-api", title: "Implement API endpoints", priority: "high", storyPoints: 4, dependsOnDraftUuids: ["draft-db"] }
+    { draftUuid: "draft-api", title: "Implement API endpoints", priority: "high", storyPoints: 4, dependsOnDraftUuids: ["draft-db"] },
+    { title: "Write integration tests", priority: "medium", storyPoints: 2, dependsOnDraftUuids: ["draft-api"] }
   ]
 })
 ```
 
+**Add/remove dependencies on existing tasks:**
+
+```
+chorus_update_task({ taskUuid: "<task-B-uuid>", addDependsOn: ["<task-A-uuid>"] })
+chorus_update_task({ taskUuid: "<task-B-uuid>", removeDependsOn: ["<task-A-uuid>"] })
+```
+
 Dependencies are validated: same project, no self-dependency, no cycles (DFS detection).
 
+### Step 9: Assign Tasks to Developer Agents (Optional)
+
+```
+chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uuid>" })
+```
+
+- Task must be `open` or `assigned`
+- Target agent must have `task: ["write"]` permission
+
 ---
 
 ## Document Writing Guidelines
@@ -361,6 +356,9 @@ Schema changes, new tables.
 ## API Design
 New/modified endpoints.
 
+## Module Contracts
+Shared conventions across tasks: return value format, error handling pattern, cross-module call points.
+
 ## Implementation Plan
 Step-by-step implementation order.
 
@@ -371,23 +369,34 @@ Potential issues and how to address them.
 ### Task Writing Guidelines
 
 Good tasks are:
-- **Atomic** — One clear deliverable per task
-- **Testable** — Clear acceptance criteria with `acceptanceCriteriaItems`
+- **Module-scoped** — One cohesive functional module per task, not a single function or file
+- **Testable** — Clear, cohesive acceptance criteria are **required** on every task (at least one non-blank item; max 6; group related checks into one criterion but list key coverage, e.g. "All tests pass: service layer unit tests, API integration tests, edge case handling")
 - **Sized** — 1-8 story points (hours of agent work)
-- **Ordered** — Use `dependsOnDraftUuids` to express execution order in the DAG
-- **Descriptive** — Include enough context for a developer agent to start without questions
+- **Ordered** — Use `dependsOnDraftUuids` / `dependsOnTaskUuids` to express execution order
+- **Descriptive** — Include enough context for a developer agent to start without questions. For tasks with cross-module dependencies, reference the tech design's Module Contracts in the AC
+- **Integration checkpoints** — For DAGs with 4+ tasks, include at least one integration checkpoint task at a convergence point whose AC requires end-to-end execution of preceding modules together
+- **Hallucination-aware** — When tasks involve external dependencies, note in the task description that developers should verify specifics (API signatures, CLI flags, config keys, model IDs, etc.) against official docs rather than relying on LLM memory
+
+### Task Granularity
+
+Each task should correspond to an **independently runnable and testable functional module** — not a single function, file, or API endpoint. Avoid splitting closely related functionality into separate tasks; the Chorus workflow overhead per task (claim → implement → self-test → submit → verify) adds up quickly.
+
+**Bad → Good examples:**
+- Bad: `Book Search` + `Book CRUD` (2 tasks) → Good: `Book Management` (1 task covering CRUD + Search for the same entity)
+- Bad: `Chart Rendering` + `Statistics Calculation` (2 tasks) → Good: `Data Analytics` (1 task covering stats + visualization as one module)
 
 ---
 
 ## Tips
 
 - Keep PRD focused on *what* and *why*; tech design focused on *how*
-- Break large features into multiple smaller tasks rather than one monolithic task
+- Break large features into cohesive module-scoped tasks — but avoid over-splitting related functionality into too many tiny tasks
 - Add `storyPoints` to help prioritize and estimate effort
-- Use `acceptanceCriteriaItems` with `required: true` for clear verification criteria
-- Always set up the task dependency DAG — tasks without dependencies are assumed parallelizable
+- Keep acceptance criteria cohesive — group related verifications into one item rather than listing each check separately
+- Always set up task dependency DAG — tasks without dependencies are assumed parallelizable
+- When multiple tasks share data formats or call each other, define contracts in the tech design before writing task AC
 - When combining multiple ideas, explain how they relate in the proposal description
-- SSE events mean you do not need to poll for approval/rejection — the plugin wakes you automatically
+- Always run the reviewer inline after submit (Step 5.5) — OpenClaw has no hook to remind you
 
 ---
 

package/skills/proposal-reviewer/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: proposal-reviewer
+description: Adversarial read-only review of a submitted Chorus proposal — document completeness, task granularity, AC↔requirement coverage, and the dependency DAG. Invoke after a proposal is submitted; ends with a VERDICT comment.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.9.4"
+  category: project-management
+  mcp_server: chorus
+---
+
+# Proposal Reviewer Skill
+
+You have been asked to **review a submitted Chorus proposal**. Your job is **not** to confirm the proposal is good — it's to find what's wrong with it.
+
+> **How you were invoked.** A PM/orchestrator agent spawned you (via the OpenClaw `sessions_spawn` tool) and told you to run this skill against a specific `proposalUuid`. Read it from your task prompt. When you finish, you post one `VERDICT:` comment back to the proposal — that comment IS your deliverable; the parent reads it.
+
+> **Tool namespace.** Chorus tools come from the connected MCP server under a `chorus__` prefix (e.g. `chorus__chorus_get_proposal`, `chorus__chorus_add_comment`). Bare names are used below for readability — prepend `chorus__` when invoking.
+
+## Hard rules (READ-ONLY)
+
+- **You are READ-ONLY.** Do NOT edit, write, or create files. Do NOT run Bash. Do NOT modify the proposal drafts, the project, or any entity except posting your one review comment.
+- **Keep your comment under 800 characters.** PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
+- **Classify every finding** as BLOCKER (blocks implementation) or NOTE (non-blocking). Pseudocode mismatches and cross-doc wording differences are always NOTE.
+- **End with a single line beginning `VERDICT:`** followed by exactly one of `PASS`, `PASS WITH NOTES`, or `FAIL`. Has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
+- **Round 2+:** focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs.
+- **Budget rule:** if you are running low on turns/time, STOP reading immediately and post your current findings as a comment via `chorus_add_comment`. Incomplete findings posted are strictly better than no comment at all.
+- **Do NOT rubber-stamp.** Your value is in finding what the PM missed. Batch all data gathering first, then produce one final comment.
+
+You have two failure patterns. **Rubber-stamping**: skimming and writing "PASS" without checking substance. **Surface-level approval**: seeing a well-structured PRD and assuming tasks match, missing requirements gaps, vague AC, or wrong dependencies. The PM who wrote this is an LLM — it produces plausible-looking proposals with systematic blind spots.
+
+## What you receive
+
+A `proposalUuid` (in your task prompt). Fetch and review the full proposal.
+
+## Review procedure
+
+**Efficiency rule:** Gather ALL data in Steps 1–2 before analyzing. Do not alternate between fetching and writing conclusions. Batch your tool calls.
+
+**Step 1: Gather context**
+```
+chorus_get_proposal({ proposalUuid: "<uuid>", section: "full" })
+chorus_get_comments({ targetType: "proposal", targetUuid: "<uuid>" })
+chorus_get_idea({ ideaUuid: "<idea-uuid>" })
+chorus_get_elaboration({ ideaUuid: "<idea-uuid>" })
+```
+> `chorus_get_proposal` defaults to `section: "basic"` (metadata + a lightweight draft index, no bodies). A full draft review needs the document/task content, so pass `section: "full"` (or fetch `section: "documents"` and `section: "tasks"` separately).
+
+**Step 2: Review documents** — for each document draft, check:
+- **Completeness**: Does the PRD cover functional, non-functional, error scenarios, and edge cases?
+- **Specificity**: Are requirements testable? "Should handle errors gracefully" is not testable.
+- **Tech feasibility**: Does the architecture make sense? Missing auth, race conditions, no error handling?
+- **Module contracts**: If multiple tasks share interfaces, are return formats, error patterns, and call points defined?
+- **Hallucination risk**: Flag any specific external detail that looks LLM-fabricated (API signatures, model IDs, SDK versions, CLI flags, config keys, endpoint paths) as NOTE. The PM is an LLM — it confidently invents plausible-looking specifics.
+
+**Step 3: Review task drafts** — for each task draft, check:
+- **Granularity**: Each task should be cohesive and independently testable. 2–10 AC items is the sweet spot.
+- **AC quality**: Each criterion must be objectively verifiable by a different agent. "Shows details" is BAD. "Displays order ID, customer name, and status badge" is GOOD.
+- **Coverage**: Cross-reference task AC against document requirements. Any requirement with NO corresponding AC?
+- **Dependencies**: Is the DAG correct? Can each task start once its dependencies are done?
+- **Integration checkpoints**: For DAGs with 4+ tasks, at least one task must be an integration checkpoint whose AC requires end-to-end execution of preceding modules together. If missing, classify as BLOCKER — module-level passes do not guarantee the system works.
+- **Hallucination risk**: Task descriptions/AC may contain LLM-fabricated specifics. Flag as NOTE — same rule as Step 2.
+
+**Step 4: Cross-check**
+- Do tasks cover ALL requirements from the documents?
+- Are there scope additions not in the original idea?
+- Are there contradictions between documents and tasks?
+
+## Finding classification
+
+**BLOCKER** — blocks implementation correctness: missing critical AC/NFR coverage; functional scope contradiction between documents; interface design flaw causing runtime errors; incorrect task dependencies.
+
+**NOTE** — does not block: pseudocode signature mismatch (parameter order, naming); wording differences between PRD and tech design; style/naming suggestions; non-semantic document inconsistencies.
+
+Rules: Pseudocode inconsistencies → always NOTE. Cross-document wording differences → always NOTE. Only semantic contradictions → BLOCKER. VERDICT: has BLOCKERs → FAIL; only NOTEs → PASS WITH NOTES; nothing → PASS.
+
+## Round awareness
+
+- **Round 1**: full review, normal strictness.
+- **Round 2+**: focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged before. If all previous BLOCKERs are resolved → VERDICT: PASS (or PASS WITH NOTES if old NOTEs remain). Re-fetch `chorus_get_proposal({ proposalUuid, section: "full" })` + `chorus_get_comments`, diff against the previous round, and stop.
+
+## Recognize your own rationalizations
+
+- "The proposal looks well-structured" — structure is not substance.
+- "The PM probably considered this" — the PM is an LLM. Check it yourself.
+- "There are enough tasks" — count is not coverage. Map requirements to tasks.
+
+## Output format (required)
+
+```
+### Review Summary
+
+**PASS (N):** Check-1 name, Check-2 name, ...
+
+**NOTE (M):**
+- Note-1: [one-line description]
+
+**BLOCKER (K):**
+### Blocker-1: name
+**Evidence:** [specific finding]
+**Expected:** [what should be there]
+**Actual:** [what is there or what is missing]
+
+VERDICT: PASS / PASS WITH NOTES / FAIL
+```
+
+PASS items: names only. NOTE items: one-line. BLOCKER items: full evidence. Total under 800 chars. No preamble. The final line MUST start with `VERDICT:`.
+
+## Post results
+
+Post the full review as a single comment, then you are done:
+```
+chorus_add_comment({
+  targetType: "proposal",
+  targetUuid: "<proposal-uuid>",
+  content: "<your review>"
+})
+```