@heihei0299/matt-skills 3.0.16 → 3.0.17

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 (5) hide show
  1. package/.agents/skills/tdd-implement/SKILL.md +11 -10
  2. package/.agents/skills/tdd-implement/references/finalize.md +10 -8
  3. package/.agents/skills/tdd-implement/references/orchestration.md +9 -7
  4. package/.agents/skills/tdd-implement/references/review.md +30 -55
  5. package/package.json +1 -1
package/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -14,7 +14,7 @@ disable-model-invocation: true
14
14
  - **多 issue**：存在多个 `Type: task` 时，读取 [orchestration.md](references/orchestration.md) 后按依赖顺序逐个完成。
15
15
  - `research`、`prototype`、`grilling` 类型任务分流到对应技能。
16
16
 
17
- 每个 issue 开始时记录 `issue_base = HEAD`。Commit 是交付 artifact，不是流程日志：Red-Green / Verify 期间不因 Behavior、阶段切换或验证动作创建 commit。Verify 通过后形成 1 个 Review Point commit；仅当 Full Review 产生 blocking findings 时，最多再形成 1 个 finding-fix commit。
17
+ 每个 issue 开始时记录 `issue_base = HEAD`。Commit 是交付 artifact，不是流程日志：Red-Green / Verify 期间不因 Behavior、阶段切换或验证动作创建 commit。Verify 通过后形成 1 个 Review Point commit；若唯一一次 `code-review` 产生 blocking findings，自动直接修复并最多再形成 1 个 finding-fix commit。
18
18
 
19
19
  生命周期：
20
20
 
@@ -50,22 +50,22 @@ disable-model-invocation: true
50
50
 
51
51
  Verify 通过后读取 [review.md](references/review.md)。
52
52
 
53
- 先将当前 issue 交付所需的代码、测试、文档和配置形成唯一的 committed Review Point commit，再按 `review.md` 完成一次完整 Review 与必要的增量 Review。
53
+ 先将当前 issue 交付所需的代码、测试、文档和配置形成唯一的 committed Review Point commit，再按 `review.md` 调用且只调用 1 次 `code-review`。若产生 blocking findings，直接自动修复并执行必要验证；修复阶段不进入 Red-Green、不执行 TDD、不执行 Incremental Review，也不再次调用 `code-review`。
54
54
 
55
- 完整 Review 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
55
+ 唯一一次 `code-review` 的审查维度、reviewer 数量、提示词和输出格式仍以 [code-review](.agents/skills/code-review/SKILL.md) 为唯一事实源。
56
56
 
57
57
  **出口：**
58
58
 
59
59
  - `full_review_done = true`；
60
60
  - `open_findings` 为空；
61
- - `review_head` 已记录；
62
- - 当前 issue 的实现范围已完整进入 Review 证据。
61
+ - `review_head` 已记录为唯一一次 `code-review` 的 Review Point；
62
+ - 若产生 finding-fix commit，其必要验证已通过。
63
63
 
64
64
  ## Finalize
65
65
 
66
- Review 通过后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
66
+ Review 完成后读取 [finalize.md](references/finalize.md)，只做 tracker/progress/status 收尾并记录 `issue_head`。
67
67
 
68
- Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容，不为单个 issue 创建收尾 commit。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
68
+ Finalize 不新增产品 Behavior，也不修改 Review 阶段已经完成的实现与 finding 修复，不为单个 issue 创建收尾 commit。若收尾时发现实现、测试、文档/配置或验证遗漏，停止当前 issue，不标记 `resolved`，并按 `finalize.md` 报告遗漏请求决策；不得在 Finalize 中补改或重新进入 Red-Green、Verify 或 Review。
69
69
 
70
70
  本次执行批次结束后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多形成 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的实现/Review commit range。
71
71
 
@@ -75,8 +75,9 @@ Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容，
75
75
  - 一个 Behavior 完成后继续下一个 Behavior，直到 Step ① 出口满足。
76
76
  - Verify 只做当前 issue 必要的最终验证；已通过的等价验证不机械重复。
77
77
  - Red-Green / Verify 期间不按 Behavior、阶段或验证动作拆 commit；完整 Review 前只形成 1 个 committed Review Point。
78
- - 每个 issue 只有一次逻辑上的完整双轴 Review；若有 blocking findings，只允许 1 个 finding-fix commit 与最多 1 次逻辑增量 Review。技术失败或中断的恢复规则以 `review.md` 为准。
79
- - 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `HEAD` 作为新的 `issue_base`。
78
+ - 每个 issue 最多调用 1 次 `code-review`；该调用一旦启动即消耗唯一机会，不因 findings、修复或技术失败再次调用。
79
+ - blocking findings 自动直接修复；修复阶段禁止 TDD、禁止 Incremental Review，最多形成 1 个 finding-fix commit。
80
+ - 当前 issue Review 与 Finalize 完成后，才能进入下一个 issue；下一个 issue 以当时的 `issue_head` 作为新的 `issue_base`。
80
81
  - 当前 Step 达到出口后继续进入下一 Step；仅在需要用户决策或存在外部阻塞时暂停。
81
82
 
82
83
  ## References
@@ -85,5 +86,5 @@ Finalize 不新增产品 Behavior，也不修改已经 Review 的实现内容，
85
86
  - Verify：[verify.md](references/verify.md)
86
87
  - Review：[review.md](references/review.md)
87
88
  - Finalize：[finalize.md](references/finalize.md)
88
- - 完整 Review：[code-review](.agents/skills/code-review/SKILL.md)
89
+ - 唯一 Review：[code-review](.agents/skills/code-review/SKILL.md)
89
90
  - 多 issue 编排：[orchestration.md](references/orchestration.md)
package/.agents/skills/tdd-implement/references/finalize.md CHANGED
@@ -1,14 +1,15 @@
1
1
  # Finalize
2
2
 
3
- 仅在 Verify 与 Review 通过后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，不修改已经 Review 的代码、测试、交付文档或配置，也不为单个 issue 创建收尾 commit。
3
+ 仅在 Verify 与 Review 完成后执行。Finalize 只负责 tracker/progress/status 收尾，不新增产品 Behavior，不修改 Review 阶段已经完成的实现或 finding 修复，也不为单个 issue 创建收尾 commit。
4
4
 
5
5
  ## 步骤
6
6
 
7
- 1. 确认 `review_head` 已记录，且 `issue_base...review_head` 对应的实现范围已经完成 Review。
8
- 2. 准备 Acceptance Criteria 与 progress/tracker 的最终状态，记录已 Review 的实现范围、Review、验证与运行结果。外部 tracker 可在此同步；仓库内 tracker/progress/status 只记录为批次待同步状态，不在当前 issue Finalize 中写入或提交。
9
- 3. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
10
- 4. 仅在未发现上述遗漏后，将当前 issue 的完成状态视为 `resolved` 并解除已满足的 blockers；仓库内对应状态仍留待批次 state-sync。
11
- 5. Finalize 不创建 commit；设置 `issue_head = review_head`。此时当前 `HEAD` 应与 `review_head` 一致。
7
+ 1. 确认 `review_head` 已记录为当前 issue 唯一一次 `code-review` 的 Review Point。
8
+ 2. 若 `HEAD != review_head`，确认 `review_head...HEAD` 只包含唯一的 finding-fix commit，且该修复已经完成必要验证；不得对该 commit 再执行 Review。
9
+ 3. 准备 Acceptance Criteria 与 progress/tracker 的最终状态，记录唯一 Review、finding 修复（如有）、验证与运行结果。外部 tracker 可在此同步；仓库内 tracker/progress/status 只记录为批次待同步状态，不在当前 issue Finalize 中写入或提交。
10
+ 4. 若 Finalize 过程中发现任何实现、测试、交付文档、配置或验证遗漏，立即停止当前 issue：保持未完成，不标记 `resolved`，不解除 blockers，不设置成功的 `issue_head`，并报告遗漏请求决策。不得在 Finalize 中补改，也不得自动重新进入 Red-Green、Verify 或 Review。
11
+ 5. 仅在未发现上述遗漏后，将当前 issue 的完成状态视为 `resolved` 并解除已满足的 blockers；仓库内对应状态仍留待批次 state-sync。
12
+ 6. Finalize 不创建 commit；设置 `issue_head = HEAD`。
12
13
 
13
14
  ## 批次状态同步
14
15
 
@@ -21,8 +22,9 @@
21
22
  ## 出口
22
23
 
23
24
  - Acceptance Criteria 全部通过；
24
- - `issue_base...review_head` 的实现范围已经完成 Review；
25
+ - `review_head` 已记录为唯一一次 `code-review` 的 Review Point；
26
+ - 如有 finding-fix commit，其必要验证已通过且未执行第二次 Review；
25
27
  - Finalize 未发现实现、测试、交付文档、配置或验证遗漏；
26
28
  - tracker/progress/status 已同步，或已进入本批次唯一的待同步集合；
27
- - `issue_head = review_head`；
29
+ - `issue_head = HEAD`；
28
30
  - issue 已 `resolved`，已满足的 blockers 已解除。
package/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -22,12 +22,12 @@ for each layer:
22
22
  Verify
23
23
  Review
24
24
  Finalize
25
- issue_head = review_head
25
+ issue_head = HEAD
26
26
  ```
27
27
 
28
- `Review` 包含当前 issue committed Review Point 的形成以及完整/增量 Review；具体以 `SKILL.md` 与 `review.md` 为准。
28
+ `Review` 包含当前 issue committed Review Point 的形成、唯一一次 `code-review`，以及 blocking findings 的直接自动修复（如有）；不执行 Incremental Review。
29
29
 
30
- 一个 issue Finalize 完成后立即进入下一个可调度 issue。Finalize 不为单个 issue 创建 commit，因此 `issue_head = review_head`；下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
30
+ 一个 issue Finalize 完成后立即进入下一个可调度 issue。Finalize 不为单个 issue 创建 commit，因此 `issue_head = HEAD`；下一个 issue 以当前 `issue_head` 作为新的 `issue_base`。前置 issue 未完成时，其依赖项保持 `blocked`。
31
31
 
32
32
  验证与 Finalize 分别以 `verify.md`、`finalize.md` 为准，本文件不重复定义其内部规则。
33
33
 
@@ -44,11 +44,12 @@ for each layer:
44
44
 
45
45
  其中：
46
46
 
47
- - `issue_base...review_head` 是已完成 Review 的实现范围；
48
- - `issue_head = review_head`，因此 `issue_base...issue_head` 只包含当前 issue 的 Review Point commit，以及可选的唯一 finding-fix commit；
47
+ - `issue_base...review_head` 是唯一一次 `code-review` 审查的 committed Review Point 范围；
48
+ - 若存在 finding-fix commit，则 `review_head...issue_head` 只包含该唯一自动修复 commit，且不再 Review；
49
+ - `issue_base...issue_head` 是当前 issue 的完整提交范围，最多包含 Review Point commit 与可选的 finding-fix commit；
49
50
  - `issue_head` 是下一个 issue 的 `issue_base`。
50
51
 
51
- 当前层所有 issue 完成后进入下一层。全部层完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的提交范围。随后确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行完整 Review。
52
+ 当前层所有 issue 完成后进入下一层。全部层完成后，如仓库内 tracker/progress/status 存在待同步状态，统一写入并最多创建 1 个 batch state-sync commit；该 commit 不属于任何单个 issue 的提交范围。随后确认 issue 与 progress 状态一致即可结束；不额外扩大验证范围，也不再次执行 `code-review`。
52
53
 
53
54
  ## 冲突与失败
54
55
 
@@ -61,6 +62,7 @@ for each layer:
61
62
 
62
63
  - 所有可执行 issue 均按依赖顺序完成；
63
64
  - issue、依赖状态与 progress 一致；
64
- - 每个完成 issue 的 `issue_base`、`review_head` 与 `issue_head` 边界明确，且每个 issue 最多包含 2 个由本技能产生的实现/Review commits；
65
+ - 每个完成 issue 只调用 1 次 `code-review`，Incremental Review 调用次数为 0；
66
+ - 每个完成 issue 最多包含 2 个由本技能产生的实现/修复 commits；
65
67
  - 仓库内状态同步如有需要，只形成最多 1 个批次 state-sync commit；
66
68
  - 不存在被误当作已完成的 blocked issue。
package/.agents/skills/tdd-implement/references/review.md CHANGED
@@ -1,30 +1,28 @@
1
1
  # Review
2
2
 
3
- 仅在 Verify 通过后执行。本文件负责当前 issue 的 committed Review Point、Review 状态与增量复核；完整 Review 的维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
3
+ 仅在 Verify 通过后执行。本文件负责当前 issue 的 committed Review Point、唯一一次 `code-review` 以及 finding 自动修复；`code-review` 的维度、reviewer 数量、提示词和输出格式仍以 `code-review` 为唯一事实源。
4
4
 
5
5
  ## 状态
6
6
 
7
- 当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次；后续因 finding 修复返回 Red-Green / Verify 后继续 Review 时保留现有状态，不得重新初始化：
7
+ 当前 issue 首次进入 Review 时初始化以下状态，且仅初始化一次：
8
8
 
9
9
  - `issue_base`：当前 issue 开始时的 `HEAD`；
10
10
  - `full_review_done = false`；
11
11
  - `open_findings = []`；
12
- - `last_reviewed_head = null`；
13
- - `review_head = null`；
14
- - `incremental_review_rounds = 0`。
12
+ - `review_head = null`。
15
13
 
16
14
  ## 1. 形成 committed Review Point
17
15
 
18
- 完整 Review 前：
16
+ 调用 `code-review` 前：
19
17
 
20
18
  1. 确认当前 issue 交付所需的代码、测试、文档和配置均已完成；
21
19
  2. 若最后的文档/配置修改影响已验证证据，重新验证受影响范围；
22
20
  3. 将当前 issue 已完成并验证的交付修改合并形成当前 issue 唯一的 Review Point commit；不得按 Behavior、阶段或验证动作拆分 commit；
23
21
  4. 确认不存在属于当前 issue 交付内容的未提交修改。
24
22
 
25
- 完整 Review 前每个 issue 只形成 1 个 Review Point commit。Commit 是交付 artifact，不是流程日志。
23
+ 每个 issue 只形成 1 个 Review Point commit。Commit 是交付 artifact，不是流程日志。
26
24
 
27
- 完整 Review 使用：
25
+ 唯一一次 `code-review` 使用：
28
26
 
29
27
  - fixed point：`issue_base`；
30
28
  - review target：当前 `HEAD`；
@@ -33,66 +31,43 @@
33
31
 
34
32
  不得用未提交 working tree 代替该 committed diff。
35
33
 
36
- ## 2. 完整 Review
34
+ ## 2. 唯一一次 code-review
37
35
 
38
- 当 `full_review_done = false` 时，只启动一次逻辑上的完整 `code-review`。
36
+ 每个 issue 最多调用 1 次 `code-review`。
39
37
 
40
- 只有 `code-review` 要求的审查轴均正常返回并形成完整聚合结果后，才：
38
+ 调用开始前确认 `full_review_done = false`。调用一旦启动，即消耗当前 issue 唯一的 `code-review` 机会；不得因 findings、修复、工具错误、stream interruption、sub-agent failure 或其它原因再次调用 `code-review`。
41
39
 
42
- - 设置 `full_review_done = true`；
43
- - 将 blocking findings 写入 `open_findings`；
44
- - 设置 `last_reviewed_head = HEAD`。
45
-
46
- 工具错误、stream interruption、sub-agent failure 或其它未形成完整聚合结果的技术失败，不改变 `full_review_done`、`open_findings` 或 `last_reviewed_head`。恢复时只补足缺失的执行结果；这种技术重试不算新的逻辑完整 Review。
47
-
48
- `full_review_done = true` 后，完整 `code-review` 路径关闭，不得再次启动完整双轴 Review。
49
-
50
- 若 `open_findings` 为空，设置 `review_head = last_reviewed_head`，Review 通过。
51
-
52
- ## 3. 增量 Review
53
-
54
- 存在 `open_findings` 时，只处理已有 finding，不扩大当前 issue 范围。一次性处理当前全部 open findings，不按 finding 拆分 commit。
40
+ 若 `code-review` 正常形成完整聚合结果：
55
41
 
56
- 每个 issue 最多执行 1 个逻辑增量 Review 轮次。只有正常形成增量 Review 结论的轮次才计数；工具错误、stream interruption、sub-agent failure 或其它未形成完整结论的技术失败不消耗轮次，只重试当前逻辑轮次。
57
-
58
- 若 `incremental_review_rounds >= 1` 且 `open_findings` 仍非空，则停止当前 issue：不得再次启动增量 Review，不设置 `review_head`，不得进入 Finalize，并报告剩余 findings 请求决策。
59
-
60
- 唯一一轮 finding 修复：
61
-
62
- 1. 一次性修复当前全部 open findings；
63
- 2. 若修复产生新的 Behavior，返回 Red-Green 对该 Behavior 执行 TDD；否则直接进入受影响证据的重新验证；
64
- 3. 重新验证全部修复直接影响的证据；
65
- 4. 将本轮全部修复合并形成最多 1 个 finding-fix commit，并确认不存在属于本轮修复的未提交修改；不得按 finding 拆分 commit；
66
- 5. 只针对 `last_reviewed_head...HEAD` 与现有 findings 做增量 Review；增量 Review 不调用完整 `code-review`。
67
-
68
- 若增量 Review 正常形成结论，先设置 `incremental_review_rounds += 1`。
42
+ - 设置 `full_review_done = true`；
43
+ - 设置 `review_head = HEAD`，记录本次唯一 Review 的 committed Review Point；
44
+ - 将 blocking findings 写入 `open_findings`。
69
45
 
70
- 增量 Review 通过时：
46
+ 若该次调用因技术原因未形成完整聚合结果，停止当前 issue并报告实际失败；不得重跑 `code-review`，不得进入 Finalize。
71
47
 
72
- - 仅关闭已由证据确认解决的 findings；
73
- - 设置 `last_reviewed_head = HEAD`。
48
+ 若 `open_findings` 为空，Review 完成，进入 Finalize。
74
49
 
75
- 增量 Review 正常完成但仍有 open findings 时：
50
+ ## 3. blocking findings 自动修复
76
51
 
77
- - 保留未关闭 findings；
78
- - 不推进 `last_reviewed_head`；
79
- - 停止当前 issue，不设置 `review_head`，不进入 Finalize，并报告剩余 findings 请求决策。
52
+ 若 `open_findings` 非空：
80
53
 
81
- 增量 Review 发生技术失败时：
54
+ 1. 一次性直接修复当前全部 blocking findings，不扩大当前 issue 范围；
55
+ 2. 修复阶段不得返回 Red-Green，不执行 TDD；
56
+ 3. 对修复直接影响的证据执行必要验证；
57
+ 4. 验证通过后，将全部修复合并形成最多 1 个 finding-fix commit；不得按 finding 拆分 commit；
58
+ 5. 修复后禁止 Incremental Review，禁止再次调用 `code-review`；
59
+ 6. 确认 findings 已按本轮修复处理后清空 `open_findings`。
82
60
 
83
- - 不增加 `incremental_review_rounds`；
84
- - 不推进 `last_reviewed_head`；
85
- - 不移除未确认关闭的 findings；
86
- - 恢复后重试当前逻辑轮次。
61
+ 若修复无法完成或必要验证不通过，停止当前 issue，保留未解决 findings，不进入 Finalize。
87
62
 
88
- 当 `open_findings` 为空时，设置 `review_head = last_reviewed_head`，Review 通过。
63
+ finding-fix commit 位于 `review_head` 之后；它是唯一 Review 后的自动修复，不属于再次 Review 的输入。
89
64
 
90
65
  ## 出口
91
66
 
92
67
  - `full_review_done = true`；
68
+ - `review_head` 非空，且指向唯一一次 `code-review` 的 Review Point；
93
69
  - `open_findings` 为空；
94
- - `review_head` 非空；
95
- - `incremental_review_rounds <= 1`；
96
- - `review_head` 指向 Review Point commit，或唯一的 finding-fix commit；
97
- - `issue_base...review_head` 是已经完成 Review 的当前 issue 实现范围，最多包含 2 个由本技能产生的 issue commits；
98
- - 不存在属于该实现范围的未提交交付修改。
70
+ - Incremental Review 调用次数为 0；
71
+ - `code-review` 调用次数为 1；
72
+ - 当前 `HEAD` 为 `review_head`，或为其后的唯一 finding-fix commit；
73
+ - 不存在属于当前 issue 的未提交交付修改。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heihei0299/matt-skills",
3
- "version": "3.0.16",
3
+ "version": "3.0.17",
4
4
  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
5
5
  "type": "module",
6
6
  "bin": {