@house365/comate 0.2.10 → 0.3.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.
package/package.json
CHANGED
package/skills/comate/SKILL.md
CHANGED
|
@@ -48,7 +48,7 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
|
|
|
48
48
|
- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
|
|
49
49
|
- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
|
|
50
50
|
- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
|
|
51
|
-
- 若 `phase: verify` 且 `verify_result: fail
|
|
51
|
+
- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
|
|
52
52
|
- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
|
|
53
53
|
- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
|
|
54
54
|
|
|
@@ -4,14 +4,30 @@
|
|
|
4
4
|
|
|
5
5
|
本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
|
|
6
6
|
|
|
7
|
+
## 先判定：这里真的需要用户输入吗？
|
|
8
|
+
|
|
9
|
+
到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
|
|
10
|
+
|
|
11
|
+
| 类别 | 判据 | 处理 |
|
|
12
|
+
|------|------|------|
|
|
13
|
+
| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
|
|
14
|
+
| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
|
|
15
|
+
| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
|
|
16
|
+
|
|
17
|
+
三条落地准则：
|
|
18
|
+
|
|
19
|
+
1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
|
|
20
|
+
2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
|
|
21
|
+
3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
|
|
22
|
+
|
|
7
23
|
## 通用规则
|
|
8
24
|
|
|
9
|
-
|
|
25
|
+
经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
|
|
10
26
|
|
|
11
27
|
- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
|
|
12
|
-
-
|
|
28
|
+
- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
|
|
13
29
|
- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
|
|
14
|
-
-
|
|
30
|
+
- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
|
|
15
31
|
|
|
16
32
|
## 七个决策点
|
|
17
33
|
|
|
@@ -24,11 +40,15 @@
|
|
|
24
40
|
引用：`comate-design` Step 1c。
|
|
25
41
|
|
|
26
42
|
3. **构建工作方式选择**（build）
|
|
27
|
-
|
|
43
|
+
开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
|
|
44
|
+
预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
|
|
28
45
|
引用：`comate-build` Step 3。
|
|
29
46
|
|
|
30
47
|
4. **验证失败决策**（verify）
|
|
31
|
-
|
|
48
|
+
验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
|
|
49
|
+
- **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
|
|
50
|
+
- **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
|
|
51
|
+
- **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
|
|
32
52
|
引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
|
|
33
53
|
|
|
34
54
|
5. **分支收尾方式选择**（verify / finishing-a-development-branch）
|
|
@@ -54,13 +54,38 @@ bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.m
|
|
|
54
54
|
|
|
55
55
|
### 3. 选择工作方式（决策阻塞点 3）
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
就工作区隔离、执行方式、TDD 模式做**一个联合决策**。规则与判定协议见 `comate/reference/decision-points.md`（先判定"三类行动"，第 3 条）。
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
#### 3a. 能力预检（展示选项前先做）
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
逐维度检查当前平台/仓库实际可执行的选项，只保留可执行者：
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
- **isolation**（脚本枚举仅 `branch` / `worktree`）
|
|
64
|
+
- `worktree`：仅当 `superpowers:using-git-worktrees` skill 可用时保留；不可用则剔除。
|
|
65
|
+
- `branch`：始终可用（HEAD detached 时先提示用户切到实分支）。
|
|
66
|
+
- **build_mode**
|
|
67
|
+
- `subagent-driven-development`：仅当当前平台有真实后台子 agent / Task 派发能力时保留；无则剔除。
|
|
68
|
+
- `executing-plans`：始终可用。
|
|
69
|
+
- **tdd_mode**：`tdd` / `direct` 始终可用。
|
|
70
|
+
|
|
71
|
+
#### 3b. 唯一选项自动应用（属"自动处理"，不阻塞）
|
|
72
|
+
|
|
73
|
+
预检后某维度只剩一个可执行选项，**直接写入并说明原因，不为它单独问用户**。例如：
|
|
74
|
+
|
|
75
|
+
- 仅 `executing-plans` 可用（无后台派发能力）→ 自动写 `build_mode: executing-plans`，说明"无后台子 agent 能力"。
|
|
76
|
+
- 仅 `branch` 可用（`using-git-worktrees` 未安装）→ 自动写 `isolation: branch`，说明"worktree skill 不可用"。
|
|
77
|
+
|
|
78
|
+
多个维度都只剩单值时，一并自动写入并逐条说明；三个维度全部只剩单值时本决策点整体跳过，直接进入 Step 3c 执行。
|
|
79
|
+
|
|
80
|
+
#### 3c. 联合决策（仍有 ≥2 有效选项的维度才问）
|
|
81
|
+
|
|
82
|
+
对仍有多个有效选项的维度，**一次 AskUserQuestion 问清全部**，选 `branch` 时**分支名也在同一次确认**，不得先问是否继续再二次追问配置或命名。已在 3b 自动写入的维度不再列入问题。每个选项附推荐理由（推荐只说明倾向，不代替用户拍板）：
|
|
83
|
+
|
|
84
|
+
- **工作区隔离**：`branch` 新建分支（简单快速，≤3 文件推荐）/ `worktree` 独立工作区（需并行或当前分支有未提交工作时推荐）。
|
|
85
|
+
- **执行方式**：`subagent-driven-development`（任务 ≥3、独立、需双阶段审查）/ `executing-plans`（任务 ≤2 且无跨模块依赖，或来自 hotfix）。
|
|
86
|
+
- **TDD 模式**：`tdd`（涉及业务逻辑/新功能/API，推荐）/ `direct`（无需测试覆盖或用户明确跳过）。
|
|
87
|
+
|
|
88
|
+
用户选择后（连同 3b 已自动应用的维度）写入：
|
|
64
89
|
|
|
65
90
|
```bash
|
|
66
91
|
bash "$COMATE" state <name> set isolation <branch|worktree>
|
|
@@ -52,13 +52,29 @@ git diff --stat "$BASE_REF"...HEAD
|
|
|
52
52
|
|
|
53
53
|
### 1b. 验证失败决策（决策阻塞点 4）
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
验证不通过时**先按严重程度分类，再判定是否需要用户输入**。规则与"三类行动"判定见 `comate/reference/decision-points.md` 第 4 条。
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
分类（**不确定性原则**：无法确定严重程度时降级 SUGGESTION > WARNING > CRITICAL）：
|
|
58
|
+
- **CRITICAL**：构建失败 / 测试失败 / 安全问题 / 核心验收场景失败
|
|
59
|
+
- **WARNING / SUGGESTION**：非阻断性问题（覆盖率不足、风格、优化建议等）
|
|
60
|
+
- **Spec 漂移**：delta spec 与 design doc 矛盾（见 Step 2b 单独处理）
|
|
58
61
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
+
按类别分流：
|
|
63
|
+
|
|
64
|
+
1. **有任何 CRITICAL（且非 Spec 漂移）** —— 属"自动处理"，唯一安全动作就是修复。**不询问**，直接：
|
|
65
|
+
```bash
|
|
66
|
+
bash "$COMATE" state <name> transition verify-fail
|
|
67
|
+
```
|
|
68
|
+
然后调 `/comate-build`。回到 build 前如实报告：哪些是 CRITICAL 失败项、判定依据、将如何修复。
|
|
69
|
+
|
|
70
|
+
2. **无 CRITICAL，仅 WARNING / SUGGESTION** —— 属"用户决策"（接受偏差是合法选择）。**一次性 AskUserQuestion 批量展示**全部失败项与推荐处理，提供：
|
|
71
|
+
- **全部修复**：`bash "$COMATE" state <name> transition verify-fail` 然后调 `/comate-build`
|
|
72
|
+
- **逐项处理**：勾选要修的项，其余接受偏差
|
|
73
|
+
- **接受偏差**：全部接受，须在报告记录每项原因和影响
|
|
74
|
+
|
|
75
|
+
3. **Spec 漂移** —— 按 Step 2b 的单选题处理（属"用户决策"，必须暂停）。
|
|
76
|
+
|
|
77
|
+
> CRITICAL 自动回 build 不代表跳过用户知情：回退前必须输出清晰的失败报告作为证据。若一次验证同时含 CRITICAL 与非 CRITICAL，以 CRITICAL 优先自动回 build，非 CRITICAL 项留待修复轮次一并处理。
|
|
62
78
|
|
|
63
79
|
### 2a. 轻量验证（小改动）
|
|
64
80
|
|