@@ -482,12 +114,12 @@ OpenCode, Gemini CLI, Kilo e Codex agora são suportados nativamente via `npx @o
## Licença
-Licença MIT. Veja [LICENSE](LICENSE).
+Licença MIT. Consulte [LICENSE](LICENSE) para detalhes.
---
-**Claude Code é poderoso. O GSD o torna confiável.**
+**Claude Code é poderoso. GSD Core o torna confiável.**
diff --git a/README.zh-CN.md b/README.zh-CN.md
index e106fb14d..7e2831c54 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,5 +1,3 @@
-> ⚠️ This is an active fork. See the [English README](README.md) for the full notice about the original repo.
-
# GSD Core
@@ -8,9 +6,7 @@
[English](README.md) · [Português](README.pt-BR.md) · **简体中文** · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md)
-**一个轻量但强大的元提示、上下文工程与规格驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、CodeBuddy 和 Cline。**
-
-**它解决的是 context rot：随着 Claude 的上下文窗口被填满，输出质量逐步劣化的问题。**
+**一套轻量级的元提示、上下文工程与规范驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等 AI 编程工具。**
[](https://www.npmjs.com/package/@opengsd/gsd-core)
[](https://www.npmjs.com/package/@opengsd/gsd-core)
@@ -19,72 +15,25 @@
[](https://github.com/open-gsd/gsd-core)
[](LICENSE)
-
-
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**支持 Mac、Windows 和 Linux。**
-
-
-
-
-
-
-
-*"只要你清楚自己想要什么，它就真的能给你做出来。不扯淡。"*
-
-*"我试过 SpecKit、OpenSpec 和 Taskmaster，这套东西目前给我的结果最好。"*
-
-*"这是我给 Claude Code 加过最强的增强。没有过度设计，是真的把事做完。"*
-
-
-
-**已被 Amazon、Google、Shopify 和 Webflow 的工程师采用。**
-
-[我为什么做这个](#我为什么做这个) · [它是怎么工作的](#它是怎么工作的) · [命令](#命令) · [为什么它有效](#为什么它有效) · [用户指南](docs/USER-GUIDE.md)
-
---
-## 我为什么做这个
+## 什么是 GSD Core
-我是独立开发者。我不写代码，Claude Code 写。
-
-市面上已经有其他规格驱动开发工具，比如 BMAD、Speckit……但它们要么把事情搞得比必要的复杂得多了些（冲刺仪式、故事点、利益相关方同步、复盘、Jira 流程），要么根本缺少对你到底在构建什么的整体理解。我不是一家 50 人的软件公司。我不想演企业流程。我只是个想把好东西真正做出来的创作者。
-
-所以我做了 GSD。复杂性在系统内部，不在你的工作流里。幕后是上下文工程、XML 提示格式、子代理编排、状态管理；你看到的是几个真能工作的命令。
-
-这套系统会把 Claude 完成工作 *以及* 验证结果所需的一切上下文都准备好。我信任这个工作流，因为它确实能把事情做好。
-
-这就是它。没有企业角色扮演式的废话，只有一套非常有效、能让你持续用 Claude Code 构建酷东西的系统。
-
-— **TÂCHES**
+GSD Core 是一套上下文工程与规范驱动开发框架，能够引导 AI 编程智能体（Claude Code、Codex、Gemini CLI、Copilot、Cursor 等）按照严格的阶段循环推进工作。它解决了[上下文腐化](docs/zh-CN/explanation/context-engineering.md)问题——即随着 AI 填满上下文窗口而逐渐累积的质量下降——通过在全新上下文的子智能体中运行所有繁重的研究、规划和执行工作，同时保持主会话的精简。
---
-Vibecoding 的名声不算好。你描述需求，AI 生成代码，结果往往是质量不稳定、规模一上来就散架的垃圾。
+## 工作原理
-GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文工程层。你只要描述想法，系统会自动提取它需要知道的一切，然后让 Claude Code 去干活。
+每个里程碑重复相同的五步循环，每次推进一个阶段：
----
-
-## 适合谁用
-
-适合那些想把自己的需求说明白，然后让系统正确构建出来的人，而不是假装自己在运营一个 50 人工程组织的人。
-
-### 功能亮点
-
-规范版本以 npm 上发布的 `@opengsd/gsd-core` 版本以及 `package.json` 为准。`docs/` 中旧的发行说明文件仅作为连续性历史保留；不要把归档编号当作当前 GSD Core 包版本。
-
-- **`--minimal` 安装档** — 别名 `--core-only`。仅安装主循环的 6 个核心技能（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`），不安装任何 `gsd-*` 子代理。将冷启动系统提示开销从 ~12k token 降至 ~700 token（≥94% 减少）。适合 32K–128K 上下文的本地 LLM 和按 token 计费的 API。
-- **`/gsd-phase --edit`** — 就地修改 `ROADMAP.md` 中已有阶段的任意字段，不改变其编号或位置。`--force` 跳过确认 diff，验证 `depends_on` 引用，并在写入时更新 `STATE.md`。
-- **合并后构建与测试门** — `execute-phase` 步骤 5.6 优先自动检测 `workflow.build_command` 配置，否则按 Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm 顺序回退。Xcode/iOS 项目自动运行 `xcodebuild build` 和 `xcodebuild test`。在并行与串行模式下均生效。
-- **每运行时评审模型选择** — `review.models.` 让每个外部评审 CLI（codex、gemini 等）独立于规划/执行档选择自己的模型。
-- **工作流设置继承** — 设置 `GSD_WORKSTREAM` 后，先加载根 `.planning/config.json`，再与该工作流的配置进行深合并（冲突时工作流优先）。工作流配置中显式 `null` 会覆盖根值。
-- **技能整合：86 → 59** — 4 个新分组技能（`capture`、`phase`、`config`、`workspace`）吸收了 31 个微技能。6 个已有父技能将收尾与子操作合并为标志：`update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`。功能无损失。
+1. **讨论（Discuss）** — 在规划任何内容之前，先捕获实现决策
+2. **规划（Plan）** — 研究、分解，并验证计划能够适配全新的上下文窗口
+3. **执行（Execute）** — 以并行波次运行计划；每个执行器以干净的 20 万 token 上下文启动
+4. **验证（Verify）** — 检查已构建的内容；在宣告完成前诊断并修复问题
+5. **交付（Ship）** — 创建 PR，归档阶段，对下一个阶段重复上述流程
---
@@ -94,727 +43,60 @@ GSD 解决的就是这个问题。它是让 Claude Code 变得可靠的上下文
npx @opengsd/gsd-core@latest
```
-安装器会提示你选择：
-1. **运行时**：Claude Code、OpenCode、Gemini、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、CodeBuddy、Cline，或全部
-2. **安装位置**：全局（所有项目）或本地（仅当前项目）
+安装程序会提示选择运行时（Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等）以及是全局安装还是本地安装。跨运行时兼容性需要使用安装程序——请勿直接从 `agents/` 或 `commands/` 目录复制文件。
-安装后可这样验证：
-- Claude Code / Gemini / Copilot / Antigravity：`/gsd-help`
-- OpenCode / Kilo / Augment / Trae / CodeBuddy：`/gsd-help`
-- Codex：`$gsd-help`
-- Cline：GSD 通过 `.clinerules` 安装 — 检查 `.clinerules` 是否存在
+使用其他运行时或没有 Node.js？请参阅[在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)。
-> [!NOTE]
-> Claude Code 2.1.88+ 和 Codex 以 skill 形式安装（`skills/gsd-*/SKILL.md`）。Cline 使用 `.clinerules`。安装器会自动处理所有格式。
-
-> [!TIP]
-> 基于源码安装或无法使用 npm 的环境，请参阅 **[docs/manual-update.md](docs/manual-update.md)**。
-
-### 保持更新
-
-GSD 迭代很快，建议定期更新：
+安装完成后，启动你的第一个项目：
```bash
-npx @opengsd/gsd-core@latest
-```
-
-
-非交互式安装（Docker、CI、脚本）
-
-```bash
-# Claude Code
-npx @opengsd/gsd-core --claude --global # 安装到 ~/.claude/
-npx @opengsd/gsd-core --claude --local # 安装到 ./.claude/
-
-# OpenCode
-npx @opengsd/gsd-core --opencode --global # 安装到 ~/.config/opencode/
-
-# Gemini CLI
-npx @opengsd/gsd-core --gemini --global # 安装到 ~/.gemini/
-
-# Kilo
-npx @opengsd/gsd-core --kilo --global # 安装到 ~/.config/kilo/
-npx @opengsd/gsd-core --kilo --local # 安装到 ./.kilo/
-
-# Codex
-npx @opengsd/gsd-core --codex --global # 安装到 ~/.codex/
-npx @opengsd/gsd-core --codex --local # 安装到 ./.codex/
-
-# Copilot
-npx @opengsd/gsd-core --copilot --global # 安装到 ~/.github/
-npx @opengsd/gsd-core --copilot --local # 安装到 ./.github/
-
-# Cursor CLI
-npx @opengsd/gsd-core --cursor --global # 安装到 ~/.cursor/
-npx @opengsd/gsd-core --cursor --local # 安装到 ./.cursor/
-
-# Antigravity
-npx @opengsd/gsd-core --antigravity --global # 安装到 ~/.gemini/antigravity/
-npx @opengsd/gsd-core --antigravity --local # 安装到 ./.agent/
-
-# Augment
-npx @opengsd/gsd-core --augment --global # 安装到 ~/.augment/
-npx @opengsd/gsd-core --augment --local # 安装到 ./.augment/
-
-# Trae
-npx @opengsd/gsd-core --trae --global # 安装到 ~/.trae/
-npx @opengsd/gsd-core --trae --local # 安装到 ./.trae/
-
-# CodeBuddy
-npx @opengsd/gsd-core --codebuddy --global # 安装到 ~/.codebuddy/
-npx @opengsd/gsd-core --codebuddy --local # 安装到 ./.codebuddy/
-
-# Cline
-npx @opengsd/gsd-core --cline --global # 安装到 ~/.cline/
-npx @opengsd/gsd-core --cline --local # 安装到 ./.clinerules
-
-# 所有运行时
-npx @opengsd/gsd-core --all --global # 安装到所有目录
-```
-
-使用 `--global`（`-g`）或 `--local`（`-l`）可以跳过安装位置提示。
-使用 `--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--cursor`、`--windsurf`、`--antigravity`、`--augment`、`--trae`、`--codebuddy`、`--cline` 或 `--all` 可以跳过运行时提示。
-
-
-
-
-开发安装
-
-克隆仓库并在本地运行安装器：
-
-```bash
-git clone https://github.com/open-gsd/gsd-core.git
-cd gsd-core
-node bin/install.js --claude --local
-```
-
-这样会安装到 `./.claude/`，方便你在贡献代码前测试自己的改动。
-
-
-
-### 推荐：跳过权限确认模式
-
-GSD 的设计目标是无摩擦自动化。运行 Claude Code 时建议使用：
-
-```bash
-claude --dangerously-skip-permissions
-```
-
-> [!TIP]
-> 这才是 GSD 的预期用法。连 `date` 和 `git commit` 都要来回确认 50 次，整个体验就废了。
-
-
-替代方案：细粒度权限
-
-如果你不想使用这个 flag，可以在项目的 `.claude/settings.json` 中加入：
-
-```json
-{
- "permissions": {
- "allow": [
- "Bash(date:*)",
- "Bash(echo:*)",
- "Bash(cat:*)",
- "Bash(ls:*)",
- "Bash(mkdir:*)",
- "Bash(wc:*)",
- "Bash(head:*)",
- "Bash(tail:*)",
- "Bash(sort:*)",
- "Bash(grep:*)",
- "Bash(tr:*)",
- "Bash(git add:*)",
- "Bash(git commit:*)",
- "Bash(git status:*)",
- "Bash(git log:*)",
- "Bash(git diff:*)",
- "Bash(git tag:*)"
- ]
- }
-}
-```
-
-
-
----
-
-## 它是怎么工作的
-
-> **已经有现成代码库？** 先运行 `/gsd-map-codebase`。它会并行拉起多个代理分析你的技术栈、架构、约定和风险点。之后 `/gsd-new-project` 就会真正“理解”你的代码库，提问会聚焦在你打算新增的部分，规划时也会自动加载你的现有模式。
-
-### 1. 初始化项目
-
-```
/gsd-new-project
```
-一个命令，一条完整流程。系统会：
-
-1. **提问**：一直问到它彻底理解你的想法（目标、约束、技术偏好、边界情况）
-2. **研究**：并行拉起代理调研领域知识（可选，但强烈建议）
-3. **需求梳理**：提取哪些属于 v1、v2，哪些不在范围内
-4. **路线图**：创建与需求映射的阶段规划
-
-你审核并批准路线图后，就可以开始构建。
-
-**生成：** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`.planning/research/`
+初次使用？请按照[你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)进行引导式操作，从安装到完成第一个交付阶段。
---
-### 2. 讨论阶段
+## 文档
-```
-/gsd-discuss-phase 1
-```
+**教程** — 边做边学：
+- [你的第一个项目](docs/zh-CN/tutorials/your-first-project.md)
+- [接入现有代码库](docs/zh-CN/tutorials/onboarding-an-existing-codebase.md)
-**这是你塑造实现方式的地方。**
+**操作指南** — 面向任务的实用方法：
+- [在你的运行时上安装](docs/zh-CN/how-to/install-on-your-runtime.md)
+- [规划一个阶段](docs/zh-CN/how-to/plan-a-phase.md)
+- [验证与交付](docs/zh-CN/how-to/verify-and-ship.md)
+- … [查看所有操作指南](docs/zh-CN/README.md#how-to-guides)
-你的路线图里，每个阶段通常只有一两句话。这点信息不足以让系统按 *你脑中的样子* 把东西做出来。这一步的作用，就是在研究和规划之前，把你的偏好先收进去。
+**参考文档** — 权威信息：
+- [命令](docs/zh-CN/COMMANDS.md)
+- [配置](docs/zh-CN/CONFIGURATION.md)
+- [CLI 工具](docs/zh-CN/CLI-TOOLS.md)
-系统会分析该阶段，并根据要构建的内容识别灰区：
+**概念说明** — 设计理念与决策：
+- [上下文工程](docs/zh-CN/explanation/context-engineering.md)
+- [阶段循环](docs/zh-CN/explanation/the-phase-loop.md)
+- [架构](docs/zh-CN/ARCHITECTURE.md)
-- **视觉功能**：布局、信息密度、交互、空状态
-- **API / CLI**：返回格式、flags、错误处理、详细程度
-- **内容系统**：结构、语气、深度、流转方式
-- **组织型任务**：分组标准、命名、去重、例外情况
-
-对每个你选择的区域，系统都会持续追问，直到你满意为止。最终产物 `CONTEXT.md` 会直接喂给后续两个步骤：
-
-1. **研究代理会读取它**：知道该研究哪些模式（例如“用户想要卡片布局” → 去研究卡片组件库）
-2. **规划代理会读取它**：知道哪些决策已经锁定（例如“已决定使用无限滚动” → 计划里就会包含滚动处理）
-
-你在这里给出的信息越具体，系统越能构建出你真正想要的东西。跳过它，你拿到的是合理默认值；用好它，你拿到的是 *你的* 方案。
-
-**生成：** `{phase_num}-CONTEXT.md`
+完整索引：[docs/zh-CN/README.md](docs/zh-CN/README.md)。其他语言：[日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) · [Português](README.pt-BR.md) · [English](README.md)。
---
-### 3. 规划阶段
+## 为什么有效
-```
-/gsd-plan-phase 1
-```
+大多数 AI 编程方案在规模化时都会失败，原因在于上下文膨胀会悄无声息地降低输出质量，各会话之间没有共享记忆，也没有任何机制来验证代码是否真正可用。GSD Core 解决了这三个问题：繁重的工作在全新的子智能体中运行，`STATE.md` 和 `CONTEXT.md` 等结构化工件能够跨越会话边界保持存续，验证步骤会检查已构建的内容并在宣告阶段完成前生成修复计划。完整的设计思路请参阅 [docs/zh-CN/explanation/context-engineering.md](docs/zh-CN/explanation/context-engineering.md)。
-系统会：
-
-1. **研究**：结合你的 `CONTEXT.md` 决策，调研这一阶段该怎么实现
-2. **制定计划**：创建 2-3 份原子化任务计划，使用 XML 结构
-3. **验证**：将计划与需求对照检查，直到通过为止
-
-每份计划都足够小，可以在一个全新的上下文窗口里执行。没有质量衰减，也不会出现“我接下来会更简洁一些”的退化状态。
-
-**生成：** `{phase_num}-RESEARCH.md`、`{phase_num}-{N}-PLAN.md`
+遇到问题？请参阅 [docs/zh-CN/how-to/recover-and-troubleshoot.md](docs/zh-CN/how-to/recover-and-troubleshoot.md)。
---
-### 4. 执行阶段
+## 社区
-```
-/gsd-execute-phase 1
-```
-
-系统会：
-
-1. **按 wave 执行计划**：能并行的并行，有依赖的顺序执行
-2. **每个计划使用新上下文**：20 万 token 纯用于实现，零历史垃圾
-3. **每个任务单独提交**：每项任务都有自己的原子提交
-4. **对照目标验证**：检查代码库是否真的交付了该阶段承诺的内容
-
-你可以离开，回来时看到的是已经完成的工作和干净的 git 历史。
-
-**Wave 执行方式：**
-
-计划会根据依赖关系被分组为不同的 “wave”。同一 wave 内并行执行，不同 wave 之间顺序推进。
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│ PHASE EXECUTION │
-├─────────────────────────────────────────────────────────────────────┤
-│ │
-│ WAVE 1 (parallel) WAVE 2 (parallel) WAVE 3 │
-│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
-│ │ Plan 01 │ │ Plan 02 │ → │ Plan 03 │ │ Plan 04 │ → │ Plan 05 │ │
-│ │ │ │ │ │ │ │ │ │ │ │
-│ │ User │ │ Product │ │ Orders │ │ Cart │ │ Checkout│ │
-│ │ Model │ │ Model │ │ API │ │ API │ │ UI │ │
-│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
-│ │ │ ↑ ↑ ↑ │
-│ └───────────┴──────────────┴───────────┘ │ │
-│ Dependencies: Plan 03 needs Plan 01 │ │
-│ Plan 04 needs Plan 02 │ │
-│ Plan 05 needs Plans 03 + 04 │ │
-│ │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**为什么 wave 很重要：**
-- 独立计划 → 同一 wave → 并行执行
-- 依赖计划 → 更晚的 wave → 等依赖完成
-- 文件冲突 → 顺序执行，或合并到同一个计划里
-
-这也是为什么“垂直切片”（Plan 01：端到端完成用户功能）比“水平分层”（Plan 01：所有 model，Plan 02：所有 API）更容易并行化。
-
-**生成：** `{phase_num}-{N}-SUMMARY.md`、`{phase_num}-VERIFICATION.md`
-
----
-
-### 5. 验证工作
-
-```
-/gsd-verify-work 1
-```
-
-**这是你确认它是否真的可用的地方。**
-
-自动化验证能检查代码存在、测试通过。但这个功能是否真的按你的预期工作？这一步就是让你亲自用。
-
-系统会：
-
-1. **提取可测试的交付项**：你现在应该能做到什么
-2. **逐项带你验证**：“能否用邮箱登录？” 可以 / 不可以，或者描述哪里不对
-3. **自动诊断失败**：拉起 debug 代理定位根因
-4. **创建验证过的修复计划**：可立刻重新执行
-
-如果一切通过，就进入下一步；如果哪里坏了，你不需要手动 debug，只要重新运行 `/gsd-execute-phase`，执行它自动生成的修复计划即可。
-
-**生成：** `{phase_num}-UAT.md`，以及发现问题时的修复计划
-
----
-
-### 6. 重复 → 发布 → 完成 → 下一个里程碑
-
-```
-/gsd-discuss-phase 2
-/gsd-plan-phase 2
-/gsd-execute-phase 2
-/gsd-verify-work 2
-/gsd-ship 2 # 从已验证的工作创建 PR
-...
-/gsd-complete-milestone
-/gsd-new-milestone
-```
-
-或者让 GSD 自动判断下一步：
-
-```
-/gsd-progress --next # 自动检测并执行下一步
-```
-
-循环执行 **讨论 → 规划 → 执行 → 验证 → 发布**，直到整个里程碑完成。
-
-如果你希望在讨论阶段更快收集信息，可以用 `/gsd-discuss-phase --batch`，一次回答一小组问题，而不是逐个问答。
-
-每个阶段都会得到你的输入（discuss）、充分研究（plan）、干净执行（execute）和人工验证（verify）。上下文始终保持新鲜，质量也能持续稳定。
-
-当所有阶段完成后，`/gsd-complete-milestone` 会归档当前里程碑并打 release tag。
-
-接着用 `/gsd-new-milestone` 开启下一个版本。它和 `new-project` 流程相同，只是面向你现有的代码库。你描述下一步想构建什么，系统研究领域、梳理需求，再产出新的路线图。每个里程碑都是一个干净周期：定义 → 构建 → 发布。
-
----
-
-### 快速模式
-
-```
-/gsd-quick
-```
-
-**适用于不需要完整规划的临时任务。**
-
-快速模式保留 GSD 的核心保障（原子提交、状态跟踪），但路径更短：
-
-- **相同的代理体系**：同样是 planner + executor，质量不降
-- **跳过可选步骤**：默认不启用 research、plan checker、verifier
-- **独立跟踪**：数据存放在 `.planning/quick/`，不和 phase 混在一起
-
-**`--discuss` 参数：** 在规划前先进行轻量讨论，理清灰区。
-
-**`--research` 参数：** 在规划前拉起研究代理。调查实现方式、库选型和潜在坑点。适合你不确定怎么下手的场景。
-
-**`--full` 参数：** 启用计划检查（最多 2 轮迭代）和执行后验证。
-
-参数可组合使用：`--discuss --research --full` 可同时获得讨论 + 研究 + 计划检查 + 验证。
-
-```
-/gsd-quick
-> What do you want to do? "Add dark mode toggle to settings"
-```
-
-**生成：** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`、`SUMMARY.md`
-
----
-
-## 为什么它有效
-
-### 上下文工程
-
-Claude Code 非常强大，前提是你把它需要的上下文给对。大多数人做不到。
-
-GSD 会替你处理：
-
-| 文件 | 作用 |
-|------|------|
-| `PROJECT.md` | 项目愿景，始终加载 |
-| `research/` | 生态知识（技术栈、功能、架构、坑点） |
-| `REQUIREMENTS.md` | 带 phase 可追踪性的 v1/v2 范围定义 |
-| `ROADMAP.md` | 你要去哪里、哪些已经完成 |
-| `STATE.md` | 决策、阻塞、当前位置，跨会话记忆 |
-| `PLAN.md` | 带 XML 结构和验证步骤的原子任务 |
-| `SUMMARY.md` | 做了什么、改了什么、已写入历史 |
-| `todos/` | 留待后续处理的想法和任务 |
-
-这些尺寸限制都是基于 Claude 在何处开始质量退化得出的。控制在阈值内，输出才能持续稳定。
-
-### XML 提示格式
-
-每个计划都会使用为 Claude 优化过的结构化 XML：
-
-```xml
-
- Create login endpoint
- src/app/api/auth/login/route.ts
-
- Use jose for JWT (not jsonwebtoken - CommonJS issues).
- Validate credentials against users table.
- Return httpOnly cookie on success.
-
- curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie
- Valid credentials return cookie, invalid return 401
-
-```
-
-指令足够精确，不需要猜。验证也内建在计划里。
-
-### 多代理编排
-
-每个阶段都遵循同一种模式：一个轻量 orchestrator 拉起专用代理、汇总结果，再路由到下一步。
-
-| 阶段 | Orchestrator 做什么 | Agents 做什么 |
-|------|---------------------|---------------|
-| 研究 | 协调与展示研究结果 | 4 个并行研究代理分别调查技术栈、功能、架构、坑点 |
-| 规划 | 校验并管理迭代 | Planner 生成计划，checker 验证，循环直到通过 |
-| 执行 | 按 wave 分组并跟踪进度 | Executors 并行实现，每个都有全新的 20 万上下文 |
-| 验证 | 呈现结果并决定下一步 | Verifier 对照目标检查代码库，debuggers 诊断失败 |
-
-Orchestrator 本身不做重活，只负责拉代理、等待、整合结果。
-
-**最终效果：** 你可以在一个阶段里完成深度研究、生成并验证多个计划、让多个执行代理并行写下成千上万行代码，再自动对照目标验证，而主上下文窗口依然能维持在 30-40% 左右。真正的工作都发生在新鲜的子代理上下文里，所以你的主会话始终保持快速、响应稳定。
-
-### 原子 Git 提交
-
-每个任务完成后都会立刻生成独立提交：
-
-```bash
-abc123f docs(08-02): complete user registration plan
-def456g feat(08-02): add email confirmation flow
-hij789k feat(08-02): implement password hashing
-lmn012o feat(08-02): create registration endpoint
-```
-
-> [!NOTE]
-> **好处：** `git bisect` 能精准定位是哪项任务引入故障；每个任务都可单独回滚；未来 Claude 读取历史时也更清晰；整个 AI 自动化工作流的可观测性更好。
-
-每个 commit 都是外科手术式的：精确、可追踪、有意义。
-
-### 模块化设计
-
-- 给当前里程碑追加 phase
-- 在 phase 之间插入紧急工作
-- 完成当前里程碑后开启新的周期
-- 在不推倒重来的前提下调整计划
-
-你不会被这套系统绑死，它会随着项目变化而调整。
-
----
-
-## 命令
-
-### 核心工作流
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-new-project [--auto]` | 完整初始化：提问 → 研究 → 需求 → 路线图 |
-| `/gsd-discuss-phase [N] [--auto] [--analyze]` | 在规划前收集实现决策（`--analyze` 增加权衡分析） |
-| `/gsd-plan-phase [N] [--auto] [--reviews]` | 为某个阶段执行研究 + 规划 + 验证（`--reviews` 加载代码库审查结果） |
-| `/gsd-execute-phase ` | 以并行 wave 执行全部计划，完成后验证 |
-| `/gsd-verify-work [N]` | 人工用户验收测试 ¹ |
-| `/gsd-ship [N] [--draft]` | 从已验证的阶段工作创建 PR，自动生成 PR 描述 |
-| `/gsd-fast ` | 内联处理琐碎任务——完全跳过规划，立即执行 |
-| `/gsd-progress --next` | 自动推进到下一个逻辑工作流步骤 |
-| `/gsd-audit-milestone` | 验证里程碑是否达到完成定义 |
-| `/gsd-complete-milestone` | 归档里程碑并打 release tag |
-| `/gsd-new-milestone [name]` | 开始下一个版本：提问 → 研究 → 需求 → 路线图 |
-| `/gsd-milestone-summary` | 从已完成的里程碑产物生成项目概览，用于团队上手 |
-| `/gsd-forensics` | 对失败或卡住的工作流进行事后调查 |
-
-### 工作流（Workstreams）
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-workstreams list` | 显示所有工作流及其状态 |
-| `/gsd-workstreams create ` | 创建命名空间工作流，用于并行里程碑工作 |
-| `/gsd-workstreams switch ` | 切换当前活跃工作流 |
-| `/gsd-workstreams complete ` | 完成并合并工作流 |
-
-### 多项目工作区
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-workspace --new` | 创建隔离工作区，包含仓库副本（worktree 或 clone） |
-| `/gsd-workspace --list` | 显示所有 GSD 工作区及其状态 |
-| `/gsd-workspace --remove` | 移除工作区并清理 worktree |
-
-### UI 设计
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-ui-phase [N]` | 为前端阶段生成 UI 设计合约（UI-SPEC.md） |
-| `/gsd-ui-review [N]` | 对已实现前端代码进行 6 维视觉审计 |
-
-### 导航
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-progress` | 我现在在哪？下一步是什么？ |
-| `/gsd-progress --next` | 自动检测状态并执行下一步 |
-| `/gsd-help` | 显示全部命令和使用指南 |
-| `/gsd-update` | 更新 GSD，并预览变更日志 |
-
-### Brownfield
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-map-codebase` | 在 `new-project` 前分析现有代码库 |
-
-### 阶段管理
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-phase` | 在路线图末尾追加 phase |
-| `/gsd-phase --insert [N]` | 在 phase 之间插入紧急工作 |
-| `/gsd-phase --edit [N] [--force]` | 就地修改已有 phase 的任意字段 — 编号与位置保持不变 |
-| `/gsd-phase --remove [N]` | 删除未来 phase，并重编号 |
-| `/gsd-discuss-phase --assumptions [N]` | 在规划前查看 Claude 打算采用的方案 |
-| `/gsd-audit-milestone --fix` | 为 audit 发现的缺口创建 phase |
-
-### 代码质量
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-review` | 对当前阶段或分支进行跨 AI 同行评审 |
-| `/gsd-pr-branch` | 创建过滤 `.planning/` 提交的干净 PR 分支 |
-| `/gsd-audit-uat` | 审计验证债务——找出缺少 UAT 的阶段 |
-
-### 积压
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-capture --seed ` | 将想法存入积压停车场，留待未来里程碑 |
-
-### 会话
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-pause-work` | 在中途暂停时创建交接上下文（写入 HANDOFF.json） |
-| `/gsd-resume-work` | 从上一次会话恢复 |
-| `/gsd-pause-work --report` | 生成会话摘要，包含已完成工作和结果 |
-
-### 工具
-
-| 命令 | 作用 |
-|------|------|
-| `/gsd-settings` | 配置模型 profile 和工作流代理 |
-| `/gsd-config --profile ` | 切换模型 profile（quality / balanced / budget / inherit） |
-| `/gsd-capture [desc]` | 记录一个待办想法 |
-| `/gsd-capture --list` | 查看待办列表 |
-| `/gsd-debug [desc]` | 使用持久状态进行系统化调试 |
-| `/gsd-do ` | 将自由文本自动路由到正确的 GSD 命令 |
-| `/gsd-note ` | 零摩擦想法捕捉——追加、列出或提升为待办 |
-| `/gsd-quick [--full] [--discuss] [--research]` | 以 GSD 保障执行临时任务（`--full` 增加计划检查和验证，`--discuss` 先补上下文，`--research` 在规划前先调研） |
-| `/gsd-health [--repair]` | 校验 `.planning/` 目录完整性，带 `--repair` 时自动修复 |
-| `/gsd-stats` | 显示项目统计——阶段、计划、需求、git 指标 |
-| `/gsd-profile-user [--questionnaire] [--refresh]` | 从会话分析生成开发者行为档案，用于个性化响应 |
-
-¹ 由 reddit 用户 OracleGreyBeard 贡献
-
----
-
-## 配置
-
-GSD 将项目设置保存在 `.planning/config.json`。你可以在 `/gsd-new-project` 时配置，也可以稍后通过 `/gsd-settings` 修改。完整的配置 schema、工作流开关、git branching 选项以及各代理的模型分配，请查看[用户指南](docs/USER-GUIDE.md#configuration-reference)。
-
-### 核心设置
-
-| Setting | Options | Default | 作用 |
-|---------|---------|---------|------|
-| `mode` | `yolo`, `interactive` | `interactive` | 自动批准，还是每一步确认 |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | phase 粒度，也就是范围切分得多细 |
-
-### 模型 Profile
-
-控制各代理使用哪种 Claude 模型，在质量和 token 成本之间平衡。
-
-| Profile | Planning | Execution | Verification |
-|---------|----------|-----------|--------------|
-| `quality` | Opus | Opus | Sonnet |
-| `balanced`（默认） | Opus | Sonnet | Sonnet |
-| `budget` | Sonnet | Sonnet | Haiku |
-| `inherit` | Inherit | Inherit | Inherit |
-
-切换方式：
-```
-/gsd-config --profile budget
-```
-
-使用非 Anthropic 提供商（OpenRouter、本地模型）时，或想跟随当前运行时的模型选择时（如 OpenCode 的 `/model`），可用 `inherit`。
-
-也可以通过 `/gsd-settings` 配置。
-
-### 工作流代理
-
-这些设置会在规划或执行时拉起额外代理。它们能提升质量，但也会增加 token 消耗和耗时。
-
-| Setting | Default | 作用 |
-|---------|---------|------|
-| `workflow.research` | `true` | 每个 phase 规划前先调研领域知识 |
-| `workflow.plan_check` | `true` | 执行前验证计划是否真能达成阶段目标 |
-| `workflow.verifier` | `true` | 执行后确认“必须交付项”是否已经落地 |
-| `workflow.auto_advance` | `false` | 自动串联 discuss → plan → execute，不中途停下 |
-| `workflow.research_before_questions` | `false` | 在讨论提问前先运行研究，而非之后 |
-| `workflow.skip_discuss` | `false` | 在自主模式下完全跳过讨论阶段 |
-| `workflow.discuss_mode` | `null` | 控制讨论阶段行为（`assumptions` 使用推断默认值） |
-
-可以用 `/gsd-settings` 开关这些项，也可以在单次命令里覆盖：
-- `/gsd-plan-phase --skip-research`
-- `/gsd-plan-phase --skip-verify`
-
-### 执行
-
-| Setting | Default | 作用 |
-|---------|---------|------|
-| `parallelization.enabled` | `true` | 是否并行执行独立计划 |
-| `planning.commit_docs` | `true` | 是否将 `.planning/` 纳入 git 跟踪 |
-| `hooks.context_warnings` | `true` | 显示上下文窗口使用量警告 |
-
-### Git 分支策略
-
-控制 GSD 在执行过程中如何处理分支。
-
-| Setting | Options | Default | 作用 |
-|---------|---------|---------|------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | 分支创建策略 |
-| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | phase 分支模板 |
-| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | milestone 分支模板 |
-
-**策略说明：**
-- **`none`**：直接提交到当前分支（GSD 默认行为）
-- **`phase`**：每个 phase 创建一个分支，在 phase 完成时合并
-- **`milestone`**：整个里程碑只用一个分支，在里程碑完成时合并
-
-在里程碑完成时，GSD 会提供 squash merge（推荐）或保留历史的 merge 选项。
-
----
-
-## 安全
-
-### 保护敏感文件
-
-GSD 的代码库映射和分析命令会读取文件来理解你的项目。**包含机密信息的文件应当加入 Claude Code 的 deny list**：
-
-1. 打开 Claude Code 设置（项目级 `.claude/settings.json` 或全局设置）
-2. 把敏感文件模式加入 deny list：
-
-```json
-{
- "permissions": {
- "deny": [
- "Read(.env)",
- "Read(.env.*)",
- "Read(**/secrets/*)",
- "Read(**/*credential*)",
- "Read(**/*.pem)",
- "Read(**/*.key)"
- ]
- }
-}
-```
-
-这样无论你运行什么命令，Claude 都无法读取这些文件。
-
-> [!IMPORTANT]
-> GSD 内建了防止提交 secrets 的保护，但纵深防御依然是最佳实践。第一道防线应该是直接禁止读取敏感文件。
-
----
-
-## 故障排查
-
-**安装后找不到命令？**
-- 重启你的运行时，让命令或 skills 重新加载
-- 检查文件是否存在于 `~/.claude/commands/gsd/`（全局）或 `./.claude/commands/gsd/`（本地）
-- 对 Codex，检查 skills 是否存在于 `~/.codex/skills/gsd-*/SKILL.md`（全局）或 `./.codex/skills/gsd-*/SKILL.md`（本地）
-
-**命令行为不符合预期？**
-- 运行 `/gsd-help` 确认安装成功
-- 重新执行 `npx @opengsd/gsd-core` 进行重装
-
-**想更新到最新版本？**
-```bash
-npx @opengsd/gsd-core@latest
-```
-
-**在 Docker 或容器环境中使用？**
-
-如果使用波浪线路径（`~/.claude/...`）时读取失败，请在安装前设置 `CLAUDE_CONFIG_DIR`：
-```bash
-CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @opengsd/gsd-core --global
-```
-这样可以确保使用绝对路径，而不是在容器里可能无法正确展开的 `~`。
-
-### 卸载
-
-如果你想彻底移除 GSD：
-
-```bash
-# 全局安装
-npx @opengsd/gsd-core --claude --global --uninstall
-npx @opengsd/gsd-core --opencode --global --uninstall
-npx @opengsd/gsd-core --gemini --global --uninstall
-npx @opengsd/gsd-core --kilo --global --uninstall
-npx @opengsd/gsd-core --codex --global --uninstall
-npx @opengsd/gsd-core --copilot --global --uninstall
-npx @opengsd/gsd-core --cursor --global --uninstall
-npx @opengsd/gsd-core --antigravity --global --uninstall
-npx @opengsd/gsd-core --augment --global --uninstall
-npx @opengsd/gsd-core --trae --global --uninstall
-npx @opengsd/gsd-core --cline --global --uninstall
-
-# 本地安装（当前项目）
-npx @opengsd/gsd-core --claude --local --uninstall
-npx @opengsd/gsd-core --opencode --local --uninstall
-npx @opengsd/gsd-core --gemini --local --uninstall
-npx @opengsd/gsd-core --kilo --local --uninstall
-npx @opengsd/gsd-core --codex --local --uninstall
-npx @opengsd/gsd-core --copilot --local --uninstall
-npx @opengsd/gsd-core --cursor --local --uninstall
-npx @opengsd/gsd-core --antigravity --local --uninstall
-npx @opengsd/gsd-core --augment --local --uninstall
-npx @opengsd/gsd-core --trae --local --uninstall
-npx @opengsd/gsd-core --cline --local --uninstall
-```
-
-这会移除所有 GSD 命令、代理、hooks 和设置，但会保留你其他配置。
-
----
-
-## 社区移植版本
-
-OpenCode、Gemini CLI、Kilo 和 Codex 现在都已经通过 `npx @opengsd/gsd-core` 获得原生支持。
-
-这些社区移植版本曾率先探索多运行时支持：
-
-| Project | Platform | Description |
-|---------|----------|-------------|
-| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | 最初的 OpenCode 适配版本 |
-| gsd-gemini (archived) | Gemini CLI | uberfuzzy 制作的最初 Gemini 适配版本 |
+| 项目 | 平台 |
+|---------|----------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | 原始 OpenCode 移植版 |
+| [Discord](https://discord.gg/mYgfVNfA2r) | 社区支持 |
---
@@ -830,14 +112,14 @@ OpenCode、Gemini CLI、Kilo 和 Codex 现在都已经通过 `npx @opengsd/gsd-c
---
-## License
+## 许可证
-MIT License。详情见 [LICENSE](LICENSE)。
+MIT 许可证。详情请参阅 [LICENSE](LICENSE)。
---
-**Claude Code 很强，GSD 让它变得可靠。**
+**Claude Code 功能强大。GSD Core 让它更可靠。**
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 361ee7683..a0f9eba18 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -23,8 +23,8 @@
GSD Core is a **meta-prompting framework** that sits between the user and AI coding agents (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). It provides:
-1. **Context engineering** — Structured artifacts that give the AI everything it needs per task
-2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows
+1. **Context engineering** — Structured artifacts that give the AI everything it needs per task (see [Context engineering](explanation/context-engineering.md))
+2. **Multi-agent orchestration** — Thin orchestrators that spawn specialized agents with fresh context windows (see [Multi-agent orchestration](explanation/multi-agent-orchestration.md))
3. **Spec-driven development** — Requirements → research → plans → execution → verification pipeline
4. **State management** — Persistent project memory across sessions and context resets
@@ -700,6 +700,8 @@ The researcher → planner → executor pipeline includes a supply-chain gate ag
### Security Hooks (v1.27)
+For a conceptual overview of how the hook and guard layers fit into the broader security approach, see [Security model](explanation/security-model.md).
+
**Prompt Guard** (`gsd-prompt-guard.js`):
- Triggers on Write/Edit to `.planning/` files
@@ -770,3 +772,12 @@ available. The current source snapshot is 2026-05-11:
5. **Model references** — `inherit` profile lets GSD defer to runtime's model selection
The installer handles all translation at install time. Workflows and agents are written in Claude Code's native format and transformed during deployment.
+
+---
+
+## Related
+
+- [Multi-agent orchestration](explanation/multi-agent-orchestration.md)
+- [Security model](explanation/security-model.md)
+- [CLI tools](CLI-TOOLS.md)
+- [docs index](README.md)
diff --git a/docs/CLI-TOOLS.md b/docs/CLI-TOOLS.md
index 649d87f08..afc5bfa0b 100644
--- a/docs/CLI-TOOLS.md
+++ b/docs/CLI-TOOLS.md
@@ -1,6 +1,6 @@
# GSD CLI Tools Reference
-> Surface-area reference for `get-shit-done/bin/gsd-tools.cjs` (Node CLI). For slash commands and user flows, see [Command Reference](COMMANDS.md).
+> Reference for the `gsd-tools` CLI (`get-shit-done/bin/gsd-tools.cjs`). For slash commands and user flows, see [Command Reference](COMMANDS.md). Return to [docs index](README.md).
---
@@ -493,7 +493,9 @@ API keys configured via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_searc
---
-## See also
+## Related
-- [Architecture](ARCHITECTURE.md) — orchestration and runtime layering
-- [Command Reference](COMMANDS.md) — user-facing `/gsd-` commands
+- [Commands](COMMANDS.md)
+- [Configuration](CONFIGURATION.md)
+- [Architecture](ARCHITECTURE.md)
+- [docs index](README.md)
diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
index 717b9378f..2e02875b5 100644
--- a/docs/COMMANDS.md
+++ b/docs/COMMANDS.md
@@ -1,6 +1,6 @@
# GSD Core Command Reference
-> Command syntax, flags, options, and examples for stable commands. For feature details, see [Feature Reference](FEATURES.md). For workflow walkthroughs, see [User Guide](USER-GUIDE.md).
+> Command reference for GSD Core — syntax, flags, options, and examples for every stable command. For feature details see [Feature Reference](FEATURES.md); for workflow walkthroughs see [User Guide](USER-GUIDE.md); for the docs index see [README](README.md).
---
@@ -144,7 +144,7 @@ Research, plan, and verify a phase.
| `--auto` | Skip interactive confirmations |
| `--research` | Force re-research even if RESEARCH.md exists |
| `--skip-research` | Skip domain research step |
-| `--research-phase ` | Research-only mode: spawn researcher for phase ``, write RESEARCH.md, exit before planner. Replaces the deleted `gsd-research-phase` standalone command (#3042). |
+| `--research-phase ` | Research-only mode: spawn researcher for phase ``, write RESEARCH.md, exit before planner. Supersedes the deleted standalone research command (#3042). |
| `--view` | Research-only modifier: when used with `--research-phase`, print existing RESEARCH.md to stdout and exit (no spawn). |
| `--gaps` | Gap closure mode (reads VERIFICATION.md, skips research) |
| `--skip-verify` | Skip plan checker verification loop |
@@ -453,12 +453,7 @@ Guided MVP planning for a phase — prompts for a user story, runs SPIDR splitti
**Prerequisites:** Phase must already exist in ROADMAP.md (created via `/gsd-new-project`, `/gsd-phase`, or `/gsd-phase --insert`). The command does not create new phases — it converts an existing phase.
-**Process:**
-1. Prompts for "As a / I want to / So that" user story (three structured questions)
-2. Validates story format against the canonical regex
-3. Runs SPIDR splitting check — if the story is too large, walks through Spike/Paths/Interfaces/Data/Rules axes and offers to split into multiple phases
-4. Writes `**Goal:** ` and `**Mode:** mvp` to the phase's ROADMAP.md section (with confirmation gate)
-5. Delegates to `/gsd-plan-phase `, which detects MVP mode automatically
+**Behaviour:** Collects a structured user story, validates format, runs a SPIDR splitting check, writes `**Goal:**` and `**Mode:** mvp` to the phase's ROADMAP.md section, then delegates to `/gsd-plan-phase `. See [How to plan an MVP phase](USER-GUIDE.md#mvp-phase-planning) for a walkthrough.
**Walking Skeleton:** Auto-triggered when `--mvp` (or `mode: mvp`) is used on Phase 1 of a new project with no prior phase summaries. The planner produces `SKELETON.md` alongside `PLAN.md`.
@@ -815,17 +810,12 @@ v1.40.0, [#2792](https://github.com/open-gsd/gsd-core/issues/2792)).
Archive accumulated phase directories from completed milestones and prune local branches whose upstream has been deleted.
+**Behaviour:** Presents a dry-run summary of phase directories to archive (moved from `.planning/phases/` into `.planning/milestones/v{X.Y}-phases/`) and local branches whose upstream is gone (pruned via `git fetch --prune`). Requires confirmation before writing any changes. The currently checked-out branch is never pruned.
+
```bash
/gsd-cleanup
```
-On confirmation, the workflow performs two actions:
-
-1. **Phase archival** — moves phase directories from `.planning/phases/` into milestone archive directories under `.planning/milestones/v{X.Y}-phases/`, using archived ROADMAP snapshots to determine phase membership.
-2. **Branch pruning** — runs `git fetch --prune` to update remote-tracking refs, then identifies and force-deletes local branches whose upstream is marked gone. The currently checked-out branch is always skipped.
-
-The dry-run summary shows both phase directories to archive and candidate local branches for deletion before confirmation.
-
---
## Spiking & Sketching Commands
@@ -1529,3 +1519,12 @@ npm run lint:descriptions
```
The check is also run as part of `npm test` via `tests/enh-2789-description-budget.test.cjs`.
+
+---
+
+## Related
+
+- [Configuration Reference](CONFIGURATION.md)
+- [CLI Tools Reference](CLI-TOOLS.md)
+- [Feature Reference](FEATURES.md)
+- [Docs index](README.md)
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index c8d3651f6..c267d9f5e 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -1,5 +1,7 @@
# GSD Configuration Reference
+Complete schema reference for `.planning/config.json`. For setup walkthroughs and task-oriented guides see the [docs index](README.md).
+
> Full configuration schema, workflow toggles, model profiles, and git branching options. For feature context, see [Feature Reference](FEATURES.md).
---
@@ -332,7 +334,9 @@ Example:
}
```
-### Recommended Presets
+### Common Setting Combinations
+
+The following combinations of `mode`, `granularity`, `model_profile`, and workflow toggles are commonly used together. See [Configure model profiles](how-to/configure-model-profiles.md) for setup guidance.
| Scenario | mode | granularity | profile | research | plan_check | verifier |
|----------|------|-------------|---------|----------|------------|----------|
@@ -380,11 +384,7 @@ The prompt injection guard hook (`gsd-prompt-guard.js`) is always active and can
### Private Planning Setup
-To keep planning artifacts out of git:
-
-1. Set `planning.commit_docs: false` and `planning.search_gitignored: true`
-2. Add `.planning/` to `.gitignore`
-3. If previously tracked: `git rm -r --cached .planning/ && git commit -m "chore: stop tracking planning docs"`
+When `planning.commit_docs` is `false` and `.planning/` is listed in `.gitignore`, GSD treats planning artefacts as local-only. `planning.search_gitignored: true` ensures broad searches still include the `.planning/` directory in this configuration. See [Configure private planning](how-to/configure-model-profiles.md) for setup steps.
---
@@ -486,19 +486,7 @@ The `plan_review.*` namespace controls the plan drift guard, which verifies that
#### Multi-developer setup
-If multiple developers will rebuild the graph in the same repo, run once per
-clone after enabling graphify:
-
-```bash
-graphify hook install
-```
-
-This installs a git merge driver that union-merges concurrent `graph.json`
-writes (no conflict markers in the knowledge graph), plus the post-commit
-rebuild hook. It writes `.gitattributes` and registers `graphify
-merge-driver` in `.git/config`. Solo projects can skip this step; running it
-anyway is harmless. Introduced upstream in graphify v0.7.0 alongside the
-`built_at_commit` freshness signal that `/gsd-graphify status` surfaces.
+When multiple developers rebuild the graph in the same repository, `graphify hook install` (run once per clone) installs a git merge driver that union-merges concurrent `graph.json` writes, eliminating conflict markers. It also registers the post-commit rebuild hook, writes `.gitattributes`, and adds `graphify merge-driver` to `.git/config`. Solo projects may skip this step. Introduced upstream in graphify v0.7.0 alongside the `built_at_commit` freshness signal surfaced by `/gsd-graphify status`.
#### Commit-based staleness
@@ -557,7 +545,7 @@ The `features.*` namespace is a dynamic key pattern — new feature flags can be
| `next_phases` | YAML flow array | Phases the `next_action` applies to (e.g. `["4.5"]`) |
| `progress` | block | Nested `total_phases` / `completed_phases` / `percent` for the milestone progress bar |
-All four fields are **optional and additive** — STATE.md files without them keep rendering exactly as in v1.38.x. See [`STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference, parser constraints, and rendering scenes.
+All four fields are **optional and additive** — STATE.md files without them keep rendering exactly as in v1.38.x. See [STATE.md schema](reference/state-md.md) for the full field reference, parser constraints, and rendering scenes.
---
@@ -1372,3 +1360,12 @@ GSD_AUDIT_ARGS=1 GSD_AUDIT=1 gsd plan --tdd
```
`GSD_AUDIT_ARGS` applies to both the stderr error line and the audit file simultaneously.
+
+---
+
+## Related
+
+- [Commands](COMMANDS.md)
+- [Configure model profiles](how-to/configure-model-profiles.md)
+- [STATE.md schema](reference/state-md.md)
+- [Docs index](README.md)
diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index 8bbbe10f6..da19c092b 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -1,6 +1,6 @@
# GSD Feature Reference
-> Complete feature and function documentation with requirements. For architecture details, see [Architecture](ARCHITECTURE.md). For command syntax, see [Command Reference](COMMANDS.md).
+> Feature index and reference for GSD Core. For architecture details, see [Architecture](ARCHITECTURE.md). For command syntax, see [Command Reference](COMMANDS.md). Return to [docs index](README.md).
---
@@ -2667,7 +2667,7 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style
- REQ-LIFECYCLE-02: `formatGsdState()` checks the lifecycle fields in priority order and emits the first matching scene (Phase active → Idle next-recommended → Milestone complete → Default fallback).
- REQ-LIFECYCLE-03: All four fields default to undefined; existing STATE.md files render byte-for-byte identically.
-**Reference issue:** [#2833](https://github.com/open-gsd/gsd-core/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](STATE-MD-LIFECYCLE.md) for the full field reference and rendering rules.
+**Reference issue:** [#2833](https://github.com/open-gsd/gsd-core/issues/2833) — see [`docs/STATE-MD-LIFECYCLE.md`](reference/state-md.md) for the full field reference and rendering rules.
---
@@ -3009,4 +3009,12 @@ explicit reviewer flags -> --all -> review.default_reviewers -> all detected rev
- REQ-JSON-ERRORS-02: CLI exit code mapping MUST remain stable for automation callers.
- REQ-JSON-ERRORS-03: Human-readable output MUST remain the default when `--json-errors` is absent.
+---
+
+## Related
+
+- [Commands](COMMANDS.md)
+- [Configuration](CONFIGURATION.md)
+- [docs index](README.md)
+
**Reference:** [JSON Error Mode](json-errors.md)
diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md
index 920d9189a..c37046ef6 100644
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -8,6 +8,8 @@
- This file enumerates every shipped surface across all six families (agents, commands, workflows, references, CLI modules, hooks). Broad docs may render narrative or curated subsets; when they disagree with the filesystem, this file and the directory listings are authoritative.
- New surfaces added after v1.36.0 should land here first, then propagate to the broad docs. The drift-control tests in `tests/inventory-counts.test.cjs`, `tests/commands-doc-parity.test.cjs`, `tests/agents-doc-parity.test.cjs`, `tests/cli-modules-doc-parity.test.cjs`, `tests/hooks-doc-parity.test.cjs`, `tests/architecture-counts.test.cjs`, and `tests/command-count-sync.test.cjs` anchor the counts and roster contents against the filesystem.
+This is the authoritative roster of every shipped GSD Core surface. See the [docs index](README.md) to navigate by topic.
+
---
## Agents (33 shipped)
@@ -484,3 +486,9 @@ Full listing: `hooks/`.
- When a new command, agent, workflow, reference, CLI module, or hook ships, update the corresponding section here before the release is cut.
- The drift-guard tests under `tests/` (see "How To Use This File" above) assert that every shipped file is enumerated in this inventory. A new file without a matching row here will fail CI.
- When the filesystem diverges from `docs/ARCHITECTURE.md` counts or from curated-subset docs (e.g. `docs/AGENTS.md`'s primary roster), this file is the source of truth.
+
+## Related
+
+- [Commands](COMMANDS.md) — user-facing command reference
+- [Architecture](ARCHITECTURE.md) — how the surfaces fit together
+- [docs index](README.md)
diff --git a/docs/README.md b/docs/README.md
index e005bcc84..edca28e0b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,36 +1,69 @@
-# GSD Core Documentation
+# GSD Core documentation
-Comprehensive documentation for GSD Core (Git. Ship. Done.) — a meta-prompting, context engineering, and spec-driven development system for AI coding agents.
+Documentation is organised into four quadrants: **tutorials** help you learn by doing, **how-to guides** solve specific tasks, **reference** states authoritative facts, and **explanation** explores concepts and design decisions.
Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md)
-## Documentation Index
+---
-| Document | Audience | Description |
-|----------|----------|-------------|
-| [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design |
-| [Installer Migrations](installer-migrations.md) | Contributors | Architecture for safe install-time migrations, cleanup, preservation, dry-run planning, and rollback |
-| [Feature Reference](FEATURES.md) | All users | Feature narratives and requirements for released features |
-| [Command Reference](COMMANDS.md) | All users | Stable commands with syntax, flags, options, and examples |
-| [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching |
-| [Custom PR Body Sections](ship-pr-body-sections.md) | All users | How to append project-specific PRD sections to `/gsd-ship` PR bodies |
-| [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents |
-| [JSON Error Mode](json-errors.md) | Contributors, agent authors | Machine-readable `gsd-tools --json-errors` failure envelopes |
-| [Agent Reference](AGENTS.md) | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the `agents/` filesystem is authoritative) |
-| [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery |
-| [Issue-Driven Orchestration](issue-driven-orchestration.md) | All users | Recipe for driving GSD from a tracker issue (GitHub / Linear / Jira) using existing primitives — no new commands or daemon |
-| [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture |
-| [Discuss Mode](workflow-discuss-mode.md) | All users | Assumptions vs interview mode for discuss-phase |
-| [Canary Stream](CANARY.md) | Maintainers | Archived stream notes; current public npm tags are `latest` and `next` |
+## Tutorials
-## Quick Links
+- [Your first project](tutorials/your-first-project.md) — install to first shipped phase, one guaranteed path
+- [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md) — bring GSD Core to a brownfield repo
-- **What's new:** install `@opengsd/gsd-core@latest` and use the npm/package version as the current source of truth; older release-note files are archived continuity notes
-- **Preview streams:** current public npm tags are `latest` and `next`; older canary notes are archived in [Canary Stream](CANARY.md)
-- **Getting started:** [README](../README.md) → install → `/gsd-new-project`
-- **Full workflow walkthrough:** [User Guide](USER-GUIDE.md)
-- **All commands at a glance:** [Command Reference](COMMANDS.md)
-- **Configuring GSD:** [Configuration Reference](CONFIGURATION.md)
-- **Customizing ship PR bodies:** [Custom PR Body Sections](ship-pr-body-sections.md)
-- **How the system works internally:** [Architecture](ARCHITECTURE.md)
-- **Contributing or extending:** [CLI Tools Reference](CLI-TOOLS.md) + [Agent Reference](AGENTS.md)
+---
+
+## How-to guides
+
+- [Install on your runtime](how-to/install-on-your-runtime.md) — runtime-specific install steps for all 15 supported runtimes
+- [Discuss a phase](how-to/discuss-a-phase.md) — capture implementation decisions before planning begins
+- [Plan a phase](how-to/plan-a-phase.md) — run research, decompose work, and verify plan quality
+- [Execute a phase](how-to/execute-a-phase.md) — run plans in parallel waves with fresh-context subagents
+- [Verify and ship](how-to/verify-and-ship.md) — walk through completed work, diagnose failures, and create the PR
+- [Run phases autonomously](how-to/run-phases-autonomously.md) — use autonomous mode for unattended phase execution
+- [Handle quick and fast tasks](how-to/handle-quick-and-fast-tasks.md) — use `/gsd-quick` and `/gsd-fast` for ad-hoc work outside the phase loop
+- [Configure model profiles](how-to/configure-model-profiles.md) — switch between quality, balanced, and budget model tiers
+- [Set up cross-AI review](how-to/set-up-cross-ai-review.md) — configure a second AI to review code produced by the primary agent
+- [Work in parallel with workstreams](how-to/work-in-parallel-with-workstreams.md) — run independent lines of work simultaneously using workstreams
+- [Isolate work with workspaces](how-to/isolate-work-with-workspaces.md) — use workspaces to sandbox experimental or risky changes
+- [Debug a failed execution](how-to/debug-a-failed-execution.md) — diagnose and recover from broken or incomplete phase execution
+- [Spike and sketch](how-to/spike-and-sketch.md) — use `/gsd-spike` and `/gsd-sketch` for exploratory work before committing to a plan
+- [Design a UI phase](how-to/design-a-ui-phase.md) — use the UI phase loop for frontend and visual work
+- [Drive GSD from a tracker issue](how-to/drive-gsd-from-a-tracker-issue.md) — start a phase from a GitHub, Linear, or Jira issue
+- [Migrate from GSD 2](how-to/migrate-from-gsd-2.md) — upgrade an existing GSD 2 project to GSD Core
+- [Update GSD](how-to/update-gsd.md) — re-run the installer to pick up the latest release
+- [Recover and troubleshoot](how-to/recover-and-troubleshoot.md) — fix common problems, rebuild context, and uninstall
+
+---
+
+## Reference
+
+- [Commands](COMMANDS.md) — every command with flags and examples
+- [Configuration](CONFIGURATION.md) — full config schema, model profiles, git branching strategies
+- [CLI tools](CLI-TOOLS.md) — `gsd-tools.cjs` programmatic API for workflows and agents
+- [Features](FEATURES.md) — complete feature index
+- [Inventory](INVENTORY.md) — installed skills and surface map
+- [STATE.md schema](reference/state-md.md) — field-by-field reference for `.planning/STATE.md`
+- [CONTEXT.md schema](reference/context-md.md) — field-by-field reference for `.planning/phases//CONTEXT.md`
+- [PLAN.md schema](reference/plan-md.md) — field-by-field reference for `.planning/phases//PLAN.md`
+- [Planning artifacts](reference/planning-artifacts.md) — all `.planning/` files and their roles
+
+---
+
+## Explanation
+
+- [Context engineering](explanation/context-engineering.md) — how context rot forms and how GSD Core prevents it
+- [The phase loop](explanation/the-phase-loop.md) — design rationale for the Discuss → Plan → Execute → Verify → Ship cycle
+- [Multi-agent orchestration](explanation/multi-agent-orchestration.md) — how subagents are spawned, scoped, and coordinated
+- [Security model](explanation/security-model.md) — trust boundaries, permissions, and safe automation
+- [Architecture](ARCHITECTURE.md) — system architecture, agent model, and data flow
+- [Discuss modes](workflow-discuss-mode.md) — assumptions mode vs interview mode for `/gsd-discuss-phase`
+- [Context monitoring](context-monitor.md) — context window monitoring hook architecture
+- [Issue-driven orchestration](issue-driven-orchestration.md) — recipe for driving GSD from a tracker issue using existing primitives
+
+---
+
+## Related
+
+- [Root README](../README.md) — landing page, quickstart, and documentation overview
+- [Changelog](../CHANGELOG.md) — release history
diff --git a/docs/STATE-MD-LIFECYCLE.md b/docs/STATE-MD-LIFECYCLE.md
deleted file mode 100644
index 40464cb95..000000000
--- a/docs/STATE-MD-LIFECYCLE.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# STATE.md Phase Lifecycle Frontmatter
-
-> **Status:** Read-side shipped in v1.40.0 (issue
-> [#2833](https://github.com/open-gsd/gsd-core/issues/2833)).
-> `parseStateMd()` reads the four frontmatter fields below and
-> `formatGsdState()` renders the in-flight / idle / progress scenes.
-> SDK write-side support to maintain the fields automatically is tracked
-> separately.
-
-GSD's `STATE.md` carries YAML frontmatter that the status-line hook reads on
-every render. This document describes the **phase-lifecycle fields** and the
-rendering scenes they trigger.
-
-All four lifecycle fields are **optional and additive**. Existing `STATE.md`
-files (without these fields) keep rendering exactly as they did before — no
-visual change, no migration required.
-
----
-
-## Frontmatter fields
-
-```yaml
----
-gsd_state_version: 1.0
-milestone: v2.0 # existing
-milestone_name: Code Quality # existing
-status: in_progress # existing — see "status semantics" below
-
-# Phase-lifecycle additions (issue #2833) — all optional
-active_phase: null # phase number when an orchestrator is in flight
-next_action: execute-phase # next recommended command when idle
-next_phases: ["4.5"] # phases that next_action applies to (1-2 ids)
-
-progress: # nested block (existing key, percent now opt-in for the bar)
- total_phases: 17
- completed_phases: 10
- percent: 59
----
-```
-
-### Field reference
-
-| Field | Type | When populated | When null/absent |
-|---|---|---|---|
-| `active_phase` | string (e.g. `"4.5"`) | An orchestrator command is in flight on this phase | Idle between phases |
-| `next_action` | string | Idle, with a recommended command (`discuss-phase` / `plan-phase` / `execute-phase` / `verify-phase`) | An orchestrator is in flight, OR no recommendation available |
-| `next_phases` | YAML flow array (e.g. `["4.5"]`) | Goes with `next_action` — phases the action applies to | Same as above |
-| `progress.percent` | integer 0-100 | Milestone progress in **phase dimension** (`completed_phases / total_phases`) | Bar rendering is opt-in — absent → no bar |
-
-### `next_phases` parser scope
-
-Only **single-line YAML flow** is parsed: `next_phases: ["4.5", "4.6"]`.
-
-Block sequences over multiple lines (`- 4.5\n - 4.6`) are intentionally
-**not parsed** — the status-line only needs the primary recommendation, and a
-single-line array keeps the regex-based parser predictable. If a project needs
-to track many candidate next phases for documentation purposes, store the
-extra ones in the `STATE.md` body.
-
-### `progress.percent` dimension
-
-The bar rendered next to the milestone version reflects **phase completion**
-(`completed_phases / total_phases`), not plan completion.
-
-Plan dimension (`completed_plans / total_plans`) trends optimistic for any
-project where future phases haven't been planned yet — `total_plans` only
-counts plans inside *already-planned* phases, so the denominator is
-structurally smaller than reality. Reporting that number to stakeholders
-overstates progress.
-
-If a project wants to show plan-level progress somewhere, store it elsewhere
-in frontmatter or the body — the status-line bar is reserved for the
-phase-dimension number that matches `ROADMAP.md` progress tables and
-`MILESTONES.md`.
-
----
-
-## Status-line rendering scenes
-
-`formatGsdState()` checks the lifecycle fields in the order below and emits
-the **first matching scene**. If none match, the renderer falls through to
-the original ` · ` format (byte-for-byte unchanged from
-v1.38.x).
-
-| Scene | Trigger | Display |
-|---|---|---|
-| **1. Phase active** | `active_phase` populated | `v2.0 [██░░░] X% · Phase 4.5 executing` |
-| **2. Idle, next recommended** | `active_phase` null AND `next_action` + `next_phases` populated | `v2.0 [██░░░] X% · next execute-phase 4.5` |
-| **3. Milestone complete** | `percent: 100` OR `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
-| **4. Default fallback** | None of the above | `v1.9 Code Quality · executing · ph (1/5)` (existing format) |
-
-### Scene priority example
-
-When both `active_phase` and `next_action` are populated, **Scene 1 wins** —
-an orchestrator is in flight, so any "next recommendation" would be misleading.
-This is enforced by check order in `formatGsdState()` and by tests in
-`tests/enh-2833-phase-lifecycle-statusline.test.cjs` (suite *"scene priority"*).
-
-### Stage labels in Scene 1
-
-In Scene 1, the second part of `Phase 4.5 ` is whichever value is in
-the `status` field at that moment. The convention proposed in issue #2833
-is to use the lifecycle stage:
-
-| Command | `status` value while in flight |
-|---|---|
-| `/gsd-discuss-phase` | `discussing` |
-| `/gsd-plan-phase` | `planning` |
-| `/gsd-execute-phase` | `executing` |
-| `/gsd-verify-work` | `verifying` |
-
-If `status` is left at `in_progress` (the milestone-level value), Scene 1
-renders just `Phase 4.5` without the stage suffix.
-
----
-
-## Frontmatter parsing constraints
-
-The status-line hook uses regex-based parsing (no full YAML library), so a
-few constraints apply:
-
-1. **Frontmatter must start at the very first character of the file.**
- Anything (including comments) above the opening `---` invalidates the
- match. The opening `---` line must be exactly that — no trailing spaces.
-
-2. **Comments inside nested blocks are not supported.**
- The parser for `progress:` requires the next line to be `[ \t]+\w+:` —
- inserting `# comment` between `progress:` and the first key breaks the
- match and the bar disappears. Put any documentation in the body of
- `STATE.md`, not inside frontmatter blocks.
-
-3. **`next_phases` accepts only single-line flow format.**
- See the parser scope note above.
-
-These constraints are tested in
-`tests/enh-2833-phase-lifecycle-statusline.test.cjs`. If a future change
-swaps the regex parser for a real YAML library, the constraints can be
-relaxed and the tests updated accordingly.
-
----
-
-## Backward compatibility
-
-This document describes additive fields. The promise is:
-
-- A `STATE.md` file with **none** of the lifecycle fields populated renders
- **byte-for-byte identically** to v1.38.x and earlier.
-- Adding any lifecycle field is **opt-in per project** — the renderer falls
- through to the existing format when fields are absent.
-- The progress bar is opt-in even when `progress` block exists — only
- `progress.percent` triggers the bar; `total_phases` / `completed_phases`
- alone don't.
-
-The `formatGsdState #2833 backward compatibility` test suite locks this
-guarantee in: any change that breaks legacy `STATE.md` rendering will fail
-the suite.
-
----
-
-## Related issues / PRs
-
-- **#1989** — *enhancement: surface GSD state in statusline.* The foundation
- this proposal extends. Established that `STATE.md` frontmatter drives the
- status-line.
-- **#2833** — *enhancement: phase-lifecycle status-line — auto-rotate
- STATE.md frontmatter as phase orchestrators progress.* This document
- describes the read-side spec from that issue. Write-side SDK / workflow
- changes to auto-maintain the fields are tracked separately so each piece
- can be reviewed independently.
-
-Companion read-side issues this proposal also helps close (each fixed a
-specific symptom of the same gap):
-
-- #1102 — STATE.md frontmatter plan counts only update on plan completion
-- #1103 — STATE.md status / last_activity not updated when a phase starts
-- #1446 / #1572 — phase complete doesn't update Plans column
-- #612 — ROADMAP.md not updating
-- #956 — planning document drift across core workflows
-- #2018 — verify-work doesn't auto-transition (fixed for verify only)
diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md
index de22e0fad..a5e31e09d 100644
--- a/docs/USER-GUIDE.md
+++ b/docs/USER-GUIDE.md
@@ -1,25 +1,31 @@
# GSD User Guide
-A detailed reference for workflows, troubleshooting, and configuration. For quick-start setup, see the [README](../README.md).
+A narrative companion guide to GSD Core — orient yourself here, then follow the links into the dedicated docs.
+
+> **GSD Core's documentation is organised by [Diataxis](https://diataxis.fr).**
+> Browse by goal: [Tutorials](README.md#tutorials) · [How-to guides](README.md#how-to-guides) · [Reference](README.md#reference) · [Explanation](README.md#explanation) · [Docs index](README.md)
---
## Table of Contents
-- [End-to-End Walkthrough](#end-to-end-walkthrough)
+- [Slash-command forms](#slash-command-forms-hyphen-vs-colon)
+- [Namespace routing primer](#namespace-routing-primer-gsdnamespace-v140)
+- [Project lifecycle overview](#project-lifecycle-overview)
- [Workflow Diagrams](#workflow-diagrams)
- [UI Design Contract](#ui-design-contract)
- [Spiking & Sketching](#spiking--sketching)
- [Backlog & Threads](#backlog--threads)
-- [Workstreams](#workstreams)
+- [Workstreams & Workspaces](#workstreams--workspaces)
- [Security](#security)
-- [Command And Configuration Reference](#command-and-configuration-reference)
- [Usage Examples](#usage-examples)
- [Troubleshooting](#troubleshooting)
- [Recovery Quick Reference](#recovery-quick-reference)
+- [Project File Structure](#project-file-structure)
+- [Related](#related)
For driving GSD directly from a GitHub / Linear / Jira issue, see the
-[Issue-Driven Orchestration guide](issue-driven-orchestration.md) — a
+[Issue-driven orchestration](issue-driven-orchestration.md) guide — a
recipe that maps tracker issues onto the workspace → discuss → plan →
execute → verify → review → ship loop using existing GSD primitives.
@@ -51,231 +57,15 @@ You almost never need to type a namespace router yourself. Their value is in the
---
-## End-to-End Walkthrough
+## Project lifecycle overview
-This walkthrough shows how GSD phases connect for a typical single-phase project — a small Node.js REST API that validates webhook signatures. Follow it to understand what each command does, what it creates, and how the next command consumes it.
+The core GSD loop is: **discuss → plan → execute → verify → ship**, repeated per phase. The full step-by-step walkthrough — including example outputs, what files get created, and all the flags in play — is in the dedicated tutorial.
-### 1. Create the project
+See [Your first project](tutorials/your-first-project.md).
-```
-/gsd-new-project
-```
+For onboarding an existing codebase before starting a new milestone, see [Onboarding an existing codebase](tutorials/onboarding-an-existing-codebase.md).
-GSD asks questions about your idea, spawns parallel research agents, extracts requirements, and creates a roadmap. You approve the roadmap before any code is written.
-
-**Example output (abridged):**
-
-```
-> What are you building?
- A webhook signature validator middleware for Express apps.
-
-> Who's the user?
- Backend developers integrating third-party webhooks (Stripe, GitHub, Shopify).
-
-[Research agents run in parallel...]
-[Requirements extracted...]
-
-Roadmap (1 phase):
- Phase 1 — Core middleware: HMAC-SHA256 signature validation,
- timing-safe compare, configurable tolerance window.
-
-Approve? [y/n]
-```
-
-**What gets created:**
-
-```
-.planning/
- PROJECT.md # "Webhook validator middleware — Express, HMAC-SHA256..."
- REQUIREMENTS.md # REQ-001: Validate signature header; REQ-002: Timing-safe...
- ROADMAP.md # Phase 1 status: pending
- STATE.md # Session memory, current position
-```
-
-`ROADMAP.md` excerpt:
-```markdown
-## Phase 1 — Core middleware
-**Status:** pending
-**Goal:** HMAC-SHA256 signature validation with timing-safe compare and a
-configurable replay-protection tolerance window.
-**Requirements:** REQ-001, REQ-002, REQ-003
-```
-
-### 2. Discuss and plan the phase
-
-```
-/gsd-discuss-phase 1
-```
-
-GSD reads the phase goal and asks about your implementation preferences before any planning happens. This is where you shape *how* it builds — not just *what* it builds.
-
-```
-> How should invalid signatures be handled?
- Reject immediately with 401, log the raw header for debugging.
-
-> Should the tolerance window be configurable per-route or global?
- Global config, but allow per-route override via middleware options.
-
-> Any library preferences for HMAC?
- Node built-in crypto only — no extra dependencies.
-```
-
-**What gets created:** `.planning/phases/01-core-middleware/CONTEXT.md`
-
-`CONTEXT.md` excerpt:
-```markdown
-## Implementation Decisions
-- Invalid signatures → 401, log raw header
-- Tolerance window → global default, per-route override via options object
-- HMAC library → Node built-in crypto (no external deps)
-- Error format → { error: "invalid_signature", ts: }
-```
-
-Now plan the phase:
-
-```
-/gsd-plan-phase 1
-```
-
-GSD spawns four parallel research agents (stack, features, architecture, pitfalls), then a planner reads `CONTEXT.md` + research findings and creates atomic task plans. A plan-checker verifies each plan achieves the phase goal before saving.
-
-**What gets created:**
-
-```
-.planning/phases/01-core-middleware/
- RESEARCH.md # Findings: crypto.timingSafeEqual docs, replay attack patterns...
- 01-01-PLAN.md # Task: create validateSignature() core function
- 01-02-PLAN.md # Task: Express middleware wrapper + error handling
-```
-
-`01-01-PLAN.md` excerpt:
-```xml
-
- Create validateSignature core function
- src/validate.js, src/validate.test.js
-
- Use crypto.createHmac('sha256', secret).update(rawBody).digest('hex').
- Compare with crypto.timingSafeEqual() — never === or ==.
- Accept tolerance window in ms; reject if |timestamp - now| exceeds it.
-
- npm test -- --grep "validateSignature"
- All timing-safe comparison tests pass; replay outside window returns false
-
-```
-
-### 3. Execute
-
-```
-/gsd-execute-phase 1
-```
-
-GSD groups plans into waves (parallel where independent, sequential where dependent), spawns a fresh 200k-context executor per plan, and commits each task atomically.
-
-```
-Wave 1 (parallel):
- [Executor A] → 01-01-PLAN.md (core function) ✓ committed
- [Executor B] → 01-02-PLAN.md (middleware) ✓ committed
-
-[Verifier] Checking codebase against phase goals...
- REQ-001 validateSignature() ✓
- REQ-002 timing-safe compare ✓
- REQ-003 tolerance window ✓
- Status: PASS
-```
-
-**Git history after execution:**
-
-```
-a1b2c3d feat(01-01): implement validateSignature with timingSafeEqual
-d4e5f6g feat(01-02): add Express middleware wrapper and 401 error format
-h7i8j9k chore(01): phase 1 verification — all requirements met
-```
-
-**What gets created:**
-
-```
-.planning/phases/01-core-middleware/
- 01-01-SUMMARY.md # "Implemented validateSignature(), 47 lines, tests passing"
- 01-02-SUMMARY.md # "Middleware wraps validator, logs raw header on 401"
- VERIFICATION.md # REQ-001 ✓, REQ-002 ✓, REQ-003 ✓ — PASS
-```
-
-`STATE.md` is updated automatically to reflect the new phase status:
-
-```markdown
-## Current Position
-Phase 1 — Core middleware: executed, pending verify
-```
-
-### 4. Verify
-
-```
-/gsd-verify-work 1
-```
-
-GSD extracts testable deliverables from the phase goal and walks you through them one at a time.
-
-```
-[1/3] Can you require the middleware and pass it to an Express route?
-> yes
-
-[2/3] Does a request with a valid signature return 200?
-> yes
-
-[3/3] Does a request with an invalid signature return 401 with { error: "invalid_signature" }?
-> no — I'm getting a 500 instead
-
-[Diagnosing...]
-Root cause: middleware catches crypto.timingSafeEqual TypeError when
-buffers are different lengths. Fix: normalize to same length before compare.
-
-Fix plan created: .planning/phases/01-core-middleware/01-03-PLAN.md
-Run /gsd-execute-phase 1 to apply.
-```
-
-After re-running execute and re-verifying:
-
-```
-All 3 checks passed. Phase 1 verified.
-```
-
-**What gets created:** `.planning/phases/01-core-middleware/UAT.md`
-
-### What's next
-
-Once a phase is verified, ship it:
-
-```
-/gsd-ship 1 # Creates a PR with auto-generated body
-```
-
-The PR body always includes the required GSD sections: `Summary`, `Changes`, `Requirements Addressed`, `Verification`, and `Key Decisions`. During `/gsd-new-project`, you can also enable optional PRD-style sections such as user stories, acceptance criteria, risks, release criteria, and stakeholder approval. These are appended through `ship.pr_body_sections` and do not change the required core sections.
-
-For setup examples, field definitions, and troubleshooting, see [Custom PR Body Sections](ship-pr-body-sections.md).
-
-For multi-phase projects, repeat the loop:
-
-```
-/gsd-discuss-phase 2
-/gsd-plan-phase 2
-/gsd-execute-phase 2
-/gsd-verify-work 2
-```
-
-Or let GSD figure out the next step automatically:
-
-```
-/gsd-progress --next
-```
-
-When all phases are done:
-
-```
-/gsd-audit-milestone # Verify all requirements shipped
-/gsd-complete-milestone # Archive, tag release
-```
-
-**Relevant flags covered in this walkthrough:**
+**Relevant flags at a glance:**
| Flag | Command | When to use |
| ---- | ------- | ----------- |
@@ -294,7 +84,7 @@ For the full command reference with all flags, see [`docs/COMMANDS.md`](COMMANDS
### Full Project Lifecycle
-```
+```text
┌──────────────────────────────────────────────────┐
│ NEW PROJECT │
│ /gsd-new-project │
@@ -348,7 +138,7 @@ For the full command reference with all flags, see [`docs/COMMANDS.md`](COMMANDS
### Planning Agent Coordination
-```
+```text
/gsd-plan-phase N
│
├── Phase Researcher (x4 parallel)
@@ -382,28 +172,17 @@ For the full command reference with all flags, see [`docs/COMMANDS.md`](COMMANDS
### Validation Architecture (Nyquist Layer)
-During plan-phase research, GSD now maps automated test coverage to each phase
-requirement before any code is written. This ensures that when Claude's executor
-commits a task, a feedback mechanism already exists to verify it within seconds.
+During plan-phase research, GSD maps automated test coverage to each phase requirement before any code is written. The researcher detects your existing test infrastructure, maps each requirement to a specific test command, and identifies any test scaffolding that must be created before implementation begins (Wave 0 tasks). The plan-checker enforces this as an 8th verification dimension: plans where tasks lack automated verify commands will not be approved.
-The researcher detects your existing test infrastructure, maps each requirement to
-a specific test command, and identifies any test scaffolding that must be created
-before implementation begins (Wave 0 tasks).
+**Output:** `{phase}-VALIDATION.md` — the feedback contract for the phase.
-The plan-checker enforces this as an 8th verification dimension: plans where tasks
-lack automated verify commands will not be approved.
-
-**Output:** `{phase}-VALIDATION.md` -- the feedback contract for the phase.
-
-**Disable:** Set `workflow.nyquist_validation: false` in `/gsd-settings` for
-rapid prototyping phases where test infrastructure isn't the focus.
+**Disable:** Set `workflow.nyquist_validation: false` in `/gsd-settings` for rapid prototyping phases where test infrastructure isn't the focus.
### Retroactive Validation (`/gsd-validate-phase`)
-For phases executed before Nyquist validation existed, or for existing codebases
-with only traditional test suites, retroactively audit and fill coverage gaps:
+For phases executed before Nyquist validation existed, or for existing codebases with only traditional test suites, retroactively audit and fill coverage gaps:
-```
+```text
/gsd-validate-phase N
|
+-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
@@ -422,12 +201,7 @@ with only traditional test suites, retroactively audit and fill coverage gaps:
+-- PARTIAL -> some gaps escalated to manual-only
```
-The auditor never modifies implementation code — only test files and
-VALIDATION.md. If a test reveals an implementation bug, it's flagged as an
-escalation for you to address.
-
-**When to use:** After executing phases that were planned before Nyquist was
-enabled, or after `/gsd-audit-milestone` surfaces Nyquist compliance gaps.
+The auditor never modifies implementation code — only test files and VALIDATION.md. If a test reveals an implementation bug, it's flagged as an escalation for you to address.
### Assumptions Discussion Mode
@@ -435,380 +209,23 @@ By default, `/gsd-discuss-phase` asks open-ended questions about your implementa
**Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd-settings`.
-**How it works:**
-
-1. Reads PROJECT.md, codebase mapping, and existing conventions
-2. Generates a structured list of assumptions (tech choices, patterns, file locations)
-3. Presents assumptions for you to confirm, correct, or expand
-4. Writes CONTEXT.md from confirmed assumptions
-
-**When to use:**
-
-- Experienced developers who already know their codebase well
-- Rapid iteration where open-ended questions slow you down
-- Projects where patterns are well-established and predictable
-
See [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) for the full discuss-mode reference.
### Decision Coverage Gates
-The discuss-phase captures implementation decisions in CONTEXT.md under a
-`` block as numbered bullets (`- **D-01:** …`). Two gates — added
-for issue #2492 — ensure those decisions survive into plans and shipped
-code.
+The discuss-phase captures implementation decisions in CONTEXT.md under a `` block as numbered bullets (`- **D-01:** …`). Two gates ensure those decisions survive into plans and shipped code.
-**Plan-phase translation gate (blocking).** After planning, GSD refuses to
-mark the phase planned until every trackable decision appears in at least
-one plan's `must_haves`, `truths`, or body. The gate names each missed
-decision by id (`D-07: …`) so you know exactly what to add, move, or
-reclassify.
+**Plan-phase translation gate (blocking).** After planning, GSD refuses to mark the phase planned until every trackable decision appears in at least one plan's `must_haves`, `truths`, or body.
-**Verify-phase validation gate (non-blocking).** During verification, GSD
-searches plans, SUMMARY.md, modified files, and recent commit messages for
-each trackable decision. Misses are logged to VERIFICATION.md as a warning
-section; verification status is unchanged. The asymmetry is deliberate —
-the blocking gate is cheap at plan time but hostile at verify time.
+**Verify-phase validation gate (non-blocking).** During verification, GSD searches plans, SUMMARY.md, modified files, and recent commit messages for each trackable decision. Misses are logged to VERIFICATION.md as a warning section; verification status is unchanged.
-**Writing decisions the gate can match.** Two match modes:
+**Opting a decision out.** Move it under the `### Claude's Discretion` heading inside ``, or tag it: `- **D-08 [informational]:** …`, `- **D-09 [folded]:** …`, `- **D-10 [deferred]:** …`.
-1. **Strict id match (recommended).** Cite the decision id anywhere in a
- plan that implements it — `must_haves.truths: ["D-12: bit offsets
- exposed"]`, a bullet in the plan body, a frontmatter comment. This is
- deterministic and unambiguous.
-2. **Soft phrase match (fallback).** If a 6+-word slice of the decision
- text appears verbatim in any plan or shipped artifact, it counts. This
- forgives paraphrasing but is less reliable.
-
-**Opting a decision out.** If a decision genuinely should not be tracked —
-an implementation-discretion note, an informational capture, a decision
-already deferred — mark it one of these ways:
-
-- Move it under the `### Claude's Discretion` heading inside ``.
-- Tag it in its bullet: `- **D-08 [informational]:** …`,
- `- **D-09 [folded]:** …`, `- **D-10 [deferred]:** …`.
-
-**Disabling the gates.** Set
-`workflow.context_coverage_gate: false` in `.planning/config.json` (or via
-`/gsd-settings`) to skip both gates silently. Default is `true`.
-
----
-
-## UI Design Contract
-
-### Why
-
-AI-generated frontends are visually inconsistent not because Claude Code is bad at UI but because no design contract existed before execution. Five components built without a shared spacing scale, color contract, or copywriting standard produce five slightly different visual decisions.
-
-`/gsd-ui-phase` locks the design contract before planning. `/gsd-ui-review` audits the result after execution.
-
-### Commands
-
-
-| Command | Description |
-| -------------------- | -------------------------------------------------------- |
-| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
-| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
-
-
-### Workflow: `/gsd-ui-phase`
-
-**When to run:** After `/gsd-discuss-phase`, before `/gsd-plan-phase` — for phases with frontend/UI work.
-
-**Flow:**
-
-1. Reads CONTEXT.md, RESEARCH.md, REQUIREMENTS.md for existing decisions
-2. Detects design system state (shadcn components.json, Tailwind config, existing tokens)
-3. shadcn initialization gate — offers to initialize if React/Next.js/Vite project has none
-4. Asks only unanswered design contract questions (spacing, typography, color, copywriting, registry safety)
-5. Writes `{phase}-UI-SPEC.md` to phase directory
-6. Validates against 6 dimensions (Copywriting, Visuals, Color, Typography, Spacing, Registry Safety)
-7. Revision loop if BLOCKED (max 2 iterations)
-
-**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/`
-
-### Workflow: `/gsd-ui-review`
-
-**When to run:** After `/gsd-execute-phase` or `/gsd-verify-work` — for any project with frontend code.
-
-**Standalone:** Works on any project, not just GSD-managed ones. If no UI-SPEC.md exists, audits against abstract 6-pillar standards.
-
-**6 Pillars (scored 1-4 each):**
-
-1. Copywriting — CTA labels, empty states, error states
-2. Visuals — focal points, visual hierarchy, icon accessibility
-3. Color — accent usage discipline, 60/30/10 compliance
-4. Typography — font size/weight constraint adherence
-5. Spacing — grid alignment, token consistency
-6. Experience Design — loading/error/empty state coverage
-
-**Output:** `{padded_phase}-UI-REVIEW.md` in phase directory with scores and top 3 priority fixes.
-
-### Configuration
-
-
-| Setting | Default | Description |
-| ------------------------- | ------- | ----------------------------------------------------------- |
-| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
-| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
-
-
-Both follow the absent=enabled pattern. Disable via `/gsd-settings`.
-
-### shadcn Initialization
-
-For React/Next.js/Vite projects, the UI researcher offers to initialize shadcn if no `components.json` is found. The flow:
-
-1. Visit `ui.shadcn.com/create` and configure your preset
-2. Copy the preset string
-3. Run `npx shadcn init --preset {paste}`
-4. Preset encodes the entire design system — colors, border radius, fonts
-
-The preset string becomes a first-class GSD planning artifact, reproducible across phases and milestones.
-
-### Registry Safety Gate
-
-Third-party shadcn registries can inject arbitrary code. The safety gate requires:
-
-- `npx shadcn view {component}` — inspect before installing
-- `npx shadcn diff {component}` — compare against official
-
-Controlled by `workflow.ui_safety_gate` config toggle.
-
-### Screenshot Storage
-
-`/gsd-ui-review` captures screenshots via Playwright CLI to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`.
-
----
-
-## Spiking & Sketching
-
-Use `/gsd-spike` to validate technical feasibility before planning, and `/gsd-sketch` to explore visual direction before designing. Both store artifacts in `.planning/` and integrate with the project-skills system via their wrap-up companions.
-
-### When to Spike
-
-Spike when you're uncertain whether a technical approach is feasible or want to compare two implementations before committing a phase to one of them.
-
-```
-/gsd-spike # Interactive intake — describes the question, you confirm
-/gsd-spike "can we stream LLM tokens through SSE"
-/gsd-spike --quick "websocket vs SSE latency"
-```
-
-Each spike runs 2–5 experiments. Every experiment has:
-- A **Given / When / Then** hypothesis written before any code
-- **Working code** (not pseudocode)
-- A **VALIDATED / INVALIDATED / PARTIAL** verdict with evidence
-
-Results land in `.planning/spikes/NNN-name/README.md` and are indexed in `.planning/spikes/MANIFEST.md`.
-
-Once you have signal, run `/gsd-spike --wrap-up` to package the findings into `.claude/skills/spike-findings-[project]/` — future sessions will load them automatically via project-skills discovery.
-
-### When to Sketch
-
-Sketch when you need to compare layout structures, interaction models, or visual treatments before writing any real component code.
-
-```
-/gsd-sketch # Mood intake — explores feel, references, core action
-/gsd-sketch "dashboard layout"
-/gsd-sketch --quick "sidebar navigation"
-/gsd-sketch --text "onboarding flow" # For non-Claude runtimes (Codex, Gemini, etc.)
-```
-
-Each sketch answers **one design question** with 2–3 variants in a single `index.html` you open directly in a browser — no build step. Variants use tab navigation and shared CSS variables from `themes/default.css`. All interactive elements (hover, click, transitions) are functional.
-
-After picking a winner, run `/gsd-sketch --wrap-up` to capture the visual decisions into `.claude/skills/sketch-findings-[project]/`.
-
-### Spike → Sketch → Phase Flow
-
-```
-/gsd-spike "SSE vs WebSocket" # Validate the approach
-/gsd-spike --wrap-up # Package learnings
-
-/gsd-sketch "real-time feed UI" # Explore the design
-/gsd-sketch --wrap-up # Package decisions
-
-/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
-/gsd-plan-phase N # Plan with confidence
-```
-
----
-
-## Backlog & Threads
-
-### Backlog Parking Lot
-
-Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
-
-```
-/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
-/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
-```
-
-Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999.1` to explore an idea further or `/gsd-plan-phase 999.1` when it's ready.
-
-**Review and promote** with `/gsd-review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
-
-### Seeds
-
-Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
-
-```
-/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
-```
-
-Seeds preserve the full WHY and WHEN to surface. `/gsd-new-milestone` scans all seeds and presents matches.
-
-**Storage:** `.planning/seeds/SEED-NNN-slug.md`
-
-### Persistent Context Threads
-
-Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
-
-```
-/gsd-thread # List all threads
-/gsd-thread fix-deploy-key-auth # Resume existing thread
-/gsd-thread "Investigate TCP timeout" # Create new thread
-```
-
-Threads are lighter weight than `/gsd-pause-work` — no phase state, no plan context. Each thread file includes Goal, Context, References, and Next Steps sections.
-
-Threads can be promoted to phases (`/gsd-phase`) or backlog items (`/gsd-capture --backlog`) when they mature.
-
-**Storage:** `.planning/threads/{slug}.md`
-
----
-
-## Workstreams
-
-Workstreams let you work on multiple milestone areas concurrently without state collisions. Each workstream gets its own isolated `.planning/` state, so switching between them doesn't clobber progress.
-
-**When to use:** You're working on milestone features that span different concern areas (e.g., backend API and frontend dashboard) and want to plan, execute, or discuss them independently without context bleed.
-
-### Commands
-
-
-| Command | Purpose |
-| ---------------------------------- | ---------------------------------------------------- |
-| `/gsd-workstreams create ` | Create a new workstream with isolated planning state |
-| `/gsd-workstreams switch ` | Switch active context to a different workstream |
-| `/gsd-workstreams list` | Show all workstreams and which is active |
-| `/gsd-workstreams complete ` | Mark a workstream as done and archive its state |
-
-
-### How It Works
-
-Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, and other commands operate on that workstream's state. Active context is session-scoped when the runtime exposes a stable session identifier, which prevents one terminal or AI instance from repointing another instance's `STATE.md`.
-
-This is lighter weight than `/gsd-workspace --new` (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts.
-
----
-
-## Security
-
-### Defense-in-Depth (v1.27)
-
-GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralized security hardening:
-
-**Path Traversal Prevention:**
-All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled.
-
-**Prompt Injection Detection:**
-The `security.cjs` module scans for known injection patterns (role overrides, instruction bypasses, system tag injections) in user-supplied text before it enters planning artifacts.
-
-**Runtime Hooks:**
-
-- `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
-- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
-
-**CI Scanner:**
-`prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors. Run as part of the test suite.
-
----
-
-### Package Legitimacy Gate (v1.42.1)
-
-AI coding tools hallucinate package names. Attackers pre-register those names on npm, PyPI, and crates.io with malicious post-install scripts — a technique called *slopsquatting*. A hallucinated name that passes `npm view` looks legitimate, so it would flow undetected through GSD's research → plan → execute pipeline all the way to `npm install ` running on your machine.
-
-v1.42.1 adds a three-layer gate that stops this before it reaches your shell.
-
-#### What you'll see
-
-**In RESEARCH.md** — every phase that recommends external packages now includes a `## Package Legitimacy Audit` table:
-
-```markdown
-## Package Legitimacy Audit
-
-| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
-|---------|----------|-----|-----------|-------------|-----------|-------------|
-| express | npm | 13 yrs | 100M+/wk | github.com/expressjs/express | [OK] | Approved |
-| some-new-util | npm | 3 days | 47 | none | [SLOP] | REMOVED |
-| api-bridge | npm | 6 mo | 1.2k/wk | github.com/user/api-bridge | [SUS] | Flagged |
-
-**Packages removed due to slopcheck:** some-new-util
-**Packages flagged as suspicious:** api-bridge — planner will require human verification before install
-```
-
-`[SLOP]` packages are removed from RESEARCH.md entirely. They never reach the planner.
-
-**In PLAN.md** — if a package is tagged `[ASSUMED]` (sourced from WebSearch, not registry-verified) or `[SUS]` (slopcheck suspicious), the plan includes a verification checkpoint *before* the install task:
-
-```xml
-
- Package verification required before install
-
- Verify these packages before proceeding:
- - `api-bridge` [SUS — 6 months old, 1.2k downloads/week, GitHub repo present]
- Check: https://npmjs.com/package/api-bridge
- Look for: maintainer history, issue tracker activity, no suspicious install scripts
-
- Type "verified" once you've confirmed all packages are legitimate
-
-```
-
-**During execution** — if an install fails, the executor surfaces a checkpoint and stops. It does not silently try a similarly-named alternative (which could be even more dangerous).
-
-#### Slopcheck verdicts
-
-| Verdict | Meaning | GSD action |
-|---------|---------|------------|
-| `[OK]` | Package passes all legitimacy checks | Proceeds — no checkpoint added |
-| `[SUS]` | Suspicious signals (new, low downloads, no source repo, etc.) | Flagged in Audit table; planner adds `checkpoint:human-verify` before install |
-| `[SLOP]` | High-confidence hallucination or attacker-registered package | Removed from RESEARCH.md; never reaches planner |
-
-#### Claim provenance and WebSearch packages
-
-Package names discovered through WebSearch are always tagged `[ASSUMED]` in RESEARCH.md, regardless of whether `npm view` succeeds. A package that exists on the registry is not the same as a package that's safe to install — `npm view` only proves registration, not legitimacy.
-
-`[ASSUMED]` packages trigger the same `checkpoint:human-verify` gate as `[SUS]` packages. You'll see the checkpoint with a link to the registry page and guidance on what to look for.
-
-#### If slopcheck isn't installed
-
-GSD attempts `pip install slopcheck` at research time. If that fails:
-
-- Every recommended package is tagged `[ASSUMED]`
-- The planner gates every install with a `checkpoint:human-verify` task
-- Research and planning complete normally — nothing hard-fails
-
-This is intentionally stricter than the normal flow: slopcheck unavailability means every package install gets a human checkpoint, which is the safest fallback.
-
-To install slopcheck manually:
-
-```bash
-pip install slopcheck
-# verify: slopcheck install express --json
-```
-
-#### slopcheck dependency
-
-`slopcheck` is a MIT-licensed Python tool maintained by ToxSec (the researcher who documented the slopsquatting attack surface). It checks packages across npm, PyPI, crates.io, RubyGems, Go modules, Maven, and Packagist using multi-signal heuristics: registry age, download count, source-repo linkage, naming distance to popular packages, and registry-specific suspicion patterns.
-
-If `slopcheck` is ever unavailable or abandoned, GSD's `[ASSUMED]`-gate fallback ensures you always get a human checkpoint before any install — the system never silently degrades to the pre-v1.42.1 behavior.
-
----
+**Disabling the gates.** Set `workflow.context_coverage_gate: false` in `.planning/config.json` (or via `/gsd-settings`). Default is `true`.
### Execution Wave Coordination
-```
+```text
/gsd-execute-phase N
│
├── Analyze plan dependencies
@@ -828,115 +245,199 @@ If `slopcheck` is ever unavailable or abandoned, GSD's `[ASSUMED]`-gate fallback
└── FAIL -> Issues logged for /gsd-verify-work
```
-### Brownfield Workflow (Existing Codebase)
+---
+## UI Design Contract
+
+AI-generated frontends are visually inconsistent not because Claude Code is bad at UI but because no design contract existed before execution. `/gsd-ui-phase` locks the design contract before planning; `/gsd-ui-review` audits the result after execution.
+
+For the full workflow, configuration, shadcn initialisation, and the registry safety gate, see [Design a UI phase](how-to/design-a-ui-phase.md).
+
+**Quick reference:**
+
+| Command | Description |
+| -------------------- | -------------------------------------------------------- |
+| `/gsd-ui-phase [N]` | Generate UI-SPEC.md design contract for a frontend phase |
+| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit of implemented UI |
+
+| Setting | Default | Description |
+| ------------------------- | ------- | ----------------------------------------------------------- |
+| `workflow.ui_phase` | `true` | Generate UI design contracts for frontend phases |
+| `workflow.ui_safety_gate` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases |
+
+---
+
+## Spiking & Sketching
+
+Use `/gsd-spike` to validate technical feasibility before planning, and `/gsd-sketch` to explore visual direction before designing. Both store artifacts in `.planning/` and integrate with the project-skills system via their wrap-up companions.
+
+For the full workflow and flow diagram, see [Spike and sketch](how-to/spike-and-sketch.md).
+
+**Typical flow:**
+
+```bash
+/gsd-spike "SSE vs WebSocket" # Validate the approach
+/gsd-spike --wrap-up # Package learnings
+
+/gsd-sketch "real-time feed UI" # Explore the design
+/gsd-sketch --wrap-up # Package decisions
+
+/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
+/gsd-plan-phase N # Plan with confidence
```
- /gsd-map-codebase
- │
- ├── Stack Mapper -> codebase/STACK.md
- ├── Arch Mapper -> codebase/ARCHITECTURE.md
- ├── Convention Mapper -> codebase/CONVENTIONS.md
- └── Concern Mapper -> codebase/CONCERNS.md
- │
- ┌───────▼──────────┐
- │ /gsd-new-project │ <- Questions focus on what you're ADDING
- └──────────────────┘
+
+---
+
+## Backlog & Threads
+
+### Backlog Parking Lot
+
+Ideas that aren't ready for active planning go into the backlog using 999.x numbering, keeping them outside the active phase sequence.
+
+```bash
+/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
+/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
+```
+
+Backlog items get full phase directories, so you can use `/gsd-discuss-phase 999.1` to explore an idea further or `/gsd-plan-phase 999.1` when it's ready.
+
+**Review and promote** with `/gsd-review-backlog` — it shows all backlog items and lets you promote (move to active sequence), keep (leave in backlog), or remove (delete).
+
+### Seeds
+
+Seeds are forward-looking ideas with trigger conditions. Unlike backlog items, seeds surface automatically when the right milestone arrives.
+
+```bash
+/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
+```
+
+`/gsd-new-milestone` scans all seeds and presents matches. **Storage:** `.planning/seeds/SEED-NNN-slug.md`
+
+### Persistent Context Threads
+
+Threads are lightweight cross-session knowledge stores for work that spans multiple sessions but doesn't belong to any specific phase.
+
+```bash
+/gsd-thread # List all threads
+/gsd-thread fix-deploy-key-auth # Resume existing thread
+/gsd-thread "Investigate TCP timeout" # Create new thread
+```
+
+Threads can be promoted to phases (`/gsd-phase`) or backlog items (`/gsd-capture --backlog`) when they mature. **Storage:** `.planning/threads/{slug}.md`
+
+---
+
+## Workstreams & Workspaces
+
+Workstreams and workspaces both provide isolation, but at different levels.
+
+**Workstreams** share the same codebase and git history but isolate planning artifacts — lighter weight, good for working on multiple milestone areas concurrently. See [Work in parallel with workstreams](how-to/work-in-parallel-with-workstreams.md).
+
+**Workspaces** create separate repo worktrees with their own `.planning/` — heavier, for feature-branch or multi-repo isolation. See [Isolate work with workspaces](how-to/isolate-work-with-workspaces.md).
+
+| Command | Purpose |
+| ---------------------------------- | ---------------------------------------------------- |
+| `/gsd-workstreams create ` | Create a new workstream with isolated planning state |
+| `/gsd-workstreams switch ` | Switch active context to a different workstream |
+| `/gsd-workstreams list` | Show all workstreams and which is active |
+| `/gsd-workstreams complete ` | Mark a workstream as done and archive its state |
+
+```bash
+# Workspace example — feature branch isolation
+/gsd-workspace --new --name feature-b --repos .
+cd ~/gsd-workspaces/feature-b
+/gsd-new-project
+
+/gsd-workspace --list
+/gsd-workspace --remove feature-b
+```
+
+---
+
+## Security
+
+### Defense-in-Depth (v1.27)
+
+GSD generates markdown files that become LLM system prompts. This means any user-controlled text flowing into planning artifacts is a potential indirect prompt injection vector. v1.27 introduced centralised security hardening:
+
+**Path Traversal Prevention:** All user-supplied file paths (`--text-file`, `--prd`) are validated to resolve within the project directory. macOS `/var` → `/private/var` symlink resolution is handled.
+
+**Prompt Injection Detection:** The `security.cjs` module scans for known injection patterns in user-supplied text before it enters planning artifacts.
+
+**Runtime Hooks:**
+
+- `gsd-prompt-guard.js` — Scans Write/Edit calls to `.planning/` for injection patterns (always active, advisory-only)
+- `gsd-workflow-guard.js` — Warns on file edits outside GSD workflow context (opt-in via `hooks.workflow_guard`)
+
+**CI Scanner:** `prompt-injection-scan.test.cjs` scans all agent, workflow, and command files for embedded injection vectors.
+
+---
+
+### Package Legitimacy Gate (v1.42.1)
+
+AI coding tools hallucinate package names. Attackers pre-register those names on npm, PyPI, and crates.io with malicious post-install scripts — a technique called *slopsquatting*. v1.42.1 adds a three-layer gate that stops this before it reaches your shell.
+
+**In RESEARCH.md** — every phase that recommends external packages includes a `## Package Legitimacy Audit` table:
+
+```markdown
+## Package Legitimacy Audit
+
+| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
+|---------|----------|-----|-----------|-------------|-----------|-------------|
+| express | npm | 13 yrs | 100M+/wk | github.com/expressjs/express | [OK] | Approved |
+| some-new-util | npm | 3 days | 47 | none | [SLOP] | REMOVED |
+| api-bridge | npm | 6 mo | 1.2k/wk | github.com/user/api-bridge | [SUS] | Flagged |
+```
+
+`[SLOP]` packages are removed from RESEARCH.md entirely and never reach the planner.
+
+**In PLAN.md** — `[SUS]` or `[ASSUMED]` packages trigger a `checkpoint:human-verify` task before the install.
+
+**During execution** — if an install fails, the executor surfaces a checkpoint and stops rather than silently trying an alternative.
+
+**Slopcheck verdicts:**
+
+| Verdict | Meaning | GSD action |
+|---------|---------|------------|
+| `[OK]` | Passes all legitimacy checks | Proceeds — no checkpoint added |
+| `[SUS]` | Suspicious signals | Flagged; planner adds `checkpoint:human-verify` |
+| `[SLOP]` | High-confidence hallucination | Removed from RESEARCH.md; never reaches planner |
+
+To install slopcheck manually:
+
+```bash
+pip install slopcheck
+# verify: slopcheck install express --json
```
---
## Code Review Workflow
-### Phase Code Review
-
-After executing a phase, run a structured code review before UAT:
+After executing a phase, run a structured code review before UAT. See [Set up cross-AI review](how-to/set-up-cross-ai-review.md) for the full workflow.
```bash
/gsd-code-review 3 # Review all changed files in phase 3
-/gsd-code-review 3 --depth=deep # Deep cross-file review (import graphs, call chains)
-```
-
-The reviewer scopes files automatically using SUMMARY.md (preferred) or git diff fallback. Findings are classified as Critical, Warning, or Info in `{phase}-REVIEW.md`.
-
-```bash
-/gsd-code-review 3 --fix # Fix Critical + Warning findings atomically
-/gsd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
-```
-
-### Autonomous Audit-to-Fix
-
-To run an audit and fix all auto-fixable issues in one pass:
-
-```bash
+/gsd-code-review 3 --depth=deep # Deep cross-file review
+/gsd-code-review 3 --fix # Fix Critical + Warning findings atomically
+/gsd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
-/gsd-audit-fix --dry-run # Preview classification without fixing
```
-### Code Review in the Full Phase Lifecycle
-
The review step slots in after execution and before UAT:
-```
-/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review N --fix -> /gsd-verify-work N
-```
-
----
-
-## Exploration & Discovery
-
-### Socratic Exploration
-
-Before committing to a new phase or plan, use `/gsd-explore` to think through the idea:
-
-```bash
-/gsd-explore # Open-ended ideation
-/gsd-explore "caching strategy" # Explore a specific topic
-```
-
-The exploration session guides you through probing questions, optionally spawns a research agent, and routes output to the appropriate GSD artifact: note, todo, seed, research question, requirements update, or new phase.
-
-### Codebase Intelligence
-
-For queryable codebase insights without reading the entire codebase, enable the intel system:
-
-```json
-{ "intel": { "enabled": true } }
-```
-
-Then build the index:
-
-```bash
-/gsd-map-codebase --query refresh # Analyze codebase and write .planning/intel/ files
-/gsd-map-codebase --query auth # Search for a term across all intel files
-/gsd-map-codebase --query status # Check freshness of intel files
-/gsd-map-codebase --query diff # See what changed since last snapshot
-```
-
-Intel files cover stack, API surface, dependency graph, file roles, and architecture decisions.
-
-### Quick Scan
-
-For a focused assessment without full `/gsd-map-codebase` overhead:
-
-```bash
-/gsd-map-codebase --fast # Quick tech + arch overview
-/gsd-map-codebase --fast --focus quality # Quality and code health only
-/gsd-map-codebase --fast --focus concerns # Risk areas and concerns
+```text
+/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review N --fix -> /gsd-verify-work N
```
---
## Command And Configuration Reference
-- **Command Reference:** see [`docs/COMMANDS.md`](COMMANDS.md) for every stable command's flags, subcommands, and examples. The authoritative shipped-command roster lives in [`docs/INVENTORY.md`](INVENTORY.md#commands-75-shipped).
-- **Configuration Reference:** see [`docs/CONFIGURATION.md`](CONFIGURATION.md) for the full `config.json` schema, every setting's default and provenance, the per-agent model-profile table (including the `inherit` option for non-Claude runtimes), git branching strategies, and security settings.
+- **Command Reference:** see [`docs/COMMANDS.md`](COMMANDS.md) for every stable command's flags, subcommands, and examples.
+- **Configuration Reference:** see [`docs/CONFIGURATION.md`](CONFIGURATION.md) for the full `config.json` schema, model-profile table, git branching strategies, and security settings.
- **Discuss Mode:** see [`docs/workflow-discuss-mode.md`](workflow-discuss-mode.md) for interview vs assumptions mode.
-This guide intentionally does not re-document commands or config settings: maintaining two copies previously produced drift (`workflow.discuss_mode`'s default, `claude_md_path`'s default, the model-profile table's agent coverage). The single-source-of-truth rule is enforced mechanically by the drift-guard tests anchored on `docs/INVENTORY.md`.
-
-
-
-
---
## Usage Examples
@@ -973,28 +474,21 @@ claude --dangerously-skip-permissions
### Existing Codebase
```bash
-/gsd-map-codebase # Analyze what exists (parallel agents)
+/gsd-map-codebase # Analyse what exists (parallel agents)
/gsd-new-project # Questions focus on what you're ADDING
# (normal phase workflow from here)
```
-**Post-execute drift detection (#2003).** After every `/gsd-execute-phase`,
-GSD checks whether the phase introduced enough structural change
-(new directories, barrel exports, migrations, or route modules) to make
-`.planning/codebase/STRUCTURE.md` stale. If it did, the default behavior is
-to print a one-shot warning suggesting the exact `/gsd-map-codebase --paths …`
-invocation to refresh just the affected subtrees. Flip the behavior with:
+**Post-execute drift detection (#2003).** After every `/gsd-execute-phase`, GSD checks whether the phase introduced enough structural change to make `.planning/codebase/STRUCTURE.md` stale. Flip the behavior with:
```bash
/gsd-settings workflow.drift_action auto-remap # remap automatically
/gsd-settings workflow.drift_threshold 5 # tune sensitivity
```
-The gate is non-blocking: any internal failure logs and the phase continues.
-
### Plan Drift Guard
-**Default-on.** The plan drift guard (`plan_review.source_grounding: true`) runs during plan review and verifies that every symbol your plans cite — decorators, classes, functions, CLI flags — actually exists in your source tree at review time. This catches hallucinated names (symbols the planner invented but that don't exist yet) before any execution agent runs.
+**Default-on.** The plan drift guard (`plan_review.source_grounding: true`) runs during plan review and verifies that every symbol your plans cite — decorators, classes, functions, CLI flags — actually exists in your source tree at review time. This catches hallucinated names before any execution agent runs.
**What it catches:**
@@ -1043,130 +537,68 @@ Toggle at project setup (`/gsd:new-project` asks during workflow preferences) or
### Speed vs Quality Presets
-
| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier |
| ----------- | ------------- | ----------- | ---------- | -------- | ---------- | -------- |
| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
| Normal dev | `interactive` | `standard` | `balanced` | on | on | on |
| Production | `interactive` | `fine` | `quality` | on | on | on |
-
-**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd-settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information.
+**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode, set `workflow.skip_discuss: true` via `/gsd-settings`.
### Mid-Milestone Scope Changes
```bash
/gsd-phase # Append a new phase to the roadmap (default mode)
-# or
/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
-# or
/gsd-phase --remove 7 # Descope phase 7 and renumber
-# or
/gsd-phase --edit 4 # Edit any field of phase 4 in place
```
-### Multi-Project Workspaces
-
-Work on multiple repos or features in parallel with isolated GSD state.
-
-```bash
-# Create a workspace with repos from your monorepo
-/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
-
-# Feature branch isolation — worktree of current repo with its own .planning/
-/gsd-workspace --new --name feature-b --repos .
-
-# Then cd into the workspace and initialize GSD
-cd ~/gsd-workspaces/feature-b
-/gsd-new-project
-
-# List and manage workspaces
-/gsd-workspace --list
-/gsd-workspace --remove feature-b
-```
-
-Each workspace gets:
-
-- Its own `.planning/` directory (fully independent from source repos)
-- Git worktrees (default) or clones of specified repos
-- A `WORKSPACE.md` manifest tracking member repos
-
---
## Troubleshooting
+For a comprehensive troubleshooting guide, see [Recover and troubleshoot](how-to/recover-and-troubleshoot.md). The most common issues are summarised below.
+
### Programmatic CLI (`gsd-tools query` vs `gsd-tools.cjs`)
-For automation and copy-paste from docs, prefer **`gsd-tools query`** with a registered subcommand (see [CLI-TOOLS.md — SDK and programmatic access](CLI-TOOLS.md#sdk-and-programmatic-access) and [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). The legacy `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI remains supported for dual-mode operation.
-
-**CLI-only (not in the query registry):** **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). **Two distinct `state` JSON shapes, both available via `gsd-tools query`:** `state.json` (frontmatter rebuild) vs `state.load` (`config` + `state_raw` + flags) — they resolve to different handlers, so pick the one whose shape you need. The legacy `gsd-tools.cjs state json` / `state load` forms produce the same two shapes. See [CLI-TOOLS.md](CLI-TOOLS.md#sdk-and-programmatic-access) and QUERY-HANDLERS.
+For automation, prefer **`gsd-tools query`** with a registered subcommand (see [CLI-TOOLS.md — SDK and programmatic access](CLI-TOOLS.md#sdk-and-programmatic-access) and QUERY-HANDLERS.md). The legacy `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI remains supported.
### STATE.md Out of Sync
-If STATE.md shows incorrect phase status or position, use the state consistency commands (**CJS-only** until ported to the query layer):
-
```bash
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate # Detect drift between STATE.md and filesystem
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify # Preview what sync would change
-node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md from disk
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate # Detect drift
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify # Preview changes
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md
```
-These commands are new in v1.32 and replace manual STATE.md editing.
-
-### Read-Before-Edit Infinite Retry Loop
-
-Some non-Claude runtimes (Cline, Augment Code) may enter an infinite retry loop when an agent attempts to edit a file it hasn't read. The `gsd-read-before-edit.js` hook (v1.32) detects this pattern and advises reading the file first. If your runtime doesn't support PreToolUse hooks, add this to your project's `CLAUDE.md`:
-
-```markdown
-## Edit Safety Rule
-Always read a file before editing it. Never call Edit or Write on a file you haven't read in this session.
-```
-
-### "Project already initialized"
-
-You ran `/gsd-new-project` but `.planning/PROJECT.md` already exists. This is a safety check. If you want to start over, delete the `.planning/` directory first.
-
### A Command Looks Frozen After "Spawning..."
-If you see `◆ Spawning researcher...` (or any "Spawning…" line) and then nothing — no output, no spinner — for 1–5 minutes, **this is normal**. GSD subagents run in a separate context window; their work is invisible to the parent session while in progress. The liveness note on the spawn line confirms this: "(runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)".
-
-**Do not interrupt the session.** Killing it discards the in-progress subagent work and forces you to restart that step. Wait for the result to appear. Research and planning agents routinely take 1–5 minutes; verification agents can take longer on large phases.
-
-**If it truly seems stuck** (>10 minutes with no result): check whether Claude Code's agent task is still active in the sidebar. If the task shows as completed but no output appeared, the result may have been lost in a context switch — run the command again.
+GSD subagents run in a separate context window — their work is invisible to the parent session while in progress. Do not interrupt the session. Wait for the result; research and planning agents routinely take 1–5 minutes.
### Context Degradation During Long Sessions
-Clear your context window between major commands: `/clear` in Claude Code. GSD is designed around fresh contexts -- every subagent gets a clean 200K window. If quality is dropping in the main session, clear and use `/gsd-resume-work` or `/gsd-progress` to restore state.
+Clear your context window between major commands: `/clear` in Claude Code. GSD is designed around fresh contexts — every subagent gets a clean 200K window. Use `/gsd-resume-work` or `/gsd-progress` to restore state after clearing.
### Plans Seem Wrong or Misaligned
-Run `/gsd-discuss-phase [N]` before planning. Most plan quality issues come from Claude making assumptions that `CONTEXT.md` would have prevented. You can also run `/gsd-discuss-phase --assumptions [N]` to see what Claude intends to do before committing to a plan.
-
-### Discuss-Phase Uses Technical Jargon I Don't Understand
-
-`/gsd-discuss-phase` adapts its language based on your `USER-PROFILE.md`. If the profile indicates a non-technical owner — `learning_style: guided`, `jargon` listed as a frustration trigger, or `explanation_depth: high-level` — gray area questions are automatically reframed in product-outcome language instead of implementation terminology.
-
-To enable this: run `/gsd-profile-user` to generate your profile. The profile is stored at `~/.claude/get-shit-done/USER-PROFILE.md` and is read automatically on every `/gsd-discuss-phase` invocation. No other configuration is required.
+Run `/gsd-discuss-phase [N]` before planning. Most plan quality issues come from Claude making assumptions that `CONTEXT.md` would have prevented.
### Execution Fails or Produces Stubs
-Check that the plan was not too ambitious. Plans should have 2-3 tasks maximum. If tasks are too large, they exceed what a single context window can produce reliably. Re-plan with smaller scope.
+Check that the plan was not too ambitious. Plans should have 2–3 tasks maximum. Re-plan with smaller scope.
### Lost Track of Where You Are
Run `/gsd-progress`. It reads all state files and tells you exactly where you are and what to do next.
-### Need to Change Something After Execution
-
-Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes, or `/gsd-verify-work` to systematically identify and fix issues through UAT.
-
### Model Costs Too High
-Switch to budget profile: `/gsd-config --profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar to you (or to Claude).
+Switch to budget profile: `/gsd-config --profile budget`. Disable research and plan-check agents via `/gsd-settings` if the domain is familiar.
### Tuning model cost by phase (`models`) — added in v1.40
-If you've heard "use Opus for planning, Sonnet for verification" and want to apply that without learning the agent taxonomy, add a `models` block to `.planning/config.json`:
+Add a `models` block to `.planning/config.json`:
```json
{
@@ -1182,8 +614,6 @@ If you've heard "use Opus for planning, Sonnet for verification" and want to app
}
```
-The six slots (`planning` / `discuss` / `research` / `execution` / `verification` / `completion`) accept tier aliases (`opus`, `sonnet`, `haiku`, `inherit`). Each slot covers a group of agents — for example, setting `models.research = "sonnet"` applies to `gsd-phase-researcher`, `gsd-codebase-mapper`, `gsd-research-synthesizer`, and the other research agents in one shot.
-
Need a per-agent exception? Add `model_overrides` alongside — it wins over `models`:
```json
@@ -1195,14 +625,10 @@ Need a per-agent exception? Add `model_overrides` alongside — it wins over `mo
}
```
-That gives sonnet to all research agents *except* the codebase mapper, which runs haiku for the cheap-but-broad fan-out scan.
-
-For the full mapping table and resolution-precedence rules, see [Per-Phase-Type Models](CONFIGURATION.md#per-phase-type-models-models--added-in-v140) in the configuration reference.
+For the full mapping table and resolution-precedence rules, see [Per-Phase-Type Models](CONFIGURATION.md#per-phase-type-models-models--added-in-v140).
### Cheap-by-default with `dynamic_routing` — added in v1.40
-If you've been paying Opus rates everywhere as insurance against a single hard verification, dynamic routing flips it: every agent starts on a cheaper tier and escalates only when the orchestrator marks a soft failure (verification inconclusive, plan-check FLAG, etc.).
-
```json
{
"dynamic_routing": {
@@ -1218,20 +644,11 @@ If you've been paying Opus rates everywhere as insurance against a single hard v
}
```
-Each agent has a default tier (`light`, `standard`, or `heavy`). On the first attempt, GSD picks `tier_models[default_tier]`. If the orchestrator detects a soft failure, it re-spawns once at the next tier up. `max_escalations` caps total retries so a runaway loop can't burn through your budget.
+For the full agent → tier mapping, see [Dynamic Routing](CONFIGURATION.md#dynamic-routing-with-failure-tier-escalation-dynamic_routing--added-in-v140).
-Concretely:
-- `gsd-codebase-mapper` (default `light`) → first attempt = `haiku`. If escalated → `sonnet`.
-- `gsd-verifier` (default `standard`) → first attempt = `sonnet`. If escalated → `opus`.
-- `gsd-planner` (default `heavy`) → always `opus`. No tier above; can't escalate further.
+### Trim MCP servers to reduce per-turn cost
-To turn it off, set `dynamic_routing.enabled: false` (the default) — behavior is identical to today.
-
-For the full agent → tier mapping and resolution-precedence rules, see [Dynamic Routing](CONFIGURATION.md#dynamic-routing-with-failure-tier-escalation-dynamic_routing--added-in-v140) in the configuration reference.
-
-### Trim MCP servers to reduce per-turn cost (the biggest lever GSD doesn't own)
-
-Before tuning `model_profile` or `models.`, audit which **MCP servers** your harness has enabled. Every enabled MCP server injects its tool schema into every turn — heavyweight servers like browser/playwright tools or platform-specific helpers can cost 20k+ tokens each, often dwarfing whatever GSD's resolver can save.
+Before tuning `model_profile` or `models.`, audit which **MCP servers** your harness has enabled. Every enabled MCP server injects its tool schema into every turn — heavyweight servers can cost 20k+ tokens each.
This is a **harness setting**, not a GSD setting. The toggle lives in `.claude/settings.json`:
@@ -1245,24 +662,20 @@ This is a **harness setting**, not a GSD setting. The toggle lives in `.claude/s
Quick audit before a long phase:
- Are any browser / playwright tools enabled when this phase has no UI work?
-- Are any platform-specific tools (Mac-tools, Windows-tools, OS-specific) enabled when not needed?
+- Are any platform-specific tools enabled when not needed?
- Are any project-specific MCPs from a different project still enabled here?
-Each disabled server removes its schema from every subsequent turn for the rest of the session. Trimming MCPs **compounds** with `model_profile` tuning — both levers are additive, and MCP savings show up immediately across every subagent the orchestrator spawns.
+Each disabled server removes its schema from every subsequent turn. Trimming MCPs **compounds** with `model_profile` tuning — both levers are additive, and MCP savings show up immediately across every subagent the orchestrator spawns.
For the full audit, harness reference, and the composition note with `model_profile`, see [MCP Tool Schema Cost](../get-shit-done/references/context-budget.md#mcp-tool-schema-cost-harness-concern) in the bundled `context-budget.md` reference.
### Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
> **Codex CLI minimum supported version: `0.130.0`** (issue [#3562](https://github.com/open-gsd/gsd-core/issues/3562)).
->
-> Codex CLI [0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) (released 2026-05-08) removed extra-skills-roots discovery via [openai/codex#21485](https://github.com/openai/codex/pull/21485). From that version onward, Codex only discovers commands from `~/.codex/skills//SKILL.md` (user root), `/.codex/skills/` (cwd root), and registered plugin roots. The GSD installer writes `~/.codex/skills/gsd-/SKILL.md` directly so `$gsd-help`, `$gsd-new-project`, etc. are discoverable after restart.
->
-> **Earlier Codex CLI versions** (pre-0.130.0) had additional skill-root scanning that discovered the GSD agent/workflow files in alternate locations. GSD still installs the `~/.codex/skills/gsd-*` copies on those versions, which can show a duplicate listing alongside the legacy auto-discovered surface — restart Codex after install and either upgrade to ≥ 0.130.0 or accept the duplicate entries until you do.
-If you installed GSD for a non-Claude runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets `resolve_model_ids: "omit"` in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model.
+If you installed GSD for a non-Claude runtime, the installer already configured model resolution. No manual setup is needed — `resolve_model_ids: "omit"` is set automatically, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model.
-To assign different models to different agents on a non-Claude runtime, add `model_overrides` to `.planning/config.json` with fully-qualified model IDs that your runtime recognizes:
+To assign different models on a non-Claude runtime:
```json
{
@@ -1275,12 +688,8 @@ To assign different models to different agents on a non-Claude runtime, add `mod
}
```
-The installer auto-configures `resolve_model_ids: "omit"` for Gemini CLI, OpenCode, Kilo, and Codex. If you're manually setting up a non-Claude runtime, add it to `.planning/config.json` yourself.
-
#### Switching from Claude to Codex with one config change (#2517)
-If you want tiered models on Codex without writing a large `model_overrides` block, set `runtime: "codex"` and pick a profile:
-
```json
{
"runtime": "codex",
@@ -1288,96 +697,50 @@ If you want tiered models on Codex without writing a large `model_overrides` blo
}
```
-GSD will resolve each agent's tier (`opus`/`sonnet`/`haiku`) to the Codex-native model and reasoning effort defined in the runtime tier map (`gpt-5.4` xhigh / `gpt-5.3-codex` medium / `gpt-5.4-mini` medium). The Codex installer embeds both `model` and `model_reasoning_effort` into each agent's TOML automatically. To override a single tier, add `model_profile_overrides.codex.`. See [Runtime-Aware Profiles](CONFIGURATION.md#runtime-aware-profiles-2517).
-
-See the [Configuration Reference](CONFIGURATION.md#non-claude-runtimes-codex-opencode-gemini-cli-kilo) for the full explanation.
+See [Runtime-Aware Profiles](CONFIGURATION.md#runtime-aware-profiles-2517).
### Manual install / no-Node.js setup
-If you cannot run the GSD installer (e.g., Windows machine without Node.js or npm), you cannot use the source files in `agents/` directly. The source files are in Claude Code's native frontmatter format; each supported runtime requires a different shape. Copying them as-is into another runtime's config directory will produce schema validation errors.
-
-> The installer function responsible for OpenCode conversion is `convertClaudeToOpencodeFrontmatter` at `bin/install.js:5208`. It is the canonical reference for what must be transformed.
-
-#### OpenCode — required transformations
-
-OpenCode validates agent frontmatter against its own schema ([opencode.ai/docs/agents](https://opencode.ai/docs/agents)). The GSD source format is incompatible in two ways:
+If you cannot run the GSD installer, you cannot use the source files in `agents/` directly — they are in Claude Code's native frontmatter format. For OpenCode, two transformations are required:
| Field | GSD source format | OpenCode-valid format | Action |
|---|---|---|---|
-| `tools:` | `Read, Bash, Grep` (comma-string) | Not a frontmatter field in OpenCode | Remove the `tools:` line entirely |
-| `color:` | Plain CSS color name (e.g., `steelblue`) | Hex (`#4682b4`) or semantic name from OpenCode's fixed set | Convert to hex or remove |
+| `tools:` | `Read, Bash, Grep` (comma-string) | Not a frontmatter field | Remove the `tools:` line entirely |
+| `color:` | Plain CSS color name | Hex or OpenCode semantic name | Convert to hex or remove |
-The minimum viable manual transformation for a single agent file:
-
-1. Open the `.md` file from `agents/` in a text editor.
-2. Remove any `tools:` line from the YAML frontmatter block.
-3. Change `color:` to a hex value, or remove it.
-4. Save the file into `~/.config/opencode/agents/.md`.
-
-All other frontmatter fields (`description:`, `system:`, `model:`) are accepted by OpenCode without modification.
-
-#### Alternative: use a machine with Node.js to run the installer
-
-If you have access to any machine with Node.js — including WSL, a Linux VM, a CI runner, or a Docker container — you can run:
+**Alternative:** run the installer on any machine with Node.js:
```bash
npx @opengsd/gsd-core@latest --opencode --global
```
-This produces a correctly converted `~/.config/opencode/agents/` directory. Copy that directory to your Windows machine.
-
-#### Other runtimes
-
-The same principle applies to all non-Claude-Code runtimes. Each runtime has its own schema, and the installer handles each conversion. If you are manually installing for a runtime not covered above, review the relevant installer converter in `bin/install.js` (search for `convert*Frontmatter`) for the exact field transformations needed.
-
### Installing for Cline
-Cline uses a rules-based integration — GSD installs as `.clinerules` rather than slash commands.
-
```bash
-# Global install (applies to all projects)
-npx @opengsd/gsd-core --cline --global
-
-# Local install (this project only)
-npx @opengsd/gsd-core --cline --local
+npx @opengsd/gsd-core --cline --global # applies to all projects
+npx @opengsd/gsd-core --cline --local # this project only
```
-Global installs write to `~/.cline/`. Local installs write to `./.cline/`. No custom slash commands are registered — GSD rules are loaded automatically by Cline from the rules file.
-
### Installing for CodeBuddy
-CodeBuddy uses a skills-based integration.
-
```bash
npx @opengsd/gsd-core --codebuddy --global
```
-Skills are installed to `~/.codebuddy/skills/gsd-*/SKILL.md`.
-
### Installing for Qwen Code
-Qwen Code uses the same open skills standard as Claude Code 2.1.88+.
-
```bash
npx @opengsd/gsd-core --qwen --global
```
-Skills are installed to `~/.qwen/skills/gsd-*/SKILL.md`. Use the `QWEN_CONFIG_DIR` environment variable to override the default install path.
+### Installing for Prerelease Editions
-### Installing for Prerelease Editions (Next / Nightly / Insiders / Preview)
-
-Many supported runtimes ship a prerelease edition alongside their stable release — Windsurf Next, Cursor Nightly, VS Code Insiders, Codex preview channels, JetBrains EAP, and so on. Prerelease editions read from a sibling configuration directory, so the default install path won't reach them.
-
-GSD does not enumerate prerelease editions as separate named runtimes. They are accommodated through the existing `_CONFIG_DIR` environment variables and the free-string runtime policy (see [#2517](https://github.com/open-gsd/gsd-core/issues/2517)) — installs work, paths resolve, GSD operates. Prerelease editions are **best-effort and not separately tested** as part of release CI.
-
-**Pattern.** Set the runtime's `*_CONFIG_DIR` env var to the prerelease directory before running the installer:
+Set the runtime's `*_CONFIG_DIR` env var to the prerelease directory before running the installer:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
```
-Select the corresponding stable runtime in the installer prompt. Skills land in the prerelease directory; commands appear in the prerelease editor.
-
**Env-var reference for supported runtimes:**
| Runtime | Stable default | Override env var |
@@ -1389,7 +752,7 @@ Select the corresponding stable runtime in the installer prompt. Skills land in
| Copilot | `~/.copilot` | `COPILOT_CONFIG_DIR` |
| Cursor | `~/.cursor` | `CURSOR_CONFIG_DIR` |
| Windsurf | `~/.codeium/windsurf` | `WINDSURF_CONFIG_DIR` |
-| Antigravity | auto-detected: `~/.gemini/antigravity` (legacy), `~/.gemini/antigravity-ide`, or `~/.gemini/antigravity-cli` | `ANTIGRAVITY_CONFIG_DIR` |
+| Antigravity | auto-detected | `ANTIGRAVITY_CONFIG_DIR` |
| Augment | `~/.augment` | `AUGMENT_CONFIG_DIR` |
| Trae | `~/.trae` | `TRAE_CONFIG_DIR` |
| Qwen Code | `~/.qwen` | `QWEN_CONFIG_DIR` |
@@ -1397,15 +760,13 @@ Select the corresponding stable runtime in the installer prompt. Skills land in
| CodeBuddy | `~/.codebuddy` | `CODEBUDDY_CONFIG_DIR` |
| Cline | `~/.cline` | `CLINE_CONFIG_DIR` |
-If your runtime's prerelease channel is not listed, point the matching env var at its config directory and file an issue if the install fails for any reason other than the path mapping.
+### Using Claude Code with Non-Anthropic Providers
-### Using Claude Code with Non-Anthropic Providers (OpenRouter, Local)
-
-If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd-config --profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd-settings` → Model Profile → Inherit.
+Switch to the `inherit` profile: `/gsd-config --profile inherit`. This makes all agents use your current session model.
### Working on a Sensitive/Private Project
-Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git.
+Set `commit_docs: false` during `/gsd-new-project` or via `/gsd-settings`. Add `.planning/` to your `.gitignore`.
### GSD Update Overwrote My Local Changes
@@ -1413,53 +774,15 @@ Since v1.17, the installer backs up locally modified files to `gsd-local-patches
### Cannot Update via npm
-If `npx @opengsd/gsd-core` fails due to npm outages or network restrictions, see [docs/manual-update.md](manual-update.md) for a step-by-step manual update procedure that works without npm access.
-
-### Surface GSD Update Notifications Without GSD's Statusline
-
-GSD checks for new versions in the background and writes the result to `~/.cache/gsd/gsd-update-check.json`. By default, GSD's statusline (`hooks/gsd-statusline.js`) reads that cache and shows the update indicator. If you use a different statusline (for example `ccstatusline`) or none at all, the update info is invisible.
-
-**Opt-in fix:** during interactive install, when you decline (or keep your existing) statusline, the installer offers a one-time prompt:
-
-```text
-Optional: GSD update banner
- 1) No banner (default)
- 2) Install update banner
-```
-
-Choose `2` (or type `y`/`yes`) and the installer registers `hooks/gsd-update-banner.js` as a `SessionStart` hook. From the next session onward, GSD prints a one-line `systemMessage` only when the cache reports an update available:
-
-```text
-GSD update available: 1.39.0 → 1.40.0. Run /gsd-update.
-```
-
-The banner is silent when no update is available. If the cache file is corrupt, GSD emits one diagnostic line (`GSD update check failed.`) and stays silent for 24 hours so a broken cache does not nag every session.
-
-**Opt-out / removal:** delete the SessionStart hook entry that references `gsd-update-banner.js` from your runtime's `settings.json` (Claude Code: `~/.claude/settings.json`; Gemini: `~/.gemini/settings.json`). `npx @opengsd/gsd-core --uninstall` removes both the script and the registration in one pass.
-
-The banner is not offered when GSD's statusline is installed — that channel already surfaces update info, so re-prompting would be noise.
+See [docs/manual-update.md](manual-update.md) for a step-by-step manual update procedure.
### Workflow Diagnostics (`/gsd-forensics`)
-When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd-forensics` to generate a diagnostic report.
-
-**What it checks:**
-
-- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts)
-- Artifact integrity (missing or malformed planning files, broken cross-references)
-- State inconsistencies (ROADMAP status vs. actual file presence, config drift)
-
-**Output:** A diagnostic report written to `.planning/forensics/` with findings and suggested remediation steps.
+When a workflow fails in a non-obvious way, run `/gsd-forensics` to generate a diagnostic report covering git history anomalies, artifact integrity, and state inconsistencies. Output goes to `.planning/forensics/`.
### Executor Subagent Gets "Permission denied" on Bash Commands
-GSD's `gsd-executor` subagents need write-capable Bash access to a project's standard tooling — `git commit`, `bin/rails`, `bundle exec`, `npm run`, `uv run`, and similar commands. Claude Code's default `~/.claude/settings.json` only allows a narrow set of read-only git commands, so a fresh install will hit "Permission to use Bash has been denied" the first time an executor tries to make a commit or run a build tool.
-
-**Fix: add the required patterns to `~/.claude/settings.json`.**
-
-The patterns you need depend on your stack. Copy the block for your stack and add it to the `permissions.allow` array.
-
-#### Required for all stacks (git + gh)
+Add the required patterns to `~/.claude/settings.json`. Core patterns needed for all stacks:
```json
"Bash(git add:*)",
@@ -1480,89 +803,11 @@ The patterns you need depend on your stack. Copy the block for your stack and ad
"Bash(gh:*)"
```
-#### Rails / Ruby
-
-```json
-"Bash(bin/rails:*)",
-"Bash(bin/brakeman:*)",
-"Bash(bin/bundler-audit:*)",
-"Bash(bin/importmap:*)",
-"Bash(bundle:*)",
-"Bash(rubocop:*)",
-"Bash(erb_lint:*)"
-```
-
-#### Python / uv
-
-```json
-"Bash(uv:*)",
-"Bash(python:*)",
-"Bash(pytest:*)",
-"Bash(ruff:*)",
-"Bash(mypy:*)"
-```
-
-#### Node / npm / pnpm / bun
-
-```json
-"Bash(npm:*)",
-"Bash(npx:*)",
-"Bash(pnpm:*)",
-"Bash(bun:*)",
-"Bash(node:*)"
-```
-
-#### Rust / Cargo
-
-```json
-"Bash(cargo:*)"
-```
-
-**Example `~/.claude/settings.json` snippet (Rails project):**
-
-```json
-{
- "permissions": {
- "allow": [
- "Write",
- "Edit",
- "Bash(git add:*)",
- "Bash(git commit:*)",
- "Bash(git merge:*)",
- "Bash(git worktree:*)",
- "Bash(git rebase:*)",
- "Bash(git reset:*)",
- "Bash(git checkout:*)",
- "Bash(git switch:*)",
- "Bash(git restore:*)",
- "Bash(git stash:*)",
- "Bash(git rm:*)",
- "Bash(git mv:*)",
- "Bash(git fetch:*)",
- "Bash(git cherry-pick:*)",
- "Bash(git apply:*)",
- "Bash(gh:*)",
- "Bash(bin/rails:*)",
- "Bash(bin/brakeman:*)",
- "Bash(bin/bundler-audit:*)",
- "Bash(bundle:*)",
- "Bash(rubocop:*)"
- ]
- }
-}
-```
-
-**Per-project permissions (scoped to one repo):** If you prefer to allow these patterns for a single project rather than globally, add the same `permissions.allow` block to `.claude/settings.local.json` in your project root instead of `~/.claude/settings.json`. Claude Code checks project-local settings first.
-
-**Interactive guidance:** When an executor is blocked mid-phase, it will identify the exact pattern needed (e.g. `"Bash(bin/rails:*)"`) so you can add it and re-run `/gsd-execute-phase`.
-
-### Subagent Appears to Fail but Work Was Done
-
-A known workaround exists for a Claude Code classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded.
+**Per-project permissions:** add the same `permissions.allow` block to `.claude/settings.local.json` in your project root instead of `~/.claude/settings.json`.
### Parallel Execution Causes Build Lock Errors
-If you see pre-commit hook failures, cargo lock contention, or 30+ minute execution times during parallel wave execution, this is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26 — parallel agents use `--no-verify` on commits and the orchestrator runs hooks once after each wave. If you're on an older version, add this to your project's `CLAUDE.md`:
+GSD handles this automatically since v1.26. If you're on an older version, add to your project's `CLAUDE.md`:
```markdown
## Git Commit Rules for Agents
@@ -1571,15 +816,10 @@ All subagent/executor commits MUST use `--no-verify`.
To disable parallel execution entirely: `/gsd-settings` → set `parallelization.enabled` to `false`.
-### Windows: Installation Crashes on Protected Directories
-
-If the installer crashes with `EPERM: operation not permitted, scandir` on Windows, this is caused by OS-protected directories (e.g., Chromium browser profiles). Fixed since v1.24 — update to the latest version. As a workaround, temporarily rename the problematic directory before running the installer.
-
---
## Recovery Quick Reference
-
| Problem | Solution |
| ------------------------------------ | ------------------------------------------------------------------------ |
| Lost context / new session | `/gsd-resume-work` or `/gsd-progress` |
@@ -1592,18 +832,15 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo
| Plan doesn't match your vision | `/gsd-discuss-phase [N]` then re-plan |
| Costs running high | `/gsd-config --profile budget` and `/gsd-settings` to toggle agents off |
| Update broke local changes | `/gsd-update --reapply` |
-| Want session summary for stakeholder | `/gsd-pause-work --report` |
-| Don't know what step is next | `/gsd-progress --next` |
+| Want session summary for stakeholder | `/gsd-pause-work --report` |
+| Don't know what step is next | `/gsd-progress --next` |
| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
-
---
## Project File Structure
-For reference, here is what GSD creates in your project:
-
-```
+```text
.planning/
PROJECT.md # Project vision and context (always loaded)
REQUIREMENTS.md # Scoped v1/v2 requirements with IDs
@@ -1639,3 +876,12 @@ For reference, here is what GSD creates in your project:
XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
```
+
+---
+
+## Related
+
+- [Docs index](README.md)
+- [Commands](COMMANDS.md)
+- [Configuration](CONFIGURATION.md)
+- [The phase loop](explanation/the-phase-loop.md)
diff --git a/docs/adr/22-plan-drift-guard.md b/docs/adr/22-plan-drift-guard.md
index a1c0eeee9..10c139dad 100644
--- a/docs/adr/22-plan-drift-guard.md
+++ b/docs/adr/22-plan-drift-guard.md
@@ -74,7 +74,7 @@ Locked sub-decisions:
- **Hard-block on any MISSING (as originally proposed).** Rejected for rung 0–1: false positives from dynamic/re-exported/generated symbols would block valid plans and get the default-on guard switched off. Retained only for rung >=3.
## References
-- Issue: open-gsd/gsd-core#22 (migrated from gsd-build/get-shit-done#3813)
+- Issue: open-gsd/gsd-core#22 (migrated from open-gsd/gsd-core#3813)
- Relates to #3802 (GitNexus first-class code intelligence) — rung 4 backend
- arXiv:2409.20550 — hallucination taxonomy + RAG mitigation (modest gains)
- arXiv:2502.05111 — grammar-constrained decoding (soft vs hard constraints)
diff --git a/docs/context-monitor.md b/docs/context-monitor.md
index e398b7588..da530e1e3 100644
--- a/docs/context-monitor.md
+++ b/docs/context-monitor.md
@@ -60,54 +60,9 @@ GSD's `/gsd-pause-work` command saves execution state. The WARNING message sugge
## Setup
-Both hooks are automatically registered during `npx @opengsd/gsd-core` installation:
+Both hooks are registered automatically during `npx @opengsd/gsd-core` installation — no manual steps are needed under normal circumstances. For hook configuration details, threshold overrides, and manual registration examples, see [Configuration](CONFIGURATION.md).
-- **Statusline** (writes bridge file): Registered as `statusLine` in settings.json
-- **Context Monitor** (reads bridge file): Registered as `PostToolUse` hook in settings.json (`AfterTool` for Gemini)
-
-Manual registration should use the absolute Node executable path that ran the installer. On Windows PowerShell, prefix the command with `&` when that executable path is quoted.
-
-Manual registration in `~/.claude/settings.json` (Claude Code):
-
-```json
-{
- "statusLine": {
- "type": "command",
- "command": "\"/usr/local/bin/node\" \"/Users/me/.claude/hooks/gsd-statusline.js\""
- },
- "hooks": {
- "PostToolUse": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "\"/usr/local/bin/node\" \"/Users/me/.claude/hooks/gsd-context-monitor.js\""
- }
- ]
- }
- ]
- }
-}
-```
-
-For Gemini CLI (`~/.gemini/settings.json`), use `AfterTool` instead of `PostToolUse`:
-
-```json
-{
- "hooks": {
- "AfterTool": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "& \"C:/Program Files/nodejs/node.exe\" \"C:/Users/me/.gemini/hooks/gsd-context-monitor.js\""
- }
- ]
- }
- ]
- }
-}
-```
+As a brief reference: the statusline hook registers as `statusLine` in `settings.json`; the context monitor (`gsd-context-monitor.js`) registers as a `PostToolUse` hook (or `AfterTool` for Gemini CLI). Both entries use the absolute Node executable path that ran the installer. On Windows PowerShell, prefix quoted executable paths with `&`.
## Safety
@@ -115,3 +70,11 @@ For Gemini CLI (`~/.gemini/settings.json`), use `AfterTool` instead of `PostTool
- It never blocks tool execution — a broken monitor should not break the agent's workflow
- Stale metrics (older than 60s) are ignored
- Missing bridge files are handled gracefully (subagents, fresh sessions)
+
+---
+
+## Related
+
+- [Architecture](ARCHITECTURE.md)
+- [Configuration](CONFIGURATION.md)
+- [docs index](README.md)
diff --git a/docs/explanation/context-engineering.md b/docs/explanation/context-engineering.md
new file mode 100644
index 000000000..879327e3f
--- /dev/null
+++ b/docs/explanation/context-engineering.md
@@ -0,0 +1,90 @@
+# Context engineering
+
+> Why GSD Core exists, and the problem it is designed to solve.
+
+---
+
+## The problem: context rot
+
+Every AI coding session starts fresh. The model reads your question, reasons over it, and replies. But a session is rarely one exchange. You ask follow-up questions, paste error messages, iterate on code, redirect the model when it drifts. Each turn adds tokens to the context window — the finite buffer of text the model can "see" at once.
+
+As that window fills, something subtle happens. The model does not fail loudly. It keeps answering. But the quality of its answers quietly degrades. Early instructions get pushed towards the edge of what it can attend to. Nuance from the first few exchanges — the constraints you stated, the architecture you agreed on, the edge cases you flagged — competes for attention against everything that came later. Researchers call this **context rot**.
+
+Context rot manifests in several ways:
+
+- The model starts contradicting earlier decisions it acknowledged.
+- Code style drifts away from the conventions established at session start.
+- Plans begin to ignore requirements that were clearly stated but are now buried deep in the history.
+- The model hallucinates file names or function signatures it had correct twenty messages ago.
+
+None of this is a model bug. It is a fundamental property of how transformer attention works over long sequences. The model is not forgetting — it never "remembered" in the human sense. It is weighting relevance across a finite window, and as that window fills with accumulated noise, signal-to-noise degrades.
+
+The naive response is to `/clear` and start over. But that loses continuity. You have to re-explain context, re-paste relevant files, re-state constraints. The session essentially resets to zero.
+
+---
+
+## GSD Core's answer: fresh-context subagents
+
+GSD Core's central insight is that *most* of the work in a coding session does not need to happen in the main context at all. Research, planning, code writing, and verification are each discrete, bounded tasks. Each can be handed to a specialised subagent that starts with a clean, carefully scoped context window — and reports its result back to a thin orchestrator that stays lean.
+
+This is not a workaround for context rot. It is a structural solution.
+
+The orchestrator — your main session — never touches source files. It spawns agents, collects their results, updates shared state, and routes to the next step. Because it does very little itself, its context window grows slowly and predictably. The heavy work happens in agents that each start fresh, receive exactly the context they need for their task, and terminate when done.
+
+Consider what this means in practice. When you run `/gsd-plan-phase`, the orchestrator:
+
+1. Loads a compact JSON context payload (project summary, phase goal, relevant config).
+2. Spawns a researcher agent with a 200k-token clean window.
+3. Spawns a planner agent with the research output and phase requirements.
+4. Spawns a plan-checker agent to verify the plan before execution.
+
+Each agent operates at full capacity, unencumbered by the accumulated history of your session. When the planner writes its `PLAN.md` files to `.planning/phases/`, that output becomes a durable artefact — not a fragile memory in a shared context window.
+
+---
+
+## Spec-driven development and meta-prompting
+
+Context engineering alone is not enough. If an agent starts fresh but receives vague instructions, it will produce vague output. GSD Core pairs fresh-context subagents with two complementary disciplines:
+
+**Spec-driven development** means that every phase produces structured artefacts before execution begins. A `CONTEXT.md` captures implementation decisions from the Discuss step. A `RESEARCH.md` records what the researcher found. A `PLAN.md` breaks work into discrete, dependency-ordered tasks with explicit acceptance criteria. By the time an executor agent touches a file, it has a precise specification to work from — not a re-interpretation of a long conversation.
+
+**Meta-prompting** means the agent definitions themselves are carefully engineered prompts, not ad-hoc instructions. The files in `get-shit-done/workflows/` and `agents/` encode hard-won knowledge about how to scope tasks, what to verify, and when to escalate to a human checkpoint. The user does not need to re-explain this knowledge in every session; it is baked into the system's own prompts.
+
+The combination is deliberate. Fresh context ensures each agent reasons clearly. Spec-driven artefacts ensure each agent reasons about the *right* thing. Meta-prompting ensures each agent knows *how* to reason about it well.
+
+---
+
+## The role of `.planning/`
+
+Context engineering requires that knowledge survive context resets. GSD Core uses the file system for this. Every meaningful output is written to `.planning/` as human-readable Markdown or JSON. This means:
+
+- Restarting your session (or the model crashing) does not lose work.
+- Any subsequent agent can read prior artefacts directly, without depending on a shared conversation history.
+- You can inspect, edit, or commit planning artefacts to git — they are plain text, not opaque state in a database.
+
+`STATE.md` is the spine of this system. It records the project's current position (which milestone, which phase, which plans are complete), active decisions and blockers, and progress metrics. When any workflow starts, it reads `STATE.md` to orient itself. When any workflow finishes a meaningful step, it writes back to `STATE.md`. Agents do not rely on memory; they rely on the file.
+
+---
+
+## Trade-offs
+
+Honesty about trade-offs matters here.
+
+**Overhead.** The phase loop introduces real friction. Running `/gsd-discuss-phase`, `/gsd-plan-phase`, and `/gsd-execute-phase` as separate steps takes more elapsed time than typing "write this feature" into a plain session. For a small, well-understood change, that overhead is not justified.
+
+**Latency.** Spawning multiple subagents with fresh context is slower than a single in-context edit. Research, planning, and execution each incur round-trip costs.
+
+**Ceremony for simple tasks.** If you need to rename a variable, fix a typo, or add a missing import, the phase loop is overkill. GSD Core provides `/gsd-quick` and `/gsd-fast` for ad-hoc work that does not warrant a full phase. See [Handle quick and fast tasks](../how-to/handle-quick-and-fast-tasks.md).
+
+The phase loop pays for itself when the work is complex enough that context rot is a real risk — multi-file features, cross-cutting refactors, work that spans hours or sessions. For everything else, reach for the lighter primitive.
+
+A useful rule of thumb: if the task could be fully specified in a single, short prompt and completed in one agent turn without further clarification, skip the phase loop. If the task requires research, involves files you have not read recently, or depends on decisions that are not yet settled, the phase loop protects you.
+
+---
+
+## Related
+
+- [The phase loop](the-phase-loop.md) — how the Discuss → Plan → Execute → Verify → Ship cycle puts context engineering into practice
+- [Multi-agent orchestration](multi-agent-orchestration.md) — how subagents are spawned, scoped, and coordinated
+- [Architecture](../ARCHITECTURE.md) — system architecture, agent model, and data flow
+- [docs index](../README.md)
diff --git a/docs/explanation/multi-agent-orchestration.md b/docs/explanation/multi-agent-orchestration.md
new file mode 100644
index 000000000..a60b45d62
--- /dev/null
+++ b/docs/explanation/multi-agent-orchestration.md
@@ -0,0 +1,234 @@
+# Multi-agent orchestration in GSD Core
+
+> **Explanation** — This document describes *why* GSD Core is designed around
+> multi-agent orchestration and *how the pieces fit together*. It is not a
+> step-by-step guide. For configuration, see
+> [Configure model profiles](../how-to/configure-model-profiles.md) and the
+> [Configuration reference](../CONFIGURATION.md). For the full agent roster,
+> see [Inventory](../INVENTORY.md).
+
+---
+
+## The problem this design solves
+
+AI coding agents degrade. Not because the model gets worse, but because the
+*context window fills up*. As a conversation grows, earlier decisions and code
+get pushed out or diluted by the noise of intermediate steps. By the time an
+agent writes the fifth file in a complex task, it may have already forgotten
+the constraint stated in the first message. This is sometimes called *context
+rot*.
+
+GSD Core's multi-agent design is a direct response to that problem. Instead of
+one long-running agent carrying the whole session, a thin orchestrator spawns
+short-lived specialised agents, each with a **fresh 200 K-token context window**
+and *only the artifacts it needs* to do its specific job. The orchestrator
+never does heavy lifting itself; it loads context, spawns the right agent,
+collects the result, and updates shared state in `.planning/`.
+
+---
+
+## The orchestrator → agent pattern
+
+Every workflow in `get-shit-done/workflows/` follows the same shape:
+
+```text
+Orchestrator (workflow .md file)
+ │
+ ├── Load context
+ │ gsd-tools.cjs init
+ │ → JSON: project info, config, state, phase details
+ │
+ ├── Resolve model
+ │ gsd-tools.cjs resolve-model
+ │ → opus | sonnet | haiku | inherit
+ │
+ ├── Spawn specialised agent (Task/SubAgent call)
+ │ ├── Agent definition (agents/*.md)
+ │ ├── Context payload (init JSON)
+ │ ├── Model assignment
+ │ └── Tool permissions
+ │
+ ├── Collect result
+ │
+ └── Update state
+ gsd-tools.cjs state update / state patch / state advance-plan
+```
+
+The orchestrator is deliberately thin. It does not reason about the domain,
+does not write code, and does not interpret results beyond routing them to the
+next step. That boundary keeps each layer's responsibility clear and prevents
+the orchestrator's context from accumulating domain noise.
+
+### The agent roster
+
+GSD Core's agents fall into functional categories that map onto the
+research → plan → execute → verify pipeline:
+
+| Category | Agents | Typical parallelism |
+|---|---|---|
+| Researchers | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4 parallel (stack, features, architecture, pitfalls) |
+| Synthesisers | `gsd-research-synthesizer` | Sequential, after researchers complete |
+| Planners | `gsd-planner`, `gsd-roadmapper` | Sequential |
+| Checkers | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | Sequential, up to 3 revision iterations |
+| Executors | `gsd-executor` | Parallel within a wave, sequential across waves |
+| Verifiers | `gsd-verifier` | Sequential, after all executors complete |
+| Mappers | `gsd-codebase-mapper` | 4 parallel sub-probes |
+| Auditors | `gsd-ui-auditor`, `gsd-security-auditor` | Sequential |
+
+Each agent definition (in `agents/*.md`) declares its allowed tool access,
+purpose, and colour for terminal output. An agent that only needs to read files
+and write a single output document gets exactly those permissions — no Bash
+execution, no access to broader state. That constraint is intentional: it
+keeps the blast radius small if an agent behaves unexpectedly.
+
+For the complete 31-agent roster, see [Inventory](../INVENTORY.md#agents-31-shipped).
+
+---
+
+## Wave-based parallel execution
+
+The most visible expression of multi-agent design is how `/gsd-execute-phase`
+handles a set of plans that may depend on one another.
+
+Before spawning any executor, the orchestrator performs a **wave analysis**:
+it reads the dependency declarations in each `PLAN.md` file and groups plans
+into waves. Plans with no declared dependencies form Wave 1 and run in
+parallel. Plans that depend on Wave 1 form Wave 2, and so on.
+
+```text
+Plan 01 (no deps) ─┐
+Plan 02 (no deps) ─┤─── Wave 1 (parallel)
+Plan 03 (depends: 01) ─┤─── Wave 2 (waits for Wave 1)
+Plan 04 (depends: 02) ─┘
+Plan 05 (depends: 03, 04) ─── Wave 3 (waits for Wave 2)
+```
+
+Each executor within a wave:
+
+- receives a fresh context window (200 K tokens, or up to 1 M on capable models)
+- receives the specific `PLAN.md` it is responsible for
+- receives project context (`PROJECT.md`, `STATE.md`)
+- receives phase context (`CONTEXT.md`, `RESEARCH.md` if available)
+- produces atomic git commits on completion
+- writes a `SUMMARY.md` describing what was built
+
+After all executors in a wave finish, the orchestrator runs the pre-commit
+hook once for the wave as a whole. Executors commit with `--no-verify` to
+prevent build-lock contention (for example, Cargo lock fights in Rust
+projects) when multiple agents commit in parallel. The hook therefore runs
+once per wave rather than once per commit.
+
+### Parallel commit safety
+
+Two mechanisms prevent write conflicts when multiple executors run
+simultaneously:
+
+1. **Atomic lock on `STATE.md`** — Every write to `STATE.md` uses a
+ lockfile (`STATE.md.lock`) with `O_EXCL` atomic creation. This prevents
+ the read-modify-write race where two agents each read the file, modify
+ different fields, and the later writer overwrites the earlier one's
+ changes. Stale locks (older than 10 seconds) are automatically cleared.
+
+2. **Per-wave hook run** — Rather than each executor running pre-commit hooks
+ independently (which can cause file-level contention on shared build
+ artefacts), the orchestrator runs `git hook run pre-commit` once after
+ every wave completes.
+
+---
+
+## Adaptive context enrichment for large-window models
+
+Standard 200 K context windows are enough for an executor to implement a
+single focused plan. When the configured `context_window` is 500 K tokens or
+larger (for example, when using Opus 4.6 or Sonnet 4.6 in 1 M-class mode),
+the orchestrator automatically enriches subagent prompts with additional
+context that would not fit in a standard window:
+
+- **Executor agents** receive prior-wave `SUMMARY.md` files and the phase
+ `CONTEXT.md`/`RESEARCH.md`, giving them cross-plan awareness within the
+ phase
+- **Verifier agents** receive all `PLAN.md`, `SUMMARY.md`, and `CONTEXT.md`
+ files plus `REQUIREMENTS.md`, enabling history-aware verification
+
+This enrichment is conditional on the `context_window` value in
+`config.json`. On standard-window configurations, prompts use truncated
+versions with cache-friendly ordering to maximise token efficiency.
+
+---
+
+## Why this design — the connection to context engineering
+
+The orchestrator → agent pattern only makes sense as part of a broader
+approach to *context engineering*: the idea that what an AI agent gets in its
+context window matters as much as the model tier or prompt quality. See
+[Context engineering](context-engineering.md) for the full treatment.
+
+Multi-agent orchestration operationalises context engineering in two ways:
+
+**Context isolation.** Each agent receives only what it needs. A researcher
+gets the project description and domain questions; it does not get the full
+planning history. A verifier gets every plan and summary; it does not get the
+raw research. Isolation keeps each agent's context dense with signal rather
+than diluted by noise from other pipeline stages.
+
+**Context hygiene across sessions.** Because all state lives in
+`.planning/` as human-readable Markdown and JSON (not in any agent's context
+window), GSD workflows survive context resets (`/clear`), tab switches, and
+multi-day breaks. The next agent always starts from persisted, verified
+artifacts rather than from a reconstructed memory of a long conversation.
+
+---
+
+## Trade-offs
+
+Multi-agent orchestration is not free.
+
+**Coordination overhead.** Each agent spawn is a round-trip: the orchestrator
+must format a prompt, hand off context, wait for the subagent to complete
+(typically 1–5 minutes), and then parse the result. A single capable agent
+working in one context would finish faster for simple tasks. GSD mitigates
+this by making parallelism the default wherever dependencies permit — the
+four researchers in a `plan-phase` run simultaneously, not sequentially.
+
+**Opacity during execution.** While a subagent is running, its work is
+invisible to the parent session. There is no live progress stream. This is a
+deliberate consequence of the fresh-context design: the subagent is operating
+in its own context window. The orchestrator shows a liveness note on the
+spawn line ("runs in a subagent — no output until it returns") to set
+expectations.
+
+**Context stitching cost.** Packaging the right artifacts for each agent
+requires the orchestrator to spend tokens assembling and transmitting context
+payloads. This is the cost of isolation. The `gsd-tools.cjs init` handler
+produces a JSON payload that balances completeness with token budget, applying
+cache-friendly ordering so that the stable parts of the payload (project
+definition, config) hit the cache on repeat invocations.
+
+**Model cost amplification.** Running five agents in parallel at Opus tier
+costs more than running one. The model profile system (`model_profiles.md`,
+resolved per agent by `model-profiles.cjs`) lets you assign cheaper tiers to
+less critical agents. The `dynamic_routing` feature further reduces cost by
+starting every agent on a cheaper tier and escalating only on a soft failure.
+See [Configuration](../CONFIGURATION.md) for the full options.
+
+In return for these costs, the design buys *consistent quality across large
+phases*. An executor writing the tenth file in a 400-line plan does not
+degrade because its context is fresh. A verifier checking twenty requirements
+does not forget the first ten because it received all of them as structured
+input rather than conversation history.
+
+---
+
+## Related
+
+- [Context engineering](context-engineering.md) — the upstream principle that
+ motivates this design
+- [Configure model profiles](../how-to/configure-model-profiles.md) — how to
+ assign model tiers per agent
+- [Configuration reference](../CONFIGURATION.md) — full `config.json` schema
+ including `models`, `model_overrides`, `dynamic_routing`, and
+ `context_window`
+- [Inventory](../INVENTORY.md) — authoritative agent roster and workflow list
+- [Architecture](../ARCHITECTURE.md#agent-model) — implementation-level detail
+ on the orchestrator → agent pattern and wave execution model
+- [Docs index](../README.md)
diff --git a/docs/explanation/security-model.md b/docs/explanation/security-model.md
new file mode 100644
index 000000000..b0d6046bd
--- /dev/null
+++ b/docs/explanation/security-model.md
@@ -0,0 +1,252 @@
+# GSD Core security model
+
+> **Explanation** — This document describes *why* GSD Core has the security
+> posture it does and *how the layers fit together*. It is not a reference for
+> every hook parameter. For the `/gsd-secure-phase` command and its options,
+> see [Commands](../COMMANDS.md). For the implementation-level hook
+> architecture, see [Architecture § Hook System](../ARCHITECTURE.md#hook-system).
+> For the org-wide security baseline (scanner controls, incident checklists,
+> ownership model), see [SECURITY.md](../../SECURITY.md).
+
+---
+
+## Why AI-driven development needs a dedicated security posture
+
+A conventional code editor does not execute arbitrary packages on your behalf.
+GSD Core does. The research → plan → execute pipeline automates the full path
+from "name a package" to "run `npm install `", from "write a
+planning artifact" to "use that artifact as an LLM system prompt". Each
+automation step removes a human from the loop — and each removal is a
+potential attack surface.
+
+GSD Core's security model is built around one organising principle:
+**defence in depth**. No single control is assumed to be perfect. Several
+overlapping layers each reduce a distinct class of risk, and together they
+make the attack surface substantially harder to exploit without eliminating
+it entirely. The honest summary at the end of this document explains what the
+system cannot protect against.
+
+---
+
+## Layer 1 — Supply-chain protection: the Package Legitimacy Gate
+
+### The threat
+
+AI models hallucinate package names. This is not a fringe failure mode: 2025
+research documents roughly 20 % of AI-generated package references as
+hallucinated names that do not correspond to legitimate packages. A subset of
+those hallucinated names — approximately 43 % in the same research — recur
+consistently across prompts, meaning an attacker can observe which names AI
+tools commonly produce and pre-register those names on npm, PyPI, or
+crates.io with malicious post-install scripts. The technique is called
+*slopsquatting*.
+
+The insidious quality of slopsquatting is that a hallucinated name that passes
+`npm view` *looks legitimate*. The registry entry proves only that someone
+registered the name — not that the package does what the AI said it does, not
+that it has any legitimate users, and not that its install scripts are safe.
+Without a gate, a hallucinated name would flow undetected through GSD's
+researcher → planner → executor pipeline and eventually run as
+`npm install ` on your machine.
+
+### How the gate works
+
+The gate operates across three pipeline stages:
+
+**Research stage.** When `gsd-phase-researcher` recommends external packages,
+it runs `slopcheck install --json` against each one. The results are
+written to a `## Package Legitimacy Audit` table in `RESEARCH.md`. Packages
+tagged `[SLOP]` (high-confidence hallucination or attacker-registered) are
+**stripped from `RESEARCH.md` entirely** before the file is saved. They never
+reach the planner.
+
+**Planning stage.** `gsd-planner` reads the Audit table. For any package
+tagged `[SUS]` (suspicious: newly registered, low download count, no source
+repository, or naming pattern close to a popular package) or `[ASSUMED]`
+(sourced from WebSearch rather than direct registry verification), the planner
+**inserts a `checkpoint:human-verify` task** before the install step. The
+checkpoint includes a direct link to the registry page and specific things to
+look for: maintainer history, issue-tracker activity, absence of suspicious
+install scripts.
+
+**Execution stage.** If an install fails, `gsd-executor` **surfaces a
+checkpoint and stops**. It does not silently try an alternative package name —
+which could itself be malicious. This is an explicit rule in the executor's
+behaviour (RULE 3 in the executor agent definition).
+
+### Why WebSearch packages are always `[ASSUMED]`
+
+Package names discovered through WebSearch are tagged `[ASSUMED]` regardless
+of whether `npm view` succeeds. A package that exists on the registry is not
+the same as a package that is safe to install. `npm view` proves registration,
+not legitimacy. The `[ASSUMED]` tag triggers the same human-verify checkpoint
+as `[SUS]`, ensuring that any unverified web-discovered recommendation always
+gets a human review before installation.
+
+### Ecosystem coverage
+
+The researcher uses registry-specific verification commands rather than a
+single generic check:
+
+- Node.js: `npm view`
+- Python: `pip index versions`
+- Rust: `cargo search`
+
+This covers cross-ecosystem hallucination, which occurs at roughly 9 %
+according to 2025 USENIX research — cases where an AI recommends a package
+that exists in one ecosystem but not the one actually in use.
+
+### Graceful degradation
+
+If `slopcheck` is unavailable (not installed, or the pip install fails at
+research time), GSD applies the strictest possible fallback: **every
+recommended package is tagged `[ASSUMED]`**, and the planner gates every
+install with a `checkpoint:human-verify` task. Research and planning proceed
+normally — the system never hard-fails on a missing tool dependency. This
+is intentionally stricter than the normal flow: slopcheck unavailability means
+every package install gets a human checkpoint.
+
+The `slopcheck` tool is MIT-licensed and pip-installable. If it is ever
+abandoned, the `[ASSUMED]`-gate fallback ensures human-checkpoint coverage is
+maintained regardless.
+
+---
+
+## Layer 2 — Prompt injection defences
+
+### The threat
+
+GSD Core generates Markdown files that become LLM system prompts. The
+research pipeline reads external web content; the planning pipeline
+incorporates user-supplied text (`--text-file`, `--prd`); the execution
+pipeline writes planning artifacts that are later re-read as agent context.
+Any user-controlled text flowing into these artifacts is a potential
+**indirect prompt injection** vector — an attacker-controlled string that,
+once inside a system prompt, attempts to override the agent's instructions or
+exfiltrate information.
+
+### How the defences work
+
+GSD Core addresses prompt injection at three levels.
+
+**Input validation (`security.cjs`).** The `get-shit-done/bin/lib/security.cjs`
+module is the central security utility. It provides:
+
+- Path traversal prevention: user-supplied file paths (`--text-file`, `--prd`)
+ are validated to resolve within the project directory, with macOS
+ `/var` → `/private/var` symlink resolution handled explicitly
+- Prompt injection detection: known injection patterns (role overrides,
+ instruction bypasses, system tag injections) are scanned in user-supplied
+ text before it enters any planning artifact
+- Safe JSON parsing: a wrapper that prevents prototype-pollution attacks via
+ crafted JSON payloads
+- Shell argument validation: arguments passed to subshell commands are
+ validated before use
+
+**Runtime hook: `gsd-prompt-guard.js`.** This hook fires on every Write or
+Edit call that targets `.planning/` files. It scans the content being written
+for the same injection patterns as `security.cjs` (a subset inlined directly
+into the hook for independence — the hook does not `require()` the module, so
+it runs even if the module path changes). Detection is **advisory-only**: the
+hook logs the finding but does not block the write. The rationale is that a
+false-positive block on a legitimate planning write would be more disruptive
+than a missed injection in a secondary scan layer.
+
+**Runtime hook: `gsd-read-injection-scanner.js`.** This hook fires on the
+output of every Read tool call. It scans the *content that was just read* for
+injected instructions in untrusted content — catching cases where an attacker
+has embedded instructions in a file that GSD is about to incorporate into an
+agent's context.
+
+**CI scanner.** `prompt-injection-scan.test.cjs` scans all agent, workflow,
+and command files for embedded injection vectors as part of the test suite.
+This catches injection attempts in the GSD source itself — for example, a
+supply-chain attack that modified a workflow file to add a role-override
+instruction.
+
+### Read Injection Scanner vs Prompt Guard
+
+The two hooks cover complementary surfaces. `gsd-prompt-guard.js` watches
+*writes to planning artifacts* — it catches injection being planted.
+`gsd-read-injection-scanner.js` watches *reads of any file* — it catches
+injection being ingested from external content (a dependency's README, a
+third-party config file, a user-provided document). Together they bracket
+the ingest → store → re-read lifecycle.
+
+---
+
+## Layer 3 — Repository and dependency integrity
+
+Upstream of GSD's runtime behaviour, the `open-gsd` organisation enforces
+controls at the repository and package level. These are documented in full in
+[`docs/security/baseline.md`](../security/baseline.md) and are summarised
+here for completeness.
+
+**Dependency integrity.** All third-party dependencies are pinned via
+`package-lock.json` and verified against published checksums before install.
+A `scripts/check-npm-integrity.cjs` gate detects invalid versions, missing
+packages, and extraneous packages at CI time. This mitigates dependency
+confusion and typosquatting attacks against GSD's own dependencies.
+
+**Secret scanning.** Every commit and PR is scanned for hardcoded secrets.
+Intentional test fixtures must be annotated with the project-standard
+exclusion grammar (see `SECURITY.md` for the annotation format). Un-annotated
+suppressions fail CI.
+
+**Locale-safe text scanning.** Output and user-facing strings are scanned for
+Unicode homoglyphs, bidirectional override characters, and invisible Unicode —
+the class of attacks documented in CVE-2021-42574 ("Trojan Source") that can
+hide malicious content in diffs.
+
+---
+
+## Trade-offs and limits
+
+The security model described here meaningfully reduces the attack surface for
+AI-driven development. It does not eliminate supply-chain risk.
+
+**What the Package Legitimacy Gate reduces:** The probability that a
+hallucinated or attacker-registered package reaches `npm install` without
+a human checkpoint. The `[SLOP]` gate removes high-confidence bad packages
+entirely; the `[SUS]` / `[ASSUMED]` gates require human review before
+execution. This substantially raises the cost of a successful slopsquatting
+attack.
+
+**What the Package Legitimacy Gate does not eliminate:** A legitimate package
+that is later compromised (account takeover, dependency confusion in its own
+tree) is not caught by slopcheck, which checks registration signals at
+research time. Lock files and `npm audit` at the dependency-integrity layer
+are the controls for that class of attack.
+
+**What the prompt injection defences reduce:** The probability that
+user-controlled text in planning artifacts successfully overrides agent
+instructions. Pattern-matching on known injection forms catches the
+common cases; novel jailbreaks or low-signal injections may pass undetected.
+The advisory-only posture means detection is logged but not blocked — a
+deliberate choice that preserves workflow continuity at the cost of
+not hard-stopping on a detection.
+
+**What the prompt injection defences do not eliminate:** A sufficiently
+creative injection that does not match known patterns, or an injection that
+arrives through a channel the hooks do not cover (for example, content injected
+into a dependency's published README that is read by a subagent browsing
+documentation). Defence in depth means each layer makes the attack harder,
+not that any single layer makes it impossible.
+
+**Reporting vulnerabilities.** Report via private GitHub security advisory at
+`https://github.com/open-gsd/gsd-core/security/advisories/new`. Do not open
+public issues. See [SECURITY.md](../../SECURITY.md) for the response timeline
+and disclosure policy.
+
+---
+
+## Related
+
+- [Commands](../COMMANDS.md) — includes `/gsd-secure-phase` and
+ `/gsd-code-review` with security-relevant flags
+- [Architecture § Hook System](../ARCHITECTURE.md#hook-system) —
+ implementation detail on every hook, its event trigger, and safety properties
+- [SECURITY.md](../../SECURITY.md) — vulnerability reporting, org-wide
+ security baseline, secret-scan exclusion governance, and dependency
+ integrity verification
+- [Docs index](../README.md)
diff --git a/docs/explanation/the-phase-loop.md b/docs/explanation/the-phase-loop.md
new file mode 100644
index 000000000..9e2ff1bc4
--- /dev/null
+++ b/docs/explanation/the-phase-loop.md
@@ -0,0 +1,129 @@
+# The phase loop
+
+> The central mental model for how GSD Core organises work.
+
+---
+
+## What the loop is
+
+GSD Core structures all development work as a repeating cycle:
+
+```text
+Discuss → (UI design) → Plan → Execute → Verify → Ship
+```
+
+Every unit of work — called a **phase** — moves through these steps in order. The loop is not a formality. Each step exists because it guards against a specific class of failure that the previous step alone cannot prevent.
+
+This document explains *why* the loop is shaped the way it is. For instructions on running each step, see the how-to guides linked at the bottom.
+
+---
+
+## Why each step exists
+
+### Discuss
+
+Planning cannot begin until you know *how* to build the thing, not just *what* to build. The phase goal in `ROADMAP.md` describes the outcome. The Discuss step captures the implementation decisions that shape the path to that outcome: which libraries, which error-handling strategy, whether a feature is per-route or global, how edge cases should behave.
+
+Without a Discuss step, the planner must make these calls itself. Sometimes it guesses right. Often it guesses plausibly but wrongly — producing a plan that is coherent but misaligned with your actual preferences. By the time execution is done and you realise the error, you are unwinding significant work.
+
+The Discuss step is deliberately lightweight. It is a conversation, not a specification exercise. The output is a `CONTEXT.md` in the phase directory: a structured record of decisions that the planner, executor, and verifier can all read. The conversation takes a few minutes; it can save hours of rework.
+
+### UI design (optional)
+
+For phases with a visual component, there is an optional `/gsd-ui-phase` step between Discuss and Plan. It produces a `UI-SPEC.md` — a design contract that describes layout, interaction, and visual behaviour before any code is written. This step is worth running when the UI is complex enough that ambiguity in the design would produce divergent implementation choices. A clear design contract is far cheaper to write than to re-implement.
+
+### Plan
+
+The Plan step does the research, decomposition, and structural thinking that execution requires. It runs as a sequence of fresh-context subagents: a researcher that investigates the ecosystem and records findings in `RESEARCH.md`, a planner that reads both the research and the `CONTEXT.md` to produce `PLAN.md` files, and a plan-checker that verifies the plans are complete, consistent, and within scope.
+
+What does a plan contain? Each `PLAN.md` describes a bounded unit of work: the files to touch, the specific changes to make, the acceptance criteria that define done. Plans are ordered into dependency waves so that parallel execution is safe — executors in the same wave touch non-overlapping concerns.
+
+The Plan step is the moment when ambiguity is most expensive. An ambiguous plan produces an executor that makes assumptions. Multiple parallel executors making different assumptions about the same concern produce conflicts. The plan-checker's job is to catch these before execution begins, not after.
+
+### Execute
+
+Execution runs the plans. Each executor gets a fresh 200k-token context window loaded with exactly what it needs: the project summary, the phase context, the research, and the specific `PLAN.md` for its task. Nothing more.
+
+Executors write code and commit atomically. Each commit corresponds to a completed task in a plan. When a wave of parallel executors finishes, the orchestrator merges their state and starts the next wave.
+
+The executor's fresh context is not a convenience — it is the mechanism by which context rot is prevented. An executor that runs with 180k tokens of accumulated session history is a degraded executor. An executor that starts clean and reads only what its plan requires is an executor operating at full capacity.
+
+### Verify
+
+After all executors have completed, a verifier agent reads the phase goal, the `CONTEXT.md` decisions, the plans, and the execution summaries — and checks that what was built matches what was intended. It produces a `VERIFICATION.md` and, if there are discrepancies, generates targeted fix plans.
+
+Verification is not just testing. It checks requirement coverage (were all the REQ-IDs addressed?), decision coverage (were the decisions captured in `CONTEXT.md` actually implemented?), and overall phase goal alignment. A phase is not done because execution finished without errors. It is done because what was built is what was planned, and what was planned is what was decided.
+
+### Ship
+
+The Ship step creates the pull request and archives the phase artefacts. `STATE.md` is updated to mark the phase complete. The loop then begins again for the next phase.
+
+---
+
+## Milestones and phases
+
+A **milestone** is a version cycle — a meaningful, releasable increment of the project. It has a name, a version number, and a set of requirements that define what it must deliver. A milestone is complete when all its phases are shipped and its requirements are covered.
+
+A **phase** is one unit of work within a milestone. A phase has a goal, a set of requirements it addresses, and a set of plans that implement it.
+
+The relationship matters because milestones and phases have different scopes of concern. A milestone asks: "What does this version of the product do, and what does it not do?" A phase asks: "What is the next bounded thing we can research, plan, execute, and verify?"
+
+Milestone boundaries are drawn at natural product boundaries — a deployable API, a working UI flow, a complete data model. Phase boundaries are drawn at the limits of what can be safely executed in one loop without the loop becoming unwieldy.
+
+---
+
+## What makes a good phase scope
+
+This is worth dwelling on because it is the most common source of friction with the loop.
+
+A phase that is too large becomes a research project unto itself. The planner struggles to decompose it into independent plans. Executors in later waves are blocked waiting for earlier waves. Verification becomes a full audit rather than a targeted review. The feedback cycle stretches from hours to days, and the risk of discovering a fundamental design mistake late — after much code has been written — rises sharply.
+
+A phase that is too small fragments work that naturally belongs together. You end up with plan files that are half a dozen lines, phases that complete in minutes, and a planning overhead that dwarfs the execution cost. The loop feels bureaucratic rather than helpful.
+
+A good phase scope is one where:
+
+- The goal can be stated in a single sentence that is neither obviously trivial nor suspiciously broad.
+- The research needed to plan it is bounded — the ecosystem questions have answers that do not depend on other phases completing first.
+- The execution can be parallelised into a handful of non-overlapping plans, not dozens.
+- There is a clear, testable definition of done that a verifier can check without reading the entire codebase.
+
+Concretely: "Add HMAC-SHA256 signature validation middleware" is a good phase scope. "Build the authentication system" usually is not — it almost always contains multiple independent concerns that would be better as separate phases. "Fix the typo in the README" is below the threshold where the loop adds value; use `/gsd-quick` instead.
+
+When in doubt, split. A smaller phase completes faster, verifies more confidently, and makes it easier to course-correct if a design decision turns out to be wrong.
+
+---
+
+## How `.planning/` carries state across the loop
+
+The loop is not a single session. Research, planning, and execution may happen across multiple sessions, with context resets in between. The `.planning/` directory is what makes this possible.
+
+Every step of the loop reads artefacts produced by earlier steps and writes artefacts for later steps. The CONTEXT.md that the Discuss step produces is still available when the Planner runs — even if that is in a different session hours later. The PLAN.md files that the Planner produces are still available when the Executor runs — even across a restart. The VERIFICATION.md that the Verifier writes is still available when you review the phase.
+
+`STATE.md` is the navigation layer above all of this. It records exactly where in the loop the project currently sits: which milestone is active, which phase is in progress, which plans are complete and which are pending. Any agent or workflow that needs to orient itself reads `STATE.md` first.
+
+For the precise structure of these files, see [Planning artifacts](../reference/planning-artifacts.md) and the [STATE.md schema](../reference/state-md.md).
+
+---
+
+## The loop is a rhythm, not a constraint
+
+It is tempting to see the loop as bureaucracy — a set of required steps that you have to perform before you are allowed to write code. That framing is wrong.
+
+The loop exists because each step prevents failures that are genuinely expensive to fix later. Discuss prevents planning on wrong assumptions. Plan prevents executing a design that is fundamentally broken. Verify prevents shipping work that missed the brief. These are not invented problems. They are the actual failure modes of AI-assisted development at the scale of real features.
+
+When the loop works well, it feels like a rhythm: a cadence of focused, bounded work where each step is clear because the previous step did its job. The overhead is real, but it is front-loaded — paid in minutes of planning rather than hours of rework.
+
+For work that falls below the threshold where the loop is warranted, GSD Core provides lighter primitives. The phase loop is one tool, not the only tool.
+
+---
+
+## Related
+
+- [Context engineering](context-engineering.md) — why fresh-context subagents prevent the quality degradation that makes the loop necessary
+- [Discuss a phase](../how-to/discuss-a-phase.md)
+- [Plan a phase](../how-to/plan-a-phase.md)
+- [Execute a phase](../how-to/execute-a-phase.md)
+- [Verify and ship](../how-to/verify-and-ship.md)
+- [Planning artifacts](../reference/planning-artifacts.md)
+- [STATE.md schema](../reference/state-md.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/configure-model-profiles.md b/docs/how-to/configure-model-profiles.md
new file mode 100644
index 000000000..94fbbd47b
--- /dev/null
+++ b/docs/how-to/configure-model-profiles.md
@@ -0,0 +1,218 @@
+# How to configure model profiles
+
+Choose the right model tier strategy for your project, then tune individual agents or entire phase types without writing a large override block. This guide starts with the simplest lever and works up to dynamic routing.
+
+---
+
+## The four profiles (plus `adaptive` and `inherit`)
+
+Set `model_profile` in `.planning/config.json` or via `/gsd-config --profile `:
+
+| Profile | Planner | Executor | Researchers | Verifier | Use when |
+|---------|---------|----------|-------------|----------|----------|
+| `quality` | Opus | Opus | Opus | Sonnet | Production-quality work where cost is secondary |
+| `balanced` | Opus | Sonnet | Sonnet | Sonnet | Normal development — the default |
+| `budget` | Sonnet | Sonnet | Haiku | Haiku | Rapid prototyping, cost-sensitive contexts |
+| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | Resolves the same way as the other tiers under runtime-aware profiles; use when switching between runtimes frequently |
+| `inherit` | (session model) | (session model) | (session model) | (session model) | Non-Anthropic providers (OpenRouter, local models) — all agents follow your current session model |
+
+The table above shows a representative subset. All 33 shipped agents have explicit per-profile tier assignments in `sdk/shared/model-catalog.json`. For the full table see [Model Profiles](../CONFIGURATION.md#model-profiles) in the configuration reference.
+
+**Quick switch via command:**
+
+```bash
+/gsd-config --profile balanced # Normal development
+/gsd-config --profile budget # Prototyping or high-cost phases
+/gsd-config --profile quality # Production release
+/gsd-config --profile inherit # OpenRouter, local models
+```
+
+**Or edit `.planning/config.json` directly:**
+
+```json
+{
+ "model_profile": "balanced"
+}
+```
+
+---
+
+## Per-agent overrides (`model_overrides`)
+
+If a single agent needs a different tier without changing the whole profile, use `model_overrides`:
+
+```json
+{
+ "model_profile": "balanced",
+ "model_overrides": {
+ "gsd-executor": "opus",
+ "gsd-codebase-mapper": "haiku"
+ }
+}
+```
+
+Valid values: `opus`, `sonnet`, `haiku`, `inherit`, or any fully-qualified model ID (e.g. `"openai/o3"`, `"google/gemini-2.5-pro"`).
+
+`model_overrides` can be set per-project in `.planning/config.json` or globally in `~/.gsd/defaults.json`. Per-project entries win on conflict; non-conflicting global entries are preserved.
+
+**Important for Codex and OpenCode:** Those runtimes embed the resolved model into each agent's static config at install time. After editing `model_overrides`, re-run the installer for the change to take effect:
+
+```bash
+npx @opengsd/gsd-core@latest --codex --global # or --opencode, --kilo, etc.
+```
+
+---
+
+## Per-phase-type models (`models`)
+
+If you want to say "Opus for planning, Sonnet for everything else" without learning all 33 agent names, use the `models` block. It maps six phase types to tier aliases:
+
+```json
+{
+ "model_profile": "balanced",
+ "models": {
+ "planning": "opus",
+ "discuss": "opus",
+ "research": "sonnet",
+ "execution": "opus",
+ "verification": "sonnet",
+ "completion": "sonnet"
+ }
+}
+```
+
+Phase types and their agents:
+
+| Phase type | Agents covered |
+|---|---|
+| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
+| `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-codebase-mapper`, `gsd-ui-researcher` |
+| `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` |
+| `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker`, `gsd-ui-auditor`, `gsd-doc-verifier` |
+| `discuss`, `completion` | Reserved — no subagent today; accepted by schema for forward compatibility |
+
+The `models` block accepts tier aliases only (`opus`, `sonnet`, `haiku`, `inherit`). For a fully-qualified model ID, use `model_overrides` per agent instead.
+
+**Combining `models` with a per-agent exception:**
+
+```json
+{
+ "model_profile": "balanced",
+ "models": {
+ "research": "sonnet"
+ },
+ "model_overrides": {
+ "gsd-codebase-mapper": "haiku"
+ }
+}
+```
+
+All five research agents resolve to `sonnet` *except* `gsd-codebase-mapper`, which is pinned to `haiku`.
+
+---
+
+## Dynamic routing — start cheap, escalate on failure
+
+If you want to pay for cheaper tiers by default and only escalate when an agent fails a quality gate, enable `dynamic_routing`:
+
+```json
+{
+ "dynamic_routing": {
+ "enabled": true,
+ "tier_models": {
+ "light": "haiku",
+ "standard": "sonnet",
+ "heavy": "opus"
+ },
+ "escalate_on_failure": true,
+ "max_escalations": 1
+ }
+}
+```
+
+Each agent has a default tier (`light`, `standard`, or `heavy`). On the first attempt, GSD picks `tier_models[default_tier]`. If the orchestrator detects a soft failure (verification inconclusive, plan-check flagged, etc.), it re-spawns the agent one tier up. `max_escalations` caps the total retries.
+
+Agents that already sit at `heavy` cannot escalate further.
+
+**Turning off escalation while keeping dynamic resolution:**
+
+```json
+{
+ "dynamic_routing": {
+ "enabled": true,
+ "escalate_on_failure": false
+ }
+}
+```
+
+Every attempt uses `tier_models[default_tier]` regardless of outcome — useful when you want explicit tier-to-model mapping without the escalation behaviour.
+
+`dynamic_routing` is **disabled by default**. Omitting the block or setting `enabled: false` preserves static resolution.
+
+---
+
+## Using GSD on non-Anthropic runtimes
+
+If you installed GSD for Codex, OpenCode, Gemini CLI, or Kilo, the installer already set `resolve_model_ids: "omit"` in your config. This tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model. No manual setup is needed for the basic case.
+
+**If you want tiered models on Codex:**
+
+```json
+{
+ "runtime": "codex",
+ "model_profile": "balanced"
+}
+```
+
+GSD resolves each tier alias to the Codex-native model and reasoning effort defined in the runtime tier map.
+
+**If you want per-agent model IDs on any non-Claude runtime:**
+
+```json
+{
+ "resolve_model_ids": "omit",
+ "model_overrides": {
+ "gsd-planner": "o3",
+ "gsd-executor": "o4-mini",
+ "gsd-debugger": "o3"
+ }
+}
+```
+
+For the full runtime-aware profiles reference and the `model_policy` surface (provider-neutral presets added in v1.42), see [Configuration reference — Model Profiles](../CONFIGURATION.md#model-profiles).
+
+---
+
+## Resolution precedence (highest to lowest)
+
+When multiple layers apply, the resolver picks the highest-priority entry:
+
+```text
+1. model_overrides[] — per-agent; full IDs; targeted exception
+2. dynamic_routing.tier_models[] — when enabled; escalates on soft failure
+3. models[] — coarse phase-level tier
+4. model_profile (per-agent column) — global tier strategy
+5. Runtime default — when nothing else applies
+```
+
+---
+
+## Choosing the right lever
+
+| You want | Use |
+|---|---|
+| One tier strategy for all agents | `model_profile` |
+| Coarse phase-level tuning ("Opus for planning") | `models.` |
+| Per-agent precision ("force Haiku on the codebase mapper") | `model_overrides[]` |
+| A fully-qualified model ID for a specific agent | `model_overrides[]: "openai/gpt-5"` |
+| Start cheap, escalate only on failure | `dynamic_routing` |
+| All agents follow the session model (non-Anthropic provider) | `model_profile: "inherit"` |
+
+---
+
+## Related
+
+- [Configuration reference](../CONFIGURATION.md)
+- [Multi-agent orchestration](../explanation/multi-agent-orchestration.md)
+- [Commands reference](../COMMANDS.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/debug-a-failed-execution.md b/docs/how-to/debug-a-failed-execution.md
new file mode 100644
index 000000000..d72e4c784
--- /dev/null
+++ b/docs/how-to/debug-a-failed-execution.md
@@ -0,0 +1,178 @@
+# How to debug a failed execution
+
+**Goal:** Recover when a phase execution fails, stalls, or produces incomplete work — and resume cleanly without losing progress or repeating work that already succeeded.
+
+**Prerequisites:** You have run `/gsd-execute-phase N` and the execution stopped before writing `VERIFICATION.md`, or you see unexpected output, missing files, or a stalled spinner.
+
+---
+
+## Detect whether the execution stalled or failed
+
+Before taking any recovery action, determine what actually happened.
+
+### If you see "Spawning…" with no output after 1–5 minutes
+
+This is normal, not a freeze. GSD subagents run in an isolated context window. The liveness note on the spawn line confirms this. Do not interrupt the session.
+
+If it has been more than 10 minutes with no result, check the Claude Code sidebar. If the agent task shows as completed but no output appeared, the result may have been lost in a context switch — re-run the same command:
+
+```bash
+/gsd-execute-phase 1
+```
+
+GSD checks for `SUMMARY.md` files before dispatching executors. Plans that already have one are skipped automatically.
+
+### If execution stopped mid-wave with an error message
+
+Check git history to see which plans committed successfully:
+
+```bash
+git log --oneline -20
+```
+
+Plans that committed their work will have an entry such as `feat(01-02): …`. Plans without a commit are incomplete and will be re-executed when you re-run.
+
+### If the executor committed code but did not write SUMMARY.md
+
+GSD detects this at the next run and surfaces a safe-resume gate with three options:
+
+- **Close out manually** — inspect the commits yourself, write `SUMMARY.md`, then re-run.
+- **Re-execute from scratch** — revert or supersede the partial commits before dispatching a new executor.
+- **Mark-and-skip** — record the anomaly and continue, only with your explicit confirmation.
+
+---
+
+## Diagnose the root cause
+
+### Run `/gsd-debug --diagnose`
+
+If execution produced wrong output, stubbed code, or a verification failure, use the diagnosis-only mode to investigate without applying any fixes:
+
+```bash
+/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
+```
+
+`--diagnose` stops at root cause without touching your files. It creates a session file at `.planning/debug/.md` so you can pick up the investigation later if needed.
+
+To start a full debug session that also applies a fix:
+
+```bash
+/gsd-debug "Login middleware not handling 401 correctly after phase 3"
+```
+
+GSD gathers symptoms, runs a structured investigation using the scientific method, and proposes a fix. If `tdd_mode: true` is set in your config, it requires a failing test before applying any fix.
+
+### Check active debug sessions
+
+```bash
+/gsd-debug list
+```
+
+Shows all open sessions with their current hypothesis and next action. To resume a specific session:
+
+```bash
+/gsd-debug continue
+```
+
+---
+
+## Run a post-mortem with `/gsd-forensics`
+
+If the cause is not clear from the error output — for example, plans reference nonexistent files, execution produced unexpected results, or state seems corrupted — run a forensic investigation:
+
+```bash
+/gsd-forensics "Phase 3 execution stalled after wave 1"
+```
+
+GSD analyses git history, `.planning/` artifact completeness, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a structured report to `.planning/forensics/report-.md` and surfaces recommended remediation steps.
+
+`/gsd-forensics` is read-only — it never modifies your project files.
+
+**What it detects:**
+
+- **Stuck loop** — the same file appears in three or more consecutive commits within a short time window (HIGH confidence if commit messages are similar)
+- **Missing artefacts** — a phase has commits but no `SUMMARY.md` or `VERIFICATION.md`
+- **Abandoned work** — uncommitted changes with STATE.md showing mid-execution and the last commit more than two hours old
+- **Crash or interruption** — uncommitted changes combined with an active execution state and orphaned worktrees
+- **Scope drift** — recent commits touch files outside the current phase's expected file set
+
+---
+
+## Resume execution after recovery
+
+Once the underlying issue is resolved, re-run the execute command:
+
+```bash
+/gsd-execute-phase 1
+```
+
+GSD skips plans whose `SUMMARY.md` already exists and dispatches executors only for the remaining plans.
+
+If you need to re-execute only a specific wave:
+
+```bash
+/gsd-execute-phase 1 --wave 2
+```
+
+If you want to validate `.planning/` integrity before dispatching:
+
+```bash
+/gsd-execute-phase 1 --validate
+```
+
+---
+
+## Roll back with `/gsd-undo`
+
+If execution produced code you want to discard entirely, roll back using the plan manifest rather than manual `git revert`:
+
+### Roll back a single plan
+
+```bash
+/gsd-undo --plan 03-02
+```
+
+Reverts all commits for plan `02` of phase `3`. GSD shows a confirmation gate before writing any change.
+
+### Roll back an entire phase
+
+```bash
+/gsd-undo --phase 03
+```
+
+Reverts all commits for phase `3`. GSD checks whether any subsequent phases depend on this phase and warns you before proceeding.
+
+### Pick interactively from recent commits
+
+```bash
+/gsd-undo --last 5
+```
+
+Shows the five most recent GSD commits and lets you select which to revert.
+
+---
+
+## Restore session context after a break
+
+If you have returned to the project after a context reset or a new session:
+
+```bash
+/gsd-resume-work
+```
+
+Restores your full session context from the last handoff, including the current phase, blockers, and where execution stopped.
+
+Alternatively, to see your current position and auto-advance to the correct next step:
+
+```bash
+/gsd-progress --next
+```
+
+---
+
+## Related
+
+- [Execute a phase](execute-a-phase.md)
+- [Recover and troubleshoot](recover-and-troubleshoot.md)
+- [Commands](../COMMANDS.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/design-a-ui-phase.md b/docs/how-to/design-a-ui-phase.md
new file mode 100644
index 000000000..e2b96cb58
--- /dev/null
+++ b/docs/how-to/design-a-ui-phase.md
@@ -0,0 +1,149 @@
+# How to design a UI phase
+
+**Goal:** Produce a locked UI design contract (`UI-SPEC.md`) that fixes spacing, colour, typography, and copywriting decisions before the planner writes tasks, preventing visual inconsistency caused by ad-hoc styling choices during execution.
+
+**Prerequisites:** `.planning/ROADMAP.md` exists. The phase must have frontend or UI work. Running `/gsd-discuss-phase N` first is strongly recommended — the UI researcher reads `CONTEXT.md` to avoid re-asking decisions you have already made.
+
+---
+
+## Decide whether this phase needs a UI contract
+
+Not all phases need `/gsd-ui-phase`. Use it when:
+
+- The phase introduces new UI surfaces (pages, flows, layouts)
+- Multiple components will be built and visual consistency matters
+- You are starting a new project's frontend and need a design system baseline
+- You are adding significant UI work to an existing project and want to lock tokens, spacing, and colour before execution
+
+Skip it when:
+
+- The phase is purely backend, infrastructure, or data work with no user-facing output
+- A UI-SPEC.md already exists for an earlier phase and this phase builds on identical visual patterns without introducing new surfaces
+
+If you are unsure, the safety gate will prompt you: when `workflow.ui_safety_gate` is enabled (default), `/gsd-plan-phase` warns when it detects frontend work but no UI-SPEC.md and asks whether to run `/gsd-ui-phase` first.
+
+---
+
+## Run the UI design contract
+
+```bash
+/gsd-ui-phase 2
+```
+
+If no phase number is given, GSD Core targets the current phase.
+
+The command runs in two stages:
+
+1. **`gsd-ui-researcher`** — reads `CONTEXT.md`, `RESEARCH.md`, and `REQUIREMENTS.md` for existing decisions, detects the design system state (shadcn `components.json`, Tailwind config, existing tokens), and asks only the unanswered design questions across five areas: spacing, colour, typography, copywriting, and registry safety.
+2. **`gsd-ui-checker`** — validates the resulting `UI-SPEC.md` across six dimensions. If issues are found, a revision loop reruns the researcher (up to two iterations) targeting only the flagged items.
+
+**Output:** `{padded_phase}-UI-SPEC.md` in `.planning/phases/{phase-dir}/`.
+
+---
+
+## What the UI-SPEC covers
+
+The researcher locks decisions across five areas:
+
+| Area | Examples |
+|---|---|
+| **Spacing** | Base scale (4px or 8px), grid alignment, component padding |
+| **Colour** | Primary, accent, neutral palette; 60/30/10 rule; dark-mode considerations |
+| **Typography** | Font families, size/weight scale constraints, heading hierarchy |
+| **Copywriting** | CTA labels, empty state messages, error state copy, loading indicators |
+| **Registry safety** | shadcn component inspection protocol (see below) |
+
+The checker validates the spec against six pillars, scored 1–4 each: Copywriting, Visuals, Colour, Typography, Spacing, and Experience Design (loading / error / empty state coverage).
+
+---
+
+## shadcn initialisation
+
+For React, Next.js, and Vite projects, the researcher offers to initialise shadcn if no `components.json` is found. The flow:
+
+1. Visit `ui.shadcn.com/create` and configure your preset (colours, border radius, fonts)
+2. Copy the preset string
+3. Run:
+
+```bash
+npx shadcn init --preset
+```
+
+The preset string becomes a first-class GSD Core planning artefact that is reproducible across phases and milestones.
+
+---
+
+## Registry safety gate
+
+Third-party shadcn registries can inject arbitrary code. When `workflow.ui_safety_gate` is enabled (default), the spec requires these steps before installing any non-official component:
+
+```bash
+npx shadcn view # inspect source before installing
+npx shadcn diff # compare against the official registry
+```
+
+The checker will flag the spec as BLOCKED if registry safety is not addressed. Disable the gate via `/gsd-settings` if your project does not use shadcn or you have an alternative vetting process.
+
+---
+
+## Use sketch findings as a head start
+
+If you have already run `/gsd-sketch --wrap-up`, the UI researcher loads `.claude/skills/sketch-findings-[project]/` automatically. Pre-validated decisions (layout, palette, typography, spacing) are treated as locked — the researcher does not re-ask them. You see a note at the start of the run:
+
+```text
+⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
+ Pre-validated decisions (layout, palette, typography, spacing) should be treated
+ as locked — not re-asked.
+```
+
+This is the main reason to run `/gsd-sketch --wrap-up` before `/gsd-ui-phase`: it turns the conversational design exploration into binding contract input.
+
+---
+
+## Retroactive visual audit with `/gsd-ui-review`
+
+`/gsd-ui-review` runs after execution, not before. Use it to audit the implemented frontend against the UI-SPEC (or against abstract 6-pillar standards when no spec exists).
+
+```bash
+/gsd-ui-review # audit the current phase
+/gsd-ui-review 3 # audit phase 3 specifically
+```
+
+It works on any project with frontend code — GSD project initialisation is not required.
+
+**What it checks (6 pillars, scored 1–4 each):**
+
+1. Copywriting — CTA labels, empty states, error states
+2. Visuals — focal points, visual hierarchy, icon accessibility
+3. Colour — accent usage discipline, 60/30/10 compliance
+4. Typography — font size and weight constraint adherence
+5. Spacing — grid alignment, token consistency
+6. Experience Design — loading, error, and empty state coverage
+
+**Output:** `{padded_phase}-UI-REVIEW.md` with scores and top three priority fixes. When a browser MCP server such as `gsd-browser` is configured, the audit also captures screenshots with visual evidence.
+
+**Screenshot storage:** Screenshots are saved to `.planning/ui-reviews/`. A `.gitignore` is created automatically to prevent binary files from reaching git. Screenshots are cleaned up during `/gsd-complete-milestone`.
+
+---
+
+## Recommended position in the phase lifecycle
+
+```text
+/gsd-discuss-phase N ← lock implementation preferences
+/gsd-ui-phase N ← lock design contract (frontend phases)
+/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
+/gsd-execute-phase N ← parallel execution
+/gsd-verify-work N ← manual UAT
+/gsd-ui-review N ← retroactive visual audit (optional but recommended)
+```
+
+`/gsd-ui-phase` sits between discuss and plan because the planner reads `UI-SPEC.md` as design context — tasks in `PLAN.md` reference spacing tokens, colour variables, and copywriting decisions that the spec locked.
+
+---
+
+## Related
+
+- [Spike and sketch](spike-and-sketch.md)
+- [Plan a phase](plan-a-phase.md)
+- [Commands](../COMMANDS.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/discuss-a-phase.md b/docs/how-to/discuss-a-phase.md
new file mode 100644
index 000000000..398dee8d2
--- /dev/null
+++ b/docs/how-to/discuss-a-phase.md
@@ -0,0 +1,158 @@
+# How to discuss a phase
+
+**Goal:** Gather the implementation decisions a phase needs before planning begins — so the researcher and planner can act without asking you again.
+
+**Prerequisites:** `.planning/ROADMAP.md` exists. If not, run `/gsd-new-project` first.
+
+---
+
+## Choose your discuss mode
+
+GSD Core offers two modes. Choose based on how well-understood the codebase is.
+
+**If you want to express your own implementation preferences upfront** (interview mode, the default):
+
+```bash
+/gsd-discuss-phase 2
+```
+
+Claude identifies grey areas in the phase scope, lets you select which to discuss, then works through approximately four questions per area.
+
+**If the codebase already has clear patterns and you find most questions obvious** (assumptions mode):
+
+```bash
+node gsd-tools.cjs config-set workflow.discuss_mode assumptions
+/gsd-discuss-phase 2
+```
+
+Claude reads 5–15 relevant codebase files via a subagent, forms assumptions with evidence and confidence levels, and presents them for confirmation or correction. Typically 2–4 interactions rather than 15–20.
+
+To switch back:
+
+```bash
+node gsd-tools.cjs config-set workflow.discuss_mode discuss
+```
+
+See [Discuss modes explained](../workflow-discuss-mode.md) for a full comparison, including when each mode is likely to save time.
+
+---
+
+## Discuss all grey areas without the selection step
+
+By default, Claude presents grey areas and asks which you want to cover. If you want to work through all of them without that selection prompt:
+
+```bash
+/gsd-discuss-phase 2 --all
+```
+
+---
+
+## Speed up a straightforward phase
+
+**If the phase is well-understood and you want Claude to pick the recommended defaults without prompting you:**
+
+```bash
+/gsd-discuss-phase 3 --auto
+```
+
+Claude selects the recommended answer for every question and logs the choices. Use this for phases where the decisions are low-stakes or already implied by prior phases.
+
+**If you have remote-session constraints (no TUI menus):**
+
+```bash
+/gsd-discuss-phase 2 --text
+```
+
+All prompts are rendered as plain-text numbered lists instead of interactive selectors.
+
+---
+
+## Work through questions in groups
+
+If you prefer to answer several questions at once rather than one at a time:
+
+```bash
+/gsd-discuss-phase 2 --batch
+```
+
+Claude groups 2–5 questions per turn.
+
+---
+
+## Add trade-off analysis to each question
+
+If you want a comparison table of the options before committing:
+
+```bash
+/gsd-discuss-phase 2 --analyze
+```
+
+---
+
+## Bulk-answer from a prepared file
+
+If you have a prepared answers file and want to push all decisions in one pass:
+
+```bash
+/gsd-discuss-phase 1 --power
+```
+
+---
+
+## Surface Claude's assumptions before discussing
+
+**If you want to see what Claude would assume and do before any interactive session** — useful for validating alignment before investing discussion time:
+
+```bash
+/gsd-discuss-phase 3 --assumptions
+```
+
+Claude outputs its assumptions (with codebase evidence and confidence levels) and exits. No CONTEXT.md is written. Review the output, then run a normal discuss or assumptions-mode session if anything needs correcting.
+
+---
+
+## What CONTEXT.md contains
+
+Both discuss and assumptions mode produce the same `{phase}-CONTEXT.md` in the phase directory. Downstream agents (researcher, planner, plan-checker) read this file identically regardless of which mode produced it. It contains six sections:
+
+| Section | Purpose |
+|---|---|
+| `` | Phase boundary — what this phase delivers |
+| `` | Locked implementation decisions from the session |
+| `` | Specs, ADRs, and docs downstream agents must read |
+| `` | Reusable assets, patterns, and integration points |
+| `` | User references and preferences |
+| `` | Ideas noted for future phases |
+
+The `` section is mandatory. If you reference a doc, spec, or ADR during the discussion, Claude adds it immediately and reads it to inform subsequent questions.
+
+See [CONTEXT.md schema](../reference/context-md.md) for the full field reference.
+
+---
+
+## How decisions feed into planning
+
+When you run `/gsd-plan-phase` next, the planner reads CONTEXT.md to know which decisions are locked. It will not re-ask questions already answered here. The researcher reads it first to know what to investigate.
+
+**If CONTEXT.md is missing when you run `/gsd-plan-phase`**, you will be offered the choice to continue without context (plans use research and requirements only, without your design preferences) or to run `/gsd-discuss-phase` first.
+
+---
+
+## If you have a PRD or acceptance-criteria document
+
+Skip discuss-phase entirely and go straight to planning:
+
+```bash
+/gsd-plan-phase 1 --prd path/to/prd.md
+```
+
+The planner synthesises CONTEXT.md from the PRD and treats all requirements as locked decisions.
+
+---
+
+## Related
+
+- [Plan a phase](plan-a-phase.md)
+- [Discuss modes](../workflow-discuss-mode.md)
+- [CONTEXT.md schema](../reference/context-md.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/drive-gsd-from-a-tracker-issue.md b/docs/how-to/drive-gsd-from-a-tracker-issue.md
new file mode 100644
index 000000000..3ed9deb3c
--- /dev/null
+++ b/docs/how-to/drive-gsd-from-a-tracker-issue.md
@@ -0,0 +1,176 @@
+# How to drive GSD Core from a tracker issue
+
+**Goal:** Take a single well-scoped GitHub, Linear, or Jira issue through the full GSD pipeline — from isolated workspace to merged PR — using only commands that already exist in GSD Core, with no custom scripts or tracker integrations.
+
+**Prerequisites:** GSD Core is installed. The issue has bounded scope, observable acceptance criteria, and no upstream blockers.
+
+For the concepts and design rationale behind this pattern, see [Issue-driven orchestration explained](../issue-driven-orchestration.md).
+
+---
+
+## Step 1: Map the issue to a phase
+
+Open your tracker issue and decide how it maps onto `ROADMAP.md`:
+
+- **Issue matches an existing phase** → note the phase number and move to Step 2.
+- **Issue is standalone new work** → add a phase:
+
+```bash
+/gsd-phase "Description matching the issue title"
+```
+
+- **Issue is urgent and must slot between existing phases** → insert a decimal phase:
+
+```bash
+/gsd-phase --insert 3 "Fix: description from issue"
+```
+
+Copy the tracker issue URL. You will paste it into `CONTEXT.md` in Step 3 so traceability survives context compaction.
+
+---
+
+## Step 2: Create an isolated workspace
+
+Every issue gets its own workspace — a git worktree with an independent `.planning/` directory. Partial work, aborted plans, and exploratory commits stay outside `main`.
+
+```bash
+/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
+```
+
+Switch into the workspace directory before continuing:
+
+```bash
+cd ~/gsd-workspaces/my-issue-slug
+```
+
+---
+
+## Step 3: Discuss the phase
+
+Run discuss-phase to lock in implementation decisions before any planning happens. When the session opens, paste the tracker issue URL into the discussion so it is captured in `CONTEXT.md`.
+
+```bash
+/gsd-discuss-phase N
+```
+
+GSD asks about ambiguities in the issue scope — error handling, edge cases, interface contracts, technology choices. Your answers shape the plan that follows.
+
+If you already know all the answers and want to move quickly:
+
+```bash
+/gsd-discuss-phase N --auto
+```
+
+---
+
+## Step 4: Plan the phase
+
+```bash
+/gsd-plan-phase N
+```
+
+GSD spawns research agents, reads your `CONTEXT.md` decisions (including the issue URL), and produces atomic `PLAN.md` files. A plan-checker validates each plan before saving.
+
+If you want peer review from external AI CLIs before execution (recommended for significant changes):
+
+```bash
+/gsd-review --phase N
+/gsd-plan-phase N --reviews
+```
+
+Or run the full plan–review–converge loop until no HIGH concerns remain:
+
+```bash
+/gsd-plan-review-convergence N
+```
+
+---
+
+## Step 5: Execute the phase
+
+For interactive, phase-at-a-time execution:
+
+```bash
+/gsd-execute-phase N
+```
+
+For a hands-off run through all remaining phases:
+
+```bash
+/gsd-autonomous
+```
+
+For an interactive dashboard where you can watch progress and dispatch work across phases:
+
+```bash
+/gsd-manager
+```
+
+All three approaches update `STATE.md`, commit each task atomically, and run the post-phase verifier.
+
+---
+
+## Step 6: Verify the work
+
+```bash
+/gsd-verify-work N
+```
+
+GSD walks you through the acceptance criteria from the phase goal (which reflects your tracker issue) one at a time. If anything fails, GSD diagnoses the root cause and creates a fix plan. Re-run execute and re-verify until all checks pass.
+
+Treat `verification_failed` as a blocker even when the code looks correct — the failure usually surfaces a missed acceptance criterion from the original issue.
+
+---
+
+## Step 7: Review and ship
+
+Run a code review before opening the PR:
+
+```bash
+/gsd-code-review N
+/gsd-code-review N --fix
+```
+
+Then create the PR:
+
+```bash
+/gsd-ship N
+```
+
+GSD assembles the PR body from your planning artifacts: phase goal, changes summary, requirements addressed, verification status, and key decisions. Include `Closes #NNN` or `Fixes #NNN` in the PR body (or set it via `/gsd-config`) so the tracker issue closes automatically when the PR merges.
+
+---
+
+## Step 8: Capture follow-up work
+
+As you work through the issue you will often discover related work. Capture it without losing context:
+
+```bash
+/gsd-capture "Follow-up: description of discovered work" # Add as a todo
+/gsd-capture --seed "Idea worth a future phase" # Preserve for the next milestone
+/gsd-capture --backlog "Not urgent but worth tracking" # Park in the backlog
+```
+
+GSD does not post to your tracker automatically. Creating a tracker issue from captured follow-ups is a separate manual step — this keeps human review in the loop.
+
+---
+
+## Conditionals
+
+| Situation | What to do |
+|-----------|-----------|
+| Issue is very small (typo, config change) | Skip workspace + discuss + plan; use `/gsd-quick` instead |
+| Issue has multiple independent sub-tasks | Use `/gsd-manager` to parallelise execution across plans |
+| Issue is blocked on another issue | Do not start until the upstream blocker is resolved; GSD has no automatic dependency poller |
+| Issue scope turns out larger than expected mid-execution | Stop, run `/gsd-phase --insert N` to add sub-phases, continue |
+| You want to skip the interactive discussion | Use `--auto` flag with `/gsd-discuss-phase`, or set `workflow.skip_discuss: true` for project-wide automation |
+| Multiple issues form a coherent release | Run `/gsd-new-milestone` to group them and `/gsd-autonomous` to execute in sequence |
+
+---
+
+## Related
+
+- [Issue-driven orchestration explained](../issue-driven-orchestration.md)
+- [Isolate work with workspaces](isolate-work-with-workspaces.md)
+- [Verify and ship](verify-and-ship.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/execute-a-phase.md b/docs/how-to/execute-a-phase.md
new file mode 100644
index 000000000..7a528853b
--- /dev/null
+++ b/docs/how-to/execute-a-phase.md
@@ -0,0 +1,119 @@
+# How to execute a phase
+
+**Goal:** Run a planned phase through wave-based parallel execution and land every plan as an atomic git commit.
+
+**Prerequisites:** The phase has at least one `PLAN.md` file. If planning is not yet done, run `/gsd-plan-phase N` first — see [Plan a phase](plan-a-phase.md).
+
+---
+
+## Run the full phase
+
+```bash
+/gsd-execute-phase 1
+```
+
+GSD reads the phase's plan files, groups them into dependency waves, and spawns a fresh executor agent per plan. Each executor commits its work atomically before the next wave begins.
+
+Before any agents are dispatched, GSD prints a wave table:
+
+```
+## Execution Plan
+
+Phase 1: Core middleware — 3 plans across 2 wave(s)
+
+| Wave | Plans | What it builds |
+|------|----------------|---------------------------|
+| 1 | 01-01, 01-02 | Core validation function |
+| 2 | 01-03 | Express middleware wrapper |
+```
+
+Wave 1 plans run in parallel (each in an isolated git worktree). Wave 2 waits until all Wave 1 commits are merged.
+
+For the underlying agent coordination model, see [Multi-agent orchestration](../explanation/multi-agent-orchestration.md).
+
+---
+
+## Run a single wave
+
+If you want to execute only one wave — for example, to inspect Wave 1 output before committing to Wave 2 — use `--wave N`:
+
+```bash
+/gsd-execute-phase 1 --wave 2
+```
+
+GSD executes only Wave 2 plans. It first checks that all earlier waves are complete; if any Wave 1 plan is still marked incomplete, it stops and tells you to finish earlier waves first.
+
+---
+
+## Validate state before execution
+
+If you suspect the `.planning/` directory is out of sync with the filesystem — for example after a crash or an interrupted previous run — pass `--validate`:
+
+```bash
+/gsd-execute-phase 1 --validate
+```
+
+GSD runs a state consistency check before spawning any executors. Detected drift is reported and you can accept or correct it before proceeding.
+
+---
+
+## Resume a stalled execution
+
+If execution stops partway through — a quota error, a network drop, or a crashed session — the wave-level progress is preserved. GSD checks for a `SUMMARY.md` file for each plan; plans that have one are skipped automatically when you re-run:
+
+```bash
+/gsd-execute-phase 1
+```
+
+GSD will skip plans where `SUMMARY.md` already exists and pick up from the first incomplete plan.
+
+**If commits exist but `SUMMARY.md` is missing** (the executor committed but did not write its summary before the session died), GSD surfaces a safe-resume gate and offers three options:
+
+- `close out manually` — inspect the commits, write `SUMMARY.md`, then re-run.
+- `re-execute from scratch` — revert or supersede the partial commits before dispatching a new executor.
+- `mark-and-skip` — record the anomaly and move on, only with explicit confirmation.
+
+For systematic failure diagnosis, see [Debug a failed execution](debug-a-failed-execution.md).
+
+---
+
+## Where output lands
+
+After all waves complete, the phase directory contains:
+
+```
+.planning/phases/01-/
+ 01-01-SUMMARY.md # What plan 01 built, key files, deviations
+ 01-02-SUMMARY.md
+ 01-03-SUMMARY.md
+ VERIFICATION.md # Requirement-by-requirement pass/fail status
+```
+
+`STATE.md` and `ROADMAP.md` are updated automatically once all waves are done. `VERIFICATION.md` is written only when the phase is fully complete.
+
+Git history will show one commit per task (from each executor), followed by tracking commits from the orchestrator.
+
+---
+
+## Cross-AI execution
+
+To delegate execution to an external AI CLI (Codex, Gemini, etc.) configured in `workflow.cross_ai_command`:
+
+```bash
+/gsd-execute-phase 2 --cross-ai
+```
+
+To force local execution even when cross-AI is enabled in config:
+
+```bash
+/gsd-execute-phase 2 --no-cross-ai
+```
+
+---
+
+## Related
+
+- [Plan a phase](plan-a-phase.md)
+- [Verify and ship](verify-and-ship.md)
+- [Debug a failed execution](debug-a-failed-execution.md)
+- [Commands](../COMMANDS.md)
diff --git a/docs/how-to/handle-quick-and-fast-tasks.md b/docs/how-to/handle-quick-and-fast-tasks.md
new file mode 100644
index 000000000..ec074b1cb
--- /dev/null
+++ b/docs/how-to/handle-quick-and-fast-tasks.md
@@ -0,0 +1,121 @@
+# How to handle quick and fast tasks
+
+Not every piece of work fits inside a phase. GSD provides two lightweight commands for work that does not need the full discuss → plan → execute → verify loop.
+
+For context on when the full phase pipeline is worth its overhead, see [Context engineering](../explanation/context-engineering.md).
+
+---
+
+## Deciding which command to use
+
+| Situation | Command |
+|-----------|---------|
+| Fixing a bug, adding a small feature, or any task you cannot summarise as a single trivial edit | `/gsd-quick` |
+| Fixing a typo, updating a config value, adding a `.gitignore` entry, or any change that touches ≤ 3 files and takes under a minute | `/gsd-fast` |
+| The task has unknowns, needs research, or will touch more than a handful of files | `/gsd-quick` with `--research` |
+
+**The rule of thumb:** if you hesitate for even a moment about whether the task is trivial, use `/gsd-quick`. `/gsd-fast` redirects you to `/gsd-quick` automatically if the scope looks non-trivial.
+
+---
+
+## `/gsd-quick` — ad-hoc tasks with GSD guarantees
+
+`/gsd-quick` runs a planner and executor with the same atomic-commit and STATE.md tracking guarantees as a full phase, but without the phase overhead (no ROADMAP entry, no discuss-phase, no wave coordination across multiple plans).
+
+### Basic use
+
+```bash
+/gsd-quick
+```
+
+GSD prompts you for a task description, then plans and executes it. Artifacts land in `.planning/quick/`.
+
+You can also pass the description directly:
+
+```bash
+/gsd-quick "Fix the login button not responding on mobile Safari"
+```
+
+### Flags
+
+Add flags to bring in more of the quality pipeline when the task warrants it.
+
+| Flag | What it adds |
+|------|-------------|
+| `--discuss` | A lightweight pre-planning discussion that surfaces grey areas and captures your decisions in a `CONTEXT.md` before the planner runs |
+| `--research` | A focused research agent investigates approaches, libraries, and pitfalls before planning |
+| `--validate` | Plan-checking (up to 2 iterations) plus post-execution verification |
+| `--full` | All of the above — equivalent to `--discuss --research --validate` |
+
+Flags compose freely:
+
+```bash
+/gsd-quick --research --validate # research + plan-checking + verification, no discuss
+/gsd-quick --discuss # just surface grey areas before planning
+/gsd-quick --full # the complete quality pipeline
+```
+
+### When to add flags
+
+- Add `--research` when you are unsure how to approach a task or which library to use.
+- Add `--validate` when the task touches critical code paths and you want a verifier agent to confirm the must-haves were met.
+- Add `--discuss` when the task has design choices you want to lock in before the planner runs — for example, when the right error-handling behaviour is not obvious.
+- Use `--full` when a task is genuinely significant and you would normally plan it as a phase but it does not belong in the ROADMAP.
+
+### Listing and resuming quick tasks
+
+```bash
+/gsd-quick list # show all quick tasks with status
+/gsd-quick status my-task-slug # show status of a specific task
+/gsd-quick resume my-task-slug # resume an interrupted task
+```
+
+---
+
+## `/gsd-fast` — inline trivial edits
+
+`/gsd-fast` does the work directly in the current context. There are no subagents, no `PLAN.md`, and no research. It is suitable only for changes you could make yourself in under a minute.
+
+```bash
+/gsd-fast "fix typo in README"
+/gsd-fast "add .env to .gitignore"
+```
+
+If you omit the description, GSD prompts you for it.
+
+`/gsd-fast` checks whether the task is actually trivial before proceeding. If it judges the scope too large it stops and redirects you:
+
+```text
+This looks like it needs planning. Use /gsd-quick instead:
+ /gsd-quick "your task description"
+```
+
+After making the change, `/gsd-fast` commits atomically and, if a `Quick Tasks Completed` table exists in `.planning/STATE.md`, appends a row to it.
+
+---
+
+## What `/gsd-quick` does that `/gsd-fast` does not
+
+| Capability | `/gsd-fast` | `/gsd-quick` |
+|------------|------------|--------------|
+| Subagent planner | No | Yes |
+| Subagent executor | No | Yes |
+| Research agent | No | Optional (`--research`) |
+| Plan-checking | No | Optional (`--validate`) |
+| Post-execution verification | No | Optional (`--validate`) |
+| Discussion phase | No | Optional (`--discuss`) |
+| Worktree isolation | No | Yes (default) |
+| Atomic commits per task | Single commit | One per plan task |
+| STATE.md tracking | Row appended if table exists | Always updated |
+| `.planning/quick/` artifacts | No | Yes |
+
+The key distinction is subagent isolation. `/gsd-quick` spawns a fresh planner and executor in separate context windows, which means the work is planned properly, commits are atomic per task, and the orchestrator can verify results. `/gsd-fast` uses only the current context window and is intentionally limited to changes trivial enough not to need any of that.
+
+---
+
+## Related
+
+- [The phase loop](../explanation/the-phase-loop.md)
+- [Context engineering](../explanation/context-engineering.md)
+- [Commands](../COMMANDS.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/install-on-your-runtime.md b/docs/how-to/install-on-your-runtime.md
new file mode 100644
index 000000000..0e2a160e7
--- /dev/null
+++ b/docs/how-to/install-on-your-runtime.md
@@ -0,0 +1,291 @@
+# How to install GSD Core on your runtime
+
+Install GSD Core (`@opengsd/gsd-core`) into the AI coding runtime you use every day. This guide gives you the standard installer path for each supported runtime, then covers the manual path for machines without Node.js.
+
+**What you need:** Node.js 18+ and npm (or npx). If you do not have Node.js, jump to [Installing without Node.js](#installing-without-nodejs).
+
+---
+
+## Why the installer is required
+
+GSD Core ships agent and command files in Claude Code's native frontmatter format. Each supported runtime expects a different schema, directory layout, and command-invocation syntax. The installer performs the necessary transformations — for example, converting tool lists and colour values for OpenCode, writing TOML agent entries for Codex, and rewriting every command body from hyphen form (`/gsd-update`) to colon form (`/gsd:update`) for Gemini CLI.
+
+**Do not copy files from `agents/` or `commands/` directly.** Doing so bypasses the transformations and produces schema-validation errors or missing commands.
+
+---
+
+## Standard install
+
+Run the installer from any directory. It prompts for your runtime and whether to install globally (all projects) or locally (this project only).
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+
+That is the only command you need for a fresh install or to re-run the installer after switching runtimes.
+
+---
+
+## Per-runtime instructions
+
+### Claude Code
+
+```bash
+npx @opengsd/gsd-core@latest --claude --global
+```
+
+Skills land in `~/.claude/`. Commands appear as `/gsd-*` slash commands in your next Claude Code session. Restart Claude Code to pick them up.
+
+**Override the install directory:**
+
+```bash
+CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
+```
+
+---
+
+### Gemini CLI
+
+```bash
+npx @opengsd/gsd-core@latest --gemini --global
+```
+
+Skills land in `~/.gemini/`. The installer rewrites all command bodies to Gemini's colon namespace (`/gsd:update`, `/gsd:config`, etc.). Restart Gemini CLI after install.
+
+**Override the install directory:**
+
+```bash
+GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
+```
+
+---
+
+### OpenCode
+
+```bash
+npx @opengsd/gsd-core@latest --opencode --global
+```
+
+Skills land in `~/.config/opencode/` (XDG) or `~/.opencode/`. The installer converts agent frontmatter to OpenCode's schema — removing the `tools:` field and converting colour values to hex. See [Installing without Node.js — OpenCode transformations](#opencode--required-transformations) if you need to understand what changes.
+
+**Override the install directory:**
+
+```bash
+OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
+```
+
+---
+
+### Kilo
+
+```bash
+npx @opengsd/gsd-core@latest --kilo --global
+```
+
+Skills land in `~/.config/kilo/` (XDG) or `~/.kilo/`. Uses the same OpenCode-style flat markdown command format.
+
+**Override the install directory:**
+
+```bash
+KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
+```
+
+---
+
+### Codex
+
+```bash
+npx @opengsd/gsd-core@latest --codex --global
+```
+
+Skills land in `~/.codex/skills/gsd-*/SKILL.md`. Agents are written with per-agent TOML entries in `config.toml`. Restart Codex (or run `codex --reload`) after install.
+
+**Minimum supported version:** Codex CLI 0.130.0. Earlier versions had additional skill-root scanning that can produce duplicate listings.
+
+---
+
+### GitHub Copilot
+
+```bash
+npx @opengsd/gsd-core@latest --copilot --global
+```
+
+Skills land in `~/.copilot/`. GSD installs as agent `.md` files and repository instruction files.
+
+**Override the install directory:**
+
+```bash
+COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
+```
+
+---
+
+### Cursor
+
+```bash
+npx @opengsd/gsd-core@latest --cursor --global
+```
+
+Skills land in `~/.cursor/`. GSD installs skills, agents, and rule references.
+
+**Override the install directory:**
+
+```bash
+CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
+```
+
+---
+
+### Windsurf
+
+```bash
+npx @opengsd/gsd-core@latest --windsurf --global
+```
+
+Skills land in `~/.codeium/windsurf/`. GSD installs skills, agents, and workspace rules.
+
+**Override the install directory:**
+
+```bash
+WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
+```
+
+---
+
+### Cline
+
+Cline uses a rules-based integration — GSD installs as `.clinerules` rather than slash commands.
+
+```bash
+# Global install (all projects)
+npx @opengsd/gsd-core@latest --cline --global
+
+# Local install (this project only)
+npx @opengsd/gsd-core@latest --cline --local
+```
+
+Global installs write to `~/.cline/`. Local installs write to `./.cline/`. Rules are loaded automatically by Cline — no custom slash commands are registered.
+
+---
+
+### CodeBuddy
+
+```bash
+npx @opengsd/gsd-core@latest --codebuddy --global
+```
+
+Skills land in `~/.codebuddy/skills/gsd-*/SKILL.md`.
+
+---
+
+### Qwen Code
+
+Qwen Code uses the same open skills standard as Claude Code 2.1.88+.
+
+```bash
+npx @opengsd/gsd-core@latest --qwen --global
+```
+
+Skills land in `~/.qwen/skills/gsd-*/SKILL.md`.
+
+**Override the install directory:**
+
+```bash
+QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
+```
+
+---
+
+### Augment Code
+
+```bash
+npx @opengsd/gsd-core@latest --augment --global
+```
+
+Skills land in `~/.augment/`. GSD installs skills and agents. No hook or statusline ownership.
+
+---
+
+### Antigravity
+
+```bash
+npx @opengsd/gsd-core@latest --antigravity --global
+```
+
+The installer auto-detects the Antigravity config directory (`~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, or `~/.gemini/antigravity-cli`). Uses Gemini-compatible settings policy.
+
+**Override the install directory:**
+
+```bash
+ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
+```
+
+---
+
+### Trae
+
+```bash
+npx @opengsd/gsd-core@latest --trae --global
+```
+
+Skills land in `~/.trae/`. GSD installs skills, agents, and rule references.
+
+---
+
+## Local vs global install
+
+All examples above use `--global`, which installs GSD once for your user account. To scope an install to a single project, replace `--global` with `--local`:
+
+```bash
+npx @opengsd/gsd-core@latest --claude --local
+```
+
+A local install writes into the `.claude/` directory at your project root. Local install settings take precedence over global ones when both exist.
+
+---
+
+## Installing prerelease editions (Next / Nightly / Insiders / Preview)
+
+Prerelease editions of runtimes (Windsurf Next, Cursor Nightly, VS Code Insiders, Codex preview channels, etc.) read from a sibling config directory. Set the matching `*_CONFIG_DIR` env var before running the installer:
+
+```bash
+WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
+```
+
+Select the corresponding stable runtime in the installer prompt. GSD does not enumerate prerelease editions as separate named runtimes — they are best-effort via this env-var mechanism and are not separately tested in release CI.
+
+---
+
+## Installing without Node.js
+
+If you cannot run `npx` (for example, on a Windows machine without Node.js), you have two options.
+
+**Option A — Use a machine that has Node.js.** Any machine with Node.js will do: WSL, a Linux VM, a CI runner, or a Docker container. Run the installer there, then copy the output directory to your target machine. For OpenCode:
+
+```bash
+npx @opengsd/gsd-core@latest --opencode --global
+# Then copy ~/.config/opencode/agents/ to the Windows machine
+```
+
+**Option B — Manually transform the source files.** The agent source files live in `agents/` in the GSD Core repository and are in Claude Code's native frontmatter format. Each runtime expects a different shape. For the exact field transformations per runtime, see [Manual install / no-Node.js setup](../USER-GUIDE.md#manual-install--no-nodejs-setup) in the User Guide, which covers the OpenCode transformations in full detail and points to the installer's `convert*Frontmatter` functions for other runtimes.
+
+---
+
+## After install
+
+Restart your runtime to pick up new commands and agents. Then start your first project:
+
+```bash
+/gsd-new-project
+```
+
+If the command is not found after restart, verify the install directory matches the runtime's expected config path. The prerelease-editions section above covers the most common mismatch.
+
+---
+
+## Related
+
+- [Your first project](../tutorials/your-first-project.md)
+- [Update GSD Core](update-gsd.md)
+- [Configuration](../CONFIGURATION.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/isolate-work-with-workspaces.md b/docs/how-to/isolate-work-with-workspaces.md
new file mode 100644
index 000000000..721e9030d
--- /dev/null
+++ b/docs/how-to/isolate-work-with-workspaces.md
@@ -0,0 +1,144 @@
+# How to isolate work with workspaces
+
+**Goal:** Create a fully isolated GSD environment — separate git worktree, independent `.planning/` root, and optionally multiple repositories — for feature branches or multi-repo work.
+
+**Prerequisites:** `git` is installed and the repository supports worktrees. For multi-repo workspaces, the target repos exist on your local machine or are accessible by path.
+
+---
+
+## What workspaces are
+
+A workspace is a self-contained environment that pairs one or more git worktrees (or clones) with its own `.planning/` root directory. Each workspace has:
+
+- Its own `.planning/` directory that is **completely independent** from the source repo's `.planning/` — not a subdirectory of it
+- Its own `WORKSPACE.md` manifest tracking member repos
+- Git worktrees (default) or full clones of the specified repos, checked out on a dedicated branch (default: `workspace/`)
+
+Workspaces live under `~/gsd-workspaces//` by default.
+
+```
+~/gsd-workspaces/
+└── feature-b/
+ ├── WORKSPACE.md ← manifest
+ ├── .planning/ ← fully independent GSD state
+ │ ├── PROJECT.md
+ │ ├── ROADMAP.md
+ │ └── ...
+ ├── hr-ui/ ← worktree or clone of hr-ui repo
+ └── ZeymoAPI/ ← worktree or clone of ZeymoAPI repo
+```
+
+Because the workspace's `.planning/` is separate from the source repos, there is no overlap or conflict with planning state that exists in the source repos themselves.
+
+---
+
+## Create a workspace for multiple repos
+
+```bash
+/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
+```
+
+GSD creates worktrees of `hr-ui` and `ZeymoAPI` inside `~/gsd-workspaces/feature-b/`, checks out a `workspace/feature-b` branch in each, writes `WORKSPACE.md`, and creates an empty `.planning/` directory ready for `/gsd-new-project`.
+
+To customise the location:
+
+```bash
+/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
+```
+
+---
+
+## Create a workspace for the current repo
+
+When you want feature-branch isolation on a single repo — independent branch, independent `.planning/`, no state bleed from main:
+
+```bash
+/gsd-workspace --new --name payments-rework --repos .
+```
+
+The `.` tells GSD to create a worktree of the current repo. The worktree is checked out on `workspace/payments-rework`.
+
+To force a full clone instead of a worktree:
+
+```bash
+/gsd-workspace --new --name payments-rework --repos . --strategy clone
+```
+
+---
+
+## Specify a branch explicitly
+
+```bash
+/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
+```
+
+The `--branch` flag sets the branch name for all repos in the workspace. Defaults to `workspace/`.
+
+---
+
+## Skip interactive questions
+
+```bash
+/gsd-workspace --new --name payments-rework --repos . --auto
+```
+
+GSD accepts all defaults without prompting.
+
+---
+
+## Initialise GSD inside the workspace
+
+After creating a workspace, move into it and initialise a GSD project:
+
+```bash
+cd ~/gsd-workspaces/feature-b
+/gsd-new-project
+```
+
+The `.planning/` directory inside the workspace is the root for all subsequent GSD commands run from that directory. It is entirely separate from any `.planning/` that exists in the source repos.
+
+---
+
+## List workspaces
+
+```bash
+/gsd-workspace --list
+```
+
+Prints all active GSD workspaces and their status.
+
+---
+
+## Remove a workspace
+
+```bash
+/gsd-workspace --remove feature-b
+```
+
+GSD removes the git worktrees and cleans up the workspace directory. This does not delete the branches from the origin remote — only the local worktrees and workspace directory.
+
+---
+
+## When to use workspaces instead of workstreams
+
+Choose workspaces when:
+
+- You are working across **multiple repositories** that need to be co-ordinated under one GSD project (e.g., an API repo and a UI repo that ship together)
+- You need a **separate git worktree** with its own branch, lock files, and build artefacts per feature — so builds and dependency installs in one environment cannot affect another
+- You want a **wholly independent `.planning/` root** rather than a subdirectory of the main repo's `.planning/`
+- You are following an issue-driven workflow where each tracker issue maps to a workspace (see [Drive GSD from a tracker issue](drive-gsd-from-a-tracker-issue.md))
+
+Choose [workstreams](work-in-parallel-with-workstreams.md) instead when:
+
+- All the work lives in **one repository** and shares the same git history
+- You want to run `/gsd-plan-phase` or `/gsd-discuss-phase` on different concern areas concurrently — API, UI, infra — without context bleed between their `STATE.md` files
+- You do not need a separate worktree per concern; switching planning context is sufficient
+
+---
+
+## Related
+
+- [Work in parallel with workstreams](work-in-parallel-with-workstreams.md)
+- [Drive GSD from a tracker issue](drive-gsd-from-a-tracker-issue.md)
+- [Commands](../COMMANDS.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/migrate-from-gsd-2.md b/docs/how-to/migrate-from-gsd-2.md
new file mode 100644
index 000000000..df3f4e782
--- /dev/null
+++ b/docs/how-to/migrate-from-gsd-2.md
@@ -0,0 +1,145 @@
+# How to migrate from GSD-2
+
+**Goal:** Bring an older GSD-2 project (`.gsd/` directory layout) forward into GSD Core (`.planning/` layout), and optionally absorb any existing ADRs, PRDs, or specs that live in the repository into the new planning structure.
+
+**Prerequisites:** GSD Core is installed. The GSD-2 project directory is available on disk.
+
+---
+
+## Understand what migrates
+
+GSD-2 used a `.gsd/` directory as its planning root. GSD Core uses `.planning/`. The migration reverses this: it reads `.gsd/` artifacts and writes them into the standard `.planning/` structure that all GSD Core commands expect.
+
+| What exists in GSD-2 | What `/gsd-import --from-gsd2` produces |
+|----------------------|-----------------------------------------|
+| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
+| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
+| `.gsd/STATE.md` | `.planning/STATE.md` |
+| `.gsd/phases/` directories | `.planning/phases/` directories |
+| Phase `PLAN.md` files | GSD Core `{NN}-{MM}-PLAN.md` files (renaming enforced) |
+
+Conflict detection runs before any files are written. If the target directory already has a `PROJECT.md` and the imported content contradicts it, the migration stops at the BLOCKER gate and lists the conflicts for you to resolve.
+
+---
+
+## Run the migration
+
+### Migrate the current directory
+
+```bash
+/gsd-import --from-gsd2
+```
+
+GSD reads `.gsd/` in the current working directory and writes the migrated artifacts into `.planning/`.
+
+### Migrate from a different path
+
+```bash
+/gsd-import --from-gsd2 --path ~/projects/old-project
+```
+
+Use `--path` when the GSD-2 project is not your current working directory.
+
+---
+
+## Resolve conflicts
+
+If conflict detection finds blockers — for example, a GSD-2 tech-stack declaration that contradicts an existing `.planning/PROJECT.md` — it prints a conflict report and stops without writing any files.
+
+Read the report, resolve the contradiction (edit the source document or the existing planning artifact), then re-run `/gsd-import --from-gsd2`. The migration is safe to re-run until it passes cleanly.
+
+---
+
+## Import an external plan file
+
+If you have a standalone plan document (a team planning document, a Markdown spec, an exported task list) rather than a full GSD-2 project, use `--from` instead:
+
+```bash
+/gsd-import --from /tmp/team-plan.md
+```
+
+GSD performs the same conflict-detection pass, converts the content to GSD Core `PLAN.md` format, and validates the result with the plan-checker. After validation you will see the target filename and next steps.
+
+---
+
+## Absorb existing documentation
+
+If your repository already contains ADRs (Architecture Decision Records), PRDs, or specification documents, use `/gsd-ingest-docs` to synthesise them into the `.planning/` structure after migration:
+
+### Scan the whole repository (auto-detects mode)
+
+```bash
+/gsd-ingest-docs
+```
+
+If `.planning/` is already present (for example, from the migration you just ran), GSD defaults to merge mode — it synthesises the ingested documents alongside what is already there rather than overwriting it.
+
+### Scope to a specific directory
+
+```bash
+/gsd-ingest-docs docs/
+/gsd-ingest-docs docs/adr/
+```
+
+### Use an explicit precedence manifest
+
+When documents have mixed types or you want to control which document wins on conflicts:
+
+```bash
+/gsd-ingest-docs --manifest ingest.yaml
+```
+
+The manifest is a YAML file listing `{path, type, precedence?}` per document. See the `--manifest` flag description in [Commands](../COMMANDS.md) for the expected shape.
+
+### Force a specific mode
+
+```bash
+/gsd-ingest-docs --mode merge # Merge into existing .planning/
+/gsd-ingest-docs --mode new # Bootstrap from scratch (overwrites)
+```
+
+**Output:** `/gsd-ingest-docs` always produces an `INGEST-CONFLICTS.md` with three buckets — auto-resolved, competing-variants, and unresolved-blockers. Review this file after every ingest run. Hard-stops only occur on LOCKED-vs-LOCKED ADR contradictions; everything else is surfaced for your review, not silently discarded.
+
+---
+
+## Verify the migrated project
+
+Once migration and any doc ingestion are complete, confirm the project state is consistent:
+
+```bash
+/gsd-health
+/gsd-health --repair
+```
+
+`/gsd-health` checks `.planning/` directory integrity and reports any drift. `--repair` auto-fixes recoverable issues.
+
+Then check that GSD Core can read your project state:
+
+```bash
+/gsd-progress
+```
+
+If the project came across cleanly you will see the current phase status and the recommended next step. From here the standard GSD Core workflow applies.
+
+---
+
+## Conditionals: what migrates and what does not
+
+| Situation | What to do |
+|-----------|-----------|
+| `.gsd/` exists in the current directory | Run `/gsd-import --from-gsd2` (no `--path` needed) |
+| `.gsd/` is in a different directory | Use `--path ~/projects/old-project` |
+| You have a standalone plan document, not a full GSD-2 project | Use `/gsd-import --from /path/to/plan.md` |
+| You have ADRs in `docs/adr/` | Run `/gsd-ingest-docs docs/adr/` after migration |
+| You have a mix of ADRs, PRDs, and specs | Run `/gsd-ingest-docs` at repo root; it classifies automatically |
+| Conflict detection reports blockers | Resolve the listed contradictions then re-run; no files are written until all blockers clear |
+| You are not sure whether migration worked | Run `/gsd-health` and `/gsd-progress` to confirm |
+| INGEST-CONFLICTS.md lists unresolved blockers | These require manual resolution before affected documents are incorporated into planning |
+
+---
+
+## Related
+
+- [Your first project](../tutorials/your-first-project.md)
+- [Commands](../COMMANDS.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/plan-a-phase.md b/docs/how-to/plan-a-phase.md
new file mode 100644
index 000000000..74f36e3e7
--- /dev/null
+++ b/docs/how-to/plan-a-phase.md
@@ -0,0 +1,216 @@
+# How to plan a phase
+
+**Goal:** Turn phase decisions and research into an atomic, verifiable task plan ready for execution.
+
+**Prerequisites:** `.planning/ROADMAP.md` exists. A `{phase}-CONTEXT.md` from `/gsd-discuss-phase` is strongly recommended but not required.
+
+---
+
+## Run the standard planning flow
+
+```bash
+/gsd-plan-phase 2
+```
+
+This runs three stages in sequence:
+
+1. **Research** — A `gsd-phase-researcher` subagent investigates the domain and writes `{phase}-RESEARCH.md`.
+2. **Plan** — A `gsd-planner` subagent reads context, research, and requirements, then writes one or more `{phase}-{N}-PLAN.md` files.
+3. **Verify** — A `gsd-plan-checker` subagent validates plan quality across eight dimensions and triggers a revision loop (up to three iterations) until quality gates pass.
+
+If no phase number is given, GSD Core targets the next unplanned phase from the roadmap.
+
+---
+
+## Skip or force research
+
+**If the domain is familiar and you do not need new research:**
+
+```bash
+/gsd-plan-phase 3 --skip-research
+```
+
+**If RESEARCH.md already exists but you want to force a refresh:**
+
+```bash
+/gsd-plan-phase 3 --research
+```
+
+**If you want to run research only** — write RESEARCH.md and exit before planning:
+
+```bash
+/gsd-plan-phase --research-phase 4
+```
+
+If RESEARCH.md already exists, you are prompted to update, view, or skip. To force-refresh without the prompt:
+
+```bash
+/gsd-plan-phase --research-phase 4 --research
+```
+
+To print existing RESEARCH.md to stdout without spawning the researcher:
+
+```bash
+/gsd-plan-phase --research-phase 4 --view
+```
+
+Note: `--research-phase ` is a flag on `/gsd-plan-phase`. There is no standalone research-phase command — the removed standalone research command was retired in favour of this flag.
+
+---
+
+## Plan vertical feature slices instead of horizontal layers
+
+**If you want tasks organised as thin end-to-end slices** (UI → API → DB per feature) rather than by technical layer:
+
+```bash
+/gsd-plan-phase 1 --mvp
+```
+
+On Phase 1 of a new project with no prior phase summaries, `--mvp` also produces `SKELETON.md` — a Walking Skeleton covering project scaffold, routing, one real DB read/write, one real UI interaction, and dev deployment.
+
+You can persist MVP mode for a phase without the flag by adding `**Mode:** mvp` to that phase's entry in ROADMAP.md.
+
+---
+
+## Require a failing test per behaviour-adding task
+
+**If you want TDD enforcement** — each behaviour-adding task begins with a failing test before implementation:
+
+```bash
+/gsd-plan-phase 1 --tdd
+```
+
+Composable with `--mvp`:
+
+```bash
+/gsd-plan-phase 1 --mvp --tdd
+```
+
+This produces vertical slices where every behaviour-adding task follows RED → GREEN → REFACTOR. The planner applies `type: tdd` to eligible tasks (business logic, API endpoints, data transformations) and uses standard `type: execute` for UI, configuration, and glue code.
+
+TDD mode can also be persisted in config:
+
+```bash
+node gsd-tools.cjs config-set workflow.tdd_mode true
+```
+
+---
+
+## Replan using cross-AI review feedback
+
+**If you have run `/gsd-review --phase N` and a `REVIEWS.md` exists:**
+
+```bash
+/gsd-plan-phase 3 --reviews
+```
+
+The planner reads `REVIEWS.md` and revises plans to address the feedback. Cannot be combined with `--gaps`.
+
+**If you want an automated loop** — replan and re-review until no HIGH concerns remain:
+
+```bash
+/gsd-plan-review-convergence 3
+```
+
+The convergence loop runs plan → review → replan → re-review cycles (up to three by default). Use `--max-cycles N` to override the cap.
+
+---
+
+## Close gaps after a failed verification
+
+**If `VERIFICATION.md` exists with unresolved gaps and you want to replan against those gaps only:**
+
+```bash
+/gsd-plan-phase 3 --gaps
+```
+
+Research is skipped; the planner reads the verification gaps directly.
+
+---
+
+## Validate project state before planning begins
+
+```bash
+/gsd-plan-phase 2 --validate
+```
+
+Runs state validation before spawning the researcher. Use this if you suspect ROADMAP.md or STATE.md has drifted.
+
+---
+
+## Run an external bounce validation after planning
+
+**If `workflow.plan_bounce_script` is configured and you want external validation of the finished plan:**
+
+```bash
+/gsd-plan-phase 1 --bounce
+```
+
+To skip bounce even if it is enabled in config:
+
+```bash
+/gsd-plan-phase 1 --skip-bounce
+```
+
+---
+
+## Suppress interactive confirmations
+
+```bash
+/gsd-plan-phase --auto
+```
+
+Skips all prompts. Useful in automated pipelines. Research is skipped if `research_enabled` is false in config.
+
+---
+
+## What the plan produces
+
+A successful run writes:
+
+| File | Purpose |
+|---|---|
+| `{phase}-RESEARCH.md` | Domain research, package legitimacy audit, validation architecture |
+| `{phase}-VALIDATION.md` | Nyquist test-mapping — the test cases the plan must satisfy (Dimension 8) |
+| `{phase}-{N}-PLAN.md` | Executable task plan with frontmatter, wave assignments, and acceptance criteria |
+| `{phase}/SKELETON.md` | Walking Skeleton (MVP mode, Phase 1 of new project only) |
+
+Each PLAN.md contains tasks with mandatory `` and `` fields. Every `` entry is verifiable as a source assertion, behaviour assertion, test command, or CLI output — never subjective language.
+
+For the full field reference see [PLAN.md schema](../reference/plan-md.md).
+
+### Plan quality dimensions
+
+The `gsd-plan-checker` validates plans across eight dimensions before allowing execution:
+
+1. Task atomicity — each task is a single concern
+2. Dependency correctness — wave ordering is consistent
+3. Acceptance criteria verifiability — no subjective criteria
+4. `` completeness — the file being modified is always listed
+5. Concrete `` values — no vague "align with" instructions
+6. `must_haves` derived from phase goal
+7. Requirement ID coverage — every phase requirement ID appears in at least one plan
+8. Nyquist test mapping — plans address the validation strategy in VALIDATION.md
+
+The revision loop runs up to three times. If quality gates have not passed after three iterations, the checker surfaces remaining issues for manual review.
+
+---
+
+## Replanning a closed phase
+
+If a phase has `VERIFICATION.md` with `status: passed`, it is considered closed. Attempting to replan it stops with an error. If the closeout was incorrect, override with `--force`:
+
+```bash
+/gsd-plan-phase 2 --force
+```
+
+A warning is emitted into the transcript and any committed plan docs.
+
+---
+
+## Related
+
+- [Discuss a phase](discuss-a-phase.md)
+- [Execute a phase](execute-a-phase.md)
+- [PLAN.md schema](../reference/plan-md.md)
+- [Commands](../COMMANDS.md)
diff --git a/docs/how-to/recover-and-troubleshoot.md b/docs/how-to/recover-and-troubleshoot.md
new file mode 100644
index 000000000..4d6b7e17d
--- /dev/null
+++ b/docs/how-to/recover-and-troubleshoot.md
@@ -0,0 +1,323 @@
+# How to recover and troubleshoot
+
+**Goal:** Identify and fix common problems — from lost context and corrupted state to installation failures and permission errors — using a conditional recipe structure.
+
+**Prerequisites:** GSD Core is installed. For install problems specifically, see [Install on your runtime](install-on-your-runtime.md).
+
+---
+
+## Context and session problems
+
+### If you have lost track of where you are
+
+```bash
+/gsd-progress
+```
+
+Reads all state files and tells you exactly where you are and what to do next.
+
+To automatically advance to the correct next step:
+
+```bash
+/gsd-progress --next
+```
+
+### If you are starting a new session and need to restore context
+
+```bash
+/gsd-resume-work
+```
+
+Restores your full session context from the last handoff, including current phase, planning decisions, and where work stopped.
+
+### If quality is dropping during a long session
+
+Clear your context window between major commands:
+
+```bash
+/clear
+```
+
+Then restore state:
+
+```bash
+/gsd-resume-work
+```
+
+GSD is designed around fresh contexts. Every subagent already gets a clean 200k window. The main session degrades over time — clearing it and resuming is the correct remedy, not pushing on.
+
+### If you want to save context before stopping
+
+```bash
+/gsd-pause-work
+```
+
+Creates `.planning/HANDOFF.json` with your current position. Add `--report` to also write a post-session summary to `.planning/reports/`:
+
+```bash
+/gsd-pause-work --report
+```
+
+---
+
+## Planning integrity problems
+
+### If `.planning/` integrity is uncertain
+
+```bash
+/gsd-health
+```
+
+Reports status across errors, warnings, and informational notes:
+
+| Status | Meaning |
+|--------|---------|
+| `HEALTHY` | All expected artefacts present and well-formed |
+| `DEGRADED` | Warnings that should be addressed but work can continue |
+| `BROKEN` | Critical errors that will block execution |
+
+Common auto-repairable issues (errors E004, E005; warnings W003, W008):
+
+```bash
+/gsd-health --repair
+```
+
+This recreates missing `STATE.md`, resets a corrupt `config.json` to defaults, and adds any missing configuration keys. It will not overwrite `PROJECT.md` or `ROADMAP.md`.
+
+### If STATE.md references a phase that does not exist
+
+This produces warning `W002`. Use the state CLI to diagnose and repair:
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
+```
+
+Preview what a sync would change without writing:
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
+```
+
+Apply the sync:
+
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
+```
+
+These commands reconstruct `STATE.md` from actual project state on disk. They replace manual `STATE.md` editing.
+
+### If you see "Project already initialised"
+
+`.planning/PROJECT.md` already exists. `/gsd-new-project` is a safety check. If you genuinely want to start over, delete the `.planning/` directory first:
+
+```bash
+rm -rf .planning/
+```
+
+Then re-run `/gsd-new-project`.
+
+### If context-window utilisation is high
+
+```bash
+/gsd-health --context
+```
+
+Probes the context-window utilisation guard. Warns at 60 %, critical at 70 %. If you are above the warning threshold, run `/clear` followed by `/gsd-resume-work` before starting the next major command.
+
+---
+
+## Execution problems
+
+### If an executor gets "Permission denied" on Bash commands
+
+GSD's `gsd-executor` subagents need write-capable Bash access. Add the required patterns to `~/.claude/settings.json` under `permissions.allow`. At minimum:
+
+```json
+"Bash(git add:*)",
+"Bash(git commit:*)",
+"Bash(git merge:*)",
+"Bash(git checkout:*)"
+```
+
+For stack-specific patterns (Rails, Python, Node, Rust), see the full table in `docs/USER-GUIDE.md` under "Executor Subagent Gets Permission denied".
+
+Per-project alternative: add the same block to `.claude/settings.local.json` in your project root.
+
+### If execution fails or produces stubs
+
+Check whether the plan is too ambitious. Plans should have two or three tasks at most. If tasks are too large they exceed what a single context window can produce reliably. Re-plan the phase with smaller scope:
+
+```bash
+/gsd-plan-phase 1
+```
+
+For systematic diagnosis of what went wrong, see [Debug a failed execution](debug-a-failed-execution.md).
+
+### If parallel execution causes build lock errors or pre-commit hook failures
+
+This is caused by multiple agents triggering build tools simultaneously. GSD handles this automatically since v1.26. If you are on an older version, or still seeing contention, disable parallel execution:
+
+```bash
+/gsd-settings
+```
+
+Set `parallelization.enabled` to `false`.
+
+### If a subagent appears to fail but commits were made
+
+Check git log before concluding something broke:
+
+```bash
+git log --oneline -10
+```
+
+A known Claude Code classification bug can report failure while work succeeded. GSD's orchestrators spot-check actual output, but if you see a mismatch, the commits are the ground truth.
+
+---
+
+## Plan and phase problems
+
+### If plans seem wrong or misaligned with your intent
+
+Run `/gsd-discuss-phase N` before planning. Most plan quality issues come from assumptions that `CONTEXT.md` would have prevented:
+
+```bash
+/gsd-discuss-phase 1
+```
+
+To see what assumptions GSD is currently making without starting a full session:
+
+```bash
+/gsd-discuss-phase 3 --assumptions
+```
+
+### If you need to change something after execution
+
+Do not re-run `/gsd-execute-phase`. Use `/gsd-quick` for targeted fixes:
+
+```bash
+/gsd-quick "Fix the login button not responding on mobile Safari"
+```
+
+Or use `/gsd-verify-work N` to systematically identify and fix issues through UAT.
+
+### If a command appears frozen at "Spawning…"
+
+Wait. GSD subagents run in a separate context window. Their work is invisible to the parent session while in progress. The liveness note on the spawn line confirms this is expected. Research and planning agents routinely take 1–5 minutes; verification agents can take longer on large phases.
+
+Do not interrupt the session. Killing it discards in-progress subagent work.
+
+If it has been more than 10 minutes, check whether the agent task still shows as active in the Claude Code sidebar.
+
+---
+
+## Workflow state problems
+
+### If the workflow seems corrupted or state is inconsistent
+
+```bash
+/gsd-forensics
+```
+
+Or with a description:
+
+```bash
+/gsd-forensics "Phase 3 execution stalled after wave 1"
+```
+
+`/gsd-forensics` runs a post-mortem investigation: git history anomalies, artefact integrity, STATE.md consistency, uncommitted work, and orphaned worktrees. It writes a report to `.planning/forensics/` and surfaces recommended remediation steps. It is read-only and never modifies your project files.
+
+### If you need to roll back a phase or plan
+
+```bash
+/gsd-undo --phase 03 # Roll back all commits for phase 3
+/gsd-undo --plan 03-02 # Roll back commits for plan 02 of phase 3
+/gsd-undo --last 5 # Pick interactively from the 5 most recent GSD commits
+```
+
+`/gsd-undo` checks dependent phases before reverting and always shows a confirmation gate.
+
+---
+
+## Install and update problems
+
+### If GSD is not recognised after install
+
+Restart your runtime. GSD installs slash commands into your runtime's command directory (for example `~/.claude/commands/gsd/`). Most runtimes discover new commands only at startup.
+
+If the problem persists, verify the install:
+
+```bash
+npx @opengsd/gsd-core@latest --claude --local
+```
+
+For runtime-specific install paths and troubleshooting, see [Install on your runtime](install-on-your-runtime.md).
+
+### If an update overwrote your local changes
+
+Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Reapply your changes:
+
+```bash
+/gsd-update --reapply
+```
+
+### If you cannot update via npm
+
+If `npx @opengsd/gsd-core` fails due to npm outages or network restrictions, see `docs/manual-update.md` for a step-by-step manual update procedure that works without npm access.
+
+For routine updates, see [Update GSD](update-gsd.md).
+
+---
+
+## Cost problems
+
+### If model costs are too high
+
+Switch to the budget profile:
+
+```bash
+/gsd-config --profile budget
+```
+
+Disable research and plan-check agents via settings if the domain is familiar:
+
+```bash
+/gsd-settings
+```
+
+Also audit which MCP servers are enabled. Every enabled MCP server injects its tool schema into every turn. Browser and platform-specific tools can cost 20k+ tokens each. Disable any that the current phase does not need in `.claude/settings.json`:
+
+```json
+{
+ "disabledMcpjsonServers": ["playwright", "mac-tools"]
+}
+```
+
+---
+
+## Recovery quick reference
+
+| Problem | Solution |
+|---------|---------|
+| Lost context or new session | `/gsd-resume-work` or `/gsd-progress` |
+| Don't know what step is next | `/gsd-progress --next` |
+| Phase went wrong | `/gsd-undo --phase NN`, then re-plan |
+| Something broke | `/gsd-debug "description"` (add `--diagnose` for analysis without fixes) |
+| STATE.md out of sync | `state validate` then `state sync` |
+| `.planning/` integrity uncertain | `/gsd-health`, then `/gsd-health --repair` |
+| Workflow state seems corrupted | `/gsd-forensics` |
+| Quick targeted fix | `/gsd-quick` |
+| Plan doesn't match your vision | `/gsd-discuss-phase N` then re-plan |
+| Costs running high | `/gsd-config --profile budget` and `/gsd-settings` to toggle agents off |
+| Update broke local changes | `/gsd-update --reapply` |
+| Want session summary | `/gsd-pause-work --report` |
+| Parallel execution build errors | Update GSD or set `parallelization.enabled: false` |
+
+---
+
+## Related
+
+- [Debug a failed execution](debug-a-failed-execution.md)
+- [Install on your runtime](install-on-your-runtime.md)
+- [Commands](../COMMANDS.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/run-phases-autonomously.md b/docs/how-to/run-phases-autonomously.md
new file mode 100644
index 000000000..ebd0bd428
--- /dev/null
+++ b/docs/how-to/run-phases-autonomously.md
@@ -0,0 +1,124 @@
+# How to run phases autonomously
+
+Run all remaining phases — or a bounded range of them — unattended, so GSD moves through discuss → plan → execute for each phase without you driving every step.
+
+For background on what the phase loop is doing during an autonomous run, see [The phase loop](../explanation/the-phase-loop.md).
+
+---
+
+## Prerequisites
+
+- An active project with `.planning/ROADMAP.md` and `.planning/STATE.md`
+- All phases you want to run must be in a state that autonomous mode can drive (pending or in-progress; not already complete)
+- Any design decisions you care about should already be in `PROJECT.md` or captured via a prior `/gsd-discuss-phase` — autonomous mode can surface grey areas interactively only when you use `--interactive`
+
+---
+
+## Run all remaining phases
+
+```bash
+/gsd-autonomous
+```
+
+GSD reads `ROADMAP.md`, discovers every incomplete phase in numeric order, and runs discuss → plan → execute on each one. After all phases complete it automatically runs the milestone lifecycle: audit → complete → cleanup.
+
+---
+
+## Run a specific range of phases
+
+Use `--from` and `--to` to bound the run. Both flags accept decimal phase numbers (e.g. `3.1`).
+
+```bash
+/gsd-autonomous --from 3 # phases 3, 4, 5 … (skip already-done phases 1 and 2)
+/gsd-autonomous --to 5 # phases up to and including 5
+/gsd-autonomous --from 3 --to 5 # exactly phases 3, 4, and 5
+```
+
+When `--to` is reached the lifecycle step is skipped, because not all milestone phases are done. The completion banner tells you how to resume:
+
+```text
+Resume with: /gsd-autonomous --from 6
+```
+
+---
+
+## Run with interactive discuss
+
+By default, autonomous mode answers discuss questions automatically using smart discuss (batch table proposals). If you want to answer design questions yourself while keeping plan and execute out of the main context:
+
+```bash
+/gsd-autonomous --interactive
+```
+
+In interactive mode:
+- `/gsd-discuss-phase` runs inline and waits for your answers
+- Planning and execution are dispatched as background agents so you can discuss the next phase while the current one builds
+- The main context stays lean — only discuss conversations accumulate
+
+---
+
+## What safety gates still apply
+
+Autonomous mode does not bypass GSD's quality pipeline. Each phase still:
+
+- Runs the plan-checker before execution
+- Reads `VERIFICATION.md` after execution and routes on the result
+- Pauses and asks you what to do when verification status is `human_needed` or `gaps_found`
+- Stops and presents options (fix and retry, skip phase, or stop) if any step fails
+
+The only difference from manual execution is that `passed` verification advances automatically — you are not prompted between phases unless a decision is required.
+
+The package legitimacy gate also remains active. If a plan includes a `checkpoint:human-verify` task for a suspicious package, the executor will stop and surface the checkpoint. Autonomous mode will not silently install flagged packages.
+
+---
+
+## When not to use autonomous mode
+
+Do not use `/gsd-autonomous` when:
+
+- **Phases have unsettled design decisions.** If you have not run `/gsd-discuss-phase` and your `PROJECT.md` does not capture your preferences, smart discuss will make autonomous choices you may not agree with. Run discuss interactively first, or use `--interactive`.
+
+- **You need fine-grained control over a single phase.** For one phase, `/gsd-execute-phase N` gives you step-by-step output and lets you react before continuing. Autonomous mode is designed for bulk unattended runs.
+
+- **The phase has novel or high-risk work.** Autonomous mode skips pauses unless it hits a blocker. On a phase where you expect surprises, stay in the loop with manual execution.
+
+- **You are mid-phase with partial execution.** Autonomous mode picks up incomplete phases but it does not resume a partially-executed wave. Use `/gsd-execute-phase N` to finish a phase that is already in progress.
+
+If a run stops partway through, see [Debug a failed execution](debug-a-failed-execution.md) for how to diagnose what went wrong.
+
+---
+
+## Checking progress during a run
+
+Autonomous mode prints a progress banner before each phase:
+
+```text
+ GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
+```
+
+If you need to check where the run stands mid-session, open another terminal and run:
+
+```bash
+/gsd-progress
+```
+
+---
+
+## Resuming after a stop
+
+If autonomous mode stops — whether you chose "Stop autonomous mode" from the blocker prompt, or the session was interrupted — resume from where it left off:
+
+```bash
+/gsd-autonomous --from 4 # replace 4 with the first incomplete phase number
+```
+
+GSD skips already-complete phases automatically, so it is safe to re-run from an earlier phase number if you are not sure where the run stopped.
+
+---
+
+## Related
+
+- [Execute a phase](execute-a-phase.md)
+- [Debug a failed execution](debug-a-failed-execution.md)
+- [Commands](../COMMANDS.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/set-up-cross-ai-review.md b/docs/how-to/set-up-cross-ai-review.md
new file mode 100644
index 000000000..305ba7e52
--- /dev/null
+++ b/docs/how-to/set-up-cross-ai-review.md
@@ -0,0 +1,159 @@
+# How to set up cross-AI review
+
+**Goal:** Configure which AI reviewers participate in plan review, run a review of a planned phase, and use the feedback to converge on a plan with no HIGH-severity concerns.
+
+**Prerequisites:** The phase has been planned (`{phase}-PLAN.md` files exist in `.planning/phases/`). At least one external AI CLI is installed and authenticated.
+
+---
+
+## Decide which reviewers to use
+
+GSD Core can route review requests to any combination of: Gemini CLI, Claude (separate session), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio, and llama.cpp.
+
+Each reviewer runs the same structured prompt against your `PLAN.md` files independently. Because different models have different blind spots, multi-reviewer consensus catches more issues than any single reviewer.
+
+**If you have no external CLIs installed yet**, install at least one:
+
+```bash
+# Gemini CLI (free with Google credentials)
+npm install -g @google/gemini-cli
+
+# Antigravity CLI (free with Google credentials)
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+
+# Codex CLI
+npm install -g @openai/codex
+```
+
+---
+
+## Set default reviewers (optional)
+
+By default, `/gsd-review` runs all detected CLIs. To pin a subset as project defaults:
+
+```bash
+/gsd-config --integrations
+```
+
+The integrations wizard covers API keys, code-review CLI routing, and the `review.default_reviewers` list. Set the list to the reviewers you want as the no-flag default — for example `["gemini","codex"]`.
+
+Alternatively, set it directly with `gsd-tools`:
+
+```bash
+gsd config-set review.default_reviewers '["gemini","codex"]'
+```
+
+For the full integration settings schema (API keys, model overrides per reviewer, local server host addresses), see [Configuration](../CONFIGURATION.md).
+
+---
+
+## Run a review
+
+### Standard review (uses your configured defaults or all detected CLIs)
+
+```bash
+/gsd-review --phase 3
+```
+
+GSD invokes each reviewer in sequence, collects structured feedback (Summary, Strengths, Concerns at HIGH/MEDIUM/LOW, Suggestions, Risk Assessment), and writes the combined output to `.planning/phases/03-.../03-REVIEWS.md`.
+
+### Select a single reviewer for a one-off run
+
+```bash
+/gsd-review --phase 3 --gemini
+/gsd-review --phase 3 --codex
+/gsd-review --phase 3 --cursor
+```
+
+Any explicit flag overrides both the `--all` default and `review.default_reviewers` for that run.
+
+### Run every available reviewer in parallel
+
+```bash
+/gsd-review --phase 3 --all
+```
+
+`--all` always overrides config and runs the full detected set, including any configured local model servers (Ollama, LM Studio, llama.cpp).
+
+### Local model server reviewers
+
+If you run Ollama or LM Studio locally, they are included automatically with `--all` when the server is reachable. You can also target them explicitly:
+
+```bash
+/gsd-review --phase 3 --ollama
+/gsd-review --phase 3 --lm-studio
+```
+
+Configure the host addresses and model selection under `review.*` keys via `/gsd-config --integrations` if the defaults (`localhost:11434` / `localhost:1234`) do not apply.
+
+---
+
+## Read the review output
+
+The `{padded_phase}-REVIEWS.md` file contains:
+
+- Individual reviews from each reviewer with severity-classified concerns
+- A **Consensus Summary** section that synthesises concerns raised by two or more reviewers — start here for the highest-priority signal
+- A **Divergent Views** section for areas where reviewers disagreed
+
+---
+
+## Incorporate feedback into the plan
+
+Once you have reviewed the output, replan incorporating the feedback:
+
+```bash
+/gsd-plan-phase 3 --reviews
+```
+
+The planner reads `REVIEWS.md` and adjusts the plans to address the concerns before saving.
+
+---
+
+## Automate the plan–review–replan loop
+
+For phases where you want to iterate until all HIGH-severity concerns are resolved, use the convergence loop:
+
+```bash
+/gsd-plan-review-convergence 3
+```
+
+This runs `plan-phase → review → replan → re-review` up to three cycles (default). The loop exits when the HIGH-concern count reaches zero.
+
+### Convergence with a specific reviewer
+
+```bash
+/gsd-plan-review-convergence 3 --codex
+/gsd-plan-review-convergence 3 --gemini
+```
+
+### Convergence with all reviewers and a higher cycle cap
+
+```bash
+/gsd-plan-review-convergence 3 --all --max-cycles 5
+```
+
+**Stall detection:** if the HIGH-concern count is not decreasing across cycles, GSD warns you. When the cycle cap is reached with open HIGH concerns, an escalation gate asks whether to proceed or review manually.
+
+---
+
+## Conditionals: which reviewers to choose
+
+| Situation | Recommended approach |
+|-----------|---------------------|
+| You have Gemini CLI already installed | `--gemini` is always a good starting reviewer |
+| You want free multi-reviewer coverage | `--gemini` + `--agy` (both use Google credentials) |
+| Your project is OpenAI-heavy | add `--codex` for an OpenAI-model perspective |
+| You want GitHub Copilot's model | add `--opencode` |
+| You want to avoid API costs entirely | configure Ollama with a local model and use `--ollama` |
+| You need maximum coverage before a release | `/gsd-plan-review-convergence N --all` |
+| You're iterating quickly and want fast feedback | pick one CLI: `/gsd-review --phase N --gemini` |
+
+---
+
+## Related
+
+- [Verify and ship](verify-and-ship.md)
+- [Configuration](../CONFIGURATION.md)
+- [Commands](../COMMANDS.md)
+- [docs index](../README.md)
diff --git a/docs/how-to/spike-and-sketch.md b/docs/how-to/spike-and-sketch.md
new file mode 100644
index 000000000..ea93c9d0f
--- /dev/null
+++ b/docs/how-to/spike-and-sketch.md
@@ -0,0 +1,160 @@
+# How to spike and sketch before committing
+
+**Goal:** De-risk an implementation by running focused feasibility experiments (spikes) and exploring visual directions through throwaway HTML mockups (sketches) before committing a phase to any specific approach.
+
+**Prerequisites:** None. `/gsd-spike` and `/gsd-sketch` create their own storage directories and do not require an initialised GSD project.
+
+---
+
+## Decide: spike, sketch, or both
+
+| You want to answer… | Use |
+|---|---|
+| "Will this technical approach actually work?" | `/gsd-spike` |
+| "Does this layout / interaction / visual treatment feel right?" | `/gsd-sketch` |
+| "What's the right technical approach, and what should it look like?" | Both, in order: spike first, then sketch |
+
+Spikes answer binary feasibility questions with executable code and a VALIDATED / INVALIDATED / PARTIAL verdict. Sketches answer visual questions with 2–3 browser-comparable HTML variants. They are complementary — a spike proves the approach is buildable, a sketch proves the design is worth building.
+
+---
+
+## Run a spike
+
+### Interactive intake (default)
+
+```bash
+/gsd-spike
+```
+
+GSD asks about the technical question, decomposes it into 2–5 independent experiments framed as **Given / When / Then** hypotheses, and asks for confirmation before building.
+
+### Provide the idea directly
+
+```bash
+/gsd-spike "can we stream LLM tokens through SSE"
+```
+
+### Skip intake and run immediately
+
+```bash
+/gsd-spike --quick "websocket vs SSE latency"
+```
+
+`--quick` skips the decomposition conversation and treats the argument as a single spike question. Use this when the question is already specific enough to run without refinement.
+
+### What each experiment produces
+
+Each spike in `.planning/spikes/NNN-descriptive-name/` includes:
+
+- Working code (not pseudocode)
+- A **Given / When / Then** hypothesis written before any code
+- An investigation trail documenting edge cases, pivots, and surprises
+- A **VALIDATED**, **INVALIDATED**, or **PARTIAL** verdict with evidence
+- A `README.md` with frontmatter, how-to-run instructions, and results
+
+All spikes are indexed in `.planning/spikes/MANIFEST.md`.
+
+### Package the findings
+
+When you have signal, wrap the findings into a project-local skill so future sessions load them automatically:
+
+```bash
+/gsd-spike --wrap-up
+```
+
+This writes `.claude/skills/spike-findings-[project]/`. The skill is discovered automatically and loaded by subsequent `/gsd-sketch`, `/gsd-ui-phase`, and `/gsd-plan-phase` runs — you do not need to reference it explicitly.
+
+---
+
+## Run a sketch
+
+### Mood intake (default)
+
+```bash
+/gsd-sketch
+```
+
+GSD opens a short conversation to explore feel, visual references, and the core user action before any code is written. It asks one question at a time and only starts building when you say go.
+
+### Provide a design direction directly
+
+```bash
+/gsd-sketch "dashboard layout"
+```
+
+### Skip mood intake and run immediately
+
+```bash
+/gsd-sketch --quick "sidebar navigation"
+```
+
+`--quick` skips the intake conversation entirely and uses the argument as the design direction.
+
+### Non-Claude runtimes (Codex, Gemini CLI, etc.)
+
+```bash
+/gsd-sketch --text "onboarding flow"
+```
+
+`--text` replaces interactive prompts with plain-text numbered lists. Use this when your runtime does not support `AskUserQuestion`.
+
+### What each sketch produces
+
+Each sketch in `.planning/sketches/NNN-descriptive-name/` includes:
+
+- `index.html` with 2–3 variants accessible via tab navigation — open directly in a browser, no build step
+- Functional interactive elements (hover, click, transitions)
+- Real-ish content using field names and data shapes from any prior spike findings
+- Shared CSS variables from `.planning/sketches/themes/default.css`
+- A `README.md` with the design question, variants, and what to look for
+
+All sketches are indexed in `.planning/sketches/MANIFEST.md`.
+
+### Package the winning design decisions
+
+After picking a variant, capture the visual decisions into a project-local skill:
+
+```bash
+/gsd-sketch --wrap-up
+```
+
+This writes `.claude/skills/sketch-findings-[project]/`. The skill is picked up automatically by `/gsd-ui-phase` — pre-validated decisions (layout, colour palette, typography, spacing) are treated as locked and are not re-asked.
+
+---
+
+## Combined flow: spike → sketch → phase
+
+This is the recommended sequence when you are uncertain about both technical feasibility and visual direction:
+
+```bash
+/gsd-spike "SSE vs WebSocket for real-time feed"
+/gsd-spike --wrap-up
+
+/gsd-sketch "real-time feed UI"
+/gsd-sketch --wrap-up
+
+/gsd-discuss-phase N
+/gsd-plan-phase N
+```
+
+The spike findings inform the sketch (real data shapes, real interaction states, realistic constraints). Both wrap-ups persist decisions that the planner and UI researcher load automatically, so you do not need to re-explain choices during `/gsd-discuss-phase` or `/gsd-ui-phase`.
+
+---
+
+## How a spike or sketch feeds into a phase
+
+Spike and sketch artifacts do not need to be manually referenced. GSD reads them automatically at two points:
+
+1. **`/gsd-sketch`** — loads `.claude/skills/spike-findings-*/` before building mockups, so variants reflect proven constraints (streaming states, real field names, etc.)
+2. **`/gsd-ui-phase N`** — loads `.claude/skills/sketch-findings-*/` before generating the UI design contract; pre-validated design decisions are treated as locked
+
+The planner also reads spike findings when a `spike-findings-*` skill is present, so validated technical choices (which library, which protocol, which data format) flow directly into task plans without repeated explanation.
+
+---
+
+## Related
+
+- [Design a UI phase](design-a-ui-phase.md)
+- [Plan a phase](plan-a-phase.md)
+- [Commands](../COMMANDS.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/update-gsd.md b/docs/how-to/update-gsd.md
new file mode 100644
index 000000000..01887fc1c
--- /dev/null
+++ b/docs/how-to/update-gsd.md
@@ -0,0 +1,120 @@
+# How to update GSD Core
+
+Update an existing GSD Core install to the latest release, preview the changelog before committing, and recover any local customisations that the update would overwrite.
+
+**What you need:** The same runtime GSD is installed for. The update command re-runs the installer under the hood, so it needs Node.js and npx available (same requirement as the original install).
+
+---
+
+## The standard update path
+
+From inside your AI runtime, run:
+
+```bash
+/gsd-update
+```
+
+GSD will:
+
+1. Detect the installed version and install scope (global or local).
+2. Check npm for the latest release of `@opengsd/gsd-core`.
+3. Fetch the changelog and show you what changed between your installed version and the latest.
+4. Ask for confirmation before touching anything.
+5. Back up any user-added files found inside GSD-managed directories to `gsd-user-files-backup/`.
+6. Run the installer (`npx @opengsd/gsd-core@latest -- --`).
+7. Clear the update-check cache so the statusline indicator resets.
+8. Report whether locally modified GSD files were backed up to `gsd-local-patches/`.
+
+Restart your runtime after the update to pick up new commands and agents.
+
+---
+
+## Flags
+
+| Flag | What it does |
+|------|--------------|
+| `--sync` | After updating, sync skills from the GSD registry |
+| `--reapply` | After updating, merge locally modified GSD files back in from `gsd-local-patches/` |
+
+```bash
+/gsd-update --sync # Update and sync skills
+/gsd-update --reapply # Update and reapply local patches
+```
+
+---
+
+## Reviewing the changelog before updating
+
+`/gsd-update` always shows the changelog diff between your installed version and the latest *before* it asks for confirmation. You do not need to visit GitHub separately. The output looks like:
+
+```text
+## GSD Update Available
+
+Installed: 1.39.0
+Latest: 1.41.0
+
+### What's New
+────────────────────────────────────────────────────────────
+[changelog entries for 1.40.0 and 1.41.0]
+────────────────────────────────────────────────────────────
+
+Proceed with update? [Yes, update now / No, cancel]
+```
+
+If the changelog cannot be fetched (no network access, npm outage), the update still proceeds after confirmation — it does not block on changelog availability.
+
+---
+
+## Recovering local customisations
+
+### Files you added inside GSD-managed directories
+
+If you placed custom files inside directories that GSD owns (for example, custom agents prefixed with `gsd-` or extra files in `commands/gsd/`), the installer will detect them and copy them to `gsd-user-files-backup/` before wiping those directories. After the update, restore them manually from that backup location.
+
+Files you placed outside GSD-managed directories — custom agents not prefixed with `gsd-`, custom commands outside `commands/gsd/`, your `CLAUDE.md` files, and custom hooks — are never touched by the installer.
+
+### GSD files you modified directly
+
+If you edited a file that GSD installed (for example, tweaking an agent's system prompt), the installer detects the modification via a hash comparison against its manifest, backs the file up to `gsd-local-patches/`, and then replaces it with the new version. After the update:
+
+```bash
+/gsd-update --reapply
+```
+
+This merges your modifications from `gsd-local-patches/` back into the newly installed files.
+
+If you skipped `--reapply` after a previous update and want to apply patches now:
+
+```bash
+/gsd-update --reapply
+```
+
+It is safe to run `--reapply` on its own without triggering a new download — if you are already on the latest version, GSD skips the install step and goes straight to reapplying patches.
+
+---
+
+## When npm is unavailable
+
+If `npx @opengsd/gsd-core@latest` fails due to an npm outage, network restrictions, or because you are working from the source repository, use the manual update procedure in [docs/manual-update.md](../manual-update.md). That document covers pulling the latest commit, building the hooks dist, and running `node bin/install.js` directly.
+
+---
+
+## If you are already on the latest version
+
+`/gsd-update` exits early with a confirmation message — no download, no install, no restart needed.
+
+---
+
+## Installer migrations
+
+Each GSD release may include installer migrations that rename, move, or retire managed files. The migration layer runs automatically before the new package payload is written. Migrations that would affect files you have modified prompt for confirmation rather than acting silently. For the full design and runtime-configuration contract registry, see [docs/installer-migrations.md](../installer-migrations.md).
+
+---
+
+## Related
+
+- [Install on your runtime](install-on-your-runtime.md)
+- [Commands reference](../COMMANDS.md)
+- [Manual update](../manual-update.md)
+- [Installer migrations](../installer-migrations.md)
+- [Docs index](../README.md)
diff --git a/docs/how-to/verify-and-ship.md b/docs/how-to/verify-and-ship.md
new file mode 100644
index 000000000..c05ce4b10
--- /dev/null
+++ b/docs/how-to/verify-and-ship.md
@@ -0,0 +1,124 @@
+# How to verify and ship a phase
+
+**Goal:** Walk executed work through user acceptance testing, diagnose and fix any failures, then open a pull request with an auto-generated body.
+
+**Prerequisites:** The phase has been executed and has `SUMMARY.md` files. If execution is not yet done, see [Execute a phase](execute-a-phase.md).
+
+---
+
+## Run user acceptance testing
+
+```bash
+/gsd-verify-work 1
+```
+
+GSD reads the phase's `SUMMARY.md` files, extracts user-observable deliverables, and walks you through them one at a time. For each checkpoint it presents what *should* happen and asks whether reality matches.
+
+- `yes` / `y` / empty → pass, move to next test
+- Anything else → recorded as an issue, severity inferred from your description
+
+You never need to categorise severity — GSD infers it from your words ("crashes" → blocker, "doesn't work" → major, "looks off" → cosmetic).
+
+Progress is written to `.planning/phases/01-/01-UAT.md` and survives a `/clear`. If a session is interrupted, re-run `/gsd-verify-work 1` and GSD offers to resume from the last checkpoint.
+
+---
+
+## When failures are found: auto-diagnose and fix planning
+
+If any tests report issues, GSD proceeds automatically:
+
+1. **Diagnoses root causes** — spawns parallel debug agents, one per issue, and updates `UAT.md` with root causes.
+2. **Plans gap closure** — spawns a `gsd-planner` in gap-closure mode, which reads `UAT.md` (with diagnoses) and writes new `PLAN.md` files.
+3. **Verifies the fix plans** — spawns a `gsd-plan-checker` to ensure the plans are executable. If issues are found, the planner and checker iterate up to three times.
+4. **Presents next step** — when plans pass the checker:
+
+```
+Plans verified and ready for execution.
+
+`/clear` then `/gsd-execute-phase 1 --gaps-only`
+```
+
+Run the suggested command to apply fixes, then re-run `/gsd-verify-work 1` to confirm everything passes.
+
+---
+
+## When all tests pass: ship the phase
+
+Once all UAT tests pass (or if this is your first run and no issues are found), the phase is marked complete in `ROADMAP.md` and `STATE.md` automatically.
+
+```bash
+/gsd-ship 1
+```
+
+GSD runs preflight checks (verification status, clean working tree, branch, remote, `gh` CLI authentication), pushes the branch, and creates a PR:
+
+```bash
+/gsd-ship 1 # Ready-for-review PR
+/gsd-ship 1 --draft # Draft PR — useful when more phases will follow
+```
+
+The PR body is assembled from planning artefacts automatically:
+
+- Phase goal from `ROADMAP.md`
+- Per-plan summaries from `SUMMARY.md` files and their key files
+- Requirements addressed (REQ-IDs)
+- Verification status from `VERIFICATION.md`
+- Key decisions from `STATE.md`
+
+No manual body writing required.
+
+---
+
+## Optional: code review before or after shipping
+
+`/gsd-ship` does not run a code review automatically, but you can slot one in at any point:
+
+**Before verification** (catches issues before UAT):
+
+```bash
+/gsd-code-review 1 # Standard review
+/gsd-code-review 1 --fix # Review then auto-fix Critical + Warning findings
+```
+
+**After the PR is open** (to gate on quality before merge):
+
+```bash
+/gsd-code-review 1 --depth=deep # Cross-file analysis including import graphs
+```
+
+See [Set up cross-AI review](set-up-cross-ai-review.md) to configure Gemini, Codex, or other reviewers for plan review earlier in the cycle.
+
+---
+
+## Optional: create a clean PR branch
+
+If your branch contains `.planning/` commits that you do not want reviewers to see:
+
+```bash
+/gsd-pr-branch # Filter against main
+/gsd-pr-branch develop # Filter against develop
+```
+
+`/gsd-pr-branch` creates a new branch with only code changes — planning artefact commits are excluded. Run this before `/gsd-ship` if your team's review policy excludes planning noise.
+
+---
+
+## Closing a milestone
+
+If this was the last phase in the milestone, run the milestone audit and archive it:
+
+```bash
+/gsd-audit-milestone # Verify all requirements shipped
+/gsd-complete-milestone # Archive, create git tag
+```
+
+`/gsd-complete-milestone` is the natural next step after the PR merges. See the [The phase loop](../explanation/the-phase-loop.md) for how verification and shipping fit into the full project lifecycle.
+
+---
+
+## Related
+
+- [Execute a phase](execute-a-phase.md)
+- [Set up cross-AI review](set-up-cross-ai-review.md)
+- [The phase loop](../explanation/the-phase-loop.md)
+- [Commands](../COMMANDS.md)
diff --git a/docs/how-to/work-in-parallel-with-workstreams.md b/docs/how-to/work-in-parallel-with-workstreams.md
new file mode 100644
index 000000000..bfbda8872
--- /dev/null
+++ b/docs/how-to/work-in-parallel-with-workstreams.md
@@ -0,0 +1,157 @@
+# How to work on multiple areas in parallel with workstreams
+
+**Goal:** Run concurrent work on different milestone areas — backend API, frontend dashboard, infrastructure, or any other concern — without planning state from one area bleeding into another.
+
+**Prerequisites:** An active GSD Core project (`.planning/ROADMAP.md` exists). If not, run `/gsd-new-project` first.
+
+---
+
+## What workstreams are
+
+A workstream is an isolated planning context within a single codebase. Each workstream gets its own `.planning/workstreams//` subtree containing independent `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md`, and `phases/` directories. The codebase itself — source code, git history, and branches — is shared across all workstreams.
+
+```
+.planning/
+├── PROJECT.md ← shared
+├── config.json ← shared
+├── codebase/ ← shared
+└── workstreams/
+ ├── backend-api/
+ │ ├── STATE.md
+ │ ├── ROADMAP.md
+ │ ├── REQUIREMENTS.md
+ │ └── phases/
+ └── frontend-dash/
+ ├── STATE.md
+ ├── ROADMAP.md
+ ├── REQUIREMENTS.md
+ └── phases/
+```
+
+When a workstream is active, every GSD command — `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase` — reads from and writes to that workstream's directory. Switching workstreams redirects all of those commands to a different subtree without touching the source tree.
+
+---
+
+## Create a workstream
+
+```bash
+/gsd-workstreams create backend-api
+```
+
+GSD creates the workstream directory under `.planning/workstreams/backend-api/` and seeds it with a skeleton `STATE.md` and `ROADMAP.md`. The workstream is not automatically activated — you switch to it explicitly.
+
+---
+
+## List workstreams
+
+```bash
+/gsd-workstreams list
+```
+
+Shows all workstreams and which one is currently active in your session.
+
+---
+
+## Switch to a workstream
+
+```bash
+/gsd-workstreams switch backend-api
+```
+
+From this point forward, all GSD workflow commands operate in the `backend-api` context. The switch is session-scoped: when multiple Claude Code terminals are open on the same repo, each session can hold a different active workstream without interfering with the others.
+
+Once switched, drive the normal phase workflow:
+
+```bash
+/gsd-discuss-phase 1
+/gsd-plan-phase 1
+/gsd-execute-phase 1
+/gsd-verify-work 1
+```
+
+To work on another area, switch workstreams in a second terminal:
+
+```bash
+/gsd-workstreams switch frontend-dash
+/gsd-discuss-phase 1
+/gsd-plan-phase 1
+```
+
+---
+
+## Check progress across all workstreams
+
+```bash
+/gsd-workstreams progress
+```
+
+Prints a cross-workstream summary — phase status, current position, and outstanding work for every workstream — without requiring you to switch between them.
+
+For detailed status on a single workstream:
+
+```bash
+/gsd-workstreams status backend-api
+```
+
+---
+
+## Resume work in a workstream
+
+After a context reset or a new session, restore your position:
+
+```bash
+/gsd-workstreams resume backend-api
+```
+
+This activates the workstream and restores your last known position within it, equivalent to switching and then running `/gsd-resume-work`.
+
+---
+
+## Archive a completed workstream
+
+When a workstream's milestone work is done:
+
+```bash
+/gsd-workstreams complete backend-api
+```
+
+GSD marks the workstream as archived and moves it out of the active listing. The planning artifacts are preserved under `.planning/workstreams/backend-api/` for audit purposes.
+
+---
+
+## Scope a single command to a workstream without switching
+
+If you need to run one command against a specific workstream without changing your session's active context, use the `--ws` flag:
+
+```bash
+/gsd-progress --ws frontend-dash
+/gsd-plan-phase 2 --ws backend-api
+```
+
+`--ws` takes highest priority in the resolution order and does not alter the session-scoped pointer.
+
+---
+
+## When to use workstreams instead of workspaces
+
+Choose workstreams when:
+
+- All the work lives in the **same repository** and shares the same git history
+- You want to plan or discuss different concern areas (API, UI, infra) **concurrently** without one workstream's `STATE.md` overwriting another's
+- You do not need a separate branch per workstream at creation time (though you can branch as normal within each workstream's execution)
+- The overhead of creating full git worktrees is not justified by the isolation you need
+
+Choose [workspaces](isolate-work-with-workspaces.md) instead when:
+
+- You are working across **multiple repositories** (e.g., `hr-ui` and `ZeymoAPI`)
+- You need the isolation of a **separate git worktree** or clone per feature — fully independent branches, lock files, and build artefacts
+- You want to run `/gsd-new-project` independently in each workspace with a wholly separate `.planning/` root, not a subdirectory of the main repo's `.planning/`
+
+---
+
+## Related
+
+- [Isolate work with workspaces](isolate-work-with-workspaces.md)
+- [The phase loop](../explanation/the-phase-loop.md)
+- [Commands](../COMMANDS.md)
+- [docs index](../README.md)
diff --git a/docs/issue-driven-orchestration.md b/docs/issue-driven-orchestration.md
index 4dbe361a1..a37cdd00a 100644
--- a/docs/issue-driven-orchestration.md
+++ b/docs/issue-driven-orchestration.md
@@ -173,11 +173,10 @@ scope for this guide.
## Related
-- [docs/USER-GUIDE.md](USER-GUIDE.md) — task-oriented walkthroughs of
- individual commands referenced above.
-- [docs/COMMANDS.md](COMMANDS.md) — full reference for `/gsd-*`
- commands.
-- [docs/FEATURES.md](FEATURES.md) — feature-level capability matrix
- (workspaces, manager, autonomous, verify, review, ship).
-- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — phase-artifact lifecycle
- and `STATE.md` mechanics.
+- [The phase loop](explanation/the-phase-loop.md) — how discuss → plan → execute → verify → ship fits together as a repeating cycle.
+- [Workspaces how-to](how-to/work-in-parallel-with-workstreams.md) — step-by-step guide to creating and managing parallel worktrees.
+- [docs index](README.md) — full table of contents for GSD Core documentation.
+- [docs/USER-GUIDE.md](./USER-GUIDE.md) — task-oriented walkthroughs of individual commands referenced above.
+- [docs/COMMANDS.md](COMMANDS.md) — full reference for `/gsd-*` commands.
+- [docs/FEATURES.md](FEATURES.md) — feature-level capability matrix (workspaces, manager, autonomous, verify, review, ship).
+- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — phase-artifact lifecycle and `STATE.md` mechanics.
diff --git a/docs/ja-JP/ARCHITECTURE.md b/docs/ja-JP/ARCHITECTURE.md
index 2e35ec039..236aace0f 100644
--- a/docs/ja-JP/ARCHITECTURE.md
+++ b/docs/ja-JP/ARCHITECTURE.md
@@ -1,30 +1,30 @@
-# GSD アーキテクチャ
+# GSD Core アーキテクチャ
-> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは[機能リファレンス](FEATURES.md)または[ユーザーガイド](USER-GUIDE.md)をご覧ください。
+> コントリビューターおよび上級ユーザー向けのシステムアーキテクチャ文書です。ユーザー向けドキュメントは [機能リファレンス](FEATURES.md) または [ユーザーガイド](USER-GUIDE.md) をご覧ください。
---
## 目次
-- [システム概要](#システム概要)
-- [設計原則](#設計原則)
-- [コンポーネントアーキテクチャ](#コンポーネントアーキテクチャ)
-- [エージェントモデル](#エージェントモデル)
-- [データフロー](#データフロー)
-- [ファイルシステムレイアウト](#ファイルシステムレイアウト)
-- [インストーラーアーキテクチャ](#インストーラーアーキテクチャ)
-- [フックシステム](#フックシステム)
-- [CLIツールレイヤー](#cliツールレイヤー)
-- [ランタイム抽象化](#ランタイム抽象化)
+- [システム概要](#system-overview)
+- [設計原則](#design-principles)
+- [コンポーネントアーキテクチャ](#component-architecture)
+- [エージェントモデル](#agent-model)
+- [データフロー](#data-flow)
+- [ファイルシステムレイアウト](#file-system-layout)
+- [インストーラーアーキテクチャ](#installer-architecture)
+- [フックシステム](#hook-system)
+- [CLI ツールレイヤー](#cli-tools-layer)
+- [ランタイム抽象化](#runtime-abstraction)
---
## システム概要
-GSDは、ユーザーとAIコーディングエージェント（Claude Code、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code）の間に位置する**メタプロンプティングフレームワーク**です。以下の機能を提供します：
+GSD Core は、ユーザーと AI コーディングエージェント（Claude Code、Gemini CLI、OpenCode、Kilo、Codex、Copilot、Antigravity、Trae、Cline、Augment Code）の間に位置する **メタプロンプティングフレームワーク** です。以下の機能を提供します：
-1. **コンテキストエンジニアリング** — タスクごとにAIが必要とするすべてを提供する構造化アーティファクト
-2. **マルチエージェントオーケストレーション** — 専門エージェントをフレッシュなコンテキストウィンドウで起動する軽量オーケストレーター
+1. **コンテキストエンジニアリング** — タスクごとに AI が必要とするすべてを提供する構造化アーティファクト（[コンテキストエンジニアリング](explanation/context-engineering.md) 参照）
+2. **マルチエージェントオーケストレーション** — フレッシュなコンテキストウィンドウで専門化されたエージェントを生成する薄いオーケストレーター（[マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md) 参照）
3. **仕様駆動開発** — 要件 → 調査 → 計画 → 実行 → 検証のパイプライン
4. **状態管理** — セッションやコンテキストリセットをまたいだ永続的なプロジェクトメモリ
@@ -106,47 +106,93 @@ GSDは、ユーザーとAIコーディングエージェント（Claude Code、G
### コマンド（`commands/gsd/*.md`）
-ユーザー向けのエントリーポイントです。各ファイルにはYAMLフロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
-- **Claude Code:** カスタムスラッシュコマンド（`/gsd-command-name`）
-- **OpenCode / Kilo:** スラッシュコマンド（`/gsd-command-name`）
+ユーザー向けのエントリーポイントです。各ファイルには YAML フロントマター（name、description、allowed-tools）とワークフローをブートストラップするプロンプト本文が含まれています。コマンドは以下の形式でインストールされます：
+
+- **Claude Code:** カスタムスラッシュコマンド（ハイフン形式、`/gsd-command-name`）
+- **OpenCode / Kilo:** スラッシュコマンド（ハイフン形式、`/gsd-command-name`）
- **Codex:** スキル（`$gsd-command-name`）
-- **Copilot:** スラッシュコマンド（`/gsd-command-name`）
+- **Copilot:** スラッシュコマンド（ハイフン形式、`/gsd-command-name`）
+- **Gemini CLI:** `gsd:` 名前空間下のスラッシュコマンド（コロン形式、`/gsd:command-name`）——Gemini はすべてのカスタムコマンドをプラグイン ID の下で名前空間化するため、インストールパスがすべての本文テキスト参照をコロン形式に書き換える
- **Antigravity:** スキル
-**コマンド総数:** 44
+**コマンド総数:** 信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#commands) を参照。
+
+#### 2 段階の階層的ルーティング（v1.40、[#2792](https://github.com/open-gsd/gsd-core/issues/2792)）
+
+eager なスキルリストのトークンコストを低く保つため、v1.40 では 6 つの名前空間 **メタスキル**（`gsd-workflow`、`gsd-project`、`gsd-quality`、`gsd-context`、`gsd-manage`、`gsd-ideate` ——`commands/gsd/ns-*.md` から取得されるが、呼び出し可能な `name:` はここに示すベア形式）を具体的なサブスキルの上にレイヤーとして導入しています。モデルは平坦な 86 スキルリスト（約 2,150 トークン）の代わりに 6 つの名前空間ルーター（約 120 トークン）を見て名前空間を選択し、名前空間ルーターの本文に埋め込まれたルーティングテーブルを通じて具体的なサブスキルにルーティングします。名前空間スキルは **付加的** です——すべての具体的なコマンドは依然として直接呼び出し可能です。
+
+#### MCP トークンバジェットの相互作用
+
+eager なスキルリストはターンごとの 2 つの主要コストの一つです。もう一つは `.claude/settings.json` で有効化されている各 MCP サーバーが注入する MCP ツールスキーマです。重量級の MCP サーバー（ブラウザ/playwright、Mac ツール、Windows ツール）はそれぞれターンごとに 20k+ トークンかかる場合があり、多くの場合 `model_profile` のチューニングで節約できるものをはるかに上回ります。トグルは Claude Code ハーネスにあります（`.claude/settings.json` の `enabledMcpjsonServers` / `disabledMcpjsonServers`）で、GSD の懸念事項ではありません。
### ワークフロー（`get-shit-done/workflows/*.md`）
コマンドが参照するオーケストレーションロジックです。以下を含むステップバイステップのプロセスが記述されています：
+
- `gsd-tools.cjs init` によるコンテキスト読み込み
- モデル解決を伴うエージェント起動の指示
- ゲート/チェックポイントの定義
- 状態更新パターン
- エラーハンドリングとリカバリー
-**ワークフロー総数:** 46
+**ワークフロー総数:** 信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#workflows) を参照。
+
+#### ワークフローのプログレッシブディスクロージャー
+
+ワークフローファイルは、対応する `/gsd-*` コマンドが呼び出されるたびに Claude のコンテキストにそのまま読み込まれます。そのコストを制限するため、`tests/workflow-size-budget.test.cjs` で強制されるワークフローサイズバジェットは #2361 のエージェントバジェットを反映します：
+
+| ティア | ファイルごとの行数制限 |
+|-----------|--------------------|
+| `XL` | 1700 — トップレベルオーケストレーター（`execute-phase`、`plan-phase`、`new-project`） |
+| `LARGE` | 1500 — 複数ステップのプランナーと大きな機能ワークフロー |
+| `DEFAULT` | 1000 — 集中した単一目的のワークフロー（対象ティア） |
### エージェント（`agents/*.md`）
-フロントマターで以下を指定する専門エージェント定義：
+フロントマターで以下を指定する専門化されたエージェント定義：
+
- `name` — エージェント識別子
- `description` — 役割と目的
-- `tools` — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearchなど）
+- `tools` — 許可されたツールアクセス（Read、Write、Edit、Bash、Grep、Glob、WebSearch など）
- `color` — 視覚的な区別のためのターミナル出力色
-**エージェント総数:** 16
+**エージェント総数:** 33
### リファレンス（`get-shit-done/references/*.md`）
-ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント：
+ワークフローとエージェントが `@-reference` で参照する共有知識ドキュメント（信頼できる数と完全なロスターについては [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) を参照）：
+
+**コアリファレンス：**
+
- `checkpoints.md` — チェックポイントタイプの定義とインタラクションパターン
+- `gates.md` — プランチェッカーと検証者に組み込まれた 4 つの正規ゲートタイプ（Confirm、Quality、Safety、Transition）
- `model-profiles.md` — エージェントごとのモデルティア割り当て
+- `model-profile-resolution.md` — モデル解決アルゴリズムのドキュメント
- `verification-patterns.md` — 各種アーティファクトの検証方法
-- `planning-config.md` — 設定スキーマの全体像と動作
-- `git-integration.md` — gitコミット、ブランチ、履歴のパターン
+- `verification-overrides.md` — アーティファクトごとの検証オーバーライドルール
+- `planning-config.md` — 完全な設定スキーマと動作
+- `git-integration.md` — git コミット、ブランチ、履歴のパターン
+- `git-planning-commit.md` — planning ディレクトリのコミット規約
- `questioning.md` — プロジェクト初期化のためのドリーム抽出フィロソフィー
- `tdd.md` — テスト駆動開発の統合パターン
- `ui-brand.md` — 視覚的な出力フォーマットパターン
+- `common-bug-patterns.md` — コードレビューと検証のための一般的なバグパターン
+
+**ワークフローリファレンス：**
+
+- `agent-contracts.md` — オーケストレーターとエージェント間の正式インターフェース
+- `context-budget.md` — コンテキストウィンドウバジェット配分ルール
+- `continuation-format.md` — セッション継続/再開フォーマット
+- `domain-probes.md` — discuss-phase のためのドメイン固有プローブ質問
+- `gate-prompts.md` — ゲート/チェックポイントプロンプトテンプレート
+- `revision-loop.md` — 計画修正の反復パターン
+- `universal-anti-patterns.md` — 検出・回避すべき一般的なアンチパターン
+- `artifact-types.md` — 計画アーティファクトタイプの定義
+- `phase-argument-parsing.md` — フェーズ引数解析の規約
+- `decimal-phase-calculation.md` — 小数サブフェーズ番号付けのルール
+- `workstream-flag.md` — ワークストリームアクティブポインターの規約
+- `user-profiling.md` — ユーザー行動プロファイリングの方法論
+- `thinking-partner.md` — 決定ポイントでの条件付きシンキングパートナー起動
### テンプレート（`get-shit-done/templates/`）
@@ -172,26 +218,36 @@ GSDは、ユーザーとAIコーディングエージェント（Claude Code、G
| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みにプロンプトインジェクションパターンがないかスキャン（アドバイザリー） |
| `gsd-workflow-guard.js` | `PreToolUse` | GSDワークフローコンテキスト外でのファイル編集を検出（アドバイザリー、`hooks.workflow_guard` によるオプトイン） |
-### CLIツール（`get-shit-done/bin/`）
+### コマンドルーティングハブ（`get-shit-done/bin/lib/command-routing-hub.cjs`）
-17のドメインモジュールを持つNode.js CLIユーティリティ（`gsd-tools.cjs`）：
+CJS コマンドファミリールーターは `CommandRoutingHub` を通じてディスパッチします。ハブはノースロー純粋結果コントラクト（`hub.dispatch()` は内部例外をキャッチして `{ ok: false, kind, ...typedPayload }` を返す）とクローズドランタイムエラー分類（`UnknownCommand`、`InvalidArgs`、`HandlerRefusal`、`HandlerFailure`）を所有します。ルーターアダプターは薄い CLI トランスレーターのままです——ハブを構築し、`dispatch` を呼び出し、結果を `output()`/`error()` 呼び出しにマッピングします。`docs/adr/0174-retire-gsd-sdk-package-boundary.md` を参照。
+
+### CLI ツール（`get-shit-done/bin/`）
+
+`get-shit-done/bin/lib/` にドメインモジュールが分割された Node.js CLI ユーティリティ（`gsd-tools.cjs`）（信頼できるロスターについては [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) を参照）：
| モジュール | 責務 |
-|--------|---------------|
-| `core.cjs` | エラーハンドリング、出力フォーマット、共有ユーティリティ |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| `core.cjs` | エラーハンドリング、出力フォーマット、共有ユーティリティ；planning ヘルパーの互換性 re-export |
+| `planning-workspace.cjs` | planning シーム（`planningDir`、`planningPaths`、アクティブなワークストリームルーティング、`.planning/.lock`） |
| `state.cjs` | STATE.md の解析、更新、進行、メトリクス |
| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス |
| `roadmap.cjs` | ROADMAP.md の解析、フェーズ抽出、プラン進捗 |
| `config.cjs` | config.json の読み書き、セクション初期化 |
| `verify.cjs` | プラン構造、フェーズ完了度、リファレンス、コミット検証 |
| `template.cjs` | テンプレート選択と変数置換による穴埋め |
-| `frontmatter.cjs` | YAMLフロントマターのCRUD操作 |
+| `frontmatter.cjs` | YAML フロントマターの CRUD 操作 |
| `init.cjs` | ワークフロータイプごとの複合コンテキスト読み込み |
| `milestone.cjs` | マイルストーンのアーカイブ、要件マーキング |
| `commands.cjs` | その他コマンド（slug、タイムスタンプ、todos、スキャフォールディング、統計） |
| `model-profiles.cjs` | モデルプロファイル解決テーブル |
-| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全なJSON解析、シェル引数バリデーション |
-| `uat.cjs` | UATファイル解析、検証デット追跡、audit-uatサポート |
+| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全な JSON 解析、シェル引数バリデーション |
+| `uat.cjs` | UAT ファイル解析、検証デット追跡、audit-uat サポート |
+| `docs.cjs` | ドキュメント更新ワークフロー init、Markdown スキャン、モノレポ検出 |
+| `workstream.cjs` | ワークストリーム CRUD、マイグレーション、セッションスコープのアクティブポインター |
+| `schema-detect.cjs` | ORM パターンのスキーマドリフト検出（Prisma、Drizzle など） |
+| `profile-pipeline.cjs` | ユーザー行動プロファイリングデータパイプライン、セッションファイルスキャン |
+| `profile-output.cjs` | プロファイルレンダリング、USER-PROFILE.md と dev-preferences.md の生成 |
---
@@ -219,19 +275,24 @@ Orchestrator (workflow .md)
└── Update state: gsd-tools.cjs state update/patch/advance-plan
```
-### エージェント起動カテゴリ
+### 主要エージェント生成カテゴリ
-| カテゴリ | エージェント | 並列実行 |
-|----------|--------|-------------|
-| **リサーチャー** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4並列（stack、features、architecture、pitfalls）; advisorはdiscuss-phase中に起動 |
+21 の主要エージェントの概念的な生成パターン分類。信頼できる 31 エージェントロスター（`gsd-pattern-mapper`、`gsd-code-reviewer`、`gsd-code-fixer`、`gsd-ai-researcher`、`gsd-domain-researcher`、`gsd-eval-planner`、`gsd-eval-auditor`、`gsd-framework-selector`、`gsd-debug-session-manager`、`gsd-intel-updater` などの 10 の高度/専門化エージェントを含む）については、[`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped) を参照。
+
+| カテゴリ | エージェント | 並列性 |
+| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **リサーチャー** | gsd-project-researcher、gsd-phase-researcher、gsd-ui-researcher、gsd-advisor-researcher | 4 並列（stack、features、architecture、pitfalls）；advisor は discuss-phase 中に起動 |
| **シンセサイザー** | gsd-research-synthesizer | 逐次（リサーチャー完了後） |
-| **プランナー** | gsd-planner, gsd-roadmapper | 逐次 |
-| **チェッカー** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | 逐次（検証ループ、最大3回反復） |
+| **プランナー** | gsd-planner、gsd-roadmapper | 逐次 |
+| **チェッカー** | gsd-plan-checker、gsd-integration-checker、gsd-ui-checker、gsd-nyquist-auditor | 逐次（検証ループ、最大 3 回反復） |
| **エグゼキューター** | gsd-executor | ウェーブ内は並列、ウェーブ間は逐次 |
| **ベリファイアー** | gsd-verifier | 逐次（全エグゼキューター完了後） |
-| **マッパー** | gsd-codebase-mapper | 4並列（tech、arch、quality、concerns） |
+| **マッパー** | gsd-codebase-mapper | 4 並列（tech、arch、quality、concerns） |
| **デバッガー** | gsd-debugger | 逐次（インタラクティブ） |
-| **オーディター** | gsd-ui-auditor | 逐次 |
+| **オーディター** | gsd-ui-auditor、gsd-security-auditor | 逐次 |
+| **Doc ライター** | gsd-doc-writer、gsd-doc-verifier | 逐次（ライター後に検証者） |
+| **プロファイラー** | gsd-user-profiler | 逐次 |
+| **アナライザー** | gsd-assumptions-analyzer | 逐次（discuss-phase 中） |
### ウェーブ実行モデル
@@ -247,18 +308,28 @@ Wave Analysis:
```
各エグゼキューターには以下が与えられます：
-- フレッシュな200Kコンテキストウィンドウ
-- 実行対象の特定のPLAN.md
+
+- フレッシュな 200K コンテキストウィンドウ（または対応モデルでは最大 1M）
+- 実行対象の特定の PLAN.md
- プロジェクトコンテキスト（PROJECT.md、STATE.md）
-- フェーズコンテキスト（CONTEXT.md、利用可能な場合はRESEARCH.md）
+- フェーズコンテキスト（CONTEXT.md、利用可能な場合は RESEARCH.md）
+
+### アダプティブコンテキスト拡充（1M モデル）
+
+コンテキストウィンドウが 500K+ トークンの場合（Opus 4.6、Sonnet 4.6 などの 1M クラスモデル）、サブエージェントプロンプトは標準 200K ウィンドウには収まらない追加コンテキストで自動的に拡充されます：
+
+- **エグゼキューターエージェント** は前のウェーブの SUMMARY.md ファイルとフェーズの CONTEXT.md/RESEARCH.md を受け取り、フェーズ内でのクロスプラン認識を可能にする
+- **検証者エージェント** はすべての PLAN.md、SUMMARY.md、CONTEXT.md ファイルと REQUIREMENTS.md を受け取り、履歴を考慮した検証を可能にする
+
+オーケストレーターは設定から `context_window` を読み取り（`gsd-tools.cjs config-get context_window`）、値が >= 500,000 の場合に条件付きでより豊富なコンテキストを含めます。標準 200K ウィンドウでは、プロンプトはコンテキスト効率を最大化するためにキャッシュフレンドリーな順序で切り詰められたバージョンを使います。
#### 並列コミットの安全性
-同一ウェーブ内で複数のエグゼキューターが実行される場合、2つの仕組みで競合を防止します：
+同一ウェーブ内で複数のエグゼキューターが実行される場合、2 つの仕組みで競合を防止します：
-1. **`--no-verify` コミット** — 並列エージェントはpre-commitフックをスキップします（ビルドロックの競合を引き起こす可能性があるため。例：Rustプロジェクトでのcargo lockファイルの競合）。オーケストレーターは各ウェーブ完了後に `git hook run pre-commit` を1回実行します。
+1. **`--no-verify` コミット** — 並列エージェントはプリコミットフックをスキップします（ビルドロックの競合を引き起こす可能性があるため。例：Rust プロジェクトでの cargo lock ファイルの競合）。オーケストレーターは各ウェーブ完了後に `git hook run pre-commit` を 1 回実行します。
-2. **STATE.md ファイルロック** — すべての `writeStateMd()` 呼び出しはロックファイルベースの相互排他（`STATE.md.lock`、`O_EXCL` によるアトミック作成）を使用します。これにより、2つのエージェントがSTATE.mdを読み取り、異なるフィールドを変更し、最後の書き込みが他方の変更を上書きする読み取り-変更-書き込みの競合状態を防止します。古いロックの検出（10秒タイムアウト）とジッター付きのスピンウェイトを含みます。
+2. **STATE.md ファイルロック** — すべての `writeStateMd()` 呼び出しはロックファイルベースの相互排他（`STATE.md.lock`、`O_EXCL` によるアトミック作成）を使用します。これにより、2 つのエージェントが STATE.md を読み取り、異なるフィールドを変更し、最後の書き込みが他方の変更を上書きする read-modify-write 競合状態を防止します。古いロックの検出（10 秒タイムアウト）とジッター付きのスピンウェイトを含みます。
---
@@ -302,16 +373,27 @@ ui-phase → UI-SPEC.md (design contract, optional)
│
▼
plan-phase
+ ├── Research gate (blocks if RESEARCH.md has unresolved open questions)
├── Phase Researcher → RESEARCH.md
- ├── Planner → PLAN.md files
- └── Plan Checker → Verify loop (max 3x)
+ │ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,
+ │ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md
+ ├── Planner (with reachability check) → PLAN.md files
+ │ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;
+ │ T-{phase}-SC STRIDE row added for install-bearing plans
+ ├── Plan Checker → Verify loop (max 3x)
+ ├── Requirements coverage gate (REQ-IDs → plans)
+ └── Decision coverage gate (CONTEXT.md `` → plans, BLOCKING — #2492)
│
▼
-execute-phase
+state planned-phase → STATE.md (Planned/Ready to execute)
+ │
+ ▼
+execute-phase (context reduction: truncated prompts, cache-friendly ordering)
├── Wave analysis (dependency grouping)
├── Executor per plan → code + atomic commits
├── SUMMARY.md per plan
└── Verifier → VERIFICATION.md
+ └── Decision coverage gate (CONTEXT.md decisions → shipped artifacts, NON-BLOCKING — #2492)
│
▼
verify-work → UAT.md (user acceptance testing)
@@ -344,29 +426,37 @@ UI-SPEC.md (per phase) ───────────────────
```
~/.claude/ # Claude Code (global install)
-├── commands/gsd/*.md # 37 slash commands
+├── skills/gsd-*/SKILL.md # Global skills (authoritative roster: docs/INVENTORY.md)
+├── commands/gsd/*.md # Local Claude installs use slash commands instead of global skills
├── get-shit-done/
│ ├── bin/gsd-tools.cjs # CLI utility
-│ ├── bin/lib/*.cjs # 15 domain modules
-│ ├── workflows/*.md # 42 workflow definitions
-│ ├── references/*.md # 13 shared reference docs
+│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md)
+│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md)
+│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md)
│ └── templates/ # Planning artifact templates
-├── agents/*.md # 15 agent definitions
-├── hooks/
-│ ├── gsd-statusline.js # Statusline hook
-│ ├── gsd-context-monitor.js # Context warning hook
-│ └── gsd-check-update.js # Update check hook
+├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md)
+├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check)
+├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary)
├── settings.json # Hook registrations
└── VERSION # Installed version number
```
他のランタイムでの同等パス：
-- **OpenCode:** `~/.config/opencode/` または `~/.opencode/`
-- **Kilo:** `~/.config/kilo/` または `~/.kilo/`
-- **Gemini CLI:** `~/.gemini/`
-- **Codex:** `~/.codex/`（コマンドの代わりにスキルを使用）
-- **Copilot:** `~/.github/`
-- **Antigravity:** `~/.gemini/antigravity/`（グローバル）または `./.agent/`（ローカル）
+
+- **OpenCode:** `~/.config/opencode/` global または `./.opencode/` local
+- **Kilo:** `~/.config/kilo/` global または `./.kilo/` local
+- **Gemini CLI:** `~/.gemini/` global または `./.gemini/` local
+- **Codex:** `~/.codex/` global または `./.codex/` local
+- **Copilot:** `~/.copilot/` global または `./.github/` local
+- **Antigravity:** auto-detected global root（`~/.gemini/antigravity/`、`~/.gemini/antigravity-ide/`、または `~/.gemini/antigravity-cli/`）または `./.agent/` local
+- **Cursor:** `~/.cursor/` global または `./.cursor/` local
+- **Windsurf:** `~/.codeium/windsurf/` global または `./.windsurf/` local
+- **Augment Code:** `~/.augment/` global または `./.augment/` local
+- **Trae:** `~/.trae/` global または `./.trae/` local
+- **Qwen Code:** `~/.qwen/` global または `./.qwen/` local
+- **Hermes Agent:** `~/.hermes/` global または `./.hermes/` local
+- **CodeBuddy:** `~/.codebuddy/` global または `./.codebuddy/` local
+- **Cline:** `~/.cline/` global または project-root `.clinerules` local
### プロジェクトファイル（`.planning/`）
@@ -424,29 +514,39 @@ UI-SPEC.md (per phase) ───────────────────
## インストーラーアーキテクチャ
-インストーラー（`bin/install.js`、約3,000行）は以下を処理します：
+インストーラー（`bin/install.js`、約 10,700 行）は以下を処理します：
-1. **ランタイム検出** — インタラクティブプロンプトまたはCLIフラグ（`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--antigravity`、`--all`）
+1. **ランタイム検出** — インタラクティブプロンプトまたは CLI フラグ（`--claude`、`--opencode`、`--gemini`、`--kilo`、`--codex`、`--copilot`、`--antigravity`、`--cursor`、`--windsurf`、`--augment`、`--trae`、`--qwen`、`--hermes`、`--codebuddy`、`--cline`、`--all`）
2. **インストール先の選択** — グローバル（`--global`）またはローカル（`--local`）
-3. **ファイルデプロイ** — コマンド、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
+3. **ファイルデプロイ** — コマンド、スキル、ワークフロー、リファレンス、テンプレート、エージェント、フックをコピー
4. **ランタイム適応** — ランタイムごとにファイル内容を変換：
- Claude Code: そのまま使用
- - OpenCode: コマンド/エージェントをOpenCode互換のフラットコマンド + サブエージェント形式に変換
- - Kilo: OpenCode変換パイプラインをKiloの設定パスで再利用
- - Codex: コマンドからTOML設定 + スキルを生成
- - Copilot: ツール名をマッピング（Read→read、Bash→executeなど）
+ - OpenCode: コマンド/エージェントを OpenCode 互換のフラットコマンド + サブエージェント形式に変換
+ - Kilo: OpenCode 変換パイプラインを Kilo の設定パスで再利用
+ - Codex: コマンドから TOML 設定 + スキルを生成
+ - Copilot: ツール名をマッピング（Read→read、Bash→execute など）
- Gemini: フックイベント名を調整（`PostToolUse` の代わりに `AfterTool`）
- - Antigravity: Googleモデル同等品によるスキルファースト
+ - Antigravity: Google モデル同等品によるスキルファースト
+ - Cursor: ルール参照付きスキルファースト
+ - Windsurf: ルール参照付きスキルファースト
+ - Trae: `~/.trae` / `./.trae` へのスキルファーストインストール、`settings.json` またはフック統合なし
+ - Qwen Code: Qwen ブランドのパスとプロンプト書き換え付きスキルファースト
+ - Hermes Agent: `skills/gsd/` 下のカテゴリベーススキル
+ - CodeBuddy: CodeBuddy パスとプロンプト書き換え付きスキルファースト
+ - Cline: ルールベース統合のための `.clinerules` を書き込む
+ - Augment Code: スキルファースト、完全なスキル変換と設定管理
5. **パス正規化** — `~/.claude/` パスをランタイム固有のパスに置換
6. **設定統合** — ランタイムの `settings.json` にフックを登録
-7. **パッチバックアップ** — v1.17以降、ローカルで変更されたファイルを `/gsd-update --reapply` 用に `gsd-local-patches/` へバックアップ
+7. **パッチバックアップ** — v1.17 以降、ローカルで変更されたファイルを `/gsd-update --reapply` 用に `gsd-local-patches/` へバックアップ
8. **マニフェスト追跡** — クリーンアンインストールのために `gsd-file-manifest.json` を書き込み
-9. **アンインストールモード** — `--uninstall` ですべてのGSDファイル、フック、設定を削除
+9. **アンインストールモード** — `--uninstall` ですべての GSD ファイル、フック、設定を削除
+
+インストール時のファイル移動、古いアーティファクトのクリーンアップ、設定の書き換え、ユーザーデータの保全は Installer Migration Module によって管理されます。[Installer Migrations](../installer-migrations.md) と [ADR 0008](../adr/0008-installer-migration-module.md) を参照してください。
### プラットフォーム対応
-- **Windows:** 子プロセスでの `windowsHide`、保護ディレクトリへのEPERM/EACCES対策、パスセパレーターの正規化
-- **WSL:** WindowsのNode.jsがWSL上で実行されていることを検出し、パスの不一致について警告
+- **Windows:** 子プロセスでの `windowsHide`、保護ディレクトリへの EPERM/EACCES 対策、パスセパレーターの正規化
+- **WSL:** Windows の Node.js が WSL 上で実行されていることを検出し、パスの不一致について警告
- **Docker/CI:** カスタム設定ディレクトリの場所に `CLAUDE_CONFIG_DIR` 環境変数をサポート
---
@@ -474,32 +574,48 @@ Runtime Engine (Claude Code / Gemini CLI)
### コンテキストモニターの閾値
| コンテキスト残量 | レベル | エージェントの動作 |
-|-------------------|-------|----------------|
+| ----------------- | -------- | --------------------------------------- |
| > 35% | Normal | 警告なし |
| ≤ 35% | WARNING | 「新しい複雑な作業の開始を避けてください」 |
| ≤ 25% | CRITICAL | 「コンテキストがほぼ枯渇、ユーザーに通知してください」 |
-デバウンス：繰り返し警告の間隔は5回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。
+デバウンス：繰り返し警告の間隔は 5 回のツール使用。重大度のエスカレーション（WARNING→CRITICAL）はデバウンスをバイパスします。
### 安全性の特性
-- すべてのフックはtry/catchでラップされ、エラー時はサイレントに終了
-- stdin タイムアウトガード（3秒）でパイプの問題によるハングを防止
-- 古いメトリクス（60秒超）は無視される
+- すべてのフックは try/catch でラップされ、エラー時はサイレントに終了
+- stdin タイムアウトガード（3 秒）でパイプの問題によるハングを防止
+- 古いメトリクス（60 秒超）は無視される
- ブリッジファイルの欠落は適切に処理される（サブエージェント、新規セッション）
- コンテキストモニターはアドバイザリーのみ — ユーザーの設定を上書きする命令的なコマンドは発行しない
+### パッケージ正当性ゲート（v1.42.1）
+
+調査者 → プランナー → エグゼキューターパイプラインには、スロップスクワッティング（AI が幻覚した悪意のあるポストインストールスクリプト付きで事前登録されたパッケージ名）に対するサプライチェーンゲートが含まれます。
+
+**ゲートレイヤー：**
+
+| レイヤー | コンポーネント | アクション |
+|-------|-----------|--------|
+| 調査 | `gsd-phase-researcher` | `slopcheck install --json` を実行；`## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込む；RESEARCH.md が書かれる前に `[SLOP]` パッケージを除去 |
+| 計画 | `gsd-planner` | 監査テーブルを読み取る；任意の `[ASSUMED]` または `[SUS]` インストールタスクの前に `checkpoint:human-verify` を挿入；`` に `T-{phase}-SC` STRIDE サプライチェーン行を追加 |
+| 実行 | `gsd-executor` | RULE 3 はパッケージインストールを自動修正スコープから除外；失敗したインストールはチェックポイントとして表面化し、サイレントな代替なし |
+
+セキュリティモデルの概念的な概要については [セキュリティモデル](explanation/security-model.md) を参照。
+
### セキュリティフック（v1.27）
**Prompt Guard**（`gsd-prompt-guard.js`）：
-- `.planning/` ファイルへのWrite/Edit時にトリガー
-- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、systemタグインジェクション）をスキャン
+
+- `.planning/` ファイルへの Write/Edit 時にトリガー
+- プロンプトインジェクションパターン（ロールオーバーライド、指示バイパス、system タグインジェクション）をスキャン
- アドバイザリーのみ — 検出をログに記録するが、ブロックはしない
- フックの独立性のため、パターンはインライン化（`security.cjs` のサブセット）
**Workflow Guard**（`gsd-workflow-guard.js`）：
-- `.planning/` 以外のファイルへのWrite/Edit時にトリガー
-- GSDワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドやTaskサブエージェントがない場合）
+
+- `.planning/` 以外のファイルへの Write/Edit 時にトリガー
+- GSD ワークフローコンテキスト外での編集を検出（アクティブな `/gsd-` コマンドや Task サブエージェントがない場合）
- 状態追跡される変更には `/gsd-quick` や `/gsd-fast` の使用をアドバイス
- `hooks.workflow_guard: true` によるオプトイン（デフォルト: false）
@@ -507,24 +623,43 @@ Runtime Engine (Claude Code / Gemini CLI)
## ランタイム抽象化
-GSDは統一されたコマンド/ワークフローアーキテクチャを通じて複数のAIコーディングランタイムをサポートしています：
+GSD Core は統一されたコマンド/ワークフローアーキテクチャを通じて複数の AI コーディングランタイムをサポートしています：
-| ランタイム | コマンド形式 | エージェントシステム | 設定場所 |
-|---------|---------------|--------------|-----------------|
-| Claude Code | `/gsd-command` | Task起動 | `~/.claude/` |
-| OpenCode | `/gsd-command` | サブエージェントモード | `~/.config/opencode/` |
-| Kilo | `/gsd-command` | サブエージェントモード | `~/.config/kilo/` |
-| Gemini CLI | `/gsd-command` | Task起動 | `~/.gemini/` |
-| Codex | `$gsd-command` | スキル | `~/.codex/` |
-| Copilot | `/gsd-command` | エージェント委譲 | `~/.github/` |
-| Antigravity | スキル | スキル | `~/.gemini/antigravity/` |
+### ランタイムインストールコントラクトマトリクス
+
+| ランタイム | グローバルルート | ローカルルート | 呼び出し面 | エージェント面 | 設定とフック |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | `~/.claude` | `./.claude` | グローバル `skills/gsd-*/SKILL.md`；ローカル `commands/gsd/*.md` | `agents/gsd-*.md` | `settings.json` フックと statusLine エントリ |
+| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` または `opencode.jsonc`；GSD フックなし |
+| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` または `kilo.jsonc`；GSD フックなし |
+| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | `settings.json` フィーチャーフラグ、フック、statusline |
+| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | エージェントソース markdown + エージェントごとの TOML | `config.toml` `[agents.gsd-*]`、`[features].hooks`、フックテーブル |
+| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` と `copilot-instructions.md` | `.agent.md` ファイル | GSD フックまたは statusline なし |
+| Antigravity | auto-detected：`~/.gemini/antigravity`、`~/.gemini/antigravity-ide`、または `~/.gemini/antigravity-cli` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD がインストールした場合の Gemini スタイル `settings.json` フックエントリ |
+| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下のルール参照；GSD フックなし |
+| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下のルール参照；GSD フックなし |
+| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | GSD フックまたは statusline なし |
+| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | `rules/` 下のルール参照；GSD フックなし |
+| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | サポートされている場合の共通 GSD 設定とフックエントリ |
+| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` と `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | サポートされている場合の共通 GSD 設定とフックエントリ |
+| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | サポートされている場合の共通 GSD 設定とフックエントリ |
+| Cline | `~/.cline` | project root | `.clinerules` | ルールのみ | GSD フックまたは statusline なし |
### 抽象化ポイント
-1. **ツール名マッピング** — 各ランタイムは独自のツール名を持つ（例：ClaudeのBash → Copilotのexecute）
-2. **フックイベント名** — Claude Codeは `PostToolUse`、Geminiは `AfterTool` を使用
+1. **ツール名マッピング** — 各ランタイムは独自のツール名を持つ（例：Claude の `Bash` → Copilot の `execute`）
+2. **フックイベント名** — Claude Code は `PostToolUse`、Gemini は `AfterTool` を使用
3. **エージェントフロントマター** — 各ランタイムは独自のエージェント定義形式を持つ
4. **パス規約** — 各ランタイムは異なるディレクトリに設定を保存
-5. **モデル参照** — `inherit` プロファイルにより、GSDはランタイムのモデル選択に委譲
+5. **モデル参照** — `inherit` プロファイルにより、GSD はランタイムのモデル選択に委譲
-インストーラーはインストール時にすべての変換を処理します。ワークフローとエージェントはClaude Codeのネイティブ形式で記述され、デプロイ時に変換されます。
+インストーラーはインストール時にすべての変換を処理します。ワークフローとエージェントは Claude Code のネイティブ形式で記述され、デプロイ時に変換されます。
+
+---
+
+## Related
+
+- [マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md)
+- [セキュリティモデル](explanation/security-model.md)
+- [CLI ツール](CLI-TOOLS.md)
+- [ドキュメント索引](README.md)
diff --git a/docs/ja-JP/CLI-TOOLS.md b/docs/ja-JP/CLI-TOOLS.md
index 926b0255e..c44183c3e 100644
--- a/docs/ja-JP/CLI-TOOLS.md
+++ b/docs/ja-JP/CLI-TOOLS.md
@@ -1,26 +1,36 @@
# GSD CLI ツールリファレンス
-> `gsd-tools.cjs` のプログラマティック API リファレンスです。ワークフローやエージェントが内部的に使用します。ユーザー向けコマンドについては、[コマンドリファレンス](COMMANDS.md) を参照してください。
+> `gsd-tools` CLI（`get-shit-done/bin/gsd-tools.cjs`）のリファレンスです。スラッシュコマンドとユーザーフローについては [コマンドリファレンス](COMMANDS.md) を参照してください。[docs インデックス](README.md) に戻る。
---
## 概要
-`gsd-tools.cjs` は、GSD の約50個のコマンド、ワークフロー、エージェントファイル全体で繰り返し使われるインライン bash パターンを置き換える Node.js CLI ユーティリティです。設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を一元化しています。
+`gsd-tools.cjs` は、設定の解析、モデル解決、フェーズ検索、git コミット、サマリー検証、状態管理、テンプレート操作を GSD コマンド・ワークフロー・エージェント全体で一元化します。
-**配置場所:** `get-shit-done/bin/gsd-tools.cjs`
-**モジュール:** `get-shit-done/bin/lib/` 内の15個のドメインモジュール
-**使い方:**
+| | |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **配置パス** | `get-shit-done/bin/gsd-tools.cjs` |
+| **実装** | `get-shit-done/bin/lib/` 配下の 20 個のドメインモジュール（ディレクトリが正式） |
+| **ステータス** | オーケストレーション・ワークフロー・自動化処理のための主要ランタイムコマンドサーフェス。 |
+
+
+**使い方（CJS）:**
+
```bash
node gsd-tools.cjs [args] [--raw] [--cwd ]
```
-**グローバルフラグ:**
-| フラグ | 説明 |
-|--------|------|
-| `--raw` | 機械可読な出力（JSON またはプレーンテキスト、フォーマットなし） |
-| `--cwd ` | 作業ディレクトリの上書き（サンドボックス化されたサブエージェント向け） |
+**グローバルフラグ（CJS）:**
+
+
+| フラグ | 説明 |
+| -------------- | ---------------------------------------------------------------------------- |
+| `--raw` | 機械可読な出力（JSON またはプレーンテキスト、フォーマットなし） |
+| `--cwd ` | 作業ディレクトリの上書き（サンドボックス化されたサブエージェント向け） |
+| `--ws ` | `.planning/workstreams/` パス用のワークストリームコンテキスト |
+
---
@@ -64,6 +74,13 @@ node gsd-tools.cjs state resolve-blocker --text "..."
# セッション継続性を記録
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
+
+# フェーズ開始 — 新しいフェーズの STATE.md Status/Last activity を更新
+node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
+
+# エージェント検出可能なブロッカーシグナル送信（discuss-phase / UI フローで使用）
+node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
+node gsd-tools.cjs state signal-resume
```
### State スナップショット
@@ -152,7 +169,9 @@ node gsd-tools.cjs config-set-model-profile
```bash
# 現在のプロファイルに基づいてエージェント用モデルを取得
node gsd-tools.cjs resolve-model
-# 戻り値: opus | sonnet | haiku | inherit
+# --raw 出力では選択されたモデル ID/ティアを返します。
+# JSON 出力ではプロファイルも含み、アクティブなランタイムがサポートしている場合は
+# reasoning_effort も含まれます。
```
エージェント名: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
@@ -198,8 +217,17 @@ node gsd-tools.cjs validate consistency
# .planning/ の整合性チェック、任意で修復
node gsd-tools.cjs validate health [--repair]
+
+# ステータスライン / フック呼び出し元向けのコンテキストウィンドウ使用率をプローブ（v1.40.0）
+node gsd-tools.cjs validate context
+
+# 型付き JSON サーフェスとしてのコンテキスト使用率（#455）
+node gsd-tools.cjs validate context --json
```
+`validate context` は `utilization`、`status`（60% / 70% の閾値で `ok` / `warn` / `critical`）、および `suggestion` 文字列を含む構造化エンベロープを出力します。同じデータが `/gsd-health --context` を支えます。
+型付き IR を直接受け取るには `--json` を渡してください（スクリプトやテストアサーションで有用）。
+
---
## Template コマンド
@@ -275,9 +303,13 @@ node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
+
+# ワークストリームスコープ付き init（`--ws` フラグ）
+node gsd-tools.cjs init execute-phase --ws
+node gsd-tools.cjs init plan-phase --ws
```
-**大容量ペイロードの処理:** 出力が約50KBを超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます:
+**大容量ペイロードの処理:** 出力が約 50KB を超える場合、CLI は一時ファイルに書き出し、`@file:/tmp/gsd-init-XXXXX.json` を返します。ワークフローは `@file:` プレフィックスを確認し、ディスクから読み込みます:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
@@ -299,6 +331,38 @@ node gsd-tools.cjs requirements mark-complete
---
+## エージェントスキル
+
+指定されたエージェントタイプのスキルブロックを出力します。
+
+```bash
+# 生の XML スキルブロックを出力（デフォルト — シェル展開に安全）
+node gsd-tools.cjs agent-skills
+
+# 型付き JSON サーフェス（#455）を出力 — { agent_type, block, skills_count }
+node gsd-tools.cjs agent-skills --json
+```
+
+`--json` フラグは構造化消費やテストアサーションに適した型付き IR オブジェクトを返します。デフォルト（フラグなし）はワークフローのシェル展開が依存する生の XML 出力を維持します。
+
+---
+
+## スキルマニフェスト
+
+コマンド読み込みを高速化するためのスキル検出の事前計算とキャッシュ。
+
+```bash
+# スキルマニフェストを生成（.claude/skill-manifest.json に書き込む）
+node gsd-tools.cjs skill-manifest
+
+# カスタム出力パスで生成
+node gsd-tools.cjs skill-manifest --output
+```
+
+利用可能なすべての GSD スキルとそのメタデータ（名前、説明、ファイルパス、引数ヒント）の JSON マッピングを返します。インストーラとセッション開始フックが繰り返しのファイルシステムスキャンを避けるために使用します。
+
+---
+
## ユーティリティコマンド
```bash
@@ -324,35 +388,70 @@ node gsd-tools.cjs summary-extract [--fields field1,field2]
# プロジェクト統計
node gsd-tools.cjs stats [json|table]
-# 進捗表示
+# 進捗表示（人間が読める形式）
node gsd-tools.cjs progress [json|table|bar]
+# 型付き JSON サーフェスとしての進捗（#455）
+node gsd-tools.cjs progress --json
+
# TODO を完了にする
node gsd-tools.cjs todo complete
# UAT 監査 — 全フェーズの未解決項目をスキャン
node gsd-tools.cjs audit-uat
+# クロスアーティファクト監査キュー — `.planning/` の未解決監査項目をスキャン
+node gsd-tools.cjs audit-open [--json]
+
+# GSD-2 プロジェクトを現在の構造にリバースマイグレーション（`/gsd-import --from-gsd2` のバックエンド）
+node gsd-tools.cjs from-gsd2 [--path ] [--force] [--dry-run]
+
# 設定チェック付き git コミット
-node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify]
+node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
-> **`--no-verify`**: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントが使用し、ビルドロックの競合（例: Rust プロジェクトでの cargo ロック競合）を回避します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。
+> `--no-verify`: プリコミットフックをスキップします。ウェーブベース実行時に並列エグゼキューターエージェントがビルドロックの競合（例: Rust プロジェクトでの cargo ロック競合）を避けるために使用します。オーケストレーターは各ウェーブ完了後にフックを一度実行します。順次実行時には `--no-verify` を使用せず、フックを通常通り実行してください。
+> `--files ` **ステージング動作**: デフォルトでは、`--files` はコミット前に各指定ファイルに対して `git add -- ` を実行します。これにより `git add -p` で設定したハンク単位のステージングが上書きされます。`git add` ステップをスキップして指定パス内のステージング済みファイルのみをコミットするには `--respect-staged` を渡してください。そのスコープ内でステージングされたファイルがない場合、コマンドはエラーなしで `{ committed: false, reason: 'nothing staged' }` を返します。コミット時の末尾 `-- ` パス指定は両モードで適用されるため、`--files` スコープ外でステージングされたファイルは決して含まれません（#3061 不変条件）。
-```bash
# Web 検索（Brave API キーが必要）
node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month]
```
---
+## Graphify
+
+`.planning/graphs/` 内のプロジェクトナレッジグラフをビルド、クエリ、検査します。`config.json` で `graphify.enabled: true` が必要です（[設定リファレンス](CONFIGURATION.md#graphify-settings) を参照）。
+
+```bash
+# ナレッジグラフをビルドまたは再ビルド
+node gsd-tools.cjs graphify build
+
+# グラフで用語を検索
+node gsd-tools.cjs graphify query
+
+# グラフの鮮度と統計を表示
+node gsd-tools.cjs graphify status
+
+# 前回のビルドからの変更を表示
+node gsd-tools.cjs graphify diff
+
+# 現在のグラフの名前付きスナップショットを書き込む
+node gsd-tools.cjs graphify snapshot [name]
+```
+
+ユーザー向けエントリーポイント: `/gsd-graphify`（[コマンドリファレンス](COMMANDS.md#gsd-graphify) を参照）。
+
+---
+
## モジュールアーキテクチャ
| モジュール | ファイル | エクスポート |
|------------|----------|--------------|
-| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, 共通ユーティリティ |
+| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`、共通ユーティリティ、互換性再エクスポート |
| State | `lib/state.cjs` | すべての `state` サブコマンド、`state-snapshot` |
| Phase | `lib/phase.cjs` | フェーズ CRUD、`find-phase`、`phase-plan-index`、`phases list` |
+| Planning Workspace | `lib/planning-workspace.cjs` | プランニングシーム: `planningDir`、`planningPaths`、アクティブワークストリームルーティング、`.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | ロードマップ解析、フェーズ抽出、進捗更新 |
| Config | `lib/config.cjs` | 設定の読み書き、セクション初期化 |
| Verify | `lib/verify.cjs` | すべての検証・バリデーションコマンド |
@@ -365,3 +464,36 @@ node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month]
| UAT | `lib/uat.cjs` | 全フェーズ横断 UAT/検証監査 |
| Profile Output | `lib/profile-output.cjs` | 開発者プロファイルのフォーマット |
| Profile Pipeline | `lib/profile-pipeline.cjs` | セッション分析パイプライン |
+| Graphify | `lib/graphify.cjs` | ナレッジグラフのビルド/クエリ/ステータス/差分/スナップショット（`/gsd-graphify` のバックエンド） |
+| Learnings | `lib/learnings.cjs` | フェーズ/SUMMARY アーティファクトからの学習抽出（`/gsd-extract-learnings` のバックエンド） |
+| Audit | `lib/audit.cjs` | フェーズ/マイルストーン監査キューハンドラ; `audit-open` ヘルパー |
+| GSD2 Import | `lib/gsd2-import.cjs` | GSD-2 プロジェクトからのリバースマイグレーションインポーター（`/gsd-import --from-gsd2` のバックエンド） |
+| Intel | `lib/intel.cjs` | クエリ可能なコードベースインテリジェンスインデックス（`/gsd-map-codebase --query` のバックエンド） |
+
+---
+
+## レビュアー CLI ルーティング
+
+`review.models.` はレビュアーフレーバーをコードレビューワークフローが呼び出すシェルコマンドにマッピングします。[`/gsd-config --integrations`](COMMANDS.md#gsd-config) または直接設定できます:
+
+```bash
+node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
+node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
+node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
+node gsd-tools.cjs config-set review.models.claude "" # クリア — セッションモデルにフォールバック
+```
+
+スラッグは `[a-zA-Z0-9_-]+` に対してバリデーションされます。空またはパスを含むスラッグは拒否されます。完全なフィールドリファレンスは [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) を参照してください。
+
+## シークレット処理
+
+`/gsd-settings` で設定された API キー（`brave_search`、`firecrawl`、`exa_search`）は `.planning/config.json` に平文で書き込まれますが、`config-set` / `config-get` のすべての出力、確認テーブル、インタラクティブプロンプトでは（`****` として）マスクされます。マスキングの実装は `get-shit-done/bin/lib/secrets.cjs` を参照してください。`config.json` ファイル自体がセキュリティ境界です — ファイルシステムのパーミッションで保護し、git には含めないようにしてください（`.planning/` はデフォルトで gitignore されます）。
+
+---
+
+## Related
+
+- [Commands](COMMANDS.md)
+- [Configuration](CONFIGURATION.md)
+- [Architecture](ARCHITECTURE.md)
+- [docs index](README.md)
diff --git a/docs/ja-JP/COMMANDS.md b/docs/ja-JP/COMMANDS.md
index 07cd1ea93..8bfad5ab7 100644
--- a/docs/ja-JP/COMMANDS.md
+++ b/docs/ja-JP/COMMANDS.md
@@ -1,88 +1,82 @@
-# GSD コマンドリファレンス
+# GSD Core コマンドリファレンス
-> コマンド構文、フラグ、オプション、使用例の完全なリファレンスです。機能の詳細については[機能リファレンス](FEATURES.md)を、ワークフローのチュートリアルについては[ユーザーガイド](USER-GUIDE.md)をご覧ください。
+> GSD Core のコマンドリファレンス — すべての安定版コマンドの構文、フラグ、オプション、および使用例。機能の詳細については [機能リファレンス](../FEATURES.md) を、ワークフローの解説については [ユーザーガイド](../USER-GUIDE.md) を、ドキュメントのインデックスについては [README](../README.md) を参照してください。
---
## コマンド構文
-- **Claude Code / Gemini / Copilot:** `/gsd-command-name [args]`
-- **OpenCode / Kilo:** `/gsd-command-name [args]`
+- **Claude Code / Copilot / OpenCode / Kilo:** `/gsd-command-name [args]`（ハイフン形式）
+- **Gemini CLI:** `/gsd:command-name [args]`（コロン形式 — Gemini は `gsd:` 配下にコマンドを名前空間化します）
- **Codex:** `$gsd-command-name [args]`
+ハイフン形式とコロン形式は、*同じコマンドのランタイム固有の表記*です。どのランタイムを使用していても、インストーラーが正しい形式をランタイムのコマンドディレクトリに書き込みます。
+
+---
+
+## 名前空間メタスキル
+
+v1.40 では、最初のステージエントリーポイントとして6つの名前空間ルーターが提供されています。これらは積極的なスキルリストのトークンコストを低く保ちます（6つのルーターで約120トークン、フラットな86スキルのリストでは約2,150トークン）。一方、フルサーフェスは直接呼び出し可能なままです。モデルは名前空間を選択し、具体的なサブスキルにルーティングします。[#2792](https://github.com/open-gsd/gsd-core/issues/2792) を参照してください。
+
+| コマンド | ルーティング先 |
+|---------|-----------|
+| `/gsd-workflow` | フェーズパイプライン — discuss / plan / execute / verify / phase / progress |
+| `/gsd-project` | プロジェクトライフサイクル — マイルストーン、監査、サマリー |
+| `/gsd-quality` | 品質ゲート — コードレビュー、デバッグ、監査、セキュリティ、eval、UI |
+| `/gsd-context` | コードベースインテリジェンス — map、graphify、docs、learnings |
+| `/gsd-manage` | 管理 — config、workspace、workstreams、thread、update、ship、inbox |
+| `/gsd-ideate` | 探索とキャプチャ — explore、sketch、spike、spec、capture |
+
+名前空間スキルは**追加的**です — 既存のすべての具体的なコマンド（例: `/gsd-plan-phase`、`/gsd-code-review --fix`）は引き続き直接呼び出せます。
+
---
## コアワークフローコマンド
### `/gsd-new-project`
-詳細なコンテキスト収集を行い、新しいプロジェクトを初期化します。
+深いコンテキスト収集を伴う新規プロジェクトの初期化。
| フラグ | 説明 |
|------|-------------|
-| `--auto @file.md` | ドキュメントから自動抽出し、対話的な質問をスキップ |
+| `--auto @file.md` | ドキュメントから自動抽出し、インタラクティブな質問をスキップ |
**前提条件:** 既存の `.planning/PROJECT.md` がないこと
**生成物:** `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、`config.json`、`research/`、`CLAUDE.md`
```bash
-/gsd-new-project # 対話モード
-/gsd-new-project --auto @prd.md # PRDから自動抽出
+/gsd-new-project # インタラクティブモード
+/gsd-new-project --auto @prd.md # PRD から自動抽出
```
---
-### `/gsd-workspace --new`
+### `/gsd-workspace`
-リポジトリのコピーと独立した `.planning/` ディレクトリを持つ分離されたワークスペースを作成します。
+GSD ワークスペースを管理 — リポジトリコピーと独立した `.planning/` ディレクトリを持つ隔離されたワークスペース環境を作成、一覧表示、または削除します。
| フラグ | 説明 |
|------|-------------|
-| `--name ` | ワークスペース名（必須） |
-| `--repos repo1,repo2` | カンマ区切りのリポジトリパスまたは名前 |
-| `--path /target` | 対象ディレクトリ（デフォルト: `~/gsd-workspaces/`） |
+| `--new` | 新しいワークスペースを作成（`--name`、`--repos` などと組み合わせて使用） |
+| `--list` | アクティブな GSD ワークスペースとそのステータスを一覧表示 |
+| `--remove ` | ワークスペースを削除し、git ワークツリーをクリーンアップ |
+| `--name ` | ワークスペース名（`--new` と組み合わせて使用） |
+| `--repos repo1,repo2` | カンマ区切りのリポジトリパスまたは名前（`--new` と組み合わせて使用） |
+| `--path /target` | ターゲットディレクトリ（デフォルト: `~/gsd-workspaces/`） |
| `--strategy worktree\|clone` | コピー戦略（デフォルト: `worktree`） |
| `--branch ` | チェックアウトするブランチ（デフォルト: `workspace/`） |
-| `--auto` | 対話的な質問をスキップ |
+| `--auto` | インタラクティブな質問をスキップ |
**ユースケース:**
-- マルチリポ: リポジトリのサブセットを分離されたGSD状態で作業
-- 機能の分離: `--repos .` で現在のリポジトリのworktreeを作成
+- マルチリポジトリ: 隔離された GSD 状態で一部のリポジトリに取り組む
+- 機能の隔離: `--repos .` で現在のリポジトリのワークツリーを作成
-**生成物:** `WORKSPACE.md`、`.planning/`、リポジトリコピー（worktreeまたはclone）
+**生成物:** `WORKSPACE.md`、`.planning/`、リポジトリコピー（ワークツリーまたはクローン）
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
-/gsd-workspace --new --name feature-b --repos . --strategy worktree # 同一リポジトリの分離
-/gsd-workspace --new --name spike --repos api,web --strategy clone # フルクローン
-```
-
----
-
-### `/gsd-workspace --list`
-
-アクティブなGSDワークスペースとそのステータスを一覧表示します。
-
-**スキャン対象:** `~/gsd-workspaces/` 内の `WORKSPACE.md` マニフェスト
-**表示内容:** 名前、リポジトリ数、戦略、GSDプロジェクトのステータス
-
-```bash
+/gsd-workspace --new --name feature-b --repos . --strategy worktree # 同一リポジトリの隔離
/gsd-workspace --list
-```
-
----
-
-### `/gsd-workspace --remove`
-
-ワークスペースを削除し、git worktreeをクリーンアップします。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `` | はい | 削除するワークスペース名 |
-
-**安全性:** コミットされていない変更があるリポジトリの削除を拒否します。名前の確認が必要です。
-
-```bash
/gsd-workspace --remove feature-b
```
@@ -90,190 +84,242 @@
### `/gsd-discuss-phase`
-計画の前に実装に関する意思決定を記録します。
+計画前にアダプティブな質問を通じてフェーズのコンテキストを収集します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号（デフォルトは現在のフェーズ） |
+| `N` | No | フェーズ番号（デフォルト: 現在のフェーズ） |
| フラグ | 説明 |
|------|-------------|
-| `--auto` | すべての質問で推奨デフォルトを自動選択 |
-| `--batch` | 質問を一つずつではなくバッチ取り込みでグループ化 |
-| `--analyze` | ディスカッション中にトレードオフ分析を追加 |
-| `--chain` | discuss → plan → execute を1つのフローで自動チェーン (v1.31) |
-| `--power` | 準備済み回答ファイルから一括入力で質問に回答 (v1.32) |
+| `--all` | エリア選択をスキップ — すべてのグレーエリアをインタラクティブに議論（自動進行なし） |
+| `--auto` | すべての質問に対して推奨デフォルトを自動選択 |
+| `--batch` | 質問を一件ずつではなくバッチ入力のためにグループ化 |
+| `--analyze` | 議論中にトレードオフ分析を追加 |
+| `--power` | 準備済みの回答ファイルからファイルベースの一括質問回答 |
+| `--assumptions` | インタラクティブセッションなしで、フェーズに関する Claude の実装上の前提を表示 |
**前提条件:** `.planning/ROADMAP.md` が存在すること
**生成物:** `{phase}-CONTEXT.md`、`{phase}-DISCUSSION-LOG.md`（監査証跡）
```bash
-/gsd-discuss-phase 1 # フェーズ1の対話的ディスカッション
-/gsd-discuss-phase 3 --auto # フェーズ3でデフォルトを自動選択
+/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 2 --analyze # トレードオフ分析付きの議論
+/gsd-discuss-phase 1 --power # ファイルからの一括回答
+/gsd-discuss-phase 3 --assumptions # 計画前に Claude の前提を表示
```
---
### `/gsd-ui-phase`
-フロントエンドフェーズのUIデザイン契約書を生成します。
+フロントエンドフェーズの UI デザインコントラクトを生成します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号（デフォルトは現在のフェーズ） |
+| `N` | No | フェーズ番号（デフォルト: 現在のフェーズ） |
-**前提条件:** `.planning/ROADMAP.md` が存在し、フェーズにフロントエンド/UI作業があること
+**前提条件:** `.planning/ROADMAP.md` が存在し、フェーズにフロントエンド/UI 作業があること
**生成物:** `{phase}-UI-SPEC.md`
```bash
-/gsd-ui-phase 2 # フェーズ2のデザイン契約書
+/gsd-ui-phase 2 # フェーズ2のデザインコントラクト
```
---
### `/gsd-plan-phase`
-フェーズの調査、計画、検証を行います。
+フェーズのリサーチ、計画、および検証を行います。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号（デフォルトは次の未計画フェーズ） |
+| `N` | No | フェーズ番号（デフォルト: 次の未計画フェーズ） |
| フラグ | 説明 |
|------|-------------|
-| `--auto` | 対話的な確認をスキップ |
-| `--research` | RESEARCH.mdが存在しても強制的に再調査 |
-| `--skip-research` | ドメイン調査ステップをスキップ |
-| `--gaps` | ギャップ解消モード（VERIFICATION.mdを読み込み、調査をスキップ） |
+| `--auto` | インタラクティブな確認をスキップ |
+| `--research` | RESEARCH.md が存在する場合でも強制的に再リサーチ |
+| `--skip-research` | ドメインリサーチステップをスキップ |
+| `--research-phase ` | リサーチのみモード: フェーズ `` 用にリサーチャーを起動し、RESEARCH.md を書き込んでからプランナーの前に終了。削除されたスタンドアロンリサーチコマンドを置き換えます（#3042）。 |
+| `--view` | リサーチのみ修飾子: `--research-phase` と組み合わせて使用すると、既存の RESEARCH.md を標準出力に表示して終了（起動なし）。 |
+| `--gaps` | ギャップクローズモード（VERIFICATION.md を読み込み、リサーチをスキップ） |
| `--skip-verify` | プランチェッカーの検証ループをスキップ |
-| `--prd ` | discuss-phaseの代わりにPRDファイルをコンテキストとして使用 |
-| `--reviews` | REVIEWS.mdのクロスAIレビューフィードバックで再計画 |
+| `--prd ` | コンテキストに discuss-phase の代わりに PRD ファイルを使用 |
+| `--ingest ` | コンテキスト統合に discuss-phase の代わりに ADR ファイルを使用 |
+| `--ingest-format ` | `--ingest` のオプション ADR パーサーフォーマットの上書き |
+| `--reviews` | REVIEWS.md のクロス AI レビューフィードバックで再計画 |
+| `--validate` | 計画開始前に状態検証を実行 |
+| `--bounce` | 計画後に外部プランバウンス検証を実行（`workflow.plan_bounce_script` を使用） |
+| `--skip-bounce` | 設定で有効になっている場合でもプランバウンスをスキップ |
+| `--mvp` | 垂直 MVP モード — プランナーはタスクを水平レイヤーではなく機能スライス（UI→API→DB）として整理します。以前のフェーズサマリーがない新規プロジェクトのフェーズ1では、`SKELETON.md`（Walking Skeleton）も生成します。ROADMAP.md の `**Mode:** mvp` でフェーズごとに永続化でき、フラグなしで `--mvp` が自動適用されます。 |
+| `--tdd` | TDD モード — プランナーは動作追加タスクに `type: tdd` を適用し、各タスクが失敗するテストから始まるようにします。`--mvp` と組み合わせ可能: `--mvp --tdd` は、すべての動作追加タスクが red-green から始まる垂直スライスを生成します。 |
**前提条件:** `.planning/ROADMAP.md` が存在すること
-**生成物:** `{phase}-RESEARCH.md`、`{phase}-{N}-PLAN.md`、`{phase}-VALIDATION.md`
+**生成物:** `{phase}-RESEARCH.md`、`{phase}-{N}-PLAN.md`、`{phase}-VALIDATION.md`; Walking Skeleton モードが発火した場合は `{phase}/SKELETON.md`
+
+**リサーチのみモード（`--research-phase `）:**
+- 修飾子なし: RESEARCH.md が既に存在する場合は `update / view / skip` を促します。
+- `--research` 付き: 強制更新 — 無条件にリサーチャーを再起動し、プロンプトなし。
+- `--view` 付き: 既存の RESEARCH.md を標準出力に表示し、起動なし。RESEARCH.md がない場合はエラー。
+
+**パッケージ正当性ゲート（v1.42.1）:**
+リサーチャーが外部パッケージを推奨する場合、各パッケージに対して `slopcheck install --json` を実行し、Registry、Age、Downloads、Source Repo、および slopcheck の評決を記録した `## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込みます。評決:
+
+- `[SLOP]` — パッケージは RESEARCH.md から完全に削除され、プランナーには届かない
+- `[SUS]` — パッケージにフラグが付けられ、プランナーはインストールタスクの前に `checkpoint:human-verify` を挿入
+- `[OK]` — パッケージが承認され、チェックポイントは追加されない
+
+WebSearch から取得したパッケージは `[ASSUMED]`（`[VERIFIED]` ではない）とタグ付けされ、`[SUS]` と同様に扱われます — インストール前に人間によるチェックポイントが設けられます。`slopcheck` がインストールできない場合、すべての推奨パッケージは `[ASSUMED]` とタグ付けされ、ゲートが設けられます。
+
+詳細については、[ユーザーガイドのパッケージ正当性ゲート](../USER-GUIDE.md#package-legitimacy-gate-v1421)（チェックポイント形式、評決テーブル、トラブルシューティングを含む）を参照してください。
```bash
-/gsd-plan-phase 1 # フェーズ1の調査＋計画＋検証
-/gsd-plan-phase 3 --skip-research # 調査なしで計画（馴染みのあるドメイン）
-/gsd-plan-phase --auto # 非対話型の計画
+/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 # 強制更新リサーチ、プロンプトなし
+/gsd-plan-phase 1 --mvp # フェーズ1の垂直スライス計画
+/gsd-plan-phase 1 --mvp --tdd # 垂直スライス + 動作追加タスクごとに失敗するテスト
+```
+
+---
+
+### `/gsd-plan-review-convergence`
+
+クロス AI プラン収束ループ — HIGH の懸念がなくなるまでレビューフィードバックで再計画します。`plan-phase → review → replan → re-review` のサイクルを実行します（デフォルトで最大3サイクル）。計画とレビューのために隔離されたエージェントを起動し、オーケストレーターはループ制御、HIGH 懸念のカウント、ストール検出、およびエスカレーションを処理します。
+
+| 引数 / フラグ | 必須 | 説明 |
+|-----------------|----------|-------------|
+| `N` | **Yes** | 計画およびレビューするフェーズ番号 |
+| `--codex` / `--gemini` / `--claude` / `--opencode` | No | 単一レビュアーの選択 |
+| `--all` | No | 設定済みのすべてのレビュアーを並列で実行 |
+| `--max-cycles N` | No | サイクル上限を上書き（デフォルト3） |
+
+**終了動作:** HIGH カウントがゼロになるとループが終了します。HIGH カウントがサイクル間で減少しない場合はストール検出が警告します。`--max-cycles` に達しても HIGH 懸念が残っている場合、エスカレーションゲートがユーザーに続行するか手動でレビューするかを確認します。
+
+```bash
+/gsd-plan-review-convergence 3 # デフォルトレビュアー、3サイクル
+/gsd-plan-review-convergence 3 --codex # Codex のみのレビュー
+/gsd-plan-review-convergence 3 --all --max-cycles 5
+```
+
+---
+
+### `/gsd-ultraplan-phase`
+
+**[BETA]** Claude Code の ultraplan クラウドにプランフェーズをオフロードし、ブラウザでレビューして戻りのインポートを行います。計画はリモートでドラフトされるためターミナルは自由なままです。ブラウザでインラインコメントをレビューし、確定した計画を `/gsd-import` を使って `.planning/` にインポートします。
+
+| フラグ | 必須 | 説明 |
+|------|----------|-------------|
+| `N` | **Yes** | リモートで計画するフェーズ番号 |
+
+**隔離:** `/gsd-plan-phase` から意図的に分離されており、ultraplan の変更がコア計画パイプラインに影響を与えないようになっています。
+
+```bash
+/gsd-ultraplan-phase 4 # フェーズ4の計画をオフロード
```
---
### `/gsd-execute-phase`
-フェーズ内のすべてのプランをウェーブベースの並列化で実行するか、特定のウェーブを実行します。
+波ベースの並列化でフェーズ内のすべての計画を実行するか、特定の波のみを実行します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | **はい** | 実行するフェーズ番号 |
-| `--wave N` | いいえ | フェーズ内のウェーブ `N` のみを実行 |
+| `N` | **Yes** | 実行するフェーズ番号 |
+| `--wave N` | No | フェーズ内の波 `N` のみを実行 |
+| `--validate` | No | 実行開始前に状態検証を実行 |
+| `--cross-ai` | No | 外部 AI CLI に実行を委任（`workflow.cross_ai_command` を使用） |
+| `--no-cross-ai` | No | 設定でクロス AI が有効な場合でもローカル実行を強制 |
-**前提条件:** フェーズにPLAN.mdファイルがあること
-**生成物:** プランごとの `{phase}-{N}-SUMMARY.md`、gitコミット、フェーズ完了時に `{phase}-VERIFICATION.md`
+**前提条件:** フェーズに PLAN.md ファイルがあること
+**生成物:** 計画ごとの `{phase}-{N}-SUMMARY.md`、git コミット、フェーズが完全に完了すると `{phase}-VERIFICATION.md`
+
+**パッケージインストール失敗（v1.42.1）:** 計画のインストールステップが失敗した場合、エグゼキューターは `checkpoint:human-verify` を表示して停止します。類似した名前の代替パッケージを自動インストールすることはありません。これは意図的なものです — パッケージ名を暗黙的に置き換えることは、スロップスクワッティングが広がる経路だからです。レジストリページでパッケージを確認した後にチェックポイントに応答してください。
```bash
/gsd-execute-phase 1 # フェーズ1を実行
-/gsd-execute-phase 1 --wave 2 # ウェーブ2のみを実行
+/gsd-execute-phase 1 --wave 2 # 波2のみを実行
+/gsd-execute-phase 1 --validate # 実行前に状態を検証
+/gsd-execute-phase 2 --cross-ai # フェーズ2を外部 AI CLI に委任
```
---
### `/gsd-verify-work`
-自動診断付きのユーザー受入テスト。
+自動診断付きのユーザー受け入れテスト。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号（デフォルトは最後に実行されたフェーズ） |
+| `N` | No | フェーズ番号（デフォルト: 最後に実行されたフェーズ） |
**前提条件:** フェーズが実行済みであること
-**生成物:** `{phase}-UAT.md`、問題が見つかった場合は修正プラン
+**生成物:** `{phase}-UAT.md`、問題が見つかった場合は修正計画
+
+ブラウザバックの UAT には、設定済みのブラウザ MCP サーバーを使用してください。現在の Open GSD コンパニオンは `gsd-browser`（`gsd-browser mcp`）で、決定論的なナビゲーション、バージョン管理された参照、アサーション、スクリーンショット、ビジュアル差分、録画、および人間への引き継ぎを提供します。既に設定済みのレガシー Playwright MCP サーバーも引き続き使用できます。
```bash
-/gsd-verify-work 1 # フェーズ1のUAT
+/gsd-verify-work 1 # フェーズ1の UAT
```
---
-### `/gsd-progress --next`
-
-次の論理的なワークフローステップに自動的に進みます。プロジェクトの状態を読み取り、適切なコマンドを実行します。
-
-**前提条件:** `.planning/` ディレクトリが存在すること
-**動作:**
-- プロジェクトなし → `/gsd-new-project` を提案
-- フェーズにディスカッションが必要 → `/gsd-discuss-phase` を実行
-- フェーズに計画が必要 → `/gsd-plan-phase` を実行
-- フェーズに実行が必要 → `/gsd-execute-phase` を実行
-- フェーズに検証が必要 → `/gsd-verify-work` を実行
-- 全フェーズ完了 → `/gsd-complete-milestone` を提案
-
-```bash
-/gsd-progress --next # 次のステップを自動検出して実行
-```
-
----
-
-### `/gsd-pause-work --report`
-
-作業サマリー、成果、推定リソース使用量を含むセッションレポートを生成します。
-
-**前提条件:** 直近の作業があるアクティブなプロジェクト
-**生成物:** `.planning/reports/SESSION_REPORT.md`
-
-```bash
-/gsd-pause-work --report # セッション後のサマリーを生成
-```
-
-**レポートに含まれる内容:**
-- 実施した作業（コミット、実行したプラン、進行したフェーズ）
-- 成果と成果物
-- ブロッカーと意思決定
-- 推定トークン/コスト使用量
-- 次のステップの推奨事項
-
---
### `/gsd-ship`
-完了したフェーズの作業から自動生成された本文でPRを作成します。
+完了したフェーズ作業から自動生成された本文付きの PR を作成します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号またはマイルストーンバージョン（例: `4` または `v1.0`） |
-| `--draft` | いいえ | ドラフトPRとして作成 |
+| `N` | No | フェーズ番号またはマイルストーンバージョン（例: `4` または `v1.0`） |
+| `--draft` | No | ドラフト PR として作成 |
-**前提条件:** フェーズが検証済み（`/gsd-verify-work` が合格）、`gh` CLIがインストールされ認証済みであること
-**生成物:** 計画アーティファクトからリッチな本文を持つGitHub PR、STATE.mdの更新
+**前提条件:** フェーズが検証済み（`/gsd-verify-work` が合格）、`gh` CLI がインストールされ認証済みであること
+**生成物:** 計画アーティファクトから豊富な本文を持つ GitHub PR、STATE.md が更新される
```bash
-/gsd-ship 4 # フェーズ4をシップ
-/gsd-ship 4 --draft # ドラフトPRとしてシップ
+/gsd-ship 4 # フェーズ4を ship
+/gsd-ship 4 --draft # ドラフト PR として ship
```
-**PR本文に含まれる内容:**
-- ROADMAP.mdからのフェーズ目標
-- SUMMARY.mdファイルからの変更サマリー
+**PR 本文の内容:**
+- ROADMAP.md からのフェーズ目標
+- SUMMARY.md ファイルからの変更サマリー
- 対応した要件（REQ-ID）
- 検証ステータス
-- 主要な意思決定
+- 主要な決定事項
+- `ship.pr_body_sections` から設定されたオプションの PRD スタイルセクション
+
+カスタム PR 本文セクションについては、[カスタム PR 本文セクション](../ship-pr-body-sections.md)（オンボーディング、例、検証ルールを含む）を参照してください。
---
### `/gsd-ui-review`
-実装済みフロントエンドの事後的な6軸ビジュアル監査。
+実装済みフロントエンドの事後的な6ピラービジュアル監査。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号（デフォルトは最後に実行されたフェーズ） |
+| `N` | No | フェーズ番号（デフォルト: 最後に実行されたフェーズ） |
-**前提条件:** プロジェクトにフロントエンドコードがあること（単体で動作、GSDプロジェクト不要）
+**前提条件:** プロジェクトにフロントエンドコードがあること（スタンドアロンで動作し、GSD プロジェクトは不要）
**生成物:** `{phase}-UI-REVIEW.md`、`.planning/ui-reviews/` 内のスクリーンショット
+より豊富なビジュアル証拠のために、`gsd-browser` や別のブラウザ MCP サーバーと組み合わせて使用すると、監査がスクリーンショット、状態、コンソール/ネットワークコンテキスト、および再現可能なインタラクション手順をキャプチャできます。
+
```bash
/gsd-ui-review # 現在のフェーズを監査
/gsd-ui-review 3 # フェーズ3を監査
@@ -283,10 +329,10 @@
### `/gsd-audit-uat`
-全フェーズを横断した未処理のUATおよび検証項目の監査。
+すべての未解決の UAT および検証項目のクロスフェーズ監査。
-**前提条件:** 少なくとも1つのフェーズがUATまたは検証付きで実行されていること
-**生成物:** カテゴリ分類された監査レポートと人間用テストプラン
+**前提条件:** 少なくとも1つのフェーズが UAT または検証付きで実行済みであること
+**生成物:** 人間によるテスト計画を含むカテゴリ別監査レポート
```bash
/gsd-audit-uat
@@ -296,9 +342,9 @@
### `/gsd-audit-milestone`
-マイルストーンが完了定義を満たしたかを検証します。
+マイルストーンが完了の定義を満たしていることを検証します。
-**前提条件:** 全フェーズが実行済みであること
+**前提条件:** すべてのフェーズが実行済みであること
**生成物:** ギャップ分析付き監査レポート
```bash
@@ -309,10 +355,10 @@
### `/gsd-complete-milestone`
-マイルストーンをアーカイブし、リリースをタグ付けします。
+マイルストーンをアーカイブし、リリースにタグを付けます。
**前提条件:** マイルストーン監査が完了していること（推奨）
-**生成物:** `MILESTONES.md` エントリ、gitタグ
+**生成物:** `MILESTONES.md` エントリ、git タグ
```bash
/gsd-complete-milestone
@@ -322,26 +368,26 @@
### `/gsd-milestone-summary`
-チームのオンボーディングやレビューのために、マイルストーンのアーティファクトから包括的なプロジェクトサマリーを生成します。
+チームのオンボーディングとレビューのためにマイルストーンアーティファクトから包括的なプロジェクトサマリーを生成します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `version` | いいえ | マイルストーンバージョン（デフォルトは現在/最新のマイルストーン） |
+| `version` | No | マイルストーンバージョン（デフォルト: 現在の/最新のマイルストーン） |
**前提条件:** 少なくとも1つの完了済みまたは進行中のマイルストーンがあること
**生成物:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md`
-**サマリーに含まれる内容:**
-- 概要、アーキテクチャの意思決定、フェーズごとの詳細分析
-- 主要な意思決定とトレードオフ
+**サマリーの内容:**
+- 概要、アーキテクチャ決定、フェーズ別の内訳
+- 主要な決定とトレードオフ
- 要件カバレッジ
-- 技術的負債と先送り項目
-- 新しいチームメンバー向けのスタートガイド
-- 生成後に対話的なQ&Aを提供
+- 技術的負債と延期された項目
+- 新しいチームメンバー向けのスタートアップガイド
+- 生成後にインタラクティブな Q&A を提供
```bash
-/gsd-milestone-summary # 現在のマイルストーンをサマリー
-/gsd-milestone-summary v1.0 # 特定のマイルストーンをサマリー
+/gsd-milestone-summary # 現在のマイルストーンのサマリー
+/gsd-milestone-summary v1.0 # 特定のマイルストーンのサマリー
```
---
@@ -352,16 +398,16 @@
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `name` | いいえ | マイルストーン名 |
-| `--reset-phase-numbers` | いいえ | 新しいマイルストーンをフェーズ1から開始し、ロードマップ作成前に古いフェーズディレクトリをアーカイブ |
+| `name` | No | マイルストーン名 |
+| `--reset-phase-numbers` | No | 新しいマイルストーンをフェーズ1から再開し、ロードマップ作成前に古いフェーズディレクトリをアーカイブ |
-**前提条件:** 前のマイルストーンが完了していること
+**前提条件:** 以前のマイルストーンが完了していること
**生成物:** 更新された `PROJECT.md`、新しい `REQUIREMENTS.md`、新しい `ROADMAP.md`
```bash
-/gsd-new-milestone # 対話モード
+/gsd-new-milestone # インタラクティブ
/gsd-new-milestone "v2.0 Mobile" # 名前付きマイルストーン
-/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile" # マイルストーン番号を1からリスタート
+/gsd-new-milestone --reset-phase-numbers "v2.0 Mobile" # マイルストーン番号付けを1から再開
```
---
@@ -370,68 +416,64 @@
### `/gsd-phase`
-ロードマップに新しいフェーズを追加します。
+ROADMAP.md のフェーズの CRUD — 単一の統合コマンドでフェーズを追加、挿入、削除、または編集します。
+
+| フラグ | 説明 |
+|------|-------------|
+| （なし） | 現在のマイルストーンの末尾に新しい整数フェーズを追加 |
+| `--insert ` | 緊急作業をフェーズ N の後に小数フェーズとして挿入（例: 3.1） |
+| `--remove ` | 将来のフェーズを削除し、後続のフェーズを番号付け直し |
+| `--edit ` | 既存フェーズの任意のフィールドをその場で編集 |
+| `--force` | 進行中または完了済みのフェーズの編集を許可（`--edit` と組み合わせて使用） |
+
+**前提条件:** `.planning/ROADMAP.md` が存在すること
+**生成物:** 更新された ROADMAP.md
```bash
-/gsd-phase # 対話型 — フェーズの説明を入力
+/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を編集
```
-### `/gsd-phase --insert`
+---
-小数番号を使用して、フェーズ間に緊急の作業を挿入します。
+### `/gsd-mvp-phase`
+
+フェーズのガイド付き MVP 計画 — ユーザーストーリーを入力するよう促し、SPIDR 分割チェックを実行し、ROADMAP.md に `**Mode:** mvp` を書き込み、次に `/gsd-plan-phase` に委任します（ロードマップフィールドを介して MVP モードを自動検出）。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | このフェーズ番号の後に挿入 |
+| `N` | **Yes** | MVP モードに変換するフェーズ番号（整数または `2.1` のような小数） |
+
+| フラグ | 説明 |
+|------|-------------|
+| `--force` | `in_progress` または `completed` のフェーズの変換を許可 |
+
+**前提条件:** フェーズが ROADMAP.md に既に存在すること（`/gsd-new-project`、`/gsd-phase`、または `/gsd-phase --insert` で作成済み）。このコマンドは新しいフェーズを作成せず、既存のフェーズを変換します。
+
+**動作:** 構造化されたユーザーストーリーを収集し、フォーマットを検証し、SPIDR 分割チェックを実行し、フェーズの ROADMAP.md セクションに `**Goal:**` と `**Mode:** mvp` を書き込み、次に `/gsd-plan-phase ` に委任します。ウォークスルーについては [MVP フェーズの計画方法](../USER-GUIDE.md#mvp-phase-planning) を参照してください。
+
+**Walking Skeleton:** 以前のフェーズサマリーがない新規プロジェクトのフェーズ1で `--mvp`（または `mode: mvp`）が使用された場合に自動トリガーされます。プランナーは `PLAN.md` と並んで `SKELETON.md` を生成します。
+
+**生成物:** 更新された ROADMAP.md、次に `/gsd-plan-phase` からのすべてのアーティファクト; Walking Skeleton モードが発火した場合は `SKELETON.md`。
```bash
-/gsd-phase --insert 3 # フェーズ3と4の間に挿入 → 3.1を作成
+/gsd-mvp-phase 1 # フェーズ1の MVP 計画
+/gsd-mvp-phase 2.1 # 小数フェーズの MVP 計画
+/gsd-mvp-phase 3 --force # 進行中の場合でもフェーズ3を変換
```
-### `/gsd-phase --remove`
-
-将来のフェーズを削除し、後続のフェーズの番号を振り直します。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `N` | いいえ | 削除するフェーズ番号 |
-
-```bash
-/gsd-phase --remove 7 # フェーズ7を削除、8→7、9→8等に番号振り直し
-```
-
-### `/gsd-discuss-phase --assumptions`
-
-計画前にClaudeの意図するアプローチをプレビューします。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号 |
-
-```bash
-/gsd-discuss-phase --assumptions 2 # フェーズ2の前提を確認
-```
-
-
-### `/gsd-plan-phase --research-phase`
-
-詳細なエコシステム調査のみを実行します（単体機能 — 通常は `/gsd-plan-phase` を使用してください）。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号 |
-
-```bash
-/gsd-plan-phase --research-phase 4 # フェーズ4のドメインを調査
-```
+---
### `/gsd-validate-phase`
-遡及的にNyquistバリデーションのギャップを監査・補填します。
+Nyquist 検証ギャップを事後的に監査して埋めます。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号 |
+| `N` | No | フェーズ番号 |
```bash
/gsd-validate-phase 2 # フェーズ2のテストカバレッジを監査
@@ -443,88 +485,219 @@
### `/gsd-progress`
-ステータスと次のステップを表示します。
+ステータス、次のステップを表示し、次の論理的なワークフローステップに自動的に進みます。プロジェクトの状態を読み込んで適切なアクションを決定します。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--next` | 手動のルート選択なしに次の論理的なワークフローステップに自動的に進む |
+| `--do "task description"` | 自由形式の意図を分析し、最も適切な GSD コマンドにディスパッチ |
+| `--forensic` | 標準レポートの後に6チェックの整合性監査を追加（STATE 整合性、孤立したハンドオフ、延期されたスコープドリフト、メモリフラグが付いた保留中の作業、ブロッキング todo、コミットされていないコード） |
+
+**自動ルーティング動作（`--next`）:**
+- プロジェクトなし → `/gsd-new-project` を提案
+- フェーズに議論が必要 → `/gsd-discuss-phase` を実行
+- フェーズに計画が必要 → `/gsd-plan-phase` を実行
+- フェーズに実行が必要 → `/gsd-execute-phase` を実行
+- フェーズに検証が必要 → `/gsd-verify-work` を実行
+- すべてのフェーズが完了 → `/gsd-complete-milestone` を提案
```bash
-/gsd-progress # "今どこにいる？次は何？"
+/gsd-progress # 「今どこにいる？次は何？」と自動ルーティング
+/gsd-progress --next # 次のステップに自動的に進む
+/gsd-progress --do "fix the auth bug" # 自由形式の意図を最適な GSD コマンドにディスパッチ
+/gsd-progress --forensic # 標準レポート + 整合性監査
```
### `/gsd-resume-work`
-前回のセッションから完全なコンテキストを復元します。
+最後のセッションからフルコンテキストを復元します。
```bash
-/gsd-resume-work # コンテキストリセットまたは新しいセッション後に使用
+/gsd-resume-work # コンテキストリセットまたは新しいセッションの後
```
### `/gsd-pause-work`
-フェーズの途中で中断する際にコンテキストのハンドオフを保存します。
+フェーズの途中で停止するときにコンテキストのハンドオフを保存します。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--report` | コミット、ファイル変更、フェーズ進捗をキャプチャするセッション後のサマリーを `.planning/reports/` に生成 |
```bash
-/gsd-pause-work # continue-here.mdを作成
+/gsd-pause-work # continue-here.md を作成
+/gsd-pause-work --report # continue-here.md + セッションレポートを作成
```
### `/gsd-manager`
-1つのターミナルから複数のフェーズを管理する対話的なコマンドセンター。
+1つのターミナルから複数のフェーズを管理するためのインタラクティブなコマンドセンター。
**前提条件:** `.planning/ROADMAP.md` が存在すること
**動作:**
-- 全フェーズのビジュアルステータスインジケータ付きダッシュボード
-- 依存関係と進捗に基づいた最適な次のアクションを推奨
-- 作業のディスパッチ: discussはインラインで実行、plan/executeはバックグラウンドエージェントとして実行
-- 1つのターミナルから複数フェーズの作業を並列化するパワーユーザー向け
+- 視覚的なステータスインジケーター付きのすべてのフェーズのダッシュボード
+- 依存関係と進捗に基づいて最適な次のアクションを推奨
+- 作業をディスパッチ: discuss はインラインで実行、plan/execute はバックグラウンドエージェントとして実行
+- 1つのターミナルから複数のフェーズで作業を並列化するパワーユーザー向けに設計
+- `manager.flags` 設定によるステップごとのパススルーフラグをサポート（[設定](../CONFIGURATION.md#manager-passthrough-flags) を参照）
```bash
-/gsd-manager # コ��ンドセンターダッシュボードを開く
+/gsd-manager # コマンドセンターダッシュボードを開く
+/gsd-manager --analyze-deps # 並列実行前に ROADMAP フェーズの依存関係を解析
```
----
+**チェックポイントハートビート（#2410）:**
-### `/gsd-manager --analyze-deps`
+バックグラウンドの `execute-phase` 実行は、すべての波と計画の境界で `[checkpoint]` マーカーを出力します。これにより、Claude API の SSE ストリームが複数計画フェーズで `Stream idle timeout - partial response received` をトリガーするほど長くアイドル状態にならないようにします。フォーマットは次のとおりです:
-フェーズ依存関係を検出し、ROADMAP.md に `Depends on` エントリを提案します。(v1.32)
+```
+[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)
+```
-**前提���件:** `.planning/ROADMAP.md` が存在すること
-**検出方法:** ファイルオーバーラップ、セマンティック依存関係（API/スキーマのプロデューサーとコンシューマー）、データフロー依存関係
-**動作:** 依存関係提案テーブルを表示し、ユーザー確認後に ROADMAP.md の `Depends on` フィールドを更新します。
+バックグラウンドフェーズが途中で失敗した場合、トランスクリプトで `[checkpoint]` を grep すると最後に確認された境界を確認できます。マネージャーのバックグラウンド完了ハンドラーは、エージェントがエラーになったときにこれらのマーカーを使用して部分的な進捗を報告します。
-```bash
-/gsd-manager --analyze-deps # 依存関係の分析と提案
+**マネージャーパススルーフラグ:**
+
+`.planning/config.json` の `manager.flags` 配下でステップごとのフラグを設定します。これらのフラグは各ディスパッチコマンドに追加されます:
+
+```json
+{
+ "manager": {
+ "flags": {
+ "discuss": "--auto",
+ "plan": "--skip-research",
+ "execute": "--validate"
+ }
+ }
+}
```
---
### `/gsd-help`
-すべてのコマンドと使用ガイドを表示します。
+要求したティアで GSD コマンドを表示します。デフォルトは1画面に収まります; `--full` は完全なリファレンス; `` は1つのセクションに直接ジャンプします。
```bash
-/gsd-help # クイックリファレンス
+/gsd-help # 1ページのツアー（デフォルト）
+/gsd-help --brief # トップコマンドの ~10 行の1ライナーリフレッシャー
+/gsd-help --full # 完全なリファレンス（すべてのコマンド、すべてのフラグ）
+/gsd-help # 1つのセクションのみ（例: /gsd-help debug）
+/gsd-help --brief # コンパクトなスコープ付きルックアップ — シグネチャ + 1行サマリー
```
+完全なエイリアステーブルについては `get-shit-done/workflows/help/modes/topic.md` を参照してください。不明なトピックは認識されたリストを表示します。
+
---
## ユーティリティコマンド
+### `/gsd-explore`
+
+ソクラテス式のアイデア発想セッション — 探索的な質問を通じてアイデアをガイドし、オプションでリサーチを起動し、出力を適切な GSD アーティファクト（メモ、todo、シード、リサーチ質問、要件、または新しいフェーズ）にルーティングします。
+
+| 引数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `topic` | No | 探索するトピック（例: `/gsd-explore authentication strategy`） |
+
+```bash
+/gsd-explore # オープンエンドのアイデア発想セッション
+/gsd-explore authentication strategy # 特定のトピックを探索
+```
+
+---
+
+### `/gsd-undo`
+
+安全な git リバート — フェーズマニフェストを使用して依存関係チェックと確認ゲートで GSD フェーズまたは計画コミットをロールバックします。
+
+| フラグ | 必須 | 説明 |
+|------|----------|-------------|
+| `--last N` | （3つのうち1つが必須） | インタラクティブな選択のための最近の GSD コミットを表示 |
+| `--phase NN` | （3つのうち1つが必須） | フェーズのすべてのコミットをリバート |
+| `--plan NN-MM` | （3つのうち1つが必須） | 特定の計画のすべてのコミットをリバート |
+
+**安全性:** リバートする前に依存するフェーズ/計画をチェック; 常に確認ゲートを表示します。
+
+```bash
+/gsd-undo --last 5 # 最近の5つの GSD コミットから選択
+/gsd-undo --phase 03 # フェーズ3のすべてのコミットをリバート
+/gsd-undo --plan 03-02 # フェーズ3の計画02のコミットをリバート
+```
+
+---
+
+### `/gsd-import`
+
+外部計画ファイルを GSD 計画システムに取り込み、何かを書き込む前に `PROJECT.md` の決定に対して競合を検出します。
+
+| フラグ | 必須 | 説明 |
+|------|----------|--------------|
+| `--from ` | Yes（または `--from-gsd2`） | インポートする外部計画ファイルへのパス |
+| `--from-gsd2` | Yes（または `--from`） | GSD-2（`.gsd/`）プロジェクトを GSD v1（`.planning/`）フォーマットに逆移行 |
+| `--path ` | No | `--from-gsd2` と組み合わせて使用: GSD-2 プロジェクトディレクトリへのパス（デフォルト: 現在のディレクトリ） |
+
+**プロセス:** 競合を検出 → 解決を促す → GSD PLAN.md として書き込む → `gsd-plan-checker` で検証
+
+```bash
+/gsd-import --from /tmp/team-plan.md # 外部計画をインポートして検証
+/gsd-import --from-gsd2 # GSD-2 から v1 に移行（現在のディレクトリ）
+/gsd-import --from-gsd2 --path ~/old-project # 別のパスから移行
+```
+
+---
+
+### `/gsd-ingest-docs`
+
+リポジトリ内の既存の ADR、PRD、SPEC、およびドキュメントから `.planning/` セットアップをブートストラップまたはマージします。並列分類（`gsd-doc-classifier`）と優先順位ルールおよびサイクル検出による統合（`gsd-doc-synthesizer`）を実行します。3バケットの競合レポート（`INGEST-CONFLICTS.md`: 自動解決済み、競合バリアント、未解決ブロッカー）を生成し、LOCKED vs LOCKED の ADR 矛盾でハードブロックします。
+
+| 引数 / フラグ | 必須 | 説明 |
+|-----------------|----------|-------------|
+| `path` | No | スキャンするターゲットディレクトリ（デフォルト: リポジトリルート） |
+| `--mode new\|merge` | No | 自動検出を上書き（デフォルト: `.planning/` がなければ `new`、あれば `merge`） |
+| `--manifest ` | No | ドキュメントごとに `{path, type, precedence?}` を列挙する YAML ファイル; ヒューリスティック分類を上書き |
+| `--resolve auto` | No | 競合解決モード（v1: `auto` のみ; `interactive` は予約済み） |
+
+**制限:** v1 は呼び出しごとに最大50ドキュメント。共有の競合検出コントラクトを `references/doc-conflict-engine.md` に抽出し、`/gsd-import` も消費します。
+
+```bash
+/gsd-ingest-docs # リポジトリルートをスキャン、モードを自動検出
+/gsd-ingest-docs docs/ # docs/ 配下のみを取り込む
+/gsd-ingest-docs --manifest ingest.yaml # 明示的な優先順位マニフェスト
+```
+
+---
+
### `/gsd-quick`
-GSDの保証付きでアドホックタスクを実行します。
+GSD の保証付きでアドホックタスクを実行します。
| フラグ | 説明 |
|------|-------------|
-| `--full` | プランチェック（2回のイテレーション）＋実行後検証を有効化 |
-| `--discuss` | 軽量な事前計画ディスカッション |
+| `--full` | 完全な品質パイプラインを有効化 — 議論 + リサーチ + プランチェック + 検証 |
+| `--validate` | プランチェック（最大2回繰り返し）+ 実行後検証のみ; 議論やリサーチなし |
+| `--discuss` | 軽量な事前計画議論 |
| `--research` | 計画前にフォーカスされたリサーチャーを起動 |
-フラグは組み合わせ可能です。
+細粒度のフラグは組み合わせ可能: `--discuss --research --validate` は `--full` と同等です。
+
+| サブコマンド | 説明 |
+|------------|-------------|
+| `list` | ステータス付きですべてのクイックタスクを一覧表示 |
+| `status ` | 特定のクイックタスクのステータスを表示 |
+| `resume ` | スラッグで特定のクイックタスクを再開 |
```bash
/gsd-quick # 基本的なクイックタスク
-/gsd-quick --discuss --research # ディスカッション＋調査＋計画
-/gsd-quick --full # プランチェックと検証付き
-/gsd-quick --discuss --research --full # すべてのオプションステージ
+/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 # クイックタスクを再開
```
### `/gsd-autonomous`
@@ -534,44 +707,14 @@ GSDの保証付きでアドホックタスクを実行します。
| フラグ | 説明 |
|------|-------------|
| `--from N` | 特定のフェーズ番号から開始 |
-| `--to N` | フェーズ N 完了後に自律実行を停止 (v1.32) |
-| `--only N` | 指定された単一フェーズのみを自律的に実行 (v1.31) |
-| `--interactive` | 各フェーズのディスカスステップでユーザー確認を要求 |
+| `--to N` | 特定のフェーズ番号を完了した後に停止 |
+| `--interactive` | ユーザー入力付きのリーンコンテキスト |
```bash
-/gsd-autonomous # 残りの全フェーズを実行
+/gsd-autonomous # 残りのすべてのフェーズを実行
/gsd-autonomous --from 3 # フェーズ3から開始
-/gsd-autonomous --to 5 # フェーズ5まで実行
-/gsd-autonomous --from 3 --to 5 # フェーズ3〜5の範囲を実行
-/gsd-autonomous --only 4 # フェーズ4のみを自律実行
-```
-
-### `/gsd-fast`
-
-フリーテキストを適切なGSDコマンドにルーティングします。
-
-```bash
-/gsd-fast # その後、やりたいことを説明
-```
-
-### `/gsd-capture`
-
-手軽にアイデアをキャプチャ — メモの追加、一覧表示、またはTodoへの昇格。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `text` | いいえ | キャプチャするメモテキスト（デフォルト: 追加モード） |
-| `list` | いいえ | プロジェクトおよびグローバルスコープからすべてのメモを一覧表示 |
-| `promote N` | いいえ | メモNを構造化されたTodoに変換 |
-
-| フラグ | 説明 |
-|------|-------------|
-| `--global` | メモ操作にグローバルスコープを使用 |
-
-```bash
-/gsd-capture "Consider caching strategy for API responses"
-/gsd-capture list
-/gsd-capture promote 3
+/gsd-autonomous --to 5 # フェーズ5を含めて実行
+/gsd-autonomous --from 3 --to 5 # フェーズ3から5を実行
```
### `/gsd-debug`
@@ -580,35 +723,26 @@ GSDの保証付きでアドホックタスクを実行します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `description` | いいえ | バグの説明 |
+| `description` | No | バグの説明 |
| フラグ | 説明 |
|------|-------------|
-| `--diagnose` | 修正を試みず調査のみを行う診断専用モード (v1.32) |
+| `--diagnose` | 診断のみモード — 修正を試みずに調査 |
+
+**サブコマンド:**
+- `/gsd-debug list` — ステータス、仮説、次のアクション付きですべてのアクティブなデバッグセッションを一覧表示
+- `/gsd-debug status ` — エージェントを起動せずにセッションの完全なサマリーを表示（証拠数、排除数、解決策、TDD チェックポイント）
+- `/gsd-debug continue ` — スラッグで特定のセッションを再開（現在のフォーカスを表示してから継続エージェントを起動）
+- `/gsd-debug [--diagnose] ` — 新しいデバッグセッションを開始（既存の動作; `--diagnose` は修正を適用せずに根本原因で停止）
+
+**TDD モード:** `.planning/config.json` に `tdd_mode: true` がある場合、デバッグセッションでは修正を適用する前に失敗するテストを書いて検証する必要があります（red → green → done）。
```bash
/gsd-debug "Login button not responding on mobile Safari"
-/gsd-debug --diagnose "API returning 500 on /users endpoint"
-```
-
-### `/gsd-capture`
-
-後で取り組むアイデアやタスクをキャプチャします。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `description` | いいえ | Todoの説明 |
-
-```bash
-/gsd-capture "Consider adding dark mode support"
-```
-
-### `/gsd-capture --list`
-
-保留中のTodoを一覧表示し、取り組むものを選択します。
-
-```bash
-/gsd-capture --list
+/gsd-debug --diagnose "Intermittent 500 errors on /api/users"
+/gsd-debug list
+/gsd-debug status auth-token-null
+/gsd-debug continue form-submit-500
```
### `/gsd-add-tests`
@@ -617,7 +751,7 @@ GSDの保証付きでアドホックタスクを実行します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `N` | いいえ | フェーズ番号 |
+| `N` | No | フェーズ番号 |
```bash
/gsd-add-tests 2 # フェーズ2のテストを生成
@@ -625,7 +759,7 @@ GSDの保証付きでアドホックタスクを実行します。
### `/gsd-stats`
-プロジェクトの統計情報を表示します。
+プロジェクト統計を表示します。
```bash
/gsd-stats # プロジェクトメトリクスダッシュボード
@@ -633,39 +767,43 @@ GSDの保証付きでアドホックタスクを実行します。
### `/gsd-profile-user`
-Claude Codeのセッション分析から8つの次元（コミュニケーションスタイル、意思決定パターン、デバッグアプローチ、UXプリファレンス、ベンダー選択、フラストレーションのトリガー、学習スタイル、説明の深さ）にわたる開発者行動プロファイルを生成します。Claudeのレスポンスをパーソナライズするアーティファクトを生成します。
+8つの次元（コミュニケーションスタイル、意思決定パターン、デバッグアプローチ、UX 設定、ベンダー選択、フラストレーショントリガー、学習スタイル、説明の深さ）で Claude Code セッション分析から開発者の行動プロファイルを生成します。Claude の応答をパーソナライズするアーティファクトを生成します。
| フラグ | 説明 |
|------|-------------|
-| `--questionnaire` | セッション分析の代わりに対話型アンケートを使用 |
+| `--questionnaire` | セッション分析の代わりにインタラクティブなアンケートを使用 |
| `--refresh` | セッションを再分析してプロファイルを再生成 |
**生成されるアーティファクト:**
- `USER-PROFILE.md` — 完全な行動プロファイル
-- `CLAUDE.md` プロファイルセクション — Claude Codeが自動検出
+- `CLAUDE.md` プロファイルセクション — Claude Code によって自動検出される
```bash
/gsd-profile-user # セッションを分析してプロファイルを構築
-/gsd-profile-user --questionnaire # 対話型アンケートのフォールバック
-/gsd-profile-user --refresh # 新鮮な分析からの再生成
+/gsd-profile-user --questionnaire # インタラクティブなアンケートのフォールバック
+/gsd-profile-user --refresh # 新鮮な分析から再生成
```
### `/gsd-health`
-`.planning/` ディレクトリの整合性を検証します。
+`.planning/` ディレクトリの整合性を検証します。`--context` を使用すると、60% / 70% のしきい値に対してコンテキストウィンドウ使用率ガードを検査します（v1.40.0 で追加、[#2792](https://github.com/open-gsd/gsd-core/issues/2792)）。
| フラグ | 説明 |
|------|-------------|
-| `--repair` | 回復可能な問題を自動修復 |
+| `--repair` | 回復可能な問題を自動修正 |
+| `--context` | コンテキストウィンドウ使用率を検査; 60% で警告、70% でクリティカル |
```bash
/gsd-health # 整合性チェック
-/gsd-health --repair # チェックして修復
+/gsd-health --repair # チェックと修正
+/gsd-health --context # コンテキスト使用率のトリアージ
```
### `/gsd-cleanup`
-完了したマイルストーンの蓄積されたフェーズディレクトリをアーカイブします。
+完了したマイルストーンからの累積フェーズディレクトリをアーカイブし、アップストリームが削除されたローカルブランチを削除します。
+
+**動作:** アーカイブするフェーズディレクトリ（`.planning/phases/` から `.planning/milestones/v{X.Y}-phases/` に移動）とアップストリームが消えたローカルブランチ（`git fetch --prune` で削除）のドライランサマリーを表示します。変更を書き込む前に確認が必要です。現在チェックアウトされているブランチは削除されません。
```bash
/gsd-cleanup
@@ -673,63 +811,141 @@ Claude Codeのセッション分析から8つの次元（コミュニケーシ
---
+## スパイキングとスケッチコマンド
+
+### `/gsd-spike`
+
+実装アプローチを確定する前に、2〜5つのフォーカスされた実現可能性実験を実行します。各実験は Given/When/Then のフレーミングを使用し、実行可能なコードを生成し、VALIDATED / INVALIDATED / PARTIAL の評決を返します。
+
+| 引数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `idea` | No | 調査する技術的な質問またはアプローチ |
+| `--quick` | No | 入力会話をスキップ; `idea` テキストを直接使用 |
+| `--wrap-up` | No | 完了したスパイクの知見を再利用可能なプロジェクトローカルスキルにパッケージ化 |
+
+**生成物:** `.planning/spikes/NNN-experiment-name/` にコード、結果、README; `.planning/spikes/MANIFEST.md`
+**`--wrap-up` の生成物:** `.claude/skills/spike-findings-[project]/` スキルファイル
+
+```bash
+/gsd-spike # インタラクティブな入力
+/gsd-spike "can we stream LLM tokens through SSE"
+/gsd-spike --quick websocket-vs-polling
+/gsd-spike --wrap-up # 知見を再利用可能なスキルにパッケージ化
+```
+
+---
+
+### `/gsd-sketch`
+
+実装を確定する前に使い捨ての HTML モックアップを通じてデザインの方向性を探索します。直接ブラウザで比較するためにデザイン質問ごとに2〜3つのバリアントを生成します。
+
+| 引数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `idea` | No | 探索する UI デザインの質問または方向性 |
+| `--quick` | No | ムード入力をスキップ; `idea` テキストを直接使用 |
+| `--text` | No | テキストモードのフォールバック — インタラクティブなプロンプトを番号付きリストに置き換え（Claude 以外のランタイム向け） |
+| `--wrap-up` | No | 採用されたスケッチの決定を再利用可能なプロジェクトローカルスキルにパッケージ化 |
+
+**生成物:** `.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]/` スキルファイル
+
+```bash
+/gsd-sketch # インタラクティブなムード入力
+/gsd-sketch "dashboard layout"
+/gsd-sketch --quick "sidebar navigation"
+/gsd-sketch --text "onboarding flow" # Claude 以外のランタイム
+/gsd-sketch --wrap-up # 採用されたスケッチをスキルにパッケージ化
+```
+
+---
+
## 診断コマンド
### `/gsd-forensics`
-失敗またはスタックしたGSDワークフローの事後調査。
+失敗した GSD ワークフローのポストモーテム調査 — 何が問題だったかを診断します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `description` | いいえ | 問題の説明（省略時はプロンプトで入力） |
+| `description` | No | 問題の説明（省略した場合はプロンプト） |
**前提条件:** `.planning/` ディレクトリが存在すること
**生成物:** `.planning/forensics/report-{timestamp}.md`
-**調査の対象:**
-- Git履歴分析（直近のコミット、スタックパターン、時間的ギャップ）
-- アーティファクトの整合性（完了フェーズで期待されるファイル）
-- STATE.mdの異常とセッション履歴
-- コミットされていない作業、コンフリクト、放棄された変更
-- 少なくとも4種類の異常をチェック（スタックループ、欠損アーティファクト、放棄された作業、クラッシュ/中断）
-- アクション可能な所見がある場合、GitHubイシューの作成を提案
+**調査対象:**
+- Git 履歴分析（最近のコミット、スタックパターン、時間的ギャップ）
+- アーティファクトの整合性（完了済みフェーズに期待されるファイル）
+- STATE.md の異常とセッション履歴
+- コミットされていない作業、競合、放棄された変更
+- 少なくとも4種類の異常をチェック（スタックループ、欠落アーティファクト、放棄された作業、クラッシュ/中断）
+- アクション可能な発見があれば GitHub Issue の作成を提案
```bash
-/gsd-forensics # 対話型 — 問題の入力を促す
+/gsd-forensics # インタラクティブ — 問題のプロンプト
/gsd-forensics "Phase 3 execution stalled" # 問題の説明付き
```
---
+### `/gsd-extract-learnings`
+
+完了したフェーズ作業から再利用可能なパターン、アンチパターン、およびアーキテクチャ上の決定を抽出します。
+
+| 引数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `N` | **Yes** | 学習を抽出するフェーズ番号 |
+
+| フラグ | 説明 |
+|------|-------------|
+| `--all` | 完了したすべてのフェーズから学習を抽出 |
+| `--format` | 出力フォーマット: `markdown`（デフォルト）、`json` |
+
+**前提条件:** フェーズが実行済みであること（SUMMARY.md ファイルが存在すること）
+**生成物:** `.planning/learnings/{phase}-LEARNINGS.md`
+
+**抽出内容:**
+- アーキテクチャ上の決定とその根拠
+- うまくいったパターン（将来のフェーズで再利用可能）
+- 遭遇したアンチパターンとその解決方法
+- 技術固有の洞察
+- パフォーマンスとテストの観察
+
+```bash
+/gsd-extract-learnings 3 # フェーズ3から学習を抽出
+/gsd-extract-learnings --all # 完了したすべてのフェーズから抽出
+```
+
+---
+
## ワークストリーム管理
### `/gsd-workstreams`
-マイルストーンの異なる領域で並行作業するためのワークストリームを管理します。
+異なるマイルストーン領域での並行作業のための並列ワークストリームを管理します。
**サブコマンド:**
| サブコマンド | 説明 |
|------------|-------------|
-| `list` | すべてのワークストリームをステータス付きで一覧表示（サブコマンド未指定時のデフォルト） |
+| `list` | ステータス付きですべてのワークストリームを一覧表示（サブコマンドなしの場合のデフォルト） |
| `create ` | 新しいワークストリームを作成 |
-| `status ` | 1つのワークストリームの詳細ステータス |
+| `status ` | 1つのワークストリームの詳細なステータス |
| `switch ` | アクティブなワークストリームを設定 |
-| `progress` | 全ワークストリームの進捗サマリー |
+| `progress` | すべてのワークストリームの進捗サマリー |
| `complete ` | 完了したワークストリームをアーカイブ |
-| `resume ` | ワークストリームでの作業を再開 |
+| `resume ` | ワークストリームの作業を再開 |
-**前提条件:** アクティブなGSDプロジェクト
+**前提条件:** アクティブな GSD プロジェクト
**生成物:** `.planning/` 配下のワークストリームディレクトリ、ワークストリームごとの状態追跡
```bash
/gsd-workstreams # すべてのワークストリームを一覧表示
/gsd-workstreams create backend-api # 新しいワークストリームを作成
/gsd-workstreams switch backend-api # アクティブなワークストリームを設定
-/gsd-workstreams status backend-api # 詳細ステータス
-/gsd-workstreams progress # ワークストリーム横断の進捗概要
+/gsd-workstreams status backend-api # 詳細なステータス
+/gsd-workstreams progress # クロスワークストリームの進捗概要
/gsd-workstreams complete backend-api # 完了したワークストリームをアーカイブ
-/gsd-workstreams resume backend-api # ワークストリームでの作業を再開
+/gsd-workstreams resume backend-api # ワークストリームの作業を再開
```
---
@@ -738,23 +954,73 @@ Claude Codeのセッション分析から8つの次元（コミュニケーシ
### `/gsd-settings`
-ワークフロートグルとモデルプロファイルの対話的な設定。
+ワークフローのトグルとモデルプロファイルのインタラクティブな設定。質問は6つの視覚的なセクションにグループ化されています:
+
+- **計画** — リサーチ、プランチェッカー、パターンマッパー、Nyquist、UI フェーズ、UI ゲート、AI フェーズ
+- **実行** — 検証者、TDD モード、コードレビュー、コードレビューの深さ _（条件付き — コードレビューがオンの場合のみ）_、UI レビュー
+- **ドキュメントと出力** — コミットドキュメント、議論スキップ、ワークツリー
+- **機能** — インテル、Graphify
+- **モデルとパイプライン** — モデルプロファイル、自動進行、ブランチング
+- **その他** — コンテキスト警告、リサーチ Q
+
+すべての回答は `gsd-tools query config-set` を介して解決されたプロジェクト設定パス（標準インストールでは `.planning/config.json`、ワークストリームがアクティブな場合は `.planning/workstreams//config.json`）にマージされ、関係のないキーを保持します。確認後、ユーザーは完全な設定オブジェクトを `~/.gsd/defaults.json` に保存でき、将来の `/gsd-new-project` 実行が同じベースラインから開始されます。
```bash
-/gsd-settings # 対話型設定
+/gsd-settings # インタラクティブな設定
```
-### `/gsd-config --profile`
+### `/gsd-config`
-クイックプロファイル切り替え。
+単一の統合コマンドで GSD 設定をインタラクティブに設定 — ワークフロートグル、高度なノブ、インテグレーション、モデルプロファイル。
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `profile` | **はい** | `quality`、`balanced`、`budget`、または `inherit` |
+| フラグ | 説明 |
+|------|-------------|
+| （なし） | 一般的なトグル: model、research、plan_check、verifier、branching |
+| `--advanced` | パワーユーザーノブ: 計画チューニング、タイムアウト、ブランチテンプレート、クロス AI 実行、ランタイム/出力 |
+| `--integrations` | サードパーティ API キー、コードレビュー CLI ルーティング、エージェントスキルインジェクション |
+| `--profile ` | クイックプロファイル切り替え: `quality`、`balanced`、`budget`、または `inherit` |
+
+**`--advanced` セクション:**
+
+| セクション | キー |
+|---------|------|
+| 計画チューニング | `workflow.plan_bounce`、`workflow.plan_bounce_passes`、`workflow.plan_bounce_script`、`workflow.subagent_timeout`、`workflow.inline_plan_threshold` |
+| 実行チューニング | `workflow.node_repair`、`workflow.node_repair_budget`、`workflow.auto_prune_state` |
+| 議論チューニング | `workflow.max_discuss_passes` |
+| クロス AI 実行 | `workflow.cross_ai_execution`、`workflow.cross_ai_command`、`workflow.cross_ai_timeout` |
+| Git カスタマイズ | `git.base_branch`、`git.phase_branch_template`、`git.milestone_branch_template` |
+| ランタイム / 出力 | `response_language`、`context_window`、`search_gitignored`、`graphify.build_timeout` |
+
+すべての回答は `gsd-tools query config-set` を介してマージされ、関係のないキーを保持します。API キーはすべての出力でマスクされます（`****`）。
```bash
-/gsd-config --profile budget # budgetプロファイルに切り替え
-/gsd-config --profile quality # qualityプロファイルに切り替え
+/gsd-config # 一般的なインタラクティブ設定
+/gsd-config --advanced # パワーユーザーノブ（6セクションプロンプト）
+/gsd-config --integrations # API キー、レビュー CLI ルーティング、エージェントスキル
+/gsd-config --profile budget # バジェットプロファイルに切り替え
+/gsd-config --profile quality # 品質プロファイルに切り替え
+```
+
+完全なスキーマとデフォルトについては [CONFIGURATION.md](../CONFIGURATION.md) を参照してください。
+
+### `/gsd-surface`
+
+再インストールなしにどのスキルを表示するかを切り替え — プロファイルを適用したり、クラスターを一覧表示または無効化したりします。
+
+| サブコマンド | 説明 |
+|------------|-------------|
+| `list` | 有効および無効なクラスターとスキルを表示 |
+| `status` | `list` のエイリアスにトークンコストサマリーを加えたもの |
+| `profile ` | `baseProfile` を書き込んでスキルを再ステージング |
+| `disable ` | クラスターを無効化リストに追加して再ステージング |
+| `enable ` | クラスターを無効化リストから削除して再ステージング |
+| `reset` | サーフェスデルタを削除; インストール時のプロファイルに戻す |
+
+```bash
+/gsd-surface list # 現在のサーフェスを表示
+/gsd-surface profile standard # スタンダードプロファイルに切り替え
+/gsd-surface disable utility # ユーティリティクラスターを無効化
+/gsd-surface reset # インストール時のプロファイルを復元
```
---
@@ -763,50 +1029,180 @@ Claude Codeのセッション分析から8つの次元（コミュニケーシ
### `/gsd-map-codebase`
-並列マッパーエージェントで既存のコードベースを分析します。
+並列マッパーエージェントで既存のコードベースを分析します。クイックな単一エージェントスキャンには `--fast` を、既存のインテルを検索するには `--query` を使用します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `area` | いいえ | マッピングを特定の領域にスコープ |
+| `area` | No | マッピングを特定のエリアにスコープ |
+| `--fast` | No | 高速な単一フォーカス評価 — 4つの並列エージェントの代わりに1つのマッパーエージェントを起動（軽量な代替手段） |
+| `--query ` | No | `.planning/intel/` 内のクエリ可能なコードベースインテルファイルを検索（`intel.enabled: true` が必要） |
+
+| フラグ | 説明 |
+|------|-------------|
+| `--focus tech\|arch\|quality\|concerns\|tech+arch` | `--fast` モードのフォーカスエリア（デフォルト: `tech+arch`） |
+
+**生成物:** `.planning/codebase/` の分析ドキュメント（フルモード）; `.planning/codebase/` 内のターゲットドキュメント（`--fast`）; インテルクエリ結果（`--query`）
```bash
-/gsd-map-codebase # コードベース全体を分析
-/gsd-map-codebase auth # auth領域にフォーカス
+/gsd-map-codebase # 完全なコードベース分析（4つの並列エージェント）
+/gsd-map-codebase auth # 認証エリアにフォーカス
+/gsd-map-codebase --fast # クイックな tech + arch 概要（1エージェント）
+/gsd-map-codebase --fast --focus quality # 品質とコードヘルスのみ
+/gsd-map-codebase --query authentication # 認証のインテルを検索
+```
+
+### `/gsd-graphify`
+
+`.planning/graphs/` に保存されたプロジェクトナレッジグラフを構築、クエリ、検査します。`config.json` の `graphify.enabled: true` でオプトイン（[設定リファレンス](../CONFIGURATION.md#graphify-settings) を参照）; 無効な場合、コマンドはアクティベーションヒントを表示して停止します。
+
+| サブコマンド | 説明 |
+|------------|-------------|
+| `build` | ナレッジグラフを構築または再構築（`graphify update .` をインラインで実行し、`.planning/graphs/` を更新） |
+| `query ` | グラフでキーワードを検索 |
+| `status` | グラフの鮮度と統計を表示 |
+| `diff` | 最後のビルド以降の変更を表示 |
+
+**生成物:** `.planning/graphs/` のグラフアーティファクト（ノード、エッジ、スナップショット）
+
+```bash
+/gsd-graphify build # ナレッジグラフを構築または再構築
+/gsd-graphify query authentication # グラフで認証を検索
+/gsd-graphify status # 鮮度と統計を表示
+/gsd-graphify diff # 最後のビルド以降の変更を表示
+```
+
+**プログラムアクセス:** `node gsd-tools.cjs graphify ` — [CLI ツールリファレンス](../CLI-TOOLS.md) を参照してください。
+
+### `gsd-tools intel api-surface`
+
+`/gsd-map-codebase` が構築した `.planning/intel/api-map.json` インデックスを `.planning/intel/` の人間が読めるフォーマットの `API-SURFACE.md` にレンダリングします。`config.json` の `intel.enabled: true` でゲート; インテルが無効な場合、コマンドはアクティベーションヒントを表示して終了します。出力パスは常に `.planning/intel/API-SURFACE.md` です — `--out` や `--format` フラグはありません。`api-map.json` が存在しないか空の場合でも、コマンドは明示的な「incomplete」バナー付きのファイルを書き込むため、コンシューマーが「何も存在しない」と勘違いすることはありません。
+
+**生成物:** `.planning/intel/API-SURFACE.md`
+
+```bash
+node gsd-tools.cjs intel api-surface # api-map.json → API-SURFACE.md にレンダリング
+```
+
+`API-SURFACE.md` の出力は、シグネチャと検出された可視性付きでソースファイルごとにグループ化された公開シンボル（関数、クラス、デコレーター、定数）を一覧表示します。`plan_review.source_grounding_authority` が `intel` に設定されている場合、プランドリフトガードは `api-surface` レンダラーを呼び出すのではなく、`api-map.json` を直接読み込みます。
+
+---
+
+## AI インテグレーションコマンド
+
+### `/gsd-ai-integration-phase`
+
+AI システムの構築を含むフェーズの AI-SPEC.md デザインコントラクトを生成します。インタラクティブな意思決定マトリクスを提示し、ドメイン固有の失敗モードと評価基準を表示し、フレームワークの推奨事項、実装ガイダンス、および評価戦略を含む `AI-SPEC.md` を生成します。
+
+**生成物:** フェーズディレクトリ内の `{phase}-AI-SPEC.md`
+
+**起動:** 3つの並列スペシャリストエージェント: domain-researcher、framework-selector、ai-researcher、および eval-planner
+
+```bash
+/gsd-ai-integration-phase # 現在のフェーズのウィザード
+/gsd-ai-integration-phase 3 # 特定のフェーズのウィザード
```
---
-## アップデートコマンド
+### `/gsd-eval-review`
+
+実行済み AI フェーズの評価カバレッジを監査し、EVAL-REVIEW.md の改善計画を作成します。`/gsd-ai-integration-phase` が生成した `AI-SPEC.md` 評価計画に対して実装をチェックします。各評価次元を COVERED/PARTIAL/MISSING でスコアリングします。
+
+**前提条件:** フェーズが実行済みで `AI-SPEC.md` があること
+**生成物:** 発見事項、ギャップ、改善ガイダンスを含む `{phase}-EVAL-REVIEW.md`
+
+```bash
+/gsd-eval-review # 現在のフェーズを監査
+/gsd-eval-review 3 # 特定のフェーズを監査
+```
+
+---
+
+## 更新コマンド
### `/gsd-update`
-変更履歴のプレビュー付きでGSDをアップデートします。
+変更ログのプレビュー付きで GSD を更新し、オプションでスキルを同期したりローカルパッチを再適用したりします。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--sync` | 更新後に GSD レジストリからスキルを同期 |
+| `--reapply` | 更新後にローカルの変更（パッチ）を復元 |
```bash
-/gsd-update # アップデートを確認してインストール
-```
-
-### `/gsd-update --reapply`
-
-GSDアップデート後にローカルの変更を復元します。
-
-```bash
-/gsd-update --reapply # ローカルの変更をマージバック
+/gsd-update # 更新を確認してインストール
+/gsd-update --sync # 更新してスキルを同期
+/gsd-update --reapply # 更新してローカルパッチを再適用
```
---
-## 高速＆インラインコマンド
+## コード品質コマンド
-### `/gsd-fast`
+### `/gsd-code-review`
-簡単なタスクをインラインで実行 — サブエージェントなし、計画のオーバーヘッドなし。タイポ修正、設定変更、小さなリファクタリング、忘れたコミットなどに最適。
+バグ、セキュリティの脆弱性、コード品質の問題についてフェーズ中に変更されたソースファイルをレビューします。レビュー後に発見事項を自動修正するには `--fix` を使用します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `task description` | いいえ | 実行する内容（省略時はプロンプトで入力） |
+| `N` | **Yes** | レビューする変更のフェーズ番号（例: `2` または `02`） |
+| `--depth=quick\|standard\|deep` | No | レビューの深さレベル（`workflow.code_review_depth` 設定を上書き）。`quick`: パターンマッチングのみ（約2分）。`standard`: 言語固有のチェックを含むファイルごとの分析（約5〜15分、デフォルト）。`deep`: インポートグラフとコールチェーンを含むクロスファイル分析（約15〜30分） |
+| `--files file1,file2,...` | No | 明示的なカンマ区切りのファイルリスト; SUMMARY/git スコーピングを完全にスキップ |
+| `--fix` | No | レビュー後に問題を自動修正 — REVIEW.md を読み込み、修正エージェントを起動し、各修正をアトミックにコミット |
+| `--fix --all` | No | 修正スコープに Info の発見事項を含める（デフォルト: Critical + Warning のみ） |
+| `--fix --auto` | No | 修正 + 再レビューの繰り返しループ、最大3回の繰り返しで上限 |
-**`/gsd-quick` の代替ではありません** — 調査、複数ステップの計画、または検証が必要な場合は `/gsd-quick` を使用してください。
+**前提条件:** フェーズが実行済みで SUMMARY.md または git 履歴があること
+**生成物:** 重大度分類された発見事項を含む `{phase}-REVIEW.md`; `--fix` 使用時は `{phase}-REVIEW-FIX.md`
+**起動:** `gsd-code-reviewer` エージェント; `--fix` 使用時は `gsd-code-fixer` エージェント
+
+**オプションの構造的プレパス:** `code_quality.fallow.enabled` を `true` に設定すると、エージェントレビューの前に fallow を実行します。GSD は `{phase}/FALLOW.json` を書き込み、`REVIEW.md` に `Structural Findings (fallow)` セクションを埋め込みます。`code_quality.fallow.scope` と `code_quality.fallow.profile` でスコープとプロファイルを設定します。
+
+```bash
+/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回の繰り返し）
+```
+
+---
+
+### `/gsd-audit-fix`
+
+自律的な監査から修正へのパイプライン — 監査を実行し、発見事項を分類し、テスト検証付きで自動修正可能な問題を修正し、各修正をアトミックにコミットします。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--source ` | 実行する監査（デフォルト: `audit-uat`） |
+| `--severity high\|medium\|all` | 処理する最小重大度（デフォルト: `medium`） |
+| `--max N` | 修正する最大発見事項数（デフォルト: 5） |
+| `--dry-run` | 修正せずに発見事項を分類（分類テーブルを表示） |
+
+**前提条件:** 少なくとも1つのフェーズが UAT または検証付きで実行済みであること
+**生成物:** テスト検証付きの修正コミット; 分類レポート
+
+```bash
+/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件修正
+```
+
+---
+
+## 高速・インラインコマンド
+
+### `/gsd-fast`
+
+サブエージェントなし、計画のオーバーヘッドなしでインラインで些細なタスクを実行します。タイポ修正、設定変更、小さなリファクタリング、忘れたコミット向け。
+
+| 引数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `task description` | No | 何をするか（省略した場合はプロンプト） |
+
+**`/gsd-quick` の代替ではありません** — リサーチ、マルチステップ計画、または検証が必要なものには `/gsd-quick` を使用してください。
```bash
/gsd-fast "fix typo in README"
@@ -815,91 +1211,149 @@ GSDアップデート後にローカルの変更を復元します。
---
-## コード品質コマンド
-
### `/gsd-review`
-外部AI CLIからのフェーズプランのクロスAIピアレビュー。
+外部 AI CLI からのフェーズ計画のクロス AI ピアレビュー。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `--phase N` | **はい** | レビューするフェーズ番号 |
+| `--phase N` | **Yes** | レビューするフェーズ番号 |
| フラグ | 説明 |
|------|-------------|
-| `--gemini` | Gemini CLIレビューを含める |
-| `--claude` | Claude CLIレビューを含める（別セッション） |
-| `--codex` | Codex CLIレビューを含める |
-| `--coderabbit` | CodeRabbitレビューを含める |
-| `--opencode` | OpenCodeレビューを含める（GitHub Copilot経由） |
-| `--qwen` | Qwen Codeレビューを含める（Alibaba Qwenモデル） |
-| `--cursor` | Cursorエージェントレビューを含める |
-| `--agy` / `--antigravity` | Antigravity CLIレビューを含める（Google認証情報で無料） |
-| `--all` | 利用可能なすべてのCLIを含める |
+| `--gemini` | Gemini CLI レビューを含める |
+| `--claude` | Claude CLI レビューを含める（別のセッション） |
+| `--codex` | Codex CLI レビューを含める |
+| `--coderabbit` | CodeRabbit レビューを含める |
+| `--opencode` | OpenCode レビューを含める（GitHub Copilot 経由） |
+| `--qwen` | Qwen Code レビューを含める（Alibaba Qwen モデル） |
+| `--cursor` | Cursor エージェントレビューを含める |
+| `--agy` / `--antigravity` | Antigravity CLI レビューを含める（Google 認証情報で無料） |
+| `--ollama` | Ollama サーバーレビューを含める |
+| `--lm-studio` | LM Studio サーバーレビューを含める |
+| `--llama-cpp` | llama.cpp サーバーレビューを含める |
+| `--all` | 利用可能なすべてのレビュアーを含める（CLI + ローカルモデルサーバー） |
-**生成物:** `{phase}-REVIEWS.md` — `/gsd-plan-phase --reviews` で利用可能
+**デフォルトレビュアーの動作（フラグなし）:**
+- `review.default_reviewers` が**未設定**の場合、`/gsd-review` は検出されたすべてのレビュアーを実行します（現在のデフォルト動作）。
+- `review.default_reviewers` が**設定済み**の場合、`/gsd-review` はそのサブセットのみを実行します（例: `["gemini","codex"]`）。
+- `--all` は常に設定を上書きし、完全な検出セットを実行します。
+- 明示的なフラグ（例: `--cursor`）は、そのランの `--all` と設定デフォルトの両方を上書きします。
+
+**生成物:** `{phase}-REVIEWS.md` — `/gsd-plan-phase --reviews` が消費可能
```bash
+# フラグなしの /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 # ワンオフの上書き
```
---
### `/gsd-pr-branch`
-`.planning/` のコミットをフィルタリングしてクリーンなPRブランチを作成します。
+`.planning/` コミットをフィルタリングしてクリーンな PR ブランチを作成します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `target branch` | いいえ | ベースブランチ（デフォルト: `main`） |
+| `target branch` | No | ベースブランチ（デフォルト: `main`） |
-**目的:** レビュアーにはコード変更のみを表示し、GSD計画アーティファクトは含めません。
+**目的:** レビュアーにはコード変更のみが表示され、GSD 計画アーティファクトは表示されません。
```bash
-/gsd-pr-branch # mainに対してフィルタリング
-/gsd-pr-branch develop # developに対してフィルタリング
+/gsd-pr-branch # main に対してフィルタリング
+/gsd-pr-branch develop # develop に対してフィルタリング
```
---
-### `/gsd-audit-uat`
+### `/gsd-secure-phase`
-全フェーズを横断した未処理のUATおよび検証項目の監査。
+完了したフェーズの脅威緩和を遡及的に検証します。
-**前提条件:** 少なくとも1つのフェーズがUATまたは検証付きで実行されていること
-**生成物:** カテゴリ分類された監査レポートと人間用テストプラン
+| 引数 | 必須 | 説明 |
+|----------|----------|-------------|
+| `phase number` | No | 監査するフェーズ（デフォルト: 最後に完了したフェーズ） |
+
+**前提条件:** フェーズが実行済みであること。既存の SECURITY.md があってもなくても動作。
+**生成物:** 脅威検証結果を含む `{phase}-SECURITY.md`
+**起動:** `gsd-security-auditor` エージェント
+
+3つの動作モード:
+1. SECURITY.md が存在する — 既存の緩和策を監査して検証
+2. SECURITY.md はないが PLAN.md に脅威モデルがある — アーティファクトから生成
+3. フェーズが実行されていない — ガイダンスと共に終了
```bash
-/gsd-audit-uat
+/gsd-secure-phase # 最後に完了したフェーズを監査
+/gsd-secure-phase 5 # 特定のフェーズを監査
```
---
-## バックログ＆スレッドコマンド
+### `/gsd-docs-update`
-### `/gsd-capture --backlog`
-
-999.x番号付けを使用して、バックログのパーキングロットにアイデアを追加します。
+コードベースに対して検証されたプロジェクトドキュメントを生成または更新します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| `description` | **はい** | バックログ項目の説明 |
+| `--force` | No | 保存プロンプトをスキップし、すべてのドキュメントを再生成 |
+| `--verify-only` | No | 既存のドキュメントの正確性を確認し、生成は行わない |
-**999.x番号付け**により、バックログ項目はアクティブなフェーズシーケンスの外に保持されます。フェーズディレクトリは即座に作成されるため、`/gsd-discuss-phase` や `/gsd-plan-phase` がそれらに対して動作します。
+**生成物:** 最大9つのドキュメントファイル（README、アーキテクチャ、API、スタートガイド、開発、テスト、設定、デプロイメント、コントリビューティング）
+**起動:** `gsd-doc-writer` エージェント（ドキュメントタイプごとに1つ）、次に `gsd-doc-verifier` エージェント（事実確認）
+
+各ドキュメントライターはコードベースを直接探索します — 幻覚されたパスや古いシグネチャはありません。ドキュメント検証者はライブファイルシステムに対してクレームを確認します。
```bash
-/gsd-capture --backlog "GraphQL API layer"
-/gsd-capture --backlog "Mobile responsive redesign"
+/gsd-docs-update # インタラクティブにドキュメントを生成/更新
+/gsd-docs-update --force # すべてのドキュメントを再生成
+/gsd-docs-update --verify-only # 既存のドキュメントのみを検証
+```
+
+---
+
+## タスクキャプチャとバックログコマンド
+
+### `/gsd-capture`
+
+アイデア、タスク、メモ、シードを適切な宛先にキャプチャします。デフォルトモードは後の作業用に構造化された todo を追加します; フラグは特化したキャプチャワークフローにルーティングします。
+
+| フラグ | 説明 |
+|------|-------------|
+| （なし） | 後の作業のための構造化された todo としてキャプチャ |
+| `--note [text]` | ゼロフリクションノート — 追加、一覧表示（`--note list`）、またはプロモート（`--note promote N`） |
+| `--backlog ` | 999.x 番号付けを使用してバックログパーキングロットに追加 |
+| `--seed [idea summary]` | トリガー条件付きで前向きなアイデアをキャプチャ |
+| `--list` | 保留中の todo を一覧表示して作業するものを選択 |
+| `--global` | グローバルスコープを使用（ノート操作に対して） |
+
+**バックログ:** 999.x 番号付けはアクティブなフェーズシーケンスの外にアイテムを保持します; フェーズディレクトリはすぐに作成されるため、`/gsd-discuss-phase` と `/gsd-plan-phase` がそれらに対して動作します。
+**シード:** 完全な WHY、WHEN（表示するタイミング）、およびパンくずを保持 — `/gsd-new-milestone` によって消費されます。
+
+**生成物:** `.planning/todos/`（デフォルト）、ノートファイル（--note）、ROADMAP.md バックログセクション（--backlog）、`.planning/seeds/SEED-NNN-slug.md`（--seed）
+
+```bash
+/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 # todo を参照してアクション
```
---
### `/gsd-review-backlog`
-バックログ項目をレビューし、アクティブなマイルストーンに昇格させます。
+バックログアイテムをレビューしてアクティブなマイルストーンにプロモートします。
-**項目ごとのアクション:** 昇格（アクティブシーケンスに移動）、保持（バックログに残す）、削除。
+**アイテムごとのアクション:** プロモート（アクティブシーケンスに移動）、保持（バックログに残す）、削除。
```bash
/gsd-review-backlog
@@ -907,44 +1361,161 @@ GSDアップデート後にローカルの変更を復元します。
---
-### `/gsd-capture --seed`
-
-トリガー条件付きの将来のアイデアをキャプチャ — 適切なマイルストーンで自動的に表面化します。
-
-| 引数 | 必須 | 説明 |
-|----------|----------|-------------|
-| `idea summary` | いいえ | シードの説明（省略時はプロンプトで入力） |
-
-シードはコンテキストの劣化を解決します：誰も読まないDeferredの一行メモの代わりに、シードは完全なWHY、いつ表面化すべきか、詳細への手がかりを保存します。
-
-**生成物:** `.planning/seeds/SEED-NNN-slug.md`
-**利用先:** `/gsd-new-milestone`（シードをスキャンしてマッチするものを提示）
-
-```bash
-/gsd-capture --seed "Add real-time collaboration when WebSocket infra is in place"
-```
-
----
-
### `/gsd-thread`
クロスセッション作業のための永続的なコンテキストスレッドを管理します。
| 引数 | 必須 | 説明 |
|----------|----------|-------------|
-| （なし） | — | すべてのスレッドを一覧表示 |
+| （なし） / `list` | — | すべてのスレッドを一覧表示 |
+| `list --open` | — | ステータスが `open` または `in_progress` のスレッドのみを一覧表示 |
+| `list --resolved` | — | ステータスが `resolved` のスレッドのみを一覧表示 |
+| `status ` | — | 特定のスレッドのステータスを表示 |
+| `close ` | — | スレッドを解決済みとしてマーク |
| `name` | — | 名前で既存のスレッドを再開 |
| `description` | — | 新しいスレッドを作成 |
-スレッドは、複数のセッションにまたがるが特定のフェーズに属さない作業のための軽量なクロスセッション知識ストアです。`/gsd-pause-work` よりも軽量です。
+スレッドは、複数のセッションにまたがるが特定のフェーズに属さない作業のための軽量なクロスセッションナレッジストアです。`/gsd-pause-work` よりも軽量です。
```bash
/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" # 新規作成
```
---
+## ロードマップ管理コマンド
+
+### `roadmap validate`
+
+マイルストーンプレフィックスの一貫性を含む構造的整合性のために ROADMAP.md を検証します。
+
+**前提条件:** `.planning/ROADMAP.md` が存在すること
+**生成物:** 検証レポート; エラーまたは警告がある場合は非ゼロで終了
+
+```bash
+node gsd-tools.cjs roadmap validate
+```
+
+---
+
+### `roadmap upgrade --convention milestone-prefixed`
+
+レガシーの `Phase N` ID をマイルストーンプレフィックス付きの `Phase M-NN` 規則に移行します。
+
+| フラグ | 必須 | 説明 |
+|------|----------|-------------|
+| `--convention milestone-prefixed` | Yes | 移行先のターゲット規則 |
+| `--apply` | No | 変更をディスクに書き込む（デフォルト: ドライランのみ） |
+
+**前提条件:** `.planning/ROADMAP.md` が存在すること
+**生成物:** ドライラン差分（デフォルト）または ROADMAP.md のインプレース書き換え（`--apply`）
+
+```bash
+node gsd-tools.cjs roadmap upgrade --convention milestone-prefixed # ドライラン
+node gsd-tools.cjs roadmap upgrade --convention milestone-prefixed --apply # 適用
+```
+
+---
+
+## 状態管理コマンド
+
+### `state validate`
+
+STATE.md と実際のファイルシステム間のドリフトを検出します。
+
+**前提条件:** `.planning/STATE.md` が存在すること
+**生成物:** STATE.md フィールドとファイルシステムの実態の間のドリフトを示す検証レポート
+
+```bash
+node gsd-tools.cjs state validate
+```
+
+---
+
+### `state sync [--verify]`
+
+ディスク上の実際のプロジェクト状態から STATE.md を再構築します。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--verify` | ドライランモード — 書き込みなしで提案された変更を表示 |
+
+**前提条件:** `.planning/` ディレクトリが存在すること
+**生成物:** ファイルシステムの実態を反映した更新された `STATE.md`
+
+```bash
+node gsd-tools.cjs state sync # ディスクから STATE.md を再構築
+node gsd-tools.cjs state sync --verify # ドライラン: 書き込みなしで変更を表示
+```
+
+---
+
+### `state planned-phase`
+
+plan-phase 完了後に状態遷移を記録します（Planned/Ready to execute）。
+
+| フラグ | 説明 |
+|------|-------------|
+| `--phase N` | 計画されたフェーズ番号 |
+| `--plans N` | 生成された計画の数 |
+
+**前提条件:** フェーズが計画済みであること
+**生成物:** 計画後の状態を含む更新された `STATE.md`
+
+```bash
+node gsd-tools.cjs state planned-phase --phase 3 --plans 2
+```
+
+---
+
## コミュニティコマンド
+### コミュニティフック
+
+`.planning/config.json` の `hooks.community: true` でゲートされたオプションの git およびセッションフック。明示的に有効にしない限りすべてノーオプです。
+
+| フック | 目的 |
+|------|---------|
+| `gsd-validate-commit.sh` | git コミットメッセージに Conventional Commits フォーマットを適用 |
+| `gsd-session-state.sh` | セッション状態の遷移を追跡 |
+| `gsd-phase-boundary.sh` | フェーズ境界チェックを適用 |
+
+有効にするには:
+```json
+{ "hooks": { "community": true } }
+```
+
+---
+
+### コミュニティへの参加
+
+GSD Discord コミュニティに参加するには、GSD README 内のリンクを訪問するか、`/gsd-help` を実行して表示される Discord リンクに従ってください。
+
+---
+
+## 貢献: スキル説明の標準
+
+スキル説明（各 `commands/gsd/*.md` フロントマターの `description:` フィールド）は、すべてのセッションのシステムプロンプトに注入されます。セッションごとのオーバーヘッドを低く保つために、説明は ≤ 100 文字でなければならず、`argument-hint:` に既に含まれるフラグのドキュメントを複製してはなりません。
+
+リントゲートで予算を適用します:
+
+```bash
+npm run lint:descriptions
+```
+
+このチェックは `tests/enh-2789-description-budget.test.cjs` を介して `npm test` の一部としても実行されます。
+
+---
+
+## Related
+
+- [Configuration Reference](../CONFIGURATION.md)
+- [CLI Tools Reference](../CLI-TOOLS.md)
+- [Feature Reference](../FEATURES.md)
+- [Docs index](../README.md)
diff --git a/docs/ja-JP/FEATURES.md b/docs/ja-JP/FEATURES.md
index 2902bc756..eda9783a7 100644
--- a/docs/ja-JP/FEATURES.md
+++ b/docs/ja-JP/FEATURES.md
@@ -102,6 +102,68 @@
- [レスポンス言語設定](#83-レスポンス言語設定)
- [手動アップデート手順](#84-手動アップデート手順)
- [新規ランタイムサポート (Trae, Cline, Augment Code)](#85-新規ランタイムサポート-trae-cline-augment-code)
+ - [自律モード `--interactive` フラグ](#86-自律モード---interactive-フラグ)
+ - [コミットドキュメントガードフック](#87-コミットドキュメントガードフック)
+ - [コミュニティフックオプトイン](#88-コミュニティフックオプトイン)
+- [v1.34.0 の機能](#v1340-の機能)
+ - [グローバル学習ストア](#89-グローバル学習ストア)
+ - [クエリ可能コードベースインテリジェンス](#90-クエリ可能コードベースインテリジェンス)
+ - [実行コンテキストプロファイル](#91-実行コンテキストプロファイル)
+ - [ゲート分類法](#92-ゲート分類法)
+ - [コードレビューパイプライン](#93-コードレビューパイプライン)
+ - [ソクラテス的探索](#94-ソクラテス的探索)
+ - [セーフアンドゥ](#95-セーフアンドゥ)
+ - [プランインポート](#96-プランインポート)
+ - [高速コードベーススキャン](#97-高速コードベーススキャン)
+ - [自律監査から修正](#98-自律監査から修正)
+ - [改善されたプロンプトインジェクションスキャナー](#99-改善されたプロンプトインジェクションスキャナー)
+ - [プランフェーズのストール検出](#100-プランフェーズのストール検出)
+ - [/gsd-progress --next のハードストップ安全ゲート](#101-gsd-progress---next-のハードストップ安全ゲート)
+ - [アダプティブモデルプリセット](#102-アダプティブモデルプリセット)
+ - [ポストマージハンク検証](#103-ポストマージハンク検証)
+- [v1.35.0 の機能](#v1350-の機能)
+ - [新規ランタイムサポート (Cline, CodeBuddy, Qwen Code)](#104-新規ランタイムサポート-cline-codebuddy-qwen-code)
+ - [GSD-2 逆マイグレーション](#105-gsd-2-逆マイグレーション)
+ - [AI 統合フェーズウィザード](#106-ai-統合フェーズウィザード)
+ - [AI 評価レビュー](#107-ai-評価レビュー)
+- [v1.36.0 の機能](#v1360-の機能)
+ - [プランバウンス](#108-プランバウンス)
+ - [外部コードレビューコマンド](#109-外部コードレビューコマンド)
+ - [クロス AI 実行デリゲーション](#110-クロス-ai-実行デリゲーション)
+ - [アーキテクチャ責任マッピング](#111-アーキテクチャ責任マッピング)
+ - [学習の抽出](#112-学習の抽出)
+ - [コンテキストウィンドウ対応プロンプト薄化](#114-コンテキストウィンドウ対応プロンプト薄化)
+ - [設定可能な CLAUDE.md パス](#115-設定可能な-claudemd-パス)
+ - [TDD パイプラインモード](#116-tdd-パイプラインモード)
+- [v1.37.0 の機能](#v1370-の機能)
+ - [スパイクコマンド](#117-スパイクコマンド)
+ - [スケッチコマンド](#118-スケッチコマンド)
+ - [エージェントサイズ予算強制](#119-エージェントサイズ予算強制)
+ - [共有ボイラープレート抽出](#120-共有ボイラープレート抽出)
+ - [ナレッジグラフ統合](#121-ナレッジグラフ統合)
+- [v1.40.0 の機能](#v1400-の機能)
+ - [スキルサーフェス統合](#122-スキルサーフェス統合)
+ - [ネームスペースメタスキル（2 段階ルーティング）](#123-ネームスペースメタスキル2-段階ルーティング)
+ - [コンテキストウィンドウ使用率ガード](#124-コンテキストウィンドウ使用率ガード)
+ - [フェーズライフサイクルステータス行リードサイド](#125-フェーズライフサイクルステータス行リードサイド)
+- [v1.41.0 の機能](#v1410-の機能)
+ - [フェーズタイプごとのモデル選択](#126-フェーズタイプごとのモデル選択)
+ - [失敗ティアエスカレーション付き動的ルーティング](#127-失敗ティアエスカレーション付き動的ルーティング)
+ - [アップデートバナーオプトイン](#128-アップデートバナーオプトイン)
+ - [issue-driven-orchestration ガイド](#129-issue-driven-orchestration-ガイド)
+ - [グラファイファイコミットベースの古さ検出](#130-グラファイファイコミットベースの古さ検出)
+- [v1.42.1 の機能](#v1421-の機能)
+ - [パッケージ正当性ゲート](#132-パッケージ正当性ゲート)
+ - [スキルサーフェス予算](#133-スキルサーフェス予算)
+ - [インストーラーマイグレーション](#134-インストーラーマイグレーション)
+ - [カスタムシップ PR ボディセクション](#135-カスタムシップ-pr-ボディセクション)
+ - [レビューデフォルトレビュアー](#136-レビューデフォルトレビュアー)
+ - [ファロー構造レビュープリパス](#137-ファロー構造レビュープリパス)
+ - [フェーズ終了時の人間検証モード](#138-フェーズ終了時の人間検証モード)
+ - [クォータとレート制限の失敗分類](#139-クォータとレート制限の失敗分類)
+ - [ステータス行コンテキスト位置](#140-ステータス行コンテキスト位置)
+ - [マイルストーンタグ作成トグル](#141-マイルストーンタグ作成トグル)
+ - [構造化 JSON エラーモード](#142-構造化-json-エラーモード)
---
@@ -166,6 +228,8 @@
- REQ-DISC-05: システムは推奨デフォルトを自動選択する `--auto` フラグをサポートしなければならない
- REQ-DISC-06: システムはグループ化された質問取り込みのための `--batch` フラグをサポートしなければならない
- REQ-DISC-07: システムはグレーゾーンを特定する前に関連ソースファイルをスカウトしなければならない（コード認識型ディスカッション）
+- REQ-DISC-08: USER-PROFILE.md が非技術的なオーナーを示す場合（learning_style: guided、frustration_triggers にジャーゴン、または高レベルの説明深度）、システムはグレーエリアの言語を製品アウトカム用語に適応しなければならない
+- REQ-DISC-09: REQ-DISC-08 が適用される場合、advisor_research の根拠段落は平易な言語で書き直されなければならない — 同じ決定、翻訳されたフレーミング
**生成物:** `{padded_phase}-CONTEXT.md` — リサーチとプランニングに反映されるユーザーの要望
@@ -335,6 +399,7 @@
- REQ-SHIP-03: システムは SUMMARY.md、VERIFICATION.md、REQUIREMENTS.md から PR 本文を自動生成しなければならない
- REQ-SHIP-04: システムは STATE.md をシッピングステータスと PR 番号で更新しなければならない
- REQ-SHIP-05: システムはドラフト PR のための `--draft` フラグをサポートしなければならない
+- REQ-SHIP-06: システムは `ship.pr_body_sections` で設定された追記専用プロジェクト PR ボディセクションをサポートしなければならない
**前提条件:** フェーズ検証済み、`gh` CLI がインストール・認証済み、フィーチャーブランチで作業中
@@ -736,6 +801,36 @@
| `TESTING.md` | テストインフラ、カバレッジ、パターン |
| `INTEGRATIONS.md` | 外部サービス、API、サードパーティ依存関係 |
+**増分リマップ — `--paths` (#2003):** マッパーはオプションの
+`--paths ` スコープヒントを受け付けます。指定した場合、ツリー全体をスキャンする代わりに、リストされたリポジトリ相対プレフィックスに探索を制限します。
+これはフェーズが実際に変更したサブツリーのみを更新するために、実行後コードベースドリフトゲートが使用するパスウェイです。各生成ドキュメントはその YAML フロントマターに `last_mapped_commit` を持ち、ドリフトを HEAD ではなくマッピング時点と照らし合わせて計測できます。
+
+### 27a. 実行後コードベースドリフト検出
+
+**導入:** #2003
+**トリガー:** すべての `/gsd-execute-phase` 終了時に自動実行
+**設定:**
+- `workflow.drift_threshold`（整数、デフォルト `3`）— ゲートが動作するまでに必要な最小新規構造要素数。
+- `workflow.drift_action`（`warn` | `auto-remap`、デフォルト `warn`）—
+ 警告のみ、または影響を受けたサブツリーにスコープした `--paths` で `gsd-codebase-mapper` をスポーン。
+
+**ドリフトとしてカウントされるもの:**
+- マッピングされたパス外の新規ディレクトリ
+- `(packages|apps)/*/src/index.*` の新規バレルエクスポート
+- 新規マイグレーションファイル（supabase/prisma/drizzle/src/migrations/…）
+- `routes/` または `api/` 下の新規ルートモジュール
+
+**非ブロッキング保証:** 内部障害（STRUCTURE.md の欠如、git エラー、マッパースポーン失敗）は
+1 行をログに記録し、フェーズは継続します。ドリフト検出が検証を失敗させることはありません。
+
+**要件:**
+- REQ-DRIFT-01: システムは `git diff --name-status last_mapped_commit..HEAD` から 4 つのドリフトカテゴリを検出しなければならない
+- REQ-DRIFT-02: アクションは要素数が `workflow.drift_threshold` 以上の場合のみ発動する
+- REQ-DRIFT-03: `warn` アクションはエージェントをスポーンしてはならない
+- REQ-DRIFT-04: `auto-remap` アクションはサニタイズされた `--paths` をマッパーに渡さなければならない
+- REQ-DRIFT-05: 検出/リマップの失敗は `/gsd-execute-phase` に対して非ブロッキングでなければならない
+- REQ-DRIFT-06: `last_mapped_commit` は各 `.planning/codebase/*.md` ファイルの YAML フロントマターを通じてラウンドトリップしなければならない
+
---
## ユーティリティ機能
@@ -925,6 +1020,7 @@ fix(03-01): correct auth token expiry
- REQ-HOOK-05: すべてのフックは3秒の stdin タイムアウトガードを含まなければならない
- REQ-HOOK-06: すべてのフックはエラー時にサイレントに失敗しなければならない
- REQ-HOOK-07: コンテキスト使用量は autocompact バッファ（16.5% リザーブ）に対して正規化されなければならない
+- REQ-HOOK-08: アップデートバナーはオプトインであり、アップデートが利用可能でない限りサイレントでなければならない（PR #2795）
**ステータスライン表示:**
```
@@ -1666,6 +1762,7 @@ Claude が GSD ワークフローコンテキスト外でファイル編集を
- REQ-CTXRED-01: システムはコンテキスト予算内に収まるよう、大きすぎる Markdown アーティファクトを切り詰めなければならない
- REQ-CTXRED-02: キャッシュフレンドリーなアセンブリのためにプロンプトを順序付けなければならない（安定したプレフィックスを先頭に）
- REQ-CTXRED-03: 削減は必須情報（見出し、要件、タスク構造）を保持しなければならない
+- REQ-CTXRED-04: スキルの `description:` フィールドは ≤ 100 文字でなければならない；`npm run lint:descriptions` で強制（`scripts/lint-descriptions.cjs` と `tests/enh-2789-description-budget.test.cjs` 参照）
**プロセス:**
1. **計測** — ワークフローの総プロンプトサイズを計算
@@ -1817,3 +1914,1077 @@ Claude が GSD ワークフローコンテキスト外でファイル編集を
- REQ-TRAE-01: インストーラーは Trae IDE インストールのための `--trae` フラグをサポートしなければならない
- REQ-CLINE-01: インストーラーは `.clinerules` 設定を通じて Cline をサポートしなければならない
- REQ-AUGMENT-01: インストーラーはスキル変換と設定管理で Augment Code をサポートしなければならない
+
+---
+
+### 86. 自律モード `--interactive` フラグ
+
+**フラグ:** `/gsd-autonomous --interactive`
+
+**目的:** ディスカスフェーズをインタラクティブ（ユーザーが質問に回答）に保ちながら、プランと実行をバックグラウンドエージェントとしてディスパッチするリーンコンテキスト自律モード。
+
+**要件:**
+- REQ-INTERACT-01: `--interactive` はインタラクティブな質問（自動回答なし）で discuss-phase をメインコンテキスト内でインラインに実行しなければならない
+- REQ-INTERACT-02: `--interactive` はコンテキスト分離のために plan-phase と execute-phase をバックグラウンドエージェントとしてディスパッチしなければならない
+- REQ-INTERACT-03: `--interactive` はパイプラインの並列性を有効にしなければならない — フェーズ N のビルド中にフェーズ N+1 をディスカス
+- REQ-INTERACT-04: メインコンテキストはディスカッション会話のみを蓄積しなければならない（リーンコンテキスト）
+
+**プロセス:**
+1. **インラインディスカス** — メインコンテキストでユーザーインタラクションとともに discuss-phase を実行
+2. **ディスパッチ** — プランと実行を新鮮なコンテキストウィンドウを持つバックグラウンドエージェントに送信
+3. **パイプライン** — バックグラウンドエージェントがフェーズ N をビルドする間、フェーズ N+1 のディスカッションを開始
+
+---
+
+### 87. コミットドキュメントガードフック
+
+**フック:** `gsd-commit-docs.js`
+
+**目的:** `commit_docs` 設定を強制する PreToolUse フックで、`planning.commit_docs` が `false` の場合に `.planning/` ファイルがコミットされることを防止します。
+
+**要件:**
+- REQ-COMMITDOCS-01: フックは `.planning/` ファイルをステージングする git commit コマンドを傍受しなければならない
+- REQ-COMMITDOCS-02: フックは `commit_docs` が `false` の場合に `.planning/` ファイルを含むコミットをブロックしなければならない
+- REQ-COMMITDOCS-03: フックは勧告的でなければならない — `commit_docs` が `true` または不在の場合はブロックしない
+
+---
+
+### 88. コミュニティフックオプトイン
+
+**フック:** `gsd-validate-commit.sh`、`gsd-session-state.sh`、`gsd-phase-boundary.sh`
+
+**目的:** GSD プロジェクト向けのオプションの git およびセッションフックで、設定の `hooks.community: true` の背後にゲートされています。
+
+**要件:**
+- REQ-COMMUNITY-01: すべてのコミュニティフックは `.planning/config.json` の `hooks.community` が `true` でない限りノーオペレーションでなければならない
+- REQ-COMMUNITY-02: `gsd-validate-commit.sh` は git コミットメッセージに Conventional Commits 形式を強制しなければならない
+- REQ-COMMUNITY-03: `gsd-session-state.sh` はセッション状態遷移をトラッキングしなければならない
+- REQ-COMMUNITY-04: `gsd-phase-boundary.sh` はフェーズ境界チェックを強制しなければならない
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `hooks.community` | boolean | `false` | コミット検証、セッション状態、フェーズ境界のオプションコミュニティフックを有効化 |
+
+---
+
+## v1.34.0 機能
+
+ - [グローバル学習ストア](#89-グローバル学習ストア)
+ - [クエリ可能コードベースインテリジェンス](#90-クエリ可能コードベースインテリジェンス)
+ - [実行コンテキストプロファイル](#91-実行コンテキストプロファイル)
+ - [ゲート分類法](#92-ゲート分類法)
+ - [コードレビューパイプライン](#93-コードレビューパイプライン)
+ - [ソクラテス的探索](#94-ソクラテス的探索)
+ - [セーフアンドゥ](#95-セーフアンドゥ)
+ - [プランインポート](#96-プランインポート)
+ - [高速コードベーススキャン](#97-高速コードベーススキャン)
+ - [自律監査から修正](#98-自律監査から修正)
+ - [改善されたプロンプトインジェクションスキャナー](#99-改善されたプロンプトインジェクションスキャナー)
+ - [プランフェーズのストール検出](#100-プランフェーズのストール検出)
+ - [/gsd-progress --next のハードストップ安全ゲート](#101-gsd-progress---next-のハードストップ安全ゲート)
+ - [アダプティブモデルプリセット](#102-アダプティブモデルプリセット)
+ - [ポストマージハンク検証](#103-ポストマージハンク検証)
+
+---
+
+### 89. グローバル学習ストア
+
+**コマンド:** フェーズ完了時に自動トリガー；プランナーが消費
+**設定:** `features.global_learnings`
+
+**目的:** セッションを超えてプロジェクトをまたいだ学習をグローバルストアに永続化し、プランナーエージェントがプロジェクト履歴全体のパターンから学習できるようにします（現在のセッションだけでなく）。
+
+**要件:**
+- REQ-LEARN-01: 学習はフェーズ完了時に `.planning/` からグローバルストアに自動コピーされなければならない
+- REQ-LEARN-02: プランナーエージェントはスポーン時にインジェクションを通じて関連する学習を受け取らなければならない
+- REQ-LEARN-03: インジェクションはコンテキストの肥大化を避けるために `learnings.max_inject` でキャップされなければならない
+- REQ-LEARN-04: 機能は `features.global_learnings: true` によるオプトインでなければならない
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `features.global_learnings` | boolean | `false` | クロスプロジェクト学習パイプラインを有効化 |
+| `learnings.max_inject` | number | (システムデフォルト) | プランナーにインジェクトされる最大学習エントリ数 |
+
+---
+
+### 90. クエリ可能コードベースインテリジェンス
+
+**コマンド:** `/gsd-map-codebase --query [|status|diff|refresh]`
+**設定:** `intel.enabled`
+
+**目的:** コードベース構造、API サーフェス、依存関係グラフ、ファイルロール、アーキテクチャ決定のクエリ可能な JSON インデックスを `.planning/intel/` に維持します。コードベース全体を読み込まずにターゲット検索を可能にします。
+
+**要件:**
+- REQ-INTEL-01: インテルファイルは `.planning/intel/` に JSON として保存されなければならない
+- REQ-INTEL-02: `query` モードはすべてのインテルファイルをまたいで用語を検索し、ファイルごとに結果をグループ化しなければならない
+- REQ-INTEL-03: `status` モードは鮮度を報告しなければならない（FRESH/STALE、古さの閾値：24 時間）
+- REQ-INTEL-04: `diff` モードは現在のインテル状態を最後のスナップショットと比較しなければならない
+- REQ-INTEL-05: `refresh` モードはすべてのファイルを再構築するために intel-updater エージェントをスポーンしなければならない
+- REQ-INTEL-06: 機能は `intel.enabled: true` によるオプトインでなければならない
+
+**生成されるインテルファイル:**
+| ファイル | 内容 |
+|---------|------|
+| `stack.json` | テクノロジースタックと依存関係 |
+| `api-map.json` | エクスポートされた関数と API サーフェス |
+| `dependency-graph.json` | モジュール間の依存関係 |
+| `file-roles.json` | 各ソースファイルのロール分類 |
+| `arch-decisions.json` | 検出されたアーキテクチャ決定 |
+
+---
+
+### 91. 実行コンテキストプロファイル
+
+**設定:** `context_profile`
+
+**目的:** 特定の作業タイプに合わせて調整されたあらかじめ設定された実行コンテキスト（モード、モデル、ワークフロー設定）を選択します（個別設定を手動で調整せずに）。
+
+**要件:**
+- REQ-CTX-01: `dev` プロファイルは反復開発に最適化しなければならない（balanced モデル、plan_check 有効）
+- REQ-CTX-02: `research` プロファイルはリサーチ重視の作業に最適化しなければならない（高いモデルティア、research 有効）
+- REQ-CTX-03: `review` プロファイルはコードレビュー作業に最適化しなければならない（verifier と code_review 有効）
+
+**利用可能なプロファイル:** `dev`、`research`、`review`
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `context_profile` | string | (なし) | 実行コンテキストプリセット：`dev`、`research`、または `review` |
+
+---
+
+### 92. ゲート分類法
+
+**参照:** `get-shit-done/references/gates.md`
+**エージェント:** plan-checker、verifier
+
+**目的:** すべてのワークフロー決定ポイントを構造化する 4 つの正規ゲートタイプを定義し、plan-checker と verifier エージェントが一貫したゲートロジックを適用できるようにします。
+
+**ゲートタイプ:**
+| タイプ | 説明 |
+|--------|------|
+| **確認** | ユーザーが進行前に承認（例：ロードマップレビュー） |
+| **品質** | 自動化された品質チェックが通過しなければならない（例：プラン検証ループ） |
+| **安全** | 検出されたリスクまたはポリシー違反でのハードストップ |
+| **遷移** | フェーズまたはマイルストーン境界の確認 |
+
+**要件:**
+- REQ-GATES-01: plan-checker は各チェックポイントを 4 つのゲートタイプのいずれかに分類しなければならない
+- REQ-GATES-02: verifier はゲートタイプに適したゲートロジックを適用しなければならない
+- REQ-GATES-03: ハードストップ安全ゲートは `--auto` フラグでバイパスされてはならない
+
+---
+
+### 93. コードレビューパイプライン
+
+**コマンド:** `/gsd-code-review`、`/gsd-code-review --fix`
+
+**目的:** フェーズ中に変更されたソースファイルの構造化レビューで、各修正をアトミックにコミットする別の自動修正パスを伴います。
+
+**要件:**
+- REQ-REVIEW-01: `gsd-code-review` は SUMMARY.md と git diff フォールバックを使用してフェーズにファイルをスコープしなければならない
+- REQ-REVIEW-02: レビューは 3 つの深さレベルをサポートしなければならない：`quick`、`standard`、`deep`
+- REQ-REVIEW-03: 所見は重大度で分類されなければならない：Critical、Warning、Info
+- REQ-REVIEW-04: `gsd-code-review --fix` は REVIEW.md を読み込み、デフォルトで Critical および Warning の所見を修正しなければならない
+- REQ-REVIEW-05: 各修正は説明的なメッセージとともにアトミックにコミットされなければならない
+- REQ-REVIEW-06: `--auto` フラグは修正と再レビューの反復ループを有効にしなければならない（最大 3 回）
+- REQ-REVIEW-07: 機能は `workflow.code_review` 設定フラグでゲートされなければならない
+
+**設定:**
+| 設定 | 型 | デフォルト | 説明 |
+|------|-----|-----------|------|
+| `workflow.code_review` | boolean | `true` | コードレビューコマンドを有効化 |
+| `workflow.code_review_depth` | string | `standard` | デフォルトのレビュー深度：`quick`、`standard`、または `deep` |
+
+---
+
+### 94. ソクラテス的探索
+
+**コマンド:** `/gsd-explore [topic]`
+
+**目的:** プランにコミットする前にソクラテス的な問いかけを通じてアイデアの探索を開発者にガイドします。出力を適切な GSD アーティファクトにルーティングします：ノート、TODO、シード、リサーチクエスチョン、要件更新、または新規フェーズ。
+
+**要件:**
+- REQ-EXPLORE-01: 探索はソクラテス的な問いかけを使用しなければならない — ソリューションを提案する前に質問する
+- REQ-EXPLORE-02: セッションは出力を適切な GSD アーティファクトにルーティングするオプションを提供しなければならない
+- REQ-EXPLORE-03: オプションのトピック引数は最初の質問をプライムしなければならない
+- REQ-EXPLORE-04: 探索はオプションで技術的実現可能性のためにリサーチエージェントをスポーンしなければならない
+
+---
+
+### 95. セーフアンドゥ
+
+**コマンド:** `/gsd-undo --last N | --phase NN | --plan NN-MM`
+
+**目的:** フェーズマニフェストと git log を使用して GSD フェーズまたはプランのコミットを安全にロールバックし、依存関係チェックとリバート適用前のハード確認ゲートを伴います。
+
+**要件:**
+- REQ-UNDO-01: `--phase` モードはマニフェストと git log フォールバックを通じてフェーズのすべてのコミットを識別しなければならない
+- REQ-UNDO-02: `--plan` モードは特定のプランのすべてのコミットを識別しなければならない
+- REQ-UNDO-03: `--last N` モードはインタラクティブな選択のために最近の GSD コミットを表示しなければならない
+- REQ-UNDO-04: システムはリバート前に依存するフェーズ/プランをチェックしなければならない
+- REQ-UNDO-05: git revert が実行される前に確認ゲートを表示しなければならない
+
+---
+
+### 96. プランインポート
+
+**コマンド:** `/gsd-import --from `
+
+**目的:** 外部プランファイルを `PROJECT.md` 決定との競合検出とともに GSD プランニングシステムに取り込み、有効な GSD PLAN.md に変換して plan-checker で検証します。
+
+**要件:**
+- REQ-IMPORT-01: インポーターは外部プランと既存の PROJECT.md 決定間の競合を検出しなければならない
+- REQ-IMPORT-02: 検出されたすべての競合は書き込み前にユーザーに提示されなければならない
+- REQ-IMPORT-03: インポートされたプランは有効な GSD PLAN.md 形式として書き込まれなければならない
+- REQ-IMPORT-04: 書き込まれたプランは `gsd-plan-checker` 検証を通過しなければならない
+
+---
+
+### 97. 高速コードベーススキャン
+
+**コマンド:** `/gsd-map-codebase --fast [--focus tech|arch|quality|concerns]`
+
+**目的:** 1 つまたは 2 つの組み合わせたフォーカスエリアに対して単一のマッパーエージェントをスポーンする `/gsd-map-codebase` の軽量な代替手段で、4 つの並列エージェントのオーバーヘッドなしに `.planning/codebase/` にターゲット出力を生成します。
+
+**要件:**
+- REQ-SCAN-01: スキャンは（4 つの並列エージェントではなく）正確に 1 つのマッパーエージェントをスポーンしなければならない
+- REQ-SCAN-02: フォーカスエリアは次のいずれかでなければならない：`tech`、`arch`、`quality`、`concerns`、または組み合わせた `tech+arch` 省略形（デフォルト：`tech+arch`）；組み合わせフォーカスは 1 回のパスで両エリアをカバーする単一エージェントとして実行
+- REQ-SCAN-03: 出力は `/gsd-map-codebase` と同じ形式で `.planning/codebase/` に書き込まれなければならない
+
+---
+
+### 98. 自律監査から修正
+
+**コマンド:** `/gsd-audit-fix [--source ] [--severity high|medium|all] [--max N] [--dry-run]`
+
+**目的:** 監査を実行し、所見を自動修正可能と手動のみに分類し、テスト検証とアトミックコミットで自動修正可能な問題を自律的に修正するエンドツーエンドパイプライン。
+
+**要件:**
+- REQ-AUDITFIX-01: 所見は変更前に自動修正可能または手動のみとして分類されなければならない
+- REQ-AUDITFIX-02: 各修正はコミット前にテストで検証されなければならない
+- REQ-AUDITFIX-03: 各修正はアトミックにコミットされなければならない
+- REQ-AUDITFIX-04: `--dry-run` は修正を適用せずに分類テーブルを表示しなければならない
+- REQ-AUDITFIX-05: `--max N` は 1 回の実行で適用される修正数を制限しなければならない（デフォルト：5）
+
+---
+
+### 99. 改善されたプロンプトインジェクションスキャナー
+
+**フック:** `gsd-prompt-guard.js`
+**スクリプト:** `scripts/prompt-injection-scan.sh`
+
+**目的:** プランニングアーティファクト内のプロンプトインジェクション試みの検出を強化し、不可視 Unicode 文字検出、エンコードの難読化パターン、エントロピーベースの分析を追加します。
+
+**要件:**
+- REQ-SCAN-INJ-01: スキャナーは不可視 Unicode 文字（ゼロ幅スペース、ソフトハイフンなど）を検出しなければならない
+- REQ-SCAN-INJ-02: スキャナーはエンコードの難読化パターン（base64 エンコードされた命令、ホモグリフ）を検出しなければならない
+- REQ-SCAN-INJ-03: スキャナーは予期しない位置の高エントロピー文字列にフラグを立てるためにエントロピー分析を適用しなければならない
+- REQ-SCAN-INJ-04: スキャナーは勧告的のみでなければならない — 検出はログに記録されるが、ブロッキングではない
+
+---
+
+### 100. プランフェーズのストール検出
+
+**コマンド:** `/gsd-plan-phase`
+
+**目的:** プランナーの修正ループが停止した（複数のイテレーションにわたって同じ出力を生成している）ことを検出し、異なる戦略にエスカレートするか明確な診断で終了してサイクルを破ります。
+
+**要件:**
+- REQ-STALL-01: 修正ループは連続するイテレーション全体で同一のプラン出力を検出しなければならない
+- REQ-STALL-02: ストール検出時、システムは再試行前に戦略をエスカレートしなければならない
+- REQ-STALL-03: 最大ストール再試行数は制限されなければならない（既存の最大 3 イテレーションでキャップ）
+
+---
+
+### 101. /gsd-progress --next のハードストップ安全ゲート
+
+**コマンド:** `/gsd-progress --next`
+
+**目的:** 繰り返し同一ステップが検出された場合に自律チェーニングを中断するハードストップ安全ゲートと連続呼び出しガードを追加し、`/gsd-progress --next` の暴走ループを防止します。
+
+**要件:**
+- REQ-NEXT-GATE-01: `/gsd-progress --next` は連続した同一ステップ呼び出しをトラッキングしなければならない
+- REQ-NEXT-GATE-02: 同一ステップの繰り返し時、システムはユーザーにハードストップゲートを提示しなければならない
+- REQ-NEXT-GATE-03: ユーザーはハードストップゲートを通過して続行するために明示的に確認しなければならない
+
+---
+
+### 102. アダプティブモデルプリセット
+
+**設定:** `model_profile: "adaptive"`
+
+**目的:** すべてのエージェントに単一のティアを適用するのではなく、現在のエージェントのロールに基づいて適切なモデルティアを自動的に選択するロールベースのモデル割り当て。
+
+**要件:**
+- REQ-ADAPTIVE-01: `adaptive` プリセットはエージェントロールに基づいてモデルティアを割り当てなければならない（planner → quality ティア、executor → balanced ティアなど）
+- REQ-ADAPTIVE-02: `adaptive` は `/gsd-config --profile adaptive` で選択可能でなければならない
+
+---
+
+### 103. ポストマージハンク検証
+
+**コマンド:** `/gsd-update --reapply`
+
+**目的:** アップデート後のローカルパッチ適用後、すべてのハンクが実際に適用されたことを期待されるパッチ内容とライブファイルシステムを比較することで検証します。不完全なマージをサイレントに受け入れるのではなく、ドロップされたまたは部分的なハンクを即座に表示します。
+
+**要件:**
+- REQ-PATCH-VERIFY-01: reapply-patches はマージ後に各ハンクが適用されたことを検証しなければならない
+- REQ-PATCH-VERIFY-02: ドロップされたまたは部分的なハンクはファイルと行のコンテキストとともにユーザーに報告されなければならない
+- REQ-PATCH-VERIFY-03: 検証はパッチごとではなく、すべてのパッチが適用された後に実行されなければならない
+
+---
+
+## v1.35.0 機能
+
+- [新規ランタイムサポート (Cline, CodeBuddy, Qwen Code)](#104-新規ランタイムサポート-cline-codebuddy-qwen-code)
+- [GSD-2 逆マイグレーション](#105-gsd-2-逆マイグレーション)
+- [AI 統合フェーズウィザード](#106-ai-統合フェーズウィザード)
+- [AI 評価レビュー](#107-ai-評価レビュー)
+
+---
+
+### 104. 新規ランタイムサポート (Cline, CodeBuddy, Qwen Code)
+
+**対象:** `npx @opengsd/gsd-core`
+
+**目的:** Cline、CodeBuddy、Qwen Code ランタイムへの GSD インストールを拡張します。
+
+**要件:**
+- REQ-CLINE-02: Cline インストールは `.clinerules` を `~/.cline/`（グローバル）または `./.cline/`（ローカル）に書き込まなければならない。カスタムスラッシュコマンドなし — ルールベースの統合のみ。フラグ：`--cline`。
+- REQ-CODEBUDDY-01: CodeBuddy インストールはスキルを `~/.codebuddy/skills/gsd-*/SKILL.md` にデプロイしなければならない。フラグ：`--codebuddy`。
+- REQ-QWEN-01: Qwen Code インストールはスキルを `~/.qwen/skills/gsd-*/SKILL.md` にデプロイしなければならない（Claude Code 2.1.88+ で使用されるオープン標準に従う）。`QWEN_CONFIG_DIR` 環境変数はデフォルトパスをオーバーライドします。フラグ：`--qwen`。
+
+**ランタイムサマリー:**
+
+| ランタイム | インストール形式 | 設定パス | フラグ |
+|-----------|----------------|---------|-------|
+| Cline | `.clinerules` | `~/.cline/` または `./.cline/` | `--cline` |
+| CodeBuddy | スキル (`SKILL.md`) | `~/.codebuddy/skills/` | `--codebuddy` |
+| Qwen Code | スキル (`SKILL.md`) | `~/.qwen/skills/` | `--qwen` |
+
+---
+
+### 105. GSD-2 逆マイグレーション
+
+**コマンド:** `/gsd-import --from-gsd2 [--dry-run] [--force] [--path ]`
+
+**目的:** GSD-2 形式（Milestone→Slice→Task 階層の `.gsd/` ディレクトリ）のプロジェクトを v1 の `.planning/` 形式に移行し、すべての GSD v1 コマンドとの完全な互換性を復元します。
+
+**要件:**
+- REQ-FROM-GSD2-01: インポーターは指定または現在のディレクトリから `.gsd/` を読み込まなければならない
+- REQ-FROM-GSD2-02: Milestone→Slice 階層は連続したフェーズ番号に平坦化されなければならない（M001/S01→フェーズ 01、M001/S02→フェーズ 02、M002/S01→フェーズ 03 など）
+- REQ-FROM-GSD2-03: `--force` なしに既存の `.planning/` ディレクトリを上書きしないよう保護しなければならない
+- REQ-FROM-GSD2-04: `--dry-run` はファイルを書き込まずにすべての変更をプレビューしなければならない
+- REQ-FROM-GSD2-05: マイグレーションは `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md`、`STATE.md`、および連続したフェーズディレクトリを生成しなければならない
+
+**フラグ:**
+
+| フラグ | 説明 |
+|-------|------|
+| `--dry-run` | ファイルを書き込まずにマイグレーション出力をプレビュー |
+| `--force` | 既存の `.planning/` ディレクトリを上書き |
+| `--path ` | GSD-2 ルートディレクトリを指定 |
+
+---
+
+### 106. AI 統合フェーズウィザード
+
+**コマンド:** `/gsd-ai-integration-phase [N]`
+
+**目的:** プロジェクトフェーズで AI/LLM 機能の選択、統合、評価計画を開発者にガイドします。プランニングと検証に組み込まれる構造化された `AI-SPEC.md` を生成します。
+
+**要件:**
+- REQ-AISPEC-01: ウィザードはフレームワーク選択、モデル選択、統合アプローチをカバーするインタラクティブな決定マトリックスを提示しなければならない
+- REQ-AISPEC-02: システムはプロジェクトタイプに関連するドメイン固有の失敗モードと評価基準を表示しなければならない
+- REQ-AISPEC-03: システムは 3 つの並列専門家エージェントをスポーンしなければならない：domain-researcher、framework-selector、eval-planner
+- REQ-AISPEC-04: 出力はフレームワーク推奨、実装ガイダンス、評価戦略を含む `{phase}-AI-SPEC.md` を生成しなければならない
+
+**生成物:** フェーズディレクトリ内の `{phase}-AI-SPEC.md`
+
+---
+
+### 107. AI 評価レビュー
+
+**コマンド:** `/gsd-eval-review [N]`
+
+**目的:** 実行された AI フェーズの評価カバレッジを `AI-SPEC.md` プランと照合して遡及的に監査します。フェーズが閉じられる前に計画済みと実装済みの評価間のギャップを特定します。
+
+**要件:**
+- REQ-EVALREVIEW-01: レビューは指定されたフェーズから `AI-SPEC.md` を読み込まなければならない
+- REQ-EVALREVIEW-02: 各評価ディメンションは COVERED、PARTIAL、または MISSING としてスコアリングされなければならない
+- REQ-EVALREVIEW-03: 出力は所見、ギャップ説明、および修正ガイダンスを含まなければならない
+- REQ-EVALREVIEW-04: `EVAL-REVIEW.md` はフェーズディレクトリに書き込まれなければならない
+
+**生成物:** スコアリングされた評価ディメンション、ギャップ分析、修正ステップを含む `{phase}-EVAL-REVIEW.md`
+
+---
+
+## v1.36.0 機能
+
+### 108. プランバウンス
+
+**コマンド:** `/gsd-plan-phase N --bounce`
+
+**目的:** プランがチェッカーを通過した後、外部スクリプト（2 番目の AI、リンター、カスタムバリデーター）を通じてオプションで精製します。バウンスステップは各プランをバックアップし、スクリプトを実行し、結果の YAML フロントマターの整合性を検証し、プランチェッカーを再実行し、何か失敗した場合は元に戻します。
+
+**要件:**
+- REQ-BOUNCE-01: `--bounce` フラグまたは `workflow.plan_bounce: true` がステップを有効化；`--skip-bounce` は常に無効化
+- REQ-BOUNCE-02: `workflow.plan_bounce_script` は有効な実行ファイルを指していなければならない；スクリプトが見つからない場合は警告を生成してスキップ
+- REQ-BOUNCE-03: 各プランはスクリプト実行前に `*-PLAN.pre-bounce.md` にバックアップされる
+- REQ-BOUNCE-04: YAML フロントマターが壊れているまたはプランチェッカーが失敗したバウンスされたプランはバックアップから復元される
+- REQ-BOUNCE-05: `workflow.plan_bounce_passes`（デフォルト：2）はスクリプトが受け取る精製パス数を制御する
+
+**設定:** `workflow.plan_bounce`、`workflow.plan_bounce_script`、`workflow.plan_bounce_passes`
+
+---
+
+### 109. 外部コードレビューコマンド
+
+**コマンド:** `/gsd-ship`（強化版）
+
+**目的:** `/gsd-ship` の手動レビューステップの前に、設定されている場合は外部コードレビューコマンドを自動的に実行します。コマンドは stdin を通じて diff とフェーズコンテキストを受け取り、JSON verdict（`APPROVED` または `REVISE`）を返します。結果に関わらず既存の手動レビューフローにフォールスルーします。
+
+**要件:**
+- REQ-EXTREVIEW-01: `workflow.code_review_command` はコマンド文字列に設定されなければならない；null はスキップを意味する
+- REQ-EXTREVIEW-02: diff は `--stat` サマリーを含めて `BASE_BRANCH` に対して生成される
+- REQ-EXTREVIEW-03: レビュープロンプトは stdin を通じてパイプされる（シェルインターポレートされない）
+- REQ-EXTREVIEW-04: 120 秒タイムアウト；失敗時に stderr をキャプチャ
+- REQ-EXTREVIEW-05: `verdict`、`confidence`、`summary`、`issues` フィールドの JSON 出力をパース
+
+**設定:** `workflow.code_review_command`
+
+---
+
+### 110. クロス AI 実行デリゲーション
+
+**コマンド:** `/gsd-execute-phase N --cross-ai`
+
+**目的:** 個々のプランを実行のために外部 AI ランタイムにデリゲートします。フロントマターに `cross_ai: true` があるプラン（または `--cross-ai` 使用時はすべてのプラン）が stdin を通じて設定済みコマンドに送信されます。正常に処理されたプランは通常の executor キューから削除されます。
+
+**要件:**
+- REQ-CROSSAI-01: `--cross-ai` はすべてのプランをクロス AI に強制；`--no-cross-ai` は無効化
+- REQ-CROSSAI-02: `workflow.cross_ai_execution: true` とプランフロントマター `cross_ai: true` がプランごとのアクティベーションに必要
+- REQ-CROSSAI-03: タスクプロンプトはインジェクションを防ぐために stdin を通じてパイプされる
+- REQ-CROSSAI-04: ダーティなワーキングツリーは実行前に警告を生成する
+- REQ-CROSSAI-05: 失敗時、ユーザーは選択する：再試行、スキップ（通常の executor にフォールバック）、またはアボート
+
+**設定:** `workflow.cross_ai_execution`、`workflow.cross_ai_command`、`workflow.cross_ai_timeout`
+
+---
+
+### 111. アーキテクチャ責任マッピング
+
+**コマンド:** `/gsd-plan-phase`（強化されたリサーチステップ）
+
+**目的:** フェーズリサーチ中に、phase-researcher が各機能をそのアーキテクチャティアオーナー（ブラウザ、フロントエンドサーバー、API、CDN/スタティック、データベース）にマッピングします。プランナーはこのマップに対してタスクをクロスリファレンスし、plan-checker はディメンション 7c としてティアコンプライアンスを強制します。
+
+**要件:**
+- REQ-ARM-01: Phase researcher は RESEARCH.md にアーキテクチャ責任マップテーブルを生成しなければならない（ステップ 1.5）
+- REQ-ARM-02: プランナーはマップに対してタスクからティアへの割り当てをサニティチェックしなければならない
+- REQ-ARM-03: Plan checker はディメンション 7c としてティアコンプライアンスを検証しなければならない（一般的な不一致は WARNING、セキュリティに敏感なものは BLOCKER）
+
+**生成物:** `{phase}-RESEARCH.md` 内の `## Architectural Responsibility Map` セクション
+
+---
+
+### 112. 学習の抽出
+
+**コマンド:** `/gsd-extract-learnings N`
+
+**目的:** 完了したフェーズのアーティファクトから構造化された知識を抽出します。PLAN.md と SUMMARY.md（必須）および VERIFICATION.md、UAT.md、STATE.md（オプション）を読み込み、決定、教訓、パターン、驚きの 4 カテゴリの学習を生成します。オプションで `capture_thought` ツールを通じて各項目を外部ナレッジベースにキャプチャします。
+
+**要件:**
+- REQ-LEARN-01: PLAN.md と SUMMARY.md が必要；見つからない場合は明確なエラーで終了
+- REQ-LEARN-02: 各抽出された項目にはソース帰属（アーティファクトとセクション）が含まれる
+- REQ-LEARN-03: `capture_thought` ツールが利用可能な場合、`source`、`project`、`phase` メタデータとともに項目をキャプチャする
+- REQ-LEARN-04: `capture_thought` が利用不可の場合、正常に完了し、外部キャプチャがスキップされたことをログに記録する
+- REQ-LEARN-05: 2 回実行すると前の `LEARNINGS.md` が上書きされる
+
+**生成物:** YAML フロントマター（phase、project、カテゴリごとのカウント、missing_artifacts）を含む `{phase}-LEARNINGS.md`
+
+**オプション統合 — `capture_thought`:** `capture_thought` は**バンドルされたツールではなく、規約**です。GSD はそれを同梱せず、必須でもありません。ワークフローは現在のセッションの MCP サーバーが `capture_thought` という名前のツールを公開しているかどうかを確認し、公開している場合は以下のシグネチャで抽出した学習ごとに 1 回呼び出します。そのようなツールが存在しない場合、ステップはサイレントにスキップされ、`LEARNINGS.md` が主要な出力として残ります。
+
+期待されるツールシグネチャ：
+```javascript
+capture_thought({
+ category: "decision" | "lesson" | "pattern" | "surprise",
+ phase: ,
+ content: ,
+ source:
+})
+```
+
+メモリ / ナレッジベース MCP サーバー（例：ExoCortex スタイルのサーバー、`claude-mem`、または `mem0` スタイルのサーバー）を実行するユーザーは、このツール名を実装して、`project`、`phase`、`source` メタデータとともに学習を自動的にナレッジベースにルーティングできます。それ以外のユーザーは追加のセットアップなしに `/gsd-extract-learnings` を使用できます — `LEARNINGS.md` アーティファクトが機能です。
+
+---
+
+### 114. コンテキストウィンドウ対応プロンプト薄化
+
+**目的:** 200K トークン未満のコンテキストウィンドウを持つモデルのスタティックプロンプトオーバーヘッドを最大 40% 削減します。拡張例とアンチパターンリストがエージェント定義から `@` required_reading を通じてオンデマンドで読み込まれる参照ファイルに抽出されます。
+
+**要件:**
+- REQ-THIN-01: `CONTEXT_WINDOW < 200000` の場合、executor と planner のエージェントプロンプトはインライン例を省略する
+- REQ-THIN-02: 抽出されたコンテンツは `references/executor-examples.md` と `references/planner-antipatterns.md` に存在する
+- REQ-THIN-03: 標準（200K-500K）と拡張（500K+）ティアは影響を受けない
+- REQ-THIN-04: コアルールと決定ロジックはインラインのまま；詳細な例のみが抽出される
+
+**参照ファイル:** `executor-examples.md`、`planner-antipatterns.md`
+
+---
+
+### 115. 設定可能な CLAUDE.md パス
+
+**目的:** プロジェクトが CLAUDE.md をルート以外の場所に保存できるようにします。`claude_md_path` 設定キーは `/gsd-profile-user` および関連コマンドが生成された CLAUDE.md ファイルを書き込む場所を制御します。
+
+**要件:**
+- REQ-CMDPATH-01: `claude_md_path` はデフォルトで `./CLAUDE.md`
+- REQ-CMDPATH-02: プロファイル生成コマンドは設定からパスを読み込み、指定された場所に書き込む
+- REQ-CMDPATH-03: 相対パスはプロジェクトルートから解決される
+
+**設定:** `claude_md_path`
+
+---
+
+### 116. TDD パイプラインモード
+
+**目的:** オプトインの TDD（レッドグリーンリファクタリング）をファーストクラスのフェーズ実行モードとして提供します。有効にすると、プランナーは適切なタスクに対して積極的に `type: tdd` を選択し、executor は RED/GREEN/REFACTOR ゲートシーケンスを強制し、RED 前の予期しない GREEN でフェイルファストします。
+
+**要件:**
+- REQ-TDD-01: `workflow.tdd_mode` 設定キー（boolean、デフォルト `false`）
+- REQ-TDD-02: 有効時、プランナーは `references/tdd.md` の TDD ヒューリスティックをすべての適格なタスク（ビジネスロジック、API、バリデーション、アルゴリズム、ステートマシン）に適用する
+- REQ-TDD-03: Executor は `type: tdd` プランのゲートシーケンスを強制する — RED コミット（`test(...)`）は GREEN コミット（`feat(...)`）より先でなければならない
+- REQ-TDD-04: Executor は RED フェーズ中にテストが予期しなくパスした場合にフェイルファストする（機能がすでに存在するかテストが間違っている）
+- REQ-TDD-05: フェーズ終了時の協調レビューチェックポイントがすべての TDD プランにわたるゲートコンプライアンスを確認する（勧告的、非ブロッキング）
+- REQ-TDD-06: ゲート違反は SUMMARY.md の `## TDD Gate Compliance` セクション下に表示される
+
+**設定:** `workflow.tdd_mode`
+**参照ファイル:** `tdd.md`、`checkpoints.md`
+
+---
+
+## v1.37.0 機能
+
+### 117. スパイクコマンド
+
+**コマンド:** `/gsd-spike [idea] [--quick]`
+
+**目的:** 実装アプローチにコミットする前に 2〜5 つの焦点を絞った実現可能性実験を実行します。各実験は Given/When/Then フレーミングを使用し、実行可能なコードを生成し、VALIDATED / INVALIDATED / PARTIAL verdict を返します。コンパニオンの `/gsd-spike --wrap-up` は所見をプロジェクトローカルのスキルにパッケージ化します。
+
+**要件:**
+- REQ-SPIKE-01: 各実験はコードが書かれる前に Given/When/Then 仮説を生成しなければならない
+- REQ-SPIKE-02: 各実験は動作するコードまたは最小限の再現を含まなければならない
+- REQ-SPIKE-03: 各実験はエビデンスとともに VALIDATED、INVALIDATED、または PARTIAL verdict のいずれかを返さなければならない
+- REQ-SPIKE-04: 結果は `.planning/spikes/NNN-experiment-name/` に README と MANIFEST.md とともに保存されなければならない
+- REQ-SPIKE-05: `--quick` フラグはインテーク会話をスキップし、引数テキストを実験方向として使用する
+- REQ-SPIKE-06: `/gsd-spike --wrap-up` は所見を `.claude/skills/spike-findings-[project]/` にパッケージ化しなければならない
+
+**生成物:**
+
+| アーティファクト | 説明 |
+|---------------|------|
+| `.planning/spikes/NNN-name/README.md` | 仮説、実験コード、verdict、エビデンス |
+| `.planning/spikes/MANIFEST.md` | verdict を含むすべてのスパイクのインデックス |
+| `.claude/skills/spike-findings-[project]/` | パッケージ化された所見（`/gsd-spike --wrap-up` 経由） |
+
+---
+
+### 118. スケッチコマンド
+
+**コマンド:** `/gsd-sketch [idea] [--quick] [--text]`
+
+**目的:** 実装にコミットする前に使い捨ての HTML モックアップを通じてデザイン方向を探索します。デザインの質問ごとに 2〜3 のインタラクティブなバリアントを生成し、ビルドステップなしにブラウザで直接閲覧できます。コンパニオンの `/gsd-sketch --wrap-up` は勝利した決定をプロジェクトローカルのスキルにパッケージ化します。
+
+**要件:**
+- REQ-SKETCH-01: 各スケッチは 1 つの特定のビジュアルデザイン質問に答えなければならない
+- REQ-SKETCH-02: 各スケッチはタブナビゲーションを持つ単一の `index.html` に 2〜3 の意味のある異なるバリアントを含まなければならない
+- REQ-SKETCH-03: すべてのインタラクティブ要素（ホバー、クリック、トランジション）は機能しなければならない
+- REQ-SKETCH-04: スケッチはリアルに近いコンテンツを使用しなければならない（ lorem ipsum ではない）
+- REQ-SKETCH-05: 共有の `themes/default.css` は合意された美観に適応した CSS 変数を提供しなければならない
+- REQ-SKETCH-06: `--quick` フラグはムードインテークをスキップ；`--text` フラグは非 Claude ランタイム用に `AskUserQuestion` を番号付きリストに置き換える
+- REQ-SKETCH-07: 勝利バリアントは README フロントマターと HTML タブの ★ でマークされなければならない
+- REQ-SKETCH-08: `/gsd-sketch --wrap-up` は勝利した決定を `.claude/skills/sketch-findings-[project]/` にパッケージ化しなければならない
+
+**生成物:**
+| アーティファクト | 説明 |
+|---------------|------|
+| `.planning/sketches/NNN-name/index.html` | 2〜3 のインタラクティブ HTML バリアント |
+| `.planning/sketches/NNN-name/README.md` | デザイン質問、バリアント、勝者、注目点 |
+| `.planning/sketches/themes/default.css` | 共有 CSS テーマ変数 |
+| `.planning/sketches/MANIFEST.md` | 勝者を含むすべてのスケッチのインデックス |
+| `.claude/skills/sketch-findings-[project]/` | パッケージ化された決定（`/gsd-sketch --wrap-up` 経由） |
+
+---
+
+### 119. エージェントサイズ予算強制
+
+**目的:** CI で強制される段階的な行数制限でエージェントプロンプトファイルをリーンに保ちます。過大なエージェントは本番のコンテキストウィンドウを肥大化させる前にキャッチされます。
+
+**要件:**
+- REQ-BUDGET-01: `agents/gsd-*.md` ファイルは 3 つのティアに分類される：XL（≤ 1,600 行）、Large（≤ 1,000 行）、Default（≤ 500 行）
+- REQ-BUDGET-02: ティア割り当てはファイルの YAML フロントマターで宣言される（`size: xl | large | default`）
+- REQ-BUDGET-03: `tests/agent-size-budget.test.cjs` は制限を強制し、違反時に CI を失敗させる
+- REQ-BUDGET-04: `size` フロントマターキーのないファイルはデフォルト（500 行）制限にデフォルトする
+
+**テストファイル:** `tests/agent-size-budget.test.cjs`
+
+---
+
+### 120. 共有ボイラープレート抽出
+
+**目的:** 共通の 2 つのボイラープレートブロックをオンデマンドで読み込まれる共有参照ファイルに抽出することでエージェント間の重複を削減します。エージェントファイルをサイズ予算内に保ち、ボイラープレートの更新を単一ファイルの変更にします。
+
+**要件:**
+- REQ-BOILER-01: 必須初期読み込み命令は `references/mandatory-initial-read.md` に抽出される
+- REQ-BOILER-02: プロジェクトスキルディスカバリー命令は `references/project-skills-discovery.md` に抽出される
+- REQ-BOILER-03: 以前これらのブロックをインライン化していたエージェントは `@` required_reading を通じてそれらを参照しなければならない
+
+**参照ファイル:** `references/mandatory-initial-read.md`、`references/project-skills-discovery.md`
+
+---
+
+### 121. ナレッジグラフ統合
+
+**目的:** `.planning/graphs/` にプロジェクトの軽量なナレッジグラフを構築、クエリ、検査します。プロジェクトごとのオプトイン。ユーザー向けコマンドの `/gsd-graphify` とプログラマティックな `gsd-tools.cjs graphify …` 動詞ファミリーとして公開されています。コマンド、エージェント、ワークフロー、フェーズをまたいだノードとエッジのグラフ指向ビューで `/gsd-map-codebase --query`（スナップショット指向）を補完します。
+
+**要件:**
+- REQ-GRAPH-01: `.planning/config.json` の `graphify.enabled: true` によるオプトイン。無効時、`/gsd-graphify` はアクティベーションヒントを表示して書き込みなしで停止。
+- REQ-GRAPH-02: スラッシュコマンド `/gsd-graphify` はサブコマンド `build`、`query `、`status`、`diff` を公開。プログラマティック CLI `node gsd-tools.cjs graphify …` はさらに `snapshot` を公開し、`graphify build` の最終ステップとして自動的に呼び出される。
+- REQ-GRAPH-03: ビルドは設定可能な `graphify.build_timeout`（秒）内で実行；タイムアウトを超えた場合、部分的なグラフを残さずにクリーンに中断。
+- REQ-GRAPH-04: `graphify.cjs` は `graph.edges` が存在しない場合に `graph.links` にフォールバックし、古いグラフアーティファクトが引き続きレンダリングされるようにする。
+- REQ-GRAPH-05: Graphify は `gsd-tools.cjs graphify ...` コマンドハンドラーを通じて呼び出される。
+
+**設定:** `graphify.enabled`、`graphify.build_timeout`
+**参照ファイル:** `commands/gsd/graphify.md`、`bin/lib/graphify.cjs`
+
+---
+
+## v1.40.0 機能
+
+### 122. スキルサーフェス統合
+
+**目的:** 31 のマイクロスキルを 4 つの新しいグループ化された親と、サブ操作をフラグとして吸収する 6 つの既存の親に折りたたんで、積極的なスキルリストのオーバーヘッドを削減します。機能的な損失はゼロ — 削除されたすべてのマイクロスキルの動作は統合された親のフラグを通じて存続します。統合後、`commands/gsd/*.md` は 59 のサブスキル（plus 6 つのネームスペースメタスキル、#123 参照）を搭載。
+
+**要件:**
+- REQ-CONSOLIDATE-01: 4 つの新しいグループ化されたスキルがマイクロスキルのクラスターを置き換える：
+ - `/gsd-capture` — add-todo（デフォルト）、note（`--note`）、add-backlog（`--backlog`）、plant-seed（`--seed`）、check-todos（`--list`）を折りたたむ
+ - `/gsd-phase` — add-phase（デフォルト）、insert-phase（`--insert`）、remove-phase（`--remove`）、edit-phase（`--edit`）を折りたたむ
+ - `/gsd-config` — settings-advanced（`--advanced`）、settings-integrations（`--integrations`）、set-profile（`--profile`）を折りたたむ
+ - `/gsd-workspace` — new-workspace（`--new`）、list-workspaces（`--list`）、remove-workspace（`--remove`）を折りたたむ
+- REQ-CONSOLIDATE-02: 6 つの既存の親がラップアップ/サブ操作をフラグとして吸収：`/gsd-update --sync`、`/gsd-update --reapply`、`/gsd-sketch --wrap-up`、`/gsd-spike --wrap-up`、`/gsd-map-codebase --fast`、`/gsd-map-codebase --query`、`/gsd-code-review --fix`、`/gsd-progress --do`、`/gsd-progress --next`。
+- REQ-CONSOLIDATE-03: 削除されたマイクロスキルスラッシュフォーム（`gsd-add-todo`、`gsd-add-backlog`、`gsd-plant-seed`、`gsd-check-todos`、`gsd-add-phase`、`gsd-insert-phase`、`gsd-remove-phase`、`gsd-edit-phase`、`gsd-new-workspace`、`gsd-list-workspaces`、`gsd-remove-workspace`、`gsd-settings-advanced`、`gsd-settings-integrations`、`gsd-set-profile`、`gsd-sketch-wrap-up`、`gsd-spike-wrap-up`、`gsd-reapply-patches`、`gsd-code-review-fix`、…）は「Unknown command」に解決しなければならない — シャドウスタブなし。
+- REQ-CONSOLIDATE-04: `autonomous.md` は（削除された `gsd-code-review-fix` を以前呼び出していた代わりに）`/gsd-code-review --fix` を呼び出す。
+
+**参照 issue:** [#2790](https://github.com/open-gsd/gsd-core/issues/2790)
+
+---
+
+### 123. ネームスペースメタスキル（2 段階ルーティング）
+
+**目的:** フラットな積極的スキルリストを 2 段階の階層的ルーティングレイヤーに置き換えます。モデルは 86 エントリの代わりに 6 つのネームスペースルーターを認識し、ネームスペースを選択してからサブスキルにルーティングします。説明にはルーティング密度のためにパイプ区切りのキーワードタグ（≤ 60 文字）を使用します。
+
+**コマンド:**
+- `/gsd-workflow` — フェーズパイプラインルーター（discuss / plan / execute / verify / phase / progress）
+- `/gsd-project` — プロジェクトライフサイクル（マイルストーン、監査、サマリー）
+- `/gsd-quality` — 品質ゲート（コードレビュー、デバッグ、監査、セキュリティ、評価、UI）
+- `/gsd-context` — コードベースインテリジェンス（マップ、グラファイファイ、ドキュメント、学習）
+- `/gsd-manage` — 設定 / ワークスペース / ワークストリーム / スレッド / アップデート / シップ / インボックス
+- `/gsd-ideate` — 探索とキャプチャ（探索、スケッチ、スパイク、スペック、キャプチャ）
+
+**トークンコスト:**
+
+| | エントリ数 | 概算トークン |
+|---|---|---|
+| v1.40 以前のフルインストール | 86 | ~2,150 |
+| ネームスペースメタスキル | 6 | ~120 |
+
+**要件:**
+- REQ-NS-01: 6 つの `commands/gsd/ns-*.md` ネームスペースルーターはパイプ区切りのキーワードタグ説明（≤ 60 文字）とともに搭載される。
+- REQ-NS-02: 既存のサブスキルは変更されず、引き続き直接呼び出し可能 — ネームスペーススキルは直接スラッシュフォームの置き換えではなく追加的。
+- REQ-NS-03: 各ネームスペースルーターの本体には、#2790 以後の統合されたサーフェス上の正しい具体的なサブスキルへのユーザーインテントをマッピングするルーティングテーブルが含まれる。
+
+**参照 issue:** [#2792](https://github.com/open-gsd/gsd-core/issues/2792)
+
+---
+
+### 124. コンテキストウィンドウ使用率ガード
+
+**コマンド:** `/gsd-health --context`
+
+**目的:** コンテキストウィンドウの飽和に対する品質ガード。2 つの閾値：60% 使用率で警告（「`/gsd-thread` を検討してください」）、70% でクリティカル（「推論品質が低下する可能性があります」；最近のコンテキストアテンション研究による破断点に一致）。
+
+**要件:**
+- REQ-CTX-GUARD-01: `/gsd-health --context` は現在の使用率、閾値ティア（`ok` / `warn` / `critical`）、修正提案を含む構造化されたステータス行を出力する。
+- REQ-CTX-GUARD-02: 同じトリアージは `gsd-tools.cjs validate context --tokens-used --context-window ` として公開されている — ステータス行とフック呼び出し元の構造化エンベロープ（#125）。両フラグは必須；ハンドラーは REQ-CTX-GUARD-03 の純粋な分類器と同じ `{ percent, state }` エンベロープを返す。
+- REQ-CTX-GUARD-03: 分類器（`bin/lib/context-utilization.cjs`）は純粋：入力 `(tokensUsed, contextWindow)`、出力 `{ percent, state }`。ユニットテストが容易で、任意の呼び出し元から再利用しやすい。
+
+**参照 issue:** [#2792](https://github.com/open-gsd/gsd-core/issues/2792)
+
+---
+
+### 125. フェーズライフサイクルステータス行リードサイド
+
+**目的:** ステータス行にフェーズオーケストレーション状態を表示します。`parseStateMd()` は 4 つの新しい STATE.md フロントマターフィールドを読み込み、`formatGsdState()` は実行中、アイドル、および進行状況シーンをレンダリングします。ライトサイドの配線は後の RC で行われます。
+
+**要件:**
+- REQ-LIFECYCLE-01: `parseStateMd()` は 4 つのオプションフィールドを読み込む：
+ - `active_phase` — オーケストレーターが実行中のフェーズ番号
+ - `next_action` — アイドル時の推奨される次のコマンド
+ - `next_phases` — 次のフェーズ番号の YAML フロー配列
+ - `progress` — ネストされた `total_phases` / `completed_phases` / `percent` ブロック
+- REQ-LIFECYCLE-02: `formatGsdState()` はライフサイクルフィールドを優先順位の順にチェックし、最初に一致するシーンを出力する（フェーズアクティブ → アイドル次推奨 → マイルストーン完了 → デフォルトフォールバック）。
+- REQ-LIFECYCLE-03: 4 つのフィールドはすべてデフォルトで undefined；既存の STATE.md ファイルはバイト単位で同一にレンダリングされる。
+
+**参照 issue:** [#2833](https://github.com/open-gsd/gsd-core/issues/2833) — フルフィールドリファレンスとレンダリングルールについては [`docs/STATE-MD-LIFECYCLE.md`](../reference/state-md.md) を参照。
+
+---
+
+## v1.41.0 機能
+
+### 126. フェーズタイプごとのモデル選択
+
+**目的:** フルエージェント分類法を習得せずにフェーズレベル（プランニング、リサーチ、実行、検証）でモデルチューニングを表現します。エージェントごとの `model_overrides`（精密、冗長）とグローバル `model_profile` ティア（粗い、均一）の中間に位置します。
+
+**設定キー:** `.planning/config.json` の `models`
+
+**フェーズタイプスロット:**
+
+| スロット | 割り当てられたエージェント |
+|---------|----------------------|
+| `planning` | `gsd-planner`、`gsd-roadmapper`、`gsd-pattern-mapper` |
+| `discuss` | （将来のサブエージェント用に予約） |
+| `research` | `gsd-phase-researcher`、`gsd-project-researcher`、`gsd-research-synthesizer`、`gsd-codebase-mapper`、`gsd-ui-researcher` |
+| `execution` | `gsd-executor`、`gsd-debugger`、`gsd-doc-writer` |
+| `verification` | `gsd-verifier`、`gsd-plan-checker`、`gsd-integration-checker`、`gsd-nyquist-auditor`、`gsd-ui-checker`、`gsd-ui-auditor`、`gsd-doc-verifier` |
+| `completion` | （将来のサブエージェント用に予約） |
+
+**受け入れられる値:** `"opus"` / `"sonnet"` / `"haiku"` / `"inherit"`
+
+**解決の優先順位（高→低）:**
+
+```text
+1. model_overrides[]
+2. dynamic_routing.tier_models[] (有効時)
+3. models[] (この機能)
+4. model_profile
+5. ランタイムデフォルト
+```
+
+**要件:**
+- REQ-PHASE-MODELS-01: 6 つの名前付き `models.*` スロットが `config-schema.cjs` と `config-schema.ts` に受け入れられる；`config-set` は不明なフェーズタイプを拒否する。
+- REQ-PHASE-MODELS-02: `models` ブロックのない設定は v1.41 以前の動作とバイト単位で同一に動作する。
+- REQ-PHASE-MODELS-03: `discuss` と `completion` は前方互換性のためにスキーマに受け入れられる；今日それらを設定することはサブエージェントが各にマッピングされるまでノーオペレーション。
+
+**参照 issue:** [#3023](https://github.com/open-gsd/gsd-core/pull/3030)
+
+---
+
+### 127. 失敗ティアエスカレーション付き動的ルーティング
+
+**目的:** デフォルトで安価なティアを使用し、オーケストレーターがソフト失敗（検証が決定的でない、プランチェック FLAG など）を検出した場合に自動的により有能なモデルにエスカレートします。
+
+**設定キー:** `.planning/config.json` の `dynamic_routing`
+
+**動作:**
+- `enabled: false`（デフォルト）— 機能はオフ；すべてのエージェントは変更なしに優先順位チェーンを使用。
+- `enabled: true` — リゾルバーは最初のスポーンに `tier_models[default_tier]` を選択し、オーケストレーターが検出したソフト失敗で 1 ティア上にエスカレートし、`max_escalations` でキャップ。
+
+**構成:** `model_overrides` は常に優先；`dynamic_routing.tier_models[]` は `models.` と `model_profile` より上で解決。
+
+**要件:**
+- REQ-DYNROUTE-01: `dynamic_routing.enabled` はマスタースイッチとして機能；`false` またはブロックが存在しない場合、動作変更はゼロ。
+- REQ-DYNROUTE-02: 新しいリゾルバー `resolveModelForTier(cwd, agent, attempt)`（`core.cjs` 内）はオーケストレーター統合の単一コールサイト。
+- REQ-DYNROUTE-03: `max_escalations` はランナウェイコストを防ぐためにエスカレーションチェーンをキャップ。
+
+**参照 issue:** [#3024](https://github.com/open-gsd/gsd-core/pull/3031)
+
+---
+
+### 128. アップデートバナーオプトイン
+
+**目的:** GSD ステータス行を拒否またはバイパスしたユーザーに、ステータス行を必要とせずにアップデートの可用性を表示します。
+
+**動作:**
+- インストール時、インストーラーが GSD ステータス行を検出しない場合、オプトインの `SessionStart` フックを提供します。
+- フックはステータス行で使用されているのと同じキャッシュ `~/.cache/gsd/gsd-update-check.json` を読み込み、アップデートが利用可能な場合のみバナーを表示します。
+- 最新の場合はサイレント。
+- 障害診断は 24 時間に 1 回に制限。
+- `npx @opengsd/gsd-core --uninstall` によってクリーンに削除。
+
+**要件:**
+- REQ-BANNER-01: バナーは明示的なオプトインなしにインストールされない。
+- REQ-BANNER-02: 追加のネットワークリクエストなし — 既存のバックグラウンドアップデートチェックキャッシュを再利用。
+- REQ-BANNER-03: アンインストールパスはバナーフックを削除する。
+
+**参照 issue:** [#2795](https://github.com/open-gsd/gsd-core/pull/2795)
+
+---
+
+### 129. issue-driven-orchestration ガイド
+
+**目的:** GitHub / Linear / Jira issue から GSD ワークフロー全体を駆動するレシピを文書化し、トラッカー中心の概念を既存の GSD プリミティブにマッピングします。
+
+**ドキュメント:** [`docs/issue-driven-orchestration.md`](../issue-driven-orchestration.md)
+
+**対象ワークフロー:**
+1. issue ごとに分離されたワークスペースを作成（`/gsd-workspace --new`）
+2. マネージャーダッシュボードを実行して全体を把握（`/gsd-manager`）
+3. 自律的に実行（`/gsd-autonomous`）
+4. 検証とレビュー（`/gsd-verify-work`、`/gsd-review`）
+5. シップして issue をクローズ（`/gsd-ship`）
+
+新しいコマンドやデーモンプロセスはなし — 既存のプリミティブをトラッカー駆動ワークフローにマッピングする純粋なドキュメントアーティファクト。
+
+**参照 issue:** [#2840](https://github.com/open-gsd/gsd-core/pull/2840)
+
+---
+
+### 130. グラファイファイコミットベースの古さ検出
+
+**目的:** アーキテクチャグラフが現在のコミットから構築されたか古いコミットから構築されたかを表示し、既存の mtime ベースの古さシグナルを補完します。
+
+**コマンド:** `/gsd-graphify status`
+
+**返される新フィールド（graphify v0.7+ グラフ）:**
+
+| フィールド | 型 | 説明 |
+|-----------|-----|------|
+| `built_at_commit` | string | グラフが構築されたコミット SHA |
+| `current_commit` | string | 現在の `git HEAD` |
+| `commits_behind` | number | グラフが HEAD から何コミット遅れているか |
+| `commit_stale` | boolean \| null | `true`=古い、`false`=最新、`null`=利用不可（v0.7 以前、非 git） |
+
+**レンダリング出力（シグナルが利用可能な場合）:**
+```
+Source commit: abc1234 (3 commits behind HEAD)
+```
+
+**セキュリティ:** `built_at_commit` は `git` に到達する前に 4〜40 の 16 進文字として検証される — 悪意のある `graph.json` はダッシュオプションを argv にインジェクトできない。
+
+**フォールバック:** v0.7 以前のグラフと非 git チェックアウトは `commit_stale: null` を返す；呼び出し元は既存の mtime ベースの `stale` フラグにフォールバック。既存ユーザーの動作変更なし。
+
+**参照 issue:** [#3170](https://github.com/open-gsd/gsd-core/issues/3170)
+
+---
+
+## v1.42.1 機能
+
+### 132. パッケージ正当性ゲート
+
+**目的:** 幻覚的、疑わしい、またはスロップスクワッティングのパッケージ名がシェルインストールコマンドに到達する前に停止します。
+
+**動作:**
+- フェーズリサーチは推奨パッケージの `## Package Legitimacy Audit` テーブルを書き込む。
+- 検索のみで確認されたパッケージは `[ASSUMED]` として扱われ、信頼されない。
+- `[SLOP]` パッケージは推奨から削除される。
+- `[ASSUMED]` または疑わしいパッケージを必要とするプランは人間の確認チェックポイントを追加する。
+- Executor のインストール失敗は、同様の名前のパッケージを自動的に試みる代わりに人間の確認のために停止する。
+
+**要件:**
+- REQ-PKG-GATE-01: リサーチはパッケージレジストリ、年齢、ダウンロード/ソースシグナル、スロップチェック verdict、および処分を記録しなければならない。
+- REQ-PKG-GATE-02: プランナーは実行前に未検証または疑わしいパッケージのインストールをゲートしなければならない。
+- REQ-PKG-GATE-03: Executor はパッケージマネージャーのインストール失敗後にパッケージ名を自動置換してはならない。
+
+**参照:** [v1.42.1 リリースノート](../RELEASE-v1.42.1.md)
+
+---
+
+### 133. スキルサーフェス予算
+
+**目的:** コンテキスト予算が重要な場合に、インストールされたスキルとエージェントのサーフェスエリアをユーザーが削減できるようにします。
+
+**インストールプロファイル:**
+| プロファイル | 目的 |
+|------------|------|
+| `core` | 最小限のメインループサーフェス |
+| `standard` | コアに加えて一般的なフェーズ管理コマンド |
+| `full` | 完全なサーフェス；デフォルト |
+
+**ランタイムコントロール:** `/gsd:surface` はプロファイル状態をリストし、再インストールなしにスキルクラスターを有効化、無効化、またはリセットします。
+
+**要件:**
+- REQ-SURFACE-01: インストーラーは `--profile=` を解決し、アクティブなプロファイルを `.gsd-profile` に永続化しなければならない。
+- REQ-SURFACE-02: `--minimal` と `--core-only` は `--profile=core` のエイリアスとして残らなければならない。
+- REQ-SURFACE-03: ランタイムサーフェス状態はインストールプロファイルマーカーの外側に永続化されなければならない。
+
+**参照:** [ADR-0011](../adr/0011-skill-surface-budget-module.md)
+
+---
+
+### 134. インストーラーマイグレーション
+
+**目的:** インストールとアップデート中のランタイム設定クリーンアップを明示的で監査可能、かつロールバック対応にします。
+
+**機能:**
+- 初回ベースラインマイグレーションは管理されたファイルを記録する。
+- レガシーステールファイルのクリーンアップは削除または再書き込み前に所有権のエビデンスを使用する。
+- ユーザー所有のアーティファクトは保存される。
+- 曖昧な GSD らしいファイルはサイレントに上書きされる代わりに明確なレポートでブロックする。
+- マイグレーションプランはドライラン報告とロールバック保護をサポートする。
+
+**要件:**
+- REQ-INSTALL-MIGRATION-01: マイグレーション記録はメタデータ、インストールスコープ、所有権のエビデンスを含まなければならない。
+- REQ-INSTALL-MIGRATION-02: 所有権が曖昧な場合、破壊的なアクションはフェイルドクローズでなければならない。
+- REQ-INSTALL-MIGRATION-03: インストール失敗はロールバックデータが存在する場合、インストール前の状態を復元しなければならない。
+
+**参照:** [インストーラーマイグレーション](../installer-migrations.md)
+
+---
+
+### 135. カスタムシップ PR ボディセクション
+
+**コマンド:** `/gsd-ship`
+
+**設定キー:** `ship.pr_body_sections`
+
+**目的:** GSD ワークフローファイルを編集せずに、生成された PR ボディにプロジェクト固有の PRD スタイルセクションを追加します。
+
+**動作:** 設定されたセクションは必須の `Summary`、`Changes`、`Requirements Addressed`、`Verification`、および `Key Decisions` セクションの後に追加されます。アーティファクトの見出しからコピー、テンプレートをレンダリング、またはスタティックテキストにフォールバックできます。
+
+**要件:**
+- REQ-SHIP-SECTIONS-01: カスタムセクションは必須の PR セクションを置き換え、削除、または並べ替えてはならない。
+- REQ-SHIP-SECTIONS-02: 不明なテンプレートトークンは設定検証によって拒否されなければならない。
+- REQ-SHIP-SECTIONS-03: 無効化されたセクションは PR 出力に表示されることなく設定に残らなければならない。
+
+**参照:** [カスタム PR ボディセクション](../ship-pr-body-sections.md)
+
+---
+
+### 136. レビューデフォルトレビュアー
+
+**コマンド:** `/gsd-review`
+
+**設定キー:** `review.default_reviewers`
+
+**目的:** チームがフラグなしの `/gsd-review` 実行のデフォルトレビュアーサブセットを選択できるようにします。
+
+**優先順位:**
+```text
+明示的なレビュアーフラグ -> --all -> review.default_reviewers -> すべての検出されたレビュアー
+```
+
+**要件:**
+- REQ-REVIEW-DEFAULTS-01: `review.default_reviewers` が欠如している場合、以前のすべて検出動作を維持しなければならない。
+- REQ-REVIEW-DEFAULTS-02: 空の配列は拒否されなければならない；すべて検出動作を復元するにはキーを削除する。
+- REQ-REVIEW-DEFAULTS-03: 既知だが利用不可のレビュアーは実行をハードフェイルさせる代わりに診断とともにスキップされなければならない。
+
+**参照:** [設定リファレンス](../CONFIGURATION.md#reviewer-defaults-for-gsd-review)
+
+---
+
+### 137. ファロー構造レビュープリパス
+
+**コマンド:** `/gsd-code-review`
+
+**設定キー:** `code_quality.fallow.*`
+
+**目的:** エージェントレビューの前にオプションの構造分析パスを追加します。
+
+**動作:** 有効時、GSD は `fallow` バイナリを解決し、境界付き監査を実行し、`FALLOW.json` を書き込み、`REVIEW.md` に構造的な所見を埋め込みます。
+
+**要件:**
+- REQ-FALLOW-01: Fallow はオプトインであり、デフォルトで無効でなければならない。
+- REQ-FALLOW-02: 欠如または失敗した fallow 実行は明確な診断を生成しなければならない。
+- REQ-FALLOW-03: 埋め込み予算を超えた所見は、生の JSON アーティファクトを保存しながら警告とともにスキップされなければならない。
+
+**参照:** [設定リファレンス](../CONFIGURATION.md#code-quality-settings)
+
+---
+
+### 138. フェーズ終了時の人間検証モード
+
+**設定キー:** `workflow.human_verify_mode`
+
+**目的:** フライト中の人間チェックポイントの中断を減らしながら、人間の検証要件を保持します。
+
+**動作:** デフォルトの `"end-of-phase"` モードは人間チェックをフェーズレビューのための `` ブロックに埋め込みます。`"mid-flight"` はブロッキングの `checkpoint:human-verify` タスクを復元します。
+
+**要件:**
+- REQ-HUMAN-VERIFY-01: `checkpoint:decision` と `checkpoint:human-action` はモードに関わらずブロッキングのまま。
+- REQ-HUMAN-VERIFY-02: 人間が必要な検証はフェーズ終了時のレビューが解決するまで保留のまま。
+- REQ-HUMAN-VERIFY-03: キーのない設定は `"end-of-phase"` を使用しなければならない。
+
+**参照:** [チェックポイントリファレンス](../../get-shit-done/references/checkpoints.md)
+
+---
+
+### 139. クォータとレート制限の失敗分類
+
+**コマンド:** `/gsd-execute-phase`
+
+**目的:** プロバイダーのクォータとレート制限の失敗を、通常の executor の失敗ではなく待機して再開の条件として扱います。
+
+**動作:** エージェント出力は `429`、`rate limit`、`usage limit`、`RESOURCE_EXHAUSTED`、`usage_limit_reached` などのシグナルに対して分類されます。一致する失敗はリセット待ちの回復パスを提示します。
+
+**要件:**
+- REQ-QUOTA-01: クォータ失敗は即時再試行を主要な回復として提供してはならない。
+- REQ-QUOTA-02: 分類は Claude、Copilot、Codex、Gemini、および汎用プロバイダーセンチネルをカバーしなければならない。
+- REQ-QUOTA-03: 非クォータ失敗は通常の実行失敗パスを継続しなければならない。
+
+**参照:** [プロバイダーレート制限シグナル](../research/provider-rate-limit-signals.md)
+
+---
+
+### 140. ステータス行コンテキスト位置
+
+**設定キー:** `statusline.context_position`
+
+**目的:** 狭いターミナルでコンテキストメーターを見やすく保ちます。
+
+**オプション:**
+| 値 | 動作 |
+|----|------|
+| `"end"` | デフォルト；行末近くにコンテキストメーターをレンダリング |
+| `"front"` | モデル名の直後にコンテキストメーターをレンダリング |
+
+**要件:**
+- REQ-STATUSLINE-POS-01: 無効な値は設定検証によって拒否されなければならない。
+- REQ-STATUSLINE-POS-02: 設定が欠如している場合、既存の末尾位置レンダリングを維持しなければならない。
+
+**参照:** [設定リファレンス](../CONFIGURATION.md#statusline-settings)
+
+---
+
+### 141. マイルストーンタグ作成トグル
+
+**コマンド:** `/gsd-complete-milestone`
+
+**設定キー:** `git.create_tag`
+
+**目的:** 外部リリース自動化を持つプロジェクトがローカル git タグを作成せずにマイルストーンを完了できるようにします。
+
+**動作:** `git.create_tag: false` はマイルストーンタグ作成をスキップします。ワークフローは引き続きマイルストーンアーティファクトと状態を更新します。
+
+**要件:**
+- REQ-MILESTONE-TAG-01: 設定が欠如している場合、自動タグ作成を維持しなければならない。
+- REQ-MILESTONE-TAG-02: 既存のタグの衝突はタグを上書きする代わりに明確に失敗しなければならない。
+- REQ-MILESTONE-TAG-03: タグ作成の無効化はマイルストーンアーカイブをスキップしてはならない。
+
+**参照:** [設定リファレンス](../CONFIGURATION.md#git-branching)
+
+---
+
+### 142. 構造化 JSON エラーモード
+
+**CLI:** `gsd-tools --json-errors`
+
+**目的:** 自動化呼び出し元に安定した機械可読エラーエンベロープを提供します。
+
+**動作:** `--json-errors` 下で失敗するコマンドは、散文のみの stderr の代わりに、エラーの種類、メッセージ、コマンドコンテキスト、および終了マッピングを含む構造化された `ok: false` ペイロードを返します。
+
+**要件:**
+- REQ-JSON-ERRORS-01: 不明なコマンド、検証エラー、タイムアウト、ネイティブ失敗、フォールバック失敗、および内部エラーは正規エラーの種類にマッピングされなければならない。
+- REQ-JSON-ERRORS-02: CLI 終了コードマッピングは自動化呼び出し元に対して安定して維持されなければならない。
+- REQ-JSON-ERRORS-03: 人間可読出力は `--json-errors` が存在しない場合にデフォルトのまま。
+
+---
+
+## 関連
+
+- [コマンド](../COMMANDS.md)
+- [設定](../CONFIGURATION.md)
+- [ドキュメントインデックス](../README.md)
+
+**参照:** [JSON エラーモード](../json-errors.md)
diff --git a/docs/ja-JP/INVENTORY.md b/docs/ja-JP/INVENTORY.md
new file mode 100644
index 000000000..b5c953b79
--- /dev/null
+++ b/docs/ja-JP/INVENTORY.md
@@ -0,0 +1,493 @@
+# GSD 出荷済みサーフェスインベントリ
+
+> 出荷済みのすべての GSD サーフェスの正式な一覧: コマンド、エージェント、ワークフロー、リファレンス、CLI モジュール、フック。広範なドキュメント（AGENTS.md、COMMANDS.md、ARCHITECTURE.md、CLI-TOOLS.md）とファイルシステムが乖離している場合は、このファイルとリポジトリツリー自体を正式なソースとして扱ってください。
+
+## このファイルの使い方
+
+- ここに記載された数値は v1.36.0 時点のファイルシステムから導出されており、リリース間で変動する可能性があります。最新の数値を確認するには、チェックアウトに対して `ls commands/gsd/*.md | wc -l`、`ls agents/gsd-*.md | wc -l` などを実行してください。
+- このファイルは出荷済みのすべてのサーフェスを 6 つのファミリー（エージェント、コマンド、ワークフロー、リファレンス、CLI モジュール、フック）にわたって列挙します。広範なドキュメントはナラティブや厳選されたサブセットを提示する場合があります。ファイルシステムと異なる場合は、このファイルとディレクトリ一覧が正式です。
+- v1.36.0 以降に追加された新しいサーフェスはまずここに記載し、その後広範なドキュメントに伝播させてください。`tests/inventory-counts.test.cjs`、`tests/commands-doc-parity.test.cjs`、`tests/agents-doc-parity.test.cjs`、`tests/cli-modules-doc-parity.test.cjs`、`tests/hooks-doc-parity.test.cjs`、`tests/architecture-counts.test.cjs`、`tests/command-count-sync.test.cjs` のドリフト管理テストが、ファイルシステムに対して数値とロスター内容を固定します。
+
+これは出荷済みのすべての GSD Core サーフェスの正式な一覧です。トピック別のナビゲーションは [docs インデックス](README.md) を参照してください。
+
+---
+
+## エージェント (33 shipped)
+
+完全な一覧は `agents/gsd-*.md` を参照してください。"Primary doc" 列は [`docs/AGENTS.md`](../AGENTS.md) が完全なロールカードを掲載している場合（*primary*）、"Advanced and Specialized Agents" セクションに短いスタブがある場合（*advanced stub*）、または掲載がない場合（*inventory only*）を示します。
+
+| エージェント | 役割（一行） | 起動元 | Primary doc |
+|--------------|-------------|--------|-------------|
+| gsd-project-researcher | ロードマップ作成前にドメインエコシステムを調査（スタック、機能、アーキテクチャ、落とし穴）。 | `/gsd-new-project`, `/gsd-new-milestone` | primary |
+| gsd-phase-researcher | 計画前に特定フェーズの実装アプローチを調査。 | `/gsd-plan-phase` | primary |
+| gsd-ui-researcher | フロントエンドフェーズ向けの UI デザインコントラクトを作成。 | `/gsd-ui-phase` | primary |
+| gsd-assumptions-analyzer | discuss-phase（仮定モード）向けに証拠に基づく仮定を作成。 | `discuss-phase-assumptions` workflow | primary |
+| gsd-advisor-researcher | discuss-phase アドバイザーモード中に単一のグレーゾーン決定を調査。 | `discuss-phase` workflow (advisor mode) | primary |
+| gsd-research-synthesizer | 並列調査エージェントの出力を統合した SUMMARY.md にまとめる。 | `/gsd-new-project` | primary |
+| gsd-planner | タスク分解とゴール後退型検証を含む実行可能なフェーズプランを作成。 | `/gsd-plan-phase`, `/gsd-quick` | primary |
+| gsd-roadmapper | フェーズ分解と要件マッピングを含むプロジェクトロードマップを作成。 | `/gsd-new-project` | primary |
+| gsd-executor | アトミックコミットと逸脱処理を伴って GSD プランを実行。 | `/gsd-execute-phase`, `/gsd-quick` | primary |
+| gsd-plan-checker | プランがフェーズ目標を達成できるか検証（8 つの検証ディメンション）。 | `/gsd-plan-phase` (verification loop) | primary |
+| gsd-integration-checker | クロスフェーズ統合とエンドツーエンドフローを検証。 | `/gsd-audit-milestone` | primary |
+| gsd-ui-checker | UI-SPEC.md デザインコントラクトを品質ディメンションに対して検証。 | `/gsd-ui-phase` (validation loop) | primary |
+| gsd-verifier | ゴール後退型分析によってフェーズ目標の達成を検証。 | `/gsd-execute-phase` | primary |
+| gsd-nyquist-auditor | テストを生成して Nyquist バリデーションのギャップを埋める。 | `/gsd-validate-phase` | primary |
+| gsd-ui-auditor | 実装済みフロントエンドコードの 6 本柱ビジュアル監査を遡及的に実施。 | `/gsd-ui-review` | primary |
+| gsd-codebase-mapper | コードベースを探索して構造化分析ドキュメントを作成。 | `/gsd-map-codebase` | primary |
+| gsd-debugger | 永続的な状態を持つ科学的手法でバグを調査。 | `/gsd-debug`, `/gsd-verify-work` | primary |
+| gsd-user-profiler | 8 つのディメンションで開発者の行動をスコアリング。 | `/gsd-profile-user` | primary |
+| gsd-doc-writer | プロジェクトドキュメントを作成・更新。 | `/gsd-docs-update` | primary |
+| gsd-doc-verifier | 生成されたドキュメントの事実に基づくクレームを検証。 | `/gsd-docs-update` | primary |
+| gsd-security-auditor | PLAN.md の脅威モデルから脅威への対策を検証。 | `/gsd-secure-phase` | primary |
+| gsd-pattern-mapper | 新しいファイルを最も近い既存の類似物にマッピングし、プランナー向けの PATTERNS.md を作成。 | `/gsd-plan-phase` (between research and planning) | advanced stub |
+| gsd-debug-session-manager | メインコンテキストをスリムに保つために、完全な `/gsd-debug` チェックポイントと継続ループを独立したコンテキストで実行。 | `/gsd-debug` | advanced stub |
+| gsd-code-reviewer | バグ、セキュリティ問題、コード品質の問題についてソースファイルをレビューし、REVIEW.md を作成。 | `/gsd-code-review` | advanced stub |
+| gsd-code-fixer | アトミックな修正コミットで REVIEW.md の指摘を適用し、REVIEW-FIX.md を作成。 | `/gsd-code-review --fix` | advanced stub |
+| gsd-ai-researcher | 選択した AI フレームワークの公式ドキュメントを実装準備済みのガイダンス（AI-SPEC.md §3–§4b）に調査。 | `/gsd-ai-integration-phase` | advanced stub |
+| gsd-domain-researcher | AI システムのドメイン専門家による評価基準と失敗モードを浮き上がらせる（AI-SPEC.md §1b）。 | `/gsd-ai-integration-phase` | advanced stub |
+| gsd-eval-planner | AI フェーズの構造化された評価戦略を設計（AI-SPEC.md §5–§7）。 | `/gsd-ai-integration-phase` | advanced stub |
+| gsd-eval-auditor | AI フェーズの評価カバレッジを遡及監査し、EVAL-REVIEW.md（COVERED/PARTIAL/MISSING）を作成。 | `/gsd-eval-review` | advanced stub |
+| gsd-framework-selector | AI/LLM フレームワークをスコアリングして推奨する 6 問以内のインタラクティブな決定マトリクス。 | `/gsd-ai-integration-phase` | advanced stub |
+| gsd-intel-updater | クエリ可能なコードベースナレッジベースとして使用される構造化インテルファイル（`.planning/intel/*.json`）を作成。 | `/gsd-map-codebase --query` | advanced stub |
+| gsd-doc-classifier | 単一の計画ドキュメントを ADR、PRD、SPEC、DOC、UNKNOWN に分類し、ドキュメントコーパスを並列処理するために生成。 | `/gsd-ingest-docs` | advanced stub |
+| gsd-doc-synthesizer | 分類された計画ドキュメントを優先規則、サイクル検出、3 バケット競合レポートで単一の統合コンテキストに合成。 | `/gsd-ingest-docs` | advanced stub |
+
+**カバレッジ注記。** `docs/AGENTS.md` は 21 のプライマリエージェントに完全なロールカードを、12 の上級エージェントに簡潔なスタブを提供します。同ファイルのエージェントツール権限サマリーはプライマリ 21 エージェントのみをカバーします。上級エージェントのツール一覧は `agents/gsd-*.md` の各エージェントフロントマターに記載されています。
+
+---
+
+## コマンド (67 shipped)
+
+完全な一覧は `commands/gsd/*.md` を参照してください。以下のグループ分けは `docs/COMMANDS.md` のセクション順に対応しています。各行にはコマンド名、コマンドのフロントマター `description:` から導出された一行の役割、ソースファイルへのリンクが含まれます。`tests/command-count-sync.test.cjs` がこの数値をファイルシステムに対して固定します。
+
+### 名前空間メタスキル
+
+これら 6 つのルーターは記述子専用のエントリーで、モデルが最初に選択します。各エントリーの本体には正しい具体的なサブスキルを指すルーティングテーブルが含まれています。積極的なスキル列挙のトークンコストを低く抑えながら、完全なサーフェスに到達可能にするために存在します。根拠は [#2792](https://github.com/open-gsd/gsd-core/issues/2792) を参照してください。ルーティングテーブルは [#2790](https://github.com/open-gsd/gsd-core/issues/2790) 以降の統合サーフェスを対象とします。
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-workflow` | フェーズパイプラインルーター — discuss / plan / execute / verify / phase / progress。 | [commands/gsd/ns-workflow.md](../../commands/gsd/ns-workflow.md) |
+| `/gsd-project` | プロジェクトライフサイクルルーター — マイルストーン、監査、サマリー。 | [commands/gsd/ns-project.md](../../commands/gsd/ns-project.md) |
+| `/gsd-quality` | 品質ゲートルーター — コードレビュー、デバッグ、監査、セキュリティ、eval、UI。 | [commands/gsd/ns-review.md](../../commands/gsd/ns-review.md) |
+| `/gsd-context` | コードベースインテリジェンスルーター — map、graphify、docs、learnings。 | [commands/gsd/ns-context.md](../../commands/gsd/ns-context.md) |
+| `/gsd-manage` | 管理ルーター — config、workspace、workstreams、thread、update、ship、inbox。 | [commands/gsd/ns-manage.md](../../commands/gsd/ns-manage.md) |
+| `/gsd-ideate` | 探索・キャプチャルーター — explore、sketch、spike、spec、capture。 | [commands/gsd/ns-ideate.md](../../commands/gsd/ns-ideate.md) |
+
+### コアワークフロー
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-new-project` | 深いコンテキスト収集と PROJECT.md で新しいプロジェクトを初期化。 | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
+| `/gsd-workspace` | GSD ワークスペースを管理 — 独立したワークスペース環境を作成（`--new`）、一覧表示（`--list`）、削除（`--remove`）。 | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
+| `/gsd-discuss-phase` | 計画前にアダプティブな質問でフェーズコンテキストを収集。 | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
+| `/gsd-mvp-phase` | フェーズを垂直 MVP スライスとして計画 — ユーザーストーリー、SPIDR 分割、その後 plan-phase。 | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
+| `/gsd-spec-phase` | 反証可能な要件を持つ SPEC.md を生成するソクラテス的仕様精緻化。 | [commands/gsd/spec-phase.md](../../commands/gsd/spec-phase.md) |
+| `/gsd-ui-phase` | フロントエンドフェーズ向けの UI デザインコントラクト（UI-SPEC.md）を生成。 | [commands/gsd/ui-phase.md](../../commands/gsd/ui-phase.md) |
+| `/gsd-ai-integration-phase` | フレームワーク選択、調査、eval 計画を経て AI デザインコントラクト（AI-SPEC.md）を生成。 | [commands/gsd/ai-integration-phase.md](../../commands/gsd/ai-integration-phase.md) |
+| `/gsd-plan-phase` | 検証ループ付きの詳細なフェーズプラン（PLAN.md）を作成。 | [commands/gsd/plan-phase.md](../../commands/gsd/plan-phase.md) |
+| `/gsd-plan-review-convergence` | クロス AI プラン収束ループ — HIGH の懸念がなくなるまでレビューフィードバックで再計画（最大 3 サイクル）。 | [commands/gsd/plan-review-convergence.md](../../commands/gsd/plan-review-convergence.md) |
+| `/gsd-ultraplan-phase` | [BETA] フェーズ計画を Claude Code の ultraplan クラウドにオフロード — リモートで下書きし、ブラウザでレビューし、`/gsd-import` 経由でインポート。Claude Code のみ。 | [commands/gsd/ultraplan-phase.md](../../commands/gsd/ultraplan-phase.md) |
+| `/gsd-spike` | 使い捨ての実験でアイデアを素早くスパイク。`--wrap-up` で調査結果を永続的なスキルとしてパッケージ化。 | [commands/gsd/spike.md](../../commands/gsd/spike.md) |
+| `/gsd-sketch` | 使い捨ての HTML モックアップで UI/デザインアイデアを素早くスケッチ。`--wrap-up` で調査結果をパッケージ化。 | [commands/gsd/sketch.md](../../commands/gsd/sketch.md) |
+| `/gsd-execute-phase` | ウェーブベースの並列化でフェーズのすべてのプランを実行。 | [commands/gsd/execute-phase.md](../../commands/gsd/execute-phase.md) |
+| `/gsd-verify-work` | 自動診断付きの会話型 UAT で構築した機能を検証。 | [commands/gsd/verify-work.md](../../commands/gsd/verify-work.md) |
+| `/gsd-ship` | 検証後に PR を作成し、レビューを実行してマージ準備を行う。 | [commands/gsd/ship.md](../../commands/gsd/ship.md) |
+| `/gsd-fast` | サブエージェントや計画オーバーヘッドなしに些細なタスクをインラインで実行。 | [commands/gsd/fast.md](../../commands/gsd/fast.md) |
+| `/gsd-quick` | GSD の保証（アトミックコミット、状態追跡）付きでクイックタスクを実行し、オプションのエージェントをスキップ。 | [commands/gsd/quick.md](../../commands/gsd/quick.md) |
+| `/gsd-ui-review` | 実装済みフロントエンドコードの 6 本柱ビジュアル監査を遡及的に実施。 | [commands/gsd/ui-review.md](../../commands/gsd/ui-review.md) |
+| `/gsd-code-review` | フェーズ中に変更されたソースファイルをバグ、セキュリティ、コード品質の問題についてレビュー。`--fix` で指摘を自動適用。 | [commands/gsd/code-review.md](../../commands/gsd/code-review.md) |
+| `/gsd-eval-review` | 実行済み AI フェーズの評価カバレッジを遡及監査し、EVAL-REVIEW.md を作成。 | [commands/gsd/eval-review.md](../../commands/gsd/eval-review.md) |
+
+### フェーズ & マイルストーン管理
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-phase` | フェーズの CRUD — ROADMAP.md でフェーズを追加（デフォルト）、挿入（`--insert`）、削除（`--remove`）、編集（`--edit`）。 | [commands/gsd/phase.md](../../commands/gsd/phase.md) |
+| `/gsd-add-tests` | UAT 基準と実装に基づいて完了したフェーズのテストを生成。 | [commands/gsd/add-tests.md](../../commands/gsd/add-tests.md) |
+| `/gsd-validate-phase` | 完了したフェーズの Nyquist バリデーションのギャップを遡及監査して埋める。 | [commands/gsd/validate-phase.md](../../commands/gsd/validate-phase.md) |
+| `/gsd-secure-phase` | 完了したフェーズの脅威への対策を遡及検証。 | [commands/gsd/secure-phase.md](../../commands/gsd/secure-phase.md) |
+| `/gsd-audit-milestone` | アーカイブ前に元の意図に対してマイルストーン完了を監査。 | [commands/gsd/audit-milestone.md](../../commands/gsd/audit-milestone.md) |
+| `/gsd-audit-uat` | 全未解決 UAT および検証項目のクロスフェーズ監査。 | [commands/gsd/audit-uat.md](../../commands/gsd/audit-uat.md) |
+| `/gsd-audit-fix` | 自律監査-修正パイプライン — 問題の発見、分類、修正、テスト、コミット。 | [commands/gsd/audit-fix.md](../../commands/gsd/audit-fix.md) |
+| `/gsd-complete-milestone` | 完了したマイルストーンをアーカイブし、次のバージョンに向けて準備。 | [commands/gsd/complete-milestone.md](../../commands/gsd/complete-milestone.md) |
+| `/gsd-new-milestone` | 新しいマイルストーンサイクルを開始 — PROJECT.md を更新して要件にルーティング。 | [commands/gsd/new-milestone.md](../../commands/gsd/new-milestone.md) |
+| `/gsd-milestone-summary` | マイルストーンアーティファクトから包括的なプロジェクトサマリーを生成。 | [commands/gsd/milestone-summary.md](../../commands/gsd/milestone-summary.md) |
+| `/gsd-cleanup` | 完了したマイルストーンから蓄積されたフェーズディレクトリをアーカイブ。 | [commands/gsd/cleanup.md](../../commands/gsd/cleanup.md) |
+| `/gsd-manager` | 1 つのターミナルから複数のフェーズを管理するインタラクティブなコマンドセンター。 | [commands/gsd/manager.md](../../commands/gsd/manager.md) |
+| `/gsd-workstreams` | 並列ワークストリームを管理 — list、create、switch、status、progress、complete、resume。 | [commands/gsd/workstreams.md](../../commands/gsd/workstreams.md) |
+| `/gsd-autonomous` | 残りのすべてのフェーズを自律的に実行 — フェーズごとに discuss → plan → execute。 | [commands/gsd/autonomous.md](../../commands/gsd/autonomous.md) |
+| `/gsd-undo` | 安全な git リバート — フェーズマニフェストを使ってフェーズまたはプランのコミットをロールバック。 | [commands/gsd/undo.md](../../commands/gsd/undo.md) |
+
+### セッション & ナビゲーション
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-progress` | プロジェクトの進捗を確認し、コンテキストを表示して次のアクションにルーティング。`--next` で自動進行、`--do` で自由形式タスクを実行。 | [commands/gsd/progress.md](../../commands/gsd/progress.md) |
+| `/gsd-capture` | アイデア、タスク、メモ、シードをキャプチャ — todo（デフォルト）、`--note`、`--backlog`、`--seed`、または `--list` で保留中の TODO を一覧表示。 | [commands/gsd/capture.md](../../commands/gsd/capture.md) |
+| `/gsd-stats` | プロジェクト統計を表示 — フェーズ、プラン、要件、git メトリクス、タイムライン。 | [commands/gsd/stats.md](../../commands/gsd/stats.md) |
+| `/gsd-pause-work` | フェーズ途中で作業を一時停止する際にコンテキスト引き継ぎを作成。 | [commands/gsd/pause-work.md](../../commands/gsd/pause-work.md) |
+| `/gsd-resume-work` | 完全なコンテキスト復元で前のセッションから作業を再開。 | [commands/gsd/resume-work.md](../../commands/gsd/resume-work.md) |
+| `/gsd-explore` | コミットする前にアイデアを考え抜くためのソクラテス的アイデア創出とアイデアルーティング。 | [commands/gsd/explore.md](../../commands/gsd/explore.md) |
+| `/gsd-review-backlog` | バックログアイテムをレビューしてアクティブなマイルストーンに昇格。 | [commands/gsd/review-backlog.md](../../commands/gsd/review-backlog.md) |
+| `/gsd-thread` | クロスセッション作業のための永続的なコンテキストスレッドを管理。 | [commands/gsd/thread.md](../../commands/gsd/thread.md) |
+
+### コードベースインテリジェンス
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-map-codebase` | 並列マッパーエージェントでコードベースを分析。`--fast` で軽量スキャン、`--query` でインテルクエリ。 | [commands/gsd/map-codebase.md](../../commands/gsd/map-codebase.md) |
+| `/gsd-graphify` | `.planning/graphs/` 内のプロジェクトナレッジグラフをビルド、クエリ、検査。 | [commands/gsd/graphify.md](../../commands/gsd/graphify.md) |
+| `/gsd-extract-learnings` | 完了したフェーズのアーティファクトから決定事項、教訓、パターン、驚きを抽出。 | [commands/gsd/extract-learnings.md](../../commands/gsd/extract-learnings.md) |
+
+### レビュー、デバッグ & リカバリー
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-review` | 外部 AI CLI からフェーズプランのクロス AI ピアレビューをリクエスト。 | [commands/gsd/review.md](../../commands/gsd/review.md) |
+| `/gsd-debug` | コンテキストリセット全体で永続的な状態を持つ体系的なデバッグ。 | [commands/gsd/debug.md](../../commands/gsd/debug.md) |
+| `/gsd-forensics` | 失敗した GSD ワークフローのポストモーテム調査 — git、アーティファクト、状態を分析。 | [commands/gsd/forensics.md](../../commands/gsd/forensics.md) |
+| `/gsd-health` | 計画ディレクトリの健全性を診断し、任意で問題を修復。 | [commands/gsd/health.md](../../commands/gsd/health.md) |
+| `/gsd-import` | プロジェクト決定に対する競合検出付きで外部プランをインジェスト。 | [commands/gsd/import.md](../../commands/gsd/import.md) |
+| `/gsd-inbox` | プロジェクトテンプレートに対してすべてのオープンな GitHub イシューと PR をトリアージおよびレビュー。 | [commands/gsd/inbox.md](../../commands/gsd/inbox.md) |
+
+### ドキュメント、プロファイル & ユーティリティ
+
+| コマンド | 役割 | ソース |
+|----------|------|--------|
+| `/gsd-docs-update` | コードベースに対して検証されたプロジェクトドキュメントを生成または更新。 | [commands/gsd/docs-update.md](../../commands/gsd/docs-update.md) |
+| `/gsd-ingest-docs` | リポジトリで混在した ADR/PRD/SPEC/DOC をスキャンし、分類・合成・競合レポートで `.planning/` セットアップをブートストラップまたはマージ。 | [commands/gsd/ingest-docs.md](../../commands/gsd/ingest-docs.md) |
+| `/gsd-profile-user` | 開発者の行動プロファイルと Claude が検出可能なアーティファクトを生成。 | [commands/gsd/profile-user.md](../../commands/gsd/profile-user.md) |
+| `/gsd-settings` | GSD ワークフロートグルとモデルプロファイルを設定。 | [commands/gsd/settings.md](../../commands/gsd/settings.md) |
+| `/gsd-config` | GSD 設定を構成 — ワークフロートグル（デフォルト）、高度なノブ（`--advanced`）、インテグレーション（`--integrations`）、またはモデルプロファイル（`--profile`）。 | [commands/gsd/config.md](../../commands/gsd/config.md) |
+| `/gsd-pr-branch` | `.planning/` コミットをフィルタリングしてクリーンな PR ブランチを作成。 | [commands/gsd/pr-branch.md](../../commands/gsd/pr-branch.md) |
+| `/gsd-surface` | サーフェスに出るスキルを切り替え — 再インストールなしでプロファイルを適用、一覧表示、またはクラスターを無効化。 | [commands/gsd/surface.md](../../commands/gsd/surface.md) |
+| `/gsd-update` | GSD を最新バージョンに更新。`--sync` でランタイム間でスキルを同期、`--reapply` でローカルパッチを再適用。 | [commands/gsd/update.md](../../commands/gsd/update.md) |
+| `/gsd-help` | 利用可能な GSD コマンドと使い方ガイドを表示。 | [commands/gsd/help.md](../../commands/gsd/help.md) |
+
+---
+
+## ワークフロー (88 shipped)
+
+完全な一覧は `get-shit-done/workflows/*.md` を参照してください。ワークフローはコマンドが内部で参照する薄いオーケストレーターです。ほとんどはエンドユーザーが直接読むものではありません。以下の行は各ワークフローファイルをその役割（`` ブロックから導出）と、該当する場合はそれを呼び出すコマンドにマッピングします。
+
+| ワークフロー | 役割 | 呼び出し元 |
+|-------------|------|-----------|
+| `add-backlog.md` | 999.x 番号付けを使って ROADMAP.md にバックログアイテムを追加。 | `/gsd-capture --backlog` |
+| `add-phase.md` | ロードマップの現在のマイルストーン末尾に新しい整数フェーズを追加。 | `/gsd-phase` (default) |
+| `add-tests.md` | フェーズのアーティファクトに基づいて完了したフェーズのユニットテストと E2E テストを生成。 | `/gsd-add-tests` |
+| `add-todo.md` | セッション中に浮上したアイデアやタスクを構造化された todo としてキャプチャ。 | `/gsd-capture` (default) |
+| `ai-integration-phase.md` | フレームワーク選択 → AI 調査 → ドメイン調査 → eval 計画を AI-SPEC.md に統合してオーケストレーション。 | `/gsd-ai-integration-phase` |
+| `analyze-dependencies.md` | ROADMAP.md のフェーズをファイル重複とセマンティックな依存関係について分析し、`Depends on` エッジを提案。 | `/gsd-manager --analyze-deps` |
+| `audit-fix.md` | 自律監査-修正パイプライン — 監査実行、解析、分類、修正、テスト、コミット。 | `/gsd-audit-fix` |
+| `audit-milestone.md` | フェーズ検証を集約してマイルストーンが完了の定義を満たしているか検証。 | `/gsd-audit-milestone` |
+| `audit-uat.md` | UAT と検証ファイルのクロスフェーズ監査。優先順位付けされた未解決項目リストを作成。 | `/gsd-audit-uat` |
+| `autonomous.md` | マイルストーンのフェーズを自律的に進行 — 残り全部、範囲指定、または単一フェーズ。 | `/gsd-autonomous` |
+| `check-todos.md` | 保留中の TODO を一覧表示し、選択を許可してコンテキストを読み込み、適切なアクションにルーティング。 | `/gsd-capture --list` |
+| `cleanup.md` | 完了したマイルストーンから蓄積されたフェーズディレクトリをアーカイブ。 | `/gsd-cleanup` |
+| `code-review-fix.md` | gsd-code-fixer を使って REVIEW.md の問題を修正ごとのアトミックコミットで自動修正。 | `/gsd-code-review --fix` |
+| `code-review.md` | gsd-code-reviewer でフェーズのソース変更をレビュー。REVIEW.md を作成。 | `/gsd-code-review` |
+| `complete-milestone.md` | 出荷されたバージョンを完了としてマーク — MILESTONES.md エントリー、PROJECT.md の進化、タグ。 | `/gsd-complete-milestone` |
+| `diagnose-issues.md` | 並列デバッグエージェントをオーケストレーションして UAT のギャップを調査し、根本原因を特定。 | `/gsd-verify-work` (auto-diagnosis) |
+| `discovery-phase.md` | 適切な深さレベルでディスカバリーを実行。 | `/gsd-new-project` (discovery path) |
+| `discuss-phase-assumptions.md` | 仮定モードの discuss — コードベースファーストの分析で実装決定を抽出。 | `/gsd-discuss-phase` (when `discuss_mode=assumptions`) |
+| `discuss-phase-power.md` | パワーユーザー discuss — すべての質問を JSON 状態ファイル + HTML UI に事前生成。 | `/gsd-discuss-phase --power` |
+| `discuss-phase.md` | 反復的なグレーゾーンの議論を通じて実装決定を抽出。 | `/gsd-discuss-phase` |
+| `mvp-phase.md` | フェーズを垂直 MVP スライスとして計画 — ユーザーストーリー、SPIDR 分割、その後 plan-phase。 | `/gsd-mvp-phase` |
+| `do.md` | ユーザーからの自由形式テキストを最も適合する GSD コマンドにルーティング。 | `/gsd-progress --do` |
+| `docs-update.md` | 正規のおよび手書きのプロジェクトドキュメントを生成、更新、検証。 | `/gsd-docs-update` |
+| `edit-phase.md` | ROADMAP.md の既存フェーズの任意フィールドを番号と位置を保ちながら編集。 | `/gsd-phase --edit` |
+| `eval-review.md` | 実装済み AI フェーズの評価カバレッジの遡及監査。 | `/gsd-eval-review` |
+| `execute-phase.md` | ウェーブベースの並列実行でフェーズのすべてのプランを実行。 | `/gsd-execute-phase` |
+| `execute-plan.md` | フェーズプロンプト（PLAN.md）を実行して成果サマリー（SUMMARY.md）を作成。 | `execute-phase.md` (per-plan subagent) |
+| `explore.md` | ソクラテス的アイデア創出 — 開発者を探索的な質問を通じてガイド。 | `/gsd-explore` |
+| `debug.md` | 体系的なデバッグ — サブコマンドルーティング、セッション作成、gsd-debug-session-manager への委任。 | `/gsd-debug` |
+| `extract-learnings.md` | 完了したフェーズのアーティファクトから決定事項、教訓、パターン、驚きを抽出。 | `/gsd-extract-learnings` |
+| `fast.md` | サブエージェントのオーバーヘッドなしに些細なタスクをインラインで実行。 | `/gsd-fast` |
+| `forensics.md` | 失敗したワークフローのフォレンジクス調査 — git、アーティファクト、状態分析。 | `/gsd-forensics` |
+| `graduation.md` | フェーズ横断で繰り返し出現する LEARNINGS.md アイテムをクラスタリングして HITL 昇格候補を浮き上がらせる。 | `transition.md` (graduation_scan step) |
+| `health.md` | `.planning/` ディレクトリの整合性を検証し、対処可能な問題を報告。 | `/gsd-health` |
+| `help.md` | 完全な GSD Core コマンドリファレンスを表示。 | `/gsd-help` |
+| `import.md` | 既存のプロジェクト決定に対する競合検出付きで外部プランをインジェスト。 | `/gsd-import` |
+| `inbox.md` | プロジェクトのコントリビューションテンプレートに対してオープンな GitHub イシューと PR をトリアージ。 | `/gsd-inbox` |
+| `ingest-docs.md` | リポジトリで混在した計画ドキュメントをスキャンし、分類・合成して `.planning/` に競合レポート付きでブートストラップまたはマージ。 | `/gsd-ingest-docs` |
+| `insert-phase.md` | マイルストーン途中で発見された緊急作業のために小数フェーズを挿入。 | `/gsd-phase --insert` |
+| `list-phase-assumptions.md` | 計画前にフェーズに関する Claude の仮定を浮き上がらせる。 | `/gsd-discuss-phase --assumptions` |
+| `list-workspaces.md` | `~/gsd-workspaces/` 内のすべての GSD ワークスペースをステータスとともに一覧表示。 | `/gsd-workspace --list` |
+| `manager.md` | インタラクティブなマイルストーンコマンドセンター — ダッシュボード、インライン discuss、バックグラウンド plan/execute。 | `/gsd-manager` |
+| `map-codebase.md` | 並列コードベースマッパーエージェントをオーケストレーションして `.planning/codebase/` ドキュメントを作成。 | `/gsd-map-codebase` |
+| `milestone-summary.md` | マイルストーンサマリー合成 — マイルストーンアーティファクトからオンボーディングとレビューアーティファクトを作成。 | `/gsd-milestone-summary` |
+| `new-milestone.md` | 新しいマイルストーンサイクルを開始 — プロジェクトコンテキストを読み込み、目標を収集して PROJECT.md/STATE.md を更新。 | `/gsd-new-milestone` |
+| `new-project.md` | 統合新プロジェクトフロー — 質問、調査（任意）、要件、ロードマップ。 | `/gsd-new-project` |
+| `new-workspace.md` | リポジトリのワークツリー/クローンと独立した `.planning/` を持つ独立したワークスペースを作成。 | `/gsd-workspace --new` |
+| `next.md` | 現在のプロジェクト状態を検出して次の論理的なステップに自動的に進む。 | `/gsd-progress --next` |
+| `node-repair.md` | タスク検証が失敗した場合の自律修復オペレーター。`execute-plan` から呼び出し。 | `execute-plan.md` (recovery) |
+| `note.md` | ゼロフリクションのアイデアキャプチャ — 1 回の Write 呼び出しと 1 行の確認。 | `/gsd-capture --note` |
+| `pause-work.md` | 構造化された `.planning/HANDOFF.json` と `.continue-here.md` 引き継ぎファイルを作成。 | `/gsd-pause-work` |
+| `plan-phase.md` | 統合された調査と検証ループを含む実行可能な PLAN.md ファイルを作成。 | `/gsd-plan-phase`, `/gsd-quick` |
+| `plan-review-convergence.md` | クロス AI プラン収束ループ — HIGH の懸念がなくなるまでレビューフィードバックで再計画。 | `/gsd-plan-review-convergence` |
+| `plant-seed.md` | 先見的なアイデアをトリガー条件付きの構造化されたシードファイルとしてキャプチャ。 | `/gsd-capture --seed` |
+| `pr-branch.md` | `.planning/` コミットをフィルタリングしてプルリクエスト用のクリーンなブランチを作成。 | `/gsd-pr-branch` |
+| `profile-user.md` | 完全な開発者プロファイリングフローをオーケストレーション — 同意、セッションスキャン、プロファイル生成。 | `/gsd-profile-user` |
+| `progress.md` | 進捗レンダリング — プロジェクトコンテキスト、位置、次のアクションルーティング。 | `/gsd-progress` |
+| `quick.md` | GSD の保証付きのクイックタスク実行（アトミックコミット、状態追跡）。 | `/gsd-quick` |
+| `reapply-patches.md` | GSD 更新後にローカルの変更を再適用。 | `/gsd-update --reapply` |
+| `remove-phase.md` | ロードマップから将来のフェーズを削除し、後続フェーズを振り直し。 | `/gsd-phase --remove` |
+| `remove-workspace.md` | GSD ワークスペースを削除してワークツリーをクリーンアップ。 | `/gsd-workspace --remove` |
+| `resume-project.md` | 作業を再開 — STATE.md、HANDOFF.json、アーティファクトから完全なコンテキストを復元。 | `/gsd-resume-work` |
+| `review.md` | 外部 CLI 経由のクロス AI プランレビュー。REVIEWS.md を作成。 | `/gsd-review` |
+| `scan.md` | 迅速な単一フォーカスのコードベーススキャン — map-codebase の軽量代替。 | `/gsd-map-codebase --fast` |
+| `secure-phase.md` | 完了したフェーズの遡及的な脅威対策監査。 | `/gsd-secure-phase` |
+| `session-report.md` | セッションレポート — トークン使用量、作業サマリー、成果。 | `/gsd-pause-work --report` |
+| `settings.md` | GSD ワークフロートグルとモデルプロファイルを設定。 | `/gsd-settings`, `/gsd-config --profile` |
+| `settings-advanced.md` | GSD パワーユーザーノブを設定 — プランバウンス、タイムアウト、ブランチテンプレート、クロス AI 実行、ランタイムノブ。 | `/gsd-config --advanced` |
+| `settings-integrations.md` | サードパーティ API キー（Brave/Firecrawl/Exa）、`review.models.` CLI ルーティング、`agent_skills.` インジェクションをマスク済み（`****`）表示で設定。 | `/gsd-config --integrations` |
+| `ship.md` | 検証後に PR を作成し、レビューを実行してマージ準備を行う。 | `/gsd-ship` |
+| `sketch.md` | 1 スケッチにつき 2〜3 バリアントの使い捨て HTML モックアップでデザインの方向性を探索。 | `/gsd-sketch` |
+| `sketch-wrap-up.md` | スケッチの調査結果を厳選して永続的な `sketch-findings-[project]` スキルとしてパッケージ化。 | `/gsd-sketch --wrap-up` |
+| `spec-phase.md` | 曖昧さスコアリング付きのソクラテス的仕様精緻化。SPEC.md を作成。 | `/gsd-spec-phase` |
+| `spike.md` | 集中した使い捨ての実験によって迅速に実現可能性を検証。 | `/gsd-spike` |
+| `spike-wrap-up.md` | スパイクの調査結果を厳選して永続的な `spike-findings-[project]` スキルとしてパッケージ化。 | `/gsd-spike --wrap-up` |
+| `stats.md` | プロジェクト統計レンダリング — フェーズ、プラン、要件、git メトリクス。 | `/gsd-stats` |
+| `sync-skills.md` | クロスランタイム GSD スキル同期 — ランタイムルート間で `gsd-*` スキルディレクトリを差分して適用。 | `/gsd-update --sync` |
+| `transition.md` | フェーズ境界遷移ワークフロー — ワークストリームチェック、状態進行。 | `execute-phase.md`, `/gsd-progress --next` |
+| `ui-phase.md` | gsd-ui-researcher で UI-SPEC.md デザインコントラクトを生成。 | `/gsd-ui-phase` |
+| `ui-review.md` | gsd-ui-auditor による遡及的な 6 本柱ビジュアル監査。 | `/gsd-ui-review` |
+| `ultraplan-phase.md` | [BETA] 計画を Claude Code の ultraplan クラウドにオフロードし、リモートで下書きして `/gsd-import` 経由でインポート。 | `/gsd-ultraplan-phase` |
+| `undo.md` | 安全な git リバート — フェーズマニフェストを使ってフェーズまたはプランのコミットをロールバック。 | `/gsd-undo` |
+| `thread.md` | クロスセッション作業のための永続的なコンテキストスレッドを作成、一覧表示、クローズ、または再開。 | `/gsd-thread` |
+| `update.md` | 変更履歴の表示付きで GSD を最新バージョンに更新。 | `/gsd-update` |
+| `validate-phase.md` | 完了したフェーズの Nyquist バリデーションのギャップを遡及監査して埋める。 | `/gsd-validate-phase` |
+| `verify-phase.md` | ゴール後退型分析によってフェーズ目標の達成を検証。 | `execute-phase.md` (post-execution) |
+| `verify-work.md` | 自動診断付きの会話型 UAT — UAT.md と修正プランを作成。 | `/gsd-verify-work` |
+
+> **注記:** 一部のワークフローには直接ユーザー向けのコマンドがありません（例: `execute-plan.md`、`verify-phase.md`、`transition.md`、`node-repair.md`、`diagnose-issues.md`）— これらはオーケストレーターワークフローによって内部的に呼び出されます。`discovery-phase.md` は `/gsd-new-project` の代替エントリーポイントです。
+
+---
+
+## リファレンス (62 shipped)
+
+完全な一覧は `get-shit-done/references/*.md` を参照してください。リファレンスはワークフローとエージェントが `@-reference` として参照する共有ナレッジドキュメントです。以下のグループ分けは [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md#references-get-shit-donereferencesmd) に対応します — コア、ワークフロー、思考モデルクラスター、モジュラープランナー分解。
+
+### コアリファレンス
+
+| リファレンス | 役割 |
+|-------------|------|
+| `checkpoints.md` | チェックポイントタイプの定義とインタラクションパターン。 |
+| `gates.md` | plan-checker と verifier に組み込まれた 4 つの標準ゲートタイプ（Confirm、Quality、Safety、Transition）。 |
+| `model-profiles.md` | エージェントごとのモデルティア割り当て。 |
+| `model-profile-resolution.md` | モデル解決アルゴリズムのドキュメント。 |
+| `verification-patterns.md` | 異なるアーティファクトタイプの検証方法。 |
+| `verification-overrides.md` | アーティファクトごとの検証オーバーライドルール。 |
+| `planning-config.md` | 完全な設定スキーマと動作。 |
+| `git-integration.md` | git コミット、ブランチ、履歴パターン。 |
+| `git-planning-commit.md` | 計画ディレクトリのコミット規約。 |
+| `questioning.md` | プロジェクト初期化のためのドリーム抽出哲学。 |
+| `tdd.md` | テスト駆動開発の統合パターン。 |
+| `ui-brand.md` | ビジュアル出力フォーマットパターン。 |
+| `common-bug-patterns.md` | コードレビューと検証のための一般的なバグパターン。 |
+| `debugger-philosophy.md` | `gsd-debugger` が読み込む常緑のデバッグ規律。 |
+| `mandatory-initial-read.md` | エージェントプロンプトに注入される共有の必読ボイラープレート。 |
+| `project-skills-discovery.md` | エージェントプロンプトに注入される共有のプロジェクトスキル検出ボイラープレート。 |
+
+### ワークフローリファレンス
+
+| リファレンス | 役割 |
+|-------------|------|
+| `agent-contracts.md` | オーケストレーターとエージェント間の正式なインターフェース。 |
+| `context-budget.md` | コンテキストウィンドウバジェット割り当てルール。 |
+| `continuation-format.md` | セッション継続/再開フォーマット。 |
+| `domain-probes.md` | discuss-phase 向けのドメイン固有のプロービング質問。 |
+| `gate-prompts.md` | ゲート/チェックポイントのプロンプトテンプレート。 |
+| `scout-codebase.md` | discuss-phase スカウトステップ向けのフェーズタイプ→コードベースマップ選択テーブル（#2551 で抽出）。 |
+| `revision-loop.md` | プラン修正の反復パターン。 |
+| `universal-anti-patterns.md` | 検出して避けるべきユニバーサルアンチパターン。 |
+| `worktree-path-safety.md` | ワークツリーガードスイート: HEAD アサーション、cwd ドリフトセンチネル（ステップ 0a、#3097）、絶対パスガード（ステップ 0b、#3099）— `` 経由でエグゼキュータースポーンプロンプトに読み込まれる。 |
+| `artifact-types.md` | 計画アーティファクトタイプの定義。 |
+| `phase-argument-parsing.md` | フェーズ引数の解析規約。 |
+| `decimal-phase-calculation.md` | 小数サブフェーズの番号付けルール。 |
+| `workstream-flag.md` | ワークストリームアクティブポインター規約（`--ws`）。 |
+| `user-profiling.md` | ユーザー行動プロファイリングの検出ヒューリスティック。 |
+| `thinking-partner.md` | 意思決定ポイントでの条件付き思考パートナー起動。 |
+| `autonomous-smart-discuss.md` | 自律モード向けのスマート discuss ロジック。 |
+| `ios-scaffold.md` | iOS アプリケーションスキャフォールディングパターン。 |
+| `ai-evals.md` | `/gsd-ai-integration-phase` 向けの AI 評価設計リファレンス。 |
+| `ai-frameworks.md` | `gsd-framework-selector` 向けの AI フレームワーク決定マトリクスリファレンス。 |
+| `executor-examples.md` | gsd-executor エージェントの実例。 |
+| `doc-conflict-engine.md` | ingest/import ワークフロー向けの共有競合検出コントラクト。 |
+| `execute-mvp-tdd.md` | MVP+TDD での execute-phase のランタイムゲートセマンティクス — タスク前の失敗テスト検証、フェーズ末尾のブロッキングレビュー。 |
+| `mvp-concepts.md` | 6 つの MVP 関連リファレンスファイルのクロスリファレンスインデックス。各ファイルの目的とどのワークフローが読み込むかをマッピング。 |
+| `verify-mvp-mode.md` | MVP モードフェーズの UAT フレーミングルール — ユーザーフローファーストの順序、延期された技術チェック、ユーザーストーリーフォーマットガード。 |
+
+### スケッチリファレンス
+
+`/gsd-sketch` ワークフローとその wrap-up コンパニオンが使用するリファレンス。
+
+| リファレンス | 役割 |
+|-------------|------|
+| `sketch-interactivity.md` | HTML スケッチをインタラクティブで生き生きとさせるためのルール。 |
+| `sketch-theme-system.md` | クロススケッチの一貫性のための共有 CSS テーマ変数システム。 |
+| `sketch-tooling.md` | すべてのスケッチに含まれるフローティングツールバーユーティリティ。 |
+| `sketch-variant-patterns.md` | マルチバリアント HTML パターン（タブ、並排表示、オーバーレイ）。 |
+
+### 思考モデルリファレンス
+
+思考クラスモデル（o3、o4-mini、Gemini 2.5 Pro）を GSD ワークフローに統合するためのリファレンス。
+
+| リファレンス | 役割 |
+|-------------|------|
+| `thinking-models-debug.md` | デバッグワークフロー向けの思考モデルパターン。 |
+| `thinking-models-execution.md` | 実行エージェント向けの思考モデルパターン。 |
+| `thinking-models-planning.md` | 計画エージェント向けの思考モデルパターン。 |
+| `thinking-models-research.md` | 調査エージェント向けの思考モデルパターン。 |
+| `thinking-models-verification.md` | 検証エージェント向けの思考モデルパターン。 |
+
+### モジュラープランナー分解
+
+`gsd-planner` エージェントは、ランタイムの文字数制限に収めるためにコアエージェントとリファレンスモジュールに分解されます。
+
+| リファレンス | 役割 |
+|-------------|------|
+| `planner-antipatterns.md` | プランナーのアンチパターンと具体性の例。 |
+| `planner-chunked.md` | チャンクモードの戻り形式（`## OUTLINE COMPLETE`、`## PLAN COMPLETE`）— Windows stdio ハングの緩和策。 |
+| `planner-gap-closure.md` | ギャップクロージャーモードの動作（VERIFICATION.md を読み込み、ターゲットを絞った再計画）。 |
+| `planner-reviews.md` | クロス AI レビュー統合（`/gsd-review` からの REVIEWS.md を読み込み）。 |
+| `planner-revision.md` | 反復的な精緻化のためのプラン修正パターン。 |
+| `planner-source-audit.md` | プランナーのソース監査と権威制限ルール。 |
+| `planner-mvp-mode.md` | MVP モード向けの垂直スライス計画ルール。 |
+| `planner-human-verify-mode.md` | `workflow.human_verify_mode = end-of-phase` のルール: `checkpoint:human-verify` タスク発行を抑制し、延期された項目を `` 経由でルーティング。 |
+| `planner-graphify-auto-update.md` | `load_graph_context` が既存の鮮度アノテーションに加えて `.last-build-status.json` の自動更新状態（running / failed / stale head）をどのように表示するか。`graphify.auto_update` でオプトイン（#3347）。 |
+| `planner-interface-context.md` | エグゼキューター向けのインターフェースコンテキストルール — 既存コードから主要なインターフェース/型/エクスポートを抽出する方法と、下流のプランが使用する新しいインターフェースのドキュメント化方法。 |
+| `skeleton-template.md` | 新プロジェクトのウォーキングスケルトン（フェーズ 1 + `--mvp`）用に出力される SKELETON.md テンプレート。 |
+| `user-story-template.md` | MVP 計画向けのユーザーストーリーフォーマット — "As a / I want to / So that" の構造化フィールド。 |
+| `spidr-splitting.md` | MVP モードで大きなユーザーストーリーを処理するための SPIDR 分割ルール。 |
+
+> **サブディレクトリ:** `get-shit-done/references/few-shot-examples/` には、特定のエージェントから参照される追加のフューショット例（`plan-checker.md`、`verifier.md`）が含まれます。これらは 62 のトップレベルリファレンスにはカウントされません。
+
+---
+
+## CLI モジュール (81 shipped)
+
+完全な一覧: `get-shit-done/bin/lib/*.cjs`。
+
+| モジュール | 責務 |
+|-----------|------|
+| `active-workstream-store.cjs` | ワークストリームソースの優先度と選択（CLI `--ws` > `GSD_WORKSTREAM` 環境変数 > 保存済みポインター）、名前のバリデーションと環境への伝播 |
+| `adr-parser.cjs` | plan-phase インジェストエクスプレスパス向けの ADR 決定パーサー。セクションの同義語を正規化し、ステータス/決定/スコープフェンスを解析して、ステータス拒否ゲートを適用 |
+| `agent-command-router.cjs` | `gsd-tools agent` 向けの薄い CJS サブコマンドルーターアダプター |
+| `artifacts.cjs` | 標準的なアーティファクトレジストリ — 既知の `.planning/` ルートファイル名。`gsd-health` W019 リントで使用 |
+| `audit.cjs` | 監査ディスパッチ、監査オープンセッション、監査ストレージヘルパー |
+| `check-command-router.cjs` | `gsd-tools check` 向けの薄い CJS サブコマンドルーターアダプター |
+| `cjs-command-router-adapter.cjs` | マニフェストバックの CJS コマンドファミリールーター向けの共有互換アダプター |
+| `clock.cjs` | 決定論的なロックテスト向けの注入可能なクロックシーム（now/sleep） |
+| `clusters.cjs` | ランタイムサーフェスモジュール向けのスキルクラスター定義（ADR-0011 フェーズ 2） |
+| `code-review-flags.cjs` | `/gsd:code-review` 向けの型付きフラグパーサー。`parseCodeReviewFlags(argv)`（→ `{ fix, all, auto, depth, files }`）と `resolveCodeReviewWorkflow(flags)`（→ `'code-review.md' \| 'code-review-fix.md'`）をエクスポート。`--fix`/`--all`/`--auto` ルーティングの標準ディスパッチシーム |
+| `command-aliases.cjs` | マニフェストバックのファミリールーター向けのエイリアス/サブコマンドメタデータ |
+| `command-arg-projection.cjs` | コマンドファミリールーター間で共有される型付きフラグと位置引数のプロジェクションヘルパー |
+| `command-routing-hub.cjs` | すべてのコマンドファミリールーターのモード決定（SDK vs CJS）、エラー分類、ノースロー契約を一元化する純粋結果ディスパッチハブ（#3788） |
+| `commands.cjs` | その他の CLI コマンド（slug、タイムスタンプ、TODO、スキャフォールディング、統計） |
+| `config-schema.cjs` | `VALID_CONFIG_KEYS` と動的キーパターンの単一ソース。バリデーターと config-schema-docs パリティテストの両方でインポートされる |
+| `config.cjs` | `config.json` の読み書き、セクション初期化。`config-schema.cjs` からバリデーターをインポート |
+| `config-types.cjs` | `model_policy` 設定ブロックの TypeScript 型定義 — `ModelPolicyConfig`、`TierEntry`、`RuntimeTiers`。発行時に `src/config-types.cts` からコンパイル（ADR-457） |
+| `configuration.cjs` | 設定モジュール — 標準的な設定読み込み、レガシーキー正規化、デフォルトマージ、明示的なディスク上のマイグレーション。SDK と CJS 両方のコンシューマーの信頼できるソース |
+| `context-utilization.cjs` | `gsd-health --context` 向けの純粋なクラシファイアー — （tokensUsed, contextWindow）を 60%/70% の骨折点閾値に対する `{ percent, state }` トリアージ結果に変換（#2792） |
+| `core.cjs` | エラー処理、出力フォーマット、共通ユーティリティ、ランタイムフォールバック。planning-workspace ヘルパーの互換性再エクスポート |
+| `decisions.cjs` | CONTEXT.md の `` ブロックを解析。数値（D-42）と英数字（D-INFRA-01）の ID を受け付け。`{id, text, category, tags, trackable}` を返す |
+| `docs.cjs` | docs-update ワークフロー初期化、Markdown スキャン、モノリポ検出 |
+| `drift.cjs` | 実行後のコードベース構造ドリフト検出器（#2003）: ファイル変更を new-dir/barrel/migration/route カテゴリに分類し、`last_mapped_commit` フロントマターをラウンドトリップ |
+| `fallow-runner.cjs` | `/gsd-code-review` 向けのファロー監査アダプター: バイナリ解決（`PATH` 次に `node_modules/.bin`）、アクション可能なバイナリ欠落エラー、構造的な調査結果の正規化 |
+| `frontmatter.cjs` | YAML フロントマター CRUD 操作 |
+| `gap-checker.cjs` | 計画後のギャップ分析（#2493）: REQUIREMENTS.md + CONTEXT.md 決定事項 vs PLAN.md カバレッジレポート（`gsd-tools gap-analysis`）の統合 |
+| `graphify.cjs` | `/gsd-graphify` 向けのナレッジグラフビルド/クエリ/ステータス/差分 |
+| `gsd2-import.cjs` | `/gsd-import --from-gsd2` 向けの外部プランインジェスト |
+| `init-command-router.cjs` | `gsd-tools init` 向けの薄い CJS サブコマンドルーターアダプター |
+| `init.cjs` | 各ワークフロータイプの複合コンテキスト読み込み |
+| `install-profiles.cjs` | `--minimal` インストール向けのインストールプロファイル許可リスト + スキルステージング（#2762）。どの `gsd-*` スキル/エージェントがランタイム設定ディレクトリに配置されるかの単一ソース |
+| `installer-migration-authoring.cjs` | レコードメタデータ、明示的スコープ、所有権の証拠、ランタイムコントラクト引用のインストーラーマイグレーション作成ガードレール |
+| `installer-migration-report.cjs` | インストール/更新統合向けのインストーラーマイグレーションレポートプロジェクションとブロックアクションガード |
+| `installer-migrations.cjs` | インストーラーマイグレーション計画、アーティファクト分類、インストール状態の永続化、ジャーナル化された適用、ロールバックヘルパー |
+| `intel.cjs` | `/gsd-map-codebase --query` と `gsd-intel-updater` を支えるコードベースインテルストア |
+| `learnings.cjs` | `/gsd-extract-learnings` 向けのクロスフェーズ学習抽出 |
+| `milestone.cjs` | マイルストーンアーカイブ、要件マーキング |
+| `model-catalog.cjs` | 共有モデルカタログ JSON の CJS アダプター。すべての CLI コンシューマーの標準ランタイムティアデフォルト、エージェントプロファイルマップ、エイリアスマップ、ルーティングメタデータをエクスポート |
+| `model-profiles.cjs` | `model-catalog.cjs` から派生した後方互換プロファイルヘルパー。独自のモデルテーブルは持たない |
+| `package-identity.cjs` | GSD の公開パッケージ座標（npm 名、bin 名、リポジトリスラッグ、変更履歴 URL、手動インストールコマンド）の生成された単一ソース。package.json から導出。更新ワーカー、`check-latest-version`、インストーラーが読み込む（#498） |
+| `phase-command-router.cjs` | `gsd-tools phase` 向けの薄い CJS サブコマンドルーターアダプター |
+| `phase-lifecycle.cjs` | フェーズライフサイクル SDK ハンドラーから抽出された純粋計算フェーズライフサイクルヘルパー |
+| `phase.cjs` | フェーズディレクトリ操作、小数番号付け、プランインデックス化 |
+| `phases-command-router.cjs` | `gsd-tools phases` 向けの薄い CJS サブコマンドルーターアダプター |
+| `plan-scan.cjs` | フラットおよびネストされたレイアウトでプランとサマリーファイルを検出するための標準フェーズプランスキャナー（k014） |
+| `planning-workspace.cjs` | 計画パス/ワークストリームシーム（`planningDir`、`planningPaths`、アクティブワークストリームルーティング、`.planning/.lock` オーケストレーション） |
+| `project-root.cjs` | 4 つのヒューリスティック（独自の `.planning/` ガード、`sub_repos` 設定、`multiRepo` フラグ、`.git` ヒューリスティック）を使って開始ディレクトリからプロジェクトルートを解決 |
+| `profile-output.cjs` | プロファイルレンダリング、USER-PROFILE.md と dev-preferences.md の生成 |
+| `profile-pipeline.cjs` | ユーザー行動プロファイリングデータパイプライン、セッションファイルスキャン |
+| `prompt-budget.cjs` | レビュープロンプト向けの純粋なトークンバジェット計算 — トークンを見積もり、決定論的なトリム優先度を適用（PROJECT.md の head 縮小、比例プラン切り捨て、コンテキスト/調査/要件の削除、ハードフェイルガード）。`review.max_prompt_tokens` 向けの構造化メタデータを返す（#3081） |
+| `review-reviewer-selection.cjs` | `/gsd-review` デフォルトレビュアーポリシーと優先度向けのレビュアー選択/正規化ヘルパー |
+| `roadmap-command-router.cjs` | `gsd-tools roadmap` 向けの薄い CJS サブコマンドルーターアダプター |
+| `roadmap-upgrade.cjs` | レガシーの `Phase N` エントリーをマイルストーンプレフィックス付きの `Phase M-NN` 規約に変換するマイグレーションツール。`computeMigrationPlan` + `applyMigration`（デフォルトのドライランとアトミックロールバック付き） |
+| `roadmap.cjs` | ROADMAP.md 解析、フェーズ抽出、プラン進捗 |
+| `runtime-artifact-layout.cjs` | ランタイムアーティファクトレイアウトモジュール — サポートされている各ランタイムのアーティファクトディレクトリ形状（コマンド、エージェント、スキル）を解決。ランタイムごとのアーティファクト配置の単一ソース（#3663） |
+| `runtime-name-policy.cjs` | ランタイム名正規化ポリシー — パス構築と表示に使用されるランタイム識別子の標準トークンサニタイゼーション |
+| `runtime-homes.cjs` | 標準ランタイム → グローバル設定/スキルディレクトリマッピング。Hermes ネストレイアウトと Cline ルールベース除外を含む全 15 ランタイムの一流サポート（#3126） |
+| `runtime-slash.cjs` | ランタイム対応スラッシュコマンドフォーマッター — ユーザー向け出力と永続化されたアーティファクトで `/gsd-`（スキルベースのランタイム）と `$gsd-`（codex）を出力する単一ソース（#3584） |
+| `schema-detect.cjs` | ORM パターンのスキーマドリフト検出（Prisma、Drizzle、Supabase、TypeORM、Payload）。`detectSchemaFiles`、`detectSchemaOrm`、`checkSchemaDrift`、`SCHEMA_PATTERNS`、`ORM_INFO` をエクスポート |
+| `secrets.cjs` | インテグレーションキー向けのシークレット設定マスキング規約（`****`）。`SECRET_CONFIG_KEYS`、`isSecretKey`、`maskSecret`、`maskIfSecret` をエクスポート |
+| `semver-compare.cjs` | 共有 semver 比較ポリシーヘルパー（`compareSemverCore`、stable-triplet バリデーション、正規化タプル解析）。更新チェックフック、statusline dev-install 検出、changeset 抽出範囲ロジックで使用（#10） |
+| `security.cjs` | パストラバーサル防止、プロンプトインジェクション検出、安全な JSON/シェルヘルパー |
+| `shell-command-projection.cjs` | マネージドフック直列化のためのランタイム対応シェルコマンドプロジェクション: ランタイム/プラットフォームによる PowerShell コールオペレーターの使用を決定し、Windows スクリプトパストークンを正規化 |
+| `state-command-router.cjs` | `gsd-tools state` 向けの薄い CJS サブコマンドルーターアダプター |
+| `state.cjs` | STATE.md 解析、更新、進行、メトリクス |
+| `state-document.cjs` | 純粋な STATE.md フィールド抽出、置換、ステータス正規化、進捗計算トランスフォーム |
+| `surface.cjs` | ランタイムサーフェスモジュール — インストール時プロファイルマーカーとは独立してランタイムの有効/無効サーフェス状態を管理（ADR-0011 フェーズ 2） |
+| `task-command-router.cjs` | `gsd-tools task` 向けの薄い CJS サブコマンドルーターアダプター |
+| `template.cjs` | 変数置換によるテンプレート選択と穴埋め |
+| `uat.cjs` | UAT ファイル解析、検証負債追跡、audit-uat サポート |
+| `ui-safety-gate.cjs` | シェルフリーのワード境界 UI トークン検出器（#3706、#3718）。フェーズセクションテキストを標準入力から読み込み、0（UI 発見）または 1（UI なし）で終了。GSD インストーラーが `$RUNTIME_DIR` に配布するために `get-shit-done/bin/lib/` にもデプロイ（#448） |
+| `update-context.cjs` | `/gsd:update` 向けの純粋なインストールコンテキストリゾルバー — ランタイム/スコープ/設定ディレクトリ/バージョン検出（LOCAL/GLOBAL/UNKNOWN）。update.md bash からポート。`gsd-tools update-context` を支える（#498） |
+| `validate-command-router.cjs` | `gsd-tools validate` 向けの薄い CJS サブコマンドルーターアダプター |
+| `validate.cjs` | 純粋なフェーズバリアント正規化ヘルパー（`phaseVariants`、`buildRoadmapPhaseVariants`、`buildNotStartedPhaseVariants`）。`verify.cjs` の W006/W007 チェックで使用。I/O なし、非同期なし |
+| `verify-command-router.cjs` | `gsd-tools verify` 向けの薄い CJS サブコマンドルーターアダプター |
+| `verify.cjs` | プラン構造、フェーズ完全性、参照、コミットバリデーション |
+| `workstream-inventory-builder.cjs` | 純粋なワークストリームインベントリプロジェクションビルダー |
+| `workstream-inventory.cjs` | 共有ワークストリームインベントリプロジェクション: 状態フィールド、フェーズ/プラン/サマリーカウント、ロードマップフェーズカウント、アクティブマーカー — 純粋なプロジェクションを `workstream-inventory-builder.cjs` に委任する薄いオーケストレーター |
+| `workstream-name-policy.cjs` | 標準ワークストリーム名バリデーション（`isValidActiveWorkstreamName`、`hasInvalidPathSegment`、`validateWorkstreamName`）とスラッグ正規化（`toWorkstreamSlug`） |
+| `workstream.cjs` | ワークストリーム CRUD、マイグレーション、セッションスコープのアクティブポインター |
+| `worktree-safety.cjs` | ワークツリールート解決と非破壊的プルーンポリシー決定。W017 ヘルスチェックロジックを所有 |
+
+[`docs/CLI-TOOLS.md`](../CLI-TOOLS.md) はこれらのモジュールのサブセットを説明している場合があります。ファイルシステムと異なる場合は、このテーブルとディレクトリ一覧が正式です。
+
+---
+
+## フック (14 shipped)
+
+完全な一覧: `hooks/`。
+
+| フック | イベント | 目的 |
+|--------|---------|------|
+| `gsd-statusline.js` | `statusLine` | モデル、タスク、ディレクトリ、コンテキスト使用率を表示 |
+| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | 残量 35%/25% でエージェント向けコンテキスト警告を注入 |
+| `gsd-check-update.js` | `SessionStart` | 新しい GSD バージョンのバックグラウンドチェック |
+| `gsd-check-update-worker.js` | (worker) | check-update のバックグラウンドワーカーヘルパー |
+| `gsd-update-banner.js` | `SessionStart` | GSD statusline を使用していない場合に更新の可用性を表示するオプトインバナー（PR #2795） |
+| `gsd-prompt-guard.js` | `PreToolUse` | `.planning/` への書き込みのプロンプトインジェクションパターンをスキャン（アドバイザリー） |
+| `gsd-workflow-guard.js` | `PreToolUse` | GSD ワークフローコンテキスト外のファイル編集を検出（アドバイザリー、オプトイン） |
+| `gsd-read-guard.js` | `PreToolUse` | 未読ファイルへの Edit/Write を防ぐアドバイザリーガード |
+| `gsd-read-injection-scanner.js` | `PostToolUse` | ツール Read 結果のプロンプトインジェクションパターンをスキャン（v1.36+、PR #2201） |
+| `gsd-worktree-path-guard.js` | `PreToolUse` | ワークツリールート外の絶対パスを持つ Edit/Write/MultiEdit をハードブロック（PR #579、#260） |
+| `gsd-session-state.sh` | `PostToolUse` | シェルベースランタイム向けのセッション状態追跡 |
+| `gsd-validate-commit.sh` | `PostToolUse` | Conventional Commit 適用のためのコミットバリデーション |
+| `gsd-phase-boundary.sh` | `PostToolUse` | ワークフロー遷移のためのフェーズ境界検出 |
+| `gsd-graphify-update.sh` | `PostToolUse` | メイン HEAD が進んだ後にナレッジグラフを自動再ビルド（オプトイン、デフォルトオフ — #3347） |
+
+---
+
+## メンテナンス
+
+- 新しいコマンド、エージェント、ワークフロー、リファレンス、CLI モジュール、またはフックが出荷される際は、リリース前に対応するセクションをここで更新してください。
+- `tests/` 配下のドリフトガードテスト（上記「このファイルの使い方」を参照）は、出荷されたすべてのファイルがこのインベントリに列挙されていることをアサートします。対応する行のない新しいファイルは CI で失敗します。
+- ファイルシステムが `docs/ARCHITECTURE.md` の数値や厳選されたサブセットドキュメント（例: `docs/AGENTS.md` のプライマリロスター）と乖離した場合は、このファイルが正式なソースです。
+
+## Related
+
+- [Commands](COMMANDS.md) — ユーザー向けコマンドリファレンス
+- [Architecture](ARCHITECTURE.md) — サーフェスがどのように組み合わさるか
+- [docs index](README.md)
diff --git a/docs/ja-JP/README.md b/docs/ja-JP/README.md
index 18e05cab1..96a7174da 100644
--- a/docs/ja-JP/README.md
+++ b/docs/ja-JP/README.md
@@ -1,27 +1,69 @@
# GSD Core ドキュメント
-GSD Core（Git. Ship. Done.）の包括的なドキュメントです。GSD Core は、AI コーディングエージェント向けのメタプロンプティング、コンテキストエンジニアリング、仕様駆動開発システムです。
+ドキュメントは 4 つの象限で構成されています。**チュートリアル**は実践で学ぶ、**ハウツーガイド**は特定のタスクを解決する、**リファレンス**は信頼できる情報を示す、**解説**はコンセプトと設計上の決定を探求する。
-## ドキュメント一覧
+言語バージョン: [English](../) · [Português (pt-BR)](../pt-BR/README.md) · **日本語** · [简体中文](../zh-CN/README.md) · [한국어](../ko-KR/README.md)
-| ドキュメント | 対象読者 | 説明 |
-|------------|---------|------|
-| [アーキテクチャ](ARCHITECTURE.md) | コントリビューター、上級ユーザー | システムアーキテクチャ、エージェントモデル、データフロー、内部設計 |
-| [機能リファレンス](FEATURES.md) | 全ユーザー | 全機能の詳細ドキュメントと要件 |
-| [コマンドリファレンス](COMMANDS.md) | 全ユーザー | 全コマンドの構文、フラグ、オプション、使用例 |
-| [設定リファレンス](CONFIGURATION.md) | 全ユーザー | 設定スキーマ、ワークフロートグル、モデルプロファイル、Git ブランチ |
-| [CLI ツールリファレンス](CLI-TOOLS.md) | コントリビューター、エージェント作成者 | CJS `gsd-tools.cjs` と `gsd-tools.cjs query` 가이드 のガイド |
-| [エージェントリファレンス](AGENTS.md) | コントリビューター、上級ユーザー | 全18種の専門エージェント — 役割、ツール、スポーンパターン |
-| [ユーザーガイド](USER-GUIDE.md) | 全ユーザー | ワークフローのウォークスルー、トラブルシューティング、リカバリー |
-| [コンテキストモニター](context-monitor.md) | 全ユーザー | コンテキストウィンドウ監視フックのアーキテクチャ |
-| [ディスカスモード](workflow-discuss-mode.md) | 全ユーザー | discuss フェーズにおける assumptions モードと interview モード |
+---
-## クイックリンク
+## チュートリアル
-- **v1.39 の新機能:** `--minimal` インストールプロファイル（≥94% コールドスタート削減）、`/gsd-phase --edit`、マージ後ビルド & テストゲート、`review.models.` ランタイム別レビューモデル、ワークストリーム設定の継承、手動カナリアリリースワークフロー、スキル統合（86 → 59）
-- **はじめに:** [README](../README.md) → インストール → `/gsd-new-project`
-- **ワークフロー完全ガイド:** [ユーザーガイド](USER-GUIDE.md)
-- **コマンド一覧:** [コマンドリファレンス](COMMANDS.md)
-- **GSD の設定:** [設定リファレンス](CONFIGURATION.md)
-- **システム内部の仕組み:** [アーキテクチャ](ARCHITECTURE.md)
-- **コントリビュートや拡張:** [CLI ツールリファレンス](CLI-TOOLS.md) + [エージェントリファレンス](AGENTS.md)
+- [はじめてのプロジェクト](tutorials/your-first-project.md) — インストールから最初のフェーズ出荷まで、確実な一本道
+- [既存コードベースのオンボーディング](tutorials/onboarding-an-existing-codebase.md) — ブラウンフィールドのリポジトリに GSD Core を導入する
+
+---
+
+## How-to guides
+
+- [ランタイムへのインストール](how-to/install-on-your-runtime.md) — サポートされる全 15 ランタイムのランタイム別インストール手順
+- [フェーズを議論する](how-to/discuss-a-phase.md) — 計画を始める前に実装上の決定事項を記録する
+- [フェーズを計画する](how-to/plan-a-phase.md) — リサーチを実行し、作業を分解し、計画の品質を検証する
+- [フェーズを実行する](how-to/execute-a-phase.md) — 新鮮なコンテキストのサブエージェントで並列ウェーブとして計画を実行する
+- [検証と出荷](how-to/verify-and-ship.md) — 完成した作業を確認し、障害を診断し、PR を作成する
+- [フェーズを自律的に実行する](how-to/run-phases-autonomously.md) — 無人フェーズ実行に自律モードを使用する
+- [クイックおよびファストタスクを処理する](how-to/handle-quick-and-fast-tasks.md) — フェーズループ外のアドホック作業に `/gsd-quick` と `/gsd-fast` を使用する
+- [モデルプロファイルを設定する](how-to/configure-model-profiles.md) — クオリティ・バランス・バジェットのモデルティア間を切り替える
+- [クロス AI レビューをセットアップする](how-to/set-up-cross-ai-review.md) — プライマリエージェントが生成したコードをレビューする 2 番目の AI を設定する
+- [ワークストリームで並列作業する](how-to/work-in-parallel-with-workstreams.md) — ワークストリームを使って独立した作業ラインを同時に実行する
+- [ワークスペースで作業を隔離する](how-to/isolate-work-with-workspaces.md) — ワークスペースを使って実験的またはリスクのある変更をサンドボックス化する
+- [失敗した実行をデバッグする](how-to/debug-a-failed-execution.md) — 壊れたまたは不完全なフェーズ実行を診断・回復する
+- [スパイクとスケッチ](how-to/spike-and-sketch.md) — 計画を確定する前の探索的作業に `/gsd-spike` と `/gsd-sketch` を使用する
+- [UI フェーズを設計する](how-to/design-a-ui-phase.md) — フロントエンドおよびビジュアル作業に UI フェーズループを使用する
+- [トラッカーイシューから GSD を動かす](how-to/drive-gsd-from-a-tracker-issue.md) — GitHub、Linear、または Jira のイシューからフェーズを開始する
+- [GSD 2 から移行する](how-to/migrate-from-gsd-2.md) — 既存の GSD 2 プロジェクトを GSD Core にアップグレードする
+- [GSD をアップデートする](how-to/update-gsd.md) — インストーラーを再実行して最新リリースを取得する
+- [回復とトラブルシューティング](how-to/recover-and-troubleshoot.md) — よくある問題を修正し、コンテキストを再構築し、アンインストールする
+
+---
+
+## リファレンス
+
+- [コマンド](COMMANDS.md) — フラグと例を含むすべてのコマンド
+- [設定](CONFIGURATION.md) — 完全な設定スキーマ、モデルプロファイル、Git ブランチ戦略
+- [CLI ツール](CLI-TOOLS.md) — ワークフローとエージェント向け `gsd-tools.cjs` プログラマティック API
+- [機能](FEATURES.md) — 完全な機能インデックス
+- [インベントリ](INVENTORY.md) — インストール済みスキルとサーフェスマップ
+- [STATE.md スキーマ](reference/state-md.md) — `.planning/STATE.md` のフィールド別リファレンス
+- [CONTEXT.md スキーマ](reference/context-md.md) — `.planning/phases//CONTEXT.md` のフィールド別リファレンス
+- [PLAN.md スキーマ](reference/plan-md.md) — `.planning/phases//PLAN.md` のフィールド別リファレンス
+- [計画アーティファクト](reference/planning-artifacts.md) — すべての `.planning/` ファイルとその役割
+
+---
+
+## 解説
+
+- [コンテキストエンジニアリング](explanation/context-engineering.md) — コンテキストの腐敗がどのように形成され、GSD Core がどのように防ぐか
+- [フェーズループ](explanation/the-phase-loop.md) — Discuss → Plan → Execute → Verify → Ship サイクルの設計理念
+- [マルチエージェントオーケストレーション](explanation/multi-agent-orchestration.md) — サブエージェントがどのように生成・スコープ設定・調整されるか
+- [セキュリティモデル](explanation/security-model.md) — 信頼境界、パーミッション、安全な自動化
+- [アーキテクチャ](ARCHITECTURE.md) — システムアーキテクチャ、エージェントモデル、データフロー
+- [ディスカスモード](workflow-discuss-mode.md) — `/gsd-discuss-phase` の assumptions モードと interview モード
+- [コンテキストモニタリング](context-monitor.md) — コンテキストウィンドウ監視フックのアーキテクチャ
+- [イシュー駆動オーケストレーション](issue-driven-orchestration.md) — 既存のプリミティブを使ってトラッカーイシューから GSD を動かすレシピ
+
+---
+
+## Related
+
+- [ルート README](../README.md) — ランディングページ、クイックスタート、ドキュメント概要
+- [変更履歴](../../CHANGELOG.md) — リリース履歴
diff --git a/docs/ja-JP/USER-GUIDE.md b/docs/ja-JP/USER-GUIDE.md
index c6ef424b5..0982dce70 100644
--- a/docs/ja-JP/USER-GUIDE.md
+++ b/docs/ja-JP/USER-GUIDE.md
@@ -1,29 +1,90 @@
# GSD ユーザーガイド
-ワークフロー、トラブルシューティング、設定の詳細なリファレンスです。クイックスタートの設定については、[README](../README.md) をご覧ください。
+GSD Core のナラティブ形式の補足ガイドです。まずここで全体像を把握し、各専用ドキュメントへのリンクをたどってください。
+
+> **GSD Core のドキュメントは [Diataxis](https://diataxis.fr) の体系で整理されています。**
+> 目的別にブラウズ: [チュートリアル](README.md#tutorials) · [ハウツーガイド](README.md#how-to-guides) · [リファレンス](README.md#reference) · [解説](README.md#explanation) · [ドキュメント索引](README.md)
---
## 目次
-- [ワークフロー図](#ワークフロー図)
-- [UI デザインコントラクト](#ui-デザインコントラクト)
-- [バックログとスレッド](#バックログとスレッド)
-- [ワークストリーム](#ワークストリーム)
-- [セキュリティ](#セキュリティ)
-- [コマンドリファレンス](#コマンドリファレンス)
-- [設定リファレンス](#設定リファレンス)
-- [使用例](#使用例)
-- [トラブルシューティング](#トラブルシューティング)
-- [リカバリークイックリファレンス](#リカバリークイックリファレンス)
+- [スラッシュコマンドの形式](#slash-command-forms-hyphen-vs-colon)
+- [名前空間ルーティング入門](#namespace-routing-primer-gsdnamespace-v140)
+- [プロジェクトライフサイクル概要](#project-lifecycle-overview)
+- [ワークフロー図](#workflow-diagrams)
+- [UI デザインコントラクト](#ui-design-contract)
+- [スパイクとスケッチ](#spiking--sketching)
+- [バックログとスレッド](#backlog--threads)
+- [ワークストリームとワークスペース](#workstreams--workspaces)
+- [セキュリティ](#security)
+- [使用例](#usage-examples)
+- [トラブルシューティング](#troubleshooting)
+- [リカバリークイックリファレンス](#recovery-quick-reference)
+- [プロジェクトファイル構造](#project-file-structure)
+- [関連](#related)
+
+GitHub / Linear / Jira のイシューから GSD を直接操作する方法については、
+[Issue-driven orchestration](issue-driven-orchestration.md) ガイドを参照してください。
+トラッカーのイシューを、既存の GSD プリミティブを用いた workspace → discuss → plan →
+execute → verify → review → ship ループにマッピングするレシピです。
---
-## ワークフロー図
+## スラッシュコマンドの形式（ハイフン形式 vs コロン形式） {#slash-command-forms-hyphen-vs-colon}
+
+GSD はサポートされているすべてのランタイムに **同一のスキルセット** を提供しますが、スラッシュ形式には 2 種類の表記が存在します。
+
+- **ハイフン形式** — `/gsd-command-name` — Claude Code、Copilot、OpenCode、Kilo、Cursor、Windsurf、Augment、Antigravity、Trae で使用されます。
+- **コロン形式** — `/gsd:command-name` — **Gemini CLI 専用**。Gemini はすべてのプラグインコマンドをプラグイン ID 配下に名前空間分けするため、インストール時に `--gemini` フラグを指定するとコマンドディレクトリ内の本文参照とコマンドファイルがすべてコロン形式に書き換えられます。
+
+どちらを選ぶ必要はありません — インストーラーが対象の各ランタイムのコマンドディレクトリに正しい形式を書き込みます。Gemini 端末でウォークスルーを実行する場合は、スラッシュコマンドを読む際に `gsd` 後のハイフンをコロンに置き換えてください。
+
+## 名前空間ルーティング入門（`gsd:`、v1.40） {#namespace-routing-primer-gsdnamespace-v140}
+
+v1.40 では、階層的ルーティングへのファーストステージエントリーポイントとして **6 つの名前空間メタスキル** が追加されました。これにより、スキル一覧のトークンコストを低く抑えながら（86 スキルのフラットな列挙の約 2,150 トークンに対し、6 つのルーターで約 120 トークン）、各具体的なサブスキルは直接呼び出し可能なままです。各名前空間ルーターの本文には、ユーザーの意図を正しい具体的サブスキルにマッピングするルーティングテーブルが含まれています。
+
+| 名前空間 | ルーター | ルーティング先 |
+|-----------|--------|-----------|
+| フェーズパイプライン | `/gsd-workflow` | discuss / plan / execute / verify / phase / progress |
+| プロジェクトライフサイクル | `/gsd-project` | マイルストーン、監査、サマリー |
+| 品質ゲート | `/gsd-quality` | コードレビュー、デバッグ、監査、セキュリティ、評価、UI |
+| コードベースインテリジェンス | `/gsd-context` | マップ、グラフ化、ドキュメント、学習内容 |
+| 管理 | `/gsd-manage` | 設定、ワークスペース、ワークストリーム、スレッド、更新、ship、受信トレイ |
+| 探索とキャプチャ | `/gsd-ideate` | 探索、スケッチ、スパイク、仕様、キャプチャ |
+
+名前空間ルーターを自分でタイプする必要はほぼありません。その価値はモデルが適切なサブスキルを見つけるために使うルーティングレイヤーにあります — システムプロンプトが 86 エントリではなく 6 エントリを列挙できるようにするために存在しています。具体的なコマンドがわかっている場合（例: `/gsd-plan-phase`）は、直接呼び出してください。
+
+---
+
+## プロジェクトライフサイクル概要 {#project-lifecycle-overview}
+
+GSD のコアループは **discuss → plan → execute → verify → ship** であり、フェーズごとに繰り返されます。例示出力、作成されるファイル、使用されるフラグを含むステップバイステップのウォークスルーは専用チュートリアルに記載されています。
+
+[最初のプロジェクト](tutorials/your-first-project.md) を参照してください。
+
+新しいマイルストーンを開始する前に既存のコードベースをオンボーディングする方法については、[既存のコードベースのオンボーディング](tutorials/onboarding-an-existing-codebase.md) を参照してください。
+
+**主要フラグ一覧:**
+
+| フラグ | コマンド | 使用場面 |
+| ---- | ------- | ----------- |
+| `--auto` | `/gsd-new-project` | インタラクティブな質問をスキップし、PRD ファイルから取り込む |
+| `--research` | `/gsd-quick` | アドホックタスクにリサーチエージェントを追加する |
+| `--validate` | `/gsd-quick` | プランチェックと実行後の検証を追加する |
+| `--chain` | `/gsd-discuss-phase` | discuss → plan → execute を停止なしで自動チェーンする |
+| `--skip-research` | `/gsd-plan-phase` | ドメインが既知の場合にリサーチエージェントをスキップする |
+| `--draft` | `/gsd-ship` | レビュー準備完了ではなくドラフト PR を作成する |
+
+すべてのフラグを含む完全なコマンドリファレンスは [`docs/COMMANDS.md`](COMMANDS.md) を、設定オプション（モデルプロファイル、ワークフローエージェント、git ブランチ戦略）は [`docs/CONFIGURATION.md`](CONFIGURATION.md) を参照してください。
+
+---
+
+## ワークフロー図 {#workflow-diagrams}
### プロジェクト全体のライフサイクル
-```
+```text
┌──────────────────────────────────────────────────┐
│ NEW PROJECT │
│ /gsd-new-project │
@@ -75,9 +136,9 @@
└──────────────────────┘
```
-### プランニングエージェントの連携
+### プランニングエージェントの協調
-```
+```text
/gsd-plan-phase N
│
├── Phase Researcher (x4 parallel)
@@ -111,21 +172,17 @@
### バリデーションアーキテクチャ（Nyquist レイヤー）
-plan-phase のリサーチ時に、GSD はコードが書かれる前に各フェーズ要件に対する自動テストカバレッジをマッピングします。これにより、Claude のエグゼキューターがタスクをコミットした際に、数秒以内で検証できるフィードバックメカニズムが既に存在することが保証されます。
+プランフェーズのリサーチ中、GSD はコードが書かれる前に各フェーズ要件に対して自動テストカバレッジをマッピングします。リサーチャーは既存のテストインフラを検出し、各要件を特定のテストコマンドにマッピングし、実装開始前に作成しなければならないテスト足場（Wave 0 タスク）を識別します。プランチェッカーはこれを 8 番目の検証ディメンションとして強制します: 自動検証コマンドが不足しているタスクを含むプランは承認されません。
-リサーチャーは既存のテストインフラを検出し、各要件を特定のテストコマンドにマッピングし、実装開始前に作成が必要なテストスキャフォールディングを特定します（Wave 0 タスク）。
+**出力:** `{phase}-VALIDATION.md` — フェーズのフィードバックコントラクト。
-プランチェッカーはこれを8番目の検証次元として強制します：自動検証コマンドが不足しているタスクを含むプランは承認されません。
+**無効化:** テストインフラが焦点でないラピッドプロトタイピングフェーズでは、`/gsd-settings` で `workflow.nyquist_validation: false` を設定してください。
-**出力：** `{phase}-VALIDATION.md` -- フェーズのフィードバックコントラクト。
+### 遡及バリデーション（`/gsd-validate-phase`）
-**無効化：** テストインフラが重視されないラピッドプロトタイピングフェーズでは、`/gsd-settings` で `workflow.nyquist_validation: false` を設定してください。
+Nyquist バリデーションが存在する前に実行されたフェーズ、またはテストスイートのみを持つ既存のコードベースに対し、カバレッジのギャップを遡及的に監査して補完します。
-### 遡及バリデーション (`/gsd-validate-phase`)
-
-Nyquist バリデーションが存在する前に実行されたフェーズ、または従来のテストスイートのみを持つ既存コードベースに対して、遡及的に監査しカバレッジのギャップを埋めます：
-
-```
+```text
/gsd-validate-phase N
|
+-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
@@ -144,203 +201,31 @@ Nyquist バリデーションが存在する前に実行されたフェーズ、
+-- PARTIAL -> some gaps escalated to manual-only
```
-オーディターは実装コードを変更しません — テストファイルと VALIDATION.md のみを変更します。テストが実装のバグを発見した場合、対処が必要なエスカレーションとしてフラグが立てられます。
+オーディターは実装コードを変更しません — テストファイルと VALIDATION.md のみです。テストが実装バグを検出した場合、対応すべきエスカレーションとして報告されます。
-**使用タイミング：** Nyquist が有効化される前にプランニングされたフェーズを実行した後、または `/gsd-audit-milestone` が Nyquist コンプライアンスのギャップを検出した後。
+### 前提条件ディスカッションモード
-### 前提確認ディスカッションモード
+デフォルトでは、`/gsd-discuss-phase` は実装の好みに関するオープンエンドな質問をします。前提条件モードではこれが逆転します: GSD がまずコードベースを読み込み、フェーズをどのように構築するかについての構造化された前提条件を提示し、修正点のみを尋ねます。
-デフォルトでは、`/gsd-discuss-phase` は実装の好みについてオープンエンドな質問を行います。前提確認モードではこれを反転させます：GSD がまずコードベースを読み込み、フェーズの構築方法に関する構造化された前提を提示し、修正が必要な箇所のみを確認します。
+**有効化:** `/gsd-settings` 経由で `workflow.discuss_mode` を `'assumptions'` に設定してください。
-**有効化：** `/gsd-settings` で `workflow.discuss_mode` を `'assumptions'` に設定します。
+詳細なディスカッションモードのリファレンスは [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) を参照してください。
-**動作の仕組み：**
-1. PROJECT.md、コードベースマッピング、既存の規約を読み込む
-2. 前提の構造化リストを生成（技術選定、パターン、ファイル配置）
-3. 前提を提示し、確認・修正・補足を求める
-4. 確認された前提から CONTEXT.md を作成
+### 意思決定カバレッジゲート
-**使用タイミング：**
-- コードベースを熟知している経験豊富な開発者
-- オープンエンドな質問が作業を遅らせる高速イテレーション
-- パターンが確立されていて予測可能なプロジェクト
+ディスカッションフェーズは実装上の意思決定を CONTEXT.md の `` ブロック内に番号付き箇条書き（`- **D-01:** …`）として記録します。2 つのゲートによりこれらの意思決定がプランおよびシップされたコードに確実に反映されます。
-ディスカッションモードの完全なリファレンスは [docs/workflow-discuss-mode.md](../workflow-discuss-mode.md) をご覧ください。
+**プランフェーズ変換ゲート（ブロッキング）。** プランニング後、GSD はすべての追跡可能な意思決定が少なくとも 1 つのプランの `must_haves`、`truths`、または本文に含まれるまでフェーズ計画済みのマークを拒否します。
----
+**検証フェーズバリデーションゲート（非ブロッキング）。** 検証中、GSD はプラン、SUMMARY.md、変更されたファイル、および直近のコミットメッセージで各追跡可能な意思決定を検索します。見落としは警告セクションとして VERIFICATION.md に記録されますが、検証ステータスは変更されません。
-## UI デザインコントラクト
+**意思決定のオプトアウト。** `` 内の `### Claude's Discretion` 見出し配下に移動するか、タグを付けてください: `- **D-08 [informational]:** …`、`- **D-09 [folded]:** …`、`- **D-10 [deferred]:** …`。
-### 背景
+**ゲートの無効化。** `.planning/config.json`（または `/gsd-settings` 経由）で `workflow.context_coverage_gate: false` を設定してください。デフォルトは `true` です。
-AI 生成のフロントエンドの見た目が一貫しないのは、Claude Code の UI 能力が低いからではなく、実行前にデザインコントラクトが存在しなかったためです。共通のスペーシングスケール、カラーコントラクト、コピーライティング基準なしに構築された5つのコンポーネントは、5つのわずかに異なるビジュアル上の判断を生み出します。
+### 実行ウェーブの協調
-`/gsd-ui-phase` はプランニング前にデザインコントラクトを確定させます。`/gsd-ui-review` は実行後に結果を監査します。
-
-### コマンド
-
-| コマンド | 説明 |
-|---------|-------------|
-| `/gsd-ui-phase [N]` | フロントエンドフェーズ用の UI-SPEC.md デザインコントラクトを生成 |
-| `/gsd-ui-review [N]` | 実装済み UI の遡及的6ピラービジュアル監査 |
-
-### ワークフロー：`/gsd-ui-phase`
-
-**実行タイミング：** `/gsd-discuss-phase` の後、`/gsd-plan-phase` の前 — フロントエンド/UI 作業を含むフェーズで使用。
-
-**フロー：**
-1. CONTEXT.md、RESEARCH.md、REQUIREMENTS.md を読み込んで既存の決定事項を確認
-2. デザインシステムの状態を検出（shadcn components.json、Tailwind 設定、既存トークン）
-3. shadcn 初期化ゲート — React/Next.js/Vite プロジェクトで未設定の場合、初期化を提案
-4. 未回答のデザインコントラクト質問のみを確認（スペーシング、タイポグラフィ、カラー、コピーライティング、レジストリの安全性）
-5. `{phase}-UI-SPEC.md` をフェーズディレクトリに書き出す
-6. 6つの次元で検証（コピーライティング、ビジュアル、カラー、タイポグラフィ、スペーシング、レジストリの安全性）
-7. BLOCKED の場合はリビジョンループ（最大2回）
-
-**出力：** `.planning/phases/{phase-dir}/` 内の `{padded_phase}-UI-SPEC.md`
-
-### ワークフロー：`/gsd-ui-review`
-
-**実行タイミング：** `/gsd-execute-phase` または `/gsd-verify-work` の後 — フロントエンドコードを含むプロジェクトで使用。
-
-**スタンドアロン：** GSD 管理プロジェクトに限らず、あらゆるプロジェクトで動作します。UI-SPEC.md が存在しない場合は、抽象的な6ピラー基準に基づいて監査します。
-
-**6ピラー（各1-4点）：**
-1. コピーライティング — CTA ラベル、空状態、エラー状態
-2. ビジュアル — フォーカルポイント、ビジュアルヒエラルキー、アイコンのアクセシビリティ
-3. カラー — アクセントカラーの使用規律、60/30/10 準拠
-4. タイポグラフィ — フォントサイズ/ウェイト制約の遵守
-5. スペーシング — グリッド整列、トークンの一貫性
-6. エクスペリエンスデザイン — ローディング/エラー/空状態のカバレッジ
-
-**出力：** フェーズディレクトリ内の `{padded_phase}-UI-REVIEW.md`（スコアと優先度の高い修正点トップ3）。
-
-### 設定
-
-| 設定 | デフォルト | 説明 |
-|---------|---------|-------------|
-| `workflow.ui_phase` | `true` | フロントエンドフェーズ用の UI デザインコントラクトを生成 |
-| `workflow.ui_safety_gate` | `true` | plan-phase 時にフロントエンドフェーズで /gsd-ui-phase の実行を促す |
-
-どちらも「未設定＝有効」パターンに従います。`/gsd-settings` から無効化できます。
-
-### shadcn の初期化
-
-React/Next.js/Vite プロジェクトの場合、UI リサーチャーは `components.json` が見つからない場合に shadcn の初期化を提案します。フローは以下の通りです：
-
-1. `ui.shadcn.com/create` にアクセスしてプリセットを設定
-2. プリセット文字列をコピー
-3. `npx shadcn init --preset {paste}` を実行
-4. プリセットはデザインシステム全体をエンコード — カラー、ボーダーラディウス、フォント
-
-プリセット文字列は GSD の第一級プランニングアーティファクトとなり、フェーズやマイルストーンをまたいで再現可能です。
-
-### レジストリの安全性ゲート
-
-サードパーティの shadcn レジストリは任意のコードを注入できます。安全性ゲートでは以下が必要です：
-- `npx shadcn view {component}` — インストール前に確認
-- `npx shadcn diff {component}` — 公式との比較
-
-`workflow.ui_safety_gate` 設定トグルで制御します。
-
-### スクリーンショットの保存
-
-`/gsd-ui-review` は Playwright CLI を使用してスクリーンショットを `.planning/ui-reviews/` にキャプチャします。バイナリファイルが git に含まれないよう、`.gitignore` が自動的に作成されます。スクリーンショットは `/gsd-complete-milestone` 時にクリーンアップされます。
-
----
-
-## バックログとスレッド
-
-### バックログパーキングロット
-
-アクティブなプランニングの準備ができていないアイデアは、999.x 番号を使用してバックログに格納され、アクティブなフェーズシーケンスの外に保持されます。
-
-```
-/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
-/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
-```
-
-バックログアイテムは完全なフェーズディレクトリを取得するため、`/gsd-discuss-phase 999.1` でアイデアをさらに探索したり、準備が整ったら `/gsd-plan-phase 999.1` を使用できます。
-
-**レビューとプロモーション** は `/gsd-review-backlog` で行います — すべてのバックログアイテムを表示し、プロモーション（アクティブシーケンスへの移動）、保持（バックログに残す）、または削除を選択できます。
-
-### シード
-
-シードは、トリガー条件を持つ将来を見据えたアイデアです。バックログアイテムとは異なり、適切なマイルストーンが到来すると自動的に表面化されます。
-
-```
-/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
-```
-
-シードは完全な WHY と表面化タイミングを保持します。`/gsd-new-milestone` はすべてのシードをスキャンし、一致するものを提示します。
-
-**保存場所：** `.planning/seeds/SEED-NNN-slug.md`
-
-### 永続コンテキストスレッド
-
-スレッドは、複数のセッションにまたがるが特定のフェーズに属さない作業のための、軽量なクロスセッション知識ストアです。
-
-```
-/gsd-thread # List all threads
-/gsd-thread fix-deploy-key-auth # Resume existing thread
-/gsd-thread "Investigate TCP timeout" # Create new thread
-```
-
-スレッドは `/gsd-pause-work` より軽量です — フェーズ状態やプランコンテキストはありません。各スレッドファイルには Goal、Context、References、Next Steps セクションが含まれます。
-
-スレッドは成熟した段階でフェーズ (`/gsd-phase`) やバックログアイテム (`/gsd-capture --backlog`) にプロモーションできます。
-
-**保存場所：** `.planning/threads/{slug}.md`
-
----
-
-## ワークストリーム
-
-ワークストリームを使うと、状態の衝突なしに複数のマイルストーン領域で並行作業できます。各ワークストリームは独立した `.planning/` 状態を持つため、切り替え時に進捗が上書きされることはありません。
-
-**使用タイミング：** 異なる関心領域にまたがるマイルストーン機能（例：バックエンド API とフロントエンドダッシュボード）に取り組んでいて、コンテキストの混在なしに独立してプランニング・実行・ディスカッションしたい場合。
-
-### コマンド
-
-| コマンド | 用途 |
-|---------|---------|
-| `/gsd-workstreams create ` | 独立したプランニング状態を持つ新しいワークストリームを作成 |
-| `/gsd-workstreams switch ` | アクティブコンテキストを別のワークストリームに切り替え |
-| `/gsd-workstreams list` | すべてのワークストリームとアクティブなものを表示 |
-| `/gsd-workstreams complete ` | ワークストリームを完了としてマークし、状態をアーカイブ |
-
-### 動作の仕組み
-
-各ワークストリームは独自の `.planning/` ディレクトリサブツリーを維持します。ワークストリームを切り替えると、GSD はアクティブなプランニングコンテキストを入れ替え、`/gsd-progress`、`/gsd-discuss-phase`、`/gsd-plan-phase` などのコマンドがそのワークストリームの状態に対して動作するようにします。
-
-これは `/gsd-workspace --new`（別のリポジトリワークツリーを作成）より軽量です。ワークストリームは同じコードベースと git 履歴を共有しつつ、プランニングアーティファクトを分離します。
-
----
-
-## セキュリティ
-
-### 多層防御（v1.27）
-
-GSD はマークダウンファイルを生成し、それが LLM のシステムプロンプトとなります。これは、プランニングアーティファクトに流入するユーザー制御テキストが、潜在的な間接プロンプトインジェクションベクターであることを意味します。v1.27 では集中型セキュリティ強化が導入されました：
-
-**パストラバーサル防止：**
-すべてのユーザー提供ファイルパス（`--text-file`、`--prd`）は、プロジェクトディレクトリ内に解決されることが検証されます。macOS の `/var` → `/private/var` シンボリックリンク解決にも対応しています。
-
-**プロンプトインジェクション検出：**
-`security.cjs` モジュールは、ユーザー提供テキストがプランニングアーティファクトに入る前に、既知のインジェクションパターン（ロールオーバーライド、インストラクションバイパス、system タグインジェクション）をスキャンします。
-
-**ランタイムフック：**
-- `gsd-prompt-guard.js` — `.planning/` への Write/Edit 呼び出しをインジェクションパターンでスキャン（常時有効、アドバイザリーのみ）
-- `gsd-workflow-guard.js` — GSD ワークフローコンテキスト外でのファイル編集を警告（`hooks.workflow_guard` でオプトイン）
-
-**CI スキャナー：**
-`prompt-injection-scan.test.cjs` は、すべてのエージェント、ワークフロー、コマンドファイルに埋め込まれたインジェクションベクターをスキャンします。テストスイートの一部として実行されます。
-
----
-
-### 実行ウェーブの調整
-
-```
+```text
/gsd-execute-phase N
│
├── Analyze plan dependencies
@@ -353,274 +238,281 @@ GSD はマークダウンファイルを生成し、それが LLM のシステ
│ └── Executor C (fresh 200K context) -> commit
│
└── Verifier
- └── Check codebase against phase goals
- │
- ├── PASS -> VERIFICATION.md (success)
- └── FAIL -> Issues logged for /gsd-verify-work
-```
-
-### ブラウンフィールドワークフロー（既存コードベース）
-
-```
- /gsd-map-codebase
- │
- ├── Stack Mapper -> codebase/STACK.md
- ├── Arch Mapper -> codebase/ARCHITECTURE.md
- ├── Convention Mapper -> codebase/CONVENTIONS.md
- └── Concern Mapper -> codebase/CONCERNS.md
- │
- ┌───────▼──────────┐
- │ /gsd-new-project │ <- Questions focus on what you're ADDING
- └──────────────────┘
+ ├── Check codebase against phase goals
+ ├── Test quality audit (disabled tests, circular patterns, assertion strength)
+ │
+ ├── PASS -> VERIFICATION.md (success)
+ └── FAIL -> Issues logged for /gsd-verify-work
```
---
-## コマンドリファレンス
+## UI デザインコントラクト {#ui-design-contract}
-### コアワークフロー
+AI が生成するフロントエンドが視覚的に一貫しないのは、Claude Code の UI 能力の問題ではなく、実行前にデザインコントラクトが存在しなかったためです。`/gsd-ui-phase` はプランニング前にデザインコントラクトをロックし、`/gsd-ui-review` は実行後に結果を監査します。
-| コマンド | 用途 | 使用タイミング |
-|---------|---------|-------------|
-| `/gsd-new-project` | フルプロジェクト初期化：質問、リサーチ、要件定義、ロードマップ | 新規プロジェクトの開始時 |
-| `/gsd-new-project --auto @idea.md` | ドキュメントからの自動初期化 | PRD やアイデアドキュメントが準備済みの場合 |
-| `/gsd-discuss-phase [N]` | 実装上の決定事項を記録 | プランニング前に、構築方法を決定するため |
-| `/gsd-ui-phase [N]` | UI デザインコントラクトを生成 | discuss-phase の後、plan-phase の前（フロントエンドフェーズ） |
-| `/gsd-plan-phase [N]` | リサーチ + プランニング + 検証 | フェーズ実行前 |
-| `/gsd-execute-phase ` | すべてのプランを並列ウェーブで実行 | プランニング完了後 |
-| `/gsd-verify-work [N]` | 自動診断付き手動 UAT | 実行完了後 |
-| `/gsd-ship [N]` | 検証済みの作業から PR を作成 | 検証合格後 |
-| `/gsd-fast ` | インラインの軽微なタスク — プランニングを完全にスキップ | タイプミス修正、設定変更、小規模リファクタリング |
-| `/gsd-progress --next` | 状態を自動検出して次のステップを実行 | いつでも — 「次に何をすべき？」 |
-| `/gsd-ui-review [N]` | 遡及的6ピラービジュアル監査 | 実行後または verify-work 後（フロントエンドプロジェクト） |
-| `/gsd-audit-milestone` | マイルストーンの完了定義を満たしているか検証 | マイルストーン完了前 |
-| `/gsd-complete-milestone` | マイルストーンをアーカイブし、リリースタグを作成 | 全フェーズの検証完了後 |
-| `/gsd-new-milestone [name]` | 次のバージョンサイクルを開始 | マイルストーン完了後 |
+完全なワークフロー、設定、shadcn の初期化、レジストリ安全ゲートについては [UI フェーズのデザイン](how-to/design-a-ui-phase.md) を参照してください。
-### ナビゲーション
+**クイックリファレンス:**
-| コマンド | 用途 | 使用タイミング |
-|---------|---------|-------------|
-| `/gsd-progress` | 状態と次のステップを表示 | いつでも -- 「今どこにいる？」 |
-| `/gsd-resume-work` | 前回のセッションからフルコンテキストを復元 | 新しいセッションの開始時 |
-| `/gsd-pause-work` | 構造化されたハンドオフを保存（HANDOFF.json + continue-here.md） | フェーズの途中で作業を中断する時 |
-| `/gsd-pause-work --report` | 作業内容と成果を含むセッションサマリーを生成 | セッション終了時、ステークホルダーへの共有時 |
-| `/gsd-help` | すべてのコマンドを表示 | クイックリファレンス |
-| `/gsd-update` | 変更履歴プレビュー付きで GSD を更新 | 新バージョンの確認時 |
+| コマンド | 説明 |
+| -------------------- | -------------------------------------------------------- |
+| `/gsd-ui-phase [N]` | フロントエンドフェーズ用の UI-SPEC.md デザインコントラクトを生成する |
+| `/gsd-ui-review [N]` | 実装済み UI の 6 柱ビジュアル監査を遡及的に実行する |
-### フェーズ管理
-
-| コマンド | 用途 | 使用タイミング |
-|---------|---------|-------------|
-| `/gsd-phase` | ロードマップに新しいフェーズを追加 | 初期プランニング後にスコープが拡大した場合 |
-| `/gsd-phase --insert [N]` | 緊急作業を挿入（小数番号） | マイルストーン中の緊急修正 |
-| `/gsd-phase --remove [N]` | 将来のフェーズを削除して番号を振り直す | 機能のスコープ縮小 |
-| `/gsd-discuss-phase --assumptions [N]` | Claude の意図するアプローチをプレビュー | プランニング前に方向性を確認 |
-| `/gsd-plan-phase --research-phase [N]` | エコシステムの深いリサーチのみ | 複雑または不慣れなドメイン |
-
-### ブラウンフィールドとユーティリティ
-
-| コマンド | 用途 | 使用タイミング |
-|---------|---------|-------------|
-| `/gsd-map-codebase` | 既存コードベースを分析 | 既存コードに対する `/gsd-new-project` の前 |
-| `/gsd-quick` | GSD 保証付きのアドホックタスク | バグ修正、小機能、設定変更 |
-| `/gsd-debug [desc]` | 永続状態を持つ体系的デバッグ | 何かが壊れた時 |
-| `/gsd-forensics` | ワークフロー障害の診断レポート | 状態、アーティファクト、git 履歴が破損していると思われる場合 |
-| `/gsd-capture [desc]` | 後でやるアイデアを記録 | セッション中にアイデアが浮かんだ時 |
-| `/gsd-capture --list` | 保留中の TODO を一覧表示 | 記録したアイデアのレビュー |
-| `/gsd-settings` | ワークフロートグルとモデルプロファイルを設定 | モデル変更、エージェントのトグル |
-| `/gsd-config --profile ` | クイックプロファイル切り替え | コスト/品質トレードオフの変更 |
-| `/gsd-update --reapply` | アップデート後にローカル変更を復元 | ローカル編集がある場合の `/gsd-update` 後 |
-
-### コード品質とレビュー
-
-| コマンド | 用途 | 使用タイミング |
-|---------|---------|-------------|
-| `/gsd-review --phase N` | 外部 CLI からのクロス AI ピアレビュー | 実行前にプランを検証 |
-| `/gsd-pr-branch` | `.planning/` コミットをフィルタリングしたクリーンな PR ブランチ | プランニングフリーの diff で PR を作成する前 |
-| `/gsd-audit-uat` | 全フェーズの検証負債を監査 | マイルストーン完了前 |
-
-### バックログとスレッド
-
-| コマンド | 用途 | 使用タイミング |
-|---------|---------|-------------|
-| `/gsd-capture --backlog ` | バックログパーキングロットにアイデアを追加（999.x） | アクティブなプランニングの準備ができていないアイデア |
-| `/gsd-review-backlog` | バックログアイテムのプロモーション/保持/削除 | 新マイルストーン前の優先順位付け |
-| `/gsd-capture --seed ` | トリガー条件付きの将来を見据えたアイデア | 将来のマイルストーンで表面化すべきアイデア |
-| `/gsd-thread [name]` | 永続コンテキストスレッド | フェーズ構造外のクロスセッション作業 |
+| 設定 | デフォルト | 説明 |
+| ------------------------- | ------- | ----------------------------------------------------------- |
+| `workflow.ui_phase` | `true` | フロントエンドフェーズ用の UI デザインコントラクトを生成する |
+| `workflow.ui_safety_gate` | `true` | プランフェーズでフロントエンドフェーズに対し /gsd-ui-phase の実行を促す |
---
-## 設定リファレンス
+## スパイクとスケッチ {#spiking--sketching}
-GSD はプロジェクト設定を `.planning/config.json` に保存します。`/gsd-new-project` 時に設定するか、後から `/gsd-settings` で更新できます。
+プランニング前に技術的な実現可能性を検証するには `/gsd-spike` を、デザイン前にビジュアルの方向性を探るには `/gsd-sketch` を使用してください。どちらもアーティファクトを `.planning/` に保存し、ラップアップコンパニオンを介してプロジェクトスキルシステムと統合されます。
-### 完全な config.json スキーマ
+完全なワークフローとフロー図は [スパイクとスケッチ](how-to/spike-and-sketch.md) を参照してください。
-```json
-{
- "mode": "interactive",
- "granularity": "standard",
- "model_profile": "balanced",
- "planning": {
- "commit_docs": true,
- "search_gitignored": false
- },
- "workflow": {
- "research": true,
- "plan_check": true,
- "verifier": true,
- "nyquist_validation": true,
- "ui_phase": true,
- "ui_safety_gate": true,
- "research_before_questions": false,
- "discuss_mode": "standard",
- "skip_discuss": false
- },
- "resolve_model_ids": "anthropic",
- "hooks": {
- "context_warnings": true,
- "workflow_guard": false
- },
- "git": {
- "branching_strategy": "none",
- "phase_branch_template": "gsd/phase-{phase}-{slug}",
- "milestone_branch_template": "gsd/{milestone}-{slug}",
- "quick_branch_template": null
- }
-}
+**典型的なフロー:**
+
+```bash
+/gsd-spike "SSE vs WebSocket" # Validate the approach
+/gsd-spike --wrap-up # Package learnings
+
+/gsd-sketch "real-time feed UI" # Explore the design
+/gsd-sketch --wrap-up # Package decisions
+
+/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
+/gsd-plan-phase N # Plan with confidence
```
-### コア設定
-
-| 設定 | オプション | デフォルト | 制御内容 |
-|---------|---------|---------|------------------|
-| `mode` | `interactive`, `yolo` | `interactive` | `yolo` は決定を自動承認、`interactive` は各ステップで確認 |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | フェーズの粒度：スコープの分割の細かさ（3-5、5-8、または 8-12 フェーズ） |
-| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | 各エージェントのモデルティア（下表を参照） |
-
-### プランニング設定
-
-| 設定 | オプション | デフォルト | 制御内容 |
-|---------|---------|---------|------------------|
-| `planning.commit_docs` | `true`, `false` | `true` | `.planning/` ファイルを git にコミットするかどうか |
-| `planning.search_gitignored` | `true`, `false` | `false` | `.planning/` を含めるためにブロード検索に `--no-ignore` を追加 |
-
-> **注：** `.planning/` が `.gitignore` に含まれている場合、設定値に関係なく `commit_docs` は自動的に `false` になります。
-
-### ワークフロートグル
-
-| 設定 | オプション | デフォルト | 制御内容 |
-|---------|---------|---------|------------------|
-| `workflow.research` | `true`, `false` | `true` | プランニング前のドメイン調査 |
-| `workflow.plan_check` | `true`, `false` | `true` | プラン検証ループ（最大3回） |
-| `workflow.verifier` | `true`, `false` | `true` | 実行後のフェーズ目標に対する検証 |
-| `workflow.nyquist_validation` | `true`, `false` | `true` | plan-phase 時のバリデーションアーキテクチャリサーチ、8番目の plan-check 次元 |
-| `workflow.ui_phase` | `true`, `false` | `true` | フロントエンドフェーズ用の UI デザインコントラクトを生成 |
-| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase 時にフロントエンドフェーズで /gsd-ui-phase の実行を促す |
-| `workflow.research_before_questions` | `true`, `false` | `false` | ディスカッション質問の後ではなく前にリサーチを実行 |
-| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | ディスカッションスタイル：オープンエンドの質問 vs. コードベース駆動の前提確認 |
-| `workflow.skip_discuss` | `true`, `false` | `false` | 自律モードで discuss-phase を完全にスキップ、ROADMAP のフェーズ目標から最小限の CONTEXT.md を作成 |
-
-### フック設定
-
-| 設定 | オプション | デフォルト | 制御内容 |
-|---------|---------|---------|------------------|
-| `hooks.context_warnings` | `true`, `false` | `true` | コンテキストウィンドウ使用量の警告 |
-| `hooks.workflow_guard` | `true`, `false` | `false` | GSD ワークフローコンテキスト外でのファイル編集の警告 |
-
-慣れたドメインやトークン節約時に、ワークフロートグルを無効にしてフェーズを高速化できます。
-
-### Git ブランチ戦略
-
-| 設定 | オプション | デフォルト | 制御内容 |
-|---------|---------|---------|------------------|
-| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | ブランチ作成のタイミングと方法 |
-| `git.phase_branch_template` | テンプレート文字列 | `gsd/phase-{phase}-{slug}` | phase 戦略のブランチ名 |
-| `git.milestone_branch_template` | テンプレート文字列 | `gsd/{milestone}-{slug}` | milestone 戦略のブランチ名 |
-| `git.quick_branch_template` | テンプレート文字列 または `null` | `null` | `/gsd-quick` タスク用のオプションブランチ名 |
-
-**ブランチ戦略の説明：**
-
-| 戦略 | ブランチ作成 | スコープ | 最適な用途 |
-|----------|---------------|-------|----------|
-| `none` | なし | N/A | ソロ開発、シンプルなプロジェクト |
-| `phase` | 各 `execute-phase` 時 | フェーズごとに1ブランチ | フェーズごとのコードレビュー、粒度の細かいロールバック |
-| `milestone` | 最初の `execute-phase` 時 | 全フェーズで1ブランチを共有 | リリースブランチ、バージョンごとの PR |
-
-**テンプレート変数：** `{phase}` = ゼロパディングされた番号（例："03"）、`{slug}` = 小文字ハイフン区切りの名前、`{milestone}` = バージョン（例："v1.0"）、`{num}` / `{quick}` = quick タスク ID（例："260317-abc"）。
-
-quick タスクのブランチ設定例：
-
-```json
-"git": {
- "quick_branch_template": "gsd/quick-{num}-{slug}"
-}
-```
-
-### モデルプロファイル（エージェント別の内訳）
-
-| エージェント | `quality` | `balanced` | `budget` | `inherit` |
-|-------|-----------|------------|----------|-----------|
-| gsd-planner | Opus | Opus | Sonnet | Inherit |
-| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit |
-| gsd-executor | Opus | Sonnet | Sonnet | Inherit |
-| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit |
-| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit |
-| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-debugger | Opus | Sonnet | Sonnet | Inherit |
-| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit |
-| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit |
-| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit |
-
-**プロファイルの方針：**
-- **quality** -- すべての意思決定エージェントに Opus、読み取り専用の検証に Sonnet。クォータに余裕があり、重要な作業に使用。
-- **balanced** -- プランニング（アーキテクチャの決定が行われる場所）にのみ Opus、それ以外は Sonnet。正当な理由があるデフォルト。
-- **budget** -- コードを書くものには Sonnet、リサーチと検証には Haiku。大量作業や重要度の低いフェーズに使用。
-- **inherit** -- すべてのエージェントが現在のセッションモデルを使用。モデルを動的に切り替える場合（例：OpenCode または Kilo の `/model`）や、Claude Code を非 Anthropic プロバイダー（OpenRouter、ローカルモデル）で使用する場合に最適で、予期しない API コストを回避できます。非 Claude ランタイム（Codex、OpenCode、Gemini CLI、Kilo）では、インストーラーが自動的に `resolve_model_ids: "omit"` を設定します -- [非 Claude ランタイムの使用](#非-claude-ランタイムの使用codexopencodegemini-clikilo)を参照。
-
---
-## 使用例
+## バックログとスレッド {#backlog--threads}
+
+### バックログ駐車場
+
+まだアクティブなプランニングの準備ができていないアイデアは、999.x 番号付けを使用してバックログに追加し、アクティブなフェーズシーケンスの外に置きます。
+
+```bash
+/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
+/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
+```
+
+バックログアイテムは完全なフェーズディレクトリを持つため、`/gsd-discuss-phase 999.1` でアイデアをさらに探索したり、準備ができたら `/gsd-plan-phase 999.1` を使用できます。
+
+**レビューとプロモーション** は `/gsd-review-backlog` で行います — すべてのバックログアイテムが表示され、プロモート（アクティブシーケンスに移動）、保持（バックログに残す）、または削除（削除）を選択できます。
+
+### シード
+
+シードはトリガー条件を持つ将来志向のアイデアです。バックログアイテムと異なり、適切なマイルストーンが来ると自動的に浮上します。
+
+```bash
+/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
+```
+
+`/gsd-new-milestone` はすべてのシードをスキャンしてマッチを提示します。**保存場所:** `.planning/seeds/SEED-NNN-slug.md`
+
+### 永続コンテキストスレッド
+
+スレッドは、複数のセッションにまたがるが特定のフェーズに属さない作業のための軽量なクロスセッション知識ストアです。
+
+```bash
+/gsd-thread # List all threads
+/gsd-thread fix-deploy-key-auth # Resume existing thread
+/gsd-thread "Investigate TCP timeout" # Create new thread
+```
+
+スレッドが成熟したら、フェーズ（`/gsd-phase`）またはバックログアイテム（`/gsd-capture --backlog`）に昇格できます。**保存場所:** `.planning/threads/{slug}.md`
+
+---
+
+## ワークストリームとワークスペース {#workstreams--workspaces}
+
+ワークストリームとワークスペースはどちらも分離を提供しますが、異なるレベルで動作します。
+
+**ワークストリーム** は同じコードベースと git 履歴を共有しながら、プランニングアーティファクトを分離します — より軽量で、複数のマイルストーン領域を並行して作業するのに適しています。[ワークストリームで並行作業する](how-to/work-in-parallel-with-workstreams.md) を参照してください。
+
+**ワークスペース** は独自の `.planning/` を持つ独立したリポジトリのワークツリーを作成します — より重量があり、フィーチャーブランチまたはマルチリポジトリの分離に適しています。[ワークスペースで作業を分離する](how-to/isolate-work-with-workspaces.md) を参照してください。
+
+| コマンド | 目的 |
+| ---------------------------------- | ---------------------------------------------------- |
+| `/gsd-workstreams create ` | 分離されたプランニング状態を持つ新しいワークストリームを作成する |
+| `/gsd-workstreams switch ` | アクティブコンテキストを別のワークストリームに切り替える |
+| `/gsd-workstreams list` | すべてのワークストリームとアクティブなものを表示する |
+| `/gsd-workstreams complete ` | ワークストリームを完了としてマークし状態をアーカイブする |
+
+```bash
+# Workspace example — feature branch isolation
+/gsd-workspace --new --name feature-b --repos .
+cd ~/gsd-workspaces/feature-b
+/gsd-new-project
+
+/gsd-workspace --list
+/gsd-workspace --remove feature-b
+```
+
+---
+
+## セキュリティ {#security}
+
+### 多層防御（v1.27）
+
+GSD は LLM のシステムプロンプトになるマークダウンファイルを生成します。これは、プランニングアーティファクトに流れ込むユーザー制御のテキストが、間接的なプロンプトインジェクションベクターになり得ることを意味します。v1.27 では集中的なセキュリティ強化が導入されました。
+
+**パストラバーサル防止:** ユーザーが指定したファイルパス（`--text-file`、`--prd`）はすべてプロジェクトディレクトリ内で解決されるよう検証されます。macOS の `/var` → `/private/var` シンボリックリンク解決も処理されます。
+
+**プロンプトインジェクション検出:** `security.cjs` モジュールは、ユーザーが指定したテキストがプランニングアーティファクトに入力される前に既知のインジェクションパターンをスキャンします。
+
+**ランタイムフック:**
+
+- `gsd-prompt-guard.js` — `.planning/` への Write/Edit 呼び出しでインジェクションパターンをスキャンする（常時有効、アドバイザリーのみ）
+- `gsd-workflow-guard.js` — GSD ワークフローコンテキスト外でのファイル編集を警告する（`hooks.workflow_guard` 経由でオプトイン）
+
+**CI スキャナー:** `prompt-injection-scan.test.cjs` はすべてのエージェント、ワークフロー、コマンドファイルに埋め込まれたインジェクションベクターをスキャンします。
+
+---
+
+### パッケージ正当性ゲート（v1.42.1）
+
+AI コーディングツールはパッケージ名を幻覚することがあります。攻撃者はそれらの名前を npm、PyPI、crates.io に悪意のあるインストール後スクリプトとともにあらかじめ登録します — これは *スロップスクワッティング* と呼ばれる手法です。v1.42.1 では、これがシェルに到達する前に停止させる 3 層ゲートが追加されました。
+
+**RESEARCH.md 内** — 外部パッケージを推奨する各フェーズには `## Package Legitimacy Audit` テーブルが含まれます:
+
+```markdown
+## Package Legitimacy Audit
+
+| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
+|---------|----------|-----|-----------|-------------|-----------|-------------|
+| express | npm | 13 yrs | 100M+/wk | github.com/expressjs/express | [OK] | Approved |
+| some-new-util | npm | 3 days | 47 | none | [SLOP] | REMOVED |
+| api-bridge | npm | 6 mo | 1.2k/wk | github.com/user/api-bridge | [SUS] | Flagged |
+```
+
+`[SLOP]` パッケージは RESEARCH.md から完全に削除され、プランナーに到達することはありません。
+
+**PLAN.md 内** — `[SUS]` または `[ASSUMED]` パッケージはインストール前に `checkpoint:human-verify` タスクをトリガーします。
+
+**実行中** — インストールが失敗した場合、エグゼキューターはチェックポイントを提示して停止し、代替案をサイレントに試みません。
+
+**スロップチェックの判定:**
+
+| 判定 | 意味 | GSD のアクション |
+|---------|---------|------------|
+| `[OK]` | すべての正当性チェックに合格 | 進行 — チェックポイントは追加されない |
+| `[SUS]` | 疑わしいシグナル | フラグ付き; プランナーが `checkpoint:human-verify` を追加 |
+| `[SLOP]` | 高確信度の幻覚 | RESEARCH.md から削除; プランナーに到達しない |
+
+slopcheck を手動でインストールするには:
+
+```bash
+pip install slopcheck
+# verify: slopcheck install express --json
+```
+
+---
+
+## コードレビューワークフロー
+
+フェーズを実行した後、UAT の前に構造化されたコードレビューを実行してください。完全なワークフローは [クロス AI レビューのセットアップ](how-to/set-up-cross-ai-review.md) を参照してください。
+
+```bash
+/gsd-code-review 3 # Review all changed files in phase 3
+/gsd-code-review 3 --depth=deep # Deep cross-file review
+/gsd-code-review 3 --fix # Fix Critical + Warning findings atomically
+/gsd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
+/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
+```
+
+レビューステップは実行後、UAT 前に位置します:
+
+```text
+/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review N --fix -> /gsd-verify-work N
+```
+
+---
+
+## コマンドおよび設定リファレンス
+
+- **コマンドリファレンス:** すべての安定版コマンドのフラグ、サブコマンド、例については [`docs/COMMANDS.md`](COMMANDS.md) を参照してください。
+- **設定リファレンス:** 完全な `config.json` スキーマ、モデルプロファイルテーブル、git ブランチ戦略、セキュリティ設定については [`docs/CONFIGURATION.md`](CONFIGURATION.md) を参照してください。
+- **ディスカッションモード:** インタビューモードと前提条件モードについては [`docs/workflow-discuss-mode.md`](workflow-discuss-mode.md) を参照してください。
+
+---
+
+## 使用例 {#usage-examples}
### 新規プロジェクト（フルサイクル）
```bash
claude --dangerously-skip-permissions
-/gsd-new-project # 質問に回答、設定、ロードマップを承認
+/gsd-new-project # Answer questions, configure, approve roadmap
/clear
-/gsd-discuss-phase 1 # 好みを確定
-/gsd-ui-phase 1 # デザインコントラクト（フロントエンドフェーズ）
-/gsd-plan-phase 1 # リサーチ + プラン + 検証
-/gsd-execute-phase 1 # 並列実行
-/gsd-verify-work 1 # 手動 UAT
-/gsd-ship 1 # 検証済み作業から PR を作成
-/gsd-ui-review 1 # ビジュアル監査（フロントエンドフェーズ）
+/gsd-discuss-phase 1 # Lock in your preferences
+/gsd-ui-phase 1 # Design contract (frontend phases)
+/gsd-plan-phase 1 # Research + plan + verify
+/gsd-execute-phase 1 # Parallel execution
+/gsd-verify-work 1 # Manual UAT
+/gsd-ship 1 # Create PR from verified work
+/gsd-ui-review 1 # Visual audit (frontend phases)
/clear
-/gsd-progress --next # 自動検出して次のステップを実行
+/gsd-progress --next # Auto-detect and run next step
...
-/gsd-audit-milestone # すべて出荷されたか確認
-/gsd-complete-milestone # アーカイブ、タグ付け、完了
-/gsd-pause-work --report # セッションサマリーを生成
+/gsd-audit-milestone # Check everything shipped
+/gsd-complete-milestone # Archive, tag, done
+/gsd-pause-work --report # Generate session summary
```
### 既存ドキュメントからの新規プロジェクト
```bash
-/gsd-new-project --auto @prd.md # ドキュメントからリサーチ/要件/ロードマップを自動実行
+/gsd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/clear
-/gsd-discuss-phase 1 # ここから通常のフロー
+/gsd-discuss-phase 1 # Normal flow from here
```
-### 既存コードベース
+### 既存のコードベース
```bash
-/gsd-map-codebase # 既存のコードを分析（並列エージェント）
-/gsd-new-project # 追加する内容に焦点を当てた質問
-# （ここから通常のフェーズワークフロー）
+/gsd-map-codebase # Analyse what exists (parallel agents)
+/gsd-new-project # Questions focus on what you're ADDING
+# (normal phase workflow from here)
```
+**実行後のドリフト検出（#2003）。** `/gsd-execute-phase` を実行するたびに、GSD はフェーズが `.planning/codebase/STRUCTURE.md` を古くするほどの構造的変更を導入したかどうかを確認します。次のコマンドで動作を切り替えられます:
+
+```bash
+/gsd-settings workflow.drift_action auto-remap # remap automatically
+/gsd-settings workflow.drift_threshold 5 # tune sensitivity
+```
+
+### プランドリフトガード
+
+**デフォルトオン。** プランドリフトガード（`plan_review.source_grounding: true`）はプランレビュー中に実行され、プランが引用するすべてのシンボル（デコレーター、クラス、関数、CLI フラグ）がレビュー時にソースツリーに実際に存在するかを検証します。これにより、実行エージェントが実行される前に幻覚された名前を検出します。
+
+**検出内容:**
+
+- PLAN.md のステップで参照されているが、ソースに存在しない関数
+- プランが書かれた後にリネームまたは削除されたクラスまたはデコレーター名
+- プランに記述されているが引数パーサーに定義されていない CLI フラグ
+- 実装ステップで引用されているがファイルに解決されないモジュールパス
+
+**needs-acknowledgement の動作。** ガードが欠損シンボルを発見すると、ハードブロックではなく `needs-acknowledgement` 通知をプランレビュー出力に出力します。承認して続行（シンボルが意図的に新規の場合）するか、プランの修正を要求できます。ガードはプランを自動拒否しません — 人間の判断のためのシグナルを提示します。
+
+**intel なしでも動作。** デフォルトではガードは `grep`/`ripgrep` を使用してソースファイルを検索します — 事前インデックスは不要です。`intel.enabled: true` で `/gsd:map-codebase` を実行済みの場合、`plan_review.source_grounding_authority: intel` を設定すると、より高速な事前構築済みの `api-map.json` インデックスを使用できます。
+
+```bash
+# Enable/disable (default: on)
+/gsd-settings plan_review.source_grounding true
+/gsd-settings plan_review.source_grounding false
+
+# Switch resolver authority
+/gsd-settings plan_review.source_grounding_authority grep # live grep (default)
+/gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json
+```
+
+プロジェクト設定時（`/gsd:new-project` がワークフロー設定中に尋ねます）または `/gsd:settings`（Planning セクション → Drift Guard）経由でいつでも切り替えられます。
+
### クイックバグ修正
```bash
@@ -631,100 +523,159 @@ claude --dangerously-skip-permissions
### 休憩後の再開
```bash
-/gsd-progress # 前回の続きと次のステップを確認
-# または
-/gsd-resume-work # 前回のセッションからフルコンテキストを復元
+/gsd-progress # See where you left off and what's next
+# or
+/gsd-resume-work # Full context restoration from last session
```
### リリース準備
```bash
-/gsd-audit-milestone # 要件カバレッジを確認、スタブを検出
-/gsd-complete-milestone # アーカイブ、タグ付け、完了
+/gsd-audit-milestone # Check requirements coverage, detect stubs
+/gsd-complete-milestone # Archive, tag, done
```
-### スピード vs 品質プリセット
+### スピードと品質のプリセット
-| シナリオ | モード | 粒度 | プロファイル | リサーチ | プランチェック | ベリファイア |
-|----------|------|-------|---------|----------|------------|----------|
-| プロトタイピング | `yolo` | `coarse` | `budget` | オフ | オフ | オフ |
-| 通常開発 | `interactive` | `standard` | `balanced` | オン | オン | オン |
-| プロダクション | `interactive` | `fine` | `quality` | オン | オン | オン |
+| シナリオ | モード | 粒度 | プロファイル | リサーチ | プランチェック | ベリファイア |
+| ----------- | ------------- | ----------- | ---------- | -------- | ---------- | -------- |
+| プロトタイピング | `yolo` | `coarse` | `budget` | off | off | off |
+| 通常の開発 | `interactive` | `standard` | `balanced` | on | on | on |
+| 本番環境 | `interactive` | `fine` | `quality` | on | on | on |
-**自律モードでの discuss-phase スキップ：** `yolo` モードで実行中に、PROJECT.md に既に十分な設定が記録されている場合は、`/gsd-settings` で `workflow.skip_discuss: true` を設定してください。これにより discuss-phase を完全にバイパスし、ROADMAP のフェーズ目標から最小限の CONTEXT.md を作成します。PROJECT.md と規約がディスカッションで新しい情報を追加しないほど包括的な場合に有用です。
+**自律モードでのディスカッションフェーズのスキップ:** `yolo` モードで実行する場合、`/gsd-settings` で `workflow.skip_discuss: true` を設定してください。
-### マイルストーン中のスコープ変更
+### マイルストーン途中でのスコープ変更
```bash
-/gsd-phase # ロードマップに新しいフェーズを追加
-# または
-/gsd-phase --insert 3 # フェーズ 3 と 4 の間に緊急作業を挿入
-# または
-/gsd-phase --remove 7 # フェーズ 7 をスコープ外にして番号を振り直す
+/gsd-phase # Append a new phase to the roadmap (default mode)
+/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
+/gsd-phase --remove 7 # Descope phase 7 and renumber
+/gsd-phase --edit 4 # Edit any field of phase 4 in place
```
-### マルチプロジェクトワークスペース
-
-独立した GSD 状態を持つ複数のリポジトリや機能で並行作業できます。
-
-```bash
-# モノレポからリポジトリを含むワークスペースを作成
-/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
-
-# フィーチャーブランチの分離 — 独自の .planning/ を持つ現在のリポジトリのワークツリー
-/gsd-workspace --new --name feature-b --repos .
-
-# ワークスペースに移動して GSD を初期化
-cd ~/gsd-workspaces/feature-b
-/gsd-new-project
-
-# ワークスペースの一覧と管理
-/gsd-workspace --list
-/gsd-workspace --remove feature-b
-```
-
-各ワークスペースには以下が含まれます：
-- 独自の `.planning/` ディレクトリ（ソースリポジトリから完全に独立）
-- 指定されたリポジトリの Git ワークツリー（デフォルト）またはクローン
-- メンバーリポジトリを追跡する `WORKSPACE.md` マニフェスト
-
---
-## トラブルシューティング
+## トラブルシューティング {#troubleshooting}
-### 「Project already initialized」
+包括的なトラブルシューティングガイドは [リカバリーとトラブルシューティング](how-to/recover-and-troubleshoot.md) を参照してください。最も一般的な問題を以下に要約します。
-`/gsd-new-project` を実行したが、`.planning/PROJECT.md` が既に存在しています。これは安全チェックです。やり直したい場合は、まず `.planning/` ディレクトリを削除してください。
+### プログラマティック CLI（`gsd-tools query` vs `gsd-tools.cjs`）
-### 長時間セッションでのコンテキスト劣化
+自動化には、登録済みサブコマンドを使用する **`gsd-tools query`** を推奨します（[CLI-TOOLS.md — SDK とプログラマティックアクセス](CLI-TOOLS.md#sdk-and-programmatic-access) と QUERY-HANDLERS.md を参照）。レガシーの `node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs` CLI は引き続きサポートされています。
-主要なコマンド間でコンテキストウィンドウをクリアしてください：Claude Code では `/clear` を使用します。GSD はフレッシュなコンテキストを前提に設計されています — すべてのサブエージェントはクリーンな 200K ウィンドウを取得します。メインセッションで品質が低下している場合は、クリアして `/gsd-resume-work` または `/gsd-progress` で状態を復元してください。
+### STATE.md の同期ずれ
-### プランが誤っている、または方向性がずれている
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate # Detect drift
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify # Preview changes
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md
+```
-プランニング前に `/gsd-discuss-phase [N]` を実行してください。プランの品質問題のほとんどは、CONTEXT.md があれば防げたはずの前提を Claude が置いてしまうことに起因します。`/gsd-discuss-phase --assumptions [N]` を使用して、プランにコミットする前に Claude の意図を確認することもできます。
+### 「Spawning...」の後にコマンドがフリーズしているように見える
-### 実行が失敗する、またはスタブが生成される
+GSD サブエージェントは独立したコンテキストウィンドウで実行されます — その作業は進行中は親セッションからは見えません。セッションを中断しないでください。リサーチおよびプランニングエージェントは通常 1〜5 分かかります。結果を待ってください。
-プランが野心的すぎなかったか確認してください。プランは最大2-3タスクにすべきです。タスクが大きすぎると、単一のコンテキストウィンドウで確実に生成できる範囲を超えてしまいます。より小さなスコープで再プランニングしてください。
+### 長いセッション中のコンテキスト劣化
-### 現在地がわからなくなった
+主要なコマンド間でコンテキストウィンドウをクリアしてください: Claude Code では `/clear`。GSD はフレッシュなコンテキストを前提に設計されています — すべてのサブエージェントはクリーンな 200K ウィンドウを取得します。クリア後に状態を復元するには `/gsd-resume-work` または `/gsd-progress` を使用してください。
-`/gsd-progress` を実行してください。すべての状態ファイルを読み込み、現在地と次にやるべきことを正確に教えてくれます。
+### プランが間違っているまたは方向性がずれている
-### 実行後に変更が必要
+プランニング前に `/gsd-discuss-phase [N]` を実行してください。プランの品質問題のほとんどは、`CONTEXT.md` があれば防げた前提をモデルが立てることから来ています。
-`/gsd-execute-phase` を再実行しないでください。ターゲットを絞った修正には `/gsd-quick` を使用するか、`/gsd-verify-work` で体系的に問題を特定し UAT を通じて修正してください。
+### 実行が失敗するかスタブを生成する
-### モデルのコストが高すぎる
+プランが野心的すぎなかったか確認してください。プランは最大 2〜3 タスクであるべきです。より小さなスコープで再プランしてください。
-budget プロファイルに切り替えてください：`/gsd-config --profile budget`。ドメインに慣れている場合（またはClaude が慣れている場合）は、`/gsd-settings` でリサーチエージェントと plan-check エージェントを無効にしてください。
+### どこにいるかわからなくなった
+
+`/gsd-progress` を実行してください。すべての状態ファイルを読み込み、現在地と次にすべきことを正確に伝えます。
+
+### モデルコストが高すぎる
+
+budget プロファイルに切り替えてください: `/gsd-config --profile budget`。ドメインが既知の場合は `/gsd-settings` でリサーチおよびプランチェックエージェントを無効化してください。
+
+### フェーズ別のモデルコスト調整（`models`）— v1.40 追加
+
+`.planning/config.json` に `models` ブロックを追加してください:
+
+```json
+{
+ "model_profile": "balanced",
+ "models": {
+ "planning": "opus",
+ "discuss": "opus",
+ "research": "sonnet",
+ "execution": "opus",
+ "verification": "sonnet",
+ "completion": "sonnet"
+ }
+}
+```
+
+エージェント単位の例外が必要な場合は、`model_overrides` を併記してください — これが `models` より優先されます:
+
+```json
+{
+ "models": { "research": "sonnet" },
+ "model_overrides": {
+ "gsd-codebase-mapper": "haiku"
+ }
+}
+```
+
+完全なマッピングテーブルと解決優先順位のルールは [フェーズタイプ別モデル](CONFIGURATION.md#per-phase-type-models-models--added-in-v140) を参照してください。
+
+### `dynamic_routing` によるデフォルトで低コスト — v1.40 追加
+
+```json
+{
+ "dynamic_routing": {
+ "enabled": true,
+ "tier_models": {
+ "light": "haiku",
+ "standard": "sonnet",
+ "heavy": "opus"
+ },
+ "escalate_on_failure": true,
+ "max_escalations": 1
+ }
+}
+```
+
+完全なエージェント → ティアマッピングは [ダイナミックルーティング](CONFIGURATION.md#dynamic-routing-with-failure-tier-escalation-dynamic_routing--added-in-v140) を参照してください。
+
+### MCP サーバーのトリミングによるターンあたりのコスト削減
+
+`model_profile` や `models.` を調整する前に、ハーネスで有効になっている **MCP サーバー** を監査してください。有効になっている各 MCP サーバーはすべてのターンにそのツールスキーマを注入します — 重量級のサーバーはそれぞれ 20k+ トークンかかることがあります。
+
+これは **ハーネスの設定** であり、GSD の設定ではありません。トグルは `.claude/settings.json` にあります:
+
+```json
+{
+ "enabledMcpjsonServers": ["context7"],
+ "disabledMcpjsonServers": ["playwright", "mac-tools"]
+}
+```
+
+長いフェーズの前のクイック監査:
+
+- このフェーズに UI 作業がないのに、ブラウザ / playwright ツールが有効になっていますか？
+- 不要なプラットフォーム固有ツールが有効になっていますか？
+- 別のプロジェクトのプロジェクト固有 MCP がここでまだ有効になっていますか？
+
+サーバーを無効にすると、以降のすべてのターンからそのスキーマが削除されます。MCP のトリミングは `model_profile` の調整と**複合効果があります** — 両方のレバーは相加的であり、MCP の節約はオーケストレーターが生成するすべてのサブエージェントにわたってすぐに現れます。
+
+完全な監査、ハーネスリファレンス、`model_profile` との組み合わせに関するノートは、バンドルされた `context-budget.md` リファレンスの [MCP ツールスキーマコスト](../../get-shit-done/references/context-budget.md#mcp-tool-schema-cost-harness-concern) を参照してください。
### 非 Claude ランタイムの使用（Codex、OpenCode、Gemini CLI、Kilo）
-非 Claude ランタイム用に GSD をインストールした場合、インストーラーがモデル解決を設定済みのため、すべてのエージェントがランタイムのデフォルトモデルを使用します。手動設定は不要です。具体的には、インストーラーが設定に `resolve_model_ids: "omit"` を設定し、GSD に Anthropic モデル ID の解決をスキップしてランタイム独自のデフォルトモデルを使用するよう指示します。
+> **Codex CLI の最小サポートバージョン: `0.130.0`**（イシュー [#3562](https://github.com/open-gsd/gsd-core/issues/3562)）。
-非 Claude ランタイムで異なるエージェントに異なるモデルを割り当てるには、ランタイムが認識する完全修飾モデル ID を使用して `.planning/config.json` に `model_overrides` を追加します：
+非 Claude ランタイム向けに GSD をインストールした場合、インストーラーがすでにモデル解決を設定しています。手動設定は不要です — `resolve_model_ids: "omit"` が自動的に設定され、GSD に Anthropic モデル ID の解決をスキップしてランタイムが独自のデフォルトモデルを選ぶよう指示します。
+
+非 Claude ランタイムで異なるモデルを割り当てるには:
```json
{
@@ -737,102 +688,200 @@ budget プロファイルに切り替えてください：`/gsd-config --profile
}
```
-インストーラーは Gemini CLI、OpenCode、Kilo、Codex 用に `resolve_model_ids: "omit"` を自動設定します。非 Claude ランタイムを手動で設定する場合は、`.planning/config.json` に自分で追加してください。
+#### 設定変更 1 つで Claude から Codex へ切り替え（#2517）
-完全な説明は[設定リファレンス](../CONFIGURATION.md#non-claude-runtimes-codex-opencode-gemini-cli-kilo)をご覧ください。
+```json
+{
+ "runtime": "codex",
+ "model_profile": "balanced"
+}
+```
-### 非 Anthropic プロバイダーでの Claude Code の使用（OpenRouter、ローカル）
+[ランタイム対応プロファイル](CONFIGURATION.md#runtime-aware-profiles-2517) を参照してください。
-GSD サブエージェントが Anthropic モデルを呼び出し、OpenRouter やローカルプロバイダーを通じて支払っている場合は、`inherit` プロファイルに切り替えてください：`/gsd-config --profile inherit`。これにより、すべてのエージェントが特定の Anthropic モデルの代わりに現在のセッションモデルを使用します。`/gsd-settings` → モデルプロファイル → Inherit も参照してください。
+### 手動インストール / Node.js なしのセットアップ
-### 機密/プライベートプロジェクトでの作業
+GSD インストーラーを実行できない場合、`agents/` のソースファイルを直接使用することはできません — これらは Claude Code のネイティブフロントマター形式です。OpenCode では 2 つの変換が必要です:
-`/gsd-new-project` 時または `/gsd-settings` で `commit_docs: false` を設定してください。`.planning/` を `.gitignore` に追加してください。プランニングアーティファクトはローカルに保持され、git に含まれません。
+| フィールド | GSD ソース形式 | OpenCode 対応形式 | アクション |
+|---|---|---|---|
+| `tools:` | `Read, Bash, Grep`（カンマ区切り文字列） | フロントマターフィールドではない | `tools:` 行を完全に削除する |
+| `color:` | プレーン CSS カラー名 | 16 進数または OpenCode セマンティック名 | 16 進数に変換するか削除する |
-### GSD アップデートがローカル変更を上書きした
+**代替案:** Node.js がある任意のマシンでインストーラーを実行します:
-v1.17 以降、インストーラーはローカルで変更されたファイルを `gsd-local-patches/` にバックアップします。`/gsd-update --reapply` を実行して変更をマージし直してください。
+```bash
+npx @opengsd/gsd-core@latest --opencode --global
+```
-### ワークフロー診断 (`/gsd-forensics`)
+### Cline へのインストール
-ワークフローが明確でない形で失敗した場合 -- プランが存在しないファイルを参照する、実行が予期しない結果を生成する、状態が破損しているように見える -- `/gsd-forensics` を実行して診断レポートを生成してください。
+```bash
+npx @opengsd/gsd-core --cline --global # applies to all projects
+npx @opengsd/gsd-core --cline --local # this project only
+```
-**チェック内容：**
-- Git 履歴の異常（孤立コミット、予期しないブランチ状態、rebase アーティファクト）
-- アーティファクトの整合性（欠落または不正なプランニングファイル、壊れた相互参照）
-- 状態の不整合（ROADMAP のステータスと実際のファイル存在の不一致、設定のドリフト）
+### CodeBuddy へのインストール
-**出力：** `.planning/forensics/` に書き出される診断レポート。検出事項と推奨される修復手順が含まれます。
+```bash
+npx @opengsd/gsd-core --codebuddy --global
+```
-### サブエージェントが失敗したように見えるが作業は完了している
+### Qwen Code へのインストール
-Claude Code の分類バグに対する既知の回避策があります。GSD のオーケストレーター（execute-phase、quick）は、失敗を報告する前に実際の出力をスポットチェックします。失敗メッセージが表示されてもコミットが作成されている場合は、`git log` を確認してください -- 作業は成功している可能性があります。
+```bash
+npx @opengsd/gsd-core --qwen --global
+```
-### 並列実行によるビルドロックエラー
+### プレリリースエディションへのインストール
-並列ウェーブ実行中に pre-commit フックの失敗、cargo ロックの競合、30分以上の実行時間が発生した場合、これは複数のエージェントが同時にビルドツールをトリガーすることが原因です。GSD は v1.26 以降これを自動的に処理します — 並列エージェントはコミット時に `--no-verify` を使用し、オーケストレーターが各ウェーブ後にフックを1回実行します。古いバージョンを使用している場合は、プロジェクトの `CLAUDE.md` に以下を追加してください：
+インストーラーを実行する前に、ランタイムの `*_CONFIG_DIR` 環境変数をプレリリースディレクトリに設定してください:
+
+```bash
+WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
+```
+
+**サポートされているランタイムの環境変数リファレンス:**
+
+| ランタイム | 安定版デフォルト | オーバーライド環境変数 |
+|---|---|---|
+| Claude Code | `~/.claude` | `CLAUDE_CONFIG_DIR` |
+| Gemini CLI | `~/.gemini` | `GEMINI_CONFIG_DIR` |
+| OpenCode | `XDG_CONFIG_HOME/opencode` | `OPENCODE_CONFIG_DIR` |
+| Codex | （Codex CLI による） | `--config-dir` フラグ |
+| Copilot | `~/.copilot` | `COPILOT_CONFIG_DIR` |
+| Cursor | `~/.cursor` | `CURSOR_CONFIG_DIR` |
+| Windsurf | `~/.codeium/windsurf` | `WINDSURF_CONFIG_DIR` |
+| Antigravity | 自動検出 | `ANTIGRAVITY_CONFIG_DIR` |
+| Augment | `~/.augment` | `AUGMENT_CONFIG_DIR` |
+| Trae | `~/.trae` | `TRAE_CONFIG_DIR` |
+| Qwen Code | `~/.qwen` | `QWEN_CONFIG_DIR` |
+| Kilo | `~/.config/kilo` | `KILO_CONFIG_DIR` |
+| CodeBuddy | `~/.codebuddy` | `CODEBUDDY_CONFIG_DIR` |
+| Cline | `~/.cline` | `CLINE_CONFIG_DIR` |
+
+### 非 Anthropic プロバイダーでの Claude Code の使用
+
+`inherit` プロファイルに切り替えてください: `/gsd-config --profile inherit`。これにより、すべてのエージェントが現在のセッションモデルを使用します。
+
+### 機密 / プライベートプロジェクトの作業
+
+`/gsd-new-project` 中または `/gsd-settings` 経由で `commit_docs: false` を設定してください。`.planning/` を `.gitignore` に追加してください。
+
+### GSD の更新でローカル変更が上書きされた
+
+v1.17 以降、インストーラーはローカルで変更されたファイルを `gsd-local-patches/` にバックアップします。変更を元に戻すには `/gsd-update --reapply` を実行してください。
+
+### npm 経由で更新できない
+
+手順ごとの手動更新手順は [docs/manual-update.md](../manual-update.md) を参照してください。
+
+### ワークフロー診断（`/gsd-forensics`）
+
+ワークフローが明らかでない方法で失敗した場合、`/gsd-forensics` を実行して git 履歴の異常、アーティファクトの整合性、状態の不整合を網羅する診断レポートを生成してください。出力は `.planning/forensics/` に保存されます。
+
+### エグゼキューターサブエージェントが Bash コマンドで「Permission denied」になる
+
+必要なパターンを `~/.claude/settings.json` に追加してください。すべてのスタックに必要なコアパターン:
+
+```json
+"Bash(git add:*)",
+"Bash(git commit:*)",
+"Bash(git merge:*)",
+"Bash(git worktree:*)",
+"Bash(git rebase:*)",
+"Bash(git reset:*)",
+"Bash(git checkout:*)",
+"Bash(git switch:*)",
+"Bash(git restore:*)",
+"Bash(git stash:*)",
+"Bash(git rm:*)",
+"Bash(git mv:*)",
+"Bash(git fetch:*)",
+"Bash(git cherry-pick:*)",
+"Bash(git apply:*)",
+"Bash(gh:*)"
+```
+
+**プロジェクト単位の権限:** `~/.claude/settings.json` の代わりに、プロジェクトルートの `.claude/settings.local.json` に同じ `permissions.allow` ブロックを追加してください。
+
+### 並列実行でビルドロックエラーが発生する
+
+GSD は v1.26 以降これを自動的に処理します。古いバージョンを使用している場合は、プロジェクトの `CLAUDE.md` に追加してください:
```markdown
## Git Commit Rules for Agents
All subagent/executor commits MUST use `--no-verify`.
```
-並列実行を完全に無効にするには：`/gsd-settings` → `parallelization.enabled` を `false` に設定。
-
-### Windows：保護されたディレクトリでインストールがクラッシュする
-
-Windows でインストーラーが `EPERM: operation not permitted, scandir` でクラッシュした場合、これは OS で保護されたディレクトリ（例：Chromium ブラウザプロファイル）が原因です。v1.24 以降修正済み — 最新バージョンに更新してください。回避策として、インストーラー実行前に問題のあるディレクトリを一時的にリネームしてください。
+並列実行を完全に無効にするには: `/gsd-settings` → `parallelization.enabled` を `false` に設定してください。
---
-## リカバリークイックリファレンス
+## リカバリークイックリファレンス {#recovery-quick-reference}
-| 問題 | 解決策 |
-|---------|----------|
-| コンテキストの喪失 / 新セッション | `/gsd-resume-work` または `/gsd-progress` |
-| フェーズが失敗した | フェーズのコミットを `git revert` して再プランニング |
-| スコープ変更が必要 | `/gsd-phase`、`/gsd-phase --insert`、または `/gsd-phase --remove` |
-| 何かが壊れた | `/gsd-debug "description"` |
-| ワークフロー状態が破損している可能性 | `/gsd-forensics` |
-| ターゲットを絞った修正 | `/gsd-quick` |
-| プランがビジョンに合わない | `/gsd-discuss-phase [N]` で再プランニング |
-| コストが高い | `/gsd-config --profile budget` と `/gsd-settings` でエージェントをオフ |
-| アップデートがローカル変更を壊した | `/gsd-update --reapply` |
-| ステークホルダー向けセッションサマリーが欲しい | `/gsd-pause-work --report` |
-| 次のステップがわからない | `/gsd-progress --next` |
-| 並列実行でビルドエラー | GSD を更新するか `parallelization.enabled: false` を設定 |
+| 問題 | 解決策 |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| コンテキスト喪失 / 新しいセッション | `/gsd-resume-work` または `/gsd-progress` |
+| フェーズが失敗した | フェーズのコミットを `git revert` してから再プランする |
+| スコープを変更する必要がある | `/gsd-phase`（デフォルト）、`/gsd-phase --insert`、または `/gsd-phase --remove` |
+| 何かが壊れた | `/gsd-debug "description"`（分析のみで修正なしは `--diagnose` を追加） |
+| STATE.md の同期ずれ | `state validate` してから `state sync` |
+| ワークフロー状態が破損しているように見える | `/gsd-forensics` |
+| クイックなターゲット修正 | `/gsd-quick` |
+| プランがビジョンと一致しない | `/gsd-discuss-phase [N]` してから再プランする |
+| コストが高騰している | `/gsd-config --profile budget` と `/gsd-settings` でエージェントをオフに |
+| 更新でローカル変更が壊れた | `/gsd-update --reapply` |
+| ステークホルダー向けセッションサマリーが欲しい | `/gsd-pause-work --report` |
+| 次のステップがわからない | `/gsd-progress --next` |
+| 並列実行でビルドエラーが発生する | GSD を更新するか `parallelization.enabled: false` を設定する |
---
-## プロジェクトファイル構造
+## プロジェクトファイル構造 {#project-file-structure}
-参考として、GSD がプロジェクトに作成するファイル構造を示します：
-
-```
+```text
.planning/
- PROJECT.md # プロジェクトのビジョンとコンテキスト（常に読み込まれる）
- REQUIREMENTS.md # スコープ付き v1/v2 要件（ID 付き）
- ROADMAP.md # ステータス追跡付きフェーズ分割
- STATE.md # 決定事項、ブロッカー、セッションメモリ
- config.json # ワークフロー設定
- MILESTONES.md # 完了したマイルストーンのアーカイブ
- HANDOFF.json # 構造化セッション引き継ぎ（/gsd-pause-work から）
- research/ # /gsd-new-project からのドメインリサーチ
- reports/ # セッションレポート（/gsd-pause-work --report から）
+ PROJECT.md # Project vision and context (always loaded)
+ REQUIREMENTS.md # Scoped v1/v2 requirements with IDs
+ ROADMAP.md # Phase breakdown with status tracking
+ STATE.md # Decisions, blockers, session memory
+ config.json # Workflow configuration
+ MILESTONES.md # Completed milestone archive
+ HANDOFF.json # Structured session handoff (from /gsd-pause-work)
+ research/ # Domain research from /gsd-new-project
+ reports/ # Session reports (from /gsd-pause-work --report)
todos/
- pending/ # 作業待ちのキャプチャされたアイデア
- done/ # 完了した TODO
- debug/ # アクティブなデバッグセッション
- resolved/ # アーカイブされたデバッグセッション
- codebase/ # ブラウンフィールドコードベースマッピング（/gsd-map-codebase から）
+ pending/ # Captured ideas awaiting work
+ done/ # Completed todos
+ debug/ # Active debug sessions
+ resolved/ # Archived debug sessions
+ spikes/ # Feasibility experiments (from /gsd-spike)
+ NNN-name/ # Experiment code + README with verdict
+ MANIFEST.md # Index of all spikes
+ sketches/ # HTML mockups (from /gsd-sketch)
+ NNN-name/ # index.html (2-3 variants) + README
+ themes/
+ default.css # Shared CSS variables for all sketches
+ MANIFEST.md # Index of all sketches with winners
+ codebase/ # Brownfield codebase mapping (from /gsd-map-codebase)
phases/
XX-phase-name/
- XX-YY-PLAN.md # アトミック実行プラン
- XX-YY-SUMMARY.md # 実行結果と決定事項
- CONTEXT.md # 実装の好み
- RESEARCH.md # エコシステムリサーチの成果
- VERIFICATION.md # 実行後の検証結果
- XX-UI-SPEC.md # UI デザインコントラクト（/gsd-ui-phase から）
- XX-UI-REVIEW.md # ビジュアル監査スコア（/gsd-ui-review から）
- ui-reviews/ # /gsd-ui-review からのスクリーンショット（gitignore 対象）
+ XX-YY-PLAN.md # Atomic execution plans
+ XX-YY-SUMMARY.md # Execution outcomes and decisions
+ CONTEXT.md # Your implementation preferences
+ RESEARCH.md # Ecosystem research findings
+ VERIFICATION.md # Post-execution verification results
+ XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase)
+ XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
+ ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
```
+
+---
+
+## 関連 {#related}
+
+- [ドキュメント索引](README.md)
+- [コマンド](COMMANDS.md)
+- [設定](CONFIGURATION.md)
+- [フェーズループ](explanation/the-phase-loop.md)
diff --git a/docs/ja-JP/context-monitor.md b/docs/ja-JP/context-monitor.md
index 4ec0ab4c6..d17532873 100644
--- a/docs/ja-JP/context-monitor.md
+++ b/docs/ja-JP/context-monitor.md
@@ -2,9 +2,9 @@
ツール使用後に実行されるフック（Claude Code では `PostToolUse`、Gemini CLI では `AfterTool`）で、コンテキストウィンドウの使用量が高くなった際にエージェントに警告します。
-## 課題
+## 問題
-ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、タスクの途中で状態を保存できないまま停止する可能性があります。
+ステータスラインはコンテキスト使用量を**ユーザー**に表示しますが、**エージェント**自身はコンテキストの制限を認識していません。コンテキストが不足すると、エージェントは限界に達するまで作業を続行し、状態を保存できないままタスクの途中で止まる可能性があります。
## 仕組み
@@ -16,34 +16,34 @@
## しきい値
| レベル | 残量 | エージェントの動作 |
-|--------|------|------------------|
+|-------|-----------|----------------|
| Normal | > 35% | 警告なし |
| WARNING | <= 35% | 現在のタスクをまとめ、新しい複雑な作業の開始を避ける |
| CRITICAL | <= 25% | 即座に停止し、状態を保存する（`/gsd-pause-work`） |
## デバウンス
-エージェントへの繰り返し警告を防ぐため:
+エージェントへの繰り返し警告を防ぐため：
- 最初の警告は即座に発火
-- 以降の警告は間に5回のツール使用が必要
+- 以降の警告は間に 5 回のツール使用が必要
- 深刻度のエスカレーション（WARNING -> CRITICAL）はデバウンスをバイパス
## アーキテクチャ
```
-ステータスラインフック (gsd-statusline.js)
- | 書き込み
+Statusline Hook (gsd-statusline.js)
+ | writes
v
/tmp/claude-ctx-{session_id}.json
- ^ 読み取り
+ ^ reads
|
-コンテキストモニター (gsd-context-monitor.js, PostToolUse/AfterTool)
- | 注入
+Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
+ | injects
v
-additionalContext -> エージェントが警告を確認
+additionalContext -> Agent sees warning
```
-ブリッジファイルはシンプルな JSON オブジェクトです:
+ブリッジファイルはシンプルな JSON オブジェクトです：
```json
{
@@ -60,56 +60,21 @@ GSD の `/gsd-pause-work` コマンドは実行状態を保存します。WARNIN
## セットアップ
-両フックは `npx @opengsd/gsd-core` のインストール時に自動的に登録されます:
+両フックは `npx @opengsd/gsd-core` のインストール時に自動的に登録されます——通常の状況では手動の手順は不要です。フック設定の詳細、しきい値のオーバーライド、手動登録の例については、[設定](CONFIGURATION.md) を参照してください。
-- **ステータスライン**（ブリッジファイルの書き込み）: settings.json の `statusLine` として登録
-- **コンテキストモニター**（ブリッジファイルの読み取り）: settings.json の `PostToolUse` フックとして登録（Gemini では `AfterTool`）
-
-`~/.claude/settings.json`（Claude Code）への手動登録:
-
-```json
-{
- "statusLine": {
- "type": "command",
- "command": "node ~/.claude/hooks/gsd-statusline.js"
- },
- "hooks": {
- "PostToolUse": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/hooks/gsd-context-monitor.js"
- }
- ]
- }
- ]
- }
-}
-```
-
-Gemini CLI（`~/.gemini/settings.json`）の場合、`PostToolUse` の代わりに `AfterTool` を使用します:
-
-```json
-{
- "hooks": {
- "AfterTool": [
- {
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.gemini/hooks/gsd-context-monitor.js"
- }
- ]
- }
- ]
- }
-}
-```
+簡単な参考として：ステータスラインフックは `settings.json` に `statusLine` として登録されます；コンテキストモニター（`gsd-context-monitor.js`）は `PostToolUse` フックとして登録されます（Gemini CLI の場合は `AfterTool`）。どちらのエントリも、インストーラーを実行した Node 実行ファイルの絶対パスを使います。Windows PowerShell では、引用符付きの実行ファイルパスに `&` をプレフィックスしてください。
## 安全性
- フックは全体を try/catch で囲み、エラー時はサイレントに終了
-- ツール実行をブロックしない — モニターの故障がエージェントのワークフローを壊してはならない
-- 古いメトリクス（60秒以上前）は無視
+- ツール実行をブロックしない — モニターが壊れてもエージェントのワークフローを壊してはならない
+- 古いメトリクス（60 秒以上前）は無視
- ブリッジファイルが存在しない場合も正常に処理（サブエージェント、新規セッション）
+
+---
+
+## Related
+
+- [アーキテクチャ](ARCHITECTURE.md)
+- [設定](CONFIGURATION.md)
+- [ドキュメント索引](README.md)
diff --git a/docs/ja-JP/explanation/context-engineering.md b/docs/ja-JP/explanation/context-engineering.md
new file mode 100644
index 000000000..8637e9e1d
--- /dev/null
+++ b/docs/ja-JP/explanation/context-engineering.md
@@ -0,0 +1,90 @@
+# コンテキストエンジニアリング
+
+> GSD Core が存在する理由、そして解決しようとしている問題。
+
+---
+
+## 問題：コンテキスト腐敗
+
+AI コーディングセッションは常に新鮮な状態から始まります。モデルは質問を読み取り、それについて推論し、返答します。しかしセッションが一度のやり取りで終わることはほとんどありません。追加の質問をし、エラーメッセージを貼り付け、コードを繰り返し修正し、モデルが脱線したときに軌道修正します。ターンを重ねるたびに、モデルが一度に「見える」有限のテキストバッファであるコンテキストウィンドウにトークンが積み重なっていきます。
+
+そのウィンドウが満たされると、微妙なことが起きます。モデルは明らかには失敗しません。答え続けます。しかしその品質は静かに低下していきます。最初の指示はモデルが注意を向けられる範囲の端へと追いやられます。最初のやり取りで確立したニュアンス——述べた制約、合意したアーキテクチャ、指摘したエッジケース——が後から積み重なったすべてのものと注意を奪い合います。研究者たちはこれを **コンテキスト腐敗** と呼びます。
+
+コンテキスト腐敗はいくつかの形で現れます：
+
+- モデルが以前に認めた決定と矛盾し始める。
+- セッション開始時に確立したコーディングスタイルの規約からコードが外れていく。
+- 計画が、明確に述べられていたが履歴の奥深くに埋もれた要件を無視し始める。
+- モデルが 20 メッセージ前に正確に把握していたファイル名や関数シグネチャを誤って出力する。
+
+これはモデルのバグではありません。トランスフォーマーアテンションが長いシーケンスに対してどう機能するかという根本的な性質です。モデルは「忘れて」いるわけではありません——人間的な意味での「記憶」は最初からありません。有限のウィンドウ全体で関連性を重み付けしており、そのウィンドウに蓄積されたノイズが増えるにつれて、シグナル対ノイズ比が低下するのです。
+
+単純な対応策は `/clear` してやり直すことです。しかしそれでは連続性が失われます。コンテキストを再説明し、関連ファイルを再貼り付けし、制約を再度述べなければなりません。セッションは実質的にゼロにリセットされます。
+
+---
+
+## GSD Core の答え：フレッシュコンテキストサブエージェント
+
+GSD Core の核心的な洞察は、コーディングセッションの作業の *ほとんど* はメインコンテキストで行う必要がそもそもないということです。調査、計画立案、コード作成、検証はそれぞれ独立した、境界が明確なタスクです。それぞれを専門化されたサブエージェントに渡すことができます。そのエージェントはクリーンで慎重にスコープされたコンテキストウィンドウで開始し、結果をスリムなオーケストレーターに報告します。
+
+これはコンテキスト腐敗への迂回策ではありません。構造的な解決策です。
+
+オーケストレーター——あなたのメインセッション——はソースファイルに触れません。エージェントを生成し、その結果を収集し、共有状態を更新し、次のステップへとルーティングします。自身がほとんど何もしないため、そのコンテキストウィンドウはゆっくりと予測可能に拡大します。重い作業はそれぞれ新鮮な状態で開始し、タスクに必要なコンテキストだけを受け取り、完了したら終了するエージェントの中で行われます。
+
+これが実際にどういう意味かを考えてみましょう。`/gsd-plan-phase` を実行すると、オーケストレーターは：
+
+1. コンパクトな JSON コンテキストペイロード（プロジェクト概要、フェーズ目標、関連設定）を読み込む。
+2. 200k トークンのクリーンなウィンドウで調査エージェントを生成する。
+3. 調査出力とフェーズ要件でプランナーエージェントを生成する。
+4. 実行前に計画を検証するプランチェッカーエージェントを生成する。
+
+各エージェントはセッション履歴の蓄積に邪魔されることなく、最大限の能力で動作します。プランナーが `PLAN.md` ファイルを `.planning/phases/` に書き込むと、その出力は永続的なアーティファクト——共有コンテキストウィンドウの中の脆弱な記憶ではなく——になります。
+
+---
+
+## 仕様駆動開発とメタプロンプティング
+
+コンテキストエンジニアリング単体では不十分です。エージェントが新鮮な状態で開始しても、曖昧な指示を受け取れば、曖昧な出力を生み出します。GSD Core はフレッシュコンテキストサブエージェントと 2 つの補完的な規律を組み合わせています。
+
+**仕様駆動開発** とは、すべてのフェーズが実行開始前に構造化されたアーティファクトを生成することを意味します。`CONTEXT.md` は Discuss ステップでの実装上の決定を記録します。`RESEARCH.md` は調査エージェントが見つけたものを記録します。`PLAN.md` は作業を独立した、依存関係の順序に従ったタスクに分解し、明確な受け入れ基準を持ちます。エグゼキューターエージェントがファイルに触れる時点では、長い会話の再解釈ではなく、正確な仕様から作業します。
+
+**メタプロンプティング** とは、エージェント定義自体が慎重に設計されたプロンプトであり、アドホックな指示ではないことを意味します。`get-shit-done/workflows/` および `agents/` 内のファイルは、タスクのスコープの決め方、何を検証するか、いつ人間のチェックポイントにエスカレートするかについての実践的な知識をエンコードしています。ユーザーはこの知識をセッションごとに再説明する必要はありません。それはシステム自身のプロンプトに組み込まれています。
+
+この組み合わせは意図的です。フレッシュコンテキストは各エージェントが明確に推論することを保証します。仕様駆動のアーティファクトは各エージェントが *正しい* ことについて推論することを保証します。メタプロンプティングは各エージェントが *うまく* 推論する方法を知っていることを保証します。
+
+---
+
+## `.planning/` の役割
+
+コンテキストエンジニアリングには、知識がコンテキストリセットを超えて生き残ることが必要です。GSD Core はこのためにファイルシステムを使用します。すべての意味のある出力は、人間が読める Markdown または JSON として `.planning/` に書き込まれます。これが意味することは：
+
+- セッションを再起動しても（またはモデルがクラッシュしても）作業が失われない。
+- 後続のエージェントは共有された会話履歴に依存せず、以前のアーティファクトを直接読み取ることができる。
+- 計画アーティファクトを検査、編集、または git にコミットできる——それらはプレーンテキストであり、データベース内の不透明な状態ではない。
+
+`STATE.md` はこのシステムの背骨です。プロジェクトの現在位置（どのマイルストーン、どのフェーズ、どの計画が完了しているか）、アクティブな決定とブロッカー、進捗メトリクスを記録します。ワークフローが開始されると、まず `STATE.md` を読み取って方向を確認します。ワークフローが意味のあるステップを完了すると、`STATE.md` に書き戻します。エージェントは記憶に頼りません。ファイルに頼ります。
+
+---
+
+## トレードオフ
+
+ここではトレードオフについて正直に述べることが重要です。
+
+**オーバーヘッド。** フェーズループには実際の摩擦があります。`/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase` を別々のステップとして実行することは、普通のセッションに「この機能を書いて」と入力するよりも多くの経過時間がかかります。小さくてよく理解された変更に対しては、そのオーバーヘッドは正当化されません。
+
+**レイテンシ。** 新鮮なコンテキストで複数のサブエージェントを生成することは、単一のインコンテキスト編集より遅くなります。調査、計画立案、実行のそれぞれにラウンドトリップのコストが発生します。
+
+**シンプルなタスクへの過剰な手続き。** 変数名を変更したり、タイポを修正したり、欠落しているインポートを追加したりする場合、フェーズループは過剰です。GSD Core は完全なフェーズを必要としないアドホックな作業のために `/gsd-quick` と `/gsd-fast` を提供します。[クイックタスクとファストタスクの処理](../how-to/handle-quick-and-fast-tasks.md) を参照してください。
+
+フェーズループは、コンテキスト腐敗が本当のリスクになるほど作業が複雑な場合——マルチファイル機能、横断的なリファクタリング、時間やセッションをまたぐ作業——に価値を発揮します。それ以外のすべてには、より軽量なプリミティブを使ってください。
+
+経験則として役立つのは：タスクが単一の短いプロンプトで完全に仕様化でき、さらなる明確化なしに 1 エージェントターンで完了できるなら、フェーズループをスキップしてください。タスクが調査を必要とし、最近読んでいないファイルを含むか、まだ確定していない決定に依存している場合は、フェーズループが保護してくれます。
+
+---
+
+## Related
+
+- [フェーズループ](the-phase-loop.md) — Discuss → Plan → Execute → Verify → Ship サイクルがコンテキストエンジニアリングをどう実践するか
+- [マルチエージェントオーケストレーション](multi-agent-orchestration.md) — サブエージェントがどのように生成、スコープ設定、調整されるか
+- [アーキテクチャ](../ARCHITECTURE.md) — システムアーキテクチャ、エージェントモデル、データフロー
+- [ドキュメント索引](../README.md)
diff --git a/docs/ja-JP/explanation/multi-agent-orchestration.md b/docs/ja-JP/explanation/multi-agent-orchestration.md
new file mode 100644
index 000000000..3a64ab961
--- /dev/null
+++ b/docs/ja-JP/explanation/multi-agent-orchestration.md
@@ -0,0 +1,146 @@
+# GSD Core におけるマルチエージェントオーケストレーション
+
+> **解説** — このドキュメントは、GSD Core がマルチエージェントオーケストレーションを中心に設計されている *理由* と、*各部品がどのように組み合わさるか* を説明します。ステップバイステップのガイドではありません。設定については、[モデルプロファイルの設定](../how-to/configure-model-profiles.md) と [設定リファレンス](../CONFIGURATION.md) を参照してください。完全なエージェントロスターについては、[インベントリ](../INVENTORY.md) を参照してください。
+
+---
+
+## この設計が解決する問題
+
+AI コーディングエージェントは劣化します。モデルが悪くなるからではなく、*コンテキストウィンドウが満杯になる* からです。会話が大きくなるにつれて、以前の決定やコードは中間ステップのノイズによって押し出されるか薄められます。複雑なタスクで 5 番目のファイルを書く頃には、エージェントは最初のメッセージで述べた制約をすでに忘れているかもしれません。これは *コンテキスト腐敗* と呼ばれることがあります。
+
+GSD Core のマルチエージェント設計はその問題への直接的な応答です。セッション全体を抱える一つの長期実行エージェントの代わりに、薄いオーケストレーターが短命の専門化されたエージェントを生成します。それぞれが **フレッシュな 200K トークンのコンテキストウィンドウ** と、自分の特定の仕事をするために必要な *アーティファクトだけ* を持ちます。オーケストレーターは自分では重い作業をしません。コンテキストを読み込み、適切なエージェントを生成し、結果を収集し、`.planning/` の共有状態を更新します。
+
+---
+
+## オーケストレーター → エージェントパターン
+
+`get-shit-done/workflows/` のすべてのワークフローは同じ形を持ちます：
+
+```text
+Orchestrator（ワークフロー .md ファイル）
+ │
+ ├── コンテキスト読み込み
+ │ gsd-tools.cjs init
+ │ → JSON: プロジェクト情報、設定、状態、フェーズ詳細
+ │
+ ├── モデル解決
+ │ gsd-tools.cjs resolve-model
+ │ → opus | sonnet | haiku | inherit
+ │
+ ├── 専門化エージェント生成（Task/SubAgent 呼び出し）
+ │ ├── エージェント定義（agents/*.md）
+ │ ├── コンテキストペイロード（init JSON）
+ │ ├── モデルアサイン
+ │ └── ツール権限
+ │
+ ├── 結果収集
+ │
+ └── 状態更新
+ gsd-tools.cjs state update / state patch / state advance-plan
+```
+
+オーケストレーターは意図的に薄く保たれています。ドメインについて推論せず、コードを書かず、次のステップへルーティングする以上に結果を解釈しません。この境界により各レイヤーの責任が明確になり、オーケストレーターのコンテキストにドメインノイズが蓄積するのを防ぎます。
+
+### エージェントロスター
+
+GSD Core のエージェントは、調査 → 計画 → 実行 → 検証パイプラインにマッピングされる機能カテゴリに分類されます：
+
+| カテゴリ | エージェント | 典型的な並列性 |
+|---|---|---|
+| 調査者 | `gsd-project-researcher`、`gsd-phase-researcher`、`gsd-ui-researcher`、`gsd-advisor-researcher` | 4 並列（スタック、機能、アーキテクチャ、落とし穴） |
+| 合成者 | `gsd-research-synthesizer` | 調査者完了後、順次実行 |
+| プランナー | `gsd-planner`、`gsd-roadmapper` | 順次実行 |
+| チェッカー | `gsd-plan-checker`、`gsd-integration-checker`、`gsd-ui-checker`、`gsd-nyquist-auditor` | 順次実行、最大 3 回の修正反復 |
+| エグゼキューター | `gsd-executor` | ウェーブ内並列、ウェーブ間順次 |
+| 検証者 | `gsd-verifier` | すべてのエグゼキューター完了後、順次実行 |
+| マッパー | `gsd-codebase-mapper` | 4 並列サブプローブ |
+| 監査者 | `gsd-ui-auditor`、`gsd-security-auditor` | 順次実行 |
+
+各エージェント定義（`agents/*.md` 内）は、許可されたツールアクセス、目的、ターミナル出力の色を宣言します。ファイルを読み取り、単一の出力ドキュメントを書くだけでよいエージェントには、まさにその権限だけが与えられます——Bash 実行なし、より広い状態へのアクセスなし。この制約は意図的です：エージェントが予期しない動作をした場合の影響範囲を小さく保ちます。
+
+完全な 31 エージェントロスターについては、[インベントリ](../INVENTORY.md#agents-31-shipped) を参照してください。
+
+---
+
+## ウェーブベースの並行実行
+
+マルチエージェント設計の最も目に見える表れは、`/gsd-execute-phase` が互いに依存しあうことのある計画セットをどう処理するかです。
+
+エグゼキューターを生成する前に、オーケストレーターは **ウェーブ分析** を実行します：各 `PLAN.md` ファイルの依存関係宣言を読み取り、計画をウェーブにグループ化します。宣言された依存関係がない計画がウェーブ 1 を形成し、並列に実行されます。ウェーブ 1 に依存する計画がウェーブ 2 を形成し、以下同様です。
+
+```text
+Plan 01（依存なし） ─┐
+Plan 02（依存なし） ─┤─── ウェーブ 1（並列）
+Plan 03（依存: 01） ─┤─── ウェーブ 2（ウェーブ 1 待ち）
+Plan 04（依存: 02） ─┘
+Plan 05（依存: 03, 04） ─── ウェーブ 3（ウェーブ 2 待ち）
+```
+
+ウェーブ内の各エグゼキューターは：
+
+- フレッシュなコンテキストウィンドウ（200K トークン、または対応モデルでは最大 1M）を受け取る
+- 担当する特定の `PLAN.md` を受け取る
+- プロジェクトコンテキスト（`PROJECT.md`、`STATE.md`）を受け取る
+- フェーズコンテキスト（`CONTEXT.md`、利用可能な場合は `RESEARCH.md`）を受け取る
+- 完了時にアトミックな git コミットを生成する
+- 構築したものを説明する `SUMMARY.md` を書く
+
+ウェーブ内のすべてのエグゼキューターが完了した後、オーケストレーターはウェーブ全体のプリコミットフックを一度実行します。エグゼキューターは `--no-verify` でコミットし、複数のエージェントが並行してコミットするときのビルドロック競合（たとえば Rust プロジェクトでの Cargo ロック競合）を防ぎます。したがってフックはコミットごとに一度ではなく、ウェーブごとに一度実行されます。
+
+### 並行コミットの安全性
+
+複数のエグゼキューターが同時に実行される場合、2 つのメカニズムが書き込み競合を防ぎます：
+
+1. **`STATE.md` へのアトミックロック** — `STATE.md` へのすべての書き込みはロックファイル（`STATE.md.lock`）と `O_EXCL` アトミック作成を使います。これにより、2 つのエージェントそれぞれがファイルを読み取り、異なるフィールドを変更し、後から書いた方が前の変更を上書きするという read-modify-write 競合が防止されます。古いロック（10 秒以上）は自動的にクリアされます。
+
+2. **ウェーブごとのフック実行** — 各エグゼキューターがプリコミットフックを独立して実行する代わりに（共有ビルドアーティファクトでファイルレベルの競合を引き起こす可能性がある）、オーケストレーターは各ウェーブが完了した後に `git hook run pre-commit` を一度実行します。
+
+---
+
+## 大窓モデルへのアダプティブコンテキスト拡充
+
+標準の 200K コンテキストウィンドウは、エグゼキューターが単一の集中した計画を実装するには十分です。設定された `context_window` が 500K トークン以上の場合（たとえば Opus 4.6 または Sonnet 4.6 を 1M クラスモードで使用する場合）、オーケストレーターは標準ウィンドウでは収まらない追加コンテキストでサブエージェントプロンプトを自動的に拡充します：
+
+- **エグゼキューターエージェント** は前のウェーブの `SUMMARY.md` ファイルとフェーズの `CONTEXT.md`/`RESEARCH.md` を受け取り、フェーズ内でのクロスプラン認識を得る
+- **検証者エージェント** はすべての `PLAN.md`、`SUMMARY.md`、`CONTEXT.md` ファイルと `REQUIREMENTS.md` を受け取り、履歴を考慮した検証が可能になる
+
+この拡充は `config.json` の `context_window` の値に条件付きです。標準ウィンドウ設定では、プロンプトはトークン効率を最大化するためにキャッシュフレンドリーな順序で切り詰められたバージョンを使います。
+
+---
+
+## なぜこの設計か——コンテキストエンジニアリングとの関連
+
+オーケストレーター → エージェントパターンは、*コンテキストエンジニアリング* というより広いアプローチの一部としてのみ意味を持ちます：AI エージェントがコンテキストウィンドウで受け取るものが、モデルの層やプロンプト品質と同じくらい重要だという考え方。完全な解説については [コンテキストエンジニアリング](context-engineering.md) を参照してください。
+
+マルチエージェントオーケストレーションはコンテキストエンジニアリングを 2 つの方法で実装します：
+
+**コンテキストの分離。** 各エージェントは必要なものだけを受け取ります。調査者はプロジェクト説明とドメイン質問を受け取ります；完全な計画履歴は受け取りません。検証者はすべての計画とサマリーを受け取ります；生の調査は受け取りません。分離により各エージェントのコンテキストは他のパイプラインステージのノイズで薄まるのではなく、シグナルで密度が高く保たれます。
+
+**セッションをまたいだコンテキストの衛生。** すべての状態は（エージェントのコンテキストウィンドウではなく）`.planning/` に人間が読める Markdown と JSON として存在するため、GSD ワークフローはコンテキストリセット（`/clear`）、タブ切り替え、複数日のブレークを超えて生き残ります。次のエージェントは常に、長い会話の再構築された記憶からではなく、永続化され検証されたアーティファクトから開始します。
+
+---
+
+## トレードオフ
+
+マルチエージェントオーケストレーションはタダではありません。
+
+**調整オーバーヘッド。** 各エージェントの生成はラウンドトリップです：オーケストレーターがプロンプトをフォーマットし、コンテキストを渡し、サブエージェントが完了するまで待ち（通常 1〜5 分）、結果を解析する必要があります。一つのコンテキストで作業する一つの有能なエージェントは、シンプルなタスクをより速く終わらせるでしょう。GSD は依存関係が許す限りデフォルトで並列性を採用することでこれを軽減します——`plan-phase` の 4 人の調査者は順次ではなく同時に実行されます。
+
+**実行中の不透明性。** サブエージェントの実行中は、その作業は親セッションには見えません。ライブの進捗ストリームはありません。これはフレッシュコンテキスト設計の意図的な帰結です：サブエージェントは自分自身のコンテキストウィンドウで動作しています。オーケストレーターは生成ラインに生存通知を表示します（「サブエージェントで実行中——返ってくるまで出力なし」）で期待値を設定します。
+
+**コンテキストスティッチングコスト。** 各エージェントに適切なアーティファクトをパッケージ化するには、オーケストレーターがコンテキストペイロードを組み立てて送信するためにトークンを使う必要があります。これが分離のコストです。`gsd-tools.cjs init` ハンドラーは、完全性とトークン予算のバランスを取る JSON ペイロードを生成し、繰り返し呼び出しでキャッシュにヒットするようにペイロードの安定した部分（プロジェクト定義、設定）にキャッシュフレンドリーな順序を適用します。
+
+**モデルコストの増幅。** Opus 層で 5 つのエージェントを並行して実行することは、1 つを実行するよりコストがかかります。モデルプロファイルシステム（`model_profiles.md`、`model-profiles.cjs` でエージェントごとに解決）により、重要度の低いエージェントに安価な層を割り当てることができます。`dynamic_routing` 機能は、すべてのエージェントを安価な層で開始し、ソフトフェイラー時にのみエスカレートすることでさらにコストを削減します。詳細なオプションについては [設定](../CONFIGURATION.md) を参照してください。
+
+これらのコストの見返りとして、この設計は*大きなフェーズにわたる一貫した品質*を買います。400 行の計画で 10 番目のファイルを書くエグゼキューターは、コンテキストがフレッシュだから劣化しません。20 の要件を確認する検証者は、すべてを会話履歴ではなく構造化された入力として受け取ったから最初の 10 を忘れません。
+
+---
+
+## Related
+
+- [コンテキストエンジニアリング](context-engineering.md) — この設計を動機づける上流の原則
+- [モデルプロファイルの設定](../how-to/configure-model-profiles.md) — エージェントごとにモデル層を割り当てる方法
+- [設定リファレンス](../CONFIGURATION.md) — `models`、`model_overrides`、`dynamic_routing`、`context_window` を含む完全な `config.json` スキーマ
+- [インベントリ](../INVENTORY.md) — 信頼できるエージェントロスターとワークフローリスト
+- [アーキテクチャ](../ARCHITECTURE.md#agent-model) — オーケストレーター → エージェントパターンとウェーブ実行モデルの実装レベルの詳細
+- [ドキュメント索引](../README.md)
diff --git a/docs/ja-JP/explanation/security-model.md b/docs/ja-JP/explanation/security-model.md
new file mode 100644
index 000000000..afc5c3d93
--- /dev/null
+++ b/docs/ja-JP/explanation/security-model.md
@@ -0,0 +1,117 @@
+# GSD Core セキュリティモデル
+
+> **解説** — このドキュメントは、GSD Core がなぜこのようなセキュリティ姿勢を持っているか、そして *各レイヤーがどのように組み合わさるか* を説明します。すべてのフックパラメーターのリファレンスではありません。`/gsd-secure-phase` コマンドとそのオプションについては、[コマンド](../COMMANDS.md) を参照してください。実装レベルのフックアーキテクチャについては、[アーキテクチャ § フックシステム](../ARCHITECTURE.md#hook-system) を参照してください。組織全体のセキュリティベースライン（スキャナー制御、インシデントチェックリスト、所有権モデル）については、[SECURITY.md](../../../SECURITY.md) を参照してください。
+
+---
+
+## AI 駆動開発が専用のセキュリティ姿勢を必要とする理由
+
+従来のコードエディターはあなたに代わって任意のパッケージを実行しません。GSD Core は実行します。調査 → 計画 → 実行パイプラインは「パッケージ名を指定する」から「`npm install ` を実行する」まで、「計画アーティファクトを書く」から「そのアーティファクトを LLM システムプロンプトとして使う」までの完全なパスを自動化します。各自動化ステップは人間をループから外します——そして各除去は潜在的な攻撃面です。
+
+GSD Core のセキュリティモデルは一つの組織原則の上に構築されています：**多層防御**。単一の制御が完璧だとは想定しません。複数の重複したレイヤーがそれぞれ異なるクラスのリスクを軽減し、合わせて全体を完全に排除することなく攻撃面を実質的に悪用しにくくします。このドキュメントの末尾にある正直な要約は、システムが何に対して保護できないかを説明します。
+
+---
+
+## レイヤー 1 — サプライチェーン保護：パッケージ正当性ゲート
+
+### 脅威
+
+AI モデルはパッケージ名を幻覚します。これはまれな失敗モードではありません：2025 年の研究では、AI が生成するパッケージ参照のおよそ 20% が正規のパッケージに対応しない幻覚された名前であることが記録されています。これらの幻覚された名前のサブセット——同じ研究でおよそ 43%——はプロンプトをまたいで一貫して繰り返され、攻撃者は AI ツールが一般的に生成する名前を観察し、npm、PyPI、または crates.io でそれらの名前を悪意のあるポストインストールスクリプト付きで事前登録できます。この技術は *スロップスクワッティング* と呼ばれます。
+
+スロップスクワッティングの陰湿な点は、`npm view` を通過する幻覚された名前が *正当に見える* ことです。レジストリエントリは誰かがその名前を登録したことを証明するだけです——パッケージが AI の言う通りのことをするとも、正規のユーザーがいるとも、インストールスクリプトが安全だとも証明しません。ゲートがなければ、幻覚された名前は GSD の調査者 → プランナー → エグゼキューターパイプラインを検出されずに流れ、最終的にあなたのマシンで `npm install ` として実行されるでしょう。
+
+### ゲートの仕組み
+
+ゲートは 3 つのパイプラインステージにわたって動作します：
+
+**調査ステージ。** `gsd-phase-researcher` が外部パッケージを推奨するとき、それぞれに対して `slopcheck install --json` を実行します。結果は `RESEARCH.md` の `## Package Legitimacy Audit` テーブルに書き込まれます。`[SLOP]`（高信頼度の幻覚または攻撃者登録済み）とタグ付けされたパッケージは、ファイルが保存される前に **`RESEARCH.md` から完全に除去されます**。それらはプランナーに届きません。
+
+**計画ステージ。** `gsd-planner` は監査テーブルを読み取ります。`[SUS]`（疑わしい：新規登録、低ダウンロード数、ソースリポジトリなし、または人気パッケージに近い命名パターン）または `[ASSUMED]`（直接レジストリ検証ではなく WebSearch から取得）とタグ付けされたパッケージについて、プランナーはインストールステップの前に **`checkpoint:human-verify` タスクを挿入します**。チェックポイントにはレジストリページへの直接リンクと、確認すべき具体的な事項が含まれます：メンテナー履歴、イシュートラッカーの活動、疑わしいインストールスクリプトがないこと。
+
+**実行ステージ。** インストールが失敗した場合、`gsd-executor` は**チェックポイントを表示して停止します**。それ自体が悪意のある可能性のある代替パッケージ名をサイレントに試みません。これはエグゼキューターの動作における明示的なルールです（エグゼキュータエージェント定義の RULE 3）。
+
+### WebSearch パッケージが常に `[ASSUMED]` である理由
+
+WebSearch を通じて発見されたパッケージ名は、`npm view` が成功するかどうかに関わらず `[ASSUMED]` とタグ付けされます。レジストリに存在するパッケージは、インストールしても安全なパッケージと同じではありません。`npm view` は登録を証明するだけで、正当性を証明しません。`[ASSUMED]` タグは `[SUS]` と同じ人間検証チェックポイントをトリガーし、未検証のウェブ検出推奨は常にインストール前に人間のレビューを受けることを保証します。
+
+### エコシステムカバレッジ
+
+調査者は単一の汎用チェックではなく、レジストリ固有の検証コマンドを使います：
+
+- Node.js：`npm view`
+- Python：`pip index versions`
+- Rust：`cargo search`
+
+これは 2025 年の USENIX 研究によると約 9% の割合で発生するクロスエコシステム幻覚をカバーします——AI が実際に使用しているエコシステムには存在しない別のエコシステムのパッケージを推奨するケース。
+
+### グレースフルデグレデーション
+
+`slopcheck` が利用できない場合（インストールされていない、または調査時に pip インストールが失敗した）、GSD は可能な限り厳格なフォールバックを適用します：**すべての推奨パッケージが `[ASSUMED]` とタグ付けされ**、プランナーはすべてのインストールを `checkpoint:human-verify` タスクでゲートします。調査と計画は通常どおり進行します——システムはツールの依存関係の欠落でハードフェイルすることはありません。これは通常フローより意図的に厳格です：slopcheck の利用不可は、すべてのパッケージインストールに人間のチェックポイントを付与することを意味します。
+
+`slopcheck` ツールは MIT ライセンスで pip インストール可能です。廃止された場合でも、`[ASSUMED]` ゲートフォールバックにより、人間チェックポイントカバレッジが維持されます。
+
+---
+
+## レイヤー 2 — プロンプトインジェクション防御
+
+### 脅威
+
+GSD Core は LLM システムプロンプトになる Markdown ファイルを生成します。調査パイプラインは外部ウェブコンテンツを読み取ります；計画パイプラインはユーザー提供のテキスト（`--text-file`、`--prd`）を組み込みます；実行パイプラインは後でエージェントコンテキストとして再読み取りされる計画アーティファクトを書きます。これらのアーティファクトに流れ込む任意のユーザー制御テキストは、潜在的な **間接プロンプトインジェクション** ベクターです——一度システムプロンプトの中に入ると、エージェントの指示を上書きしたり情報を窃取しようとする攻撃者制御の文字列。
+
+### 防御の仕組み
+
+GSD Core はプロンプトインジェクションを 3 つのレベルで対処します。
+
+**入力検証（`security.cjs`）。** `get-shit-done/bin/lib/security.cjs` モジュールは中心的なセキュリティユーティリティです。以下を提供します：
+
+- パストラバーサル防止：ユーザー提供のファイルパス（`--text-file`、`--prd`）はプロジェクトディレクトリ内で解決されることを検証し、macOS の `/var` → `/private/var` シンリンク解決を明示的に処理
+- プロンプトインジェクション検出：既知のインジェクションパターン（ロールオーバーライド、指示バイパス、システムタグインジェクション）が計画アーティファクトに入る前にユーザー提供テキストをスキャン
+- 安全な JSON パース：クラフトされた JSON ペイロードによるプロトタイプ汚染攻撃を防ぐラッパー
+- シェル引数検証：サブシェルコマンドに渡される引数の使用前検証
+
+**ランタイムフック：`gsd-prompt-guard.js`。** このフックは `.planning/` ファイルを対象とするすべての Write または Edit 呼び出しで発火します。書き込まれるコンテンツを `security.cjs` と同じインジェクションパターンでスキャンします（サブセットがフックの独立性のために直接インライン化されています——フックはモジュールを `require()` しないため、モジュールパスが変わっても実行されます）。検出は **アドバイザリーのみ**：フックは発見をログに記録しますが書き込みをブロックしません。理由は、正当な計画書き込みでの偽陽性ブロックは、セカンダリスキャンレイヤーで見逃したインジェクションより破壊的だからです。
+
+**ランタイムフック：`gsd-read-injection-scanner.js`。** このフックはすべての Read ツール呼び出しの出力で発火します。GSD がエージェントのコンテキストに組み込もうとしているファイルの *読み取ったばかりのコンテンツ* をスキャンし、攻撃者が命令を埋め込んでいるケースをキャッチします。
+
+**CI スキャナー。** `prompt-injection-scan.test.cjs` はテストスイートの一部として、すべてのエージェント、ワークフロー、コマンドファイルに埋め込まれたインジェクションベクターをスキャンします。これは GSD ソース自体でのインジェクション試みをキャッチします——たとえば、ワークフローファイルにロールオーバーライド命令を追加するよう変更したサプライチェーン攻撃。
+
+### Read Injection Scanner vs Prompt Guard
+
+2 つのフックは補完的な面をカバーします。`gsd-prompt-guard.js` は *計画アーティファクトへの書き込み* を監視します——植え付けられているインジェクションをキャッチします。`gsd-read-injection-scanner.js` は *任意のファイルの読み取り* を監視します——外部コンテンツ（依存関係の README、サードパーティの設定ファイル、ユーザー提供のドキュメント）から取り込まれるインジェクションをキャッチします。合わせて、取り込み → 保存 → 再読み取りのライフサイクルを括ります。
+
+---
+
+## レイヤー 3 — リポジトリおよび依存関係の整合性
+
+GSD のランタイム動作の上流で、`open-gsd` 組織はリポジトリおよびパッケージレベルで制御を強制しています。これらは [`docs/security/baseline.md`](../../security/baseline.md) に完全に記録されており、ここでは完全性のために要約します。
+
+**依存関係の整合性。** すべてのサードパーティ依存関係は `package-lock.json` でピン留めされ、インストール前に公開されたチェックサムに対して検証されます。`scripts/check-npm-integrity.cjs` ゲートは CI 時に無効なバージョン、欠落パッケージ、余分なパッケージを検出します。これにより GSD 自身の依存関係に対する依存関係混同とタイポスクワッティング攻撃を軽減します。
+
+**シークレットスキャン。** すべてのコミットと PR にはハードコードされたシークレットのスキャンが実施されます。意図的なテストフィクスチャは、プロジェクト標準の除外文法でアノテーションが必要です（アノテーション形式については `SECURITY.md` を参照）。アノテーションなしの抑制は CI を失敗させます。
+
+**ロケールセーフなテキストスキャン。** 出力とユーザー向け文字列は、Unicode ホモグリフ、双方向オーバーライド文字、不可視の Unicode についてスキャンされます——CVE-2021-42574（「トロイの木馬ソース」）で記録された、差分に悪意のあるコンテンツを隠すことができる攻撃クラス。
+
+---
+
+## トレードオフと限界
+
+ここで説明するセキュリティモデルは、AI 駆動開発の攻撃面を意味のある程度低減します。サプライチェーンリスクを排除するものではありません。
+
+**パッケージ正当性ゲートが低減するもの：** 幻覚されたまたは攻撃者登録済みのパッケージが人間のチェックポイントなしに `npm install` に届く確率。`[SLOP]` ゲートは高信頼度の悪質なパッケージを完全に除去します；`[SUS]`/`[ASSUMED]` ゲートは実行前に人間のレビューを要求します。これによりスロップスクワッティング攻撃の成功コストが実質的に引き上げられます。
+
+**パッケージ正当性ゲートが排除しないもの：** 後で侵害された正規パッケージ（アカウント乗っ取り、そのパッケージ自体のツリーでの依存関係混同）は、調査時に登録シグナルを確認する slopcheck ではキャッチされません。その種の攻撃に対するコントロールは、依存関係整合性レイヤーのロックファイルと `npm audit` です。
+
+**プロンプトインジェクション防御が低減するもの：** 計画アーティファクト内のユーザー制御テキストがエージェントの指示を正常に上書きする確率。既知のインジェクション形式のパターンマッチングは一般的なケースをキャッチします；新しいジェイルブレイクや低シグナルのインジェクションは検出されない可能性があります。アドバイザリーのみの姿勢は、検出がログに記録されるがブロックされないことを意味します——検出でハード停止するコストではなく、ワークフロー継続性を保持する意図的な選択。
+
+**プロンプトインジェクション防御が排除しないもの：** 既知のパターンにマッチしない十分に創造的なインジェクション、またはフックがカバーしないチャンネルを通じて届くインジェクション（たとえば、サブエージェントがドキュメントをブラウズする際に読み取る依存関係の公開 README にインジェクトされたコンテンツ）。多層防御は各レイヤーが攻撃を困難にすることを意味し、単一のレイヤーが不可能にすることを意味しません。
+
+**脆弱性の報告。** `https://github.com/open-gsd/gsd-core/security/advisories/new` でプライベートな GitHub セキュリティアドバイザリを通じて報告してください。パブリックなイシューを開かないでください。対応タイムラインと開示ポリシーについては [SECURITY.md](../../../SECURITY.md) を参照してください。
+
+---
+
+## Related
+
+- [コマンド](../COMMANDS.md) — セキュリティ関連フラグを含む `/gsd-secure-phase` と `/gsd-code-review`
+- [アーキテクチャ § フックシステム](../ARCHITECTURE.md#hook-system) — すべてのフック、そのイベントトリガー、安全性プロパティの実装詳細
+- [SECURITY.md](../../../SECURITY.md) — 脆弱性報告、組織全体のセキュリティベースライン、シークレットスキャン除外ガバナンス、依存関係整合性検証
+- [ドキュメント索引](../README.md)
diff --git a/docs/ja-JP/explanation/the-phase-loop.md b/docs/ja-JP/explanation/the-phase-loop.md
new file mode 100644
index 000000000..00b4e4d2d
--- /dev/null
+++ b/docs/ja-JP/explanation/the-phase-loop.md
@@ -0,0 +1,129 @@
+# フェーズループ
+
+> GSD Core が作業を整理する方法の核心的なメンタルモデル。
+
+---
+
+## ループとは何か
+
+GSD Core はすべての開発作業を繰り返すサイクルとして構造化します：
+
+```text
+Discuss → (UI デザイン) → Plan → Execute → Verify → Ship
+```
+
+**フェーズ** と呼ばれる作業の各単位は、順番にこれらのステップを経ていきます。ループは形式的なものではありません。各ステップは、前のステップだけでは防ぎきれない特定のクラスの失敗を防ぐために存在します。
+
+このドキュメントは、ループがなぜこの形をしているかを説明します。各ステップの実行方法については、下部にリンクされた how-to ガイドを参照してください。
+
+---
+
+## 各ステップが存在する理由
+
+### Discuss（議論）
+
+計画は、*何を*作るかだけでなく、*どのように*作るかを知るまでは始められません。`ROADMAP.md` のフェーズ目標は成果を記述します。Discuss ステップは、その成果への道を形作る実装上の決定を記録します：どのライブラリを使うか、どのエラーハンドリング戦略か、機能がルートごとかグローバルか、エッジケースはどう振る舞うべきか。
+
+Discuss ステップなしでは、プランナーがこれらの決定を自分で行わなければなりません。うまく推測することもありますが、もっともらしいが誤った推測をすることも多く——一貫性はあっても実際の好みとずれた計画を生み出します。実行が終わってエラーに気づく頃には、かなりの作業を巻き戻すことになります。
+
+Discuss ステップは意図的に軽量です。それは仕様書を書く演習ではなく、会話です。出力はフェーズディレクトリ内の `CONTEXT.md` です：プランナー、エグゼキューター、検証者がすべて読める決定の構造化された記録です。会話には数分かかります。それが何時間もの手直しを節約できます。
+
+### UI デザイン（任意）
+
+視覚的なコンポーネントを持つフェーズの場合、Discuss と Plan の間にオプションの `/gsd-ui-phase` ステップがあります。これは `UI-SPEC.md` を生成します——コードが書かれる前にレイアウト、インタラクション、視覚的な振る舞いを説明するデザインコントラクトです。デザインの曖昧さが異なる実装上の選択を生む可能性があるほど UI が複雑な場合に、このステップを実行する価値があります。明確なデザインコントラクトは、再実装するよりずっと安く書けます。
+
+### Plan（計画）
+
+Plan ステップは、実行に必要な調査、分解、構造的な思考を行います。フレッシュコンテキストサブエージェントのシーケンスとして実行されます：エコシステムを調査して `RESEARCH.md` に発見を記録する調査エージェント、調査と `CONTEXT.md` の両方を読んで `PLAN.md` ファイルを生成するプランナー、そして計画が完全で一貫していてスコープ内にあることを検証するプランチェッカー。
+
+計画には何が含まれるのか？各 `PLAN.md` は作業の境界が明確な単位を記述します：変更するファイル、行う特定の変更、完了を定義する受け入れ基準。計画は依存関係のウェーブ順に並べられ、並行実行が安全になります——同じウェーブ内のエグゼキューターは重複しない懸念事項を担当します。
+
+Plan ステップは曖昧さが最もコストが高い瞬間です。曖昧な計画は仮定を立てるエグゼキューターを生み出します。同じ懸念について異なる仮定を立てる複数の並行エグゼキューターは競合を生み出します。プランチェッカーの仕事は、実行が始まった後ではなく、その前にこれらをキャッチすることです。
+
+### Execute（実行）
+
+実行は計画を実施します。各エグゼキューターは、必要なものだけを正確にロードしたフレッシュな 200k トークンのコンテキストウィンドウを受け取ります：プロジェクトサマリー、フェーズコンテキスト、調査結果、そして自分のタスクのための特定の `PLAN.md`。それ以上でも以下でもありません。
+
+エグゼキューターはコードを書いてアトミックにコミットします。各コミットは計画内の完了したタスクに対応します。並行エグゼキューターのウェーブが完了すると、オーケストレーターはその状態をマージして次のウェーブを開始します。
+
+エグゼキューターのフレッシュコンテキストは便宜のためではありません——コンテキスト腐敗を防ぐメカニズムです。180k トークンの蓄積されたセッション履歴で実行するエグゼキューターは劣化しています。クリーンな状態で開始し、計画が必要とするものだけを読み取るエグゼキューターは、最大能力で動作しています。
+
+### Verify（検証）
+
+すべてのエグゼキューターが完了した後、検証エージェントはフェーズ目標、`CONTEXT.md` の決定、計画、実行サマリーを読み取り、構築されたものが意図されたものと一致するかを確認します。`VERIFICATION.md` を生成し、不一致があれば対象を絞った修正計画を生成します。
+
+検証はテストだけではありません。要件カバレッジ（すべての REQ-ID が対処されたか？）、決定カバレッジ（`CONTEXT.md` に記録された決定が実際に実装されたか？）、そして全体的なフェーズ目標との整合性を確認します。実行がエラーなく終了したからフェーズが完了なのではありません。構築されたものが計画されたものであり、計画されたものが決定されたものである場合に完了です。
+
+### Ship（出荷）
+
+Ship ステップはプルリクエストを作成し、フェーズアーティファクトをアーカイブします。`STATE.md` はフェーズ完了としてマークするために更新されます。その後ループは次のフェーズのために再び始まります。
+
+---
+
+## マイルストーンとフェーズ
+
+**マイルストーン** はバージョンサイクルです——プロジェクトの意味のあるリリース可能な増分。名前、バージョン番号、そして何を提供しなければならないかを定義する要件のセットを持ちます。すべてのフェーズが出荷され、要件がカバーされるとマイルストーンは完了です。
+
+**フェーズ** はマイルストーン内の一つの作業単位です。フェーズには目標、それが対処する要件のセット、それを実装する計画のセットがあります。
+
+この関係は重要です。なぜならマイルストーンとフェーズは異なるスコープの懸念事項を持っているからです。マイルストーンは「このバージョンの製品は何をするのか、しないのか？」と問います。フェーズは「調査、計画、実行、検証ができる次の境界が明確なものは何か？」と問います。
+
+マイルストーンの境界は自然な製品境界——デプロイ可能な API、動作する UI フロー、完全なデータモデル——に引かれます。フェーズの境界は、ループが手に負えなくなることなく一度のループで安全に実行できることの限界に引かれます。
+
+---
+
+## 良いフェーズスコープとは
+
+これはループで最もよく見られる摩擦の原因なので、詳しく考える価値があります。
+
+大きすぎるフェーズはそれ自体が調査プロジェクトになります。プランナーは独立した計画に分解するのに苦労します。後のウェーブのエグゼキューターは前のウェーブを待ちながらブロックされます。検証は対象を絞ったレビューではなく全体監査になります。フィードバックサイクルが時間から日に延びて、多くのコードが書かれた後に根本的な設計ミスを発見するリスクが急激に高まります。
+
+小さすぎるフェーズは自然に属する作業を断片化します。数行の計画ファイル、数分で完了するフェーズ、実行コストを矮小化する計画オーバーヘッドが生じます。ループは役に立つというよりお役所的に感じられます。
+
+良いフェーズスコープとは：
+
+- 目標が明らかに些細でも疑わしいほど広くもない単一の文で述べられる。
+- 計画するために必要な調査が境界を持つ——エコシステムの問題に、他のフェーズが先に完了することに依存しない答えがある。
+- 実行が少数の非重複する計画に並行化できる（数十ではなく）。
+- 検証者がコードベース全体を読まずに確認できる、明確でテスト可能な完了の定義がある。
+
+具体的には：「HMAC-SHA256 署名検証ミドルウェアを追加する」は良いフェーズスコープです。「認証システムを構築する」は通常そうではありません——ほぼ常に、別々のフェーズの方が良い複数の独立した懸念事項が含まれています。「README のタイポを修正する」はループが価値を加えるしきい値を下回っています；代わりに `/gsd-quick` を使ってください。
+
+迷ったら、分割してください。小さいフェーズは速く完了し、より自信を持って検証でき、設計上の決定が誤りとわかった場合に方向修正しやすくなります。
+
+---
+
+## `.planning/` はどのようにループをまたいで状態を維持するか
+
+ループは単一のセッションではありません。調査、計画立案、実行は複数のセッションにわたって行われ、その間にコンテキストリセットが発生することもあります。`.planning/` ディレクトリがこれを可能にするものです。
+
+ループの各ステップは以前のステップが生み出したアーティファクトを読み取り、後のステップのためのアーティファクトを書き出します。Discuss ステップが生成する CONTEXT.md は、プランナーが実行するときに——たとえそれが数時間後の別のセッションであっても——まだ利用可能です。プランナーが生成する PLAN.md ファイルは、エグゼキューターが実行するときに——再起動をまたいでも——まだ利用可能です。検証者が書く VERIFICATION.md は、フェーズをレビューするときにまだ利用可能です。
+
+`STATE.md` はこれすべての上のナビゲーション層です。ループ内でプロジェクトが現在どこにいるかを正確に記録します：どのマイルストーンがアクティブか、どのフェーズが進行中か、どの計画が完了していてどれが保留中か。自分の方向を確認する必要があるエージェントやワークフローは、まず `STATE.md` を読み取ります。
+
+これらのファイルの正確な構造については、[計画アーティファクト](../reference/planning-artifacts.md) と [STATE.md スキーマ](../reference/state-md.md) を参照してください。
+
+---
+
+## ループはリズムであり、制約ではない
+
+ループを官僚主義として見たくなる誘惑があります——コードを書く許可を得る前に実行しなければならない必須ステップのセット。そのフレーミングは誤りです。
+
+ループは、各ステップが後で修正するのが本当にコストが高い失敗を防ぐために存在します。Discuss は誤った仮定の上での計画立案を防ぎます。Plan は根本的に壊れた設計の実行を防ぎます。Verify は仕様を外れた作業の出荷を防ぎます。これらは作り上げられた問題ではありません。実際の機能規模での AI 支援開発の実際の失敗モードです。
+
+ループがうまく機能すれば、リズムのように感じます：各ステップが前のステップが仕事をしたために明確である、集中した境界を持つ作業のカデンス。オーバーヘッドは現実ですが、前払いです——何時間もの手直しではなく数分の計画として支払われます。
+
+ループが正当化されるしきい値を下回る作業には、GSD Core はより軽量なプリミティブを提供します。フェーズループは一つのツールであり、唯一のツールではありません。
+
+---
+
+## Related
+
+- [コンテキストエンジニアリング](context-engineering.md) — フレッシュコンテキストサブエージェントがなぜループを必要にする品質低下を防ぐのか
+- [フェーズの議論](../how-to/discuss-a-phase.md)
+- [フェーズの計画](../how-to/plan-a-phase.md)
+- [フェーズの実行](../how-to/execute-a-phase.md)
+- [検証と出荷](../how-to/verify-and-ship.md)
+- [計画アーティファクト](../reference/planning-artifacts.md)
+- [STATE.md スキーマ](../reference/state-md.md)
+- [ドキュメント索引](../README.md)
diff --git a/docs/ja-JP/how-to/configure-model-profiles.md b/docs/ja-JP/how-to/configure-model-profiles.md
new file mode 100644
index 000000000..2cb243c82
--- /dev/null
+++ b/docs/ja-JP/how-to/configure-model-profiles.md
@@ -0,0 +1,218 @@
+# モデルプロファイルの設定方法
+
+プロジェクトに適したモデルティア戦略を選び、大規模なオーバーライドブロックを書かずに個々のエージェントやフェーズタイプを調整します。このガイドは最もシンプルなレバーから始め、動的ルーティングまで段階的に説明します。
+
+---
+
+## 4 つのプロファイル（`adaptive` と `inherit` も含む）
+
+`.planning/config.json` または `/gsd-config --profile