/openspec-aware

name: openspec-aware
description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Pi. Detects the local `openspec` CLI, scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via the `chorus-mcp-call.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.16.0"
  category: project-management
  mcp_server: chorus

OpenSpec-aware Authoring (Pi 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 session_start context** (see §1) and branch on it. Do not re-run the detection block — the session_start handler has already done it once for this session.

---

§1. Detection — already done at session_start

The Chorus extension's `session_start` handler computes `CHORUS_OPENSPEC_ACTIVE` once when the session opens and writes a `## OpenSpec Mode` section into the extension'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 session_start handler 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 session_start 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:

if [ "${CHORUS_OPENSPEC_MODE:-}" = "off" ]; then
  CHORUS_OPENSPEC_ACTIVE=0
elif [ ! -d "$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 session_start 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-mcp-call.sh <tool_name> "$PAYLOAD"

`chorus-mcp-call.sh` ships with the `chorus-pi` package (declared as a `bin`). Invoke it via the `bash` tool. The extension resolves the wrapper path at startup and states it in the injected Quick Reference (line `- **OpenSpec wrapper**: … is at <PATH>`). Prefer that injected path:

CHORUS_BIN="<injected path from the Quick Reference>"   # copy from the `- **OpenSpec wrapper**` line
# …or if it wasn't injected, resolve it once:
CHORUS_BIN=$(find ~/.pi/agent/npm -path '*chorus-pi/bin/chorus-mcp-call.sh' -type f 2>/dev/null | head -1)
# for local-path installs (pi install ./packages/chorus-pi) the script lives next to the package:
CHORUS_BIN="$(dirname "$(realpath packages/chorus-pi/bin/chorus-mcp-call.sh 2>/dev/null)")/chorus-mcp-call.sh"
"$CHORUS_BIN" <tool> '<json>'

then call `"$CHORUS_BIN" <tool> '<json>'`. The bare command `chorus-mcp-call.sh` is **only** on `PATH` for npm/git installs — for a local-path install (`pi install ./packages/chorus-pi`) it is NOT linked, so always use the resolved `$CHORUS_BIN`.

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 exact byte-equality guarantee holds **only** on the wrapper path. 3. **Single source of truth.** With the wrapper, the local `openspec/ch