/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.18.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.

> **⚠️ Tool namespace under dsh.** The Chorus tools are exposed by the connected Chorus **MCP server**, and dsh namespaces MCP-sourced tools with a `mcp__chorus__` prefix. Wherever this skill (or any Chorus skill) writes a bare tool name like `chorus_get_task`, the actual callable name in your dsh session is `mcp__chorus__chorus_get_task` (e.g. `chorus_checkin` → `mcp__chorus__chorus_checkin`, `chorus_submit_for_verify` → `mcp__chorus__chorus_submit_for_verify`). The bare names are kept in the docs for readability and parity with the Chorus tool reference; **prepend `mcp__chorus__` when you actually invoke them.** This single rule applies to every Chorus skill — it is not repeated in each one.

> **Headless rule.** dsh normally provides `ask_user_question`. When `CHORUS_DAEMON_HEADLESS=1`, never call it or wait on terminal input. Persist human decisions through a Chorus elaboration round and/or an `@mention` comment, then end the turn.

---

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. (Reminder: prepend `mcp__chorus__` when invoking — see the namespace note above.)

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 the `projectUuids` array in the plugin configuration (see [Setup](#setup) below).

**Behavior**:

• **Empty array (default)**: Returns all projects
• **One or more UUIDs**: Returns only matching projects and their events

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

Session (Sub-Agents Only)

Unlike the Claude Code plugin (which fully automates session lifecycle via hooks), **dsh does not run the Claude Code SubagentStart / heartbeat / cleanup hooks**. Session handling is therefore **manual** on dsh. See `develop-chorus` for the full manual session protocol. In short, a sub-agent must:

1. `chorus_create_session` — create its own session once, near the start (or reuse an injected `sessionUuid` if the host provided one) 2. `chorus_session_checkin_task` — before starting work on a task 3. Pass `sessionUuid` to `chorus_update_task` and `chorus_report_work` 4. `chorus_session_checkout_task` — when done with a task 5. `chorus_close_session` — when the sub-agent finishes (no hook closes it for you)

Main agent / Team Lead: no session needed — call