@rpamis/comet 0.1.7 → 0.2.0

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 (67) hide show
  1. package/README.md +45 -13
  2. package/assets/manifest.json +2 -0
  3. package/assets/skills/comet/SKILL.md +214 -219
  4. package/assets/skills/comet/scripts/comet-archive.sh +8 -2
  5. package/assets/skills/comet/scripts/comet-guard.sh +32 -22
  6. package/assets/skills/comet/scripts/comet-state.sh +496 -0
  7. package/assets/skills/comet-archive/SKILL.md +6 -19
  8. package/assets/skills/comet-build/SKILL.md +16 -23
  9. package/assets/skills/comet-design/SKILL.md +7 -23
  10. package/assets/skills/comet-hotfix/SKILL.md +136 -167
  11. package/assets/skills/comet-open/SKILL.md +9 -31
  12. package/assets/skills/comet-tweak/SKILL.md +122 -154
  13. package/assets/skills/comet-verify/SKILL.md +11 -33
  14. package/assets/skills-zh/comet/SKILL.md +87 -92
  15. package/assets/skills-zh/comet-archive/SKILL.md +63 -76
  16. package/assets/skills-zh/comet-build/SKILL.md +153 -160
  17. package/assets/skills-zh/comet-design/SKILL.md +91 -107
  18. package/assets/skills-zh/comet-hotfix/SKILL.md +18 -49
  19. package/assets/skills-zh/comet-open/SKILL.md +70 -92
  20. package/assets/skills-zh/comet-tweak/SKILL.md +19 -51
  21. package/assets/skills-zh/comet-verify/SKILL.md +114 -136
  22. package/dist/cli/index.js +28 -1
  23. package/dist/cli/index.js.map +1 -1
  24. package/dist/commands/doctor.d.ts +6 -0
  25. package/dist/commands/doctor.d.ts.map +1 -0
  26. package/dist/commands/doctor.js +168 -0
  27. package/dist/commands/doctor.js.map +1 -0
  28. package/dist/commands/init.d.ts +9 -0
  29. package/dist/commands/init.d.ts.map +1 -0
  30. package/dist/commands/init.js +183 -0
  31. package/dist/commands/init.js.map +1 -0
  32. package/dist/commands/status.d.ts +6 -0
  33. package/dist/commands/status.d.ts.map +1 -0
  34. package/dist/commands/status.js +89 -0
  35. package/dist/commands/status.js.map +1 -0
  36. package/dist/commands/update.d.ts +8 -0
  37. package/dist/commands/update.d.ts.map +1 -0
  38. package/dist/commands/update.js +47 -0
  39. package/dist/commands/update.js.map +1 -0
  40. package/dist/core/detect.d.ts +8 -0
  41. package/dist/core/detect.d.ts.map +1 -0
  42. package/dist/core/detect.js +73 -0
  43. package/dist/core/detect.js.map +1 -0
  44. package/dist/core/openspec.d.ts +5 -0
  45. package/dist/core/openspec.d.ts.map +1 -0
  46. package/dist/core/openspec.js +58 -0
  47. package/dist/core/openspec.js.map +1 -0
  48. package/dist/core/platforms.d.ts.map +1 -1
  49. package/dist/core/platforms.js +6 -1
  50. package/dist/core/platforms.js.map +1 -1
  51. package/dist/core/skills.d.ts +22 -0
  52. package/dist/core/skills.d.ts.map +1 -0
  53. package/dist/core/skills.js +59 -0
  54. package/dist/core/skills.js.map +1 -0
  55. package/dist/core/superpowers.d.ts +5 -0
  56. package/dist/core/superpowers.d.ts.map +1 -0
  57. package/dist/core/superpowers.js +60 -0
  58. package/dist/core/superpowers.js.map +1 -0
  59. package/dist/core/types.d.ts +2 -0
  60. package/dist/core/types.d.ts.map +1 -0
  61. package/dist/core/types.js +2 -0
  62. package/dist/core/types.js.map +1 -0
  63. package/package.json +61 -50
  64. package/dist/core/init.d.ts +0 -14
  65. package/dist/core/init.d.ts.map +0 -1
  66. package/dist/core/init.js +0 -492
  67. package/dist/core/init.js.map +0 -1
@@ -1,76 +1,63 @@
1
- ---
2
- name: comet-archive
3
- description: "Comet 阶段 5:归档。用 /comet-archive 调用。同步 delta spec 到主 spec,归档 change。"
4
- ---
5
-
6
- # Comet 阶段 5:归档(Archive)
7
-
8
- ## 前置条件
9
-
10
- - 验证已通过(阶段 4 完成)
11
- - 分支已处理
12
- - `openspec/changes/<name>/.comet.yaml` 中 `verify_result: pass`
13
-
14
- ## 步骤
15
-
16
- ### 0. 入口状态验证(Entry Check)
17
-
18
- 在执行任何操作之前,读取并验证当前状态:
19
-
20
- **检查清单:**
21
- 1. `openspec/changes/<name>/.comet.yaml` 存在
22
- 2. `phase` 字段的值为 `"archive"`
23
- 3. `verify_result` 字段的值为 `"pass"`
24
- 4. `archived` 字段为 `"false"` 或 null(尚未归档)
25
-
26
- **验证方式:**
27
- - `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
28
- - 如 `verify_result` 不是 `"pass"`,必须先完成验证
29
-
30
- **失败输出:**
31
- ```
32
- [HARD STOP] Entry check failed for comet-archive
33
- Expected: phase=archive, verify_result=pass, archived=false|null
34
- Actual: phase=<实际值>, verify_result=<实际值>, archived=<实际值>
35
- Suggestion: Run comet-verify first, or this change was already archived.
36
- ```
37
-
38
- 验证通过后才进入步骤 1。
39
-
40
- ### 1. 执行归档
41
-
42
- 运行归档脚本,自动完成以下全部步骤:
43
-
44
- ```bash
45
- COMET_ARCHIVE=$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)
46
- bash "$COMET_ARCHIVE" "<change-name>"
47
- ```
48
-
49
- 脚本自动执行:
50
- 1. 入口状态验证(phase=archive, verify_result=pass, archived=false)
51
- 2. Delta spec 同步到主 spec
52
- 3. Design doc 前置元数据标注(archived-with, status)
53
- 4. Plan 前置元数据标注(archived-with)
54
- 5. 移动 change 到归档目录
55
- 6. 更新 archived: true
56
-
57
- 如脚本返回非零退出码,报告错误并停止。
58
- 如脚本返回零退出码,归档完成。
59
-
60
- 如需预览而不实际执行,使用 `--dry-run` 参数。
61
-
62
- ### 2. 生命周期闭环
63
-
64
- Spec 生命周期在此完成:
65
- ```
66
- brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
67
- ```
68
-
69
- ## 退出条件
70
-
71
- - 归档脚本执行成功(退出码 0)
72
- - **阶段守卫**:运行 `bash $COMET_GUARD <change-name> archive`,全部 PASS 后确认归档完整
73
-
74
- ## 完成
75
-
76
- Comet 流程全部完成。如需开始新工作,调用 `/comet` 或 `/comet-open`。
1
+ ---
2
+ name: comet-archive
3
+ description: "Comet 阶段 5:归档。用 /comet-archive 调用。同步 delta spec 到主 spec,归档 change。"
4
+ ---
5
+
6
+ # Comet 阶段 5:归档(Archive)
7
+
8
+ ## 前置条件
9
+
10
+ - 验证已通过(阶段 4 完成)
11
+ - 分支已处理
12
+ - `openspec/changes/<name>/.comet.yaml` 中 `verify_result: pass`
13
+
14
+ ## 步骤
15
+
16
+ ### 0. 入口状态验证(Entry Check)
17
+
18
+ 执行入口验证:
19
+
20
+ ```bash
21
+ COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
22
+ bash "$COMET_STATE" check <name> archive
23
+ ```
24
+
25
+ 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
26
+
27
+ ### 1. 执行归档
28
+
29
+ 运行归档脚本,自动完成以下全部步骤:
30
+
31
+ ```bash
32
+ COMET_ARCHIVE="${COMET_ARCHIVE:-$(find . -path '*/comet/scripts/comet-archive.sh' -type f -print -quit)}"
33
+ bash "$COMET_ARCHIVE" "<change-name>"
34
+ ```
35
+
36
+ 脚本自动执行:
37
+ 1. 入口状态验证(phase=archive, verify_result=pass, archived=false)
38
+ 2. Delta spec 同步到主 spec
39
+ 3. Design doc 前置元数据标注(archived-with, status)
40
+ 4. Plan 前置元数据标注(archived-with)
41
+ 5. 移动 change 到归档目录
42
+ 6. 更新 archived: true
43
+
44
+ 如脚本返回非零退出码,报告错误并停止。
45
+ 如脚本返回零退出码,归档完成。
46
+
47
+ 如需预览而不实际执行,使用 `--dry-run` 参数。
48
+
49
+ ### 2. 生命周期闭环
50
+
51
+ Spec 生命周期在此完成:
52
+ ```
53
+ brainstorming delta spec → 实施 → 验证 → 主 spec 覆盖 → design doc 标注 → 归档
54
+ ```
55
+
56
+ ## 退出条件
57
+
58
+ - 归档脚本执行成功(退出码 0)
59
+ - **阶段守卫**:运行 `bash $COMET_GUARD <change-name> archive`,全部 PASS 后确认归档完整
60
+
61
+ ## 完成
62
+
63
+ Comet 流程全部完成。如需开始新工作,调用 `/comet` 或 `/comet-open`。
@@ -1,160 +1,153 @@
1
- ---
2
- name: comet-build
3
- description: "Comet 阶段 3:计划与构建。用 /comet-build 调用。制定计划并通过 subagent-driven-development 执行实施。"
4
- ---
5
-
6
- # Comet 阶段 3:计划与构建(Build)
7
-
8
- ## 前置条件
9
-
10
- - Design Doc 已创建(阶段 2 完成)
11
- - 活跃 change 存在
12
-
13
- ## 步骤
14
-
15
- ### 0. 入口状态验证(Entry Check)
16
-
17
- 在执行任何操作之前,读取并验证当前状态:
18
-
19
- **检查清单:**
20
- 1. `openspec/changes/<name>/.comet.yaml` 存在
21
- 2. `phase` 字段的值为 `"build"`
22
- 3. `design_doc` 字段非 null 且非空
23
- 4. `design_doc` 引用的文件存在(例如 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`)
24
- 5. `openspec/changes/<name>/proposal.md` 存在且非空
25
- 6. `openspec/changes/<name>/tasks.md` 存在且非空
26
-
27
- **验证方式:**
28
- - `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
29
- - 用 `ls` 或 `test -f` 确认 design_doc 文件存在
30
-
31
- **失败输出:**
32
- ```
33
- [HARD STOP] Entry check failed for comet-build
34
- Expected: phase=build, design_doc=<path> exists
35
- Actual: phase=<实际值>, design_doc=<实际值或文件不存在>
36
- Suggestion: Run comet-design first, or verify design_doc file exists.
37
- ```
38
-
39
- 验证通过后才进入步骤 1。
40
-
41
- ### 1. 制定计划
42
-
43
- **立即执行:** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
44
-
45
- 技能加载后,按其指引制定计划。计划要求:
46
- - 保存至 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
47
- - 引用设计文档,拆分为可执行任务
48
- - **Plan 文件头必须包含关联元数据**:
49
-
50
- ```yaml
51
- ---
52
- change: <openspec-change-name>
53
- design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
54
- ---
55
- ```
56
-
57
- ### 2. 更新计划状态
58
-
59
- 先记录 plan 路径:
60
-
61
- ```bash
62
- sed -i 's|^plan:.*|plan: docs/superpowers/plans/YYYY-MM-DD-feature.md|' openspec/changes/<name>/.comet.yaml
63
- ```
64
-
65
- 无需手动更新 phase,guard 会在退出条件满足后自动流转。
66
-
67
- ### 3. 工作区隔离
68
-
69
- 计划已写入当前分支。在开始执行前,选择工作区隔离方式:
70
-
71
- | 选项 | 方式 | 说明 |
72
- |------|------|------|
73
- | A | 创建分支 | 在当前仓库创建新分支,简单快速 |
74
- | B | 创建 Worktree | 隔离工作区,完全独立,适合并行开发 |
75
-
76
- **推荐规则**:
77
- - 变更涉及 3 个文件 → 推荐 A
78
- - 需要并行开发、当前分支有未提交工作 → 推荐 B
79
-
80
- 用户选择后,在 `openspec/changes/<name>/.comet.yaml` 中更新 `isolation`。`isolation` 只允许以下值之一:
81
-
82
- - `branch`
83
- - `worktree`
84
-
85
- **执行隔离**:
86
-
87
- - **branch**:执行 `git checkout -b <change-name>`,后续工作在新分支上进行
88
- - **worktree**:调用 `superpowers:using-git-worktrees` 技能或使用原生 `EnterWorktree` 工具创建隔离工作区
89
-
90
- 创建隔离后,确认计划文件可访问(分支方式天然可访问;worktree 方式需确认计划已提交)。
91
-
92
- ### 4. 选择执行方式
93
-
94
- 向用户展示计划摘要(任务数、涉及模块),然后询问执行方式:
95
-
96
- | 选项 | 技能 | 适用场景 |
97
- |------|------|---------|
98
- | A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
99
- | B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
100
-
101
- **推荐规则**:
102
- - 任务数 ≥ 3 → 推荐 A
103
- - 任务数 2 且无跨模块依赖 → 推荐 B
104
- - 来自 hotfix 路径 → 推荐 B
105
-
106
- 用户选择后,在 `openspec/changes/<name>/.comet.yaml` 中更新 `build_mode`。`build_mode` 只允许以下值之一:
107
-
108
- - `subagent-driven-development`
109
- - `executing-plans`
110
- - `direct`(仅 hotfix preset 使用)
111
-
112
- 然后,**立即执行:** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
113
-
114
- 如所选 Superpowers 技能不可用,停止流程并提示安装或启用对应技能,不要用普通对话替代该步骤。
115
-
116
- 技能加载后,按其指引执行:
117
- - 按计划执行任务
118
- - 完成 tasks.md 勾选(`- [ ]` → `- [x]`)
119
- - 每个任务完成后提交代码
120
-
121
- ### 5. Spec 增量更新
122
-
123
- 实施过程中发现初版 spec 不完整时,按变更规模分级处理:
124
-
125
- | 规模 | 触发条件 | 做法 |
126
- |------|---------|------|
127
- | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md,追加 tasks.md 任务 |
128
- | | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
129
- | | 全新 capability 需求 | `/opsx:new` 创建独立 change |
130
-
131
- **50% 阈值判定**:以 tasks.md 初始任务总数为基准,若新增任务数超过该总数的一半,视为超出原计划范围,应考虑拆分为新 change。
132
-
133
- **原则**:
134
- - delta spec 是活文档,本阶段期间随时可修改
135
- - 每次更新应提交,commit message 说明变更原因
136
- - 不提前同步到 main spec,归档时统一同步
137
- - 如增量任务超过原 tasks.md 初始任务总数 50%,考虑拆分为新 change
138
- - 小规模增量直接改 delta spec 时,应在 commit message 中注明,便于归档时判断 design doc 漂移
139
-
140
- ## 退出条件
141
-
142
- - tasks.md 全部勾选
143
- - 代码已提交
144
- - 测试通过
145
- - `.comet.yaml` 中 `phase` 已更新为 `verify`
146
- - **阶段守卫**:运行 `bash $COMET_GUARD <change-name> build`,全部 PASS 后才允许流转
147
-
148
- 退出前运行 guard 自动流转:
149
-
150
- ```bash
151
- bash $COMET_GUARD <change-name> build --apply
152
- ```
153
-
154
- 状态文件自动更新为 `phase: verify`、`verify_result: pending`。
155
-
156
- ## 自动流转
157
-
158
- 退出条件满足后,**无需等待用户再次输入**,直接执行下一阶段:
159
-
160
- > **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。
1
+ ---
2
+ name: comet-build
3
+ description: "Comet 阶段 3:计划与构建。用 /comet-build 调用。制定计划并通过 subagent-driven-development 执行实施。"
4
+ ---
5
+
6
+ # Comet 阶段 3:计划与构建(Build)
7
+
8
+ ## 前置条件
9
+
10
+ - Design Doc 已创建(阶段 2 完成)
11
+ - 活跃 change 存在
12
+
13
+ ## 步骤
14
+
15
+ ### 0. 入口状态验证(Entry Check)
16
+
17
+ 执行入口验证:
18
+
19
+ ```bash
20
+ COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
21
+ bash "$COMET_STATE" check <name> build
22
+ ```
23
+
24
+ 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
25
+
26
+ ### 1. 制定计划
27
+
28
+ **立即执行:** 使用 Skill 工具加载 `superpowers:writing-plans` 技能。禁止跳过此步骤。
29
+
30
+ 技能加载后,按其指引制定计划。计划要求:
31
+ - 保存至 `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`
32
+ - 引用设计文档,拆分为可执行任务
33
+ - **Plan 文件头必须包含关联元数据**:
34
+
35
+ ```yaml
36
+ ---
37
+ change: <openspec-change-name>
38
+ design-doc: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
39
+ ---
40
+ ```
41
+
42
+ ### 2. 更新计划状态
43
+
44
+ 先记录 plan 路径:
45
+
46
+ ```bash
47
+ bash "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
48
+ ```
49
+
50
+ 无需手动更新 phase,guard 会在退出条件满足后自动流转。
51
+
52
+ ### 3. 工作区隔离
53
+
54
+ 计划已写入当前分支。在开始执行前,选择工作区隔离方式:
55
+
56
+ | 选项 | 方式 | 说明 |
57
+ |------|------|------|
58
+ | A | 创建分支 | 在当前仓库创建新分支,简单快速 |
59
+ | B | 创建 Worktree | 隔离工作区,完全独立,适合并行开发 |
60
+
61
+ **推荐规则**:
62
+ - 变更涉及 3 个文件 → 推荐 A
63
+ - 需要并行开发、当前分支有未提交工作 → 推荐 B
64
+
65
+ 用户选择后,更新 `isolation` 字段。`isolation` 只允许以下值之一:
66
+
67
+ ```bash
68
+ bash "$COMET_STATE" set <name> isolation <value>
69
+ ```
70
+
71
+ - `branch`
72
+ - `worktree`
73
+
74
+ **执行隔离**:
75
+
76
+ - **branch**:执行 `git checkout -b <change-name>`,后续工作在新分支上进行
77
+ - **worktree**:调用 `superpowers:using-git-worktrees` 技能或使用原生 `EnterWorktree` 工具创建隔离工作区
78
+
79
+ 创建隔离后,确认计划文件可访问(分支方式天然可访问;worktree 方式需确认计划已提交)。
80
+
81
+ ### 4. 选择执行方式
82
+
83
+ 向用户展示计划摘要(任务数、涉及模块),然后询问执行方式:
84
+
85
+ | 选项 | 技能 | 适用场景 |
86
+ |------|------|---------|
87
+ | A | `superpowers:subagent-driven-development` | 任务独立、复杂度高、需要双阶段审查 |
88
+ | B | `superpowers:executing-plans` | 任务简单、无子agent环境、轻量快速 |
89
+
90
+ **推荐规则**:
91
+ - 任务数 ≥ 3 → 推荐 A
92
+ - 任务数 ≤ 2 且无跨模块依赖 → 推荐 B
93
+ - 来自 hotfix 路径 → 推荐 B
94
+
95
+ 用户选择后,更新 `build_mode` 字段。`build_mode` 只允许以下值之一:
96
+
97
+ ```bash
98
+ bash "$COMET_STATE" set <name> build_mode <value>
99
+ ```
100
+
101
+ - `subagent-driven-development`
102
+ - `executing-plans`
103
+ - `direct`(仅 hotfix preset 使用)
104
+
105
+ 然后,**立即执行:** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
106
+
107
+ 如所选 Superpowers 技能不可用,停止流程并提示安装或启用对应技能,不要用普通对话替代该步骤。
108
+
109
+ 技能加载后,按其指引执行:
110
+ - 按计划执行任务
111
+ - 完成 tasks.md 勾选(`- [ ]` → `- [x]`)
112
+ - 每个任务完成后提交代码
113
+
114
+ ### 5. Spec 增量更新
115
+
116
+ 实施过程中发现初版 spec 不完整时,按变更规模分级处理:
117
+
118
+ | 规模 | 触发条件 | 做法 |
119
+ |------|---------|------|
120
+ | 小 | 遗漏验收场景、边界条件 | 直接编辑 delta spec + design.md,追加 tasks.md 任务 |
121
+ | | 接口变更、新增组件、数据流变化 | 重新 `superpowers:brainstorming` 更新 Design Doc + delta spec |
122
+ | 大 | 全新 capability 需求 | `/opsx:new` 创建独立 change |
123
+
124
+ **50% 阈值判定**:以 tasks.md 初始任务总数为基准,若新增任务数超过该总数的一半,视为超出原计划范围,应考虑拆分为新 change。
125
+
126
+ **原则**:
127
+ - delta spec 是活文档,本阶段期间随时可修改
128
+ - 每次更新应提交,commit message 说明变更原因
129
+ - 不提前同步到 main spec,归档时统一同步
130
+ - 如增量任务超过原 tasks.md 初始任务总数 50%,考虑拆分为新 change
131
+ - 小规模增量直接改 delta spec 时,应在 commit message 中注明,便于归档时判断 design doc 漂移
132
+
133
+ ## 退出条件
134
+
135
+ - tasks.md 全部勾选
136
+ - 代码已提交
137
+ - 测试通过
138
+ - `.comet.yaml` `phase` 已更新为 `verify`
139
+ - **阶段守卫**:运行 `bash $COMET_GUARD <change-name> build`,全部 PASS 后才允许流转
140
+
141
+ 退出前运行 guard 自动流转:
142
+
143
+ ```bash
144
+ bash $COMET_GUARD <change-name> build --apply
145
+ ```
146
+
147
+ 状态文件自动更新为 `phase: verify`、`verify_result: pending`。
148
+
149
+ ## 自动流转
150
+
151
+ 退出条件满足后,**无需等待用户再次输入**,直接执行下一阶段:
152
+
153
+ > **REQUIRED NEXT SKILL:** 调用 `comet-verify` skill 进入验证与收尾阶段。
@@ -1,107 +1,91 @@
1
- ---
2
- name: comet-design
3
- description: "Comet 阶段 2:深度设计。用 /comet-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
4
- ---
5
-
6
- # Comet 阶段 2:深度设计(Design)
7
-
8
- ## 前置条件
9
-
10
- - 活跃 change 已存在(proposal.md、design.md、tasks.md)
11
- - 无 Design Doc(`docs/superpowers/specs/` 下无对应文件)
12
-
13
- ## 步骤
14
-
15
- ### 0. 入口状态验证(Entry Check)
16
-
17
- 在执行任何操作之前,读取并验证当前状态:
18
-
19
- **检查清单:**
20
- 1. `openspec/changes/<name>/.comet.yaml` 存在
21
- 2. `phase` 字段的值为 `"design"`
22
- 3. `workflow` 字段的值为 `"full"`
23
- 4. `design_doc` 字段为 `null` 或空
24
- 5. `openspec/changes/<name>/proposal.md` 存在且非空
25
- 6. `openspec/changes/<name>/design.md` 存在且非空
26
- 7. `openspec/changes/<name>/tasks.md` 存在且非空
27
-
28
- **验证方式:**
29
- - `cat openspec/changes/<name>/.comet.yaml` 读取全部字段
30
- - 逐条比对检查清单
31
-
32
- **失败输出:**
33
- ```
34
- [HARD STOP] Entry check failed for comet-design
35
- Expected: phase=design, design_doc=<empty/null>, workflow=full
36
- Actual: phase=<实际值>, design_doc=<实际值>, workflow=<实际值>
37
- Suggestion: Run comet-open first, or check if .comet.yaml was modified out of sequence.
38
- ```
39
-
40
- 验证通过后才进入步骤 1。
41
-
42
- ### 1a. 读取已有上下文
43
-
44
- 读取活跃 change 下的 `proposal.md` 和 `design.md`,将核心内容整理为摘要:
45
- - **proposal 摘要**:目标、动机、范围
46
- - **design 摘要**:架构决策、高层设计
47
-
48
- ### 1b. 执行 Brainstorming(带上下文)
49
-
50
- **立即执行:** 使用 Skill 工具加载 `superpowers:brainstorming` 技能,ARGUMENTS 包含:
51
-
52
- ```
53
- Change: <change-name>
54
- Proposal 摘要: <proposal 核心内容>
55
- Design 摘要: <design.md 架构决策>
56
- 跳过上下文探索,直接进入设计提问。
57
- ```
58
-
59
- 禁止跳过此步骤,禁止在未加载该技能的情况下继续。
60
-
61
- 如 `superpowers:brainstorming` 不可用,停止流程并提示安装或启用 Superpowers 技能,不要用普通对话替代该步骤。
62
-
63
- 技能加载后,按其指引产出:
64
- - `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — 设计文档(技术 RFC)
65
- - `openspec/changes/<name>/specs/<capability>/spec.md` 能力规格(delta)
66
-
67
- ### 2. 更新 Comet 状态
68
-
69
- 先记录 design_doc 路径,再运行 guard 自动流转:
70
-
71
- ```bash
72
- # 记录 design_doc 路径
73
- sed -i 's|^design_doc:.*|design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md|' openspec/changes/<name>/.comet.yaml
74
-
75
- # 自动流转到下一阶段
76
- bash $COMET_GUARD <change-name> design --apply
77
- ```
78
-
79
- 状态文件自动更新,无需手动编辑其他字段。
80
-
81
- ### 3. 双 Spec 分工
82
-
83
- | Spec 类型 | 归属 | 存放位置 | 定义 |
84
- |-----------|------|---------|------|
85
- | 能力规格 | OpenSpec | `openspec/changes/<name>/specs/` | 系统应该做什么(需求 + 验收场景) |
86
- | 设计文档 | Superpowers | `docs/superpowers/specs/` | 怎么构建(技术架构 + 实现细节) |
87
-
88
- ### 4. 文档层级确认
89
-
90
- ```
91
- proposal.md(阶段 1) → Why + What
92
- design.md(阶段 1,OpenSpec) → 高层架构决策
93
- 设计文档(阶段 2,Superpowers) → 深度技术设计
94
- 能力规格(阶段 2,delta) → 需求 + 验收场景
95
- ```
96
-
97
- ## 退出条件
98
-
99
- - Design Doc 已创建并保存
100
- - 如有新能力则 delta spec 已创建
101
- - **阶段守卫**:运行 `bash $COMET_GUARD <change-name> design`,全部 PASS 后才允许流转
102
-
103
- ## 自动流转
104
-
105
- 退出条件满足后,**无需等待用户再次输入**,直接执行下一阶段:
106
-
107
- > **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。
1
+ ---
2
+ name: comet-design
3
+ description: "Comet 阶段 2:深度设计。用 /comet-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
4
+ ---
5
+
6
+ # Comet 阶段 2:深度设计(Design)
7
+
8
+ ## 前置条件
9
+
10
+ - 活跃 change 已存在(proposal.md、design.md、tasks.md)
11
+ - 无 Design Doc(`docs/superpowers/specs/` 下无对应文件)
12
+
13
+ ## 步骤
14
+
15
+ ### 0. 入口状态验证(Entry Check)
16
+
17
+ 执行入口验证:
18
+
19
+ ```bash
20
+ COMET_STATE="${COMET_STATE:-$(find . -path '*/comet/scripts/comet-state.sh' -type f -print -quit)}"
21
+ bash "$COMET_STATE" check <name> design
22
+ ```
23
+
24
+ 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
25
+
26
+ ### 1a. 读取已有上下文
27
+
28
+ 读取活跃 change 下的 `proposal.md` 和 `design.md`,将核心内容整理为摘要:
29
+ - **proposal 摘要**:目标、动机、范围
30
+ - **design 摘要**:架构决策、高层设计
31
+
32
+ ### 1b. 执行 Brainstorming(带上下文)
33
+
34
+ **立即执行:** 使用 Skill 工具加载 `superpowers:brainstorming` 技能,ARGUMENTS 包含:
35
+
36
+ ```
37
+ Change: <change-name>
38
+ Proposal 摘要: <proposal 核心内容>
39
+ Design 摘要: <design.md 架构决策>
40
+ 跳过上下文探索,直接进入设计提问。
41
+ ```
42
+
43
+ 禁止跳过此步骤,禁止在未加载该技能的情况下继续。
44
+
45
+ `superpowers:brainstorming` 不可用,停止流程并提示安装或启用 Superpowers 技能,不要用普通对话替代该步骤。
46
+
47
+ 技能加载后,按其指引产出:
48
+ - `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` 设计文档(技术 RFC)
49
+ - `openspec/changes/<name>/specs/<capability>/spec.md` — 能力规格(delta)
50
+
51
+ ### 2. 更新 Comet 状态
52
+
53
+ 先记录 design_doc 路径,再运行 guard 自动流转:
54
+
55
+ ```bash
56
+ # 记录 design_doc 路径
57
+ bash "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
58
+
59
+ # 自动流转到下一阶段
60
+ bash $COMET_GUARD <change-name> design --apply
61
+ ```
62
+
63
+ 状态文件自动更新,无需手动编辑其他字段。
64
+
65
+ ### 3. Spec 分工
66
+
67
+ | Spec 类型 | 归属 | 存放位置 | 定义 |
68
+ |-----------|------|---------|------|
69
+ | 能力规格 | OpenSpec | `openspec/changes/<name>/specs/` | 系统应该做什么(需求 + 验收场景) |
70
+ | 设计文档 | Superpowers | `docs/superpowers/specs/` | 怎么构建(技术架构 + 实现细节) |
71
+
72
+ ### 4. 文档层级确认
73
+
74
+ ```
75
+ proposal.md(阶段 1) → Why + What
76
+ design.md(阶段 1,OpenSpec) → 高层架构决策
77
+ 设计文档(阶段 2,Superpowers) → 深度技术设计
78
+ 能力规格(阶段 2,delta) → 需求 + 验收场景
79
+ ```
80
+
81
+ ## 退出条件
82
+
83
+ - Design Doc 已创建并保存
84
+ - 如有新能力则 delta spec 已创建
85
+ - **阶段守卫**:运行 `bash $COMET_GUARD <change-name> design`,全部 PASS 后才允许流转
86
+
87
+ ## 自动流转
88
+
89
+ 退出条件满足后,**无需等待用户再次输入**,直接执行下一阶段:
90
+
91
+ > **REQUIRED NEXT SKILL:** 调用 `comet-build` skill 进入计划与构建阶段。