comet-dsh-plugin 0.0.0-stage → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/LICENSE +21 -0
  2. package/README.en.md +176 -0
  3. package/README.md +152 -2
  4. package/client.js +349 -0
  5. package/cordis.patch.yml +4 -0
  6. package/icon.png +0 -0
  7. package/index.js +183 -0
  8. package/locale/en.json +7 -0
  9. package/locale/zh.json +7 -0
  10. package/package.json +57 -4
  11. package/rules/comet-workflow-guard.md +63 -0
  12. package/rules/migration-assets.json +218 -0
  13. package/server/comet-plugin-setup.mjs +192 -0
  14. package/skills/comet/SKILL.md +37 -0
  15. package/skills/comet/agents/openai.yaml +3 -0
  16. package/skills/comet/reference/change-walkthrough.md +77 -0
  17. package/skills/comet/reference/edit-review.md +26 -0
  18. package/skills/comet/reference/host-check.md +11 -0
  19. package/skills/comet/reference/platform-execution.md +34 -0
  20. package/skills/comet/reference/task-learning.md +39 -0
  21. package/skills/comet/runtime/classic/checks.yaml +6 -0
  22. package/skills/comet/runtime/classic/guardrails.yaml +13 -0
  23. package/skills/comet/runtime/classic/skill.yaml +122 -0
  24. package/skills/comet/scripts/comet-archive.mjs +310 -0
  25. package/skills/comet/scripts/comet-check.mjs +179 -0
  26. package/skills/comet/scripts/comet-entry-runtime.mjs +151 -0
  27. package/skills/comet/scripts/comet-env.mjs +15 -0
  28. package/skills/comet/scripts/comet-guard.mjs +335 -0
  29. package/skills/comet/scripts/comet-handoff.mjs +289 -0
  30. package/skills/comet/scripts/comet-hook-guard.mjs +294 -0
  31. package/skills/comet/scripts/comet-hook-router-guard.mjs +628 -0
  32. package/skills/comet/scripts/comet-hook-router.mjs +17 -0
  33. package/skills/comet/scripts/comet-intent.mjs +181 -0
  34. package/skills/comet/scripts/comet-plugin-hook.mjs +213 -0
  35. package/skills/comet/scripts/comet-resume-probe.mjs +205 -0
  36. package/skills/comet/scripts/comet-runtime.mjs +571 -0
  37. package/skills/comet/scripts/comet-state.mjs +381 -0
  38. package/skills/comet/scripts/comet-yaml-validate.mjs +182 -0
  39. package/skills/comet-any/SKILL.md +47 -0
  40. package/skills/comet-any/agents/openai.yaml +5 -0
  41. package/skills/comet-any/reference/sdk-creation.md +100 -0
  42. package/skills/comet-archive/SKILL.md +28 -0
  43. package/skills/comet-archive/agents/openai.yaml +5 -0
  44. package/skills/comet-archive/reference/compat.md +188 -0
  45. package/skills/comet-build/SKILL.md +35 -0
  46. package/skills/comet-build/agents/openai.yaml +5 -0
  47. package/skills/comet-build/reference/compat.md +191 -0
  48. package/skills/comet-classic/SKILL.md +98 -0
  49. package/skills/comet-classic/agents/openai.yaml +3 -0
  50. package/skills/comet-classic/reference/auto-transition.md +34 -0
  51. package/skills/comet-classic/reference/classic-layout.md +36 -0
  52. package/skills/comet-classic/reference/comet-yaml-fields.md +82 -0
  53. package/skills/comet-classic/reference/context-recovery.md +128 -0
  54. package/skills/comet-classic/reference/debug-gate.md +30 -0
  55. package/skills/comet-classic/reference/decision-point.md +109 -0
  56. package/skills/comet-classic/reference/dirty-worktree.md +59 -0
  57. package/skills/comet-classic/reference/file-structure.md +32 -0
  58. package/skills/comet-classic/reference/intent-frame.md +132 -0
  59. package/skills/comet-classic/reference/scripts.md +144 -0
  60. package/skills/comet-classic/reference/sdk-methods.md +136 -0
  61. package/skills/comet-classic/reference/subagent-dispatch.md +75 -0
  62. package/skills/comet-classic/reference/workspace.md +23 -0
  63. package/skills/comet-design/SKILL.md +25 -0
  64. package/skills/comet-design/agents/openai.yaml +5 -0
  65. package/skills/comet-design/reference/compat.md +191 -0
  66. package/skills/comet-hotfix/SKILL.md +46 -0
  67. package/skills/comet-hotfix/agents/openai.yaml +5 -0
  68. package/skills/comet-hotfix/reference/compat.md +240 -0
  69. package/skills/comet-memory/SKILL.md +68 -0
  70. package/skills/comet-memory/agents/openai.yaml +5 -0
  71. package/skills/comet-native/SKILL.md +139 -0
  72. package/skills/comet-native/agents/openai.yaml +3 -0
  73. package/skills/comet-native/reference/artifacts.md +118 -0
  74. package/skills/comet-native/reference/clarification.md +120 -0
  75. package/skills/comet-native/reference/commands.md +321 -0
  76. package/skills/comet-native/reference/edit-review.md +26 -0
  77. package/skills/comet-native/reference/recovery.md +64 -0
  78. package/skills/comet-native/reference/workspace.md +70 -0
  79. package/skills/comet-native/scripts/comet-native-archive.mjs +475 -0
  80. package/skills/comet-native/scripts/comet-native-cancel.mjs +461 -0
  81. package/skills/comet-native/scripts/comet-native-doctor.mjs +475 -0
  82. package/skills/comet-native/scripts/comet-native-hook-guard.mjs +470 -0
  83. package/skills/comet-native/scripts/comet-native-init.mjs +465 -0
  84. package/skills/comet-native/scripts/comet-native-new.mjs +478 -0
  85. package/skills/comet-native/scripts/comet-native-next.mjs +464 -0
  86. package/skills/comet-native/scripts/comet-native-root.mjs +472 -0
  87. package/skills/comet-native/scripts/comet-native-runtime.mjs +525 -0
  88. package/skills/comet-native/scripts/comet-native-select.mjs +468 -0
  89. package/skills/comet-native/scripts/comet-native-show.mjs +462 -0
  90. package/skills/comet-native/scripts/comet-native-spec.mjs +468 -0
  91. package/skills/comet-native/scripts/comet-native-status.mjs +467 -0
  92. package/skills/comet-native/scripts/comet-native-transfer.mjs +466 -0
  93. package/skills/comet-open/SKILL.md +265 -0
  94. package/skills/comet-open/agents/openai.yaml +5 -0
  95. package/skills/comet-open/reference/batch-changes.md +51 -0
  96. package/skills/comet-review/SKILL.md +121 -0
  97. package/skills/comet-review/agents/openai.yaml +5 -0
  98. package/skills/comet-tweak/SKILL.md +49 -0
  99. package/skills/comet-tweak/agents/openai.yaml +5 -0
  100. package/skills/comet-tweak/reference/compat.md +232 -0
  101. package/skills/comet-verify/SKILL.md +30 -0
  102. package/skills/comet-verify/agents/openai.yaml +5 -0
  103. package/skills/comet-verify/reference/compat.md +202 -0
@@ -0,0 +1,265 @@
1
+ ---
2
+ name: comet-open
3
+ description: '创建 Classic change,整理需求并请用户确认。在用户调用 /comet-open,或 Classic 进入 Open、恢复初始化时使用。'
4
+ ---
5
+
6
+ # Comet 阶段 1:开启(Open)
7
+
8
+ 首次进入阶段、交接给新 Agent 或上下文恢复后,读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言),优先采用当前 continuation 或已领取 Action 的 `contextRequest`;同一阶段连续执行不重复获取。
9
+
10
+ 开始或恢复任务前,必须先读取并遵守 `comet-classic/reference/classic-layout.md`。本文件中的 OpenSpec CLI 调用必须通过适配器执行,文件路径必须基于该协议绑定的 `<classic-*>` 逻辑根目录。
11
+
12
+ ## 前置条件
13
+
14
+ - 无活跃 change,或用户希望创建新 change
15
+
16
+ ## 步骤
17
+
18
+ ### 0. 设置输出语言
19
+
20
+ 向 OpenSpec 传递提问和文档生成要求时,都必须明确指定 Comet 配置的产物语言,使用 `en`、`zh-CN` 这类规范化 ID。change 尚未初始化时,依次读取项目 `.comet/config.yaml` 和全局 `~/.comet/config.yaml` 的 `classic.language`;初始化后,复用当前有效响应中的 `configuration.language`;缺少时才使用 `comet state get <name> language` 读取。没有配置语言时,才采用当前用户请求的语言。生成的 `proposal.md`、`design.md`、`tasks.md` 必须以该语言为主。
21
+
22
+ ### 0a. 当前 change 绑定
23
+
24
+ 响应已有 `agent.continuation.mode` 时,先按 `comet-classic/reference/auto-transition.md` 处理;`wait` 按 auto-transition.md 区分手动衔接和原任务等待,不能因兼容字段 `nextAction.kind: reconcile` 再做恢复查询。使用当前响应的命令与输入;Skill 工作实际完成后才使用 `completion` 提交。下文依据 `nextAction.kind` 的恢复规则仅用于没有 `mode` 的旧响应。
25
+
26
+ 恢复已有 change 时,复用同一工作区和 Run 的最新有效 continuation 与归属;冷恢复、外部状态变化或信息缺失时才运行 `comet state next <name> --json`,再按 `data.runtimeFormat` 处理:
27
+
28
+ - `sdk`:复用现有 Run,按 `data.nextAction.kind` 恢复;已领取但结果未明的 Action 先核对原结果,不重新创建 change 或重发外部工作。
29
+ - `compat`:复用原流程和 `.comet.yaml`;不能自动把该 change 改建为 SDK Run。
30
+ - 命令失败:核对错误、归属记录、Run 和实际状态文件。归属冲突或状态格式异常时停止并报告;若本地 Run 记录丢失,先检查状态文件中的 `run_checkpoint`,按 `/comet-classic` 的恢复步骤沿用已保存阶段。旧状态没有检查点且用户明确同意重启时,才回到 Open 重新核对证据和确认。只有证实尚无任何 Runtime 归属、change 目录有效时,才按所选隔离方式准备工作区并初始化。不得因缺少某一个文件名就重新初始化。
31
+
32
+ SDK 与旧 change 在冷恢复、工作区变化或绑定信息缺失时,通过以下命令核对并绑定工作区;已有有效选择和 projectRoot 时直接复用:
33
+
34
+ ```bash
35
+ comet classic workspace resolve <change-name> --json
36
+ # 进入返回的 projectRoot
37
+ comet state select <change-name>
38
+ ```
39
+
40
+ 创建新 change 时,在创建 OpenSpec 基础目录后立即初始化 SDK Run,再运行上述 select 命令;初始化前不得手工写入 change 选择记录。
41
+
42
+ ### 0b. Open 前工作区决策与准备
43
+
44
+ 创建 Classic change 时,读取 `comet-classic/reference/workspace.md`。必须先确定工作区,再创建 OpenSpec 产物和 SDK Run,不能推迟到 Build:
45
+
46
+ - 用户明确要求并行工作时,直接使用 `worktree`;先准备好独立工作区,再创建 OpenSpec 产物和 state
47
+ - 用户未指定隔离方式时,按参考文档处理:需要用户选择时,展示可用的 `current`、`branch`、`worktree` 选项,推荐理由不能代替用户选择
48
+ - 用户选择 `current` 或 `branch` 时,仍应串行工作,不得将其描述为适合多个会话同时使用
49
+
50
+ 新 change 在运行 OpenSpec `new` 前准备工作区:
51
+
52
+ ```bash
53
+ comet classic workspace prepare <name> --isolation <current|branch|worktree> --json
54
+ # 进入返回的 projectRoot;后续 OpenSpec、state 和产物写入都必须在该目录执行
55
+ ```
56
+
57
+ 准备命令会复用已登记且分支匹配的 Worktree;分支仍在但已登记的 Worktree 被移除时,会重建 Worktree。只有分支已重命名、被用户用于其他工作,或无法确认归属时,才暂停,请用户明确确认 rebind。
58
+
59
+ ### 0c. OpenSpec 兼容性检查
60
+
61
+ 首次使用或上游安装发生变化时运行一次,记录用于排错的版本:
62
+
63
+ ```bash
64
+ comet classic openspec -- --version
65
+ ```
66
+
67
+ 兼容性必须通过实际能力检查,不能只凭版本号判断。status 必须提供 `changeRoot`、`applyRequires`,以及每个产物的 `requires`、`outputPath`、`status`;instructions 必须提供可用的 `resolvedOutputPath`。当前适配已核对 OpenSpec 1.11.0/1.12.0 的状态接口要求,不保证兼容所有历史版本。命令不可用、返回非零或缺少必需能力时,停止并展示错误和升级建议,不自动升级用户环境。
68
+
69
+ 创建 change 后,由 `comet state artifacts <name> --json` 校验路径、全部必需依赖和实际文件。该命令会展开 `applyRequires` 和 Classic 必需的 proposal/tasks 的所有依赖,形成完整依赖闭包。闭包要求生成 design 时,不能因为 instructions 称其“可选”就跳过;闭包不要求 design 时,不强制生成。
70
+
71
+ 只有需求不涉及行为规格变更、`.openspec.yaml` 明确设置了 `skip_specs: true`,且没有冲突的规格文件时,才允许跳过 specs。当前支持 proposal/specs/design/tasks 角色;遇到不支持的必需角色或输出模式时,必须明确报告,不能自行猜测处理方式。
72
+
73
+ ### 1. 探索想法与需求澄清
74
+
75
+ **立即执行:** 使用 Skill 工具加载 `openspec-explore` 技能。禁止跳过此步骤。
76
+
77
+ <!-- external-openspec-skill-override -->
78
+
79
+ **外部 OpenSpec Skill 适配规则:** 加载后只采用其探索方法,不执行其中直接运行官方 CLI、切换到固定 cwd,或读写写死的 OpenSpec 目录的指令。所有 CLI 调用改用 `comet classic openspec -- <args...>`,所有文件路径改用本轮绑定的 `<classic-*>` 逻辑根目录。
80
+
81
+ 技能加载后,先复用用户提供的 PRD、设计与已确认事实,围绕下列内容检查缺口并形成澄清摘要。只对会改变范围、方案或验收的未知项提问;信息已足够时可以不追加问答,不设置最低澄清轮数:
82
+
83
+ - 目标:用户真正要解决的问题和期望结果
84
+ - 非目标:本次明确不做的内容
85
+ - 范围边界:涉及/不涉及的模块、用户、平台或数据
86
+ - 关键未知项:仍不确定的假设、风险或依赖
87
+ - 验收场景草案:至少覆盖核心成功场景和关键边界场景
88
+
89
+ 澄清摘要必须包含:目标、非目标、范围边界、关键未知项、验收场景草案。
90
+
91
+ 需要向用户澄清时,必须先读取 `comet-classic/reference/decision-point.md`,以明确问题、推荐及理由、各选项影响的形式提问,并优先使用可用的 `AskUserQuestion`。只询问当前缺口;事实或素材无法提供真实选项时说明缺失内容后请求补充。外部探索 Skill 的提问也应用该协议,不能因加载了探索方法而省略选项或替用户选择。
92
+
93
+ 引用完整 PRD 时,给出文件路径和相关章节,不复制全文。已确认的事实不重复征求同意;发现矛盾时,只澄清矛盾点。OpenSpec 技能仍是必需依赖,探索结束后必须返回 Comet,不能由外部 Skill 自行进入设计、实施或归档。探索中的确认不能代替 Open 最后的产物确认。
94
+
95
+ ### 1a. 创建前确认是否拆分 PRD
96
+
97
+ 用户提供大型 PRD、路线图、完整产品方案,或需求包含多个可独立交付的目标时,创建产物前读取并执行[PRD 拆分与批量恢复](reference/batch-changes.md)。恢复 `.comet/batches/<batch-id>.json` 中的一批 changes 时也读取该参考。普通单 change 直接继续;已确认的拆分项复用原范围。
98
+
99
+ ### 1b. 整理需求并确定 Change 名称
100
+
101
+ 创建 OpenSpec 产物前,把 Step 1 的澄清结果整理为需求摘要(resolved brief),包括目标、非目标、范围边界、关键未知项和验收场景草案。根据这份摘要,拟定一个能准确表达范围的 kebab-case 英文 change 名称。
102
+
103
+ - **范围与命名都明确时直接继续**,不得仅为了让用户批准摘要或名称而创建停顿点;最终审视会统一确认 change 名称、范围和产物内容
104
+ - 用户已经提供名称时,规范化为 kebab-case 并在进度说明中回显;规范化不改变含义时无需再次确认
105
+ - 已确认批量拆分项直接复用批量清单中的摘要与名称;检测到范围漂移或清单信息缺失时,才重新澄清
106
+ - 只有仍需在不同范围或不同目标 change 之间作出选择时,才按 `comet-classic/reference/decision-point.md` 将相关问题合并提问;不能仅因命名偏好而单独暂停
107
+
108
+ OpenSpec change 名称必须是 kebab-case 英文(小写字母、数字、单连字符)。名称冲突但目标仍明确时,拟定一个不冲突且含义一致的名称,然后继续。只有无法判断应复用现有 change 还是创建新 change 时,才交给用户选择。
109
+
110
+ resolved brief 或 change 名称仍不明确时不得运行 `comet classic openspec -- new change`,也不得创建 proposal/design/tasks;继续澄清或处理真正的用户决策后再进入 Step 2。
111
+
112
+ ### 2. 创建 Change 结构 + 初始化状态
113
+
114
+ 本节沿用 [SDK 创建顺序](../comet-classic/reference/sdk-methods.md#开始与产物):OpenSpec 先创建基础目录,再初始化 SDK Run。已有 Run 时只恢复,不重建目录或状态。
115
+
116
+ **立即执行:** 使用 Skill 工具加载 `openspec-new-change` 技能。禁止跳过此步骤。
117
+
118
+ <!-- external-openspec-skill-override -->
119
+
120
+ **外部 OpenSpec Skill 适配规则:** 加载后只采用其创建 change 的方法,不执行其中直接运行官方 CLI、切换到固定 cwd,或把 change 写到固定 OpenSpec 根目录的指令。创建、status 与 instructions 全部改用 `comet classic openspec -- <args...>`,文件路径全部改用 `<classic-change-dir>` 等本轮逻辑根目录。
121
+
122
+ 完整 `/comet-classic` 流程默认不得使用 Skill 工具加载 `openspec-propose` 技能;只有用户明确要求一次性生成提案和其他产物时,才允许加载。
123
+
124
+ <!-- external-openspec-skill-override -->
125
+
126
+ **外部 OpenSpec Skill 适配规则:** 使用 `openspec-propose` 时,同样不能直接运行官方 CLI、采用固定 cwd 或读写固定 OpenSpec 目录。命令必须通过适配器执行,产物必须写入路径解析器返回的 `<classic-*>` 逻辑根目录。
127
+
128
+ 技能加载后,按其指引创建 change 的基础目录和文件。Step 1b 已形成范围明确的 resolved brief 时,不再执行其中的 "STOP and wait for user direction",直接继续,避免重复询问。
129
+
130
+ 直接使用 Step 1b 的 resolved brief 填充产物内容。只有 brief 仍有会改变范围的歧义时,才回退到技能的提问流程。
131
+
132
+ change 的基础目录和文件创建后,立即初始化 SDK Run,以便中断后恢复;不能等所有产物都生成后才初始化(入口状态验证统一在 Step 3 执行,这里不重复):
133
+
134
+ ```bash
135
+ comet state init <name> full --isolation <selected-isolation>
136
+ comet state select <name> --json
137
+ ```
138
+
139
+ 任一命令失败都停止。选择结果必须返回 `runtimeFormat: sdk`、`phase: open` 和当前 Run 的待执行 Action;缺少这些字段时才运行 `comet state next <name> --json` 补读。随后运行一次 `comet classic openspec --agent-json -- status --change "<name>" --json` 并执行兼容性预检:
140
+
141
+ - `changeRoot` 解析后必须等于路径解析器绑定的 `<classic-change-dir>`,`planningHome`(如存在)也必须位于当前仓库;不支持仓库外的产物路径
142
+ - `artifacts` 必须包含 Classic 必需 ID `proposal`、`tasks`,其他要求沿 `requires` 递归展开
143
+ - `applyRequires` 必须是可解析的产物 ID 列表;直接引用和间接依赖的产物都必须存在,且不能循环依赖
144
+ - 返回数据缺少字段、路径越界或必需 ID 缺失时,立即停止,不能改用猜测的固定模板
145
+
146
+ 预检通过后,按 OpenSpec CLI 返回的 schema 和依赖图生成实施所需的产物:
147
+
148
+ Agent JSON 模式下,从 `data.upstream.data` 读取上游字段。下一步必须使用 `data.nextAction` 返回的完整 argv,并在其指定的 cwd 执行;上游原始 nextSteps 仅用于诊断。
149
+
150
+ **根据 OpenSpec 状态逐项生成产物**:
151
+
152
+ 1. 首轮复用 Step 2 兼容性预检刚返回的 status;后续复用上一轮写入后刷新的 status。只有恢复或外部产物变化时重新运行 `comet classic openspec --agent-json -- status --change "<name>" --json`,从 `data.upstream.data` 读取完整上游 JSON。
153
+ 2. 展开 `applyRequires` 加 proposal/tasks 的完整依赖闭包。闭包中每项都为 `done` 或合法 `skipped` 时,适配器在同一次 status 调用中校验完整闭包和实际文件;仅当调用成功且 `data.artifactRequirements.problems` 为空时退出循环。顶层 tasks 已完成不能掩盖未完成依赖。`isComplete` 只作诊断。
154
+ 3. 在尚未完成、状态为 `status: "ready"` 的产物中,优先处理 `applyRequires` 所需的依赖,并遵循 CLI 返回的顺序。不得写死生成顺序,也不能假设 schema 只有 proposal/design/tasks。
155
+ 4. 对每个 ready 的 `<artifact-id>` 获取实时指令:
156
+
157
+ ```bash
158
+ comet classic openspec --agent-json -- instructions <artifact-id> --change "<name>" --json
159
+ ```
160
+
161
+ 5. 根据返回的 JSON 指令,必须完成以下操作:
162
+ - 读取 `dependencies` 中列出的每个已完成依赖产物
163
+ - 以 `template` 作为产物结构
164
+ - 遵循 `instruction` 的指引
165
+ - 遵守 `context` 和 `rules` 中的约束,**不得将这些内容复制到产物中**
166
+ - 写入 `resolvedOutputPath`;通配输出必须按 instruction 创建每个实际文件
167
+ - 验证 CLI 返回的实际输出文件存在且非空
168
+ 6. 每创建一个产物并确认实际输出文件存在且非空后,执行 instructions 响应中 `data.nextAction` 指定的 status 命令,读取更新后的依赖和 ready 项。循环中不插入 `state artifacts`;该命令仍可单独诊断,但会重新查询 OpenSpec。已经变为 `done` 的项不得重复生成;只处理闭包中新增的 ready 项,不额外生成无关的可选产物。
169
+
170
+ **阻塞与失败处理**:`applyRequires` 尚未全部完成、但其所需依赖中已没有 ready 产物时,必须报告相关 `blocked` 产物的 `missingDeps`,然后停止。不得猜测生成顺序或跳过依赖。适配器的 `status` / `instructions` 调用失败、返回无效 JSON、产物路径超出仓库,或未提供可用的 `resolvedOutputPath` 时,也必须立即停止并报告 OpenSpec 错误,不能改用写死的文档结构。
171
+
172
+ **核对名称和变更范围**:change name 必须使用 Step 1b 解析出的 kebab-case 英文名,不得使用非 kebab-case(如中文)名称。变更范围必须与 resolved brief 和用户描述一致,不得自行扩大或缩小。
173
+
174
+ 确认以下产物已创建:
175
+
176
+ ```
177
+ <classic-change-dir>/
178
+ ├── .openspec.yaml
179
+ ├── proposal.md # Why + What:问题、目标、范围
180
+ ├── design.md # 仅在依赖要求或实际需要时创建,保存技术决策,不复制到第二份设计文档
181
+ └── tasks.md # 任务清单(勾选框)
182
+ ```
183
+
184
+ SDK Run 保存在用户级工作区 Runtime 目录;新 change 保存 `comet-state.yaml`,历史 `.comet.yaml` 原地保留;恢复时通过 `state next` 和 `state check` 读取 Run,不直接编辑 Run 的存储文件。
185
+
186
+ ### 3. 入口状态验证
187
+
188
+ 已有初始化或选择成功返回的同一 Run、Open phase、工作区和 revision 时,直接继续 Step 4。冷恢复、外部状态变化或必要信息缺失时才验证初始化状态:
189
+
190
+ ```bash
191
+ comet state check <name> open
192
+ ```
193
+
194
+ 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
195
+
196
+ **恢复未完成的创建步骤**:open 阶段的操作允许安全重试;恢复时按以下顺序识别已完成的部分,只补未完成的工作:
197
+
198
+ 1. 先运行 `comet state next <name> --json` 确认归属。`runtimeFormat: sdk` 时复用原 Run;`runtimeFormat: compat` 时保留原流程。只有证实没有 Run、归属记录及新旧两种状态文件,才准备工作区并运行 `comet state init <name> full --isolation <selected-isolation>`;格式异常或归属冲突时停止,不覆盖。随后选择 change 并运行 `comet state check <name> open`。
199
+ 2. 运行 `comet classic openspec --agent-json -- status --change "<name>" --json`,重新验证 `changeRoot`、核心 ID、`applyRequires`、`artifacts` 和 `missingDeps`。
200
+ 3. `done`:该产物已完成,保持原文件不变,不重复生成。
201
+ 4. `ready`:依赖已经满足,可以生成。先运行 `comet classic openspec --agent-json -- instructions <artifact-id> --change "<name>" --json`,按返回内容写入;检查实际输出后按 `data.nextAction` 刷新 status。
202
+ 5. `blocked`:读取 `missingDeps`,先完成属于 `applyRequires` 依赖闭包的依赖产物,再刷新 status,不能直接生成 blocked 产物。
203
+ 6. 重复上述处理,直到完整必需闭包为 done 或合法 skipped,且本次 status 成功返回 `data.artifactRequirements.problems: []`。
204
+
205
+ 如果必需依赖仍无法完成,必须列出相关 blocked 产物及其 `missingDeps`,然后停止并报告。不能仅凭目录或三个固定文件存在,就替代 CLI 的检查结论;也不能因为 `isComplete: false`,就让不属于 `applyRequires` 的可选产物阻止流程进入实施阶段。
206
+
207
+ ### 4. 内容完整性检查
208
+
209
+ 使用最近一次 status 成功返回的 `data.artifactRequirements` 核对必需产物;文件或 schema 变化后必须重新运行 status。冷恢复时也重新查询,不使用上次会话保存的闭包替代当前检查。任一问题未解决时,不得进入 Step 5 或执行阶段守卫。
210
+
211
+ 随后检查关键产物的内容:proposal 应说明问题、目标、范围和非目标;design 应说明高层决策与数据流;tasks 应列出明确任务。schema 返回 specs 等其他产物时,也必须按对应的 instructions 检查内容,不能因为 proposal、design、tasks 三个文件已经存在就跳过。
212
+
213
+ ### 5. 核对授权并完成 Open
214
+
215
+ 全部 OpenSpec 产物完成且内容完整性检查通过后,使用当前有效响应的 `runtimeFormat`;归属信息缺失或发生外部变化时才运行 `comet state next <name> --json`。SDK change 再运行 `comet guard <change-name> open --json` 取得预检结果、内容摘要和 `data.approvalHash`;预检未通过时先修复问题。随后按 `comet-classic/reference/decision-point.md` 核对授权;没有覆盖当前产物的有效授权时,先请用户决定,再应用阶段守卫。
216
+
217
+ 最终审视核对 change 名称、范围和产物内容是否符合已获授权的要求;名称与范围已明确时,不另加常规摘要或命名确认。
218
+
219
+ 按 `comet-classic/reference/decision-point.md` 核对当前产物与已有授权。授权仍覆盖当前内容时,记录依据并继续;需要新决定时才展示待确认内容并等待答复。
220
+
221
+ 需要用户确认时,以单选题形式呈现,包含以下摘要和选项:
222
+
223
+ **摘要内容**:
224
+
225
+ - **change 名称与 resolved brief**:最终名称、目标、非目标、范围边界和关键未知项
226
+ - **proposal.md**:问题背景、目标、范围
227
+ - **schema 要求的 specs 等产物**:功能、需求和关键验收场景
228
+ - **design.md**:高层架构决策、方案选型
229
+ - **tasks.md**:任务数量和关键任务描述
230
+
231
+ **选项**:
232
+
233
+ - 「确认,继续下一阶段」— 产物符合预期,执行阶段守卫流转
234
+ - 「需要调整」— 附带调整说明,修改后重新请求确认
235
+
236
+ 用户选择「确认」后继续执行退出条件。SDK change 必须沿用向用户展示的同一次预检返回的 `approvalHash`;用户选择「需要调整」时,按其说明修改对应文件,重新预检并请求确认,不能沿用旧哈希。
237
+
238
+ ## 退出条件
239
+
240
+ - `comet state artifacts <name> --json` 通过:完整必需闭包已完成或合法跳过,所需实际输出非空
241
+ - **用户已确认** 全部 OpenSpec 产物的内容符合预期
242
+ - **阶段守卫**:SDK change 使用当前预检的 `approvalHash` 应用;旧 change 保留原有 `comet guard <change-name> open --apply`。全部 PASS 后由守卫推进到下一阶段。
243
+
244
+ 退出前必须应用阶段守卫,否则 Run 或旧 `.comet.yaml` 仍停留在 Open,下一阶段入口检查会失败。SDK 预检后若产物变化,应重新预检并让用户确认当前内容,不能拿旧哈希重试。
245
+
246
+ ```bash
247
+ comet guard <change-name> open --apply --approval-hash <approvalHash> # SDK
248
+ comet guard <change-name> open --apply # legacy
249
+ ```
250
+
251
+ 完整流程会自动更新为 `phase: design`;hotfix/tweak 预设会自动更新为 `phase: build`。
252
+
253
+ ## 自动衔接下一阶段
254
+
255
+ SDK change 优先使用成功结果中同一 Run 的 `nextAction.kind`、phase 和 `agent.continuation` 继续;缺少时才运行 `comet state next <change-name> --json`:`action` 才加载返回的 Skill;`decision`、`evidence`、`reconcile` 先进入对应恢复步骤,不自动重放。旧 change 按 `comet-classic/reference/auto-transition.md` 和成功结果中的 `agent.continuation` 继续。已有仍然有效的状态信息时,不重复 next、select 或 check。只有丢失上下文后恢复任务、外部状态变化,或旧结果未提供这些信息时,才运行:
256
+
257
+ ```bash
258
+ comet state next <change-name>
259
+ ```
260
+
261
+ - `NEXT: auto` → 调用 `SKILL` 指向的 skill 进入下一阶段
262
+ - `NEXT: manual` → 不调用下一 skill,按 `HINT` 交还控制权并结束当前调用;不再创建确认点
263
+ - `NEXT: done` → 流程已完成,无需继续
264
+
265
+ hotfix/tweak 预设由对应预设 Skill 控制后续流转(phase 直接进入 build),其 `next` 会返回对应预设 Skill。
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: 'Comet Classic 阶段 1:开启'
3
+ short_description: '创建 Classic change,整理需求文档并请用户确认范围与内容'
4
+ policy:
5
+ allow_implicit_invocation: true
@@ -0,0 +1,51 @@
1
+ # PRD 拆分与批量恢复
2
+
3
+ 用户提供大型 PRD、路线图或完整产品方案,或澄清摘要显示包含多个独立功能、模块、用户操作流程或里程碑时,必须先评估是否需要拆分为多个 change,再创建 OpenSpec 产物。
4
+
5
+ 拆分预检必须基于已澄清的信息,输出候选拆分清单。每个候选拆分项必须包含:
6
+
7
+ - 建议 change 名称
8
+ - 目标与范围边界
9
+ - 明确非目标
10
+ - 依赖关系或推荐执行顺序
11
+ - 对应的核心验收场景
12
+
13
+ 满足任一条件时,应推荐拆分:
14
+
15
+ - PRD 包含多个可以独立设计、构建、验证和归档的功能
16
+ - 涉及多个模块或用户路径,且其中一部分可独立交付
17
+ - 存在明显分阶段里程碑
18
+ - 多个 delta spec 对应可分别验收与交付的独立目标;文档或任务数量本身不决定拆分
19
+ - 任一部分失败或延期不应阻塞其他部分进入后续阶段
20
+
21
+ 如推荐拆分,必须按 `comet-classic/reference/decision-point.md` 的协议暂停并等待用户选择。
22
+
23
+ 用户选择必须包含:
24
+
25
+ - 「创建多个 OpenSpec changes」— 按候选拆分逐个创建独立 change
26
+ - 「保持为一个 change」— 继续单 change 流程,并在 proposal/design/tasks 中记录不拆分原因
27
+ - 「调整拆分方案后继续」— 用户说明调整方向后,重新输出候选拆分清单并再次确认
28
+
29
+ 每个被接受的拆分项都必须通过 `/comet-open` 创建独立 change,不得直接调用 `/opsx:new`。`/comet-open` 负责创建 OpenSpec 产物并初始化独立的 SDK Run,确保每个 change 都由 Comet 管理。
30
+
31
+ 不得在用户完成 PRD 拆分选择前创建 proposal.md、design.md 或 tasks.md。若用户选择创建多个 change,当前 `/comet-open` 调用只负责完成拆分确认与调度,随后按用户确认的顺序分别进入每个拆分项的 `/comet-open`。
32
+
33
+ 用户确认创建多个 changes 后,必须立即把确认结果保存到 `.comet/batches/<batch-id>.json`。`batch-id` 使用固定的 kebab-case 标识。文件至少记录 `version`、原始目标摘要、创建时间、按顺序排列的 change 名称,以及每项的目标、范围、非目标、验收场景和 `pending|open-complete|selected` 状态。每创建或完成一个拆分项,都要原子更新该文件。这份清单用于记录批量创建顺序和进度,不替代各 change 的 SDK Run。
34
+
35
+ 批量拆分模式下,进入每个拆分项的 `/comet-open` 时,必须明确标注「已确认拆分项」,并传入该项的目标、范围、非目标和验收场景。已确认的拆分项默认跳过 PRD 拆分预检,除非该项本身仍明显包含多个独立功能。
36
+
37
+ 批量拆分模式下,单个拆分项完成 open 阶段后,不得自动进入 `/comet-design`。拆分完成后,必须暂停,请用户选择从哪一个 change 开始。只将用户选中的 change 推进到 `/comet-design`;其他 change 保持未归档状态,稍后通过 `/comet-classic` 恢复。
38
+
39
+ **逐项检查批量创建结果(不得跳过)**:全部拆分项完成各自的 open 阶段后,对用户确认清单中的每个 `<name>` 逐个运行:
40
+
41
+ ```bash
42
+ comet state check <name> design --json
43
+ ```
44
+
45
+ 该入口已检查 OpenSpec 的全部必需依赖、实际输出和 Comet 状态,不再额外重复查询 status。`isComplete` 仅用于诊断,非必需产物不会阻止流程继续。检查失败时,再查询 status,找出尚未生成的依赖,或处理已报告的路径错误、缺少必需能力等问题。
46
+
47
+ 任一拆分项未通过检查时,不能宣告拆分完成,也不能询问用户开始哪个 change。应停止后续推进,从该 change 的第一个 `ready` 或 `blocked` 产物恢复 `/comet-open`。OpenSpec 检查通过、但 Comet state 检查失败时,先核对该 change 的 Runtime 归属、Run 和 phase,再重新执行整批检查;`compat` change 按原状态机恢复。
48
+
49
+ 只有所有拆分项都通过入口检查后,才暂停,请用户选择从哪一个 change 开始。用户选择后,将批量清单中的该项标记为 `selected`,只推进该 change 进入 `/comet-design`;其他 change 保持未归档状态,稍后通过 `/comet-classic` 恢复。
50
+
51
+ 中断后恢复时,先读取 `.comet/batches/<batch-id>.json`,再对清单中已创建且未归档的 changes 运行上述 CLI 检查。已完整通过的拆分项不得重复创建;未通过的拆分项,从 OpenSpec 返回的第一个 `ready` 产物继续。尚未创建的项,按已保存的清单继续创建。清单缺失或损坏时,停止并请用户重建或确认,不能从目录列表猜测原来这一批包含哪些 change。
@@ -0,0 +1,121 @@
1
+ ---
2
+ name: comet-review
3
+ description: '手动审查当前 Comet change 的实现差异,只报告正确性、安全和边界问题,不推进工作流。'
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Comet 手动代码审查
8
+
9
+ 对当前选中的 Comet change 执行一次按需、只读的代码审查。这个入口不属于任何阶段,也不替代 Build 或 Verify 的验证和审查。
10
+
11
+ 本入口独立于 `review_mode`。`review_mode` 控制流程内的自动审查策略,`/comet-review` 则由用户手动触发,只执行一次审查;调用本入口不得读取、修改或覆盖当前 change 的 `review_mode`。
12
+
13
+ ## 只执行读取和审查操作
14
+
15
+ 本 Skill 的整个调用必须保持只读:
16
+
17
+ - 不修改、创建或删除文件;
18
+ - 不暂存、提交、切换分支、创建分支或创建 worktree;
19
+ - 不运行 `comet state select`、`comet native select`、`comet state set`、`comet state transition`、阶段守卫、`comet native next` 或归档命令;
20
+ - 不修复发现的问题,不推进 phase,不更新 tasks、状态、验证报告或审查记录;
21
+ - 不把本次结果称为 Verify 通过,也不把“没有发现”视为测试已经通过。
22
+
23
+ 只允许执行读取文件、查询状态和查看 Git 差异所需的命令。任何可能运行项目代码、安装依赖或产生文件的检查都不属于本入口。
24
+
25
+ ## 1. 定位项目与当前 change
26
+
27
+ 1. 使用只读 Git 查询确定项目根目录;如果不是 Git 仓库,则使用当前 Comet 项目根目录。
28
+ 2. 在项目根目录运行:
29
+
30
+ ```bash
31
+ comet status . --json
32
+ ```
33
+
34
+ 3. 读取 `.comet/current-change.json`,并按以下顺序确定审查对象:
35
+ - 文件包含有效的 `comet.selection.v2` 时,使用其中的 `workflow` 和 `change`;
36
+ - 没有 selection 记录,且状态输出中只有一个未归档的 Comet change 时,只在本次审查中使用该 change,不写入 selection;
37
+ - 没有 selection 记录且存在多个 change 时,列出名称、workflow 和 phase,请用户指定一个,然后停止当前调用;
38
+ - selection 指向缺失、已归档或状态无效的 change 时,报告当前选择已过期或无效(stale/invalid selection),然后停止,不自行修复。
39
+
40
+ 忽略不受 Comet 管理的普通 OpenSpec change。不得因为默认 workflow 与 selection 不同而改用默认 workflow。
41
+
42
+ ## 2. 收集审查上下文
43
+
44
+ 只读取当前 change 的必要上下文,并为每个事实保留来源路径或命令。
45
+
46
+ ### Classic
47
+
48
+ 1. 先读取并遵守 `comet-classic/reference/classic-layout.md`,解析当前项目的 Classic 逻辑根。
49
+ 2. 读取当前 change 的 `proposal.md`、`design.md`、`tasks.md` 和 `specs/*/spec.md`;存在关联 Design Doc 时一并读取。
50
+ 3. 使用以下只读状态查询获得 phase、基线和已有证据引用:
51
+
52
+ ```bash
53
+ comet state get <change-name> phase
54
+ comet state get <change-name> base_ref
55
+ comet state get <change-name> plan
56
+ comet state get <change-name> verification_report
57
+ ```
58
+
59
+ 4. 读取已有的 plan、验证报告,以及 `comet status . --json` 返回的 build/verify 命令检查结果。缺失的证据应标为“未提供”,不能推断为失败或通过。
60
+
61
+ ### Native
62
+
63
+ 运行以下只读命令:
64
+
65
+ ```bash
66
+ comet native show <change-name> --json
67
+ comet native status <change-name> --details --json
68
+ ```
69
+
70
+ 根据返回的引用,读取 brief、完整的拟议规格(proposed Specs)、acceptance、Builder handoff、checks、verification、risks、blockers 和验证报告(verification report)。只使用当前 candidate/iteration 的证据;历史轮次只用于解释尚未消除的风险,不能据此覆盖当前状态。
71
+
72
+ ## 3. 确定实现差异
73
+
74
+ 1. 先运行 `git status --short --untracked-files=all`,列出工作区中全部已暂存、未暂存和未跟踪的文件。
75
+ 2. 结合当前 change 的需求、工作区绑定、Git 历史和工作树状态,确定最可信且与当前 change 相关的审查范围。对于 Classic,优先使用有效的 plan `base-ref`;不存在或无效时回退到状态中的 `base_ref`,不要求两者一致。只有两者均无效时,才将 Classic 基线视为缺失。对于 Native,将状态中的工作区关系和当前 candidate 的实现范围证据作为判断依据。
76
+ 3. 查看从可信基线到当前工作树的完整差异,包括已提交、已暂存和未暂存修改。对属于当前 change 的所有未跟踪文件,包括源码、测试、文档、配置和元数据(例如 `SKILL.md` 与 `agents/openai.yaml`),直接读取内容并明确标注其未跟踪状态。
77
+ 4. 排除明确归属于其他 change 或用户无关工作的差异。只有歧义会实质影响审查结论时才询问用户;否则基于现有证据继续审查,并在结果中说明范围判断和假设。
78
+
79
+ 如果结合上述证据仍无法确定可信且可验证的基线,继续审查当前可见的工作树差异,并在结果中显著标注“审查范围不完整”。
80
+
81
+ ## 4. 执行审查
82
+
83
+ 根据需求、任务和当前差异进行一次聚焦审查,只检查:
84
+
85
+ - 实现正确性和明显逻辑错误;
86
+ - 安全风险、权限或路径边界问题;
87
+ - 错误处理、兼容性和重要边界条件;
88
+ - 任务遗漏、实现与当前 change 明确要求不一致;
89
+ - 测试是否覆盖本次行为变化,以及已有测试证据能否支撑相应结论。
90
+
91
+ 不要把风格偏好、无关重构或没有具体影响的猜测列为审查问题。每条问题都必须指向具体文件和行号,并说明什么情况会触发错误或风险。证据不足时,降低严重程度或放入“开放问题”。
92
+
93
+ 严重度仅使用:
94
+
95
+ - `CRITICAL`:安全破坏、数据丢失或核心流程不可用;
96
+ - `IMPORTANT`:明确的正确性错误、核心验收遗漏或高概率回归;
97
+ - `WARNING`:真实但非阻塞的边界风险或测试缺口;
98
+ - `SUGGESTION`:有明确收益但不影响当前正确性的改进。
99
+
100
+ ## 5. 输出
101
+
102
+ 先列出发现的问题,按严重程度排序。每条使用以下格式:
103
+
104
+ ```text
105
+ [IMPORTANT] 简短标题 — path/to/file.ts:123
106
+ 影响:什么输入或场景会出现什么错误。
107
+ 依据:与 diff、任务、规格或证据的具体对应关系。
108
+ ```
109
+
110
+ 随后输出:
111
+
112
+ - `审查范围`:workflow、change、phase、基线、纳入的差异和任何范围限制;
113
+ - `证据状态`:已读取哪些测试、构建和验证记录,以及这些记录是否仍适用于当前改动;不重新执行测试;
114
+ - `开放问题`:只有确实阻碍判断的问题;
115
+ - `结论`:汇总发现的问题数量,或明确写“未发现具体问题”。
116
+
117
+ 即使没有发现问题,也必须说明尚存的风险和未执行的检查。结尾固定提醒:
118
+
119
+ > 这是只读的手动审查,不会推进 Comet phase,也不能替代 `/comet-verify` 或 Native Verify。
120
+
121
+ 如果用户随后要求修复审查发现的问题,将修复作为新的写入任务处理:退出本 Skill,按仓库当前工作流规则重新进入开发流程。
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: 'Comet 手动代码审查'
3
+ short_description: '只读审查当前 change,报告问题及依据,不推进工作流'
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: comet-tweak
3
+ description: '使用 Classic 预设流程完成单个 change 的轻量调整。在用户明确调用 /comet-tweak、选择 tweak,或恢复 workflow: tweak 时使用。'
4
+ ---
5
+
6
+ # Comet 预设路径:Tweak
7
+
8
+ 开始或恢复任务前,必须先读取并遵守 `comet-classic/reference/classic-layout.md`。本文件中的 OpenSpec CLI 调用必须通过适配器执行,文件路径必须基于该协议绑定的 `<classic-*>` 逻辑根目录。
9
+
10
+ Tweak 为 Comet 五阶段流程提供一组预设配置。它通过 OpenSpec 完成需求与实施工作,复用 open、build、verify、archive 阶段,跳过 Superpowers brainstorming 和完整实施计划,不另建一套独立流程。
11
+
12
+ 适用于配置调整、文档或提示词优化等轻量改动,也适用于需要依据 spec(含 delta spec)实施、但不需要完整 `/comet-classic` 深度设计的中等变更。Tweak 正常支持 delta spec,不能仅因为需要 delta spec 就要求升级流程。
13
+
14
+ **适用条件**(必须全部满足):
15
+
16
+ 1. 可以在**单个 OpenSpec change** 中完成
17
+ 2. 无需通过 Superpowers Design Doc 和完整实施计划,就能明确方案
18
+ 3. 不涉及跨模块、跨层级的架构协调
19
+ 4. 任务规模可预估(文件数和任务数仅作提示,不会自动要求升级,见 SDK 方法参考的预设范围复核)
20
+
21
+ **不适用**:变更过程中如发现 SDK 方法参考的预设范围复核列出的变化,需要由用户决定是否改用完整 `/comet-classic` 流程。
22
+
23
+ 首次进入阶段、交接给新 Agent 或上下文恢复后,读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言),优先采用当前 continuation 或已领取 Action 的 `contextRequest`;同一阶段连续执行不重复获取。
24
+
25
+ 个人记忆只保存可复用用户信息,不写入任务摘要、进展、命令输出或测试结果。
26
+
27
+ ## SDK Run 路径
28
+
29
+ 先读取并执行[普通命令与检查](../comet/reference/platform-execution.md)。新旧 Run 均使用平台工具执行普通命令,在原 Run 提交实际检查报告;自动升级不恢复旧检查执行器。阶段准备、用户选择、任务完成和验收要求继续有效。
30
+
31
+ 首次进入当前 SDK 阶段、换 Agent 或恢复上下文时,读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节;本会话已有且仍有效时直接复用。下文按当前阶段执行;`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。
32
+
33
+ 开始或恢复时,优先复用当前有效结果中的 `agent.continuation` / `data.nextAction` 及已绑定的 change、工作区、phase 和 Run revision,按已知的 `data.runtimeFormat` 路由。只有冷恢复、外部状态变化或缺少这些信息时,才运行 `comet state next <change-name> --json`。`sdk` 只按本节推进;SDK 方法参考的适用条件、OpenSpec apply 方法、升级判定和文件数授权规则仍适用,状态与证据通过本节命令提交。若 `nextAction.kind` 为 `reconcile`,运行 `comet state check <change-name> <phase> --recover --json` 核对原 Action;结果未明时不重做实现、检查或归档。
34
+
35
+ 1. 新建时先按 [工作区选择](../comet-classic/reference/workspace.md) 确定隔离方式,运行 `comet classic workspace prepare <name> --isolation <selected-isolation> --json`,进入返回的 `projectRoot`,先按 [开始与产物](../comet-classic/reference/sdk-methods.md#开始与产物) 创建 OpenSpec 基础目录,再运行 `comet state init <name> tweak --isolation <selected-isolation>`,随后运行 `comet state select <name>` 绑定 Hook 路由。按 SDK 方法参考的开始与产物章节创建 OpenSpec 产物,包括本次确需的 delta spec;运行 `comet guard <change-name> open --json` 预览确认内容,保存返回的 `data.approvalHash`。向用户展示本次 Open 产物与范围,获得明确批准后,运行 `comet guard <change-name> open --apply --approval-hash <approvalHash>`。产物变化后必须重新预览并确认,不复用旧哈希。只有 Run 进入 Build,Open 才完成。
36
+ 2. `tweak.build.execute` 待执行时,沿用本次 change、工作区和 Run,直接恢复 Build,不重新初始化或重跑 Open。按 SDK 方法参考的预设范围复核章节的 OpenSpec apply 方法读取指令与上下文,逐项实施并勾选同一 tasks.md。出现实质升级信号或文件数超限且无有效授权时,先运行 `comet state propose-escalation <change-name> --reason "<reason>"`;向用户展示当前原因和继续 tweak / 升级 full 的影响,并保存返回的 `data.wait.proposalHash`。用户明确选择后运行 `comet state decide-escalation <change-name> --proposal-hash <proposalHash> --choice <continue|upgrade>`。`continue` 仍须满足 SDK 方法参考的范围、风险与 ruling 要求;`upgrade` 在同一个 Run 和工作区进入 full Design,立即按入口加载 comet-design。恢复待决定 Wait 时复用原提案,不重新提案或替用户选。
37
+ 3. 所有任务完成、必要检查与审查完成且仍适合当前预设时,运行 `comet state complete-build <change-name> --session <builder-execution-ref> --checks <checks-json-file>` 提交实际结果。此处没有新的用户决定;Runtime 核对当前任务、配置、工作区和报告后进入 Verify。失败或结果未明时按返回的当前 Action 核对原任务,不重复执行。
38
+ 4. Run 进入 Verify 时,**立即执行:** 使用 Skill 工具加载 comet-verify 技能。禁止跳过此步骤。若有 delta spec,按 SDK 方法参考的完整验证方法覆盖其一致性,不调用旧 `state set verify_mode`。Run 进入 Archive 时,**立即执行:** 使用 Skill 工具加载 comet-archive 技能。禁止跳过此步骤。归档和交付仍须获得用户当前授权;当前成功结果显示 Run 完成后才能宣告完成;缺少完成状态时再读 `state next --json`。
39
+
40
+ 每次推进后,优先使用同次结果的 `agent.continuation` / `data.nextAction`;状态仍有效且信息完整时,不重复 next、select 或 check。仅在冷恢复、外部状态变化或缺少必要信息时补读。`decision`、`evidence`、`reconcile` 先处理当前 Run 的等待或恢复;`action` 才执行对应步骤。
41
+ SDK Build 使用真实的 `--session <builder-execution-ref>` 关联执行;已经携带时无需再次传入。
42
+
43
+ ## Compat 路径
44
+
45
+ 以下旧 Runtime 步骤仅用于 `runtimeFormat: compat`。必须读取 [Compat 操作](reference/compat.md),按其中当前阶段继续;SDK 不加载该参考。
46
+
47
+ ## 可选变更说明
48
+
49
+ Build 收尾和 Verify 展示结果前,先核对项目 `.comet/config.yaml` 的 `change_walkthrough`(默认开启;仅显式 `false` 关闭)。开启时读取并执行[变更说明](../comet/reference/change-walkthrough.md),用共享模板生成或更新同一 `walkthrough.html` 并给出打开链接;关闭时跳过额外讲解、详细指引和渲染,保留原有摘要。Archive 只随现有材料保存已有页面并提供实际归档链接,不补生成、不新增确认、不为页面更新重跑代码检查。
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: 'Comet Classic 预设:Tweak'
3
+ short_description: '在单个 change 中完成轻量或中等调整,按需维护增量规格'
4
+ policy:
5
+ allow_implicit_invocation: true