specwf 0.2.0

package/dist/templates/skills/ship.md

@@ -0,0 +1,94 @@
+# 交付工作流指引
+
+## 概述
+
+将完成的 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

@@ -0,0 +1,96 @@
+# 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

@@ -0,0 +1,147 @@
+# 测试验证工作流指引
+
+## 概述
+
+在 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 模板

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "specwf",
+  "version": "0.2.0",
+  "description": "规格驱动开发工作流 — spec-driven development workflow for AI coding agents",
+  "type": "module",
+  "bin": {
+    "specwf": "bin/specwf.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.6.0",
+    "commander": "^15.0.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "spec-driven",
+    "workflow",
+    "ai-agent",
+    "cli",
+    "openspec",
+    "gsd"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperion2144/specwf.git"
+  },
+  "exports": {
+    ".": "./dist/cli.js"
+  }
+}