@heihei0299/matt-skills 1.6.2 → 1.6.4-test.0

package/.agents/skills/show-me/SKILL.md

@@ -0,0 +1,5 @@
+---
+name: show-me
+description: Show the current state or demo for review.
+---
+Show the current implementation or state for the user to review.

package/.agents/skills/tdd-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd-implement
-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."
+description: "Multi-task orchestrator: use when the user provides a spec/ticket or Type:task issues (wayfinder/to-tickets/single spec) for test-first implementation. Main agent executes tasks sequentially by Blocked-by Kahn order, each task full ①→⑦ implement (seam red-green → typecheck → code-review → commit-check → single commit). For non-TDD use implement; for technique alone use tdd."
 ---
 
 # TDD Implement
@@ -11,13 +11,11 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 
 ## 分支
 
-- **单线**：单 spec / 单 issue，走下节 Steps ①→⑦（详规见 [stages.md](references/stages.md)）。
-- **多 issue 编排**：`.scratch/<feature>/issues/` 下多文件且含 `Blocked by` 时走编排模式——见下节与 [orchestration.md](references/orchestration.md)。
-
-## 多 issue 编排（按依赖分层并行）
-
-触发见 [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。
+- **入口**：单 `spec` 文件（`.scratch/<feature>/spec.md` 或等价）/ `Type: task` 的 `issue`（`wayfinder`/`to-tickets` 产出）均视同单 `task`，走下节 Steps ①→⑦；`Type: research/prototype/grilling` 分流至对应技能。
+- **多 issue 编排**：`.scratch/<feature>/issues/` 下多 `task` 时走编排模式——见上节与 [orchestration.md](references/orchestration.md)。
+## 多 issue 编排（按依赖串行，主代理直接执行）
 
+触发见 [orchestration.md](references/orchestration.md)；`.scratch/<feature>/issues/` 下多文件时触发，主过程 A0 依赖图 → A1 Kahn 分层 L1入度0→L2→Ln → A2 主代理串行调度（按层串行、层内亦串行，主代理直接执行完整 ①→⑦，禁止子代理派发；每 issue 单独 `commit`，绿后即 `code-review` + `commit-check` 双门禁） → A3 层收敛 → A4 全量收敛。`Blocked by` 仍为排序输入，三入口（单 `spec` / `Type: task` issue / `wayfinder task`）同构。强制维护 `.scratch/<feature>/progress.md`（`DAG` + `Layers` + `Progress` 表，派生视图，真相源为 `spec` + `issues/*.md`）。
 ## Steps
 
 按序执行，每步达到完成条件才进入下一步；进入任一步前先读取其在 [stages.md](references/stages.md) 的定义。
@@ -32,12 +30,12 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 | ⑥ Commit | 跑 [commit-check](.agents/skills/commit-check/SKILL.md) 门禁四项后提交 | commit 完成且历史校验通过 | [stages.md#阶段-⑥](references/stages.md#阶段-⑥commit) |
 | ⑦ 收尾 | 文档对齐 → issue 状态与实施总结 → 目录卫生 | 文档已对齐、issue 已 `resolved`+总结落盘、工作区干净 | [stages.md#阶段-⑦](references/stages.md#阶段-⑦收尾文档对齐--issue-状态--实施总结) |
 
-子代理内部仍走上表 ①→⑦（其中 ④ 为相关测试口径，全量由编排器收敛）。
+主代理串行时每 `task` 仍走上表 ①→⑦（每 issue 单独 `commit`，`code-review` + `commit-check` 双门禁逐 issue，全量由 A4 收敛）。
 
 ### 阶段间流转
 
 - 正常流转：出口条件满足即进入下一阶段，不在阶段间停顿。
-- 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md#A5](references/orchestration.md#a5-回退与冲突)。
+- 回退路由：见 [stages.md#回退路由](references/stages.md#回退路由)；编排模式回退见 [orchestration.md](references/orchestration.md)。
 - 回合连续性与任务分解：见 [stages.md ③-3e/3f](references/stages.md#阶段-③tdd-开发循环)（红→绿→typecheck→下一 seam 一个回合内串行完成，直至阶段出口；预告下一步后立即执行；write>150 行/replace>5 处拆小步）。
 
 ## 引用
@@ -47,4 +45,4 @@ description: "TDD seam red-green loop: use when the user provides a spec/ticket
 - Mock 指南：[tdd/mocking.md](.agents/skills/tdd/mocking.md)
 - Commit 门禁：[commit-check](.agents/skills/commit-check/SKILL.md)
 - 单线详规：[stages.md](references/stages.md)
-- 多 issue 编排详规：[orchestration.md](references/orchestration.md)（全量保留）
+- 多 issue 编排详规：[orchestration.md](references/orchestration.md)（A0-A1 排序 + 主代理串行，不含子代理）

package/.agents/skills/tdd-implement/references/orchestration.md

@@ -1,17 +1,18 @@
-# 多 issue 编排（按依赖分层并行）
+# 多 issue 编排（按依赖串行，主代理直接执行）
 
-本文件仅在多 issue 编排模式下生效；单 issue / 单 spec 走 [stages.md](stages.md) 单线流程，不经过本文件。
+本文件仅在多 `task` 编排时生效；单 `spec` / 单 `task` 走 [stages.md](stages.md) 单线 ①→⑦，主代理直接执行完整流程并单独提交，不经子代理。
 
-多 issue 触发条件：`.scratch/<feature>/issues/` 下存在多个 issue 文件且至少部分含 `Blocked by` 依赖声明。
+多 issue 触发条件：`.scratch/<feature>/issues/` 下存在多个 `Type: task` 的 issue 文件（`wayfinder`/`to-tickets` 产出或等价），按 `Blocked by` 组织依赖。
+
+三入口（单 `spec` / 单 `task` / 多 `task`）在单 issue 层面同构：`spec`/`issue` 均为 `task` 闭环输入，`research`/`prototype`/`grilling` 分流不进本技能。编排层 Feature—`.scratch/<feature>/` 下全部 `task` 按 `Blocked by` 分层。
 
 ## 目录
 
 - [A0. 依赖图构建](#a0-依赖图构建)
 - [A1. 拓扑分层](#a1-拓扑分层)
-- [A2. 分层调度](#a2-分层调度)
-- [A3. 子代理契约（单 issue 单代理）](#a3-子代理契约单-issue-单代理)
+- [A2. 主代理串行调度](#a2-主代理串行调度)
+- [A3. 层收敛](#a3-层收敛)
 - [A4. 全量收敛](#a4-全量收敛)
-- [A5. 回退与冲突](#a5-回退与冲突)
 - [出口条件](#出口条件)
 - [边界](#边界)
 
@@ -24,8 +25,8 @@
    - `Blocked by: 01, 02` / `Blocked by: 01（…）` → 依赖 `01`、`02` 对应的 issue 文件（按编号前缀匹配）
    - 无法解析的行 → 视为无依赖，并在编排总结中注明告警
 2. 以 issue 编号为节点、`Blocked by` 为有向边构建 DAG；若检测到环，立即报错并列出环上节点，不进入调度。
-3. 读取 `spec.md`（若存在）作为各子代理的共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
-
+3. 读取 `spec.md`（若存在）作为共享上下文；同时读取 `CONTEXT.md` 与 `docs/adr/` 供一致性校验。
+4. **强制初始化 `progress.md`**：在 `.scratch/<feature>/progress.md` 落 `## DAG` + `## Layers (Kahn L1..Ln)` + `## Progress` 空表（`| NN | Status | Commit | Review | Tests |`），作为编排态唯一派生视图（真相源仍为 `spec` + `issues/*.md`）。
 ### A1. 拓扑分层
 
 对 DAG 做 Kahn 分层（BFS 拓扑）：
@@ -37,101 +38,52 @@ L2 = 移除 L1 后入度为 0 的节点
 Ln = 最后一层
 ```
 
-每层内节点互无依赖，可并行；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才派发。
-若两 issue 在阶段②已声明预期改动同一文件，编排器在 A0 后提示建议追加 `Blocked by` 使其串行（轻提示，不强制）；主要仍靠 A2 串行错峰自然错峰。
-### A2. 分层调度
-
-```
-for each 层 Li in L1..Ln:
-  并行派发：为 Li 中每个 issue 启动一个子代理（single 模式，共享 working tree，禁止 parallel tasks 数组；N>1 时串行错峰派发）
-  等待：阻塞直到 Li 全部子代理返回回执卡片
-  验收：编排器按 A3 验收清单逐 issue 验收（只认回执卡片的关键信息 + 抽检验证在最新 HEAD 上执行，不消费全量日志）
-  层收敛验证：验收全通过进入全量验证（完成条件 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
-全部层层收敛通过后进入 A4 全量收敛
-```
-
-- **派发纪律**：与阶段⑤双轴审查一致——逐个 `subagent` 派发，禁止 `parallel tasks` 数组（同因：中文报告截断）。
-- **等待语义**：层内任一子代理失败不取消同层其他子代理；待层内全部返回后统一按 A5 最小重派处理。
-- **冲突判定（Q1/Q2）**：同文件即冲突，以 `HEAD` 已移动（`git log` 已含先完成者 `#NN`）为准判定慢者前后不一致；不在工作区瞬时覆盖时判定。
-- **回合连续性**：编排器在层间不结束回合——一层收敛后立即派发下一层，直到全部层完成或外部阻塞；预告下一层后立即执行。
-- **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` 等（需显式确认）。
-### A3. 子代理契约（单 issue 单代理）
-
-每个子代理是一个**完整的 tdd-implement 单 issue 执行单元**，输入与产出严格界定：
-
-> 编排层为 Feature 层，按 `Blocked by` 分层；每子代理各自治完成完整 tdd-implement 流程，产出独立 commit；禁止跨 issue 改动；输出约束为回执卡片，不透传全量过程日志；主代理验收保证无跨 issue 改动与逐 issue 验收，打回重派直至验收通过才计入层收敛。
+每层内节点互无依赖（但仍串行执行，主代理一次一 issue）；层间有依赖，必须串行。分层结果在编排开始前一次性展示给用户确认（合规交互点），确认后才进入 A2。若两 issue 在阶段②已声明预期改动同一文件，建议追加 `Blocked by` 使其串行（轻提示，不强制）。
 
-- **输入**：
-  - `spec.md`（feature 级共享 spec，若无则以该 issue 正文为准）
-  - 分配的单个 `NN-<slug>.md`（唯一 issue 输入）
-  - `CONTEXT.md` + `docs/adr/`（术语与决策一致性）
-- **执行**：严格走 tdd-implement ①→⑦全流程——①理解需求（读 spec + issue）→ ②确认 seams（该 issue 范围内）→ ③红-绿循环（每 cycle 后 typecheck + 相关测试）→ ④相关测试套件（仅该 issue 相关 + typecheck，不跑全量；全量由编排器在 A2 层收敛/A4 统一执行，单 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 行）：
+### A2. 分层调度（主代理串行）
 
 ```
-[回执] #NN <issue 标题>
-- 提交：<commit hash> — <message>
-- seams：<清单>
-- 测试：相关测试 <数量> 项全绿 / 失败清单（全量由编排器层收敛/A4 验证）
-- typecheck：通过 / 失败原因
-- review：Standards <通过/问题> / Spec <通过/问题>
-- 验收：checkbox <m/n 全绿，缺口说明>
-- 文档：<更新文件 / 无需更新>
-- 遗留：<如有>
+for each 层 Li in L1..Ln:
+  for each issue in Li（按编号顺序）:
+    主代理直接执行该 issue 的完整 ①→⑦：
+      ①理解需求 → ②确认 seams → ③红-绿循环（每 cycle 后 typecheck）→ ④相关测试 → ⑤code-review（双轴，逐 issue）→ ⑥commit-check + 单独 commit → ⑦收尾（Status: resolved + ## 实施总结 + map.md 指针如为 wayfinder 产物 + 目录卫生）
+    产回执卡片（改动文件/测试结果/commit hash）并回写该 issue 文件后**强制更新 `progress.md` 该行**（`Status`/`Commit`/`Review`/`Tests`）后再取下一 issue
+  层收敛：该层全部 issue `Status: resolved` 且 `progress.md` 同步为 `done`、各自独立 commit 已落盘、相关测试通过、`git status` 卫生、历史校验通过，才进下一层
+全部层串行完成后进入 A4
 ```
 
-卡片字段缺一不可；缺失字段视为验收不通过。详细过程与证据留在子代理的 commit 与 issue 文件中，编排器按需抽检而非全量消费。
-
-#### 主代理验收（编排器逐 issue 验收）
-
-编排器收到回执后逐 issue 验收，不盲信子代理自检：
+- **回合连续性**：主代理在层内/层间不结束回合——一 issue 提交后立即取下一 issue，直到全部层完成或外部阻塞；预告下一 issue 后立即执行。
+- **Git 历史保护**：进入 A2 前记录 `BASE_HEAD=$(git rev-parse HEAD)`，每 issue 提交前校验 `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` 等。
+- **Chunking**：每 issue 产回执卡片并回写后再继续，防单回合截断。
 
-1. **落盘校验**：`git log --oneline` 含该 commit 且 message 含 `#NN`；issue 文件 `Status: resolved` 且底部 `## 实施总结` 已落盘。**完成条件：5 项检查表，全部通过才计入层收敛，任一不过即打回重派**（详见 `SKILL.md` 主代理验收）。
-2. **抽检验证**：抽跑该 issue 相关测试（或 `tsc --noEmit` 抽检），不重跑全量套件；抽检失败即打回。
-3. **改动边界**：`git diff <base>..HEAD --name-only` 核对无跨 issue 文件改动；有跨改视为不通过。
-4. **卫生**：`git status` 无 `[DEBUG-...]` 残留与未跟踪临时文件。
-5. **提交关联**：`git log` message 含 `#NN` 且与落盘 commit 一致；缺失或不一致视为不通过。
+### A3. 层收敛
 
-任一项不通过 → 打回重派该子代理（仅该 issue），层内其他已通过不受影响；验收通过才计入层收敛。验收结论随层收敛一并输出。
+每层全部 issue 串行完成后，主代理执行层收敛 4 项（全部通过才进下一层）：
+1. 该层全部 issue `Status: resolved` 且 `## 实施总结` 已落盘且 `progress.md` 同步为 `done`
+2. 相关测试通过（该层 issue 相关；全量仅在 A4）
+3. `git status` 卫生（仅删本次临时产物）
+4. 历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过
 
-子代理内部的回合连续性、任务分解、Todo 规定、Git 历史保护与单线模式完全一致（见 [stages.md 阶段③ 3e/3f/3h](stages.md#阶段-③tdd-开发循环) 与 Git 安全前置）。子代理同样在入口记录 `BASE_HEAD` 并在每阶段出口校验 `git merge-base --is-ancestor $BASE_HEAD HEAD`，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
+任一失败定位到该层失败 issue，重做该 issue 的失败 seam/阶段后重检该层。
 
 ### A4. 全量收敛
 
-全部层逐 issue 验收通过后，编排器执行：
-
-1. **全量测试套件**：跑仓库完整测试套件（所有 issue 执行完毕后的唯一全量，阶段④与 A2 已改为相关，仅此一次）
-2. **历史校验**：执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明编排过程中历史被改写，立即经 `git reflog` 恢复后重跑收敛。
-3. **目录卫生**：`git status` 确认无 `[DEBUG-...]` 残留、无未跟踪临时文件；有残留则仅删本次临时产物后重检，禁止 `git reset --hard`/`git checkout .`/`git clean -fd`/`git stash push --include-untracked` 等。
-4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件，不透传子代理全量日志（各 issue 的 `## 实施总结` 已落盘，详查落盘文件）。
-
-### A5. 回退与冲突
-
-- **子代理内回退（最小单元）**：按 [stages.md 回退路由](stages.md#回退路由) 精确回退——`typecheck 失败→③`、`测试失败→③`、`review Standards 味→⑤重构`、`review Spec 偏离→①`、`review seams 遗漏→②补 seams`、`commit-check 文档/卫生/message 失败→⑥/⑦ 对应阶段`。失败点之前的已 `done` seam/Todo 永不回退，仅重跑失败阶段及下游；`seams 清单` 与已绿 seam 默认复用，仅 `seams 遗漏/需求偏差` 两类才回到 `②/①` 重确认。
-- **层收敛失败（最小重派）**：层内任一子代理未达到 `resolved`（含验收 5 项、相关测试、卫生、历史校验任一不过）→ 该 issue 保持原 `Status`，编排器在层等待结束后报告失败清单，不自动进入下一层；待修复后仅重派失败节点，同层其他已通过不受影响。层原子语义保持：`Li` 未全 `resolved` 不派 `L_{i+1}`。
-- **全量收敛失败（精确定位）**：A4 全量测试失败 → 以测试文件路径/报错栈精确定位到单 issue 单 seam，回到其所在层仅重派该 issue 的失败 seam + 相关测试，全量由编排器在重派后再次 A4 统一验证；无法精确定位时退化到层级重派，不重跑无关联 issue。
-- **文件冲突（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` 已移动）为准，编排器不做静态文件监听预判。
-- **环依赖**：A0 检测到环即报错终止，不派发任何子代理。
+全部层串行完成且各自层收敛通过后，执行：
+1. **全量测试套件**：跑仓库完整测试套件（仅此一次全量）
+2. **历史校验**：`git merge-base --is-ancestor $BASE_HEAD HEAD`，失败即 `reflog` 恢复后重跑
+3. **目录卫生**：`git status` 无 `[DEBUG-...]` 残留、无未跟踪临时文件
+4. **汇总总结**：在会话输出汇总各 issue 的回执卡片关键信息（提交 hash / seams / 验收 checkbox / 测试结果 / 文档对齐）；不另写汇总文件
 
 ### 出口条件
 
-- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘
+- 全部 issue `Status: resolved` + 各自 `## 实施总结` 已落盘且 `progress.md` 同步为 `done`
 - 全量测试套件通过
-- 工作区干净（`git status` 无残留）
+- 工作区干净且 `progress.md` 与 `issues/*.md` 一致（不一致时以 `issues/*.md` 为准，`progress.md` 为派生可重算）
 
 ### 边界
 
-- 单 issue / 单 spec 不走本文件；但一旦进入编排模式（多 issue 且含 Blocked by），无论 N==1 还是 N>1，所有 issue 的 ①→⑦ 必须经子代理 single 派发完成，禁止主会话直做（编排器仅编排、验收、归集、清理）
-- 子代理不跨 issue 改动；编排器不替子代理写实现代码；主会话不直接写业务代码/测试/文档（仅做编排与验收）
+- 单 issue / 单 spec 不走本文件编排，但一旦进入多 issue 编排（多 `task`），所有 issue 的 ①→⑦ 均由主代理串行直接执行，禁止子代理派发
+- 不跨 issue 改动；主代理按层串行，一次一 issue 一 commit
 - 汇总总结只在对话输出，不落盘额外汇总文件
-- 必须先编排子代理计划（输出依赖图/DAG/Kahn 分层 `L1..Ln` 并确认）后才派子代理，禁止跳过计划直接派发导致重复调度
+- 必须先输出依赖图/DAG 与 Kahn 分层 `L1..Ln` 并确认后才进入 A2，禁止跳过计划直接执行导致乱序
 - TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在本文件重写
-

package/.agents/skills/tdd-implement/references/stages.md

@@ -1,7 +1,6 @@
 # 阶段详细定义
 
-单线 ①→⑦ 的详细定义；多 issue 编排主过程见 [SKILL.md](../SKILL.md#多-issue-编排按依赖分层并行)，详规见 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
-
+单 `spec` / 单 `task` 与多 `task`（按 `Blocked by` 依赖分层串行、主代理直接执行）共用下表 ①→⑦；多 issue 编排（A0-A1 排序 + 主代理串行）见 [SKILL.md](../SKILL.md) 与 [orchestration.md](orchestration.md)。TDD 语义以 [tdd 技能](.agents/skills/tdd/SKILL.md) 为唯一事实源，不在此重写。
 ## 目录
 
 - [阶段 ①：理解需求](#阶段-①理解需求)
@@ -20,11 +19,11 @@
 
 ### 入口条件
 
-- 用户提供了 spec 或一组 ticket
+- 用户提供了单 `spec` 文件（`.scratch/<feature>/spec.md` 或等价）或一个 `Type: task` 的 ticket（`wayfinder`/`to-tickets` 产出，含 `Blocked by`/`Status`）；`Type: research/prototype/grilling` 分流至对应技能，不进本技能
 
 ### 操作
 
-1. 完整读取 spec/ticket 内容
+1. 完整读取入口（`spec` 或 `issue`）内容
 2. 若存在 `CONTEXT.md` 和 `docs/adr/`，先阅读，确保术语和 ADR 决策不被违背
 3. 如有歧义，先向用户澄清再继续
 
@@ -35,8 +34,8 @@
 
 ### 边界
 
-
----
+- `CONTEXT` 术语冲突时以 `CONTEXT` 为准，必要时先 `domain-modeling` 纠偏
+- 单 `spec` 与单 `task` 同构，均走 ①→⑦；多 `task` 由 [orchestration.md](orchestration.md) A0-A1 排序后主代理串行，不经子代理
 
 ## 阶段 ②：确认 Seams（测试接缝）
 
@@ -140,7 +139,7 @@
 
 ### 操作
 
-1. 运行仓库的完整测试套件（单线模式的唯一全量；多 issue 子代理此步仅相关，全量由 A4 统一执行）
+1. 运行仓库的完整测试套件（仅该 issue 相关 + typecheck 已在阶段③完成，全量由多 issue 时的 A4 统一执行；单 issue / 单 spec 场景此步即全量）
 2. 检查所有测试是否通过
 
 ### 出口条件
@@ -148,7 +147,6 @@
 - 全部测试通过
 
 ### 边界
-
 - 测试失败时回到阶段 ③ 修复，修复后重新运行完整套件——进入 review 前必须全绿
 
 ---
@@ -161,11 +159,11 @@
 
 ### 操作
 
-1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前所有改动：
+1. 调用 [code-review 技能](.agents/skills/code-review/SKILL.md) 按**双轴**审查当前 issue 的改动：
    - **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]`）。需要更完整输出时，要求子代理把报告写入临时文件，主代理再读取
+2. **逐 issue 触发**：每 issue 绿后即审查，未通过则当 issue 打回重做（→③/②/①），不进入下一 issue
 3. 审查发现的问题按 [回退路由](#回退路由) 处理
 
 ### 出口条件
@@ -178,8 +176,6 @@
 - review 通过后才进入 commit
 - 审查结果只在对话输出，不生成书面审查报告（不落盘 `review-*.md` 类文件）
 
----
-
 ## 阶段 ⑥：Commit
 
 ### 入口条件
@@ -190,7 +186,7 @@
 
 1. 调用 [commit-check 技能](.agents/skills/commit-check/SKILL.md) 执行提交门禁——四项检查：①审查文档 ②对齐 README ③保持目录卫生 ④规范 commit message
 2. **历史校验**：commit 前执行 `git merge-base --is-ancestor $BASE_HEAD HEAD`，若为 false 说明历史被改写，立即经 `git reflog` 恢复 `BASE_HEAD` 后的提交，校验通过才继续
-3. 四项**全部通过才 commit**（含历史校验 `git merge-base --is-ancestor $BASE_HEAD HEAD` 通过）：将工作提交到当前分支，附清晰的 commit message
+3. 四项**全部通过才 commit**（含历史校验通过）：将工作提交到当前分支，附清晰的 commit message（单 issue 单提交，如 `feat(<feature>): <issue title> (#NN)`）；多 issue 时每 issue 独立提交后才取下一 issue
 
 ### 出口条件
 
@@ -199,8 +195,7 @@
 ### 边界
 
 - Commit message 格式与内容由 commit-check ④ 把关（描述变更内容而非过程）
-
----
+- 每 issue 独立提交，主代理串行时一 issue 一 commit 后再进入下一 issue 的 ①
 
 ## 阶段 ⑦：收尾（文档对齐 + issue 状态 + 实施总结）
 
@@ -225,9 +220,9 @@
    - 文档对齐：<更新了哪些文件 / 无需更新>
    - 遗留 / 后续建议：<如有>
    ```
-
-5. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
-6. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。Git 历史保护与禁令见本文件阶段③ [Git 安全前置](#git-安全前置历史保护)与 `docs/agents/skill-design.md` Rule 4，仅删本次临时产物，禁止为达干净而执行 git 层破坏性命令。
+5. **强制更新 `progress.md`**：在 `.scratch/<feature>/progress.md` 更新该 `NN` 行的 `Status`/`Commit`/`Review`/`Tests`（派生视图，真相源仍为 `issues/*.md`）
+6. 无关联 issue（直接实现用户给的 spec）→ 跳过状态更新，将总结作为会话最终输出
+7. **保持目录卫生**：仅清理本次实现产生的临时产物——`[DEBUG-...]` 标记的调试代码/日志、一次性脚本、临时文件与备份文件；用 `git status` 确认工作区只含预期改动，无残留未跟踪文件后才结束。Git 历史保护与禁令见本文件阶段③ [Git 安全前置](#git-安全前置历史保护)与 `docs/agents/skill-design.md` Rule 4，仅删本次临时产物，禁止为达干净而执行 git 层破坏性命令。
 
 ### 出口条件
 
@@ -246,7 +241,7 @@
 
 ## Todo 规定
 
-本节复用 `tdd`/`implement` 的 Todo 规定，`tdd-implement` 仅做多 issue 编排与串联，不再重写层次细节。
+本节复用 `tdd`/`implement` 的 Todo 规定，`tdd-implement` 仅做多 issue 串行（主代理按依赖顺序）与单 issue 闭环，不再重写层次细节。
 
 ### 拆分层级（大小任务层次）
 
@@ -255,7 +250,7 @@
 3. **小任务**：Todo——seam 内可独立验证、可勾选的执行单元（T1/T2/T3…）
 4. **执行步**：Subtodo——Todo 内的串行步骤（红 → 绿 → typecheck），回合内逐步勾选推进
 
-> 编排模式新增一层见 [SKILL.md](../SKILL.md#多-issue-编排按依赖分层并行) 主过程与 [orchestration.md](orchestration.md) 详规：**编排层** Feature——`.scratch/<feature>/` 下全部 issues，按 `Blocked by` 分层；每层一组并行子代理，每子代理一个 issue 的完整 ①→⑦。
+> 多 issue（串行）新增一层见 [SKILL.md](../SKILL.md#多-issue-编排按依赖串行主代理直接执行) 与 [orchestration.md](orchestration.md)：**编排层** Feature——`.scratch/<feature>/` 下全部 issues，按 `Blocked by` 分层；主代理按层串行、层内亦串行，每 issue 完整 ①→⑦ 并单独提交。
 
 ### Todo 清单格式
 
@@ -267,7 +262,7 @@
 - 完成标准（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 清单为**分层清单**：`L1: [01, 02] → L2: [03, 04] → L3: [05]`，每层按依赖串行（不再并行）；每 issue 的 DoD 为 `Status: resolved` + 独立 commit + 实施总结已落盘。
 
 ### Todo 状态机
 
@@ -277,7 +272,7 @@ pending → in-progress → done
 ```
 
 - Subtodo 不单独设 `blocked`——阻塞状态归父 Todo，Subtodo 跟随父状态
-- 编排模式下 issue 粒度状态机：`pending → in-progress(子代理已派发) → done(Status: resolved)`；`blocked` 表示 `Blocked by` 依赖未满足，待前层全 `resolved` 后自动解阻。
+- 编排模式下 issue 粒度状态机：`pending → in-progress(主代理执行中) → done(Status: resolved)`；`blocked` 表示 `Blocked by` 依赖未满足，待前层全 `resolved` 后自动解阻。
 
 ### 粒度与回合归属
 
@@ -287,13 +282,13 @@ pending → in-progress → done
 - 每完成一个 todo 立即更新其状态，再进入下一个
 - todo 状态只按实际推进更新（pending → in-progress → done），不基于旧快照重写整个清单；已完成项（done）永不回退
 - 全部 todo 为 done 才进入阶段④
-- 编排模式下：每层全部 issue `done` 才进入下一层；全部层 `done` 后编排器做全量收敛验证。
+- 编排模式下：前层全部 issue `done` 才进入下一层；全部层 `done` 后执行全量收敛（A4）。
 
 ### 阻塞处理
 
 - 外部阻塞（权限拒绝、缺失授权、依赖不可用）→ 标记 `blocked`，记录所需授权或替代路径
 - 不静默停止；恢复后回到 `in-progress` 继续
-- 编排模式下：`Blocked by` 依赖阻塞由编排器自动管理——前层未全 `resolved` 时后层 `blocked`，前层收敛后自动解阻派发；不需人工确认依赖满足。
+- 编排模式下：`Blocked by` 依赖阻塞由主代理按层自动管理——前层未全 `resolved` 时后层 `blocked`，前层提交后自动解阻；不需人工确认依赖满足。
 
 ---
 
@@ -307,5 +302,4 @@ pending → in-progress → done
 | ⑤ Code Review | seams 遗漏 | → ② 补充 seams |
 | ⑤ Code Review | 需求偏差 | → ① 澄清需求 |
 
-编排模式回退主过程见 [SKILL.md](../SKILL.md#多-issue-编排按依赖分层并行) A5，详规见 [orchestration.md#A5](orchestration.md#a5-回退与冲突)：子代理内回退按上表在子代理内闭环；编排器层收敛失败（全量测试失败 / 目录不干净）→ 定位到失败 issue 所在层重派对应子代理。
-
+编排模式回退见 [orchestration.md](orchestration.md)：单 issue 内回退按上表在当 issue 内闭环；层收敛/全量失败定位到失败 issue 所在层重做该 issue 的失败 seam。

package/README.md

@@ -8,7 +8,7 @@ mattpocock/skills（`skills/engineering` + `skills/productivity`）的配置仓
 template/
 ├── AGENTS.md         项目级全局配置（行为路由 + 分文件指针）
 ├── .agents/
-│   └── skills/       32 个技能（上游 26 + 独有 6：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test）单一源；模板全量 32，默认安装仅编程相关 22（engineering 18 + 核心独有 4，见 config/engineering.json），--all 展开全量
+│   └── skills/       33 个技能（上游 26 + 独有 6：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test；另含 show-me）单一源；模板全量 33，默认安装编程相关 26（engineering 18 + 独有所需 1 + 核心独有 4，见 config/engineering.json 与 config/required.json），--all 展开全量
 ├── .pi/              pi-agent 项目配置
 │   ├── skills/       空占位（项目自定义技能，含 .gitkeep + README.md）
 │   ├── prompts/      issue-audit 命令（prompt template）
@@ -29,27 +29,24 @@ template/
 在目标仓库根目录执行一条命令：
 
 ```sh
-npx @heihei0299/matt-skills init              # 默认仅编程相关 21（engineering + 独有），--all 展开全量 32
-npx @heihei0299/matt-skills init --all       # 安装全量 32（含 productivity）
+npx @heihei0299/matt-skills init              # 默认编程相关 26（engineering 18 + 独有所需 4 + 核心独有 4），--all 展开全量 33
+npx @heihei0299/matt-skills init --all       # 安装全量 33（含 productivity）
 ```
 
-`init` 做一件事：复制 `template/` 快照（`AGENTS.md`、`.agents/skills/`、`.opencode/`、`.pi/`）到当前目录；模板全量 32，默认仅安装编程相关 24（上游 engineering 桶，见 config/engineering.json + 独有 6），`--all` 展开全量，无需二次拉取上游。
+`init` 做一件事：复制 `template/` 快照（`AGENTS.md`、`.agents/skills/`、`.opencode/`、`.pi/`）到当前目录；模板全量 33，默认仅安装默认范围 26（engineering 18 + 独有所需 4 + 核心独有 4，见 config/engineering.json 与 config/required.json），`--all` 展开全量，无需二次拉取上游。
 
-选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程技能（productivity，默认仅编程）。
+选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含非编程技能（productivity，默认编程 26：engineering 18 + 独有所需 4 + 核心独有 4）（默认跳过已存在）。
 **增量同步（已有项目）**：已有项目更新到最新模板与技能：
 
 ```sh
-npx @heihei0299/matt-skills sync                                 # 默认仅对比不写盘（check），有差异 exit 1，--json 可解析（仅编程）
-npx @heihei0299/matt-skills sync --all --json                  # 全量对比
-npx @heihei0299/matt-skills sync --apply                         # 安全增量：AGENTS.md 定制跳过，编程技能 rm+cp，不删多余 productivity（默认保留）
-npx @heihei0299/matt-skills sync --apply --all                  # 安全增量全量
-npx @heihei0299/matt-skills sync --force                         # 硬盖编程：AGENTS.md 备份后硬盖，编程技能全量 add/update/remove（含 productivity 删除与旧镜像清理）
-npx @heihei0299/matt-skills sync --force --all                  # 硬盖全量
-npx @heihei0299/matt-skills sync --apply --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
+npx @heihei0299/matt-skills sync                                 # 默认安全增量：AGENTS.md 有定制则跳过，默认技能 26 rm+cp（不删多余）
+npx @heihei0299/matt-skills sync --all                           # 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 AGENTS.md（不跳过定制），不删多余
+npx @heihei0299/matt-skills sync --dry-run --json                # 预演：只比对不写盘（默认范围，--all 全量可透传）
+npx @heihei0299/matt-skills sync --dest <path> --upstream <url> --ref <ref> --json  # 选项可组合
 ```
 
-`sync` 专为已有项目设计，三档语义：默认 `check` 仅对比不写盘（仅编程，`--all` 展开全量，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；`--apply` 安全增量写盘（编程模式：`AGENTS.md` 若含独有路由如 `tdd-implement` 则跳过，`.agents/skills` 按编程子集 `rm+cp force` 覆盖但不 `remove` 多余 productivity，`template/.agents/.opencode/.pi` 按过滤增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留的共享技能自动清理但保留项目自定义；`--all` 则全量）；`--force` 硬盖（编程模式：`AGENTS.md` 备份 `.bak` 后强制覆盖，编程技能 `add/update/remove` 全做（含 productivity 删除与旧镜像清理）；`--all` 则全量硬盖）。`--dest`、`--upstream`、`--ref`、`--json`、`--all` 在三档均可透传。
-目标仓库会话即自动加载共享技能（`.agents/skills/` 单一源，默认编程 22，`--all` 全量 32）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
+`sync` 专为已有项目设计，两档语义：`--dry-run` 仅对比不写盘（默认范围 engineering + 独有所需，`--all` 展开全量同名集合，打印“上游 HEAD / 本地非独有 vs 上游 / 新增/更新/删除/一致”表，`--json` 可解析，有差异 `exit 1`）；默认安全增量写盘（`AGENTS.md` 若含 `tdd-implement` 则跳过，`.agents/skills` 按默认范围 26 `rm+cp` 覆盖但不删多余，`template/.opencode/.pi` 增量 `add/update`，旧镜像 `.pi/skills` + `.opencode/skills` 中残留共享技能自动清理但保留项目自定义）；`--all` 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余。`--dest`、`--upstream`、`--ref`、`--json`、`--all`、`--dry-run` 可透传。
+目标仓库会话即自动加载共享技能（`.agents/skills/` 单一源，默认编程 26，`--all` 全量 33）与项目级全局配置（行为路由表、分文件约定）；项目自定义技能可按需放入 `.pi/skills/` 或 `.opencode/skills/`（按 harness 自动发现）；`issue-audit` 以子代理 + 命令形式分发（`.opencode/agents/`、`.opencode/commands/`）；9 个显式触发技能注册为 opencode 命令（`.opencode/commands/`，`/命令名` 触发）。
 **pi-agent 用户**：初始化命令完全相同。pi 从 `.agents/skills/` 自动发现全部共享技能，无需额外指向；`.pi/skills/` 仅用于项目自定义。首次在目标仓库交互启动时 pi 会询问项目信任，用 `/trust` 保存即可。
 
 **手动方式（备选）**：无 npx 环境时，将 `template/` 整个文件夹复制到目标仓库根目录即可（已含全量技能）：
@@ -70,7 +67,7 @@ git clone --depth 1 https://github.com/mattpocock/skills.git /tmp/mattpocock-ski
 
 | 工作区 | 模板 |
 |--------|------|
-| `.agents/skills/`（全部 32 个：上游 26 + 独有 6） | `template/.agents/skills/`（全量快照，单一源） |
+| `.agents/skills/`（全部 33 个：上游 26 + 独有 7：ci-guard、tdd-implement、grill-to-spec、diagnose-fix、commit-check、scaffold-functional-test、show-me） | `template/.agents/skills/`（全量快照，单一源） |
 | `.agents/skills/` 的 harness 占位说明 | `template/.pi/skills/.gitkeep` + `README.md`、`template/.opencode/skills/.gitkeep` + `README.md`（空目录占位，供项目自定义） |
 | `.opencode/agents/issue-audit.md`、`commands/*.md`（issue-audit + 9 个显式技能命令）、`.gitignore`、`package.json`、`package-lock.json` | `template/.opencode/` 同名 |
 | `.pi/prompts/issue-audit.md`（pi 命令：opencode 版适配，去 subagent frontmatter） | `template/.pi/prompts/issue-audit.md` |
@@ -103,13 +100,13 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 
 - **全局**：`~/.pi/agent/skills/`、`~/.agents/skills/`（用户级技能，自动发现）；配置在 `~/.pi/agent/settings.json`
 - **项目**：
-  - `.agents/skills/` — 共享技能单一源（默认编程 22，`--all` 全量 32，自动发现）
+  - `.agents/skills/` — 共享技能单一源（默认编程 26，`--all` 全量 32，自动发现）
   - `.pi/skills/` — 项目自定义技能（pi 标准结构，自动发现，仅放项目本地技能）
   - `.pi/prompts/` — pi 命令（prompt template）自动发现，如 `issue-audit.md` → `/issue-audit`
   - `.pi/settings.json` — 已简化为空对象（历史指向 `.opencode/skills` 已移除，共享技能走 `.agents/skills`）
 ### opencode
 
-- **项目**：`.agents/skills/`（共享技能单一源，默认编程 22，`--all` 全量 32）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 9 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
+- **项目**：`.agents/skills/`（共享技能单一源，默认编程 26，`--all` 全量 33）、`.opencode/skills/`（项目自定义技能）、`.opencode/agents/`（子代理）、`.opencode/commands/`（命令：issue-audit + 9 个显式触发技能，`/命令名` 触发）、`.opencode/docs/`（文档）
 
 同一份技能（Agent Skills 标准）与 `AGENTS.md` 行为路由在两种 harness 下均可加载：pi 与 codex/claude 从 `.agents/skills/` 自动发现；opencode 按本模板约定同样优先读取 `.agents/skills/`（`.opencode/skills/` 仅用于项目自定义）。
 
@@ -118,42 +115,40 @@ pi 下对应能力以内置工具或已装扩展为准（`AGENTS.md`「能力边
 仓库内提供安装管理 CLI（`bin/cli.js`，依赖 `prompts`，见 `package.json`），同时作为 npm 包 `@heihei0299/matt-skills` 分发（`npx @heihei0299/matt-skills <command>`）：
 
 ```sh
-node bin/cli.js init [--dest <dir>] [--force] [--all]                               # 初始化项目：template 全量 32，默认编程 22
-node bin/cli.js sync [--apply|--force] [--all] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新（默认编程）
+node bin/cli.js init [--dest <dir>] [--all]                               # 初始化项目：template 全量 33，默认编程 26
+node bin/cli.js sync [--all] [--dry-run] [--dest <path>] [--upstream <url>] [--ref <ref>] [--json]  # 同步已有项目到最新（默认编程，--all 仅同名 upsert + AGENTS.md）
 node bin/cli.js list [--json] [--all]                                            # 列出技能（默认编程）
 node bin/cli.js install [选项]                                                 # 把技能复制到目标工具目录（交互式选择，默认编程）
-node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]          # 只读检查上游技能是否最新（等价 sync 默认，仅编程）
+node bin/cli.js check [--json] [--all] [--upstream <url>] [--ref <ref>]          # 只读检查上游技能是否最新（等价 sync --dry-run，默认范围）
 ```
 
-`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--force` 覆盖已存在的文件（直接覆盖，`AGENTS.md` 会备份到 `.bak`）（默认跳过）；`--all` 包含非编程（productivity，默认仅编程 22），见「初始化」。
-`sync` 选项：`--apply` 安全增量（编程默认：`AGENTS.md` 定制跳过、编程技能不删 productivity，旧镜像清理保留项目自定义；`--all` 全量），`--force` 硬盖（编程默认：`AGENTS.md` 备份后硬盖、编程技能与模板全量 `remove` 含 productivity 删除与旧镜像清理；`--all` 全量）；`--all` 展开全量；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认无参等价 `check` 仅对比不写盘（仅编程，`--all` 全量），`--json` 可解析，有差异 `exit 1`。
-`check` 选项：`--json`、`--all`（默认仅编程）、`--upstream <url>`、`--ref <ref>`（等价 `sync` 默认 `check`）。
+`init` 选项：`--dest <path>` 指定目标目录（默认当前目录）；`--all` 包含非编程（productivity，默认编程 26：engineering 18 + 独有所需 1 + 核心独有 4），见「初始化」。
+`sync` 选项：`--all` 仅更新同名技能内容（存在则覆盖，不存在则新增）并更新 `AGENTS.md`（不跳过定制），不删多余；`--dry-run` 预演（只比对不写盘，`--json` 可解析，有差异 `exit 1`）；`--all` 展开同名全量；`--dest <path>` 目标目录；`--upstream <url>` 上游地址；`--ref <ref>` 上游分支；`--json` JSON 输出；默认即安全增量（`AGENTS.md` 有定制则跳过）。
+`check` 选项：`--json`、`--all`（默认范围：engineering + 独有所需）、`--upstream <url>`、`--ref <ref>`（等价 `sync --dry-run`）。
 
 `install` 选项：
 
 - `--dest <dir>`：复制到指定目录（覆盖工具映射）
 - `--tools <t1,t2>`：指定工具，项目级已统一 `codex/pi/opencode/claude → .agents/skills`（共享技能单一源，`.pi/skills`/`.opencode/skills` 仅用于项目自定义）
 - `--global`：安装到全局目录（`~/.codex/skills`、`~/.pi/agent/skills`、`~/.config/opencode/skills`、`~/.claude/skills`）；`--project` 回到项目级
-- `--all`：安装全部技能（默认仅编程 22，`--all` 32，交互勾选时仅列编程）；`--force`：覆盖已存在的技能
+- `--all`：安装全部技能（默认编程 26，`--all` 33，交互勾选时仅列默认范围）；`--force`：覆盖已存在的技能
 
 
 ### 上游同步（自动更新）
 
 本仓库的 `.agents/skills/` 中 **非独有技能** 来自 `mattpocock/skills` 上游。已实现双通道自动同步：
 
-- **本地 CLI**：`matt-skills sync` 三档——默认 `check` 只读比对（等价 `matt-skills check`，有差异 `exit 1`，`--json` 可解析）、`matt-skills sync --apply` 安全增量、`matt-skills sync --force` 硬盖；`matt-skills check [--json] [--upstream <url>] [--ref <ref>]` 仍保留为只读别名；`matt-skills update` 已合并到 `sync --apply`（执行提示 `update 已合并到 sync --apply` 且 `exit 1`）
-- **GitHub Actions**：`.github/workflows/sync-upstream.yml` 每周一 02:00 UTC 自动 `check`，有差异则 `apply` 并提 PR（`upstream-sync/<short-sha>`），支持 `workflow_dispatch` 手动触发（`ref`/`dry_run` 参数）
-
+- **本地 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`）
 ```sh
-npx @heihei0299/matt-skills sync --json              # 默认 check 只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
-npx @heihei0299/matt-skills sync --apply             # 安全增量写盘
-npx @heihei0299/matt-skills sync --force             # 硬盖写盘
-npx @heihei0299/matt-skills check --json             # 等价 sync 默认 check
+npx @heihei0299/matt-skills sync --dry-run --json              # 预演只读检查，JSON 输出：{ head, counts, result: { added, updated, renamed, removed, same } }
+npx @heihei0299/matt-skills sync                               # 默认安全增量（AGENTS.md 定制跳过，默认技能 26）
+npx @heihei0299/matt-skills sync --all                         # 仅同名 upsert + AGENTS.md
+npx @heihei0299/matt-skills check --json             # 等价 sync --dry-run
 node scripts/sync-upstream.js --check               # 等价底层脚本（CLI sync/check 的实现）
 node scripts/sync-upstream.js --apply --dry-run
 ```
 
-实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单 + `config/engineering.json` 为编程白名单（engineering 桶即编程，productivity 默认不装，`--all` 展开），上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
+实现细节：`scripts/sync-upstream.js` 为单一事实源（CLI 与 Actions 共用），以 `config/proprietary.json` 为独有白名单 + `config/engineering.json` 为编程白名单 + `config/required.json` 为独有所需白名单（当前仅 grilling：grill-to-spec 经 grill-with-docs 所需，属 productivity 但默认同步；其余 productivity 默认不装，`--all` 展开），上游通过 `git clone --depth 1 https://github.com/mattpocock/skills.git` 获取，比对 `SKILL.md` 的 sha256，自动处理新增/更新/重命名/删除；Actions 提 PR 后需人工合入，合入后按“发布”节打 `v*` 标签即发布（自动 patch 发版可在后续扩展为 PR 合入后自动 bump）。
 上游重命名映射：`RENAMES = { "writing-great-skills": "writing-for-agents" }`，Actions/CLI 均会删除旧目录并复制新目录。
 ## 发布
 
@@ -186,7 +181,7 @@ npm publish
 
 ```sh
 npm test                          # 全量测试
-npm run build:template            # 从单源生成 template/.agents/skills（全量 32 技能）+ 空占位
+npm run build:template            # 从单源生成 template/.agents/skills（全量 33 技能）+ 空占位
 ```
 
 交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`、`test/cli-init.test.js`、`test/template-sync.test.js`。