@namewta/speculo 0.1.21 → 0.2.0

package/template/vendor/matt-pocock/engineering/diagnosing-bugs/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: diagnosing-bugs
+description: 针对疑难 bug 和性能回归的诊断循环。当用户说"诊断"/"调试这个"，或报告有东西损坏/抛出异常/失败/变慢时使用。
+---
+
+# 诊断 Bug
+
+针对疑难 bug 的规程。仅在明确有理由时才跳过阶段。
+
+探索代码仓时，阅读 `CONTEXT.md`（如果存在）以获取相关模块的清晰心智模型，并检查你接触区域的 ADR。
+
+## 阶段 1 — 构建反馈回路
+
+**这就是核心技能。** 其他一切都是机械性的。如果你针对 bug 有一个**紧凑的**通过/失败信号 — 一个在_此_ bug 上会变红的信号 — 你就会找到原因；二分查找、假设检验和插桩都只是消费它。如果你没有一个这样的信号，再盯着代码看也救不了你。
+
+在此投入不成比例的精力。**要激进。要有创意。拒绝放弃。**
+
+### 构建方式 — 按大致顺序尝试
+
+1. **失败测试**，位于能触及 bug 的任意缝合点 — 单元、集成、端到端。
+2. **Curl / HTTP 脚本**，针对正在运行的开发服务器。
+3. **CLI 调用**，带固定输入，将 stdout 与已知良好快照进行 diff。
+4. **无头浏览器脚本**（Playwright / Puppeteer）— 驱动 UI，对 DOM/控制台/网络进行断言。
+5. **回放捕获的追踪数据。** 将真实网络请求 / 负载 / 事件日志保存到磁盘；在隔离环境中通过代码路径回放。
+6. **一次性测试夹具。** 启动系统的最小子集（一个服务、模拟依赖），用单个函数调用来驱动 bug 代码路径。
+7. **属性 / 模糊测试循环。** 如果 bug 是"有时输出错误"，运行 1000 次随机输入，寻找故障模式。
+8. **二分查找夹具。** 如果 bug 出现在两个已知状态之间（commit、数据集、版本），自动化"在状态 X 启动、检查、重复"以便 `git bisect run`。
+9. **差分循环。** 通过旧版本 vs 新版本（或两种配置）运行相同输入，对输出进行 diff。
+10. **HITL bash 脚本。** 最后手段。如果必须由人工点击，用 `scripts/hitl-loop.template.sh` 驱动_他们_，使循环仍然结构化。捕获的输出反馈给你。
+
+构建了正确的反馈回路，bug 就修复了 90%。
+
+### 收紧回路
+
+将回路视为产品。一旦你有了_一个_回路，**收紧**它：
+
+- 能更快吗？（缓存设置，跳过无关初始化，缩小测试范围。）
+- 信号能更清晰吗？（针对具体症状断言，而非"没崩溃"。）
+- 能更确定性吗？（固定时间、种子随机数、隔离文件系统、冻结网络。）
+
+一个 30 秒的抖动回路比没有回路好不了多少；一个 2 秒的确定性回路才是紧凑的 — 这是调试的超能力。
+
+### 非确定性 bug
+
+目标不是干净的复现，而是**更高的复现率**。循环触发 100 次，并行化，增加压力，缩小时间窗口，注入 sleep。50% 抖动的 bug 是可调试的；1% 则不行 — 持续提高复现率直到可调试。
+
+### 当确实无法构建回路时
+
+停下来，明确说明。列出你尝试过的方法。向用户请求：(a) 访问能复现的任何环境，(b) 一个捕获的产物（HAR 文件、日志转储、核心转储、带时间戳的屏幕录制），或 (c) 添加临时生产环境插桩的许可。**不要**在没有回路的情况下进入假设阶段。
+
+### 完成标准 — 一个会变红的紧凑回路
+
+阶段 1 完成的条件是回路**紧凑**且**具备变红能力**：你能说出**一条命令** — 一个脚本路径、一个测试调用、一个 curl — 你**已经至少运行过一次**（粘贴调用及其输出），并且该命令满足：
+
+- [ ] **具备变红能力** — 它驱动实际的 bug 代码路径，并断言**用户的确切症状**，因此它能在此 bug 上变红，修复后变绿。不是"运行不出错" — 它必须能够_捕获这个具体的 bug_。
+- [ ] **确定性** — 每次运行结果一致（抖动 bug：固定的、足够高的复现率，如上所述）。
+- [ ] **快速** — 秒级，而非分钟级。
+- [ ] **Agent 可运行** — 你可以无人值守地运行它；只有在通过 `scripts/hitl-loop.template.sh` 时才能有人工参与。
+
+如果你发现自己在回路存在之前阅读代码来构建理论，**停下来 — 直接跳到假设正是本技能要防止的确切失败模式。** 没有变红能力的命令，就没有阶段 2。
+
+## 阶段 2 — 复现 + 最小化
+
+运行回路。看着它变红 — bug 出现。
+
+确认：
+
+- [ ] 回路产生了**用户**描述的故障模式 — 不是恰好碰巧在附近的另一个故障。错误的 bug = 错误的修复。
+- [ ] 故障可跨多次运行复现（或对于非确定性 bug，以足够高的复现率可调试）。
+- [ ] 你已捕获确切的症状（错误消息、错误输出、缓慢的计时），以便后续阶段验证修复确实解决了它。
+
+### 最小化
+
+一旦变红，将复现场景缩小到**仍能变红的最小场景**。**逐个**削减输入、调用者、配置、数据和步骤，每次削减后重新运行回路 — 只保留对故障有负载作用的部分。
+
+为什么费这个劲：最小复现场景缩小了阶段 3 的假设空间（值得怀疑的移动部件更少），并成为阶段 5 的干净回归测试。
+
+完成条件是**每个剩余元素都有负载作用** — 移除其中任何一个都会使回路变绿。
+
+在复现**且**最小化之前不要继续。
+
+## 阶段 3 — 提出假设
+
+在测试任何假设之前生成 **3-5 个排名假设**。单一假设生成会锚定在第一个看似合理的想法上。
+
+每个假设必须是**可证伪的**：陈述它的预测。
+
+> 格式："如果 <X> 是原因，那么 <改变 Y> 会使 bug 消失 / <改变 Z> 会使它更糟。"
+
+如果你无法陈述预测，这个假设只是感觉 — 丢弃或精炼它。
+
+**在测试之前向用户展示排名列表。** 他们通常拥有能立即重新排名的领域知识（"我们刚刚部署了对第 3 项的改动"），或知道他们已经排除的假设。低成本检查点，大幅节省时间。如果用户 AFK，不要等待 — 按你的排名继续。
+
+## 阶段 4 — 插桩
+
+每个探测必须映射到阶段 3 中的一个具体预测。**每次只改变一个变量。**
+
+工具偏好：
+
+1. **调试器 / REPL 检查**，如果环境支持。一个断点胜过十行日志。
+2. **针对性日志**，在能区分假设的边界处。
+3. 永远不要"记录一切然后 grep"。
+
+**用唯一前缀标记每条调试日志**，例如 `[DEBUG-a4f2]`。最后的清理只需一次 grep。未标记的日志保留；已标记的日志删除。
+
+**性能分支。** 对于性能回归，日志通常是错误的。替代方案：建立基线测量（计时夹具、`performance.now()`、分析器、查询计划），然后二分查找。先测量，后修复。
+
+## 阶段 5 — 修复 + 回归测试
+
+在修复**之前**编写回归测试 — 但仅当存在**正确的缝合点**时才这样做。
+
+正确的缝合点是指测试能在调用点处驱动**真实的 bug 模式**。如果唯一可用的缝合点太浅（bug 需要多个调用者时却只有单调用者测试，单元测试无法复现触发 bug 的调用链），在那里的回归测试会给出虚假的信心。
+
+**如果不存在正确的缝合点，这本身就是发现。** 记录下来。代码仓架构正在阻止锁定此 bug。将此标记给下一阶段。
+
+如果存在正确的缝合点：
+
+1. 将最小复现转为该缝合点处的失败测试。
+2. 看着它失败。
+3. 应用修复。
+4. 看着它通过。
+5. 对原始（未最小化的）场景重新运行阶段 1 的反馈回路。
+
+## 阶段 6 — 清理 + 事后分析
+
+宣布完成前必须完成：
+
+- [ ] 原始复现不再复现（重新运行阶段 1 的回路）
+- [ ] 回归测试通过（或缝合点的缺失已被记录）
+- [ ] 所有 `[DEBUG-...]` 插桩已移除（grep 该前缀）
+- [ ] 一次性原型已删除（或移至明确标记的调试位置）
+- [ ] 被证明正确的假设在 commit / PR 消息中陈述 — 以便下一个调试者学习
+
+**然后问：什么本可以预防这个 bug？** 如果答案涉及架构变更（没有好的测试缝合点、纠缠的调用者、隐藏的耦合），将具体情况移交给 `/improve-codebase-architecture` 技能。在修复**之后**提出建议，而非之前 — 你现在比开始时拥有更多信息。

package/template/vendor/matt-pocock/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# 人在回路（Human-in-the-loop）重现循环。
+# 复制此文件，编辑下面的步骤，然后运行它。
+# Agent 运行脚本；用户在其终端中按照提示操作。
+#
+# 用法：
+#   bash hitl-loop.template.sh
+#
+# 两个辅助函数：
+#   step "<指令>"          → 显示指令，等待按 Enter
+#   capture VAR "<问题>"   → 显示问题，读取响应到 VAR
+#
+# 结束时，捕获的值以 KEY=VALUE 格式打印，供 agent 解析。
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- 在下方编辑 ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- 在上方编辑 ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/template/vendor/matt-pocock/engineering/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR 格式
+
+ADR 存放在 `docs/adr/` 中，使用顺序编号：`0001-slug.md`、`0002-slug.md` 等。
+
+延迟创建 `docs/adr/` 目录 — 仅在需要第一个 ADR 时才创建。
+
+## 模板
+
+```md
+# {决策的简短标题}
+
+{1-3 句话：背景是什么，我们做了什么决策，以及为什么。}
+```
+
+就这样。一个 ADR 可以就是一个段落。其价值在于记录*已经*做出了决策以及*为什么* — 而不是填满各个部分。
+
+## 可选部分
+
+仅当它们真正增加价值时才包含这些。大多数 ADR 不需要它们。
+
+- **Status** 前置元数据（`proposed | accepted | deprecated | superseded by ADR-NNNN`）— 当决策被重新审视时有用
+- **Considered Options** — 仅当被拒绝的替代方案值得记住时
+- **Consequences** — 仅当需要指出非显而易见的下游影响时
+
+## 编号
+
+扫描 `docs/adr/` 中的最高现有编号，然后加 1。
+
+## 何时提供 ADR
+
+以下三个条件必须同时为真：
+
+1. **难以逆转** — 以后改变主意的成本是实质性的
+2. **没有上下文的话令人惊讶** — 未来的读者会看着代码想"他们到底为什么这样做？"
+3. **真实权衡的结果** — 确实存在替代方案，你基于特定原因选择了一个
+
+如果决策容易逆转，跳过它 — 你反正会逆转的。如果不令人惊讶，没人会想为什么。如果没有真正的替代方案，那就没有可记录的，除了"我们做了显而易见的事"。
+
+### 什么算作
+
+- **架构形态。** "我们使用 monorepo。" "写模型采用事件溯源，读模型投影到 Postgres。"
+- **上下文间的集成模式。** "Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。"
+- **带来锁定效应的技术选择。** 数据库、消息总线、认证提供商、部署目标。不是每个库 — 只是那些需要花一个季度才能替换的。
+- **边界和范围决策。** "客户数据由 Customer 上下文拥有；其他上下文仅通过 ID 引用它。"明确的"不做"和"要做"同样有价值。
+- **有意偏离显而易见路径的决策。** "我们使用手动 SQL 而不是 ORM，因为 X。"任何合理读者会假设相反的情况。这些可以阻止下一个工程师"修复"一个刻意为之的东西。
+- **代码中不可见的约束。** "由于合规要求，我们不能使用 AWS。" "由于合作伙伴 API 合同，响应时间必须低于 200ms。"
+- **拒绝的原因不明显的被拒绝替代方案。** 如果你考虑了 GraphQL 而因微妙原因选择了 REST，记录下来 — 否则 6 个月后有人会再次建议 GraphQL。

package/template/vendor/matt-pocock/engineering/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md 格式
+
+## 结构
+
+```md
+# {上下文名称}
+
+{对该上下文是什么以及为什么存在的一两句话描述。}
+
+## Language
+
+**Order**：
+{对该术语的一两句话描述}
+_Avoid_: Purchase, transaction
+
+**Invoice**：
+发货后发送给客户的付款请求。
+_Avoid_: Bill, payment request
+
+**Customer**：
+下订单的个人或组织。
+_Avoid_: Client, buyer, account
+```
+
+## 规则
+
+- **要有主见。** 当同一概念存在多个词时，选择最好的那个，并将其他的列在 `_Avoid_` 下。
+- **定义保持精炼。** 最多一两句话。定义它是什么，而不是它做什么。
+- **仅包含特定于该项目上下文的术语。** 通用的编程概念（超时、错误类型、工具模式）即使项目广泛使用也不属于这里。添加术语前自问：这是该上下文独有的概念，还是一个通用编程概念？只有前者才属于这里。
+- **当自然形成聚类时，用子标题分组术语。** 如果所有术语属于一个单一的凝聚领域，扁平列表也可以。
+
+## 单上下文 vs 多上下文仓库
+
+**单上下文（大多数仓库）：** 在仓库根目录下一个 `CONTEXT.md`。
+
+**多上下文：** 在仓库根目录下一个 `CONTEXT-MAP.md` 列出各个上下文、它们的位置以及它们之间的关系：
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — 接收并跟踪客户订单
+- [Billing](./src/billing/CONTEXT.md) — 生成发票并处理付款
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — 管理仓库拣货和发货
+
+## Relationships
+
+- **Ordering → Fulfillment**：Ordering 发出 `OrderPlaced` 事件；Fulfillment 消费它们以开始拣货
+- **Fulfillment → Billing**：Fulfillment 发出 `ShipmentDispatched` 事件；Billing 消费它们以生成发票
+- **Ordering ↔ Billing**：共享 `CustomerId` 和 `Money` 类型
+```
+
+该 skill 会根据存在情况推断适用哪种结构：
+
+- 如果存在 `CONTEXT-MAP.md`，读取它以找到各个上下文
+- 如果只存在根目录下的 `CONTEXT.md`，则为单上下文
+- 如果两者都不存在，当第一个术语被确定时延迟创建一个根目录下的 `CONTEXT.md`
+
+当存在多个上下文时，推断当前主题与哪个上下文相关。如果不清楚，询问。

package/template/vendor/matt-pocock/engineering/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: 构建和精炼项目的领域模型。当用户想要确定领域术语或通用语言、记录架构决策，或当其他技能需要维护领域模型时使用。
+---
+
+# 领域建模
+
+在设计过程中积极构建和精炼项目的领域模型。这是*主动*规程 — 挑战术语、发明边界场景、并在决策结晶的那一刻立即写下词汇表和决策。（仅仅_阅读_ `CONTEXT.md` 获取词汇不是本技能 — 那是任何技能都可以做到的一行习惯。本技能用于当你正在_改变_模型，而不仅仅是消费它时。）
+
+## 文件结构
+
+大多数仓库只有一个上下文：
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+如果根目录存在 `CONTEXT-MAP.md`，则仓库有多个上下文。该映射指向每个上下文所在的位置：
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← 系统级决策
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← 上下文特定的决策
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+延迟创建文件 — 仅当有内容可写时才创建。如果 `CONTEXT.md` 不存在，在第一个术语确定时创建。如果 `docs/adr/` 不存在，在第一个 ADR 需要时创建。
+
+## 会话期间
+
+### 对照词汇表挑战
+
+当用户使用的术语与 `CONTEXT.md` 中的现有语言冲突时，立即指出。"你的词汇表将 'cancellation' 定义为 X，但你似乎指的是 Y — 到底是哪个？"
+
+### 精炼模糊语言
+
+当用户使用含糊或重载的术语时，提出一个精确的规范术语。"你在说 'account' — 你指的是 Customer 还是 User？它们是不同的东西。"
+
+### 讨论具体场景
+
+当讨论领域关系时，用具体场景进行压力测试。发明探索边界情况的场景，迫使用户精确界定概念之间的边界。
+
+### 与代码交叉引用
+
+当用户陈述某事如何工作时，检查代码是否一致。如果发现矛盾，指出来："你的代码取消的是整个 Order，但你刚才说部分取消是可能的 — 哪个是正确的？"
+
+### 及时更新 CONTEXT.md
+
+当术语确定时，当场更新 `CONTEXT.md`。不要批量处理 — 发生时立即捕获。使用 [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) 中的格式。
+
+`CONTEXT.md` 应该完全不包含实现细节。不要将 `CONTEXT.md` 当作规范、草稿纸或实现决策的仓库。它只是词汇表，别无其他。
+
+### 谨慎创建 ADR
+
+仅在以下三个条件全部满足时才提供创建 ADR：
+
+1. **难以逆转** — 以后改变主意的成本是有意义的
+2. **没有上下文会令人惊讶** — 未来的读者会疑惑"他们为什么这样做？"
+3. **真实权衡的结果** — 存在真正的替代方案，你出于特定原因选择了一个
+
+如果缺少任何一个条件，跳过 ADR。使用 [ADR-FORMAT.md](./ADR-FORMAT.md) 中的格式。

package/template/vendor/matt-pocock/engineering/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: 一场无情的访谈，用于打磨计划或设计，同时在此过程中创建文档（ADR 和词汇表）。
+disable-model-invocation: true
+---
+
+运行 `/grilling` 会话，使用 `/domain-modeling` 技能。

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

@@ -0,0 +1,15 @@
+---
+name: implement
+description: "基于规范或工单集实现一项工作。"
+disable-model-invocation: true
+---
+
+基于规范或工单实现用户描述的工作。
+
+尽可能使用 /tdd，在预先商定的缝合点处进行。
+
+定期运行类型检查，定期运行单个测试文件，最后运行一次完整的测试套件。
+
+完成后，使用 /code-review 审查工作。
+
+将你的工作提交到当前分支。

package/template/vendor/matt-pocock/engineering/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML 报告格式
+
+架构审查渲染为一个独立的 HTML 文件，存放在操作系统临时目录中。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状的图表；手工构建的 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。混合使用两者 — 不要所有事情都依赖 Mermaid，否则会变得千篇一律。
+
+## 脚手架
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* Tailwind 无法很好覆盖的小型自定义层：
+         虚线接缝线、手绘感箭头等。 */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## 页头
+
+仓库名称、日期和一个紧凑的图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，粗黑框 = 深模块。无介绍段落 — 直接进入候选。
+
+## 候选卡片
+
+图表承担主要分量。文字稀疏、平实，并使用来自 `/codebase-design` skill 的术语，不刻意修饰。
+
+每个候选是一个 `<article>`：
+
+- **标题** — 简短，命名深化方案（例如"Collapse the Order intake pipeline"）。
+- **徽章行** — 推荐强度（`Strong` = 翡翠绿，`Worth exploring` = 琥珀色，`Speculative` = 石板灰），外加一个依赖类别标签（`in-process`、`local-substitutable`、`ports & adapters`、`mock`）。
+- **文件** — 等宽字体列表，`font-mono text-sm`。
+- **Before / After 图表** — 核心。两列，并排。参见下方模式。
+- **Problem** — 一句话。痛点是什么。
+- **Solution** — 一句话。改变了什么。
+- **Wins** — 要点，每个不超过 6 个词。例如 "Tests hit one interface"、"Pricing logic stops leaking"、"Delete 4 shallow wrappers"。
+- **ADR 标注**（如适用）— 一行，放在琥珀色调的框中。
+
+无需解释段落。如果图表需要一段文字才能理解，重新画图。
+
+## 图表模式
+
+选择适合候选的模式。混合使用它们。不要让每个图表看起来都一样 — 多样性本身就是目的的一部分。
+
+### Mermaid 图表（依赖/调用流的常用工具）
+
+当重点是"X 调用 Y 调用 Z，看看这有多混乱"时，使用 Mermaid `flowchart` 或 `graph`。用 Tailwind 风格卡片包裹它，这样不会显得突兀。使用 classDef 将泄漏边缘着红色，深模块着深色。序列图适合展示"before：6 个往返；after：1 个"。
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### 手工绘制的框线图（当 Mermaid 的布局难以驾驭时）
+
+模块用带边框和标签的 `<div>` 表示。箭头用绝对定位在相对容器上的内联 SVG `<line>` 或 `<path>` 元素表示。当你希望"after"图表看起来像一个粗边的深模块，内部元素灰显时使用 — Mermaid 不会以合适的权重渲染这种效果。
+
+### 横截面图（适合分层浅度）
+
+堆叠水平条（`h-12 border-l-4`）来展示调用经过的各层。Before：6 个薄层，每个都不做什么。After：一个厚条，标注合并后的职责。
+
+### 质量图（适合"接口与实现一样宽"的场景）
+
+每个模块两个矩形 — 一个表示接口表面积，一个表示实现。Before：接口矩形几乎和实现矩形一样高（浅）。After：接口矩形短，实现矩形高（深）。
+
+### 调用图坍缩
+
+Before：嵌套框呈现的函数调用树。After：同一棵树坍缩成一个框，内部调用在其内部以淡化形式显示。
+
+## 样式指导
+
+- 偏向编辑风格，而非企业仪表盘风格。宽松的留白。标题可选择衬线字体（`font-serif` 与 stone/slate 搭配效果很好）。
+- 色彩使用克制：一种强调色（翠绿或靛蓝），加上红色用于泄漏，琥珀色用于警告。
+- 保持图表约 320px 高，使 before/after 能够舒适地并排放置而无需滚动。
+- 使用 `text-xs uppercase tracking-wider` 用于图表内的模块标签 — 它们应读起来像示意图，而非 UI。
+- 唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。除此之外报告是静态的 — 没有应用代码，除了 Mermaid 自身的渲染之外没有交互。
+
+## 顶部推荐部分
+
+一张更大的卡片。候选名称，一句话说明为什么，指向其卡片的锚链接。这就够了。
+
+## 语气
+
+平实的英语，简洁 — 但架构名词和动词直接来自 `/codebase-design` skill。简洁不是偏离的借口。
+
+**完全使用：** module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality。
+
+**绝不替代：** component、service、unit（代替 module）· API、signature（代替 interface）· boundary（代替 seam）· layer、wrapper（代替 module，当你的意思是 module 时）。
+
+**符合风格的表达方式：**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins 要点**用术语表命名收益：*"locality: bugs concentrate in one module"*、*"leverage: one interface, N call sites"*、*"interface shrinks; implementation absorbs the wrappers"*。不要写 *"easier to maintain"* 或 *"cleaner code"* — 这些术语不在术语表中，不值得留下。
+
+不模糊其词，不清喉咙，不说"值得注意的是……"。如果一句话可以变成一个要点，就变成要点。如果一个要点可以删除，就删除它。如果一个术语不在 `/codebase-design` 术语表中，在发明新术语之前先用术语表中已有的。

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

@@ -0,0 +1,66 @@
+---
+name: improve-codebase-architecture
+description: 扫描代码仓寻找深化机会，以可视化 HTML 报告呈现，然后针对你选择的任一方案进行访谈打磨。
+disable-model-invocation: true
+---
+
+# 改善代码仓架构
+
+揭示架构摩擦，提出**深化机会** — 将浅层模块转变为深层模块的重构。目标是可测试性和 AI 可导航性。
+
+此命令_基于_项目的领域模型，并建立在共享设计词汇之上：
+
+- 运行 `/codebase-design` 技能获取架构词汇（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其原则（删除测试、"接口就是测试表面"、"一个适配器 = 假设缝合点，两个 = 真实缝合点"）。在每个建议中严格使用这些术语 — 不要滑向 "component"、"service"、"API" 或 "boundary"。
+- `CONTEXT.md` 中的领域语言为好的缝合点提供名称；`docs/adr/` 中的 ADR 记录此命令不应重新争论的决策。
+
+## 流程
+
+### 1. 探索
+
+首先阅读项目的领域词汇表（`CONTEXT.md`）和你接触区域的任何 ADR。
+
+然后使用 Agent 工具，以 `subagent_type=Explore` 遍历代码仓。不要遵循僵化的启发式 — 有机地探索，注意你在何处遇到摩擦：
+
+- 理解一个概念需要在多个小模块之间反复跳跃？
+- 哪些模块是**浅层的** — 接口几乎和实现一样复杂？
+- 哪些纯函数仅为了可测试性而被提取，但真正的 bug 却隐藏在它们的调用方式中（没有**局部性**）？
+- 哪些紧密耦合的模块在其缝合点处泄漏？
+- 代码仓的哪些部分未经测试，或难以通过其当前接口进行测试？
+
+对你怀疑是浅层的任何东西应用**删除测试**：删除它会集中复杂性，还是仅仅移动它？"是的，会集中"就是你想要的信号。
+
+### 2. 以 HTML 报告呈现候选方案
+
+将自包含的 HTML 文件写入操作系统临时目录，以免任何内容落入仓库。从 `$TMPDIR` 解析临时目录，回退到 `/tmp`（Windows 上用 `%TEMP%`），写入 `<临时目录>/architecture-review-<时间戳>.html`，使每次运行获得全新文件。为用户打开它 — Linux 上用 `xdg-open <路径>`，macOS 上用 `open <路径>`，Windows 上用 `start <路径>` — 并告知绝对路径。
+
+报告使用 **Tailwind via CDN** 进行布局和样式设置，使用 **Mermaid via CDN** 绘制图/流程/序列可靠传达结构的图表。混合使用 Mermaid 和手写 CSS/SVG 视觉效果 — 当关系是图形态时（调用图、依赖关系、序列）使用 Mermaid，当想要更偏编辑性时（质量图、横截面、折叠动画）使用手写 div/SVG。每个候选方案包含一个**前后对比可视化**。要注重视觉效果。
+
+为每个候选方案渲染一张卡片，包含：
+
+- **文件** — 涉及哪些文件/模块
+- **问题** — 为什么当前架构正在造成摩擦
+- **解决方案** — 用简明英语描述将发生什么变化
+- **收益** — 用局部性和杠杆效应解释，以及测试将如何改善
+- **前后对比图** — 并排，自定义绘制，展示浅层性和深化过程
+- **建议强度** — `Strong`、`Worth exploring`、`Speculative` 之一，渲染为徽章
+
+以**最佳推荐**部分结束报告：你会首先处理哪个候选方案以及原因。
+
+**使用 CONTEXT.md 的词汇处理领域，使用 `/codebase-design` 的词汇处理架构。** 如果 `CONTEXT.md` 定义了 "Order"，谈论 "Order 接收模块" — 而非 "FooBarHandler"，也非 "Order 服务"。
+
+**ADR 冲突**：如果某个候选方案与现有 ADR 矛盾，仅在摩擦足够真实、值得重新审视 ADR 时才提出。在卡片中清晰标记（例如警告标注：_"与 ADR-0007 矛盾 — 但值得重新讨论因为……"_）。不要列出 ADR 禁止的所有理论重构。
+
+参见 [HTML-REPORT.md](HTML-REPORT.md) 获取完整的 HTML 脚手架、图表模式和样式指南。
+
+此时**不要**提出接口。文件写入后，询问用户："你想探索其中哪一个？"
+
+### 3. 访谈循环
+
+一旦用户选择了候选方案，运行 `/grilling` 技能与他们一起遍历设计树 — 约束、依赖、深化模块的形状、缝合点后面的内容、哪些测试存留下来。
+
+当决策结晶时，副作用即时发生 — 运行 `/domain-modeling` 技能保持领域模型同步更新：
+
+- **为 `CONTEXT.md` 中没有的概念命名深化模块？** 将术语添加到 `CONTEXT.md`。如果文件不存在则延迟创建。
+- **在对话中精炼模糊术语？** 当场更新 `CONTEXT.md`。
+- **用户以具有负载作用的理由拒绝候选方案？** 提供 ADR，框架为：_"要我将其记录为 ADR 吗？这样未来的架构审查不会重新建议它。"_ 仅在未来的探索者确实需要此理由来避免重新建议相同内容时才提供 — 跳过暂时性理由（"现在不值得做"）和自明性理由。
+- **想要探索深化模块的替代接口？** 运行 `/codebase-design` 技能并使用其"设计两次"并行子 agent 模式。

package/template/vendor/matt-pocock/engineering/prototype/LOGIC.md

@@ -0,0 +1,79 @@
+# 逻辑原型
+
+一个小型交互式终端应用，让用户手动驱动状态模型。当问题与**业务逻辑、状态转换或数据形态**相关时使用 — 这类问题在纸面上看起来合理，但只有在通过真实案例推动时才会感到不对。
+
+## 何时适合使用这种形式
+
+- "我不确定这个状态机是否处理 X 然后 Y 的边界情况。"
+- "这个数据模型是否真的能让我表示……这种情况？"
+- "我想在写代码之前感受一下 API 应该是什么样子。"
+- 任何用户想要**按下按钮观看状态变化**的场景。
+
+如果问题是"这应该长什么样" — 走错分支了。请使用 [UI.md](UI.md)。
+
+## 流程
+
+### 1. 明确问题
+
+在写代码之前，写下你在为哪个状态模型和什么问题做原型。一段话，放在原型的 README 中或文件顶部的注释中。一个回答了错误问题的逻辑原型纯属浪费 — 明确问题以便稍后检查，无论用户是现在看着还是稍后回来离线查看。
+
+### 2. 选择语言
+
+使用宿主项目使用的任何语言。如果项目没有明显的运行时（例如文档仓库），则询问。
+
+匹配项目现有的工具约定 — 不要仅仅为了原型而添加新的包管理器或运行时。
+
+### 3. 将逻辑隔离在可移植模块中
+
+将实际逻辑 — 回答问题的部分 — 放在一个小的纯接口后面，这个接口可以提取出来稍后放入真实代码库。围绕它的 TUI 是一次性的；逻辑模块不应该是。
+
+正确的形态取决于问题：
+
+- **纯 reducer** — `(state, action) => state`。适合动作为离散事件且状态是单个值的情况。
+- **状态机** — 明确的状态和转换。适合"哪些动作在当前状态下是合法的"本身就是问题的一部分。
+- **一组在纯数据类型上的小函数。** 适合没有隐式当前状态的情况 — 只是转换。
+- **具有清晰方法面的类或模块**，当逻辑确实拥有持续的内部状态时。
+
+选择最适合所问问题的形态，*而不是*最容易连接到 TUI 的形态。保持纯：无 I/O、无终端代码、无用于控制流的 `console.log`。TUI 导入它并调用它；没有任何东西向相反方向流动。
+
+这就是让原型在其生命周期之后仍然有用的关键。当问题得到回答后，经过验证的 reducer / 状态机 / 函数集可以被提取到真实模块中 — TUI 外壳则被删除。
+
+### 4. 构建最小的 TUI 来暴露状态
+
+将其构建为**轻量级 TUI** — 在每个时钟周期，清除屏幕（`console.clear()` / `print("\033[2J\033[H")` / 等价方式）并重新渲染整个帧。用户应始终看到一个稳定的视图，而非不断增长的滚动日志。
+
+每帧有两个部分，按此顺序：
+
+1. **当前状态**，美化打印且便于 diff（每行一个字段，或格式化的 JSON）。使用**粗体**表示字段名或节标题，**暗色**表示不太重要的上下文（时间戳、ID、派生值）。原生 ANSI 转义码即可 — `\x1b[1m` 粗体，`\x1b[2m` 暗色，`\x1b[0m` 重置。除非项目中已有样式库，否则无需引入。
+2. **键盘快捷键**，列在底部：`[a] add user  [d] delete user  [t] tick clock  [q] quit`。粗体显示按键，暗色显示描述，或反之 — 读起来清晰即可。
+
+行为：
+
+1. **初始化状态** — 单个内存中的对象/结构体。启动时渲染第一帧。
+2. **一次读取一个按键（或一行）**，分发给变更状态的处理函数。
+3. **在每次操作后重新渲染**完整帧 — 不要追加，替换。
+4. **循环直到退出。**
+
+整个帧应能放在一屏内。
+
+### 5. 使其通过一条命令即可运行
+
+在项目现有的任务运行器（`package.json` scripts、`Makefile`、`justfile`、`pyproject.toml`）中添加一个脚本。用户应该运行 `pnpm run <prototype-name>` 或等价命令 — 永远不需要记忆路径。
+
+如果宿主项目没有任务运行器，直接将命令放在原型的 README 顶部。
+
+### 6. 交付
+
+将运行命令交给用户。他们自己驱动；有趣的时刻是当他们说"等等，这不应该是可能的"或"嗯，我以为 X 会不一样" — 那些是*想法*中的 bug，这正是整个目的。如果他们想要添加新动作，就添加。原型会演化。
+
+### 7. 捕获答案
+
+当原型完成其使命后，问题的答案就是唯一值得保留的东西。如果用户在旁，询问他们学到了什么。如果不在，在原型的旁边留下一个 `NOTES.md`，以便答案可以在原型被删除之前填写（或由你填写，如果你观察了整个会话）。
+
+## 反模式
+
+- **不要添加测试。** 需要测试的原型不再是原型。
+- **不要连接到真实数据库。** 使用内存存储，除非问题明确与持久化相关。
+- **不要泛化。** 不要"如果我们以后想支持 X 怎么办"。原型回答一个问题。
+- **不要将逻辑和 TUI 混在一起。** 如果 reducer / 状态机引用了 `console.log`、提示或终端转义码，它就不再可移植。将 TUI 作为纯模块上的一个薄外壳。
+- **不要将 TUI 外壳发布到生产环境。** 外壳是为从终端手动驱动而优化的。其背后的逻辑模块才是值得保留的部分。