@chorus-aidlc/chorus-pi 0.0.1 → 0.0.3

package/README.md

@@ -6,6 +6,7 @@ Chorus AI-DLC collaboration platform extension for [Pi](https://pi.dev). Ported
 
 - **12 skills** — `/skill:chorus`, `/skill:idea`, `/skill:proposal`, `/skill:develop`, `/skill:review`, `/skill:quick-dev`, `/skill:yolo`, `/skill:brainstorm`, `/skill:orchestrate`, `/skill:docs`, `/skill:chorus-cli`, `/skill:openspec-aware`
 - **3 read-only reviewer sub-agents** — `chorus-proposal-reviewer`, `chorus-task-reviewer`, `chorus-code-reviewer`
+- **1 worker sub-agent** — `chorus-worker`, a general-purpose Chorus implementer that claims and completes ONE task via the develop workflow (dispatch it with the `subagent` tool, single or parallel mode, for wave-based execution)
 - **1 session-aware extension** (`extensions/chorus.ts`) — subscribes to Pi native events to automate checkin, context injection, reviewer nudges, and session lifecycle
 - **The official pi subagent pattern** bundled at `extensions/subagent/` (the `subagent` tool + package-relative agent discovery)
 
@@ -25,11 +26,17 @@ reviewer agents are discovered directly from the package's own `agents/` dir —
 there is **no** separate subagents dependency and **no** manual copy of agent
 files into `~/.pi/agent/agents/`.
 
-Then configure `.mcp.json` and env vars — see [`docs/CONNECT_PI.md`](../../docs/CONNECT_PI.md).
+Then configure `mcp.json` and env vars — see [`docs/CONNECT_PI.md`](../../docs/CONNECT_PI.md).
 
 `chorus init` (a.k.a. `chorus agents add`) automates this: select **Pi** in the agent
-checklist and it runs `pi install npm:@chorus-aidlc/chorus-pi` for you (degrading to the
-manual command if the `pi` CLI is absent).
+checklist and it runs both installs (`pi install npm:pi-mcp-adapter && pi install
+npm:@chorus-aidlc/chorus-pi`, degrading to the manual commands if the `pi` CLI is absent)
+**and** writes pi's global `~/.pi/agent/mcp.json` with an `mcpServers.chorus` entry whose
+`Authorization` header references the key by environment variable (`Bearer ${CHORUS_API_KEY}`)
+— the resolved endpoint URL is a literal, and **no `cho_` key is written to disk** (the same
+keyless model Claude Code and Codex use). You still export `CHORUS_API_KEY` (and
+`CHORUS_AGENT_PROFILE`) in the shell that launches interactive pi — pi has no settings env-file
+to persist them into; the daemon spawner injects them for the wake path.
 
 ## Wakeable daemon backend (`--agent pi`)
 
@@ -49,7 +56,7 @@ that wakes it. See [`docs/CONNECT_PI.md`](../../docs/CONNECT_PI.md#run-pi-as-a-w
 
 ## Why Pi is the lowest-friction target
 
-- **MCP: zero installer.** `pi-mcp-adapter` auto-discovers the repo's `.mcp.json` (literal URL + Bearer — no `${VAR}` expansion needed, unlike Codex). The main agent gets all 40+ `chorus_*` tools with no setup script.
+- **MCP: adapter path, keyless config.** `pi-mcp-adapter` reads the `mcp.json` `chorus agents add` writes at `~/.pi/agent/mcp.json` (or a project-root `.mcp.json`) and exposes all 40+ `chorus_*` tools — the extension never registers tools itself. The `Authorization` header references the key by env var (`Bearer ${CHORUS_API_KEY}`, which the adapter interpolates at connect time), so no `cho_` key lands on disk. A literal Bearer also works, but the env-referenced form is what the CLI writes.
 - **Hooks: TypeScript, not bash.** The extension replaces ~10 bash hook scripts with one TS file. No `curl`/`jq`, no Bash 3.2 compatibility traps (the `${2:-{}}` JSON-parse bug that plagued the Codex port is structurally impossible here).
 - **Sub-agent sessions: automatic.** By monitoring `subagent` tool events, the extension auto-creates a Chorus session for each worker task in a dispatch and closes it when the tool call returns — a capability the Codex port lacks (Codex has no sub-agent lifecycle events, so its workers manage sessions manually).
 - **Skills: same standard.** Pi implements the Agent Skills standard, so the skill bodies port with find/replace only (Claude's `Task` tool → the `subagent` tool; `/chorus:develop` → `/skill:develop`).
@@ -71,17 +78,18 @@ packages/chorus-pi/
 │   ├── brainstorm/ orchestrate/  # divergent prelude + multi-agent orchestration
 │   ├── docs/ chorus-cli/      # docs router + CLI reference
 │   └── openspec-aware/        # opt-in spec-driven authoring sub-procedure
-├── agents/                   # 3 reviewer sub-agents — discovered package-relative by extensions/subagent/agents.ts (no manual copy)
-│   ├── chorus-proposal-reviewer.md
+├── agents/                   # 4 sub-agents — discovered package-relative by extensions/subagent/agents.ts (no manual copy)
+│   ├── chorus-proposal-reviewer.md   # read-only reviewers
 │   ├── chorus-task-reviewer.md
-│   └── chorus-code-reviewer.md
+│   ├── chorus-code-reviewer.md
+│   └── chorus-worker.md              # general-purpose task implementer (inherits full tools)
 ├── bin/
 │   └── chorus-mcp-call.sh    # stateless MCP-over-HTTP wrapper (from the Codex port) for OpenSpec byte-exact document mirroring
 └── README.md
 ```
 ## Status
 
-**Complete port** of the Claude Code / Codex plugins to Pi. All 12 skills, all 3 reviewer sub-agents, the session-aware extension, the bundled official subagent pattern, and the OpenSpec wrapper are implemented and validated (TS transpiles, JSON valid, all skill/agent names compliant with the Agent Skills standard, no Claude/Codex-specific references remain).
+**Complete port** of the Claude Code / Codex plugins to Pi. All 12 skills, all 3 reviewer sub-agents plus the `chorus-worker` implementer, the session-aware extension, the bundled official subagent pattern, and the OpenSpec wrapper are implemented and validated (TS transpiles, JSON valid, all skill/agent names compliant with the Agent Skills standard, no Claude/Codex-specific references remain).
 
 The extension goes beyond the Codex port in one key way: by using Pi's `tool_call` event (pre-execution, mutable input), it **auto-injects the Chorus session UUID + workflow into each dispatched worker's task** — the Pi-native equivalent of Claude's `SubagentStart` hook. The Codex port has no pre-spawn mutation channel, so its workers must manage sessions manually. On Pi, dispatch a worker via the `subagent` tool and the extension handles session creation + context injection, then closes the session when the (ephemeral) tool call returns.
 

package/agents/chorus-worker.md

@@ -0,0 +1,99 @@
+---
+name: chorus-worker
+description: General-purpose Chorus implementer subagent that claims and completes ONE Chorus task end-to-end via the develop workflow. Dispatch it via the blocking subagent tool (single or parallel mode) for wave-based execution.
+---
+
+You are a Chorus implementer. Your job is to take ONE assigned Chorus task and drive it from open to `to_verify` by writing real, working code — then hand back to the main agent for independent review and admin verification. You do NOT review, verify, or approve your own work.
+
+This mirrors the single-task execution flow of `/skill:develop`; consult that skill for the full workflow and edge cases.
+
+=== WHAT YOU RECEIVE ===
+
+Your dispatch prompt contains a Chorus **task UUID** (and usually a project UUID). It also carries a block the chorus-pi extension auto-injects at the end:
+
+```
+--- Chorus session (auto-injected by the chorus-pi extension) ---
+Session UUID: <session-uuid>
+...
+```
+
+Read the `Session UUID` from that block and pass it as `sessionUuid` on every task-lifecycle call below (checkin, update, report, checkout). If no such block is present (e.g. you were run without the extension), omit `sessionUuid` — the task calls still work, just without session attribution.
+
+=== MCP TOOL NAMES ===
+
+Use the `chorus_*` MCP tools for all Chorus data access — do NOT use curl or raw HTTP. Depending on how pi-mcp-adapter exposed the server, the tool-name prefix is either `chorus_*` (native) or `chorus_chorus_*` (gateway mode). If unsure, probe once with a checkin (`chorus_checkin` / `chorus_chorus_checkin`) and use whichever prefix resolves; apply it consistently for the rest of the run.
+
+=== WORKFLOW ===
+
+**1. Gather context.** Do NOT rely on the dispatch summary — read the source of truth:
+```
+chorus_get_task({ taskUuid: "<task-uuid>" })
+```
+Read the description, `acceptanceCriteriaItems`, priority, `dependsOn`, and `commentCount`. Then, for context:
+- `chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })` if `commentCount > 0` (prior work reports, feedback).
+- `chorus_get_proposal({ proposalUuid: "<from-task>", section: "documents" })` for the PRD / tech design the task implements.
+- `chorus_get_document({ documentUuid: "<doc-uuid>" })` for any linked references or full doc bodies.
+- Read upstream `dependsOn` tasks + their comments for the interfaces/contracts your work builds on.
+
+**2. Claim the task:**
+```
+chorus_claim_task({ taskUuid: "<task-uuid>" })
+```
+
+**3. Check in and start:**
+```
+chorus_session_checkin_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })
+chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress", sessionUuid: "<session-uuid>" })
+```
+> If `chorus_update_task(status:"in_progress")` is rejected for unresolved dependencies, stop and report the blocker back to the main agent — do not force it.
+
+**4. Implement.** Write real code per the task description and acceptance criteria. Follow the repo's conventions (read `CLAUDE.md` / `AGENTS.md` if present). Run the project's tests / build / lint and make them pass — do not narrate tests you did not run.
+
+**5. Report progress:**
+```
+chorus_report_work({
+  taskUuid: "<task-uuid>",
+  report: "What was done, files changed, commits, remaining work/blockers",
+  sessionUuid: "<session-uuid>"
+})
+```
+
+**6. Self-check acceptance criteria.** Re-read the task's `acceptanceCriteriaItems`, then:
+```
+chorus_report_criteria_self_check({
+  taskUuid: "<task-uuid>",
+  criteria: [
+    { uuid: "<criterion-uuid>", devStatus: "passed", devEvidence: "<evidence>" }
+    // ...
+  ]
+})
+```
+For **required** criteria, keep working until you can self-check as `passed`. Only mark **optional** criteria `failed` if genuinely out of scope.
+
+**7. Check out and submit for verify:**
+```
+chorus_session_checkout_task({ sessionUuid: "<session-uuid>", taskUuid: "<task-uuid>" })
+chorus_submit_for_verify({ taskUuid: "<task-uuid>", summary: "<what you built + AC self-check result>" })
+```
+
+=== HARD LIMITS ===
+
+- Do **NOT** admin-verify or approve your own work. `chorus_admin_verify_task`, `chorus_mark_acceptance_criteria`, and proposal approval are the main agent's / orchestrator's job — after you submit, the main agent spawns `chorus-task-reviewer` and acts on its VERDICT.
+- Do **NOT** call `chorus_create_session` or `chorus_close_session` — the chorus-pi extension owns session lifecycle (it created your session and closes it when the dispatching `subagent` tool call returns).
+- Work on **ONE** task. If you cannot complete it (missing knowledge, hard blocker), `chorus_release_task` it, add a comment explaining why, and report that back — do not leave it half-claimed.
+
+=== OUTPUT FORMAT (REQUIRED) ===
+
+End your run with this exact structure so the main agent can proceed to review:
+
+```
+## Completed
+<one-paragraph summary of what you implemented and the task's final status (to_verify)>
+
+## Files Changed
+- path/to/file.ts — what changed
+- ...
+
+## Notes
+- Test/build results, any AC left optional-failed with rationale, blockers, or follow-ups
+```

package/lib/lib.ts

@@ -102,11 +102,13 @@ export function isReviewerAgent(name: string): boolean {
  * the session workflow into them adds irrelevant task-lifecycle instructions and
  * unnecessary chorus_create_session API traffic for agents that never touch a task.
  *
- * This is a positive allowlist (not a reviewer exclusion) so arbitrary custom
- * read-only agents also do NOT get a session. Add more worker names here if the
- * project introduces them.
+ * `chorus-worker` is this package's own general-purpose implementer agent
+ * (agents/chorus-worker.md); `worker` is retained for back-compat with pi's
+ * subagent example. This is a positive allowlist (not a reviewer exclusion) so
+ * arbitrary custom read-only agents also do NOT get a session. Add more worker
+ * names here if the project introduces them.
  */
-export const WORKER_AGENT_NAMES = ["worker"] as const;
+export const WORKER_AGENT_NAMES = ["worker", "chorus-worker"] as const;
 export function isWorkerAgent(name: string): boolean {
   return (WORKER_AGENT_NAMES as readonly string[]).includes(name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus-pi",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Chorus AI-DLC collaboration platform extension for the Pi coding agent. Provides skills for every stage of the AI-DLC lifecycle, read-only reviewer subagents, and session-aware extension hooks. The Chorus MCP server is auto-discovered from the repo's .mcp.json by pi-mcp-adapter — no installer required.",
   "author": {
     "name": "Chorus-AIDLC"

package/skills/chorus/SKILL.md

@@ -15,6 +15,12 @@ Chorus is a work collaboration platform for AI Agents, enabling multiple Agents
 
 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 names under Pi — read this first.** Pi reaches the Chorus MCP server through `pi-mcp-adapter`, which **prefixes every tool with the server key `chorus`**. Throughout these skills tools are written with their bare name (`chorus_checkin`, `chorus_pm_create_idea`, …), but Pi does **not** register those bare names — a bare `chorus_checkin` call returns *"tool not found"*. Address each tool by its adapter name instead:
+> - **Namespaced form (preferred):** `mcp__chorus__<tool>` — e.g. `mcp__chorus__chorus_checkin`, `mcp__chorus__chorus_pm_create_idea`.
+> - **Flattened alias:** `chorus_<tool>` → the server prefix produces a **doubled** `chorus_chorus_*` (e.g. `chorus_chorus_pm_create_idea`). The double `chorus_` is expected, not a typo.
+>
+> So: wherever a skill names a tool `chorus_…`, call it as `mcp__chorus__chorus_…`. If a tool ever reads as *"not found"*, you almost certainly dropped the `mcp__chorus__` prefix. This is Pi-specific — Claude Code / Codex resolve the bare names directly.
+
 ---
 
 ## Overview
@@ -151,7 +157,7 @@ Projects can be organized into **Project Groups** — a single-level grouping th
 
 ### 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 `content` parameter's description carries the three-section template (`## Summary` / `## Decisions` / `## Follow-ups`) — read it there. `/skill:yolo` writes one mandatorily; `/skill:develop` offers it advisorily on last-task verify; the extension nudges if neither fired.
+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:yolo` writes one mandatorily; `/skill:develop` offers it advisorily on last-task verify; the extension nudges if neither fired.
 
 ### References
 

package/skills/develop/SKILL.md

@@ -78,7 +78,7 @@ Review your persona, current assignments, and pending work counts.
 
 **Skip if you are the main agent or Team Lead.**
 
-If you are a **sub-agent** (spawned via `subagent_spawn`), the Chorus extension automatically creates your session and injects it into your task prompt — look for a `--- Chorus session (auto-injected) ---` section containing your `Session UUID`. Keep it for all task operations.
+If you are a **sub-agent** (dispatched via the `subagent` tool), the Chorus extension automatically creates your session and injects it into your task prompt — look for a `--- Chorus session (auto-injected) ---` section containing your `Session UUID`. Keep it for all task operations.
 
 ### Step 2: Find Work
 
@@ -259,13 +259,13 @@ Once Admin verifies (status: `done`), move to the next available task (back to S
 
 ### Step 11: Idea Completion Report (advisory)
 
-If the task you just self-verified was the LAST one of its Idea (every Task across every approved Proposal is now `done`/`closed`) and you have `document:write`, offer to call `chorus_create_report` via `AskUserQuestion`. The `content` parameter's description carries the section template. Skip on decline — the extension will remind on the next run.
+If the task you just self-verified was the LAST one of its Idea (every Task across every approved Proposal is now `done`/`closed`) and you have `document:write`, offer to call `chorus_create_report` via `AskUserQuestion`. The call requires `title` (a short report title) plus `content`; `content`'s parameter description carries the three-section template (`## Summary` / `## Decisions` / `## Follow-ups`). Skip on decline — the extension will remind on the next run.
 
 ---
 
 ## Session (Sub-Agents Only)
 
-The Chorus extension **fully automates** session lifecycle — creation (on `subagent_spawn`, via `tool_call` task injection) and cleanup (on `subagent_manage close`) are handled by the extension. Sub-agents only do 3 things manually:
+The Chorus extension **fully automates** session lifecycle — a Chorus session is created (on `subagent` dispatch, via `tool_call` task injection) and closed (when the blocking `subagent` call returns) by the extension. Sub-agents only do 3 things manually:
 
 1. `chorus_session_checkin_task({ sessionUuid, taskUuid })` — before starting work
 2. `chorus_session_checkout_task({ sessionUuid, taskUuid })` — when done (recommended; plugin also auto-checkouts on exit)
@@ -277,13 +277,15 @@ The Chorus extension **fully automates** session lifecycle — creation (on `sub
 
 ## Parallel Sub-Agent Integration
 
-When using Pi's subagents (`pi-subagents`) to run multiple sub-agents in parallel, Chorus provides full work observability. The `chorus-pi` extension automates the session lifecycle: when you `subagent_spawn` a worker, it creates a Chorus session and injects the session UUID + workflow into the worker's task; when you `subagent_manage close` the agent, it closes the session.
+Use the `subagent` tool to run multiple Chorus workers in parallel; Chorus provides full work observability. The `subagent` tool is **blocking** — a parallel dispatch runs every worker to completion and returns their aggregated output in one call (there is no async spawn, no `agentId`, and no manual close). The `chorus-pi` extension automates session lifecycle: when you dispatch a `chorus-worker`, it creates a Chorus session and injects the session UUID + workflow into that worker's task; when the `subagent` call returns, it closes the session.
+
+> The `subagent` tool has three modes — **single** (`{ agent, task }`), **parallel** (`{ tasks: [...] }`, max 8 per call, concurrency 4), and **chain** (`{ chain: [...] }`, sequential with a `{previous}` placeholder). Dispatch `agent: "chorus-worker"` for Chorus task implementation.
 
 ### Two-Layer Architecture
 
 | Layer | System | Purpose |
 |-------|--------|---------|
-| **Orchestration** | Pi subagents (`subagent_spawn` / `subagent_send` / `subagent_mailbox`) | Spawning sub-agents, follow-up tasks, inter-agent messaging |
+| **Orchestration** | The `subagent` tool (single / parallel / chain) | Dispatching workers to isolated pi subprocesses and collecting their results |
 | **Work Tracking** | Chorus | Task lifecycle, session observability, activity stream |
 
 ### Team Lead Workflow
@@ -293,24 +295,28 @@ When using Pi's subagents (`pi-subagents`) to run multiple sub-agents in paralle
 chorus_checkin()
 chorus_list_tasks({ projectUuid: "<project-uuid>" })
 
-# 2. Spawn sub-agents (async — returns immediately with an agentId)
-# Pass only task UUIDs — the chorus-pi extension auto-injects the session
-# UUID + workflow into the worker's task.
-subagent_spawn({
-  agent: "worker",
-  task: "Your Chorus task UUID: <task-uuid>\nProject UUID: <project-uuid>\n\nImplement..."
+# 2. Dispatch a worker per ready task in ONE blocking parallel call (max 8).
+# Pass only task + project UUIDs — the chorus-pi extension auto-injects the
+# session UUID + workflow into each worker's task.
+subagent({
+  tasks: [
+    { agent: "chorus-worker",
+      task: "Your Chorus task UUID: <task-uuid>\nProject UUID: <project-uuid>\n\nImplement..." },
+    // ... one entry per ready task, max 8 (batch into multiple calls if more)
+  ]
 })
-# → returns agentId (sa_<uuid>); keep it to close the agent later.
+# The call BLOCKS until every worker finishes and returns their outputs.
+# For a single task, use single mode: subagent({ agent: "chorus-worker", task: "..." })
 ```
 
 **What the Team Lead prompt needs:**
-- Task UUID(s)
+- Task UUID(s) + Project UUID
 - NO session UUID, NO workflow boilerplate — the extension auto-injects everything
-- The `agentId` returned by `subagent_spawn` (needed to `subagent_manage close` later)
+- No `agentId` to track and no close step — the blocking call owns the worker's whole lifecycle
 
 ### Sub-Agent Workflow
 
-The extension injects the session UUID + workflow into the sub-agent's task automatically (at `tool_call` time, before the subprocess starts). The sub-agent reads the `Session UUID:` from its task prompt and follows the injected steps:
+The extension injects the session UUID + workflow into the worker's task automatically (at `tool_call` time, before the subprocess starts). The worker reads the `Session UUID:` from its task prompt and follows the injected steps:
 
 ```
 # 1. Checkin to task (sessionUuid comes from the auto-injected task)
@@ -328,11 +334,9 @@ chorus_report_work({ taskUuid: "<my-task-uuid>", report: "...", sessionUuid: "<m
 chorus_session_checkout_task({ sessionUuid: "<my-session-uuid>", taskUuid: "<my-task-uuid>" })
 chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })
 
-# 6. (Optional) notify the team lead via mailbox — you need its agentId
-subagent_mailbox({ action: "send", agentId: "<team-lead-agentId>", message: "Task complete" })
-
-# DO NOT call chorus_close_session — the extension closes it when the
-# team lead runs subagent_manage({ action: "close", agentId: "<my-agentId>" })
+# The worker's final message is returned to the Team Lead as the subagent result.
+# DO NOT call chorus_close_session — the extension closes the session when the
+# blocking `subagent` call returns.
 ```
 
 ### Handling Task Dependencies (DAG)
@@ -341,25 +345,26 @@ subagent_mailbox({ action: "send", agentId: "<team-lead-agentId>", message: "Tas
 
 **Wave-based execution (recommended):**
 1. `chorus_get_unblocked_tasks` — find ready tasks
-2. `subagent_spawn` workers for Wave 1 (async; keep the agentIds)
-3. Wait for `to_verify` (poll `chorus_list_tasks` or read the async completion messages), then **verify each task** (`chorus_admin_verify_task` → `done`)
-4. `subagent_manage close` each finished worker (releases its slot + closes its Chorus session)
-5. `chorus_get_unblocked_tasks` — find newly unblocked tasks (Wave 2)
-6. Repeat until all tasks done
+2. Dispatch a `chorus-worker` per ready task in ONE blocking `subagent({ tasks: [...] })` call (max 8; batch if more). The call returns when the whole wave has finished (each worker at `to_verify`).
+3. **Verify each task** — spawn `chorus-task-reviewer`, act on its VERDICT, then `chorus_admin_verify_task` → `done`.
+4. `chorus_get_unblocked_tasks` — find newly unblocked tasks (Wave 2)
+5. Repeat until all tasks done
 
-> **Critical:** `to_verify` does NOT resolve dependencies — only `done` or `closed` does. The Team Lead must verify tasks between waves. Also remember to `subagent_manage close` finished workers — Pi limits concurrent sub-agents and `completed` does not release the slot.
+> **Critical:** `to_verify` does NOT resolve dependencies — only `done` or `closed` does. The Team Lead must verify tasks between waves. The blocking `subagent` call already released each worker's slot on return, so there is nothing to close.
 
 ### Multiple Tasks Per Sub-Agent
 
-A single sub-agent can work on multiple tasks sequentially:
+A single worker can handle several tasks sequentially — use single mode with an ordered list:
 
 ```
-subagent_spawn({
-  agent: "worker",
+subagent({
+  agent: "chorus-worker",
   task: "Your Chorus tasks (work in order):\n1. task-schema-uuid\n2. task-api-uuid (depends on #1)\n\nFor EACH task: checkin -> in_progress -> work -> report -> checkout -> submit_for_verify"
 })
 ```
 
+For strictly dependent stages where each step consumes the previous output, use chain mode: `subagent({ chain: [{ agent: "chorus-worker", task: "..." }, { agent: "chorus-worker", task: "... {previous} ..." }] })`.
+
 ### MCP Access for Sub-Agents
 
 Sub-agents need MCP configured at **project level** (`.mcp.json`) or **user level** (`~/.pi/agent/mcp.json`). The chorus-pi extension's session injection works regardless, because it calls chorus over its own MCP-over-HTTP fetch (not the sub-agent's gateway).

package/skills/openspec-aware/SKILL.md

@@ -376,11 +376,18 @@ The hook is read-only; you (the agent) perform the archive:
 
 3. **Halt on any error** from `openspec archive` or `chorus_pm_update_document`. Print stderr verbatim, post a comment on the proposal recording the failure (`chorus_add_comment` with `targetType: "proposal"`, `targetUuid: <proposalUuid>`), then stop. No retry. Matches §6 "no silent errors." (Comment on the proposal, not the idea: the failure is in archiving proposal-derived specs, and proposals can be `inputType: "document"` with no idea attached.)
 
-4. **Confirm success.** Resolve each matching Document UUID and run
-   `verify-document-roundtrip.sh <local-spec-path> <document-uuid>`. This
-   performs exact-byte comparison and metadata-only mismatch diagnostics. Do
-   not replace it with recursive `jq`, `head`, command substitution, or newline
-   normalization.
+4. **Confirm success.** For each capability, verify that
+   `openspec/specs/<capability>/spec.md` round-trips **byte-equal (modulo a
+   single trailing `\n`)** with its Chorus Document. The `--arg-file` mirror path
+   already guarantees this, so a spot check is enough: fetch the Document
+   `content` and `cmp` it against the local file. **Do NOT use `jq -r`** to
+   extract the content — it appends a trailing newline and manufactures a phantom
+   1-byte drift (a spec that mirrored correctly will read as 1 byte longer on the
+   server). Use `jq -j` (no trailing newline) or `cmp` directly, and never rely
+   on recursive `jq`, `head`, command substitution, or newline normalization.
+   (Unlike the Claude Code / Kiro / Codex plugins, the `chorus-pi` package ships
+   no `verify-document-roundtrip.sh` — the `--arg-file` byte-equality guarantee
+   makes it unnecessary.)
 
 **Strict opt-in:** if the verified task is not the last of its idea, OR the proposal description carries no `OpenSpec change slug: <slug>` line, OR the local shell has no `openspec` CLI, the hook exits 0 silently and no archive reminder is injected. Existing free-form behavior is preserved.
 

package/skills/yolo/SKILL.md

@@ -159,7 +159,7 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
            { id: "b", label: "<option B>" }
          ]
        }
-       // ... 5-8 questions covering functional, technical, scope aspects
+       // ... 5-8 questions covering functional, technical_context, scope aspects
      ]
    })
    ```
@@ -322,7 +322,9 @@ After `chorus_pm_submit_proposal`, the extension nudges you to spawn `chorus-pro
 
 After proposal approval, tasks exist in `open` status. Execute them in dependency-ordered waves using subagents. If spawning fails, fall back to main agent execution.
 
-#### Primary: Agent Team (parallel)
+#### Primary: subagent parallel dispatch (wave-based)
+
+The `subagent` tool is **blocking** — a parallel dispatch runs every worker in the wave to completion and returns their aggregated output in one call. There is no async spawn, no `agentId` to track, and no manual close. The chorus-pi extension auto-injects each worker's Chorus session UUID + workflow at `tool_call` time and closes the sessions when the dispatch returns.
 
 ```
 wave = 1
@@ -338,35 +340,37 @@ loop:
     # Stuck -- tasks failed review and can't proceed
     break with escalation report
 
-  # 2. Spawn a sub-agent for each unblocked task (async)
-  #    The chorus-pi extension auto-injects the session UUID + workflow
-  #    into each worker's task at tool_call time.
-  for each task in unblocked:
-    subagent_spawn({
-      agent: "worker",
-      task: "Your Chorus task UUID: {task.uuid}\nProject UUID: {project-uuid}\n\nImplement the task per its description and acceptance criteria. Read the task, proposal, and project documents for context."
-    })
-    # keep the returned agentId (sa_<uuid>) to close the worker later
-
-  # 3. Wait for all sub-agents to complete
-  #    Each sub-agent follows the /skill:develop workflow:
-  #    claim -> in_progress -> develop -> report -> self-check AC -> submit_for_verify
-  #    the extension nudges you to spawn chorus-task-reviewer after submit_for_verify
-  #    (use the blocking `subagent` tool so it waits for the VERDICT)
-
-  # 4. Proceed to Phase 4 (verification) for this wave
+  # 2. Dispatch one chorus-worker per unblocked task in a SINGLE blocking
+  #    parallel call. Max 8 tasks per call (concurrency 4) — if the wave has
+  #    more than 8 ready tasks, split into batches of <=8 sequential calls.
+  #    Pass only task + project UUIDs; the chorus-pi extension auto-injects the
+  #    session UUID + workflow into each worker's task at tool_call time.
+  subagent({
+    tasks: [
+      { agent: "chorus-worker",
+        task: "Your Chorus task UUID: {task.uuid}\nProject UUID: {project-uuid}\n\nImplement the task per its description and acceptance criteria. Read the task, proposal, and project documents for context." },
+      // ... one entry per unblocked task, max 8
+    ]
+  })
+  # The call BLOCKS until EVERY worker in the wave finishes. Each worker follows
+  # the /skill:develop workflow: claim -> in_progress -> report -> self-check AC
+  # -> submit_for_verify (leaving its task at to_verify).
+  # For a single ready task, use single mode instead:
+  #   subagent({ agent: "chorus-worker", task: "..." })
+
+  # 3. Proceed to Phase 4 (verification) for this wave
   wave += 1
 ```
 
-**What the sub-agent prompt needs:**
-- Task UUID(s)
-- Project UUID
+**What each worker task needs:**
+- Task UUID + Project UUID
 - NO session UUID, NO workflow boilerplate -- the extension auto-injects via tool_call mutation
+- No `agentId` and no close step — the blocking call owns the worker's whole lifecycle
 
 
 #### Fallback: Main Agent (sequential)
 
-If `subagent_spawn` fails (e.g., pi-subagents not installed, permission denied, or sub-agents crash repeatedly), fall back to executing tasks sequentially as the main agent:
+If the `subagent` dispatch is unavailable or its workers fail repeatedly (e.g., the subagent extension is not loaded, permission denied, or the child pi processes crash), fall back to executing tasks sequentially as the main agent:
 
 ```
 for each task in unblocked:
@@ -510,7 +514,7 @@ After all waves complete, output a markdown summary:
 
 ### Phase 5b: Idea Completion Report (mandatory)
 
-A successful `/yolo` run always finishes the Idea — call `chorus_create_report` once with `proposalUuid` set to the last verified proposal. The `content` parameter's description carries the section template; follow it. Surface the returned `documentUuid` in the Phase 5 summary. Skipping is a protocol violation.
+A successful `/yolo` run always finishes the Idea — call `chorus_create_report` once with `proposalUuid` set to the last verified proposal. The call requires `title` (a short report title) plus `content`; `content`'s parameter description carries the three-section template (`## Summary` / `## Decisions` / `## Follow-ups`); follow it. Surface the returned `documentUuid` in the Phase 5 summary. Skipping is a protocol violation.
 
 > **Order:** the completion report is written only **after** the Phase 4.5 code-review gateway returns PASS / PASS WITH NOTES. Never write it while a code-review FAIL is outstanding — the report is a ship-time summary, and the gateway is what clears the feature to ship.