Current Position

Current Position

Phase: Not started (defining requirements) Plan: — Status: Defining requirements Last activity: [today] — Milestone v[X.Y] started

工作流中特意引用了 **Bug #2630** 作为反面教训：旧版本手改 Current Position 正文却让 frontmatter 停留在上一里程碑，导致 `state.json`、`getMilestoneInfo`、进度条等所有下游读取方一直报告过期里程碑，直到第一次阶段推进强制同步才修复。这正是"务必走 `state.milestone-switch` SDK handler"的原因。

### 清理与提交

```bash
# 删除已消费的 MILESTONE-CONTEXT.md（如存在）
# 清空上一里程碑遗留的阶段目录
gsd-sdk query phases.clear --confirm
# 提交文档改动
gsd-sdk query commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md

六、Step 7–7.5：初始化上下文、解析模型与 --reset-phase-numbers 安全门禁

工作流通过 gsd-sdk query init.new-milestone 获取初始化 JSON（可能以 @file: 前缀指向临时文件，需 cat 展开），并解析出 researcher_model、synthesizer_model、roadmapper_model、research_enabled、current_milestone、project_exists、phase_dir_count、phase_archive_path、agents_installed、missing_agents 等字段，同时用 gsd-sdk query agent-skills gsd-project-researcher|gsd-research-synthesizer|gsd-roadmapper 取回三个子代理的技能块。

子代理缺失时的降级路径

若 agents_installed 为 false，工作流会打印警告（列出缺失代理），并提示用 npx get-shit-done-cc@latest --global 安装，然后跳过并行研究、改为内联生成路线图——不让编排直接失败。

--reset-phase-numbers 的安全设计

选择从 Phase 1 重新编号时，若上一里程碑遗留了阶段目录（phase_dir_count > 0），必须先归档旧目录，否则新的 01-*/02-* 会与陈旧目录冲突：

mkdir -p "${phase_archive_path}"
find .planning/phases -mindepth 1 -maxdepth 1 -type d -exec mv {} "${phase_archive_path}/" \;

归档后需校验 .planning/phases/ 不再含旧目录；若 phase_dir_count > 0 但缺少归档目标（phase_archive_path 为空），工作流会停止并解释"缺少已完成里程碑归档目标时重置编号不安全"，要求先完成/归档上一里程碑再重跑 /gsd:new-milestone --reset-phase-numbers。

七、Step 8：研究决策——并行 4 路领域研究

第 8 步从 init JSON 读取 research_enabled（来源是 config），但用户本次选择不会写回 config.json（workflow.research 是跨项目控制 plan-phase 的持久偏好，改默认值应走 /gsd:settings）。

若选择 "Research first"，系统在 .planning/research/ 下并行派出 4 个 gsd-project-researcher 子代理，维度分别为 Stack / Features / Architecture / Pitfalls，各自独立产出 STACK.md、FEATURES.md、ARCHITECTURE.md、PITFALLS.md，其提示模板的维度字段差异如下表：

字段	Stack	Features	Architecture	Pitfalls
QUESTION	新增功能需要哪些技术栈增减？	目标功能通常如何运作、预期行为？	如何与既有架构集成？	在该领域新增该功能的常见错误？
CONSUMER	具体库+版本、集成点、哪些不要加	入场门槛 vs 差异化 vs 反功能、依赖	集成点、新组件、数据流变化、构建顺序	警示信号、预防策略、由哪个阶段处理
FILE	STACK.md	FEATURES.md	ARCHITECTURE.md	PITFALLS.md

4 个研究者都只读取 .planning/PROJECT.md 做上下文，且被要求 DO NOT re-research 已具备的能力——只聚焦新增功能。

工作流内嵌了两条 CODEX RUNTIME 编排规则：

1. 派发完 4 个研究者后不得自己读研究文件或抢着综合；
2. 等待全部完成后才派出 gsd-research-synthesizer，读取 4 份产出并写入 .planning/research/SUMMARY.md 后立即提交。

编排完成后向用户呈现研究结论摘要（Stack additions / Feature table stakes / Watch Out For）。

八、Step 9：定义带 REQ-ID 的可勾选需求

进入 DEFINING REQUIREMENTS 阶段后：

1. 读取 PROJECT.md 的核心价值与已验证需求，并叠加 $SELECTED_SEEDS 的种子想法；
2. 若有研究，则从 FEATURES.md 提取分类，按"Table stakes / Differentiators / Research notes"分门别类展示；无研究则通过对话收集（"新功能中用户主要需要做什么？"）；
3. 逐分类圈定范围（AskUserQuestion 多选，header 不超过 12 字符）：选中 → 本次里程碑；未选中的 table stakes → future；未选中的 differentiators → out of scope；
4. 识别研究未覆盖的缺口；
5. 生成 .planning/REQUIREMENTS.md，结构参考 get-shit-done/templates/requirements.md：v1 需求按分类勾选 + REQ-ID 编号（格式 [CATEGORY]-[NUMBER]，如 AUTH-01、NOTIF-02，延续既有编号）、Future Requirements（v2 顺延）、Out of Scope（显式排除+理由）、Traceability（初始为空，由路线图回填，含 Coverage 统计）。

模板给出的需求质量判据值得写进你的评审清单：

• 具体且可测试：写"用户可通过邮件链接重置密码"，而非"处理密码重置"；
• 以用户为中心：写"用户能做 X"，而非"系统会做 Y"；
• 原子化：每条只承载一个能力（避免"用户能登录并管理资料"）；
• 低依赖：需求之间依赖最小。

全文展示完整需求列表请求确认（yes / adjust），确认后提交：

gsd-sdk query commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md

九、Step 10：派发 roadmapper 生成路线图并审批

工作流向 gsd-roadmapper 子代理提供 PROJECT.md、REQUIREMENTS.md、研究 SUMMARY.md（如存在）、config.json、MILESTONES.md，并下达硬性指令：

1. 尊重编号模式（--reset-phase-numbers → 从 Phase 1；默认 → 延续上一里程碑末阶段号）；
2. 只依据本里程碑的需求派生阶段；
3. 每条需求必须映射到恰好一个阶段（100% 覆盖校验）；
4. 每阶段派生 2–5 条成功标准（可观察的用户行为）；
5. 先写文件再返回：立即写 ROADMAP.md、更新 STATE.md 与 REQUIREMENTS.md 的 Traceability 段，返回 ROADMAP CREATED（阻塞时返回 ROADMAP BLOCKED，需与用户协作后重新派发）。

路线图文件的阶段结构约定见 get-shit-done/templates/roadmap.md：整数阶段（1、2、3）表示计划内里程碑工作，十进制阶段（2.1、2.2）用于紧急插入（标记 INSERTED），并给出 Phase Details 的 Goal / Depends on / Requirements / Success Criteria / Plans 模板。

创建完成后向用户呈现提议路线图表格（阶段数、映射需求数、每条目的成功标准数），提供三个选项：

• Approve → 提交并继续；
• Adjust phases → 收集修改意见后带着修订上下文重新派发 roadmapper，循环至通过；
• Review full file → 展示原始 ROADMAP.md 后重新询问。

批准后提交：

gsd-sdk query commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md

十、Step 10.5：将待办事项链接到路线图阶段

路线图获批后，工作流扫描 .planning/todos/pending/ 下的待办：

PENDING_TODOS=$(ls .planning/todos/pending/*.md 2>/dev/null | head -50)

• 无待办则静默跳过；
• 有待办时，将每个待办的 title、area frontmatter 字段及正文 Problem/Solution，与各阶段的 Goal、REQ-ID 描述做尽力而为匹配（匹配判据：阶段目标/需求直接描述了实现与待办相同功能、区域或能力；窄且具体的待办是最佳候选，模糊或横切性质的待办保持不链接）；
• 命中则在该待办 YAML frontmatter 追加 resolves_phase: [N]（保留原有 created/title/area/files 字段，仅插入一行），绝不修改不匹配的待办；
• 若有关联发生则统一提交并打印摘要（◆ Linked [N] pending todos to roadmap phases，并注明有多少待办留在 pending/）。

十一、Step 11：完成横幅与下一步引导

全部成功后渲染 GSD ► MILESTONE INITIALIZED ✓ 横幅，汇总产物位置（PROJECT / research / REQUIREMENTS / ROADMAP），给出 [N] phases | [X] requirements | Ready to build，并以 Next Up 区块引导后续动作：

/clear then:
/gsd:discuss-phase [N] ${GSD_WS}    — gather context and clarify approach
也可用 /gsd:plan-phase [N] ${GSD_WS} 跳过讨论直接规划