@namewta/speculo 0.2.6 → 0.2.9

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

@@ -1,156 +0,0 @@
----
-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 约定已在使用中的标志
-- `speculo/config.json` —— 全局配置文件是否已存在？若存在，读取其内容
-
-### 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）。
-
-**D 节 —— 语言与配置偏好。**
-
-> 解释：Speculo 使用 `speculo/config.json` 存储全局配置，包括 AI 与用户的交互语言、报告生成语言、以及持久化路径覆盖。其他 commands 和 workflows 在初始化时读取此文件以自动选择语言和确认策略。
-
-询问用户：
-
-- **交互语言** —— Speculo 与用户交互时使用的语言。选项：`zh-CN`（简体中文）、`en`（英文）。默认：`zh-CN`。
-- **报告语言** —— AI 生成产物（HTML 报告、Markdown 文档、issue 正文）的默认语言。默认与交互语言相同。
-
-### 3. 确认并编辑
-
-向用户展示以下内容的草稿：
-
-- 要添加到 `CLAUDE.md` / `AGENTS.md`（根据第 4 步的选择规则决定编辑哪个文件）的 `## Agent skills` 块
-- `docs/agents/issue-tracker.md`、`docs/agents/triage-labels.md`、`docs/agents/domain.md` 的内容
-- `speculo/config.json` 的内容（若不存在则新建）
-
-让他们在写入之前编辑。
-
-### 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`。
-
-如果 `speculo/config.json` 不存在，根据 D 节的用户选择创建：
-
-```jsonc
-{
-  "schema_version": 1,
-  "language": "<用户选择的交互语言>",
-  "persistence": {
-    "root_override": null
-  },
-  "defaults": {
-    "confirm_before_external_write": true,
-    "report_language": "<用户选择的报告语言>"
-  }
-}
-```
-
-如果 `speculo/config.json` 已存在，仅更新用户本次修改的字段，保留其他现有值。
-
-### 5. 完成
-
-告诉用户配置已完成，以及哪些工程化技能现在将读取这些文件。提醒他们之后可以直接编辑 `docs/agents/*.md` —— 只有在需要切换 issue tracker 或从头重新配置时才需要重新运行此技能。

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

@@ -1,40 +0,0 @@
-# 领域文档
-
-工程 skills 在探索代码库时应如何使用该仓库的领域文档。
-
-## 布局：单上下文
-
-```
-{state_root}/knowledge/
-├── CONTEXT.md                          ← 项目领域术语与概念（待 domain-modeling 创建）
-├── adr/                                ← 架构决策记录（待 domain-modeling 创建）
-│   └── NNNN-slug.md
-└── domain.md                           ← 本文件
-```
-
-## 路径解析规则
-
-**本文件描述的路径均为相对于 `{state_root}/knowledge/` 的逻辑路径。** 实际写入时由 Speculo persistence 层映射到 `{state_root}/knowledge/` 命名空间下。
-
-- `CONTEXT.md` → `{state_root}/knowledge/CONTEXT.md`
-- `adr/` → `{state_root}/knowledge/adr/`
-- `{state_root}` 由 runtime-context 解析，默认为 `speculo/.speculo/<workflow>/`
-
-Vendor skills（如 domain-modeling）描述的是通用项目布局（"仓库根目录下的 CONTEXT.md"），这是正确的通用行为。本文件作为 Speculo 适配层，负责将这些通用路径翻译到 Speculo 持久化命名空间内。当 vendor skill 指示"在仓库根目录创建 CONTEXT.md"时，实际写入路径为 `{state_root}/knowledge/CONTEXT.md`。
-
-## 在探索之前
-
-- **`CONTEXT.md`**（位于 knowledge/ 命名空间内，由 domain-modeling skill 创建）—— 项目领域语言
-- **`adr/`** —— 涉及工作区域的 ADR
-
-如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`domain-modeling` skill 在术语或决策实际被确定时延迟创建它们。
-
-## 使用术语表的词汇
-
-输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到术语表明确避免的同义词。如果需要的新概念尚未在术语表中，记录给 `domain-modeling`。
-
-## 标记 ADR 冲突
-
-如果输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
-
-> _与 ADR-NNNN 矛盾 — 但值得重新讨论，因为……_

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

@@ -1,45 +0,0 @@
-# 问题跟踪器：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

@@ -1,46 +0,0 @@
-# 问题跟踪器：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

@@ -1,30 +0,0 @@
-# 问题跟踪器：本地 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

@@ -1,15 +0,0 @@
-# 分类标签
-
-各 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

@@ -1,36 +0,0 @@
----
-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

@@ -1,59 +0,0 @@
-# 何时使用 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 返回一个特定的形态
-- 测试设置中无需条件逻辑
-- 更容易看出测试涉及哪些端点
-- 每个端点的类型安全

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

@@ -1,77 +0,0 @@
-# 好的测试与坏的测试
-
-## 好的测试
-
-**集成风格**：通过真实接口测试，而非 mock 内部部件。
-
-```typescript
-// 好：测试可观察的行为
-test("user can checkout with valid cart", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
-
-特征：
-
-- 测试用户/调用方关心的行为
-- 仅使用公共 API
-- 经受住内部重构
-- 描述 WHAT（做什么），而非 HOW（怎么做）
-- 每个测试一个逻辑断言
-
-## 坏的测试
-
-**实现细节测试**：与内部结构耦合。
-
-```typescript
-// 坏：测试实现细节
-test("checkout calls paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-危险信号：
-
-- Mock 内部协作者
-- 测试私有方法
-- 断言调用次数/顺序
-- 重构时测试失败但没有行为变化
-- 测试名称描述 HOW 而非 WHAT
-- 通过外部手段而非接口进行验证
-
-```typescript
-// 坏：绕过接口进行验证
-test("createUser saves to database", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// 好：通过接口进行验证
-test("createUser makes user retrievable", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```
-
-**同义反复测试**：预期值重述了实现，因此测试在构造上就通过了。
-
-```typescript
-// 坏：预期值以与代码计算方式相同的方式重新计算
-test("calculateTotal sums line items", () => {
-  const items = [{ price: 10 }, { price: 5 }];
-  const expected = items.reduce((sum, i) => sum + i.price, 0);
-  expect(calculateTotal(items)).toBe(expected);
-});
-
-// 好：预期值是独立的、已知的字面量
-test("calculateTotal sums line items", () => {
-  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
-});
-```

package/template/vendor/matt-pocock/engineering/to-spec/SKILL.md

@@ -1,75 +0,0 @@
----
-name: to-spec
-description: "将当前对话转化为 spec 并发布到项目 issue tracker —— 无需访谈，仅综合你们已讨论过的内容。"
-disable-model-invocation: true
----
-
-此技能读取当前对话上下文和代码库理解，产出一份 spec（你可能也称之为 PRD）。不要访谈用户 —— 仅综合你已经知道的内容。
-
-Issue tracker 和 triage 标签词汇表应已提供给你 —— 如果没有，运行 `/setup-matt-pocock-skills`。
-
-## 流程
-
-1. 探索仓库以了解代码库的当前状态（如果尚未这样做）。在整个 spec 中使用项目的领域词汇表，并尊重所涉及区域的任何 ADR。
-
-2. 草拟你将用于测试该功能的接缝（seam）。优先使用现有接缝而不是新建。使用尽可能高层的接缝。如果需要新接缝，在尽可能高的层级提出。代码库中的接缝越少越好 —— 理想数量是 1 个。
-
-与用户确认这些接缝是否符合他们的期望。
-
-3. 使用以下模板编写 spec，然后发布到项目 issue tracker。应用 `ready-for-agent` triage 标签 —— 无需额外 triage。
-
-<spec-template>
-
-## 问题陈述
-
-从用户视角描述用户面临的问题。
-
-## 解决方案
-
-从用户视角描述问题的解决方案。
-
-## 用户故事
-
-一个详细的、编号的用户故事列表。每个用户故事格式为：
-
-1. 作为 <角色>，我希望 <功能>，以便 <收益>
-
-<user-story-example>
-1. 作为手机银行客户，我希望查看账户余额，以便做出更明智的消费决策
-</user-story-example>
-
-用户故事列表应极其详尽，涵盖该功能的所有方面。
-
-## 实现决策
-
-已做出的实现决策列表。可包含：
-
-- 将构建/修改的模块
-- 这些模块将被修改的接口
-- 开发者的技术澄清
-- 架构决策
-- Schema 变更
-- API 契约
-- 具体交互
-
-不要包含具体文件路径或代码片段。它们可能很快过时。
-
-例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联在相关决策中，并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
-
-## 测试决策
-
-已做出的测试决策列表。包含：
-
-- 什么构成好测试的描述（只测试外部行为，不测试实现细节）
-- 哪些模块将被测试
-- 测试的先例（即代码库中类似类型的测试）
-
-## 超出范围
-
-描述此 spec 超出范围的内容。
-
-## 补充说明
-
-关于该功能的任何补充说明。
-
-</spec-template>