openspec

name	openspec
description	用于 OpenSpec、/opsx、proposal/spec/design/tasks 工件编写与继续治理的专用技能。仅在任务明确涉及 OpenSpec 或跨端规格治理时启用。

仅当任务明确涉及 OpenSpec、/opsx、proposal/spec/design/tasks 工件或跨端规格治理时使用本技能。

总原则

• 先收紧任务边界，再读文件、搜索、编辑。
• 不要在同一轮里同时做实现、验证、归档。
• 如果剩余工作主要是验证，切换为 verify 心态，不继续按 apply 心态扩散。
• 先完成一个最小闭环，再进入下一个子任务。

Task Node Verification

• 所有任务拆分都必须使用严格的 - [ ] checklist 格式。
• 每个一级任务必须包含一个父级范围的验证子任务。
• 该验证子任务必须是独立的 - [ ] checkbox，不能写成普通文本、备注或全局验证的一部分。
• 一级任务下的实现子任务完成后，必须先停下来执行当前父级验证节点，不能跳到下一个一级任务。
• 一级任务在实现子任务完成时仍不算完成。
• 只有在对应的父级验证节点通过后，该一级任务才算完成。
• 如果验证暂时不能执行，验证节点仍必须保留，并明确写出阻塞原因、缺失证据和恢复条件。
• 没有 - [ ] N.x 节点验证 的一级任务，视为拆分不完整，必须先补齐后再继续。

推荐格式

• - [ ] 1.6 节点验证: [验证目标] - [如何验证] - [预期断言]
• - [ ] 2.7 单元测试/节点验证: [验证目标] - [脚本或步骤] - [预期结果]

tasks.md 拆分规则

• 任务默认至少拆到二级。
• 子任务描述优先写成可交付证据或验收产物，而不是宽泛动作。
• 如果一个子任务结果无法在 3 到 5 行内总结为证据摘要，说明拆分还不够细。
• 走查调用链、定位状态同步、协议边界校验这类任务，必须先拆成函数级、链路级或单一验证点。
• 不要把多个一级任务的验证统一堆到最后的“总体验证”里。

搜索策略

• 不做无约束全仓搜索。
• 每次搜索前先明确这次搜索要消除哪个未知数。
• 优先搜索稳定符号：类名、函数名、字段名、协议名、日志键。
• 默认顺序：
  1. 找定义
  2. 找调用点或赋值点
  3. 只读命中位置的局部上下文
  4. 必要时再扩展范围
• 不要在一个回合里连续发起过多大范围搜索。

Windows Shell 兼容

• 在 Windows 环境中，不要默认依赖 pwsh.exe 或 PowerShell Core。
• 若只是创建 openspec/changes/... 目录、proposal/spec/design/tasks 文档骨架，优先直接创建文件与目录，不要把目录创建绑定到 pwsh.exe。
• 如果 shell 工具报错显示 pwsh.exe 不存在、PowerShell Core 不可用，必须立即改用以下之一：
  • powershell.exe
  • cmd /c mkdir
  • 直接文件创建/编辑能力
• 遇到这类错误时，不要继续重复同一个 pwsh.exe 调用链。

证据沉淀

• 对调用链、模式分支、状态同步类任务，先沉淀证据，再组织结论。
• 每个关键节点都应记录一张证据卡：
  • 文件
  • 函数/方法
  • 上游入口
  • 下游去向
  • 相关模式条件
  • 当前结论

Apply / Verify 边界

• apply 阶段只处理当前任务明确要求的实现边界。
• verify 阶段一次只验证一个子任务或一个边界场景。
• 如果验证失败，只记录失败点、影响和最可能原因，不要自动切回整条链路重新扩搜。

交接摘要

• 交接摘要控制在 10 行内。
• 必须包含：
  • change-id
  • 已修改文件
  • 已完成任务
  • 未完成任务
  • 待验证项
  • 下一轮严格边界

何时使用本技能

• 用户明确提到 OpenSpec、/opsx、proposal、spec、design、tasks。
• 用户要求继续某个 change、修订文档工件、补 tasks 节点验证规则。
• 需要治理跨端协议、设计文档、任务拆分规范，而不是直接写实现代码。