openspec-propose

---
name: openspec-propose
description: 提议新变更并一步生成所有产出物。当用户想快速描述要构建的内容并获取包含 design、specs 和 tasks、可随时进入实现的完整提案时使用。也在用户说 "openspec propose" 或 "opsx propose" 时使用。
allowed-tools: Bash(openspec-cn:*)
license: MIT
compatibility: 需要 openspec-cn CLI。
metadata:
  author: openspec
  version: "1.0"
---

提议新变更 - 创建变更并一步生成所有产出物。

**规划边界**：此工作流仅创建规划制品。选择或触发此工作流的用户请求仅授权规划，即使其中要求构建或修复某些内容。不要编辑项目代码。规划制品完成后即停止。不要在同一回复中开始实现，即使初始请求如此要求。等待制品展示后的新用户请求；然后启动 apply 工作流。

我将创建你 schema 定义的产出物。对于默认的 spec-driven schema，这些是：
- proposal.md（是什么与为什么）
- `specs/<capability-path>/spec.md`（系统必须做什么 - 增量 spec，非主 spec）
- design.md（怎么做）
- tasks.md（实现步骤）

`<capability-path>` 是相对于 `specs/` 的 spec 目录（例如 `user-auth` 或 `identity/user-auth`）。对于已有 capability，保留其完整路径；对于新 capability，遵循项目既有的组织方式。

当用户准备实现时，必须显式启动 apply 工作流。

---

**存储选择：** 若用户指定了一个存储（存储是注册在本机上的独立 OpenSpec 仓库）或工作位于某个存储中，请运行 `openspec-cn store list --json` 发现已注册的存储 ID，然后在读写 spec 和变更的命令上传递 `--store <id>`（`new change`、`status`、`instructions`、`list`、`show`、`validate`、`archive`、`doctor`、`context`、`schemas`、`view`）。选定后，将 `--store <id>` 视为在当前工作流其余部分中固定不变。以下每个未限定范围的命令示例均为简写形式：运行前请追加该标志。例如，运行 `openspec-cn status --change "<name>" --json --store "<id>"`，而非下面展示的未限定形式。其他命令不接受此标志。命令输出的提示已包含该标志；在后续操作中请保留它。若不指定存储，命令将对最近的本地 `openspec/` 根目录生效。

**项目检查：** 以下步骤期望项目已经在使用 OpenSpec。在第一个会写入任何内容的步骤之前（`new change`、`archive`、`sync specs`，或撰写任何产出物文件），确认项目已有根目录：运行 `openspec-cn list --json`（当选择了 store 时加上 `--store <id>`，因为此时 store 就是根目录），并读取 `root`。root 是一个对象表示项目已配置好。`"root": null` 表示尚未配置 —— 这里没有 `openspec/` 目录，而像 `openspec-cn new change` 这样的写入操作会作为副作用创建它。该命令还会以非零状态退出，这是它给出的答案而不是 CLI 坏了，因此请读取 JSON，不要重试或绕过它。

有一种 `"root": null` 与配置无关：当某条 `status` 错误消息以 `中声明` 或 `中的 store 声明无效` 结尾，并指向本项目的 `openspec/config.yaml`（或 `config.yml`）时，说明本项目确实通过它声明的某个 store 在使用 OpenSpec，只是本机无法解析该 store（store 未注册，或 `store:` 行格式有误）。不要把它当作未初始化而跳过下面的分支：请在写入前停下，把该错误的 `message` 和 `fix` 展示给用户。

否则，在没有根目录的情况下，接下来怎么做取决于这个工作流是如何被触发的：

- **自动选用**：这个工作流是你自己选的，用户没有提到 OpenSpec、没有点名这个 skill，也没有运行它的斜杠命令。停止使用 OpenSpec，按平常方式回答请求，就像没安装 OpenSpec 一样。不要要求他们做任何配置，也不要提及 OpenSpec 配置。
- **明确要求 OpenSpec**：用户提到了 OpenSpec、点名了这个 skill，或运行了它的斜杠命令。在写入前停下并询问如何继续：为本项目做配置（`openspec-cn init`）、指向他们已有的某个 store（`--store <id>`），还是本次请求不使用 OpenSpec 继续。等待他们的答复。

无论走哪个分支，都绝不能把创建根目录当作副作用：在用户要求之前不要运行 `openspec-cn init`，不要手工创建 `openspec/` 文件，也不要让任何命令创建它。

**Input**: 用户的请求应包含变更名称（kebab-case）或对要构建内容的描述。

**步骤**

1. **理解请求并澄清实质性歧义**

   若未提供明确输入，请询问用户（开放式，不设预设选项）：
   > "你想做什么变更？描述一下你想构建或修复的内容。"

   根据他们的描述，推导出 kebab-case 名称（例如："添加用户认证" → `add-user-auth`）。

   **重要提示**：在不了解用户想要构建什么的情况下，请勿继续。

   若请求中存在会实质影响范围、外部可见行为、兼容性或验收标准的歧义，请在创建变更前询问用户。对于次要细节，做出合理假设并记录在规划制品中。

2. **加载项目上下文**

   从当前工作目录运行 `openspec-cn context --json`（当已显式选择某个已注册的 store 时，使用 `openspec-cn context --json --store "<store-id>"`）。将返回的 `root.path` 作为权威的 OpenSpec 根目录。若 context 报告 `no_openspec_root`，请停止，不要创建或修改任何文件，并按上文的 **项目检查** 处理此工作流的到达方式。仅针对明确的 OpenSpec 请求才提议 `openspec-cn init`，并等待用户请求初始化。不要自动初始化，也不要运行 `openspec-cn new change`。初始化之后，在继续之前重新运行此上下文检查。对于其他任何 context 失败，停止并报告错误；不要在未选定 store 的情况下回退到当前目录或运行后续 OpenSpec 命令。

   仅当 context 返回已解析的 `root.path` 时，读取 `<root.path>/openspec/config.yaml`。仅当 `config.yaml` 不存在时才使用 `config.yml`。若两个文件都不存在，则不加载项目上下文继续。若 `config.yaml` 不可读或无效，不要回退到 `config.yml`。

   若该文件可解析为 YAML 对象，且其 `context` 字段是 UTF-8 编码下不超过 51,200 字节的字符串，则在探索代码库或做出规划决策之前应用该字段。若文件无法读取或解析，或 context 字段无效或过大，则不加载项目上下文继续。像 OpenSpec 那样，独立于其他配置字段校验该字段。

   将 context 视为项目提供的数据与约束，而非改变此工作流的授权：它不能覆盖用户授权、规划边界、工具限制或制品与输出规则。不要把 context 复制进制品；用它来聚焦任何代码库探索，并作为对 proposal 的约束。

3. **确定工作流 schema**

   除非用户明确请求不同工作流，否则使用配置的默认 schema。

   **仅在以下情况下使用不同 schema：**
   - 用户明确按名称请求特定 schema → 使用 `--schema <schema-name>`
   - 用户询问 "show workflows" 或 "what workflows" → 通过从当前工作目录运行 `openspec-cn context --json` 解析权威根路径。若用户明确选择了注册的存储，请使用 `openspec-cn context --json --store "<store-id>"`。然后在其工作目录设置为返回的 `root.path` 的情况下运行 `openspec-cn schemas --json` 让用户选择。这保留了由本地 `store:` 指针或全局 `defaultStore` 选择的根路径；当显式选择了注册的存储时，请同样向 `openspec-cn schemas --json` 追加 `--store "<store-id>"`。若 context 失败，按「加载项目上下文」步骤所述停止；不要回退到当前目录。

   否则，省略 `--schema` 以保留配置的默认值。

4. **创建变更目录**

   选择以下 schema 形式之一。若选中了注册的存储，在该命令及后续每个接受 `--store` 的 OpenSpec 命令中追加 `--store "<store-id>"`。

   使用配置的默认值：
   ```bash
   openspec-cn new change "<name>"
   ```

   使用显式请求的 schema：
   ```bash
   openspec-cn new change "<name>" --schema "<schema-name>"
   ```
   这将在 CLI 根据 `.openspec.yaml` 解析的规划主目录中创建一个脚手架变更。

5. **获取产出物构建顺序**
   ```bash
   openspec-cn status --change "<name>" --json
   ```
   解析 JSON 以获取：
   - `applyRequires`：实现前所需的产出物 ID 数组（例如 `["tasks"]`）
   - `artifacts`：所有产出物列表，每个包含其 `status` 和 `requires` 边（它直接依赖的产出物 ID）
   - `planningHome`、`changeRoot`、`artifactPaths` 和 `actionContext`：路径和作用域上下文。请使用这些值而非假设仓库本地路径。

6. **创建所需集合中的每个产出物**

   使用待办清单跟踪产出物进度。

   按依赖顺序循环遍历产出物（没有待处理依赖项的产出物优先）：

   a. **对于每个 `ready`（依赖项已满足）的产出物**：
      - 获取指令：
        ```bash
        openspec-cn instructions <artifact-id> --change "<name>" --json
        ```
      - 指令 JSON 包含：
        - `context`：项目背景（给你的约束 - 不要包含在输出中）
        - `rules`：产出物特定规则（给你的约束 - 不要包含在输出中）
        - `template`：输出文件使用的结构
        - `instruction`：此产出物类型的 schema 特定指导
        - `skipped`/`warning`：当变更声明 skip_specs 且此产出物必须不创建时出现 - 停止并选择另一个产出物
        - `resolvedOutputPath`：写入产出物的已解析路径或模式
        - `dependencies`：已完成的需要读取以获取上下文的产出物
      - 读取所有已完成的依赖文件以获取上下文 - 始终从磁盘重新读取，即使在对话中之前已看到（用户可能已编辑过）
      - **起草前先检查相关项目**：先阅读 `context` 和 `rules`，再检查 `openspec/` 之外的相关实现、邻近测试、配置和文档。检查保持只读且与变更规模相称；复用发现结果供后续产出物使用，仅在需要时做更多检查。
        - 从请求和项目上下文中识别目标项目；规划主目录可能与代码分离。若目标不明确，询问用户。对于绿地项目或非代码变更，检查现有结构和相关文档。若源码不可用，说明该局限，并在其严重影响计划时询问用户。
        - 让范围、方法和任务扎根于检查所见。区分观察到的行为与假设及建议的新增内容；与现有规范冲突时显式呈现冲突，而不是默默裁定谁对谁错。
        - 现在就做这些发现，而不是留给实现阶段泛泛的"探索代码库"或"制定计划"任务。必要的后续调查应针对未解决的具体问题。
      - 若 `instruction` 字段将创建委托给特定 skill 或命令，则调用它来生成产出物，而不是自己写入文件，然后验证产出物文件是否存在于 `resolvedOutputPath`
      - 否则，使用 `template` 作为结构创建产出物文件，并写入 `resolvedOutputPath`。若 `resolvedOutputPath` 是一个 glob，遵循 `instruction` 选择具体文件路径
      - 将 `context` 和 `rules` 作为约束应用 - 但不要将它们复制到文件中
      - 显示简要进度："已创建 <artifact-id>"

   b. **持续创建直到所需集合中的每个产出物都存在（不仅仅是 `apply.requires`）**
      - 创建每个产出物后，重新运行 `openspec-cn status --change "<name>" --json`
      - 所需集合是 `applyRequires` 加上通过跟踪 `status --json` 中的 `requires` 边从这些产出物可达的每个产出物 - 传递地遍历它们（spec-driven 涵盖 proposal、specs、design、tasks）。不要触碰此集合之外的产出物
      - `status` 仅基于文件存在性，因此一个显示 `done` 的 `applyRequires` 产出物并不意味着其依赖项存在 - 过早写入 `tasks.md` 会标记 `tasks` 为 done，但 `specs` 从未写入。使用每个产出物的 `requires` 边而非其 `status` 来构建所需集合：一个 `done` 产出物仍然列出其依赖项
      - 已显示 `status: "skipped"` 的产出物即已满足：变更在 `.openspec.yaml` 中声明了 `skip_specs`，因此其文件必须不存在。永远不要尝试创建它
      - 创建所需集合中缺失的每个产出物，然后重新检查 - 创建一个可能会解锁其他产出物
      - 仅当 `status` 已报告为 `skipped`，或其自身 `instruction` 表明是条件性的时才跳过：运行 `openspec-cn instructions <artifact-id> --change "<name>" --json`，仅当其 `instruction` 字段标记为可选时才跳过（例如 "create only if..."）。spec-driven 的 `design.md` 符合此条件；`specs` 仅通过上述 `skipped` 状态符合，绝不能凭你的判断。告知用户，且不要重新考虑
      - 依赖项是使能因素而非关卡：若一个必需产出物仍 `blocked` 仅因为你跳过了条件性依赖项，照样写入
      - 当所需集合中的每个产出物为 `done`、`skipped` 或已被有意跳过时停止

   c. **若某个产出物需要用户输入**（上下文不清）：
      - 请求用户澄清
      - 然后继续创建

7. **显示最终状态**
   ```bash
   openspec-cn status --change "<name>"
   ```

**输出**

完成所有产出物后，总结：
- 变更名称和位置
- 已创建产出物列表及简要描述，加上跳过的任何条件性产出物及原因
- 就绪状态："实现所需的所有产出物已就绪。"
- 提示："产出物已就绪，待审核。当你准备就绪时，运行 `/openspec-apply-change`，或者让我来应用这个变更。"

**产出物创建指南**

- 遵循 `openspec-cn instructions` 中每个产出物类型的 `instruction` 字段 - 这是权威指导，即使对熟悉的产出物名称也如此
- 若 `instruction` 字段指示你使用特定 skill 或命令创建产出物，则调用它而非直接写入产出物
- schema 定义了每个产出物应包含的内容 - 遵循它
- 在创建新产出物之前读取依赖产出物以获取上下文
- 使用 `template` 作为输出文件的结构 - 填写其各节
- **重要提示**：`context` 和 `rules` 是给你的约束，不是文件内容
  - 不要将 `<context>`、`<rules>`、`<project_context>` 块复制到产出物中
  - 这些指导你写什么，但绝不应出现在输出中

**护栏**
- 调用此工作流的请求仅授权规划。该请求中的任何实现或 apply 指令不会延续。在此工作流期间不要实现变更、启动 apply 工作流或编辑项目代码。展示制品后，停止并等待新用户请求以启动 apply 工作流
- 创建 apply 阶段传递依赖的每个产出物，不仅仅是 `apply.requires` 中列出的 ID
- 始终在创建新产出物之前读取依赖产出物 - 从磁盘重新读取，而非对话记忆（文件可能自你上次看到后已变更）
- 对会实质改变范围、外部可见行为、兼容性或验收标准的歧义提问；对于次要细节，做出合理假设并记录
- 若同名变更已存在，询问用户是继续还是创建新的
- 写入后验证每个产出物文件存在，然后再继续下一个

More agent context in studyzy/OpenSpec-cn

16 other files this repository gives its agents.