get-shit-done 的 gsd:phase 命令ROADMAP.md 阶段全生命周期管理实战指南【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读gsd:phase是 get-shit-done简称 GSD中用于管理ROADMAP.md阶段Phase的单一整合命令覆盖阶段的新增、插入、删除、编辑四种 CRUD 操作。本文围绕 commands/gsd/phase.md 展开结合仓库中 get-shit-done/workflows/ 四个配套工作流与 SDK 查询层源码讲解四种模式各自的路由规则、参数格式、校验门禁、对.planning/目录结构与状态文件的副作用并给出可直接复制的命令用法。读完后你将掌握如何在里程碑执行过程中安全地增删改阶段、用十进制编号插入紧急任务而不重排既有阶段以及这些操作底层经由gsd-sdk query的调用链路。一、命令定位与模式路由在 GSD 中ROADMAP.md 以里程碑Milestone→ 阶段Phase的层级组织工作每个阶段通常对应一个整数编号如 72。开发过程中阶段的调整非常频繁里程碑末尾追加规划工作、执行中插入紧急修复、清理已取消的远期阶段、修订阶段描述等。gsd:phase把这些散落在不同命令中的操作收敛为一个入口通过首个参数旗标自动路由到对应工作流旗标动作路由工作流用途无旗标在里程碑末尾追加新整数阶段add-phase常规规划--insert在指定阶段后插入十进制阶段如 72.1insert-phase紧急插单--remove移除未来阶段并重排其后续阶段remove-phase清理/取消--edit就地修改既有阶段的任意字段edit-phase修订描述命令参数提示为[--insert | --remove | --edit] phase-name-or-number。解析逻辑见 commands/gsd/phase.md 的context段非常简单首个 token 是--insert剥离旗标将剩余参数格式after-phase-number description交给 insert-phase 工作流首个 token 是--remove剥离旗标将阶段编号交给 remove-phase 工作流首个 token 是--edit剥离旗标将phase-number [--force]交给 edit-phase 工作流其余情况全部参数视为阶段描述交给 add-phase 工作流。需要强调的是命令本身不直接读写文件。其execution_context声明了四个待加载的工作流文件在本仓库中对应 add-phase、insert-phase、remove-phase、edit-phase而 ROADMAP 与项目状态都在工作流内部通过init.phase-op查询和定向读取解析命令层面的要求是保留目标工作流的全部校验门禁。二、默认模式在里程碑末尾新增阶段2.1 用法与参数不带旗标调用即进入 add-phase 模式所有参数拼成阶段描述/gsd:phase Add authentication # 描述 Add authentication /gsd:phase Fix critical performance issues若未提供任何参数add-phase 工作流会输出错误与用法说明并退出ERROR: Phase description required Usage: /gsd-add-phase description Example: /gsd-add-phase Add authentication system2.2 初始化与底层委托工作流先加载阶段操作上下文与--insert/--remove/--edit共用同一初始化路径INIT$(gsd-sdk query init.phase-op 0) if [[ $INIT file:* ]]; then INIT$(cat ${INIT#file:}); fi检查initJSON 中的roadmap_exists若为 false 则报错并提示先执行/gsd:new-project初始化ERROR: No roadmap found (.planning/ROADMAP.md) Run /gsd:new-project to initialize.随后将添加操作整体委托给 SDKRESULT$(gsd-sdk query phase.add ${description})SDK 查询处理器承担了全部脏活见 sdk/src/query/phase-lifecycle.ts 中phase.add处理器及注释Query handler for phase.add查找当前最高整数阶段号、计算下一编号max 1、由描述生成 slug、创建阶段目录.planning/phases/{NN}-{slug}/、向 ROADMAP.md 插入含 Goal / Depends on / Plans 小节的新阶段条目。调用方从结果中提取phase_number、padded、name、slug、directory。源码实现中还提到并发安全设计注释明确说明phase.add需处理两次并发调用同时观察到同一最大编号的竞态场景见 sdk/src/query/phase-lifecycle.ts这是直接把原 JS 工具phase.cjs移植为 TypeScript 查询处理器时保留的行为。2.3 状态同步与收尾新阶段落盘后还需把演变记录写进.planning/STATE.md在## Accumulated Context → ### Roadmap Evolution下追加- Phase {N} added: {description}若该小节不存在则创建。完成时向用户呈现摘要Phase {N} added to current milestone: - Description: {description} - Directory: .planning/phases/{phase-num}-{slug}/ - Status: Not planned yet Roadmap updated: .planning/ROADMAP.md并提示下一步/clear后执行/gsd:plan-phase {N}开始规划该阶段。注意add-phase 的验证清单success_criteria要求phase.add执行成功、目录已建、ROADMAP 已更新、STATE.md 已记录且不自动提交——何时 commit 由用户决定。三、--insert十进制编号插入紧急阶段3.1 设计动机里程碑进行到一半发现必须立刻处理的紧急工作时若直接追加到末尾会打乱规划的依赖顺序若整体重排又会造成大规模改写。insert-phase 采用十进制编号72.1、72.2方案紧跟在目标整数阶段之后插入既保持既有整数阶段的逻辑顺序又无需重排整份路线图。/gsd:phase --insert 72 Fix critical auth bug # after 72 # description Fix critical auth bug缺参或首参非整数时给出明确报错ERROR: Both phase number and description required Usage: /gsd:phase --insert after description Example: /gsd:phase --insert 72 Fix critical auth bug3.2 插入逻辑与 (INSERTED) 标记初始化仍走gsd-sdk query init.phase-op ${after_phase}并检查roadmap_exists。随后委托RESULT$(gsd-sdk query phase.insert ${after_phase} ${description})SDK 处理器负责校验目标阶段存在于 ROADMAP.md、在磁盘上检查已有十进制编号并计算下一个编号、生成 slug、创建.planning/phases/{N.M}-{slug}/目录、在 ROADMAP.md 目标阶段之后插入条目并加(INSERTED)标记以标识这是紧急插单区别于计划性阶段。3.3 状态指针更新不可裸写 STATE.md与 add-phase 不同插单会改变当前执行指针因此需要更新 STATE.md 的 next-phase 指向。关键在于工作流明确规定必须经由 SDK handler绝不可直接使用Edit/Write裸写——项目可能内置protect-files.shPreToolUse 钩子拦截对 STATE.md 的直接写入。正确做法是gsd-sdk query state.patch {Current Phase:{decimal_phase},Next recommended run:/gsd:plan-phase {decimal_phase}}字段名需按 STATE.md 实际暴露的指针字段调整handler 会回报其实际匹配到的字段。再经由专门的演进记录 handler 追加条目——它会在## Accumulated Context下自动创建### Roadmap Evolution小节并对相同条目去重gsd-sdk query state.add-roadmap-evolution \ --phase {decimal_phase} \ --action inserted \ --after {after_phase} \ --note {description} \ --urgent预期响应形如{ added: true, entry: - Phase ... (URGENT) }重放时则返回{ added: false, reason: duplicate, entry: ... }。验收条件见 insert-phase明确覆盖了这两种响应形状与state.patch的字段匹配结果。3.4 反模式红线insert-phase 的anti_patterns列出一组硬性约束值得在此完整保留不要用它做里程碑末尾的计划性工作那应走/gsd-add-phase不要在 Phase 1 之前插入十进制 0.1 无意义不要重排既有阶段不要改动目标阶段自身的内容不要在此阶段就创建计划那是/gsd:plan-phase的职责不要自动提交由用户决定提交时机。插入完成提示用户检查Phase {next_integer} 的依赖是否仍然成立并建议先/gsd:plan-phase {decimal_phase}规划该紧急阶段。四、--remove移除未来阶段并自动重排4.1 只允许移除未来阶段remove-phase 仅允许删除尚未开始的远期阶段同时支持整数与十进制编号/gsd:phase --remove 17 # 移除 Phase 17 /gsd:phase --remove 16.1 # 移除 Phase 16.1初始化通过gsd-sdk query init.phase-op ${target}返回phase_found、phase_dir、phase_number、commit_docs、roadmap_exists等字段。随后用 STATE.md 中的当前阶段号做护栏目标必须大于当前阶段号否则报错并建议ERROR: Cannot remove Phase {target} Only future phases can be removed: - Current phase: {current} - Phase {target} is current or completed To abandon current work, use /gsd:pause-work instead.4.2 确认与委托删除删除影响范围大因此先展示摘要并要求 y/n 确认Removing Phase {target}: {Name} This will: - Delete: .planning/phases/{target}-{slug}/ - Renumber all subsequent phases - Update: ROADMAP.md, STATE.md Proceed? (y/n)确认后整体委托给 SDKRESULT$(gsd-sdk query phase.remove ${target})SDK 处理器一次性完成全部联动删除阶段目录按逆序重排后续所有目录以避免冲突重命名被重排目录内的全部文件PLAN.md、SUMMARY.md 等更新 ROADMAP.md移除对应小节、重排所有阶段引用、修正依赖更新 STATE.md递减阶段计数。调用方从结果提取removed、directory_deleted、renamed_directories、renamed_files、roadmap_updated、state_updated。若目标阶段已产生执行过的计划存在 SUMMARY.md 文件SDK 会直接报错只有在用户明确确认后才可追加--forceRESULT$(gsd-sdk query phase.remove ${target} --force)4.3 git 提交即历史记录与其他模式不自动提交不同remove-phase 会主动提交因为 git 提交就是删除行为的唯一历史凭证gsd-sdk query commit chore: remove phase {target} ({original-phase-name}) --files .planning/同时其反模式强调不要往 STATE.md 里补写已移除阶段的备注git 提交即记录不要手工重排——phase.remove处理器已处理全部重排不要动已完成的阶段目录。只有--force才能越过含 SUMMARY.md 的已执行阶段守卫。五、--edit就地编辑阶段字段5.1 用法、守卫与状态映射编辑模式的口号是编号与位置永远不变只改字段/gsd:phase --edit 5 # 编辑 Phase 5 /gsd:phase --edit 5 --force # 允许编辑 in-progress/completed 阶段 /gsd:phase --edit 12.1流程先以init.phase-op加载上下文并检查 ROADMAP 存在性再用roadmap get-phase读取目标阶段PHASE_DATA$(gsd-sdk query roadmap get-phase ${target})若found为 false 则报错并建议用/gsd:progress查看可用阶段。从结果中提取phase_name、goal、success_criteria、section保留 depends_on、requirements、plans 等的完整原文段并需从原文段额外解析depends_on兼容**Depends on:**与**Depends on**:两种写法与requirements。关键安全门禁在状态检查通过gsd-sdk query roadmap analyze获取每个阶段的磁盘状态disk_status再映射为友好状态complete→completedplanned/partial→in_progressempty、no_directory、discussed、researched→future若阶段处于in_progress或completed且未传--force直接拦截——因为编辑进行中或已完成的阶段可能使已执行的计划失效传了--force则打印 WARNING 继续。5.2 两种编辑路径先展示当前值Title / Goal / Depends on / Requirements / Success Criteria 列表再让用户在三种选项中抉择[1] Edit specific fields (title, goal, depends_on, requirements, success_criteria) [2] Regenerate all fields from a clarified intent [3] Cancel路径 [1] 逐字段编辑选择字段后逐项提问只有显式作答的字段才进入更新集合空答案保持原值。路径 [2] 由澄清意图整体重写让用户描述修订后的意图据此重新生成简明标题、完整 Goal、更新后的 requirements原有用到才生成、3~5 条可度量的 success_criteriadepends_on除非用户明确提及否则保留不动。5.3 depends_on 校验与 diff 确认任何depends_on更新或保留非空值都要校验先roadmap analyze拿到全部合法阶段号集合对每个引用做规范化去空白、去 Phase 前缀再检查它存在于合法集合且不等于自身。任一引用非法即拒绝写入ERROR: depends_on references invalid phase(s): {bad_refs} Valid phase numbers: {valid_list} Fix the depends_on field and try again.随后构建更新后的阶段小节按字段类型精确替换标题替换Phase {N}:后的文本、Goal 替换**Goal:**行值、depends_on/requirements 替换或补建对应行/块、success_criteria 替换编号列表、整体重写则重建整个小节并展示 unified 风格 diffProposed changes to Phase {target}: --- current updated ... - **Goal:** {old_goal} **Goal:** {new_goal} ... Apply these changes? (y/n):用户确认后才写回。写回要求精确定位阶段小节## Phase {N}:或### Phase {N}:标题只替换该段原文前后内容其他阶段、里程碑标题、汇总清单一律不动不允许未先读取就对 ROADMAP.md 裸写。写回后同样通过state.add-roadmap-evolution --action edited --note edited fields: ...记录演变。编辑模式的反模式强调绝不改编号与位置只编辑一个阶段时不动其他阶段不跳过 depends_on 校验不展示 diff 并获得确认前绝不写盘不--force编辑进行中/已完成阶段不修改阶段目录结构不自动提交。六、源码级原理init.phase-op 与查询处理器命令之所以能四合一还保持每种操作的校验完整性底层依赖 SDK 查询层的两大机制统一初始化init.phase-op四个工作流第一步都执行gsd-sdk query init.phase-op phase在 sdk/src/query/init.ts 中对应initPhaseOp处理器从原init.cjs移植。它复用findPhase查找目录带归档降级若唯一匹配来自已归档里程碑则优先以当前 ROADMAP 为准见shouldDropArchivedPhaseMatch逻辑并通过roadmapGetPhase对比路线图条目。roadmap_exists字段在多个初始化点都由existsSync(join(planningDir, ROADMAP.md))计算见 sdk/src/query/init.ts是各工作流没有路线图先建项目守卫的数据来源。集中式查询处理器注册按 sdk/src/query/QUERY-HANDLERS.md 的查询族清单phase族注册了phase.add、phase.add-batch、phase.insert等多个 handlerphase.add等具体实现集中在 sdk/src/query/phase-lifecycle.ts并继承了原get-shit-done/bin/lib/phase.cjs的语义该文件头部注释即写明Ported from ...。因此从架构上可以推断gsd:phase系列命令与phase族查询形成了瘦命令只做路由→ 厚工作流编排与校验→ 查询处理器原子化落盘三层结构任何单点逻辑编号计算、slug 生成、目录/文件重排、ROADMAP/STATE 联动更新都被收敛在处理器内复用保证四个入口行为一致。七、使用建议与边界提醒编号即语义整数编号是规划性阶段的稳定标识十进制编号专门留给里程碑中途的紧急插单不要试图用--insert做常规追加也不要为了清理而让十进制阶段长期滞留路线图——对确已无用的插单阶段用--remove支持十进制编号在规划前移除即可。--force是最后手段无论编辑还是删除--force只在用户明确确认对进行中/已完成阶段动刀时才使用因为那可能使已执行计划失配。自动提交范围仅 remove-phase 会主动 commit其删除动作本身就是历史记录add/insert/edit 均把提交决定留给用户。依赖一致性插单和编辑都可能影响既有阶段依赖depends_on删除则自动重排后续编号并修正依赖编辑模式内置了引用合法性校验手动改 ROADMAP 时请参照同一约束。本文涉及的四种工作流文档位于 get-shit-done/workflows/命令路由规则见 commands/gsd/phase.md相关测试可参考 sdk/src/query/phase.test.ts 与 sdk/src/query/phase-lifecycle.test.ts可据此进一步验证各模式在仓库中的实际行为契约。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 get-shit-done 的 gsd:phase 命令：ROADMAP.md 阶段全生命周期管理实战指南
get-shit-done 的 gsd:phase 命令ROADMAP.md 阶段全生命周期管理实战指南【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done导读gsd:phase是 get-shit-done简称 GSD中用于管理ROADMAP.md阶段Phase的单一整合命令覆盖阶段的新增、插入、删除、编辑四种 CRUD 操作。本文围绕 commands/gsd/phase.md 展开结合仓库中 get-shit-done/workflows/ 四个配套工作流与 SDK 查询层源码讲解四种模式各自的路由规则、参数格式、校验门禁、对.planning/目录结构与状态文件的副作用并给出可直接复制的命令用法。读完后你将掌握如何在里程碑执行过程中安全地增删改阶段、用十进制编号插入紧急任务而不重排既有阶段以及这些操作底层经由gsd-sdk query的调用链路。一、命令定位与模式路由在 GSD 中ROADMAP.md 以里程碑Milestone→ 阶段Phase的层级组织工作每个阶段通常对应一个整数编号如 72。开发过程中阶段的调整非常频繁里程碑末尾追加规划工作、执行中插入紧急修复、清理已取消的远期阶段、修订阶段描述等。gsd:phase把这些散落在不同命令中的操作收敛为一个入口通过首个参数旗标自动路由到对应工作流旗标动作路由工作流用途无旗标在里程碑末尾追加新整数阶段add-phase常规规划--insert在指定阶段后插入十进制阶段如 72.1insert-phase紧急插单--remove移除未来阶段并重排其后续阶段remove-phase清理/取消--edit就地修改既有阶段的任意字段edit-phase修订描述命令参数提示为[--insert | --remove | --edit] phase-name-or-number。解析逻辑见 commands/gsd/phase.md 的context段非常简单首个 token 是--insert剥离旗标将剩余参数格式after-phase-number description交给 insert-phase 工作流首个 token 是--remove剥离旗标将阶段编号交给 remove-phase 工作流首个 token 是--edit剥离旗标将phase-number [--force]交给 edit-phase 工作流其余情况全部参数视为阶段描述交给 add-phase 工作流。需要强调的是命令本身不直接读写文件。其execution_context声明了四个待加载的工作流文件在本仓库中对应 add-phase、insert-phase、remove-phase、edit-phase而 ROADMAP 与项目状态都在工作流内部通过init.phase-op查询和定向读取解析命令层面的要求是保留目标工作流的全部校验门禁。二、默认模式在里程碑末尾新增阶段2.1 用法与参数不带旗标调用即进入 add-phase 模式所有参数拼成阶段描述/gsd:phase Add authentication # 描述 Add authentication /gsd:phase Fix critical performance issues若未提供任何参数add-phase 工作流会输出错误与用法说明并退出ERROR: Phase description required Usage: /gsd-add-phase description Example: /gsd-add-phase Add authentication system2.2 初始化与底层委托工作流先加载阶段操作上下文与--insert/--remove/--edit共用同一初始化路径INIT$(gsd-sdk query init.phase-op 0) if [[ $INIT file:* ]]; then INIT$(cat ${INIT#file:}); fi检查initJSON 中的roadmap_exists若为 false 则报错并提示先执行/gsd:new-project初始化ERROR: No roadmap found (.planning/ROADMAP.md) Run /gsd:new-project to initialize.随后将添加操作整体委托给 SDKRESULT$(gsd-sdk query phase.add ${description})SDK 查询处理器承担了全部脏活见 sdk/src/query/phase-lifecycle.ts 中phase.add处理器及注释Query handler for phase.add查找当前最高整数阶段号、计算下一编号max 1、由描述生成 slug、创建阶段目录.planning/phases/{NN}-{slug}/、向 ROADMAP.md 插入含 Goal / Depends on / Plans 小节的新阶段条目。调用方从结果中提取phase_number、padded、name、slug、directory。源码实现中还提到并发安全设计注释明确说明phase.add需处理两次并发调用同时观察到同一最大编号的竞态场景见 sdk/src/query/phase-lifecycle.ts这是直接把原 JS 工具phase.cjs移植为 TypeScript 查询处理器时保留的行为。2.3 状态同步与收尾新阶段落盘后还需把演变记录写进.planning/STATE.md在## Accumulated Context → ### Roadmap Evolution下追加- Phase {N} added: {description}若该小节不存在则创建。完成时向用户呈现摘要Phase {N} added to current milestone: - Description: {description} - Directory: .planning/phases/{phase-num}-{slug}/ - Status: Not planned yet Roadmap updated: .planning/ROADMAP.md并提示下一步/clear后执行/gsd:plan-phase {N}开始规划该阶段。注意add-phase 的验证清单success_criteria要求phase.add执行成功、目录已建、ROADMAP 已更新、STATE.md 已记录且不自动提交——何时 commit 由用户决定。三、--insert十进制编号插入紧急阶段3.1 设计动机里程碑进行到一半发现必须立刻处理的紧急工作时若直接追加到末尾会打乱规划的依赖顺序若整体重排又会造成大规模改写。insert-phase 采用十进制编号72.1、72.2方案紧跟在目标整数阶段之后插入既保持既有整数阶段的逻辑顺序又无需重排整份路线图。/gsd:phase --insert 72 Fix critical auth bug # after 72 # description Fix critical auth bug缺参或首参非整数时给出明确报错ERROR: Both phase number and description required Usage: /gsd:phase --insert after description Example: /gsd:phase --insert 72 Fix critical auth bug3.2 插入逻辑与 (INSERTED) 标记初始化仍走gsd-sdk query init.phase-op ${after_phase}并检查roadmap_exists。随后委托RESULT$(gsd-sdk query phase.insert ${after_phase} ${description})SDK 处理器负责校验目标阶段存在于 ROADMAP.md、在磁盘上检查已有十进制编号并计算下一个编号、生成 slug、创建.planning/phases/{N.M}-{slug}/目录、在 ROADMAP.md 目标阶段之后插入条目并加(INSERTED)标记以标识这是紧急插单区别于计划性阶段。3.3 状态指针更新不可裸写 STATE.md与 add-phase 不同插单会改变当前执行指针因此需要更新 STATE.md 的 next-phase 指向。关键在于工作流明确规定必须经由 SDK handler绝不可直接使用Edit/Write裸写——项目可能内置protect-files.shPreToolUse 钩子拦截对 STATE.md 的直接写入。正确做法是gsd-sdk query state.patch {Current Phase:{decimal_phase},Next recommended run:/gsd:plan-phase {decimal_phase}}字段名需按 STATE.md 实际暴露的指针字段调整handler 会回报其实际匹配到的字段。再经由专门的演进记录 handler 追加条目——它会在## Accumulated Context下自动创建### Roadmap Evolution小节并对相同条目去重gsd-sdk query state.add-roadmap-evolution \ --phase {decimal_phase} \ --action inserted \ --after {after_phase} \ --note {description} \ --urgent预期响应形如{ added: true, entry: - Phase ... (URGENT) }重放时则返回{ added: false, reason: duplicate, entry: ... }。验收条件见 insert-phase明确覆盖了这两种响应形状与state.patch的字段匹配结果。3.4 反模式红线insert-phase 的anti_patterns列出一组硬性约束值得在此完整保留不要用它做里程碑末尾的计划性工作那应走/gsd-add-phase不要在 Phase 1 之前插入十进制 0.1 无意义不要重排既有阶段不要改动目标阶段自身的内容不要在此阶段就创建计划那是/gsd:plan-phase的职责不要自动提交由用户决定提交时机。插入完成提示用户检查Phase {next_integer} 的依赖是否仍然成立并建议先/gsd:plan-phase {decimal_phase}规划该紧急阶段。四、--remove移除未来阶段并自动重排4.1 只允许移除未来阶段remove-phase 仅允许删除尚未开始的远期阶段同时支持整数与十进制编号/gsd:phase --remove 17 # 移除 Phase 17 /gsd:phase --remove 16.1 # 移除 Phase 16.1初始化通过gsd-sdk query init.phase-op ${target}返回phase_found、phase_dir、phase_number、commit_docs、roadmap_exists等字段。随后用 STATE.md 中的当前阶段号做护栏目标必须大于当前阶段号否则报错并建议ERROR: Cannot remove Phase {target} Only future phases can be removed: - Current phase: {current} - Phase {target} is current or completed To abandon current work, use /gsd:pause-work instead.4.2 确认与委托删除删除影响范围大因此先展示摘要并要求 y/n 确认Removing Phase {target}: {Name} This will: - Delete: .planning/phases/{target}-{slug}/ - Renumber all subsequent phases - Update: ROADMAP.md, STATE.md Proceed? (y/n)确认后整体委托给 SDKRESULT$(gsd-sdk query phase.remove ${target})SDK 处理器一次性完成全部联动删除阶段目录按逆序重排后续所有目录以避免冲突重命名被重排目录内的全部文件PLAN.md、SUMMARY.md 等更新 ROADMAP.md移除对应小节、重排所有阶段引用、修正依赖更新 STATE.md递减阶段计数。调用方从结果提取removed、directory_deleted、renamed_directories、renamed_files、roadmap_updated、state_updated。若目标阶段已产生执行过的计划存在 SUMMARY.md 文件SDK 会直接报错只有在用户明确确认后才可追加--forceRESULT$(gsd-sdk query phase.remove ${target} --force)4.3 git 提交即历史记录与其他模式不自动提交不同remove-phase 会主动提交因为 git 提交就是删除行为的唯一历史凭证gsd-sdk query commit chore: remove phase {target} ({original-phase-name}) --files .planning/同时其反模式强调不要往 STATE.md 里补写已移除阶段的备注git 提交即记录不要手工重排——phase.remove处理器已处理全部重排不要动已完成的阶段目录。只有--force才能越过含 SUMMARY.md 的已执行阶段守卫。五、--edit就地编辑阶段字段5.1 用法、守卫与状态映射编辑模式的口号是编号与位置永远不变只改字段/gsd:phase --edit 5 # 编辑 Phase 5 /gsd:phase --edit 5 --force # 允许编辑 in-progress/completed 阶段 /gsd:phase --edit 12.1流程先以init.phase-op加载上下文并检查 ROADMAP 存在性再用roadmap get-phase读取目标阶段PHASE_DATA$(gsd-sdk query roadmap get-phase ${target})若found为 false 则报错并建议用/gsd:progress查看可用阶段。从结果中提取phase_name、goal、success_criteria、section保留 depends_on、requirements、plans 等的完整原文段并需从原文段额外解析depends_on兼容**Depends on:**与**Depends on**:两种写法与requirements。关键安全门禁在状态检查通过gsd-sdk query roadmap analyze获取每个阶段的磁盘状态disk_status再映射为友好状态complete→completedplanned/partial→in_progressempty、no_directory、discussed、researched→future若阶段处于in_progress或completed且未传--force直接拦截——因为编辑进行中或已完成的阶段可能使已执行的计划失效传了--force则打印 WARNING 继续。5.2 两种编辑路径先展示当前值Title / Goal / Depends on / Requirements / Success Criteria 列表再让用户在三种选项中抉择[1] Edit specific fields (title, goal, depends_on, requirements, success_criteria) [2] Regenerate all fields from a clarified intent [3] Cancel路径 [1] 逐字段编辑选择字段后逐项提问只有显式作答的字段才进入更新集合空答案保持原值。路径 [2] 由澄清意图整体重写让用户描述修订后的意图据此重新生成简明标题、完整 Goal、更新后的 requirements原有用到才生成、3~5 条可度量的 success_criteriadepends_on除非用户明确提及否则保留不动。5.3 depends_on 校验与 diff 确认任何depends_on更新或保留非空值都要校验先roadmap analyze拿到全部合法阶段号集合对每个引用做规范化去空白、去 Phase 前缀再检查它存在于合法集合且不等于自身。任一引用非法即拒绝写入ERROR: depends_on references invalid phase(s): {bad_refs} Valid phase numbers: {valid_list} Fix the depends_on field and try again.随后构建更新后的阶段小节按字段类型精确替换标题替换Phase {N}:后的文本、Goal 替换**Goal:**行值、depends_on/requirements 替换或补建对应行/块、success_criteria 替换编号列表、整体重写则重建整个小节并展示 unified 风格 diffProposed changes to Phase {target}: --- current updated ... - **Goal:** {old_goal} **Goal:** {new_goal} ... Apply these changes? (y/n):用户确认后才写回。写回要求精确定位阶段小节## Phase {N}:或### Phase {N}:标题只替换该段原文前后内容其他阶段、里程碑标题、汇总清单一律不动不允许未先读取就对 ROADMAP.md 裸写。写回后同样通过state.add-roadmap-evolution --action edited --note edited fields: ...记录演变。编辑模式的反模式强调绝不改编号与位置只编辑一个阶段时不动其他阶段不跳过 depends_on 校验不展示 diff 并获得确认前绝不写盘不--force编辑进行中/已完成阶段不修改阶段目录结构不自动提交。六、源码级原理init.phase-op 与查询处理器命令之所以能四合一还保持每种操作的校验完整性底层依赖 SDK 查询层的两大机制统一初始化init.phase-op四个工作流第一步都执行gsd-sdk query init.phase-op phase在 sdk/src/query/init.ts 中对应initPhaseOp处理器从原init.cjs移植。它复用findPhase查找目录带归档降级若唯一匹配来自已归档里程碑则优先以当前 ROADMAP 为准见shouldDropArchivedPhaseMatch逻辑并通过roadmapGetPhase对比路线图条目。roadmap_exists字段在多个初始化点都由existsSync(join(planningDir, ROADMAP.md))计算见 sdk/src/query/init.ts是各工作流没有路线图先建项目守卫的数据来源。集中式查询处理器注册按 sdk/src/query/QUERY-HANDLERS.md 的查询族清单phase族注册了phase.add、phase.add-batch、phase.insert等多个 handlerphase.add等具体实现集中在 sdk/src/query/phase-lifecycle.ts并继承了原get-shit-done/bin/lib/phase.cjs的语义该文件头部注释即写明Ported from ...。因此从架构上可以推断gsd:phase系列命令与phase族查询形成了瘦命令只做路由→ 厚工作流编排与校验→ 查询处理器原子化落盘三层结构任何单点逻辑编号计算、slug 生成、目录/文件重排、ROADMAP/STATE 联动更新都被收敛在处理器内复用保证四个入口行为一致。七、使用建议与边界提醒编号即语义整数编号是规划性阶段的稳定标识十进制编号专门留给里程碑中途的紧急插单不要试图用--insert做常规追加也不要为了清理而让十进制阶段长期滞留路线图——对确已无用的插单阶段用--remove支持十进制编号在规划前移除即可。--force是最后手段无论编辑还是删除--force只在用户明确确认对进行中/已完成阶段动刀时才使用因为那可能使已执行计划失配。自动提交范围仅 remove-phase 会主动 commit其删除动作本身就是历史记录add/insert/edit 均把提交决定留给用户。依赖一致性插单和编辑都可能影响既有阶段依赖depends_on删除则自动重排后续编号并修正依赖编辑模式内置了引用合法性校验手动改 ROADMAP 时请参照同一约束。本文涉及的四种工作流文档位于 get-shit-done/workflows/命令路由规则见 commands/gsd/phase.md相关测试可参考 sdk/src/query/phase.test.ts 与 sdk/src/query/phase-lifecycle.test.ts可据此进一步验证各模式在仓库中的实际行为契约。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考