@namewta/speculo 0.1.21 → 0.2.0

package/template/skills/worktree-isolation/references/merge-and-cleanup.md

@@ -1,6 +1,6 @@
 # 合并回收与清理
 
-finalize 验证通过后，把 change 分支合并回原分支并清理 worktree。调用方：`dev/04` finalize 的 Merge Back & Cleanup 阶段（条件）。**全程破坏性，须先列计划、经用户确认。**
+finalize 验证通过后，把 change 分支合并回原分支并清理 worktree。由 `../../../commands/finalize.md` 在隔离模式下调用。**全程破坏性，须先列计划、经用户确认。**
 
 ## 前置
 
@@ -15,16 +15,16 @@ finalize 验证通过后，把 change 分支合并回原分支并清理 worktree
 
    ```bash
    git switch <base_branch>
-   git merge --no-ff speculo/<cat>/<change>
+   git merge --no-ff speculo/<workflow>/<change>
    ```
 
    - 合并冲突 → **停止**，报告冲突文件，交回用户解决，不强推、不 `--force`。
-   - 合并成功 → 置 `worktree_status: merged`。合并后 base 分支已包含代码与 `speculo/.speculo/<cat>/<change>/` 产物。
+   - 合并成功 → 置 `worktree_status: merged`。合并后 base 分支已包含代码与 `speculo/.speculo/<workflow>/changes/<change>/` 产物。
 3. **清理工作树与分支**：
 
    ```bash
    git worktree remove .worktree/<change>
-   git branch -d speculo/<cat>/<change>
+   git branch -d speculo/<workflow>/<change>
    ```
 
    - 完成后置 `worktree_status: removed`。
@@ -40,4 +40,4 @@ finalize 验证通过后，把 change 分支合并回原分支并清理 worktree
 
 - `verification_status` 非 `verified` 不合并。
 - 未获用户确认不执行任何合并 / 删除 / 移除。
-- 不自行选择持久化目录；`worktree_status` 由调用方写入 `speculo/.speculo/<cat>/<change>/.status.json`。
+- 不自行选择持久化目录；`worktree_status` 由调用方写入 `speculo/.speculo/<workflow>/changes/<change>/.status.json`。

package/template/vendor/README.md

@@ -1,6 +1,6 @@
 # Vendor — 原生 AgentSkills 收集目录
 
-本目录用于收集来自各处的**原生 AgentSkills**，原样保存、不做 Speculo 化改造。
+本目录用于收集来自各处的**原生 AgentSkills**，原样保存、不做 Speculo 化改造。Speculo 的组合、路径适配和持久化规则位于 workflow 包，不写回 vendor。
 
 ## 与 `skills/` 的区别
 
@@ -9,12 +9,15 @@
 | 来源 | Speculo 官方出品 | 第三方搜集收录 |
 | 格式 | 遵循 Speculo frontmatter 契约 | 保持原始格式，不做修改 |
 | 结构 | `SKILL.md` + `references/` + `scripts/` | 原样保留原始目录结构 |
-| 更新策略 | `speculo init` 全覆盖刷新 | 增量合并（见下） |
+| 更新策略 | `speculo init` 全覆盖刷新 | 按 workflow 选择并增量合并（见下） |
 
 ## 更新策略
 
-- **`speculo init`（无 `--all`）**：增量合并 —— 只添加 `vendor/` 中尚不存在的技能，已收集的原生技能不受影响
-- **`speculo init --all`**：全覆盖 —— 用当前打包的 `vendor/` 内容完全替换
+- **首次安装**：复制通用 vendor；`matt-pocock/` 仅在选择同名 workflow 时复制。
+- **`speculo init`（无 `--all`）**：只添加缺失 vendor，保留用户已有内容。
+- **`speculo init --all`**：选择全部 workflow，并用当前包中符合选择条件的 vendor 全量刷新。
+
+`vendor/matt-pocock/` 保留上游的领域目录和原生 `SKILL.md`。直接激活 raw skill 不受 Speculo 持久化保证；规范入口是 `../workflows/matt-pocock/WORKFLOW.md`。
 
 ## 如何添加原生技能
 
@@ -23,12 +26,10 @@
 ```text
 speculo/vendor/
 ├── README.md
-├── some-native-skill/
-│   └── SKILL.md
-└── another-skill/
-    ├── SKILL.md
-    └── references/
-        └── guide.md
+└── matt-pocock/
+    ├── engineering/
+    ├── productivity/
+    └── in-progress/
 ```
 
 无需修改内容，无需添加 Speculo frontmatter。

package/template/vendor/matt-pocock/README.md

@@ -0,0 +1,41 @@
+### 工程
+
+我日常编码工作中使用的 skill。
+
+**用户调用**
+
+- [**ask-matt**](./engineering/ask-matt/SKILL.md) — 询问哪个 skill 或工作流适合你的情况。本仓库中用户调用 skill 的路由器。
+- [**grill-with-docs**](./engineering/grill-with-docs/SKILL.md) — 在问答式访谈会话中同时构建项目的领域模型，打磨术语并内联更新 `CONTEXT.md` 和 ADR。
+- [**triage**](./engineering/triage/SKILL.md) — 通过分类角色状态机处理 issues。
+- [**improve-codebase-architecture**](./engineering/improve-codebase-architecture/SKILL.md) — 扫描代码库寻找深化机会，以可视化 HTML 报告呈现，然后深入讨论你选择的任何一个。
+- [**setup-matt-pocock-skills**](./engineering/setup-matt-pocock-skills/SKILL.md) — 为工程 skill 配置此仓库（issue tracker、分类标签、领域文档布局）。在使用其他工程 skill 之前每个仓库运行一次。
+- [**to-spec**](./engineering/to-spec/SKILL.md) — 将当前对话转化为 spec 并发布到 issue tracker。无需访谈——只是综合你已经讨论过的内容。
+- [**to-tickets**](./engineering/to-tickets/SKILL.md) — 将任何计划、spec 或对话分解为一组 tracer-bullet 票据，每个声明其阻塞边界——作为本地文件中的文本写入，或作为真实 tracker 上的原生阻塞链接。
+- [**implement**](./engineering/implement/SKILL.md) — 构建 spec 或票据集描述的工作，在预先约定的 seam 处驱动 `/tdd`，并在提交前以 `/code-review` 收尾。
+- [**wayfinder**](./engineering/wayfinder/SKILL.md) — 规划一大块工作，超过一个 agent 会话所能容纳的量，作为 issue tracker 上的共享调查票据地图——一次解决一个，直到通往目的地的路径清晰。
+
+**模型调用**
+
+- [**prototype**](./engineering/prototype/SKILL.md) — 构建一次性原型来回答设计问题——用于状态/逻辑问题的可运行终端应用，或多种可从同一路由切换的截然不同的 UI 变体。
+- [**diagnosing-bugs**](./engineering/diagnosing-bugs/SKILL.md) — 用于困难 bug 和性能回归的规范化诊断循环：重现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试。
+- [**research**](./engineering/research/SKILL.md) — 针对高可信度的主要来源调查问题，并将发现捕获为仓库中的带引用 Markdown 文件，作为后台 agent 运行。
+- [**tdd**](./engineering/tdd/SKILL.md) — 使用红-绿-重构循环的测试驱动开发。一次一个垂直切片地构建功能或修复 bug。
+- [**domain-modeling**](./engineering/domain-modeling/SKILL.md) — 主动构建和打磨项目的领域模型——对照词汇表挑战术语、用边界场景压力测试、内联更新 `CONTEXT.md` 和 ADR。
+- [**codebase-design**](./engineering/codebase-design/SKILL.md) — 设计深层模块的共享准则和词汇：大量行为放在小接口背后，置于清晰的 seam 处，通过该接口可测试。
+- [**code-review**](./engineering/code-review/SKILL.md) — 从固定点开始的 diff 双轴审查：**标准**（是否遵循仓库的编码标准，加上 Fowler 气味基线？）和 **Spec**（是否忠实实现了原始 issue/PRD？），作为并行子 agent 运行，互不污染。
+
+### 生产力
+
+通用工作流工具，不限于编码。
+
+**用户调用**
+
+- [**grill-me**](./productivity/grill-me/SKILL.md) — 接受对计划或设计 relentless 的访谈，直到决策树的每个分支都被解决。
+- [**handoff**](./productivity/handoff/SKILL.md) — 将当前对话压缩为交接文档，以便另一个 agent 可以继续工作。
+- [**teach**](./productivity/teach/SKILL.md) — 在多个会话中向用户教授新 skill 或概念，使用当前目录作为有状态的教学工作区。
+- [**writing-great-skills**](./productivity/writing-great-skills/SKILL.md) — 编写和编辑 skill 的参考：使 skill 可预测的词汇和原则。
+
+**模型调用**
+
+- [**grilling**](./productivity/grilling/SKILL.md) — relentlessly 访谈用户关于计划或设计，直到决策树的每个分支都被解决。`grill-me` 和 `grill-with-docs` 背后的可复用循环。
+

package/template/vendor/matt-pocock/engineering/README.md

@@ -0,0 +1,28 @@
+# 工程
+
+我日常编码工作中使用的 skill。
+
+## 用户调用
+
+只能由用户输入来访问（`disable-model-invocation: true`）。
+
+- **[ask-matt](./ask-matt/SKILL.md)** — 询问哪个 skill 或工作流适合您的情况。本仓库中用户调用 skill 的路由器。
+- **[grill-with-docs](./grill-with-docs/SKILL.md)** — 在问答会话中同时构建项目的领域模型，打磨术语并内联更新 `CONTEXT.md` 和 ADR。
+- **[triage](./triage/SKILL.md)** — 通过分类角色状态机处理 issues。
+- **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — 扫描代码库寻找深化机会，以可视化 HTML 报告呈现，然后深入讨论您选择的任何一个。
+- **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — 为工程 skill 配置此仓库（issue tracker、分类标签、领域文档布局）。每个仓库运行一次。
+- **[to-spec](./to-spec/SKILL.md)** — 将当前对话转化为 spec 并发布到 issue tracker。
+- **[to-tickets](./to-tickets/SKILL.md)** — 将任何计划、spec 或对话分解为一组 tracer-bullet 票据，每个声明其阻塞边界——本地文件中的文本，或真实 tracker 上的原生阻塞链接。
+- **[wayfinder](./wayfinder/SKILL.md)** — 规划一大块工作——超过一个 agent 会话所能容纳的量——作为 issue tracker 上的共享调查票据地图，一次解决一个，直到通往目的地的路径清晰。
+
+## 模型调用
+
+模型或用户均可访问（丰富的触发措辞使模型能够使用它们）。
+
+- **[prototype](./prototype/SKILL.md)** — 构建一次性原型来回答设计问题：用于状态/逻辑的可运行终端应用，或多种可切换的 UI 变体。
+- **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — 用于困难 bug 和性能回归的规范化诊断循环：重现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试。
+- **[research](./research/SKILL.md)** — 针对高可信度的主要来源调查问题，并将发现捕获为仓库中的带引用的 Markdown 文件，作为后台 agent 运行。
+- **[tdd](./tdd/SKILL.md)** — 使用红-绿-重构循环的测试驱动开发。一次一个垂直切片地构建功能或修复 bug。
+- **[domain-modeling](./domain-modeling/SKILL.md)** — 主动构建和打磨项目的领域模型——挑战术语、用场景压力测试、内联更新 `CONTEXT.md` 和 ADR。
+- **[codebase-design](./codebase-design/SKILL.md)** — 设计深层模块的共享准则和词汇：小接口、清晰缝线、通过接口可测试。
+- **[code-review](./code-review/SKILL.md)** — 从固定点开始的 diff 双轴审查：**标准**（是否遵循仓库的编码标准，加上 Fowler 气味基线？）和 **Spec**（是否忠实地实现了原始 issue/PRD？），作为并行子 agent 运行。

package/template/vendor/matt-pocock/engineering/ask-matt/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ask-matt
+description: 询问哪种技能或流程适合你的情况。本仓库技能的导航器。
+disable-model-invocation: true
+---
+
+# 咨询 Matt
+
+你不需要记住每个技能，直接问就行了。
+
+**流程**是指技能之间的路线。大多数路线沿着一条**主流程**走，两条**入口匝道**汇入其中。其他所有内容要么是独立技能，要么是运行在底层的词汇层。
+
+## 主流程：从想法到交付
+
+大多数工作遵循这条路线。你有一个想法，想要把它构建出来。
+
+1. **`/grill-with-docs`** — 通过访谈打磨想法。当你**已有代码仓**时从这里开始：它是有状态的，会将学到的内容保留在 `CONTEXT.md` 和 ADR 中。（没有代码仓？使用 `/grill-me` — 见独立技能。两者都运行相同的 `/grilling` 原语；`grill-with-docs` 是会留下书面记录的那个。）
+2. **分支 — 你能在对话中解决所有问题吗？** 如果某个问题需要可运行的答案（状态、业务逻辑、必须亲眼看才能确定的 UI），通过原型来绕路，用 **`/handoff`** 在双向桥接（见跨会话）：
+   - **`/handoff`** 传出，然后针对该文件开启一个新会话，
+   - **`/prototype`** 用一次性代码来回答问题，
+   - **`/handoff`** 传回你学到的东西，并在原始想法线程中引用它。
+3. **分支 — 这是一个跨会话的构建吗？**
+   - **是** → **`/to-spec`**（将线程转为规范），然后 **`/to-tickets`** 将其拆分为 tracer-bullet 工单，每个工单声明其**阻塞边界**。在本地追踪器上，这是一个有序的 `tickets.md` 文件，你手动操作；在真正的追踪器上，边界变为原生的阻塞链接，任何阻塞项已完成的工单都可以被领取 — 按工单启动 **`/implement`**，**在每个工单之间清理上下文**。
+   - **否** → 直接在当前上下文窗口中运行 **`/implement`**。
+
+   无论哪种方式，**`/implement`** 在构建每个问题时都内部驱动 **`/tdd`** — 每次一个红-绿切片 — 然后在提交前通过运行 **`/code-review`** 来收尾，这是对 diff 的双轴审查（标准 + 规范）。当你只想先测试一个具体行为而不需要完整规范时，单独使用 **`/tdd`**；当你想针对一个固定点审查分支或 PR 时，单独使用 **`/code-review`**。
+
+### 上下文卫生
+
+将步骤 1-3 保持在**一个不间断的上下文窗口**中 — 在 `/to-tickets` 之前不要压缩或清理 — 这样访谈、规范和工单都建立在相同的思考基础上。然后每个 `/implement` 从工单开始，以全新上下文启动。
+
+此处的限制是**[智能区间](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**：模型在此窗口内（当前最先进模型约 120k token）仍能保持敏锐推理。如果会话在 `/to-tickets` 之前接近这个限制，不要硬撑 — 使用 `/handoff` 并在新线程中继续。
+
+## 入口匝道
+
+产生工作的起始场景，然后汇入主流程。
+
+- **Bug 和请求堆积如山** → **`/triage`**。它让问题通过分类角色流转，生成可供 agent 处理的工单，后续由 **`/implement`** 领取。
+
+  分类仅适用于**不是你创建的**问题 — bug 报告、新功能请求、任何原始到达的内容。`/to-tickets` 生成的工单已经是 agent 可处理的，所以**不要对它们进行分类**。
+
+- **有东西坏了** → **`/diagnosing-bugs`**。用于疑难杂症：一眼看不出的 bug、间歇性抖动、在两个已知良好状态之间悄然而入的回归。它在拥有一个**紧凑反馈回路**之前拒绝推测 — 即一个已经在此 bug 上变红的一条命令 — 然后用回归测试修复。如果真正的发现是没有好的缝合点来锁定 bug，其事后分析会移交给 **`/improve-codebase-architecture`**。
+
+- **一项庞大而模糊的工作 — 一个从零开始的项目或一个大型功能构建，单个会话装不下** → **`/wayfinder`**。当从起点到终点的路径尚不可见时，它在问题追踪器上绘制一张**共享地图**的调查工单，并逐个解决 — 产出的是**决策，而非交付物** — 直到迷雾被驱散、路径清晰可见。然后它在 **`/to-spec`** 处汇入主流程（或者，如果工作量原来很小，直接进入 **`/implement`**）。如果说 **`/grill-with-docs`** 打磨的是你一个会话内能把握的想法，那么 wayfinder 面向的是你无法在一个会话内把握的想法。
+
+## 代码仓健康
+
+不是功能开发 — 是维护。
+
+- **`/improve-codebase-architecture`** — 有空闲时就运行，保持代码仓对 agent 友好。它会暴露**深化机会**；选择一个机会就_生成一个想法_，你可以将其带入主流程的 `/grill-with-docs`。它是找到候选方案的普查；**`/codebase-design`**（见下文）是你设计选中方案的台面。
+
+## 底层词汇
+
+两个由模型调用的参考技能，运行在其他技能的_下层_ — 各自是其词汇的单一事实来源。当**词语**而非流程是问题时，直接使用它们；或者让上面的技能自行拉取。
+
+- **`/domain-modeling`** — 精炼项目的_领域_语言：挑战模糊术语、解决一个超载的词汇（一个 "account" 干了三件事）、将难以逆转的决策记录为 ADR。它是 `/grill-with-docs` 驱动的、保持 `CONTEXT.md` 成为干净词汇表的主动规程。
+- **`/codebase-design`** — 深层模块词汇（module、interface、depth、seam、adapter、leverage、locality），用于设计模块的_形状_：在一个干净的缝合点后面、通过一个小接口承载大量行为。`/tdd` 和 `/improve-codebase-architecture` 都使用它。
+
+## 跨会话
+
+- **`/handoff`** — 当线程已满或你需要分叉（例如进入 `/prototype` 会话）时，将对话压缩为一个 markdown 文件。你不会在原处继续 — 你要**开启一个新会话并引用该文件**来传递上下文。它是上下文窗口之间的桥梁，双向皆可。当你想要**全新会话**但需要**保留当前对话**时使用它。
+- **`/compact`**（内置） — 停留在**同一对话**中，让之前的轮次被总结。在**阶段之间有意识地中断**时使用，当你不介意丢失逐字历史时。不要在阶段中间压缩 — agent 可能迷失方向。`/handoff` 是分叉；`/compact` 是继续。
+
+## 独立技能
+
+完全脱离主流程。
+
+- **`/grill-me`** — 与 `/grill-with-docs` 同样无情的访谈，但适用于你**没有代码仓**的情况。无状态：它不保存任何本地内容，不构建 `CONTEXT.md`。当你需要打磨任何不位于仓库中的计划或设计时使用它。
+- **`/prototype`** — 一个回答单个设计问题的小型一次性程序：这个状态模型感觉对吗，或者这个 UI 应该长什么样。从一开始就是一次性的 — 保留答案，删除代码。它是主流程第 2 步中的绕路，但任何时候当设计问题难以在纸面上解决时都可以使用它。
+- **`/research`** — 将阅读跑腿工作委托给**后台 agent**：它对照**一手资料**调查问题，然后在仓库中留下一个带引用的 Markdown 文件。你继续工作，让它去阅读。它产生的文件可以带入主流程的 `/grill-with-docs` — 研究喂养思考，而非替代思考。
+- **`/teach`** — 跨多个会话学习一个概念，将当前目录用作有状态的工作区。
+- **`/writing-great-skills`** — 编写和编辑技能的参考指南。
+
+## 前置条件
+
+**`/setup-matt-pocock-skills`** — 在首次工程流程之前运行，用于配置问题追踪器、分类标签和其他技能所依赖的文档布局。自定义问题追踪器同样适用。

package/template/vendor/matt-pocock/engineering/code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: code-review
+description: 沿两个轴线审查自某个固定点（commit、分支、tag 或合并基准）以来的变更 — 标准（代码是否遵循此仓库已记录的编码规范？）和规范（代码是否匹配原始 issue/PRD 要求的内容？）。以并行子 agent 运行两项审查，并将结果并排呈现。当用户想要审查分支、PR、进行中的变更，或要求"从 X 开始审查"时使用。
+---
+
+对 `HEAD` 与用户提供的某个固定点之间的 diff 进行双轴审查：
+
+- **标准** — 代码是否符合此仓库已记录的编码规范？
+- **规范** — 代码是否忠实地实现了原始 issue / PRD / 规范？
+
+两个轴以**并行子 agent** 方式运行，以免互相污染上下文，然后本技能汇总它们的发现。
+
+应该已经向你提供了问题追踪器 — 如果 `docs/agents/issue-tracker.md` 缺失，请运行 `/setup-matt-pocock-skills`。
+
+## 流程
+
+### 1. 确定固定点
+
+用户所说的任何固定点 — 一个 commit SHA、分支名、tag、`main`、`HEAD~5` 等。如果用户未指定，请询问。
+
+一次性捕获 diff 命令：`git diff <固定点>...HEAD`（三个点，以便与合并基准比较）。同时通过 `git log <固定点>..HEAD --oneline` 记录 commit 列表。
+
+继续之前，确认固定点可解析（`git rev-parse <固定点>`）且 diff 非空。无效引用或空 diff 应在此处失败 — 而非在两个并行子 agent 内部。
+
+### 2. 识别规范来源
+
+按以下顺序查找原始规范：
+
+1. commit 消息中的 issue 引用（`#123`、`Closes #45`、GitLab `!67` 等）— 通过 `docs/agents/issue-tracker.md` 中的工作流获取。
+2. 用户作为参数传入的路径。
+3. 位于 `docs/`、`specs/` 或 `.scratch/` 下的、与分支名称或功能匹配的 PRD/规范文件。
+4. 如果未找到任何内容，询问用户规范在哪里。如果用户说没有，**规范**子 agent 将跳过并报告"无可用的规范"。
+
+### 3. 识别标准来源
+
+仓库中所有记录代码应如何编写的文件，如 `CODING_STANDARDS.md` 或 `CONTRIBUTING.md`。
+
+在仓库记录的任何标准之上，标准轴始终携带以下**异味基线** — 一组固定的 Fowler 代码异味（《重构》第 3 章），即使仓库没有任何记录也适用。两条规则约束它：
+
+- **仓库优先。** 已记录的仓库标准始终优先；当它认可基线可能标记的内容时，抑制该异味。
+- **始终是判断。** 每个异味是一个带标签的启发式（"可能的 Feature Envy"），从来不是硬性违规 — 并且，与这里的任何标准一样，跳过工具链已在强制执行的内容。
+
+每个异味读作*它是什么* → *如何修复*；将其与 diff 进行匹配：
+
+- **Mysterious Name** — 函数、变量或类型，其名称不能揭示它做什么或持有什么。→ 重命名；如果没有诚实的名称可用，说明设计不清晰。
+- **Duplicated Code** — 相同的逻辑形态出现在变更中的一个以上代码块或文件中。→ 提取共享形态，从两处调用。
+- **Feature Envy** — 一个方法过多地访问另一个对象的数据，而非自身数据。→ 将该方法移动到它所羡慕的数据上。
+- **Data Clumps** — 相同的几个字段或参数总是一起出现（一个等待诞生的类型）。→ 将它们捆绑成一个类型，传递该类型。
+- **Primitive Obsession** — 一个基本类型或字符串替代了应拥有自己类型的领域概念。→ 为该概念创建自己的小型类型。
+- **Repeated Switches** — 对同一类型的相同 `switch`/`if` 级联在变更中反复出现。→ 用多态替代，或使用两个位置共享的一个映射。
+- **Shotgun Surgery** — 一个逻辑变更迫使在 diff 中跨多个文件进行分散编辑。→ 将一起变更的内容汇聚到一个模块中。
+- **Divergent Change** — 一个文件或模块因多个不相关的原因被编辑。→ 拆分，使每个模块因一个原因变更。
+- **Speculative Generality** — 为规范中没有的需求添加的抽象、参数或钩子。→ 删除它；回退内联，直到真实需求出现。
+- **Message Chains** — 调用者不应依赖的长链式 `a.b().c().d()` 导航。→ 在第一个对象上用一个方法隐藏整个链路。
+- **Middle Man** — 一个类或函数大部分只是委托转发。→ 删除它，直接调用真正的目标。
+- **Refused Bequest** — 一个子类或实现者忽略或覆盖了其继承的大部分内容。→ 放弃继承，使用组合。
+
+### 4. 并行启动两个子 agent
+
+发送一条消息，包含两个 `Agent` 工具调用。两者均使用 `general-purpose` 子 agent。
+
+**标准子 agent 提示词** — 包含：
+
+- 完整的 diff 命令和 commit 列表。
+- 在第 3 步中找到的标准来源文件列表，**加上第 3 步中的异味基线全文粘贴** — 子 agent 没有其他途径获取它。
+- 任务简述："报告 — 在相关时按文件/代码块 — (a) diff 违反已记录标准的每个地方：引用标准（文件 + 规则）；以及 (b) 你发现的任何基线异味：命名并引用代码块。区分硬性违规和判断性调用 — 已记录标准的违规可以是硬性的，但基线异味始终是判断性调用，且已记录的仓库标准覆盖基线。跳过工具链已强制执行的内容。400 词以内。"
+
+**规范子 agent 提示词** — 包含：
+
+- diff 命令和 commit 列表。
+- 规范的路径或已获取的内容。
+- 任务简述："报告：(a) 规范要求但缺失或不完整的需求；(b) diff 中存在但未被要求的、超出范围的行为；(c) 看起来已实现但实现方式错误的需求。每个发现引用规范原文。400 词以内。"
+
+如果规范缺失，跳过规范子 agent 并在最终报告中注明。
+
+### 5. 汇总
+
+在 `## 标准` 和 `## 规范` 标题下呈现两份报告，原文或略微整理。**不要**合并或重新排名发现 — 两个轴故意分离（见_为什么是两个轴_）。
+
+以一行摘要结束：每个轴的发现总数，以及每个轴内_最严重的问题_（如有）。不要在轴之间选一个"赢家" — 那正是分离设计要防止的重新排名。
+
+## 为什么是两个轴
+
+一个变更可能通过一个轴而未通过另一个：
+
+- 代码遵循所有标准但实现了错误的东西 → **标准通过，规范未通过。**
+- 代码完全按 issue 要求做了，但违反了项目的约定 → **规范通过，标准未通过。**
+
+分开报告可以防止一个轴掩盖另一个轴。

package/template/vendor/matt-pocock/engineering/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# 深化
+
+如何在给定依赖关系的情况下，安全地深化一组浅模块。假定你已掌握 [SKILL.md](SKILL.md) 中的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）。
+
+## 依赖类别
+
+在评估一个深化候选时，对其依赖进行分类。类别决定了深化后的模块如何通过其接缝进行测试。
+
+### 1. 进程内
+
+纯计算、内存状态、无 I/O。始终可深化 — 合并模块并通过新接口直接测试。不需要适配器。
+
+### 2. 本地可替换
+
+具有本地测试替代品的依赖（PGLite 替代 Postgres、内存文件系统）。如果存在替代品则可深化。深化后的模块在测试套件中使用运行的替代品进行测试。接缝是内部的；在模块的外部接口处不需要端口。
+
+### 3. 远程但自有（端口与适配器）
+
+跨网络边界的自有服务（微服务、内部 API）。在接缝处定义一个 **port**（端口，即接口）。深模块拥有逻辑；传输层作为 **adapter**（适配器）注入。测试使用内存适配器。生产环境使用 HTTP/gRPC/队列适配器。
+
+建议形式：*"在接缝处定义一个端口，为生产环境实现 HTTP 适配器，为测试实现内存适配器，这样逻辑就驻留在一个深模块中，即使它跨网络部署。"*
+
+### 4. 真正的外部依赖（Mock）
+
+你无法控制的第三方服务（Stripe、Twilio 等）。深化后的模块将外部依赖作为注入端口；测试提供一个 mock 适配器。
+
+## 接缝纪律
+
+- **一个适配器意味着假设性接缝。两个适配器意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单一适配器的接缝只是间接层。
+- **内部接缝 vs 外部接缝。** 一个深模块可以既有内部接缝（对其实现私有，供其自身的测试使用），也有其接口处的外部接缝。不要仅仅因为测试使用了内部接缝就通过接口暴露它们。
+
+## 测试策略：替换，而非叠加
+
+- 一旦深化后模块接口的测试存在，旧有浅模块上的单元测试就变成了废料 — 删除它们。
+- 在深化后模块的接口处编写新测试。**接口就是测试表面**。
+- 测试通过接口断言可观察的结果，而非内部状态。
+- 测试应经受住内部重构 — 它们描述的是行为，而非实现。如果测试在实现改变时必须更改，那它就是在测试接口之后的东西。

package/template/vendor/matt-pocock/engineering/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# 设计两次
+
+当用户想要为选定的深化候选探索替代接口时，使用此并行子 Agent 模式。基于"Design It Twice"（Ousterhout）— 你的第一个想法不太可能是最好的。
+
+使用 [SKILL.md](SKILL.md) 中的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）、**leverage**（杠杆）。
+
+## 流程
+
+### 1. 界定问题空间
+
+在启动子 Agent 之前，为选定候选编写一份面向用户的问题空间说明：
+
+- 任何新接口需要满足的约束条件
+- 它将依赖的依赖项，以及它们属于哪个类别（参见 [DEEPENING.md](DEEPENING.md)）
+- 一个粗略的示例代码草图来使约束具体化 — 不是提案，只是让约束变得具体的一种方式
+
+将此展示给用户，然后立即进入第 2 步。用户在子 Agent 并行工作时阅读和思考。
+
+### 2. 启动子 Agent
+
+使用 Agent 工具并行启动 3+ 个子 Agent。每个子 Agent 必须为深化后的模块生成一个**截然不同的**接口。
+
+为每个子 Agent 提供一份独立的技术简报（文件路径、耦合细节、来自 [DEEPENING.md](DEEPENING.md) 的依赖类别、接缝背后的内容）。简报独立于第 1 步中面向用户的问题空间说明。给每个 Agent 一个不同的设计约束：
+
+- Agent 1："最小化接口 — 目标 1–3 个入口点。最大化每个入口点的杠杆。"
+- Agent 2："最大化灵活性 — 支持多种用例和扩展。"
+- Agent 3："为最常见的调用方优化 — 让默认情况变得简单。"
+- Agent 4（如适用）："围绕接缝设计端口与适配器，以处理跨接缝依赖。"
+
+在简报中同时包含 [SKILL.md](SKILL.md) 词汇和 CONTEXT.md 词汇，以便每个子 Agent 能使用架构语言和项目的领域语言一致地命名事物。
+
+每个子 Agent 输出：
+
+1. 接口（类型、方法、参数 — 以及不变量、排序、错误模式）
+2. 使用示例，展示调用方如何使用它
+3. 实现在接缝背后隐藏了什么
+4. 依赖策略和适配器（参见 [DEEPENING.md](DEEPENING.md)）
+5. 权衡 — 哪里杠杆高，哪里杠杆薄
+
+### 3. 展示和比较
+
+按顺序展示各个设计，让用户能够消化每一个，然后用文字进行比较。通过 **depth**（深度，接口处的杠杆）、**locality**（局部性，变更集中的位置）和 **seam placement**（接缝位置）来对比。
+
+比较之后，给出你自己的建议：你认为哪个设计最强以及原因。如果不同设计中的元素可以很好地组合，提出一个混合方案。要有主见 — 用户想要的是一个有力的判断，而不是一个菜单。

package/template/vendor/matt-pocock/engineering/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: 设计深层模块的共享词汇。当用户想要设计或改进模块接口、寻找深化机会、决定缝合点放在哪里、使代码更可测试或更适合 AI 导航，或当其他技能需要深层模块词汇时使用。
+---
+
+# 代码仓设计
+
+设计**深层模块**：通过一个小接口承载大量行为，放置在干净的缝合点处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
+
+## 术语表
+
+严格使用以下术语 — 不要用 "component"、"service"、"API" 或 "boundary" 替代。一致的语言才是重点。
+
+**Module（模块）** — 任何具有接口和实现的东西。有意识地与规模无关：函数、类、包或跨层切片。_避免使用_：unit、component、service。
+
+**Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。_避免使用_：API、signature（太窄 — 它们仅指类型层面的表面）。
+
+**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论缝合点时用 "adapter"；否则用 "implementation"。
+
+**Depth（深度）** — 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口可以驱动的行为量。当大量行为隐藏在小接口后面时，模块是**深层的**；当接口几乎和实现一样复杂时，模块是**浅层的**。
+
+**Seam（缝合点）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。缝合点放在哪里本身就是一个设计决策，与缝合点后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
+
+**Adapter（适配器）** — 在缝合点处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
+
+**Leverage（杠杆效应）** — 调用者从深度中获得的好处：每学习一个单位的接口获得更多的能力。一个实现为 N 个调用点和 M 个测试带来回报。
+
+**Locality（局部性）** — 维护者从深度中获得的好处：变更、bug、知识和验证集中在一个地方，而非分散在调用者之间。一次修复，处处生效。
+
+## 深层 vs 浅层
+
+**深层模块** = 小接口 + 大量实现：
+
+```
+┌─────────────────────┐
+│   小接口             │  ← 少量方法，简单参数
+├─────────────────────┤
+│                     │
+│  深层实现            │  ← 隐藏的复杂逻辑
+│                     │
+└─────────────────────┘
+```
+
+**浅层模块** = 大接口 + 少量实现（应避免）：
+
+```
+┌─────────────────────────────────┐
+│       大接口                     │  ← 大量方法，复杂参数
+├─────────────────────────────────┤
+│  薄实现                          │  ← 仅仅是透传
+└─────────────────────────────────┘
+```
+
+设计接口时，问自己：
+
+- 我能减少方法数量吗？
+- 我能简化参数吗？
+- 我能隐藏更多内部的复杂性吗？
+
+## 原则
+
+- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部缝合点**（对其实现私有，用于其自身测试）以及位于其接口处的**外部缝合点**。
+- **删除测试。** 想象删除这个模块。如果复杂性消失，它就是个透传层。如果复杂性在 N 个调用者中重新出现，它就在发挥价值。
+- **接口就是测试表面。** 调用者和测试穿过同一个缝合点。如果你想测试接口_之外_的内容，模块可能形状不对。
+- **一个适配器意味着假设的缝合点。两个适配器意味着真实的缝合点。** 除非有东西确实在缝合点两侧变化，否则不要引入缝合点。
+
+## 为可测试性而设计
+
+良好的接口使测试变得自然：
+
+1. **接收依赖，不要创建依赖。**
+
+   ```typescript
+   // 可测试
+   function processOrder(order, paymentGateway) {}
+
+   // 难以测试
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **返回结果，不要产生副作用。**
+
+   ```typescript
+   // 可测试
+   function calculateDiscount(cart): Discount {}
+
+   // 难以测试
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **小表面积。** 更少的方法 = 更少的测试需求。更少的参数 = 更简单的测试设置。
+
+## 关系
+
+- 一个 **Module** 恰好有一个 **Interface**（它向调用者和测试呈现的表面）。
+- **Depth** 是一个 **Module** 的属性，对照其 **Interface** 来度量。
+- 一个 **Seam** 是一个 **Module** 的 **Interface** 所在的位置。
+- 一个 **Adapter** 位于 **Seam** 处，满足 **Interface**。
+- **Depth** 为调用者产生 **Leverage**，为维护者产生 **Locality**。
+
+## 已拒绝的框架
+
+- **深度作为实现行数与接口行数之比** (Ousterhout)：奖励填充实现。我们使用深度即杠杆效应来替代。
+- **"Interface" 作为 TypeScript 的 `interface` 关键字或类的公开方法**：太窄 — 此处的接口包括调用者必须了解的每个事实。
+- **"Boundary"**：与 DDD 的有界上下文重载。说 **seam** 或 **interface**。
+
+## 深入阅读
+
+- **给定依赖的情况下深化一个集群** — 见 [DEEPENING.md](DEEPENING.md)：依赖类别、缝合点规程、以及替换而非分层的测试。
+- **探索替代接口** — 见 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)：启动并行子 agent，以几种截然不同的方式设计接口，然后在深度、局部性和缝合点位置上进行比较。