robsonprod/portfolio

实施 OpenSpec 变更中的任务。

仓库选择： 如果用户提到了一个仓库（即本机上注册的一个独立的 OpenSpec 仓库）或者工作在某个仓库中，请运行 openspec store list --json 来发现已注册的仓库 ID，然后在所有读取或写入规约和变更的命令（如 new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）上传递 --store <id>。一旦选定，将 --store <id> 视为粘贴性的，在后续工作流中持续使用。下面每个未指定范围的命令示例都是简写形式：在执行前，请附加该标志。例如，应运行 openspec status --change "<name>" --json --store "<id>"，而不是下面所示的未指定范围的形式。其他命令不接受此标志。命令打印的提示已携带该标志；请在其后续操作中保留它。如果没有指定仓库，命令将在最近的本地 openspec/ 根目录上操作。

项目检查： 这些步骤假设项目已经使用了 OpenSpec。在执行任何写入操作（new change、archive、sync specs 或编写工件文件）的第一步之前，请确认项目拥有根目录：运行 openspec list --json（如果选择了仓库，则带上 --store <id>，因为此时仓库就是根目录）并读取 root。如果返回 root 对象，说明项目已设置。"root": null 表示未设置——这里没有 openspec/ 目录，并且像 openspec new change 这样的写入操作会作为副作用创建一个。该命令还会以非零状态退出，这是该答案，而不是 CLI 故障，因此请读取 JSON，而不是重试或绕开它。

有一种 "root": null 的情况与设置无关：当 status 的错误消息以 Declared in 或 Invalid store declaration in 开头，并且提到了本项目的 openspec/config.yaml（或 config.yml）时，说明该项目确实通过其声明的仓库使用了 OpenSpec，但本机无法解析该仓库（仓库未注册，或者 store: 行格式错误）。不要将其视为未初始化而跳过下面的分支：在写入之前停止，并向用户显示该错误的 message 和 fix。

否则，如果没有根目录，接下来发生什么取决于如何到达此工作流：

• 自动选择：你自行选择了此工作流，而没有用户提及 OpenSpec、提及此技能或运行其斜杠命令。停止使用 OpenSpec，像没有安装 OpenSpec 一样正常响应用户请求。不要要求用户设置任何内容，也不要提及 OpenSpec 设置。
• 明确的 OpenSpec 请求：用户提到了 OpenSpec、提到了此技能或运行了其斜杠命令。在写入之前停止，并询问如何继续：设置此项目（openspec init）、使用他们已有的仓库（--store <id>），或者在此请求中不使用 OpenSpec 继续。等待他们的回答。

在这两个分支中，永远不要将创建根目录作为副作用：除非用户要求，否则不要运行 openspec init；不要手动创建 openspec/ 文件；也不要让任何命令创建它。

输入：可选地指定一个变更名称（例如，/opsx:apply add-auth）。如果省略，检查是否可以从对话上下文中推断出来。如果含糊不清或有歧义，你必须提示用户从可用的变更中选择。

步骤

1. 选择变更

   如果提供了名称，则直接使用。否则：

   • 从对话上下文中推断用户是否提到了某个变更
   • 如果只有一个活跃的变更，则自动选择
   • 如果存在歧义，运行 openspec list --json 获取可用变更，并要求用户选择一个

   始终宣布："正在使用的变更：<名称>" 以及如何覆盖（例如，/opsx:apply <other>）。

2. 检查状态以了解 schema

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

   解析 JSON 以了解：

   • schemaName：正在使用的工作流（例如，"spec-driven"）
   • planningHome、changeRoot 和 actionContext：规划范围和编辑约束
   • 哪个工件包含任务（对于 spec-driven 通常是 "tasks"，其他 schema 请查看 status）

3. 获取 apply 指令

   openspec instructions apply --change "<name>" --json
   

   这将返回：

   • contextFiles：工件 ID -> 具体文件路径数组（因 schema 而异——可以是 proposal/specs/design/tasks，或 spec/tests/implementation/docs）
   • 进度（总计、已完成、剩余）
   • 任务列表，包含状态、源路径和源行号
   • 基于当前状态的动态指令
   • 可选的 context：来自所选根目录的当前必需的项目指令输入
   • 可选的 operationGuidance：当前适用于 apply 的咨询性指导
   • missingArtifacts（如果存在）：所需但尚未输出结果的工件 ID

   处理状态：

   • 如果 state: "blocked"：显示消息并暂停实施。
     • 如果 missingArtifacts 非空：建议完成缺失的工件。运行 openspec status --change "<name>" --json，选择下一个状态为 ready 的工件（非 skipped 或 blocked），并使用 openspec instructions "<artifact-id>" --change "<name>" --json 获取其规则和模板。在这两个命令上都保留所选的 --store <id>。
     • 否则，按照 CLI 指令从现有规划工件中创建或修复 schema 配置的跟踪文件。在被阻塞时，不要假设另一个工件已就绪或开始实施。
   • 如果 state: "all_done"：报告所有跟踪任务已完成，并建议在归档前进行适当的审查或验证。
   • 否则：继续实施。

   将 context 视为必需的提示级输入。阅读并考虑它，并在实施时应用相关的项目事实、约定和约束。 将 operationGuidance 视为可选的附加建议。阅读并考虑每条条目，并遵循那些适用且与内置工作流兼容的条目。

   将这两个字段与 CLI 返回的状态、缺失工件、任务、进度、contextFiles 和内置 instruction 分开对待。它们不是任务完成的证据，不取代内置指令，也不允许绕过阻塞状态。如果 context 与内置指令、用户明确选择或 CLI 控制的值冲突，报告冲突并保留控制值。如果不适用或与这些控制输入冲突，则不遵循该指导并解释原因。这些是提示级的行为契约，不是可执行的检查。

4. 读取上下文文件

   读取 apply 指令输出中 contextFiles 下列出的每个文件路径。 文件取决于所使用的 schema：

   • spec-driven：proposal、specs、design、tasks
   • 其他 schema：遵循 CLI 输出中的 contextFiles

   不要将 context 或 operationGuidance 逐字复制到实施文件或规划工件中，除非用户另外请求该内容。

5. 显示当前进度

   显示：

   • 正在使用的 schema
   • 进度："已完成 N/M 个任务"
   • 剩余任务概览
   • 来自 CLI 的动态指令

6. 实施任务（循环直到完成或被阻塞）

   对于每个待处理的任务：

   • 显示正在处理哪个任务
   • 进行所需的代码更改
   • 保持更改最小化且集中
   • 在编辑之前，确认返回的 sourcePath 和 line 处的复选框仍然与任务描述匹配；如果不匹配，重新运行 apply 指令并使用刷新后的位置
   • 在返回的 sourcePath 和 line 处将任务标记为完成：- [ ] → - [x]
   • 重新运行 apply 指令，确认该任务现在已完成且进度已更新
   • 继续下一个任务

   在以下情况下暂停：

   • 任务不明确 → 请求澄清
   • 实施揭示了设计问题 → 建议更新工件
   • 任务需要超出规约和任务描述范围的工作，或者你倾向于悄悄放弃、缩小、推迟或对指定行为接受例外以使其适用 → 披露增加的 scope 并询问；不要默默吸收
   • 遇到错误或阻塞 → 报告并等待指导
   • 用户中断

7. 完成或暂停时，显示状态

   显示：

   • 本次会话完成的任务
   • 总体进度："已完成 N/M 个任务"
   • 如果全部完成：报告跟踪任务已完成，并建议在归档前进行适当的审查或验证
   • 如果暂停：解释原因并等待指导

实施期间的输出

## 正在实施：<change-name> (schema: <schema-name>)

正在处理任务 3/7：<任务描述>
[...正在实施...]
✓ 任务完成

正在处理任务 4/7：<任务描述>
[...正在实施...]
✓ 任务完成

完成时的输出

## 实施完成

**变更：** <change-name>
**Schema：** <schema-name>
**进度：** 7/7 个任务已完成 ✓

### 本次会话完成
- [x] 任务 1
- [x] 任务 2
...

所有跟踪任务均已完成。请在归档前对变更进行适当的审查或验证。可以使用 `/opsx:archive` 归档此变更。

暂停时的输出（遇到问题）

## 实施暂停

**变更：** <change-name>
**Schema：** <schema-name>
**进度：** 4/7 个任务已完成

### 遇到问题
<问题描述>

**选项：**
1. <选项 1>
2. <选项 2>
3. 其他方法

您想怎么做？

护栏

• 持续处理任务直到完成或受阻
• 始终在开始实施前读取上下文文件（来自 apply 指令输出）
• 如果任务有歧义，在实施前暂停并询问
• 如果实施揭示问题，暂停并建议更新工件
• 保持代码更改最小化并限定在每个任务范围内
• 每完成一个任务后立即更新任务复选框
• 遇到错误、阻塞或要求不明确时暂停——不要猜测
• 当任务需要超出规约描述范围的工作时，披露增加的 scope 并暂停——永远不要悄悄放弃、缩小、推迟或简化指定的行为
• 仅当指定行为完全实施后才将任务标记为 - [x]，而不是部分完成或推迟时
• 使用 CLI 输出中的 contextFiles，不要假定特定的文件名
• 使用每个任务的 sourcePath 和 line 来更新其精确的复选框
• 不要将 context 或 operation guidance 用作任务完成的证据
• 应用相关项目上下文；报告与控制工作流输入的冲突
• 考虑每条指导条目；解释任何不适用或冲突的建议
• 不要将运行时上下文或操作指导复制到实施文件或规划工件中
• 保留 CLI 控制的 blocked/ready/all-done 行为和完成标准

灵活工作流集成

本技能支持“对变更的操作”模型：

• 可随时调用：在所有工件完成之前（如果存在任务）、部分实施之后、与其他操作交错进行
• 允许工件更新：如果实施揭示设计问题，建议更新工件——不是阶段锁定，而是灵活工作