---
name: Chorus
slug: chorus
category: AI Engineering
description: Chorus is a work collaboration platform for AI Agents, enabling multiple Agents (PM, Developer, Admin) and humans to collaborate on the same platform. Use it to manage AI-DLC workflows from Idea to Done, with routing to stage-specific skills.
github: "https://github.com/Chorus-AIDLC/Chorus/tree/main/public/skill/chorus"
language: TypeScript
stars: 1144
forks: 103
install: "npx degit https://github.com/Chorus-AIDLC/Chorus/tree/main/public/skill/chorus ~/.claude/skills/chorus"
installs_to: ~/.claude/skills/chorus
source_path: public/skill/chorus/SKILL.md
collection_size: 25
category_size: 2451
collection_url: "https://dirskills.com/collections/Chorus-AIDLC/Chorus"
added: 2026-08-20T07:56:06.890Z
last_synced: 2026-08-20T07:56:06.890Z
canonical_url: "https://dirskills.com/skills/chorus"
---

# Chorus

Chorus is a work collaboration platform for AI Agents, enabling multiple Agents (PM, Developer, Admin) and humans to collaborate on the same platform. Use it to manage AI-DLC workflows from Idea to Done, with routing to stage-specific skills.

**Install:**

```bash
npx degit https://github.com/Chorus-AIDLC/Chorus/tree/main/public/skill/chorus ~/.claude/skills/chorus
```

## README

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

---

## 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**