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.4","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 below.

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

---

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 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 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), OpenClaw does not run the Claude Code SubagentStart / heartbeat / cleanup hooks. Session handling is therefore manual on OpenClaw. See /develop 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 tools without sessionUuid.

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

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 section template — read it there. /yolo writes one mandatorily; /develop 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. (Bare tool names per the namespace note above — prepend chorus__ when invoking.)

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 /idea (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 (array of proposal UUID strings).

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)
• 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__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 must be created manually by the user in the Chorus Web UI.

Ask the user to:

1. Open the Chorus settings page (e.g., https://chorus.example.com/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. Plugin Configuration

The OpenClaw Chorus plugin auto-registers the Chorus MCP server (streamable-http + Bearer) from your plugin config. Config file: ~/.openclaw/openclaw.json.

Add the Chorus plugin configuration under plugins.entries.chorus-openclaw-plugin.config:

{
  "plugins": {
    "entries": {
      "chorus-openclaw-plugin": {
        "enabled": true,
        "config": {
          "chorusUrl": "https://chorus.example.com",
          "apiKey": "cho_your_api_key_here",
          "projectUuids": [],
          "autoStart": true
        }
      }
    }
  }
}

Configuration fields:

Field	Required	Description
chorusUrl	Yes	Chorus server URL (e.g., https://chorus.example.com)
apiKey	Yes	Chorus API Key (must start with cho_ prefix)
projectUuids	No	Array of project UUIDs to monitor. Empty array = all projects.
autoStart	No	Auto-claim and begin work on task_assigned events (default: true)

Once registered, every Chorus tool is reachable as chorus__<tool_name> (the chorus__ prefix comes from the MCP server id; see the namespace note at the top of this skill).

3. Verify Connection

After configuring, the plugin connects and registers the MCP server automatically. Verify by calling:

chorus__chorus_checkin()

If it fails, check: API Key correct (cho_ prefix)? URL reachable? Plugin enabled in config? MCP server shown as connected in OpenClaw?

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 / chorus_update_task (dependency edits via addDependsOn/removeDependsOn)	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 /

5. Review Skills

The plugin bundles three independent review skills: /proposal-reviewer, /task-reviewer, and /code-reviewer. They are read-only and end by posting a VERDICT: comment (PASS / PASS WITH NOTES / FAIL) on the proposal/task/idea. /code-reviewer is the final ship-time gateway: after an Idea's last task is verified it reviews the Idea's aggregate code change (the whole feature across all its tasks) and posts its VERDICT on the idea.

How review runs on OpenClaw. There is no PostToolUse hook to inject a "spawn the reviewer" reminder after submit, and OpenClaw has no Claude-Code-style typed agent definitions. Instead, the proposal/develop/yolo skills put the reviewer step inline: the orchestrating agent uses the OpenClaw sessions_spawn tool to spawn a sub-agent and instructs it (in the spawn task) to run the /proposal-reviewer, /task-reviewer, or /code-reviewer skill against the entity (passing the ideaUuid for code review), then waits for the VERDICT (poll subagents / sessions_yield). Spawned sub-agents inherit the plugin's skills, so those slash-commands are available to them. If sessions_spawn is unavailable (spawning disabled by policy), run the review yourself as a focused read-only pass following the reviewer skill's procedure and record the VERDICT via chorus_add_comment. See the relevant stage skill for the exact procedure.

Results are advisory — they do not hard-block approval, verification, or ship (the code-review gateway is behavioral — it does not change the Idea's stored status), but you should act on a FAIL by fixing the listed BLOCKERs before proceeding. For a code-review FAIL, the orchestrator invokes quick-dev (/quick-dev) to create new tasks on the original approved proposal; it does not reopen completed tasks or apply untracked fixes. Group related small BLOCKERs by default and split only materially large or independently testable fixes. Every fix task must pass AC self-check, independent task review, and admin verification. Re-run aggregate review only after all fixes are successfully done; a failed or cancelled fix stops the loop and escalates. Keep maxCodeReviewRounds authoritative.

6. Enable OpenSpec Mode (Optional)

Opt-in spec-driven path: /proposal, /develop, /yolo write proposal.md / design.md / spec deltas on disk and mirror them into Chorus drafts. Fully optional — free-form authoring works without it. The stage skills re-check the three activation signals inline (OpenClaw has no SessionStart hook): CHORUS_OPENSPEC_MODE ≠ off, an openspec/ directory at the project root, and the openspec CLI on PATH.

When the user wants it on, actually enable it for them — run whichever steps are missing, don't just describe them:

npm i -g @fission-ai/openspec       # 1. install the CLI if it's not on PATH (global, pure Node)
openspec init --tools none          # 2. scaffold the openspec/ directory

OpenSpec has no OpenClaw integration (it's not in the --tools list), so --tools none is correct — Chorus's detection only needs the openspec/ directory and the stage skills drive the CLI directly. There's no SessionStart banner on OpenClaw — the stage skills re-check the three signals inline, so once the directory and CLI are both present they fold in /openspec-aware automatically. To turn it off, set CHORUS_OPENSPEC_MODE=off.

---

SSE Event-Driven Model (Bidirectional Daemon Host)

The OpenClaw Chorus plugin runs a background service that holds a Server-Sent Events (SSE) connection to the Chorus server. It is a fully bidirectional daemon host, on a par with the Chorus CLI daemon: it is not just a receiver of notifications that wakes the agent — it also registers a connection identity, reports its execution lifecycle back to the server, and accepts reverse control commands (interrupt / resume / deliver an instruction turn) so a human in the Chorus UI can observe and steer an in-flight run. Instead of polling, the agent is notified the moment something needs its attention, and the server always has a live, controllable view of what this host is running.

Inbound: notifications wake the agent

1. The plugin connects to the Chorus SSE endpoint using the configured API Key
2. When a notification event arrives, the plugin fetches the full notification details
3. If projectUuids is configured, events from other projects are filtered out
4. The plugin resolves the event's lineage and routes it to the agent (an in-process embedded-agent run) with context-rich instructions
5. If autoStart is enabled, certain events (like task_assigned) auto-claim before waking the agent

Connection identity (connection_registered)

Right after the SSE handshake, the server assigns this stream a DaemonConnection and reports its connectionUuid via a connection_registered data event. The plugin captures that uuid (refreshing it on every reconnect, so a recycled stream never carries a stale identity) and uses it as the single source of truth for "which connection am I." This identity is what makes the connection addressable: it appears in the Chorus Agent Connections UI, scopes the reverse control channel, and stamps every outbound report below.

Outbound: the daemon reports its lifecycle to the server

While a woken run executes, the plugin reports back over the /api/daemon/* REST surface (host-agnostic, the same payload shapes the CLI daemon sends) so the connection's activity is observable in the UI in real time:

Report	What it conveys
turn-advance	Advances the wake's turn lifecycle (running → ended) so the UI knows when a turn starts and finishes
execution-state	Publishes this connection's running/queued execution snapshot (entity, root idea, status, start time) — the live "what is this host doing" view
transcript	Streams the finalized user/assistant text of the turn (only { role, text } — no internals) so the run's transcript is visible in the UI
report-interrupt	Records that a run ended as interrupted (reason user or crash) rather than completing

Reports are fire-and-forget and never crash the run: a network/non-2xx failure is logged with its cause and surfaced as a structured failure result, never silently swallowed.

Reverse control channel (interrupt / resume / deliver_turn)

The server publishes control commands on a control:{connectionUuid} channel and forwards them as type:"control" SSE events. These are forked away from the wake path — a control event can never spawn a new agent run for itself. The plugin acts on a command only after a double-check: (1) the command's targetConnectionUuid matches this connection's own uuid (a stale/recycled uuid or another connection's command is ignored and logged), and (2) for interrupt, this host actually holds a running embedded-agent run for that entity.

Command	Effect
interrupt	Aborts the matching in-flight run (true mid-run stop via its AbortController), then reports report-interrupt
resume	Re-dispatches the entity's wake to continue the same session (the synthetic "resume" wake; resolves lineage so it anchors on the same direct idea)
deliver_turn	Runs a human instruction turn delivered into the conversation — precisely the one turn when a turnUuid is present (origin-only live delivery), or a full pending-turns sweep as a fallback for an older server

Backfill on reconnect

After an SSE gap, the plugin re-pulls (1) unread notifications missed during the gap and (2) this connection's unstarted pending turns from the turn table (the safety net for a deliver_turn ping lost while disconnected). The two sources share a seen-set, so a turn is run at most once across live delivery and backfill.

Event Types

Event	Trigger	Agent Action
task_assigned	A task is assigned to this agent	Fetch task details with chorus_get_task, begin work
mentioned	Someone @mentions this agent in a comment	Review the entity and respond via chorus_add_comment
elaboration_requested	PM starts an elaboration round on a claimed Idea	Review questions with chorus_get_elaboration
elaboration_answered	Stakeholder answers elaboration questions	Review answers, validate or request follow-up
proposal_rejected	Admin rejects a Proposal	Review feedback, fix drafts, resubmit
proposal_approved	Admin approves a Proposal	Check new tasks with chorus_get_available_tasks
idea_claimed	An Idea is assigned to this agent	Review idea with chorus_get_idea, begin elaboration
task_verified	Admin verifies a completed task	Check if downstream tasks are unblocked
task_reopened	Admin reopens a task for rework	Review feedback in comments, fix issues

Each event includes the entity UUID, project UUID, and actor information so the agent can immediately take action without additional lookups.

---

Execution Rules

1. Always check in first — Call chorus_checkin() at session start
2. Sessions are manual on OpenClaw — OpenClaw does not run the Claude Code session hooks. Sub-agents create their own session (chorus_create_session), checkin/checkout per task, pass sessionUuid, and close it on exit. The main agent skips session tools. See /develop.
3. Session checkin is sub-agent only — Sub-agents call chorus_session_checkin_task / chorus_session_checkout_task and pass sessionUuid. Main agent skips session tools entirely.
4. Stay in your role — Only use tools available to your role
5. Report progress — Use chorus_report_work or chorus_add_comment
6. Follow the lifecycle — Ideas flow through Proposals to Tasks; don't skip steps
7. Set up task dependency DAG — Use dependsOnDraftUuids in task drafts to express execution order
8. Verify before claiming — Check available items before claiming
9. Document decisions — Add comments explaining your reasoning
10. Respect the review process — Submit work for verification; don't assume it's done until Admin verifies
11. Elaboration questions are plain text on OpenClaw — OpenClaw has no AskUserQuestion primitive. Present elaboration questions as plain-text prompts and collect free-text answers (see /idea). In /yolo the agent self-answers without any user interaction.
12. Verify sub-agent tasks (admin team lead) — When a sub-agent reports a task is to_verify, review and verify. Tasks in to_verify do NOT unblock downstream — 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)

---

Skill Routing

This is the core overview skill. For stage-specific workflows, use:

Stage	Skill	Description
Full Auto	/yolo	Full-auto AI-DLC pipeline — from prompt to done. Automates Idea → Proposal → Execute → Verify with adversarial reviewers
Orchestration	/orchestrate	Coordinate OTHER agents & humans across the lifecycle — delegate ideas (chorus_pm_assign_idea) & tasks, fan a theme out to child ideas, run independent reviewers, and gatekeep the proposal/verify gates
Quick Dev	/quick-dev	Skip Idea→Proposal, create tasks directly, execute, and verify
Ideation	/idea	Claim Ideas, run elaboration rounds, prepare for proposal
Planning	/proposal	Create Proposals with document & task drafts, manage dependency DAG, submit for review
Development	/develop	Claim Tasks, report work, manual session & sub-agent management
Review	/review	Approve/reject Proposals, verify Tasks, project governance
Docs	/docs	Consult the live Chorus documentation site to answer product-usage questions — UI workflow, agent/plugin setup, API/MCP, deployment, operations
OpenSpec mode	openspec-aware	Opt-in shared sub-procedure invoked by /proposal, /develop, and /yolo whenever the user has the openspec CLI installed. Scaffolds openspec/changes/<slug>/ on disk and mirrors files into Chorus document drafts via the chorus-api.sh wrapper. Runs an inline three-check detection (no SessionStart hook on OpenClaw). Skips silently in fallback mode.

Getting Started

1. Call chorus_checkin() to learn your role and assignments
2. Based on your role, use the appropriate skill:
   • Full Auto → /yolo — give a prompt, agent handles everything (requires Admin-preset permissions: write on every resource + approve/verify admin bits)
   • PM Agent → /idea then /proposal
   • Developer Agent → /develop
   • Admin Agent → /review (also has access to all PM and Developer tools)