@house365/comate 0.1.0 → 0.1.1
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.
- package/LICENSE +21 -21
- package/README.md +78 -78
- package/bin/init.mjs +18 -6
- package/package.json +52 -52
- package/skills/comate/SKILL.md +213 -213
- package/skills/comate/reference/decision-points.md +54 -54
- package/skills/comate/reference/dirty-worktree.md +58 -58
- package/skills/comate/reference/prerequisites.md +88 -88
- package/skills/comate-archive/SKILL.md +63 -63
- package/skills/comate-build/SKILL.md +152 -152
- package/skills/comate-design/SKILL.md +106 -106
- package/skills/comate-hotfix/SKILL.md +115 -115
- package/skills/comate-open/SKILL.md +109 -109
- package/skills/comate-tweak/SKILL.md +109 -109
- package/skills/comate-verify/SKILL.md +130 -130
package/skills/comate/SKILL.md
CHANGED
|
@@ -1,213 +1,213 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: comate
|
|
3
|
-
description: "comate —— OpenSpec + Superpowers 规格驱动开发编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# comate —— OpenSpec + Superpowers 规格驱动开发流
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## 决策核心
|
|
14
|
-
|
|
15
|
-
agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
|
|
16
|
-
|
|
17
|
-
### 自动阶段探测
|
|
18
|
-
|
|
19
|
-
**Step 0：活跃 change 发现 + 意图探测**
|
|
20
|
-
|
|
21
|
-
1. 先探测预设；命中 hotfix/tweak 条件则直接调用对应预设 skill，不进入普通 open 分支。
|
|
22
|
-
2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
|
|
23
|
-
|
|
24
|
-
**预设探测优先级最高**：
|
|
25
|
-
- 用户明确描述 bug 修复/热修 + 满足 hotfix 条件 → 直接调用 `/comate-hotfix`
|
|
26
|
-
- 用户明确描述文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接调用 `/comate-tweak`
|
|
27
|
-
- 无预设命中 → 按下表处理
|
|
28
|
-
|
|
29
|
-
| 活跃 change | 用户输入 | 行为 |
|
|
30
|
-
|-------------|----------|------|
|
|
31
|
-
| 无 | 非预设输入 | → 调用 `/comate-open` |
|
|
32
|
-
| 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
|
|
33
|
-
| 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
|
|
34
|
-
| 恰好 1 个 | `/comate` 无描述 | → 自动选中，进入 Step 1 |
|
|
35
|
-
| 多个 | `/comate` 无描述 | → 列出 change 供用户选择 |
|
|
36
|
-
|
|
37
|
-
<IMPORTANT>
|
|
38
|
-
用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
|
|
39
|
-
`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
|
|
40
|
-
直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
|
|
41
|
-
</IMPORTANT>
|
|
42
|
-
|
|
43
|
-
**Step 1：读取 `.comate.yaml` 状态元数据**
|
|
44
|
-
|
|
45
|
-
优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
|
|
46
|
-
|
|
47
|
-
**断点恢复规则**：
|
|
48
|
-
- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
|
|
49
|
-
- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
|
|
50
|
-
- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
|
|
51
|
-
- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点（决策点 4）：暂停询问修复或接受偏差；仅在用户选修复后运行 `state transition <name> verify-fail` 并调用 `/comate-build`。
|
|
52
|
-
- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
|
|
53
|
-
- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
|
|
54
|
-
|
|
55
|
-
**Step 2：阶段判定**（按顺序检查，首个命中者生效）
|
|
56
|
-
|
|
57
|
-
1. `archived: true` 或 change 已移入 archive → 流程完成
|
|
58
|
-
2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
|
|
59
|
-
3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
|
|
60
|
-
4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
|
|
61
|
-
5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`hotfix`→`/comate-hotfix`，`tweak`→`/comate-tweak`，`full`→`/comate-build`
|
|
62
|
-
6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
|
|
63
|
-
7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
|
|
64
|
-
8. 无活跃 change → 调用 `/comate-open`
|
|
65
|
-
|
|
66
|
-
元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
|
|
67
|
-
|
|
68
|
-
### 预设升级判定
|
|
69
|
-
|
|
70
|
-
**hotfix → full**（任一满足即升级）：改动 ≥ 3 文件 / 架构变更（新模块、新接口、新依赖）/ 数据库 schema 变更 / 引入新 public API / 范围超出单一函数模块。
|
|
71
|
-
|
|
72
|
-
**tweak → full**（任一满足即升级）：改动 ≥ 5 文件 / 跨模块协调 / 需新增 ≥ 5 测试用例 / 配置项增删（非值修改）。
|
|
73
|
-
|
|
74
|
-
### 错误处理速查
|
|
75
|
-
|
|
76
|
-
| 场景 | 处理 |
|
|
77
|
-
|------|------|
|
|
78
|
-
| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `openspec init` |
|
|
79
|
-
| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
|
|
80
|
-
| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
|
|
81
|
-
| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
|
|
82
|
-
| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
|
|
83
|
-
|
|
84
|
-
### 阶段流转
|
|
85
|
-
|
|
86
|
-
<IMPORTANT>
|
|
87
|
-
一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
|
|
88
|
-
|
|
89
|
-
流转链：open → design → build → verify → archive
|
|
90
|
-
|
|
91
|
-
**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
|
|
92
|
-
|
|
93
|
-
7 个决策阻塞点 + Red Flags 表见 `comate/reference/decision-points.md`。到达任一决策点必须停下用 AskUserQuestion 等待用户选择；其他无歧义流转自动进行，不得中途退出。
|
|
94
|
-
</IMPORTANT>
|
|
95
|
-
|
|
96
|
-
---
|
|
97
|
-
|
|
98
|
-
## 子命令速查
|
|
99
|
-
|
|
100
|
-
| 命令 | 阶段 | Owner | 产物 |
|
|
101
|
-
|------|------|-------|------|
|
|
102
|
-
| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
|
|
103
|
-
| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
|
|
104
|
-
| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
|
|
105
|
-
| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
|
|
106
|
-
| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
|
|
107
|
-
| `/comate-hotfix` | 预设 | 双方 | 快速修复（跳过 brainstorming） |
|
|
108
|
-
| `/comate-tweak` | 预设 | 双方 | 小调整（跳过 brainstorming + 完整 plan） |
|
|
109
|
-
|
|
110
|
-
```
|
|
111
|
-
/comate
|
|
112
|
-
↓ 自动探测
|
|
113
|
-
/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
|
|
114
|
-
(OpenSpec) (Superpowers) (Superpowers) (双方) (OpenSpec)
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
---
|
|
118
|
-
|
|
119
|
-
## 参考附录
|
|
120
|
-
|
|
121
|
-
### 脚本定位（单一入口）
|
|
122
|
-
|
|
123
|
-
comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
|
|
124
|
-
|
|
125
|
-
```bash
|
|
126
|
-
COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
|
|
127
|
-
[ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
|
|
128
|
-
done | head -1)}"
|
|
129
|
-
if [ -z "$COMATE" ]; then
|
|
130
|
-
echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
|
|
131
|
-
return 1 2>/dev/null || exit 1
|
|
132
|
-
fi
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
之后全程复用 `$COMATE`：
|
|
136
|
-
|
|
137
|
-
```bash
|
|
138
|
-
bash "$COMATE" state <name> init <full|hotfix|tweak>
|
|
139
|
-
bash "$COMATE" state <name> transition <event>
|
|
140
|
-
bash "$COMATE" state <name> check <phase> [--json]
|
|
141
|
-
bash "$COMATE" state <name> recover <phase>
|
|
142
|
-
bash "$COMATE" state <name> scale
|
|
143
|
-
bash "$COMATE" state <name> validate
|
|
144
|
-
bash "$COMATE" guard <name> <phase> [--apply] [--json]
|
|
145
|
-
bash "$COMATE" handoff <name> <design|build> --write [--full]
|
|
146
|
-
bash "$COMATE" sources <name> track <file...> [--note <text>]
|
|
147
|
-
bash "$COMATE" sources <name> check | list
|
|
148
|
-
bash "$COMATE" sources find <file>
|
|
149
|
-
bash "$COMATE" archive <name> [--dry-run]
|
|
150
|
-
bash "$COMATE" status
|
|
151
|
-
bash "$COMATE" doctor
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
|
|
155
|
-
|
|
156
|
-
### `.comate.yaml` 字段参考
|
|
157
|
-
|
|
158
|
-
状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
|
|
159
|
-
|
|
160
|
-
| 字段 | 含义 |
|
|
161
|
-
|------|------|
|
|
162
|
-
| `schema_version` | 状态文件格式版本（当前 1） |
|
|
163
|
-
| `workflow` | `full` / `hotfix` / `tweak` |
|
|
164
|
-
| `phase` | `open` / `design` / `build` / `verify` / `archive` |
|
|
165
|
-
| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
|
|
166
|
-
| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；hotfix/tweak 默认 `direct`） |
|
|
167
|
-
| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
|
|
168
|
-
| `verify_mode` | `light` / `full`（由 scale 评估写入） |
|
|
169
|
-
| `verify_result` | `pending` / `pass` / `fail` |
|
|
170
|
-
| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
|
|
171
|
-
| `branch_status` | `pending` / `handled` |
|
|
172
|
-
| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
|
|
173
|
-
| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
|
|
174
|
-
| `direct_override` | full 流程用 `direct` 需显式 `true` |
|
|
175
|
-
| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
|
|
176
|
-
| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
|
|
177
|
-
| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
|
|
178
|
-
|
|
179
|
-
状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
|
|
180
|
-
- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
|
|
181
|
-
- `build → verify` 前 `build_mode` 必须已选
|
|
182
|
-
- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
|
|
183
|
-
- `build_mode: direct` 默认仅 hotfix/tweak；full 流程需 `direct_override: true`
|
|
184
|
-
- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
|
|
185
|
-
|
|
186
|
-
### 文件结构
|
|
187
|
-
|
|
188
|
-
```
|
|
189
|
-
openspec/ # OpenSpec —— WHAT
|
|
190
|
-
├── changes/<name>/
|
|
191
|
-
│ ├── .comate.yaml # comate 状态机真相源
|
|
192
|
-
│ ├── proposal.md / design.md / tasks.md
|
|
193
|
-
│ ├── specs/<capability>/spec.md # delta 能力规格
|
|
194
|
-
│ └── .comate/handoff/ # 脚本生成的阶段交接包
|
|
195
|
-
│ └── ../sources.manifest # 知识库源文件清单（source_kind=file 时）
|
|
196
|
-
└── specs/<capability>/spec.md # 主 spec（归档时由 delta 覆盖）
|
|
197
|
-
|
|
198
|
-
docs/knowledge-base/<...>.md # 可追踪的需求源文档（source_kind=file）
|
|
199
|
-
|
|
200
|
-
docs/superpowers/ # Superpowers —— HOW
|
|
201
|
-
├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
|
|
202
|
-
├── plans/YYYY-MM-DD-<feature>.md # 实施计划
|
|
203
|
-
└── reports/ # 验证报告
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
### 最佳实践
|
|
207
|
-
|
|
208
|
-
1. brainstorming 不可跳过（hotfix/tweak 除外）
|
|
209
|
-
2. delta spec 是活文档，build 阶段随时改，归档时同步
|
|
210
|
-
3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
|
|
211
|
-
4. tasks.md 实时同步，每完成一个任务勾选并提交
|
|
212
|
-
5. 验证通过才归档
|
|
213
|
-
6. 预设有边界，命中升级条件及时转 full
|
|
1
|
+
---
|
|
2
|
+
name: comate
|
|
3
|
+
description: "comate —— OpenSpec + Superpowers 规格驱动开发编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# comate —— OpenSpec + Superpowers 规格驱动开发流
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（hotfix 和 tweak 预设除外）。**
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 决策核心
|
|
14
|
+
|
|
15
|
+
agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
|
|
16
|
+
|
|
17
|
+
### 自动阶段探测
|
|
18
|
+
|
|
19
|
+
**Step 0：活跃 change 发现 + 意图探测**
|
|
20
|
+
|
|
21
|
+
1. 先探测预设；命中 hotfix/tweak 条件则直接调用对应预设 skill，不进入普通 open 分支。
|
|
22
|
+
2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
|
|
23
|
+
|
|
24
|
+
**预设探测优先级最高**：
|
|
25
|
+
- 用户明确描述 bug 修复/热修 + 满足 hotfix 条件 → 直接调用 `/comate-hotfix`
|
|
26
|
+
- 用户明确描述文案/配置/文档/prompt 小调整 + 满足 tweak 条件 → 直接调用 `/comate-tweak`
|
|
27
|
+
- 无预设命中 → 按下表处理
|
|
28
|
+
|
|
29
|
+
| 活跃 change | 用户输入 | 行为 |
|
|
30
|
+
|-------------|----------|------|
|
|
31
|
+
| 无 | 非预设输入 | → 调用 `/comate-open` |
|
|
32
|
+
| 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
|
|
33
|
+
| 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
|
|
34
|
+
| 恰好 1 个 | `/comate` 无描述 | → 自动选中，进入 Step 1 |
|
|
35
|
+
| 多个 | `/comate` 无描述 | → 列出 change 供用户选择 |
|
|
36
|
+
|
|
37
|
+
<IMPORTANT>
|
|
38
|
+
用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
|
|
39
|
+
`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
|
|
40
|
+
直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
|
|
41
|
+
</IMPORTANT>
|
|
42
|
+
|
|
43
|
+
**Step 1：读取 `.comate.yaml` 状态元数据**
|
|
44
|
+
|
|
45
|
+
优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
|
|
46
|
+
|
|
47
|
+
**断点恢复规则**：
|
|
48
|
+
- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
|
|
49
|
+
- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
|
|
50
|
+
- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
|
|
51
|
+
- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点（决策点 4）：暂停询问修复或接受偏差；仅在用户选修复后运行 `state transition <name> verify-fail` 并调用 `/comate-build`。
|
|
52
|
+
- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
|
|
53
|
+
- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
|
|
54
|
+
|
|
55
|
+
**Step 2：阶段判定**（按顺序检查，首个命中者生效）
|
|
56
|
+
|
|
57
|
+
1. `archived: true` 或 change 已移入 archive → 流程完成
|
|
58
|
+
2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
|
|
59
|
+
3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
|
|
60
|
+
4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
|
|
61
|
+
5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`hotfix`→`/comate-hotfix`，`tweak`→`/comate-tweak`，`full`→`/comate-build`
|
|
62
|
+
6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
|
|
63
|
+
7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
|
|
64
|
+
8. 无活跃 change → 调用 `/comate-open`
|
|
65
|
+
|
|
66
|
+
元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
|
|
67
|
+
|
|
68
|
+
### 预设升级判定
|
|
69
|
+
|
|
70
|
+
**hotfix → full**（任一满足即升级）：改动 ≥ 3 文件 / 架构变更（新模块、新接口、新依赖）/ 数据库 schema 变更 / 引入新 public API / 范围超出单一函数模块。
|
|
71
|
+
|
|
72
|
+
**tweak → full**（任一满足即升级）：改动 ≥ 5 文件 / 跨模块协调 / 需新增 ≥ 5 测试用例 / 配置项增删（非值修改）。
|
|
73
|
+
|
|
74
|
+
### 错误处理速查
|
|
75
|
+
|
|
76
|
+
| 场景 | 处理 |
|
|
77
|
+
|------|------|
|
|
78
|
+
| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `openspec init` |
|
|
79
|
+
| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
|
|
80
|
+
| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
|
|
81
|
+
| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
|
|
82
|
+
| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
|
|
83
|
+
|
|
84
|
+
### 阶段流转
|
|
85
|
+
|
|
86
|
+
<IMPORTANT>
|
|
87
|
+
一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
|
|
88
|
+
|
|
89
|
+
流转链：open → design → build → verify → archive
|
|
90
|
+
|
|
91
|
+
**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
|
|
92
|
+
|
|
93
|
+
7 个决策阻塞点 + Red Flags 表见 `comate/reference/decision-points.md`。到达任一决策点必须停下用 AskUserQuestion 等待用户选择；其他无歧义流转自动进行，不得中途退出。
|
|
94
|
+
</IMPORTANT>
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 子命令速查
|
|
99
|
+
|
|
100
|
+
| 命令 | 阶段 | Owner | 产物 |
|
|
101
|
+
|------|------|-------|------|
|
|
102
|
+
| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
|
|
103
|
+
| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
|
|
104
|
+
| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
|
|
105
|
+
| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
|
|
106
|
+
| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
|
|
107
|
+
| `/comate-hotfix` | 预设 | 双方 | 快速修复（跳过 brainstorming） |
|
|
108
|
+
| `/comate-tweak` | 预设 | 双方 | 小调整（跳过 brainstorming + 完整 plan） |
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
/comate
|
|
112
|
+
↓ 自动探测
|
|
113
|
+
/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
|
|
114
|
+
(OpenSpec) (Superpowers) (Superpowers) (双方) (OpenSpec)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 参考附录
|
|
120
|
+
|
|
121
|
+
### 脚本定位（单一入口）
|
|
122
|
+
|
|
123
|
+
comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
|
|
127
|
+
[ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
|
|
128
|
+
done | head -1)}"
|
|
129
|
+
if [ -z "$COMATE" ]; then
|
|
130
|
+
echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
|
|
131
|
+
return 1 2>/dev/null || exit 1
|
|
132
|
+
fi
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
之后全程复用 `$COMATE`：
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
bash "$COMATE" state <name> init <full|hotfix|tweak>
|
|
139
|
+
bash "$COMATE" state <name> transition <event>
|
|
140
|
+
bash "$COMATE" state <name> check <phase> [--json]
|
|
141
|
+
bash "$COMATE" state <name> recover <phase>
|
|
142
|
+
bash "$COMATE" state <name> scale
|
|
143
|
+
bash "$COMATE" state <name> validate
|
|
144
|
+
bash "$COMATE" guard <name> <phase> [--apply] [--json]
|
|
145
|
+
bash "$COMATE" handoff <name> <design|build> --write [--full]
|
|
146
|
+
bash "$COMATE" sources <name> track <file...> [--note <text>]
|
|
147
|
+
bash "$COMATE" sources <name> check | list
|
|
148
|
+
bash "$COMATE" sources find <file>
|
|
149
|
+
bash "$COMATE" archive <name> [--dry-run]
|
|
150
|
+
bash "$COMATE" status
|
|
151
|
+
bash "$COMATE" doctor
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
|
|
155
|
+
|
|
156
|
+
### `.comate.yaml` 字段参考
|
|
157
|
+
|
|
158
|
+
状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
|
|
159
|
+
|
|
160
|
+
| 字段 | 含义 |
|
|
161
|
+
|------|------|
|
|
162
|
+
| `schema_version` | 状态文件格式版本（当前 1） |
|
|
163
|
+
| `workflow` | `full` / `hotfix` / `tweak` |
|
|
164
|
+
| `phase` | `open` / `design` / `build` / `verify` / `archive` |
|
|
165
|
+
| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
|
|
166
|
+
| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；hotfix/tweak 默认 `direct`） |
|
|
167
|
+
| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
|
|
168
|
+
| `verify_mode` | `light` / `full`（由 scale 评估写入） |
|
|
169
|
+
| `verify_result` | `pending` / `pass` / `fail` |
|
|
170
|
+
| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
|
|
171
|
+
| `branch_status` | `pending` / `handled` |
|
|
172
|
+
| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
|
|
173
|
+
| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
|
|
174
|
+
| `direct_override` | full 流程用 `direct` 需显式 `true` |
|
|
175
|
+
| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
|
|
176
|
+
| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
|
|
177
|
+
| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
|
|
178
|
+
|
|
179
|
+
状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
|
|
180
|
+
- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
|
|
181
|
+
- `build → verify` 前 `build_mode` 必须已选
|
|
182
|
+
- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
|
|
183
|
+
- `build_mode: direct` 默认仅 hotfix/tweak；full 流程需 `direct_override: true`
|
|
184
|
+
- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
|
|
185
|
+
|
|
186
|
+
### 文件结构
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
openspec/ # OpenSpec —— WHAT
|
|
190
|
+
├── changes/<name>/
|
|
191
|
+
│ ├── .comate.yaml # comate 状态机真相源
|
|
192
|
+
│ ├── proposal.md / design.md / tasks.md
|
|
193
|
+
│ ├── specs/<capability>/spec.md # delta 能力规格
|
|
194
|
+
│ └── .comate/handoff/ # 脚本生成的阶段交接包
|
|
195
|
+
│ └── ../sources.manifest # 知识库源文件清单（source_kind=file 时）
|
|
196
|
+
└── specs/<capability>/spec.md # 主 spec（归档时由 delta 覆盖）
|
|
197
|
+
|
|
198
|
+
docs/knowledge-base/<...>.md # 可追踪的需求源文档（source_kind=file）
|
|
199
|
+
|
|
200
|
+
docs/superpowers/ # Superpowers —— HOW
|
|
201
|
+
├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
|
|
202
|
+
├── plans/YYYY-MM-DD-<feature>.md # 实施计划
|
|
203
|
+
└── reports/ # 验证报告
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### 最佳实践
|
|
207
|
+
|
|
208
|
+
1. brainstorming 不可跳过（hotfix/tweak 除外）
|
|
209
|
+
2. delta spec 是活文档，build 阶段随时改，归档时同步
|
|
210
|
+
3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
|
|
211
|
+
4. tasks.md 实时同步，每完成一个任务勾选并提交
|
|
212
|
+
5. 验证通过才归档
|
|
213
|
+
6. 预设有边界，命中升级条件及时转 full
|
|
@@ -1,54 +1,54 @@
|
|
|
1
|
-
# 决策阻塞点清单（decision-points）
|
|
2
|
-
|
|
3
|
-
规范路径：`comate/reference/decision-points.md`（单一真相源）
|
|
4
|
-
|
|
5
|
-
本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
|
|
6
|
-
|
|
7
|
-
## 通用规则
|
|
8
|
-
|
|
9
|
-
**决策点是阻塞点**。到达下列任一节点时，当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
|
|
10
|
-
|
|
11
|
-
- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
|
|
12
|
-
- 不得用推荐规则、默认值或历史偏好替代用户确认。
|
|
13
|
-
- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
|
|
14
|
-
- 其他无歧义的阶段流转必须自动进行，不得中途退出。
|
|
15
|
-
|
|
16
|
-
## 七个决策点
|
|
17
|
-
|
|
18
|
-
1. **开题产物审视确认**（open）
|
|
19
|
-
proposal/design/tasks 三件套完成且内容完整后，暂停请用户确认或要求调整。
|
|
20
|
-
引用：`comate-open` 退出条件。
|
|
21
|
-
|
|
22
|
-
2. **设计方案确认**（design / brainstorming）
|
|
23
|
-
brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
|
|
24
|
-
引用：`comate-design` Step 1c。
|
|
25
|
-
|
|
26
|
-
3. **构建工作方式选择**（build）
|
|
27
|
-
开始执行前，**一次性**询问工作区隔离方式（branch / worktree）、执行方式（subagent-driven-development / executing-plans）和 TDD 模式（tdd / direct）。一次交互内取得三项选择，并分别写入 `isolation`、`build_mode`、`tdd_mode`。
|
|
28
|
-
引用：`comate-build` Step 3。
|
|
29
|
-
|
|
30
|
-
4. **验证失败决策**（verify）
|
|
31
|
-
验证不通过时，暂停请用户决定全部修复 / 逐项处理 / 接受偏差。含 Spec 漂移处理（design doc 与 delta spec 矛盾）。CRITICAL 失败项必须修复。用户选择修复后才执行 `state transition <name> verify-fail` 并回到 build。
|
|
32
|
-
引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
|
|
33
|
-
|
|
34
|
-
5. **分支收尾方式选择**（verify / finishing-a-development-branch）
|
|
35
|
-
暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
|
|
36
|
-
引用：`comate-verify` Step 3。
|
|
37
|
-
|
|
38
|
-
6. **预设升级确认**（hotfix / tweak → full）
|
|
39
|
-
命中升级条件（见各 preset SKILL 的「升级条件」表）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
|
|
40
|
-
引用：`comate-hotfix` / `comate-tweak`「升级条件」。
|
|
41
|
-
|
|
42
|
-
7. **构建期范围扩张**（build）
|
|
43
|
-
实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
|
|
44
|
-
引用：`comate-build` Step 4。
|
|
45
|
-
|
|
46
|
-
## Red Flags — 出现这些念头就停下来检查
|
|
47
|
-
|
|
48
|
-
| Agent 的念头 | 实际风险 |
|
|
49
|
-
|--------------|----------|
|
|
50
|
-
| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
|
|
51
|
-
| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
|
|
52
|
-
| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
|
|
53
|
-
| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
|
|
54
|
-
| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |
|
|
1
|
+
# 决策阻塞点清单（decision-points）
|
|
2
|
+
|
|
3
|
+
规范路径：`comate/reference/decision-points.md`（单一真相源）
|
|
4
|
+
|
|
5
|
+
本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
|
|
6
|
+
|
|
7
|
+
## 通用规则
|
|
8
|
+
|
|
9
|
+
**决策点是阻塞点**。到达下列任一节点时，当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
|
|
10
|
+
|
|
11
|
+
- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
|
|
12
|
+
- 不得用推荐规则、默认值或历史偏好替代用户确认。
|
|
13
|
+
- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
|
|
14
|
+
- 其他无歧义的阶段流转必须自动进行，不得中途退出。
|
|
15
|
+
|
|
16
|
+
## 七个决策点
|
|
17
|
+
|
|
18
|
+
1. **开题产物审视确认**（open）
|
|
19
|
+
proposal/design/tasks 三件套完成且内容完整后，暂停请用户确认或要求调整。
|
|
20
|
+
引用：`comate-open` 退出条件。
|
|
21
|
+
|
|
22
|
+
2. **设计方案确认**（design / brainstorming）
|
|
23
|
+
brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
|
|
24
|
+
引用：`comate-design` Step 1c。
|
|
25
|
+
|
|
26
|
+
3. **构建工作方式选择**（build）
|
|
27
|
+
开始执行前，**一次性**询问工作区隔离方式（branch / worktree）、执行方式（subagent-driven-development / executing-plans）和 TDD 模式（tdd / direct）。一次交互内取得三项选择，并分别写入 `isolation`、`build_mode`、`tdd_mode`。
|
|
28
|
+
引用：`comate-build` Step 3。
|
|
29
|
+
|
|
30
|
+
4. **验证失败决策**（verify）
|
|
31
|
+
验证不通过时，暂停请用户决定全部修复 / 逐项处理 / 接受偏差。含 Spec 漂移处理（design doc 与 delta spec 矛盾）。CRITICAL 失败项必须修复。用户选择修复后才执行 `state transition <name> verify-fail` 并回到 build。
|
|
32
|
+
引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
|
|
33
|
+
|
|
34
|
+
5. **分支收尾方式选择**（verify / finishing-a-development-branch）
|
|
35
|
+
暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
|
|
36
|
+
引用：`comate-verify` Step 3。
|
|
37
|
+
|
|
38
|
+
6. **预设升级确认**（hotfix / tweak → full）
|
|
39
|
+
命中升级条件（见各 preset SKILL 的「升级条件」表）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
|
|
40
|
+
引用：`comate-hotfix` / `comate-tweak`「升级条件」。
|
|
41
|
+
|
|
42
|
+
7. **构建期范围扩张**（build）
|
|
43
|
+
实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
|
|
44
|
+
引用：`comate-build` Step 4。
|
|
45
|
+
|
|
46
|
+
## Red Flags — 出现这些念头就停下来检查
|
|
47
|
+
|
|
48
|
+
| Agent 的念头 | 实际风险 |
|
|
49
|
+
|--------------|----------|
|
|
50
|
+
| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
|
|
51
|
+
| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
|
|
52
|
+
| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
|
|
53
|
+
| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
|
|
54
|
+
| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |
|