docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

* 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>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions

View File

@@ -0,0 +1,148 @@
# CONTEXT.md 结构参考
每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd:discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
---
## 概述
每个经过讨论工作流处理的阶段,均会在以下路径生成一份 `CONTEXT.md`:
```
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
```
示例:`.planning/phases/03-post-feed/03-CONTEXT.md`。
该文件由 `get-shit-done/workflows/discuss-phase.md` 中的 `write_context` 步骤生成(或通过 PRD/ADR 摄入快速路径生成)。在正常操作中,该文件不会被手动编辑——讨论阶段工作流负责写入,下游代理将其作为封闭的可信来源读取。
---
## 前言(Frontmatter)
`CONTEXT.md` 不包含 YAML 前言。元数据以内联形式写在正文顶部:
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
```
`Status` 字段在文件首次写入时始终为 `Ready for planning`,创建后不再更新。
---
## 块结构
正文由若干具名 XML 风格的块组成,以固定顺序出现。下游代理通过块名而非行号来读取各块内容。
| 块名 | 用途 | 由谁填充 | 由谁消费 |
|---|---|---|---|
| `<domain>` | 声明阶段边界——本阶段交付内容及明确排除在范围之外的内容。在规划和执行过程中为范围护栏提供锚点。 | `discuss-phase`(来自 ROADMAP.md 阶段目标) | `gsd-planner`、`gsd-plan-checker`(范围合规性) |
| `<spec_lock>` | 仅在 `check_spec` 步骤发现 `*-SPEC.md` 时才存在。列出锁定的需求数量和范围边界;代理被指示直接读取 `SPEC.md` 以获取完整需求。 | `discuss-phase`(条件性) | `gsd-planner`(直接读取 SPEC.md,而非在此重读需求) |
| `<decisions>` | 从讨论中收集的实现决策,使用 `D-NN` 标识符标注。分类由实际讨论内容产生,而非固定分类体系。包含 `Claude's Discretion` 子节,用于用户委托代理自行决定的领域。 | `discuss-phase`(交互式讨论) | `gsd-planner`(锁定的决策必须实现)、`gsd-plan-checker`(维度 7 合规性) |
| `<canonical_refs>` | 与本阶段相关的所有规格文档、ADR、功能文档或设计文档的完整相对路径。必填——每份 CONTEXT.md 必须包含此节。代理在规划或实现之前必须读取列出的文件。 | `discuss-phase`(从 ROADMAP.md 引用 + 讨论中的用户引用 + 代码库侦查积累) | `gsd-phase-researcher`、`gsd-planner` |
| `<code_context>` | 在 `scout_codebase` 步骤中发现的可复用资产、已建立的模式和集成点。引导代理使用现有代码,而非重新实现。 | `discuss-phase`(代码库侦查) | `gsd-planner`、`gsd-phase-researcher` |
| `<specifics>` | 讨论期间逐字记录的具体"我希望它像 X 一样"的参考、产品对比或特定示例。 | `discuss-phase`(自由形式用户输入) | `gsd-planner` |
| `<deferred>` | 讨论中出现但属于其他阶段的想法,予以保留以免遗失。当待办事项经过审查但未纳入范围时,包含 `Reviewed Todos` 子节。 | `discuss-phase`(范围蔓延重定向) | 不被自动化代理消费;仅供人工参考 |
---
## 决策标识符格式
`<decisions>` 中的每条决策均带有顺序编号的 `D-NN` 标识符:
```markdown
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
```
标识符的作用域限定在阶段内。第 3 阶段中的 `D-01` 与第 7 阶段中的 `D-01` 无关。计划检查器(维度 7)会验证每个 `D-NN` 是否在生成计划中至少有一个任务动作加以覆盖。
---
## 规范引用
`<canonical_refs>` 块为**必填项**。如果代理发现其缺失,会将该 CONTEXT.md 视为不完整并发出警告。条目按主题分组,包含完整相对路径以及对文件所决定或定义内容的简要说明:
```markdown
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
```
当项目没有外部规格文档时,该节应明确说明:
```
No external specs — requirements fully captured in decisions above
```
在 `<decisions>` 中散落的内联提及(如"参见 ADR-019")是不够的;代理需要在专用节中获取完整路径。
---
## 决策覆盖关卡关系
计划检查器的**维度 7:上下文合规性**在规划完成后执行覆盖关卡检查:
1. `<decisions>` 中的每个 `D-NN` 标识符必须出现在至少一个计划任务的 `<action>` 或说明中。
2. 任何任务均不得实现 `<deferred>` 中列出的内容(即范围蔓延)。
3. `Claude's Discretion` 领域免于此检查——规划者可自由选择。
决策被成功纳入计划的 CONTEXT.md 被视为合规。决策被悄然丢弃或部分交付的 CONTEXT.md 会触发**维度 7b:范围缩减检测**,这始终是一个**阻断项**。
---
## SPEC.md 集成
当 `/gsd:spec-phase` 在讨论阶段之前运行时,`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`:
```markdown
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
```
当 `<spec_lock>` 存在时,`<decisions>` 中仅包含来自讨论的实现决策——即"如何做",而非"做什么"。需求不会在两个文件之间重复。
---
## 页脚
每份 CONTEXT.md 以身份页脚结尾:
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## 相关内容
- [PLAN.md 结构](plan-md.md)
- [规划产物](planning-artifacts.md)
- [讨论模式](../workflow-discuss-mode.md)
- [文档索引](../README.md)