Back to Details

create-epics

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Epics

创建Epic

An epic is a named, bounded body of work that maps to one architectural module. It defines what needs to be built and who owns it architecturally. It does not prescribe implementation steps — that is the job of stories.
Run this skill once per layer as you approach that layer in development. Do not create Feature layer epics until Core is nearly complete — the design will have changed.
Output: 
production/epics/[epic-slug]/EPIC.md
+ 
production/epics/index.md
Next step after each epic: 
/create-stories [epic-slug]
When to run: After 
/create-control-manifest
and 
/architecture-review
pass.
Epic是一个有名称、有边界的工作单元，对应一个架构模块。它定义了需要构建什么以及架构层面的负责人。它不规定实现步骤——那是用户故事的工作。
在开发推进到对应层级时，每个层级运行一次该技能。在Core层接近完成前，不要创建Feature层的Epic——设计会发生变化。
输出： 
production/epics/[epic-slug]/EPIC.md
+ 
production/epics/index.md
每个Epic创建后的下一步： 
/create-stories [epic-slug]
运行时机： 在
/create-control-manifest
和
/architecture-review
通过之后。

1. Parse Arguments

1. 解析参数

Resolve the review mode (once, store for all gate spawns this run):
  1. If 
    --review [full|lean|solo]
    was passed → use that
  2. Else read 
    production/review-mode.txt
    → use that value
  3. Else → default to 
    lean
See 
.claude/docs/director-gates.md
for the full check pattern.
Modes:
  • /create-epics all
    — process all systems in layer order
  • /create-epics layer: foundation
    — Foundation layer only
  • /create-epics layer: core
    — Core layer only
  • /create-epics layer: feature
    — Feature layer only
  • /create-epics layer: presentation
    — Presentation layer only
  • /create-epics [system-name]
    — one specific system
  • No argument — ask: "Which layer or system would you like to create epics for?"
确定评审模式（一次性设置，本次运行的所有gate实例均使用该模式）：
  1. 如果传入了
    --review [full|lean|solo]
    → 使用该值
  2. 否则读取
    production/review-mode.txt
    → 使用该文件中的值
  3. 否则 → 默认使用
    lean
完整的检查规则请参见
.claude/docs/director-gates.md
。
模式：
  • /create-epics all
    — 按层级顺序处理所有系统
  • /create-epics layer: foundation
    — 仅处理Foundation层
  • /create-epics layer: core
    — 仅处理Core层
  • /create-epics layer: feature
    — 仅处理Feature层
  • /create-epics layer: presentation
    — 仅处理Presentation层
  • /create-epics [system-name]
    — 仅处理指定的单个系统
  • 无参数 — 询问："您想要为哪个层级或系统创建Epic？"

2. Load Inputs

2. 加载输入

Step 2a — Summary scan (fast)

步骤2a — 摘要扫描（快速）

Grep all GDDs for their 
## Summary
sections before reading anything fully:
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
For 
layer:
or 
[system-name]
modes: filter to only in-scope GDDs based on the Summary quick-reference. Skip full-reading anything out of scope.
在完整读取任何文档之前，先提取所有GDD中的
## Summary
部分：
Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
对于
layer:
或
[system-name]
模式：基于摘要快速参考结果，过滤出仅在范围内的GDD。跳过所有范围外的文档的完整读取。

Step 2b — Full document load (in-scope systems only)

步骤2b — 完整文档加载（仅范围內的系统）

Using the Step 2a grep results, identify which systems are in scope. Read full documents only for in-scope systems — do not read GDDs or ADRs for out-of-scope systems or layers.
Read for in-scope systems:
  • design/gdd/systems-index.md
    — authoritative system list, layers, priority
  • In-scope GDDs only (Approved or Designed status, filtered by Step 2a results)
  • docs/architecture/architecture.md
    — module ownership and API boundaries
  • Accepted ADRs whose domains cover in-scope systems only — read the "GDD Requirements Addressed", "Decision", and "Engine Compatibility" sections; skip ADRs for unrelated domains
  • docs/architecture/control-manifest.md
    — manifest version date from header
  • docs/architecture/tr-registry.yaml
    — for tracing requirements to ADR coverage
  • docs/engine-reference/[engine]/VERSION.md
    — engine name, version, risk levels
Report: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
利用步骤2a的grep结果，确定哪些系统在范围内。仅读取范围內系统的完整文档——不要读取范围外系统或层级的GDD或ADR。
为范围內系统读取以下内容：
  • design/gdd/systems-index.md
    — 权威的系统列表、层级和优先级
  • 仅范围內的GDD（状态为Approved或Designed，经步骤2a结果过滤）
  • docs/architecture/architecture.md
    — 模块归属和API边界
  • 仅覆盖范围內系统的已接受ADR — 读取"GDD Requirements Addressed"、"Decision"和"Engine Compatibility"部分；跳过无关领域的ADR
  • docs/architecture/control-manifest.md
    — 头部中的清单版本日期
  • docs/architecture/tr-registry.yaml
    — 用于追踪需求到ADR的覆盖情况
  • docs/engine-reference/[engine]/VERSION.md
    — 引擎名称、版本、风险等级
报告："已加载[N]个GDD、[M]个ADR，引擎：[名称 + 版本]。"

3. Processing Order

3. 处理顺序

Process in dependency-safe layer order:
  1. Foundation (no dependencies)
  2. Core (depends on Foundation)
  3. Feature (depends on Core)
  4. Presentation (depends on Feature + Core)
Within each layer, use the order from 
systems-index.md
.
按依赖安全的层级顺序处理：
  1. Foundation（无依赖）
  2. Core（依赖Foundation）
  3. Feature（依赖Core）
  4. Presentation（依赖Feature + Core）
在每个层级内，按照
systems-index.md
中的顺序处理。

4. Define Each Epic

4. 定义每个Epic

For each system, map it to an architectural module from 
architecture.md
.
Check ADR coverage against the TR registry:
  • Traced requirements: TR-IDs that have an Accepted ADR covering them
  • Untraced requirements: TR-IDs with no ADR — warn before proceeding
Present to user before writing anything:
undefined
对于每个系统，将其与
architecture.md
中的架构模块对应起来。
检查ADR对TR注册表的覆盖情况：
  • 已追踪需求：有已接受ADR覆盖的TR-ID
  • 未追踪需求：没有ADR的TR-ID — 继续前发出警告
在写入任何内容前，先向用户展示：
undefined

Epic: [System Name]

Epic: [系统名称]

Layer: [Foundation / Core / Feature / Presentation] GDD: design/gdd/[filename].md Architecture Module: [module name from architecture.md] Governing ADRs: [ADR-NNNN, ADR-MMMM] Engine Risk: [LOW / MEDIUM / HIGH — highest risk among governing ADRs] GDD Requirements Covered by ADRs: [N / total] Untraced Requirements: [list TR-IDs with no ADR, or "None"]

If there are untraced requirements:
> "⚠️ [N] requirements in [system] have no ADR. The epic can be created, but
> stories for these requirements will be marked Blocked until ADRs exist.
> Run `/architecture-decision` first, or proceed with placeholders."

Use `AskUserQuestion`:
- Prompt: "Shall I create Epic: [name]?"
- Options:
  - `[A] Yes, create it`
  - `[B] Skip this epic`
  - `[C] Pause — I need to write ADRs first`

---
层级: [Foundation / Core / Feature / Presentation] GDD: design/gdd/[filename].md 架构模块: [来自architecture.md的模块名称] 主导ADR: [ADR-NNNN, ADR-MMMM] 引擎风险: [LOW / MEDIUM / HIGH — 主导ADR中的最高风险] ADR覆盖的GDD需求: [已覆盖数 / 总数] 未追踪需求: [无ADR的TR-ID列表，或"无"]

如果存在未追踪需求：
> "⚠️ [系统名称]中有[N]个需求没有对应的ADR。Epic可以创建，但这些需求对应的用户故事将被标记为Blocked，直到ADR存在。请先运行`/architecture-decision`，或使用占位符继续。"

使用`AskUserQuestion`：
- 提示："是否创建Epic: [名称]？"
- 选项：
  - `[A] 是，创建它`
  - `[B] 跳过这个Epic`
  - `[C] 暂停 — 我需要先编写ADR`

---

4b. Producer Epic Structure Gate

4b. 生产者Epic结构检查

Review mode check — apply before spawning PR-EPIC:
  • solo
    → skip. Note: "PR-EPIC skipped — Solo mode." Proceed to Step 5 (write epic files).
  • lean
    → skip (not a PHASE-GATE). Note: "PR-EPIC skipped — Lean mode." Proceed to Step 5 (write epic files).
  • full
    → spawn as normal.
After all epics for the current layer are defined (Step 4 completed for all in-scope systems), and before writing any files, spawn 
producer
via Task using gate PR-EPIC (
.claude/docs/director-gates.md
).
Pass: the full epic structure summary (all epics, their scope summaries, governing ADR counts), the layer being processed, milestone timeline and team capacity.
Present the producer's assessment.
If UNREALISTIC: offer to revise epic boundaries (split overscoped or merge underscoped epics). Revise and re-run the gate before writing.
If CONCERNS, use 
AskUserQuestion
:
  • Prompt: "Producer raised concerns about the epic structure. How do you want to proceed?"
  • Options: 
    • [A] Proceed as planned — I accept the producer's concerns
    • [B] Revise epic boundaries — split or merge as recommended
    • [C] Stop — I want to reconsider the scope
If [A]: proceed to Step 5. If [B]: revise epic definitions from Step 4 and re-run the producer gate. If [C]: stop. Verdict: BLOCKED — user wants to reconsider epic scope.
Do not write epic files until the producer gate resolves.
评审模式检查 — 在生成PR-EPIC前应用：
  • solo
    → 跳过。备注："PR-EPIC已跳过 — 单人模式。" 继续步骤5（写入Epic文件）。
  • lean
    → 跳过（非PHASE-GATE）。备注："PR-EPIC已跳过 — 精简模式。" 继续步骤5（写入Epic文件）。
  • full
    → 正常生成。
在当前层级的所有Epic定义完成后（所有范围內系统的步骤4已完成），且在写入任何文件前，通过Task使用PR-EPIC gate（
.claude/docs/director-gates.md
）生成
producer
。
传递内容：完整的Epic结构摘要（所有Epic及其范围摘要、主导ADR数量）、正在处理的层级、里程碑时间线和团队产能。
展示生产者的评估结果。
如果评估为UNREALISTIC：提议修改Epic边界（拆分范围过大的Epic或合并范围过小的Epic）。修改后重新运行检查，再进行写入。
如果评估为CONCERNS，使用
AskUserQuestion
：
  • 提示："生产者对Epic结构提出了担忧。您希望如何处理？"
  • 选项： 
    • [A] 按计划继续 — 我接受生产者的担忧
    • [B] 修改Epic边界 — 按照建议拆分或合并
    • [C] 停止 — 我想重新考虑范围
如果选[A]：继续步骤5。 如果选[B]：修改步骤4中的Epic定义，重新运行生产者检查。 如果选[C]：停止。结论：BLOCKED — 用户希望重新考虑Epic范围。
在生产者检查解决前，不要写入Epic文件。

5. Write Epic Files

5. 写入Epic文件

After approval, ask: "May I write the epic file to 
production/epics/[epic-slug]/EPIC.md
?"
After user confirms, write:
获得批准后，询问："是否将Epic文件写入
production/epics/[epic-slug]/EPIC.md
？"
用户确认后，写入：

production/epics/[epic-slug]/EPIC.md

production/epics/[epic-slug]/EPIC.md

markdown
undefined
markdown
undefined

Epic: [System Name]

Epic: [系统名称]

Layer: [Foundation / Core / Feature / Presentation] GDD: design/gdd/[filename].md Architecture Module: [module name] Status: Ready Stories: Not yet created — run 
/create-stories [epic-slug]
层级: [Foundation / Core / Feature / Presentation] GDD: design/gdd/[filename].md 架构模块: [模块名称] 状态: Ready 用户故事: 尚未创建 — 运行
/create-stories [epic-slug]

Overview

概述

[1 paragraph describing what this epic implements, derived from the GDD Overview and the architecture module's stated responsibilities]
[1段描述，基于GDD概述和架构模块的既定职责，说明该Epic实现的内容]

Governing ADRs

主导ADR

ADRDecision SummaryEngine Risk
ADR-NNNN: [title][1-line summary]LOW/MEDIUM/HIGH
ADR决策摘要引擎风险
ADR-NNNN: [标题][1行摘要]LOW/MEDIUM/HIGH

GDD Requirements

GDD需求

TR-IDRequirementADR Coverage
TR-[system]-001[requirement text from registry]ADR-NNNN ✅
TR-[system]-002[requirement text]❌ No ADR
TR-ID需求ADR覆盖情况
TR-[system]-001[来自注册表的需求文本]ADR-NNNN ✅
TR-[system]-002[需求文本]❌ 无ADR

Definition of Done

完成定义

This epic is complete when:
  • All stories are implemented, reviewed, and closed via 
    /story-done
  • All acceptance criteria from 
    design/gdd/[filename].md
    are verified
  • All Logic and Integration stories have passing test files in 
    tests/
  • All Visual/Feel and UI stories have evidence docs with sign-off in 
    production/qa/evidence/
当满足以下条件时，该Epic视为完成：
  • 所有用户故事均已实现、评审并通过
    /story-done
    关闭
  • design/gdd/[filename].md
    中的所有验收标准均已验证
  • 所有Logic和Integration用户故事在
    tests/
    中有通过的测试文件
  • 所有Visual/Feel和UI用户故事在
    production/qa/evidence/
    中有带签署的证据文档

Next Step

下一步

Run 
/create-stories [epic-slug]
to break this epic into implementable stories.
undefined
运行
/create-stories [epic-slug]
将该Epic拆分为可实现的用户故事。
undefined

Update 
production/epics/index.md

更新
production/epics/index.md

Create or update the master index:
markdown
undefined
创建或更新主索引：
markdown
undefined

Epics Index

Epics索引

Last Updated: [date] Engine: [name + version]
EpicLayerSystemGDDStoriesStatus
[name]Foundation[system][file]Not yet createdReady

---
最后更新时间: [日期] 引擎: [名称 + 版本]
Epic层级系统GDD用户故事状态
[名称]Foundation[系统][文件]尚未创建Ready

---

6. Gate-Check Reminder

6. 检查提醒

After writing all epics for the requested scope:
  • Foundation + Core complete: These are required for the Pre-Production → Production gate. Run 
    /gate-check production
    to check readiness.
  • Reminder: Epics define scope. Stories define implementation steps. Run 
    /create-stories [epic-slug]
    for each epic before developers can pick up work.
完成请求范围内的所有Epic写入后：
  • Foundation + Core层完成：这是Pre-Production → Production检查的必要条件。运行
    /gate-check production
    检查就绪情况。
  • 提醒：Epic定义范围，用户故事定义实现步骤。在开发者开始工作前，为每个Epic运行
    /create-stories [epic-slug]
    。

Collaborative Protocol

协作协议

  1. One epic at a time — present each epic definition before asking to create it
  2. Warn on gaps — flag untraced requirements before proceeding
  3. Ask before writing — per-epic approval before writing any file
  4. No invention — all content comes from GDDs, ADRs, and architecture docs
  5. Never create stories — this skill stops at the epic level
After all requested epics are processed:
  • Verdict: COMPLETE — [N] epic(s) written. Run 
    /create-stories [epic-slug]
    per epic.
  • Verdict: BLOCKED — user declined all epics, or no eligible systems found.
  1. 一次处理一个Epic — 在请求创建前，先展示每个Epic的定义
  2. 提示缺口 — 继续前标记未追踪的需求
  3. 写入前询问 — 每个Epic都需获得批准后再写入文件
  4. 不自行创造内容 — 所有内容均来自GDD、ADR和架构文档
  5. 绝不创建用户故事 — 该技能仅处理到Epic层面
完成所有请求的Epic处理后：
  • 结论: COMPLETE — 已写入[N]个Epic。为每个Epic运行
    /create-stories [epic-slug]
    。
  • 结论: BLOCKED — 用户拒绝了所有Epic，或未找到符合条件的系统。