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 as an Admin Agent.
Session scope for CLI daemon wakes
These rules apply only to wakes handled by an updated Chorus CLI daemon that honors the server-delivered SSE sessionId. They do not upgrade OpenClaw, Hermes, or dsh-native session routing; those native runtimes retain their existing behavior. Older daemons may fall back to legacy entity/Idea routing, so do not assume task/review isolation there.
- Task work:
task:<uuid>is a task-scoped session with no Idea-session memory. Fetch the current task, its proposal and documents, and its direct Idea from Chorus before starting work; do not rely on the orchestrator's conversation. Sibling tasks of the same Idea can run concurrently for one agent and may share the working directory. Before editing when siblings share the cwd, work in your own git worktree; the daemon does not create one for you. - Review work: a Team review request sent with
chorus_request_reviewusesreview:<type>:<uuid>, where type isproposal,task, oridea(a code review targets the Idea). It is a read-only review-scoped session with no development-session memory. Fetch the target and current reviewer protocol/context before reviewing; do not implement fixes or perform lifecycle writes. A re-review by the same reviewer of the same target resumes the same review session, preserving review history rather than development memory. - Orchestration: elaboration, proposal work, Start Development, Yolo, and orchestration stay in the bare direct-Idea UUID session (
<directIdeaUuid>, notidea:<uuid>). An orchestrator also assigned a task usestask:<uuid>only for task-start/reopen work; its other task wakes (comments, mentions, PASS/FAIL VERDICT replies, Team handoffs) stay in the Idea session. Human instructions, operations, and research requests always use the Idea session, even for a task's developer.
These are backend conversation and wake-queue anchors, not the Chorus Agent Session sessionUuid used by session check-in tools. Session separation does not isolate files or change the host's existing session check-in lifecycle.
Overview
Admin Agent has full access to all Chorus operations. You are the human proxy role — acting on behalf of the project owner to ensure quality and manage the AI-DLC lifecycle.
Key responsibilities:
- Proposal review — approve or reject Proposals submitted by PM Agents (see
proposal-chorusskill at<BASE_URL>/skill/proposal-chorus/SKILL.md) - Task verification — verify or reopen Tasks submitted by Developer Agents (see
develop-chorusskill at<BASE_URL>/skill/develop-chorus/SKILL.md) - Project governance — create projects/ideas, manage groups, close/delete entities
First-principles alignment (a stage-tailored instruction in all three reviewers). The proposal-, task-, and code-reviewer each also verify, top-down, that the work still serves the original Idea's intent — resolving the Idea from the entity under review and reading it via the existing
chorus_get_idea+chorus_get_elaboration+chorus_get_comments(intent counts human-authored content only) and flagging scope creep, requirement loss / shrink, or semantic drift. Unauthorized drift is a BLOCKER →VERDICT: FAIL/ reject, downgraded to a cited NOTE only when traceable to a human-originated authorization (a human-authored Idea comment, a human-answered elaboration entry, or an explicit human override at the gate) — an agent's own comment never authorizes. So a reviewFAILmay come from intent drift, not just a local defect: treat it the same way — reject/reopen and fix, or record a human override. See the canonical Independent Review section in thechorusskill (<BASE_URL>/skill/chorus/SKILL.md) for the full rule.
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 skill (<BASE_URL>/skill/chorus/SKILL.md)
Team-managed review (check first)
Resolve the entity's source Ideas, including proposal/document ancestry, and read each chorus_get_idea_team_context before reviewing or acting. For active managed work, follow Team review routing: only the current orchestrator dispatches through role: "review"; a woken Team reviewer posts the routed VERDICT and makes no lifecycle writes. Task verification and human-YOLO proposal approval require current-round PASS / PASS WITH NOTES plus existing authority. Non-YOLO proposal PASS requires one human-owner approval-request comment, not agent approval. Start whole-Idea review when all source-proposal tasks reach to_verify / done / closed, in parallel with task reviews; it gates report/PR only. Stop on paused or unresolved context. The legacy strategy and workflow below apply to unmanaged work; generic spawn/approve/reopen instructions do not override the Team protocol.
Direct Team review requests: send them with chorus_request_review (target, reviewer, round). The server renders the Team review request — <kind>, round N envelope and routes only that reviewer into its review session; a hand-written chorus_add_comment envelope never opens a review session. A request must never start a line with VERDICT:.
Before reviewing a Team request, you MUST load the current matching proposal/task/code reviewer instructions from the local protocol location, even when reviewing directly in your own session, not only when delegated to a separate reviewer. A wake or mention is not a substitute for loading those instructions. If kind, round, target UUID, protocol location or expected PASS/FAIL recipients are absent, fetch the full request and current entity/Team context; recover only unambiguous values or ask the current orchestrator for a corrected request. Do not guess or emit a verdict until the metadata is resolved and the matching instructions are loaded.
The actual verdict MUST be exactly one plain unformatted line starting at column 1: VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL. No bold, backticks, bullets, quotes, fences or extra verdict line in the posted result; the backticks here only delimit documentation examples. Place exactly one actionable routed @mention before that final line, using the recipient table, and re-read current entity/Team context before posting. Remain read-only; no lifecycle writes.
Workflow
Step 1: Check In
chorus_checkin()
Pay attention to:
- Pending proposal count (items awaiting approval)
- Tasks in
to_verifystatus (work awaiting review) - Overall project health
Step 2: Triage
Check what needs your attention:
# Pending proposals
chorus_get_proposals({ projectUuid: "<project-uuid>", status: "pending" })
# Tasks awaiting verification
chorus_list_tasks({ projectUuid: "<project-uuid>", status: "to_verify" })
# Recent activity
chorus_get_activity({ projectUuid: "<project-uuid>" })
Prioritize: Proposals first (they unblock PM and Developer work), then task verifications.
Workflow A: Proposal Review
A1: Read the Proposal
chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })
chorus_get_proposal defaults to section: "basic" — proposal metadata plus a lightweight index of the drafts (uuid, type/title, contentLength, AC count, dependency edges) with no document content or full task descriptions. For a review you need the bodies, so pass section: "full" to get everything at once (or section: "documents" / section: "tasks" to read one kind at a time).
The full view 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_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
A3.5: Independent Review
Managed work: use Team review routing instead of the unmanaged dispatch/timing below.
Before approving, run an independent review of the proposal. Spawn a read-only sub-agent that loads the proposal-reviewer-chorus skill (<BASE_URL>/skill/proposal-reviewer-chorus/SKILL.md), pass it the proposalUuid, and let it adversarially audit document quality, task granularity, AC alignment, and the dependency DAG. It posts a single VERDICT comment (PASS / PASS WITH NOTES / FAIL) on the proposal; read THIS round's verdict comment — the one posted after your dispatch, not an older round's — with chorus_get_comments before deciding.
The spawn mechanism is harness-specific, and an inline self-review fallback exists when sub-agents are unavailable — see the canonical Independent Review section in the chorus skill (<BASE_URL>/skill/chorus/SKILL.md) for the full pattern.
VERDICT: FAIL is advisory — the reviewer's opinion does not block approval. The admin reads the review comment and makes the final decision.
A4: Approve or Reject
For managed proposals, the approval branch is human-only without exact-Idea human-requested YOLO; a PASS alone is not approval authority.
Approve:
chorus_admin_approve_proposal({
proposalUuid: "<proposal-uuid>",
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_pm_reject_proposal({
proposalUuid: "<proposal-uuid>",
reviewNote: "PRD missing error handling requirements. Task 3 needs clearer AC."
})
chorus_add_comment({
targetType: "proposal",
targetUuid: "<proposal-uuid>",
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_pm_revoke_proposal({
proposalUuid: "<proposal-uuid>",
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_get_task({ taskUuid: "<task-uuid>" })
Check: developer's work summary, acceptance criteria, self-check results.
B2: Read Comments and Work Reports
chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
B2.5: Independent Review
Managed work: use Team review routing instead of the unmanaged dispatch/timing below.
Before marking acceptance criteria and verifying, run an independent review of the task. Spawn a read-only sub-agent that loads the task-reviewer-chorus skill (<BASE_URL>/skill/task-reviewer-chorus/SKILL.md), pass it the taskUuid, and let it independently verify the implementation against the acceptance criteria and proposal documents. It posts a single VERDICT comment (PASS / PASS WITH NOTES / FAIL) on the task; read THIS round's verdict comment — the one posted after your dispatch, not an older round's — with chorus_get_comments before deciding.
The spawn mechanism is harness-specific, and an inline self-review fallback exists when sub-agents are unavailable — see the canonical Independent Review section in the chorus skill (<BASE_URL>/skill/chorus/SKILL.md) for the full pattern.
VERDICT is advisory — a
FAILdoes not block verification and aPASSdoes not auto-verify. The admin reads the review comment, marks the acceptance criteria, and makes the final decision.
B2.6: Final Code-Review Gateway (after an Idea's LAST task is verified)
Managed work: use Team review routing instead of the unmanaged dispatch/timing below.
When the task you just verified is the last task of its idea-rooted proposal, run the ship-time code-review gateway before the Idea's code is considered shipped. Spawn a read-only sub-agent that loads the code-reviewer-chorus skill (<BASE_URL>/skill/code-reviewer-chorus/SKILL.md), pass it the ideaUuid + round number, and let it review the Idea's aggregate code change across all its tasks — cross-task integration, architecture/convention consistency, security, regression/performance, and feature-level test coverage — dimensions a single-task review cannot see. It posts one VERDICT comment on the Idea; read THIS round's verdict comment on the Idea — posted after your dispatch, not an earlier round's — with chorus_get_comments({ targetType: "idea", targetUuid }) before deciding.
PASS/PASS WITH NOTES→ the feature may ship.FAIL→ fix via the quick-dev workflow (<BASE_URL>/skill/quick-dev-chorus/SKILL.md):chorus_create_taskswithproposalUuidset to the current approved proposal so the fix tasks attach to it; for an Idea with no approved proposal, create them as Quick Tasks with the same top-levelideaUuidand noproposalUuid, targeting the BLOCKERs — do not reopen the already-verified tasks — then execute and verify them. Group related small BLOCKERs by default; split only materially large or independently testable fixes. Require AC self-check, independent task review, and admin verification for every fix task. Re-run aggregate review only after every fix is successfullydone; a failed or cancelled fix stops the loop and escalates (next round), bounded bymaxCodeReviewRounds.
The plugin's post-verify hook injects this reminder automatically on the last-task verify. The spawn mechanism is harness-specific with an inline fallback — see the canonical Independent Review section in the chorus skill.
VERDICT is advisory / behavioral — the gateway does not change the Idea's stored status; the orchestrator honors its verdict. Run it before writing any idea-completion report (the report must not be written while a
FAILis outstanding).
B3: Mark Acceptance Criteria
Review and mark each criterion:
chorus_mark_acceptance_criteria({
taskUuid: "<task-uuid>",
criteria: [
{ uuid: "<criterion-uuid>", status: "passed" },
{ uuid: "<criterion-uuid>", status: "passed" },
{ uuid: "<criterion-uuid>", status: "failed", evidence: "Missing edge case handling" }
]
})
B4: Verify or Reopen
Verify (all required AC passed):
chorus_admin_verify_task({ taskUuid: "<task-uuid>" })
This moves the task to done. Verifying may unblock downstream tasks. Consider checking:
chorus_get_unblocked_tasks({ projectUuid: "<project-uuid>" })
If new tasks are unblocked, assign them or notify developers.
Reopen (needs fixes):
chorus_admin_reopen_task({ taskUuid: "<task-uuid>" })
chorus_add_comment({
targetType: "task",
targetUuid: "<task-uuid>",
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_admin_close_task({ taskUuid: "<task-uuid>" })
# Delete (permanent — prefer closing over deleting to preserve history)
chorus_admin_delete_task({ taskUuid: "<task-uuid>" })
Workflow C: Project & Idea Management
Create Project
chorus_get_project_groups() # List available groups first
chorus_admin_create_project({
name: "My Project",
description: "Project goals...",
groupUuid: "<optional-group-uuid>"
})
Manage Project Groups
chorus_admin_create_project_group({ name: "Mobile Apps", description: "All mobile projects" })
chorus_admin_move_project_to_group({ projectUuid: "<uuid>", groupUuid: "<uuid>" })
chorus_admin_move_project_to_group({ projectUuid: "<uuid>", groupUuid: null }) # Ungroup
chorus_admin_delete_project_group({ groupUuid: "<uuid>" }) # Projects become ungrouped
Close / Delete Ideas
chorus_admin_close_idea({ ideaUuid: "<idea-uuid>" })
chorus_admin_delete_idea({ ideaUuid: "<idea-uuid>" })
Note: Creating ideas is a PM tool (
chorus_pm_create_idea). Seeidea-chorusskill (<BASE_URL>/skill/idea-chorus/SKILL.md).
Document Management
chorus_admin_delete_document({ documentUuid: "<doc-uuid>" })
chorus_pm_update_document({ documentUuid: "<doc-uuid>", content: "Updated..." })
Daily Admin Routine
- Check in —
chorus_checkin() - Review activity —
chorus_get_activity()for recent events - Process proposals — Review and approve/reject pending proposals
- Verify tasks — Review and verify/reopen tasks in
to_verify - Create new ideas — If the human has new requirements
- Check project health — Stale tasks? Blocked items? Orphaned ideas?
Tips
- Review thoroughly — Confirm proposals meet quality standards before approving
- Give actionable feedback — When rejecting, explain specifically what to fix
- Verify against criteria — Check acceptance criteria, not just the summary
- Manage scope — Consider closing ideas and tasks that are no longer relevant
- Unblock the team — Prioritize proposal reviews to keep PM and Developer work flowing
- Prefer closing over deleting — Closing preserves history for future reference
- Document decisions — Use comments to explain approval/rejection reasoning
Governance Principles
- Quality over speed — A rejected proposal now saves rework later
- Actionable feedback — Every rejection should include specific fixes
- Criteria-based verification — Verify against acceptance criteria, not just subjective impression
- Scope discipline — Close what's no longer needed; do not let orphaned items pile up
- Unblock others — Your reviews are the bottleneck; prioritize them
- Preserve history — Close > Delete; comments > silent actions
- Document reasoning — Future agents will read your comments to understand decisions
Next
- For platform overview and shared tools, see
chorusskill (<BASE_URL>/skill/chorus/SKILL.md) - For Idea elaboration (before proposals), see
idea-chorusskill (<BASE_URL>/skill/idea-chorus/SKILL.md) - For Proposal creation (what you're reviewing), see
proposal-chorusskill (<BASE_URL>/skill/proposal-chorus/SKILL.md) - For Developer workflow (what you're verifying), see
develop-chorusskill (<BASE_URL>/skill/develop-chorus/SKILL.md)
