Translate approved GDDs + architecture into epics — one epic per architectural module. Defines scope, governing ADRs, engine risk, and untraced requirements. Does NOT break into stories — run /create-stories [epic-slug] after each epic is created.
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.
Resolve the review mode (once, store for all gate spawns this run):
--review [full|lean|solo] was passed → use thatproduction/review-mode.txt → use that valueleanSee .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 systemGrep 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.
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, prioritydocs/architecture/architecture.md — module ownership and API boundariesdocs/architecture/control-manifest.md — manifest version date from headerdocs/architecture/tr-registry.yaml — for tracing requirements to ADR coveragedocs/engine-reference/[engine]/VERSION.md — engine name, version, risk levelsReport: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
Process in dependency-safe layer order:
Within each layer, use the order from systems-index.md.
For each system, map it to an architectural module from architecture.md.
Check ADR coverage against the TR registry:
Present to user before writing anything:
## Epic: [System Name]
**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-decisionfirst, or proceed with placeholders."
Ask: "Shall I create Epic: [name]?" Options: "Yes, create it", "Skip", "Pause — I need to write ADRs first"
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) before writing. If CONCERNS, surface them and let the user decide. Do not write epic files until the producer gate resolves.
After approval, ask: "May I write the epic file to production/epics/[epic-slug]/EPIC.md?"
After user confirms, write:
production/epics/[epic-slug]/EPIC.md# Epic: [System Name]
> **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]`
## Overview
[1 paragraph describing what this epic implements, derived from the GDD Overview
and the architecture module's stated responsibilities]
## Governing ADRs
| ADR | Decision Summary | Engine Risk |
|-----|-----------------|-------------|
| ADR-NNNN: [title] | [1-line summary] | LOW/MEDIUM/HIGH |
## GDD Requirements
| TR-ID | Requirement | ADR Coverage |
|-------|-------------|--------------|
| TR-[system]-001 | [requirement text from registry] | ADR-NNNN ✅ |
| TR-[system]-002 | [requirement text] | ❌ No 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/`
## Next Step
Run `/create-stories [epic-slug]` to break this epic into implementable stories.
production/epics/index.mdCreate or update the master index:
# Epics Index
Last Updated: [date]
Engine: [name + version]
| Epic | Layer | System | GDD | Stories | Status |
|------|-------|--------|-----|---------|--------|
| [name] | Foundation | [system] | [file] | Not yet created | Ready |
After writing all epics for the requested scope:
/gate-check production to check readiness./create-stories [epic-slug] for each epic before developers can pick up work.After all requested epics are processed:
/create-stories [epic-slug] per epic.