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, see 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)

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)

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

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

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

---

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 — When you need user input (elaboration answers, clarifications, design decisions), prefer your IDE's interactive prompt mechanism over displaying questions as plain text
10. Verify sub-agent tasks promptly (admin) — Tasks in to_verify do NOT unblock downstream dependencies — 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)

---

Independent Review

Chorus uses independent, read-only adversarial reviewers at three gates: before a proposal is approved, before a task is verified, and before an Idea's code ships (the final aggregate gateway). The reviewer's job is to find what is wrong — not to rubber-stamp. Its output is advisory: it informs the orchestrator's decision but does not by itself approve, reject, verify, reopen, or ship anything.

This is the single canonical description of the reviewer pattern. The develop-chorus, review-chorus, and yolo-chorus skills all point back here rather than redefining it.

The Pattern

1. Spawn a read-only sub-agent that loads one of the three reviewer skills:
   • proposal-reviewer-chorus (<BASE_URL>/skill/proposal-reviewer-chorus/SKILL.md) — for reviewing a proposal before approval. Pass it the proposalUuid.
   • task-reviewer-chorus (<BASE_URL>/skill/task-reviewer-chorus/SKILL.md) — for reviewing a task before verification. Pass it the taskUuid.
   • code-reviewer-chorus (<BASE_URL>/skill/code-reviewer-chorus/SKILL.md) — the final ship-time gateway: reviews an Idea's aggregate code change (the whole feature across all its tasks) after its last task is verified, before the code ships. Pass it the ideaUuid and the review round number. Posts its VERDICT on the Idea.
2. The reviewer audits independently and posts exactly one structured VERDICT comment on the proposal/task/idea via chorus_add_comment. The comment ends with one literal verdict string: VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL.
3. Read the verdict and act. Fetch the comment with chorus_get_comments({ targetType, targetUuid }), read the BLOCKER / NOTE findings, then make the call:
   • PASS / PASS WITH NOTES → proceed (approve the proposal / verify the task / ship the feature), addressing NOTEs at your discretion.
   • FAIL → do not proceed; route the BLOCKERs back for a fix (reject/revise the proposal, reopen/rework the task, or — for the code-review gateway — add new fix tasks to the approved proposal and re-run once they are done), then re-review. The cleanest way to run those code-review fix tasks is the quick-dev workflow (<BASE_URL>/skill/quick-dev-chorus/SKILL.md): call chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it (not standalone), then group related small BLOCKERs by default and split only materially large or independently testable fixes. Never reopen completed tasks or apply untracked fixes. Require AC self-check, independent task review, and admin verification for every fix; re-run aggregate review only after all are successfully . A failed or cancelled fix stops the loop and escalates, while remains authoritative.

The verdict is advisory: even a FAIL does not hard-block, and a PASS does not auto-approve. A human/admin (or, under /yolo, the automated orchestrator) makes the final decision. The code-review gateway in particular is a behavioral gate — it does not change the Idea's stored status; the orchestrator honors its verdict.

Spawn Mechanism Is Harness-Specific

How you spawn the read-only sub-agent depends on your agent harness — give it the reviewer skill plus the target UUID and instruct it to post a single VERDICT comment. Concrete examples:

• Claude Code — use the Task / Agent tool to launch a sub-agent that loads task-reviewer-chorus (or proposal-reviewer-chorus / code-reviewer-chorus) and pass the taskUuid / proposalUuid / ideaUuid.
• Codex — use spawn_agent with the reviewer skill and the target UUID.
• Other harnesses: use whatever sub-agent / sub-task primitive they expose.

Inline Self-Review Fallback

When sub-agents are not available in your harness, run the review inline yourself: load the relevant reviewer skill's procedure (proposal-reviewer-chorus, task-reviewer-chorus, or code-reviewer-chorus), audit the proposal/task/idea against its checklist with the same adversarial posture, and post the single VERDICT comment yourself before acting on it. A same-agent self-review is weaker than a fresh independent reviewer, but it is far better than skipping the gate.

---

Skill Routing

This is the core overview skill. For stage-specific workflows, download and read the appropriate skill:

Stage	Skill	Path
Overview (this file)	chorus	<BASE_URL>/skill/chorus/SKILL.md
Quick Dev	quick-dev-chorus	<BASE_URL>/skill/quick-dev-chorus/SKILL.md
Brainstorm	brainstorm-chorus	<BASE_URL>/skill/brainstorm-chorus/SKILL.md
Ideation	idea-chorus	<BASE_URL>/skill/idea-chorus/SKILL.md
Planning	proposal-chorus	<BASE_URL>/skill/proposal-chorus/SKILL.md
Development	develop-chorus	<BASE_URL>/skill/develop-chorus/SKILL.md
Review	review-chorus	<BASE_URL>/skill/review-chorus/SKILL.md
Docs	docs-chorus	<BASE_URL>/skill/docs-chorus/SKILL.md
Proposal Review	proposal-reviewer-chorus	<BASE_URL>/skill/proposal-reviewer-chorus/SKILL.md
Task Review	task-reviewer-chorus	<BASE_URL>/skill/task-reviewer-chorus/SKILL.md
Code Review (ship gateway)	code-reviewer-chorus	<BASE_URL>/skill/code-reviewer-chorus/SKILL.md
Full-Auto	yolo-chorus	<BASE_URL>/skill/yolo-chorus/SKILL.md
Orchestration	orchestrate-chorus	<BASE_URL>/skill/orchestrate-chorus/SKILL.md

Getting Started

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