@chorus-aidlc/chorus 0.7.1 → 0.8.1

package/.next/standalone/public/chorus-plugin/skills/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.8.0"
+  version: "0.8.3"
   category: project-management
   mcp_server: chorus
 ---
@@ -387,6 +387,7 @@ This is the core overview skill. For stage-specific workflows, use:
 | **Planning** | `/proposal` | Create Proposals with document & task drafts, manage dependency DAG, submit for review |
 | **Development** | `/develop` | Claim Tasks, report work, session & sub-agent management, Agent Teams integration |
 | **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. Skips silently in fallback mode. See `.claude/skills/openspec-aware/SKILL.md`. |
 
 ### Getting Started
 

package/.next/standalone/public/chorus-plugin/skills/develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.8.0"
+  version: "0.8.3"
   category: project-management
   mcp_server: chorus
 ---
@@ -133,6 +133,14 @@ Each task and proposal includes a `commentCount` field — use it to decide whic
    chorus_get_documents({ projectUuid: "<project-uuid>" })
    ```
 
+> **Document update flow (OpenSpec mode):** if the originating proposal `description` contains a line `OpenSpec change slug: <slug>`, the project's PRD / tech_design / spec Documents are **mirrors** of files under `openspec/changes/<slug>/`. To update such a Document (e.g. clarify an AC, fix a spec scenario before resubmitting), load the `openspec-aware` skill at `.claude/skills/openspec-aware/SKILL.md` and follow §3.8: edit the local `.md` file first, then mirror through the `chorus-api.sh` wrapper with `json_encode_file` and `chorus_check_response`.
+>
+> **⛔ Do not** call `chorus_pm_update_document` directly from the MCP harness with a hand-typed `content` field in OpenSpec mode. The local file is the source of truth; agent-typed content drifts and burns tokens (`openspec-aware` §2 Rule 1).
+>
+> When the LAST task of an OpenSpec idea is verified, the plugin's PostToolUse hook injects an archive reminder (`openspec-aware` §3.9) — run `openspec archive <slug> --yes`, then mirror each emitted `openspec/specs/<capability>/spec.md` back via §3.8.
+>
+> In the no-OpenSpec fallback (no slug line, or no `openspec` CLI), edit the Document content directly via the existing MCP tool with no wrapper, no local file step.
+
 ### Step 5: Start Working
 
 **Sub-agent**: checkin to the task first:

package/.next/standalone/public/chorus-plugin/skills/idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.8.0"
+  version: "0.8.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/skills/openspec-aware/SKILL.md

@@ -0,0 +1,436 @@
+---
+name: openspec-aware
+description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Claude Code. Detects 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.
+license: AGPL-3.0
+metadata:
+  author: chorus
+  version: "0.8.3"
+  category: project-management
+  mcp_server: chorus
+---
+
+# OpenSpec-aware Authoring (Claude Code plugin)
+
+This skill is a **shared sub-procedure** invoked by the Chorus stage skills (proposal, develop, yolo) whenever the user wants spec-driven authoring through the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec). It is opt-in:
+
+- 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.
+
+When you reach a point in proposal / develop / yolo where this skill is referenced, **read the value of `CHORUS_OPENSPEC_ACTIVE` from the SessionStart context** (see §1) and branch on it. Do not re-run the detection block — the SessionStart hook has already done it once for this session.
+
+---
+
+## §1. Detection — already done at SessionStart
+
+The Chorus plugin's SessionStart hook (`bin/on-session-start.sh`) computes `CHORUS_OPENSPEC_ACTIVE` once when the session opens and writes a `## OpenSpec Mode` section into the plugin's injected context. The value of `CHORUS_OPENSPEC_ACTIVE` is `1` only when **all three** of these hold:
+
+1. `CHORUS_OPENSPEC_MODE` is **not** set to `off` (explicit opt-out wins).
+2. The project root contains an `openspec/` directory (i.e. someone ran `openspec init` here).
+3. The `openspec` CLI is on `PATH`.
+
+Both signals (2) and (3) are required because the OpenSpec authoring path needs the working directory **and** the CLI — having one without the other leaves the workflow unrunnable. If signal (2) holds but (3) does not, the SessionStart hook surfaces a "OpenSpec repo detected — install with: `npm i -g @fission-ai/openspec`" hint to the user; the agent should pass this through if asked rather than silently choosing free-form.
+
+### How to read the value
+
+You should already see something like this in your context (look for the `## OpenSpec Mode` section near the top of the conversation):
+
+```
+## OpenSpec Mode
+
+CHORUS_OPENSPEC_ACTIVE=1 (openspec/ directory + openspec CLI both present)
+```
+
+or:
+
+```
+## OpenSpec Mode
+
+CHORUS_OPENSPEC_ACTIVE=0 (no openspec/ directory at /path/to/repo/openspec)
+```
+
+Branch:
+
+- `CHORUS_OPENSPEC_ACTIVE=1` → follow §3 (OpenSpec authoring).
+- `CHORUS_OPENSPEC_ACTIVE=0` → return to the calling skill's free-form path. **Do not** scaffold `openspec/changes/`. **Do not** add the slug line to the proposal description.
+
+### Manual fallback
+
+If you're in a sub-shell, sub-agent, or session that did not see SessionStart context (e.g. you were spawned mid-session and the parent's context was not forwarded), reconstruct the value yourself with the same three checks:
+
+```bash
+if [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
+  CHORUS_OPENSPEC_ACTIVE=0
+elif [ ! -d "${CLAUDE_PROJECT_DIR:-$PWD}/openspec" ]; then
+  CHORUS_OPENSPEC_ACTIVE=0
+elif ! openspec --version >/dev/null 2>&1; then
+  CHORUS_OPENSPEC_ACTIVE=0
+else
+  CHORUS_OPENSPEC_ACTIVE=1
+fi
+```
+
+Use this only when SessionStart context is genuinely unavailable — duplicating the detection is wasteful when the hook already computed it.
+
+---
+
+## §2. ⛔ Two non-negotiable rules
+
+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
+
+Document/draft mirror calls (`chorus_pm_add_document_draft`, `chorus_pm_update_document_draft`, `chorus_pm_update_document`) **MUST** go through:
+
+```
+chorus-api.sh mcp-tool <tool_name> "$PAYLOAD"
+```
+
+`chorus-api.sh` is on `PATH` — call it by name.
+
+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:
+
+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.
+
+### Rule 2 — Halt on error via `chorus_check_response`
+
+Every wrapper call must check three signals: wrapper exit code, `"error":` in body, empty body. Bare `RC=$?` is **insufficient** — the wrapper exits 0 on HTTP 401 (auth failure) with empty body, so a single-signal check silently misses the most common runtime failure. See §6 for the helper definition.
+
+---
+
+## §3. OpenSpec mode authoring
+
+### 3.1 Pick a slug
+
+`openspec/changes/<slug>/` is the local change folder. The slug must be:
+
+- kebab-case (`add-export-csv`, not `addExportCsv` or `add_export_csv`),
+- derived from the source Idea title,
+- unique within `openspec/changes/`.
+
+Record it for later steps:
+
+```bash
+SLUG="add-export-csv"
+```
+
+### 3.2 Scaffold the change folder
+
+```bash
+openspec new change "$SLUG" --description "<one-line idea summary>"
+```
+
+This creates `openspec/changes/$SLUG/` with `README.md` and `.openspec.yaml`. Then author by hand:
+
+| Local file | Purpose | Mirror as `Document.type` |
+|---|---|---|
+| `proposal.md` | Why + What Changes + Capabilities + Impact | `prd` |
+| `design.md` | Architecture, contracts, risks | `tech_design` |
+| `specs/<capability>/spec.md` | Delta spec (`## ADDED Requirements` + Scenarios) | `spec` (one draft per capability) |
+| `tasks.md` | OpenSpec tasks list | _(not mirrored — Chorus task drafts are source of truth)_ |
+
+Use `openspec instructions <artifact> --change "$SLUG"` (artifacts: `proposal`, `specs`, `design`, `tasks`) for templates.
+
+### 3.3 Spec file shape (verified against `openspec instructions specs`)
+
+A delta spec lists one or more block headers — `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements` — and within each, `### Requirement:` entries. Mix freely in the same file; only include the blocks you actually need.
+
+#### `## ADDED Requirements`
+
+Append a brand-new Requirement to the long-term spec.
+
+```
+## ADDED Requirements
+
+### Requirement: <name>
+<requirement text — use SHALL / MUST for normative behavior>
+
+#### Scenario: <name>
+- **WHEN** <condition>
+- **THEN** <expected outcome>
+```
+
+#### `## MODIFIED Requirements`
+
+**Whole-block replacement, not merge.** Whatever you write here completely replaces the existing same-named Requirement in the long-term spec — title, description, and *all* scenarios. Half-writing it deletes the rest.
+
+```
+## MODIFIED Requirements
+
+### Requirement: <existing name>
+<full updated requirement text>
+
+#### Scenario: <name>
+- **WHEN** <condition>
+- **THEN** <expected outcome>
+
+#### Scenario: <other name>
+- **WHEN** <condition>
+- **THEN** <expected outcome>
+```
+
+Always include every scenario you want the post-archive spec to have, even ones that were already present and unchanged.
+
+#### `## REMOVED Requirements`
+
+Delete a Requirement from the long-term spec. The block under the heading is just the requirement name(s) you're removing — no scenarios needed.
+
+```
+## REMOVED Requirements
+
+### Requirement: <existing name>
+```
+
+#### `## RENAMED Requirements`
+
+Rename a Requirement's title. Body and scenarios are preserved as-is in the long-term spec; use `MODIFIED` instead if you need to change anything besides the title.
+
+```
+## RENAMED Requirements
+
+### Requirement: <old name> -> <new name>
+```
+
+**Critical formatting rules (verified):**
+
+- Scenarios MUST use **exactly 4 hashtags** (`#### Scenario:`). 3 hashtags or a bullet list silently fail validation.
+- Every `### Requirement:` under `ADDED` or `MODIFIED` MUST have at least one `#### Scenario:`.
+- `MODIFIED` blocks MUST include the **full updated content** — they overwrite, not patch.
+- Use `SHALL` / `MUST` for normative requirements; avoid `should` / `may`.
+- The merge into `openspec/specs/<capability>/spec.md` happens at `openspec archive` time (§3.9), not at proposal time. While the proposal is in flight, Chorus only sees the delta file as one `spec` Document — there is no half-merged state for the skill to reason about.
+
+Optional:
+
+```bash
+openspec validate "$SLUG"
+```
+
+### 3.4 Helper: `json_encode_file`
+
+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.
+
+```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
+}
+```
+
+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.
+
+### 3.5 Create the proposal container with the slug provenance line
+
+Use the regular `chorus_pm_create_proposal` MCP tool (no wrapper required for this single call — the description is short, the LLM-emitted version is fine). The description **must** carry exactly one line:
+
+```
+OpenSpec change slug: <slug>
+```
+
+- on its own line (no other text on that line),
+- literal prefix `OpenSpec change slug: ` (capital O, capital S, single space after colon),
+- no trailing punctuation,
+- value matches the slug passed to `openspec new change`.
+
+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
+
+> **Rule 1 reminder:** these calls go through `chorus-api.sh`, not direct MCP. The agent must not retype the document body.
+
+Define the halt-on-error helper from §6 once at the top, then run one call per file:
+
+```bash
+# chorus-api.sh is on PATH — no absolute path needed.
+# PRD draft
+CONTENT=$(json_encode_file "openspec/changes/$SLUG/proposal.md")
+PAYLOAD=$(cat <<JSON
+{
+  "proposalUuid": "$PROPOSAL_UUID",
+  "type": "prd",
+  "title": "PRD: $HUMAN_TITLE",
+  "content": $CONTENT
+}
+JSON
+)
+RESULT=$(chorus-api.sh mcp-tool chorus_pm_add_document_draft "$PAYLOAD")
+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.
+
+### 3.7 Editing a draft after the first mirror
+
+Local file changes propagate via `chorus_pm_update_document_draft` — same wrapper, same `json_encode_file`, same halt check.
+
+```bash
+CONTENT=$(json_encode_file "openspec/changes/$SLUG/proposal.md")
+PAYLOAD=$(cat <<JSON
+{
+  "proposalUuid": "$PROPOSAL_UUID",
+  "draftUuid": "$PRD_DRAFT_UUID",
+  "content": $CONTENT
+}
+JSON
+)
+RESULT=$(chorus-api.sh mcp-tool chorus_pm_update_document_draft "$PAYLOAD")
+RC=$?
+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`:
+
+```bash
+CONTENT=$(json_encode_file "openspec/changes/$SLUG/specs/<capability>/spec.md")
+PAYLOAD=$(cat <<JSON
+{
+  "documentUuid": "$SPEC_DOCUMENT_UUID",
+  "content": $CONTENT
+}
+JSON
+)
+RESULT=$(chorus-api.sh mcp-tool chorus_pm_update_document "$PAYLOAD")
+RC=$?
+chorus_check_response "chorus_pm_update_document" "$RC" "$RESULT"
+```
+
+To re-derive `$SPEC_DOCUMENT_UUID` from a fresh shell, look it up via `chorus_get_documents` for the proposal's project and match by `title` + `type`. Re-derive `$SLUG` by grepping the proposal's `description` for `^OpenSpec change slug: `.
+
+### 3.9 Archive after the last task is verified
+
+When the **LAST** task of an OpenSpec-mode idea is admin-verified via `chorus_admin_verify_task`, the plugin's PostToolUse hook (`bin/on-post-verify-task.sh`) injects an `additionalContext` reminder containing the literal substring `openspec archive <slug>` so you can act without re-reading the slug.
+
+The hook is read-only; you (the agent) perform the archive:
+
+1. **Run archive locally.** Use `--yes` for non-interactive mode. Do NOT pass `--skip-specs` (defeats the mirror-back) or `--no-validate` (lets malformed deltas corrupt cumulative specs).
+
+   ```bash
+   openspec archive "$SLUG" --yes
+   ```
+
+   This moves `openspec/changes/$SLUG/` under `openspec/changes/archive/<date>-<slug>/` and emits/updates `openspec/specs/<capability>/spec.md` for each capability. (Run `openspec archive --help` against your installed version to confirm the current flag set — flags can drift between releases.)
+
+2. **Mirror each updated `openspec/specs/<capability>/spec.md` back** to the matching post-approval Chorus Document (§3.8 contract). `chorus_get_documents` only supports `projectUuid` + `type` server-side filters; filter by title client-side. One `chorus_pm_update_document` call per capability.
+
+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.** List `openspec/specs/<capability>/spec.md` files and verify they round-trip byte-equal (modulo trailing newline) with their Chorus Document counterparts.
+
+**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.
+
+---
+
+## §4. Fallback authoring (no openspec)
+
+When detection puts the agent in fallback mode (`CHORUS_OPENSPEC_ACTIVE=0`), this skill is a **no-op**. Return to the calling skill's free-form path:
+
+- No `openspec/changes/` folder is created or referenced.
+- No `OpenSpec change slug: …` line is added to the proposal description.
+- Document drafts are authored via direct MCP `chorus_pm_add_document_draft` calls with inline `content` — same as before this skill existed.
+- Rule 1 (wrapper-only mirror) does not apply — there is no local file source of truth.
+- The §3.9 archive hook does nothing (no slug → silent exit).
+
+---
+
+## §5. Document type mapping (reference table)
+
+| Local file | Chorus `Document.type` | Mirrored? |
+|---|---|---|
+| `openspec/changes/<slug>/proposal.md` | `prd` | yes |
+| `openspec/changes/<slug>/design.md` | `tech_design` | yes |
+| `openspec/changes/<slug>/specs/<capability>/spec.md` | `spec` | yes (one draft per capability) |
+| `openspec/changes/<slug>/tasks.md` | _(not mapped)_ | **no** — Chorus task drafts are source of truth |
+
+`prd`, `tech_design`, `spec` are pre-existing valid `Document.type` values — no schema change required.
+
+---
+
+## §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.
+
+Define this helper **once** at the top of the authoring session and use it after every wrapper call:
+
+```bash
+chorus_check_response() {
+  local _tool="$1"
+  local _rc="$2"
+  local _body="$3"
+  local _has_error=0
+  local _is_empty=0
+
+  local _trimmed
+  _trimmed=$(printf '%s' "$_body" | tr -d ' \t\n\r')
+  [ -z "$_trimmed" ] && _is_empty=1
+
+  if [ "$_is_empty" -eq 0 ]; then
+    if command -v jq >/dev/null 2>&1; then
+      if printf '%s' "$_body" | jq -e 'try ([.. | objects | has("error")] | any) catch false' >/dev/null 2>&1; then
+        _has_error=1
+      fi
+    else
+      printf '%s' "$_body" | grep -qE '"error"[[:space:]]*:' && _has_error=1
+    fi
+  fi
+
+  if [ "$_rc" -ne 0 ] || [ "$_has_error" -eq 1 ] || [ "$_is_empty" -eq 1 ]; then
+    echo "ERROR: $_tool failed (exit=$_rc, error_in_body=$_has_error, empty_body=$_is_empty)" >&2
+    echo "Output: $_body" >&2
+    [ "$_rc" -ne 0 ] && exit "$_rc" || exit 1
+  fi
+}
+```
+
+**Anti-patterns** — do **not**:
+
+- Collapse to `|| true`.
+- Redirect stderr to `/dev/null`.
+- Bury the wrapper call inside a pipeline (masks `$?`).
+- 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:**
+
+```bash
+RESULT=$(chorus-api.sh mcp-tool <tool_name> "$PAYLOAD")
+RC=$?
+chorus_check_response "<tool_name>" "$RC" "$RESULT"
+# ...if we reach here, the call succeeded; parse RESULT and continue.
+```
+
+This is project-wide policy: no silent errors.
+
+---
+
+## §7. Quick reference checklist
+
+When invoked from a stage skill (proposal / develop / yolo):
+
+1. Read `CHORUS_OPENSPEC_ACTIVE` from the `## OpenSpec Mode` section in the SessionStart context (§1). If it isn't there, fall back to the manual probe in §1.
+2. If `CHORUS_OPENSPEC_ACTIVE=0` → return to caller's free-form path (§4).
+3. Otherwise:
+   a. Pick `$SLUG` (§3.1).
+   b. `openspec new change "$SLUG"` (§3.2).
+   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. Define `json_encode_file`, `chorus_check_response` helpers. (`chorus-api.sh` is on PATH — no `$API` variable needed.)
+   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`.
+   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 → hook fires → run §3.9 archive flow.

package/.next/standalone/public/chorus-plugin/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.8.0"
+  version: "0.8.3"
   category: project-management
   mcp_server: chorus
 ---
@@ -84,6 +84,16 @@ chorus_pm_create_proposal({
 
 **Multiple Ideas:** You can combine multiple ideas into one proposal by passing multiple UUIDs in `inputUuids`.
 
+### Step 1.5: Detect OpenSpec mode
+
+Before authoring document drafts, **load the `openspec-aware` skill at `.claude/skills/openspec-aware/SKILL.md`** and run its §1 detection contract. Branch on the result:
+
+- **`CHORUS_OPENSPEC_ACTIVE=1`** → 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.
+
+- **`CHORUS_OPENSPEC_ACTIVE=0`** (CLI absent 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`.
+
 ### Step 2: Add Document Drafts
 
 Add document drafts one at a time:

package/.next/standalone/public/chorus-plugin/skills/quick-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quick-dev
-version: 0.8.0
+version: 0.8.3
 description: Quick Task workflow — skip Idea→Proposal, create tasks directly, execute, and verify.
 ---
 

package/.next/standalone/public/chorus-plugin/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.8.0"
+  version: "0.8.3"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/chorus-plugin/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.8.0"
+  version: "0.8.3"
   category: project-management
   mcp_server: chorus
 ---
@@ -181,18 +181,40 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
 #### Step 1.4: Create Proposal
 
-1. **Create empty container:**
+1. **Detect OpenSpec mode.** Load the `openspec-aware` skill at `.claude/skills/openspec-aware/SKILL.md` and run its §1 detection contract. The result determines how the rest of this step authors documents:
+
+   - `CHORUS_OPENSPEC_ACTIVE=1` → spec-driven branch (sub-step 2a below).
+   - `CHORUS_OPENSPEC_ACTIVE=0` → free-form branch (sub-step 2b below).
+
+   This is mandatory — yolo runs unattended, so silently picking the wrong mode is exactly the failure scenario the detection contract exists to prevent.
+
+2. **Create the empty proposal container.** In OpenSpec mode, the `description` MUST contain the literal line `OpenSpec change slug: <slug>` (use the `$SLUG` you'll pick in 2a); in free-form mode, omit that line.
+
    ```
    chorus_pm_create_proposal({
      projectUuid: "<project-uuid>",
      title: "<feature name>",
-     description: "<summary of what the proposal covers>",
+     description: "<summary>\n\nOpenSpec change slug: <slug>",   // OpenSpec mode
+     // description: "<summary>",                                 // free-form mode
      inputType: "idea",
      inputUuids: ["<idea-uuid>"]
    })
    ```
 
-2. **Add tech design document draft:**
+   Then branch:
+
+   **2a. OpenSpec mode (`CHORUS_OPENSPEC_ACTIVE=1`).** 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 `$API`, `json_encode_file`, `chorus_check_response` helpers (§3.4, §6).
+   - Mirror each local file via `"$API" mcp-tool chorus_pm_add_document_draft "$PAYLOAD"` (§3.6) — 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.
+
+   Then continue to step 3 (task drafts).
+
+   **2b. Free-form mode (`CHORUS_OPENSPEC_ACTIVE=0`).** Add a tech design document draft directly via MCP, content authored inline:
+
    ```
    chorus_pm_add_document_draft({
      proposalUuid: "<proposal-uuid>",

package/README.md

@@ -26,15 +26,18 @@ Inspired by the **[AI-DLC (AI-Driven Development Lifecycle)](https://aws.amazon.
 ```
 Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Verify ──> Done
   ^          ^               ^                     ^          ^         ^
-Human     PM Agent       PM Agent              Dev Agent    Admin     Admin
-creates   analyzes       drafts PRD            codes &      reviews   closes
-          & plans        & tasks               reports      & verifies
+Human     idea:write     proposal:write         task:write   *:admin    *:admin
+creates   + elaborate    + drafts                + reports   + verifies + closes
 ```
 
+The labels under each stage are the **permissions** an actor needs at that stage — granted to a human, an Agent (preset or Custom), or both. There are no fixed roles; any combination of the 5 × 3 permission matrix is possible. See [`docs/PERMISSIONS.md`](docs/PERMISSIONS.md).
+
 ---
 
 ## What's New
 
+**[v0.8.0](https://chorus-ai.dev/blog/chorus-v0.8.0-release/)** — OpenSpec-aware mode (Claude Code): auto-activates when an `openspec/` directory and the `openspec` CLI are both present, adds `/opsx/{explore,propose,apply,archive}` and a post-verify archive-trigger hook.
+
 **[v0.7.0](https://chorus-ai.dev/blog/chorus-v0.7.0-release/)** — Fine-grained agent permissions: 5 resources × 3 actions grid replaces the PM/Developer/Admin three-way choice, with presets + a Custom option for free combination.
 
 **[v0.6.7](https://chorus-ai.dev/blog/chorus-v0.6.7-release/)** — Chorus plugin for Codex CLI (one-command installer), workspace picker when one email belongs to multiple Companies, per-client connect guides.
@@ -195,8 +198,9 @@ A Cmd+K command palette for searching across all 6 entity types (Tasks, Ideas, P
 └──────────────────────────────────────────────────────────────────┘
      ↑              ↑              ↑              ↑
   Agent w/      Agent w/       Agent w/         Human
-  PM perms   Developer perms  Admin perms     (Browser)
-   (LLM)         (LLM)          (LLM)
+  idea+proposal  task:write    *:admin perms   (Browser)
+   :write perms    perms      (proxy approval)
+   (LLM)          (LLM)         (LLM)
                      │
           ┌──────────▼──────────┐   ┌─────────────────────┐
           │  PostgreSQL + Prisma │   │  Redis (optional)   │
@@ -317,8 +321,29 @@ Create API Keys in the Web UI under **Settings → Agents → Create API Key**.
 
 | Method | Location | Use Case |
 |--------|----------|----------|
-| **Plugin-embedded** | `public/chorus-plugin/skills/chorus/` | Claude Code + Plugin, automated Sessions |
-| **Standalone** | `public/skill/` (served at `/skill/`) | Any Agent, manual Session management |
+| **Plugin-embedded (Claude Code)** | `public/chorus-plugin/skills/` | Claude Code + Chorus plugin, automated Sessions and lifecycle hooks |
+| **Plugin-embedded (Codex CLI)** | `plugins/chorus/skills/` | Codex CLI + Chorus plugin, ported skills with `$`-prefixed slash commands |
+| **Standalone** | `public/skill/` (served at `/skill/`) | Any other MCP-capable Agent (Cursor, Continue, custom), manual Session management |
+
+### OpenSpec mode (opt-in, plugin 0.8.1+)
+
+PM agents that have the [OpenSpec](https://github.com/Fission-AI/OpenSpec)
+CLI installed can author proposals in a structured `proposal.md` +
+`design.md` + `specs/<capability>/spec.md` layout. Local files are the
+working copy and Chorus `documentDrafts` are the mirror; reviewers see a
+predictable shape (`## ADDED Requirements`, `### Requirement:`,
+`#### Scenario:`) instead of free-form Markdown. A PostToolUse hook on
+`chorus_admin_verify_task` injects an `openspec archive <slug>` reminder
+when the last task of an OpenSpec idea is verified, so finalized specs
+are merged into the long-term spec set right after sign-off. The mode is
+strictly opt-in: when `openspec` is not installed, behavior is unchanged.
+Master switch on Claude Code is `enableOpenSpec` (plugin userConfig,
+default `true`); both clients also honor `CHORUS_OPENSPEC_MODE=off`. No
+new MCP tools or schema changes ship in this mode; the canonical skill
+reuses the existing `chorus_pm_*` draft and document tools, with mirror
+calls routed through the `chorus-api.sh` wrapper to keep multi-thousand-
+line markdown out of LLM context. See
+[OPENSPEC_MODE.md](docs/OPENSPEC_MODE.md) for the full guide.
 
 ---
 
@@ -329,7 +354,9 @@ Create API Keys in the Web UI under **Settings → Agents → Create API Key**.
 | [PRD](docs/PRD_Chorus.md) | Product Requirements Document |
 | [Architecture](docs/ARCHITECTURE.md) | Technical Architecture Document |
 | [MCP Tools](docs/MCP_TOOLS.md) | MCP Tools Reference |
+| [Permissions](docs/PERMISSIONS.md) | Agent permission model (5 × 3 matrix, presets, Custom mode) |
 | [Chorus Plugin](docs/chorus-plugin.md) | Plugin Design & Hook Documentation |
+| [OpenSpec Mode](docs/OPENSPEC_MODE.md) | Opt-in OpenSpec authoring mode for PM agents (Plugin 0.8.1+) |
 | [Search](docs/SEARCH.md) | Global Search Technical Design |
 | [AI-DLC Gap Analysis](docs/AIDLC_GAP_ANALYSIS.md) | AI-DLC Methodology Gap Analysis |
 | [AIG Implementation Plan](docs/CHORUS_AIG_PLAN.md) | Agent transparency roadmap |