@namewta/speculo 0.2.15 → 0.3.0

package/template/workflows/specdev/common/dev-worktree/SKILL.md

@@ -18,121 +18,31 @@ description: 在 Speculo workflow change 内创建隔离 git worktree 进行开
 | 已在 worktree 中，未完成 | 继续开发，不重复创建 |
 | 用户要求 PR / 暂存 / 丢弃 | 阶段 B 按对应选项执行 |
 
----
-
 ## 阶段 A：创建 Worktree
 
-详细步骤见 [references/create.md](references/create.md)。核心流程：
-
-### A0. 检测现有隔离
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-SUPER=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
-```
-
-- `SUPER` 有值 → submodule 内，按普通仓库处理，不误判
-- `GIT_DIR != GIT_COMMON` 且非 submodule → 已在 worktree，跳到 A3 设置
-- `GIT_DIR == GIT_COMMON` → 主工作区，继续
-
-### A1. 命名与路径
-
-| 要素 | 值 |
-|------|-----|
-| 基础分支 | 当前分支（`git rev-parse --abbrev-ref HEAD`） |
-| change 分支 | `speculo/<workflow>/<change>` |
-| worktree 路径 | `{state-root}/<workflow>/changes/<change>/.worktree/` |
-
-分支或路径已存在 → 停止，不覆盖不复用。
-
-**前置检查：** `speculo/.speculo/` 必须被 git 跟踪——产物需随分支合并。若被忽略则降级为非 worktree 模式。
-
-### A2. 创建
-
-```bash
-git worktree add -b speculo/<workflow>/<change> {state-root}/<workflow>/changes/<change>/.worktree
-```
-
-确保 `.gitignore` 含 `.worktree/`；缺失则追加并提交。
-
-### A3. 项目设置与基线
-
-自动检测并安装依赖、运行基线测试：
-
-```bash
-[ -f package.json ] && (npm install 2>/dev/null || true)
-[ -f Cargo.toml ] && cargo build
-[ -f requirements.txt ] && pip install -r requirements.txt
-[ -f go.mod ] && go mod download
-# 跑基线测试
-```
+完整步骤见 [references/create.md](references/create.md)。概览：
 
-基线测试失败 → 报告并询问，未获许可不开始实现。
+1. **检测现有隔离** — 已在 worktree 则跳过创建；submodule 内按普通仓库处理
+2. **命名** — 分支 `speculo/<workflow>/<change>`；路径 `{state-root}/<workflow>/changes/<change>/.worktree/`；已存在则停止
+3. **创建** — `git worktree add -b …`；确保 `.gitignore` 含 `.worktree/`
+4. **基线** — 安装依赖并跑基线测试；失败则报告并询问
+5. **写回** — 将 `base_branch` / `change_branch` / `worktree_path` / `worktree_status: active` 写入 change 的 `.status.json`
 
-### A4. 写回状态
-
-将 `base_branch`、`change_branch`、`worktree_path`、`worktree_status: active` 写入 change 的 `.status.json`。
-
----
+**前置：** `speculo/.speculo/` 必须被 git 跟踪；若被忽略则降级为非 worktree 模式。
 
 ## 阶段 B：收尾合并
 
-详细步骤见 [references/finalize.md](references/finalize.md)。
-
-### B1. 验证测试
-
-跑项目测试套件。失败 → 停止，禁止合并/PR。
-
-### B2. 展示选项
-
-```
-实现已完成。你想怎么做？
-
-1. 本地合并回 <base-branch>（推荐，默认）
-2. 推送并创建 Pull Request
-3. 保持现状（稍后处理）
-4. 丢弃
+完整步骤见 [references/finalize.md](references/finalize.md)。概览：
 
-选哪个？
-```
+1. **验证测试** — 失败则停止，禁止合并/PR
+2. **展示选项** — 本地合并（默认）/ 创建 PR / 保持 / 丢弃
+3. **执行** — 本地合并顺序：checkout base → pull → `merge --no-ff` → 重跑测试 → `worktree remove` → `branch -d` → `prune` → 更新 `.status.json`
 
-分离 HEAD 时移除选项 1。用户未指定时默认选项 1。
-
-### B3. 执行 —— 顺序不可变
-
-**选项 1（本地合并）：**
-1. 合并到 base：`git checkout <base> && git pull && git merge --no-ff <change_branch>`
-2. 在合并结果上再跑测试
-3. 测试通过 → 从主仓库根删除 worktree：`git worktree remove <path>`
-4. 删除分支：`git branch -d <change_branch>`
-5. `git worktree prune`
-6. 更新 `.status.json`：`worktree_status: removed`
-
-**选项 2（PR）：** 推送分支、创建 PR，保留 worktree。
-**选项 3（保持）：** 不动，报告状态。
-**选项 4（丢弃）：** 确认后删除 worktree 和分支。
-
-合并冲突或测试失败 → 停止，保留现场，报告原因，不强推。
-
----
+合并冲突或测试失败 → 停止，保留现场。冲突解决见 `<Path>{roots.workflows}/specdev/common/resolving-merge-conflicts/SKILL.md</Path>`。
 
 ## 红线
 
-**绝不：**
-- 已在 worktree 时嵌套创建
-- 覆盖已有分支或路径
-- 测试失败时继续合并/PR
-- 合并结果未验证就删 worktree
-- 先删分支再 worktree remove（顺序：merge → remove worktree → delete branch）
-- 在 worktree 内部执行 `git worktree remove`
-- 未经确认执行破坏性操作
-- 强制推送
-
-**始终：**
-- 分支名：`speculo/<workflow>/<change>`
-- worktree 路径：change 目录下的 `.worktree/`
-- 创建后装依赖 + 基线测试
-- 收尾前验证测试
-- 合并成功后再清理
-- 清理后 `git worktree prune`
+- 已在 worktree 时不嵌套创建；不覆盖已有分支或路径
+- 测试失败时不合并/不发 PR；合并结果未验证不删 worktree
+- 清理顺序固定：merge → remove worktree → delete branch；在 worktree 内部不执行 `git worktree remove`
+- 破坏性操作须先确认；不强制推送

package/template/workflows/specdev/common/handoff/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: handoff
+description: "将一段对话或子代理会话压缩为一份交接文档，供另一个 agent 接手继续工作。适用于 Lead 压缩子代理实现上下文、会话移交、或任何需要把上下文浓缩为可持久化摘要的场景。"
+---
+
+# Handoff — 交接文档
+
+将当前对话（或指定的子代理会话）压缩为一份交接文档，使新的 agent 无需读取完整转录即可继续工作。
+
+## 内容要求
+
+交接文档包含以下部分：
+
+- **做了什么** —— 实现或完成的工作摘要
+- **关键决策** —— 做出的决策及理由；与 spec/plan 的任何偏差及原因
+- **验证状态** —— 测试结果摘要、已运行的检查
+- **产物引用** —— 相关 spec、ADR、commit、diff 的路径或 URL
+- **建议 skills** —— 建议接手 agent 调用的 skills 列表
+
+不重复已被其他产物（spec、方案、ADR、issue、commit、diff）覆盖的内容，改用路径或 URL 引用它们。
+
+清除任何敏感信息，如 API 密钥、密码或个人身份信息。
+
+如果调用方传入了对下一个会话重点的描述，据此定制文档内容。
+
+## 产物位置
+
+产物位置由调用方指定：
+
+- Lead 编排场景（子代理交接）：写入操作系统临时目录，关键信息由调用方回写到对应 ticket 文件（参见 `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` §2.2）
+- 调用方未指定时：写入 `<Path>{roots.state}/specdev/changes/{change}/handoff/<YYYY-MM-DD>-<topic>.md</Path>`
+
+## 路径引用规范
+
+文档中所有文件/文件夹引用使用**项目根目录**的相对路径。
+
+- ✅ `src/modules/auth/`
+- ✅ `speculo/.speculo/specdev/changes/<YYYY-MM-DD>-<topic>/spec.md`
+- ❌ `../../specdev/changes/...` — 相对于交接文档自身，脱离目录后不可定位
+- ❌ `auth` — 裸名，无法判断是目录/文件/子模块
+
+例外：skills 名称属于逻辑标识而非文件路径，不适用此规则。

package/template/workflows/specdev/common/triage/OUT-OF-SCOPE.md

@@ -20,7 +20,7 @@
 
 文件应以轻松、可读的风格编写 — 更像一份简短的设计文档，而非数据库条目。使用段落、代码示例和实例让理由清晰并对初次遇到它的人有用。
 
-```markdown
+````markdown
 # Dark Mode
 
 此项目不支持深色模式或面向用户的主题化。
@@ -50,7 +50,7 @@ interface ThemeConfig {
 - #42 — "添加深色模式支持"
 - #87 — "用于无障碍的夜间主题"
 - #134 — "深色主题选项"
-```
+````
 
 ### 文件命名
 

package/template/workflows/specdev/common/triage/SKILL.md

@@ -40,13 +40,13 @@ Triage 期间发布到 issue tracker 的每条评论或 issue **必须**以此
 
 每个经 triage 的 issue 应携带恰好一个类别角色和一个状态角色。如果状态角色冲突，标记它并在做任何其他操作之前询问维护者。
 
-这些是标准角色名称 —— issue tracker 中使用的实际标签字符串可能不同。映射关系应已提供给你 —— 如果没有，运行 `/setup-matt-pocock-skills`。
+这些是标准角色名称 —— issue tracker 中使用的实际标签字符串可能不同。映射关系读取 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`（若存在），否则直接使用角色名。
 
 状态转换：未标记的 issue 通常先进入 `needs-triage`；然后移动到 `needs-info`、`ready-for-agent`、`ready-for-human` 或 `wontfix`。当报告者回复后，`needs-info` 返回 `needs-triage`。维护者可随时覆盖 —— 标记看起来不寻常的转换并在继续之前询问。
 
 ## 调用方式
 
-维护者调用 `/triage` 并用自然语言描述他们想要什么。解读请求并行动。示例：
+维护者调用本 skill 并用自然语言描述他们想要什么。解读请求并行动。示例：
 
 - "展示需要我关注的内容"
 - "我们看看 #42"（issue 或 PR）
@@ -73,7 +73,7 @@ Triage 期间发布到 issue tracker 的每条评论或 issue **必须**以此
 
 3. **验证声明。** 在任何质询之前，检查声明是否成立。对于 bug，按报告者的步骤复现。对于 PR，确认 diff 做了它声称做的事情 —— checkout 它，运行相关测试或命令。报告结果：已确认（含代码路径）、未通过、或细节不足（强烈的 `needs-info` 信号）。已确认的验证会产生更强的 agent 摘要。
 
-4. **质询（如需要）。** 如果请求需要充实，同时运行 `/grilling` 和 `/domain-modeling` 技能 —— 逐个问题地进行质询，随着决策落地内联更新 `CONTEXT.md`/ADR。
+4. **质询（如需要）。** 如果请求需要充实，按 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` 逐个问题地进行质询，并按 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 随着决策落地内联更新 `CONTEXT.md`/ADR。
 
 5. **应用结果：**
    - `ready-for-agent` —— 发布 agent 摘要评论（[AGENT-BRIEF.md](AGENT-BRIEF.md)）。

package/template/workflows/specdev/common/improve-codebase-architecture/HTML-REPORT.md

@@ -1,125 +0,0 @@
-# HTML 报告格式
-
-架构审查渲染为一个独立的 HTML 文件，存放在操作系统临时目录中。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状的图表；手工构建的 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。混合使用两者 — 不要所有事情都依赖 Mermaid，否则会变得千篇一律。
-
-`{{config.defaults.report_language}}` 占位符由 runtime-context 输出的 `config` 对象填充，值来自 `speculo/config.json` 的 `defaults.report_language` 字段；若 config 文件不存在，默认值为 `"en"`。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状的图表；手工构建的 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。混合使用两者 — 不要所有事情都依赖 Mermaid，否则会变得千篇一律。
-
-## 脚手架
-
-```html
-<!doctype html>
-<html lang="{{config.defaults.report_language}}">
-  <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/workflows/specdev/common/improve-codebase-architecture/SKILL.md

@@ -1,66 +0,0 @@
----
-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 模式。