specwf 0.2.2 → 0.3.0

package/dist/templates/skills/review.md

@@ -1,148 +0,0 @@
-# 三重审查工作流指引
-
-## 概述
-
-对 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

@@ -1,104 +0,0 @@
-# 路线图工作流指引
-
-## 概述
-
-将项目拆分为 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）

package/dist/templates/skills/ship.md

@@ -1,94 +0,0 @@
-# 交付工作流指引
-
-## 概述
-
-将完成的 phase（或其变更集）交付。Ship 分为两级：(1) Ship Phase — 创建 PR + 更新 STATE.md；(2) Ship Milestone — 创建 release tag + 更新 PROJECT.md 版本。
-
-Ship Phase 在每个 phase 的 change 循环全部完成后触发。Ship Milestone 在 milestone 的所有 phase 完成后触发。
-
-## 前置条件
-
-- 当前 phase 内所有 change 的 verify 已通过（passed 状态）
-- archive 已执行
-
-## 执行步骤
-
-### 1. 检查交付就绪
-
-- [ ] 所有 change 的 VERIFICATION.md 状态为 passed
-- [ ] 所有 change 已 archive（delta-specs 已合并、代码认知已提取）
-- [ ] 没有未合并的 delta-spec 冲突
-- [ ] 测试通过、构建通过
-
-### 2. Ship Phase
-
-**创建 PR**：
-\`\`\`
-git checkout -b ship/ph-<phase-name>
-git merge --squash <phase-branch>（或逐个 cherry-pick change）
-git commit -m "feat(<phase>): <phase 标题>"
-git push origin ship/ph-<phase-name>
-\`\`\`
-
-创建 PR：
-- 标题：\`feat(<phase>): <标题>\`
-- 正文包含：
-  - 本 phase 的 scope 概述
-  - 包含的 change 列表
-  - 变更统计（文件数、行数）
-  - 测试覆盖状态
-  - CHECKLIST（所有 change 已 verify passed、已 archive）
-
-PR 通过后合并到主分支。
-
-**更新 STATE.md**：
-\`\`\`markdown
-# 状态
-
-## Phase: <name>
-- 状态: ✅ shipped
-- PR: #<PR 号>
-- Ship 日期: <date>
-\`\`\`
-
-### 3. Ship Milestone（可选，仅在 milestone 全部完成时）
-
-当 milestone 的最后 phase ship 后：
-
-\`\`\`
-git tag v<major>.<minor>.<patch>
-git push origin v<major>.<minor>.<patch>
-\`\`\`
-
-更新 PROJECT.md（或 README.md）的版本号和 changelog。
-
-### 4. 通知
-
-（可选）在项目日志或 release notes 中记录交付内容。
-
-## 产物
-
-- GitHub PR（ship phase）
-- \`specwf/STATE.md\`（更新，标记 phase 为 shipped）
-- （milestone）git tag + release notes
-
-## 验证
-
-- [ ] PR 已创建且包含完整信息
-- [ ] STATE.md 已更新
-- [ ] CI 通过
-- [ ] （milestone）tag 已创建和推送
-- [ ] 主分支代码与 PR 一致
-
-## 常见陷阱
-
-- 不要跳过 PR 直接合并到主分支 — PR 是审计轨迹的一部分
-- squash merge 要注意 squash 后的 message 包含所有 change 信息
-- 如果发现 CI 失败，不要强行合并 — 修复后重试
-- STATE.md 更新使用 \`shipped\` 枚举值，不是自由文本
-- Milestone ship 前确认所有 phase 都已 shipped
-
-## 参考
-
-- Conventional Commits 规范（feat 类型）
-- GSD Core 的 ship 流程

package/dist/templates/skills/split.md

@@ -1,96 +0,0 @@
-# Change 拆分工作流指引
-
-## 概述
-
-将 Phase 的工作拆分为多个可并行（或有序）执行的 Change。每个 Change 是独立可验证的工作单元，有明确的输入输出和被测试场景覆盖。
-
-拆分产出依赖图，支持三种并行策略：串行、依赖图并行、流水线并行。
-
-## 前置条件
-
-- context.md 已完成
-- phase 的 scope 和接口边界明确
-
-## 执行步骤
-
-### 1. 识别独立工作单元
-
-从 phase 的 scope 中识别可独立实现和验证的功能单位：
-- 每个 change 对应一个完整的功能切面
-- 不跨 change 共享未完成的代码（除非依赖图明确）
-- 每个 change 有明确的可验证结果
-
-### 2. 建立依赖关系
-
-绘制 change 之间的依赖图：
-\`\`\`
-Change A ──→ Change B ──→ Change C
-                  ↓
-            Change D ──→ Change E
-\`\`\`
-
-依赖类型：
-- **数据依赖**：B 依赖 A 的数据结构
-- **接口依赖**：D 依赖 B 的接口
-- **顺序依赖**：C 必须在 B 之后（但不需要 B 的产出物）
-
-### 3. 为每个 Change 准备 skeleton
-
-每个 change 的目录：
-\`\`\`
-changes/<change-name>/
-├── proposal.md       # 当前 change 的需求范围
-├── specs/
-│   └── <domain>/
-│       └── spec.md   # delta-specs（初始空，plan 阶段写）
-├── design.md         # （plan 阶段产出）
-├── tasks.md          # （plan 阶段产出）
-├── reviews/          # （review 阶段产出）
-└── VERIFICATION.md   # （verify 阶段产出）
-\`\`\`
-
-proposal.md 内容：
-\`\`\`markdown
-# Change: <名称>
-
-## 目标
-## 范围
-## 依赖（前置 change 列表）
-## 关键接口（输入/输出/副作用）
-## 测试场景清单
-\`\`\`
-
-### 4. 确认并行策略
-
-根据 change 依赖图配置并行策略：
-
-- **serial**: 所有 change 串行（依赖图全序）
-- **dependency-graph**: 无依赖的 change 并行，有依赖的串行（默认推荐）
-- **pipeline**: 按依赖深度分层，同层并行、异层流水线
-
-## 产物
-
-- \`changes/<change-name>/proposal.md\` — 每个 change 的定义
-- \`changes/<change-name>/specs/\` — 每个 change 的 delta-specs 目录（初始空）
-- 依赖图（在 conversation 中记录，不生成独立文件）
-
-## 验证
-
-- [ ] 每个 change 有明确的可验证结果
-- [ ] 依赖图无循环
-- [ ] 变更范围不重叠
-- [ ] 所有 phase scope 被覆盖
-- [ ] 依赖关系合理（无缺少的依赖）
-
-## 常见陷阱
-
-- change 太大 → 超出 review 合理范围（建议单个 change ≤ 400 行 diff）
-- change 太小 → 上下文切换成本高于并行收益
-- 不要「偷渡」未计划的改动到一个 change 中
-- 依赖图不要太深（3 层以上意味着拆分粒度需要调整）
-- 如果不确定独立程度，宁拆大不拆小
-
-## 参考
-
-- OpenSpec 的 change 结构设计
-- GSD Core 的 dependency-graph 并行策略

package/dist/templates/skills/verify.md

@@ -1,147 +0,0 @@
-# 测试验证工作流指引
-
-## 概述
-
-在 Review 通过后，对实现进行完整的测试验证。Verify 负责确保代码正确运行、所有场景覆盖，并处理回环路由 —— 根据缺陷类型路由到不同的修复阶段。
-
-## 前置条件
-
-- review 阶段已通过（三重审查全部 PASS 或 gate 条件满足）
-- 测试套件完整（包括 RED 阶段写的测试）
-
-## 执行步骤
-
-### 1. 运行完整测试套件
-
-\`\`\`
-# 运行所有测试
-bun run test
-
-# 运行类型检查
-bun run typecheck
-
-#（可选）运行集成测试
-bun run test:integration
-\`\`\`
-
-### 2. 测试覆盖率分析
-
-分析测试覆盖缺口：
-- delta-specs 中每个 SHALL/MUST 是否有测试
-- 正常路径覆盖
-- 边界路径覆盖
-- 异常路径覆盖
-
-### 3. 人工检查点验证
-
-逐项检查 tasks.md 中每个任务的完成标准：
-\`\`\`
-- [ ] 所有 type:behavior 验证通过
-- [ ] 所有非 TDD 任务验证通过
-- [ ] 无回归（已有测试通过）
-- [ ] 代码未破坏依赖项
-\`\`\`
-
-### 4. 诊断失败（如有）
-
-如果任何测试失败或验证不通过：
-
-**根因诊断**：
-1. 确定失败是测试问题还是实现问题
-2. 明确缺陷的类型（见下方路由规则）
-3. 在 VERIFICATION.md 中记录根因
-
-### 5. 回环路由
-
-根据缺陷类型路由到不同阶段：
-
-\`\`\`
-# 路由规则
-
-## 计划缺陷 → 回 plan 重设计
-触发条件：
-- delta-specs 中的场景在代码中无法实现（设计不合理）
-- design.md 的方案有架构缺陷
-- 依赖关系在 split 时未正确识别
-- 拆分的 tasks 粒度不合理
-
-行为：
-1. 标记缺陷类型为 PLAN
-2. 记录问题和修改建议
-3. 输出 \`路由目标: plan\`
-4. 不修代码，回 plan 更新 design.md / tasks.md / delta-specs
-
-## 实现缺陷 → 回 apply 重实现
-触发条件：
-- 测试失败（实现未满足 delta-spec）
-- 代码逻辑错误
-- 类型错误
-- 性能不达标
-- 缺少边界处理
-
-行为：
-1. 标记缺陷类型为 IMPLEMENTATION
-2. 记录根因和具体位置（文件+行号）
-3. 输出 \`路由目标: apply\`
-4. 回 apply 修复实现
-
-## 规格缺陷 → 标记 spec 待修（回 plan）
-触发条件：
-- delta-specs 本身不合理或矛盾
-- 现有 specs/ 被违反但 delta-specs 未覆盖
-- 场景遗漏（关键路径缺少 spec 定义）
-- spec 与需求矛盾
-
-行为：
-1. 标记缺陷类型为 SPEC
-2. 记录问题描述和修复建议
-3. 输出 \`路由目标: plan（spec 待修）\`
-4. 在 specs/ 中标记 \`[TODO: FIX SPEC]\`
-5. 回 plan 修正规格
-\`\`\`
-
-### 6. 产出 VERIFICATION.md
-
-\`\`\`markdown
-# Change: <名称> — 验证报告
-
-## 测试结果
-- 单元测试: 通过 / 失败（N/N）
-- 类型检查: 通过 / 失败
-- 集成测试: 通过 / 失败（可选）
-
-## 覆盖率
-- 正常路径: N/N
-- 边界路径: N/N
-- 异常路径: N/N
-
-## 路由决策
-- 状态: passed | replan | reapply
-- 路由目标: （通过时不填）
-- 缺陷类型: PLAN | IMPLEMENTATION | SPEC
-- 根因: ...
-\`\`\`
-
-## 产物
-
-- \`changes/<change-name>/VERIFICATION.md\` — 验证报告
-
-## 验证
-
-- [ ] 测试套件全部通过（passed 时）
-- [ ] delta-specs SHALL/MUST 全覆盖
-- [ ] tasks.md 完成标准全通过
-- [ ] VERIFICATION.md 路由决策清晰
-
-## 常见陷阱
-
-- 不要自己修发现的问题 — 路由是给主流程的信号，不是直接在 verify 中修改代码
-- 不要混淆缺陷类型 —「这代码写错了」是 IMPLEMENTATION，「这规格就不对」是 SPEC
-- 如果多个缺陷属于不同类型，按优先级最高的路由
-- 不要只跑单元测试 — 集成测试才能暴露接口交互问题
-- 路由前确认缺陷确实可重现，不是测试环境配置问题
-
-## 参考
-
-- GSD Core 的 verify phase 回环机制
-- OpenSpec 的 verification 模板