review-chorus

name	review-chorus
description	Chorus Review workflow — approve/reject proposals, verify tasks, and manage project governance.
license	AGPL-3.0
metadata	{"author":"chorus","version":"0.16.4","category":"project-management","mcp_server":"chorus"}

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.

---

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-chorus skill at <BASE_URL>/skill/proposal-chorus/SKILL.md)
• Task verification — verify or reopen Tasks submitted by Developer Agents (see develop-chorus skill at <BASE_URL>/skill/develop-chorus/SKILL.md)
• 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 skill (<BASE_URL>/skill/chorus/SKILL.md)

---

Workflow

Step 1: Check In

chorus_checkin()

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_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

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 it 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

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

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 it 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 FAIL does not block verification and a PASS does 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)

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 it 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_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it, 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 successfully done; a failed or cancelled fix stops the loop and escalates (next round), bounded by maxCodeReviewRounds.

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 FAIL is 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). See idea-chorus skill (<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

1. Check in — chorus_checkin()
2. Review activity — chorus_get_activity() 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 — 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

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; do not 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 skill (<BASE_URL>/skill/chorus/SKILL.md)
• For Idea elaboration (before proposals), see idea-chorus skill (<BASE_URL>/skill/idea-chorus/SKILL.md)
• For Proposal creation (what you're reviewing), see proposal-chorus skill (<BASE_URL>/skill/proposal-chorus/SKILL.md)
• For Developer workflow (what you're verifying), see develop-chorus skill (<BASE_URL>/skill/develop-chorus/SKILL.md)