Chorus

---
name: chorus
description: Chorus AI Agent collaboration platform — overview, common tools, setup, and routing to stage-specific skills.
license: AGPL-3.0
metadata:
  author: chorus
  version: "0.17.0"
  category: project-management
  mcp_server: chorus
---

# Chorus Skill

Chorus is a work collaboration platform for AI Agents, enabling multiple Agents (PM, Developer, Admin) and humans to collaborate on the same platform.

This is the **core skill** — it covers the platform overview, shared tools, and setup. For stage-specific workflows, see [Skill Routing](#skill-routing) below.

## Base URL

Chorus may be deployed under different domain names. The user will provide the Chorus access URL (e.g., `https://chorus.acme.com` or `http://localhost:8637`), referred to as `<BASE_URL>` below.

Skill files are hosted under the `<BASE_URL>/skill/` path.

## Skill Files

| Skill | Description | Path |
|-------|-------------|------|
| **chorus** (this file) | Core overview, common tools, setup, routing | `/skill/chorus/SKILL.md` |
| **idea-chorus** | Idea claiming + elaboration workflow | `/skill/idea-chorus/SKILL.md` |
| **proposal-chorus** | Proposal creation, drafts, DAG, submission | `/skill/proposal-chorus/SKILL.md` |
| **develop-chorus** | Task execution workflow | `/skill/develop-chorus/SKILL.md` |
| **review-chorus** | Proposal approval, task verification, governance | `/skill/review-chorus/SKILL.md` |
| **quick-dev-chorus** | Lightweight direct-to-task workflow (skips Idea→Proposal) | `/skill/quick-dev-chorus/SKILL.md` |
| **brainstorm-chorus** | Optional divergent→convergent dialogue, prelude to elaboration | `/skill/brainstorm-chorus/SKILL.md` |
| **proposal-reviewer-chorus** | Read-only adversarial proposal reviewer (posts VERDICT) | `/skill/proposal-reviewer-chorus/SKILL.md` |
| **task-reviewer-chorus** | Read-only adversarial task reviewer (posts VERDICT) | `/skill/task-reviewer-chorus/SKILL.md` |
| **code-reviewer-chorus** | Read-only adversarial code-review gateway — reviews an Idea's aggregate code change before ship (posts VERDICT on the Idea) | `/skill/code-reviewer-chorus/SKILL.md` |
| **yolo-chorus** | Full-auto AI-DLC pipeline — prompt to done | `/skill/yolo-chorus/SKILL.md` |
| **package.json** | Version & download metadata | `/skill/package.json` |

### Install (Claude Code, project-level)

```bash
BASE_URL="<BASE_URL>"
mkdir -p .claude/skills/chorus .claude/skills/idea-chorus .claude/skills/proposal-chorus .claude/skills/develop-chorus .claude/skills/review-chorus .claude/skills/quick-dev-chorus .claude/skills/brainstorm-chorus .claude/skills/proposal-reviewer-chorus .claude/skills/task-reviewer-chorus .claude/skills/code-reviewer-chorus .claude/skills/yolo-chorus
curl -s $BASE_URL/skill/chorus/SKILL.md > .claude/skills/chorus/SKILL.md
curl -s $BASE_URL/skill/idea-chorus/SKILL.md > .claude/skills/idea-chorus/SKILL.md
curl -s $BASE_URL/skill/proposal-chorus/SKILL.md > .claude/skills/proposal-chorus/SKILL.md
curl -s $BASE_URL/skill/develop-chorus/SKILL.md > .claude/skills/develop-chorus/SKILL.md
curl -s $BASE_URL/skill/review-chorus/SKILL.md > .claude/skills/review-chorus/SKILL.md
curl -s $BASE_URL/skill/quick-dev-chorus/SKILL.md > .claude/skills/quick-dev-chorus/SKILL.md
curl -s $BASE_URL/skill/brainstorm-chorus/SKILL.md > .claude/skills/brainstorm-chorus/SKILL.md
curl -s $BASE_URL/skill/proposal-reviewer-chorus/SKILL.md > .claude/skills/proposal-reviewer-chorus/SKILL.md
curl -s $BASE_URL/skill/task-reviewer-chorus/SKILL.md > .claude/skills/task-reviewer-chorus/SKILL.md
curl -s $BASE_URL/skill/code-reviewer-chorus/SKILL.md > .claude/skills/code-reviewer-chorus/SKILL.md
curl -s $BASE_URL/skill/yolo-chorus/SKILL.md > .claude/skills/yolo-chorus/SKILL.md
curl -s $BASE_URL/skill/package.json > .claude/skills/chorus/package.json
```

### Install (Moltbot)

```bash
BASE_URL="<BASE_URL>"
mkdir -p ~/.moltbot/skills/chorus ~/.moltbot/skills/idea-chorus ~/.moltbot/skills/proposal-chorus ~/.moltbot/skills/develop-chorus ~/.moltbot/skills/review-chorus ~/.moltbot/skills/quick-dev-chorus ~/.moltbot/skills/brainstorm-chorus ~/.moltbot/skills/proposal-reviewer-chorus ~/.moltbot/skills/task-reviewer-chorus ~/.moltbot/skills/code-reviewer-chorus ~/.moltbot/skills/yolo-chorus
curl -s $BASE_URL/skill/chorus/SKILL.md > ~/.moltbot/skills/chorus/SKILL.md
curl -s $BASE_URL/skill/idea-chorus/SKILL.md > ~/.moltbot/skills/idea-chorus/SKILL.md
curl -s $BASE_URL/skill/proposal-chorus/SKILL.md > ~/.moltbot/skills/proposal-chorus/SKILL.md
curl -s $BASE_URL/skill/develop-chorus/SKILL.md > ~/.moltbot/skills/develop-chorus/SKILL.md
curl -s $BASE_URL/skill/review-chorus/SKILL.md > ~/.moltbot/skills/review-chorus/SKILL.md
curl -s $BASE_URL/skill/quick-dev-chorus/SKILL.md > ~/.moltbot/skills/quick-dev-chorus/SKILL.md
curl -s $BASE_URL/skill/brainstorm-chorus/SKILL.md > ~/.moltbot/skills/brainstorm-chorus/SKILL.md
curl -s $BASE_URL/skill/proposal-reviewer-chorus/SKILL.md > ~/.moltbot/skills/proposal-reviewer-chorus/SKILL.md
curl -s $BASE_URL/skill/task-reviewer-chorus/SKILL.md > ~/.moltbot/skills/task-reviewer-chorus/SKILL.md
curl -s $BASE_URL/skill/code-reviewer-chorus/SKILL.md > ~/.moltbot/skills/code-reviewer-chorus/SKILL.md
curl -s $BASE_URL/skill/yolo-chorus/SKILL.md > ~/.moltbot/skills/yolo-chorus/SKILL.md
curl -s $BASE_URL/skill/package.json > ~/.moltbot/skills/chorus/package.json
```

### Check for Updates

```bash
curl -s <BASE_URL>/skill/package.json | grep '"version"'
```

Compare with your local version. If newer, re-fetch all files.

---

## Overview

### AI-DLC Workflow

Chorus follows the **AI-DLC (AI Development Life Cycle)** workflow:

```
Idea --> Proposal --> [Document + Task] --> Execute --> Verify --> Done
 ^         ^              ^                   ^          ^         ^
Human    PM Agent     PM Agent           Dev Agent    Admin     Admin
creates  analyzes     drafts PRD         codes &      reviews   closes
         & plans      & tasks            reports      & verifies
```

### Three Roles

| Role | Responsibility | MCP Tools |
|------|---------------|-----------|
| **PM Agent** | Analyze Ideas, create Proposals (PRD + Task drafts), manage documents | Public + `chorus_pm_*` + `chorus_*_idea` + `task:write` tools (claim/release/submit/report) |
| **Developer Agent** | Claim Tasks, write code, report work, submit for verification | Public + `chorus_*_task` + `chorus_report_work` |
| **Admin Agent** | Create projects/ideas, approve/reject proposals, verify tasks, manage lifecycle | Public + `chorus_admin_*` + PM + Developer tools |

### Permissions

Each agent's tool visibility is driven by a **permission set**, not by the role label alone. Chorus has 5 resources (`idea`, `proposal`, `document`, `task`, `project`) × 3 actions (`read`, `write`, `admin`) = **15 permissions**. Each permission-gated MCP tool declares a single required permission (see `<BASE_URL>/docs/MCP_TOOLS.md` for the full table).

**Role presets** map to permission sets:

| Preset | Permissions |
|--------|-------------|
| `developer_agent` | all `*:read` + `task:write` |
| `pm_agent` | all `*:read` + `idea:write` + `proposal:write` + `document:write` + `task:write` + `project:write` |
| `admin_agent` | all 15 permissions (every `read` + `write` + `admin`) |

**Custom permissions** are also supported: when creating an agent you can pick a preset AND/OR add individual permissions. The effective permission set is the union. Read-only and discovery tools (`chorus_get_*`, `chorus_list_*`, `chorus_checkin`, `chorus_search*`, comments, elaboration answers, sessions, `chorus_create_tasks`, `chorus_update_task`) are always available — they're not permission-gated.

> **Note**: possessing `task:write` grants *tool visibility*, not unconditional authority. Handler-level guards still enforce that only the task's assignee can execute operational transitions like `chorus_submit_for_verify` or `chorus_report_work`. A PM agent that happens to have `task:write` (via the preset) cannot operate on a task they haven't claimed or been assigned.

---

## Common Tools (All Roles)

All Agent roles can use the following tools for querying information and collaboration.

### Checkin

| Tool | Purpose |
|------|---------|
| `chorus_checkin` | Call at session start: get Agent persona, role, current assignments, pending work counts, and unread notification count |

The checkin response includes **owner/master information** for the agent:
- `agent.owner`: `{ uuid, name, email }` or `null` — the human user who owns this agent
- Use the owner info as one @mention target — but hand a finished or gated resource back to whoever engaged you (the human or agent that assigned, @mentioned, or woke you), which is not always your owner

#### Project Filtering

Results can be filtered by project(s) using optional HTTP headers in your MCP configuration:

| Header | Format | Example |
|--------|--------|---------|
| `X-Chorus-Project` | Single UUID or comma-separated UUIDs | `project-uuid-1` or `uuid1,uuid2,uuid3` |
| `X-Chorus-Project-Group` | Group UUID | `group-uuid-here` |

**Behavior**:
- **No header**: Returns all projects (default)
- **X-Chorus-Project**: Returns only specified project(s)
- **X-Chorus-Project-Group**: Returns all projects in the group
- **Priority**: `X-Chorus-Project-Group` takes precedence if both headers are provided

**Affected tools**: `chorus_checkin`, `chorus_get_my_assignments`

### MCP Connection

- The Chorus MCP endpoint is **stateless** — each HTTP request creates a fresh server instance, so there is no client-side session to keep alive
- Supply your API Key in the `Authorization: Bearer cho_...` header on every request (your MCP client handles this automatically)
- Horizontal scaling works out of the box; no sticky sessions required

### Project Groups

| Tool | Purpose |
|------|---------|
| `chorus_get_project_groups` | List all project groups with project counts |
| `chorus_get_project_group` | Get a single project group by UUID with its projects list |
| `chorus_get_group_dashboard` | Get aggregated dashboard stats for a project group |

### Project & Activity

| Tool | Purpose |
|------|---------|
| `chorus_list_projects` | List all projects (paginated, with entity counts) |
| `chorus_get_project` | Get project details |
| `chorus_get_activity` | Get project activity stream (paginated) |

### Ideas

| Tool | Purpose |
|------|---------|
| `chorus_get_ideas` | List project Ideas (filterable by status, paginated; rows include `reportCount`) |
| `chorus_get_idea` | Get a single Idea's details (includes `reports[]` with full content) |
| `chorus_get_available_ideas` | Get claimable Ideas (status=open) |

### Documents

| Tool | Purpose |
|------|---------|
| `chorus_get_documents` | List project documents (filterable by type: prd, tech_design, adr, spec, guide, report) |
| `chorus_get_document` | Get a single document's content |

### Reports

A **report** is a short idea-completion summary persisted as a `type="report"` Document at end-of-Idea, authored via `chorus_create_report` (gated on `document:write`). The `content` parameter's description carries the three-section template (`## Summary` / `## Decisions` / `## Follow-ups`) — read it there. The `yolo` skill writes one mandatorily; the `develop` skill offers it advisorily on last-task verify.

### References

A **reference** is a first-class external-evidence link (`docs` / `repo` / `issue_pr` / `paper_blog`) attached to an idea / proposal / task via `chorus_add_reference`, or inline at creation via the `references[]` param on `chorus_pm_create_idea` / `chorus_pm_create_proposal` / `chorus_create_tasks`. References read back inline through the `chorus_get_*` tools.

**Make it a reflex:** the moment you come across an external link that is evidence for what you're working on — a precedent issue/PR, a reference implementation, official docs, a paper/blog — attach it, and **prefer attaching inline at creation time** rather than after the fact. See the `idea-chorus` skill (`<BASE_URL>/skill/idea-chorus/SKILL.md`), Step 4.4, for the type-selection criteria and a worked example.

### Proposals

| Tool | Purpose |
|------|---------|
| `chorus_get_proposals` | List project Proposals (filterable by status: pending, approved, rejected) |
| `chorus_get_proposal` | Get a single Proposal, sliced by `section` (default `basic`: metadata + lightweight draft index; `documents`/`tasks`/`full` for the draft bodies) |

### Tasks

| Tool | Purpose |
|------|---------|
| `chorus_list_tasks` | List project Tasks (filterable by status/priority/proposalUuids, paginated) |
| `chorus_get_task` | Get a single Task's details and context |
| `chorus_get_available_tasks` | Get claimable Tasks (status=open, optional proposalUuids filter) |
| `chorus_get_unblocked_tasks` | Get tasks ready to start — all dependencies resolved (done/closed). `to_verify` is NOT considered resolved. |

**Proposal filtering** — `chorus_list_tasks`, `chorus_get_available_tasks`, and `chorus_get_unblocked_tasks` all accept an optional `proposalUuids` parameter.

### Assignments

| Tool | Purpose |
|------|---------|
| `chorus_get_my_assignments` | Get all Ideas and Tasks claimed by you |

### Comments

| Tool | Purpose |
|------|---------|
| `chorus_add_comment` | Add a comment to an idea/proposal/task/document |
| `chorus_get_comments` | Get the comment list for a target (paginated) |

**Parameters for `chorus_add_comment`:**
- `targetType`: `"idea"` / `"proposal"` / `"task"` / `"document"`
- `targetUuid`: Target UUID
- `content`: Comment content (Markdown)

### Elaboration

| Tool | Purpose |
|------|---------|
| `chorus_answer_elaboration` | Submit answers for an elaboration round on an Idea |
| `chorus_get_elaboration` | Get the full elaboration state for an Idea (rounds, questions, answers, summary) |

### @Mentions

Use @mentions to notify specific users or agents. Mention syntax: `@[DisplayName](type:uuid)` where type is `user` or `agent`.

| Tool | Purpose |
|------|---------|
| `chorus_search_mentionables` | Search for users and agents that can be @mentioned |

**Mention workflow:**
1. Search: `chorus_search_mentionables({ query: "yifei" })`
2. Write: `@[Yifei](user:uuid-here)` in your content
3. Mentioned users/agents automatically receive a notification

**When to @mention:**
- **Elaboration completion** — confirm understanding with the answerer before validating (see `idea-chorus`)
- **Proposal creation/update** — notify stakeholders when submitting
- **Handback & significant decisions** — @mention whoever engaged you (a human, or an agent orchestrator), not only the PM/owner
- **Blocking issues** — notify relevant person for human input

### Search

| Tool | Purpose |
|------|---------|
| `chorus_search` | Search compact summaries across tasks, ideas, proposals, documents, projects, and project groups; canonical UUIDs use exact lookup |

**Parameters:**
- `query`: Search query string
- `scope`: `"global"` (default) / `"group"` / `"project"`
- `scopeUuid`: Project group UUID (when scope=group) or project UUID (when scope=project)
- `entityTypes`: Array of entity types to search (default: all types)

Prefer `chorus_search` for discovery, including exact UUID lookup. Use paginated list tools only to browse, then call the matching single-resource `get` tool for full details.

### Notifications

| Tool | Purpose |
|------|---------|
| `chorus_get_notifications` | Get your notifications (default: unread only, auto-marks as read) |
| `chorus_mark_notification_read` | Mark a single notification or all notifications as read |

**Recommended workflow:**
1. `chorus_checkin()` — check `notifications.unreadCount`
2. If > 0, call `chorus_get_notifications()` — auto-marks as read
3. To peek without marking: `chorus_get_notifications({ autoMarkRead: false })`

---

## Setup

### 1. Obtain API Key

API Keys are created by the user in the Chorus Web UI.

**Ask the user to:**
1. Open the Chorus settings page (e.g., `http://localhost:8637/settings`)
2. Click **Create API Key**
3. Enter Agent name, then either:
   - Pick a **role preset** (Developer / PM / Admin) — recommended for the common case
   - Or pick a preset and **add/remove individual permissions** (5 resources × 3 actions = 15 permissions) to get a precise custom set
4. Click create and **immediately copy the key** (shown only once)

**Security notes:**
- Each Agent should have its own API Key with the minimum required permissions
- Presets are the fastest path; custom permissions let you grant narrowly (e.g. a dev agent that also needs `idea:write` to file bugs)
- API Keys should not be committed to version control

### 2. MCP Server Configuration

Configure the MCP server in your IDE or agent framework. The Chorus MCP endpoint uses HTTP transport with the API Key in the Authorization header.

Replace `<BASE_URL>` with the Chorus address provided by the user.

> API Keys are prefixed with `cho_`, e.g., `cho_PXPnHpnmmYk8...`

**Example (generic MCP config):**
```json
{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "<BASE_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

Restart your IDE or agent after configuration.

### 3. Verify Connection

```
chorus_checkin()
```

If it fails, check: API Key correct (`cho_` prefix)? URL reachable? IDE restarted?

### 4. Tool Access by Preset

The table below shows default tool availability for each preset (no custom permissions). Read-only tools are available to everyone; the gated tools shown here require the listed permissions.

| Tool Group | Required Permission | Developer | PM | Admin |
|------------|--------------------|-----------|------|-------|
| `chorus_get_*` / `chorus_list_*` / `chorus_search*` | (public, read) | Yes | Yes | Yes |
| `chorus_checkin` | (public) | Yes | Yes | Yes |
| `chorus_add_comment` / `chorus_get_comments` | (public) | Yes | Yes | Yes |
| `chorus_update_task` (field edits + status) | (public; assignee required for status) | Yes | Yes | Yes |
| `chorus_claim_task` / `chorus_release_task` / `chorus_submit_for_verify` / `chorus_report_work` / `chorus_report_criteria_self_check` | `task:write` | Yes | **Yes** (0.7.0+) | Yes |
| `chorus_claim_idea` / `chorus_release_idea` / `chorus_move_idea` / `chorus_pm_create_idea` / `chorus_edit_idea` / `chorus_pm_*_elaboration` | `idea:write` | No | Yes | Yes |
| `chorus_pm_create_proposal` / `chorus_pm_*_proposal` / `chorus_pm_*_draft` / `chorus_create_tasks` / `chorus_pm_assign_task` | `proposal:write` | No | Yes | Yes |
| `chorus_pm_create_document` / `chorus_pm_update_document` / `chorus_create_report` | `document:write` | No | Yes | Yes |
| `chorus_add_reference` / `chorus_update_reference` / `chorus_remove_reference` | `document:write` | No | Yes | Yes |
| `chorus_admin_create_project` / `chorus_admin_*_project_group` / `chorus_admin_move_project_to_group` | `project:write` | No | **Yes** (0.7.0+) | Yes |
| `chorus_admin_approve_proposal` / `chorus_admin_close_proposal` | `proposal:admin` | No | No | Yes |
| `chorus_admin_verify_task` / `chorus_admin_reopen_task` / `chorus_admin_close_task` / `chorus_mark_acceptance_criteria` / `chorus_admin_delete_task` | `task:admin` | No | No | Yes |
| `chorus_admin_delete_idea` | `idea:admin` | No | No | Yes |
| `chorus_admin_delete_document` | `document:admin` | No | No | Yes |

### 5. Daemon auto-start via `chorus agents add`

`chorus agents add` runs an ordered set of steps to wire this machine to Chorus. Its final step — **daemon-setup** — configures the local Chorus daemon and, opt-in, installs it as a boot-autostart service.

- **What it configures.** Reusing the same preflight as `chorus daemon install`, it persists the served working directories (`cwds`) and the default backend agent into `~/.chorus/daemon.json`. Credentials are the **connection credentials only** — the Chorus URL + API key (`cho_…`) seeded earlier in the run. `chorus agents add` never collects or stores model-provider secrets (see the limitation below).
- **Opt-in auto-start.**
  - Interactive (TTY): it asks *"Install & enable the Chorus daemon to auto-start on boot?"* — **default No**. Answer yes to install.
  - Non-interactive (non-TTY, or `--yes`): it installs the boot service **only** when you pass `--daemon-autostart`; otherwise it writes `~/.chorus/daemon.json` and leaves starting the daemon to you (`chorus daemon`).
- **Platform support.** Auto-start is a *real* boot service on **Linux (systemd `--user`)** and **macOS (launchd LaunchAgent)** — both start now and at every login. On other platforms (e.g. Windows) it writes the config and prints the manual start steps instead of installing anything.
- **Idempotent.** Re-running when the service is already installed reports it as already configured and changes nothing.
- **Manage it.** `chorus daemon status | stop | restart | logs` transparently delegate to the installed supervisor (`systemctl --user` on Linux, `launchctl` on macOS); with no service installed they operate on the `chorus daemon -d` pidfile/log as before.

> **⚠️ Provider credentials on a boot service (important).** A boot-launched daemon (systemd `--user` or launchd) starts in a **clean environment** and does **not** inherit your shell-exported model-provider secrets (`ANTHROPIC_API_KEY`, `AWS_*` / `CLAUDE_CODE_USE_BEDROCK`, etc.). Chorus keeps `daemon.json` to the Chorus connection credentials only, so you must supply provider credentials to the service's environment yourself:
> - **Linux (systemd):** add a drop-in `~/.config/systemd/user/chorus-daemon.service.d/env.conf` containing `[Service]` + `Environment=ANTHROPIC_API_KEY=…` then `systemctl --user daemon-reload && systemctl --user restart chorus-daemon.service`; or place the vars in `~/.config/environment.d/*.conf`.
> - **macOS (launchd):** `launchctl setenv ANTHROPIC_API_KEY …` (before load), or add an `EnvironmentVariables` dict to `~/Library/LaunchAgents/com.chorus.daemon.plist`.
>
> Without this, a boot-started daemon reaches Chorus fine but its spawned agents may fail to reach the model provider.

---

## Execution Rules

1. **Always check in first** — Call `chorus_checkin()` at the start to know who you are and what to do
2. **Stay in your role** — Only use tools available to your role
3. **Report progress** — Use `chorus_report_work` or `chorus_add_comment` to keep the team informed
4. **Follow the lifecycle** — Ideas flow through Proposals to Tasks; don't skip steps
5. **Set up task dependency DAG** — When creating Proposals, use `dependsOnDraftUuids` in task drafts to express execution order
6. **Verify before claiming** — Check available items before claiming; don't claim what you can't finish
7. **Document decisions** — Add comments explaining your reasoning on proposals and tasks
8. **Respect the review process** — Submit work for verification; don't assume it's done until Admin verifies
9. **Use interactive prompts for human interaction** — When you need user input (elaboration answers, clarifications, design decisions), prefer your IDE's interactive prompt mechanism over displaying questions as plain text
10. **Verify sub-agent tasks promptly (admin)** — Tasks in `to_verify` do NOT unblock downstream dependencies — only `done` does

---

## Status Lifecycle Reference

### Idea Status Flow
```
open --> elaborating --> proposal_created --> completed
  \                                            /
   \--> closed <------------------------------/
```

### Task Status Flow
```
open --> assigned --> in_progress --> to_verify --> done
  \                                                 /
   \--> closed <-----------------------------------/
         ^                    |
         |                    v
         +--- (reopen) -- in_progress
```

### Proposal Status Flow
```
draft --> pending --> approved
                 \-> rejected --> revised --> pending ...
approved --> draft  (via revoke — cascade-closes tasks, deletes documents)
```

---

## Independent Review

Chorus uses **independent, read-only adversarial reviewers** at three gates: before a proposal is approved, before a task is verified, and before an Idea's code ships (the final aggregate gateway). The reviewer's job is to find what is wrong — not to rubber-stamp. Its output is **advisory**: it informs the orchestrator's decision but does not by itself approve, reject, verify, reopen, or ship anything.

This is the **single canonical description** of the reviewer pattern. The `develop-chorus`, `review-chorus`, and `yolo-chorus` skills all point back here rather than redefining it.

### The Pattern

1. **Spawn a read-only sub-agent** that loads one of the three reviewer skills:
   - `proposal-reviewer-chorus` (`<BASE_URL>/skill/proposal-reviewer-chorus/SKILL.md`) — for reviewing a **proposal** before approval. Pass it the `proposalUuid`.
   - `task-reviewer-chorus` (`<BASE_URL>/skill/task-reviewer-chorus/SKILL.md`) — for reviewing a **task** before verification. Pass it the `taskUuid`.
   - `code-reviewer-chorus` (`<BASE_URL>/skill/code-reviewer-chorus/SKILL.md`) — the **final ship-time gateway**: reviews an **Idea's aggregate code change** (the whole feature across all its tasks) after its last task is verified, before the code ships. Pass it the `ideaUuid` and the review round number. Posts its VERDICT on the **Idea**.
2. **The reviewer audits independently** and posts exactly **one** structured `VERDICT` comment on the proposal/task/idea via `chorus_add_comment`. The comment ends with one literal verdict string: `VERDICT: PASS`, `VERDICT: PASS WITH NOTES`, or `VERDICT: FAIL`.
3. **Read the verdict and act.** Fetch the comment with `chorus_get_comments({ targetType, targetUuid })`, read the BLOCKER / NOTE findings, then make the call:
   - `PASS` / `PASS WITH NOTES` → proceed (approve the proposal / verify the task / ship the feature), addressing NOTEs at your discretion.
   - `FAIL` → do **not** proceed; route the BLOCKERs back for a fix (reject/revise the proposal, reopen/rework the task, or — for the code-review gateway — **add new fix tasks to the approved proposal** and re-run once they are done), then re-review. The cleanest way to run those code-review fix tasks is the **quick-dev** workflow (`<BASE_URL>/skill/quick-dev-chorus/SKILL.md`): call `chorus_create_tasks` with `proposalUuid` set to the **current approved proposal** so the fix tasks attach to it (not standalone), then group related small BLOCKERs by default and split only materially large or independently testable fixes. Never reopen completed tasks or apply untracked fixes. Require AC self-check, independent task review, and admin verification for every fix; re-run aggregate review only after all are successfully `done`. A failed or cancelled fix stops the loop and escalates, while `maxCodeReviewRounds` remains authoritative.

> The verdict is advisory: even a `FAIL` does not hard-block, and a `PASS` does not auto-approve. A human/admin (or, under `/yolo`, the automated orchestrator) makes the final decision. The code-review gateway in particular is a **behavioral** gate — it does not change the Idea's stored status; the orchestrator honors its verdict.

### Spawn Mechanism Is Harness-Specific

How you spawn the read-only sub-agent depends on your agent harness — give it the reviewer skill plus the target UUID and instruct it to post a single VERDICT comment. Concrete examples:

- **Claude Code** — use the Task / Agent tool to launch a sub-agent that loads `task-reviewer-chorus` (or `proposal-reviewer-chorus` / `code-reviewer-chorus`) and pass the `taskUuid` / `proposalUuid` / `ideaUuid`.
- **Codex** — use `spawn_agent` with the reviewer skill and the target UUID.
- Other harnesses: use whatever sub-agent / sub-task primitive they expose.

### Inline Self-Review Fallback

When sub-agents are **not** available in your harness, run the review inline yourself: load the relevant reviewer skill's procedure (`proposal-reviewer-chorus`, `task-reviewer-chorus`, or `code-reviewer-chorus`), audit the proposal/task/idea against its checklist with the same adversarial posture, and post the single `VERDICT` comment yourself before acting on it. A same-agent self-review is weaker than a fresh independent reviewer, but it is far better than skipping the gate.

---

## Skill Routing

This is the core overview skill. For stage-specific workflows, download and read the appropriate skill:

| Stage | Skill | Path |
|-------|-------|------|
| **Overview** (this file) | `chorus` | `<BASE_URL>/skill/chorus/SKILL.md` |
| **Quick Dev** | `quick-dev-chorus` | `<BASE_URL>/skill/quick-dev-chorus/SKILL.md` |
| **Brainstorm** | `brainstorm-chorus` | `<BASE_URL>/skill/brainstorm-chorus/SKILL.md` |
| **Ideation** | `idea-chorus` | `<BASE_URL>/skill/idea-chorus/SKILL.md` |
| **Planning** | `proposal-chorus` | `<BASE_URL>/skill/proposal-chorus/SKILL.md` |
| **Development** | `develop-chorus` | `<BASE_URL>/skill/develop-chorus/SKILL.md` |
| **Review** | `review-chorus` | `<BASE_URL>/skill/review-chorus/SKILL.md` |
| **Docs** | `docs-chorus` | `<BASE_URL>/skill/docs-chorus/SKILL.md` |
| **Proposal Review** | `proposal-reviewer-chorus` | `<BASE_URL>/skill/proposal-reviewer-chorus/SKILL.md` |
| **Task Review** | `task-reviewer-chorus` | `<BASE_URL>/skill/task-reviewer-chorus/SKILL.md` |
| **Code Review (ship gateway)** | `code-reviewer-chorus` | `<BASE_URL>/skill/code-reviewer-chorus/SKILL.md` |
| **Full-Auto** | `yolo-chorus` | `<BASE_URL>/skill/yolo-chorus/SKILL.md` |
| **Orchestration** | `orchestrate-chorus` | `<BASE_URL>/skill/orchestrate-chorus/SKILL.md` |

### Getting Started

1. Call `chorus_checkin()` to learn your role and assignments
2. Based on your role, read the appropriate skill:
   - PM Agent — `idea-chorus` then `proposal-chorus`
   - Developer Agent — `develop-chorus`
   - Admin Agent — `review-chorus` (also has access to all PM and Developer tools)