GSD 命令参考手册：get-shit-done 全量 Slash 命令语法、Flags 与实战示例

2026-09-08 21:26:47作者：明树来

本文是 get-shit-done（GSD）的命令级参考手册，系统梳理 v1.40+ 稳定版中全部 /gsd-* 命令的语法、参数、Flags、前置条件与产物文件，并给出可直接复制的实战示例。读完本文，你将掌握：跨运行时（Claude Code / Codex / Gemini CLI 等）的命令拼写差异、六大命名空间路由技能的组织方式、从 new-project 到 complete-milestone 的完整阶段流水线操作，以及 debug、spike、graphify、code-review 等辅助命令的深度用法。功能层面的设计细节可参见 Feature Reference，端到端工作流演示可参见 User Guide。

1. 命令语法：同一命令在不同 AI 运行时的不同拼写

GSD 的命令在所有运行时中共享同一套语义，但拼写形式随宿主 CLI 而异：

运行时	命令形式	示例
Claude Code / Copilot / OpenCode / Kilo	连字符形式	`/gsd-plan-phase 1`
Gemini CLI	冒号形式（命令挂在 `gsd:` 命名空间下）	`/gsd:plan-phase 1`
Codex	美元符号前缀	`$gsd-plan-phase 1`

连字符形式与冒号形式是同一命令在不同运行时的拼写变体。安装器会根据检测到的运行时，把正确形式写入该运行时的命令目录，因此你无需手工记忆或转换——在哪个运行时上，就用那个运行时的拼写。命令的语义、参数与产物在所有运行时完全一致，这为团队跨工具协作（例如计划用 Claude Code、评审用 Codex/Gemini）提供了统一心智模型。

2. 命名空间元技能：六个一级路由入口

v1.40 引入了 6 个命名空间路由器作为命令的第一级入口。其核心动机是控制每会话的 token 开销：6 个路由技能的 eager 技能列表约消耗 120 tokens，而平铺的 86 个技能列表约消耗 2,150 tokens——差距约 18 倍。模型先选择命名空间，再路由到具体子技能：

命令	路由范围
`/gsd-workflow`	阶段流水线 — discuss / plan / execute / verify / phase / progress
`/gsd-project`	项目生命周期 — milestones、audits、summary
`/gsd-quality`	质量门禁 — code review、debug、audit、security、eval、ui
`/gsd-context`	代码库智能 — map、graphify、docs、learnings
`/gsd-manage`	管理 — config、workspace、workstreams、thread、update、ship、inbox
`/gsd-ideate`	探索与捕获 — explore、sketch、spike、spec、capture

需要特别强调的是，命名空间技能是**叠加式（additive）**的：所有既有具体命令（如 /gsd-plan-phase、/gsd-code-review --fix）依然可直接调用，路由层不屏蔽任何命令。在源码层面，命令注册通过 sdk/src/query/command-catalog.ts 的 registerAliasCatalog 完成——它为每个规范命令名注册别名，并将同一 handler 绑定到全部别名上，这解释了为什么冒号/连字符/命名空间三种形式最终都落到同一个执行逻辑。

3. 核心工作流命令

3.1 `/gsd-new-project`：初始化新项目

以深度上下文收集方式初始化一个全新项目。

Flag	说明
`--auto @file.md`	从文档自动抽取信息，跳过交互式提问

前置条件： 不存在 .planning/PROJECT.md
产物： PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md、config.json、research/、CLAUDE.md

/gsd-new-project                    # 交互模式
/gsd-new-project --auto @prd.md     # 从 PRD 自动抽取

--auto 模式非常适合已有 PRD/规格文档的团队：直接把 PRD 喂给命令，GSD 会解析出需求、路线图与项目状态，免去逐个回答提问的过程。

3.2 `/gsd-workspace`：隔离工作区管理

创建、列出或移除隔离的 GSD 工作区。每个工作区拥有独立的仓库副本与独立的 .planning/ 目录，互不干扰。

Flag	说明
`--new`	创建新工作区（配合 `--name`、`--repos` 等使用）
`--list`	列出活跃工作区及状态
`--remove <name>`	移除工作区并清理 git worktree
`--name <name>`	工作区名称（与 `--new` 搭配）
`--repos repo1,repo2`	逗号分隔的仓库路径或名称（与 `--new` 搭配）
`--path /target`	目标目录（默认：`~/gsd-workspaces/<name>`）
`--strategy worktree\|clone`	复制策略（默认：`worktree`）
`--branch <name>`	要检出的分支（默认：`workspace/<name>`）
`--auto`	跳过交互式提问

典型用例：

多仓库场景：只对仓库子集工作，同时保持独立的 GSD 状态
特性隔离：--repos . 为当前仓库创建 worktree，实现同仓库隔离
产物： WORKSPACE.md、.planning/、仓库副本（worktree 或 clone）

/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
/gsd-workspace --new --name feature-b --repos . --strategy worktree  # 同仓库隔离
/gsd-workspace --list
/gsd-workspace --remove feature-b

3.3 `/gsd-discuss-phase`：规划前的情境收集

在规划前通过自适应提问收集阶段上下文。

参数	必填	说明
`N`	否	阶段号（默认当前阶段）

Flag	说明
`--all`	跳过区域选择——交互式讨论所有灰色地带（不自动推进）
`--auto`	对所有问题自动选择推荐默认值
`--batch`	将问题分组批量接收，而非逐个问答
`--analyze`	讨论过程中附加权衡分析
`--power`	基于预填答案文件的文件式批量问答
`--assumptions`	不进行交互会话，直接呈现 Claude 对该阶段的实现假设

前置条件： .planning/ROADMAP.md 存在
产物： {phase}-CONTEXT.md、{phase}-DISCUSSION-LOG.md（审计轨迹）

/gsd-discuss-phase 1                # 阶段 1 的交互式讨论
/gsd-discuss-phase 1 --all          # 讨论所有灰色地带，跳过选择步骤
/gsd-discuss-phase 3 --auto         # 阶段 3 自动选择默认值
/gsd-discuss-phase --batch          # 当前阶段的批量模式
/gsd-discuss-phase 2 --analyze      # 带权衡分析的讨论
/gsd-discuss-phase 1 --power        # 从文件批量回答
/gsd-discuss-phase 3 --assumptions  # 规划前呈现 Claude 的假设

3.4 `/gsd-ui-phase`：生成 UI 设计契约

为前端阶段生成 UI 设计契约。

参数	必填	说明
`N`	否	阶段号（默认当前阶段）

前置条件： .planning/ROADMAP.md 存在，且阶段含前端/UI 工作
产物： {phase}-UI-SPEC.md

/gsd-ui-phase 2                     # 为阶段 2 生成设计契约

3.5 `/gsd-plan-phase`：研究、规划与校验

对阶段执行"研究 + 规划 + 校验"三合一流程，是流水线中最常用的命令之一。

参数	必填	说明
`N`	否	阶段号（默认下一个未规划阶段）

Flag	说明
`--auto`	跳过交互式确认
`--research`	即使 `RESEARCH.md` 已存在也强制重新研究
`--skip-research`	跳过领域研究步骤
`--research-phase <N>`	仅研究模式：为阶段 `<N>` 派生研究员、写入 `RESEARCH.md` 后在规划器之前退出。取代已删除的独立命令 `gsd-research-phase`（#3042）
`--view`	仅研究修饰符：与 `--research-phase` 搭配时，将现有 `RESEARCH.md` 打印到 stdout 并退出（不派生）
`--gaps`	缺口闭合模式（读取 `VERIFICATION.md`，跳过研究）
`--skip-verify`	跳过规划检查器的校验循环
`--prd <file>`	使用 PRD 文件替代 discuss-phase 作为上下文
`--ingest <path-or-glob>`	使用 ADR 文件替代 discuss-phase 进行上下文综合
`--ingest-format <auto\|nygard\|madr\|narrative>`	`--ingest` 的可选 ADR 解析器格式覆盖
`--reviews`	携带 `REVIEWS.md` 的跨 AI 评审反馈重新规划
`--validate`	规划开始前运行状态校验
`--bounce`	规划后运行外部规划反弹校验（使用 `workflow.plan_bounce_script`）
`--skip-bounce`	即使配置中启用了反弹也跳过

前置条件： .planning/ROADMAP.md 存在
产物： {phase}-RESEARCH.md、{phase}-{N}-PLAN.md、{phase}-VALIDATION.md

仅研究模式（--research-phase <N>）行为细节：

无修饰符：若 RESEARCH.md 已存在，提示 update / view / skip
带 --research：强制刷新——无条件重新派生研究员，不提示
带 --view：打印现有 RESEARCH.md 到 stdout，不派生；若 RESEARCH.md 缺失则报错

包合法性门禁（Package Legitimacy Gate，v1.42.1）：

当研究员推荐外部包时，会对每个包运行 slopcheck install <pkg> --json，并在 RESEARCH.md 中写入 ## Package Legitimacy Audit 表，记录 Registry、Age、Downloads、Source Repo 与 slopcheck 判定。判定结果分三档：

判定	行为
`[SLOP]`	包从 `RESEARCH.md` 中完全移除，永远到不了规划器
`[SUS]`	包被标记；规划器在安装任务前插入 `checkpoint:human-verify`
`[OK]`	包获批；不添加 checkpoint

来源为 WebSearch 的包会被标记为 [ASSUMED]（而非 [VERIFIED]），并按 [SUS] 同等对待——安装前需人工确认。若 slopcheck 无法安装，则所有推荐包都标记为 [ASSUMED] 并进入门禁。完整 checkpoint 格式、判定表与故障排查参见 User Guide 中的 Package Legitimacy Gate 小节。

/gsd-plan-phase 1                              # 阶段 1：研究 + 规划 + 校验
/gsd-plan-phase 3 --skip-research              # 不研究直接规划（熟悉领域）
/gsd-plan-phase --auto                         # 非交互式规划
/gsd-plan-phase 2 --validate                   # 规划前校验状态
/gsd-plan-phase 1 --bounce                     # 规划 + 外部反弹校验
/gsd-plan-phase 2 --ingest docs/adr/0010.md   # ADR 快捷路径综合上下文
/gsd-plan-phase 2 --ingest 'docs/adr/00*.md' --ingest-format auto
/gsd-plan-phase --research-phase 4             # 仅研究阶段 4（若 RESEARCH.md 存在则提示）
/gsd-plan-phase --research-phase 4 --view      # 打印已有 RESEARCH.md，不派生
/gsd-plan-phase --research-phase 4 --research  # 强制刷新研究，不提示

3.6 `/gsd-plan-review-convergence`：跨 AI 规划收敛循环

跨 AI 规划收敛循环——携带评审反馈反复重新规划，直到不再有 HIGH 级别关切。内部执行 plan-phase → review → replan → re-review 循环（默认最多 3 轮）。规划与评审各自派生隔离的 Agent，由编排器负责循环控制、HIGH 关切计数、停滞检测与升级处理。

参数 / Flag	必填	说明
`N`	是	要规划并评审的阶段号
`--codex` / `--gemini` / `--claude` / `--opencode`	否	选择单一评审者
`--all`	否	并行运行所有已配置评审者
`--max-cycles N`	否	覆盖循环上限（默认 3）

退出行为： 当 HIGH 计数归零时循环退出。停滞检测会在 HIGH 计数跨轮不降时发出警告。当达到 --max-cycles 但仍有 HIGH 关切未闭合时，升级门禁会询问用户是继续还是人工评审。

/gsd-plan-review-convergence 3                    # 默认评审者，3 轮
/gsd-plan-review-convergence 3 --codex            # 仅 Codex 评审
/gsd-plan-review-convergence 3 --all --max-cycles 5

3.7 `/gsd-ultraplan-phase`：云端规划（BETA）

[BETA] 将规划阶段卸载到 Claude Code 的 ultraplan 云；在浏览器中评审后导回。规划在远端起草，终端保持空闲；在浏览器中评审行内评论，然后通过 /gsd-import 把最终计划导入 .planning/。

Flag	必填	说明
`N`	是	要在远端规划的阶段号

隔离设计： 有意与 /gsd-plan-phase 分离，这样上游 ultraplan 的变更不会影响核心规划流水线。

/gsd-ultraplan-phase 4                  # 阶段 4 卸载到云端规划

3.8 `/gsd-execute-phase`：波次并行执行

以波次（wave）并行化执行阶段内全部计划，也可只执行指定波。

参数	必填	说明
`N`	是	要执行的阶段号

Flag	说明
`--wave N`	只执行阶段内的 Wave `N`
`--validate`	执行开始前运行状态校验
`--cross-ai`	将执行委托给外部 AI CLI（使用 `workflow.cross_ai_command`）
`--no-cross-ai`	即使配置启用了跨 AI 也强制本地执行

前置条件： 阶段存在 PLAN.md 文件
产物： 每个计划的 {phase}-{N}-SUMMARY.md、git 提交；阶段完全完成时生成 {phase}-VERIFICATION.md

包安装失败处理（v1.42.1）： 若某计划的安装步骤失败，执行器会弹出 checkpoint:human-verify 并停止。它不会自动安装名称相近的替代包——这是有意为之：静默替换包名正是 slopsquatting（依赖名仿冒攻击）的传播方式。请在注册页核实包后再响应 checkpoint。

/gsd-execute-phase 1                # 执行阶段 1
/gsd-execute-phase 1 --wave 2       # 只执行 Wave 2
/gsd-execute-phase 1 --validate     # 执行前校验状态
/gsd-execute-phase 2 --cross-ai     # 委托阶段 2 给外部 AI CLI

3.9 `/gsd-verify-work`：带自动诊断的 UAT

用户验收测试（UAT），发现问题时自动生成修复计划。

参数	必填	说明
`N`	否	阶段号（默认最后执行的阶段）

前置条件： 阶段已执行
产物： {phase}-UAT.md，发现问题时生成修复计划

/gsd-verify-work 1                  # 阶段 1 的 UAT

3.10 `/gsd-ship`：从已完成阶段创建 PR

从已完成阶段工作创建 PR，正文自动生成。

参数	必填	说明
`N`	否	阶段号或里程碑版本（如 `4` 或 `v1.0`）
`--draft`	否	以草稿 PR 形式创建

前置条件： 阶段已通过验证（/gsd-verify-work 通过）、已安装并认证 gh CLI
产物： 正文丰富的 GitHub PR（基于规划产物生成），STATE.md 更新

/gsd-ship 4                         # 交付阶段 4
/gsd-ship 4 --draft                 # 以草稿 PR 交付

PR 正文包含：

来自 ROADMAP.md 的阶段目标
来自 SUMMARY.md 文件的变更摘要
已覆盖的需求（REQ-ID）
验证状态
关键决策
ship.pr_body_sections 配置的可选 PRD 风格小节

自定义 PR 正文小节的接入、示例与校验规则参见 Custom PR Body Sections。

3.11 `/gsd-ui-review`：六支柱视觉审计

对已实现前端进行追溯式六支柱视觉审计。

参数	必填	说明
`N`	否	阶段号（默认最后执行的阶段）

前置条件： 项目有前端代码（可独立运行，无需 GSD 项目）
产物： {phase}-UI-REVIEW.md、.planning/ui-reviews/ 下的截图

/gsd-ui-review                      # 审计当前阶段
/gsd-ui-review 3                    # 审计阶段 3

3.12 `/gsd-audit-uat`：跨阶段 UAT 审计

跨阶段审计所有未决的 UAT 与验证项。

前置条件： 至少一个阶段已执行且含 UAT 或验证
产物： 分类审计报告 + 人工测试计划

/gsd-audit-uat

3.13 `/gsd-audit-milestone`：里程碑完成度审计

校验里程碑是否达成其完成定义（definition of done）。

前置条件： 所有阶段已执行
产物： 带差距分析的审计报告

/gsd-audit-milestone

3.14 `/gsd-complete-milestone`：归档里程碑并打标签

归档里程碑、打发布标签。

前置条件： 建议先完成里程碑审计
产物： MILESTONES.md 条目、git 标签

/gsd-complete-milestone

3.15 `/gsd-milestone-summary`：里程碑综合摘要

从里程碑产物生成综合项目摘要，用于团队入职与评审。

参数	必填	说明
`version`	否	里程碑版本（默认当前/最新里程碑）

前置条件： 至少一个已完成或进行中的里程碑
产物： .planning/reports/MILESTONE_SUMMARY-v{version}.md

摘要包含：

概述、架构决策、逐阶段分解
关键决策与权衡
需求覆盖情况
技术债与延期项
面向新成员的上手指南
生成后提供交互式 Q&A

/gsd-milestone-summary                # 汇总当前里程碑
/gsd-milestone-summary v1.0           # 汇总指定里程碑

3.16 `/gsd-new-milestone`：开启下一版本周期

开启下一个版本周期。

参数	必填	说明
`name`	否	里程碑名称
`--reset-phase-numbers`	否	在新里程碑从阶段 1 重新开始编号，并在路线图规划前归档旧阶段目录

前置条件： 上一里程碑已完成
产物： 更新的 PROJECT.md、新的 REQUIREMENTS.md、新的 ROADMAP.md

/gsd-new-milestone                  # 交互式
/gsd-new-milestone "v2.0 Mobile"    # 命名里程碑
/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile"  # 里程碑编号从 1 重新开始

4. 阶段管理命令

4.1 `/gsd-phase`：ROADMAP 阶段 CRUD

用单一命令对 ROADMAP.md 中的阶段执行增、插、删、改。

Flag	说明
（无）	在当前里程碑末尾追加一个新的整数阶段
`--insert <N>`	在阶段 N 之后插入紧急工作为十进制阶段（如 3.1）
`--remove <N>`	移除未来阶段并对后续阶段重新编号
`--edit <N>`	原地编辑既有阶段的任意字段
`--force`	允许编辑进行中或已完成的阶段（与 `--edit` 搭配）

前置条件： .planning/ROADMAP.md 存在
产物： 更新后的 ROADMAP.md

/gsd-phase "Add authentication system"          # 追加带描述的新阶段
/gsd-phase --insert 3 "Fix auth race condition" # 在阶段 3 与 4 之间插入 → 生成 3.1
/gsd-phase --remove 7               # 移除阶段 7，8→7、9→8 重新编号
/gsd-phase --edit 5                 # 编辑阶段 5 的任意字段
/gsd-phase --edit 5 --force         # 即使阶段 5 进行中或已完成也编辑

4.2 `/gsd-validate-phase`：Nyquist 验证缺口审计

追溯审计并补齐 Nyquist 验证缺口。

参数	必填	说明
`N`	否	阶段号

/gsd-validate-phase 2               # 审计阶段 2 的测试覆盖

5. 导航命令

5.1 `/gsd-progress`：状态总览与自动推进

显示状态、下一步，并自动推进到下一个逻辑工作流步骤。它读取项目状态并判定应执行的动作。

Flag	说明
`--next`	无需手动选择路由，自动推进到下一个逻辑工作流步骤
`--do "task description"`	分析自由文本意图并分派到最合适的 GSD 命令
`--forensic`	在标准报告后追加 6 项完整性审计（STATE 一致性、孤立 handoff、延期范围漂移、内存标记的待办工作、阻塞 todo、未提交代码）

自动路由行为（--next）：

项目状态	建议动作
无项目	建议 `/gsd-new-project`
阶段需要讨论	运行 `/gsd-discuss-phase`
阶段需要规划	运行 `/gsd-plan-phase`
阶段需要执行	运行 `/gsd-execute-phase`
阶段需要验证	运行 `/gsd-verify-work`
所有阶段完成	建议 `/gsd-complete-milestone`

这套"状态机式"路由在源码中有精确对应：sdk/src/query/route-next-action.ts 的 routeNextAction handler 依次检查：暂停标记（返回 /gsd-resume-work）→ .continue-here.md / 错误状态 / 未解决验证（返回阻塞提示）→ ROADMAP 有阶段但磁盘无阶段目录（/gsd-discuss-phase）→ 无 CONTEXT/RESEARCH（/gsd-discuss-phase）→ 有上下文但无 PLAN.md（/gsd-plan-phase）→ 存在未完成计划（/gsd-execute-phase）→ 全部有 SUMMARY 但未验证（/gsd-verify-work）→ 已验证则推进下一阶段（/gsd-discuss-phase）→ 无后续阶段（/gsd-complete-milestone）。此外，sdk/src/query/progress.ts 的 determinePhaseStatus 依据各阶段目录中 PLAN.md 与 SUMMARY.md 的数量比对和 VERIFICATION.md 检查，输出 Pending / Planned / In Progress / Executed / Complete / Needs Review 六种状态，是上述路由决策的数据基础。

/gsd-progress                       # "我在哪？下一步做什么？" + 自动路由
/gsd-progress --next                # 自动推进到下一步
/gsd-progress --do "fix the auth bug"  # 将自由文本意图分派到最佳 GSD 命令
/gsd-progress --forensic            # 标准报告 + 完整性审计

5.2 `/gsd-resume-work`：恢复完整上下文

从上次会话恢复完整上下文。

/gsd-resume-work                    # 上下文重置或新会话后使用

5.3 `/gsd-pause-work`：保存上下文交接

在阶段中途停止时保存上下文交接。

Flag	说明
`--report`	在 `.planning/reports/` 生成会后摘要，记录提交、文件变更与阶段进展

/gsd-pause-work                     # 创建 continue-here.md
/gsd-pause-work --report            # 创建 continue-here.md + 会话报告

5.4 `/gsd-manager`：多阶段命令中心

在单个终端管理多个阶段的交互式命令中心。

前置条件： .planning/ROADMAP.md 存在
行为特性：
- 全部阶段的可视化状态仪表盘
- 基于依赖与进展推荐最优下一步
- 任务分派：discuss 内联运行，plan/execute 以后台 Agent 运行
- 面向在一个终端并行推进多阶段的进阶用户设计
- 通过 manager.flags 配置支持逐步透传 flags（见 Configuration）

/gsd-manager                        # 打开命令中心仪表盘
/gsd-manager --analyze-deps         # 并行执行前扫描 ROADMAP 阶段的依赖关系

Checkpoint 心跳（#2410）：

后台 execute-phase 运行会在每个 wave 与 plan 边界发射 [checkpoint] 标记，确保 Claude API SSE 流在多计划阶段永远不会空闲到触发 Stream idle timeout - partial response received。格式如下：

[checkpoint] phase {N} wave {W}/{M} starting, {count} plan(s), {P}/{Q} plans done
[checkpoint] phase {N} wave {W}/{M} plan {plan_id} starting ({P}/{Q} plans done)
[checkpoint] phase {N} wave {W}/{M} plan {plan_id} complete ({P}/{Q} plans done)
[checkpoint] phase {N} wave {W}/{M} complete, {P}/{Q} plans done ({ok}/{count} ok)

若后台阶段中途失败，可在 transcript 中 grep [checkpoint] 查看最后确认的边界。manager 的后台完成处理器用这些标记在 Agent 报错时汇报部分进展。

Manager 透传 Flags：

在 .planning/config.json 的 manager.flags 下配置各步骤 flag，会追加到每个分派命令后：

{
  "manager": {
    "flags": {
      "discuss": "--auto",
      "plan": "--skip-research",
      "execute": "--validate"
    }
  }
}

对应工作流实现见 get-shit-done/workflows/manager.md，其中明确 manager_flags 逐步骤透传的初始化方式（例如 gsd-sdk query config-set manager.flags.discuss "--auto --analyze"）。

5.5 `/gsd-help`：分级帮助系统

按你要求的层级展示 GSD 命令。默认适合一屏；--full 为完整参考；<topic> 直接跳到某个小节。

/gsd-help                           # 一页速览（默认）
/gsd-help --brief                   # 约 10 行的顶级命令速记
/gsd-help --full                    # 完整参考（每个命令、每个 flag）
/gsd-help <topic>                   # 只显示一个小节（如 /gsd-help debug）
/gsd-help --brief <topic>           # 紧凑定向查询——签名 + 一行摘要

帮助主题的完整别名映射表位于 get-shit-done/workflows/help/modes/topic.md，未知主题会打印已识别列表。分层实现由 get-shit-done/workflows/help/modes/ 下的 default.md、brief.md、full.md、topic.md 四个模式文件共同支撑。

6. 工具命令

6.1 `/gsd-explore`：苏格拉底式构思

通过探询式提问引导想法，可选派生研究，然后把输出路由到正确的 GSD 产物（笔记、todos、seeds、研究问题、需求或新阶段）。

参数	必填	说明
`topic`	否	要探索的主题（如 `/gsd-explore authentication strategy`）

/gsd-explore                        # 开放式构思会话
/gsd-explore authentication strategy  # 探索特定主题

6.2 `/gsd-undo`：安全的 git 回滚

基于阶段 manifest 回滚 GSD 阶段或计划提交，带依赖检查与确认门禁。

Flag	必填	说明
`--last N`	（三者必选其一）	展示近期 GSD 提交供交互式选择
`--phase NN`	（三者必选其一）	回滚某阶段全部提交
`--plan NN-MM`	（三者必选其一）	回滚某具体计划的全部提交

安全性： 回滚前检查依赖阶段/计划；始终显示确认门禁。

/gsd-undo --last 5                  # 从最近 5 个 GSD 提交中选择
/gsd-undo --phase 03                # 回滚阶段 3 的全部提交
/gsd-undo --plan 03-02              # 回滚阶段 3 计划 02 的提交

6.3 `/gsd-import`：导入外部计划

将外部计划文件摄入 GSD 规划系统，写入前先对照 PROJECT.md 决策做冲突检测。

Flag	必填	说明
`--from <filepath>`	是（或 `--from-gsd2`）	要导入的外部计划文件路径
`--from-gsd2`	是（或 `--from`）	将 GSD-2（`.gsd/`）项目反向迁移回 GSD v1（`.planning/`）格式
`--path <dir>`	否	与 `--from-gsd2` 搭配：GSD-2 项目目录路径（默认当前目录）

流程： 检测冲突 → 提示解决 → 以 GSD PLAN.md 格式写入 → 经 gsd-plan-checker 校验

/gsd-import --from /tmp/team-plan.md    # 导入并校验外部计划
/gsd-import --from-gsd2                # 从 GSD-2 迁移回 v1（当前目录）
/gsd-import --from-gsd2 --path ~/old-project  # 从其他路径迁移

6.4 `/gsd-ingest-docs`：文档批量导入

从仓库既有 ADRs、PRDs、SPECs 与文档引导或合并 .planning/ 初始化。并行运行分类（gsd-doc-classifier）加综合（gsd-doc-synthesizer），综合带优先级规则与循环检测。产出三桶冲突报告（INGEST-CONFLICTS.md：自动解决 / 竞争变体 / 未解决阻塞），并对 LOCKED-vs-LOCKED 的 ADR 矛盾硬阻断。

参数 / Flag	必填	说明
`path`	否	要扫描的目标目录（默认仓库根）
`--mode new\|merge`	否	覆盖自动检测（默认：无 `.planning/` 时为 `new`，存在时为 `merge`）
`--manifest <file>`	否	列出每个文档 `{path, type, precedence?}` 的 YAML 文件；覆盖启发式分类
`--resolve auto`	否	冲突解决模式（v1 仅支持 `auto`；`interactive` 预留）

限制： v1 单次调用上限 50 个文档。共享的冲突检测契约抽取在 references/doc-conflict-engine.md，/gsd-import 同样消费该契约。

/gsd-ingest-docs                            # 扫描仓库根，自动检测模式
/gsd-ingest-docs docs/                      # 只摄入 docs/ 下的文档
/gsd-ingest-docs --manifest ingest.yaml     # 显式优先级 manifest

6.5 `/gsd-quick`：带 GSD 保证的临时任务

Flag	说明
`--full`	启用完整质量流水线——讨论 + 研究 + 计划检查 + 验证
`--validate`	仅计划检查（最多 2 轮）+ 执行后验证；不含讨论与研究
`--discuss`	轻量级规划前讨论
`--research`	规划前派生专注研究员

粒度 flag 可自由组合：--discuss --research --validate 等价于 --full。

子命令	说明
`list`	列出全部临时任务及状态
`status <slug>`	显示指定临时任务的状态
`resume <slug>`	按 slug 恢复指定临时任务

/gsd-quick                          # 基础临时任务
/gsd-quick --discuss --research     # 讨论 + 研究 + 规划
/gsd-quick --validate               # 仅计划检查 + 验证
/gsd-quick --full                   # 完整质量流水线
/gsd-quick list                     # 列出全部临时任务
/gsd-quick status my-task-slug      # 显示临时任务状态
/gsd-quick resume my-task-slug      # 恢复临时任务

6.6 `/gsd-autonomous`：全自动运行剩余阶段

Flag	说明
`--from N`	从指定阶段号开始
`--to N`	在完成指定阶段号后停止
`--interactive`	精简上下文 + 用户输入

/gsd-autonomous                     # 运行所有剩余阶段
/gsd-autonomous --from 3            # 从阶段 3 开始
/gsd-autonomous --to 5              # 运行到并包括阶段 5
/gsd-autonomous --from 3 --to 5     # 运行阶段 3 到 5

6.7 `/gsd-debug`：带持久状态的系统化调试

参数	必填	说明
`description`	否	Bug 描述

Flag	说明
`--diagnose`	仅诊断模式——只调查、不尝试修复

子命令：

/gsd-debug list — 列出全部活跃调试会话，含状态、假设与下一步
/gsd-debug status <slug> — 不派生 Agent，直接打印会话完整摘要（证据数、已排除数、解决方案、TDD checkpoint）
/gsd-debug continue <slug> — 按 slug 恢复指定会话（先呈现 Current Focus 再派生续接 Agent）
/gsd-debug [--diagnose] <description> — 开启新调试会话（--diagnose 在定位根因后停止，不应用修复）

TDD 模式： 当 .planning/config.json 中 tdd_mode: true 时，调试会话要求先写出并验证一个失败测试，然后才应用修复（红 → 绿 → 完成）。

/gsd-debug "Login button not responding on mobile Safari"
/gsd-debug --diagnose "Intermittent 500 errors on /api/users"
/gsd-debug list
/gsd-debug status auth-token-null
/gsd-debug continue form-submit-500

6.8 `/gsd-add-tests`：为已完成阶段生成测试

参数	必填	说明
`N`	否	阶段号

/gsd-add-tests 2                    # 为阶段 2 生成测试

6.9 `/gsd-stats`：项目统计

/gsd-stats                          # 项目指标仪表盘

6.10 `/gsd-profile-user`：开发者行为画像

基于 Claude Code 会话分析生成开发者行为画像，覆盖 8 个维度（沟通风格、决策模式、调试方式、UX 偏好、供应商选择、挫折触发点、学习风格、解释深度）。产物用于个性化 Claude 的响应。

Flag	说明
`--questionnaire`	用交互式问卷替代会话分析
`--refresh`	重新分析会话并重新生成画像

生成产物：

USER-PROFILE.md — 完整行为画像
CLAUDE.md profile 小节 — 由 Claude Code 自动发现

/gsd-profile-user                   # 分析会话并构建画像
/gsd-profile-user --questionnaire   # 交互式问卷兜底
/gsd-profile-user --refresh         # 从全新分析重新生成

6.11 `/gsd-health`：规划目录健康检查

校验 .planning/ 目录完整性。带 --context 时探测上下文窗口利用率门禁（60% / 70% 阈值，v1.40.0 新增，见 #2792）。

Flag	说明
`--repair`	自动修复可恢复问题
`--context`	探测上下文窗口利用率；60% 警告、70% 危急

/gsd-health                         # 检查完整性
/gsd-health --repair                # 检查并修复
/gsd-health --context               # 上下文利用率分流

6.12 `/gsd-cleanup`：归档阶段目录

归档已完成里程碑积累的阶段目录。

/gsd-cleanup

7. 试验与草图命令

7.1 `/gsd-spike`：可行性试验

在确定实现方案前运行 2–5 个聚焦的可行性试验。每个试验使用 Given/When/Then 框架，产出可执行代码，并返回 VALIDATED / INVALIDATED / PARTIAL 判定。

参数	必填	说明
`idea`	否	要调查的技术问题或方案
`--quick`	否	跳过摄入对话，直接使用 `idea` 文本
`--wrap-up`	否	将完成的 spike 发现打包为可复用的项目本地技能

产物： .planning/spikes/NNN-experiment-name/（含代码、结果与 README）；.planning/spikes/MANIFEST.md
--wrap-up 产物： .claude/skills/spike-findings-[project]/ 技能文件

/gsd-spike                              # 交互式摄入
/gsd-spike "can we stream LLM tokens through SSE"
/gsd-spike --quick websocket-vs-polling
/gsd-spike --wrap-up                    # 把发现打包成可复用技能

7.2 `/gsd-sketch`：HTML 原型设计探索

通过一次性 HTML 原型探索设计方向。每个设计问题产出 2–3 个变体，供浏览器直接对比。

参数	必填	说明
`idea`	否	要探索的 UI 设计问题或方向
`--quick`	否	跳过情绪摄入，直接使用 `idea` 文本
`--text`	否	文本模式兜底——用编号列表替代交互式提示（供非 Claude 运行时）
`--wrap-up`	否	将胜出的草图决策打包为可复用的项目本地技能

产物： .planning/sketches/NNN-descriptive-name/index.html（2–3 个交互变体）、README.md、共享 themes/default.css；.planning/sketches/MANIFEST.md
--wrap-up 产物： .claude/skills/sketch-findings-[project]/ 技能文件

/gsd-sketch                             # 交互式情绪摄入
/gsd-sketch "dashboard layout"
/gsd-sketch --quick "sidebar navigation"
/gsd-sketch --text "onboarding flow"    # 非 Claude 运行时
/gsd-sketch --wrap-up                   # 把胜出草图打包成技能

8. 诊断命令

8.1 `/gsd-forensics`：失败工作流的事后分析

针对失败的 GSD 工作流做事后调查——诊断哪里出了问题。

参数	必填	说明
`description`	否	问题描述（省略时提示输入）

前置条件： .planning/ 目录存在
产物： .planning/forensics/report-{timestamp}.md

调查覆盖：

Git 历史分析（近期提交、卡死模式、时间空隙）
产物完整性（已完成阶段应有的文件）
STATE.md 异常与会话历史
未提交工作、冲突、被放弃的变更
至少检查 4 类异常（卡死循环、缺失产物、被放弃工作、崩溃/中断）
若有可操作发现，提供 GitHub issue 创建入口

/gsd-forensics                              # 交互式——提示输入问题
/gsd-forensics "Phase 3 execution stalled"  # 带问题描述

8.2 `/gsd-extract-learnings`：可复用经验抽取

从已完成阶段工作中抽取可复用的模式、反模式与架构决策。

参数	必填	说明
`N`	是	要抽取经验的阶段号

Flag	说明
`--all`	从全部已完成阶段抽取
`--format`	输出格式：`markdown`（默认）、`json`

前置条件： 阶段已执行（存在 SUMMARY.md 文件）
产物： .planning/learnings/{phase}-LEARNINGS.md

抽取内容：

架构决策及其理由
效果良好的模式（未来阶段可复用）
遭遇的反模式及解决方式
技术特定洞察
性能与测试观察

/gsd-extract-learnings 3                    # 抽取阶段 3 的经验
/gsd-extract-learnings --all                # 从全部已完成阶段抽取

9. 工作流管理

9.1 `/gsd-workstreams`：并行工作流管理

管理并行工作流，用于不同里程碑区域的并发工作。

子命令：

子命令	说明
`list`	列出全部工作流及状态（无子命令时默认）
`create <name>`	创建新工作流
`status <name>`	单个工作流的详细状态
`switch <name>`	设置活跃工作流
`progress`	跨工作流进展汇总
`complete <name>`	归档已完成工作流
`resume <name>`	恢复某工作流中的工作

前置条件： 活跃 GSD 项目
产物： .planning/ 下的工作流目录、每个工作流的状态追踪

/gsd-workstreams                    # 列出全部工作流
/gsd-workstreams create backend-api # 创建新工作流
/gsd-workstreams switch backend-api # 设置活跃工作流
/gsd-workstreams status backend-api # 详细状态
/gsd-workstreams progress           # 跨工作流进展总览
/gsd-workstreams complete backend-api  # 归档已完成工作流
/gsd-workstreams resume backend-api    # 恢复工作流中的工作

10. 配置命令

10.1 `/gsd-settings`：交互式工作流开关与模型画像

交互式配置工作流开关与模型画像。问题按六个可视化分区组织：

Planning（规划） — Research、Plan Checker、Pattern Mapper、Nyquist、UI Phase、UI Gate、AI Phase
Execution（执行） — Verifier、TDD Mode、Code Review、Code Review Depth （条件项——仅当 Code Review 开启时出现）、UI Review
Docs & Output（文档与输出） — Commit Docs、Skip Discuss、Worktrees
Features（特性） — Intel、Graphify
Model & Pipeline（模型与流水线） — Model Profile、Auto-Advance、Branching
Misc（杂项） — Context Warnings、Research Qs

所有答案经 gsd-sdk query config-set 合并到解析出的项目配置路径（标准安装为 .planning/config.json，存在活跃工作流时为 .planning/workstreams/<active>/config.json），保留无关键。确认后，可将完整设置对象保存到 ~/.gsd/defaults.json，使未来的 /gsd-new-project 从同一基线开始。

/gsd-settings                       # 交互式配置

10.2 `/gsd-config`：统一配置命令

用单一命令交互式配置 GSD——工作流开关、高级旋钮、集成与模型画像。

Flag	说明
（无）	常见开关：model、research、plan_check、verifier、branching
`--advanced`	进阶用户旋钮：规划调优、超时、分支模板、跨 AI 执行、运行时/输出
`--integrations`	第三方 API 密钥、代码评审 CLI 路由、Agent 技能注入
`--profile <name>`	快速画像切换：`quality`、`balanced`、`budget` 或 `inherit`

--advanced 分区：

分区	键
Planning Tuning	`workflow.plan_bounce`、`workflow.plan_bounce_passes`、`workflow.plan_bounce_script`、`workflow.subagent_timeout`、`workflow.inline_plan_threshold`
Execution Tuning	`workflow.node_repair`、`workflow.node_repair_budget`、`workflow.auto_prune_state`
Discussion Tuning	`workflow.max_discuss_passes`
Cross-AI Execution	`workflow.cross_ai_execution`、`workflow.cross_ai_command`、`workflow.cross_ai_timeout`
Git Customization	`git.base_branch`、`git.phase_branch_template`、`git.milestone_branch_template`
Runtime / Output	`response_language`、`context_window`、`search_gitignored`、`graphify.build_timeout`

所有答案经 gsd-sdk query config-set 合并，保留无关键。API 密钥在所有输出中掩码显示为 ****<last-4>。底层实现在 sdk/src/query/config-mutation.ts：config-set 执行 key 校验与值强制转换（与 CJS cmdConfigSet 行为对齐，见 #3593），拒绝 config-set <key> 这类缺值调用，并对布尔/数组类型做严格判定，避免把 git.create_tag maybe 这类非法值静默写入。

/gsd-config                         # 常见开关交互式配置
/gsd-config --advanced              # 进阶用户旋钮（六分区提示）
/gsd-config --integrations          # API 密钥、评审 CLI 路由、Agent 技能
/gsd-config --profile budget        # 切换到 budget 画像
/gsd-config --profile quality       # 切换到 quality 画像

完整 schema 与默认值见 CONFIGURATION.md。

10.3 `/gsd-surface`：技能面开关

切换哪些技能被暴露——应用画像、列出或禁用某个集群，无需重装。

子命令	说明
`list`	显示已启用与已禁用的集群和技能
`status`	`list` 的别名，另附 token 成本摘要
`profile <name>`	写入 `baseProfile` 并重新编排技能
`disable <cluster>`	把集群加入禁用列表并重新编排
`enable <cluster>`	把集群从禁用列表移除并重新编排
`reset`	删除 surface 增量；恢复安装时画像

/gsd-surface list                   # 显示当前技能面
/gsd-surface profile standard       # 切换到 standard 画像
/gsd-surface disable utility        # 禁用 utility 集群
/gsd-surface reset                  # 恢复安装时画像

11. 存量代码库命令（Brownfield）

11.1 `/gsd-map-codebase`：并行代码库测绘

用并行 mapper Agent 分析既有代码库。--fast 做快速单 Agent 扫描，--query 检索既有 intel。

参数	必填	说明
`area`	否	将测绘范围限定到特定领域
`--fast`	否	快速单焦点评估——派生 1 个 mapper Agent 而非 4 个并行（轻量替代）
`--query <term>`	否	检索 `.planning/intel/` 中的可查询代码库 intel 文件（需 `intel.enabled: true`）

Flag	说明
`--focus tech\|arch\|quality\|concerns\|tech+arch`	`--fast` 模式的焦点领域（默认：`tech+arch`）

产物： .planning/codebase/ 分析文档（完整模式）；.planning/codebase/ 定向文档（--fast）；intel 检索结果（--query）

/gsd-map-codebase                   # 完整代码库分析（4 个并行 Agent）
/gsd-map-codebase auth              # 聚焦 auth 领域
/gsd-map-codebase --fast            # 快速技术 + 架构总览（1 个 Agent）
/gsd-map-codebase --fast --focus quality  # 仅质量与代码健康
/gsd-map-codebase --query authentication  # 检索 intel 中的术语

11.2 `/gsd-graphify`：项目知识图谱

构建、检索与检视存储在 .planning/graphs/ 的项目知识图谱。通过 config.json 中 graphify.enabled: true 开启（见 Configuration Reference）；禁用时命令打印激活提示并停止。

子命令	说明
`build`	构建或重建知识图谱（内联运行 `graphify update .` 并刷新 `.planning/graphs/`）
`query <term>`	在图谱中检索某术语
`status`	显示图谱新鲜度与统计
`diff`	显示自上次构建以来的变更

产物： .planning/graphs/ 图谱产物（节点、边、快照）

/gsd-graphify build                 # 构建或重建知识图谱
/gsd-graphify query authentication  # 在图谱中检索某术语
/gsd-graphify status                # 显示新鲜度与统计
/gsd-graphify diff                  # 显示自上次构建以来的变更

编程式访问： node gsd-tools.cjs graphify <build|query|status|diff|snapshot>——见 CLI Tools Reference。

12. AI 集成命令

12.1 `/gsd-ai-integration-phase`：AI 系统设计契约

为涉及构建 AI 系统的阶段生成 AI-SPEC.md 设计契约。呈现交互式决策矩阵，暴露领域特定失败模式与 eval 标准，产出含框架推荐、实现指引与评估策略的 AI-SPEC.md。

产物： 阶段目录下的 {phase}-AI-SPEC.md
派生： 3 个并行专家 Agent：domain-researcher、framework-selector、ai-researcher、eval-planner

/gsd-ai-integration-phase              # 当前阶段的向导
/gsd-ai-integration-phase 3           # 指定阶段的向导

12.2 `/gsd-eval-review`：AI 阶段评估覆盖审计

审计已执行 AI 阶段的评估覆盖，产出 EVAL-REVIEW.md 整改计划。对照 /gsd-ai-integration-phase 产出的 AI-SPEC.md 评估计划检查实现。每个评估维度评分为 COVERED/PARTIAL/MISSING。

前置条件： 阶段已执行且存在 AI-SPEC.md
产物： {phase}-EVAL-REVIEW.md，含发现、缺口与整改指引

/gsd-eval-review                       # 审计当前阶段
/gsd-eval-review 3                     # 审计指定阶段

13. 更新命令

13.1 `/gsd-update`：带变更日志预览的更新

带变更日志预览更新 GSD，可选同步技能或重新应用本地补丁。

Flag	说明
`--sync`	更新后从 GSD registry 同步技能
`--reapply`	更新后恢复本地修改（补丁）

/gsd-update                         # 检查更新并安装
/gsd-update --sync                  # 更新并同步技能
/gsd-update --reapply               # 更新并重新应用本地补丁

14. 代码质量命令

14.1 `/gsd-code-review`：阶段变更评审

评审阶段内变更的源文件，检查 bug、安全漏洞与代码质量问题。--fix 在评审后自动修复发现。

参数	必填	说明
`N`	是	要评审其变更的阶段号（如 `2` 或 `02`）

Flag	说明
`--depth=quick\|standard\|deep`	评审深度（覆盖 `workflow.code_review_depth` 配置）。`quick`：仅模式匹配（约 2 分钟）。`standard`：逐文件分析 + 语言特定检查（约 5–15 分钟，默认）。`deep`：跨文件分析，含导入图与调用链（约 15–30 分钟）
`--files file1,file2,...`	显式逗号分隔文件列表；完全跳过 SUMMARY/git 范围界定
`--fix`	评审后自动修复——读取 REVIEW.md、派生 fixer Agent、每个修复原子提交
`--fix --all`	把 Info 级发现纳入修复范围（默认仅 Critical + Warning）
`--fix --auto`	修复 + 复审迭代循环，上限 3 轮

前置条件： 阶段已执行且存在 SUMMARY.md 或 git 历史
产物： {phase}-REVIEW.md（按严重级分类的发现）；使用 --fix 时生成 {phase}-REVIEW-FIX.md
派生： gsd-code-reviewer Agent；--fix 时派生 gsd-code-fixer Agent

可选结构化预扫描： 设 code_quality.fallow.enabled 为 true，在 Agent 评审前运行 fallow。GSD 写入 {phase}/FALLOW.json 并在 REVIEW.md 中嵌入 Structural Findings (fallow) 小节。用 code_quality.fallow.scope 与 code_quality.fallow.profile 配置范围与画像。

/gsd-code-review 3                          # 阶段 3 标准评审
/gsd-code-review 2 --depth=deep             # 深度跨文件评审
/gsd-code-review 4 --files src/auth.ts,src/token.ts  # 显式文件列表
/gsd-code-review 3 --fix                    # 评审后修复 Critical + Warning 发现
/gsd-code-review 3 --fix --all             # 评审后修复含 Info 在内的全部发现
/gsd-code-review 3 --fix --auto            # 评审、修复、复审直至干净（最多 3 轮）

14.2 `/gsd-audit-fix`：自主审计到修复流水线

自主"审计到修复"流水线——运行审计、分类发现、带测试验证修复可自动修复项、每个修复原子提交。

Flag	说明
`--source <audit>`	运行哪个审计（默认：`audit-uat`）
`--severity high\|medium\|all`	要处理的最低严重级（默认：`medium`）
`--max N`	最多修复的发现数（默认：5）
`--dry-run`	不修复，仅分类发现（显示分类表）

前置条件： 至少一个阶段已执行且含 UAT 或验证
产物： 带测试验证的修复提交；分类报告

/gsd-audit-fix                              # 运行 audit-uat，修复 medium+ 问题（最多 5 个）
/gsd-audit-fix --severity high             # 只修复高严重级问题
/gsd-audit-fix --dry-run                   # 预览分类而不修复
/gsd-audit-fix --max 10 --severity all     # 修复最多 10 个任意严重级问题

15. 快速与内联命令

15.1 `/gsd-fast`：内联琐碎任务

内联执行琐碎任务——无子 Agent、无规划开销。适合错别字修复、配置变更、小重构、遗忘的提交。

参数	必填	说明
`task description`	否	要做什么（省略时提示）

不是 /gsd-quick 的替代品——任何需要研究、多步规划或验证的任务都应使用 /gsd-quick。

/gsd-fast "fix typo in README"
/gsd-fast "add .env to gitignore"

15.2 `/gsd-review`：外部 AI CLI 的跨 AI 评审

由外部 AI CLI 对阶段计划做跨 AI 同行评审。

参数	必填	说明
`--phase N`	是	要评审的阶段号

Flag	说明
`--gemini`	纳入 Gemini CLI 评审
`--claude`	纳入 Claude CLI 评审（独立会话）
`--codex`	纳入 Codex CLI 评审
`--coderabbit`	纳入 CodeRabbit 评审
`--opencode`	纳入 OpenCode 评审（经 GitHub Copilot）
`--qwen`	纳入 Qwen Code 评审（阿里 Qwen 模型）
`--cursor`	纳入 Cursor Agent 评审
`--ollama`	纳入 Ollama 服务器评审
`--lm-studio`	纳入 LM Studio 服务器评审
`--llama-cpp`	纳入 llama.cpp 服务器评审
`--all`	纳入所有可用评审者（CLI + 本地模型服务器）

无 flag 时的默认评审者行为：

若 review.default_reviewers 未设置，/gsd-review 运行全部检测到的评审者（当前默认行为）
若 已设置，只运行该子集（例如 ["gemini","codex"]）
--all 始终覆盖配置，运行全部检测集合
显式 flag（如 --cursor）覆盖该次运行的 --all 与配置默认值
产物： {phase}-REVIEWS.md——可被 /gsd-plan-phase --reviews 消费

# 设置无 flag 运行时 /gsd-review 的项目默认评审者
gsd config-set review.default_reviewers '["gemini","codex"]'

/gsd-review --phase 2             # 从配置运行 gemini+codex
/gsd-review --phase 3 --all
/gsd-review --phase 2 --gemini
/gsd-review --phase 2 --cursor    # 单次覆盖

15.3 `/gsd-pr-branch`：过滤规划提交的干净 PR 分支

通过过滤 .planning/ 提交创建干净的 PR 分支。

参数	必填	说明
`target branch`	否	基础分支（默认：`main`）

目的： 评审者只看到代码变更，不看到 GSD 规划产物。

/gsd-pr-branch                     # 相对 main 过滤
/gsd-pr-branch develop             # 相对 develop 过滤

15.4 `/gsd-secure-phase`：威胁缓解追溯验证

追溯验证已完成阶段的威胁缓解措施。

参数	必填	说明
`phase number`	否	要审计的阶段（默认：最后完成的阶段）

前置条件： 阶段必须已执行。有或没有 SECURITY.md 均可工作
产物： {phase}-SECURITY.md，含威胁验证结果
派生： gsd-security-auditor Agent

三种工作模式：

存在 SECURITY.md — 审计并验证既有缓解措施
无 SECURITY.md 但 PLAN.md 含威胁模型 — 从产物生成
阶段未执行 — 退出并给出指引

/gsd-secure-phase                   # 审计最后完成的阶段
/gsd-secure-phase 5                 # 审计指定阶段

15.5 `/gsd-docs-update`：经代码库验证的文档生成

生成或更新对照代码库验证过的项目文档。

参数	必填	说明
`--force`	否	跳过保留提示，重新生成全部文档
`--verify-only`	否	只检查既有文档准确性，不生成

产物： 最多 9 个文档文件（README、architecture、API、getting started、development、testing、configuration、deployment、contributing）
派生： gsd-doc-writer Agent（每个文档类型一个），随后 gsd-doc-verifier Agent 做事实校验

每个文档写作者直接探索代码库——不产生幻觉路径或过期签名。文档校验器对照实时文件系统核查声明。

/gsd-docs-update                    # 交互式生成/更新文档
/gsd-docs-update --force            # 重新生成全部文档
/gsd-docs-update --verify-only      # 只校验既有文档

16. 任务捕获与积压命令

16.1 `/gsd-capture`：捕获想法与任务

把想法、任务、笔记与种子捕获到相应目的地。默认模式添加结构化 todo；flags 路由到专门的捕获工作流。

Flag	说明
（无）	捕获为结构化 todo 供后续工作
`--note [text]`	零摩擦笔记——追加、列出（`--note list`）或升级（`--note promote N`）
`--backlog <description>`	用 999.x 编号加入积压停车区
`--seed [idea summary]`	捕获带触发条件的未来导向想法
`--list`	列出待办 todo 并选择一项工作
`--global`	使用全局作用域（用于笔记操作）

积压（Backlog）： 999.x 编号使条目保持在活跃阶段序列之外；阶段目录立即创建，因此 /gsd-discuss-phase 与 /gsd-plan-phase 可直接对它们工作。 种子（Seeds）： 保留完整 WHY、WHEN to surface 与面包屑——由 /gsd-new-milestone 消费。

产物： .planning/todos/（默认）、笔记文件（--note）、ROADMAP.md 积压小节（--backlog）、.planning/seeds/SEED-NNN-slug.md（--seed）

/gsd-capture "Consider adding dark mode support"   # 添加 todo
/gsd-capture --note "Caching strategy idea"        # 快速笔记
/gsd-capture --note list                           # 列出全部笔记
/gsd-capture --note promote 3                      # 把笔记 3 升级为 todo
/gsd-capture --backlog "GraphQL API layer"         # 加入积压
/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
/gsd-capture --list                                # 浏览并处理 todos

16.2 `/gsd-review-backlog`：积压评审与升级

评审并把积压条目升级到活跃里程碑。每个条目的动作： Promote（移入活跃序列）、Keep（留在积压）、Remove（删除）。

/gsd-review-backlog

16.3 `/gsd-thread`：持久上下文线程

管理跨会话工作的持久上下文线程。

参数	必填	说明
（无）/ `list`	—	列出全部线程
`list --open`	—	只列出 `open` 或 `in_progress` 状态的线程
`list --resolved`	—	只列出 `resolved` 状态的线程
`status <slug>`	—	显示指定线程状态
`close <slug>`	—	将线程标记为已解决
`name`	—	按名称恢复既有线程
`description`	—	创建新线程

线程是轻量级跨会话知识存储，用于跨多会话但不属于任何具体阶段的工作。比 /gsd-pause-work 更轻量。

/gsd-thread                         # 列出全部线程
/gsd-thread list --open             # 只列出打开/进行中线程
/gsd-thread list --resolved         # 只列出已解决线程
/gsd-thread status fix-deploy-key   # 显示线程状态
/gsd-thread close fix-deploy-key    # 标记线程已解决
/gsd-thread fix-deploy-key-auth     # 恢复线程
/gsd-thread "Investigate TCP timeout in pasta service"  # 创建新线程

17. 状态管理命令

状态管理命令以 node gsd-tools.cjs 编程式调用，面向脚本化与流水线集成场景。

17.1 `state validate`：STATE 漂移检测

检测 STATE.md 与真实文件系统之间的漂移。

前置条件： .planning/STATE.md 存在
产物： 校验报告，展示 STATE.md 字段与文件系统现实之间的任何漂移

node gsd-tools.cjs state validate

17.2 `state sync [--verify]`：从磁盘重建 STATE

从磁盘上的真实项目状态重建 STATE.md。

Flag	说明
`--verify`	试运行模式——只展示拟议变更，不写入

前置条件： .planning/ 目录存在
产物： 反映文件系统现实的更新版 STATE.md

node gsd-tools.cjs state sync             # 从磁盘重建 STATE.md
node gsd-tools.cjs state sync --verify    # 试运行：不写入，只展示变更

17.3 `state planned-phase`：记录规划后状态迁移

在 plan-phase 完成后记录状态迁移（Planned/Ready to execute）。

Flag	说明
`--phase N`	已规划的阶段号
`--plans N`	生成的计划数

前置条件： 阶段已规划
产物： 带规划后状态的更新版 STATE.md

node gsd-tools.cjs state planned-phase --phase 3 --plans 2

18. 社区命令与 Hooks

18.1 社区 Hooks

可选的 git 与会话 hooks，由 .planning/config.json 中 hooks.community: true 控制。除非显式启用，否则全部为 no-op。

Hook	用途
`gsd-validate-commit.sh`	强制 git 提交信息符合 Conventional Commits 格式
`gsd-session-state.sh`	追踪会话状态迁移
`gsd-phase-boundary.sh`	强制阶段边界检查

启用方式：

{ "hooks": { "community": true } }

18.2 社区邀请

要加入 GSD Discord 社区，请访问 GSD README 中的链接，或运行 /gsd-help 并点击其中显示的 Discord 链接。

19. 贡献规范：技能描述预算

每个 commands/gsd/*.md frontmatter 中的 description: 字段会被注入每个会话的系统提示。为控制单会话开销，描述必须 ≤ 100 字符，且不得重复 argument-hint: 中已有的 flag 文档。

lint 门禁强制执行该预算：

npm run lint:descriptions

该检查也作为 npm test 的一部分运行，对应测试为 tests/enh-2789-description-budget.test.cjs。

附：命令速查索引

类别	命令
命名空间	`workflow`、`project`、`quality`、`context`、`manage`、`ideate`
核心工作流	`new-project`、`workspace`、`discuss-phase`、`ui-phase`、`plan-phase`、`plan-review-convergence`、`ultraplan-phase`、`execute-phase`、`verify-work`、`ship`、`ui-review`、`audit-uat`、`audit-milestone`、`complete-milestone`、`milestone-summary`、`new-milestone`
阶段管理	`phase`、`validate-phase`
导航	`progress`、`resume-work`、`pause-work`、`manager`、`help`
工具	`explore`、`undo`、`import`、`ingest-docs`、`quick`、`autonomous`、`debug`、`add-tests`、`stats`、`profile-user`、`health`、`cleanup`
试验与草图	`spike`、`sketch`
诊断	`forensics`、`extract-learnings`
工作流管理	`workstreams`
配置	`settings`、`config`、`surface`
存量代码库	`map-codebase`、`graphify`
AI 集成	`ai-integration-phase`、`eval-review`
更新	`update`
代码质量	`code-review`、`audit-fix`
快速与内联	`fast`、`review`、`pr-branch`、`secure-phase`、`docs-update`
任务捕获	`capture`、`review-backlog`、`thread`
状态管理	`state validate`、`state sync`、`state planned-phase`