@namewta/speculo 0.2.2 → 0.2.6

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -0,0 +1,132 @@
+---
+id: specdev/init-setup
+type: workflow-entry
+workflow: specdev
+name: 初始化设置
+description: 为 specdev workflow 配置变更追踪、领域文档布局、状态标签和语言偏好。首次使用其他 specdev works 前运行一次。
+keywords: [初始化, 配置, 设置, setup]
+---
+
+# 初始化设置
+
+为 specdev workflow 搭建本地持久化配置——变更追踪约定、领域文档布局、状态标签映射和交互语言偏好。这是一个提示驱动的入口，先探索，展示发现结果，与用户确认，然后写入。
+
+所有配置产物写入 `<Path>{roots.state}/specdev/</Path>` 下：
+
+- **变更追踪约定** → `<Path>{roots.state}/specdev/.config/tracking.md</Path>` —— 变更以本地 markdown 目录形式管理
+- **领域文档布局** → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>` —— 三文件模型（ADR/LOG/CONTEXT）的读写规则
+- **状态标签映射** → `<Path>{roots.state}/specdev/.config/status-labels.md</Path>` —— 五个标准 triage 角色的标签字符串
+- **语言与配置** → `<Path>{roots.state}/specdev/config.json</Path>` —— 交互语言、报告语言和持久化设置
+
+首次使用 specdev 的任意 work 之前运行一次。之后可直接编辑 `<Path>{roots.state}/specdev/.config/</Path>` 下的文件进行调整，无需重新运行。
+
+## 流程
+
+### 1. 探索
+
+查看当前仓库以了解 specdev 的初始配置状态。读取已有内容；不要假设：
+
+- `<Path>{roots.state}/specdev/config.json</Path>` —— 全局配置文件是否已存在？若存在，读取其内容
+- `<Path>{roots.state}/specdev/.config/tracking.md</Path>` —— 变更追踪约定是否已配置？
+- `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>` —— 领域文档布局是否已配置？
+- `<Path>{roots.state}/specdev/.config/status-labels.md</Path>` —— 状态标签映射是否已配置？
+- `<Path>{roots.state}/specdev/status.json</Path>` —— 当前是否有活跃变更？
+- `<Path>{roots.state}/specdev/changes/</Path>` —— 已有哪些变更目录？
+- `<Path>{roots.state}/specdev/archive/</Path>` —— 归档了哪些历史变更？
+
+总结已存在的和缺失的内容。
+
+**完成标准**：当前 `<Path>{roots.state}/specdev/</Path>` 和已有配置已摸底，已存在的和缺失的内容已明确。
+
+然后进入配置阶段——**逐项**引导用户完成四项决策：展示一节，获得用户回答，然后进入下一节。不要一次抛出全部四项。每个配置阶段之前，简短解释它是什么、specdev 的 works 为什么需要它、选择不同会有什么变化。
+
+### 2. 变更追踪
+
+specdev 的变更追踪使用**本地 markdown** 作为唯一选项。变更以目录形式存放在 `<Path>{roots.state}/specdev/changes/<YYYY-MM-DD>-<topic>/</Path>` 下，通过 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组追踪当前活跃变更。
+
+变更追踪是 specdev 记录工作进度的地方。当你运行 `S-spec`、`I-implement`、`G-grill-with-docs` 等 work 时，它们会将产物写入当前变更目录。与 GitHub Issues 或 Jira 不同，本地 markdown 方式让所有工作产物（需求文档、设计决策、实现记录）与代码存放在同一仓库中，无需网络连接，且完全由 git 版本控制。
+
+确认用户理解此约定后，将详细规则写入 `<Path>{roots.state}/specdev/.config/tracking.md</Path>`。
+
+详细约定参见 `<Path>{roots.workflows}/specdev/I-init-setup/tracking-convention.md</Path>`。
+
+**完成标准**：变更追踪约定已确认并写入 `<Path>{roots.state}/specdev/.config/tracking.md</Path>`。
+
+### 3. 领域文档布局
+
+specdev 使用**单上下文**布局。每个变更目录 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下维护三个文件：
+
+- **CONTEXT.md** —— 项目领域术语与概念
+- **ADR.md** —— 架构决策记录（本变更相关的决策）
+- **LOG.md** —— 设计决策日志（按时间顺序记录每次设计调整）
+
+部分 specdev work（如 `G-grill-with-docs`、`I-implement`）在探索代码库时会读取 CONTEXT.md 了解项目的领域语言，以及 ADR.md 了解过去的架构决策。单上下文意味着整个 specdev workflow 共享一套术语和决策记录，所有变更目录下的三文件模型均遵循相同约定。
+
+确认用户理解此布局后，将消费方规则写入 `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`。
+
+详细约定参见 `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout.md</Path>`。
+
+**完成标准**：领域文档布局已确认——三文件（ADR/LOG/CONTEXT）持久化到 `<Path>{roots.state}/specdev/changes/{change}/</Path>`，消费方规则已写入。
+
+### 4. 状态标签
+
+specdev 使用五个标准状态角色来追踪工作项的生命周期：
+
+| 角色 | 默认标签 | 含义 |
+|------|---------|------|
+| `needs-triage` | `needs-triage` | 需要评估 |
+| `needs-info` | `needs-info` | 等待补充信息 |
+| `ready-for-agent` | `ready-for-agent` | 可执行（agent 无需额外人工上下文即可领取） |
+| `ready-for-human` | `ready-for-human` | 需人工处理 |
+| `wontfix` | `wontfix` | 不处理 |
+
+当 `T-tickets`、`W-wayfinder` 等 work 处理工作项时，它们会将工作项移过一个状态机——需要评估、等待补充、可供 agent 领取、需人工处理、或不予处理。状态标签是这些状态在持久化文件中的字符串表示。默认每个角色的标签等于其名称，如果你的项目已有不同命名习惯，可以在此映射。
+
+确认用户是否接受默认标签，或需要覆盖为自定义字符串。将映射写入 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`。
+
+详细约定参见 `<Path>{roots.workflows}/specdev/I-init-setup/status-labels.md</Path>`。
+
+**完成标准**：状态标签映射已确认并写入 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`。
+
+### 5. 语言与配置
+
+询问用户两项语言偏好：
+
+- **交互语言** —— specdev 与用户交互时使用的语言。选项：`zh-CN`（简体中文）、`en`（英文）。默认：`zh-CN`。
+- **报告语言** —— AI 生成产物（Markdown 文档、issue 正文、报告）的默认语言。默认与交互语言相同。
+
+specdev 使用 `<Path>{roots.state}/specdev/config.json</Path>` 存储全局配置。所有 specdev works 在启动时读取此文件以自动选择交互语言和确认策略，无需每次手动指定。
+
+将配置写入 `<Path>{roots.state}/specdev/config.json</Path>`：
+
+```jsonc
+{
+  "schema_version": 1,
+  "language": "<用户选择的交互语言>",
+  "persistence": {
+    "root_override": null
+  },
+  "defaults": {
+    "confirm_before_external_write": true,
+    "report_language": "<用户选择的报告语言>"
+  }
+}
+```
+
+如果 `<Path>{roots.state}/specdev/config.json</Path>` 已存在，仅更新用户本次修改的字段，保留其他现有值。
+
+**完成标准**：语言偏好和配置已写入 `<Path>{roots.state}/specdev/config.json</Path>`。
+
+---
+
+配置完成后，提醒用户可以直接编辑 `<Path>{roots.state}/specdev/.config/</Path>` 下的文件进行调整。只有在需要从头重新配置时才需重新运行本入口。
+
+## 子文件引用
+
+以下子文件包含各配置阶段的详细约定和消费方规则，仅在对应步骤进入时加载：
+
+| 文件 | 内容 | 触发条件 |
+|------|------|---------|
+| `<Path>{roots.workflows}/specdev/I-init-setup/tracking-convention.md</Path>` | 本地 markdown 变更追踪的读写约定 | 步骤 2「变更追踪」进入时 |
+| `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout.md</Path>` | 单上下文三文件模型的路径解析和消费方规则 | 步骤 3「领域文档布局」进入时 |
+| `<Path>{roots.workflows}/specdev/I-init-setup/status-labels.md</Path>` | 五个标准状态角色的标签字符串映射 | 步骤 4「状态标签」进入时 |

package/template/workflows/specdev/I-init-setup/domain-layout.md

@@ -0,0 +1,90 @@
+# 领域文档布局
+
+specdev 各 work 在探索代码库时应如何使用该仓库的领域文档。
+
+## 布局：单上下文
+
+specdev 使用单上下文布局——整个 workflow 共享一套领域术语和架构决策。每个变更目录 `changes/<change>/` 下维护三文件模型：
+
+```
+{state_root}/changes/<change>/
+├── CONTEXT.md                          ← 项目领域术语与概念
+├── ADR.md                              ← 本变更相关的架构决策记录
+└── LOG.md                              ← 设计决策日志（按时间顺序记录每次设计调整）
+```
+
+- **CONTEXT.md** —— 定义项目特有的领域概念和术语表。各 work 在输出中引用领域概念时以本文档为准。
+- **ADR.md** —— 记录本变更范围内的架构决策（格式：`## ADR-NNNN: 标题`）。如果变更跨多个上下文，决策记录在触发该决策的变更目录下。
+- **LOG.md** —— 按时间倒序记录每次设计调整、决策变更及其原因。格式：`## YYYY-MM-DD HH:MM — 标题`，每次记录包含：**决策**（做什么）、**原因**（为什么）、**影响**（影响哪些 work/文件）。
+
+> 与 vendor 技能（如 domain-modeling）描述的通用仓库布局不同，specdev 将所有领域文档限定在 `changes/<change>/` 目录内。当 vendor skill 指示"在仓库根目录创建 CONTEXT.md"时，specdev 的适配层将其翻译为写入 `{state_root}/changes/<change>/CONTEXT.md`。
+
+## 路径解析规则
+
+**本文件描述的路径均为相对于 `{state_root}` 的逻辑路径。** 实际写入时由 Speculo persistence 层映射到 `{roots.state}/specdev/` 命名空间下。
+
+- `CONTEXT.md` → `{state_root}/changes/<current_change>/CONTEXT.md`
+- `ADR.md` → `{state_root}/changes/<current_change>/ADR.md`
+- `LOG.md` → `{state_root}/changes/<current_change>/LOG.md`
+- `{state_root}` 由 runtime-context 解析为 `{roots.state}/specdev/`
+- `<current_change>` 由 `status.json` 的 `active` 数组确定（取第一个活跃变更）
+
+## 在探索之前
+
+当 specdev work 需要领域上下文时，按以下顺序读取：
+
+1. **`CONTEXT.md`**（位于当前变更目录内）—— 项目领域语言，由 `G-grill-with-docs` 或 `I-implement` 在探索代码库时创建或更新
+2. **`ADR.md`**（位于当前变更目录内）—— 涉及当前变更的架构决策，由 `G-grill-with-docs` 在讨论架构时更新
+3. **`LOG.md`**（位于当前变更目录内）—— 设计决策历史，由各 work 在设计调整时追加记录
+
+如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`G-grill-with-docs` 和 `I-implement` 在领域知识或决策实际被确定时延迟创建它们。
+
+## 使用术语表的词汇
+
+输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到术语表明确避免的同义词。如果需要的新概念尚未在术语表中，记录到 `CONTEXT.md` 并通知用户。
+
+如果 `CONTEXT.md` 不存在，在首次需要时由当前 work 创建骨架：
+
+```markdown
+# CONTEXT — <change 主题>
+
+## 领域术语
+
+| 术语 | 定义 | 别名 / 避免使用 |
+|------|------|----------------|
+| ... | ... | ... |
+
+## 边界上下文
+
+<!-- 如有多个子域，在此划分边界 -->
+```
+
+## 标记 ADR 冲突
+
+如果输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
+
+> _与 `<Path>{roots.state}/specdev/changes/<change>/ADR.md</Path>` 中的 ADR-NNNN 矛盾 — 但值得重新讨论，因为……_
+
+同时将冲突记录追加到 `LOG.md`：
+
+```markdown
+## YYYY-MM-DD HH:MM — ADR 冲突标记
+
+- **冲突**: 当前建议与 ADR-NNNN 矛盾
+- **原因**: <重新讨论的理由>
+- **影响**: 如采纳新方案，需更新 ADR.md 并记录迁移路径
+```
+
+## 写入 LOG.md
+
+每次设计调整或决策变更时，在 `LOG.md` 顶部追加一条记录（时间倒序）：
+
+```markdown
+## YYYY-MM-DD HH:MM — <简短标题>
+
+- **决策**: <做了什么设计决定>
+- **原因**: <为什么做这个决定>
+- **影响**: <影响哪些 work、哪些文件、哪些后续步骤>
+```
+
+`LOG.md` 不同于 `ADR.md`：ADR 记录的是相对稳定的架构决策，LOG 记录的是日常设计调整的过程脉络。如果某条 LOG 记录具有长期参考价值，提取为 ADR。

package/template/workflows/specdev/I-init-setup/status-labels.md

@@ -0,0 +1,54 @@
+# 状态标签
+
+specdev 各 work 使用五种规范的状态角色来追踪工作项的生命周期。本文件将这些角色映射到持久化文件中使用的实际标签字符串。
+
+| 角色 | 标签 | 含义 |
+|------|------|------|
+| `needs-triage` | `needs-triage` | 需要评估 —— 维护者需要判断此工作项的性质、优先级和归属 |
+| `needs-info` | `needs-info` | 等待补充信息 —— 工作项描述不足，等待报告者或需求方提供更多上下文 |
+| `ready-for-agent` | `ready-for-agent` | 可执行 —— 已完整定义，agent 无需额外人工上下文即可领取并开始工作 |
+| `ready-for-human` | `ready-for-human` | 需人工处理 —— 工作项需要人工判断、审批或执行，不适合 agent 自动处理 |
+| `wontfix` | `wontfix` | 不处理 —— 经评估后决定不予处理，保留记录以供追溯 |
+
+## 使用方式
+
+当 work 提及某个角色（例如"标记为需要评估"、"应用 ready-for-agent 状态"）时，使用此表中对应的标签字符串写入持久化文件。
+
+标签字符串写入位置取决于具体 work：
+
+- **T-tickets** —— 写入工作项文件（`tickets/NN-<slug>.md`）顶部的 `Status:` 行
+- **W-wayfinder** —— 写入 `wayfinder/map.md` 中工作项的状态标记
+- **其他 work** —— 在变更目录的相应产物文件中以 frontmatter 或元数据行形式记录
+
+## 状态流转
+
+```
+needs-triage ──→ needs-info ──→ needs-triage ──→ ready-for-agent
+     │                                                │
+     │                                                ├──→ ready-for-human
+     │                                                │
+     └──────────────────→ wontfix ←──────────────────┘
+```
+
+- `needs-triage` → `needs-info`：评估后发现信息不足，退回补充
+- `needs-triage` → `ready-for-agent`：已完整定义，可供 agent 执行
+- `needs-triage` → `ready-for-human`：需要人工处理
+- `needs-triage` → `wontfix`：决定不予处理
+- `needs-info` → `needs-triage`：补充信息后重新评估
+- `ready-for-agent` → `wontfix`：执行过程中发现不再适用
+
+## 自定义标签
+
+如果你的项目已有不同的标签命名习惯（例如使用 `bug:triage` 而不是 `needs-triage`），编辑右侧的"标签"列以匹配你实际使用的字符串。左侧的"角色"列不变——各 work 通过角色名引用状态，不直接依赖标签字符串。
+
+例如，如果你的项目使用中文标签：
+
+| 角色 | 标签 |
+|------|------|
+| `needs-triage` | `待评估` |
+| `needs-info` | `待补充` |
+| `ready-for-agent` | `可执行` |
+| `ready-for-human` | `需人工` |
+| `wontfix` | `不处理` |
+
+确保标签字符串在实际使用位置（tickets 文件、wayfinder 地图等）保持一致。

package/template/workflows/specdev/I-init-setup/tracking-convention.md

@@ -0,0 +1,58 @@
+# 变更追踪：本地 Markdown
+
+specdev workflow 的变更以 markdown 目录形式存储在 `{roots.state}/specdev/changes/` 中。
+
+## 约定
+
+- 每个变更一个目录：`{roots.state}/specdev/changes/<YYYY-MM-DD>-<topic>/`
+  - 例如：`changes/2026-07-21-add-auth-layer/`
+- 当前活跃变更通过 `{roots.state}/specdev/status.json` 的 `active` 数组追踪
+- 归档变更移至：`{roots.state}/specdev/archive/YYYY-MM/<change>/`
+  - 例如：`archive/2026-07/2026-07-21-add-auth-layer/`
+- 变更目录内的工作产物由各 work 定义，典型结构：
+  ```
+  changes/<YYYY-MM-DD>-<topic>/
+  ├── CONTEXT.md      ← 领域术语与概念（由 domain-modeling 或 G-grill-with-docs 创建/更新）
+  ├── ADR.md          ← 架构决策记录（由 G-grill-with-docs 或 I-implement 创建/更新）
+  ├── LOG.md          ← 设计决策日志（按时间顺序记录每次设计调整）
+  ├── spec.md         ← 需求规格（由 S-spec 创建）
+  ├── tickets/        ← 工作项（由 T-tickets 创建）
+  │   └── NN-<slug>.md
+  └── wayfinder/      ← 路线图（由 W-wayfinder 创建）
+      └── map.md
+  ```
+- `status.json` 结构：
+  ```jsonc
+  {
+    "schema_version": 1,
+    "workflow": "specdev",
+    "active": [
+      "2026-07-21-add-auth-layer"
+    ]
+  }
+  ```
+
+## 当 work 说"发布到变更目录"时
+
+在 `{roots.state}/specdev/changes/<change>/` 下创建或更新指定文件。如果变更目录尚未加入 `active` 数组，将其追加到 `status.json` 的 `active` 中。
+
+例如：`S-spec` 说"将规格发布到变更目录" → 写入 `<Path>{roots.state}/specdev/changes/<change>/spec.md</Path>`。
+
+## 当 work 说"获取当前变更"时
+
+读取 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组，获取当前活跃变更列表。如果存在多个活跃变更，提示用户选择目标变更。如果无活跃变更，提示用户先运行 `S-spec` 或 `I-init-setup` 创建变更。
+
+## 当 work 说"归档变更"时
+
+将变更目录从 `{roots.state}/specdev/changes/<change>/` 移动到 `{roots.state}/specdev/archive/YYYY-MM/<change>/`（YYYY-MM 取变更日期中的年月），并从 `status.json` 的 `active` 数组中移除。
+
+## Wayfinding 操作
+
+供 `W-wayfinder` 使用。**地图**是一个文件，每个工作项有一个**子**文件。
+
+- **地图**：`{roots.state}/specdev/changes/<change>/wayfinder/map.md` —— Notes / Decisions-so-far / Fog 正文。
+- **子工单**：`{roots.state}/specdev/changes/<change>/tickets/NN-<slug>.md`，从 `01` 开始编号，正文中包含问题。`Type:` 行记录工单类型（`research` / `prototype` / `grilling` / `task`）；`Status:` 行记录 `claimed` / `resolved`。
+- **阻塞**：顶部附近的 `Blocked by: NN, NN` 行。当其列出的每个文件都处于 `resolved` 状态时，工单解除阻塞。
+- **前沿**：扫描 `tickets/` 中处于开放、未阻塞且未认领状态的文件；按编号取第一个。
+- **认领**：设置 `Status: claimed` 并在任何工作开始前保存。
+- **解决**：在 `## Answer` 标题下追加答案，设置 `Status: resolved`，然后将上下文指针（gist + 链接）追加到 `map.md` 中地图的 Decisions-so-far 中。

package/template/workflows/specdev/INDEX.md

@@ -0,0 +1,81 @@
+---
+id: specdev
+type: workflow
+workflow: specdev
+name: SpecDev Workflow
+description: 软件研发全流程——从初始化设置、设计访谈（带 ADR/LOG/CONTEXT）、spec 编写、ticket 拆分、寻路到 TDD 实现与双轴审查
+keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现, 审查]
+---
+
+# SpecDev Workflow
+
+本文件是 `specdev` 的唯一入口——包含运行时根、持久化约定、启动协议、状态字段、路径分配、副作用边界以及 work 条目索引。
+
+## 运行时根
+
+- **workflow 根**（`{roots.workflows}`）解析为 `<Path>{roots.workflows}/specdev/</Path>`，指向 work 入口和子文件所在目录
+- **state 根**（`{roots.state}`）解析为 `<Path>{roots.state}/specdev/</Path>`，指向持久化状态和变更产物所在目录
+
+## 持久化约定
+
+在 state 根下维护以下结构：
+
+| 名称 | 路径 | 说明 |
+|------|------|------|
+| 状态索引 | `<Path>{roots.state}/specdev/status.json</Path>` | workflow 全局状态 |
+| 活跃变更 | `<Path>{roots.state}/specdev/changes/</Path>` | 进行中的 change 产物（ADR、LOG、CONTEXT、spec、tickets、map 等） |
+| 永久 ADR | `<Path>{roots.state}/specdev/adr/</Path>` | changes 中经确认后的 ADR 提升至此，始终反映当前架构决策现状 |
+| 永久词汇表 | `<Path>{roots.state}/specdev/context/</Path>` | changes 中经确认后的 CONTEXT 提升至此，始终反映当前领域术语现状 |
+| 变更归档 | `<Path>{roots.state}/specdev/archive/</Path>` | 已完成并归档的历史 change，按 YYYY-MM/<change>/ 组织 |
+
+`status.json`、`changes/`、`archive/` 为固定骨架，由 `speculo init` 创建。`adr/` 和 `context/` 为确认后创建——当 changes 中的 ADR、CONTEXT 经确认符合当前现状后，提升到这两个目录，始终保持与项目当前状态一致。
+
+## 启动协议
+
+1. **解析运行时** — 解析 workspace 配置和 workflow/state roots。已解析时复用。
+2. **选择 change** — 读取 `<Path>{roots.state}/specdev/status.json</Path>`：
+   - 用户指定 → 直接使用
+   - 唯一活跃 change → 直接使用
+   - 无活跃 → 创建 `changes/<YYYY-MM-DD>-<kebab-topic>/`，注册到 `active` 数组
+   - 多个候选 → 先消歧
+
+## 状态字段
+
+`<Path>{roots.state}/specdev/status.json</Path>` 包含以下字段：
+
+- **`schema_version`**（数字）— 状态 schema 版本号，当前为 1
+- **`workflow`**（字符串）— workflow 标识，固定为 `"specdev"`
+- **`active`**（字符串数组）— 当前活跃 change 的目录名列表，每个元素为 `"YYYY-MM-DD-<topic>"` 格式。空数组表示无活跃 change
+- **`current_work`**（字符串或 null）— 当前正在执行的 work id，如 `"specdev/grill-with-docs"`。无正在执行的 work 时为 null
+- **`work_history`**（对象数组）— work 调用记录，每条包含：
+  - `work_id` — work 标识
+  - `started_at` — 开始时间（ISO 8601）
+  - `completed_at` — 完成时间（ISO 8601），未完成时为 null
+  - `result` — 完成结果，如 `"completed"`、`"aborted"`
+  - `artifacts` — 产物的项目相对路径列表
+
+## 路径分配
+
+1. 产物写入当前 change 目录（`<Path>{roots.state}/specdev/changes/{change}/</Path>`）
+2. 领域文档（ADR.md、LOG.md、CONTEXT.md）由 `G-grill-with-docs` 维护
+3. Spec、tickets、map 等产物由对应 work 写入当前 change 目录
+4. 项目代码、测试写入项目相对路径，验证指针记录到 change
+5. 所有引用使用 `<Path>{roots.workflows}/specdev/...</Path>` 或 `<Path>{roots.state}/specdev/...</Path>` 格式，不引用外部
+
+## 副作用边界
+
+确认前不得执行：提交代码、合并/删除 worktree、发布/部署。结果记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。敏感值不得写入。
+
+## Work 条目
+
+<!-- AUTO-INDEX-START -->
+
+- **D-diagnose-bugs** — 诊断：针对疑难 bug 建立诊断循环——构建紧凑反馈回路、复现最小化、可证伪假设排名、插桩定位根因，确认后移交 I-implement 修复。
+- **G-grill-with-docs** — 设计访谈（带文档）：无情访谈打磨设计，同时持续产出 ADR.md、LOG.md 和 CONTEXT.md 三个领域文档。在设计讨论中捕获术语定义、记录架构决策、保存完整设计轨迹。
+- **I-implement** — 实现：基于 spec 或 tickets 实现工作——以深层模块设计原则指导架构、以 TDD 红绿循环驱动编码、以双轴审查把关质量。
+- **I-init-setup** — 初始化设置：为 specdev workflow 配置变更追踪、领域文档布局、状态标签和语言偏好。首次使用其他 specdev works 前运行一次。
+- **S-spec** — 编写 Spec：将当前对话综合为一份完整的 spec 文档，包含问题陈述、解决方案、用户故事、实现决策和测试决策，持久化到变更目录。
+- **T-tickets** — 拆分 Tickets：将 spec 或计划拆分为一组曳光弹式垂直切片 tickets，每个声明阻塞边，持久化到变更目录。支持宽重构的扩展-收缩排序。
+- **W-wayfinder** — 寻路：为超出单次会话容量的大块工作绘制共享地图，逐个解决调查 tickets 直到通往目标的路径清晰可见。支持研究和决策型 ticket 类型。
+
+<!-- AUTO-INDEX-END -->

package/template/workflows/specdev/S-spec/S-spec.md

@@ -0,0 +1,91 @@
+---
+id: specdev/spec
+type: workflow-entry
+workflow: specdev
+name: 编写 Spec
+description: 将当前对话综合为一份完整的 spec 文档，包含问题陈述、解决方案、用户故事、实现决策和测试决策，持久化到变更目录。
+keywords: [spec, 规范, 需求, PRD, 用户故事]
+---
+
+# 编写 Spec
+
+此 work 读取当前对话上下文和代码库理解，产出一份 spec（你可能也称之为 PRD）。不要访谈用户 —— 仅综合你已经知道的内容。
+
+## 流程
+
+### 1. 探索代码库
+
+探索仓库以了解代码库的当前状态（如果尚未这样做）。在整个 spec 中使用项目的领域词汇表，并尊重所涉及区域的任何 ADR。
+
+先读取 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 了解项目的领域词汇表——使用其中的术语定义，不要自创名称。
+
+再读取 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 了解已做出的架构决策——不要与已有决策冲突。如果 spec 涉及与某 ADR 相同或相邻的区域，在实现决策中引用该 ADR。
+
+`{change}` 为当前活跃变更的目录名，格式为 `<YYYY-MM-DD>-<topic>`。如果尚未创建变更目录，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 的启动变更阶段初始化 CONTEXT.md 和 ADR.md。
+
+**完成标准**：代码库当前状态已理解，领域词汇表和 ADR 已纳入考量。
+
+### 2. 草拟接缝
+
+草拟你将用于测试该功能的接缝（seam）。接缝是你可以插入测试以验证行为的位置——API 端点、CLI 命令、UI 交互点、事件回调等。
+
+**接缝规则：**
+
+- 优先使用现有接缝而不是新建。查看代码库中已有的测试，了解项目如何注入测试。
+- 使用尽可能高层的接缝。UI 测试 > API 测试 > 单元测试，按此优先级选择。
+- 如果需要新接缝，在尽可能高的层级提出。代码库中的接缝越少越好 —— 理想数量是 1 个。
+- 每个接缝描述：接缝位置（什么模块/组件）、接缝类型（E2E、API、单元）、何时触发、如何验证。
+
+**与用户确认这些接缝是否符合他们的期望。** 展示草拟的接缝列表，询问：
+- 接缝层级是否合适？（太高可能遗漏细节，太低可能过于脆弱）
+- 是否有遗漏的接缝？
+- 现有接缝是否已足够，无需新增？
+
+**完成标准**：测试接缝已草拟并经用户确认。
+
+### 3. 编写 spec
+
+按以下模板编写完整 spec，写入 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。
+
+---
+
+**问题陈述** —— 从用户视角描述用户面临的问题。不要描述技术问题——描述用户遇到的困境、无法完成的任务、或当前流程中的痛点。一两段即可，但必须具体到让读者理解"为什么需要这个功能"。
+
+**解决方案** —— 从用户视角描述问题的解决方案。描述用户将如何与新功能交互、他们的体验将如何改变。不要写实现细节——写用户能做什么、看到什么。一两段即可。
+
+**用户故事** —— 一个详细的、编号的用户故事列表。每个用户故事格式为：
+
+> 作为 &lt;角色&gt;，我希望 &lt;功能&gt;，以便 &lt;收益&gt;
+
+例如：*作为手机银行客户，我希望查看账户余额，以便做出更明智的消费决策。*
+
+用户故事列表应极其详尽，涵盖该功能的所有方面。覆盖以下维度：
+- 主要流程（happy path）—— 用户最常走的路径
+- 边界情况 —— 空数据、极限值、并发操作
+- 错误处理 —— 用户犯错时发生什么
+- 权限与角色 —— 不同角色的不同体验
+- 状态转换 —— 数据从创建到归档的每个状态变化
+
+**实现决策** —— 已做出的实现决策列表。可包含：将构建/修改的模块、这些模块将被修改的接口、开发者的技术澄清、架构决策、Schema 变更、API 契约、具体交互。不要包含具体文件路径或代码片段——它们可能很快过时。
+
+例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联在相关决策中，并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+
+**测试决策** —— 已做出的测试决策列表。包含：什么构成好测试的描述（只测试外部行为，不测试实现细节）、哪些模块将被测试、测试的先例（即代码库中类似类型的测试）。
+
+**超出范围** —— 描述此 spec 超出范围的内容。明确说出**不做什么**与说出做什么同样重要。对于每个超出范围的条目，简要说明原因（是后续版本的规划、还是技术上不可行、还是与产品愿景不符）。
+
+**补充说明** —— 关于该功能的任何补充说明。可包含：已知风险或不确定性、依赖的外部系统或团队、需要进一步调研的领域、迁移或废弃计划。
+
+---
+
+写入后，不要做额外的 triage 或标签操作——spec.md 的地位由其在变更目录中的存在本身决定。
+
+**完成标准**：spec.md 已写入变更目录——问题陈述、解决方案、用户故事、实现决策、测试决策、超出范围、补充说明各章节齐全，无残留 `[TODO:]`。
+
+## 子文件引用
+
+本入口为单文件 work，所有内容均已内联。以下引用仅在其他 work 需要读取 spec 时使用：
+
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` —— 编写的 spec 产物
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` —— 领域词汇表（阅读用）
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` —— 架构决策记录（阅读用）