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 Hermes setup. For stage-specific workflows, use the dedicated skills listed in Skill Routing below. Load any of them with skill_view("chorus:<name>").

Tool names under Hermes. The Chorus MCP tools come from the chorus MCP server and appear in Hermes as mcp__chorus__chorus_<op> — e.g. mcp__chorus__chorus_checkin, mcp__chorus__chorus_get_task, mcp__chorus__chorus_pm_add_document_draft. All Chorus skills use the shorter backend names (chorus_checkin, chorus_get_task, …) for brevity; call the mcp__chorus__-prefixed tool that matches. The Chorus Hermes plugin's transform_tool_result reminders match on the end of the tool name, so they fire for these prefixed native tools.

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

On Hermes the Chorus plugin's pre_llm_call hook calls chorus_checkin on the first turn of each session (and again after /reset or context compression) and injects the result as ## Checkin, together with ## Spec Mode and ## Quick Reference. You only need to call it yourself to refresh.

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 on the Chorus MCP server entry:

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 (native mcp_servers entry in ~/.hermes/config.yaml) — headers on the native entry are env-expanded, so keep the key as a ${CHORUS_API_KEY} placeholder:

mcp_servers:
  chorus:
    url: ${CHORUS_URL}/api/mcp
    headers:
      Authorization: Bearer ${CHORUS_API_KEY}
      X-Chorus-Project: project-uuid-1,project-uuid-2

Or set it from the shell: hermes config set mcp_servers.chorus.headers.X-Chorus-Project 'project-uuid-1,project-uuid-2'. The filter applies to the model's MCP tool calls; the plugin's own session-start check-in (## Checkin) does not send these headers.

Session (Sub-Agents Only)

On Hermes, Chorus sessions for workers are not auto-created. Sessions exist for observability of delegate_task workers, and the parent manages them:

1. Before delegating, the parent creates (or reuses: chorus_list_sessions then chorus_reopen_session) one session per worker with chorus_create_session({ name: "<worker-name>" }) and passes its sessionUuid in the worker's context.
2. The worker calls chorus_session_checkin_task before starting work on a task.
3. The worker passes sessionUuid to chorus_update_task and chorus_report_work.
4. The worker calls chorus_session_checkout_task when done with the task.
5. The parent calls chorus_close_session after delegate_task returns.

Main agent / Team Lead: no session needed — call tools without sessionUuid. See skill_view("chorus:develop") for details.

Reviewer children (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_view("chorus:yolo") writes one mandatorily; skill_view("chorus:develop") offers it advisorily on last-task verify; the Chorus Hermes plugin's chorus_admin_verify_task reminder 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_view("chorus: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_view("chorus: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
• Questions in a gateway session — when Chorus woke you and no human is in chat, an @mention comment is how you reach the human (see Execution Rules)

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. Install the Hermes plugins (pinned)

Chorus on Hermes is two independently installable directories:

Hermes --ref accepts only a full 40-character commit SHA, so resolve the release tag first. Chorus release tags are lightweight, so the peeled ^{} query returns nothing for them and the unpeeled ref is the one that answers; keep both lines:

VERSION=0.22.0   # the Chorus release you want
REPO=https://github.com/Chorus-AIDLC/Chorus.git
SHA=$(git ls-remote "$REPO" "refs/tags/v$VERSION^{}" | cut -f1)
[ -n "$SHA" ] || SHA=$(git ls-remote "$REPO" "refs/tags/v$VERSION" | cut -f1)
[ -n "$SHA" ] || { echo "error: tag v$VERSION not found on $REPO" >&2; exit 1; }

hermes plugins install Chorus-AIDLC/Chorus/packages/chorus-hermes/chorus     --ref "<sha>" --enable
hermes plugins install Chorus-AIDLC/Chorus/packages/chorus-hermes/chorus-mcp --ref "<sha>" --enable
hermes plugins list --plain --no-bundled   # both: enabled  git pinned@<sha8>

<sha> is the 40-character value resolved into $SHA above (pass "$SHA"). Never install unpinned; if the tag does not resolve, stop. Easier path: install the Chorus CLI (npm install -g @chorus-aidlc/chorus@0.22.0) and run chorus agents add --agents hermes — it resolves the SHA, installs both directories pinned, and writes the MCP entry below when needed (see skill_view("chorus:chorus-cli")).

3. Environment and MCP URL

Credentials are read only from the environment (or ~/.hermes/.env), both by the plugin's own check-in/gateway calls and by the MCP header expansion:

export CHORUS_URL=https://chorus.example.com     # base URL, no trailing /api/mcp
export CHORUS_API_KEY=cho_xxx                    # your agent key

MCP URL rule. Portable mcp.json URLs are not env-expanded, so the chorus-mcp package ships the literal loopback URL http://localhost:8637/api/mcp (a local pnpm dev Chorus) with header Authorization: Bearer ${CHORUS_API_KEY} (headers are expanded). For any other deployment add a native entry, which Hermes does expand and which wins over the portable server of the same name:

hermes config set mcp_servers.chorus.url '${CHORUS_URL}/api/mcp'
hermes config set mcp_servers.chorus.headers.Authorization 'Bearer ${CHORUS_API_KEY}'

The single quotes matter: the config stores the ${VAR} placeholders, never the values. With the native entry present Hermes logs Portable MCP server 'chorus' conflicts with native config; skipping — expected. chorus agents add --agents hermes writes this native entry for you when CHORUS_URL is not the loopback default.

Restart Hermes after configuration (a new session, or restart hermes gateway). Verify with hermes plugins list --plain --no-bundled and, if needed, hermes mcp list.

4. Working directory and the gateway

• terminal.cwd — set it in ~/.hermes/config.yaml to the repository this agent works in. The plugin reports realpath(terminal.cwd) to Chorus and refuses to connect the gateway when it is unset or a placeholder (., auto, cwd). One gateway serves one repository.
• hermes gateway — keeps the agent online. The chorus gateway platform (auto-enabled when CHORUS_URL and CHORUS_API_KEY are set) receives Chorus SSE notifications — task/idea assigned, elaboration answered, @mention, comment added — and wakes the agent. Each wake is a model turn in the session keyed idea:<ideaUuid>, so successive wakes for one Idea share a session.
• Approval transport chorus — dangerous-command approvals in Chorus-woken sessions are posted as Chorus comments that @mention the owner. Setting security.approval.transport_fallback: builtin keeps the built-in prompt for interactive CLI sessions.

5. Verify Connection

chorus_checkin()

If it fails, check: API Key correct (cho_ prefix)? URL reachable? Native mcp_servers.chorus entry present for a non-loopback Chorus? Hermes restarted?

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