/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.16.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, use the dedicated skills listed in [Skill Routing](#skill-routing) below.

---

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 `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 to know who to @mention for confirmations and approvals

Project Filtering

Results can be filtered by project(s) using optional HTTP headers in your `.mcp.json` 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, backward compatible)
• **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`

**Example `.mcp.json`** (Pi auto-discovers this via pi-mcp-adapter; no installer needed):

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "http://localhost:8637/api/mcp",
      "headers": {
        "Authorization": "Bearer cho_xxx",
        "X-Chorus-Project": "project-uuid-1,project-uuid-2"
      }
    }
  }
}

Session (Sub-Agents Only)

The Chorus Pi extension **fully automates** session lifecycle. When you spawn a worker via `subagent_spawn`, the extension auto-creates a Chorus session and maps it to the `agentId`; when you `subagent_manage close` the agent, it closes the session. Sub-agents only need to:

1. `chorus_session_checkin_task` — before starting work on a task 2. `chorus_session_checkout_task` — when done with a task 3. Pass `sessionUuid` to `chorus_update_task` and `chorus_report_work`

Main agent / Team Lead: no session needed — call tools without `sessionUuid`. See `/skill:develop` for details.

> Reviewer sub-agents (`chorus-proposal-reviewer`, `chorus-task-reviewer`, `chorus-code-reviewer`) do **not** get a Chorus session — they are read-only and post a single VERDICT comment.

Project Groups

Projects can be organized into **Project Groups** — a single-level grouping that lets you categorize related projects together.

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

#