specops 0.2.4 → 0.3.0

package/.opencode/workflows/new-milestone.md

@@ -0,0 +1,382 @@
+<purpose>
+
+为现有项目启动新的里程碑周期。加载项目上下文，收集里程碑目标（来自 MILESTONE-CONTEXT.md 或对话），更新 PROJECT.md 和 STATE.md，可选运行并行研究，定义带 REQ-ID 的范围化需求，生成路线图规划器创建分阶段执行计划，并提交所有产物。相当于 new-project 的棕地版本。
+
+</purpose>
+
+<required_reading>
+
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+
+</required_reading>
+
+<process>
+
+## 1. 加载上下文
+
+- 读取 PROJECT.md（现有项目、已验证的需求、决策）
+- 读取 MILESTONES.md（之前交付了什么）
+- 读取 STATE.md（待办事项、阻塞项）
+- 检查 MILESTONE-CONTEXT.md（来自 /specops:discuss-milestone）
+
+## 2. 收集里程碑目标
+
+**如果 MILESTONE-CONTEXT.md 存在：**
+- 使用 discuss-milestone 中的功能和范围
+- 展示摘要以获取确认
+
+**如果没有上下文文件：**
+- 展示上一个里程碑交付了什么
+- 询问："你接下来想构建什么？"
+- 使用 AskUserQuestion 探索功能、优先级、约束、范围
+
+## 3. 确定里程碑版本
+
+- 从 MILESTONES.md 解析上一个版本
+- 建议下一个版本（v1.0 → v1.1，或 v2.0 用于主要版本）
+- 与用户确认
+
+## 4. 更新 PROJECT.md
+
+添加/更新：
+
+```markdown
+## Current Milestone: v[X.Y] [Name]
+
+**Goal:** [描述里程碑焦点的一句话]
+
+**Target features:**
+- [功能 1]
+- [功能 2]
+- [功能 3]
+```
+
+更新活跃需求部分和"Last updated"页脚。
+
+## 5. 更新 STATE.md
+
+```markdown
+## Current Position
+
+Phase: Not started (defining requirements)
+Plan: —
+Status: Defining requirements
+Last activity: [today] — Milestone v[X.Y] started
+```
+
+保留上一个里程碑的 Accumulated Context 部分。
+
+## 6. 清理并提交
+
+如果存在则删除 MILESTONE-CONTEXT.md（已消费）。
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+```
+
+## 7. 加载上下文并解析模型
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init new-milestone)
+```
+
+从初始化 JSON 中提取：`researcher_model`、`synthesizer_model`、`roadmapper_model`、`commit_docs`、`research_enabled`、`current_milestone`、`project_exists`、`roadmap_exists`。
+
+## 8. 研究决策
+
+AskUserQuestion："在定义需求之前，是否研究新功能的领域生态系统？"
+- "先研究（推荐）" — 为新能力发现模式、功能、架构
+- "跳过研究" — 直接进入需求
+
+**将选择持久化到配置**（以便后续 `/specops:plan-phase` 遵循）：
+
+```bash
+# 如果选择"先研究"：持久化 true
+node .opencode/bin/specops-tools.cjs config-set workflow.research true
+
+# 如果选择"跳过研究"：持久化 false
+node .opencode/bin/specops-tools.cjs config-set workflow.research false
+```
+
+**如果选择"先研究"：**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 正在研究
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 并行生成 4 个研究员……
+  → 技术栈、功能、架构、陷阱
+```
+
+```bash
+mkdir -p .planning/research
+```
+
+生成 4 个并行的 specops-project-researcher Agent。每个使用此模板并填充维度特定字段：
+
+**所有 4 个研究员的通用结构：**
+```
+Task(prompt="
+<research_type>Project Research — {DIMENSION} for [new features].</research_type>
+
+<milestone_context>
+SUBSEQUENT MILESTONE — Adding [target features] to existing app.
+{EXISTING_CONTEXT}
+Focus ONLY on what's needed for the NEW features.
+</milestone_context>
+
+<question>{QUESTION}</question>
+
+<files_to_read>
+- .planning/PROJECT.md (Project context)
+</files_to_read>
+
+<downstream_consumer>{CONSUMER}</downstream_consumer>
+
+<quality_gate>{GATES}</quality_gate>
+
+<output>
+Write to: .planning/research/{FILE}
+Use template: .opencode/templates/research-project/{FILE}
+</output>
+", subagent_type="specops-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+```
+
+**维度特定字段：**
+
+| 字段 | Stack | Features | Architecture | Pitfalls |
+|------|-------|----------|-------------|----------|
+| EXISTING_CONTEXT | 现有已验证能力（不要重新研究）：[来自 PROJECT.md] | 现有功能（已构建）：[来自 PROJECT.md] | 现有架构：[来自 PROJECT.md 或代码库映射] | 聚焦于向现有系统添加这些功能时的常见错误 |
+| QUESTION | [新功能]需要哪些技术栈添加/变更？ | [目标功能]通常如何工作？预期行为？ | [目标功能]如何与现有架构集成？ | 向[领域]添加[目标功能]时的常见错误？ |
+| CONSUMER | 新能力的具体库及版本、集成点、不应添加的内容 | 基本功能 vs 差异化功能 vs 反功能，标注复杂度，现有依赖 | 集成点、新组件、数据流变更、建议构建顺序 | 警告信号、预防策略、哪个阶段应处理 |
+| GATES | 版本最新（用 Context7 验证）、理由说明为什么、考虑了集成 | 类别清晰、标注复杂度、识别依赖 | 识别集成点、明确新增 vs 修改、构建顺序考虑依赖 | 陷阱针对添加这些功能、覆盖集成陷阱、预防可操作 |
+| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
+
+所有 4 个完成后，生成合成器：
+
+```
+Task(prompt="
+Synthesize research outputs into SUMMARY.md.
+
+<files_to_read>
+- .planning/research/STACK.md
+- .planning/research/FEATURES.md
+- .planning/research/ARCHITECTURE.md
+- .planning/research/PITFALLS.md
+</files_to_read>
+
+Write to: .planning/research/SUMMARY.md
+Use template: .opencode/templates/research-project/SUMMARY.md
+Commit after writing.
+", subagent_type="specops-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+```
+
+展示 SUMMARY.md 中的关键发现：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 研究完成 ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**技术栈添加：** [来自 SUMMARY.md]
+**基本功能：** [来自 SUMMARY.md]
+**注意事项：** [来自 SUMMARY.md]
+```
+
+**如果选择"跳过研究"：** 继续到步骤 9。
+
+## 9. 定义需求
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 定义需求
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+读取 PROJECT.md：核心价值、当前里程碑目标、已验证的需求（已有的）。
+
+**如果研究存在：** 读取 FEATURES.md，提取功能类别。
+
+按类别展示功能：
+```
+## [类别 1]
+**基本功能：** 功能 A、功能 B
+**差异化功能：** 功能 C、功能 D
+**研究备注：** [任何相关备注]
+```
+
+**如果没有研究：** 通过对话收集需求。询问："[新功能]的主要用户需求是什么？"澄清，探索相关能力，按类别分组。
+
+**通过 AskUserQuestion 确定每个类别的范围**（multiSelect: true，header 最多 12 字符）：
+- "[功能 1]" — [简要描述]
+- "[功能 2]" — [简要描述]
+- "此里程碑不需要" — 推迟整个类别
+
+追踪：已选择 → 此里程碑。未选择的基本功能 → 未来。未选择的差异化功能 → 超出范围。
+
+**通过 AskUserQuestion 识别缺口：**
+- "不，研究已覆盖" — 继续
+- "是，让我补充一些" — 捕获补充内容
+
+**生成 REQUIREMENTS.md：**
+- v1 需求按类别分组（复选框，REQ-ID）
+- 未来需求（已推迟）
+- 超出范围（明确排除及理由）
+- 追溯部分（空的，由路线图填充）
+
+**REQ-ID 格式：** `[CATEGORY]-[NUMBER]`（AUTH-01、NOTIF-02）。从现有编号继续。
+
+**需求质量标准：**
+
+好的需求应该是：
+- **具体且可测试：** "用户可以通过邮件链接重置密码"（不是"处理密码重置"）
+- **以用户为中心：** "用户可以 X"（不是"系统做 Y"）
+- **原子化：** 每个需求一个能力（不是"用户可以登录并管理个人资料"）
+- **独立：** 对其他需求的依赖最小
+
+展示完整需求列表以获取确认：
+
+```
+## 里程碑 v[X.Y] 需求
+
+### [类别 1]
+- [ ] **CAT1-01**：用户可以做 X
+- [ ] **CAT1-02**：用户可以做 Y
+
+### [类别 2]
+- [ ] **CAT2-01**：用户可以做 Z
+
+这是否涵盖了你要构建的内容？（是 / 调整）
+```
+
+如果选择"调整"：返回范围确定。
+
+**提交需求：**
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
+```
+
+## 10. 创建路线图
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 创建路线图
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 生成路线图规划器……
+```
+
+**起始阶段编号：** 读取 MILESTONES.md 获取上一个阶段编号。从那里继续（v1.0 在阶段 5 结束 → v1.1 从阶段 6 开始）。
+
+```
+Task(prompt="
+<planning_context>
+<files_to_read>
+- .planning/PROJECT.md
+- .planning/REQUIREMENTS.md
+- .planning/research/SUMMARY.md (if exists)
+- .planning/config.json
+- .planning/MILESTONES.md
+</files_to_read>
+</planning_context>
+
+<instructions>
+Create roadmap for milestone v[X.Y]:
+1. Start phase numbering from [N]
+2. Derive phases from THIS MILESTONE's requirements only
+3. Map every requirement to exactly one phase
+4. Derive 2-5 success criteria per phase (observable user behaviors)
+5. Validate 100% coverage
+6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+7. Return ROADMAP CREATED with summary
+
+Write files first, then return.
+</instructions>
+", subagent_type="specops-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+```
+
+**处理返回：**
+
+**如果 `## ROADMAP BLOCKED`：** 展示阻塞项，与用户协作，重新生成。
+
+**如果 `## ROADMAP CREATED`：** 读取 ROADMAP.md，内联展示：
+
+```
+## 拟定路线图
+
+**[N] 个阶段** | **[X] 个需求已映射** | 全部覆盖 ✓
+
+| # | 阶段 | 目标 | 需求 | 成功标准 |
+|---|------|------|------|----------|
+| [N] | [名称] | [目标] | [REQ-ID] | [数量] |
+
+### 阶段详情
+
+**阶段 [N]：[名称]**
+目标：[目标]
+需求：[REQ-ID]
+成功标准：
+1. [标准]
+2. [标准]
+```
+
+**通过 AskUserQuestion 请求批准：**
+- "批准" — 提交并继续
+- "调整阶段" — 告诉我要改什么
+- "查看完整文件" — 显示原始 ROADMAP.md
+
+**如果选择"调整"：** 获取备注，带修订上下文重新生成路线图规划器，循环直到批准。
+**如果选择"查看"：** 显示原始 ROADMAP.md，重新询问。
+
+**提交路线图**（批准后）：
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+## 11. 完成
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps ► 里程碑已初始化 ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**里程碑 v[X.Y]：[名称]**
+
+| 产物           | 位置                        |
+|----------------|-----------------------------|
+| 项目           | `.planning/PROJECT.md`      |
+| 研究           | `.planning/research/`       |
+| 需求           | `.planning/REQUIREMENTS.md` |
+| 路线图         | `.planning/ROADMAP.md`      |
+
+**[N] 个阶段** | **[X] 个需求** | 准备构建 ✓
+
+## ▶ 下一步
+
+**阶段 [N]：[阶段名称]** — [目标]
+
+`/specops:discuss-phase [N]` — 收集上下文并明确方案
+
+<sub>先 `/clear` → 全新上下文窗口</sub>
+
+也可以：`/specops:plan-phase [N]` — 跳过讨论，直接规划
+```
+
+</process>
+
+<success_criteria>
+- [ ] PROJECT.md 已更新 Current Milestone 部分
+- [ ] STATE.md 已为新里程碑重置
+- [ ] MILESTONE-CONTEXT.md 已消费并删除（如果存在）
+- [ ] 研究已完成（如果选择）— 4 个并行 Agent，里程碑感知
+- [ ] 需求已按类别收集和确定范围
+- [ ] REQUIREMENTS.md 已创建并包含 REQ-ID
+- [ ] specops-roadmapper 已使用阶段编号上下文生成
+- [ ] 路线图文件已立即写入（非草稿）
+- [ ] 用户反馈已纳入（如有）
+- [ ] ROADMAP.md 阶段从上一个里程碑继续编号
+- [ ] 所有提交已完成（如果规划文档需要提交）
+- [ ] 用户知道下一步：`/specops:discuss-phase [N]`
+
+**原子提交：** 每个阶段立即提交其产物。
+</success_criteria>