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 names under Pi — discover the active backend first. Skills use backend names such as chorus_checkin:

• Native MCP (stable Pi >=0.99.0 <2.0.0): discover mcp__chorus__chorus_checkin through native tool_search, then use the discovered schema via codemode, or call the direct tool when exposed. Native codemode is the default; direct mode is not required.
• Legacy (Pi 0.84.4–0.98.x, adapter5): expose Chorus with directTools: true. Direct tools are usually chorus_chorus_checkin, or bare chorus_checkin when toolPrefix: "none". Naming and exposure are separate settings; inspect registered tools rather than assuming an alias.
• Legacy mcp/mcpScript gateway-only calls do not trigger workflow reminders. The matcher reads only the outer toolName, never input.tool or script text. Native codemode emits real child MCP events and therefore supports reminders without duplicate parent nudges.

Bundled reviewers allow only discovered safe query/checkin/comment operations, exclude legacy gateways and fail closed on empty permissions. Worker tool inheritance is unchanged. Hosts below 0.84.4 and Pi 2.x are unsupported; unknown/prerelease versions require diagnosis rather than speculative adapter changes.

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.

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 optional HTTP headers in your backend's MCP configuration:

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-Group takes precedence if both headers are provided

Affected tools: chorus_checkin, chorus_get_my_assignments

Example server headers (native global mcp.json / trusted project .pi/mcp.json; legacy adapter5 global mcp-adapter.json):

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "http://localhost:8637/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CHORUS_API_KEY}",
        "X-Chorus-Project": "project-uuid-1,project-uuid-2"
      }
    }
  }
}

Session (Sub-Agents Only)

The Chorus Pi extension fully automates session lifecycle. When you dispatch a worker with the subagent tool, the extension auto-creates a Chorus session and injects its UUID + workflow into that worker's task; it closes the session when the dispatch returns (bundled subagent) or when the run settles (subagent:async-complete / process-terminal under nicobailon pi-subagents). Sub-agents only need to:

1. chorus_session_checkin_task — before starting work on a task
2. chorus_session_checkout_task — when done with a task
3. Pass sessionUuid to chorus_update_task and chorus_report_work

Main agent / Team Lead: no session needed — call tools without sessionUuid. See /skill:develop for details.

Reviewer sub-agents (chorus-proposal-reviewer, chorus-task-reviewer, chorus-code-reviewer) do not get a Chorus session — they are read-only and post a single VERDICT comment.

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. /skill:yolo writes one mandatorily; /skill:develop offers it advisorily on last-task verify; the extension nudges 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 /skill: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

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 /skill: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

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

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

Prefer chorus agents add: it selects native MCP for stable Pi >=0.99.0 <2.0.0 (Chorus-only install), or pinned pi-mcp-adapter@5.0.0 plus Chorus for Pi 0.84.4–0.98.x. Native global config is ~/.pi/agent/mcp.json; native project config is .pi/mcp.json and requires trust. Adapter5's primary global file is ~/.pi/agent/mcp-adapter.json, not mcp.json; its legacy discovery/import paths differ from native. $PI_CODING_AGENT_DIR overrides the global agent directory.

Use this JSON at the selected path; on legacy hosts add "directTools": true to the Chorus entry for workflow reminders:

{
  "mcpServers": {
    "chorus": {
      "type": "http",
      "url": "<BASE_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CHORUS_API_KEY}"
      }
    }
  }
}

Then export the same values as env vars for the extension's own checkin/session calls:

export CHORUS_URL=http://localhost:8637
export CHORUS_API_KEY=cho_your_key

Restart Pi after configuration (/reload or a fresh session).

Chorus's own config fallback reads the version-appropriate global file, honoring the agent-dir override; legacy adapter5 primary outranks retained old global mcp.json. With CHORUS_API_KEY exported it can discover the URL from that generated file. Explicit environment values take precedence; unresolved environment credentials are not sent. Native project .pi/mcp.json is not read by this fallback, so export both variables for project-only setup. Fresh legacy setup enables direct tools; existing exposure choices are preserved. Init only copies old global mcp.json when adapter primary is absent, leaves the source intact, and refuses malformed/unreadable files. Existing adapter packages and -builtin:mcp settings on native hosts produce scope-specific warnings only: manually remove/re-enable them if choosing native, then restart and verify. Neither config writes nor package-installed status guarantee connectivity. Targeted upgrades preserve pins; they never update all extensions or automatically remove an adapter.

3. Verify Connection

chorus_checkin()

If it fails, check: API Key correct (cho_ prefix)? URL reachable? Pi 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.

5. Review Agent Configuration

The extension includes three independent review agents. After proposal submission, task verification, or the last task of an idea-rooted proposal being verified, the extension nudges you to dispatch the reviewer with the subagent tool. You must spawn it manually — it is NOT auto-launched. All are enabled by default.

To disable, export the env var as false; to tune the code-review gateway loop cap, set CHORUS_MAX_CODE_REVIEW_ROUNDS:

export CHORUS_ENABLE_PROPOSAL_REVIEWER=false
export CHORUS_ENABLE_TASK_REVIEWER=false
export CHORUS_ENABLE_CODE_REVIEWER=false
export CHORUS_MAX_CODE_REVIEW_ROUNDS=5   # 0 = unlimited

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 /skill:quick-dev workflow: chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it. 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.

6. Spec mode: OpenSpec (default when usable) vs spec-lite (fallback)

The extension's session_start handler resolves one spec mode per session (via the TS resolveSpecMode, the single source of truth) and injects a ## Spec Mode section stating it — the stage skills consume that value, they don't re-derive it. 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 (never synced) plus dated per-change folders <slug>/<YYYY-MM-DD>-<change-slug>/ of Chorus-typed docs mirrored 1:1 into Chorus (see /skill:spec-lite). CHORUS_SPEC_MODE=off selects free-form (no spec artifact).

OpenSpec spec-driven path: /skill:proposal, /skill:develop, and /skill:yolo write proposal.md / design.md / spec deltas on disk and mirror them into Chorus drafts.

When the user wants OpenSpec on (e.g. they saw (spec: spec-lite) / (spec: off …) in the 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                        # 2. scaffold openspec/ (interactive; pick your editor tooling)

The spec mode is resolved once at session start, so it can't flip mid-session — after the steps succeed, tell the user to restart 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, 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.

Execution Rules

1. Always check in first — Call chorus_checkin() at session start (the extension does this automatically and injects the result)
2. Sessions are automatic — The extension creates the session when you dispatch a worker with the subagent tool, and closes it when the dispatch returns (bundled subagent) or when the run settles (nicobailon pi-subagents). Never call chorus_create_session or chorus_close_session yourself.
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. Always use AskUserQuestion for human interaction — NEVER display questions as plain text; use interactive radio buttons (the ask_user_question tool)
12. No close step — a subagent dispatch owns its children's whole lifecycle: the bundled subagent's children exit within the call, and a nicobailon run settles on its own, so there is nothing to close (inspect a run with subagent({ action: "status" }) if needed).

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. The extension auto-calls chorus_checkin() at session start and injects your role and assignments
2. Based on your role, use the appropriate skill:
   • Full Auto → /skill:yolo — give a prompt, agent handles everything (requires Admin-preset permissions: write on every resource + approve/verify admin bits)
   • PM Agent → /skill:idea then /skill:proposal
   • Developer Agent → /skill:develop
   • Admin Agent → /skill:review (also has access to all PM and Developer tools)