@heihei0299/matt-skills 1.6.0 → 1.6.2

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 (8) hide show
  1. package/.agents/skills/tdd-implement/SKILL.md +9 -19
  2. package/.agents/skills/tdd-implement/references/orchestration.md +12 -12
  3. package/.agents/skills/tdd-implement/references/stages.md +1 -1
  4. package/package.json +1 -1
  5. package/template/.agents/skills/tdd-implement/SKILL.md +9 -19
  6. package/template/.agents/skills/tdd-implement/references/orchestration.md +12 -12
  7. package/template/.agents/skills/tdd-implement/references/stages.md +1 -1
  8. package/template/AGENTS.md +9 -7
package/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: tdd-implement
3
- description: "TDD seam red-green loop: use when the user provides a spec/ticket to implement test-first, or mentions TDD/red-green/test-first and wants the full loop through typecheck, review, commit and closeout. For implementation without TDD use implement; for TDD technique alone use tdd."
3
+ description: "TDD seam red-green loop: use when the user provides a spec/ticket for test-first implementation or asks for red-green loop through typecheck/review/commit. For non-TDD implementation use implement; for technique alone use tdd."
4
4
  ---
5
5
 
6
6
  # TDD Implement
@@ -12,20 +12,12 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
12
12
  ## 分支
13
13
 
14
14
  - **单线**：单 spec / 单 issue，走下节 Steps ①→⑦（详规见 [stages.md](references/stages.md)）。
15
- - **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——编排器按依赖分层并行调度，子代理各自治完成 ①→⑦。主过程见下节 [多 issue 编排](#多-issue-编排按依赖分层并行)，详规见 [orchestration.md](references/orchestration.md)。
15
+ - **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——见下节与 [orchestration.md](references/orchestration.md)。
16
16
 
17
17
  ## 多 issue 编排（按依赖分层并行）
18
- 精简主过程（可执行约束全保留，详规见 [orchestration.md](references/orchestration.md)；`references/orchestration.md` 全量保留为详规真相源）。
19
- - **触发**：`.scratch/<feature>/issues/` 下多文件且至少部分含 `Blocked by` 依赖声明；单 issue / 单 spec 不走本节，走 [stages.md](references/stages.md) 单线 ①→⑦。
20
- - **A0 依赖图**：扫描 `NN-<slug>.md` 解析 `Blocked by`（`None`/`（无`/无此行→无依赖；`01, 02`/`01（…）`→依赖对应编号；无法解析→视无依赖并告警），以编号为节点构建 DAG，环则报错列环上节点不调度。
21
- - **A1 Kahn 分层**：对 DAG 做 Kahn BFS 拓扑分层 `L1=入度0 → L2=移除L1后入度0 → … → Ln`；层内无依赖可并行，层间串行；分层结果展示给用户确认后派发。
22
- - **A2 分层调度**：`for Li in L1..Ln: 并行派发（逐个 subagent single 模式，禁 parallel tasks 数组）→ 等待全层回执卡片 → 按 A3 逐 issue 验收（只认回执+抽检，不消费全量日志）→ 层收敛 4 项全过才进下一层`；层收敛 4 项：①该层全部 issue 验收通过 ②相关测试通过 ③`git status` 卫生（仅删 `[DEBUG-...]` 临时产物，禁 `reset --hard/checkout ./clean -fd/stash --include-untracked`）④`git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；任一失败按 A5 回退重派。层间回合连续性：一层收敛后立即派下一层。
23
- - **A3 子代理契约**：每子代理为完整单 issue ①→⑦执行单元（输入：`spec.md`+ 单 `NN-<slug>.md`+`CONTEXT/adr`；执行：①读 issue →②该 issue seams →③红-绿+typecheck →④相关测试（非全量）→⑤双轴 review →⑥commit-check+commit →⑦文档对齐+`Status: resolved`+`## 实施总结`+卫生；产出：独立 commit `feat(<feature>): <title> (#NN)`+ 落盘+测试全绿；禁止跨 issue/跳过⑤⑥）。
24
- - **输出约束**：仅回执卡片（≤30 行，不透传全量日志）：`[回执] #NN <标题>` + 提交/ seams/ 测试（相关）/ typecheck/ review(Standards/Spec)/ 验收 checkbox/ 文档/ 遗留；缺字段视不通过。
25
- - **主代理验收（5 项，任一不过打回重派）**：①落盘（`git log` 含 `#NN` + issue 文件 `resolved`+总结）②抽检（相关测试/`tsc --noEmit`）③改动边界（`git diff <base>..HEAD --name-only` 无跨改）④卫生（无 `[DEBUG-...]` 残留）⑤提交关联（message 含 `#NN` 且一致）；子代理同样 `BASE_HEAD`+回合计 Chunk/历史保护与单线一致。
26
- - **A4 全量收敛**：全部层验收后编排器执行唯一全量测试 + `merge-base --is-ancestor $BASE_HEAD HEAD` 历史校验（失败经 `reflog` 恢复）+ `git status` 卫生（含禁令）+ 会话汇总回执关键信息（不另写汇总文件）。
27
- - **A5 回退与冲突**：子代理内按 `stages.md` 回退表闭环；层收敛失败→该 issue 保持原 Status、不进下一层、修复后重派；全量失败→定位归属 issue 重派；文件冲突→后完成者 rebase 解决后重跑 typecheck+相关测试，禁丢弃提交、必校验 `merge-base` 与 `git log` 全含；环依赖→A0 即终止。
28
- - **出口/边界**：全部 issue `Status: resolved`+`## 实施总结` 落盘 + 全量测试通过 + 工作区干净；单 issue 不走本节、子代理不跨改、编排器不替写代码、汇总只对话输出；**必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度**；TDD 语义以 `tdd` 技能为唯一事实源。
18
+
19
+ 触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件且部分含 `Blocked by` 时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 分层调度（逐个 subagent single 派发、共享 working tree，禁止主会话直做；`N>1` 时串行错峰派发以减同文件竞写，文件冲突由后完成者 rebase 解决） → A3 子代理契约 → A4 全量收敛 → A5 回退与冲突（最小重派：按失败点精确回退、精确定位单 issue 单 seam，全量保留为详规真相源）。必须先编排子代理计划（输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认）后才派发，禁止跳过计划直接派发导致重复调度；编排模式下所有 issue 的 `①→⑦` 必须经子代理执行、主会话仅编排与验收，禁止任何“为省开销/效率”在主会话直做；层收敛 4 项（验收/相关测试/`git status`仅删`[DEBUG-...]`/ `BASE_HEAD`历史校验 `git merge-base --is-ancestor`）与子代理回执卡片（≤30行、缺字段视为不通过）、打回重派、rebase 冲突处理等可执行约束全量见 orchestration.md。
20
+
29
21
  ## Steps
30
22
 
31
23
  按序执行，每步达到完成条件才进入下一步；进入任一步前先读取其在 [stages.md](references/stages.md) 的定义。
@@ -34,20 +26,19 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
34
26
  |------|--------|-------------------|------|
35
27
  | ① 理解需求 | 读取 spec/ticket + `CONTEXT.md`/`docs/adr/`，澄清歧义 | 能复述需求且无未澄清歧义 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
36
28
  | ② 确认 Seams | 列出待测公共接口 seams（名称+输入+预期输出），向用户确认并生成 Todo | 用户明确同意 seams 清单；Todo 已生成 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
37
- | ③ TDD 开发循环 | 逐 seam 红-绿循环，串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
29
+ | ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
38
30
  | ④ 完整测试套件 | 跑全量测试 | 全部测试通过（失败回 ③） | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
39
31
  | ⑤ Code Review | 按 [code-review](.agents/skills/code-review/SKILL.md) 双轴审查（Standards + Spec） | 双轴均通过 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
40
32
  | ⑥ Commit | 跑 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁四项后提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
41
33
  | ⑦ 收尾 | 文档对齐 → issue 状态与实施总结 → 目录卫生 | 文档已对齐、issue 已 `resolved`+总结落盘、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
42
34
 
43
- 编排主过程见上节 [多 issue 编排](#多-issue-编排按依赖分层并行)，详规见 [orchestration.md](references/orchestration.md)；子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
35
+ 子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
44
36
 
45
37
  ### 阶段间流转
46
38
 
47
39
  - 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
48
- - 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见上节 [多 issue 编排 A5](#多-issue-编排按依赖分层并行) 与 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
49
- - 回合连续性：阶段内连续动作（红→绿→typecheck→下一 seam）在**一个回合内串行完成**，直至阶段出口；预告下一步后立即执行。详规见 [stages.md ③-3e](references/stages.md#3e-回合连续性) 与上节 [多 issue 编排 A2](#多-issue-编排按依赖分层并行) / [orchestration.md#A2](references/orchestration.md#a2-分层调度)。
50
- - 任务分解：巨型写入拆小步——`write` 超 ~150 行先写骨架再分批补全，`replace` 超 ~5 处分批执行并验证。详见 [stages.md ③-3f](references/stages.md#3f-任务分解chunking)。
40
+ - 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
41
+ - 回合连续性与任务分解：见 [stages.md ③-3e/3f](references/stages.md#阶段-③tdd-开发循环)（红→绿→typecheck→下一 seam 一个回合内串行完成，直至阶段出口；预告下一步后立即执行；write>150 行/replace>5 处拆小步）。
51
42
 
52
43
  ## 引用
53
44
 
@@ -56,5 +47,4 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
56
47
  - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
57
48
  - Commit 门禁：[commit-check](.agents/skills/commit-check/SKILL.md)
58
49
  - 单线详规：[stages.md](references/stages.md)
59
- - 多 issue 编排主过程：本文件 [多 issue 编排](#多-issue-编排按依赖分层并行)
60
50
  - 多 issue 编排详规：[orchestration.md](references/orchestration.md)（全量保留）
package/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -38,23 +38,23 @@ Ln = 最后一层
38
38
  ```
39
39
 
40
40
  每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
41
-
41
+ 若两 issue 在阶段②已声明预期改动同一文件，编排器在 A0 后提示建议追加 `Blocked by` 使其串行（轻提示，不强制）；主要仍靠 A2 串行错峰自然错峰。
42
42
  ### A2. 分层调度
43
43
 
44
44
  ```
45
45
  for each 层 Li in L1..Ln:
46
- 并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，禁止 parallel tasks 数组）
46
+ 并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，共享 working tree，禁止 parallel tasks 数组；N>1 时串行错峰派发）
47
47
  等待：阻塞直到 Li 全部子代理返回回执卡片
48
- 验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证，不消费全量日志）
49
- 层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或相关/卫生/历史任一失败按 A5 回退重派该 issue
48
+ 验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证在最新 HEAD 上执行，不消费全量日志）
49
+ 层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 最小重派该 issue）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或相关/卫生/历史任一失败按 A5 重派该 issue
50
50
  全部层层收敛通过后进入 A4 全量收敛
51
51
  ```
52
52
 
53
53
  - **派发纪律**：与阶段⑤双轴审查一致——逐个 `subagent` 派发，禁止 `parallel tasks` 数组（同因：中文报告截断）。
54
- - **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 处理。
54
+ - **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 最小重派处理。
55
+ - **冲突判定（Q1/Q2）**：同文件即冲突，以 `HEAD` 已移动（`git log` 已含先完成者 `#NN`）为准判定慢者前后不一致；不在工作区瞬时覆盖时判定。
55
56
  - **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
56
57
  - **Git 历史保护（正向：仅追加；护栏：禁改写）**：编排器在分层调度前记录 `BASE_HEAD=$(git rev-parse HEAD)`，每层收敛后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复；为达 `git status` 干净仅删本次产生的 `[DEBUG-...]`临时产物（正向），护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`/`git push --force` 等（需显式确认）。
57
-
58
58
  ### A3. 子代理契约（单 issue 单代理）
59
59
 
60
60
  每个子代理是一个**完整的 tdd-implement 单 issue 执行单元**，输入与产出严格界定：
@@ -115,10 +115,10 @@ for each 层 Li in L1..Ln:
115
115
 
116
116
  ### A5. 回退与冲突
117
117
 
118
- - **子代理内回退**：按 [stages.md 回退路由](stages.md#回退路由) 在子代理内闭环（typecheck 失败 → ③、测试失败 → ③、review 不通过 → ③/②/①）。
119
- - **层收敛失败**：层内任一子代理未达到 `resolved`（测试失败 / review 不通过 / commit-check 门禁失败）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后重派该层失败节点。
120
- - **全量收敛失败**：A4 全量测试失败 → 定位到失败测试归属的 issue，回到其所在层重派对应子代理。
121
- - **文件冲突**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，rebase 后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果为准，编排器不做静态预判。
118
+ - **子代理内回退（最小单元）**：按 [stages.md 回退路由](stages.md#回退路由) 精确回退——`typecheck 失败→③`、`测试失败→③`、`review Standards 味→⑤重构`、`review Spec 偏离→①`、`review seams 遗漏→②补 seams`、`commit-check 文档/卫生/message 失败→⑥/⑦ 对应阶段`。失败点之前的已 `done` seam/Todo 永不回退，仅重跑失败阶段及下游；`seams 清单` 与已绿 seam 默认复用，仅 `seams 遗漏/需求偏差` 两类才回到 `②/①` 重确认。
119
+ - **层收敛失败（最小重派）**：层内任一子代理未达到 `resolved`（含验收 5 项、相关测试、卫生、历史校验任一不过）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后仅重派失败节点，同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`。
120
+ - **全量收敛失败（精确定位）**：A4 全量测试失败 → 以测试文件路径/报错栈精确定位到单 issue 单 seam，回到其所在层仅重派该 issue 的失败 seam + 相关测试，全量由编排器在重派后再次 A4 统一验证；无法精确定位时退化到层级重派，不重跑无关联 issue。
121
+ - **文件冲突（Q1-Q4）**：同文件即冲突（Q1 慢者因 `HEAD` 已移动致前后不一致）；慢者完成当前 seam 的 `红→绿→typecheck` 后再以新 HEAD 为基线 rebase，仅重做该冲突文件关联的 seam（其余已绿复用，Q3/Q4 最小化）；后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，rebase 后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果（`HEAD` 已移动）为准，编排器不做静态文件监听预判。
122
122
  - **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
123
123
 
124
124
  ### 出口条件
@@ -129,8 +129,8 @@ for each 层 Li in L1..Ln:
129
129
 
130
130
  ### 边界
131
131
 
132
- - 单 issue / 单 spec 不走本文件
133
- - 子代理不跨 issue 改动；编排器不替子代理写实现代码
132
+ - 单 issue / 单 spec 不走本文件；但一旦进入编排模式（多 issue 且含 Blocked by），无论 N==1 还是 N>1，所有 issue 的 ①→⑦ 必须经子代理 single 派发完成，禁止主会话直做（编排器仅编排、验收、归集、清理）
133
+ - 子代理不跨 issue 改动；编排器不替子代理写实现代码；主会话不直接写业务代码/测试/文档（仅做编排与验收）
134
134
  - 汇总总结只在对话输出，不落盘额外汇总文件
135
135
  - 必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度
136
136
  - TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
package/.agents/skills/tdd-implement/references/stages.md CHANGED
@@ -227,7 +227,7 @@
227
227
  ```
228
228
 
229
229
  5. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
230
- 6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。
230
+ 6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。Git 历史保护与禁令见本文件阶段③ [Git 安全前置](#git-安全前置历史保护)与 `docs/agents/skill-design.md` Rule 4，仅删本次临时产物，禁止为达干净而执行 git 层破坏性命令。
231
231
 
232
232
  ### 出口条件
233
233
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heihei0299/matt-skills",
3
- "version": "1.6.0",
3
+ "version": "1.6.2",
4
4
  "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
5
5
  "type": "module",
6
6
  "bin": {
package/template/.agents/skills/tdd-implement/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: tdd-implement
3
- description: "TDD seam red-green loop: use when the user provides a spec/ticket to implement test-first, or mentions TDD/red-green/test-first and wants the full loop through typecheck, review, commit and closeout. For implementation without TDD use implement; for TDD technique alone use tdd."
3
+ description: "TDD seam red-green loop: use when the user provides a spec/ticket for test-first implementation or asks for red-green loop through typecheck/review/commit. For non-TDD implementation use implement; for technique alone use tdd."
4
4
  ---
5
5
 
6
6
  # TDD Implement
@@ -12,20 +12,12 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
12
12
  ## 分支
13
13
 
14
14
  - **单线**：单 spec / 单 issue，走下节 Steps ①→⑦（详规见 [stages.md](references/stages.md)）。
15
- - **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——编排器按依赖分层并行调度，子代理各自治完成 ①→⑦。主过程见下节 [多 issue 编排](#多-issue-编排按依赖分层并行)，详规见 [orchestration.md](references/orchestration.md)。
15
+ - **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——见下节与 [orchestration.md](references/orchestration.md)。
16
16
 
17
17
  ## 多 issue 编排（按依赖分层并行）
18
- 精简主过程（可执行约束全保留，详规见 [orchestration.md](references/orchestration.md)；`references/orchestration.md` 全量保留为详规真相源）。
19
- - **触发**：`.scratch/<feature>/issues/` 下多文件且至少部分含 `Blocked by` 依赖声明；单 issue / 单 spec 不走本节，走 [stages.md](references/stages.md) 单线 ①→⑦。
20
- - **A0 依赖图**：扫描 `NN-<slug>.md` 解析 `Blocked by`（`None`/`（无`/无此行→无依赖；`01, 02`/`01（…）`→依赖对应编号；无法解析→视无依赖并告警），以编号为节点构建 DAG，环则报错列环上节点不调度。
21
- - **A1 Kahn 分层**：对 DAG 做 Kahn BFS 拓扑分层 `L1=入度0 → L2=移除L1后入度0 → … → Ln`；层内无依赖可并行，层间串行；分层结果展示给用户确认后派发。
22
- - **A2 分层调度**：`for Li in L1..Ln: 并行派发（逐个 subagent single 模式，禁 parallel tasks 数组）→ 等待全层回执卡片 → 按 A3 逐 issue 验收（只认回执+抽检，不消费全量日志）→ 层收敛 4 项全过才进下一层`；层收敛 4 项：①该层全部 issue 验收通过 ②相关测试通过 ③`git status` 卫生（仅删 `[DEBUG-...]` 临时产物，禁 `reset --hard/checkout ./clean -fd/stash --include-untracked`）④`git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；任一失败按 A5 回退重派。层间回合连续性：一层收敛后立即派下一层。
23
- - **A3 子代理契约**：每子代理为完整单 issue ①→⑦执行单元（输入：`spec.md`+ 单 `NN-<slug>.md`+`CONTEXT/adr`；执行：①读 issue →②该 issue seams →③红-绿+typecheck →④相关测试（非全量）→⑤双轴 review →⑥commit-check+commit →⑦文档对齐+`Status: resolved`+`## 实施总结`+卫生；产出：独立 commit `feat(<feature>): <title> (#NN)`+ 落盘+测试全绿；禁止跨 issue/跳过⑤⑥）。
24
- - **输出约束**：仅回执卡片（≤30 行，不透传全量日志）：`[回执] #NN <标题>` + 提交/ seams/ 测试（相关）/ typecheck/ review(Standards/Spec)/ 验收 checkbox/ 文档/ 遗留；缺字段视不通过。
25
- - **主代理验收（5 项，任一不过打回重派）**：①落盘（`git log` 含 `#NN` + issue 文件 `resolved`+总结）②抽检（相关测试/`tsc --noEmit`）③改动边界（`git diff <base>..HEAD --name-only` 无跨改）④卫生（无 `[DEBUG-...]` 残留）⑤提交关联（message 含 `#NN` 且一致）；子代理同样 `BASE_HEAD`+回合计 Chunk/历史保护与单线一致。
26
- - **A4 全量收敛**：全部层验收后编排器执行唯一全量测试 + `merge-base --is-ancestor $BASE_HEAD HEAD` 历史校验（失败经 `reflog` 恢复）+ `git status` 卫生（含禁令）+ 会话汇总回执关键信息（不另写汇总文件）。
27
- - **A5 回退与冲突**：子代理内按 `stages.md` 回退表闭环；层收敛失败→该 issue 保持原 Status、不进下一层、修复后重派；全量失败→定位归属 issue 重派；文件冲突→后完成者 rebase 解决后重跑 typecheck+相关测试，禁丢弃提交、必校验 `merge-base` 与 `git log` 全含；环依赖→A0 即终止。
28
- - **出口/边界**：全部 issue `Status: resolved`+`## 实施总结` 落盘 + 全量测试通过 + 工作区干净；单 issue 不走本节、子代理不跨改、编排器不替写代码、汇总只对话输出；**必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度**；TDD 语义以 `tdd` 技能为唯一事实源。
18
+
19
+ 触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件且部分含 `Blocked by` 时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 分层调度（逐个 subagent single 派发、共享 working tree，禁止主会话直做；`N>1` 时串行错峰派发以减同文件竞写，文件冲突由后完成者 rebase 解决） → A3 子代理契约 → A4 全量收敛 → A5 回退与冲突（最小重派：按失败点精确回退、精确定位单 issue 单 seam，全量保留为详规真相源）。必须先编排子代理计划（输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认）后才派发，禁止跳过计划直接派发导致重复调度；编排模式下所有 issue 的 `①→⑦` 必须经子代理执行、主会话仅编排与验收，禁止任何“为省开销/效率”在主会话直做；层收敛 4 项（验收/相关测试/`git status`仅删`[DEBUG-...]`/ `BASE_HEAD`历史校验 `git merge-base --is-ancestor`）与子代理回执卡片（≤30行、缺字段视为不通过）、打回重派、rebase 冲突处理等可执行约束全量见 orchestration.md。
20
+
29
21
  ## Steps
30
22
 
31
23
  按序执行，每步达到完成条件才进入下一步；进入任一步前先读取其在 [stages.md](references/stages.md) 的定义。
@@ -34,20 +26,19 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
34
26
  |------|--------|-------------------|------|
35
27
  | ① 理解需求 | 读取 spec/ticket + `CONTEXT.md`/`docs/adr/`，澄清歧义 | 能复述需求且无未澄清歧义 | [stages.md#阶段-①](references/stages.md#阶段-①理解需求) |
36
28
  | ② 确认 Seams | 列出待测公共接口 seams（名称+输入+预期输出），向用户确认并生成 Todo | 用户明确同意 seams 清单；Todo 已生成 | [stages.md#阶段-②](references/stages.md#阶段-②确认-seams测试接缝) |
37
- | ③ TDD 开发循环 | 逐 seam 红-绿循环，串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
29
+ | ③ TDD 开发循环 | 逐 seam 红-绿循环（红→绿→typecheck）串行推进至全绿 | 所有 seams 红-绿完成 + typecheck 通过 | [stages.md#阶段-③](references/stages.md#阶段-③tdd-开发循环) |
38
30
  | ④ 完整测试套件 | 跑全量测试 | 全部测试通过（失败回 ③） | [stages.md#阶段-④](references/stages.md#阶段-④完整测试套件) |
39
31
  | ⑤ Code Review | 按 [code-review](.agents/skills/code-review/SKILL.md) 双轴审查（Standards + Spec） | 双轴均通过 | [stages.md#阶段-⑤](references/stages.md#阶段-⑤code-review) |
40
32
  | ⑥ Commit | 跑 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁四项后提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
41
33
  | ⑦ 收尾 | 文档对齐 → issue 状态与实施总结 → 目录卫生 | 文档已对齐、issue 已 `resolved`+总结落盘、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
42
34
 
43
- 编排主过程见上节 [多 issue 编排](#多-issue-编排按依赖分层并行)，详规见 [orchestration.md](references/orchestration.md)；子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
35
+ 子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
44
36
 
45
37
  ### 阶段间流转
46
38
 
47
39
  - 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
48
- - 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见上节 [多 issue 编排 A5](#多-issue-编排按依赖分层并行) 与 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
49
- - 回合连续性：阶段内连续动作（红→绿→typecheck→下一 seam）在**一个回合内串行完成**，直至阶段出口；预告下一步后立即执行。详规见 [stages.md ③-3e](references/stages.md#3e-回合连续性) 与上节 [多 issue 编排 A2](#多-issue-编排按依赖分层并行) / [orchestration.md#A2](references/orchestration.md#a2-分层调度)。
50
- - 任务分解：巨型写入拆小步——`write` 超 ~150 行先写骨架再分批补全，`replace` 超 ~5 处分批执行并验证。详见 [stages.md ③-3f](references/stages.md#3f-任务分解chunking)。
40
+ - 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
41
+ - 回合连续性与任务分解：见 [stages.md ③-3e/3f](references/stages.md#阶段-③tdd-开发循环)（红→绿→typecheck→下一 seam 一个回合内串行完成，直至阶段出口；预告下一步后立即执行；write>150 行/replace>5 处拆小步）。
51
42
 
52
43
  ## 引用
53
44
 
@@ -56,5 +47,4 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
56
47
  - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
57
48
  - Commit 门禁：[commit-check](.agents/skills/commit-check/SKILL.md)
58
49
  - 单线详规：[stages.md](references/stages.md)
59
- - 多 issue 编排主过程：本文件 [多 issue 编排](#多-issue-编排按依赖分层并行)
60
50
  - 多 issue 编排详规：[orchestration.md](references/orchestration.md)（全量保留）
package/template/.agents/skills/tdd-implement/references/orchestration.md CHANGED
@@ -38,23 +38,23 @@ Ln = 最后一层
38
38
  ```
39
39
 
40
40
  每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
41
-
41
+ 若两 issue 在阶段②已声明预期改动同一文件，编排器在 A0 后提示建议追加 `Blocked by` 使其串行（轻提示，不强制）；主要仍靠 A2 串行错峰自然错峰。
42
42
  ### A2. 分层调度
43
43
 
44
44
  ```
45
45
  for each 层 Li in L1..Ln:
46
- 并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，禁止 parallel tasks 数组）
46
+ 并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，共享 working tree，禁止 parallel tasks 数组；N>1 时串行错峰派发）
47
47
  等待：阻塞直到 Li 全部子代理返回回执卡片
48
- 验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证，不消费全量日志）
49
- 层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 回退）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或相关/卫生/历史任一失败按 A5 回退重派该 issue
48
+ 验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证在最新 HEAD 上执行，不消费全量日志）
49
+ 层收敛验证：验收全通过进入全量验证（完成条件 4 项，全部通过才进下一层，任一失败按 A5 最小重派该 issue）：①该层全部 issue 验收通过 ②相关测试套件通过（全量仅在 A4） ③`git status` 卫生（仅删本次临时产物，正向；护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`）④历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过；验收不通过或相关/卫生/历史任一失败按 A5 重派该 issue
50
50
  全部层层收敛通过后进入 A4 全量收敛
51
51
  ```
52
52
 
53
53
  - **派发纪律**：与阶段⑤双轴审查一致——逐个 `subagent` 派发，禁止 `parallel tasks` 数组（同因：中文报告截断）。
54
- - **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 处理。
54
+ - **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 最小重派处理。
55
+ - **冲突判定（Q1/Q2）**：同文件即冲突，以 `HEAD` 已移动（`git log` 已含先完成者 `#NN`）为准判定慢者前后不一致；不在工作区瞬时覆盖时判定。
55
56
  - **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
56
57
  - **Git 历史保护（正向：仅追加；护栏：禁改写）**：编排器在分层调度前记录 `BASE_HEAD=$(git rev-parse HEAD)`，每层收敛后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即经 `git reflog` 恢复；为达 `git status` 干净仅删本次产生的 `[DEBUG-...]`临时产物（正向），护栏：禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked`/`git push --force` 等（需显式确认）。
57
-
58
58
  ### A3. 子代理契约（单 issue 单代理）
59
59
 
60
60
  每个子代理是一个**完整的 tdd-implement 单 issue 执行单元**，输入与产出严格界定：
@@ -115,10 +115,10 @@ for each 层 Li in L1..Ln:
115
115
 
116
116
  ### A5. 回退与冲突
117
117
 
118
- - **子代理内回退**：按 [stages.md 回退路由](stages.md#回退路由) 在子代理内闭环（typecheck 失败 → ③、测试失败 → ③、review 不通过 → ③/②/①）。
119
- - **层收敛失败**：层内任一子代理未达到 `resolved`（测试失败 / review 不通过 / commit-check 门禁失败）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后重派该层失败节点。
120
- - **全量收敛失败**：A4 全量测试失败 → 定位到失败测试归属的 issue，回到其所在层重派对应子代理。
121
- - **文件冲突**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，rebase 后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果为准，编排器不做静态预判。
118
+ - **子代理内回退（最小单元）**：按 [stages.md 回退路由](stages.md#回退路由) 精确回退——`typecheck 失败→③`、`测试失败→③`、`review Standards 味→⑤重构`、`review Spec 偏离→①`、`review seams 遗漏→②补 seams`、`commit-check 文档/卫生/message 失败→⑥/⑦ 对应阶段`。失败点之前的已 `done` seam/Todo 永不回退，仅重跑失败阶段及下游；`seams 清单` 与已绿 seam 默认复用，仅 `seams 遗漏/需求偏差` 两类才回到 `②/①` 重确认。
119
+ - **层收敛失败（最小重派）**：层内任一子代理未达到 `resolved`（含验收 5 项、相关测试、卫生、历史校验任一不过）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后仅重派失败节点，同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`。
120
+ - **全量收敛失败（精确定位）**：A4 全量测试失败 → 以测试文件路径/报错栈精确定位到单 issue 单 seam，回到其所在层仅重派该 issue 的失败 seam + 相关测试，全量由编排器在重派后再次 A4 统一验证；无法精确定位时退化到层级重派，不重跑无关联 issue。
121
+ - **文件冲突（Q1-Q4）**：同文件即冲突（Q1 慢者因 `HEAD` 已移动致前后不一致）；慢者完成当前 seam 的 `红→绿→typecheck` 后再以新 HEAD 为基线 rebase，仅重做该冲突文件关联的 seam（其余已绿复用，Q3/Q4 最小化）；后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突解决禁止使用 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 丢弃对方提交，rebase 后必校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 且 `git log --oneline` 含全部层提交；冲突检测以 `git` 合并结果（`HEAD` 已移动）为准，编排器不做静态文件监听预判。
122
122
  - **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
123
123
 
124
124
  ### 出口条件
@@ -129,8 +129,8 @@ for each 层 Li in L1..Ln:
129
129
 
130
130
  ### 边界
131
131
 
132
- - 单 issue / 单 spec 不走本文件
133
- - 子代理不跨 issue 改动；编排器不替子代理写实现代码
132
+ - 单 issue / 单 spec 不走本文件；但一旦进入编排模式（多 issue 且含 Blocked by），无论 N==1 还是 N>1，所有 issue 的 ①→⑦ 必须经子代理 single 派发完成，禁止主会话直做（编排器仅编排、验收、归集、清理）
133
+ - 子代理不跨 issue 改动；编排器不替子代理写实现代码；主会话不直接写业务代码/测试/文档（仅做编排与验收）
134
134
  - 汇总总结只在对话输出，不落盘额外汇总文件
135
135
  - 必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度
136
136
  - TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
package/template/.agents/skills/tdd-implement/references/stages.md CHANGED
@@ -227,7 +227,7 @@
227
227
  ```
228
228
 
229
229
  5. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
230
- 6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。禁止为达干净而执行 `git reset --hard`、`git checkout .`、`git clean -fd`、`git stash push --include-untracked` 等（需显式用户确认；`stash` 如需使用改用 `--keep-index` 并在 `pop` 后校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`）。
230
+ 6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。Git 历史保护与禁令见本文件阶段③ [Git 安全前置](#git-安全前置历史保护)与 `docs/agents/skill-design.md` Rule 4，仅删本次临时产物，禁止为达干净而执行 git 层破坏性命令。
231
231
 
232
232
  ### 出口条件
233
233
 
package/template/AGENTS.md CHANGED
@@ -15,7 +15,7 @@
15
15
 
16
16
  1. 读 `CONTEXT.md`（术语）——没有则跳过
17
17
  2. 按行为路由表行动；未命中用 ask-matt 或直接澄清
18
- 3. 探索代码库：优先 codegraph CLI（`codegraph explore`），无索引时派 explore 子代理
18
+ 3. 探索代码库：直接使用 `codegraph explore`（`codegrafh CLI`）；若无 `.codegraph/` 索引先执行 `codegraph init` 初始化，再 `explore`
19
19
 
20
20
  ## 执行原则
21
21
 
@@ -30,9 +30,9 @@
30
30
 
31
31
  命中即行动，回复中简短声明所用技能与原因。
32
32
 
33
- - 探索/定位/理解代码库 → 有 `.codegraph/` 索引：`codegraph explore`（CLI）优先；无索引用 explore 子代理
33
+ - 探索/定位/理解代码库 → 直接使用 `codegraph explore`（`codegrafh CLI`）；若无 `.codegraph/` 索引先 `codegraph init` 初始化，再 `explore`（Q1 硬判定，Q2 意图文+文件锚点，Q3 仅完整源码免读，Q4 跨仓才传 projectPath，Q5 研调链用 research 另行触发）
34
34
  - 后台调研 → research；原型验证 → prototype
35
- - 实现（有 spec）→ implement（无 spec 先 to-spec）；测试先行 → tdd
35
+ - 实现（有 spec 且要求 TDD/测试先行）→ tdd-implement（seam red-green）；实现（有 spec 不要求 TDD）→ implement（无 spec 先 to-spec）；测试先行 → tdd
36
36
  - 设计打磨 → grilling；达成共识→spec → grill-to-spec（grilling→domain-modeling→to-spec）
37
37
  - 领域术语/ADR → domain-modeling；模块接口 → codebase-design；巨型规划 → wayfinder
38
38
  - 诊断 → diagnose-fix（编排 diagnosing-bugs + tdd，硬门槛）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（文档一致性 → 目录卫生 → commit message，三项）
@@ -49,8 +49,10 @@
49
49
 
50
50
  ## CodeGraph
51
51
 
52
- 仓库被 CodeGraph 索引（根目录存在 `.codegraph/`）时，理解/定位代码**优先于** grep/find/读文件——一次调用拿到相关符号源码与调用路径：
52
+ 理解/定位代码**必须**使用 `codegrafh CLI`，直接优于 grep/find/读文件——一次调用拿到相关符号逐字源码与调用路径：
53
53
 
54
- - **CLI**：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码。
55
-
56
- 没有 `.codegraph/` 目录则完全跳过 CodeGraph——是否建立索引由用户决定。
54
+ - **CLI**：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码，默认 `maxFiles: 12` 覆盖跨 5-8 文件调用链。
55
+ - **初始化**：若根目录无 `.codegraph/`，先执行 `codegraph init` 初始化索引，再 `explore`；已有索引直接 `explore`（硬判定，不回退 explore 子代理）。
56
+ - **已读等价**：返回体含完整源码块的文件视为已 `Read`，不再重复 `read`；仅返回调用路径片段时补一次带行号 `read`。
57
+ - **跨仓/子项目**：仅当探索第二代码库或 monorepo 子项目（根无索引但子目录有）时显式传 `projectPath`。
58
+ 与 `research`（后台调研产出 Markdown 文件）分工：`codegraph explore` 为代码定位唯一首选，`research` 仅用于需产出调研文档的后台任务。