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

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:

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

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), 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 tools without sessionUuid.

Project Groups

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

Project & Activity

Ideas

Documents

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 call requires title (a short report title) plus content; content's parameter description carries the three-section template (## Summary / ## Decisions / ## Follow-ups) — read it there. yolo-chorus writes one mandatorily; develop-chorus 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 mcp__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-chorus (Step 4.4) for the type-selection criteria and a worked example.

Proposals

Tasks

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

Comments

Parameters for chorus_add_comment:

• targetType: "idea" / "proposal" / "task" / "document"
• targetUuid: Target UUID
• content: Comment content (Markdown)

Elaboration

@Mentions

Use @mentions to notify specific users or agents. Mention syntax: @[DisplayName](type:uuid) where type is user or agent.

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

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

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

dsh Runtime Contract

This bundle configures the Chorus MCP connection from CHORUS_URL and CHORUS_API_KEY in the dsh process environment. After profile activation, verify that mcp__chorus__chorus_checkin is present and succeeds. Tool visibility remains controlled by the connected Chorus agent permissions.

Review Skills

The plugin bundles three independent review skills: proposal-reviewer-chorus, task-reviewer-chorus, and code-reviewer-chorus. They are read-only and end by posting a VERDICT: comment (PASS / PASS WITH NOTES / FAIL) on the proposal/task/idea. code-reviewer-chorus 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 dsh. The stage skills run review inline after submission. Spawn the reviewer with run_in_background: false (foreground — the call waits for the reviewer to finish, and the verdict is the VERDICT: comment it posts rather than the call's return value; the approve/verify/ship decision depends on it): a subagent whose task explicitly tells it to call the skill tool with the matching reviewer skill; then read this round's Chorus VERDICT: comment. Set run_in_background: true (a continuable/background sub-agent whose settlement notice you collect later) only when you deliberately want to fan out. If delegation is unavailable, load the same reviewer skill and perform its read-only procedure inline.

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-chorus) 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. Spec mode: OpenSpec (default when usable) vs spec-lite (fallback)

Every PM authoring flow (proposal-chorus, develop-chorus, yolo-chorus) runs in one spec mode. dsh has no SessionStart hook, so the chorus-dsh bundle resolves the mode once at load (resolveSpecMode in src/spec-mode.ts — the tested single source of truth), publishes CHORUS_SPEC_MODE + CHORUS_OPENSPEC_ACTIVE to the process environment, and injects a ## Spec Mode block into the first agent step stating the resolved mode + reason. Read that block; do not re-derive the rule.

Resolution: an explicit CHORUS_SPEC_MODE (lite/openspec/off) wins; when unset, OpenSpec is the default whenever it is usable (CHORUS_OPENSPEC_MODE ≠ off, an openspec/ directory at the project root, and the openspec CLI on PATH). When OpenSpec is absent or disabled, the mode falls back to spec-lite — a Chorus-native, git-tracked model with a durable local .chorus/specs/<slug>/spec.md per capability (edited in place, never synced) plus dated per-change folders <slug>/<YYYY-MM-DD>-<change-slug>/ of Chorus-typed docs (prd.md required; tech_design.md / adr.md / guide.md / spec.md optional) mirrored 1:1 into persistent Chorus Documents (see spec-lite-chorus). CHORUS_SPEC_MODE=off selects free-form (no spec artifact). An explicit CHORUS_SPEC_MODE=openspec that cannot be honored makes the stage skills halt — they never silently downgrade.

In OpenSpec mode, proposal-chorus / develop-chorus / yolo-chorus write proposal.md / design.md / spec deltas on disk and mirror them into Chorus drafts via openspec-aware-chorus. In either spec mode, byte-exact document mirroring prefers chorus mcp call … --arg-file content=<file>, falling back to the package-local wrapper path exported as CHORUS_MCP_CALL when chorus is not on PATH; a missing transport is a visible blocker, never a reason to retype document content.

When the user wants OpenSpec on (the ## Spec Mode block reads spec-lite/off and they want the OpenSpec path), actually enable it for them — run whichever steps are missing, don't just describe them: npm i -g @fission-ai/openspec then openspec init --tools none (OpenSpec has no dsh integration, so none is correct — Chorus's resolution only needs the openspec/ directory + CLI). The mode is resolved at bundle load, so tell the user to restart the dsh session afterwards. To turn OpenSpec off, set CHORUS_OPENSPEC_MODE=off — the mode then falls back to spec-lite (or set CHORUS_SPEC_MODE=off for free-form).

Execution Rules

1. Always check in first — Call chorus_checkin() at session start
2. Sessions are manual on dsh — dsh 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-chorus.
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. Respect the headless gate — use ask_user_question for user-owned decisions in interactive dsh. When CHORUS_DAEMON_HEADLESS=1, persist the decision request through Chorus and end the turn without polling.
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:

Getting Started

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