OpenSpec mode

OpenSpec mode is an opt-in authoring style for the Chorus plugin on Claude Code and Codex. When it is active, the AI-DLC workflow still runs exactly as usual, but proposal authoring changes shape: instead of free-form Markdown typed straight into Chorus, the agent writes structured files on disk with the openspec CLI and mirrors them into your proposal’s document drafts. The local files are the working copy; the Chorus drafts are a faithful mirror your reviewers read on the proposal page.

When OpenSpec is not present, nothing changes — the plugin authors free-form drafts the way it always has. OpenSpec mode ships in the Claude Code and Codex plugins only; the standalone skill distribution does not support it.

When it activates

Detection runs once, when the session starts. All three signals must hold for OpenSpec mode to turn on:

1. CHORUS_OPENSPEC_MODE is not set to off — an explicit opt-out always wins.
2. An openspec/ directory exists at the repository root — the “this repo uses OpenSpec” signal, created by openspec init.
3. The openspec CLI is on your PATH — the mode needs the CLI to scaffold, validate, and archive changes, so the directory alone is not enough.

If all three hold, the connection toast reports that the mode is on:

Chorus connected at <your Chorus URL> (OpenSpec Enabled)

If the openspec/ directory is present but the CLI is missing, the toast surfaces an install hint instead, and the agent stays on the free-form path:

Chorus connected at <your Chorus URL> (OpenSpec repo detected — install with: npm i -g @fission-ai/openspec)

Install and initialize

OpenSpec is a Node CLI from Fission AI. Install it globally, then initialize the repository where the agent authors proposals:

npm install -g @fission-ai/openspec
openspec init

openspec init creates the openspec/ working directory (changes/, specs/, config, and instruction files). Restart the agent session afterward so detection picks up both new signals — the openspec/ directory and the CLI.

Installing the plugin itself is covered per runtime on the Claude Code and Codex pages.

What changes in proposal, develop, and yolo

With the mode active, the proposal, develop, and yolo skills author a change on disk under a kebab-case slug and mirror three file types into your Chorus proposal’s document drafts:

| On-disk file | Mirrored as document | | --- | --- | | openspec/changes/<slug>/proposal.md | PRD | | openspec/changes/<slug>/design.md | Tech design | | openspec/changes/<slug>/specs/<capability>/spec.md | Spec (one per capability) |

openspec/changes/<slug>/tasks.md is not mirrored: Chorus task drafts are the source of truth for tasks, so the OpenSpec task list is left on disk.

So a later run can recover the change, the proposal description carries one exact line:

OpenSpec change slug: <slug>

The mirror is byte-faithful — the plugin streams each file’s bytes into the draft rather than re-typing the content through the model, which keeps the local file and the Chorus draft identical. You do not run this yourself; the plugin’s skill handles it. The exact wrapper contract (the chorus-api.sh document-mirror flow, its halt-on-error rules, and post-approval re-sync) lives in the authoritative sources rather than being reproduced here — see docs/OPENSPEC_MODE.md and the plugin skill public/chorus-plugin/skills/openspec-aware/SKILL.md.

When openspec archive runs

openspec archive is deferred to the very end of the change. After the last task of the change is verified, the plugin reminds the agent to run:

openspec archive <slug>

Archiving moves the change out of openspec/changes/ and merges its spec deltas into the long-term specs under openspec/specs/. The plugin then mirrors the updated openspec/specs/<capability>/spec.md files back into the matching Chorus documents. Until that point the change stays in flight and Chorus only ever sees the delta spec, so there is no half-merged state to reason about.

Opt out

Two switches, in precedence order:

1. enableOpenSpec userConfig toggle (Claude Code plugin only, default on). Set it to off in the plugin’s install configuration to disable the mode plugin-wide, including the archive reminder. This is equivalent to OpenSpec being uninstalled.

2. CHORUS_OPENSPEC_MODE=off environment variable (both plugins). A per-shell, CI-friendly opt-out that forces free-form mode even when the openspec/ directory and the CLI are both present:

   export CHORUS_OPENSPEC_MODE=off

The Codex plugin has no userConfig surface, so only the environment variable applies there. Either way, opting out leaves any existing openspec/ directory on disk untouched and adds no slug line to new proposals — behavior is identical to a host without OpenSpec installed.

For agents

• Triggers. The proposal, develop, and yolo skills read CHORUS_OPENSPEC_ACTIVE from the ## OpenSpec Mode section of the SessionStart context and branch on it — they do not re-detect. When CHORUS_OPENSPEC_ACTIVE=1, author on disk and mirror; when 0, follow the free-form path. After the last task of the change is verified, a PostToolUse hook injects an openspec archive <slug> reminder.
• Constraints. Every document-draft mirror call must go through the plugin wrapper (chorus-api.sh mcp-tool on Claude Code, chorus-mcp-call.sh on Codex) with file bytes encoded verbatim — never re-type document content inline, and halt on any wrapper error. Do not mirror tasks.md. The proposal description must carry the exact line OpenSpec change slug: <slug>. When the mode is off, do not scaffold openspec/changes/ and do not add the slug line. The standalone public/skill/ distribution does not support OpenSpec mode.
• Cite. docs/OPENSPEC_MODE.md (user-facing summary and detection contract), public/chorus-plugin/skills/openspec-aware/SKILL.md (Claude Code authoritative skill), and plugins/chorus/skills/openspec-aware/SKILL.md (Codex authoritative skill).