3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
9.1 KiB
使用 GSD 进行议题驱动的编排
状态： 稳定工作流指南 受众： 在 GitHub Issues、Linear、Jira 或类似议题跟踪系统中管理工作的开发者，希望通过 GSD 现有原语驱动 AI 辅助实现。
本指南的内容
本指南提供一套方案，将 GSD 已有的命令组合成一个"议题跟踪 → 工作区 → 计划/执行 → 验证/审核 → PR"的循环。这仅是文档说明。无新命令、无守护进程、无跟踪系统集成 —— 下文引用的每一条命令在 GSD 中均已存在。
本方案的结构受到 OpenAI 开源 Symphony 编排参考（代码库）的启发。GSD 不内嵌或封装 Symphony。Symphony 中的编排概念可以清晰地映射到 GSD 已有的原语上；本指南只是将这种映射明确阐述出来，让你无需编写粘合代码或绕过 GSD 的安全门控即可采用该模式。
为何存在本指南
GSD 具备议题驱动 AI 开发的基础构建块 ——
/gsd-workspace --new、/gsd-manager、/gsd-autonomous、/gsd-verify-work、
/gsd-review、/gsd-ship，以及 STATE.md 和阶段产物套件
—— 但缺少一份说明如何从单个跟踪议题驱动它们、无需编写自定义编排脚本的指南。没有这份指南，常见的失效模式是：
- 使用不足：开发者手动运行 discuss/plan/execute，即使工作模式完全适合，也从未使用
/gsd-manager或/gsd-autonomous。 - 绕过脚本：开发者在跟踪系统与
claude调用之间编写临时 shell 循环，绕过STATE.md、阶段清单和验证门控。
本指南使规范循环变得易于发现。
概念映射
每行将 Symphony 风格的编排概念映射到 GSD 中对应的原语。在阅读 Symphony 文档、博客文章或第三方编排资料时，可将此表用作转换参考。
| Symphony 概念 | GSD 原语 |
|---|---|
WORKFLOW.md（顶层意图） |
ROADMAP.md（项目意图）、STATE.md（实时状态）、阶段 CONTEXT.md（每阶段范围）、阶段 PLAN.md（可执行步骤） |
| 每个任务一个独立的代理工作区 | /gsd-workspace --new --strategy worktree |
| 代理调度与并发 | /gsd-manager（交互式仪表板）、/gsd-autonomous（无人值守） |
| 每阶段的计划与讨论步骤 | /gsd-discuss-phase → /gsd-plan-phase → /gsd-execute-phase |
| 工作证明 / 测试证据 | /gsd-verify-work（UAT.md 在 /clear 后持久保存） |
| 对抗性审核 | /gsd-review（由独立 AI CLI 对计划进行交叉对等审核） |
| 人工合并门控 | /gsd-ship（创建 PR，可选代码审查，准备合并） |
| 后续工作捕获 | /gsd-capture、/gsd-capture --seed、/gsd-new-milestone，或手动打开的跟踪议题 |
| 并发控制 | Manager / 后台代理语义（无持续轮询器） |
映射是单向的：GSD 持有安全门控（验证、人工审核、后续工作创建的明确确认）。Symphony 的"持续编排"框架被有意地未采用 —— 参见非目标。
端到端流程
规范的"议题 → PR"循环，设计为可从单个跟踪议题端到端运行。运行前请替换括号中的占位符。
- 选择跟踪议题。 从你的跟踪系统（GitHub、Linear 等）中选择一个范围足够明确可供自主实现的议题 —— 边界清晰、验收标准可观察、没有阻碍执行的上游依赖。
- 映射到 GSD 阶段。 如果该议题对应
ROADMAP.md中已有的阶段，选择它。若无，运行/gsd-new-milestone（用于一批相关议题的新里程碑），或通过/gsd-phase//gsd-phase --insert打开一个阶段。将跟踪议题 URL 写入该阶段的CONTEXT.md，确保可追溯性在压缩后依然保留。 - 创建独立工作区。 运行
/gsd-workspace --new --strategy worktree <slug>，以创建一个带有独立.planning/目录的 git 工作树。工作树是安全边界：任何探索、部分提交或中止的计划都保留在main之外。 - 通过 GSD 运行 discuss → plan → execute。 在工作区内部运行
/gsd-discuss-phase澄清歧义，运行/gsd-plan-phase生成PLAN.md，再通过/gsd-manager（交互式仪表板）或/gsd-execute-phase//gsd-autonomous（无人值守）来实现。避免从 GSD 外部直接驱动原始claude调用 —— 这会绕过STATE.md更新和阶段清单。 - 要求工作证明。 运行
/gsd-verify-work，引导用户根据阶段的验收标准进行 UAT。测试、截图、日志捕获和配置差异均记录在UAT.md中，该文件在/clear后持久保存，并在验证发现遗漏范围时通过/gsd-plan-phase --gaps补充缺口。 - 通过审核和发布门控。 运行
/gsd-review，从独立 AI CLI 获取对计划的对抗性对等审核（逐模型发现盲点），然后运行/gsd-ship，从规划产物中组装丰富的 PR 正文并打开 PR。两个门控都需要人工决策，之后才能推送到远端。 - 明确捕获后续工作。 使用
/gsd-capture记录内联备注，使用/gsd-capture --seed记录值得未来阶段处理的想法，或使用/gsd-new-milestone记录一组有关联的后续工作。从发现的后续工作创建跟踪议题需要明确的用户确认 —— GSD 不会自动向远程跟踪系统发布内容。
PR 合并后，循环关闭。PR 正文中的自动关闭关键词（Closes #NNN / Fixes #NNN）会在合并时关闭跟踪议题。
安全边界
该循环之所以安全，是因为四项不变量在构建上得到保证：
- 独立工作树。 每个议题在
/gsd-workspace --new工作树中运行，因此部分工作、中止的计划和探索性提交永远不会触及main。gsd-local-patches/是恢复入口，当工作树的手动编辑需要跨更新带回时可使用。 - 明确的人工审核。
/gsd-review和/gsd-ship均会停下来等待人工批准。没有自动合并，也没有从执行路径自动创建 PR 的路径。如果你想为特定代码库移除人工门控，那是你的分支保护 / 合并队列策略决定，而非 GSD 代为选择的。 - 不自动公开发布。 GSD 从不在没有明确用户发起命令的情况下打开、评论或关闭跟踪议题。后续工作捕获默认写入本地产物（备注、种子、里程碑）；推回跟踪系统是单独的手动步骤。
- 发布前先验证。
/gsd-verify-work的 UAT.md 必须记录证据，才能运行/gsd-ship。推荐的规范是将verification_failed视为阻塞项，即使实现看起来正确 —— 失败通常意味着遗漏了验收标准，而非测试不稳定。
如果这些不变量中的任何一项被绕过（例如直接对工作树运行 claude、跳过 /gsd-verify-work，或在没有用户确认的情况下通过跟踪 API 脚本化创建议题），本指南的保证将不再适用。
非目标
本指南刻意不提出以下任何内容。在此列出，以防止未来贡献者在代码审查中重新讨论：
- 不内嵌或复制 Symphony 代码。 GSD 复用自身原语。上述映射是概念性的；本代码库中不包含任何 Symphony 衍生源码。
- 无长期运行的守护进程。 GSD 不轮询 GitHub 或 Linear。Manager 和自主工作流通过后台代理语义处理并发，而非通过守护进程。
- 无强制跟踪系统依赖。 该循环无需任何跟踪系统集成即可运行。"跟踪议题"步骤是一种人工输入 —— URL 写入
CONTEXT.md。GSD 不关心你使用哪个跟踪系统，或者你是否使用跟踪系统。 - 不绕过验证、审核或人工决策门控。 即使在运行
/gsd-autonomous时，验证和审核门控依然触发。"autonomous（自主）"标签指的是阶段间的推进，而非跳过人工批准。 - 不扩展默认技能 / 命令面。 本指南引用的每一条命令均已存在。本指南是文档面，而非功能面。
可能的未来后续
如果维护者在使用该循环的过程中积累了足够的经验，一个独立的 approved-enhancement 可在未来添加最小化的跟踪桥接：
- 将一个 GitHub 或 Linear 议题导入 GSD 工作区 / 阶段。
- 将
UAT.md证据作为评论导出到源议题。 - 从
/gsd-capture --seed输出生成后续跟踪议题。
上述每一项都将是独立的增强提案，因为每项都增加了集成面和持续维护负担。它们超出了本指南的范围。
相关资源
- 阶段循环 — 说明 discuss → plan → execute → verify → ship 如何作为重复循环组合在一起。
- 工作区操作指南 — 创建和管理并行工作树的逐步指南。
- 文档索引 — GSD Core 文档的完整目录。
- docs/USER-GUIDE.md — 上述各命令以任务为导向的操作指南。
- docs/COMMANDS.md —
/gsd-*命令的完整参考。 - docs/FEATURES.md — 功能级能力矩阵（工作区、manager、autonomous、verify、review、ship）。
- docs/ARCHITECTURE.md — 阶段产物生命周期与
STATE.md机制。