@namewta/speculo 0.1.0

package/speculo/skills/speculo-write/references/workflow-authoring-sop.md

@@ -0,0 +1,130 @@
+# Workflow Authoring SOP
+
+## 入口结构
+
+workflow 放在 `speculo/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`ops`。
+
+目录和入口文件必须同名：
+
+```text
+speculo/workflows/<cat>/<entry>/<entry>.md
+```
+
+主线 workflow 使用数字前缀，如 `01-grill-with-docs`。横向 workflow 使用字母前缀，如 `H-diagnose`、`R-review`、`D-docs-sync`。
+
+## Frontmatter
+
+入口 frontmatter 只承载发现元数据：
+
+```yaml
+---
+id: <cat>/<name>
+category: <cat>
+name: <人类可读名>
+description: <一句话用途>
+keywords: [<关键词>]
+---
+```
+
+禁止把 phases、模板、依赖、状态字段写进 frontmatter。
+
+## 正文必备章节
+
+入口正文必须包含：
+
+- `## 阶段`
+- `## 依赖`
+- `## 状态扩展字段`
+- `## 完成与状态更新`
+
+阶段条目必须写清：
+
+- 规范 phase 文件
+- 模板路径
+- 产物文件名
+- 完成准则
+
+## Phase 文件
+
+phase 文件不需要 frontmatter。每个 phase 文件写清：
+
+- 输入
+- 产物
+- 填写引导
+- 边界
+- 完成准则
+
+phase 文件只放该阶段执行所需内容，不重复入口文件的全局说明。
+
+## 模板
+
+模板放在：
+
+```text
+speculo/workflows/<cat>/_templates/
+```
+
+命名：
+
+```text
+<name>-<artifact>-template.md
+```
+
+模板不写 frontmatter，顶部用归属说明：
+
+```markdown
+> **服务工作流：** `../<entry>/<entry>.md`
+> **产物文件名：** `<artifact>.md`
+```
+
+模板占位符必须使用 `[TODO: ...]`。
+
+## 持久化路径
+
+workflow 产物写入：
+
+```text
+.speculo/<cat>/<change>/
+```
+
+当前 change 的状态写入：
+
+```text
+.speculo/<cat>/<change>/.status.json
+```
+
+顶层 active 索引写入：
+
+```text
+.speculo/<cat>-status.json
+```
+
+项目级规则、经验、上下文和 ADR 使用：
+
+```text
+.speculo/.config/RULES.md
+.speculo/.config/LESSONS.md
+.speculo/.config/context/
+.speculo/.config/adr/
+```
+
+不要把新状态放到项目根目录。`.status.json` 元字段、顶层索引 schema 和写入责任表见 `persistence-contract-sop.md`。
+
+## 索引与文档同步
+
+新增 workflow 后检查：
+
+- 对应分类的 `00-INDEX.md` 是否需要新增别名
+- `.speculo/<cat>-status.json` 和 `.speculo/<cat>/.gitkeep` 是否存在
+- `.speculo/archive/<cat>/.gitkeep` 是否存在
+- 项目若有 `docs/quick-reference.md` 等入口索引，是否需要新增条目
+- CLI tests 是否需要断言复制新入口
+
+## 完成线
+
+- 入口 frontmatter 合规
+- 正文必备章节齐全
+- 所有跨文件引用使用相对路径
+- 非模板文件不残留无说明 TODO
+- 模板只保留 `[TODO: ...]` 占位符
+- `pnpm test` 通过或记录无法运行原因

package/speculo/workflows/dev/00-INDEX.md

@@ -0,0 +1,56 @@
+---
+id: dev/index
+category: dev
+name: Dev Workflow Index
+description: 开发工作流导航、状态汇报与下一步推荐入口
+keywords: [dev, 开发, workflow, index, 状态]
+---
+
+# Dev Workflow Index
+
+本文件是 dev 分类的导航入口。进入时先读取 `../../.speculo/dev-status.json`，再按其中 active change 读取 `../../.speculo/dev/<change>/.status.json`，根据用户意图推荐下一步。
+
+## 入口别名
+
+| 别名 | 入口 | 用途 |
+|------|------|------|
+| `dev/01` | `01-grill-with-docs/01-grill-with-docs.md` | 领域术语、CONTEXT、ADR 与方案拷问 |
+| `dev/02` | `02-prd/02-prd.md` | zoom-out 全景理解与 PRD 综合 |
+| `dev/03` | `03-tdd/03-tdd.md` | 垂直切片 TDD 实现 |
+| `dev/I` | `I-to-issues/I-to-issues.md` | 垂直切片 issue 分解，可嵌入其他 dev workflow |
+| `dev/H` | `H-diagnose/H-diagnose.md` | hotfix / bug / 性能回退诊断 |
+| `dev/R` | `R-review/R-review.md` | Standards / Spec 双维度 diff 审查 |
+| `dev/D` | `D-docs-sync/D-docs-sync.md` | 基于 git diff 同步 README、CHANGELOG、AGENTS 等对外文档 |
+
+## 进入协议
+
+1. 若用户未指定 change，扫描 `../../.speculo/dev-status.json` 和 `../../.speculo/dev/*/.status.json`，列出 active changes。
+2. 若只有一个 active change，默认继续该 change；若有多个 active change，要求用户选择。
+3. 若没有 active change，按用户意图创建新的 change 目录，并初始化 `.status.json` 与 `../../.speculo/dev-status.json`。
+4. 推荐入口时优先使用用户显式别名；没有别名时按执行模式推荐。
+5. 执行任何 workflow 前，读取该 workflow 入口文件、阶段文件、模板和被调用 skill wrapper。
+
+## 执行模式
+
+- `full`：`dev/01` -> `dev/02` -> `dev/I` -> `dev/03`。
+- `planning-only`：`dev/01` -> `dev/02` -> `dev/I`，不进入实现。
+- `implementation-only`：已有 PRD、issue 或明确任务时，从 `dev/03` 开始。
+- `hotfix`：Bug、异常、性能回退时，从 `dev/H` 开始；修复阶段可嵌入 `dev/03` 的 TDD 回归循环。
+- `review`：已有 fixed point 或用户要求审查时，从 `dev/R` 开始。
+- `docs-sync`：需要基于 git 差异刷新对外文档时，从 `dev/D` 开始。
+
+## 状态汇报
+
+输出 dev 状态时至少包含：
+
+- active change 数量与每个 change 的 `current_phase`
+- 最近更新的 change，按 `updated_at` 倒序
+- `phase_history` 最后一项为 `blocked` 或 `updated_at` 超过 14 天未变化的 change
+- 推荐下一步入口和原因
+
+## 完成与状态更新
+
+- 所有 dev workflow 必须维护同一 change 的 `.status.json`。
+- 进入 phase 时更新 `current_phase`，并在 `phase_history` 追加 `in-progress` 记录。
+- phase 完成时写入 `completed_at` 和 `status: completed`。
+- 只有完成当前 change 的最终交付边界时，才把 `change_status` 置为 `completed`。

package/speculo/workflows/dev/01-grill-with-docs/01-grill-with-docs.md

@@ -0,0 +1,79 @@
+---
+id: dev/grill-with-docs
+category: dev
+name: Grill With Docs
+description: 结合项目术语、CONTEXT 与 ADR 对方案进行领域澄清和决策压力测试
+keywords: [grill, context, adr, 术语, 决策]
+---
+
+# Grill With Docs 工作流执行指引
+
+本工作流用于在 PRD 或实现前澄清领域语言、识别决策分支，并把已确认的上下文沉淀为当前 change 的可追踪产物。领域拷问、CONTEXT 格式和 ADR 判断规则已内置在本 workflow 目录中。
+
+## 内置指引
+
+### 何时使用
+
+当 dev workflow 需要把用户方案与现有领域模型、术语表、ADR 或代码现实交叉验证时使用。
+
+### 输入
+
+- 用户提出的计划、需求、设计或变更意图
+- `.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
+- `.speculo/.config/context/CONTEXT.md`、`.speculo/.config/context/CONTEXT-MAP.md`、`.speculo/.config/adr/` 和相关代码
+- 当前 change 目录：`.speculo/dev/<change>/`
+
+### 输出
+
+- `.speculo/dev/<change>/context-map.md`
+- `.speculo/dev/<change>/decision-log.md`
+- 已确认的术语、决策、开放问题和 ADR 候选
+- 需要用户进一步决策的问题，每次只问一个
+
+### 执行原则
+
+针对计划的每个方面不断向用户提问，直到达成共识。沿着设计树的每条分支逐一展开，逐个解决决策之间的依赖关系。对于每个问题，给出推荐答案。
+
+每次只问一个问题，等待用户对当前问题的反馈后再继续。如果某个问题可以通过探索代码库来回答，就直接探索代码库。
+
+需要格式约定时读取同目录 `CONTEXT-FORMAT.md` 或 `ADR-FORMAT.md`。项目 CONTEXT 或 ADR 的创建、修改必须写入 `.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
+
+## 阶段
+
+### 1. Context Scan — 上下文扫描
+- 规范：`grill-context-scan.md`
+- 模板：`../_templates/grill-context-map-template.md`
+- 产物：`context-map.md`
+- 完成准则：
+  - 已记录相关术语表、ADR、代码区域和缺口
+  - `context-map.md` 无残留 `[TODO:]`
+
+### 2. Decision Grill — 决策拷问
+- 规范：`grill-decision.md`
+- 模板：`../_templates/grill-decision-log-template.md`
+- 产物：`decision-log.md`
+- 完成准则：
+  - 关键决策均有结论、推荐答案或开放问题
+  - 需要写入 `.speculo/.config/context/` 或 `.speculo/.config/adr/` 的内容已获用户确认，或记录为候选
+  - `decision-log.md` 无残留 `[TODO:]`
+
+## 依赖
+
+- 软依赖：无
+- 硬依赖：无
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/01`
+- `embedded_guides` (array) — 包含 `grill-with-docs`
+- `context_paths` (array) — 已读取的 CONTEXT、ADR、代码或配置路径
+- `decision_status` (open | resolved | blocked) — 决策澄清状态
+- `adr_candidates` (array) — ADR 候选清单
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- phase 完成后更新 `updated_at`、产物路径和扩展字段。
+- 本 workflow 完成后不自动完成 change；默认移交 `../02-prd/02-prd.md` 或按用户要求停止。

package/speculo/workflows/dev/01-grill-with-docs/ADR-FORMAT.md

@@ -0,0 +1,49 @@
+# ADR 格式
+
+本辅助文档只定义项目 ADR 的写法。默认产物仍写入 `.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建项目 ADR。
+
+ADR 存放在 `.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。
+
+`.speculo/.config/adr/` 目录由 Speculo 初始化提供；如果目标项目缺失该目录，按需创建。
+
+## 模板
+
+```md
+# {决策的简短标题}
+
+{1-3 句话：背景是什么、我们决定了什么、为什么这样决定。}
+```
+
+就这些。一个 ADR 可以只是一段话。价值在于记录「做出了某个决策」以及「为什么」——而不是填满各个章节。
+
+## 可选章节
+
+只有确实能增加价值时才包含以下章节。大多数 ADR 不需要它们。
+
+- **Status** 前置元数据（`proposed | accepted | deprecated | superseded by ADR-NNNN`）—— 当决策被重新审视时很有用
+- **Considered Options** —— 只有被拒绝的替代方案值得记住时才写
+- **Consequences** —— 只有非显而易见的下游影响需要指出时才写
+
+## 编号
+
+扫描 `.speculo/.config/adr/` 找到已有的最大编号，然后加一。
+
+## 何时提议创建 ADR
+
+以下三个条件必须同时满足：
+
+1. **难以逆转** —— 日后改变主意的代价不可忽略
+2. **缺少上下文会令人意外** —— 未来的读者看到代码会疑惑「他们到底为什么要这样做？」
+3. **真实权衡的结果** —— 确实存在替代方案，而你基于特定原因选择了其中一个
+
+如果一个决策很容易逆转，就跳过它——你反正会逆转它。如果它不令人意外，没人会疑惑为什么。如果没有真正的替代方案，除了「我们做了显而易见的事」之外没有什么可记录的。
+
+### 哪些情况应该写 ADR
+
+- **架构形态。** 「我们使用 monorepo。」「写模型采用事件溯源，读模型投射到 Postgres。」
+- **上下文之间的集成模式。** 「Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。」
+- **带有锁定效应的技术选型。** 数据库、消息总线、认证提供商、部署目标。不是每个库——只是那些换掉需要花一个季度的。
+- **边界和范围决策。** 「客户数据由 Customer 上下文拥有，其他上下文只通过 ID 引用。」明确的「不做」和「要做」同样有价值。
+- **刻意偏离显而易见的路径。** 「我们用原生 SQL 而非 ORM，因为 X。」任何理性读者会假设相反做法的地方。这能防止下一个工程师去“修复”某个刻意为之的设计。
+- **代码中看不见的约束。** 「因为合规要求，我们不能用 AWS。」「因为合作方 API 合约，响应时间必须在 200 ms 以内。」
+- **拒绝理由不明显的替代方案。** 如果你考虑过 GraphQL 但因为某些微妙原因选了 REST，记录下来——否则六个月后会有人再次提议 GraphQL。

package/speculo/workflows/dev/01-grill-with-docs/CONTEXT-FORMAT.md

@@ -0,0 +1,65 @@
+# CONTEXT.md 格式
+
+本辅助文档只定义项目术语表的写法。默认产物仍写入 `.speculo/dev/<change>/context-map.md` 和 `.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建或更新 `.speculo/.config/context/CONTEXT.md` / `.speculo/.config/context/CONTEXT-MAP.md`。
+
+## 结构
+
+```md
+# {上下文名称}
+
+{一到两句话描述这个上下文是什么、为什么存在。}
+
+## 术语
+
+**订单（Order）**：
+{一到两句话描述该术语}
+_避免使用_：Purchase、transaction
+
+**发票（Invoice）**：
+交付后向客户发送的付款请求。
+_避免使用_：Bill、payment request
+
+**客户（Customer）**：
+下单的个人或组织。
+_避免使用_：Client、buyer、account
+```
+
+## 规则
+
+- **要有主见。** 当同一个概念有多个词汇时，选择最好的一个，将其他词列为「避免使用」的别名。
+- **显式标记冲突。** 如果某个术语被合混地使用，在「已标记的合混」中明确指出并给出解决方案。
+- **保持定义简洁。** 最多一到两句话。定义它「是什么」，而不是「做什么」。
+- **展示关系。** 使用粗体术语名称，在明显的地方表达基数关系。
+- **只包含本项目的上下文特有的术语。** 通用编程概念（超时、错误类型、工具模式）即使项目大量使用也不应该包含。添加术语前问自己：这是本项目上下文特有的概念，还是通用编程概念？只有前者才应该包含。
+- **当自然分组出现时，用子标题分组术语。** 如果所有术语属于一个紧密相关的领域，平铺列表即可。
+- **写一段示例对话。** 一段开发者与领域专家之间的对话，展示术语如何自然交互，并澄清相关概念之间的边界。
+
+## 单上下文与多上下文仓库
+
+**单上下文（大多数仓库）：** `.speculo/.config/context/CONTEXT.md` 记录项目级术语表。
+
+**多上下文：** `.speculo/.config/context/CONTEXT-MAP.md` 列出所有上下文、它们的位置以及它们之间的关系：
+
+```md
+# 上下文映射
+
+## 上下文
+
+- [Ordering](./ordering.md) —— 接收并跟踪客户订单
+- [Billing](./billing.md) —— 生成发票并处理付款
+- [Fulfillment](./fulfillment.md) —— 管理仓库拣货和发货
+
+## 关系
+
+- **Ordering → Fulfillment**：Ordering 发出 `OrderPlaced` 事件；Fulfillment 消费这些事件开始拣货
+- **Fulfillment → Billing**：Fulfillment 发出 `ShipmentDispatched` 事件；Billing 消费这些事件生成发票
+- **Ordering ↔ Billing**：共享 `CustomerId` 和 `Money` 类型
+```
+
+技能会自动推断适用哪种结构：
+
+- 如果 `.speculo/.config/context/CONTEXT-MAP.md` 存在，读取它以查找上下文
+- 如果只有 `.speculo/.config/context/CONTEXT.md`，则为单上下文
+- 如果都不存在，在第一个术语确定时按需创建 `.speculo/.config/context/CONTEXT.md`
+
+当存在多个上下文时，推断当前主题与哪个上下文相关。如果不确定，就问。

package/speculo/workflows/dev/01-grill-with-docs/grill-context-scan.md

@@ -0,0 +1,30 @@
+# Context Scan Phase
+
+## 输入
+
+- 用户提出的计划、需求、设计或问题
+- `.speculo/.config/RULES.md` 和用户明确指出的项目规则、设计约束或长期文档
+- `.speculo/.config/context/CONTEXT.md`、`.speculo/.config/context/CONTEXT-MAP.md`、`.speculo/.config/adr/` 和相关代码
+- 本 workflow 入口文件中的内置领域拷问指引
+
+## 产物
+
+- `.speculo/dev/<change>/context-map.md`，由 `../_templates/grill-context-map-template.md` 填写
+
+## 填写引导
+
+1. 先探索仓库事实，不向用户询问可从文件中确认的问题。
+2. 记录存在的领域术语来源、ADR 来源、关键模块和调用者。
+3. 标出缺失的术语表、缺失 ADR 或与用户描述冲突的代码事实。
+4. 只记录事实和待确认项，不在本阶段做方案裁决。
+5. 若 `.speculo/.config/context/CONTEXT-MAP.md` 存在，先读取它以判断涉及哪个上下文；若只有 `.speculo/.config/context/CONTEXT.md`，按单上下文处理；若都不存在，只记录“缺少术语表”，不在本阶段创建。
+
+## 边界
+
+- 不直接修改 `.speculo/.config/context/` 或 `.speculo/.config/adr/`；修改动作留到 Decision Grill 阶段确认后执行。
+- 不创建实现计划或 PRD。
+
+## 完成准则
+
+- `context-map.md` 无残留 `[TODO:]`
+- 已列出下一阶段必须追问的最高优先级问题

package/speculo/workflows/dev/01-grill-with-docs/grill-decision.md

@@ -0,0 +1,38 @@
+# Decision Grill Phase
+
+## 输入
+
+- `.speculo/dev/<change>/context-map.md`
+- 用户当前方案或目标
+- 本 workflow 入口文件中的内置领域拷问指引
+- 同目录 `CONTEXT-FORMAT.md`、`ADR-FORMAT.md`
+
+## 产物
+
+- `.speculo/dev/<change>/decision-log.md`，由 `../_templates/grill-decision-log-template.md` 填写
+- 可选：经用户确认后更新 `.speculo/.config/context/CONTEXT.md`、`.speculo/.config/context/CONTEXT-MAP.md` 或 `.speculo/.config/adr/*.md`
+
+## 填写引导
+
+1. 遵循 `01-grill-with-docs.md` 的内置指引，再按需读取同目录格式文档。
+2. 每次只问一个会改变决策树的问题，并给出推荐答案。
+3. 对术语冲突、代码现实冲突和 ADR 候选直接指出。
+4. 用户确认后，把决策写入 `decision-log.md`。
+5. 只有用户明确同意时，才把术语写入 `.speculo/.config/context/` 或创建 `.speculo/.config/adr/` 下的 ADR。
+6. 当用户使用的术语与 `.speculo/.config/context/` 中已有定义冲突时，立即指出冲突并要求在当前问题中消解。
+7. 当用户使用含混或一词多义的术语时，提议一个精确的规范术语。
+8. 当讨论领域关系时，用具体场景压力测试边界情况。
+9. 当用户描述某个东西如何运作时，检查代码是否一致；若矛盾，直接指出。
+10. 只有同时满足“难以逆转”“缺少上下文会令人意外”“真实权衡的结果”三个条件时，才提议 ADR。
+
+## 边界
+
+- 不输出 PRD；PRD 由 `../02-prd/02-prd.md` 负责。
+- 不把未确认的 ADR 候选写成正式 ADR。
+- 不修改 `.speculo/.config/RULES.md` 或用户未明确授权的项目规则文档。
+
+## 完成准则
+
+- 每个关键问题都有结论、推荐答案或 blocked 原因
+- `.status.json` 的 `decision_status` 已更新
+- `decision-log.md` 无残留 `[TODO:]`

package/speculo/workflows/dev/02-prd/02-prd.md

@@ -0,0 +1,64 @@
+---
+id: dev/prd
+category: dev
+name: PRD
+description: 通过 zoom-out 全景理解与 to-prd 综合产出开发 PRD
+keywords: [prd, zoom-out, 需求, 计划]
+---
+
+# PRD 工作流执行指引
+
+本工作流用于把已知上下文综合为当前 Speculo change 内的 overview 和 PRD。zoom-out 全景理解与 PRD 综合能力已内置在本 workflow 目录中。
+
+## 内置指引
+
+### Zoom Out
+
+当 agent 对某段代码或业务区域不熟悉，需要先建立全局视角再继续 PRD、设计、诊断或实现时使用。用项目领域术语表给出相关模块、调用者、关键边界、上下游依赖和需要进一步确认的问题。
+
+### PRD Synthesis
+
+当 dev workflow 已完成足够上下文探索，需要把当前对话和代码理解沉淀成 PRD 时使用。不要重复访谈已明确的信息；综合当前对话、代码库事实、领域术语、ADR、模块候选和测试目标。
+
+PRD 只写入 `.speculo/dev/<change>/prd.md`，overview 只写入 `.speculo/dev/<change>/overview.md`。不写项目根下的任意规划文档，不默认发布外部 issue。只有 tracker 已配置且用户明确要求时，才进入外部发布动作。
+
+## 阶段
+
+### 1. Zoom Out — 全景理解
+- 规范：`prd-zoom-out.md`
+- 模板：`../_templates/prd-overview-template.md`
+- 产物：`overview.md`
+- 完成准则：
+  - 已说明相关模块、调用者、边界和未知点
+  - `overview.md` 无残留 `[TODO:]`
+
+### 2. PRD Synthesis — PRD 综合
+- 规范：`prd-synthesis.md`
+- 模板：`../_templates/prd-template.md`
+- 产物：`prd.md`
+- 完成准则：
+  - PRD 包含问题、方案、用户故事、实现决策、测试决策、范围边界
+  - 已确认模块候选和测试目标
+  - `prd.md` 无残留 `[TODO:]`
+
+## 依赖
+
+- 软依赖：`../01-grill-with-docs/01-grill-with-docs.md`，scope: same-change
+- 硬依赖：无
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/02`
+- `embedded_guides` (array) — 包含 `zoom-out`、`to-prd`
+- `prd_slug` (string) — PRD 短 slug
+- `module_candidates` (array) — 候选模块或边界
+- `test_targets` (array) — 用户确认的测试目标
+- `issue_tracker_mode` (disabled | local-only | publish-requested | published) — issue tracker 使用状态
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- 默认把 PRD 写入当前 change 的 `prd.md`；不默认写项目根下的任意规划文档。
+- 本 workflow 完成后不自动完成 change；默认移交 `../I-to-issues/I-to-issues.md` 或 `../03-tdd/03-tdd.md`。

package/speculo/workflows/dev/02-prd/prd-synthesis.md

@@ -0,0 +1,30 @@
+# PRD Synthesis Phase
+
+## 输入
+
+- `.speculo/dev/<change>/overview.md`
+- 可选的 `context-map.md`、`decision-log.md`、用户故事或 issue
+- `02-prd.md` 中的 PRD Synthesis 内置指引
+
+## 产物
+
+- `.speculo/dev/<change>/prd.md`，由 `../_templates/prd-template.md` 填写
+
+## 填写引导
+
+1. 遵循 `02-prd.md` 的 PRD Synthesis 内置指引。
+2. 综合已有上下文，不重复访谈已明确的信息。
+3. 与用户确认模块候选和需要测试的行为。
+4. 默认只生成本地 `prd.md`；只有 tracker 已配置且用户明确要求时才发布 issue。
+5. PRD 中避免易过时的具体文件路径和代码片段，除非它们表达不可替代的决策。
+
+## 边界
+
+- 不进行 issue 切片；切片由 `../I-to-issues/I-to-issues.md` 负责。
+- 不修改业务代码。
+- 不把 change 标记为 completed。
+
+## 完成准则
+
+- `prd.md` 无残留 `[TODO:]`
+- `test_targets`、`prd_slug`、`issue_tracker_mode` 已写入 `.status.json`

package/speculo/workflows/dev/02-prd/prd-zoom-out.md

@@ -0,0 +1,29 @@
+# Zoom Out Phase
+
+## 输入
+
+- 用户目标、已有 `context-map.md` 或 `decision-log.md`
+- 相关代码区域、架构文档、ADR 和配置
+- `02-prd.md` 中的 Zoom Out 内置指引
+
+## 产物
+
+- `.speculo/dev/<change>/overview.md`，由 `../_templates/prd-overview-template.md` 填写
+
+## 填写引导
+
+1. 遵循 `02-prd.md` 的 Zoom Out 内置指引。
+2. 用项目领域术语说明相关模块和调用者。
+3. 标明现有行为、缺失能力、接口边界、上下游依赖和风险。
+4. 输出服务于 PRD 综合的事实，不提前写实现步骤。
+
+## 边界
+
+- 不发布 issue。
+- 不修改代码。
+- 不创建 PRD；PRD 留到下一阶段。
+
+## 完成准则
+
+- `overview.md` 无残留 `[TODO:]`
+- `.status.json` 已记录 `module_candidates`

package/speculo/workflows/dev/03-tdd/03-tdd.md

@@ -0,0 +1,80 @@
+---
+id: dev/tdd
+category: dev
+name: TDD Implementation
+description: 按垂直切片执行红绿重构，实现功能或回归修复
+keywords: [tdd, implement, red-green-refactor, 实现, 测试]
+---
+
+# TDD Implementation 工作流执行指引
+
+本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 红绿重构、测试、mock、接口设计、deep module 和重构指引已内置在本 workflow 目录中。
+
+## 内置指引
+
+### 核心原则
+
+测试应通过公共接口验证行为，而不是实现细节。代码可以完全重写；测试不应该。
+
+好的测试是集成式的：它们通过公共 API 运行真实的代码路径，描述系统“做什么”，不描述“怎么做”。坏的测试与实现耦合：mock 内部协作者、测试私有方法，或通过外部手段验证内部状态。
+
+### 反模式：水平切片
+
+不要先写全部测试，再写全部实现。正确做法是追踪弹式垂直切片：一个测试 -> 一个实现 -> 重复。每个测试都基于上一轮学到的东西做出响应。
+
+### 渐进披露
+
+- `tests.md`：设计测试方式时读取。
+- `mocking.md`：考虑 mock 边界时读取。
+- `deep-modules.md`：识别深模块机会时读取。
+- `interface-design.md`：设计可测试公共接口时读取。
+- `refactoring.md`：进入重构阶段时读取。
+
+## 阶段
+
+### 1. TDD Plan — 行为与接口计划
+- 规范：`tdd-plan.md`
+- 模板：`../_templates/tdd-plan-template.md`
+- 产物：`tdd-plan.md`
+- 完成准则：
+  - 已确认公共接口、关键行为和测试优先级
+  - `tdd-plan.md` 无残留 `[TODO:]`
+
+### 2. Slice Loop — 红绿重构循环
+- 规范：`tdd-loop.md`
+- 模板：`../_templates/tdd-log-template.md`
+- 产物：`implementation-log.md`
+- 完成准则：
+  - 每个切片都有 RED、GREEN、REFACTOR 和验证记录
+  - `implementation-log.md` 无残留 `[TODO:]`
+
+### 3. Finish — 验证与收尾
+- 规范：`tdd-finish.md`
+- 模板：`../_templates/tdd-verification-template.md`
+- 产物：`verification.md`
+- 完成准则：
+  - 已运行相关测试或明确记录无法运行原因
+  - 无调试残留和推测性功能
+  - `verification.md` 无残留 `[TODO:]`
+
+## 依赖
+
+- 软依赖：`../02-prd/02-prd.md` 或 `../I-to-issues/I-to-issues.md`，scope: same-change
+- 硬依赖：无；若用户提供明确修复或实现任务，可直接进入
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/03`
+- `embedded_guides` (array) — 包含 `tdd`
+- `slice_source` (prd | issues | diagnosis | user-request) — 切片来源
+- `red_green_refactor_cycles` (array) — 每轮 TDD 循环摘要
+- `verification_commands` (array) — 已运行或应运行的验证命令
+- `implementation_status` (planned | in-progress | verified | blocked) — 实现状态
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- 每完成一个切片，追加 `red_green_refactor_cycles`。
+- 全部用户要求的实现边界完成并验证后，可把 `change_status` 置为 `completed`，或移交 review/handoff command。