@namewta/speculo 0.1.21 → 0.2.1

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

@@ -0,0 +1,127 @@
+---
+name: wayfinder
+description: "规划超出一个 agent 会话容量的大块工作 —— 在 issue tracker 上建立一张调查 tickets 的共享地图，逐个解决它们，直到通往目标的路径清晰可见。"
+disable-model-invocation: true
+---
+
+一个模糊的想法出现了 —— 太大而无法放入单个 agent 会话，且笼罩在迷雾中：从当前状态到**目标**的路径尚不可见。寻路（Wayfinding）就是找到那条路，而非冲向目标。此技能在仓库的 issue tracker 上绘制路径作为一张**共享地图**，然后逐个处理其 tickets，直到路径变得清晰。
+
+目标因工作而异，命名目标是绘制地图的第一步 —— 它塑造每个 ticket。目标可能是一份待移交和迭代的 spec、一个在规划开始前需锁定的决策、或是一个原地完成的变更（如数据结构迁移）。地图是领域无关的 —— 工程工作、课程内容，任何符合此形态的内容都可以。
+
+## 规划，而非执行
+
+Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其**Notes**覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
+
+## 用名称引用
+
+每张地图和每个 ticket 都是一个 issue，因此它有一个**名称** —— 即其标题。在人类阅读的所有内容中 —— 叙述、地图的 Decisions-so-far —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。ID 和 URL 不会消失 —— 名称包裹着其链接 —— 但它们在名称*内部*，绝不是名称的替代品。
+
+## 地图
+
+地图是本仓库 issue tracker 上的单个 issue，标记为 `wayfinder:map` —— 是规范的产物。其 tickets 是地图的子 issues。
+
+地图是一个**索引**，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。
+
+**地图、其子 tickets、阻塞关系和前沿查询的物理存放位置取决于 tracker。** Issue tracker 应已提供给你 —— 如果没有，运行 `/setup-matt-pocock-skills`。查阅 tracker 文档的"寻路操作"章节，了解*此*仓库如何表达这些内容。如果未提供 tracker，则默认使用本地 markdown tracker。
+
+### 地图正文
+
+整个地图的低分辨率视图，每个会话加载一次。开放的 tickets **不**列出 —— 它们是通过查询找到的开放子 issues。
+
+```markdown
+## 目的地
+
+<到达此地图终点时的样子 —— 此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 ticket 之前以其为定位。>
+
+## 说明
+
+<领域；每个会话应咨询的技能；此工作的常设偏好>
+
+## 已做出的决策
+
+<!-- 索引 —— 每个已关闭 ticket 一行：足以判断相关性，然后放大链接查看 ticket 持有的详细信息 -->
+
+- [<已关闭 ticket 标题>](link) —— <答案的一句话概括>
+
+## 尚未明确
+
+<!-- 参见"战争迷雾"：范围内但你尚无法做成 ticket 的迷雾；随着前沿推进而升级 -->
+
+## 超出范围
+
+<!-- 参见"超出范围"：被裁定在目标之外的工作；已关闭，永不升级 -->
+```
+
+### Tickets
+
+每个 ticket 是地图的**子 issue**；tracker 的 issue ID 是其标识。其正文是问题，大小适配一个 100K token 的 agent 会话：
+
+```markdown
+## 问题
+
+<此 ticket 要解决的决策或调查>
+```
+
+每个 ticket 携带一个 `wayfinder:<type>` 标签 —— 以下之一：`research`、`prototype`、`grilling`、`task`（参见 [Ticket 类型](#ticket-类型)）。
+
+一个会话通过将 ticket **分配**给驱动地图的开发者来**领取**它，在开始任何工作**之前**分配，以便并发会话跳过它。该分配者*就是*领取标记：一个开放、未分配的 ticket 是未被领取的。
+
+阻塞关系使用 tracker 的**原生**依赖关系 —— 这很关键，因为它使前沿在 tracker 自己的 UI 中*可视化*呈现，因此人类无需打开地图就能看到哪些可以被领取。只有缺少原生阻塞功能的 tracker 才退回到正文约定。当一个 ticket 的所有阻塞 tickets 都已关闭时，该 ticket 是**未被阻塞的**；**前沿**是开放、未被阻塞、未被领取的子 issues —— 即已知的边界。
+
+答案不是正文的一部分 —— 它在解决时记录（参见[遍历地图](#遍历地图)）。解决 ticket 时创建的资产从 issue 链接，而非粘贴进去。
+
+## Ticket 类型
+
+每个 ticket 要么是 **HITL** —— 人在回路中，与一个代表自己发言的人类*一起*工作 —— 要么是 **AFK**，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。
+
+- **Research**（AFK）：阅读文档、第三方 API 或知识库等本地资源。创建一个 markdown 摘要作为链接资产。当需要当前工作目录之外的知识时使用。
+- **Prototype**（HITL）：通过制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或通过 /prototype 技能实现的 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
+- **Grilling**（HITL）：通过 /grilling 和 /domain-modeling 技能逐个问题进行的对话。默认情况。
+- **Task**（HITL 或 AFK）：在*决策*能够做出之前必须完成的手动工作 —— 没有需要决定、原型化或研究的内容，但讨论被阻塞直到完成。注册服务以便判断其 API、开通访问权限、移动数据以便看到其形态。这是唯一一个*执行*而非决策的类型 —— 它通过为决策解除阻塞来赢得其位置，而非通过交付目标。Agent 在可能的情况下独立驱动（AFK）；否则它交给人类一份精确的清单（HITL）。当工作完成时解决；答案记录已完成的工作以及后续 tickets 依赖的任何结果性事实（凭据位置、新 URL、行数）。
+
+## 战争迷雾
+
+地图是*刻意*不完整的：不要绘制你还看不到的内容。在活跃的 tickets 之外是**战争迷雾** —— 你能感觉到即将到来但尚无法确定的决策和调查的模糊视野，因为它们依赖于尚未解决的问题。解决一个 ticket 会清除它前方的迷雾，将任何现在可以明确的内容升级为新的 tickets —— 逐个进行，直到通往目标的路径清晰且没有剩余 tickets。
+
+地图的**尚未明确**章节记录这些模糊视野：待定的问题、后续重新审视的区域。它是朝向目标*方向*的未发现前沿 —— 此处的所有内容都在范围内，只是不够清晰以做成 ticket。根据视野允许的范围，尽可能松散或完整地书写；它同时也是协作者阅读工作方向的路标。
+
+**迷雾还是 ticket？** 判断标准是你是否现在就能精确地陈述问题 —— 而不是你现在是否能回答它。
+
+- **做成 ticket 当** 问题已经清晰 —— 即使它被阻塞，你尚不能行动。
+- **尚未明确当** 你还无法如此精确地表述它。不要将迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗糙，一个补丁可能在当前沿到达时升级为多个 tickets，或零个。
+
+**尚未明确**排除已决策的内容（Decisions so far）、已有的活跃 ticket 以及超出范围的内容（下一节）。
+
+## 超出范围
+
+迷雾只会向目标方向*聚集*。目标确定了范围，因此目标之外的工作是**超出范围**的 —— 它不是迷雾，也不属于**尚未明确**。它在地图上拥有自己的**超出范围**章节：你已自觉排除在*此*工作之外的工作。是范围而非清晰度让它落入此处。
+
+超出范围的工作永不升级 —— 前沿停在目标处 —— 因此只有在目标被重新划定后才会重新考虑，且以一个全新的工作而非恢复旧工作的形式出现。
+
+将某物裁定为超出范围是一个范围界定行为，而非路径上的一步。当已有的一个 ticket 被发现位于目标之外 —— 绘制地图时范围划分错误，或因某个解决方案而暴露 —— **关闭它**（一个已关闭的 ticket 明确地不在前沿上），并在**超出范围**章节留下一行：概括加上为何超出范围，链接已关闭的 ticket。它不会出现在**已做出的决策**中，该节记录实际走过的路径 —— 范围边界不是路径上的一步。
+
+## 调用方式
+
+两种模式。无论哪种，**每个会话绝不解决超过一个 ticket。**
+
+### 绘制地图
+
+用户带着模糊的想法调用。
+
+1. **命名目标。** 运行一次 `/grilling` 和 `/domain-modeling` 会话，以确定此地图正在寻路的目标 —— spec、决策或变更。目标确定了范围，因此先确定它。
+2. **绘制前沿。** 再次质询，这次**广度优先**：在整个空间上扩展而非深入任何一条线索，揭示开放的决策和现在可以迈出的第一步。**如果此过程没有浮现任何迷雾** —— 通往目标的路径已经清晰，整个旅程足够小到放入一个会话 —— 你不需要地图。停下来询问用户他们希望如何继续。
+3. **创建地图**（标签 `wayfinder:map`）：填写 Destination 和 Notes，Decisions so-far 为空，迷雾草拟进**尚未明确**。
+4. **创建你现在能明确的 tickets** 作为地图的子 issues —— 然后在**第二遍**中连接阻塞边（issues 需要首先有 ID 才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— **尚未明确**章节。
+5. 停止 —— 绘制地图是一个会话的工作；不要同时解决 tickets。
+
+### 遍历地图
+
+用户带着一张地图（URL 或编号）调用。Ticket 是**可选的** —— 不提供时，你选择下一个决策，而非用户。
+
+1. 加载**地图** —— 低分辨率视图，而非每个 ticket 的正文。
+2. 选择 ticket。如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket。**领取它**：在任何工作之前将它分配给你自己。
+3. 解决它 —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用 `## Notes` 块中指定的技能。如有疑问，使用 `/grilling` 和 `/domain-modeling`。
+4. 记录解决方案：发布答案作为**解决方案评论**，**关闭** issue，并在地图的 Decisions-so-far 中**追加一条上下文指针**。
+5. 添加新浮现的 tickets（先创建再连接）；升级答案使任何变得可明确的迷雾，从**尚未明确**中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，**将其裁定为超出范围**而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets。
+
+用户可以并行运行未被阻塞的 tickets，因此需预期其他会话会并发编辑 tracker。

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

@@ -0,0 +1,10 @@
+# 开发中
+
+仍在开发中的 skill。尚未准备好发布——预期会有粗糙的边界、破坏性变更和被放弃的实验。在毕业到稳定分类之前，它们被排除在插件和顶层 README 之外。
+
+- **[loop-me](./loop-me/SKILL.md)** — 在多个会话中将自己访谈成可实施的工作流规范，使用当前目录作为有状态的工作区。用户调用。
+- **[wizard](./wizard/SKILL.md)** — 生成一个交互式 bash 向导，引导用户完成手动流程（设置、一次性迁移、状态转换）——打开 URL、捕获值、写入 `.env` 和 GitHub Actions secrets。用户调用。
+- **[writing-beats](./writing-beats/SKILL.md)** — 将文章塑造成一段节拍的旅程，选择你自己的冒险风格。选择一个起始节拍，只写那个节拍，然后转向下一个，直到文章达到自然结束。
+- **[writing-fragments](./writing-fragments/SKILL.md)** — 挖掘式访谈会话，挖掘您的碎片——异质的写作素材——并将其追加到单个文档中，作为未来文章的原始材料。
+- **[writing-shape](./writing-shape/SKILL.md)** — 获取原始材料的 markdown 文件，逐段塑造成文章，在每一步争论格式选择。
+- **[claude-handoff](./claude-handoff/SKILL.md)** — 将当前对话移交给一个新的后台 agent，该 agent 通过 `claude --bg` 种子化的交接摘要立即接手工作。用户调用。

package/template/vendor/matt-pocock/in-progress/claude-handoff/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: claude-handoff
+description: "将当前对话交接给一个新的后台代理，由它立即接手继续工作。"
+argument-hint: "下一个会话将用于什么？"
+disable-model-invocation: true
+---
+
+编写当前对话的交接摘要，以便新的代理可以继续工作。不要保存摘要，而是启动一个后台代理，并将摘要作为其提示词：`claude --bg --name "<描述性名称>" "<交接摘要>"`。它在当前工作目录中启动并立即返回；用户通过 `claude agents` 管理它。
+
+始终传递 `-n`/`--name` 并附上描述性名称（例如 `--name "修复登录 bug"`）——它设置显示名称，该名称会出现在作业列表、会话选择器和终端标题中。
+
+在摘要中包含一个"建议技能"部分，建议代理应调用的技能。
+
+不要重复已在其他制品（PRD、计划、ADR、issue、commit、diff）中捕获的内容。改用路径或 URL 引用它们。
+
+脱敏处理任何敏感信息，如 API 密钥、密码或个人身份信息——摘要将成为代理的提示词。
+
+如果用户传递了参数，将其视为对下一个会话关注内容的描述，并据此定制摘要。

package/template/vendor/matt-pocock/in-progress/loop-me/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: loop-me
+description: "在此工作区内，反复追问我想要构建的工作流规格。"
+disable-model-invocation: true
+argument-hint: "一个要设计的工作流，或为空以自行查找一个"
+---
+
+运行一个有状态的 `/grilling` 会话，其唯一输出是**工作流**规格。使用追问规则——不留情面，一次一个问题，每个问题附带一个推荐答案——围绕以下词汇和目标展开。在追问过程中根据需要创建、编辑和删除规格。
+
+## 循环视角
+
+**循环**是用户生活中反复出现的模式：他们的职业生涯、他们的一周、他们的早晨、一个重复的活动。将生活想象成循环嵌套循环的结构，揭示了其活动的可预测性——这正是它们值得**委托**的原因。使用这一视角来发现有价值的循环，并提出用户尚未注意到的循环。
+
+**工作流**是一个循环的规格，被具体化为现实。你在一个循环上运行一个工作流——循环是它的运行实例。工作流存放在 `workflows/*.md` 中，是单一事实来源。
+
+## 词汇
+
+一套共享语言，仅在某个工作流需要时才使用——绝不是清单。**不强加任何结构要求**：一个工作流不需要 AI、不需要检查点、不需要时间表，除非追问表明它确实需要。
+
+- **触发器**——每次运行的启动方式：**事件**（一封新邮件、一个新 issue）或**时间表**（每天早晨）。事件触发通常更高效。
+- **检查点**——一个人工参与点，在此处询问用户进行验证或决策。有些工作流没有检查点，全自动运行；有些则完全不使用 AI。
+- **向右推**——将检查点尽可能推迟。在让人工参与之前完成最大量的工作，这样他们只被询问一次，在最后阶段，一切准备就绪。
+- **简报**——检查点呈现的内容：一份紧凑、可决策的摘要——产出了什么、为什么、以及指向资产本身的链接——永远不是原始输出。用户读的是简报，而不是草稿。阅读速度至关重要。
+
+## 完成标准
+
+当一个工作流规格可以让一个实现代理在无需提出任何问题的情况下构建时，它就是完成的。在此之前持续追问；只要还有问题未解决，就不算完成。
+
+## 工作区
+
+- `workflows/*.md`——每个工作流一个规格。
+- `NOTES.md`——关于用户世界的原始笔记：他们使用的工具、他们处理的信息渠道、以及他们对两者的称呼术语。当它为空或内容不足时，在指定任何内容之前，先采访用户了解他们的世界。将模糊术语精炼为规范术语，并记录在此。

package/template/vendor/matt-pocock/in-progress/wizard/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: wizard
+description: "生成一个交互式 bash 向导，引导人工用户完成一个手动流程——第三方设置、一次性迁移、A→B 状态转换——打开 URL、捕获值、确认每一步，并写入 .env 文件和 GitHub Actions secrets。"
+disable-model-invocation: true
+---
+
+# Wizard
+
+**向导**是一个 bash 脚本，一步一步引导人工用户完成一个手动流程——既繁琐又难以每次都向 AI 重新解释。它会打开每个 URL，准确说明要点击和复制什么，捕获值，将它们写入该去的地方（`.env`、GitHub secrets），在每个阶段确认，并显示还剩多少。它可以配置第三方服务、运行一次性迁移，或将项目从一种状态迁移到另一种状态。
+
+出色的 UX 已经由 [template.sh](template.sh) 解决了——带有剩余时间估算的进度显示、确认关卡、跨平台 URL 打开（包括 WSL）、隐藏的密钥输入、幂等的 `.env` 追加更新、`gh secret`/`gh variable` 写入，以及结束摘要。**你的工作仅仅是确定流程范围并编写其阶段。** `STAGES` 标记上方的库代码在每个向导中完全相同；这种一致性正是关键——永远不要手动编辑它。
+
+向导默认是一次性的——为单次运行构建，保存到临时目录或 `scripts/` 路径，任务完成后删除。仅在用户希望有一个可重复的设置流程并应保留在仓库中时才提交它。
+
+## 流程
+
+### 1. 确定流程范围
+
+梳理出人工用户必须执行的每个手动步骤以及沿途捕获的每个值。先阅读仓库——不要直接冷提问：
+
+- 对于设置：`.env`、`.env.example`、`.env.*`、`README`、`docker-compose*`、框架配置以及 `.github/workflows/*`（每个 `secrets.*` / `vars.*` 引用都是向导必须产出的值）。
+- 对于迁移或转换：当前状态、目标状态以及它们之间的不可逆操作。
+
+然后向用户展示有序的阶段列表以及每个阶段产出的值，并确认——他们可以添加、删除或重新排序。
+
+**完成标准：** 每个阶段按顺序命名，对于每个捕获的值，你知道 (a) 人工用户从哪里获取它，(b) 它被写到哪里（`.env`、GitHub secret、两者都有、或无处——某些阶段是纯操作），以及 (c) 它是密钥（隐藏输入）还是公开的。
+
+### 2. 映射每个阶段的路径
+
+对于每个阶段，写出人工用户遵循的精确路径：打开哪个 URL、在那里做什么、某个值在哪里显示、它填入哪个变量——例如"Dashboard → Developers → API keys → Reveal test key → 复制"。当你实际不确定当前 UI 或确切命令时，明确说明并询问用户或查阅文档——永远不要编造可能不存在的步骤。
+
+**完成标准：** 每个阶段都对应一个陌生人也能遵循的具体操作指引。
+
+### 3. 编写向导
+
+将 `template.sh` 复制到目标路径。用每个步骤一个 `stage` 替换示例阶段，按依赖顺序排列。使用库辅助函数——`stage`、`say`/`step`、`open_url`、`ask`/`ask_secret`、`write_env`、`set_secret`/`set_var`、`pause`/`confirm`——并将 `TOTAL_STAGES` 和 `TOTAL_MINUTES` 设置为诚实的估算值（这驱动剩余时间显示）。
+
+保持模板设定的标准：在请求输入值之前先打开 URL，对任何密钥使用 `ask_secret`，对每个持久化的值使用 `write_env`，仅对 CI 实际需要的值使用 `set_secret`，在任何不可逆操作前使用 `confirm`。每个 `stage` 清屏，仅显示当前步骤——让每个阶段专注一个任务，以确保人工用户需要的任何内容不会滚出屏幕。不要触碰标记上方的库代码。
+
+### 4. 验证并交付
+
+- `bash -n <script>`；如果可用，运行 `shellcheck`。
+- `chmod +x <script>`。
+- 不要自己端到端运行它——它会打开浏览器并等待人工输入。改为静态跟踪：步骤 1 中确定的每个值都被捕获并落入步骤 1 所说的位置，每个 `set_secret` 名称与 CI 中的 `secrets.*` 引用完全匹配。
+- 告诉用户如何运行它。如果它是一个可重复的设置流程，提交它并在 README 中添加链接，以便下一个用户运行脚本而不是询问 AI。

package/template/vendor/matt-pocock/in-progress/wizard/template.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+#
+# 向导（Wizard）——逐步引导用户完成手动流程。
+# 由 /wizard skill 生成。
+#
+# "STAGES" 标记以上部分是向导库：请勿手动编辑。
+# 在标记下方编写各阶段的步骤。
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# 向导库 — 令人愉悦、一致的用户体验。每个向导完全相同。
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# 作者在 stages 部分顶部设置这两个变量。
+TOTAL_STAGES=0
+TOTAL_MINUTES=0
+
+_STAGE_INDEX=0
+_MINUTES_ELAPSED=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # 本次运行写入 ENV_FILE 的 KEY
+WRITTEN_SECRET=() # 本次运行设置的 secret NAME
+SKIPPED=()        # 无法完成的操作（例如 gh 不可用）
+
+# _clear — 清空终端，使屏幕上仅显示当前步骤。当输出不是终端时
+# 不执行操作，使管道日志保持可读。
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "标题" — 开始画面：此向导做什么以及需要多长时间。
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages · about %s minutes%s\n\n' \
+    "$DIM" "$TOTAL_STAGES" "$TOTAL_MINUTES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later — it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "名称" <分钟> — 清屏，然后宣布一个阶段并显示
+# 进度 + 剩余时间。清屏使屏幕上仅保留当前步骤。
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  local remaining=$((TOTAL_MINUTES - _MINUTES_ELAPSED))
+  (( remaining < 0 )) && remaining=0
+  _MINUTES_ELAPSED=$((_MINUTES_ELAPSED + ${2:-0}))
+  printf '\n%s%s▸ Stage %s/%s · %s%s  %s(~%s min left)%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET" "$DIM" "$remaining" "$RESET"
+}
+
+# say "..." — 一行普通指令。
+say()  { printf '  %s\n' "$1"; }
+# step "..." — 用户在浏览器中执行的一个带编号的操作。
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL — 在用户的浏览器中打开，跨平台，包括 WSL。
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser — visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser — visit it manually: $url"
+}
+
+# pause "消息" — 等待用户确认已完成手动部分。
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "问题" — y/N 确认；成功返回 yes。
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY — 返回 ENV_FILE 中 KEY 的当前值（如果存在）。
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "提示" — 读取值到 $KEY。重新运行时提供现有 .env 值
+# 作为默认值（按 Enter 保留）。可见输入（非机密）。
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "提示" — 类似 ask，但输入被隐藏。
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE — 将 KEY=VALUE upsert 到 ENV_FILE（创建文件；
+# 替换任何现有行）。幂等。
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE — 通过 gh 设置 GitHub Actions 仓库 secret。
+# 如果 gh 不可用或未认证，回退到警告（并记录）。
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name — gh not ready; set it later"
+}
+
+# set_var NAME VALUE — 设置 GitHub Actions 仓库变量（非机密）。
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name — gh not ready; set it later"
+}
+
+# finish — 清屏，然后显示配置完成的总览。
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES — 在此编写步骤。用户执行的每个操作对应一个 stage()。
+# 替换下面的示例。将两个总数设置为与你编写的阶段匹配。
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+TOTAL_MINUTES=5
+
+banner "Stripe setup"
+
+# ── 示例阶段：替换为你的实际步骤 ───────────────────────────────────────────
+stage "Stripe — API keys" 5
+say "We'll grab your Stripe test keys and store them for local dev + CI."
+open_url "https://dashboard.stripe.com/test/apikeys"
+step "On the API keys page, copy the Publishable key (starts pk_test_)."
+ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
+step "Click 'Reveal test key' on the Secret key row, then copy it."
+ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
+write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"
+write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
+set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"   # CI 需要这一个
+# ──────────────────────────────────────────────────────────────────────────
+
+finish

package/template/vendor/matt-pocock/in-progress/writing-beats/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: writing-beats
+description: "写作，利用阶段——将原始素材组装成一段节拍旅程，在每个节拍依赖某个术语之前先将其落地。"
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+用户已经传递（或将传递）一个包含原始素材的 markdown 文件。这是**利用**阶段：探索已完成，素材堆已固定——承诺一条贯穿路径，并挖掘素材堆来填充每个节拍。
+
+如果用户没有说明将文章保存到哪里，询问一次并记住路径。
+
+然后运行一个逐节拍的旅程，选择你自己的冒险风格：
+
+1. **确定前置条件。** 在任何节拍之前，与用户确认读者走进来时已经知道什么——从一开始就已经**落地**的概念。其他所有概念必须由某个节拍落地后，后续节拍才能使用。参见[落地](#grounding)。
+2. 从原始素材中撰写 2-3 个候选**起始节拍**。每个是文章的不同入口。每个只能依赖已落地的概念；注明每个节拍落地了哪些新概念。在写入文章文件之前向用户展示这些节拍。用户选择一个。预览该选择解锁了哪些节拍——就像让用户看到路径前方的一小段路。
+3. 用户选定起始节拍后，将**仅那个节拍**写入文章文件。一个节拍可以是一句话，也可以是几段——取决于该节拍自然该是什么。到此为止。
+4. 从磁盘重新读取文章文件。然后提供 2-3 个候选**下一个节拍**——文章从当前状态可以转向的不同方向。每个必须从当前已落地集合可达；注明每个落地了什么。
+5. 循环步骤 3-5，直到文章达到自然的结尾。
+
+</what-to-do>
+
+<supporting-info>
+
+## 落地
+
+每个**概念**必须在一个节拍依赖它之前被**落地**：读者要么走进来时就知道它，要么在之前的节拍中遇到它。一个试图使用未落地概念的节拍会使读者迷失——这是旅程中唯一不能做的动作。单元是概念，而非表达它的词语：即使没有行话出现，一个节拍也可能依赖读者尚未掌握的想法。当一个概念有一个名称——一个**术语**——落地它意味着同时传达想法和术语。
+
+概念通过两种方式之一被落地：
+
+- **前置**——在第一个节拍之前就已落地。读者自带。在开始时固定。
+- **引入**——某个节拍建立它，从那时起，它对之后的所有节拍都是落地的。
+
+因此，每个节拍做两件事：它**依赖**已经落地的概念，并且它**落地**新的概念。维护一个已落地概念的运行列表，并在每个节拍落地后更新它。
+
+这正是塑造选择你自己的冒险风格的关键。一个候选节拍只有当它所依赖的一切都已经落地时才是可达的；选择一个落地了概念 X 的节拍，就解锁了所有等待 X 的节拍。当你提供下一个节拍时，它们必须都从当前已落地集合可达——并说明每个落地了什么，以便用户看到它打开了哪些路径。
+
+重要的杠杆是：你让什么成为前置条件，以及你让什么在文章内部落地。前置条件要求太多会排斥不具备这些条件的读者；在内部落地太多则会导致前面的节拍淹没在定义中。在确定前置条件时与用户解决这个问题，并在一个有吸引力的节拍被发现依赖一个尚未落地的概念时重新审视——解决方案要么是在它之前插入一个落地节拍，要么是将该概念提升为前置条件。
+
+## 什么是节拍
+
+节拍是旅程中的一个动作。它做一件事——设定一个场景、表达一个观点、提出一个问题、插入一段旁白、转换一个角度。然后它停下，将读者留在下一个节拍可以转向的地方。
+
+节拍的大小取决于它的需要：
+
+- 一句话，如果那就是整个动作（"然后三周什么也没发生。"）。
+- 一小段，如果动作需要铺垫。
+- 多段，如果节拍是一个自包含的小品、论证或示例。
+
+如果一个"节拍"需要五段文字和三个小标题，那它不是节拍——是两个节拍粘在一起。拆分它。
+
+## 从素材堆中取材
+
+从原始素材堆中取材料来填充每个节拍。你可以改写、拆分、重组或引用。素材堆是一个采石场。
+
+## 结束旅程
+
+当旅程完成时文章就结束了——而不是当素材堆被清空时。大多数素材堆会有剩余的碎片没有进入文章。这是正常的；这正是拥有多于所需原始素材的意义所在。
+
+## 写作节奏
+
+- 一次追加一个节拍。不要提前写。
+- 在每次写入之前从磁盘重新读取文章文件。绝对保留用户的编辑。
+- 如果用户大幅编辑了之前的节拍，让它改变后续内容。
+- 如果用户说"重写那个节拍"或"回去试试不同的第 3 节拍"，照做——在原位置编辑，其余内容保持不变。
+
+</supporting-info>

package/template/vendor/matt-pocock/in-progress/writing-fragments/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: writing-fragments
+description: "写作，探索阶段——挖掘原始碎片，尚无结构。"
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+这是纯粹的**探索**：拓宽可能写出的内容空间，而不承诺结构——承诺是_利用_阶段，那是另一个技能的工作。运行一个追问会话，产出碎片，无情地采访用户关于他们想写的任何内容。强加阶段、大纲或文章结构不在本技能范围内。
+
+当碎片从对话的任一方出现时，将它们追加到一个 markdown 文件中。
+
+如果用户没有传递路径，询问一次将文档保存到哪里，然后在剩余会话中记住它。
+
+从用户说的第一句话开始捕获碎片，包括初始提示词。
+
+首次写入时，在顶部放一个 H1 作为工作标题（可以后续更改），除此之外什么都不放——没有元数据、没有目录、没有日期。
+
+</what-to-do>
+
+<supporting-info>
+
+## 什么是碎片
+
+碎片是任何可能存活到最终文章中的文本片段。它必须_对作者可读_——作者能明白它的意思——但它不需要定义其术语，也不需要让陌生读者理解。标准是"这是一段好文字吗？"，而不是"这是一个自包含的论证吗？"
+
+碎片刻意保持异质性。可以成为碎片的示例：
+
+- 一句精辟的话，你想在某个地方使用但还不知道用在哪里。
+- 一个带有一行理由的断言。
+- 一个小品：一件发生过的事、一段代码片段、一个场景、一个类比。
+- 一个半成品的想法："关于 X 感觉像 Y，以后再展开。"
+- 一段引用、一句对话、一句听到的话。
+- 一组凭感觉聚集在一起的相关观察。
+- 一句抱怨、一句坦白、一句点睛之笔。
+- 一个**引导词**——一个紧凑的隐喻或造词，整篇文章可以挂靠其上（一个为思想命名的术语，就像_曳光弹_或_战争迷雾_命名了整个模式）。
+
+这其中，引导词是最有价值的碎片。它是承重的：在探索阶段命名正确的词，之后它会塑造结构、过渡和标题——在整个利用阶段持续产生回报。当对话围绕一个反复出现的想法时，推动为其创造一个词。
+
+小说家的日记是范本：多年的无结构观察，后来被开采为原始素材。碎片就是观察。
+
+## 文件格式
+
+```markdown
+# 工作标题
+
+第一个碎片放在这里。
+
+它可以有多段。它可以包含列表、代码、引用——无论碎片自然采取什么形态。
+
+---
+
+第二个碎片。
+
+---
+
+> 用户想保留的一句引用。
+
+对它的反应。
+
+---
+
+- 一组相关观察
+- 凭感觉聚集在一起
+- 并希望彼此靠近
+```
+
+碎片之间用水平线（`\n---\n`）分隔。正文中不使用标题。不使用标签。除了添加顺序外没有其他排序。
+
+## 写作节奏
+
+静默追加。不要为每个碎片征求许可。顺带提及你添加了什么（"加上那个"），但不要用保存对话框打断对话。
+
+在每次写入之前：从磁盘重新读取文件。用户可能在两次交互之间编辑、重新排序或删除了碎片——保留他们的更改。永远不要覆盖文件；仅追加（或者，如果用户要求，在原位置编辑特定碎片）。
+
+用户可以随时说"删掉最后一个"、"把那个改得更犀利些"、"把那两个合并"。将这些视为一级指令。
+
+</supporting-info>