specwf 0.2.0

package/dist/templates/skills/init.md

@@ -0,0 +1,116 @@
+# 项目初始化工作流指引
+
+## 概述
+
+初始化 specwf 项目结构。这是整个工作流的起点，负责创建 specwf/ 目录骨架、specs/ 和 conventions/ 目录、project.yml 配置文件，以及平台命令/agent/skill 文件。
+
+对于存量项目，同时执行 codebase mapping 和 spec bootstrap 两个并行任务，从已有代码中提取行为契约。
+
+## 前置条件
+
+- 项目根目录已初始化 git 仓库
+- 确定 project.yml 配置内容（profile、workflow 开关等）
+
+## 执行步骤
+
+### 1. 创建目录结构
+
+创建以下目录层级：
+\`\`\`
+specwf/
+  project.yml          # 项目配置
+  changes/             # 临时 change
+  research/            # 调研产出
+milestones/
+  <ms-name>/
+    ph/
+      <ph-name>/
+        changes/
+          <change-name>/
+            specs/     # delta-specs
+            design.md
+            tasks.md
+            reviews/
+            VERIFICATION.md
+conventions/           # 项目约定（按需手写）
+specs/                 # 全局行为契约
+  <domain>/
+    spec.md            # SHALL/MUST + GIVEN/WHEN/THEN
+\`\`\`
+
+### 2. 生成 project.yml
+
+\`\`\`yaml
+version: 1
+platform:
+  - omp
+  - claude-code
+profile: standard  # lite | standard | strict
+context: project   # project | milestone | phase
+workflow:
+  research: true
+  plan_check: true
+  tdd: true
+  triple_review: true
+  auto_advance: true
+  spec_injection: true
+review:
+  gate: all-pass    # all-pass | severity | report-only
+  parallel: true
+change:
+  parallel: serial  # serial | dependency-graph | pipeline
+  isolation: false
+git:
+  branching: none   # none | phase | milestone
+  create_tag: false
+conventions:
+  inject: true
+models: {}
+\`\`\`
+
+### 3. 生成平台文件
+
+运行 \`specwf init\` 自动生成：
+- \`.omp/commands/specwf-<step>.md\` — 14 个 slash command
+- \`skills/specwf-<step>/SKILL.md\` — 14 个 skill 指引
+- \`.omp/agents/specwf-<role>.md\` — 6 个 agent 定义
+
+### 4. 存量项目：并行引导（可选）
+
+如果目标项目已有代码，执行两个并行任务：
+
+**任务 A — Codebase Mapping**
+- 分析技术栈和架构
+- 梳理模块结构和依赖关系
+- 产出 specwf/research/STACK.md + ARCHITECTURE.md
+
+**任务 B — Spec Bootstrap**
+- 从核心模块的函数签名和注释提取行为契约
+- 写入 specs/<domain>/spec.md（标记 \`# BOOTSTRAPPED\`）
+- 从测试文件推断端到端场景
+
+## 产物
+
+- \`specwf/\` 目录结构完整
+- \`specwf/project.yml\` 配置文件
+- 平台文件已生成（.omp/ + skills/）
+- 存量项目额外产出：STACK.md + ARCHITECTURE.md + 初始 specs/
+
+## 验证
+
+- [ ] specwf/ 目录存在且结构完整
+- [ ] project.yml 可被 loadConfig 读取
+- [ ] 平台文件各目录非空
+- [ ] （存量）STACK.md + ARCHITECTURE.md 已生成
+
+## 常见陷阱
+
+- 不要将 specwf/ 目录放在 .gitignore 中（它承载项目元数据）
+- 存量项目的 spec bootstrap 是估算，后续在 plan 的 delta-spec 中精化
+- conventions/ 需要人工编写，不自动生成
+
+## 参考
+
+- OpenSpec 的目录结构设计
+- GSD Core 的新项目初始化流程
+- Trellis 的 spec bootstrap 概念仅作参考（AGPL-3.0 不拷代码）

package/dist/templates/skills/milestone.md

@@ -0,0 +1,36 @@
+# 里程碑管理工作流指引
+
+## 概述
+
+里程碑（Milestone）是版本周期。当前 milestone 所有 phase 完成后，切换到新 milestone。
+
+## 前置条件
+
+- 当前 milestone 已完成
+
+## 执行步骤
+
+### 1. 切换 milestone
+
+```bash
+specwf state set-milestone <id>
+```
+
+### 2. 继续工作流
+
+```bash
+specwf continue
+```
+
+## 产物
+
+- specwf/state.md — current_milestone 更新
+
+## 验证
+
+- [ ] specwf state 确认切换
+- [ ] specwf continue 有可用下一步
+
+## 常见陷阱
+
+- 切换后需更新 roadmap.md 补充新 milestone 的阶段划分

package/dist/templates/skills/plan.md

@@ -0,0 +1,144 @@
+# Change 设计工作流指引
+
+## 概述
+
+对单个 Change 进行详细设计：产出技术方案（design.md）、实现清单（tasks.md）和 delta-specs（规范预先写好的行为契约）。
+
+PLAN 是 Change 循环的起点，决定了后续实现和审查的质量。PLAN 做得好，apply 和 review 就流畅。
+
+## 前置条件
+
+- change 的 proposal.md 已确认
+- context.md 中相关的实现决策已记录
+- 相关的 specs/ 和 conventions/ 已读取
+
+## 执行步骤
+
+### 1. 读取上下文
+
+运行 \`specwf context plan\` 获取当前步骤的上下文清单：
+- 相关的 specs/ 文件
+- conventions/ 文件
+- context.md
+- 外部依赖文档
+
+逐个读取列出的文件。
+
+### 2. 设计技术方案 — design.md
+
+\`\`\`markdown
+# Change: <名称> — 技术方案
+
+## 概述
+## 架构变化
+### 新增模块
+### 修改模块
+### 删除模块
+
+## 数据模型
+### 新增类型
+### 修改类型
+
+## 接口设计
+### 新增接口
+### 修改接口
+
+## 关键算法 / 流程
+## 异常处理
+## 测试策略
+## 风险评估
+\`\`\`
+
+### 3. 编写 delta-specs
+
+在 \`changes/<change>/specs/<domain>/spec.md\` 中预先写本次 change 的行为契约：
+
+\`\`\`markdown
+# <domain> 规格
+
+## SHALL
+- SHALL <条件>: <预期行为>
+  场景: <GIVEN/WHEN/THEN>
+
+## MUST
+- MUST <约束条件>
+  场景: ...
+\`\`\`
+
+**delta-spec 规则**：
+- 只写本次 change 引入或修改的行为
+- 用 SHALL/MUST 表达强制规范
+- 每个条目附带 GIVEN/WHEN/THEN 场景
+- 格式遵循 \`SHALL <条件>: <预期行为>\`
+- 明确引用变更的 spec ID（如有）
+- 覆盖正常路径、边界路径、异常路径
+
+### 4. 拆分为 tasks — tasks.md
+
+\`\`\`markdown
+# Change: <名称> — 实现任务
+
+## type:behavior（需走 TDD 循环）
+1. [ ] RED: <失败的测试>
+   - GREEN: <最小实现>
+   - REFACTOR: <重构目标>
+2. [ ] RED: ...
+
+## type:config（跳过 TDD）
+1. [ ] 配置文件: ...
+
+## type:refactor（跳过 TDD）
+1. [ ] 重构: ...
+
+## type:docs（跳过 TDD）
+1. [ ] 文档: ...
+
+## type:scaffolding（跳过 TDD）
+1. [ ] 脚手架: ...
+\`\`\`
+
+**TDD 协议（强制）**：
+- \`type:behavior\` 任务必须走 RED→GREEN→REFACTOR 三步
+- 每个 RED 任务必须有可运行的失败测试
+- GREEN 是使测试通过的最小实现
+- REFACTOR 不改变行为，只改进结构
+- \`type:config/refactor/docs/scaffolding\` 跳过 RED→GREEN→REFACTOR
+
+### 5. plan-checker 验证
+
+运行 plan-checker 自动验证：
+- [ ] 所有 tasks 标注了 type
+- [ ] type:behavior 任务有完整的 RED→GREEN→REFACTOR 三元组
+- [ ] delta-specs 覆盖了 proposal.md 中所有的 must_haves
+- [ ] 与 context.md 中的决策无矛盾（drift check）
+- [ ] 依赖图完整（跨 change 的 key_links 已标注）
+- [ ] 每个任务有明确的完成标准
+
+## 产物
+
+- \`changes/<change-name>/design.md\` — 技术方案设计
+- \`changes/<change-name>/tasks.md\` — 实现任务清单（含 TDD 标注）
+- \`changes/<change-name>/specs/<domain>/spec.md\` — delta-specs
+
+## 验证
+
+- [ ] plan-checker 输出 PASS
+- [ ] 所有 must_have 被 tasks 覆盖
+- [ ] delta-specs 使用 SHALL/MUST 格式
+- [ ] type:behavior 任务有完整的 RED→GREEN→REFACTOR
+- [ ] design.md 与 context.md 的决策一致
+
+## 常见陷阱
+
+- delta-specs 不能写成实现细节（如「调用 X 函数」），而是行为契约（如「当 X 条件满足时返回 Y」）
+- 不要跳过 type:behavior 的 RED 阶段 — TDD 的关键是测试先行
+- tasks.md 粒度适中：每个任务在 15-60 分钟内完成
+- 如果 change 太大无法清晰拆分 tasks，考虑回到 split 重新拆分
+- delta-specs 覆盖异常路径 — 只写 happy path 等于没写
+
+## 参考
+
+- TDD (Test-Driven Development) by Kent Beck
+- GSD Core 的 plan phase
+- OpenSpec 的 delta-spec 格式
+- spec-checker 验证清单

package/dist/templates/skills/research-phase.md

@@ -0,0 +1,66 @@
+# Phase 调研工作流指引
+
+## 概述
+
+对单个 Phase 的实现路径进行技术调研。与项目级 research 不同，phase research 聚焦于具体的实现选择 —— 库的用法、API 设计模式、性能调优策略、已知坑点等。
+
+调研由 specwf-researcher agent 在独立上下文中并行执行。
+
+## 前置条件
+
+- context.md 已记录本次 phase 的决策
+- 确定了需要调研的技术问题（1-3 个方向）
+
+## 执行步骤
+
+### 1. 提取调研问题
+
+从 context.md 和相关的 specs 中提取需要调研的具体问题：
+- 某个库的特定用法
+- 某类问题的模式或最佳实践
+- 框架的功能边界和限制
+- 性能基准数据
+
+### 2. 执行调研（可并行）
+
+每个问题由 researcher agent 独立调研：
+\`\`\`
+task agent: specwf-researcher
+\`\`\`
+
+调研内容：
+- 阅读官方文档和 API 参考
+- 检查社区实践和已知陷阱
+- （可选）验证关键假设 —— 写最小原型测试
+- 产出 RESEARCH.md
+
+### 3. 更新 context.md
+
+将调研结论的记录 \`[RESEARCHED]\` 标记追加到 context.md：
+- 推荐的实现路径
+- 已知陷阱和规避方法
+- 推荐使用的库版本和配置
+
+## 产物
+
+- \`specwf/research/ph-<name>/RESEARCH.md\` — Phase 调研报告
+- \`specwf/context.md\`（更新，追加调研结论）
+
+## 验证
+
+- [ ] 所有调研问题都有答案
+- [ ] 有推荐的实现路径
+- [ ] 已知陷阱和规避方法
+- [ ] 不遗漏关键依赖项
+
+## 常见陷阱
+
+- 不要只调研「怎么做成」，还要调研「怎么做对」
+- 如果调研发现某个技术选型不可行，立即在 context.md 记录并通知
+- 调研结果要可操作 —— 不是知识收集，是为了指导代码
+- 最小原型对验证关键假设最有效，但不应对原型做重构
+
+## 参考
+
+- GSD Core 的 phase research 路线
+- context.md 格式

package/dist/templates/skills/research.md

@@ -0,0 +1,76 @@
+# 项目技术调研工作流指引
+
+## 概述
+
+对项目涉及的技术方向进行并行多方向调研。产出数据驱动的选型对比报告，为 roadmap 和后续 phase 提供技术基础。
+
+Research 由 specwf-researcher agent 在独立上下文中并行执行。
+
+## 前置条件
+
+- 已完成 grill，proposal.md 已确认
+- 确定了 2-5 个需要调研的方向
+
+## 执行步骤
+
+### 1. 确定调研方向
+
+从 proposal.md 提取需要调研的技术决策点，例如：
+- 框架选择（如 Express vs Fastify vs Hono）
+- 数据库选择（如 PostgreSQL vs SQLite）
+- 部署方案（如 Docker vs 无服务器）
+- 关键库/工具评估（如 zod vs valibot 等）
+
+列出每个方向的候选方案（2-4 个候选）。
+
+### 2. 并行调研（fan-out）
+
+每个方向由独立 researcher agent 执行：
+\`\`\`
+task agent: specwf-researcher × N
+\`\`\`
+
+每个 researcher 的 assignment 包含：
+- **方向**：要调研的技术决策
+- **候选方案**：要对比的选项
+- **评估维度**：功能满足度、性能、社区活跃度、学习曲线、生态集成、许可证
+- **交付要求**：写入 specwf/research/<direction>/STACK.md
+
+### 3. 汇总调研结果
+
+收集所有 researcher 的产出，检查：
+- 所有方向是否有推荐方案和理由
+- 候选方案对比表是否完整
+- 已知的 caveat 和陷阱是否记录
+- 推荐方案是否相互兼容
+
+### 4. 更新 proposal.md
+
+将调研结论的关键决策追加到 proposal.md 的「技术倾向」部分，添加 \`[RESEARCHED]\` 标记。
+
+## 产物
+
+- \`specwf/research/<direction>/STACK.md\` — 每个方向的方案对比和推荐
+- \`specwf/research/<direction>/PITFALLS.md\` — 已知陷阱和注意事项
+- \`specwf/research/summary.md\` — 汇总决策表
+
+## 验证
+
+- [ ] 每个调研方向至少有两个候选方案的对比
+- [ ] 推荐方案都有明确理由
+- [ ] 已知陷阱已记录
+- [ ] 推荐的多个方案之间兼容性已检查
+- [ ] proposal.md 已更新调研结论
+
+## 常见陷阱
+
+- 避免只调研一个方案（确认偏差）
+- 避免过度调研 — 设定每个方向 10-20 条有效信息来源的上限
+- 注意许可证兼容性（GPL/AGPL vs MIT/Apache）
+- 框架的版本号重要 — 确认调研的是最新稳定版
+- 团队熟悉度是合法因素，在推荐理由中记录
+
+## 参考
+
+- GSD Core 的 research phase 路线
+- OpenSpec 的 STACK.md 模板

package/dist/templates/skills/review.md

@@ -0,0 +1,148 @@
+# 三重审查工作流指引
+
+## 概述
+
+对 Apply 产出的代码进行三重并行审查：规格审查、质量审查、目标审查。三重审查全部通过后才能进入 verify 阶段。
+
+Review 由 specwf-reviewer agent 在独立上下文中并行执行。审查结果决定是否需要回 apply 修改。
+
+## 前置条件
+
+- apply 阶段已完成，代码已提交
+- delta-specs、design.md、tasks.md、proposal.md 已就位
+
+## 执行步骤
+
+### 1. 并行启动三重审查
+
+一次启动三个 reviewer agent 并行审查：
+\`\`\`
+task agent: specwf-reviewer × 3（并行）
+  1. Spec Review — 规格符合性审查
+  2. Quality Review — 代码质量审查
+  3. Goal Review — 目标达成审查
+\`\`\`
+
+### 2. 规格审查（Spec Review）
+
+**检查项**：
+- [ ] delta-specs 中的每个 SHALL 场景在代码中实现
+- [ ] delta-specs 中的每个 MUST 约束在代码中遵守
+- [ ] 全局 specs/ 中相关的 SHALL/MUST 未被违反
+- [ ] GIVEN/WHEN/THEN 场景在测试中覆盖
+- [ ] 接口签名与 design.md 一致
+- [ ] 异常处理覆盖 spec 中定义的错误场景
+
+**输出**: \`reviews/spec-review.md\`
+\`\`\`markdown
+# 规格审查报告
+
+## 审查结果：PASS / FAIL / CONDITIONAL_PASS
+
+## 通过项
+- SHALL-001: ✓ 已实现且测试覆盖
+- ...
+
+## 未通过项
+- SHALL-003: ✗ 未处理输入为空场景
+  - 严重性: HIGH / MEDIUM / LOW
+  - 建议: ...
+
+## 与全局 specs 冲突
+- ...
+\`\`\`
+
+### 3. 质量审查（Quality Review）
+
+**检查项**：
+- [ ] 明显的 bug 模式（空指针、越界、竞态条件）
+- [ ] 安全漏洞（注入、权限缺失、敏感信息泄露）
+- [ ] 代码规范（项目约定的代码风格和模式）
+- [ ] 测试质量（不是 trivial 测试，覆盖边界条件）
+- [ ] 性能问题（不必要的分配、N+1 查询等）
+- [ ] 错误处理（错误被吞没、错误信息不明确）
+
+**输出**: \`reviews/quality-review.md\`
+\`\`\`markdown
+# 质量审查报告
+
+## 审查结果：PASS / FAIL / CONDITIONAL_PASS
+
+## Bug 类
+- ...
+
+## 安全类
+- ...
+
+## 规范类
+- ...
+
+## 测试质量
+- ...
+\`\`\`
+
+### 4. 目标审查（Goal Review）
+
+**检查项**：
+- [ ] change proposal.md 中定义的目标已实现
+- [ ] tasks.md 中所有 tasks 已完成（无论 type）
+- [ ] design.md 中的方案在代码中落地
+- [ ] 没有 scope creep（实现了 proposal 外的功能）
+- [ ] 测试覆盖满足 change 的测试策略要求
+
+**输出**: \`reviews/goal-review.md\`
+\`\`\`markdown
+# 目标审查报告
+
+## 审查结果：PASS / FAIL / CONDITIONAL_PASS
+
+## 目标达成
+- proposal 目标 1: ✓
+- ...
+
+## 任务完成度
+- tasks.md 完成: 7/7
+
+## Scope Creep 检查
+- 发现 1 处额外实现: ...
+\`\`\`
+
+### 5. 汇总结果
+
+收集所有三份审查报告，根据 gate 配置决定是否进入 verify：
+
+- **all-pass（默认）**：三份报告都 PASS 才进入 verify
+- **severity**：没有 HIGH 严重性问题即可进入 verify
+- **report-only**：审查结果仅供参考，不阻止进入 verify
+
+任一审查 FAIL 时：
+- 记录问题清单
+- 回 apply 阶段修复
+- 修复后重新审查涉及的部分
+
+## 产物
+
+- \`changes/<change-name>/reviews/spec-review.md\` — 规格审查报告
+- \`changes/<change-name>/reviews/quality-review.md\` — 质量审查报告
+- \`changes/<change-name>/reviews/goal-review.md\` — 目标审查报告
+
+## 验证
+
+- [ ] 三重审查全部完成
+- [ ] gate 条件满足（根据配置）
+- [ ] 审查报告写入对应目录
+- [ ] FAIL 的问题在回 apply 前修复
+
+## 常见陷阱
+
+- 不要合并审查职责 — 规格/质量/目标是三个独立视角，必须由不同 reviewer（或至少不同上下文）执行
+- 不要在审查报告里写模糊的描述 — 每个问题必须有文件/行号引用
+- 不要把「风格偏好」作为 FAIL 理由 — 只有违反项目约定的才记录
+- 如果条件允许，一次审查只覆盖单个 change 的 diff，不涉及全局代码
+- ALL-PASS 模式下，一个 CONDITIONAL_PASS 算 FAIL
+
+## 参考
+
+- GSD Core 的 triple review 机制
+- OpenSpec 的 review 模板
+- OWASP 代码审查指南（质量审查的安全类参考）

package/dist/templates/skills/roadmap.md

@@ -0,0 +1,104 @@
+# 路线图工作流指引
+
+## 概述
+
+将项目拆分为 Milestone 和 Phase 两个层级。Milestone 是长期里程碑（通常 1-3 个月），Phase 是 Milestone 内的开发阶段（通常 1-2 周）。
+
+路线图基于 proposal.md 和 research 产出，输出可执行的阶段规划。
+
+## 前置条件
+
+- 已完成 grill
+- （可选）已完成 research —— 调研结果指导技术栈拆分
+- 对项目范围有清晰共识
+
+## 执行步骤
+
+### 1. 定义 Milestone
+
+按功能领域或发布节奏划分里程碑。每个 milestone 应有：
+- **名称**：简短标识（如 \`M1-core\`）
+- **目标**：一个句子描述的里程碑目标
+- **范围**：包含和不包含的功能
+- **成功标准**：可测量的完成条件
+- **预估时长**：1-3 个月
+
+示例：
+\`\`\`
+M1 — Core Infrastructure
+目标：搭建基础 CLI 框架 + spec 管理系统
+范围：init/grill/research/roadmap/.../archive 完整循环
+时长：6 周
+\`\`\`
+
+### 2. 为每个 Milestone 拆分 Phase
+
+每个 milestone 包含 3-8 个 phase：
+\`\`\`
+<ms-name>
+├── ph.1 基础搭建
+├── ph.2 核心功能 A
+├── ph.3 核心功能 B
+├── ph.4 集成测试
+└── ph.5 文档和完善
+\`\`\`
+
+每个 Phase 定义：
+- **名称**（ph.N-<name>）
+- **目标**
+- **依赖**（依赖的技术或前置 phase）
+- **输入**（specs 文件、conventions、设计文档）
+- **输出**（代码、specs 更新、文档）
+- **预估 Change 数**
+
+### 3. 验证里程碑覆盖
+
+逐项检查 proposal.md 的「范围」是否被 Milestone 和 Phase 完整覆盖：
+- 没有遗漏的功能
+- 依赖关系合理
+- Phase 之间的依赖不形成循环
+
+### 4. 产出 ROADMAP.md
+
+\`\`\`markdown
+# <项目> 路线图
+
+## Milestone 概览
+
+| Milestone | 目标 | Phase 数 | 时长 |
+|---|---|---|---|
+
+## M1 — <名称>
+<Milestone 目标>
+
+### Phase 列表
+
+| Phase | 目标 | 依赖 | 预估 Change 数 |
+|---|---|---|---|
+
+### ph.1 <名称>
+<详细说明>
+\`\`\`
+
+## 产物
+
+- \`specwf/ROADMAP.md\` — 完整的路线图文档
+
+## 验证
+
+- [ ] 所有 proposal.md 范围被覆盖
+- [ ] Phase 之间的依赖不循环
+- [ ] 每个 Phase 有可验证的成功标准
+- [ ] 路线图长度合理（3-15 个 Phase 总）
+
+## 常见陷阱
+
+- 不要把 Phase 拆得太细 — 每个 phase 至少能产出可演示的成果
+- 第一个 Phase 应该是最小可行路径，不是最复杂的
+- 不要忽略集成和文档 phase
+- Phase 的先后依赖不要过于乐观 — 列清楚前置条件
+
+## 参考
+
+- GSD Core 的 roadmap 方法
+- 产品路线图最佳实践（outcome-focused）