@chorus-aidlc/chorus-openclaw-plugin 0.16.2 → 0.17.1

package/skills/openspec-aware/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: openspec-aware
-description: Opt-in OpenSpec-mode authoring for Chorus PM workflows on OpenClaw. Runs inline three-check detection for the local `openspec` CLI, scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via the `chorus-api.sh` wrapper. Required reading for the proposal, develop, and yolo skills whenever the user has the `openspec` CLI installed.
+description: Opt-in OpenSpec-mode authoring for Chorus PM workflows on OpenClaw. Runs inline three-check detection for the local `openspec` CLI, scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via `chorus mcp call --arg-file` (bash `chorus-api.sh` wrapper as fallback). Required reading for the proposal, develop, and yolo skills whenever the user has the `openspec` CLI installed.
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -16,7 +16,7 @@ This skill is a **shared sub-procedure** invoked by the Chorus stage skills (pro
 - Activates when **all three** signals hold (see §1): `CHORUS_OPENSPEC_MODE` is not `off`, an `openspec/` directory exists at the project root, and the `openspec` CLI is on `PATH`.
 - Otherwise the calling skill falls back to its existing free-form behavior.
 
-> **Tool namespace:** Chorus MCP tools are exposed under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_pm_create_proposal`). Bare names are used in prose for readability — prepend `chorus__` when invoking the MCP tools directly. **Document-mirror calls do NOT go through the MCP harness at all** — they go through the `chorus-api.sh` wrapper (see §2 Rule 1), which talks to the Chorus MCP endpoint over HTTP using your API key, independent of the `chorus__` namespacing.
+> **Tool namespace:** Chorus MCP tools are exposed under a `chorus__` prefix on OpenClaw (e.g. `chorus__chorus_pm_create_proposal`). Bare names are used in prose for readability — prepend `chorus__` when invoking the MCP tools directly. **Document-mirror calls do NOT go through the MCP harness at all** — they go through the `chorus` CLI (`chorus mcp call`, preferred) or the `chorus-api.sh` wrapper (fallback) (see §2 Rule 1), which talk to the Chorus MCP endpoint over HTTP using your API key, independent of the `chorus__` namespacing.
 
 ---
 
@@ -63,25 +63,28 @@ Run this detection inline whenever proposal / develop / yolo reference this skil
 
 Both are enforced at review time. Both have caused incidents in past releases.
 
-### Rule 1 — Mirror via the wrapper, never re-type document content from agent output
+### Rule 1 — Fill `content` from the file (CLI preferred, bash-wrapper fallback); never re-type document content from agent output
 
-Document/draft mirror calls (`chorus_pm_add_document_draft`, `chorus_pm_update_document_draft`, `chorus_pm_update_document`) **MUST** go through:
+Document/draft mirror calls (`chorus_pm_add_document_draft`, `chorus_pm_update_document_draft`, `chorus_pm_update_document`) **MUST** fill the `content` field from the local file's bytes, never from a hand-typed body. Calling these tools directly from the agent's MCP harness with a hand-typed `content` field is a **protocol violation** for OpenSpec mode and will fail review. Use whichever transport is available, preferred first:
 
-```
-chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"
-```
+- **Primary — the `chorus` CLI:** `chorus mcp call <tool_name> '<json-without-content>' --arg-file content=<file>`. `--arg-file content=<path>` reads the file's raw bytes and injects them as the JSON `content` string, byte-exact — the CLI's built-in replacement for `json_encode_file`, so no helper is needed. `chorus mcp call` reads the same `CHORUS_URL` / `CHORUS_API_KEY` from the environment (availability note below). See §3.6. **Requires chorus >= 0.17.0** (the `chorus mcp` subcommand was added then; an older CLI errors with "unknown command"); on any version or unknown-command failure, upgrade with `npm install -g @chorus-aidlc/chorus`.
+- **Fallback — the `chorus-api.sh` wrapper, when `chorus` is not on `PATH`:** build `$PAYLOAD` with the `json_encode_file` helper and call `chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"`. Defined in the §3.6 fallback block.
+
+> **New to the `chorus` CLI?** See the **`chorus-cli`** skill for install, configuring agents (`chorus agents add|remove|list`), the connection env vars, and `chorus mcp` basics.
+
+> **Acting identity — which agent the call acts as.** `chorus mcp call` resolves the agent from, in order: `CHORUS_AGENT_PROFILE` (a name or UUID) → `CHORUS_URL` + `CHORUS_API_KEY` in the environment → the single agent configured in `~/.chorus/daemon.json`. A daemon-woken session already has `CHORUS_AGENT_PROFILE` set. If a mirror call fails with `Multiple agents … specify --agent` (several agents configured and no profile/creds in the env), pass your own identity explicitly: `chorus mcp call <tool> … --agent <your-agentUuid>` — your UUID is in your `chorus_checkin` result, and `chorus agents` lists every configured name/UUID.
 
-with `$PAYLOAD` built using `json_encode_file` (defined in §3.4). Calling these tools directly from the agent's MCP harness with a hand-typed `content` field is a **protocol violation** for OpenSpec mode and will fail review. Reasons:
+Reasons (they apply to both paths):
 
-1. **Token cost.** Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. The wrapper streams bytes through `jq -Rs '.'` — content never enters LLM context. A typical 3-doc proposal mirror via the script costs roughly zero content-tokens; via direct MCP it routinely costs 20k+.
-2. **Byte-equality.** `jq -Rs '.'` is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The byte-equality guarantee (modulo trailing `\n`) holds **only** on the wrapper path.
-3. **Single source of truth.** With the wrapper, the local `openspec/changes/<slug>/*.md` is authoritative and Chorus is a mirror. With agent re-typing, authority splits between local file and whatever the LLM happened to output — a future diff cannot tell which one is correct.
+1. **Token cost.** Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. Both the CLI's `--arg-file` and the fallback's `json_encode_file` stream the file's bytes into the JSON string — content never enters LLM context. A typical 3-doc proposal mirror costs roughly zero content-tokens this way; via direct MCP with a re-typed body it routinely costs 20k+.
+2. **Byte-equality.** A file-fill path (CLI `--arg-file`, or the fallback's `jq -Rs '.'`) is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. LLM re-emission has a non-zero failure rate on long markdown — table alignment drifts, fence escapes get "fixed", long URLs wrap. The byte-equality guarantee (modulo trailing `\n`) holds **only** on a file-fill path, never on LLM re-emission.
+3. **Single source of truth.** With a file-fill mirror, the local `openspec/changes/<slug>/*.md` is authoritative and Chorus is a mirror. With agent re-typing, authority splits between local file and whatever the LLM happened to output — a future diff cannot tell which one is correct.
 
-> **`chorus-api.sh` availability on OpenClaw.** This wrapper is the document-mirror transport. It must be reachable as `chorus-api.sh` on `PATH` (the Chorus standalone skill bundle ships it; if you installed via that bundle it is already on `PATH`). If it is **not** on `PATH` in your OpenClaw environment, do one of:
-> - call it by its absolute path (e.g. `"$HOME/.chorus/bin/chorus-api.sh" mcp-tool ...`), or
+> **`chorus` / `chorus-api.sh` availability on OpenClaw.** The document-mirror transport is either the `chorus` CLI (preferred) or the `chorus-api.sh` wrapper (fallback). The wrapper must be reachable as `chorus-api.sh` on `PATH` (the Chorus standalone skill bundle ships it; if you installed via that bundle it is already on `PATH`). If neither `chorus` nor `chorus-api.sh` is on `PATH` in your OpenClaw environment, do one of:
+> - call the wrapper by its absolute path (e.g. `"$HOME/.chorus/bin/chorus-api.sh" mcp-tool ...`), or
 > - reproduce its single behavior inline — POST a JSON-RPC `tools/call` for `<tool_name>` with arguments `$PAYLOAD` to `"$CHORUS_URL/api/mcp"` with header `Authorization: Bearer $CHORUS_API_KEY` using `curl`, capturing the raw body for the §6 halt-on-error check.
 >
-> The wrapper requires `CHORUS_URL` and `CHORUS_API_KEY` in the environment (same values as your plugin config `chorusUrl` / `apiKey`). Export them before the first call if they are not already set. What you must NOT do is re-type the document body through the model — the wrapper-only rule stands regardless of how you invoke the wrapper.
+> Both `chorus mcp call` and the wrapper read `CHORUS_URL` and `CHORUS_API_KEY` from the environment (same values as your plugin config `chorusUrl` / `apiKey`). Export them before the first call if they are not already set. What you must NOT do is re-type the document body through the model — the file-fill rule stands regardless of which transport you use.
 
 ### Rule 2 — Halt on error via `chorus_check_response`
 
@@ -196,25 +199,12 @@ Optional:
 openspec validate "$SLUG"
 ```
 
-### 3.4 Helper: `json_encode_file`
+### 3.4 Filling the `content` field byte-exact
 
-Define once at the top of the authoring session. With `jq` available it streams the file into a JSON string; the fallback matches `chorus-api.sh`'s own escaping when `jq` is missing.
+The document `content` must be inserted **byte-for-byte** from the local file — never re-typed by the LLM. Two mechanisms, preferred first:
 
-```bash
-json_encode_file() {
-  local _path="$1"
-  if command -v jq >/dev/null 2>&1; then
-    jq -Rs '.' < "$_path"
-  else
-    local _content
-    _content=$(cat "$_path")
-    _content=${_content//\\/\\\\}
-    _content=${_content//\"/\\\"}
-    _content=${_content//$'\n'/\\n}
-    printf '"%s"' "$_content"
-  fi
-}
-```
+- **Primary — `chorus mcp call … --arg-file content=<path>`** (§3.6). The CLI reads the file's raw bytes and injects them as the JSON `content` string. This is the byte-faithful replacement for `json_encode_file`, so on the CLI path **no helper is needed** — pass the base JSON without a `content` field and let `--arg-file` fill it.
+- **Fallback — `json_encode_file`** (defined in the §3.6 fallback block, used only when `chorus` is not on `PATH`). With `jq` available it streams the file through `jq -Rs '.'`; the pure-shell branch matches `chorus-api.sh`'s own escaping when `jq` is missing.
 
 Round-trip: the Chorus backend appends a single `\n` to draft content on write, so server `content` is **byte-equal modulo a trailing newline**. Reviewers diffing local file vs server should ignore that one byte.
 
@@ -233,13 +223,46 @@ OpenSpec change slug: <slug>
 
 This line is machine-grep-able by future runs of this skill and by the §3.9 archive trigger.
 
-### 3.6 Mirror each document draft via the wrapper
+### 3.6 Mirror each document draft (CLI primary, wrapper fallback)
+
+> **Rule 1 reminder:** `content` comes from the file's bytes, never a hand-typed body. The agent must not retype the document body.
+
+Ensure `CHORUS_URL` and `CHORUS_API_KEY` are exported (Rule 1 note) — both the CLI and the wrapper read them. Define the halt-on-error helper from §6 once at the top. **Primary path — the `chorus` CLI:** pass the base JSON *without* a `content` field and let `--arg-file content=<file>` fill it byte-exact. One call per file:
+
+```bash
+# PRD draft — --arg-file fills content byte-exact from the file; no json_encode_file needed.
+RESULT=$(chorus mcp call chorus_pm_add_document_draft \
+  "{\"proposalUuid\":\"$PROPOSAL_UUID\",\"type\":\"prd\",\"title\":\"PRD: $HUMAN_TITLE\"}" \
+  --arg-file content="openspec/changes/$SLUG/proposal.md")
+RC=$?
+chorus_check_response "chorus_pm_add_document_draft (prd)" "$RC" "$RESULT"
+PRD_DRAFT_UUID=$(printf '%s' "$RESULT" | grep -o '"draftUuid"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
+```
+
+Repeat with `type: "tech_design"` for `design.md`, and one call per capability with `type: "spec"` for each `specs/<capability>/spec.md`. Do **not** mirror `tasks.md` — Chorus task drafts (created via the `chorus_pm_add_task_draft` MCP tool, no wrapper needed) are the source of truth for tasks.
+
+> Why parsing uses `printf '%s' "$RESULT" | grep` not `echo "$RESULT" | jq`: `echo` interprets backslash sequences inside the captured JSON, turning embedded `\n` into a real newline. `jq` then aborts with `Invalid string: control characters from U+0000 through U+001F must be escaped`. `printf '%s'` emits the captured bytes verbatim. Same pattern applies to all wrapper-result parsing in this skill.
 
-> **Rule 1 reminder:** these calls go through `chorus-api.sh`, not direct MCP. The agent must not retype the document body.
+#### Fallback — when the `chorus` CLI is not on `PATH`
 
-Ensure `CHORUS_URL` and `CHORUS_API_KEY` are exported (Rule 1 note). Define the halt-on-error helper from §6 once at the top, then run one call per file:
+If `command -v chorus` fails, mirror through the `chorus-api.sh` wrapper (or the absolute-path / inline-`curl` variants from the Rule 1 availability note). Define `json_encode_file` here (it is used **only** on this fallback path), then build `$PAYLOAD` with an embedded `content`. The `chorus_check_response` halt-on-error check applies exactly as on the primary path.
 
 ```bash
+# Define once, fallback-only: byte-faithful file → JSON string.
+json_encode_file() {
+  local _path="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -Rs '.' < "$_path"
+  else
+    local _content
+    _content=$(cat "$_path")
+    _content=${_content//\\/\\\\}
+    _content=${_content//\"/\\\"}
+    _content=${_content//$'\n'/\\n}
+    printf '"%s"' "$_content"
+  fi
+}
+
 # PRD draft
 CONTENT=$(json_encode_file "openspec/changes/$SLUG/proposal.md")
 PAYLOAD=$(cat <<JSON
@@ -257,13 +280,19 @@ chorus_check_response "chorus_pm_add_document_draft (prd)" "$RC" "$RESULT"
 PRD_DRAFT_UUID=$(printf '%s' "$RESULT" | grep -o '"draftUuid"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')
 ```
 
-Repeat with `type: "tech_design"` for `design.md`, and one call per capability with `type: "spec"` for each `specs/<capability>/spec.md`. Do **not** mirror `tasks.md` — Chorus task drafts (created via the `chorus_pm_add_task_draft` MCP tool, no wrapper needed) are the source of truth for tasks.
+### 3.7 Editing a draft after the first mirror
 
-> Why parsing uses `printf '%s' "$RESULT" | grep` not `echo "$RESULT" | jq`: `echo` interprets backslash sequences inside the captured JSON, turning embedded `\n` into a real newline. `jq` then aborts with `Invalid string: control characters from U+0000 through U+001F must be escaped`. `printf '%s'` emits the captured bytes verbatim. Same pattern applies to all wrapper-result parsing in this skill.
+Local file changes propagate via `chorus_pm_update_document_draft` — same primary/fallback split as §3.6, same halt check. Primary (CLI):
 
-### 3.7 Editing a draft after the first mirror
+```bash
+RESULT=$(chorus mcp call chorus_pm_update_document_draft \
+  "{\"proposalUuid\":\"$PROPOSAL_UUID\",\"draftUuid\":\"$PRD_DRAFT_UUID\"}" \
+  --arg-file content="openspec/changes/$SLUG/proposal.md")
+RC=$?
+chorus_check_response "chorus_pm_update_document_draft" "$RC" "$RESULT"
+```
 
-Local file changes propagate via `chorus_pm_update_document_draft` — same wrapper, same `json_encode_file`, same halt check.
+Fallback (no `chorus` on `PATH`) — `json_encode_file` from the §3.6 fallback block:
 
 ```bash
 CONTENT=$(json_encode_file "openspec/changes/$SLUG/proposal.md")
@@ -282,7 +311,17 @@ chorus_check_response "chorus_pm_update_document_draft" "$RC" "$RESULT"
 
 ### 3.8 Editing a Document after proposal approval
 
-Once the proposal is approved, drafts materialize into Documents with their own UUIDs. To keep `openspec/changes/$SLUG/` and the Chorus Document in sync, mirror file edits via `chorus_pm_update_document`:
+Once the proposal is approved, drafts materialize into Documents with their own UUIDs. To keep `openspec/changes/$SLUG/` and the Chorus Document in sync, mirror file edits via `chorus_pm_update_document`. Primary (CLI):
+
+```bash
+RESULT=$(chorus mcp call chorus_pm_update_document \
+  "{\"documentUuid\":\"$SPEC_DOCUMENT_UUID\"}" \
+  --arg-file content="openspec/changes/$SLUG/specs/<capability>/spec.md")
+RC=$?
+chorus_check_response "chorus_pm_update_document" "$RC" "$RESULT"
+```
+
+Fallback (no `chorus` on `PATH`) — `json_encode_file` from the §3.6 fallback block:
 
 ```bash
 CONTENT=$(json_encode_file "openspec/changes/$SLUG/specs/<capability>/spec.md")
@@ -351,9 +390,9 @@ When the §1 detection puts the agent in fallback mode (`CHORUS_OPENSPEC_ACTIVE=
 
 ## §6. Failure visibility — the `chorus_check_response` helper
 
-There is a known wrapper edge case: when the server returns HTTP 4xx (e.g. 401 from a bad `CHORUS_API_KEY`), `chorus-api.sh mcp-tool` captures the JSON-RPC error body internally, pipes it through a `.result.content[]?` jq filter that produces no output when `.result` is absent, and exits 0 with empty stdout. A bare `RC=$?` check would not halt on this — the most common runtime failure mode would be invisible. (If you reproduced the wrapper inline via `curl` per the Rule 1 note, the same three-signal check still applies to the raw HTTP body.)
+This helper guards **both** the primary CLI path and the fallback wrapper path. On the fallback path there is a known wrapper edge case: when the server returns HTTP 4xx (e.g. 401 from a bad `CHORUS_API_KEY`), `chorus-api.sh mcp-tool` captures the JSON-RPC error body internally, pipes it through a `.result.content[]?` jq filter that produces no output when `.result` is absent, and exits 0 with empty stdout. A bare `RC=$?` check would not halt on this — the most common runtime failure mode would be invisible. (If you reproduced the wrapper inline via `curl` per the Rule 1 note, the same three-signal check still applies to the raw HTTP body. `chorus mcp call` exits non-zero on tool/transport errors, so `RC` is reliable on the primary path — but run the same three-signal check on both, as defense in depth.)
 
-Define this helper **once** at the top of the authoring session and use it after every wrapper call:
+Define this helper **once** at the top of the authoring session and use it after every mirror call (CLI or wrapper):
 
 ```bash
 chorus_check_response() {
@@ -393,9 +432,15 @@ chorus_check_response() {
 - Skip capturing `$RESULT` into a variable; the helper needs the body.
 - Use only `if [ "$RC" -ne 0 ]; then ...` — that misses the HTTP-error path.
 
-**Minimal call site shape:**
+**Minimal call site shape (both paths):**
 
 ```bash
+# Primary — chorus CLI:
+RESULT=$(chorus mcp call <tool_name> '<json-without-content>' --arg-file content=<file>)
+RC=$?
+chorus_check_response "<tool_name>" "$RC" "$RESULT"
+
+# Fallback — chorus-api.sh wrapper (chorus not on PATH):
 RESULT=$(chorus-api.sh mcp-tool <tool_name> "$PAYLOAD")
 RC=$?
 chorus_check_response "<tool_name>" "$RC" "$RESULT"
@@ -418,8 +463,8 @@ When invoked from a stage skill (proposal / develop / yolo):
    c. Author `proposal.md`, `design.md`, `specs/<capability>/spec.md` (§3.2–§3.3). Mix `ADDED` / `MODIFIED` / `REMOVED` / `RENAMED` blocks as needed; remember `MODIFIED` overwrites the whole Requirement.
    d. Optional: `openspec validate "$SLUG"`.
    e. `chorus_pm_create_proposal` (direct MCP) with the `OpenSpec change slug: $SLUG` line in description (§3.5).
-   f. Export `CHORUS_URL` / `CHORUS_API_KEY`; define `json_encode_file`, `chorus_check_response` helpers; confirm `chorus-api.sh` is reachable (Rule 1 note).
-   g. For each row in §5 with "yes" — mirror via `chorus-api.sh mcp-tool chorus_pm_add_document_draft` (§3.6). Record each `$DRAFT_UUID`.
+   f. Export `CHORUS_URL` / `CHORUS_API_KEY` (both the CLI and the wrapper read them); define the `chorus_check_response` helper. Prefer `chorus mcp call … --arg-file content=<file>` for mirrors (§3.6) — no `json_encode_file` needed on that path; define `json_encode_file` and confirm `chorus-api.sh` is reachable (Rule 1 note) only when falling back to the wrapper because `chorus` is not on `PATH`.
+   g. For each row in §5 with "yes" — mirror via `chorus mcp call chorus_pm_add_document_draft … --arg-file content=<file>` (§3.6; fallback = `chorus-api.sh mcp-tool`). Record each `$DRAFT_UUID`.
    h. On any failed `chorus_check_response` — halt, surface the error, do NOT proceed.
 4. Edits before approval → §3.7. Edits after approval → §3.8.
 5. Last task verified → detect the trigger yourself (no hook) → run §3.9 archive flow.

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: orchestrate
+description: Multi-agent orchestration playbook — coordinate OTHER agents and humans across the AI-DLC lifecycle by delegating ideas and tasks, running independent reviewers, and gatekeeping at the Reversed-Conversation gates.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.17.0"
+  category: project-management
+  mcp_server: chorus
+---
+
+# Orchestrate Skill
+
+This skill is for an **orchestrator** (typically an Admin-preset agent) that coordinates *other* agents and humans across the AI-DLC lifecycle instead of doing all the work itself. The orchestrator decomposes work, hands each piece to a chosen owner, runs independent reviewers as quality gates, and gatekeeps the human-owned approval/verify gates — but never ships on its own.
+
+> **Tool namespace under OpenClaw.** Bare tool names below (e.g. `chorus_pm_assign_idea`) are the readable form; the actual callable name is `chorus__`-prefixed (`chorus__chorus_pm_assign_idea`). See the namespace note in the core `chorus` skill.
+
+It complements the other skills rather than replacing them:
+
+- `/yolo` — **one** agent drives the whole pipeline solo. Orchestration is the opposite: **many** agents, each owning a piece, coordinated by you.
+- `/idea`, `/proposal`, `/develop`, `/review`, `/quick-dev` — a single stage you execute yourself. Orchestration is the layer *above* those: you decide who runs each stage.
+
+---
+
+## When to use this skill
+
+Use it when **more than one agent (or agent + human) will touch the work** and someone has to keep them coherent:
+
+- You own a **theme / epic / container idea** that decomposes into several independent child ideas, and you want to hand each child to a specific worker (the motivating case: a theme owner gives one child to Codex, another to a Claude dev agent, another to a human).
+- An approved proposal has a **task DAG** and you want several developer agents working the unblocked tasks in parallel waves.
+- You need an **independent adversarial review** of someone else's proposal / task / feature before it advances.
+- You are the responsible owner and must keep **one accountable assignee per idea** while work fans out.
+
+Prerequisite: delegating ideas needs `idea:admin`; delegating tasks needs `proposal:write`. Run `chorus_checkin()` first to confirm your permission set.
+
+---
+
+## Delegation primitives
+
+### Assign an idea — `chorus_pm_assign_idea` (`idea:admin`)
+
+Hand a whole idea to a chosen agent or user. Parameters:
+
+| Param | Meaning |
+|-------|---------|
+| `ideaUuid` | The idea to delegate |
+| `assigneeType` | `"agent"` or `"user"` |
+| `assigneeUuid` | The chosen agent/user UUID (resolve names with `chorus_search_mentionables`) |
+| `instanceUuid` | *(optional, agent targets only)* pin the work to one durable AgentInstance — the `(agent, host, cwd)` place — so wakes land where the code lives |
+
+Behavior you must understand:
+
+- **The assignee is woken and advances from the idea's *current* stage** — it does **NOT** re-claim. If the idea is `open` it moves to `elaborating`; any other status is preserved. The assignee picks up wherever the idea already is (elaboration, ready-for-proposal, etc.).
+- **Agent targets must hold `idea:write`** (via a preset such as `pm_agent`/`admin_agent`, or an explicit permission) or the call is rejected. **User targets must be in your company.** `instanceUuid` is rejected for user targets.
+- **Silent takeover.** Reassigning an already-owned idea simply moves ownership to the new assignee — there is one owner at a time, no confirmation prompt. Use this deliberately, not by accident.
+
+### Assign a task — `chorus_pm_assign_task` (`proposal:write`)
+
+Hand a single task to a developer agent. Parameters: `taskUuid`, `agentUuid` (must hold `task:write`), optional `instanceUuid`. The task must be `open` or `assigned`. The assignee is woken to execute it. Use this to distribute the tasks of an approved proposal.
+
+### Derive child ideas and fan them out
+
+The theme-decomposition case, end to end:
+
+1. Read the container/theme idea and its context (`chorus_get_idea`, `chorus_get_documents`, `chorus_get_comments`).
+2. For each independent slice, create a child idea with `chorus_pm_create_idea` (link it back to the parent in the body / via `references[]`).
+3. Assign each child to a distinct owner with `chorus_pm_assign_idea` — e.g. one child to Codex, one to a Claude dev agent, one to a human. Each child now has its **own single owner** and advances independently.
+4. @mention each assignee and the theme owner so the delegation is visible.
+
+---
+
+## Independent review as an adversarial gate
+
+Chorus ships three read-only reviewer skills. As orchestrator you run them at the three gates and act on the verdict — this is your primary quality lever when you are not writing the code yourself.
+
+| Reviewer skill | Run after | Reviews |
+|----------------|-----------|---------|
+| `/proposal-reviewer` | a proposal is submitted | proposal draft quality (VERDICT on the proposal) |
+| `/task-reviewer` | a task is submitted for verify | one task vs its acceptance criteria (VERDICT on the task) |
+| `/code-reviewer` | the idea's last task is verified | the idea's **aggregate** code change — the final ship gateway (VERDICT on the idea) |
+
+Spawn a read-only sub-agent with `sessions_spawn` and instruct it (in the spawn `task`) to run the matching reviewer skill against the entity (pass the `ideaUuid` for code review), then poll for its VERDICT. If spawning is disabled by policy, run the reviewer's procedure yourself as a focused read-only pass and record the VERDICT via `chorus_add_comment`. Each posts exactly one `VERDICT: PASS` / `PASS WITH NOTES` / `FAIL` comment. Verdicts are **advisory** — they do not auto-approve, auto-verify, or hard-block; you read the BLOCKERs and decide. A `FAIL` means route the BLOCKERs back for a fix before advancing (for a code-review FAIL, add fix tasks to the *approved* proposal via `/quick-dev` and re-run once they are `done`). See `/review` for the full pattern.
+
+---
+
+## Choosing a collaboration mode
+
+Pick the lightest mode that fits the shape of the work:
+
+| Mode | Use when | How you run it |
+|------|----------|----------------|
+| **Single-owner drives one idea** | The work is one coherent feature | Assign the idea once (`chorus_pm_assign_idea`); that owner runs idea → proposal → tasks; you gatekeep the gates |
+| **Fan-out children to N agents** | A theme decomposes into independent slices | Derive child ideas, assign each to a distinct owner; children run in parallel, each single-owner |
+| **Parallel task waves** | One approved proposal with a task DAG | Assign the currently-unblocked tasks (`chorus_pm_assign_task`) to several dev agents; as tasks reach `done`, assign the next wave |
+| **Review-only** | Work is already produced elsewhere | Spawn the relevant reviewer, read the VERDICT, and gatekeep — no new delegation |
+
+Guidance: start narrow. If a single owner can hold the whole feature in their head, prefer **single-owner** — coordination overhead is not free. Reach for **fan-out** only when slices are genuinely independent (separate scope, separable elaboration). Use **parallel task waves** only after a proposal is approved and its DAG is real; respect dependencies — `to_verify` does **not** unblock downstream, only `done` does.
+
+---
+
+## Single-owner & concurrency discipline
+
+- **One responsible assignee per idea at a time.** This mirrors the daemon's single-owner semantics: the idea is the authoritative pin root, and its owner's proposals/tasks/wakes inherit that identity. Don't leave an idea ambiguously "owned by the team."
+- **Don't race duplicate sessions on the same work.** Two daemon sessions (or two agents) driving the same idea/task will collide on status transitions and produce conflicting wakes. Assign, then let one owner run.
+- **Pin with `instanceUuid` when the work is tied to a place.** If a child idea's code lives on a specific host/cwd, pin the assignment to that AgentInstance so every downstream wake lands there instead of a random daemon.
+
+---
+
+## Reversed-Conversation gates (you never auto-ship)
+
+Chorus is **AI proposes, humans verify**. As orchestrator you enforce that, you do not bypass it:
+
+- **Proposal gate.** When a delegated owner submits a proposal, STOP. Run the proposal reviewer, then hand the approve/reject decision to the human owner. Do not self-approve just because you *can* (`proposal:admin`).
+- **Verify gate.** When a task reaches `to_verify`, STOP. Run the task reviewer, then let the human verify. Permission to verify is not authorization to rubber-stamp your own coordinated work.
+- **Never merge or push.** The orchestrator drives work up to "PR ready" and hands it back to the human — it does not merge, push, or otherwise ship autonomously.
+
+@mention the owner at each gate so the handoff is explicit and auditable.
+
+---
+
+## Derive a child idea vs add a task vs assign directly
+
+| Do this | When |
+|---------|------|
+| **Derive a new child idea** (`chorus_pm_create_idea` + assign) | The slice is genuinely separate scope that deserves its own elaboration, proposal, and owner — a theme decomposition, or a parallelizable sub-feature. |
+| **Add a task to an approved proposal** (`chorus_create_tasks` with `proposalUuid`) | The work is a discrete unit of the **same** feature that already has a proposal — e.g. code-review fix tasks, or a follow-up step in an existing DAG. |
+| **Assign the existing idea/task directly** (`chorus_pm_assign_idea` / `chorus_pm_assign_task`) | The work is already scoped and just needs a (different) owner or executor — reassignment, taking over a stalled idea, or distributing existing tasks. |
+
+Rule of thumb: **new scope → child idea; same-proposal unit → task; only the owner changes → assign.**

package/skills/proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -97,7 +97,7 @@ Branch on the result:
 
 - **OpenSpec active (all three checks pass)** → follow `openspec-aware` §3. Pick `$SLUG`, scaffold `openspec/changes/<slug>/`, author `proposal.md` / `design.md` / `specs/<capability>/spec.md` locally, then create the proposal container (Step 1 above) with the literal line `OpenSpec change slug: <slug>` in `description`, and mirror each local file into a document draft.
 
-  > **⛔ Mandatory in OpenSpec mode:** mirror calls go through the `chorus-api.sh` wrapper with `content` produced by `json_encode_file` — see `openspec-aware` §3.6. Do **not** call `chorus_pm_add_document_draft` directly from the MCP harness with a hand-typed `content` field. Re-typing thousands of lines through the LLM burns 20k+ content tokens per proposal and breaks byte-equality with the local source of truth (`openspec-aware` §2 Rule 1 explains the full reasoning). Skip Step 2 below when in OpenSpec mode — the wrapper-based flow in `openspec-aware` §3.6 replaces it for documents.
+  > **⛔ Mandatory in OpenSpec mode:** mirror calls fill `content` from the local file — prefer `chorus mcp call … --arg-file content=<file>`, falling back to the `chorus-api.sh` wrapper with `json_encode_file` when `chorus` is not on `PATH` — see `openspec-aware` §3.6. Do **not** call `chorus_pm_add_document_draft` directly from the MCP harness with a hand-typed `content` field. Re-typing thousands of lines through the LLM burns 20k+ content tokens per proposal and breaks byte-equality with the local source of truth (`openspec-aware` §2 Rule 1 explains the full reasoning). Skip Step 2 below when in OpenSpec mode — the file-fill flow in `openspec-aware` §3.6 replaces it for documents.
 
 - **OpenSpec inactive (any check fails, or `CHORUS_OPENSPEC_MODE=off`)** → proceed with Step 2 unchanged. Author drafts inline as free-form Markdown via direct MCP `chorus_pm_add_document_draft`.
 

package/skills/proposal-reviewer/SKILL.md

@@ -4,7 +4,7 @@ description: Adversarial read-only review of a submitted Chorus proposal — doc
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/task-reviewer/SKILL.md

@@ -4,7 +4,7 @@ description: Adversarial verification of a submitted Chorus task against its AC
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/yolo/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — from prompt to done. Automates the en
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.16.2"
+  version: "0.17.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -213,8 +213,8 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
    **2a. OpenSpec mode (all three checks pass).** Follow `openspec-aware` §3 end-to-end:
    - Pick `$SLUG`, run `openspec new change "$SLUG"` (§3.1–§3.2).
    - Author `proposal.md`, `design.md`, and one `specs/<capability>/spec.md` per capability locally on disk (§3.3). ADDED Requirements only; per-spec fallback to free-form Markdown if MODIFIED/REMOVED is needed.
-   - Define `json_encode_file`, `chorus_check_response` helpers (§3.4, §6).
-   - Mirror each local file via `chorus-api.sh mcp-tool chorus_pm_add_document_draft "$PAYLOAD"` (§3.6) — one call per file, with the document type from `openspec-aware` §5.
+   - Define the `chorus_check_response` helper (§6); prefer `chorus mcp call … --arg-file content=<file>` for mirrors (§3.4/§3.6) — the bash-wrapper fallback's `json_encode_file` is only needed when `chorus` is not on `PATH`.
+   - Mirror each local file via `chorus mcp call chorus_pm_add_document_draft … --arg-file content=<file>` (§3.6; fallback = `chorus-api.sh mcp-tool chorus_pm_add_document_draft "$PAYLOAD"`) — one call per file, with the document type from `openspec-aware` §5.
 
    > **⛔ Do not** invoke `chorus_pm_add_document_draft` / `chorus_pm_update_document_draft` / `chorus_pm_update_document` from the MCP harness with a hand-typed `content` field in this branch. Re-typing the markdown body wastes 20k+ tokens per proposal and breaks byte-equality with the local files. See `openspec-aware` §2 Rule 1.
 

package/src/commands.ts

@@ -2,13 +2,14 @@ import type { ChorusMcpClient } from "./mcp-client.js";
 
 // ===== Response types from Chorus MCP tools =====
 //
-// These mirror the CURRENT (Chorus 0.7.2+) tool output shapes:
-//   - chorus_checkin           → { checkinTime, agent, ideaTracker, notifications }
+// These mirror the CURRENT (Chorus 0.17.0+) tool output shapes:
+//   - chorus_checkin           → { checkinTime, agent, activeProjects, guidance, notifications }
 //   - chorus_get_my_assignments → { ideaTracker, taskTracker }
-// Both `ideaTracker` and `taskTracker` are Records keyed by project UUID, with
-// the work items nested inside each project bucket. Every field is read
-// defensively (optional chaining) so a missing/renamed field degrades to "0"
-// or "none" rather than throwing.
+// chorus_checkin returns a per-project `activeProjects` distribution (name +
+// activeIdeaCount, NOT a per-idea list); the full per-idea `ideaTracker` lives
+// only in chorus_get_my_assignments. Both trackers are Records keyed by project
+// UUID. Every field is read defensively (optional chaining) so a missing/renamed
+// field degrades to "0"/"none" rather than throwing.
 
 interface IdeaTrackerEntry {
   uuid: string;
@@ -36,6 +37,11 @@ interface TaskTrackerProject {
   tasks?: TaskTrackerEntry[];
 }
 
+interface CheckinActiveProject {
+  name?: string;
+  activeIdeaCount?: number;
+}
+
 interface CheckinResponse {
   checkinTime?: string;
   agent?: {
@@ -43,7 +49,7 @@ interface CheckinResponse {
     name?: string;
     persona?: string | null;
   };
-  ideaTracker?: Record<string, IdeaTrackerProject>;
+  activeProjects?: Record<string, CheckinActiveProject>;
   notifications?: {
     unread?: number;
   };
@@ -71,6 +77,7 @@ const PLUGIN_SKILLS = [
   { name: "review", description: "Approve/reject proposals, verify tasks, project governance" },
   { name: "yolo", description: "Full-auto AI-DLC pipeline — from prompt to done" },
   { name: "openspec-aware", description: "Opt-in OpenSpec authoring for PM workflows when the openspec CLI is present" },
+  { name: "chorus-cli", description: "Install, configure agents (chorus agents add|remove|list), env vars, and chorus mcp operations" },
 ] as const;
 
 // ===== Formatting helpers =====
@@ -97,24 +104,17 @@ function formatSkillsList(): string {
   ].join("\n");
 }
 
-// Sum a count across every project bucket in a tracker Record.
-function countTracker<T>(
-  tracker: Record<string, { ideas?: T[]; tasks?: T[] }> | undefined,
-  key: "ideas" | "tasks"
-): number {
-  if (!tracker) return 0;
-  return Object.values(tracker).reduce((total, project) => {
-    const items = key === "ideas" ? project.ideas : project.tasks;
-    return total + (items?.length ?? 0);
-  }, 0);
-}
-
 function formatStatus(checkin: CheckinResponse, connectionStatus: string): string {
-  const ideaCount = countTracker(checkin?.ideaTracker, "ideas");
+  const projects = Object.values(checkin?.activeProjects ?? {});
+  const activeIdeaTotal = projects.reduce(
+    (total, p) => total + (p.activeIdeaCount ?? 0),
+    0
+  );
   const lines: string[] = [
     `Connection: ${connectionStatus}`,
     `Agent: ${checkin?.agent?.name ?? "unknown"}`,
-    `Assigned ideas: ${ideaCount}`,
+    `Active projects: ${projects.length} (${activeIdeaTotal} active idea(s))`,
+    ...projects.map((p) => `  - ${p.name ?? "(unnamed)"}: ${p.activeIdeaCount ?? 0}`),
     `Notifications: ${checkin?.notifications?.unread ?? 0} unread`,
     `Skills: ${PLUGIN_SKILLS.map((s) => s.name).join(", ")}`,
   ];

package/src/daemon-client.ts

@@ -402,7 +402,7 @@ export class OpenClawDaemonClient {
       this.emitExecutionSnapshot();
     }
     let advancedToRunning = false;
-    await this.advanceTurn(reportSessionId, "running", entity);
+    const runningTurnUuid = await this.advanceTurn(reportSessionId, "running", entity);
     advancedToRunning = true;
 
     const runId = this.nextRunId(contextKey);
@@ -462,7 +462,7 @@ export class OpenClawDaemonClient {
     // clean, aborted, or crashed). Guarded on advancedToRunning so a never-started wake
     // never attempts an illegal pending→ended transition.
     if (advancedToRunning) {
-      await this.advanceTurn(reportSessionId, "ended", entity);
+      await this.advanceTurn(reportSessionId, "ended", entity, runningTurnUuid);
     }
 
     // Interrupt-vs-crash reporting (entity-keyed — only for a reportable resource).
@@ -533,16 +533,20 @@ export class OpenClawDaemonClient {
     sessionId: string,
     status: "running" | "ended",
     entity: { entityType: string; entityUuid: string } | null,
-  ): Promise<void> {
+    turnUuid: string | null = null,
+  ): Promise<string | null> {
     try {
-      await this.restClient.turnAdvance({
+      const outcome = await this.restClient.turnAdvance({
         sessionId,
+        ...(turnUuid ? { turnUuid } : {}),
         status,
         entityType: entity?.entityType ?? null,
         entityUuid: entity?.entityUuid ?? null,
       });
+      return typeof outcome.data?.turnUuid === "string" ? outcome.data.turnUuid : null;
     } catch (err) {
       this.logger.warn(`[Chorus] advanceTurn failed for session ${sessionId} → ${status}: ${err}`);
+      return null;
     }
   }