/openspec-aware-chorus

name: openspec-aware-chorus
description: OpenSpec-mode authoring for Chorus PM workflows on dsh — the default whenever OpenSpec is usable. Consumes the `## Spec Mode` block the chorus-dsh bundle injects (mode resolved once at load by `src/spec-mode.ts`), scaffolds `openspec/changes/<slug>/` on disk, and mirrors Markdown files into Chorus document drafts via `chorus mcp call --arg-file` (package-local `chorus-mcp-call.mjs` wrapper as fallback). When OpenSpec isn't usable the mode resolves to spec-lite (see `spec-lite-chorus`). Required reading for the proposal, develop, and yolo skills.
license: AGPL-3.0
metadata:
  author: chorus
  version: "0.18.1"
  category: project-management
  mcp_server: chorus

OpenSpec-aware Authoring (dsh plugin)

This skill is a **shared sub-procedure** invoked by the Chorus stage skills (proposal, develop, yolo) whenever the resolved spec mode is a usable [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) setup. It is one of the modes the chorus-dsh bundle resolves at load:

• Activates when the resolved spec mode is a **usable OpenSpec** (see §1): `CHORUS_SPEC_MODE=openspec` *or* unset, **and** `CHORUS_OPENSPEC_MODE` not `off`, an `openspec/` directory at the project root, and the `openspec` CLI on `PATH`.
• Otherwise the calling skill follows the resolved `CHORUS_SPEC_MODE` — **spec-lite** (the default when OpenSpec isn't usable) or free-form (`=off`). This skill is then a **no-op**.

> **See also — `spec-lite-chorus` (the lightweight fallback):** OpenSpec (this skill) stays the default whenever it is usable. When OpenSpec is absent or disabled — or `CHORUS_SPEC_MODE=lite` — the mode resolves to **spec-lite**: a durable local `.chorus/specs/<slug>/spec.md` (never synced) + per-change dated folders `<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs mirrored 1:1 into Chorus via the same `--arg-file` transport. See the `spec-lite-chorus` skill.

> **Tool namespace:** Chorus MCP tools are exposed under a `mcp__chorus__` prefix on dsh (e.g. `mcp__chorus__chorus_pm_create_proposal`). Bare names are used in prose for readability — prepend `mcp__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 package-local `chorus-mcp-call.mjs` wrapper (fallback) (see §2 Rule 1), which talk to the Chorus MCP endpoint over HTTP using your API key, independent of the `mcp__chorus__` namespacing.

---

§1. Detection — read the mode the bundle already resolved

> **dsh difference:** the Claude Code plugin resolves the spec mode in a SessionStart hook. dsh has no SessionStart hook, but the **chorus-dsh bundle resolves the mode once at plugin load** (`resolveSpecMode`, the single source of truth — the TS mirror of the canonical bash resolver) and both (a) injects a `## Spec Mode` block into your first-step context and (b) publishes `CHORUS_SPEC_MODE` + `CHORUS_OPENSPEC_ACTIVE` to the process environment, before the daemon-origin gate, so interactive and daemon-woken sessions inherit it. **Consume that value — do NOT re-run detection and do NOT hand-roll an OpenSpec-only check.**

The bundle marks OpenSpec active (a `CHORUS_OPENSPEC_ACTIVE=1` line + `CHORUS_SPEC_MODE=openspec`) only when `CHORUS_SPEC_MODE` is `openspec` **or unset**, **and 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 bundle's `## Spec Mode` note carries an install hint (`npm i -g @fission-ai/openspec`); pass it through if asked rather than silently choosing another mode.

How to read the value

Look for the `## Spec Mode` section near the top of your context:

## Spec Mode

CHORUS_SPEC_MODE=openspec (default — openspec/ directory + openspec CLI both present)

CHORUS_OPENSPEC_ACTIVE=1 (openspec/ directory + openspec CLI both present)

or (resolved to lite / off — no `CHORUS_OPENSPEC_ACTIVE=1` line):

## Spec Mode

CHORUS_SPEC_MODE=lite (default — OpenSpec not usable: no openspec/ directory at /path/to/repo/openspec)

Branch:

• `CHORUS_OPENSPEC_ACTIVE=1` line present (equivalently the `CHORUS_OPENSPEC_ACTIVE` env var is `1`) → follow §3 (OpenSpec authoring).
• No `CHORUS_OPENSPEC_ACTIVE=1` → this skill is a **no-op**; return to the caller, which follows the resolved `CHORUS_SPEC_MODE` (**spec-lite** — see the `spec-lite-chorus` skill — or free-form when `=off`). **Do not** scaffold `openspec/changes/`. **Do not** add the slug line to the proposal description.

Manual fallback (context genuinely absent)

If you were spawned mid-session without the `## Spec Mode` context, read the environment variables the bundle published — `CHORUS_OPENSPEC_ACTIVE` (`1` ⇒ §3) and `CHORUS_SPEC_MODE` (`lite`/`off` ⇒ no-op, caller follows that mode). **Never hand-roll an OpenSpec-only three-check that hard-codes "else free-form"** — that ignores `CHORUS_SPEC_MODE` and mis-routes a `lite` repo to free-form. Only if **both** env vars are genuinely unset (a broken/older bundle) resolve the full mode yourself: an explicit `CHORUS_SPEC_MODE` (`lite`/`openspec`/`off`) wins; otherwise OpenSpec is active iff `CHORUS_OPENSPEC_MODE` ≠ `off` **and** an `openspec/` dir is present **and** `openspec --version` succeeds, else the mode is **spec-lite** (never free-form-by-default).

# Last-resort resolution when NEITHER CHORUS_OPENSPEC_ACTIVE nor CHORUS_SPEC_MODE
# was published (broken bundle). PROJECT_DIR defaults to $PWD (dsh exports no CLAUDE_PROJECT_DIR).
PROJECT_DIR="${PWD}"
case "${CHORUS_SPEC_MODE:-}" in
  openspec|"") : ;;                       # may be