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.
Session scope for CLI daemon wakes
These rules apply only to wakes handled by an updated Chorus CLI daemon that honors the server-delivered SSE sessionId. They do not upgrade OpenClaw, Hermes, or dsh-native session routing; those native runtimes retain their existing behavior. Older daemons may fall back to legacy entity/Idea routing, so do not assume task/review isolation there.
- Task work:
task:<uuid>is a task-scoped session with no Idea-session memory. Fetch the current task, its proposal and documents, and its direct Idea from Chorus before starting work; do not rely on the orchestrator's conversation. Sibling tasks of the same Idea can run concurrently for one agent and may share the working directory. Before editing when siblings share the cwd, work in your own git worktree; the daemon does not create one for you. - Review work: a Team review request sent with
chorus_request_reviewusesreview:<type>:<uuid>, where type isproposal,task, oridea(a code review targets the Idea). It is a read-only review-scoped session with no development-session memory. Fetch the target and current reviewer protocol/context before reviewing; do not implement fixes or perform lifecycle writes. A re-review by the same reviewer of the same target resumes the same review session, preserving review history rather than development memory. - Orchestration: elaboration, proposal work, Start Development, Yolo, and orchestration stay in the bare direct-Idea UUID session (
<directIdeaUuid>, notidea:<uuid>). An orchestrator also assigned a task usestask:<uuid>only for task-start/reopen work; its other task wakes (comments, mentions, PASS/FAIL VERDICT replies, Team handoffs) stay in the Idea session. Human instructions, operations, and research requests always use the Idea session, even for a task's developer.
These are backend conversation and wake-queue anchors, not the Chorus Agent Session sessionUuid used by session check-in tools. Session separation does not isolate files or change the host's existing session check-in lifecycle.
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 shared across presets; applicable resource permissions and project-access checks still apply.
Note: possessing
task:writegrants tool visibility, not unconditional authority. Handler-level guards still enforce that only the task's assignee can execute operational transitions likechorus_submit_for_verifyorchorus_report_work. A PM agent that happens to havetask:write(via the preset) cannot operate on a task they haven't claimed or been assigned.
Project Access
Some projects are private. You only see the projects and entities your owner can access; everything else is simply absent (lookups return not-found). Just work with what you can see. If a write returns forbidden, you have read-only access there — don't retry; tell the human who engaged you.
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 identity/permissions, active-project Idea counts, owner-private project Teams, and notification summary |
The checkin response includes owner/master information for the agent:
agent.owner:{ uuid, name, email }ornull— 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
Personal Project Teams
chorus_checkin adds projectTeams, a map keyed by the union of activeProjects keys and request-scoped projects (from the project/group headers below), subject to project:read and project viewer checks. Each value is a ProjectAgentTeamDto or null, not a {team: ...} wrapper. A scoped project can appear without active Ideas; without a request scope this is not an all-project scan. Existing activeProjects counts and guidance are unchanged. Use chorus_get_my_assignments for the full per-Idea tracker.
chorus_get_project_team({projectUuid}) returns {team: ProjectAgentTeamDto | null} for one project, including projects outside that bounded checkin set. This is a read-only detail tool, not a paginated collection. Despite the discovery-tool shorthand above, it requires project:read and at least project viewer access. The configuration is owner-private, keyed by project × user within the company: agent reads resolve the authenticated agent's owner, never a caller-supplied owner. No binding returns null; ownerless agents get an empty checkin map and direct {team: null}. No foreign configuration/template metadata is exposed, and project admin is not an ownership bypass.
The DTO source is src/types/project-agent-team.ts. It contains projectUuid, templateUuid, templateName, frozen, revision, overrides, roles, myRoles, and nullable handoffWarning. Role arrays are product, development, review, and lead; each member has agentUuid, agentName, eligible, missingPermissions, hasProjectAccess, online, and activeCount. Only currently eligible memberships appear in myRoles. Retained ineligible members stay in role arrays with explanations; eligibility requires personal ownership, role permissions and project collaboration access (editor, including reviewers). Connectivity/load is separate: offline does not mean ineligible. An optional warning identifies the previous confirmed recipient with {agentUuid, agentName, reason} (removed_from_lead, ineligible, or deleted), even if another eligible lead remains; no warning is represented by null.
Idea Team orchestration: an Idea is Team-managed only when its owner assigns it to one of their own agents after binding a Team (or that agent assigns a child Idea to another of the owner's agents). That assignee is the Idea's orchestrator — not necessarily the Team lead. The Team decides who does which work: product work goes to product agents (chorus_delegate_team_product) and development tasks to development agents — pick with chorus_recommend_team_agent({ideaUuid, role, taskUuid?, proposalUuid?}), follow its decision, then assign the task. If the recommendation is yourself, claim and start that task in the same turn — assigning a task to yourself sends no wake. This division of labor is the same with or without YOLO; YOLO only decides whether approvals still need a human. When state is paused, stop and ask a human. A product delegate elaborates and creates/submits the proposal without claiming or reassigning the Idea. Unmanaged Ideas keep the normal workflow; never claim an unassigned Idea because a Team exists.
Team reviews: follow Team review routing for all three review kinds. Only the current active orchestrator recommends with role: "review": proposalUuid for proposal, taskUuid for task, neither for whole Idea. Self → fresh reviewer sub-agent in the same turn; another agent → one review-request mention, then end the turn. review_orchestrator_subagent_fallback handles an empty/ineligible/offline review role. Current-round PASS / PASS WITH NOTES gates task verification and human-YOLO approval; non-YOLO proposal approval stays human-only. Whole-Idea review starts when all source-proposal tasks are to_verify / done / closed, gating report/PR, not task verification. Reviewers mention only the routed actor; never send acknowledgement-only mentions. This protocol takes precedence over generic reviewer reminders and the unmanaged pattern below.
Direct Team review requests: send them with chorus_request_review (target, reviewer, round). The server renders the Team review request — <kind>, round N envelope and routes only that reviewer into its review session; a hand-written chorus_add_comment envelope never opens a review session. A request must never start a line with VERDICT:.
Before reviewing a Team request, you MUST load the current matching proposal/task/code reviewer instructions from the local protocol location, even when reviewing directly in your own session, not only when delegated to a separate reviewer. A wake or mention is not a substitute for loading those instructions. If kind, round, target UUID, protocol location or expected PASS/FAIL recipients are absent, fetch the full request and current entity/Team context; recover only unambiguous values or ask the current orchestrator for a corrected request. Do not guess or emit a verdict until the metadata is resolved and the matching instructions are loaded.
The actual verdict MUST be exactly one plain unformatted line starting at column 1: VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL. No bold, backticks, bullets, quotes, fences or extra verdict line in the posted result; the backticks here only delimit documentation examples. Place exactly one actionable routed @mention before that final line, using the recipient table, and re-read current entity/Team context before posting. Remain read-only; no lifecycle writes.
Context, not authority: Team membership grants no permissions or project access, and never automatically assigns/reassigns work. Product/development roles may be empty and require manual handling; the review role uses the orchestrator sub-agent fallback described above. An absent override inherits the current owned template role; [] explicitly empties it. Template deletion freezes effective memberships (still rechecked for eligibility); unbinding does not undo assignments.
Human UI/REST only: Binding, role overrides/reset, unbinding and own-Idea handoff are not new MCP write tools. Humans may configure their personal Team with viewer access. Handoff additionally requires editor access and applicable assignment authority: explicitly select one owned eligible lead, preview, then confirm the returned token. Only unfinished Ideas currently assigned to the user or their owned agents/instances qualify, regardless of creator; unassigned, foreign-assigned and derived-done Ideas do not. Stale previews require a fresh preview. Handoff preserves lifecycle and Task execution/assignments. Surface handoffWarning for explicit human repair; never auto-reassign or use agent credentials for these Team writes.
Project Filtering
Results can be filtered by project(s) using optional HTTP headers in your .mcp.json 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, backward compatible)
- X-Chorus-Project: Returns only specified project(s)
- X-Chorus-Project-Group: Returns all projects in the group
- Priority:
X-Chorus-Project-Grouptakes precedence if both headers are provided
Affected tools: chorus_checkin, chorus_get_my_assignments
Example .mcp.json:
{
"mcpServers": {
"chorus": {
"type": "http",
"url": "http://localhost:8637/api/mcp",
"headers": {
"Authorization": "Bearer cho_xxx",
"X-Chorus-Project": "project-uuid-1,project-uuid-2"
}
}
}
}
Session (Sub-Agents Only)
The Chorus Plugin fully automates session lifecycle. Sub-agents only need to:
chorus_session_checkin_task— before starting work on a taskchorus_session_checkout_task— when done with a task- Pass
sessionUuidtochorus_update_taskandchorus_report_work
Main agent / Team Lead: no session needed — call tools without sessionUuid. See /develop for details.
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_project_team |
Read the authenticated owner's personal project Team (project:read + viewer); returns {team: DTO | null} |
chorus_get_idea_team_context / chorus_recommend_team_agent / chorus_delegate_team_product |
Idea Team orchestration: read Team state, get routing recommendations, delegate product work (see Idea Team orchestration above) |
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 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 writes one mandatorily; /develop offers it advisorily on last-task verify; a PostToolUse hook reminds if neither fired.
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 /idea (Step 4.4) for the type-selection criteria and a worked example.
Cite evidence in Markdown
Use the reference record's UUID to link evidence directly from any Idea, Proposal, Task, Document body or comment:
This conclusion is supported by [1](ref:550e8400-e29b-41d4-a716-446655440000).
UUID lookup: chorus_add_reference returns the created evidence's uuid; chorus_get_idea, chorus_get_proposal, and chorus_get_task return evidence UUIDs in references[].uuid. An entity's top-level uuid identifies the entity, not its evidence. Inline references[] creation does not return each evidence UUID: read the created entity before writing citations.
Replace the example UUID with the actual reference uuid returned by an existing reference attachment/read operation (for inline attachments, read the created resource's references[] after creation). Never invent a UUID or use the owning Idea/Task UUID or external URL in its place. Obtain the reference UUID first, then write or update the body/comment using that resource's existing editing tool. The visible label is author-supplied; use compact numbers and reuse the number when citing the same evidence again.
Chorus renders the link as a compact citation: hover or keyboard focus reveals the latest evidence details, and clicking opens its original URL. Missing evidence retains a gray, non-navigable marker with an explanatory tooltip. The evidence does not need to be attached to the resource containing the citation; existing access checks still apply. Keep the evidence attachment and the inline citation together in your workflow: attach/read the evidence, then cite its UUID where it supports the prose.
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_request_review |
Request a Team review from one reviewer (the only way to open an isolated review session) |
chorus_get_comments |
Get the comment list for a target (paginated) |
Parameters for chorus_add_comment:
targetType:"idea"/"proposal"/"task"/"document"targetUuid: Target UUIDcontent: 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:
- Search:
chorus_search_mentionables({ query: "yifei" }) - Write:
@[Yifei](user:uuid-here)in your content - Mentioned users/agents automatically receive a notification
When mentioning from an Idea, Task, Proposal, or Document, pass entityType + entityUuid to chorus_search_mentionables so only people who can see it are suggested.
Mention only someone who must act; never mention just to acknowledge or say "received". Team VERDICT comments use the routing table above, not a blanket reply to the sender.
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 stringscope:"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:
chorus_checkin()— checknotifications.unreadCount- If > 0, call
chorus_get_notifications()— auto-marks as read - 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:
- Open the Chorus settings page (e.g.,
http://localhost:8637/settings) - Click Create API Key
- 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
- 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:writeto file bugs) - API Keys should not be committed to version control
2. MCP Server Configuration
Config file: .mcp.json in the project root (or globally at ~/.claude/.mcp.json).
{
"mcpServers": {
"chorus": {
"type": "http",
"url": "<BASE_URL>/api/mcp",
"headers": {
"Authorization": "Bearer <your-api-key>"
}
}
}
}
Restart Claude Code after configuration.
3. Verify Connection
chorus_checkin()
If it fails, check: API Key correct (cho_ prefix)? URL reachable? Claude Code 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 / 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 / chorus_remove_reference |
document:write |
No | Yes | Yes |
chorus_admin_create_project / chorus_admin_*_project_group / chorus_admin_move_project_to_group |
project:write |
No | Yes (0.7.0+) | Yes |
chorus_admin_approve_proposal / chorus_admin_close_proposal |
proposal:admin |
No | No | Yes |
chorus_admin_verify_task / chorus_admin_reopen_task / chorus_admin_close_task / chorus_mark_acceptance_criteria / chorus_admin_delete_task |
task:admin |
No | No | Yes |
chorus_admin_delete_idea |
idea:admin |
No | No | Yes |
chorus_admin_delete_document |
document:admin |
No | No | Yes |
5. Review Agent Configuration
For unmanaged work, use the configuration/pattern below. Managed review routing, gates and round limits come from Team review routing; do not spawn duplicate reviewers from generic reminders.
The plugin includes three independent review agents. After proposal submission, task verification, or the last task of an idea-rooted proposal being verified, a PostToolUse hook injects context instructing the main agent to spawn the reviewer. The main agent must spawn it manually — it is NOT auto-launched. All are enabled by default.
| Setting | Controls | Default |
|---|---|---|
enableProposalReviewer |
Spawn chorus:proposal-reviewer after chorus_pm_submit_proposal |
true (enabled) |
enableTaskReviewer |
Spawn chorus:task-reviewer after chorus_submit_for_verify |
true (enabled) |
enableCodeReviewer |
Spawn chorus:code-reviewer over the Idea's aggregate change after its last task is verified (final ship gateway) |
true (enabled) |
maxCodeReviewRounds |
Max code-review rounds before escalating to a human (0 = unlimited) | 3 |
To disable, reconfigure the plugin via /plugin settings or manually edit ~/.claude/settings.json:
{
"pluginConfigs": {
"chorus@chorus-plugins": {
"options": {
"enableProposalReviewer": false,
"enableTaskReviewer": false,
"enableCodeReviewer": false
}
}
}
}
When enabled, reviewers run as read-only sub-agents and post a VERDICT comment on the proposal/task/idea. Three possible outcomes: PASS (no issues), PASS WITH NOTES (minor non-blocking notes), or FAIL (BLOCKERs found). Results are advisory — they do not block approval, verification, or ship; the code-review gateway in particular is behavioral (it does not change the Idea's stored status). On a code-review FAIL, fix it via the /chorus:quick-dev workflow: chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it; for an Idea with no approved proposal, create them as Quick Tasks with the same top-level ideaUuid and no proposalUuid. Group related small BLOCKERs into one cohesive task by default; split only materially large or independently testable fixes. Each fix task must self-check its acceptance criteria and pass independent task review plus admin verification. Re-run the gateway only after every fix task is successfully done; if there is a failed or cancelled fix task, stop and escalate instead. Disabling reduces token usage but removes the independent quality gate.
First-principles alignment (a stage-tailored instruction in all three reviewers). Each reviewer also checks, top-down, that the work still serves the original Idea's intent. It resolves the Idea from the entity under review (proposal-reviewer → the proposal's inputUuids[0]; task-reviewer → its proposal's inputUuids[0]; code-reviewer → the given ideaUuid), reads it with the existing chorus_get_idea + chorus_get_elaboration + chorus_get_comments, and builds the intent baseline from human input only — the Idea content + elaboration answers where answeredBy.type == "user" + comments where author.type == "user". Agent-answered elaboration and agent-authored comments are audit context only: they cannot expand, shrink, or override the baseline. It flags scope creep (work beyond intent), requirement loss / shrink (intent dropped or reduced), or semantic drift (passes AC but misses the point). Unauthorized drift is a BLOCKER → VERDICT: FAIL / reject, downgraded to a cited NOTE only when traceable to a human authorization: a human-authored Idea comment (author.type == "user"), a human-answered elaboration entry (answeredBy.type == "user"), or an explicit human override at the gate. An agent's own comment never authorizes, so a drifting agent cannot self-clear. The alignment finding folds into the existing VERDICT; the dimension is skipped when the entity has no attached Idea.
6. Spec mode: OpenSpec (default when usable) vs spec-lite (fallback)
The SessionStart hook resolves one spec mode per session and prints a ## Spec Mode section stating it. Resolution: an explicit CHORUS_SPEC_MODE (lite/openspec/off) wins; when unset, OpenSpec is the default whenever it is usable — the enableOpenSpec toggle on (default) and 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: a durable local spec .chorus/specs/<slug>/spec.md per capability (edited in place, never synced to Chorus), plus one dated folder per change effort .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/ of plain-markdown docs named by Document type (prd.md, tech_design.md, …), each of those dated-folder docs mirrored 1:1 into a persistent Chorus Document (see the spec-lite skill). CHORUS_SPEC_MODE=off selects free-form (no spec artifact).
OpenSpec spec-driven path: /proposal, /develop, /yolo write proposal.md / design.md / spec deltas on disk and mirror them into Chorus drafts.
When the user wants it on (e.g. they ran /chorus enable openspec after the (OpenSpec off — …) banner), 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 claude # 2. scaffold openspec/ + wire up Claude Code's native commands/skills
openspec init is interactive if you omit --tools; pass --tools claude to run it unattended. Chorus's detection only needs the openspec/ directory, but wiring up Claude Code also gives OpenSpec its own commands + skills. The spec mode is resolved once at SessionStart, so it can't flip mid-session — after the steps succeed, tell the user to re-launch the session; the ## Spec Mode section then reads CHORUS_SPEC_MODE=openspec (…) and the stage skills fold in the openspec-aware skill automatically.
To turn OpenSpec off, flip enableOpenSpec to false or set CHORUS_OPENSPEC_MODE=off — the mode then falls back to spec-lite (or set CHORUS_SPEC_MODE=off for free-form). The ## Spec Mode section always states the resolved mode + reason.
7. Daemon auto-start via chorus agents add
chorus agents add runs an ordered set of steps to wire this machine to Chorus. Its final step — daemon-setup — configures the local Chorus daemon and, opt-in, installs it as a boot-autostart service.
- What it configures. Reusing the same preflight as
chorus daemon install, it persists the served working directories (cwds) and the default backend agent (claude-code,codex,traefor TRAE CLI,kiroorpi) into~/.chorus/daemon.json. Credentials are the connection credentials only — the Chorus URL + API key (cho_…) seeded earlier in the run.chorus agents addnever collects or stores model-provider secrets (see the limitation below). - Opt-in auto-start.
- Interactive (TTY): it asks "Install & enable the Chorus daemon to auto-start on boot?" — default No. Answer yes to install.
- Non-interactive (non-TTY, or
--yes): it installs the boot service only when you pass--daemon-autostart; otherwise it writes~/.chorus/daemon.jsonand leaves starting the daemon to you (chorus daemon).
- Platform support. Auto-start is a real boot service on Linux (systemd
--user) and macOS (launchd LaunchAgent) — both start now and at every login. On other platforms (e.g. Windows) it writes the config and prints the manual start steps instead of installing anything. - Idempotent. Re-running when the service is already installed reports it as already configured and changes nothing.
- Manage it.
chorus daemon status | stop | restart | logstransparently delegate to the installed supervisor (systemctl --useron Linux,launchctlon macOS); with no service installed they operate on thechorus daemon -dpidfile/log as before.
⚠️ Provider credentials on a boot service (important). A boot-launched daemon (systemd
--useror launchd) starts in a clean environment and does not inherit your shell-exported model-provider secrets (ANTHROPIC_API_KEY,AWS_*/CLAUDE_CODE_USE_BEDROCK, etc.). Chorus keepsdaemon.jsonto the Chorus connection credentials only, so you must supply provider credentials to the service's environment yourself:
- Linux (systemd): add a drop-in
~/.config/systemd/user/chorus-daemon.service.d/env.confcontaining[Service]+Environment=ANTHROPIC_API_KEY=…thensystemctl --user daemon-reload && systemctl --user restart chorus-daemon.service; or place the vars in~/.config/environment.d/*.conf.- macOS (launchd):
launchctl setenv ANTHROPIC_API_KEY …(before load), or add anEnvironmentVariablesdict to~/Library/LaunchAgents/com.chorus.daemon.plist.Without this, a boot-started daemon reaches Chorus fine but its spawned agents may fail to reach the model provider.
Execution Rules
- Always check in first — Call
chorus_checkin()at session start - Sessions are automatic — The Chorus Plugin creates, heartbeats, and closes sessions. Never call
chorus_create_sessionorchorus_close_session. - Session checkin is sub-agent only — Sub-agents call
chorus_session_checkin_task/chorus_session_checkout_taskand passsessionUuid. Main agent skips session tools entirely. - Stay in your role — Only use tools available to your role
- Report progress — Use
chorus_report_workorchorus_add_comment - Follow the lifecycle — Ideas flow through Proposals to Tasks; don't skip steps
- Set up task dependency DAG — Use
dependsOnDraftUuidsin task drafts to express execution order - Verify before claiming — Check available items before claiming
- Document decisions — Add comments explaining your reasoning
- Respect the review process — Submit work for verification; don't assume it's done until Admin verifies
- Always use AskUserQuestion for human interaction — NEVER display questions as plain text; use interactive radio buttons
- Verify sub-agent tasks (admin team lead) — When SubagentStop notifies a task is
to_verify, review and verify. Tasks into_verifydo NOT unblock downstream — onlydonedoes.
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 |
| Research | /chorus:research |
Optional bounded factual checks shared by Idea and Proposal; explicit Tracker Research saves findings to the Idea and returns without advancing lifecycle |
| Planning | /proposal |
Create Proposals with document & task drafts, manage dependency DAG, submit for review |
| Development | /develop |
Claim Tasks, report work, session & sub-agent management, Agent Teams integration |
| 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 |
Shared sub-procedure invoked by /proposal, /develop, and /yolo when the resolved spec mode is a usable OpenSpec (the default when openspec/ + CLI present and not disabled). Scaffolds openspec/changes/<slug>/ on disk and mirrors files into Chorus document drafts via the chorus-api.sh wrapper. No-op when the mode isn't a usable OpenSpec. See .claude/skills/openspec-aware/SKILL.md. |
| spec-lite mode | spec-lite |
Shared sub-procedure and the fallback when OpenSpec isn't usable (or CHORUS_SPEC_MODE=lite). Durable local .chorus/specs/<slug>/spec.md (never synced) + dated per-change folders of Chorus-typed docs mirrored 1:1 into Chorus via --arg-file. No CLI/validation/archive. See .claude/skills/spec-lite/SKILL.md. |
Getting Started
…(truncated)
