@namewta/speculo 0.1.21 → 0.2.0

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

@@ -0,0 +1,30 @@
+---
+name: prototype
+description: 构建一次性原型来回答设计问题。当用户想要快速验证状态模型或逻辑是否感觉正确，或探索 UI 应该长什么样时使用。
+---
+
+# 原型
+
+原型是**回答问题的一次性代码**。问题决定形态。
+
+## 选择分支
+
+识别正在回答哪个问题 — 从用户提示、周围代码或用户在线时通过询问来判断：
+
+- **"这个逻辑 / 状态模型感觉对吗？"** → [LOGIC.md](LOGIC.md)。构建一个微型交互式终端应用，将状态机推向难以在纸面上推理的用例。
+- **"这个应该长什么样？"** → [UI.md](UI.md)。在单一路由上生成几个截然不同的 UI 变体，通过 URL 搜索参数和浮动底栏切换。
+
+两个分支产生截然不同的产物 — 选错会浪费整个原型。如果问题确实模棱两可且用户不在线，默认选择更能匹配周围代码的分支（后端模块 → 逻辑；页面或组件 → UI），并在原型顶部陈述假设。
+
+## 适用于两者的规则
+
+1. **从一开始就是一次性的，并清楚标记。** 将原型代码放在它实际将被使用的位置附近（靠近它正在原型化的模块或页面旁边），这样上下文是明确的 — 但命名时让随意读者能看出它是原型，而非生产代码。对于一次性 UI 路由，遵循项目已有的任何路由约定；不要发明新的顶层结构。
+2. **一条命令运行。** 无论项目现有任务运行器支持什么 — `pnpm <名称>`、`python <路径>`、`bun <路径>` 等。用户必须能毫不费力地启动它。
+3. **默认不持久化。** 状态驻留在内存中。持久化是原型正在_检验_的东西，而非它应该依赖的东西。如果问题明确涉及数据库，用一个标记着"PROTOTYPE — 请清除我"的临时数据库或本地文件。
+4. **跳过润色。** 没有测试，没有超出使原型_可运行_的错误处理，没有抽象。重点是快速学到东西然后删除它。
+5. **呈现状态。** 每次操作后（逻辑）或每次变体切换时（UI），打印或渲染完整的相关状态，让用户看到什么发生了变化。
+6. **完成后删除或吸收。** 当原型回答了它的问题时，要么删除它，要么将已验证的决策整合到真实代码中 — 不要让它烂在仓库里。
+
+## 完成后
+
+_答案_是原型中唯一值得保留的东西。将其捕获到某个持久的地方（commit 消息、ADR、issue，或原型旁边的 `NOTES.md`），连同它所回答的问题。如果用户在线，这只是一个快速对话；如果不，留下占位符以便他们（或你，在下一轮）能在删除原型之前填上结论。

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

@@ -0,0 +1,112 @@
+# UI 原型
+
+在单个路由上生成**多个截然不同的 UI 变体**，通过一个浮动底栏切换。用户在浏览器中翻看各个变体，选择一个（或从每个变体中各取一些），然后丢弃其余。
+
+如果问题关乎逻辑/状态而非外观 — 走错分支了。请使用 [LOGIC.md](LOGIC.md)。
+
+## 何时适合使用这种形式
+
+- "这个页面应该长什么样？"
+- "我想在提交之前看看这个仪表盘的几种选项。"
+- "试试设置页面的不同布局。"
+- 任何用户本来会花一天时间在脑子里犹豫三种模糊草图的场景。
+
+## 两种子形式 — 强烈偏好子形式 A
+
+当 UI 原型**和应用的其余部分放在一起**时，判断起来要容易得多 — 真实的页头、真实的侧边栏、真实的数据、真实的密度。一个单独的临时路由是在真空中：每个变体在隔离状态下看起来都没问题。只要存在合理的既有页面来承载变体，就默认使用子形式 A。只有当原型确实没有附近的归宿时才使用子形式 B。
+
+### 子形式 A — 对现有页面的调整（首选）
+
+路由已经存在。变体在**同一路由**上渲染，通过 `?variant=` URL 搜索参数来控制。现有的数据获取、参数和认证全部保留 — 只有渲染部分切换。这是默认选择；除非有特定理由不这样做。
+
+如果原型是给某个还没有页面但*自然会放在某个页面内*的东西（仪表盘的新增部分、设置页面上的新卡片、现有流程中的新步骤）— 这仍然是子形式 A。在宿主页面中挂载变体。
+
+### 子形式 B — 新建页面（最后手段）
+
+仅适用于被原型化的东西确实没有可放入的现有页面时 — 例如一个全新的顶层界面，或一个无法合理嵌入任何地方的流程。
+
+按照项目已有的路由约定创建一个**临时路由** — 不要发明新的顶层结构。命名时要明显表明它是原型（例如在路径或文件名中包含 `prototype` 一词）。使用同样的 `?variant=` 模式。
+
+在采取子形式 B 之前，做一个合理性检查：是否确实没有可嵌入的现有页面？一个空路由会隐藏设计问题，而填充了内容的路由会暴露出来。
+
+两种子形式中，浮动底栏是相同的。
+
+## 流程
+
+### 1. 明确问题并确定 N 值
+
+默认为 **3 个变体**。超过 5 个就不再是截然不同而是变成噪音 — 以此为上限。
+
+在原型的存放位置或文件顶部注释中，用一行写下计划：
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+这无论用户在还是不在都能用。
+
+### 2. 生成截然不同的变体
+
+起草每个变体。对每个变体检查：
+
+- 页面的目的及其可访问的数据。
+- 项目的组件库 / 样式系统（TailwindCSS、shadcn、MUI、plain CSS 等）。
+- 清晰的导出组件名，例如 `VariantA`、`VariantB`、`VariantC`。
+
+变体必须是**结构上不同**的 — 不同的布局、不同的信息层级、不同的主要操作入口，而不仅仅是不同的颜色。三个略微调整的卡片网格不是 UI 原型，是壁纸。如果两个草稿太相似，用明确的"不要使用卡片网格"指导重新做一个。
+
+### 3. 将它们连接起来
+
+在路由上创建一个单一的切换器组件：
+
+```tsx
+// 伪代码 — 根据项目的框架进行调整
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+对于子形式 A（现有页面）：将所有现有的数据获取保留在切换器之上；只有渲染的子树按变体变化。
+
+对于子形式 B（新页面）：`/prototype/<name>` 下的临时路由挂载相同的切换器。
+
+### 4. 构建浮动切换器
+
+屏幕底部居中的小型固定位置栏，包含三部分：
+
+- **左箭头** — 切换到上一个变体（循环）。
+- **变体标签** — 显示当前变体键，如果变体导出了名称，也显示该名称。例如 `B — Sidebar layout`。
+- **右箭头** — 向前切换（循环）。
+
+行为：
+
+- 点击箭头更新 URL 搜索参数（使用框架的路由器 — Next 上用 `router.replace`，React Router 上用 `navigate` 等），使变体可分享且在刷新后保持。
+- 键盘：`←` 和 `→` 方向键也可切换。当 `<input>`、`<textarea>` 或 `[contenteditable]` 获得焦点时不要截获方向键。
+- 视觉上与页面区分开（例如高对比度的胶囊形状、微妙的阴影），使其明显不是正在评估的设计的一部分。
+- 在生产构建中隐藏 — 通过 `process.env.NODE_ENV !== 'production'` 或等价检查来控制，这样意外合并的原型不会将切换器发布给用户。
+
+将切换器放在单个共享组件中，以便两种子形式都能复用。将其放在项目中共享 UI 的存放位置。
+
+### 5. 交付
+
+展示 URL（以及 `?variant=` 键值）。用户有空时会翻看。有趣的反馈通常是**"我想要 B 的页头加上 C 的侧边栏"** — 那才是他们真正想要的设计。
+
+### 6. 捕获答案并清理
+
+一旦有变体胜出，写下是哪一个以及为什么（commit message、ADR、issue，或者如果离线运行且用户尚未回应，则在原型的旁边写一个 `NOTES.md`）。然后：
+
+- **子形式 A** — 删除落选的变体和切换器；将胜出者融合到现有页面中。
+- **子形式 B** — 将胜出的变体提升为真正的路由，删除临时路由和切换器。
+
+不要将变体组件或切换器遗留在代码中。它们腐烂很快，会困惑下一个阅读者。
+
+## 反模式
+
+- **仅在颜色或文案上有差异的变体。** 那是微调，不是原型。真正的变体在结构上有分歧。
+- **变体之间共享太多代码。** 共享的 `<Header>` 没问题；共享的 `<Layout>` 违背了目的。每个变体应能自由地抛弃布局。
+- **将变体连接到真实的变更操作。** 只读原型是可以的。如果一个变体需要变更操作，让它指向一个桩 — 问题是"这应该长什么样"，而不是"后端是否工作"。
+- **直接将原型提升到生产环境。** 变体代码是在原型约束下编写的（无测试、最小错误处理）。在融合时要正确地重写它。

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

@@ -0,0 +1,12 @@
+---
+name: research
+description: "针对高可信度一手来源调查问题，并将发现结果以 Markdown 文件记录到仓库中。适用于需要研究某个主题、收集文档或 API 信息、或委托阅读工作给后台 Agent 的场景。"
+---
+
+启动一个**后台 Agent** 来进行研究，这样你可以在它阅读时继续工作。
+
+其工作内容：
+
+1. 针对**一手来源**调查问题 —— 官方文档、源代码、规范、第一方 API —— 而不是基于这些来源的二次编写材料。将每个声明追溯到拥有该声明的来源。
+2. 将发现结果写入单个 Markdown 文件，为每个声明标注来源。
+3. 将文件保存到仓库已有的笔记存放位置；遵循现有约定，如果没有则放到合适的位置并说明存放位置。

package/template/vendor/matt-pocock/engineering/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "用于解决进行中的 git merge/rebase 冲突。"
+---
+
+1. **查看 merge/rebase 的当前状态**。检查 git 历史记录和冲突文件。
+
+2. **查找每个冲突的一手来源**。深入理解每个更改的原因以及原始意图。阅读 commit 消息、检查 PR、查看原始 issue/ticket。
+
+3. **解决每个冲突块。** 尽可能保留双方的意图。当不兼容时，选择与合并既定目标一致的一方，并注明权衡。**不要**发明新行为。务必解决；绝不执行 `--abort`。
+
+4. 查找项目的**自动化检查**并运行它们 —— 通常按类型检查、测试、格式化的顺序。修复合并破坏的任何内容。
+
+5. **完成 merge/rebase。** 暂存所有内容并提交。如果是 rebase，继续 rebase 过程直到所有 commits 都已 rebase。

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: setup-matt-pocock-skills
+description: "为本仓库配置工程化技能 —— 设置 issue tracker、triage 标签词汇表以及领域文档布局。在首次使用其他工程化技能之前运行一次。"
+disable-model-invocation: true
+---
+
+# 配置 Matt Pocock 技能
+
+搭建工程化技能所依赖的每仓库配置：
+
+- **Issue tracker** —— issue 的存放位置（默认使用 GitHub；也支持本地 markdown）
+- **Triage 标签** —— 五个标准 triage 角色使用的字符串
+- **领域文档** —— `CONTEXT.md` 和 ADR 的存放位置，以及读取它们的消费方规则
+
+这是一个提示驱动的技能，不是确定性脚本。先探索，展示发现结果，与用户确认，然后写入。
+
+## 流程
+
+### 1. 探索
+
+查看当前仓库以了解其初始状态。读取已有内容；不要假设：
+
+- `git remote -v` 和 `.git/config` —— 这是 GitHub 仓库吗？是哪一个？
+- 仓库根目录下的 `AGENTS.md` 和 `CLAUDE.md` —— 是否存在？其中是否已有 `## Agent skills` 章节？
+- 仓库根目录下的 `CONTEXT.md` 和 `CONTEXT-MAP.md`
+- `docs/adr/` 和所有 `src/*/docs/adr/` 目录
+- `docs/agents/` —— 此技能之前的输出是否已存在？
+- `.scratch/` —— 表示本地 markdown issue tracker 约定已在使用中的标志
+
+### 2. 展示发现结果并询问
+
+总结已存在的和缺失的内容。然后**逐项**引导用户完成三项决策 —— 展示一节，获得用户回答，然后进入下一节。不要一次抛出全部三项。
+
+假设用户不了解这些术语的含义。每节以简短解释开头（它是什么、这些技能为什么需要它、选择不同会有什么变化）。然后展示选项和默认值。
+
+**A 节 —— Issue tracker。**
+
+> 解释："Issue tracker" 是本仓库 issue 的存放位置。`to-tickets`、`triage`、`to-spec`、`qa` 等技能会从中读取和写入 —— 它们需要知道是调用 `gh issue create`、在 `.scratch/` 下写入 markdown 文件，还是遵循你描述的其他工作流。请选择你实际跟踪本仓库工作的地方。
+
+默认倾向：这些技能是为 GitHub 设计的。如果 `git remote` 指向 GitHub，则建议使用 GitHub。如果 `git remote` 指向 GitLab（`gitlab.com` 或自托管主机），则建议使用 GitLab。否则（或用户偏好其他方式），提供：
+
+- **GitHub** —— issue 存放在仓库的 GitHub Issues 中（使用 `gh` CLI）
+- **GitLab** —— issue 存放在仓库的 GitLab Issues 中（使用 [`glab`](https://gitlab.com/gitlab-org/cli) CLI）
+- **本地 markdown** —— issue 以文件形式存放在本仓库的 `.scratch/<feature>/` 下（适合个人项目或无远程仓库的场景）
+- **其他**（Jira、Linear 等）—— 请用户用一段话描述工作流；技能将记录为自由文本
+
+仅当用户选择了 **GitHub** 或 **GitLab** 时，才追问一个问题：
+
+> 解释：开源仓库经常以 Pull Request 形式收到功能请求，而不仅仅是 issue —— PR 是附带代码的 issue。如果开启此选项，`/triage` 会将*外部* PR 拉入同一队列，并对其应用与 issue 相同的标签和状态（协作者进行中的 PR 不受影响）。如果 PR 不是你接收请求的渠道，请关闭此选项。
+
+- **PR 作为请求渠道** —— 是 / 否（默认：否）。将答案记录到 `docs/agents/issue-tracker.md`。对于本地 markdown 和其他 tracker，跳过此问题 —— 没有 PR。
+
+**B 节 —— Triage 标签词汇表。**
+
+> 解释：当 `triage` 技能处理一个收到的 issue 时，它会将其移过一个状态机 —— 需要评估、等待报告者回复、可供 AFK agent 领取、可供人工处理、或不予处理。为此，它需要应用与你在 issue tracker 中*实际配置*的字符串相匹配的标签。如果你的仓库已使用不同的标签名称（例如 `bug:triage` 而不是 `needs-triage`），请在此处映射，以便技能应用正确的标签，而不是创建重复标签。
+
+五个标准角色：
+
+- `needs-triage` —— 维护者需要评估
+- `needs-info` —— 等待报告者回复
+- `ready-for-agent` —— 已完全明确，AFK 可用（agent 无需人工上下文即可领取）
+- `ready-for-human` —— 需要人工实现
+- `wontfix` —— 不予处理
+
+默认值：每个角色的字符串等于其名称。询问用户是否需要覆盖。如果他们的 issue tracker 没有现有标签，默认值即可。
+
+**C 节 —— 领域文档。**
+
+> 解释：一些技能（`improve-codebase-architecture`、`diagnosing-bugs`、`tdd`）会读取 `CONTEXT.md` 文件以了解项目的领域语言，以及 `docs/adr/` 以了解过去的架构决策。它们需要知道仓库是有一个全局上下文还是有多个（例如 mono repo 中前端/后端各有独立上下文），以便在正确的位置查找。
+
+确认布局：
+
+- **单上下文** —— 仓库根目录下一个 `CONTEXT.md` + `docs/adr/`。大多数仓库属于此类。
+- **多上下文** —— 根目录下 `CONTEXT-MAP.md` 指向各上下文的 `CONTEXT.md` 文件（通常为 mono repo）。
+
+### 3. 确认并编辑
+
+向用户展示以下内容的草稿：
+
+- 要添加到 `CLAUDE.md` / `AGENTS.md`（根据第 4 步的选择规则决定编辑哪个文件）的 `## Agent skills` 块
+- `docs/agents/issue-tracker.md`、`docs/agents/triage-labels.md`、`docs/agents/domain.md` 的内容
+
+让他们在写入之前编辑。
+
+### 4. 写入
+
+**选择要编辑的文件：**
+
+- 如果 `CLAUDE.md` 存在，编辑它。
+- 否则如果 `AGENTS.md` 存在，编辑它。
+- 如果两者都不存在，询问用户要创建哪一个 —— 不要替他们选择。
+
+当 `CLAUDE.md` 已存在时绝不创建 `AGENTS.md`（反之亦然）—— 始终编辑已存在的那个。
+
+如果所选文件中已有 `## Agent skills` 块，原地更新其内容，而不是追加重复块。不要覆盖用户对周围章节的编辑。
+
+该块的内容：
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[关于 issue 跟踪位置的一句话总结，以及外部 PR 是否作为 triage 渠道]。参见 `docs/agents/issue-tracker.md`。
+
+### Triage labels
+
+[关于标签词汇表的一句话总结]。参见 `docs/agents/triage-labels.md`。
+
+### Domain docs
+
+[关于布局的一句话总结 —— "单上下文"或"多上下文"]。参见 `docs/agents/domain.md`。
+```
+
+然后使用此技能文件夹中的种子模板作为起点，写入三个文档文件：
+
+- [issue-tracker-github.md](./issue-tracker-github.md) —— GitHub issue tracker
+- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) —— GitLab issue tracker
+- [issue-tracker-local.md](./issue-tracker-local.md) —— 本地 markdown issue tracker
+- [triage-labels.md](./triage-labels.md) —— 标签映射
+- [domain.md](./domain.md) —— 领域文档消费方规则 + 布局
+
+对于"其他"issue tracker，根据用户的描述从头编写 `docs/agents/issue-tracker.md`。
+
+### 5. 完成
+
+告诉用户配置已完成，以及哪些工程化技能现在将读取这些文件。提醒他们之后可以直接编辑 `docs/agents/*.md` —— 只有在需要切换 issue tracker 或从头重新配置时才需要重新运行此技能。

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/domain.md

@@ -0,0 +1,51 @@
+# 领域文档
+
+工程 skills 在探索代码库时应如何使用该仓库的领域文档。
+
+## 在探索之前，阅读这些
+
+- **`CONTEXT.md`**（位于仓库根目录），或
+- **`CONTEXT-MAP.md`**（位于仓库根目录，如果存在的话）— 它指向每个上下文的一个 `CONTEXT.md`。阅读与主题相关的每一个。
+- **`docs/adr/`** — 阅读涉及你要工作区域的 ADR。在多上下文仓库中，还要检查 `src/<context>/docs/adr/` 以获取上下文范围的决策。
+
+如果这些文件都不存在，**静默继续**。不要标记它们的缺失；不要预先建议创建它们。`/domain-modeling` skill（通过 `/grill-with-docs` 和 `/improve-codebase-architecture` 到达）在术语或决策实际被确定时延迟创建它们。
+
+## 文件结构
+
+单上下文仓库（大多数仓库）：
+
+```
+/
+├── 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/
+```
+
+## 使用术语表的词汇
+
+当你的输出中命名了一个领域概念（在 issue 标题、重构提案、假设、测试名称中），使用 `CONTEXT.md` 中定义的术语。不要偏离到术语表明确避免的同义词。
+
+如果你需要的概念尚未在术语表中，这是一个信号 — 要么你在发明项目不使用的语言（重新考虑），要么确实存在缺口（记录给 `/domain-modeling`）。
+
+## 标记 ADR 冲突
+
+如果你的输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
+
+> _与 ADR-0007（事件溯源订单）矛盾 — 但值得重新讨论，因为……_

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/issue-tracker-github.md

@@ -0,0 +1,45 @@
+# 问题跟踪器：GitHub
+
+该仓库的 Issues 和 PRD 以 GitHub issues 形式存在。所有操作使用 `gh` CLI。
+
+## 约定
+
+- **创建 issue**：`gh issue create --title "..." --body "..."`。多行正文使用 heredoc。
+- **阅读 issue**：`gh issue view <number> --comments`，通过 `jq` 过滤评论并获取标签。
+- **列出 issues**：`gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`，配合适当的 `--label` 和 `--state` 过滤器。
+- **评论 issue**：`gh issue comment <number> --body "..."`
+- **应用 / 移除标签**：`gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **关闭**：`gh issue close <number> --comment "..."`
+
+从 `git remote -v` 推断仓库 — 在 clone 仓库内运行时 `gh` 会自动推断。
+
+## 将 Pull requests 作为分类处理面
+
+**PR 作为请求处理面：否。** _（如果该仓库将外部 PR 视为功能请求，则设为 `yes`；`/triage` 读取此标志。）_
+
+当设为 `yes` 时，PR 与 issue 一样经过相同的标签和状态处理，使用 `gh pr` 等价命令：
+
+- **阅读 PR**：`gh pr view <number> --comments`，以及 `gh pr diff <number>` 查看 diff。
+- **列出待分类的外部 PR**：`gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments`，然后仅保留 `authorAssociation` 为 `CONTRIBUTOR`、`FIRST_TIME_CONTRIBUTOR` 或 `NONE` 的（排除 `OWNER`/`MEMBER`/`COLLABORATOR`）。
+- **评论 / 标签 / 关闭**：`gh pr comment`、`gh pr edit --add-label`/`--remove-label`、`gh pr close`。
+
+GitHub 在 issue 和 PR 之间共享同一个编号空间，因此一个裸的 `#42` 可能是两者之一 — 通过 `gh pr view 42` 解析，并回退到 `gh issue view 42`。
+
+## 当 skill 说"发布到问题跟踪器"时
+
+创建一个 GitHub issue。
+
+## 当 skill 说"获取相关工单"时
+
+运行 `gh issue view <number> --comments`。
+
+## Wayfinding 操作
+
+供 `/wayfinder` 使用。**地图**是一个包含**子** issue 作为工单的单个 issue。
+
+- **地图**：一个标记为 `wayfinder:map` 的单个 issue，包含 Notes / Decisions-so-far / Fog 正文。`gh issue create --label wayfinder:map`。
+- **子工单**：作为 GitHub 子 issue 链接到地图的 issue（在子 issue 端点上使用 `gh api`）。在子 issue 不可用的地方，将子工单添加到地图正文的任务列表中，并在子工单正文顶部放置 `Part of #<map>`。标签：`wayfinder:<type>`（`research`/`prototype`/`grilling`/`task`）。一旦认领，工单分配给驱动开发者。
+- **阻塞**：GitHub 的**原生 issue 依赖** — 规范的、UI 可见的表示。通过 `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>` 添加边，其中 `<blocker-db-id>` 是阻塞者的数字**数据库 id**（`gh api repos/<owner>/<repo>/issues/<n> --jq .id`，_不是_ `#number` 或 `node_id`）。GitHub 报告 `issue_dependencies_summary.blocked_by`（仅开放阻塞者 — 实时关卡）。在依赖不可用的地方，回退到子工单正文顶部的 `Blocked by: #<n>, #<n>` 行。当每个阻塞者都已关闭时，工单解除阻塞。
+- **前沿查询**：列出地图的开放子工单（`gh issue list --state open`，限定在地图的子 issue / 任务列表范围内），排除任何有开放阻塞者（`issue_dependencies_summary.blocked_by > 0`，或 `Blocked by` 行中的开放 issue）或被分配的；按地图顺序取第一个。
+- **认领**：`gh issue edit <n> --add-assignee @me` — 会话的首次写入。
+- **解决**：`gh issue comment <n> --body "<answer>"`，然后 `gh issue close <n>`，然后将上下文指针（gist + 链接）追加到地图的 Decisions-so-far 中。

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -0,0 +1,46 @@
+# 问题跟踪器：GitLab
+
+该仓库的 Issues 和 PRD 以 GitLab issues 形式存在。所有操作使用 [`glab`](https://gitlab.com/gitlab-org/cli) CLI。
+
+## 约定
+
+- **创建 issue**：`glab issue create --title "..." --description "..."`。多行描述使用 heredoc。传递 `--description -` 以打开编辑器。
+- **阅读 issue**：`glab issue view <number> --comments`。使用 `-F json` 获取机器可读输出。
+- **列出 issues**：`glab issue list -F json`，配合适当的 `--label` 过滤器。
+- **评论 issue**：`glab issue note <number> --message "..."`。GitLab 将评论称为"notes"。
+- **应用 / 移除标签**：`glab issue update <number> --label "..."` / `--unlabel "..."`。多个标签可以用逗号分隔或重复标志。
+- **关闭**：`glab issue close <number>`。`glab issue close` 不接受关闭评论，因此先用 `glab issue note <number> --message "..."` 发布说明，然后关闭。
+- **合并请求**：GitLab 将 PR 称为"merge requests"。使用 `glab mr create`、`glab mr view`、`glab mr note` 等 — 与 `gh pr ...` 形态相同，用 `mr` 替换 `pr`，用 `note`/`--message` 替换 `comment`/`--body`。
+
+从 `git remote -v` 推断仓库 — 在 clone 仓库内运行时 `glab` 会自动推断。
+
+## 将合并请求作为分类处理面
+
+**MR 作为请求处理面：否。** _（如果该仓库将外部合并请求视为功能请求，则设为 `yes`；`/triage` 读取此标志。）_
+
+当设为 `yes` 时，MR 与 issue 一样经过相同的标签和状态处理，使用 `glab mr` 等价命令：
+
+- **阅读 MR**：`glab mr view <number> --comments`，以及 `glab mr diff <number>` 查看 diff。
+- **列出待分类的外部 MR**：`glab mr list -F json`，然后仅保留作者不是项目成员/所有者的 MR（贡献者的 MR，而非维护者的进行中工作）。
+- **评论 / 标签 / 关闭**：`glab mr note`、`glab mr update --label`/`--unlabel`、`glab mr close`。
+
+与 GitHub 不同，GitLab 的 issue 和 MR 编号是分开的，因此一旦你知道维护者指的是哪个处理面，`#42` 就没有歧义。
+
+## 当 skill 说"发布到问题跟踪器"时
+
+创建一个 GitLab issue。
+
+## 当 skill 说"获取相关工单"时
+
+运行 `glab issue view <number> --comments`。
+
+## Wayfinding 操作
+
+供 `/wayfinder` 使用。**地图**是一个包含**子** issue 作为工单的单个 issue。
+
+- **地图**：一个标记为 `wayfinder:map` 的单个 issue，包含 Notes / Decisions-so-far / Fog 正文。`glab issue create --label wayfinder:map`。（在支持原生 epic 的 GitLab 层级上，epic 可以承载地图；标记的 issue 在任何地方都通用。）
+- **子工单**：一个 issue，在其描述顶部放置 `Part of #<map>`，标签为 `wayfinder:<type>`（`research`/`prototype`/`grilling`/`task`）。一旦认领，工单分配给驱动开发者。
+- **阻塞**：GitLab 的**原生阻塞链接** — 规范的、UI 可见的表示。通过 `/blocked_by #<n>` 快速操作添加，以 note 形式发布（`glab issue note <child> --message "/blocked_by #<blocker>"`）。原生阻塞链接是 Premium/Ultimate 功能；在免费层级（或不可用的地方），回退到描述顶部的 `Blocked by: #<n>, #<n>` 行。当每个阻塞者都已关闭时，工单解除阻塞。
+- **前沿查询**：`glab issue list -F json`，限定在地图的子工单范围内，排除任何有开放阻塞者的 — 指向开放 issue 的原生 `blocked_by` 链接（`glab api projects/:id/issues/:iid/links`），或 `Blocked by` 行中的开放 issue — 或被分配的；按地图顺序取第一个。
+- **认领**：`glab issue update <n> --assignee @me` — 会话的首次写入。
+- **解决**：`glab issue note <n> --message "<answer>"`，然后 `glab issue close <n>`，然后将上下文指针（gist + 链接）追加到地图的 Decisions-so-far 中。

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/issue-tracker-local.md

@@ -0,0 +1,30 @@
+# 问题跟踪器：本地 Markdown
+
+该仓库的 Issues 和 PRD 以 markdown 文件形式存储在 `.scratch/` 中。
+
+## 约定
+
+- 每个功能一个目录：`.scratch/<feature-slug>/`
+- PRD 为 `.scratch/<feature-slug>/PRD.md`
+- 实现 issue 为 `.scratch/<feature-slug>/issues/<NN>-<slug>.md`，从 `01` 开始编号
+- 分类状态记录为每个 issue 文件顶部附近的 `Status:` 行（参见 `triage-labels.md` 中的角色字符串）
+- 评论和对话历史追加到文件底部 `## Comments` 标题下
+
+## 当 skill 说"发布到问题跟踪器"时
+
+在 `.scratch/<feature-slug>/` 下创建一个新文件（如有需要则创建目录）。
+
+## 当 skill 说"获取相关工单"时
+
+读取引用路径处的文件。用户通常会直接传递路径或 issue 编号。
+
+## Wayfinding 操作
+
+供 `/wayfinder` 使用。**地图**是一个文件，每个工单有一个**子**文件。
+
+- **地图**：`.scratch/<effort>/map.md` — Notes / Decisions-so-far / Fog 正文。
+- **子工单**：`.scratch/<effort>/issues/NN-<slug>.md`，从 `01` 开始编号，正文中包含问题。`Type:` 行记录工单类型（`research`/`prototype`/`grilling`/`task`）；`Status:` 行记录 `claimed`/`resolved`。
+- **阻塞**：顶部附近的 `Blocked by: NN, NN` 行。当其列出的每个文件都处于 `resolved` 状态时，工单解除阻塞。
+- **前沿**：扫描 `.scratch/<effort>/issues/` 中处于开放、未阻塞且未认领状态的文件；按编号取第一个。
+- **认领**：设置 `Status: claimed` 并在任何工作开始前保存。
+- **解决**：在 `## Answer` 标题下追加答案，设置 `Status: resolved`，然后将上下文指针（gist + 链接）追加到 `map.md` 中地图的 Decisions-so-far 中。

package/template/vendor/matt-pocock/engineering/setup-matt-pocock-skills/triage-labels.md

@@ -0,0 +1,15 @@
+# 分类标签
+
+各 skills 使用五种规范的分类角色。本文件将这些角色映射到该仓库问题跟踪器中使用的实际标签字符串。
+
+| 在 mattpocock/skills 中的标签 | 在我们跟踪器中的标签 | 含义                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | 维护者需要评估此 issue                     |
+| `needs-info`               | `needs-info`         | 等待报告者提供更多信息                       |
+| `ready-for-agent`          | `ready-for-agent`    | 已完整定义，可供离线 Agent 执行              |
+| `ready-for-human`          | `ready-for-human`    | 需要人工实现                                |
+| `wontfix`                  | `wontfix`            | 不会采取行动                                |
+
+当 skill 提及某个角色（例如"应用 AFK-ready 分类标签"）时，使用此表中对应的标签字符串。
+
+编辑右侧列以匹配你实际使用的词汇。

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

@@ -0,0 +1,36 @@
+---
+name: tdd
+description: "测试驱动开发。适用于需要以测试先行方式构建功能或修复 bug、提及"红-绿-重构"循环、或需要集成测试的场景。"
+---
+
+# 测试驱动开发
+
+TDD 是红 → 绿循环。此技能是该循环的参考指南，确保该循环产出的测试值得保留：什么是一个好的测试、测试放在哪里、反模式、以及循环的规则。每个章节在每次循环中都适用 —— 在循环之前和循环期间查阅，而不是之后。
+
+在探索代码库时，读取 `CONTEXT.md`（如果存在），使测试名称和接口词汇与项目的领域语言保持一致，并尊重所涉及区域的 ADR。
+
+## 什么是好的测试
+
+测试通过公共接口验证行为，而不是实现细节。代码可以完全改变；测试不应该。一个好的测试读起来像规范 —— "用户可以使用有效购物车结账" 准确地告诉你存在什么能力 —— 并且在重构后能够存活，因为它不关心内部结构。
+
+参见 [tests.md](tests.md) 了解示例，[mocking.md](mocking.md) 了解 Mock 指南。
+
+## 接缝 —— 测试放置的位置
+
+**接缝（seam）** 是你进行测试的公共边界：你在该接口处观察行为而不触及内部。测试位于接缝处，绝不针对内部细节。
+
+**仅在预先约定的接缝处进行测试。** 在编写任何测试之前，写下要测试的接缝并与用户确认。没有在未确认的接缝处编写测试。你无法测试一切 —— 提前约定接缝可以确保测试工作集中在关键路径和复杂逻辑上，而不是每个边缘情况。
+
+问："公共接口是什么，我们应该在哪些接缝处进行测试？"
+
+## 反模式
+
+- **与实现耦合** —— mock 内部协作者、测试私有方法、或通过旁路通道验证（查询数据库而不是使用接口）。特征：当重构时代码行为未变但测试却失败了。
+- **同义反复** —— 断言以与代码相同的方式重新计算预期值（`expect(add(a, b)).toBe(a + b)`、以相同方式手动推导的快照、将常量断言为等于自身），因此它在构造上就必然通过，永远不可能与代码产生分歧。预期值必须来自独立的真相来源 —— 已知正确的字面量、手工计算示例、规范。
+- **水平切片** —— 先写所有测试，再写所有实现。批量测试验证的是*想象中*的行为：你测试的是事物的*形态*而非面向用户的行为，测试变得对真实变更不敏感，并且你在理解实现之前就锁定了测试结构。应采用**垂直切片** —— 一个测试 → 一个实现 → 重复，每个测试都是一颗**曳光弹**，响应上一个循环的反馈。
+
+## 循环的规则
+
+- **先红后绿。** 先写失败的测试，然后只写足以通过测试的代码。不要预测未来的测试或添加推测性功能。
+- **一次一个切片。** 每个循环一个接缝、一个测试、一个最小实现。
+- **重构不属于循环。** 它属于审查阶段（参见 `code-review` 技能），而不是红 → 绿实现循环的一部分。

package/template/vendor/matt-pocock/engineering/tdd/mocking.md

@@ -0,0 +1,59 @@
+# 何时使用 Mock
+
+仅在**系统边界**处使用 Mock：
+
+- 外部 API（支付、邮件等）
+- 数据库（有时 — 优先使用测试数据库）
+- 时间/随机性
+- 文件系统（有时）
+
+不要 Mock：
+
+- 你自己的类/模块
+- 内部协作者
+- 任何你控制的东西
+
+## 为可 Mock 性设计
+
+在系统边界处，设计易于 mock 的接口：
+
+**1. 使用依赖注入**
+
+将外部依赖从外部传入，而不是在内部创建：
+
+```typescript
+// 易于 mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// 难以 mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. 偏好 SDK 风格接口而非通用获取器**
+
+为每个外部操作创建特定的函数，而不是带有条件逻辑的通用函数：
+
+```typescript
+// 好：每个函数可以独立 mock
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// 坏：mock 需要在 mock 内部编写条件逻辑
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+SDK 方式的优点：
+- 每个 mock 返回一个特定的形态
+- 测试设置中无需条件逻辑
+- 更容易看出测试涉及哪些端点
+- 每个端点的类型安全