Openspec Aware

OpenSpec-aware Authoring (Hermes plugin)

This skill is a shared sub-procedure invoked by the Chorus stage skills (proposal, develop, yolo) when the resolved spec mode is a usable OpenSpec — spec-driven authoring through the OpenSpec CLI:

• 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 exists at the project root, and the openspec CLI is on PATH.
• Otherwise the calling skill follows the resolved mode — spec-lite (the default when OpenSpec isn't usable) or free-form (CHORUS_SPEC_MODE=off).

See also — spec-lite (the lightweight fallback): OpenSpec (this skill) stays the default whenever 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 skill_view("chorus:spec-lite").

When you reach a point in proposal / develop / yolo where this skill is referenced, read the resolved mode from the ## Spec Mode section (see §1) and branch on it. Do not re-derive the detection — the Chorus Hermes plugin's pre_llm_call session-start check-in has already resolved it once for this session.

Hermes specifics: the document-mirror transport is the chorus CLI (chorus mcp call … --arg-file content=<file>, §2 Rule 1), run through the terminal tool. When chorus is not on PATH, the fallback is the native Chorus MCP tool (mcp__chorus__chorus_pm_add_document_draft, mcp__chorus__chorus_pm_update_document_draft, mcp__chorus__chorus_pm_update_document) with content read from the file via read_file. There is no bundled shell wrapper on Hermes. The helper snippets below are Bash; run multi-line blocks under bash -lc (or save them as a .sh script with a Bash shebang) if the terminal shell is not Bash.

§1. Spec mode — already resolved at session start

The Chorus Hermes plugin's pre_llm_call hook resolves the spec mode on the first turn of each session (and again after /reset or context compression) via its spec_mode.py — the single source of truth, a Python port of the canonical resolver with the same rules — and writes a ## Spec Mode section into the injected context stating CHORUS_SPEC_MODE=<lite|openspec|off>; when the resolved mode is a usable OpenSpec it also carries a CHORUS_OPENSPEC_ACTIVE=1 line. That line is present only when CHORUS_SPEC_MODE is openspec or unset, and all three of these hold:

1. OpenSpec is not disabled (CHORUS_OPENSPEC_MODE not off, CHORUS_ENABLE_OPENSPEC not false).
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. If signal (2) holds but (3) does not, the ## Spec Mode section carries an install hint (npm i -g @fission-ai/openspec); pass it through if asked.

How to read the value

You should already see something like this in your context (look for the ## Spec Mode section near the top of the conversation):

## 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 → follow §3 (OpenSpec authoring).
• No CHORUS_OPENSPEC_ACTIVE=1 line → this skill is a no-op; return to the caller, which follows the resolved CHORUS_SPEC_MODE (spec-lite or free-form). Do not scaffold openspec/changes/. Do not add the slug line to the proposal description.

If the ## Spec Mode section shows an explicit CHORUS_SPEC_MODE=openspec that cannot be honored (OpenSpec disabled or not installed — it carries a config-conflict / not-installed reason and no CHORUS_OPENSPEC_ACTIVE=1 line), the caller MUST halt and surface it — do not silently fall back.

Manual fallback

The mode is resolved by the Chorus Hermes plugin (spec_mode.py) at session start — there is no resolver for you to source, and you must not hand-roll the rule (a hand-rolled OpenSpec-only check ignores CHORUS_SPEC_MODE and the lite/off cases). If the ## Spec Mode section is genuinely absent:

• You are a delegate_task child (children start with an isolated context): the parent must pass the resolved ## Spec Mode lines verbatim in your context. If it did not, report back to the parent that the spec mode is missing and stop, rather than guessing.
• Otherwise (e.g. the checkin/connection failed): set CHORUS_SPEC_MODE explicitly (lite | openspec | off) and start a fresh session (/reset, or restart hermes gateway for Chorus-woken sessions) so the plugin re-resolves it — rather than guessing.

§2. ⛔ Two non-negotiable rules

Both are enforced at review time. Both have caused incidents in past releases.

Rule 1 — Fill content from the file (CLI preferred, native-tool 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 fill the content field from the local file's bytes, never from a hand-typed body. Calling these tools directly from the native MCP tools with a hand-typed content field is a protocol violation for OpenSpec mode and will fail review. Use whichever transport is available, preferred first:

• 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, so no encoding helper is needed. 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.
• Primary transport runs through terminal. The chorus CLI is a Node binary on PATH; run it with the Hermes terminal tool so the file bytes never pass through model context.
• Fallback — the native Chorus MCP tool, when chorus is not on PATH: read the file with read_file and call mcp__chorus__chorus_pm_add_document_draft / mcp__chorus__chorus_pm_update_document_draft / mcp__chorus__chorus_pm_update_document with content set to the file's text exactly as read — no edits, no reflow, no "fixes", and none of any line-number prefix the reader adds for display. This is a degraded path: the body does pass through model context (token cost) and loses the byte-exact guarantee, so after each call spot-check the round-trip (§3.9 step 4) and prefer installing the CLI (npm install -g @chorus-aidlc/chorus) before any multi-document mirror. There is no bundled shell wrapper on Hermes.

New to the chorus CLI? See skill_view("chorus:chorus-cli") 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. On Hermes the credentials come from the environment (CHORUS_URL, CHORUS_API_KEY) or ~/.hermes/.env; export them in the terminal command if the shell does not see them. 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.

Reasons (they are why the CLI path is preferred, and why the fallback must copy the file text verbatim):

1. Token cost. Re-typing a multi-thousand-line markdown body through the LLM burns input + output tokens for every draft. The CLI's --arg-file streams 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. The CLI's --arg-file 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 --arg-file path, never on LLM re-emission — which is why the native-tool fallback needs a round-trip spot check.
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.

Rule 2 — Halt on error via chorus_check_response

Every chorus mcp call must check three signals: exit code, "error": in body, empty body. Bare RC=$? is defense in depth only — an auth failure or a tool-level error can surface in the body rather than the exit code, so a single-signal check can silently miss the most common runtime failure. See §6 for the helper definition. On the native-tool fallback, treat any error result (or an empty/unexpected result) from the tool as a halt.

§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:

SLUG="add-export-csv"

3.2 Scaffold the change folder

openspec new change "$SLUG" --description "<one-line idea summary>"

This creates openspec/changes/$SLUG/ with README.md and .openspec.yaml. Then author by hand:

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:

openspec validate "$SLUG"

3.4 Filling the content field byte-exact

The document content must be inserted byte-for-byte from the local file — never re-typed by the LLM. Two mechanisms, preferred first:

• 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 byte-faithful, so no encoding helper is needed — pass the base JSON without a content field and let --arg-file fill it.
• Fallback — the native MCP tool (§3.6 fallback, used only when chorus is not on PATH). content is the read_file text copied verbatim; verify the round-trip afterwards.

Round-trip verification is exact: a trailing newline difference is real drift and MUST NOT be normalized or ignored.

3.5 Create the proposal container with the slug provenance line

Use the regular chorus_pm_create_proposal MCP tool (no CLI 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 (CLI primary, native-tool fallback)

Rule 1 reminder: content comes from the file's bytes, never a hand-typed body. The agent must not retype the document body.

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:

# PRD draft — --arg-file fills content byte-exact from the file; no encoding helper 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 CLI 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 CLI-result parsing in this skill.