@heihei0299/matt-skills 1.0.0

package/template/.pi/skills/tdd-implement/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: tdd-implement
+description: "Implement from a spec or ticket via strict TDD red-green loop, then typecheck, review, commit, update the issue status, and write an implementation summary. Use this skill whenever the user asks to implement from a spec/ticket/issue, mentions TDD/red-green/test-first, or wants test-first work carried through review, commit and issue close-out in one pass — even if they don't name the process. For implementation without the test-first pipeline use implement; for test technique alone use tdd — this skill is the complete orchestration."
+---
+
+# TDD Implement
+
+整合 **implement** + **tdd** 的完整实现流程：每个 seam 一个红-绿循环，直到 commit。TDD 语义（红-绿循环、seam 定义、好测试标准）以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源——测试标准详见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 边界见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)；本技能只编排阶段与运行时规则。
+
+本技能是**长程任务**（Long-Horizon Skill）：多阶段串行执行，自带**回合连续性**（Turn Continuity）与**任务分解**（Chunking）规则（见 [stages.md](references/stages.md) 阶段③ 3e/3f）。术语定义见 `CONTEXT.md`，技能设计规则见 `docs/agents/skill-design.md`。
+
+## 流程速览
+
+```
+① 理解需求 → ② 确认 Seams → ③ TDD 开发循环 → ④ 完整测试套件 → ⑤ Code Review → ⑥ Commit → ⑦ 收尾（文档对齐 + issue 状态 + 实施总结）
+```
+
+每阶段的入口条件、操作与边界规则见 [`stages.md`](references/stages.md)——进入任一阶段前先读取该阶段的定义。③ TDD 开发循环的红-绿规则见 [tdd 技能](.agents/skills/tdd/SKILL.md)，不在本文件重写。多 issue 编排见下节与 [`stages.md` 附录：多 issue 编排](references/stages.md#附录-多-issue-编排按依赖分层并行)。
+
+阶段要点：
+- ⑤ Code Review：按 [code-review](.agents/skills/code-review/SKILL.md) **双轴审查**——Standards 轴（编码标准符合度）与 Spec 轴（spec/issue 实现忠实度），两轴独立报告互不掩盖；审查结果只在对话输出，不生成书面审查报告（不落盘 `review-*.md` 类文件）。**派发纪律：两轴必须用 subagent single 模式或 `subagent_consult` 逐个派发，禁止 parallel `tasks` 数组**（parallel 结果仅保留 160 字节摘要，中文报告必截断；详见 stages.md 阶段⑤）
+- ⑥ Commit：commit 前运行 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁（①审查文档 ②对齐 README ③目录卫生 ④commit message），四项全过才提交
+- ⑦ 收尾：先对齐文档——检查 README 与 docs/ 中涉及本次实现的描述与实现是否一致，不一致则更新并 commit；再更新 issue 状态（有关联 issue 时，其验收标准逐条转写为 checkbox 清单并打勾——全部 `- [x]` 才允许标 `resolved`）；最后保持目录卫生（清理 `[DEBUG-...]` 调试残留与临时产物，`git status` 确认工作区干净）
+
+## 多 issue 编排（按依赖分层并行）
+
+当 `.scratch/<feature>/issues/` 下存在多个 issue 且彼此有 `Blocked by` 依赖时走本模式；单 issue / 单 spec 仍走上节单线流程。触发后主代理为**编排器**，子代理按**单 issue 单代理**各自治完成完整 tdd-implement 流程（①→⑦）。详规见 [`stages.md` 附录](references/stages.md#附录-多-issue-编排按依赖分层并行)，本节只定契约：
+
+- **触发**：扫描 `.scratch/<feature>/issues/` 多文件且含 `Blocked by` 时进入编排模式；否则单线执行——不为单 issue 引入编排开销。
+- **编排器职责**：解析 `Blocked by` 依赖图 → 拓扑分层 → 按层调度子代理 → 逐 issue 验收（见下）→ 层间收敛验证（全量测试 + `git status` 干净）→ 汇总实施总结。
+- **子代理契约（单 issue 单代理）**：输入 `spec.md + 单个 issue.md + CONTEXT.md/ADRs`，严格走 tdd-implement ①→⑦（含 seams 确认、红-绿循环、typecheck、双轴 review、commit-check 门禁、issue `resolved` + 实施总结）；产出独立 commit；禁止跨 issue 改动。
+- **子代理输出约束**：只返回**回执卡片**（结构化关键信息），不透传全量过程日志。回执字段：issue 编号与标题 / commit hash / seams 清单 / 测试结果（数量与是否全绿）/ typecheck 结论 / 双轴 review 结论 / 验收 checkbox 结果 / 文档对齐清单 / 遗留与风险。红-绿细节、typecheck 原始输出、review 全文等过程日志留在子代理内部，不向主代理透传。
+- **主代理验收**：编排器不盲信回执，逐 issue 验收后才算该 issue 完成。验收项：① commit 存在且 message 含 issue 编号 ② issue 文件 `Status: resolved` + `## 实施总结` 已落盘 ③ 抽检验证（抽跑相关测试或 `tsc --noEmit` 抽检，不重跑全量）④ 无跨 issue 改动（`git diff --name-only` 核对）⑤ 工作区干净。任一项不通过则打回重派该子代理，层内其他已通过不受影响；验收通过才计入层收敛。
+- **分层并行**：同层无依赖的 issue 并行派发子代理，层内全部验收通过后才进入下一层；层间串行，层内并行。
+- **冲突处理**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。
+- **收敛**：全部层验收通过后编排器跑全量测试套件 + 目录卫生检查，任一失败按回退路由回到对应层重派。
+
+## 回合连续性规则
+
+flash 类模型在长程任务上容易在"预告下一步"处提前收尾——本规则源自一次真实事故（一次会话停四次，见 docs/agents/skill-design.md），是长程技能能否跑完的决定性规则。每个逻辑单元（一次红-绿循环、一次 typecheck、一次测试失败修复）必须**在一个回合内连续执行完毕后才输出**：测试 → 分析失败 → 修正 → 重跑 → 全绿 整条链一气呵成，中间不停顿、不等用户说"继续"。
+
+回合终点仅为三类之一：
+- **合规交互点**：技能要求的用户确认（如阶段② seams 清单确认）——此时提问并等待
+- **外部阻塞**：权限拒绝、缺失授权、依赖不可用——此时明确说明需要什么授权或替代路径，不静默停止
+- **阶段完成**：整个阶段的出口条件满足（如阶段③的所有 seams 红-绿完成 + typecheck 通过、commit 完成）——单个 seam 全绿只是阶段③的内部步骤，不是回合终点
+
+输出进度/预告本身不结束回合——输出后继续执行，直到三类终点之一达成；预告下一步后立即执行该步骤。逐 seam 的执行细则见 [stages.md 3e](references/stages.md#阶段-③tdd-开发循环)。
+
+编排模式下回合连续性延伸至**层**：一层内全部子代理派发后，编排器等待该层全 `resolved` 再进入下一层，不在层间停顿等待用户"继续"；子代理内部仍遵守单 issue 的回合连续性。
+
+## 不做什么
+
+- 不重写 TDD 语义：红-绿循环、seam 定义、好测试标准、mocking 边界一律查 [tdd 技能](.agents/skills/tdd/SKILL.md)，本技能只编排阶段与运行时规则
+- 不把重构塞进红-绿循环：重构归阶段⑤ Code Review
+- 不在阶段间停顿：单 seam 全绿、单次 typecheck 通过都不是回合终点（见回合连续性规则）
+- 不生成书面审查报告：阶段⑤审查结果只在对话输出，不落盘 `review-*.md` 类文件
+- 不手写超大改动：巨型 write/批量 replace 会撞输出上限、中途截断，因此单次 `write` 超 ~150 行先写骨架再分批补全；批量 `replace` 超 ~5 处先拆分再分批执行（见 [stages.md](references/stages.md) 3f）
+- 不跳步：阶段出口未达成不进入下一阶段（见路由规则）
+- 不为单 issue 引入编排：单 issue / 单 spec 不走多 issue 编排分支
+
+## 任务拆分与 Todo 规定
+
+### 拆分层级（大小任务层次）
+
+1. **大任务**：Goal/Ticket——整个实现单元，对应一次完整的 tdd-implement 流程
+2. **中任务**：Seam（阶段②确认）——一个红-绿循环单元，每 seam 一个 Todo
+3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
+4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
+
+编排模式下新增一层：
+
+5. **编排层**：Feature——`.scratch/<feature>/` 下全部 issues，按 `Blocked by` 分层；每层一组并行子代理，每子代理一个 issue 的完整 ①→⑦。
+
+### Todo 清单格式
+阶段② seams 确认后立即生成 todo 清单，每个 seam 一个 todo：
+- 编号：`T1`、`T2`、`T3`…
+- 描述：seam 名称 + 输入 + 预期输出
+- 状态：`pending` / `in-progress` / `done` / `blocked`
+- 完成标准（DoD）：该 seam 测试全绿 + typecheck 通过 + 既有测试不受影响
+- 执行步（Subtodo）：`T1-R` 红（写失败测试）→ `T1-G` 绿（最小实现）→ `T1-T` typecheck
+
+编排模式下 Todo 清单为**分层清单**：`L1: [01, 02] → L2: [03, 04] → L3: [05]`，每层内 issue 并行，层间串行；每 issue 的 DoD 为 `Status: resolved` + 独立 commit + 实施总结已落盘。
+
+### Todo 状态机
+```
+pending → in-progress → done
+                ↘ blocked（外部阻塞）→（授权/替代路径）→ in-progress
+```
+- Subtodo 不单独设 `blocked`——阻塞状态归父 Todo，Subtodo 跟随父状态
+
+编排模式下 issue 粒度状态机：`pending → in-progress(子代理已派发) → done(Status: resolved)`；`blocked` 表示 `Blocked by` 依赖未满足，待前层全 `resolved` 后自动解阻。
+
+### 粒度与回合归属
+- 一个 todo = 一个 seam 的红-绿 cycle + typecheck，不可再拆
+- 一个 todo 必须在一个回合内完成（红→绿→typecheck→全绿）
+- Subtodo 是 todo 内的执行步：每完成一步立即进入下一步（`T1-R` → `T1-G` → `T1-T`），禁止停在步间预告
+- 每完成一个 todo 立即更新其状态，再进入下一个
+- todo 状态只按实际推进更新（pending → in-progress → done），不基于旧快照重写整个清单；已完成项（done）永不回退
+- 全部 todo 为 done 才进入阶段④
+
+编排模式下：每层全部 issue `done` 才进入下一层；全部层 `done` 后编排器做全量收敛验证。
+
+### 阻塞处理
+- 外部阻塞（权限拒绝、缺失授权、依赖不可用）→ 标记 `blocked`，记录所需授权或替代路径
+- 不静默停止；恢复后回到 `in-progress` 继续
+
+编排模式下：`Blocked by` 依赖阻塞由编排器自动管理——前层未全 `resolved` 时后层 `blocked`，前层收敛后自动解阻派发；不需人工确认依赖满足。
+
+## 路由规则
+
+### 正常流转
+
+| 当前阶段 | 出口条件 | 下一阶段 |
+|----------|----------|----------|
+| ① 理解需求 | 需求已澄清，无歧义 | → ② 确认 Seams |
+| ② 确认 Seams | 用户确认 seams 清单 | → ③ TDD 开发 |
+| ③ TDD 开发 | 所有 seams 红-绿完成，typecheck 通过 | → ④ 完整测试套件 |
+| ④ 完整测试套件 | 全部测试通过 | → ⑤ Code Review |
+| ⑤ Code Review | 审查通过 | → ⑥ Commit |
+| ⑥ Commit | commit 完成 | → ⑦ 收尾 |
+| ⑦ 收尾 | issue 状态已更新 + 实施总结已写 | ✅ 结束 |
+
+编排模式流转：`编排器：依赖图 → 分层 → [层内并行子代理(①→⑦) → 层收敛]×N → 全量收敛 → 汇总总结 ✅`；子代理内部仍走上表单 issue 流转。
+
+### 回退路由
+
+| 当前阶段 | 回退条件 | 回退目标 |
+|----------|----------|----------|
+| ③ TDD 开发 | typecheck 失败 | → ③ 修复类型错误 |
+| ④ 完整测试套件 | 测试失败 | → ③ 修复失败测试 |
+| ⑤ Code Review | 实现错误 | → ③ 修复实现 |
+| ⑤ Code Review | seams 遗漏 | → ② 补充 seams |
+| ⑤ Code Review | 需求偏差 | → ① 澄清需求 |
+
+编排模式回退：子代理内回退按上表在子代理内闭环；编排器层收敛失败（全量测试失败 / 目录不干净）→ 定位到失败 issue 所在层重派对应子代理。
+
+## 引用
+
+- TDD 核心规则：[tdd 技能](.agents/skills/tdd/SKILL.md)
+- 测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
+- Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
+- Commit 门禁：[commit-check 技能](.agents/skills/commit-check/SKILL.md)
+- Issue tracker 约定：[issue-tracker.md](../../docs/agents/issue-tracker.md)

package/template/.pi/skills/tdd-implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "TDD Implement"
+  short_description: "Implement from spec/ticket via TDD red-green loop"
+policy:
+  allow_implicit_invocation: false

package/template/.pi/skills/tdd-implement/references/stages.md

@@ -0,0 +1,315 @@
+# 阶段详细定义
+
+## 目录
+
+- [阶段 ①：理解需求](#阶段-①理解需求)
+- [阶段 ②：确认 Seams（测试接缝）](#阶段-②确认-seams测试接缝)
+- [阶段 ③：TDD 开发循环](#阶段-③tdd-开发循环)
+- [阶段 ④：完整测试套件](#阶段-④完整测试套件)
+- [阶段 ⑤：Code Review](#阶段-⑤code-review)
+- [阶段 ⑥：Commit](#阶段-⑥commit)
+- [阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）](#阶段-⑦收尾文档对齐--issue-状态--实施总结)
+- [附录：多 issue 编排（按依赖分层并行）](#附录-多-issue-编排按依赖分层并行)
+
+## 阶段 ①：理解需求
+
+### 入口条件
+- 用户提供了 spec 或一组 ticket
+
+### 操作
+1. 完整读取 spec/ticket 内容
+2. 若存在 `CONTEXT.md` 和 `docs/adr/`，先阅读，确保术语和 ADR 决策不被违背
+3. 如有歧义，先向用户澄清再继续
+
+### 出口条件
+- 能用自己的话复述需求
+- 无未澄清的歧义
+
+### 边界
+- 本阶段只澄清需求——实现与测试设计在后续阶段进行
+
+---
+
+## 阶段 ②：确认 Seams（测试接缝）
+
+### 入口条件
+- 需求已澄清，无歧义
+
+### 操作
+1. 列出所有将要测试的公共接口（seams）
+2. 每个 seam 需包含：名称、输入、预期输出
+3. 向用户展示 seams 清单并确认
+4. 用户确认后才写任何测试代码
+5. seams 确认后生成 todo 清单（每 seam 一个 todo，含编号/状态/DoD）——格式与状态机见 [SKILL.md「任务拆分与 Todo 规定」](../SKILL.md#任务拆分与-todo-规定)
+
+### 出口条件
+- 用户明确同意了 seams 清单
+
+### 边界
+- 一个 seam 对应一个公共接口上的一个待测行为（输入 + 预期输出）：一个 seam = 一个测试 + 一个最小实现 cycle；同一接口的多个行为拆分为多个 seam，而非内部函数
+
+> Seams 定义参考：[tdd 技能](.agents/skills/tdd/SKILL.md#seams--where-tests-go)
+
+---
+
+## 阶段 ③：TDD 开发循环
+
+### 入口条件
+- Seams 已确认
+
+### 操作
+
+**红-绿循环前与循环中都查阅 tdd 技能各节**（Every section applies on every cycle）：TDD 语义与测试规则以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不再在此重写——好测试标准见 [tdd/tests.md](.agents/skills/tdd/tests.md)，Mock 指南见 [tdd/mocking.md](.agents/skills/tdd/mocking.md)。
+本阶段只执行编排：按阶段②生成的 todo 清单逐条推进（大小任务层次与 Subtodo 格式见 [SKILL.md「任务拆分与 Todo 规定」](../SKILL.md#任务拆分与-todo-规定)），每完成一个 todo（红-绿 cycle + typecheck）立即更新其状态为 `done`，再进入下一个 todo。
+
+#### 3a/3b. 红-绿（Red-Green）
+红-绿循环的执行规则（Red before green、One slice at a time、Anti-patterns、垂直切片）以 tdd 技能为准，见 [tdd/SKILL.md](.agents/skills/tdd/SKILL.md) 与 [tdd/tests.md](.agents/skills/tdd/tests.md)。
+
+#### 3c. 切换 seam
+每完成一个 seam 立即进入下一个 seam，同一回合内串行推进，不等用户“继续”。
+
+#### 3d. Typecheck
+- 每个 cycle 结束后运行 typecheck
+- 发现问题立即修复，修复后再继续
+
+#### 3e. 回合连续性
+- 每个红-绿 cycle 及其 typecheck 必须在一个回合内串行完成：测试 → 分析失败 → 修正 → 重跑 → 全绿，中途不输出、不停止、不等用户“继续”
+- **单个 seam 全绿不是回合终点**：它只是阶段③的内部步骤；阶段③的出口是“所有 seams 红-绿完成 + typecheck 通过”，在出口达成前不停顿、不等待确认，直接进入下一个 seam
+- 预告下一步后立即执行该步骤，回合终点仅为合规交互点、外部阻塞或阶段出口条件满足
+- 进度输出并入工具调用序列，不单独结束回合——输出后继续执行，直到三类终点之一达成
+- 输出只发生在：合规交互点（用户确认）、外部阻塞（明确说明所需授权或替代路径）、阶段出口条件满足时
+- 外部阻塞（如权限拒绝）时明确请求授权或改用不冲突的路径，不静默等待
+
+#### 3f. 任务分解（Chunking）
+- 单次 `write` 超过 ~150 行：先写骨架再分批补全
+- 批量 `replace` 超过 ~5 处：分批执行，每批后立即 typecheck 验证
+
+#### 3g. Todo 更新纪律
+- 每完成一个红-绿 cycle（含 typecheck），按实际推进更新对应 todo 状态：`in-progress` → `done`
+- 更新基于当前实际状态，不基于旧快照重写整个清单；已完成项（done）永不回退
+
+### 出口条件
+- 所有 seams 的红-绿循环完成
+- Typecheck 通过
+
+### 边界
+- 每个 cycle 后运行 typecheck
+- 全部 todo 为 done 才进入阶段④
+- 测试质量规则（公共接口验证、独立断言、mock 边界、重构归属 review）见 tdd 技能，不在本阶段重写
+
+> Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
+> 好测试标准：[tdd/tests.md](.agents/skills/tdd/tests.md)
+
+---
+
+## 阶段 ④：完整测试套件
+
+### 入口条件
+- 阶段 ③ 完成，typecheck 通过
+
+### 操作
+1. 运行仓库的完整测试套件
+2. 检查所有测试是否通过
+
+### 出口条件
+- 全部测试通过
+
+### 边界
+- 测试失败时回到阶段 ③ 修复，修复后重新运行完整套件——进入 review 前必须全绿
+
+---
+
+## 阶段 ⑤：Code Review
+
+### 入口条件
+- 完整测试套件通过
+
+### 操作
+1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前所有改动：
+   - **Standards 轴**：改动是否符合仓库文档化的编码标准（含 smell baseline 判断）
+   - **Spec 轴**：改动是否忠实实现来源 spec/issue（逐条对照验收要求）
+   - 两轴独立报告、**互不掩盖**——一轴通过另一轴失败时仍须修复后重审
+2. **派发方式（强制）**：两轴必须用 subagent **single 模式**（`agent`+`task`）或 `subagent_consult` 逐个派发；**禁止 parallel `tasks` 数组**——pi-subagents 对 parallel 结果只保留前 160 字节摘要（`truncateUtf8(summary, 160)`），中文/多行报告必被截断（标记 `… [truncated by pi-subagents]`）。需要更完整输出时，要求子代理把报告写入临时文件，主代理再读取
+3. 审查发现的问题按 [SKILL.md 回退路由](../SKILL.md#回退路由) 处理
+### 出口条件
+- Code review 通过
+
+### 边界
+- 重构在此阶段进行，而非 TDD 循环阶段
+- review 通过后才进入 commit
+- 审查结果只在对话输出，不生成书面审查报告（不落盘 `review-*.md` 类文件）
+
+---
+
+## 阶段 ⑥：Commit
+
+### 入口条件
+- Code review 通过
+
+### 操作
+1. 调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md) 执行提交门禁——四项检查：①审查文档 ②对齐 README ③保持目录卫生 ④规范 commit message
+2. 四项**全部通过才 commit**：将工作提交到当前分支，附清晰的 commit message
+3. 任一项发现问题的：先修复，再重跑该项，全部通过才 commit
+
+### 出口条件
+- Commit 完成
+
+### 边界
+- Commit message 格式与内容由 commit-check ④ 把关（描述变更内容而非过程）
+
+---
+
+## 阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）
+
+### 入口条件
+- Commit 完成（阶段⑥出口）
+
+### 操作
+1. **对齐文档**：检查 README 与 `docs/` 中涉及本次实现的描述（用法、CLI、配置、示例、架构、行为）是否与实现一致；不一致则更新文档，并单独 commit（message 遵循 commit-check ④ 规范，如 `docs: align README with <feature>`）
+2. 若本次实现有关联 issue/ticket（`.scratch/<feature-slug>/issues/`）：先审查该 issue——从 issue 提取验收标准（无显式验收标准节时以其正文行为要求为准），逐条转写为 checkbox 清单并逐条验证：通过标 `- [x]`，未通过保留 `- [ ]` 并注明缺口（证据：文件:行号 / 测试名）。全部打勾后才允许下一步：
+3. 将 `Status:` 行改为 `resolved`（无该行则追加），不改动 spec 与既有 Comments
+4. 在 issue 文件底部追加实施总结（`## 实施总结` 标题）：
+
+   ```
+   ## 实施总结
+   - 提交：`<commit hash>` — `<commit message>`
+   - 实现的 seams：<清单>
+   - 验收标准：逐条 `- [x]`（未全绿列出缺口）
+   - 测试结果：<全绿 / 数量>
+   - typecheck：通过
+   - 文档对齐：<更新了哪些文件 / 无需更新>
+   - 遗留 / 后续建议：<如有>
+   ```
+
+5. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
+6. **保持目录卫生**：清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束
+
+### 出口条件
+- 文档与实现对齐（无相关文档或已更新）
+- issue 状态已更新（或确认无 issue）
+- 实施总结已落盘 / 输出
+- 工作区干净（临时产物已清理，`git status` 无残留未跟踪文件）
+
+### 边界
+- 只追加不改写：不修改 spec.md 与既有 Comments 内容
+- 文档对齐仅限与本次实现直接相关的描述，不顺手重构无关文档
+- 总结写事实（提交 / 测试 / 遗留），不写过程叙述
+
+---
+
+## 附录：多 issue 编排（按依赖分层并行）
+
+本附录仅在多 issue 编排模式下生效（见 [SKILL.md 多 issue 编排](../SKILL.md#多-issue-编排按依赖分层并行)）；单 issue / 单 spec 走上节单线流程，不经过本附录。
+
+### 入口条件
+- `.scratch/<feature>/issues/` 下存在多个 issue 文件
+- 至少部分 issue 含 `Blocked by` 依赖声明
+
+### A0. 依赖图构建
+
+1. 扫描 `.scratch/<feature>/issues/` 下全部 `NN-<slug>.md`，逐文件解析 `Blocked by` 行：
+   - `Blocked by: None` / `Blocked by: （无` / 无此行 → 无依赖（frontier）
+   - `Blocked by: 01, 02` / `Blocked by: 01（…）` → 依赖 `01`、`02` 对应的 issue 文件（按编号前缀匹配）
+   - 无法解析的行 → 视为无依赖，并在编排总结中注明告警
+2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；若检测到环，立即报错并列出环上节点，不进入调度。
+3. 读取 `spec.md`（若存在）作为各子代理的共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
+
+### A1. 拓扑分层
+
+对 DAG 做 Kahn 分层（BFS 拓扑）：
+
+```
+L1 = 全部入度为 0 的节点（可立即开始）
+L2 = 移除 L1 后入度为 0 的节点
+…
+Ln = 最后一层
+```
+
+每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
+
+### A2. 分层调度
+
+```
+for each 层 Li in L1..Ln:
+  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，禁止 parallel tasks 数组）
+  等待：阻塞直到 Li 全部子代理返回回执卡片
+  验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证，不消费全量日志）
+  收敛：验收全通过进入 Li+1；有不通过按 A5 回退重派该 issue
+全部层验收通过后进入 A4 全量收敛
+```
+
+- **派发纪律**：与阶段⑤双轴审查一致——逐个 `subagent` 派发，禁止 `parallel tasks` 数组（同因：中文报告截断）。
+- **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 处理。
+- **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
+
+### A3. 子代理契约（单 issue 单代理）
+
+每个子代理是一个**完整的 tdd-implement 单 issue 执行单元**，输入与产出严格界定：
+
+- **输入**：
+  - `spec.md`（feature 级共享 spec，若无则以该 issue 正文为准）
+  - 分配的单个 `NN-<slug>.md`（唯一 issue 输入）
+  - `CONTEXT.md` + `docs/adr/`（术语与决策一致性）
+- **执行**：严格走 tdd-implement ①→⑦全流程——①理解需求（读 spec + issue）→ ②确认 seams（该 issue 范围内）→ ③红-绿循环 → ④完整测试套件 → ⑤双轴 review → ⑥commit-check 门禁 + commit → ⑦文档对齐（仅该 issue 相关描述）+ `Status: resolved` + `## 实施总结` 落盘 + 目录卫生。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在子代理内重写。
+- **产出**：
+  - 独立 commit（message 含 issue 编号，如 `feat(<feature>): <issue title> (#NN)`）
+  - 该 issue 文件 `Status: resolved` + 底部 `## 实施总结`
+  - 该 issue 范围内的测试全绿 + typecheck 通过
+- **禁止**：跨 issue 改动；修改其他 issue 文件；跳过 ⑤/⑥ 直接 commit。
+
+#### 输出约束（子代理只返回回执卡片）
+
+子代理不向编排器透传全量过程日志（各 seam 的红-绿细节、typecheck 原始输出、双轴 review 全文、完整测试日志）。只返回一张**回执卡片**（结构化关键信息，中文，≤ 30 行）：
+
+```
+[回执] #NN <issue 标题>
+- 提交：<commit hash> — <message>
+- seams：<清单>
+- 测试：<数量> 项，全绿 / 失败清单
+- typecheck：通过 / 失败原因
+- review：Standards <通过/问题> / Spec <通过/问题>
+- 验收：checkbox <m/n 全绿，缺口说明>
+- 文档：<更新文件 / 无需更新>
+- 遗留：<如有>
+```
+
+卡片字段缺一不可；缺失字段视为验收不通过。详细过程与证据留在子代理的 commit 与 issue 文件中，编排器按需抽检而非全量消费。
+
+#### 主代理验收（编排器逐 issue 验收）
+
+编排器收到回执后逐 issue 验收，不盲信子代理自检：
+
+1. **落盘校验**：`git log --oneline` 含该 commit 且 message 含 `#NN`；issue 文件 `Status: resolved` 且底部 `## 实施总结` 已落盘。
+2. **抽检验证**：抽跑该 issue 相关测试（或 `tsc --noEmit` 抽检），不重跑全量套件；抽检失败即打回。
+3. **改动边界**：`git diff <base>..HEAD --name-only` 核对无跨 issue 文件改动；有跨改视为不通过。
+4. **卫生**：`git status` 无 `[DEBUG-...]` 残留与未跟踪临时文件。
+
+任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
+
+子代理内部的回合连续性、任务分解、Todo 规定与单线模式完全一致（见 SKILL.md 回合连续性规则与 stages.md 阶段③ 3e/3f）。
+
+### A4. 全量收敛
+
+全部层逐 issue 验收通过后，编排器执行：
+
+1. **全量测试套件**：跑仓库完整测试套件（阶段④口径），失败则按 A5 回退。
+2. **目录卫生**：`git status` 确认无 `[DEBUG-...]` 残留、无未跟踪临时文件；有残留则清理后重检。
+3. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件，不透传子代理全量日志（各 issue 的 `## 实施总结` 已落盘，详查落盘文件）。
+
+### A5. 回退与冲突
+
+- **子代理内回退**：按 SKILL.md 回退路由在子代理内闭环（typecheck 失败 → ③、测试失败 → ③、review 不通过 → ③/②/①）。
+- **层收敛失败**：层内任一子代理未达到 `resolved`（测试失败 / review 不通过 / commit-check 门禁失败）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后重派该层失败节点。
+- **全量收敛失败**：A4 全量测试失败 → 定位到失败测试归属的 issue，回到其所在层重派对应子代理。
+- **文件冲突**：同层子代理若触及同一文件，后完成者 rebase 解决冲突后重跑 typecheck + 相关测试；跨层天然串行无冲突。冲突检测以 `git` 合并结果为准，编排器不做静态预判。
+- **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
+
+### 出口条件
+- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘
+- 全量测试套件通过
+- 工作区干净（`git status` 无残留）
+
+### 边界
+- 单 issue / 单 spec 不走本附录
+- 子代理不跨 issue 改动；编排器不替子代理写实现代码
+- 汇总总结只在对话输出，不落盘额外汇总文件

package/template/AGENTS.md

@@ -0,0 +1,59 @@
+## 优先级
+
+系统 / developer 指令 > 用户当次明确要求 > 本文件 > 全局 AGENTS.md > 技能（Skills）
+
+## 基础偏好
+
+- 执行类给短进度，分析类给结论/依据/权衡
+- 不为严谨展开冗长流程；复杂/根因不明/高风险/跨模块才展开；回合连续性（逻辑单元一回合串行完成，见分文件）
+
+## 能力边界
+
+- 工具：以当前 harness 实际提供为准（bash / 文件读写 / grep / glob / 代码图 / 子代理 / 网页抓取等可用子集）；不硬编码不存在的工具；承诺前先检查 git/依赖/端口
+
+## 快速上手
+
+1. 读 `CONTEXT.md`（术语）——没有则跳过
+2. 按行为路由表行动；未命中用 ask-matt 或直接澄清
+3. 探索代码库：优先 codegraph CLI（`codegraph explore`），无索引时派 explore 子代理
+
+## 执行原则
+
+- 先澄清边界再实现；局部最小修改；用户当次指令优先于历史经验；脏工作区不回滚他人改动
+- 执行与文档维护细则（沉淀门槛、条目格式）见分文件
+
+## 安全边界
+
+以全局 AGENTS.md 安全铁律为准，本仓库无附加差异。
+
+## 行为路由
+
+命中即行动，回复中简短声明所用技能与原因。
+
+- 探索/定位/理解代码库 → 有 `.codegraph/` 索引：`codegraph explore`（CLI）优先；无索引用 explore 子代理
+- 后台调研 → research；原型验证 → prototype
+- 实现（有 spec）→ implement（无 spec 先 to-spec）；测试先行 → tdd
+- 设计打磨 → grilling；达成共识→spec → grill-to-spec（grilling→domain-modeling→to-spec）
+- 领域术语/ADR → domain-modeling；模块接口 → codebase-design；巨型规划 → wayfinder
+- 诊断 → diagnose-fix（编排 diagnosing-bugs 诊断 + tdd 修复，修复环节强制 TDD）；审查 → code-review；合并冲突 → resolving-merge-conflicts；提交前 → commit-check（审查文档 + 对齐 README + 目录卫生 + commit message）
+- 分诊 → triage；架构扫描 → improve-codebase-architecture；综合 spec → to-spec；拆票 → to-tickets
+- 教学 → teach；交接 → handoff；技能写作 → writing-great-skills
+- 兜底 → ask-matt；模板维护 → README.md
+
+显式触发（须用户 `/` 发起）：grill-to-spec、wayfinder、to-spec、to-tickets、triage、improve-codebase-architecture、teach、handoff、writing-great-skills
+
+## 分文件
+
+- 运行时纪律与执行/文档维护细则 → `docs/agents/runtime-discipline.md`
+- 技能设计规范 → `docs/agents/skill-design.md`
+- Issue tracker → `docs/agents/issue-tracker.md`；Triage labels → `docs/agents/triage-labels.md`；Domain docs → `docs/agents/domain.md`
+- 术语表 → `CONTEXT.md`
+
+## CodeGraph
+
+仓库被 CodeGraph 索引（根目录存在 `.codegraph/`）时，理解/定位代码**优先于** grep/find/读文件——一次调用拿到相关符号源码与调用路径：
+
+- **CLI**（首选）：`codegraph explore "<符号名或问题>"` 一次回答大部分代码问题——相关符号的逐字源码 + 调用路径（含 grep 追不上的动态分派跳转）。在 query 中指名文件/符号即可读取其带行号的当前源码。
+- **MCP 工具**（可用时补充）：`codegraph_explore` 输出与 CLI 相同；若列出但延迟加载，用工具搜索按名加载。
+
+没有 `.codegraph/` 目录则完全跳过 CodeGraph——是否建立索引由用户决定。