openspec-propose

提出一项新变更——创建变更并一次性生成所有制品。

规划边界：此工作流仅创建规划制品。选择或触发此工作流的用户请求仅授权进行规划，即使请求要求构建或修复某项内容也是如此。不要编辑项目代码。规划制品完成后立即停止。即使初始请求要求实施，也不要在同一回复中开始实施。呈现制品后，等待用户提出新请求；然后再启动应用工作流。

我将根据架构定义创建变更及其制品。对于默认的规范驱动架构，制品包括：

• proposal.md（做什么以及为什么）
• specs/<capability-path>/spec.md（系统必须做什么——增量，而非主规范）
• design.md（如何实现）
• tasks.md（实施步骤）

<capability-path> 是相对于 specs/ 的规范目录（例如，user-auth 或 identity/user-auth）。保留现有能力的完整路径；新增能力则遵循项目既定的组织方式。

用户准备好实施时，必须明确启动应用工作流。

---

**存储区选择：**如果用户指定了存储区（存储区是此计算机上已注册的独立 OpenSpec 仓库），或工作所属的仓库就是某个存储区，则运行 openspec store list --json 以查找已注册的存储区 ID，然后在读取或写入规范和变更的命令中传入 --store <id>（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）。选择后，在工作流剩余步骤中始终使用 --store <id>。下方这些命令的未指定存储区示例都是简写形式：运行前请追加该标志。例如，应运行 openspec status --change "<name>" --json --store "<id>"，而不是下方所示的未指定存储区形式。其他命令不接受此标志。命令打印的提示中已包含该标志；后续命令也请保留该标志。未指定存储区时，命令会作用于最近的本地 openspec/ 根目录。

输入：用户请求应包含变更名称（kebab-case），或描述他们想要构建的内容。

步骤

1. 理解请求并澄清重要歧义

   如果未提供明确的输入，请向用户提问（开放式，不提供预设选项）：

   “你想处理什么变更？请描述你想构建或修复的内容。”

   根据用户的描述推导一个 kebab-case 名称（例如，“添加用户身份验证” → add-user-auth）。

   重要：未了解用户想要构建什么之前，不要继续。

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

2. 确定工作流架构

   使用已配置的默认架构，除非用户明确要求使用其他工作流。

   仅在以下情况下使用其他架构：

   • 用户明确指定架构名称 → 使用 --schema <schema-name>
   • 用户要求“显示工作流”或询问有哪些工作流 → 从当前工作目录运行 openspec context --json，以确定权威根目录。如果用户明确选择了已注册的存储区，则使用 openspec context --json --store "<store-id>"。然后将工作目录设为返回的 root.path，运行 openspec schemas --json 并让用户选择。这会保留由本地 store: 指针或全局 defaultStore 选择的根目录；如果用户明确选择了已注册的存储区，也要在 openspec schemas --json 中追加 --store "<store-id>"。如果 context 只报告 no_openspec_root，则改为从当前工作目录运行 openspec schemas --json。对于无效或不可用的存储区，不要使用此回退方式。

   其他情况下，省略 --schema 以保留已配置的默认设置。

3. 创建变更目录 选择以下一种 schema 形式。如果选择了已注册的存储，请在该命令以及下方每个接受 --store 的后续 OpenSpec 命令中追加 --store "<store-id>"。

   使用已配置的默认值：

   openspec new change "<name>"
   

   使用明确指定的 schema：

   openspec new change "<name>" --schema "<schema-name>"
   

   这会在 CLI 通过 .openspec.yaml 解析出的规划目录中创建一个脚手架变更。

4. 获取制品构建顺序

   openspec status --change "<name>" --json
   

   解析 JSON 以获取：

   • applyRequires：实现前所需制品 ID 的数组（例如，["tasks"]）
   • artifacts：所有制品的列表，每个制品都包含其 status 和 requires 依赖项（它直接依赖的制品 ID）
   • planningHome、changeRoot、artifactPaths 和 actionContext：路径和范围上下文。请使用这些信息，不要假定路径位于仓库内。

5. 创建所需集合中的每个制品

   使用待办列表跟踪制品进度。

   按依赖顺序遍历制品（优先处理没有待解决依赖项的制品）：

   a. 对于每个状态为 ready（依赖项已满足）的制品：

   • 获取说明：

     openspec instructions <artifact-id> --change "<name>" --json
     

   • 说明 JSON 包含：
     • context：项目背景（对你的约束——请勿包含在输出中）
     • rules：针对制品的规则（对你的约束——请勿包含在输出中）
     • template：输出文件所用的结构
     • instruction：针对该制品类型的 schema 专属指导
     • skipped/warning：当变更声明了 skip_specs 且不得创建此制品时提供——停止并选择其他制品
     • resolvedOutputPath：要写入制品的解析后路径或模式
     • dependencies：要阅读以了解上下文的已完成制品
   • 阅读所有已完成的依赖文件以了解上下文——即使你在之前的对话中看过，也务必从磁盘重新读取（用户可能已经编辑过这些文件）
   • 如果 instruction 字段要求委托特定技能或命令来创建制品，请调用该技能或命令生成制品，而不是自行编写文件，然后验证 resolvedOutputPath 处是否存在制品文件
   • 否则，使用 template 作为结构创建制品文件，并将其写入 resolvedOutputPath。如果 resolvedOutputPath 是 glob，请遵循 instruction 选择具体文件路径
   • 将 context 和 rules 作为约束应用——但请勿将它们复制到文件中
   • 简要显示进度：“已创建 ” b. 继续操作，直到所需集合中的每个工件都存在（而不仅仅是 apply.requires 中的工件）
   • 每创建一个工件后，重新运行 openspec status --change "<name>" --json
   • 所需集合包括 applyRequires，以及沿着 status --json 中的 requires 边从这些工件出发可到达的所有工件——递归遍历（spec-driven 会递归包含 proposal、specs、design、tasks）。集合之外的工件不要处理
   • status 只检查文件是否存在，因此，applyRequires 中的工件显示为 done，并不代表其依赖项也存在——提前写入 tasks.md 会让 tasks 显示为 done，但 specs 可能从未写入。构建所需集合时，请使用每个工件的 requires 边，而不是其 status：显示为 done 的工件仍会列出其依赖项
   • 已显示 status: "skipped" 的工件视为已满足：该变更在 .openspec.yaml 中声明了 skip_specs，因此其文件必须不存在。切勿尝试创建
   • 创建所需集合中所有缺失的工件，然后重新检查——创建一个工件可能会解除其他工件的阻塞状态
   • 只有在 status 已报告其为 skipped，或其自身的 instruction 声明它是有条件的情况下，才跳过该工件：运行 openspec instructions <artifact-id> --change "<name>" --json，仅当其 instruction 字段标明它是可选的（例如“仅在……时创建”）才跳过。Spec-driven 的 design.md 符合条件；specs 只有在上述 skipped 状态下才符合条件，不能由你自行判断。告知用户，并且不要重新考虑
   • 依赖项是促成条件，而不是门槛：如果某个必需工件仅因跳过了有条件的依赖项而仍处于 blocked，仍要编写该工件
   • 当所需集合中的每个工件都处于 done、skipped 状态，或已被有意跳过时，停止

   c. 如果某个工件需要用户输入（上下文不明确）：

   • 请用户澄清
   • 然后继续创建

6. 显示最终状态

   openspec status --change "<name>"
   

输出

完成所有工件后，进行总结：

• 变更名称和位置
• 已创建工件的列表及简要说明，以及跳过的任何有条件工件和原因
• 就绪状态：“所有实现所需的工件均已就绪。”
• 提示：“工件已准备好供审查。准备就绪后，请运行 /openspec-apply-change，或让我应用此变更。”

工件创建指南

• 对于每种工件类型，请遵循 openspec instructions 的 instruction 字段——这是权威指导，即使工件名称很熟悉也应遵循
• 如果 instruction 字段指示使用特定技能或命令来创建工件，请调用它，而不是直接编写工件
• Schema 定义了每种工件应包含的内容——请遵循
• 创建新工件前，请阅读依赖工件以了解上下文
• 使用 template 作为输出文件的结构——填写其中的各个部分
• 重要： context 和 rules 是对你的约束，不是文件内容
  • 不要将 <context>、<rules>、<project_context> 块复制到工件中
  • 这些内容用于指导你的写作，但绝不能出现在输出中 防护措施
• 调用此工作流的请求仅授权进行规划。该请求中的任何实现或应用指令均不延续生效。此工作流中请勿实现更改、启动应用工作流或编辑项目代码。呈现所有产物后，请停止并等待新的用户请求，以启动应用工作流
• 创建应用阶段传递依赖的所有产物，而不仅是 apply.requires 中列出的 ID
• 创建新产物前，务必先读取依赖产物；从磁盘重新读取，不要依赖对话记忆（自上次查看后，文件可能已更改）
• 对于会实质改变范围、外部可观察行为、兼容性或验收标准的歧义，先提问确认；对于次要细节，做出合理假设并记录下来
• 如果已存在同名更改，请询问用户是要继续该更改还是创建新的更改
• 写入后，请在继续下一项之前确认每个产物文件确实存在