--- name: chorus-review description: Chorus review workflow for OpenCode. Use when approving or rejecting proposals, verifying tasks, interpreting reviewer verdicts, and managing project governance. license: AGPL-3.0 compatibility: opencode metadata: author: chorus version: "0.10.0" category: project-management mcp_server: lazy-chorus-bridge workflow: review role: task:admin audience: opencode-agents source: chorus-plugin keywords: proposal-review,task-verification,verdict,governance,acceptance-criteria tools: chorus_admin_approve_proposal,chorus_pm_reject_proposal,chorus_mark_acceptance_criteria,chorus_admin_verify_task,chorus_admin_reopen_task --- # Review Skill This skill covers the **Review** stage of the AI-DLC workflow: approving or rejecting Proposals, verifying completed Tasks, and managing overall project governance for agents with `task:admin`. ## OpenCode Tool Access In OpenCode plugin mode, Chorus uses the lazy bridge tools `chorus_tools`, `chorus_tool_get`, and `chorus_tool_execute`. Start with `chorus_tools`, inspect one tool with `chorus_tool_get({ toolName: "..." })`, then execute it with `chorus_tool_execute({ toolName: "...", arguments: { ... } })`. --- ## Overview Agents using this skill need `task:admin` and should treat it as the verification and governance entry point for Chorus review work. You are the human proxy for the project owner, ensuring quality and managing the AI-DLC lifecycle. Key responsibilities: - **Proposal review** — approve or reject Proposals submitted through `chorus-proposal` - **Task verification** — verify or reopen Tasks submitted through `chorus-develop` - **Project governance** — create projects/ideas, manage groups, close/delete entities --- ## Tools **Admin-Exclusive:** | Tool | Purpose | |------|---------| | `chorus_admin_create_project` | Create a new project (optional `groupUuid` for group assignment) | | `chorus_admin_approve_proposal` | Approve proposal (materializes documents + tasks) | | `chorus_admin_verify_task` | Verify completed task (to_verify -> done). Blocked if required AC not all passed. | | `chorus_mark_acceptance_criteria` | Mark acceptance criteria as passed/failed during verification (batch) | | `chorus_admin_reopen_task` | Reopen task for rework (to_verify -> in_progress) | | `chorus_admin_close_task` | Close task (any state -> closed) | | `chorus_admin_close_idea` | Close idea (any state -> closed) | | `chorus_admin_delete_idea` | Delete an idea permanently | | `chorus_admin_delete_task` | Delete a task permanently | | `chorus_admin_delete_document` | Delete a document permanently | | `chorus_admin_create_project_group` | Create a new project group | | `chorus_admin_update_project_group` | Update a project group (name, description) | | `chorus_admin_delete_project_group` | Delete a project group (projects become ungrouped) | | `chorus_admin_move_project_to_group` | Move a project to a group or ungroup it | **PM + Admin (proposal reject/revoke):** | Tool | Purpose | |------|---------| | `chorus_pm_reject_proposal` | Reject a pending proposal (pending -> draft). PM: own proposals only. Admin: any proposal. | | `chorus_pm_revoke_proposal` | Revoke an approved proposal (approved -> draft). Cascade-closes tasks, deletes documents. PM: own only. Admin: any. | **All PM tools** (`chorus_pm_*`, `chorus_*_idea`) and **all Developer tools** (`chorus_*_task`, `chorus_report_work`) are also available to Admin. **Shared tools** (checkin, query, comment, search, notifications): see `/chorus` --- ## Review Strategy When reviewing proposals or tasks, use the automatic reviewer gate before manual judgment: 1. **Use the reviewer gate first.** `chorus_pm_submit_proposal` auto-launches `proposal-reviewer`; `chorus_submit_for_verify` auto-launches `task-reviewer`. The plugin waits for the current reviewer VERDICT or timeout before returning the tool result. The reviewer posts a VERDICT comment with detailed findings. 2. **Read the VERDICT.** After the gated tool result returns, inspect the reviewer result and, if needed, call `chorus_get_comments` to find the current comment containing `VERDICT:`. There are exactly three possible outcomes: - **VERDICT: PASS** — No issues found. Approve (proposals) or mark AC passed and verify (tasks). - **VERDICT: PASS WITH NOTES** — Minor non-blocking notes. Still approve/verify. Notes are informational. - **VERDICT: FAIL** — BLOCKERs found. Reject (proposals) or reopen (tasks). Fix the specific BLOCKERs listed in the comment before resubmitting. 3. **Reviewer timeout or no current VERDICT?** Inspect the reported reviewer child session and Chorus comments. Do not silently approve or verify. Resubmit for another reviewer gate, reopen/reject if evidence is unclear, or escalate to human review. 4. **Track rounds.** Use the plugin's max review round settings and existing VERDICT comments. After repeated FAIL verdicts on the same item, stop the loop and escalate to human review. 5. **Fallback.** If the reviewer gate is unavailable (e.g., agent type not registered, sub-agent spawn fails, or timeout persists), review the item yourself using the quality checklists below and record the reason for manual handling. --- ## Workflow ### Step 1: Check In ``` chorus_tool_execute({ toolName: "chorus_checkin", arguments: {} }) ``` Pay attention to: - Pending proposal count (items awaiting approval) - Tasks in `to_verify` status (work awaiting review) - Overall project health ### Step 2: Triage Check what needs your attention: ``` # Pending proposals chorus_tool_execute({ toolName: "chorus_get_proposals", arguments: { projectUuid: "", status: "pending" } }) # Tasks awaiting verification chorus_tool_execute({ toolName: "chorus_list_tasks", arguments: { projectUuid: "", status: "to_verify" } }) # Recent activity chorus_tool_execute({ toolName: "chorus_get_activity", arguments: { projectUuid: "" } }) ``` Prioritize: **Proposals first** (they unblock PM and Developer work), then task verifications. ### Workflow A: Proposal Review #### A1: Read the Proposal ``` chorus_tool_execute({ toolName: "chorus_get_proposal", arguments: { proposalUuid: "", section: "full" } }) ``` This returns: title, description, input ideas, **document drafts** (PRD, tech design), **task drafts** (with descriptions and acceptance criteria). #### A2: Quality Checklist **Documents:** - [ ] PRD clearly describes the *what* and *why* - [ ] Requirements are specific and testable - [ ] Tech design is feasible and follows project conventions - [ ] No missing edge cases or security considerations **Tasks:** - [ ] Tasks cover all requirements in the PRD - [ ] Each task has clear acceptance criteria - [ ] Tasks are appropriately sized (1-8 story points) - [ ] Task descriptions have enough context for a developer agent - [ ] Priority is set correctly **Overall:** - [ ] Proposal aligns with the original idea(s) - [ ] No scope creep beyond what was requested - [ ] Implementation approach is reasonable #### A3: Read Comments ``` chorus_tool_execute({ toolName: "chorus_get_comments", arguments: { targetType: "proposal", targetUuid: "" } }) ``` #### A3.5: Independent Review If the proposal just returned from `chorus_pm_submit_proposal`, use the gated reviewer result from that submit call. Otherwise, read the latest reviewer VERDICT comment and apply the [Review Strategy](#review-strategy) above before proceeding. #### A4: Approve or Reject **Approve:** ``` chorus_tool_execute({ toolName: "chorus_admin_approve_proposal", arguments: { proposalUuid: "", reviewNote: "Approved. Good breakdown of tasks." } }) ``` The response includes `materializedTasks` and `materializedDocuments` — use them to immediately assign tasks or reference documents. When approved: - Document drafts become real Documents - Task drafts become real Tasks (status: `open`) **Reject:** ``` chorus_tool_execute({ toolName: "chorus_pm_reject_proposal", arguments: { proposalUuid: "", reviewNote: "PRD missing error handling requirements. Task 3 needs clearer AC." } }) chorus_tool_execute({ toolName: "chorus_add_comment", arguments: { targetType: "proposal", targetUuid: "", content: "Specific feedback:\n1. Add error scenarios to PRD\n2. Task 3 AC should include performance benchmarks" } }) ``` ### Workflow A2: Revoking Approved Proposals If an approved Proposal's direction turns out to be wrong, use `chorus_pm_revoke_proposal` to undo the approval. Unlike `reject` (which acts on pending proposals), `revoke` acts on already-approved proposals and rolls back all materialized resources. ``` chorus_tool_execute({ toolName: "chorus_pm_revoke_proposal", arguments: { proposalUuid: "", reviewNote: "Requirements changed — original approach no longer viable." } }) ``` Cascade effects: all materialized Tasks are closed, all materialized Documents are deleted, and related AcceptanceCriteria/TaskDependencies/SessionCheckins are cleaned up. The Proposal returns to `draft` status so the PM can revise and resubmit. ### Workflow B: Task Verification #### B1: Review the Submitted Task ``` chorus_tool_execute({ toolName: "chorus_get_task", arguments: { taskUuid: "" } }) ``` Check: developer's work summary, acceptance criteria, self-check results. #### B2: Read Comments and Work Reports ``` chorus_tool_execute({ toolName: "chorus_get_comments", arguments: { targetType: "task", targetUuid: "" } }) ``` #### B2.5: Independent Review Use the gated reviewer result from `chorus_submit_for_verify`, or read the latest reviewer VERDICT comment if you are resuming verification later: - **VERDICT: PASS** or **PASS WITH NOTES** → proceed to B3 (mark AC) and B4 (verify). - **VERDICT: FAIL** → skip to B4 and **reopen** the task. Do NOT mark AC as passed. #### B3: Mark Acceptance Criteria Review and mark each criterion: ``` chorus_tool_execute({ toolName: "chorus_mark_acceptance_criteria", arguments: { taskUuid: "", criteria: [ { uuid: "", status: "passed" }, { uuid: "", status: "passed" }, { uuid: "", status: "failed", evidence: "Missing edge case handling" } ] } }) ``` #### B4: Verify or Reopen **Verify (all required AC passed):** ``` chorus_tool_execute({ toolName: "chorus_admin_verify_task", arguments: { taskUuid: "" } }) ``` This moves the task to `done`. **Important:** verifying may unblock downstream tasks. Check: ``` chorus_tool_execute({ toolName: "chorus_get_unblocked_tasks", arguments: { projectUuid: "" } }) ``` If new tasks are unblocked, assign them or notify developers. **Reopen (needs fixes):** ``` chorus_tool_execute({ toolName: "chorus_admin_reopen_task", arguments: { taskUuid: "" } }) chorus_tool_execute({ toolName: "chorus_add_comment", arguments: { targetType: "task", targetUuid: "", content: "Reopened: Missing error handling for user-not-found edge case." } }) ``` The task returns to `in_progress`. All acceptance criteria are reset. #### B5: Close / Delete Tasks ``` # Close (preserves history) chorus_tool_execute({ toolName: "chorus_admin_close_task", arguments: { taskUuid: "" } }) # Delete (permanent, use sparingly) chorus_tool_execute({ toolName: "chorus_admin_delete_task", arguments: { taskUuid: "" } }) ``` ### Workflow C: Project & Idea Management #### Create Project ``` chorus_tool_execute({ toolName: "chorus_get_project_groups", arguments: {} }) # List available groups first chorus_tool_execute({ toolName: "chorus_admin_create_project", arguments: { name: "My Project", description: "Project goals...", groupUuid: "" } }) ``` #### Manage Project Groups ``` chorus_tool_execute({ toolName: "chorus_admin_create_project_group", arguments: { name: "Mobile Apps", description: "All mobile projects" } }) chorus_tool_execute({ toolName: "chorus_admin_move_project_to_group", arguments: { projectUuid: "", groupUuid: "" } }) chorus_tool_execute({ toolName: "chorus_admin_move_project_to_group", arguments: { projectUuid: "", groupUuid: null } }) # Ungroup chorus_tool_execute({ toolName: "chorus_admin_delete_project_group", arguments: { groupUuid: "" } }) # Projects become ungrouped ``` #### Close / Delete Ideas ``` chorus_tool_execute({ toolName: "chorus_admin_close_idea", arguments: { ideaUuid: "" } }) chorus_tool_execute({ toolName: "chorus_admin_delete_idea", arguments: { ideaUuid: "" } }) ``` > **Note:** Creating ideas is a PM tool (`chorus_pm_create_idea`). See `chorus-idea`. #### Document Management Use OpenCode's native `write` / `edit` tools when preparing updated document files for upload. ``` chorus_tool_execute({ toolName: "chorus_admin_delete_document", arguments: { documentUuid: "" } }) # Write the updated content to the Chorus staging directory first, then: chorus_tool_execute({ toolName: "chorus_pm_update_document", arguments: { documentUuid: "", contentPath: "/updated.md" } }) ``` --- ## Daily Admin Routine 1. **Check in** — `chorus_tool_execute({ toolName: "chorus_checkin", arguments: {} })` 2. **Review activity** — `chorus_tool_execute({ toolName: "chorus_get_activity", arguments: {} })` for recent events 3. **Process proposals** — Review and approve/reject pending proposals 4. **Verify tasks** — Review and verify/reopen tasks in `to_verify` 5. **Create new ideas** — If the human has new requirements 6. **Check project health** — Stale tasks? Blocked items? Orphaned ideas? --- ## Tips - **Review thoroughly** — Don't rubber-stamp proposals; check quality - **Give actionable feedback** — When rejecting, explain specifically what to fix - **Verify against criteria** — Check acceptance criteria, not just the summary - **Manage scope** — Close ideas and tasks that are no longer relevant - **Unblock the team** — Prioritize proposal reviews to keep PM and Developer work flowing - **Use delete sparingly** — Prefer closing over deleting; closing preserves history - **Document decisions** — Use comments to explain approval/rejection reasoning - **Verify between waves** — In OpenCode subagents mode, verify tasks to `done` between waves to unblock downstream dependencies --- ## Governance Principles 1. **Quality over speed** — A rejected proposal now saves rework later 2. **Actionable feedback** — Every rejection should include specific fixes 3. **Criteria-based verification** — Verify against acceptance criteria, not just subjective impression 4. **Scope discipline** — Close what's no longer needed, don't let orphaned items pile up 5. **Unblock others** — Your reviews are the bottleneck; prioritize them 6. **Preserve history** — Close > Delete; comments > silent actions 7. **Document reasoning** — Future agents will read your comments to understand decisions --- ## Next - For platform overview and shared tools, see `/chorus` - For Idea elaboration (before proposals), see `chorus-idea` - For Proposal creation (what you're reviewing), see `chorus-proposal` - For Developer workflow (what you're verifying), see `chorus-develop`