specwf 0.2.0

package/dist/templates/commands/ship.md

@@ -0,0 +1,36 @@
+# 交付
+
+## Phase ship
+
+创建 PR + 更新 @specwf/state.md。
+
+PR 正文应包含：
+- Phase scope 概述
+- 包含的 change 列表（每个 change 的 scope 摘要 + 产出文件）
+- 变更统计（文件数、行数）
+- 测试覆盖状态（vitest run 结果）
+- Checklist（所有 change 已 verify passed、已 archive）
+
+## Milestone ship
+
+发布 release tag + 更新 @specwf/project.md 版本号。
+
+Release notes 应包含：
+- 版本号与里程碑名称
+- 变更总览（按 phase 分组）
+- Breaking changes（如有）
+- Git diff 统计（+/- 行数、文件数）
+- 测试结果汇总
+
+## 上下文
+
+```bash
+specwf state
+specwf continue change <last-change-name>
+```
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/split.md

@@ -0,0 +1,16 @@
+# Change 拆分
+
+将 phase 拆分为多个 change，确定依赖图。
+
+## 上下文
+
+```bash
+specwf context split
+specwf state
+```
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/commands/verify.md

@@ -0,0 +1,22 @@
+# 测试验证
+
+运行测试，诊断根因，路由回环。
+
+## 上下文
+
+```bash
+specwf context verify
+specwf state
+```
+
+## 回环路由
+
+- 计划缺陷 → `specwf continue`（回 plan）
+- 实现缺陷 → 回 apply 重实现
+- 规格缺陷 → 标记 spec 待修
+
+## 下一步
+
+```bash
+specwf continue
+```

package/dist/templates/skills/adhoc.md

@@ -0,0 +1,53 @@
+# 创建临时 Change 工作流指引
+
+## 概述
+
+临时 Change 是与 milestone/phase 无关的独立变更，直接走标准 Change 循环。适用于紧急修复、独立改进等场景。
+
+## 前置条件
+
+- specwf 项目已初始化
+- 变更名称已确定
+
+## 执行步骤
+
+### 1. 创建 change 目录
+
+```bash
+specwf change new <name>
+```
+
+自动生成：
+- `specwf/changes/<name>/proposal.md`
+- `specwf/changes/<name>/design.md`
+- `specwf/changes/<name>/tasks.md`
+- `specwf/changes/<name>/specs/` 目录
+
+### 2. 填写 proposal.md
+
+### 3. 继续推进
+
+```bash
+specwf continue
+```
+
+## 产物
+
+- proposal.md / design.md / tasks.md
+- state.md adhoc 记录
+
+## 验证
+
+- [ ] change 目录存在
+- [ ] 模板文件已生成
+- [ ] specwf state 能看到新 change
+
+## 常见陷阱
+
+- 临时 change 归档后统一存放在 specwf/archive/ 下
+- 临时 change 不走 milestone/phase 的 discuss/research-phase/split 流程
+- 如果需要关联到 phase，使用 `specwf change new --phase <id>`
+
+## 参考
+
+- specwf 工作流设计中的「临时 Change」章节

package/dist/templates/skills/apply.md

@@ -0,0 +1,134 @@
+# Change 实现工作流指引
+
+## 概述
+
+按 tasks.md 实现代码。TDD 强制执行：type:behavior 任务必须走 RED→GREEN→REFACTOR 循环。
+
+Apply 阶段由 specwf-executor agent 在隔离环境中执行，支持多任务分组并发和原子提交。
+
+## 前置条件
+
+- plan 阶段已完成，tasks.md、design.md、delta-specs 已就位
+- specwf context apply 已获取上下文
+- 隔离环境已准备（git worktree 或 OMP isolated mode）
+
+## 执行步骤
+
+### 1. 读取上下文
+
+运行 \`specwf context apply\`：
+- design.md — 技术方案
+- tasks.md — 实现清单
+- delta-specs — 行为契约
+- 依赖的 specs/ — 已有全局规范
+
+### 2. 分组执行
+
+根据 tasks.md 中的依赖关系分组，每组作为一次提交（或一组相关提交）：
+
+**组内串行**：依赖关系强制顺序
+**组间并行**：无依赖的任务由不同 executor agent 并行执行
+
+\`\`\`
+# 分组示例
+Group 1（并行）: task A, task B（无依赖）
+├── task A → 代码 + 测试 → commit
+└── task B → 代码 + 测试 → commit
+
+Group 2（串行）: task C → task D
+├── task C → 代码 + 测试 → commit
+└── task D → 代码 + 测试 → commit
+\`\`\`
+
+### 3. TDD 执行流程（type:behavior 任务）
+
+每个 type:behavior 任务严格执行：
+
+**RED — 写失败测试**
+\`\`\`
+1. 根据 delta-spec 的 SHALL/MUST 条目编写测试
+2. 测试应该明确断言行为契约
+3. 运行测试 → 预期失败（红色）
+4. 提交消息格式: \`test(<domain>): add failing test for <feature>\`
+\`\`\`
+
+**GREEN — 最小实现**
+\`\`\`
+1. 写恰好让测试通过的最少量代码
+2. 不要过度工程，不要提前优化
+3. 运行测试 → 预期通过（绿色）
+4. 提交消息格式: \`feat(<domain>): implement <feature>\`
+\`\`\`
+
+**REFACTOR — 重构改进**
+\`\`\`
+1. 在测试保护下重构代码结构
+2. 测试应该仍然通过
+3. 提交消息格式: \`refactor(<domain>): improve <aspect>\`
+4. REFACTOR 不改变行为，不修改测试
+\`\`\`
+
+### 4. 原子提交协议
+
+每个任务完成后执行原子提交：
+
+\`\`\`
+# 提交原则
+- 每个提交是一个逻辑单元，可独立 review
+- RED/GREEN/REFACTOR 每个阶段至少一个提交
+- 不混合不同任务的改动在一个提交中
+- 提交消息使用 Conventional Commits 格式
+
+# 提交消息格式
+<type>(<scope>): <description>
+
+[optional body — why]
+\`\`\`
+
+### 5. 非 TDD 任务（type:config/refactor/docs/scaffolding）
+
+直接实现，单次提交即可：
+\`\`\`
+chore(config): add ESLint rule for ...
+docs(api): add JSDoc to ...
+refactor(core): extract validateInput helper
+\`\`\`
+
+### 6. 各组完成检查
+
+每组完成后运行：
+- [ ] 所有测试通过
+- [ ] 代码风格一致（运行 formatter）
+- [ ] delta-specs 中的每个 SHALL/MUST 有对应测试覆盖
+- [ ] 无 lint 错误
+- [ ] 无死代码/注释掉的代码
+
+## 产物
+
+- 实现代码（按 design.md 和 delta-specs）
+- 测试代码（type:behavior 任务）
+- 原子提交记录
+
+## 验证
+
+- [ ] 所有 type:behavior 任务已完成 RED→GREEN→REFACTOR
+- [ ] 所有非 TDD 任务已实现
+- [ ] 所有测试通过
+- [ ] 每个 delta-spec 的 SHALL/MUST 有对应测试
+- [ ] 代码无 lint/类型错误
+
+## 常见陷阱
+
+- GREEN 阶段只做「恰好通过」的实现 — 不要提前写 REFACTOR 的内容
+- 不要在 RED 和 GREEN 之间插入无关改动
+- 不要跳过 RED 直接写实现 — 先写测试再写代码
+- 如果测试无法先写（IO 密集型、UI 代码），标注为 \`type:refactor\` 或 \`type:scaffolding\`
+- 一个提交涵盖多个不相关改动 → 无法原子回滚
+- 跨 change 共享代码使用依赖约定或 key_links，不要复制粘贴
+
+## 参考
+
+- TDD (Test-Driven Development) by Kent Beck
+- Conventional Commits 规范
+- GSD Core 的 execute phase
+- OpenSpec 的 atomic commit 协议

package/dist/templates/skills/archive.md

@@ -0,0 +1,109 @@
+# 归档工作流指引
+
+## 概述
+
+Change 循环的收尾阶段。负责两件事：(1) 将 delta-specs 确定性合并到全局 specs/；(2) 从代码 diff 中提取新的行为和约束，回灌到 specs/ 中。
+
+归档完成后，Change 的工作永久记录在 specs/ 中，供后续 Change 参考和使用。
+
+## 前置条件
+
+- verify 阶段已通过（passed 状态）
+- 合并目标分支的准备已完成（ship 阶段前）
+
+## 执行步骤
+
+### 1. 读取上下文
+
+读取以下文件清单：
+\`\`\`
+changes/<change-name>/specs/<domain>/spec.md  — delta-specs
+specs/<domain>/spec.md                         — 全局 specs（目标）
+changes/<change-name>/tasks.md                 — 任务清单（确认 REFACTOR 阶段可以删除的实现细节 delta）
+changes/<change-name>/VERIFICATION.md          — 验证报告（确认哪些通过了）
+\`\`\`
+
+### 2. Delta-Spec 合并
+
+将 delta-specs 合并到全局 specs/ 中：
+
+**合并规则**：
+- **新增条目**：直接追加到对应域名的 specs/ 文件中
+- **修改条目**：替换或修订全局 specs/ 中的对应 ID
+- **删除条目**：从全局 specs/ 中移除（标记 \`[DELETED: <change-name>]\`）
+- **冲突**：如果全局 specs/ 中的条目与 delta-spec 矛盾，标记 \`[CONFLICT: <change-name>]\` 并列出冲突双方
+
+**合并流程**：
+\`\`\`
+1. 读取 changes/<change>/specs/ 下的所有 spec 文件
+2. 对每个文件：
+   a. 按 SHALL/MUST 编号索引
+   b. 对全局 specs/ 执行新增/修改/删除
+   c. 记录变更日志在 spec 文件头部
+3. 处理冲突（见冲突规则）
+4. 写入更新后的 specs/
+\`\`\`
+
+### 3. 代码认知提取
+
+从代码 diff 中提取未在 delta-specs 中预写的行为和约束：
+
+**提取来源**：
+- 新增的函数、方法、模块的公共 API（类型签名、注释、实现）
+- 测试中隐含的行为约束（如「一个用户只有一个 active session」）
+- 配置文件、常量中的业务规则
+- 错误消息中体现的领域概念
+
+**提取规则**：
+- **系统行为**（什么是系统做的） → 提取为 SHALL 条目
+- **业务约束**（必须遵守的限制） → 提取为 MUST 条目
+- **用户可见行为**（API 响应格式、错误码） → 提取为 SHOULD 条目
+- **实现细节**（内部变量名、helper 函数） → 不提取
+
+**AUTO-EXTRACTED 标记**：
+每个自动提取的条目在末尾添加：
+\`\`\`
+# AUTO-EXTRACTED from <change-name> on <timestamp>
+# Source: <file>:<line>
+\`\`\`
+
+标记的目的是：
+- 标识是工具自动生成的，不是人工编写的
+- 便于后续人工 review 时定位和验证
+- 在后续归档中，如果人工 review 确认正确，移除 \`AUTO-EXTRACTED\` 标记
+
+### 4. 最终检查
+
+- [ ] 所有 delta-specs 已合并或标记冲突
+- [ ] 已扫描代码 diff 并提取认知
+- [ ] 提取的条目有 \`AUTO-EXTRACTED\` 标记
+- [ ] 全局 specs/ 文件无格式损坏
+- [ ] change 目录保留为历史记录（不删除）
+
+## 产物
+
+- \`specs/<domain>/spec.md\`（更新） — 合并后的全局规范
+- \`specs/<domain>/spec.md\`（追加） — 代码认知提取后的新增条目
+
+## 验证
+
+- [ ] delta-specs 已正确合并到全局 specs/
+- [ ] 冲突已标记 \`[CONFLICT: <change>]\` 且列出双方
+- [ ] 代码提取条目有 \`AUTO-EXTRACTED\` 标记
+- [ ] 全局 specs/ 可被 parseSpec 读取（无格式错误）
+- [ ] change 目录保留
+
+## 常见陷阱
+
+- 不要删除 change 目录 — 它是 git 历史之外的辅助审计轨迹
+- 不要覆盖全局 specs/ — 只追加、替换对应 ID、或标记删除
+- 代码提取不是 code review — 提取行为契约，不是判断代码好坏
+- 提取要克制 — 只有「系统行为/约束」才提取，「实现方式」不提取
+- AUTO-EXTRACTED 条目需要人肉 review 确认，不是最终版
+- 如果一个 extract 发现的行为明确违反现有 specs/ 或 conventions/，额外标记 \`[FLAG: conflict with <existing-spec-ref>]\`
+
+## 参考
+
+- OpenSpec 的 delta-merge 流程
+- Trellis 的代码认知回灌概念（仅参考）
+- GSD Core 的 archive 阶段

package/dist/templates/skills/continue.md

@@ -0,0 +1,97 @@
+# 自动推进工作流指引
+
+## 概述
+
+读取 STATE.md，由状态机确定当前状态，自动触发对应的下一个 slash command。
+
+Continue 是整个工作流的自动导航器。它不执行任何业务逻辑，只负责判断「现在该做什么」并触发。
+
+## 前置条件
+
+- specwf/STATE.md 存在且格式正确
+- specwf 已初始化
+
+## 执行步骤
+
+### 1. 读取 STATE.md
+
+\`\`\`
+specwf state
+\`\`\`
+
+STATE.md 包含：
+- 当前 milestone / phase / change 的位置
+- 各个实体的状态
+- 下一步提示（如果有）
+
+### 2. 查询特定 change 的状态
+
+\`\`\`
+specwf continue change <name>
+\`\`\`
+
+查询指定 change 或临时 change 的当前状态和下一步建议。
+
+### 3. 状态机匹配
+
+根据 STATE.md 数据，状态引擎自动匹配合法转移。每个步骤对应一个 slash command：
+
+| 层级 | 当前步骤 | 下一步命令 | 子代理 |
+|------|---------|-----------|--------|
+| 项目层 | initialized | /specwf:grill | — |
+| 项目层 | requirements-defined | /specwf:research | researcher |
+| 项目层 | researched | /specwf:roadmap | — |
+| 项目层 | roadmap-defined | /specwf:discuss | — |
+| Phase | phase-discuss | /specwf:research-phase | researcher |
+| Phase | phase-research | /specwf:split | — |
+| Phase | phase-split 后 | /specwf:plan → apply → review → verify → archive | 各步对应 subagent |
+| Phase | change-archived | /specwf:ship | — |
+| Phase | phase-shipped | /specwf:ship（milestone）或 /specwf:discuss（下一 phase）| — |
+| 临时 change | adhoc-proposal | /specwf:plan | planner |
+
+完整的状态转移表见 `src/types/state.ts`。
+
+### 3. 输出下一步
+
+输出格式：
+\`\`\`
+# Continue 结果
+
+## 当前状态
+- Project: <name>
+- Milestone: <ms-name>（<status>）
+- Phase: <ph-name>（<status>）
+- Change: <change-name>（<status>）
+
+## 下一步
+- 命令: /specwf:<next-step>
+- 前置条件: ...
+\`\`\`
+
+### 4. 触发（可选）
+
+如果配置了 \`auto_advance: true\`，自动加载对应的 skill 并开始执行。
+
+## 产物
+
+- （无永久文件输出）
+- 控制台输出下一步建议（或自动触发）
+
+## 验证
+
+- [ ] 正确识别当前状态
+- [ ] 正确匹配下一步
+- [ ] STATE.md 格式可解析
+- [ ] 无状态机死循环风险
+
+## 常见陷阱
+
+- 如果 STATE.md 内容不完整或格式损坏，不要猜测 — 提示用户运行 \`specwf init\` 或手动修复
+- 如果多个 change 存在且状态不一致，优先处理最深的未完成 change
+- 不要自动推进跳过 review → verify → archive 的流程（review 必须由用户触发来确认质量）
+- auto_advance 模式不跳过 review — 只是自动触发 review 命令，仍需要 reviewer agent
+
+## 参考
+
+- state-machine 模块的状态转换表
+- OMP 的 continue 命令设计

package/dist/templates/skills/discuss.md

@@ -0,0 +1,95 @@
+# Phase 讨论工作流指引
+
+## 概述
+
+为当前 Phase 做详细的实现决策讨论。这是进入技术实现前的最后一道设计关卡 — 确定 Phase 的目标、范围、设计方案和实现决策，产出 context.md 作为后续所有 change 的决策依据。
+
+Discuss 不直接产出代码，但它决定了后续 coding 的质量和方向。
+
+## 前置条件
+
+- 路线图 ROADMAP.md 已确定
+- 当前 phase 的依赖 phase 已完成
+- 相关的 specs 和 conventions 已就位
+
+## 执行步骤
+
+### 1. 确定 Phase 范围和边界
+
+- 回顾 ROADMAP.md 中当前 phase 的描述
+- 确认 phase 的输入和输出
+- 明确与其他 phase 的接口边界
+
+### 2. 讨论技术决策
+
+逐项讨论以下决策，每项达成共识后记录：
+
+**架构决策**
+- 模块划分和分层
+- 接口设计模式
+- 数据流方向
+
+**技术实现决策**
+- 关键数据结构
+- 异常处理策略
+- 测试策略
+
+**质量要求**
+- 性能指标
+- 安全要求
+- 可维护性要求
+
+### 3. 记录 context.md
+
+将讨论结果写入 \`specwf/context.md\`：
+
+\`\`\`markdown
+# Phase: <名称>
+
+## 目标
+## 范围
+## 架构决策
+- ADR-001: <决策项>
+  - 上下文: ...
+  - 决策: ...
+  - 理由: ...
+
+## 接口契约
+## 数据模型
+## 关键实现约束
+## 测试要求
+## 未解决问题
+\`\`\`
+
+如果 context.md 已存在，追加或更新当前 phase 的部分。
+
+### 4. 识别灰色地带
+
+对尚未明确的决策点标记 \`[TODO: discuss]\`，可以先搁置但需记录：
+- 不确定的点
+- 需要进一步调研的领域
+- 可以延后决定的事项
+
+## 产物
+
+- \`specwf/context.md\`（更新）— 实现决策文档
+
+## 验证
+
+- [ ] 所有架构决策都有记录和理由
+- [ ] 接口边界清晰
+- [ ] 灰色地带已标记
+- [ ] context.md 与 ROADMAP.md 不矛盾
+
+## 常见陷阱
+
+- 不要跳过「看起来简单」的决策 — 记录所有选择
+- 如果决策依赖未完成的 phase，标记为 \`[DEFERRED]\`
+- 避免过度设计 — 只讨论当前 phase 需要的决策
+- 如果反复无法达成决策，使用 specwf-advisor agent 提供建议
+
+## 参考
+
+- ADR（Architecture Decision Record）模式
+- GSD Core 的 discuss 工作流
+- OpenSpec 的 context.md 格式

package/dist/templates/skills/grill.md

@@ -0,0 +1,90 @@
+# 需求探讨工作流指引
+
+## 概述
+
+通过无限制细节提问，与用户深入探讨需求，直到对项目的目标、范围、约束和技术方向达成共识。Grill 阶段不需要代码 — 它的产出一份扎实的 proposal.md，供后续 research 和 roadmap 使用。
+
+核心原则：不问「是/否」，而是「为什么」「在什么场景下」「现在的方案是什么」「成功怎么衡量」。
+
+## 前置条件
+
+- 至少有一个初步想法或需求方向
+- （可选）已读完用户提供的任何参考资料
+
+## 执行步骤
+
+### 1. 理解背景
+
+先让用户描述他想做什么。用简短问题确认：
+- 项目核心目标是什么？
+- 目标用户是谁？
+- 当前状态（从零开始 / 改进现有 / 重构）？
+
+### 2. 深挖细节（5W1H）
+
+针对每个模糊点持续追问，直到边界清晰：
+
+**What**
+- 具体要做什么功能？不做什么（明确排除范围）
+- 有什么输入/输出？
+
+**Why**
+- 为什么需要这个？业务驱动力是什么？
+- 有什么必须满足的约束（合规、性能、部署环境）？
+
+**Who**
+- 谁用这个系统？用户角色和权限模型？
+- 谁维护？维护者的技术栈？
+
+**When**
+- 时间线？里程碑节奏？
+- 最短可用的范围是什么？
+
+**Where**
+- 部署环境（云端/私有化/边缘）？
+- 是否已有基础设施（数据库、消息队列、CI/CD）？
+
+**How**
+- 偏好的技术栈倾向？
+- 对开发流程有要求吗（TDD、review 强度等）？
+
+### 3. 产出 proposal.md
+
+将讨论共识整理为 proposal.md：
+\`\`\`markdown
+# <项目名称> Proposal
+
+## 概述
+## 目标和成功标准
+## 范围（含排除项）
+## 用户角色
+## 技术倾向
+## 非功能需求
+## 风险与不确定性
+\`\`\`
+
+### 4. 确认共识
+
+与用户逐项回顾 proposal.md，确认无误后进入 research 阶段。
+
+## 产物
+
+- \`specwf/proposal.md\` — 需求共识文档
+
+## 验证
+
+- [ ] 用户对 proposal.md 所有条目确认无歧义
+- [ ] 排除范围清晰表述
+- [ ] 风险项已知且列出
+
+## 常见陷阱
+
+- 不要太快跳到技术方案 — 先确认「做什么」再讨论「怎么做」
+- 不要默认用户的术语和你一致 — 每遇到专业术语都问一次定义
+- 如果用户有明显的先验假设，温和地指出并确认
+- 当用户说「简单」或「标准」时，一定追问具体是什么
+
+## 参考
+
+- The Mom Test 提问方法论
+- GSD Core 的 grill 流程