@chorus-aidlc/chorus-openclaw-plugin 0.3.1 → 0.5.0

package/skills/quick-dev/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: quick-dev
+description: Quick Task workflow — skip Idea→Proposal, create tasks directly, execute, and verify.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.9.0"
+  category: project-management
+  mcp_server: chorus
+---
+
+# Quick Dev Skill
+
+Skip the full AI-DLC pipeline (Idea → Elaboration → Proposal → Approval) and create tasks directly. Ideal for small, well-understood work. The goal is for agents to **autonomously record their development work and verify task completion** through structured acceptance criteria.
+
+> **Tool namespace:** Chorus tools are exposed by the connected MCP server under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_create_tasks`). Bare names are used below for readability — prepend `chorus__` when invoking. See `/chorus` for the full rule.
+
+---
+
+## Overview
+
+The standard AI-DLC flow ensures quality through structured planning, but adds overhead that slows down small tasks. Quick Dev provides a lightweight alternative:
+
+```
+[check admin role] → chorus_create_tasks → chorus_claim_task → in_progress → report → self-check AC → submit for verify → [self-verify if admin] → done
+```
+
+**Use Quick Dev when:**
+- Bug fixes with clear reproduction steps
+- Small features (< 2 story points)
+- Post-delivery patches and gap-filling after a proposal's tasks are done
+- Prototype or exploratory tasks
+- Urgent hotfixes that can't wait for proposal review
+
+**Do NOT use Quick Dev when:**
+- The feature needs a PRD or tech design document
+- Multiple interdependent tasks require upfront planning
+- Stakeholder elaboration is needed to clarify requirements
+- The work impacts architecture or shared components significantly
+
+For complex work, use `/idea` + `/proposal` instead.
+
+---
+
+## Pre-Flight: Admin Self-Verify Check
+
+**Before creating tasks**, if `chorus_checkin().agent.permissions.task` includes `"admin"`, ask the user (as a **plain-text prompt** — OpenClaw has no `AskUserQuestion`):
+
+> "I have admin privileges. After development, should I verify the task myself, or leave it for another admin to verify? Reply 'self' or 'other'."
+
+This matters because admin agents can call `chorus_admin_verify_task` to close the loop autonomously. If the user approves self-verification, you can complete the entire create → develop → verify cycle without human intervention. Record the decision and apply it in Step 7.
+
+---
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_create_tasks` | Create task(s) — omit `proposalUuid` for standalone Quick Task, or pass it to attach to an existing proposal |
+| `chorus_update_task` | Edit task fields (title, description, priority, AC, dependencies) or change status |
+| `chorus_claim_task` | Claim a task (open → assigned) |
+| `chorus_report_work` | Report progress with optional status update |
+| `chorus_report_criteria_self_check` | Self-check acceptance criteria before submitting |
+| `chorus_submit_for_verify` | Submit for admin verification |
+| `chorus_admin_verify_task` | **(admin only)** Verify task — use when self-verification is approved |
+
+---
+
+## Workflow
+
+### Step 1: Create a Quick Task
+
+**Always include `acceptanceCriteriaItems`** — these are the foundation for self-checking in Step 6. Write specific, testable criteria that you can objectively verify after development. Vague AC like "works correctly" defeats the purpose; prefer "returns 200 on GET /api/foo with valid token".
+
+```
+chorus_create_tasks({
+  projectUuid: "<project-uuid>",
+  tasks: [{
+    title: "Fix login redirect loop on Safari",
+    description: "Safari loses session cookie after redirect...",
+    priority: "high",
+    storyPoints: 1,
+    acceptanceCriteriaItems: [
+      { description: "Login works on Safari 17+", required: true },
+      { description: "Existing Chrome/Firefox behavior unchanged", required: true }
+    ]
+  }]
+})
+```
+
+**`proposalUuid` is optional:**
+- **Omit** for standalone quick tasks (bug fixes, hotfixes, exploratory work)
+- **Pass** to attach the task to an existing proposal — useful for gap-filling, follow-up patches, or continuing work after a proposal's initial tasks are delivered
+
+### Step 2: Claim the Task
+
+```
+chorus_claim_task({ taskUuid: "<task-uuid>" })
+```
+
+### Step 3: Edit Details (if needed)
+
+Use `chorus_update_task` to refine the task after creation. **If you skipped AC in Step 1, add them now** — you will need them for self-check later. Also update AC when your understanding of the task changes during development.
+
+```
+chorus_update_task({
+  taskUuid: "<task-uuid>",
+  description: "Updated with more details...",
+  acceptanceCriteriaItems: [
+    { description: "Login works on Safari 17+", required: true },
+    { description: "Added CSRF token handling", required: true }
+  ],
+  addDependsOn: ["<other-task-uuid>"]
+})
+```
+
+### Step 4: Start Working
+
+```
+chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress" })
+```
+
+**Sub-agents:** create your own session first (manual on OpenClaw — see `/develop`), then pass `sessionUuid` for attribution:
+```
+chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress", sessionUuid: "<session-uuid>" })
+```
+
+### Step 5: Report Progress
+
+```
+chorus_report_work({
+  taskUuid: "<task-uuid>",
+  report: "Fixed Safari cookie issue:\n- Root cause: SameSite=Strict incompatible with redirect\n- Changed to SameSite=Lax\n- Commit: abc1234",
+  sessionUuid: "<session-uuid>"
+})
+```
+
+### Step 6: Self-Check Acceptance Criteria
+
+```
+chorus_report_criteria_self_check({
+  taskUuid: "<task-uuid>",
+  criteria: [
+    { uuid: "<ac-uuid-1>", devStatus: "passed", devEvidence: "Tested on Safari 17.2" },
+    { uuid: "<ac-uuid-2>", devStatus: "passed", devEvidence: "Chrome/Firefox regression tests pass" }
+  ]
+})
+```
+
+### Step 7: Submit for Verification (or Self-Verify)
+
+```
+chorus_submit_for_verify({
+  taskUuid: "<task-uuid>",
+  summary: "Fixed Safari login redirect loop. Changed SameSite cookie policy. All AC passed."
+})
+```
+
+**Admin self-verification:** If you have `task: ["admin"]` in `permissions` and the user approved self-verification in the Pre-Flight check, you can verify the task yourself immediately after submitting:
+
+```
+chorus_admin_verify_task({ taskUuid: "<task-uuid>" })
+```
+
+This completes the full autonomous cycle: create → develop → verify → done.
+
+> **Optional independent review:** for non-trivial quick tasks you may still run the `/task-reviewer` skill in a spawned sub-agent (`sessions_spawn` with a task telling it to run `/task-reviewer` against the taskUuid, then wait for the VERDICT) or do a focused read-only self-review before verifying — same pattern as `/develop` Step 8.5. There is no PostToolUse hook on OpenClaw, so do this inline if you want it.
+
+---
+
+## Session Integration
+
+Quick Tasks support sub-agent execution just like proposal-based tasks. **Session lifecycle is manual on OpenClaw** (no SubagentStart/heartbeat/cleanup hooks):
+
+- **Main agent**: create quick tasks, work them yourself, or hand task UUIDs to sub-agents
+- **Sub-agents**: create your own session (`chorus_create_session`), checkin/checkout per task, pass `sessionUuid` to `chorus_update_task` / `chorus_report_work`, and close the session on exit — see `/develop` for the full manual protocol
+
+> OpenClaw has no Agent Teams / `TeamCreate` primitive; if you need to run several quick tasks, work them sequentially as the main agent (or dispatch generic sub-agents one at a time).
+
+---
+
+## Tips
+
+- Keep Quick Tasks small — if you need more than 2-3 tasks, consider using `/proposal`
+- **Always write acceptance criteria at creation time** — they are your self-check contract. Specific, testable AC enables autonomous verification and makes the entire workflow self-contained
+- Use `chorus_update_task` to refine tasks (including AC) after creation rather than deleting and recreating
+- Pass `proposalUuid` to attach follow-up or gap-filling tasks to an existing proposal — this keeps related work grouped in the same project context and DAG
+- Quick Tasks show up in the same project task list and DAG as proposal-based tasks
+- Admin agents can run the full lifecycle autonomously (create → develop → self-verify) — but always confirm with the user first (plain-text prompt)
+
+---
+
+## Next
+
+- For full task lifecycle details, see `/develop`
+- For admin verification, see `/review`
+- For the standard planning flow, see `/idea` and `/proposal`
+- For platform overview, see `/chorus`

package/skills/review/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: review
+description: Chorus Review workflow — approve/reject proposals, verify tasks, and manage project governance.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.9.0"
+  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.
+
+> **Tool namespace:** Chorus tools are exposed by the connected MCP server under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_admin_verify_task`). Bare names are used below for readability — prepend `chorus__` when invoking. See `/chorus` for the full rule.
+
+---
+
+## 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`)
+- **Task verification** — verify or reopen Tasks submitted by Developer Agents (see `/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, get an independent VERDICT before approving/verifying. On OpenClaw there is **no PostToolUse hook** to remind you — invoke the review yourself, inline.
+
+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** (for proposals) or the `/task-reviewer` skill (for tasks) — both bundled with this plugin — against the entity. Wait for it (poll the `subagents` tool or use `sessions_yield` — do NOT detach; you must have the VERDICT before proceeding). The sub-agent inherits the plugin skills, so the reviewer skill is available to it; it posts a VERDICT comment with detailed findings. Example task prompt: `Run the /proposal-reviewer skill to review proposalUuid <uuid>; post your VERDICT comment when done.`
+2. **Read the VERDICT.** After the reviewer completes, call `chorus_get_comments` and find the most recent 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. **No new VERDICT comment?** The sub-agent exhausted its turn budget before posting. Respawn it ONCE with an explicit prompt like: *"Stay within your turn budget. Skip deep source verification — batch all MCP fetches up front, skim for obvious BLOCKERs only, and reserve your last few turns to post the VERDICT comment."* If the second attempt also fails to post, review manually (step 5).
+4. **Track rounds.** Count existing VERDICT comments before spawning. After 3 rounds of FAIL on the same item, stop the loop and escalate to human review.
+5. **Fallback — review it yourself (no `sessions_spawn` on the host).** If spawning is unavailable (disabled by policy, or the spawn fails), perform the review yourself as a **focused, read-only pass** using the quality checklists in the workflows below: read the entity, its comments, and the relevant documents/code, run read-only test/build commands where applicable, and do NOT modify anything. Then record your VERDICT via `chorus_add_comment` ending with a `VERDICT:` line (PASS / PASS WITH NOTES / FAIL), classifying every finding as BLOCKER or NOTE. The `/proposal-reviewer` and `/task-reviewer` skills are the authoritative checklists for this manual pass — read them and follow their procedure.
+
+---
+
+## 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>" })
+```
+
+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_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
+```
+
+#### A3.5: Independent Review
+
+Get a VERDICT per the [Review Strategy](#review-strategy) above — spawn a sub-agent via `sessions_spawn` and have it run the `/proposal-reviewer` skill (wait for it), otherwise review yourself as a read-only pass and post the VERDICT. Read its VERDICT comment before proceeding.
+
+#### 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
+
+Get a VERDICT per the [Review Strategy](#review-strategy) above — spawn a sub-agent via `sessions_spawn` and have it run the `/task-reviewer` skill (wait for it), otherwise review yourself as a read-only pass and post the VERDICT. After it completes, read its VERDICT:
+
+- **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_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`. **Important:** verifying may unblock downstream tasks. Check:
+
+```
+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, use sparingly)
+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`.
+
+#### 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** — 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 sequential wave execution, 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 `/idea`
+- For Proposal creation (what you're reviewing), see `/proposal`
+- For Developer workflow (what you're verifying), see `/develop`

package/skills/task-reviewer/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: task-reviewer
+description: Adversarial verification of a submitted Chorus task against its AC and proposal documents — read the code, verify each criterion, run tests. Invoke after a task is submitted for verify; ends with a VERDICT comment.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.9.0"
+  category: project-management
+  mcp_server: chorus
+---
+
+# Task Reviewer Skill
+
+You have been asked to **verify a submitted Chorus task**. Your job is **not** to confirm the implementation works — it's to find where it doesn't match the requirements.
+
+> **How you were invoked.** A developer/orchestrator agent spawned you (via the OpenClaw `sessions_spawn` tool) and told you to run this skill against a specific `taskUuid`. Read it from your task prompt. When you finish, you post one `VERDICT:` comment back to the task — 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_task`, `chorus__chorus_add_comment`). Bare names are used below for readability — prepend `chorus__` when invoking.
+
+## Hard rules (READ-ONLY, except read-only Bash)
+
+- **You CANNOT edit, write, or create files** in the project directory. Do NOT modify any entity except posting your one review comment.
+- **Bash is READ-ONLY:** only test/build/lint commands and inspection (`cat`/`head`/`tail`/`wc`/`diff`, `grep`/`rg`/`ls`/`find`, `git diff`/`git log`/`git show`). **Strictly forbidden:** `git add`/`commit`/`push`/`checkout`/`reset`; `rm`/`mv`/`cp`/`echo >`/`tee`/`sed -i`; package installs (`npm install`, `pnpm add`, `pip install`); `curl -X POST/PUT/DELETE`.
+- **Keep your comment under 800 characters.** PASS items: names only. NOTE items: one-line. BLOCKER items: command + output + evidence.
+- **Classify every finding** as BLOCKER (blocks correctness: build/test failure, AC not implemented, semantic contradiction) or NOTE (non-blocking: pseudocode mismatch, wording difference, style).
+- **End with a single line beginning `VERDICT:`** — exactly one of `PASS`, `PASS WITH NOTES`, `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 running low on turns/time, STOP reading files AND stop running bash/tests immediately and post your current findings via `chorus_add_comment`. Incomplete findings posted beat no comment.
+- **Do NOT confirm — find what's wrong.** Batch data gathering, then one final comment.
+
+You have two failure patterns. **Verification avoidance**: reading code, narrating what you would test, writing "PASS," never actually running anything. **Being seduced by the first 80%**: passing tests + clean code, not noticing AC are only superficially met, the implementation diverges from proposal documents, or edge cases silently fail. The developer is an LLM — its self-tests may be circular (testing mocks, not behavior).
+
+## What you receive
+
+A `taskUuid` (in your task prompt). Fetch the task, its AC, and the proposal documents, then independently verify the implementation.
+
+## Review procedure
+
+**Efficiency rule:** Gather ALL context in Steps 1–2 before verifying. Batch tool calls — do not alternate between fetching and concluding.
+
+**Step 1: Gather context**
+```
+chorus_get_task({ taskUuid: "<uuid>" })
+chorus_get_comments({ targetType: "task", targetUuid: "<uuid>" })
+chorus_get_proposal({ proposalUuid: "<from-task>" })
+chorus_get_document({ documentUuid: "<doc-uuid>" })
+```
+
+**Step 2: Read the code.** Use Glob/Grep to find relevant files, then read them. Do NOT rely on the developer's summary — read the code yourself.
+
+**Step 3: Verify each AC independently.** For EACH acceptance criterion: (1) read what it requires, word by word; (2) find the code that implements it; (3) run a verification command if possible; (4) determine PASS or FAIL with evidence. Do NOT batch AC as "all look good." Check each one.
+
+**Step 4: Cross-reference with proposal documents.** Does the PRD mention fields, behaviors, or error scenarios not covered by any AC? Does the tech design specify contracts the code doesn't follow?
+
+**Step 5: Run tests/build if available.** A broken build or failing tests is an automatic FAIL. Test results are context, not proof — verify AC independently after noting results.
+
+**Step 6: Adversarial probes.** Pick 2–3 probes that fit the task: boundary values, missing fields, error paths, concurrency. Run them — don't just describe them.
+
+**Hallucination check:** Flag anything that looks LLM-fabricated as NOTE — API signatures, CLI flags, config keys, model IDs, endpoint URLs, package names, or any external detail the developer likely wrote from memory.
+
+## Finding classification
+
+**BLOCKER** — blocks correctness: AC not actually implemented; build or test failures; implementation diverges from proposal documents (semantic contradiction); edge cases causing runtime errors; missing error handling for required scenarios.
+
+**NOTE** — does not block: pseudocode signature mismatch; wording differences between docs and comments; style/naming suggestions; non-semantic inconsistencies.
+
+Rules: Pseudocode inconsistencies → always NOTE. Cross-document wording differences → always NOTE. Only functional/behavioral issues → 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 unflagged areas. If all previous BLOCKERs resolved → VERDICT: PASS (or PASS WITH NOTES if old NOTEs remain). Re-read only the specific files and re-run only the specific tests tied to previous BLOCKERs — do not re-scan unrelated code or rerun the full suite. Trusting the developer's diff summary without targeted re-verification is the "verification avoidance" anti-pattern.
+
+## Recognize your own rationalizations
+
+- "The code looks correct based on my reading" — reading is not verification. Run it.
+- "The developer's tests already pass" — the developer is an LLM. Verify independently.
+- "This AC is probably met" — probably is not verified. Find the specific code and check.
+- "The API call looks right" — for external API/SDK calls, request execution evidence (run logs, test output, errors). If none and you cannot run it, flag as NOTE.
+
+## Output format (required)
+
+```
+### Review Summary
+
+**PASS (N):** AC-1 name, AC-2 name, ...
+
+**NOTE (M):**
+- Note-1: [one-line description]
+
+**BLOCKER (K):**
+### Blocker-1: name
+**Command run:** [exact command executed]
+**Output observed:** [actual output — copy-paste, not paraphrased]
+**Evidence:** [file paths, line numbers]
+**Expected:** [expected behavior]
+**Actual:** [actual behavior]
+
+VERDICT: PASS / PASS WITH NOTES / FAIL
+```
+
+PASS items: names only. NOTE items: one-line. BLOCKER items: full command/output/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: "task",
+  targetUuid: "<task-uuid>",
+  content: "<your review>"
+})
+```