Openspec Aware

OpenSpec-aware Authoring (Codex 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. It is opt-in:

• 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 SPEC_MODE — spec-lite (the default when OpenSpec isn't usable) or free-form (=off).

See also — spec-lite (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 skill.

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.

Codex specifics: the preferred document-mirror transport is the chorus CLI (chorus mcp call … --arg-file content=<file>, §2 Rule 1). The bundled chorus-mcp-call.sh wrapper is the fallback when chorus is not on PATH: it is Codex's stateless MCP wrapper, located at $CHORUS_PLUGIN_DIR/hooks/chorus-mcp-call.sh after resolving $CHORUS_PLUGIN_DIR with §2.1, and is invoked as chorus-mcp-call.sh <TOOL_NAME> '<JSON_ARGUMENTS>' — no mcp-tool subcommand (unlike the Claude Code variant). The Codex port has no on-disk session state; every call is self-contained.

The helper snippets below are Bash snippets. Codex executes shell commands through the user's configured shell, which may be zsh; run multi-line helper blocks under bash -lc (or save them as a .sh script with a Bash shebang) before using json_encode_file / chorus_check_response.

§1. Detection — already done at SessionStart

The Chorus plugin's SessionStart hook (hooks/on-session-start.sh, via the shared hooks/resolve-spec-mode.sh) resolves the spec mode once when the session opens and writes a ## Spec Mode section into the developer-message context; when the resolved mode is a usable OpenSpec it also carries a CHORUS_OPENSPEC_ACTIVE=1 line. That happens 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 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 ## Spec Mode section near the top of the developer message):

## 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 SPEC_MODE (spec-lite or free-form). Do not scaffold openspec/changes/. Do not add the slug line to the proposal description.

Manual fallback

If you're in a sub-agent that did not see the ## Spec Mode context (e.g. spawned mid-session with the parent's context not forwarded), do not hand-roll the detection — source the same resolver the hook uses, so there is one computation of the mode (Codex hooks run from $PWD, which the resolver uses as PROJECT_ROOT):

# 1. Resolve $CHORUS_PLUGIN_DIR first (per §2.1). 2. Then source the shared resolver:
. "$CHORUS_PLUGIN_DIR/hooks/resolve-spec-mode.sh"
# sets SPEC_MODE (lite|openspec|off), SPEC_FAIL (non-empty ⇒ halt), CHORUS_OPENSPEC_ACTIVE (1 only for a usable openspec)

Then: if SPEC_FAIL is non-empty, halt and surface it; if CHORUS_OPENSPEC_ACTIVE=1 follow §3; otherwise no-op — return to the caller per the resolved SPEC_MODE. Never re-derive the rule inline — the hook/helper is the single source of truth. If you genuinely cannot locate the helper, set CHORUS_SPEC_MODE explicitly and re-launch rather than guessing.

§2. Wrapper setup and non-negotiable rules

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

2.1 Resolve the Codex wrapper path

Define this once before the first wrapper call. Do not require the user to add plugin scripts to PATH; Codex does not do that automatically.

resolve_chorus_plugin_dir() {
  if [[ -n "${CHORUS_PLUGIN_DIR:-}" && -x "$CHORUS_PLUGIN_DIR/hooks/chorus-mcp-call.sh" ]]; then
    printf '%s\n' "$CHORUS_PLUGIN_DIR"
    return 0
  fi
  if [[ -n "${PLUGIN_ROOT:-}" && -x "$PLUGIN_ROOT/hooks/chorus-mcp-call.sh" ]]; then
    printf '%s\n' "$PLUGIN_ROOT"
    return 0
  fi
  if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && -x "$CLAUDE_PLUGIN_ROOT/hooks/chorus-mcp-call.sh" ]]; then
    printf '%s\n' "$CLAUDE_PLUGIN_ROOT"
    return 0
  fi

  local _codex_home="${CODEX_HOME:-$HOME/.codex}"
  local _candidate
  _candidate=$(
    find "$_codex_home/plugins/cache" -path '*/hooks/chorus-mcp-call.sh' -type f 2>/dev/null | sort | tail -n 1
  )
  if [[ -n "$_candidate" ]]; then
    dirname "$(dirname "$_candidate")"
    return 0
  fi

  return 1
}

CHORUS_PLUGIN_DIR="$(resolve_chorus_plugin_dir)" || {
  echo "Unable to locate Chorus Codex plugin root; cannot call chorus-mcp-call.sh" >&2
  exit 1
}
API="$CHORUS_PLUGIN_DIR/hooks/chorus-mcp-call.sh"

Rule 1 — Fill content from the file (CLI preferred, bash-wrapper 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 Codex's MCP harness 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 — the CLI's built-in replacement for json_encode_file, so no 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.
• Fallback — the Codex chorus-mcp-call.sh wrapper, when chorus is not on PATH: build $PAYLOAD with the json_encode_file helper and call "$API" <tool_name> "$PAYLOAD" (resolve $API via §2.1; two-arg signature — no mcp-tool subcommand). Defined in the §3.6 fallback block.

New to the chorus CLI? See the chorus-cli skill 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. A daemon-woken session already has CHORUS_AGENT_PROFILE set. 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 apply to both paths):

1. Token cost. Re-typing a multi-thousand-line markdown body through the model burns input + output tokens for every draft. Both the CLI's --arg-file and the fallback's json_encode_file stream the file's bytes into the JSON string — content never enters model 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. A file-fill path (CLI --arg-file, or the fallback's jq -Rs '.') is a byte-faithful encoder: backslashes, quotes, newlines, code-fence content, zero-width chars all survive. Model 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 a file-fill path, never on model re-emission.
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 model 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 for the same wrapper-bug reason described in §6 — keep using the helper even though Codex's chorus-mcp-call.sh differs slightly in implementation from Claude Code's chorus-api.sh.

§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 model. 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 the byte-faithful replacement for json_encode_file, so on the CLI path no helper is needed — pass the base JSON without a content field and let --arg-file fill it.
• Fallback — json_encode_file (defined in the §3.6 fallback block, used only when chorus is not on PATH). With jq available it streams the file through jq -Rs '.'; the pure-shell branch matches the Codex wrapper's escaping when jq is missing.

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 wrapper required for this single call — the description is short, the model-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.