create-epics

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,docs.density,engine_values,system_overrides

已在上方解析——请照此使用；--review 会覆盖 review_mode。若没有拦截 → 使用 .claude/docs/config-resolution.md 中的默认值。

使用提问工具提问。如果没有提问工具，请按编号列出选项，然后结束本轮以等待回复。 跳过或关闭的问题不算回答：请改用纯文本再次提问。

创建 Epic

Epic 是针对一个架构模块的范围明确的工作内容：构建什么，以及哪些决策对其进行约束。如何构建由 Story 说明。随着开发推进到相应层级，每层运行一次：在 Core 即将完成前编写的 Feature Epic，描述的设计可能已经发生变化。

写入内容： 每个 Epic 的 production/epics/[epic-slug]/EPIC.md，以及其在 production/epics/index.md 中对应的行；两者都需各自获得同意后再写入。 下一步： 每个 Epic 执行一次 /create-stories [epic-slug]。此技能绝不会编写 Story。

提问遵循 .claude/docs/automation-modes.md（协作模式始终提问，引导模式会针对重大选择提问，自主模式会记录并继续；automation_always_ask 类别始终提问）。

清单（复制并在进行时逐项勾选）：

- [ ] Phase 1: scope and tier
- [ ] Phase 2: inputs loaded and reported
- [ ] Phase 3: each epic shown, "Shall I create Epic: …?" asked one at a time
- [ ] Phase 4: producer review run, or its skip noted
- [ ] Phase 5: each EPIC.md and index row written after its own yes
- [ ] Phase 6: closing block printed

阶段 1：范围和层级

技能名称后输入的文本（移除任何 --review <mode> 参数对之后）：

• all：按层级顺序涵盖所有系统。
• layer: foundation（或 core、feature、presentation）：仅涵盖该层。
• 系统名称：仅涵盖该系统。
• 未输入内容：如果请求中提到了层级或系统（“foundation and core”），则使用请求中的内容；否则询问“您希望为哪个层级或系统创建 Epic？”

层级。 项目的 workflow 值决定所需内容（阶段 2）。范围内每个系统自身的 GDD 要求，以其 system_overrides 行为准（若存在）。

在 minimal 层级：先告知用户： 此层级的这一步是可选的，因为 /create-stories 可以单独根据 design/game-brief.md 构建 Epic。之后，如果用户要求创建 Epic，则继续。

阶段 2：加载输入

minimal：项目简述

读取 design/game-brief.md。如果文件不存在，则停止并告知：“没有 design/game-brief.md——请先运行 /start 或 /brainstorm。”绝不要索要 GDD、系统索引、架构文档、ADR、TR 注册表或控制清单，也绝不要先让用户运行 /design-system、/map-systems 或 /create-architecture：此层级本来就不包含这些内容。

请先逐字报告：

Loaded: design/game-brief.md · engine [name version from the engine_values line]
At minimal this step is optional: /create-stories builds the epic from the brief by itself.

Epic 根据项目简述的 MVP 功能列表及其构建顺序生成。简短的项目简述对应一个 Epic，其 slug 根据简述中的暂定标题生成（若未输入内容，这也是 /create-stories 使用的 slug）。如果用户要求将工作分组，则针对可一起交付的每组 MVP 功能创建一个 Epic。每个 Epic 都要注明其 slug，因为运行 /create-stories 时需要输入该 slug。

standard 和 full：设计与架构

1. 系统 GDD。 bash .claude/scripts/gdd-structure-check.sh 会列出所有系统 GDD；游戏概念、系统索引、支柱、交叉评审和其他非系统文档都不在其中，需由你处理。它们的数量为 N。若 N 为 0：停止，并提示“在 design/gdd/ 中未找到系统 GDD——请先运行 /design-system。”
2. 范围内的内容。 每个 GDD 的 ## Summary 快速参考会给出其层级和优先级。没有 Summary 的 GDD（较早的 GDD 创建时还没有此部分），其层级取自 design/gdd/systems-index.md。绝不要将缺少 ## Summary 视为系统缺失：该系统仍在范围内。
3. 架构。 两个层级都必须有 docs/architecture/architecture.md：若缺失，则停止并提示“没有 docs/architecture/architecture.md——请先运行 /create-architecture。”绝不要臆造模块边界。
4. 仅针对范围内的系统，按章节读取，绝不读取整份文档：
   • 每个 GDD 的 Overview 和 Acceptance Criteria （bash .claude/scripts/md-section.sh extract design/gdd/<file>.md "Overview"）；
   • 使用 bash .claude/scripts/adr-status.sh 查看每份 ADR 的状态、层级和缺失章节；然后读取涵盖范围内系统的 ADR 中的 GDD Requirements Addressed、Decision 和 Engine Compatibility 章节；
   • docs/architecture/tr-registry.yaml：其中 system: 为范围内系统的条目；
   • 控制清单的 Manifest Version 行（若存在，则在 standard 下读取；在 full 下为必需项）；
   • 引擎风险级别对应的 docs/engine-reference/<engine>/VERSION.md。

定义任何内容之前，先根据实际状态进行报告：

Loaded: [N] system GDDs, [n] in scope ([names]) · [M] ADRs ([A] Accepted, [P] Proposed) · manifest v[date | absent] · engine [name version from the engine_values line]

在 full 下，每个范围内的 GDD 都必须包含全部 8 个章节，且状态为 Approved；TR 注册表和控制清单也为必需项。在 standard 下，GDD 必须包含 5 个必需章节，且仅要求关键（Foundation 层）的 ADR。

第 3 阶段：定义每个 epic，逐个询问

按层级处理：先 Foundation，然后 Core、Feature、Presentation；同一层级内按系统索引顺序处理（在 minimal 下，按 brief 的 Build 顺序）。每个系统都要对应 architecture.md 中的模块（在 minimal 下，对应 brief 中的功能组）。

需求覆盖情况（minimal 下除外）。系统的每个 TR-ID 都属于以下情况之一：

• 已覆盖：有一份状态为 Accepted 的 ADR 涵盖该需求；
• 未追溯：其他情况。若某项需求唯一对应的 ADR 状态为 Proposed（或任何其他状态），则该需求属于未追溯，绝不算已覆盖：其行显示为 ❌ No ADR (ADR-NNNN Proposed)，因此 /create-stories 仍会看到该 ADR，并阻止创建对应的 story。

未追溯的需求列在 Untraced Requirements 下。以下 ⚠️ 警告适用于 full 下的每一项未追溯需求；在 standard 下，仅适用于 Foundation 层的未追溯需求。standard 下的其他未追溯需求仅作为信息列出，不发出警告。

## Epic: [System Name]
**Layer**: [Foundation | Core | Feature | Presentation]
**GDD**: design/gdd/[file].md   (at minimal: design/game-brief.md, MVP features [list])
**Architecture Module**: [module]
**Governing ADRs**: [Accepted ADRs, or "none"]
**Engine Risk**: [LOW | MEDIUM | HIGH — the highest among governing ADRs, else VERSION.md's]
**Requirements covered by Accepted ADRs**: [n / total]
**Untraced Requirements**: [TR-IDs with why, or "None"]

适用时显示以下警告：“⚠️ [N] 项 [system] 需求没有状态为 Accepted 的 ADR。它们对应的 story 将在没有适用 ADR 的情况下编写，或者因 ADR 状态为 Proposed 而受阻。如果这些需求需要决策，请先运行 /architecture-decision；否则，可继续并接受这一缺口。”

然后仅针对当前这个 epic询问：“要创建 Epic: [name] 吗？”选项：是，创建 / 跳过此 epic / 暂停——我需要先编写 ADR。仅在得到当前 epic 的答复后，才展示并询问下一个 epic。绝不要把多个 epic 合并成一个问题。

无论措辞是否表示涵盖全部（“全部都做”“全部继续”），肯定答复都只适用于它所回答的那个 epic：看到某个 epic 后，只有该 epic 获得批准。展示下一个 epic 的内容并再次询问，直到范围内的每个 epic 都已展示并得到答复。

第 4 阶段：Producer 评审

读取上方的 review_gate 行。skill-gates=skip（solo 或 lean）：不启用 Agent；在回复和结尾块中注明 PR-EPIC skipped — [Solo | Lean] mode。skill-gates=run：读取 references/pr-epic-gate.md 和 .claude/docs/director-gates.md，并在范围内的所有 epic 都已定义、但尚未执行任何写入之前，立即运行该流程。若跳过，则不要加载这些文件。

阶段 5：编写每个史诗

按顺序处理用户答应编写的每个史诗：

已有 EPIC.md： 绝不覆盖。询问：“[name] 已有一个 EPIC.md。要就地更新，还是跳过此史诗？”选项：就地更新 / 跳过此史诗。 更新时，只编辑此技能负责的内容（Stories、Overview、Governing ADRs、GDD Requirements、Definition of Done 以外的标题字段），并保留 **Stories** 行和任何 ## Stories 表格原样不动：/create-stories 已写入这些内容，重置它们会使现有故事失去关联。

新建： 询问：“可以写入 production/epics/[epic-slug]/EPIC.md 并将其行添加到 production/epics/index.md 吗[, 如有需要则创建该文件]？”这是单独的一次确认，每个史诗都要询问一次，并且在阶段 3 获得肯定答复之后进行：那次肯定答复批准的是史诗，而不是写入操作。只有得到明确肯定答复后才能写入。 就在写入之前，运行 bash .claude/scripts/write-guard.sh overwrite production/epics/[epic-slug]/EPIC.md。它总会输出一行 checked；如果随后返回一行 OVERWRITE，说明文件最终确实存在，因此不要写入，而要改为询问是否更新。

docs.density 决定 Overview 的详略（terse 为简短要点，balanced 为简短段落，thorough 为完整说明，包含 ADR 理由和风险）；无论详略如何，都保留完整表格。

# Epic: [System Name]

> **Layer**: [Foundation | Core | Feature | Presentation]
> **GDD**: design/gdd/[file].md
> **Architecture Module**: [module]
> **Status**: Ready
> **Stories**: Not yet created — run `/create-stories [epic-slug]`

## Overview

[What this epic implements, from the GDD Overview and the module's responsibilities]

## Governing ADRs

| ADR | Decision Summary | Engine Risk |
|-----|------------------|-------------|
| ADR-NNNN: [title] | [one line] | LOW/MEDIUM/HIGH |

## GDD Requirements

| TR-ID | Requirement | ADR Coverage |
|-------|-------------|--------------|
| TR-[system]-001 | [requirement text from the registry] | ADR-NNNN ✅ |
| TR-[system]-002 | [requirement text] | ❌ No ADR (ADR-NNNN Proposed) |

## Definition of Done

- Every story implemented, reviewed and closed with `/story-done`
- Every acceptance criterion of design/gdd/[file].md verified
- Logic and Integration stories have passing tests in the test root
- Visual/Feel and UI stories have retained screenshots in `production/qa/evidence/`
  (a lead sign-off too for Visual/Feel)

在 minimal 模式下，GDD 行写为 design/game-brief.md，省略 Governing ADRs 和 GDD Requirements 表格，并用 Scope 列表按 Build 顺序列出该史诗的 MVP 功能。

production/epics/index.md： 每个史诗一行。已有行的史诗保留该行：就地更新，绝不添加第二行，也绝不重置 Stories 单元格。

# Epics Index

Last Updated: [date]
Engine: [name version]

| Epic | Layer | System | GDD | Stories | Status |
|------|-------|--------|-----|---------|--------|
| [name] | [layer] | [system] | [file] | Not yet created | Ready |

阶段 6：结束

在 standard 和 full 模式下，Foundation 和 Core 史诗都已存在后，添加：“Foundation 和 Core 史诗是 Pre-Production → Production 门槛所需的内容。/gate-check production 会检查是否已准备就绪。”minimal 模式下绝不添加。

每个史诗的内容都来自 GDD、ADR 和架构文档（minimal 模式下则来自 brief）；不得凭空编造。

本次运行的最后一条回复以此块结尾（如果之前已显示过，则再次重复）：

Verdict: COMPLETE — [N] epics written: [slugs]
Review: [PR-EPIC skipped — Solo mode | skipped — Lean mode | its verdict]
Index: production/epics/index.md [created | updated]
Next step: /create-stories [first-epic-slug]

如果用户跳过或拒绝了所有史诗：Verdict: BLOCKED — no epic written ([why])。如果指定范围内没有系统：Verdict: BLOCKED — no eligible systems in [scope]。