OpenSpec 模式

OpenSpec 模式是 Chorus 插件在 Claude Code 与 Codex 上的一种可选编写方式。开启后， AI-DLC 工作流照常运行，只是方案编写的形态发生了变化：不再把自由格式的 Markdown 直接敲进 Chorus，而是由 Agent 用 openspec CLI 在磁盘上编写结构化文件，再把它们镜像进方案的文档草稿。磁盘上的文件是工作副本，Chorus 草稿是审阅者在方案页面上阅读的忠实镜像。

如果本机没有 OpenSpec，则一切不变，插件仍按原有方式编写自由格式草稿。OpenSpec 模式仅随 Claude Code 与 Codex 插件提供；独立技能分发包不支持它。

何时激活

检测在会话启动时进行一次。以下三个信号必须全部成立，OpenSpec 模式才会开启：

CHORUS_OPENSPEC_MODE 未设为 off，显式退出始终优先。
仓库根目录存在 openspec/ 目录，这是「本仓库使用 OpenSpec」的信号，由 openspec init 创建。
openspec CLI 位于你的 PATH 中，该模式需要 CLI 来搭建脚手架、校验与归档变更，仅有目录还不够。

三者全部成立时，连接提示会显示模式已开启：

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

若 openspec/ 目录存在但缺少 CLI，提示会改为给出安装提示，Agent 继续走自由格式路径：

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

安装与初始化

OpenSpec 是 Fission AI 提供的一个 Node CLI。先全局安装，再在 Agent 编写方案的仓库里初始化：

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

openspec init 会创建 openspec/ 工作目录（changes/、specs/、配置及说明文件）。之后请重启 Agent 会话，让检测重新识别这两个新信号：openspec/ 目录与 CLI。

插件本身的安装按运行时分别记录在 Claude Code 与 Codex 页面。

proposal、develop、yolo 中的变化

模式开启后，proposal、develop、yolo 技能会以一个 kebab-case slug 在磁盘上编写变更，并把三类文件镜像进 Chorus 方案的文档草稿：

| 磁盘上的文件 | 镜像为文档 | | --- | --- | | openspec/changes/<slug>/proposal.md | PRD | | openspec/changes/<slug>/design.md | 技术设计 | | openspec/changes/<slug>/specs/<capability>/spec.md | 规格（每个能力一份） |

openspec/changes/<slug>/tasks.md 不被镜像：Chorus 的任务草稿才是任务的唯一真实来源，因此 OpenSpec 的任务清单留在磁盘上。

为了让后续运行能恢复该变更，方案描述里会带上一行精确内容：

OpenSpec change slug: <slug>

镜像是逐字节忠实的，插件把每个文件的字节流写入草稿，而不是让模型重新逐字敲一遍内容，从而保证磁盘文件与 Chorus 草稿完全一致。你无需自己执行，这由插件的技能完成。具体的封装脚本契约（ chorus-api.sh 文档镜像流程、其遇错即停规则，以及审批后的再同步）保留在权威来源中，本页不再复述，参见 docs/OPENSPEC_MODE.md 与插件技能 public/chorus-plugin/skills/openspec-aware/SKILL.md。

`openspec archive` 何时运行

openspec archive 被推迟到变更的最后一步。当该变更的最后一个任务通过验证后，插件会提醒 Agent 运行：

openspec archive <slug>

归档会把该变更移出 openspec/changes/，并把其规格增量合并进 openspec/specs/ 下的长期规格。随后插件会把更新后的 openspec/specs/<capability>/spec.md 文件反向镜像回对应的 Chorus 文档，在此之前变更一直在进行中，Chorus 只会看到增量规格，因此不存在需要处理的半合并状态。

如何退出

两个开关，按优先级排列：

enableOpenSpec userConfig 开关（仅 Claude Code 插件，默认开启）。在插件的安装配置中把它关掉，即可在插件层面禁用该模式，包括归档提醒。这等同于未安装 OpenSpec。
CHORUS_OPENSPEC_MODE=off 环境变量（两个插件均适用）。这是一个按 shell 生效、对 CI 友好的退出方式；即便 openspec/ 目录与 CLI 都存在，也会强制走自由格式模式：
Terminal window
```
export CHORUS_OPENSPEC_MODE=off
```

Codex 插件没有 userConfig 界面，因此那里只有环境变量生效。无论用哪种方式退出，磁盘上已有的 openspec/ 目录都保持不动，新方案也不会加上 slug 行，行为与未安装 OpenSpec 的主机完全一致。

面向 Agent

触发条件。 proposal、develop、yolo 技能从 SessionStart 上下文的 ## OpenSpec Mode 小节读取 CHORUS_OPENSPEC_ACTIVE 并据此分支，它们不重新检测。当 CHORUS_OPENSPEC_ACTIVE=1 时，在磁盘上编写并镜像；为 0 时走自由格式路径。变更的最后一个任务通过验证后，一个 PostToolUse 钩子会注入 openspec archive <slug> 提醒。
约束。 每一次文档草稿的镜像调用都必须经由插件封装脚本（Claude Code 上是 chorus-api.sh mcp-tool，Codex 上是 chorus-mcp-call.sh），并逐字节地编码文件内容，切勿把文档内容内联重敲，且遇到任何封装脚本错误都要停止。不要镜像 tasks.md。方案描述必须带上精确的 OpenSpec change slug: <slug> 一行。模式关闭时，不要搭建 openspec/changes/，也不要加 slug 行。独立的 public/skill/ 分发包不支持 OpenSpec 模式。
引用来源。 docs/OPENSPEC_MODE.md（面向用户的概述与检测契约）、 public/chorus-plugin/skills/openspec-aware/SKILL.md（Claude Code 权威技能）、以及 plugins/chorus/skills/openspec-aware/SKILL.md（Codex 权威技能）。