@heihei0299/matt-skills 2.1.3 → 2.1.7

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 (21) hide show
  1. package/.agents/skills/grill-to-spec/SKILL.md +22 -14
  2. package/.agents/skills/grill-to-spec/references/rules.md +24 -5
  3. package/.agents/skills/implement-review-loop/SKILL.md +34 -0
  4. package/.agents/skills/implement-review-loop/agents/openai.yaml +5 -0
  5. package/.agents/skills/tdd-implement/SKILL.md +2 -2
  6. package/.agents/skills/tdd-implement/references/orchestration.md +6 -6
  7. package/.agents/skills/tdd-implement/references/stages.md +4 -5
  8. package/.agents/skills/tdd-implement/references/verify.md +1 -1
  9. package/README.md +56 -161
  10. package/package.json +1 -1
  11. package/template/.agents/skills/grill-to-spec/SKILL.md +22 -14
  12. package/template/.agents/skills/grill-to-spec/references/rules.md +24 -5
  13. package/template/.agents/skills/implement-review-loop/SKILL.md +34 -0
  14. package/template/.agents/skills/implement-review-loop/agents/openai.yaml +5 -0
  15. package/template/.agents/skills/tdd-implement/SKILL.md +2 -2
  16. package/template/.agents/skills/tdd-implement/references/orchestration.md +6 -6
  17. package/template/.agents/skills/tdd-implement/references/stages.md +4 -5
  18. package/template/.agents/skills/tdd-implement/references/verify.md +1 -1
  19. package/template/.opencode/commands/grill-to-spec.md +2 -2
  20. package/template/AGENTS.md +16 -3
  21. package/template/PROJECT.md +3 -0
package/.agents/skills/grill-to-spec/SKILL.md CHANGED
@@ -6,42 +6,50 @@ disable-model-invocation: true
6
6
 
7
7
  # Grill to Spec
8
8
 
9
- 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试。
9
+ 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试、不自动 commit。
10
10
 
11
11
  ## 流程
12
12
 
13
+ ### 0. 预检
14
+
15
+ - 只读确认 issue tracker、目标上下文、feature slug 和已有 spec/issue 状态。
16
+ - tracker 未配置、slug 不明确或目标路径不可写时，在任何 ADR/spec/issue 写入前报告阻塞。
17
+ - 已有同一 feature 的产物先读取并比较；相同共识不重复发布，设计变化进入变更流程。
18
+
13
19
  ### ① 形成共识
14
20
 
15
21
  调用 [`grill-with-docs`](.agents/skills/grill-with-docs/SKILL.md)，由 `grilling` 与 `domain-modeling` 完成采访、术语和设计决策。
16
22
 
17
23
  - glossary 按上游规则 inline 更新；
18
- - 只有确需 ADR 时才创建 ADR 草稿；
19
- - ADR 必须先展示完整草稿，用户明确确认后才写入，未确认不得落盘。
24
+ - 只有同时满足 ADR 条件时才提出 ADR，但 ADR 等最终决策清单确认后再写入；
25
+ - 在本阶段让 [`to-spec`](.agents/skills/to-spec/SKILL.md) 做代码理解和 seam 分析；seam 是共识的一部分，不单独制造发布确认；
26
+ - 形成精简决策清单：目标、范围、关键选择、seam、未纳入范围和待验证假设；只展示清单，不展示任何 ADR/spec/issue 正文或草稿；
27
+ - 用户确认决策清单后，立即进入阶段 ②。
20
28
 
21
- 出口：用户确认共识已达成，且所有 ADR 草稿都已获得单独确认或明确不写入。
29
+ 出口：决策清单已确认，glossary 已按需更新；尚未确认的 ADR/spec/issue 不写入。
22
30
 
23
31
  ### ② 发布 spec
24
32
 
25
- 将已确认的共识交给 [`to-spec`](.agents/skills/to-spec/SKILL.md)，完成代码库理解、seam 提案和 spec 组装。
33
+ 将已确认的决策清单和 seam 分析交给 `to-spec`；此处只综合、写入和发布，不重新采访或再次确认 seam。
26
34
 
27
- - 将 seam 提案并入最终 spec 草稿，不单独制造一次重复确认；
28
- - 发布前展示完整 spec 草稿，用户一次明确确认后才写入 `.scratch/<feature-slug>/spec.md`；
29
- - 发布时使用 `ready-for-agent`，格式细则只读取 [`references/rules.md`](references/rules.md)。
35
+ - 按 ADR → spec → issue 的顺序执行；issue 发布成功后设置 `ready-for-agent`；格式细则只读取 [`references/rules.md`](references/rules.md)。
36
+ - 相同 feature 复用已有产物，设计变化按 tracker 的更新语义保留历史；
37
+ - 任一步失败都保留已成功写入的内容，记录状态和失败点，重跑时从第一个未完成出口继续；不回滚、不重复发布。
30
38
 
31
- 出口：spec 已发布，路径、状态和未纳入范围已报告。
39
+ 出口：ADR/spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围，不复制正文。
32
40
 
33
41
  ## 回合连续性
34
42
 
35
- 本 skill 是 Long-Horizon Skill。阶段 ① 达到出口后立即进入阶段 ②；正常的阶段切换、进度汇报或“接下来生成 spec”不是回合终点。仅在必须获得用户确认的 ADR/spec 草稿、明确外部阻塞、用户主动停止或整个 skill 出口时暂停。确认完成后在同一任务链继续推进到下一可验证出口，不要求用户额外回复“继续”。
43
+ 本 skill 是 Long-Horizon Skill。预检、阶段 ①、代码理解、决策清单确认后的阶段 ② 在同一任务链连续执行；进度汇报和阶段切换不是回合终点。仅在需要设计确认、决策清单确认、外部阻塞、用户主动停止或整个 skill 出口时暂停；确认完成后不要求用户额外回复“继续”。
36
44
 
37
45
  ## 本 skill 独有门禁
38
46
 
39
- - ADR：草稿 → 用户确认 → 落盘，任何情况不例外；
40
- - spec：共识与 seam 合并为一个最终草稿，只设置一次发布前确认；
41
- - 全程不写代码、不修改测试、不执行实现。
47
+ - 文档正文永不展示；用户只确认精简决策清单，发布后只接收元数据报告；
48
+ - ADR/spec/issue 不设置额外草稿确认；
49
+ - 不写代码、不修改源码或测试、不自动 commit；实现 tickets 交给 `to-tickets`。
42
50
 
43
51
  ## 异常
44
52
 
45
53
  - 用户放弃或没有可形成 spec 的主题时终止；
46
54
  - issue tracker 未配置时报告配置阻塞，不绕过发布；
47
- - 用户改变已确认的设计时回到 ①，不在 ② 静默扩大范围。
55
+ - 用户改变已确认设计时回到阶段 ①，按变更语义保留历史，不静默覆盖。
package/.agents/skills/grill-to-spec/references/rules.md CHANGED
@@ -2,25 +2,44 @@
2
2
 
3
3
  本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
4
4
 
5
+ ## 预检与状态规则
6
+
7
+ - 写入前只读确认 issue tracker、目标上下文、feature slug、已有 spec/issue 和当前状态；tracker 未配置或目标不可写时不写 ADR/spec/issue。
8
+ - feature slug 是 spec 路径和 issue 幂等键；候选不明确或冲突时才询问。
9
+ - 记录共识、ADR、spec、issue、`ready-for-agent` 出口；重跑从第一个未完成出口继续，不重复已成功动作。
10
+ - 已有相同共识的 feature 只报告已有路径或标识；设计变化走变更流程，不创建重复 issue。
11
+
5
12
  ## Glossary 增量规则
6
13
 
7
14
  - 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
8
15
  - 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
9
- - glossary 可按上游流程 inline 更新，不额外增加确认轮次。
16
+ - glossary 可按上游流程 inline 更新，不额外增加确认轮次；设计变化时按历史保留规则修正。
10
17
 
11
18
  ## ADR 增量规则
12
19
 
13
20
  - 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
14
- - ADR 草稿必须完整展示并获得用户明确确认后才落盘；这是本 skill 的独有硬门禁。
15
- - 不把 ADR 当 glossary 一样静默 inline 更新。
21
+ - ADR 不像 glossary 一样静默 inline 更新；等最终决策清单确认后直接落盘，不展示正文，不增加独立确认轮次。
22
+ - 用户改变决策时不静默覆盖旧 ADR；按项目 ADR 规则追加、废弃或标记 superseded。
16
23
 
17
24
  ## Spec 增量规则
18
25
 
19
26
  - Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
20
- - seam 提案并入最终 spec 草稿，不再制造独立的一次确认。
21
- - 发布前只做一次最终 spec 明确确认；确认后写入并标记 `ready-for-agent`。
27
+ - 代码理解和 seam 分析属于共识阶段；seam 纳入最终决策清单，不在发布阶段再次询问。
28
+ - 决策清单确认后直接写入 spec；不展示 spec 正文或草稿。
22
29
  - 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
23
30
 
31
+ ## Issue 增量规则
32
+
33
+ - 按已配置的 issue tracker 直接发布唯一 spec issue；implementation tickets 交给 `to-tickets`。
34
+ - issue 正文不在对话中展示；发布成功后设置 `ready-for-agent`。
35
+ - issue 创建成功但 label/status 更新失败时保留 issue，报告标识和失败点，不删除、不误报为 ready。
36
+ - 设计变化委托 tracker 的原生更新语义：本地追加变更记录，远端按 body/comment/关联关系更新；不另造版本模板。
37
+
38
+ ## 失败与 Git 边界
39
+
40
+ - 任一步失败都保留已成功写入的内容并报告部分状态；不做跨文件或跨 tracker 回滚，不盲目重试。
41
+ - 本 skill 不自动创建 Git commit；发布文档与 Git 提交是两个独立出口。
42
+
24
43
  ## 反模式
25
44
 
26
45
  - 不复制 `to-spec` 的章节清单、User Story 模板或 Implementation Decisions 细则。
package/.agents/skills/implement-review-loop/SKILL.md ADDED
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: implement-review-loop
3
+ description: "Implement changes with one executor model and one independent reviewer model, iterating on only the changed surface until no actionable issues remain."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ Use two distinct roles:
8
+
9
+ - **Executor**: implements the requested change, fixes findings, and runs the smallest relevant verification.
10
+ - **Reviewer**: independently reviews the latest diff and relevant verification results. It does not perform the implementation.
11
+
12
+ Workflow:
13
+
14
+ ```text
15
+ Executor implements
16
+ → targeted verification
17
+ → Reviewer reviews latest diff
18
+ → if findings exist: Executor fixes only those findings
19
+ → targeted re-verification
20
+ → Reviewer re-reviews changed parts and unresolved findings
21
+ → repeat until Reviewer reports no actionable issues
22
+ ```
23
+
24
+ Rules:
25
+
26
+ - Keep implementation, testing, and review scoped to the current change and directly affected paths.
27
+ - Prefer targeted tests: changed test files, affected modules, regression cases, or the original reproduction path.
28
+ - Do not rerun equivalent checks after every small edit.
29
+ - Reviewer should inspect the latest diff first, then only enough surrounding code to validate behavior and integration.
30
+ - On subsequent rounds, review the new changes plus unresolved findings; do not restart a whole-project review.
31
+ - Expand test or review scope only when the change crosses modules, modifies shared/public contracts or core infrastructure, targeted evidence is insufficient, final release/merge validation requires it, or the user explicitly requests it.
32
+ - Findings must be concrete and actionable. Separate blockers from optional improvements.
33
+ - Stop the loop when the Reviewer has no actionable findings and targeted verification is green.
34
+ - Do not let the Reviewer silently become the Executor; preserve role independence throughout the loop.
package/.agents/skills/implement-review-loop/agents/openai.yaml ADDED
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Implement Review Loop"
3
+ short_description: "Implement with an independent review loop"
4
+ policy:
5
+ allow_implicit_invocation: false
package/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -16,7 +16,7 @@ disable-model-invocation: true
16
16
  - **多 issue**：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 文件时，先读取 [orchestration.md](references/orchestration.md)，按 `Blocked by` 构建 DAG、Kahn 分层，再由主代理按层串行完成各 issue。
17
17
  - `Type: research`、`prototype`、`grilling` 分流到对应技能，不进入本技能。
18
18
 
19
- 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、全量收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
19
+ 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、最终收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
20
20
 
21
21
  ## 三阶段 Steps
22
22
 
@@ -40,7 +40,7 @@ Finalize 出口：commit 已创建、Acceptance Criteria 全部通过，Tracker
40
40
  - 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度只在进入 Step ② 时读取 [red-green.md](references/red-green.md)。
41
41
  - 每个 issue 只在 Verify 的最终 diff 稳定后调用一次 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；A3 层收敛不再次调用 review。
42
42
  - 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；三个阶段出口与 Finalize 全部满足后才可标记 `resolved`。
43
- - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，全仓测试由 orchestration 的 A4 在全部 issue 完成后执行一次。
43
+ - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，A4 只做最终编排收敛，不额外扩大测试范围。
44
44
 
45
45
  ## 引用
46
46
 
package/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -10,7 +10,7 @@
10
10
  - [A1：Kahn 拓扑分层](#a1kahn-拓扑分层)
11
11
  - [A2：分层串行调度](#a2分层串行调度)
12
12
  - [A3：层收敛](#a3层收敛)
13
- - [A4：全量收敛](#a4全量收敛)
13
+ - [A4：最终收敛](#a4最终收敛)
14
14
  - [A5：回退与冲突处理](#a5回退与冲突处理)
15
15
 
16
16
  ---
@@ -80,7 +80,7 @@ for each layer Li in L1..Ln:
80
80
  全部层完成后进入 A4
81
81
  ```
82
82
 
83
- 每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
83
+ 每个 issue 的 Verify 只运行当前 issue 影响范围内的测试；编排层不额外扩大测试范围。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
84
84
 
85
85
  主代理在层内和层间连续调度：一个 issue 的 Finalize 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
86
86
 
@@ -129,11 +129,11 @@ A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每
129
129
 
130
130
  任一项失败，定位到该层失败 issue，按 A5 回退并重做该 issue 的受影响阶段或 Behavior，然后重新收敛本层。
131
131
 
132
- ## A4：全量收敛
132
+ ## A4：最终收敛
133
133
 
134
134
  全部层完成且各层收敛通过后：
135
135
 
136
- 1. 按 A0 的验证矩阵运行一次仓库全量测试；这是多 issue 流程唯一的全量回归点。只有修复全量失败后才允许必要重跑；
136
+ 1. 汇总并确认各 issue 的相关测试、typecheck/build、真实运行和 review 证据仍对应最终状态；若后续改动使证据失效，只重新验证受影响范围；
137
137
  2. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`；失败时按 A5 恢复后重验；
138
138
  3. 执行 `git status`，确认无 `[DEBUG-...]`、一次性脚本或未跟踪临时文件；
139
139
  4. 汇总各 issue 回执卡片的 commit、Behaviors、Acceptance Criteria、测试、真实运行和文档对齐结果；汇总只在对话输出，不另写汇总文件。
@@ -141,7 +141,7 @@ A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每
141
141
  ### A4 出口
142
142
 
143
143
  - 全部 issue 已有独立 commit、实施总结和 `progress.md` 派生记录；
144
- - 全量测试通过；
144
+ - 各 issue 的受影响验证证据仍对应最终状态；
145
145
  - 工作区卫生、历史校验和真实运行要求均满足；
146
146
  - `progress.md` 与 `issues/*.md` 一致，不一致时以 issue 真相源为准并修复派生视图。
147
147
 
@@ -156,7 +156,7 @@ A5 负责所有编排级失败，不把失败静默吞掉，也不把不相关
156
156
  | Red-Green 的有效 Red、实现、typecheck 或 targeted test 失败 | 回到该 issue 的 Red-Green，修复当前 Behavior 并重新验证 |
157
157
  | Verify 的测试、build、真实运行或 review blocking finding 失败 | 回到受影响 issue 的对应阶段；修复后只做受影响检查和 delta review |
158
158
  | Finalize 的必要 docs、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Finalize 问题后重新验证 |
159
- | 全量测试失败 | 定位到引入失败的 issue，按上述路径修复；只在修复后重跑必要范围和全量测试 |
159
+ | A4 收敛发现验证证据失效 | 定位到受影响 issue，按上述路径修复；只重新验证受影响范围 |
160
160
  | `Blocked by` 依赖未完成 | 后续 issue 保持 `blocked`，前置 issue resolved 后自动解阻 |
161
161
  | 多 issue 预期修改同一文件 | 记录冲突，按编号串行；无法安全归属时暂停并请求用户决定 |
162
162
  | Git 历史祖先校验失败 | 立即停止写入，使用 `git reflog` 找回 `BASE_HEAD` 之后的提交，校验通过后继续 |
package/.agents/skills/tdd-implement/references/stages.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # 三阶段详细定义 + Finalize
2
2
 
3
- 单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、全量收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
3
+ 单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、最终收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
4
4
 
5
5
  ## 目录
6
6
 
@@ -61,7 +61,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finaliz
61
61
  - `code-review` 可用性；
62
62
  - 可用的 browser 或 Playwright 路径；
63
63
  - ticket 要求的真实运行验证方式。
64
- 6. 建立一次验证矩阵，列出 targeted tests、typecheck、全量测试、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
64
+ 6. 建立一次验证矩阵，列出 targeted tests、typecheck、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
65
65
  7. 识别公共测试边界和 Behaviors。一个 Seam 是一个公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 Seam 可以包含多个 Behaviors。每个 Behavior 明确输入、可观察输出、对应 Acceptance Criterion 和验证层级。
66
66
  8. spec 已确认且未变化的 Seam 直接复用；只有出现需求歧义、验收缺口、范围变化、破坏性操作或互斥方案时才请求用户确认。
67
67
 
@@ -142,8 +142,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finaliz
142
142
 
143
143
  ### 测试与真实运行验证
144
144
 
145
- - 多 issue 模式只运行当前 issue 影响范围内的完整测试；不在每个 issue 重复运行全仓测试。全部 issues 完成后由 orchestration A4 运行一次全仓测试。
146
- - 单 issue 或单 spec 模式运行仓库完整测试。按照 Contract 的验证矩阵执行，不同时运行等价命令。
145
+ - 单 issue / 单 spec 与多 issue 均只运行当前 issue 影响范围内的测试，按照 Contract 的验证矩阵执行，不同时运行等价命令；不因进入 Verify 自动扩大测试范围。
147
146
  - ticket 要求真实运行时，优先使用专用 browser 工具，其次使用项目已有 Playwright；HTTP/CLI 只能补充 API 验证，不能替代 WebUI 验证。
148
147
  - 真实进程验证使用隔离配置和临时端口，保存 PID，记录实际请求结果或页面可见结果，结束时清理进程和临时目录。
149
148
 
@@ -252,4 +251,4 @@ Progress: pending | in_progress | done | blocked
252
251
  | ③ Verify | 测试、build、真实运行或 review finding 失败 | → ② 修复 Behavior；需求偏差 → ① |
253
252
  | Finalize | 必要 docs 未同步、commit 失败或 Tracker 信息不完整 | → ①/③ 修复对应问题；仍在 Finalize 完成前解决 |
254
253
 
255
- 多 issue 的层收敛、全量失败、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。
254
+ 多 issue 的层收敛、最终收敛、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。
package/.agents/skills/tdd-implement/references/verify.md CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  ## 规则
10
10
 
11
- - 单 issue / 单 spec：按 Contract 验证矩阵运行完整相关测试；多 issue：只跑当前 issue 影响范围，全仓测试留给 orchestration A4。
11
+ - 单 issue / 单 spec 与多 issue 均按 Contract 验证矩阵运行当前 issue 影响范围测试；不因进入 Verify 自动扩大测试范围。
12
12
  - ticket 要求真实运行时，优先专用 browser，其次项目已有 Playwright；HTTP/CLI 不能替代 WebUI 可见验证。
13
13
  - 临时进程必须使用隔离配置/端口，记录 PID 与实际结果，结束后清理。
14
14
  - 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。`tdd-implement` 只规定调用时机；审查维度、reviewer 数量、提示词、上下文与输出格式以 `code-review` 为唯一事实源。
package/README.md CHANGED
@@ -1,32 +1,26 @@
1
1
  # matt-skills
2
2
 
3
- mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓库：工作区维护完整 skill 集合，其中一部分 proprietary skill 只供本仓库使用；`template/` 只包含可分发内容，以 npm 包 `@heihei0299/matt-skills` 分发，目标仓库一条命令即完成初始化。
3
+ 面向项目仓库的 Agent skills 与配置模板。模板包含共享 skills、`AGENTS.md`、项目上下文占位文件，以及 pi / opencode 所需的项目配置。
4
4
 
5
- ## 模板结构
5
+ ## 模板内容
6
6
 
7
- ```
7
+ ```text
8
8
  template/
9
- ├── AGENTS.md 项目级全局配置（行为路由 + 分文件指针）
10
- ├── .agents/
11
- │ └── skills/ workspace 的完整 skill 单一源；template 只携带可分发 skill，默认安装 programming 范围，--all 展开全部可分发 skill
12
- ├── .pi/ pi-agent 项目配置
13
- │ ├── skills/ 空占位（项目自定义技能，含 .gitkeep + README.md）
14
- │ ├── prompts/ issue-audit 命令（prompt template）
15
- │ ├── docs/agents/ 5 个分文件镜像
16
- │ └── CONTEXT.md 术语表镜像
17
- └── .opencode/ opencode 项目配置
18
- ├── skills/ 空占位（项目自定义技能，含 .gitkeep + README.md）
19
- ├── agents/ issue-audit 子代理定义
20
- ├── commands/ issue-audit + 可分发的显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
21
- ├── docs/agents/ 5 个分文件（运行时纪律 / 技能设计 / issue tracker / triage labels / domain）
22
- ├── CONTEXT.md 术语表
23
- ├── package.json 插件依赖清单
24
- └── .gitignore
9
+ ├── AGENTS.md Agent 行为路由与项目上下文入口
10
+ ├── PROJECT.md 目标项目填写的目标、范围和主要入口
11
+ ├── .agents/skills/ 共享 skills 的唯一项目级来源
12
+ ├── .opencode/ opencode agents、commands、docs
13
+ └── .pi/ pi prompts、docs 与项目自定义 skills 占位
25
14
  ```
26
15
 
16
+ - `PROJECT.md` 描述项目是什么；操作规则放在 `AGENTS.md`。
17
+ - `.opencode/CONTEXT.md` / `.pi/CONTEXT.md` 保存领域术语与边界。
18
+ - `.opencode/skills/` 与 `.pi/skills/` 仅用于项目自定义 skills。
19
+ - `ci-guard`、`commit-check` 是本仓库维护用的 repo-local skills，不会分发到目标项目。
20
+
27
21
  ## 独有 skill 分发边界
28
22
 
29
- 本仓库维护 7 个独有（proprietary）skill：
23
+ 本仓库有 7 个独有（proprietary）skills：
30
24
 
31
25
  ### 可分发的 5 个
32
26
 
@@ -36,194 +30,95 @@ template/
36
30
  - `scaffold-functional-test`
37
31
  - `show-me`
38
32
 
39
- 默认 programming 范围中的 4 个独有 skill 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`；`scaffold-functional-test` 可分发但默认可选。
40
-
41
33
  ### 仓库内部的 2 个
42
34
 
43
35
  - `ci-guard`
44
36
  - `commit-check`
45
37
 
46
- `ci-guard` 和 `commit-check` 只服务 matt-skills 仓库自身，不会通过 `list`、`install`、`init`、`sync`、`--all` 或 global install 分发到用户项目。workspace 保留完整集合，template 只包含可分发集合。
38
+ repo-local skills 不会通过 `init`、`install`、`sync` 分发到用户项目。
47
39
 
48
40
  ## 初始化
49
41
 
50
- 在目标仓库根目录执行一条命令：
42
+ 在目标仓库根目录执行：
51
43
 
52
44
  ```sh
53
- npx @heihei0299/matt-skills init # 默认 programming 范围
54
- npx @heihei0299/matt-skills init --all # 安装全部可分发 skill（含 productivity）
45
+ npx @heihei0299/matt-skills init # 安装默认 programming skills
46
+ npx @heihei0299/matt-skills init --all # 安装全部可分发 skills
55
47
  ```
56
48
 
57
- `init` 默认只在目标没有 `AGENTS.md` 时初始化；已有项目默认跳过以保护定制，显式 `init --all` 会刷新模板并安装/覆盖全部可分发 skill。模板已经包含可分发内容，无需二次拉取上游；repo-local skill 不会进入目标项目。
58
-
59
- 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含全部可分发的非默认 skill（包括 productivity 和 optional proprietary）；已有目标使用 `init --all` 刷新，普通 `init` 跳过。
60
- **增量同步（已有项目）**：已有项目更新到最新模板与技能：
49
+ 已有项目同步：
61
50
 
62
51
  ```sh
63
- npx @heihei0299/matt-skills sync # 默认安全增量：同步默认 programming skill（不删多余）
64
- npx @heihei0299/matt-skills sync --all # 同步全部可分发 skill（不删多余）
65
- npx @heihei0299/matt-skills sync --dry-run --json # 预演：只比对不写盘（默认范围，--all 可透传）
66
- npx @heihei0299/matt-skills sync --dest <path> --upstream <url> --ref <ref> --json # 选项可组合
52
+ npx @heihei0299/matt-skills sync # 安全增量同步默认范围
53
+ npx @heihei0299/matt-skills sync --all # 同步全部可分发 skills
54
+ npx @heihei0299/matt-skills sync --dry-run --json
67
55
  ```
68
56
 
69
- `sync` 专为已有项目设计，两档语义：写盘模式下默认同步默认 programming 范围，`--all` 同步全部可分发 skill；`--dry-run` 仅对比上游、不写盘，默认比较 engineering + required 的上游部分，`--all` 比较全量上游范围，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`。上游 dry-run/check 不比较 proprietary，因为它们不属于上游；默认安全增量写盘不删多余，模板配置增量更新，旧镜像中的共享 skill 自动清理但保留项目自定义。repo-local skill 永远不新增、不覆盖、不删除，发现历史副本时只提示保留。`--dest`、`--upstream`、`--ref`、`--json`、`--all`、`--dry-run` 可透传。
70
- 目标仓库会话即自动加载可分发共享技能（`.agents/skills/` 单一源）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；可分发的显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
71
- **pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部可分发共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
72
-
73
- **手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全部可分发 skill）：
57
+ `init` 默认保护已有 `AGENTS.md`；需要刷新完整模板时使用 `init --all`。`sync` 不删除目标项目的额外文件或自定义 skills。
74
58
 
75
- ```sh
76
- cp -r template/. /path/to/target/
77
- ```
59
+ 默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
78
60
 
79
- 旧的手动拉取上游步骤已不再需要；若需单独验证上游，仍可：
61
+ ## CLI
80
62
 
81
63
  ```sh
82
- git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-skills
64
+ npx @heihei0299/matt-skills list [--all] [--json]
65
+ npx @heihei0299/matt-skills install [--all] [--tools <list>] [--global] [--dest <dir>]
66
+ npx @heihei0299/matt-skills init [--all] [--dest <dir>]
67
+ npx @heihei0299/matt-skills sync [--all] [--dry-run] [--json] [--dest <dir>]
68
+ npx @heihei0299/matt-skills check [--all] [--json] [--upstream <url>] [--ref <ref>]
83
69
  ```
84
70
 
85
- ## 维护约定
86
-
87
- 改动工作区后，必须同步到 `template/` 对应路径，路径映射如下（同步方向单向：工作区 → 模板快照）：
88
-
89
- | 工作区 | 模板 |
90
- |--------|------|
91
- | `.agents/skills/`（workspace 完整 skill 集合：upstream + proprietary） | `template/.agents/skills/`（仅可分发 skill） |
92
- | `.agents/skills/` 的 harness 占位说明 | `template/.pi/skills/.gitkeep` + `README.md`、`template/.opencode/skills/.gitkeep` + `README.md`（空目录占位，供项目自定义） |
93
- │ │ ├── commands/ issue-audit + 可分发的显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-for-agents）
94
- | `.pi/prompts/issue-audit.md`（pi 命令：opencode 版适配，去 subagent frontmatter） | `template/.pi/prompts/issue-audit.md` |
95
- | `AGENTS.md` | `template/AGENTS.md`（引用映射为 `.opencode/` 路径） |
96
- | `CONTEXT.md` | `template/.opencode/CONTEXT.md` + `template/.pi/CONTEXT.md` |
97
- | `docs/agents/*` | `template/.opencode/docs/agents/*` + `template/.pi/docs/agents/*`（引用映射为 `.opencode/` 路径） |
98
-
99
- 共享技能统一在 `.agents/skills` 单一源，不再双份镜像到 `.opencode/skills` / `.pi/skills`。
100
- `test/template-sync.test.js` 守护同步（含路径映射），漏同步测试即红。
71
+ 常用选项：
101
72
 
102
- 新增技能前先查上游 `mattpocock/skills` 是否已存在；仅上游没有的技能才作为 proprietary skill 落在本仓库。Proprietary skill 再分为 distributable 和 repo-local：后者只服务本仓库，不进入 template 或任何用户安装路径。上游技能通过 `scripts/sync-upstream.js` 同步到 `.agents/skills` 后，只有可分发内容会进入模板。
103
-
104
- ## harness 支持
105
-
106
- 模板同时面向 opencode 与 pi-agent 两种 harness：技能（Agent Skills 标准）与 `AGENTS.md` 行为路由跨 harness 通用，同一份配置两处均可运行。
107
-
108
- 以下为 opencode 专属能力，**pi 下不可用**（不移植，仅文档注明）：
109
-
110
- - `issue-audit`：opencode 以 subagent + command 形式分发（`.opencode/agents/`、`.opencode/commands/`）；pi 无 subagent 机制，以 prompt template 命令分发（`.pi/prompts/issue-audit.md`，去 subagent 委托、保留完整审计流程）
111
- - codegraph MCP：`opencode.jsonc` 配置的代码图服务，pi 无原生 MCP
112
- - `explore` 子代理、`firecrawl` 网页抓取：opencode 会话能力
113
-
114
- pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边界」已按此表述）。
73
+ - `--all`：包含全部可分发 skills，默认范围只包含 programming skills。
74
+ - `--dest <dir>`：指定目标目录。
75
+ - `--tools <list>`：选择 `codex`、`pi`、`opencode` 或 `claude`；项目级共享 skills 统一写入 `.agents/skills/`。
76
+ - `--global`：写入用户级 skills 目录。
77
+ - `--dry-run`：只检查差异，不写入；`--json` 输出机器可读结果。
115
78
 
116
79
  ## Codex CLI 支持
117
80
 
118
- 本仓库将 Codex CLI 作为一等本地 harness 支持。Codex 与 pi、opencode、Claude 共用项目级 `.agents/skills/`，项目级 `AGENTS.md` 继续作为通用行为路由和约束入口。
119
-
120
- - **项目级技能**：`.agents/skills/`（唯一共享源）
121
- - **全局技能**：`~/.codex/skills/`
122
- - **不创建**：项目级 `.codex/skills/` 副本；Codex 技能不单独分叉
123
- - **安装映射**：`--tools codex` 使用 `.agents/skills/`，`--global --tools codex` 使用 `~/.codex/skills/`
124
-
125
- 使用真实 Codex CLI 验证支持：
126
-
127
- ```sh
128
- npm run codex:smoke # 默认 SKIP，不需要 Codex 凭证
129
- CODEX_E2E=1 npm run codex:smoke # 显式运行真实 smoke test
130
- ```
131
-
132
- 真实 smoke test 使用临时 fixture、ephemeral 会话、read-only sandbox 和 JSONL 输出，验证 `AGENTS.md` 与最小 `codex-probe` skill 的 sentinel。结果分为 `PASS`、`SKIP`、`FAIL_ENV` 和 `FAIL_CONTRACT`；环境问题与契约失败分别返回非零退出码。运行结果会记录 `codex --version`，但不绑定最低 CLI 版本。
133
-
134
- 本期不包含 Codex Cloud、Codex-specific commands、plugins 或 MCP 配置。
135
- ## harness 目录结构
136
-
137
- 两个 harness 的技能加载目录结构如下（本项目只分发项目级目录，全局目录由用户自备）：
138
-
139
- ### pi-agent
140
-
141
- - **全局**：`~/.pi/agent/skills/`、`~/.agents/skills/`（用户级技能，自动发现）；配置在 `~/.pi/agent/settings.json`
142
- - **项目**：
143
- - `.agents/skills/` — 可分发共享技能单一源（默认 programming，`--all` 全部可分发，自动发现）
144
- - `.pi/skills/` — 项目自定义技能（pi 标准结构，自动发现，仅放项目本地技能）
145
- - `.pi/prompts/` — pi 命令（prompt template）自动发现，如 `issue-audit.md` → `/issue-audit`
146
- - `.pi/settings.json` — 已简化为空对象（历史指向 `.opencode/skills` 已移除，共享技能走 `.agents/skills`）
147
- ### opencode
148
-
149
- - **项目**：`.agents/skills/`（可分发共享技能单一源，默认 programming，`--all` 全部可分发）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 可分发显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
150
-
151
- 同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：pi 与 codex/claude 从 `.agents/skills/` 自动发现；opencode 按本模板约定同样优先读取 `.agents/skills/`（`.opencode/skills/` 仅用于项目自定义）。
152
-
153
- ## 仓库 CLI
154
-
155
- 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
81
+ Codex 与其他 harness 共用项目级 `.agents/skills/` 唯一共享源；全局 skills 位于 `~/.codex/skills`。
156
82
 
157
83
  ```sh
158
- node bin/cli.js init [--dest <dir>] [--all] # 初始化项目：默认 programming 或全部可分发 skill
159
- node bin/cli.js sync [--all] [--dry-run] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json] # 同步已有项目到最新（默认编程，--all 仅同名 upsert + AGENTS.md）
160
- node bin/cli.js list [--json] [--all] # 列出技能（默认编程）
161
- node bin/cli.js install [选项] # 把技能复制到目标工具目录（交互式选择，默认编程）
162
- node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>] # 只读检查上游技能是否最新（等价 sync --dry-run，默认范围）
84
+ npm run codex:smoke
85
+ CODEX_E2E=1 npm run codex:smoke
163
86
  ```
164
87
 
165
- `init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含全部可分发 skill，见「初始化」。
166
- `sync` 选项：写盘时 `--all` 更新全部可分发同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余；默认写盘只同步默认 programming；`--dry-run` 只比对上游、不写盘（默认 engineering + required 上游范围，`--all` 为全量上游范围，`--json` 可解析，有差异 `exit 1`）；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认安全增量会保留目标定制。
167
- `check` 选项：`--json`、`--all`（默认只比较 engineering + required 上游范围；proprietary 不参与上游 compare）、`--upstream <url>`、`--ref <ref>`（等价 `sync --dry-run`）。
168
-
169
- `install` 选项：
88
+ 本项目不包含 Codex Cloud、Codex 专用 commands、plugins 或 MCP 配置。
170
89
 
171
- - `--dest <dir>`：复制到指定目录（覆盖工具映射）
172
- - `--tools <t1,t2>`：指定工具，项目级已统一 `codex/pi/opencode/claude → .agents/skills`（共享技能单一源，`.pi/skills`/`.opencode/skills` 仅用于项目自定义）
173
- - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
174
- - `--all`：安装全部可分发 skill（交互勾选时默认只列 programming 范围）；`--force`：覆盖已存在的技能
90
+ ## 上游同步
175
91
 
92
+ 非独有 skills 来自 [mattpocock/skills](https://github.com/mattpocock/skills)。
176
93
 
177
- ### 上游同步（自动更新）
178
-
179
- 本仓库的 `.agents/skills/` 中 **非独有技能** 来自 `mattpocock/skills` 上游。已实现双通道自动同步：
180
-
181
- - **本地 CLI**：`matt-skills sync` 两档——`--dry-run` 只读比对（有差异 `exit 1`，`--json` 可解析）、默认安全增量与 `sync --all` 仅同名 upsert + `AGENTS.md`；`matt-skills check [--json] [--upstream <url>] [--ref <ref>]` 为只读别名（等价 `sync --dry-run`）；`matt-skills update` 已合并到 `sync`（执行提示 `update 已合并到 sync` 且 `exit 1`）
182
94
  ```sh
183
- npx @heihei0299/matt-skills sync --dry-run --json # 预演只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
184
- npx @heihei0299/matt-skills sync # 默认安全增量（AGENTS.md 定制跳过，默认 programming）
185
- npx @heihei0299/matt-skills sync --all # 仅同名 upsert + AGENTS.md
186
- npx @heihei0299/matt-skills check --json # 等价 sync --dry-run
187
- node scripts/sync-upstream.js --check # 等价底层脚本（CLI sync/check 的实现）
188
- node scripts/sync-upstream.js --apply --dry-run
95
+ npx @heihei0299/matt-skills sync --dry-run --json # 检查上游差异
96
+ npx @heihei0299/matt-skills sync # 同步默认范围
97
+ npx @heihei0299/matt-skills sync --all # 同步全部可分发范围
189
98
  ```
190
99
 
191
- 实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 proprietary 分类契约排除本仓库独有 skill，以 `config/engineering.json` 为编程白名单，以 `config/required.json` 为独有所需白名单；上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除。上游同步只维护 workspace，模板生成时再按 distributable 边界投影。
192
- 上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
193
100
  ## 发布
194
101
 
195
- 推送 `v*` 标签自动发布到 npm（GitHub Actions，见 `.github/workflows/ci.yml`）：
102
+ 推送 `v*` 标签会触发 GitHub Actions：全量测试、模板检查和 npm 发布。
196
103
 
197
104
  ```sh
198
- # 1. 确保 main 分支为最新且测试全绿
199
- git checkout main && git pull
200
105
  npm test
201
-
202
- # 2. 打标签并推送（标签即版本，v 前缀自动去除）
203
- git tag v1.0.1
204
- git push origin v1.0.1
205
- ```
206
-
207
- Action 流程：`checkout` → 校验标签在 `main` 分支 → `Node 24` → `npm ci` → `npm test` 全绿 → 以标签为准 `npm version <tag> --no-git-tag-version` → `npm publish --access public`（需在 GitHub Secrets 配置 `NPM_TOKEN`）。
208
-
209
- 本地手动发布（备选）：
210
-
211
- ```sh
212
- npm version <patch|minor|major>
213
- npm publish
106
+ npm run build:template
107
+ git tag vX.Y.Z
108
+ git push origin main vX.Y.Z
214
109
  ```
215
110
 
216
- - `prepublishOnly` 自动跑全量测试（`node --test test/*.test.js`）
217
- - 发布内容 = `bin/` + `template/` + `.agents/skills/` + `scripts/` + `config/` + `README.md`，由 `package.json` 的 `files` 白名单控制，`npm pack` 可预览
218
- - `template/` 与 `.agents/skills/` 是包内容：改动后需重新发版才对目标仓库生效
111
+ 发布需要 GitHub Secrets 中配置 `NPM_TOKEN`。模板或共享 skills 的改动需要新版本才会分发给目标项目。
219
112
 
220
113
  ## 开发
221
114
 
222
115
  ```sh
223
- npm test # 全量测试
224
- npm run build:template # 从 workspace 生成仅含可分发 skill 的 template + 空占位
116
+ npm test
117
+ npm run build:template
225
118
  ```
226
119
 
227
- 交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`、`test/cli-init.test.js`、`test/template-sync.test.js`。
120
+ 测试位于 `test/`；模板由 `scripts/build-template.js` 从工作区生成，提交前应确保模板同步测试通过。
121
+
122
+ ## 许可证
228
123
 
229
- 用户手动触发的功能测试：`/instance-test`（matt-skills 专属示范，见 `.agents/skills/instance-test/SKILL.md`）——验证 sync 合并 update 后的行为，`references/instances.md` 由 `scaffold-functional-test` 从 spec 生成；通用模板已废弃。新增生成器 `/scaffold-functional-test`（见 `.agents/skills/scaffold-functional-test/SKILL.md`）——读 spec 生成定制化功能测试 skill。
124
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heihei0299/matt-skills",
3
- "version": "2.1.3",
3
+ "version": "2.1.7",
4
4
  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
5
5
  "type": "module",
6
6
  "bin": {
package/template/.agents/skills/grill-to-spec/SKILL.md CHANGED
@@ -6,42 +6,50 @@ disable-model-invocation: true
6
6
 
7
7
  # Grill to Spec
8
8
 
9
- 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试。
9
+ 只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试、不自动 commit。
10
10
 
11
11
  ## 流程
12
12
 
13
+ ### 0. 预检
14
+
15
+ - 只读确认 issue tracker、目标上下文、feature slug 和已有 spec/issue 状态。
16
+ - tracker 未配置、slug 不明确或目标路径不可写时，在任何 ADR/spec/issue 写入前报告阻塞。
17
+ - 已有同一 feature 的产物先读取并比较；相同共识不重复发布，设计变化进入变更流程。
18
+
13
19
  ### ① 形成共识
14
20
 
15
21
  调用 [`grill-with-docs`](.agents/skills/grill-with-docs/SKILL.md)，由 `grilling` 与 `domain-modeling` 完成采访、术语和设计决策。
16
22
 
17
23
  - glossary 按上游规则 inline 更新；
18
- - 只有确需 ADR 时才创建 ADR 草稿；
19
- - ADR 必须先展示完整草稿，用户明确确认后才写入，未确认不得落盘。
24
+ - 只有同时满足 ADR 条件时才提出 ADR，但 ADR 等最终决策清单确认后再写入；
25
+ - 在本阶段让 [`to-spec`](.agents/skills/to-spec/SKILL.md) 做代码理解和 seam 分析；seam 是共识的一部分，不单独制造发布确认；
26
+ - 形成精简决策清单：目标、范围、关键选择、seam、未纳入范围和待验证假设；只展示清单，不展示任何 ADR/spec/issue 正文或草稿；
27
+ - 用户确认决策清单后，立即进入阶段 ②。
20
28
 
21
- 出口：用户确认共识已达成，且所有 ADR 草稿都已获得单独确认或明确不写入。
29
+ 出口：决策清单已确认，glossary 已按需更新；尚未确认的 ADR/spec/issue 不写入。
22
30
 
23
31
  ### ② 发布 spec
24
32
 
25
- 将已确认的共识交给 [`to-spec`](.agents/skills/to-spec/SKILL.md)，完成代码库理解、seam 提案和 spec 组装。
33
+ 将已确认的决策清单和 seam 分析交给 `to-spec`；此处只综合、写入和发布，不重新采访或再次确认 seam。
26
34
 
27
- - 将 seam 提案并入最终 spec 草稿，不单独制造一次重复确认；
28
- - 发布前展示完整 spec 草稿，用户一次明确确认后才写入 `.scratch/<feature-slug>/spec.md`；
29
- - 发布时使用 `ready-for-agent`，格式细则只读取 [`references/rules.md`](references/rules.md)。
35
+ - 按 ADR → spec → issue 的顺序执行；issue 发布成功后设置 `ready-for-agent`；格式细则只读取 [`references/rules.md`](references/rules.md)。
36
+ - 相同 feature 复用已有产物，设计变化按 tracker 的更新语义保留历史；
37
+ - 任一步失败都保留已成功写入的内容，记录状态和失败点，重跑时从第一个未完成出口继续；不回滚、不重复发布。
30
38
 
31
- 出口：spec 已发布，路径、状态和未纳入范围已报告。
39
+ 出口：ADR/spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围，不复制正文。
32
40
 
33
41
  ## 回合连续性
34
42
 
35
- 本 skill 是 Long-Horizon Skill。阶段 ① 达到出口后立即进入阶段 ②；正常的阶段切换、进度汇报或“接下来生成 spec”不是回合终点。仅在必须获得用户确认的 ADR/spec 草稿、明确外部阻塞、用户主动停止或整个 skill 出口时暂停。确认完成后在同一任务链继续推进到下一可验证出口，不要求用户额外回复“继续”。
43
+ 本 skill 是 Long-Horizon Skill。预检、阶段 ①、代码理解、决策清单确认后的阶段 ② 在同一任务链连续执行；进度汇报和阶段切换不是回合终点。仅在需要设计确认、决策清单确认、外部阻塞、用户主动停止或整个 skill 出口时暂停；确认完成后不要求用户额外回复“继续”。
36
44
 
37
45
  ## 本 skill 独有门禁
38
46
 
39
- - ADR：草稿 → 用户确认 → 落盘，任何情况不例外；
40
- - spec：共识与 seam 合并为一个最终草稿，只设置一次发布前确认；
41
- - 全程不写代码、不修改测试、不执行实现。
47
+ - 文档正文永不展示；用户只确认精简决策清单，发布后只接收元数据报告；
48
+ - ADR/spec/issue 不设置额外草稿确认；
49
+ - 不写代码、不修改源码或测试、不自动 commit；实现 tickets 交给 `to-tickets`。
42
50
 
43
51
  ## 异常
44
52
 
45
53
  - 用户放弃或没有可形成 spec 的主题时终止；
46
54
  - issue tracker 未配置时报告配置阻塞，不绕过发布；
47
- - 用户改变已确认的设计时回到 ①，不在 ② 静默扩大范围。
55
+ - 用户改变已确认设计时回到阶段 ①，按变更语义保留历史，不静默覆盖。
package/template/.agents/skills/grill-to-spec/references/rules.md CHANGED
@@ -2,25 +2,44 @@
2
2
 
3
3
  本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
4
4
 
5
+ ## 预检与状态规则
6
+
7
+ - 写入前只读确认 issue tracker、目标上下文、feature slug、已有 spec/issue 和当前状态；tracker 未配置或目标不可写时不写 ADR/spec/issue。
8
+ - feature slug 是 spec 路径和 issue 幂等键；候选不明确或冲突时才询问。
9
+ - 记录共识、ADR、spec、issue、`ready-for-agent` 出口；重跑从第一个未完成出口继续，不重复已成功动作。
10
+ - 已有相同共识的 feature 只报告已有路径或标识；设计变化走变更流程，不创建重复 issue。
11
+
5
12
  ## Glossary 增量规则
6
13
 
7
14
  - 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
8
15
  - 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
9
- - glossary 可按上游流程 inline 更新，不额外增加确认轮次。
16
+ - glossary 可按上游流程 inline 更新，不额外增加确认轮次；设计变化时按历史保留规则修正。
10
17
 
11
18
  ## ADR 增量规则
12
19
 
13
20
  - 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
14
- - ADR 草稿必须完整展示并获得用户明确确认后才落盘；这是本 skill 的独有硬门禁。
15
- - 不把 ADR 当 glossary 一样静默 inline 更新。
21
+ - ADR 不像 glossary 一样静默 inline 更新；等最终决策清单确认后直接落盘，不展示正文，不增加独立确认轮次。
22
+ - 用户改变决策时不静默覆盖旧 ADR；按项目 ADR 规则追加、废弃或标记 superseded。
16
23
 
17
24
  ## Spec 增量规则
18
25
 
19
26
  - Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
20
- - seam 提案并入最终 spec 草稿，不再制造独立的一次确认。
21
- - 发布前只做一次最终 spec 明确确认；确认后写入并标记 `ready-for-agent`。
27
+ - 代码理解和 seam 分析属于共识阶段；seam 纳入最终决策清单，不在发布阶段再次询问。
28
+ - 决策清单确认后直接写入 spec；不展示 spec 正文或草稿。
22
29
  - 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
23
30
 
31
+ ## Issue 增量规则
32
+
33
+ - 按已配置的 issue tracker 直接发布唯一 spec issue；implementation tickets 交给 `to-tickets`。
34
+ - issue 正文不在对话中展示；发布成功后设置 `ready-for-agent`。
35
+ - issue 创建成功但 label/status 更新失败时保留 issue，报告标识和失败点，不删除、不误报为 ready。
36
+ - 设计变化委托 tracker 的原生更新语义：本地追加变更记录，远端按 body/comment/关联关系更新；不另造版本模板。
37
+
38
+ ## 失败与 Git 边界
39
+
40
+ - 任一步失败都保留已成功写入的内容并报告部分状态；不做跨文件或跨 tracker 回滚，不盲目重试。
41
+ - 本 skill 不自动创建 Git commit；发布文档与 Git 提交是两个独立出口。
42
+
24
43
  ## 反模式
25
44
 
26
45
  - 不复制 `to-spec` 的章节清单、User Story 模板或 Implementation Decisions 细则。
package/template/.agents/skills/implement-review-loop/SKILL.md ADDED
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: implement-review-loop
3
+ description: "Implement changes with one executor model and one independent reviewer model, iterating on only the changed surface until no actionable issues remain."
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ Use two distinct roles:
8
+
9
+ - **Executor**: implements the requested change, fixes findings, and runs the smallest relevant verification.
10
+ - **Reviewer**: independently reviews the latest diff and relevant verification results. It does not perform the implementation.
11
+
12
+ Workflow:
13
+
14
+ ```text
15
+ Executor implements
16
+ → targeted verification
17
+ → Reviewer reviews latest diff
18
+ → if findings exist: Executor fixes only those findings
19
+ → targeted re-verification
20
+ → Reviewer re-reviews changed parts and unresolved findings
21
+ → repeat until Reviewer reports no actionable issues
22
+ ```
23
+
24
+ Rules:
25
+
26
+ - Keep implementation, testing, and review scoped to the current change and directly affected paths.
27
+ - Prefer targeted tests: changed test files, affected modules, regression cases, or the original reproduction path.
28
+ - Do not rerun equivalent checks after every small edit.
29
+ - Reviewer should inspect the latest diff first, then only enough surrounding code to validate behavior and integration.
30
+ - On subsequent rounds, review the new changes plus unresolved findings; do not restart a whole-project review.
31
+ - Expand test or review scope only when the change crosses modules, modifies shared/public contracts or core infrastructure, targeted evidence is insufficient, final release/merge validation requires it, or the user explicitly requests it.
32
+ - Findings must be concrete and actionable. Separate blockers from optional improvements.
33
+ - Stop the loop when the Reviewer has no actionable findings and targeted verification is green.
34
+ - Do not let the Reviewer silently become the Executor; preserve role independence throughout the loop.
package/template/.agents/skills/implement-review-loop/agents/openai.yaml ADDED
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Implement Review Loop"
3
+ short_description: "Implement with an independent review loop"
4
+ policy:
5
+ allow_implicit_invocation: false
package/template/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -16,7 +16,7 @@ disable-model-invocation: true
16
16
  - **多 issue**：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 文件时，先读取 [orchestration.md](references/orchestration.md)，按 `Blocked by` 构建 DAG、Kahn 分层，再由主代理按层串行完成各 issue。
17
17
  - `Type: research`、`prototype`、`grilling` 分流到对应技能，不进入本技能。
18
18
 
19
- 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、全量收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
19
+ 多 issue 的 A0-A5 是编排控制活动，不是额外的产品交付阶段：依赖图、分层、串行调度、层收敛、最终收敛和回退/冲突处理的详规只在 [orchestration.md](references/orchestration.md) 中维护。
20
20
 
21
21
  ## 三阶段 Steps
22
22
 
@@ -40,7 +40,7 @@ Finalize 出口：commit 已创建、Acceptance Criteria 全部通过，Tracker
40
40
  - 一个 seam 是公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 seam 可以包含多个 Behaviors。Seam/Behavior 的细节和 Todo 粒度只在进入 Step ② 时读取 [red-green.md](references/red-green.md)。
41
41
  - 每个 issue 只在 Verify 的最终 diff 稳定后调用一次 `code-review`；审查维度、reviewer 数量、提示词和输出格式全部由 `code-review` 自己定义，`tdd-implement` 不复制这些规则。`code-review` 未完成或存在 blocking finding 时 issue 不得收敛；A3 层收敛不再次调用 review。
42
42
  - 当前 issue 的范围、Acceptance Criteria、Out of Scope、测试/typecheck/build/真实运行证据和最终 commit 必须可追溯。Seam 或专项测试绿色不代表 issue 完成；三个阶段出口与 Finalize 全部满足后才可标记 `resolved`。
43
- - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，全仓测试由 orchestration 的 A4 在全部 issue 完成后执行一次。
43
+ - 多 issue 模式中，每个 issue 只提交一个独立 commit；issue 影响范围测试在 Step ③ 执行，A4 只做最终编排收敛，不额外扩大测试范围。
44
44
 
45
45
  ## 引用
46
46
 
package/template/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -10,7 +10,7 @@
10
10
  - [A1：Kahn 拓扑分层](#a1kahn-拓扑分层)
11
11
  - [A2：分层串行调度](#a2分层串行调度)
12
12
  - [A3：层收敛](#a3层收敛)
13
- - [A4：全量收敛](#a4全量收敛)
13
+ - [A4：最终收敛](#a4最终收敛)
14
14
  - [A5：回退与冲突处理](#a5回退与冲突处理)
15
15
 
16
16
  ---
@@ -80,7 +80,7 @@ for each layer Li in L1..Ln:
80
80
  全部层完成后进入 A4
81
81
  ```
82
82
 
83
- 每个 issue 的 Verify 只运行当前 issue 影响范围内的完整测试；全仓测试不在每个 issue 中重复执行。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
83
+ 每个 issue 的 Verify 只运行当前 issue 影响范围内的测试；编排层不额外扩大测试范围。当前 issue 的最终 diff 稳定后只调用一次 `code-review`；review 的内部方法完全由 `code-review` 定义。修复 blocking finding 后执行受影响验证和 finding delta recheck，不重复调用完整 `code-review`。
84
84
 
85
85
  主代理在层内和层间连续调度：一个 issue 的 Finalize 出口满足后，立即取下一个 issue，直到全部层完成或发生明确外部阻塞。进度输出并入执行序列，不在正常切换点等待用户“继续”。
86
86
 
@@ -129,11 +129,11 @@ A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每
129
129
 
130
130
  任一项失败，定位到该层失败 issue，按 A5 回退并重做该 issue 的受影响阶段或 Behavior，然后重新收敛本层。
131
131
 
132
- ## A4：全量收敛
132
+ ## A4：最终收敛
133
133
 
134
134
  全部层完成且各层收敛通过后：
135
135
 
136
- 1. 按 A0 的验证矩阵运行一次仓库全量测试；这是多 issue 流程唯一的全量回归点。只有修复全量失败后才允许必要重跑；
136
+ 1. 汇总并确认各 issue 的相关测试、typecheck/build、真实运行和 review 证据仍对应最终状态；若后续改动使证据失效，只重新验证受影响范围；
137
137
  2. 执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`；失败时按 A5 恢复后重验；
138
138
  3. 执行 `git status`，确认无 `[DEBUG-...]`、一次性脚本或未跟踪临时文件；
139
139
  4. 汇总各 issue 回执卡片的 commit、Behaviors、Acceptance Criteria、测试、真实运行和文档对齐结果；汇总只在对话输出，不另写汇总文件。
@@ -141,7 +141,7 @@ A3 只做编排收敛，不再次调用 `code-review`；正式 review 已在每
141
141
  ### A4 出口
142
142
 
143
143
  - 全部 issue 已有独立 commit、实施总结和 `progress.md` 派生记录；
144
- - 全量测试通过；
144
+ - 各 issue 的受影响验证证据仍对应最终状态；
145
145
  - 工作区卫生、历史校验和真实运行要求均满足；
146
146
  - `progress.md` 与 `issues/*.md` 一致，不一致时以 issue 真相源为准并修复派生视图。
147
147
 
@@ -156,7 +156,7 @@ A5 负责所有编排级失败，不把失败静默吞掉，也不把不相关
156
156
  | Red-Green 的有效 Red、实现、typecheck 或 targeted test 失败 | 回到该 issue 的 Red-Green，修复当前 Behavior 并重新验证 |
157
157
  | Verify 的测试、build、真实运行或 review blocking finding 失败 | 回到受影响 issue 的对应阶段；修复后只做受影响检查和 delta review |
158
158
  | Finalize 的必要 docs、commit 或 Tracker 失败 | 保持 issue 未 resolved，修复 Finalize 问题后重新验证 |
159
- | 全量测试失败 | 定位到引入失败的 issue，按上述路径修复；只在修复后重跑必要范围和全量测试 |
159
+ | A4 收敛发现验证证据失效 | 定位到受影响 issue，按上述路径修复；只重新验证受影响范围 |
160
160
  | `Blocked by` 依赖未完成 | 后续 issue 保持 `blocked`，前置 issue resolved 后自动解阻 |
161
161
  | 多 issue 预期修改同一文件 | 记录冲突，按编号串行；无法安全归属时暂停并请求用户决定 |
162
162
  | Git 历史祖先校验失败 | 立即停止写入，使用 `git reflog` 找回 `BASE_HEAD` 之后的提交，校验通过后继续 |
package/template/.agents/skills/tdd-implement/references/stages.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # 三阶段详细定义 + Finalize
2
2
 
3
- 单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、全量收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
3
+ 单 `spec` / 单 `task` 与多 `task` 共用下列三个交付阶段；Verify 通过后执行 Finalize 收尾，Finalize 不计入阶段。多 issue 的依赖图、Kahn 分层、层收敛、最终收敛和回退/冲突处理见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
4
4
 
5
5
  ## 目录
6
6
 
@@ -61,7 +61,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finaliz
61
61
  - `code-review` 可用性；
62
62
  - 可用的 browser 或 Playwright 路径；
63
63
  - ticket 要求的真实运行验证方式。
64
- 6. 建立一次验证矩阵，列出 targeted tests、typecheck、全量测试、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
64
+ 6. 建立一次验证矩阵，列出 targeted tests、typecheck、必要 build、smoke/package check 和真实运行验证，并记录各项的触发条件，后续只复用这份矩阵。
65
65
  7. 识别公共测试边界和 Behaviors。一个 Seam 是一个公共可观察边界；一个 Behavior 是一个红-绿 cycle；一个 Seam 可以包含多个 Behaviors。每个 Behavior 明确输入、可观察输出、对应 Acceptance Criterion 和验证层级。
66
66
  8. spec 已确认且未变化的 Seam 直接复用；只有出现需求歧义、验收缺口、范围变化、破坏性操作或互斥方案时才请求用户确认。
67
67
 
@@ -142,8 +142,7 @@ Seam 或专项测试绿色不等于 issue 完成；只有三个阶段与 Finaliz
142
142
 
143
143
  ### 测试与真实运行验证
144
144
 
145
- - 多 issue 模式只运行当前 issue 影响范围内的完整测试；不在每个 issue 重复运行全仓测试。全部 issues 完成后由 orchestration A4 运行一次全仓测试。
146
- - 单 issue 或单 spec 模式运行仓库完整测试。按照 Contract 的验证矩阵执行，不同时运行等价命令。
145
+ - 单 issue / 单 spec 与多 issue 均只运行当前 issue 影响范围内的测试，按照 Contract 的验证矩阵执行，不同时运行等价命令；不因进入 Verify 自动扩大测试范围。
147
146
  - ticket 要求真实运行时，优先使用专用 browser 工具，其次使用项目已有 Playwright；HTTP/CLI 只能补充 API 验证，不能替代 WebUI 验证。
148
147
  - 真实进程验证使用隔离配置和临时端口，保存 PID，记录实际请求结果或页面可见结果，结束时清理进程和临时目录。
149
148
 
@@ -252,4 +251,4 @@ Progress: pending | in_progress | done | blocked
252
251
  | ③ Verify | 测试、build、真实运行或 review finding 失败 | → ② 修复 Behavior；需求偏差 → ① |
253
252
  | Finalize | 必要 docs 未同步、commit 失败或 Tracker 信息不完整 | → ①/③ 修复对应问题；仍在 Finalize 完成前解决 |
254
253
 
255
- 多 issue 的层收敛、全量失败、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。
254
+ 多 issue 的层收敛、最终收敛、依赖冲突和跨 issue 修改冲突按 [orchestration.md](orchestration.md) A5 回退，不跨 issue 无记录改动。
package/template/.agents/skills/tdd-implement/references/verify.md CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  ## 规则
10
10
 
11
- - 单 issue / 单 spec：按 Contract 验证矩阵运行完整相关测试；多 issue：只跑当前 issue 影响范围，全仓测试留给 orchestration A4。
11
+ - 单 issue / 单 spec 与多 issue 均按 Contract 验证矩阵运行当前 issue 影响范围测试；不因进入 Verify 自动扩大测试范围。
12
12
  - ticket 要求真实运行时，优先专用 browser，其次项目已有 Playwright；HTTP/CLI 不能替代 WebUI 可见验证。
13
13
  - 临时进程必须使用隔离配置/端口，记录 PID 与实际结果，结束后清理。
14
14
  - 当前 issue 的最终 diff 稳定后，调用一次 [code-review](.agents/skills/code-review/SKILL.md)。`tdd-implement` 只规定调用时机；审查维度、reviewer 数量、提示词、上下文与输出格式以 `code-review` 为唯一事实源。
package/template/.opencode/commands/grill-to-spec.md CHANGED
@@ -9,5 +9,5 @@ description: 编排 grill-with-docs → to-spec，把设计打磨成共识并发
9
9
  **主题：** $ARGUMENTS
10
10
 
11
11
  - 只编排与产出：设计打磨成共识 → 综合成 spec 发布，不写代码、不动源码
12
- - 产出物限：领域文档（glossary/ADR）与 spec
13
- - ADR 落盘必须经用户显式确认
12
+ - 产出物限：领域文档（glossary/ADR）与一份 spec issue，不拆 implementation tickets
13
+ - 共识达成后直接写入/发布 ADR、spec 与 issue，不向用户展示正文；只报告路径或标识、状态和范围摘要
package/template/AGENTS.md CHANGED
@@ -4,12 +4,20 @@
4
4
  * 外部调研 / 方案比较 → `research`
5
5
  * 原型 / PoC → `prototype`
6
6
  * 简单修改 → 直接实现
7
+ * 实现 + 独立验收闭环 → `implement-review-loop`
7
8
  * TDD / 集成测试 → `tdd`
8
9
  * 代码审查 → `code-review`
9
10
  * 设计质询 → `grilling`
10
11
  * 领域建模 → `domain-modeling`
11
12
  * 无法归类 → `ask-matt`
12
13
  \仅当关键歧义会改变结果时询问用户。
14
+
15
+ ## 项目上下文
16
+ 开始任务前按需读取：
17
+ - `PROJECT.md`（若存在）：项目目标、范围和主要入口
18
+ - `README.md`（若存在）：用户视角的使用与开发说明
19
+ - `.opencode/CONTEXT.md`（若存在）：领域术语与边界
20
+
13
21
  ## CodeGraph
14
22
  仓库内代码理解首先使用：
15
23
  ```bash
@@ -36,9 +44,14 @@ codegraph explore "<问题>"
36
44
  * 仅在需要用户判断或授权时中断闭环。
37
45
  ## 验证
38
46
  服从全局授权规则。
39
- * 已授权时执行能证明本次改动正确的最小验证。
40
- * bug 验证原复现路径；性能问题使用可测量指标。
41
- * 根据验证反馈修正，不重复等价检查或自动增加 review / CI。
47
+ * 默认只验证本次修改及直接受影响路径；优先相关单测、单文件测试、模块测试和原复现路径。
48
+ * 修复什么就测试什么；根据反馈继续修正，不重复等价检查。
49
+ * 不因每个小步骤自动扩大测试范围。
50
+ * 仅当修改跨模块、触及公共接口/核心基础设施、局部验证不足以证明正确、进入发布/合并最终验收，或用户明确要求时，才考虑更大范围验证。
51
+ ## Review
52
+ * 默认只 review 本轮 diff、修改文件及直接受影响调用链。
53
+ * 修复后只复验新增修改和此前未通过项，不重复审查无关代码。
54
+ * 仅在影响面明显扩大、局部 review 无法建立信心、进入发布/合并最终验收，或用户明确要求时扩大 review 范围。
42
55
  ## Harness
43
56
  同类问题反复出现时，优先将约束落实到测试、lint、类型、工具或代码结构，而不是继续扩充本文件。
44
57
  ## Git
package/template/PROJECT.md ADDED
@@ -0,0 +1,3 @@
1
+ # Project Context
2
+
3
+ <!-- 请在目标仓库中填写项目目标、范围、主要入口和关键约束。代理操作规则放在 AGENTS.md。 -->