# Chorus

> Chorus AI Agent collaboration platform for Hermes Agent — overview, common tools, Hermes setup, and routing to stage-specific skills.

- Skill: `chorus-aidlc/chorus-7` (Agent Skill)
- Install (CLI): `npx get-skill add chorus-aidlc/chorus-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chorus-aidlc/chorus-7/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: AGPL-3.0
- Author: chorus-aidlc (https://skillmd.com/u/chorus-aidlc)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/chorus-aidlc/chorus-7

---


# 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](#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.

---

## 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_review` uses `review:<type>:<uuid>`, where type is `proposal`, `task`, or `idea` (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>`, not `idea:<uuid>`). An orchestrator also assigned a task uses `task:<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: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 identity/permissions, active-project Idea counts, owner-private project Teams, and notification summary |

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

#### 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](../orchestrate/SKILL.md#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 → matching read-only reviewer via the host-specific path in that section 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 on the Chorus MCP server entry:

| 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-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:
```yaml
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.

| 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. `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:

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

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

| Directory | Hermes plugin type | What it provides |
|---|---|---|
| `packages/chorus-hermes/chorus` | native plugin `chorus` | session check-in and reminders, the Chorus skills (`chorus:<name>`), the `chorus` gateway platform, the `chorus` approval transport |
| `packages/chorus-hermes/chorus-mcp` | portable package `chorus-mcp` | the `chorus` MCP server, so the model gets `mcp__chorus__*` tools |

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:

```bash
VERSION=0.24.1   # 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.24.1`) 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:

```bash
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:

```bash
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.

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

### 7. Review Agent Configuration

The plugin ships three independent, read-only reviewer skills. After proposal submission, task submission, or the last task of an idea-rooted proposal being verified, the Chorus Hermes plugin's `transform_tool_result` hook appends a reminder to the tool result telling you to run the reviewer as a `delegate_task` child. You must delegate it yourself — it is NOT auto-launched.

| Reminder fires after | Reviewer skill | Toggle |
|----------------------|----------------|--------|
| `chorus_pm_submit_proposal` | `chorus:chorus-proposal-reviewer` | always on (ignore the reminder to skip) |
| `chorus_submit_for_verify` | `chorus:chorus-task-reviewer` | always on (ignore the reminder to skip) |
| `chorus_admin_verify_task` on the last task of an idea-rooted proposal (final ship gateway) | `chorus:chorus-code-reviewer` over the Idea's aggregate change | `CHORUS_ENABLE_CODE_REVIEWER` (default `true`; set `false` to disable) |

Run a reviewer like this — the `[chorus-reviewer:<kind>]` marker (kind = `proposal` | `task` | `code`) MUST start `context` and should also be in `goal`; the plugin uses it to run the child in read-only mode (Chorus write tools other than `chorus_add_comment` are blocked, and so are `write_file`, `patch`, `terminal`, `execute_code`, and `delegate_task`):

```
delegate_task(
  goal="[chorus-reviewer:task] Review Chorus task <task-uuid> and post one VERDICT comment.",
  context="[chorus-reviewer:task]\nFirst call skill_view(\"chorus:chorus-task-reviewer\") and follow it.\nTask UUID: <uuid>\nMax review rounds: 3\nRepo: <abs path>\nEvidence: <abs paths of the evidence bundle files>",
)
```

Because the reviewer cannot run commands, **you build an evidence bundle first** for task and code reviews: write `git diff <base>...HEAD`, `git log --oneline <base>..HEAD`, and the project's test/build output to files (e.g. under `/tmp/chorus-review/<uuid>/`) and pass the absolute paths in `context`. `delegate_task` blocks until the reviewer returns; then read its `VERDICT:` comment with `chorus_get_comments` (the comment posted for THIS round, not an older one) and act on it.

Reviewers 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). The code-review gateway is capped at 3 rounds before escalating the Idea's feature-level BLOCKERs to a human instead of shipping. On a code-review FAIL, fix it via the quick-dev workflow (`skill_view("chorus:quick-dev")`): `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. Skipping reviewers reduces token usage but removes the independent quality gate.

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

The Chorus Hermes plugin resolves one **spec mode** per session (its `spec_mode.py`, the same rules as the Codex resolver) and its `pre_llm_call` check-in 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`, `CHORUS_ENABLE_OPENSPEC` ≠ `false`, an `openspec/` directory in the working directory, 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_view("chorus:spec-lite")`). `CHORUS_SPEC_MODE=off` selects free-form (no spec artifact).

OpenSpec spec-driven path: `chorus:proposal`, `chorus:develop`, and `chorus: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 injected context), actually **enable it for them** — run whichever steps are missing via `terminal`, don't just describe them:

```bash
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 **start a new session** (`/reset`, or restart `hermes gateway` for Chorus-woken sessions); 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` (or `CHORUS_ENABLE_OPENSPEC=false`) — 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** — `chorus_checkin()` runs at session start (the Chorus Hermes plugin's `pre_llm_call` hook does this automatically and injects the result); call it again only to refresh
2. **Worker sessions are yours to manage** — Hermes does not auto-create Chorus sessions. When you delegate workers with `delegate_task`, create (or reopen) one session per worker, pass its `sessionUuid` in the worker's `context`, and call `chorus_close_session` after `delegate_task` returns. Reviewers get no session.
3. **Session checkin is sub-agent only** — Workers call `chorus_session_checkin_task` / `chorus_session_checkout_task` and pass `sessionUuid`. The main agent skips session tools apart from creating/closing worker sessions.
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. **Route human questions through Chorus** — Structured questions (elaboration or brainstorm choices) go into an elaboration round via `chorus_pm_start_elaboration` (2-5 options per question; the Chorus UI adds "Other"). Then reach the human:
    - **Interactive CLI/TUI session with the human in chat**: also list the round's questions in the chat, numbered, with lettered options and your recommended option marked; record the replies with `chorus_answer_elaboration` (the round stays the audit trail). The human may answer in the Chorus UI instead.
    - **Gateway (Chorus-woken) session, or no human in chat**: post one `chorus_add_comment` on the Idea that @mentions the owner (`@[Name](user:<ownerUuid>)` from `chorus_checkin`) and points to the pending round, then END THE TURN. Do not poll — the gateway wakes you when the round is answered or the owner replies.
    - **Yes/no confirmations** (skip elaboration, confirm understanding before validating, approve a destructive step): ask in chat when interactive; otherwise `chorus_add_comment` with an @mention on the entity and end the turn, acting on the reply when woken.
    - Never answer on the 

…(truncated)
