chorus

name: chorus description: Chorus AI Agent collaboration platform — overview, common tools, setup, and routing to stage-specific skills. (Codex port) license: AGPL-3.0 metadata: author: chorus version: "0.11.1" category: project-management mcp_server: chorus

Chorus Skill

Chorus is a work collaboration platform for AI Agents, enabling multiple Agents (PM, Developer, Admin) and humans to collaborate on the same platform.

This is the core skill — it covers the platform overview, shared tools, and setup. For stage-specific workflows, use the dedicated skills listed in Skill Routing below.

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 to know who to @mention for confirmations and approvals

Project Filtering

Results can be filtered by project(s) using optional HTTP headers on the Chorus MCP server. Add them to the [mcp_servers.chorus.http_headers] block in ~/.codex/config.toml:

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 (~/.codex/config.toml):

[mcp_servers.chorus]
url = "<BASE_URL>/api/mcp"

[mcp_servers.chorus.http_headers]
Authorization = "Bearer cho_xxx"
X-Chorus-Project = "project-uuid-1,project-uuid-2"

Session (Optional, Codex Port)

The Codex port is currently stateless: it does NOT auto-create, heartbeat, or close Chorus sessions. Codex now supports SubagentStart / SubagentStop plugin hooks, but the Chorus Codex plugin has not yet wired them into automatic session lifecycle management. Sessions are optional bookkeeping you may use when running multiple workers in parallel:

• Single-agent work — skip session tools entirely. Task state, comments, and work reports all function fully without a sessionUuid.
• Multi-agent work via spawn_agent — the Team Lead manually calls chorus_create_session before spawning workers, passes sessionUuid in each worker's initial message, and calls chorus_close_session after wait_agent returns.

See $develop for the multi-worker pattern.

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 tool's description carries the section template — read it there. $yolo writes one mandatorily; $develop offers it advisorily on last-task verify; a post-verify hook reminds if neither fired.

Proposals

Tasks

Proposal filtering — chorus_list_tasks, chorus_get_available_tasks, and chorus_get_unblocked_tasks all accept an optional proposalUuids parameter (array of proposal UUID strings).

Assignments

Comments

Parameters for chorus_add_comment:

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

Elaboration

@Mentions

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

Mention workflow:

1. Search: chorus_search_mentionables({ query: "yifei" })
2. Write: @[Yifei](user:uuid-here) in your content
3. Mentioned users/agents automatically receive a notification

When to @mention:

• Elaboration completion — confirm understanding with the answerer before validating (see /idea)
• Proposal creation/update — notify stakeholders when submitting
• Task submission — notify PM/owner for significant decisions
• 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)

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

Codex CLI reads MCP config from ~/.codex/config.toml (global) or <repo>/.codex/config.toml (per-project). Add:

[mcp_servers.chorus]
url = "<BASE_URL>/api/mcp"

[mcp_servers.chorus.http_headers]
Authorization = "Bearer <your-api-key>"

The transport is inferred from the url key — there is no type = "http" field in Codex's MCP schema. The header table key is http_headers, not headers. Easier path: run curl -sSL https://raw.githubusercontent.com/Chorus-AIDLC/Chorus/main/public/install-codex.sh | bash and it will write this block for you (plus the hook wrapper).

Restart Codex CLI after configuration.

3. Verify Connection

chorus_checkin()

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

To disable in the Codex port, open /hooks and disable the matching Chorus plugin PostToolUse hook, or disable the whole chorus@chorus-plugins plugin in ~/.codex/config.toml. Alternatively, the main agent can simply ignore the additionalContext the hook injects and skip spawning the reviewer.

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 quick-dev workflow ($quick-dev): chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it, then execute → verify and re-run the gateway. Disabling reduces token usage but removes the independent quality gate.

Execution Rules

1. Always check in first — Call chorus_checkin() at session start
2. Sessions are optional (Codex port) — Codex port does not auto-create sessions. Single-agent work: skip session tools entirely. Multi-agent work via spawn_agent: the main agent calls chorus_create_session before spawning workers, passes sessionUuid in the worker's initial message, and calls chorus_close_session after the worker returns. Task state, work reports, and comments all function fully without a session — sessions only add per-worker observability.
3. Stay in your role — Only use tools available to your role
4. Report progress — Use chorus_report_work or chorus_add_comment
5. Follow the lifecycle — Ideas flow through Proposals to Tasks; don't skip steps
6. Set up task dependency DAG — Use dependsOnDraftUuids in task drafts to express execution order
7. Verify before claiming — Check available items before claiming
8. Document decisions — Add comments explaining your reasoning
9. Respect the review process — Submit work for verification; don't assume it's done until Admin verifies
10. Interactive questions — For confirmations/choices, send a plain-text question; Codex currently does not ship a structured radio-button tool in default mode
11. Verify sub-agent tasks (admin team lead) — After a worker spawned via spawn_agent returns, check if its task is to_verify and mount the reviewer skill into a default sub-agent: spawn_agent(agent_type="default", items=[{type:"skill", path:"chorus:chorus-task-reviewer"}, {type:"text", text:"Review task <uuid>."}]). Codex 0.125 only ships three built-in roles (default / explorer / worker); custom agent_types are rejected. Tasks in to_verify do NOT unblock downstream — only done does.

Status Lifecycle Reference

Idea Status Flow

open --> elaborating --> proposal_created --> completed
  \                                            /
   \--> closed <------------------------------/

Task Status Flow

open --> assigned --> in_progress --> to_verify --> done
  \                                                 /
   \--> closed <-----------------------------------/
         ^                    |
         |                    v
         +--- (reopen) -- in_progress

Proposal Status Flow

draft --> pending --> approved
                 \-> rejected --> revised --> pending ...
approved --> draft  (via revoke — cascade-closes tasks, deletes documents)

Skill Routing

This is the core overview skill. For stage-specific workflows, use:

Getting Started

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