specwf 0.2.2 → 0.3.0

package/dist/templates/skills/discuss.md

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

@@ -1,90 +0,0 @@
-# 需求探讨工作流指引
-
-## 概述
-
-通过无限制细节提问，与用户深入探讨需求，直到对项目的目标、范围、约束和技术方向达成共识。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 流程

package/dist/templates/skills/init.md

@@ -1,116 +0,0 @@
-# 项目初始化工作流指引
-
-## 概述
-
-初始化 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

@@ -1,36 +0,0 @@
-# 里程碑管理工作流指引
-
-## 概述
-
-里程碑（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

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

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

@@ -1,76 +0,0 @@
-# 项目技术调研工作流指引
-
-## 概述
-
-对项目涉及的技术方向进行并行多方向调研。产出数据驱动的选型对比报告，为 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 模板