@chorus-aidlc/chorus-openclaw-plugin 0.3.1 → 0.5.0

package/skills/chorus/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: chorus
+description: Chorus AI Agent collaboration platform — overview, common tools, setup, and routing to stage-specific skills.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.9.0"
+  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](#skill-routing) below.
+
+> **⚠️ Tool namespace under OpenClaw.** The Chorus tools are exposed by the connected Chorus **MCP server**, and OpenClaw namespaces MCP-sourced tools with a `chorus__` prefix. Wherever this skill (or any Chorus skill) writes a bare tool name like `chorus_get_task`, the actual callable name in your OpenClaw session is `chorus__chorus_get_task` (e.g. `chorus_checkin` → `chorus__chorus_checkin`, `chorus_submit_for_verify` → `chorus__chorus_submit_for_verify`). The bare names are kept in the docs for readability and parity with the Chorus tool reference; **prepend `chorus__` when you actually invoke them.** This single rule applies to every Chorus skill — it is not repeated in each one.
+
+---
+
+## 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 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. (Reminder: prepend `chorus__` when invoking — see the namespace note above.)
+
+### Checkin
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_checkin` | Call at session start: get Agent persona, role, current assignments, pending work counts, and unread notification count |
+
+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 the `projectUuids` array in the plugin configuration (see [Setup](#setup) below).
+
+**Behavior**:
+- **Empty array (default)**: Returns all projects
+- **One or more UUIDs**: Returns only matching projects and their events
+
+**Affected tools**: `chorus_checkin`, `chorus_get_my_assignments`
+
+### Session (Sub-Agents Only)
+
+Unlike the Claude Code plugin (which fully automates session lifecycle via hooks), **OpenClaw does not run the Claude Code SubagentStart / heartbeat / cleanup hooks**. Session handling is therefore **manual** on OpenClaw. See `/develop` for the full manual session protocol. In short, a sub-agent must:
+
+1. `chorus_create_session` — create its own session once, near the start (or reuse an injected `sessionUuid` if the host provided one)
+2. `chorus_session_checkin_task` — before starting work on a task
+3. Pass `sessionUuid` to `chorus_update_task` and `chorus_report_work`
+4. `chorus_session_checkout_task` — when done with a task
+5. `chorus_close_session` — when the sub-agent finishes (no hook closes it for you)
+
+Main agent / Team Lead: no session needed — call tools without `sessionUuid`.
+
+### 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_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 tool's description carries the section template — read it there. `/yolo` writes one mandatorily; `/develop` offers it advisorily on last-task verify.
+
+### Proposals
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_get_proposals` | List project Proposals (filterable by status: pending, approved, rejected) |
+| `chorus_get_proposal` | Get a single Proposal's details, including documentDrafts and taskDrafts |
+
+### 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_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 `/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
+
+| Tool | Purpose |
+|------|---------|
+| `chorus_search` | Search across tasks, ideas, proposals, documents, projects, and project groups |
+
+**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
+
+| 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., `https://chorus.example.com/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. Plugin Configuration
+
+The OpenClaw Chorus plugin auto-registers the Chorus MCP server (streamable-http + Bearer) from your plugin config. Config file: `~/.openclaw/openclaw.json`.
+
+Add the Chorus plugin configuration under `plugins.entries.chorus-openclaw-plugin.config`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "chorus-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "chorusUrl": "https://chorus.example.com",
+          "apiKey": "cho_your_api_key_here",
+          "projectUuids": [],
+          "autoStart": true
+        }
+      }
+    }
+  }
+}
+```
+
+**Configuration fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `chorusUrl` | Yes | Chorus server URL (e.g., `https://chorus.example.com`) |
+| `apiKey` | Yes | Chorus API Key (must start with `cho_` prefix) |
+| `projectUuids` | No | Array of project UUIDs to monitor. Empty array = all projects. |
+| `autoStart` | No | Auto-claim and begin work on `task_assigned` events (default: `true`) |
+
+Once registered, every Chorus tool is reachable as `chorus__<tool_name>` (the `chorus__` prefix comes from the MCP server id; see the namespace note at the top of this skill).
+
+### 3. Verify Connection
+
+After configuring, the plugin connects and registers the MCP server automatically. Verify by calling:
+
+```
+chorus__chorus_checkin()
+```
+
+If it fails, check: API Key correct (`cho_` prefix)? URL reachable? Plugin enabled in config? MCP server shown as connected in OpenClaw?
+
+### 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_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_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 Skills
+
+The plugin bundles two independent **review skills**: `/proposal-reviewer` and `/task-reviewer`. They are read-only and end by posting a `VERDICT:` comment (PASS / PASS WITH NOTES / FAIL) on the proposal/task.
+
+**How review runs on OpenClaw.** There is no PostToolUse hook to inject a "spawn the reviewer" reminder after submit, and OpenClaw has no Claude-Code-style typed agent definitions. Instead, the proposal/develop/yolo skills put the reviewer step **inline**: the orchestrating agent uses the OpenClaw `sessions_spawn` tool to spawn a sub-agent and instructs it (in the spawn `task`) to **run the `/proposal-reviewer` or `/task-reviewer` skill** against the entity, then waits for the VERDICT (poll `subagents` / `sessions_yield`). Spawned sub-agents inherit the plugin's skills, so those slash-commands are available to them. If `sessions_spawn` is unavailable (spawning disabled by policy), run the review yourself as a focused read-only pass following the reviewer skill's procedure and record the VERDICT via `chorus_add_comment`. See the relevant stage skill for the exact procedure.
+
+Results are advisory — they do not hard-block approval or verification, but you should act on a FAIL by fixing the listed BLOCKERs before proceeding.
+
+---
+
+## SSE Event-Driven Model
+
+The OpenClaw Chorus plugin runs a background service that holds a **Server-Sent Events (SSE)** connection to the Chorus server and wakes the agent (via the plugin's in-process system-event bridge) when relevant events arrive. Instead of polling, the agent is notified the moment something needs its attention.
+
+### How It Works
+
+1. The plugin connects to the Chorus SSE endpoint using the configured API Key
+2. When a notification event arrives, the plugin fetches the full notification details
+3. If `projectUuids` is configured, events from other projects are filtered out
+4. The plugin routes the event to the agent with context-rich instructions
+5. If `autoStart` is enabled, certain events (like `task_assigned`) auto-claim before waking the agent
+
+### Event Types
+
+| Event | Trigger | Agent Action |
+|-------|---------|--------------|
+| `task_assigned` | A task is assigned to this agent | Fetch task details with `chorus_get_task`, begin work |
+| `mentioned` | Someone @mentions this agent in a comment | Review the entity and respond via `chorus_add_comment` |
+| `elaboration_requested` | PM starts an elaboration round on a claimed Idea | Review questions with `chorus_get_elaboration` |
+| `elaboration_answered` | Stakeholder answers elaboration questions | Review answers, validate or request follow-up |
+| `proposal_rejected` | Admin rejects a Proposal | Review feedback, fix drafts, resubmit |
+| `proposal_approved` | Admin approves a Proposal | Check new tasks with `chorus_get_available_tasks` |
+| `idea_claimed` | An Idea is assigned to this agent | Review idea with `chorus_get_idea`, begin elaboration |
+| `task_verified` | Admin verifies a completed task | Check if downstream tasks are unblocked |
+| `task_reopened` | Admin reopens a task for rework | Review feedback in comments, fix issues |
+
+Each event includes the entity UUID, project UUID, and actor information so the agent can immediately take action without additional lookups.
+
+---
+
+## Execution Rules
+
+1. **Always check in first** — Call `chorus_checkin()` at session start
+2. **Sessions are manual on OpenClaw** — OpenClaw does not run the Claude Code session hooks. Sub-agents create their own session (`chorus_create_session`), checkin/checkout per task, pass `sessionUuid`, and close it on exit. The main agent skips session tools. See `/develop`.
+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. **Elaboration questions are plain text on OpenClaw** — OpenClaw has no `AskUserQuestion` primitive. Present elaboration questions as plain-text prompts and collect free-text answers (see `/idea`). In `/yolo` the agent self-answers without any user interaction.
+12. **Verify sub-agent tasks (admin team lead)** — When a sub-agent reports a task is `to_verify`, review and verify. 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:
+
+| Stage | Skill | Description |
+|-------|-------|-------------|
+| **Full Auto** | `/yolo` | Full-auto AI-DLC pipeline — from prompt to done. Automates Idea → Proposal → Execute → Verify with adversarial reviewers |
+| **Quick Dev** | `/quick-dev` | Skip Idea→Proposal, create tasks directly, execute, and verify |
+| **Ideation** | `/idea` | Claim Ideas, run elaboration rounds, prepare for proposal |
+| **Planning** | `/proposal` | Create Proposals with document & task drafts, manage dependency DAG, submit for review |
+| **Development** | `/develop` | Claim Tasks, report work, manual session & sub-agent management |
+| **Review** | `/review` | Approve/reject Proposals, verify Tasks, project governance |
+| **OpenSpec mode** | `openspec-aware` | Opt-in **shared sub-procedure** invoked by `/proposal`, `/develop`, and `/yolo` whenever the user has the `openspec` CLI installed. Scaffolds `openspec/changes/<slug>/` on disk and mirrors files into Chorus document drafts via the `chorus-api.sh` wrapper. Runs an inline three-check detection (no SessionStart hook on OpenClaw). Skips silently in fallback mode. |
+
+### 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)