create-epics skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,docs.density,storygranularity,systemoverrides

Resolved above — use as-is; --review overrides review_mode. No block → defaults in .claude/docs/config-resolution.md.

Create Epics

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 (at full). At standard, critical ADRs + a control manifest suffice. At minimal, this skill is optional and not part of the path — /create-stories synthesizes the epic from design/game-brief.md itself (Option A). If run anyway, it decomposes directly from the brief with no GDD/ADR/manifest prerequisite.

At minimal, this skill is optional — /create-stories synthesizes the epic

(Option A). At that tier /create-stories reads design/game-brief.md

directly, writes a lightweight implicit production/epics//EPIC.md, and

generates stories from the MVP list — so the path is /brainstorm →

/create-stories → /dev-story, with no separate /create-epics or

/sprint-plan step. At standard/full an epic IS required:

/create-stories reads production/epics/[slug]/EPIC.md, and skipping this

skill there leaves /dev-story with no story to implement — a dead end, not a

shortcut.

1. Parse Arguments

See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

workflow (per .claude/docs/workflow-modes.md):

create-epics runs project-wide: it uses the project-level tier for its prerequisite expectations and consults workflowoverrides.systemoverrides. per-system when reading each in-scope GDD. See "Workflow tier adjustment" in Step 2.

storygranularity — it sizes the epic's story breakdown: expect 3–5 child stories per epic at coarse, 5–10 at balanced (default), 10–20** at fine.

docs.density — it controls the depth of each epic's written scope and rationale, not the story count (that is story_granularity). modes.rigor sets it alongside workflow; set docs.density explicitly to vary epic prose alone: terse = scope as bullets, one-line rationale; balanced = a scope paragraph with light rationale (default); thorough = full scope prose with governing-ADR rationale and risk discussion. The EPIC.md tables (GDD requirements, governing ADRs) are structural and stay whole at every density.

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?"

2. Load Inputs

Step 2a — Summary scan (fast, fail-open)

Establish the denominator first. Glob design/gdd/.md, excluding the non-system docs (game-concept.md, systems-index.md, game-pillars.md, gameplay-tags.md, entity-registry.md, fixture-swap-ledger.md, and any gdd-cross-review-.md — the same set gdd-structure-check.sh skips). Call the count N. If N is 0, there are no system GDDs — report "No system GDDs found in design/gdd/ — run /design-system first" and stop.

Scan for Summary sections:

Grep pattern="^## Summary" glob="design/gdd/*.md" output_mode="content" -A 5

Interpret the M matches against N. These are three different outcomes, and a zero-match scan is never the same as "nothing in scope":

Never treat an absent ## Summary as an absent system. The scan narrows the read set when it succeeds; it never shrinks the in-scope set. In all mode every system is in scope regardless of Summary, so the scan is a convenience only — never a filter.

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

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:

unrelated domains entirely. For each in-scope ADR, load only the "GDD Requirements Addressed", "Decision", and "Engine Compatibility" sections — never an unbounded full read:

• 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 — skip ADRs for

Grep pattern="^## (GDD Requirements Addressed|Decision|Engine Compatibility)" path="docs/architecture/[adr-file].md" output_mode="content" -n

then Read(offset, limit) bounded to each match through the next ## heading (or to end of file for the last match). This matters most on a large ADR — measured at 47k tokens this way vs. 103k for an unbounded read of the same size file.

• 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]."

Workflow tier adjustment (resolved in Step 1; per-system via

system_overrides). The inputs above are the full baseline:

- full — every in-scope GDD must be Approved with all 8 sections; TR

registry + control manifest are required inputs; untraced requirements

(Step 4) are flagged before proceeding.

- standard — GDDs need the 5 required sections (+ conditional Formulas)

approved; only critical (Foundation-layer) ADRs are expected; the control

manifest is read if present, not required. A system pinned higher via

system_overrides must still meet its higher bar.

- minimal — decompose against design/game-brief.md +

acceptance criteria. Do not require GDDs, ADRs, the TR registry, or the

manifest; skip the untraced-requirement gate. If run, the epic is still

produced — but note /create-stories also synthesizes one from the brief when

this skill is skipped (the default minimal path).

3. Processing Order

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.