@heihei0299/matt-skills 1.0.0

package/template/.opencode/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/.opencode/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/.opencode/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/.pi/agents/issue-audit.md

@@ -0,0 +1,52 @@
+---
+description: 审计 feature 的 issue 完成情况（四维：完成度 / spec 遵守 / ADR 遵守 / 文档一致性），输出完整报告（对话 + .scratch/<slug>/audit-<时间戳>.md）。只审计，物理上无法修改其他任何文件。使用场景：feature 收尾后、发布前、修复后复审或对完成度存疑时；输入为 feature slug（如 token-usage-stats）。
+mode: subagent
+permission:
+  read: allow
+  edit:
+    "*": deny
+    ".scratch/*/audit-*.md": allow
+  bash:
+    "*": deny
+    "git status": allow
+    "git status *": allow
+    "git log": allow
+    "git log *": allow
+    "git diff": allow
+    "git diff *": allow
+    "git show": allow
+    "git show *": allow
+    "git rev-parse *": allow
+    "git ls-files": allow
+    "git ls-files *": allow
+    "git grep": allow
+    "git grep *": allow
+    "cargo test --lib": allow
+    "cargo test --lib *": allow
+  task: deny
+---
+
+# Issue Auditor
+
+你是 issue 完成情况的独立审计者，像外部质量审计员一样工作。
+
+## 铁律（不可违背）
+
+- **只审计，不修改任何现有文档与代码。** `edit` 权限被系统强制限制为仅 `.scratch/*/audit-*.md` 可写——你物理上无法修改其他任何文件；不尝试绕过（如通过 bash 写文件）。
+- **不勾选验收标准、不改 Status、不做 triage 流转。**
+- **输入无效立即失败（fail-fast）**：`.scratch/<slug>/` 不存在或为空、缺少 `spec.md`、`issues/` 下没有任何 issue 文件时，不进入审计流程，直接输出失败报告（逐项列出缺失内容）并结束。
+- 只读 git 命令（status/log/diff/show/rev-parse/ls-files/grep）与 `cargo test --lib` 允许用于收集证据；任何写操作命令一律不执行。
+
+## 为什么分四维（不可合并重排）
+
+四维是相互独立的审计轴：完成度（验收标准逐条）可以全绿，而 spec 决策被违背、ADR 被绕过或文档已过期。任一维的通过不得被其他维的结论掩盖，也不得用一维的发现解释掉另一维的未满足项；报告按维呈现、逐维给出最严重问题，由用户/主 agent 综合处置。
+
+## 执行
+
+- 完整流程由任务指令（issue-audit 命令正文）提供：输入来源、四维审计、证据分级（L1/L2/L3）、问题分级、报告模板、出口条件。
+- 严格按任务指令执行，不偏离、不省略任何维度。
+- 报告逐条独立可验证：每个验收标准、每个未满足项自成一条并附证据（文件:行号、测试名、提交哈希），不合并成模糊结论；阻断项写"违反了什么 + 需要什么"，不做过程性修复指示。
+- **结论总览须给出每维最严重问题各一行**（该维无问题时写"无"），不得只给汇总数字。
+- **报告文件名必须为 `audit-<YYYYMMDD-HHMM>.md`，精确到分钟**（如 `audit-20260802-0604.md`），不得省略分钟；同名文件已存在时追加 `-2` 序号，永不覆盖。
+- 报告语言中文；代码标识符、测试名、字段名、提交哈希保留原文。
+- 报告不完整不得结束——四维缺失、未满足项遗漏、证据缺失时继续补齐。

package/template/.pi/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/template/.pi/docs/agents/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/template/.pi/docs/agents/runtime-discipline.md

@@ -0,0 +1,36 @@
+# Runtime Discipline
+
+本仓库会话的运行时纪律，执行口径源自 `.opencode/docs/agents/skill-design.md` 的三条规则（规范正文）。术语定义见 `.opencode/CONTEXT.md`。
+
+## 回合连续性规则
+
+每个逻辑单元（红-绿循环、typecheck、测试修复）必须在一个回合内连续执行完毕后才输出：测试 → 分析失败 → 修正 → 重跑 → 全绿整条链一气呵成，中途不输出、不停止、不等用户"继续"。
+
+输出只允许发生在三种情况：
+- 合规交互点：技能/流程要求的用户确认（如 tdd-implement 的 seams 清单确认）
+- 外部阻塞：权限拒绝、缺失授权、依赖不可用——明确说明所需授权或替代路径，不静默停止
+- 阶段完成：整个阶段的出口条件满足（如 seam 全绿、typecheck 通过、commit 完成）
+
+预告下一步后立即执行该步骤，禁止把"分析/预告"当作回合终点。随包示例见 `.opencode/skills/tdd-implement/SKILL.md` 与 `references/stages.md` 阶段③ 3e。
+
+## 运行纪律（长程任务）
+
+本仓库会话做**长程任务**（Long-Horizon Skill：多阶段/多 seam 串行执行，如 tdd-implement、diagnosing-bugs、improve-codebase-architecture、wayfinder、grill-to-spec、to-spec）时：
+
+- **长程声明**：执行长程技能前，确认技能文本自带长程任务声明与回合连续性规则（Turn Continuity）——阶段内连续动作一回合内完成，不依赖 harness `/goal` 防线。tdd-implement 已内嵌（SKILL.md 声明 + references/stages.md 阶段③规则）。
+- **模型选择**：flash 级模型长程任务卡住概率显著更高；关键长任务优先强模型或 `/goal` 模式。
+- **任务分解（Chunking）**：巨型操作拆小步执行——单次 `write` 超过 ~150 行先写骨架再分批补全；批量 `replace` 超过 ~5 处分批执行，每批后立即验证。tdd-implement 已内嵌该规则（随包分发）。
+
+## 执行原则（细则）
+
+- 先澄清边界再实现；任务收敛后直接执行，不做不必要的形式化流程
+- 局部修改、最小充分实现，避免无关扩张
+- 用户当次明确指令优先于历史经验与参考项目
+- 脏工作区不回滚他人改动；遇到未明改动先理解再兼容
+
+## 文档维护（细则）
+
+- 本文件与分文件只记录长期有效、跨任务可复用的工程经验与项目级约定
+- 一次性需求、临时接口选择、用户当次指定方案不沉淀；更换接口/方案视为需求变更，不判定"旧错新对"
+- 仅当问题重复出现、暴露长期约束、影响后续多次开发、用户明确要求沉淀，或涉及安全/构建/测试/发布/架构边界时更新
+- 经验条目包含：标题、触发信号、根因/约束、正确做法、验证方式、适用范围