chorus

name	chorus
description	Chorus AI Agent collaboration platform — overview, tools, and workflow routing.
metadata	{"openclaw":{"emoji":"🎵","homepage":"https://github.com/Chorus-AIDLC/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.

---

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	Common + chorus_pm_* + chorus_claim_idea
Developer Agent	Claim Tasks, write code, report work, submit for verification	Common + chorus_claim_task + chorus_report_work
Admin Agent	Create projects/ideas, approve/reject proposals, verify tasks, manage lifecycle	Common + chorus_admin_* + PM + Developer tools

---

Common Tools (All Roles)

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

Checkin

Tool	Purpose
chorus_checkin	Call at startup: 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 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

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

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 tool's description carries the section template — read it there. The yolo skill writes one mandatorily; the develop skill offers it advisorily on last-task verify.

Proposals

Tool	Purpose
chorus_get_proposals	List project Proposals (filterable by status: draft, pending, approved, rejected)
chorus_get_proposal	Get a single Proposal's details, including documentDrafts and taskDrafts

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.
chorus_create_tasks	Batch create tasks. Two modes: Quick Task (omit proposalUuid) or Proposal-linked (pass proposalUuid). Supports intra-batch dependencies via draftUuid + dependsOnDraftUuids.
chorus_update_task	Update task fields (title, description, priority, storyPoints, dependencies) or change status (in_progress, to_verify).

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
• Proposal creation/update — notify stakeholders when submitting
• Task submission — notify PM/owner for significant decisions
• Blocking issues — notify relevant person for human input

Search

Tool	Purpose
chorus_search	Search across tasks, ideas, proposals, documents, projects, and project groups

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)

Notifications

Tool	Purpose
chorus_get_notifications	Get your notifications (default: unread only, auto-marks 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 })

---

Role-Specific Tools

Developer Tools

Tool	Purpose
chorus_claim_task	Claim an open task (open -> assigned)
chorus_report_work	Report work progress or completion on a task
chorus_submit_for_verify	Submit task for human verification (in_progress -> to_verify)
chorus_report_criteria_self_check	Report self-check results on acceptance criteria before submitting

PM Tools

Tool	Purpose
chorus_claim_idea	Claim an open Idea for elaboration (open -> elaborating)
chorus_start_elaboration	Start an elaboration round with structured questions
chorus_validate_elaboration	Validate elaboration answers (empty issues = resolved)
chorus_create_proposal	Create an empty Proposal container
chorus_add_document_draft	Add a document draft to a Proposal
chorus_add_task_draft	Add a task draft to a Proposal
chorus_update_document_draft	Update a document draft in a Proposal
chorus_update_task_draft	Update a task draft in a Proposal
chorus_remove_document_draft	Remove a document draft from a Proposal
chorus_remove_task_draft	Remove a task draft from a Proposal
chorus_validate_proposal	Validate a Proposal before submission (always call before submit)
chorus_submit_proposal	Submit a Proposal for approval (draft -> pending)
chorus_pm_assign_task	Assign a task to a specific Developer Agent
chorus_move_idea	Move an Idea to a different project
chorus_pm_create_idea	Create a new Idea in a project

Admin Tools

Tool	Purpose
chorus_admin_create_project	Create a new project (optionally in a group)
chorus_admin_create_project_group	Create a new project group
chorus_admin_approve_proposal	Approve a Proposal — materializes drafts into real Documents and Tasks
chorus_admin_verify_task	Verify a task (to_verify -> done). Unblocks downstream dependencies.
chorus_mark_acceptance_criteria	Mark acceptance criteria as passed/failed during verification

---

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, select role (Developer / PM / Admin)
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 role
• API Keys should not be committed to version control

2. Plugin Configuration

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)

3. Verify Connection

After configuring, the plugin will automatically connect. Verify by calling:

chorus_checkin()

If it fails, check: API Key correct (cho_ prefix)? URL reachable? Plugin enabled in config?

4. Role-Specific Tool Access

Tool Prefix	Developer	PM	Admin
chorus_get_* / chorus_list_*	Yes	Yes	Yes
chorus_checkin	Yes	Yes	Yes
chorus_add_comment / chorus_get_comments	Yes	Yes	Yes
chorus_create_tasks / chorus_update_task	Yes	Yes	Yes
chorus_search / chorus_search_mentionables	Yes	Yes	Yes
chorus_claim_task / chorus_report_work	Yes	No	Yes
chorus_submit_for_verify / chorus_report_criteria_self_check	Yes	No	Yes
chorus_claim_idea / chorus_pm_*	No	Yes	Yes
chorus_admin_*	No	No	Yes

---

SSE Event-Driven Model

The OpenClaw Chorus plugin uses a Server-Sent Events (SSE) model to receive real-time notifications from the Chorus server. Instead of polling, the plugin maintains a persistent SSE connection and automatically wakes the agent when relevant events occur.

How It Works

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 routes the event to the agent with context-rich instructions
5. If autoStart is enabled, certain events (like task_assigned) will auto-claim before waking the agent

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 startup to learn your role and assignments
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 — Use dependsOnDraftUuids in task drafts to express execution order
6. Verify before claiming — Check available items before claiming
7. Document decisions — Add comments explaining your reasoning
8. Respect the review process — Submit work for verification; don't assume it's done until Admin verifies
9. Self-check acceptance criteria — Before submitting for verify, call chorus_get_task to review acceptance criteria, then use chorus_report_criteria_self_check to report self-check results
10. Respond to SSE events promptly — When the plugin wakes you with an event, handle it before starting other work
11. @mention after completing work — When an event includes actor info, @mention the actor in your response comment

---

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

---

Skill Routing

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

Stage	Skill	Description
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, execute, submit for verification
Review	/review	Approve/reject Proposals, verify Tasks, project governance

Getting Started

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