Skip to content

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

Delete /create-epics-stories and update all references

Donchitos9f731f3d86f9
diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md
index f36cb69a..966f5fec 100644
--- a/.claude/docs/quick-start.md
+++ b/.claude/docs/quick-start.md
@@ -92,7 +92,9 @@ Ask yourself: "What department would handle this in a real studio?"
| `/architecture-decision` | Creates an ADR |
| `/architecture-review` | Validate all ADRs, dependency ordering, GDD traceability |
| `/create-control-manifest` | Flat programmer rules sheet from Accepted ADRs |
-| `/create-epics-stories` | Break GDDs + ADRs into implementable story files |
+| `/create-epics` | Translate GDDs + ADRs into epics (one per architectural module) |
+| `/create-stories` | Break a single epic into implementable story files |
+| `/dev-story` | Read a story and implement it — routes to the correct programmer agent |
| `/sprint-plan` | Creates or updates sprint plans |
| `/sprint-status` | Quick 30-line sprint snapshot |
| `/story-readiness` | Validate a story is implementation-ready before pickup |
diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md
index a82cf462..502a5db6 100644
--- a/.claude/docs/skills-reference.md
+++ b/.claude/docs/skills-reference.md
@@ -43,7 +43,9 @@
| Command | Purpose |
|---------|---------|
-| `/create-epics-stories` | Translate GDDs + ADRs + manifest into implementable story files |
+| `/create-epics` | Translate GDDs + ADRs into epics — one per architectural module |
+| `/create-stories` | Break a single epic into implementable story files |
+| `/dev-story` | Read a story and implement it — routes to the correct programmer agent |
| `/sprint-plan` | Generate or update a sprint plan; initializes sprint-status.yaml |
| `/sprint-status` | Fast 30-line sprint snapshot (reads sprint-status.yaml) |
| `/story-readiness` | Validate a story is implementation-ready before pickup (READY/NEEDS WORK/BLOCKED) |
diff --git a/.claude/skills/adopt/SKILL.md b/.claude/skills/adopt/SKILL.md
index 0d2352e8..f7773c4b 100644
--- a/.claude/skills/adopt/SKILL.md
+++ b/.claude/skills/adopt/SKILL.md
@@ -116,7 +116,7 @@ If `design/gdd/systems-index.md` exists:
1. **Parenthetical status values** — Grep for any Status cell containing
parentheses: `"Needs Revision ("`, `"In Progress ("`, etc.
- These break exact-string matching in `/gate-check`, `/create-epics-stories`,
+ These break exact-string matching in `/gate-check`, `/create-stories`,
and `/architecture-review`. **BLOCKING.**
2. **Valid status values** — check that Status column values are only from:
@@ -240,7 +240,7 @@ Stories audited: [N]
Gap counts:
BLOCKING: [N] — template skills will malfunction without these fixes
- HIGH: [N] — unsafe to run /create-epics-stories or /story-readiness
+ HIGH: [N] — unsafe to run /create-stories or /story-readiness
MEDIUM: [N] — quality degradation
LOW: [N] — optional improvements
@@ -350,7 +350,7 @@ If ADRs are missing Status fields:
If GDDs are missing Acceptance Criteria:
> "The most important GDD gap is missing Acceptance Criteria — without these,
-> `/create-epics-stories` can't generate stories. Shall I start with
+> `/create-stories` can't generate stories. Shall I start with
> `design/gdd/[highest-priority-system].md` using `/design-system retrofit`?"
Use `AskUserQuestion`:
diff --git a/.claude/skills/content-audit/SKILL.md b/.claude/skills/content-audit/SKILL.md
index 0c4ba825..1b9dd22f 100644
--- a/.claude/skills/content-audit/SKILL.md
+++ b/.claude/skills/content-audit/SKILL.md
@@ -181,7 +181,7 @@ After writing the report, ask:
> "Would you like to create backlog stories for any of the content gaps?"
If yes: for each system the user selects, suggest a story title and point them
-to `/create-epics-stories` or `/quick-design` depending on the size of the gap.
+to `/create-stories [epic-slug]` or `/quick-design` depending on the size of the gap.
### --summary mode
diff --git a/.claude/skills/create-control-manifest/SKILL.md b/.claude/skills/create-control-manifest/SKILL.md
index a4273788..003f5325 100644
--- a/.claude/skills/create-control-manifest/SKILL.md
+++ b/.claude/skills/create-control-manifest/SKILL.md
@@ -235,7 +235,7 @@ These APIs are deprecated or unverified for [engine + version]:
After writing the manifest:
-- If epics/stories don't exist yet: "Run `/create-epics-stories` — programmers
+- If epics/stories don't exist yet: "Run `/create-epics layer: foundation` then `/create-stories [epic-slug]` — programmers
can now use this manifest when writing story implementation notes."
- If this is a regeneration (manifest already existed): "Updated. Recommend
notifying the team of changed rules — especially any new Forbidden entries."
diff --git a/.claude/skills/create-epics-stories/SKILL.md b/.claude/skills/create-epics-stories/SKILL.md
deleted file mode 100644
index fdfcc38d..00000000
--- a/.claude/skills/create-epics-stories/SKILL.md
+++ /dev/null
@@ -1,407 +0,0 @@
----
-name: create-epics-stories
-description: "DEPRECATED — use /create-epics then /create-stories instead. This skill has been split into two focused skills: /create-epics (architect-level scoping, one per layer) and /create-stories (lead-programmer story breakdown, one per epic)."
-argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]"
-user-invocable: true
-allowed-tools: Read, Glob, Grep, Write, Task
-context: fork
-agent: technical-director
----
-
-# Create Epics & Stories — DEPRECATED
-
-> **This skill has been superseded.** Use the two-skill workflow instead:
->
-> 1. `/create-epics layer: foundation` — define Foundation epics (technical-director)
-> 2. `/create-stories [epic-slug]` — break each epic into stories (lead-programmer)
-> 3. `/create-epics layer: core` — define Core epics
-> 4. `/create-stories [epic-slug]` — break each Core epic into stories
->
-> **Why the split?** Epics are architectural scope decisions (technical-director's domain).
-> Stories are implementation decomposition (lead-programmer's domain). Mixing them in one
-> skill caused the wrong agent to own the wrong decisions.
->
-> **To implement a story** once stories exist, use `/dev-story [story-path]`.
-
----
-
-This skill translates the approved design and architecture into implementable
-work units. Each **epic** maps to one architectural module. Each **story** is a
-single implementable behaviour — small enough for one session, self-contained,
-and fully traceable to the GDD requirement it satisfies and the ADR that governs
-how to implement it.
-
-**Output:** `production/epics/[epic-slug]/`
-
-**When to run:** After `/architecture-review` passes and `/create-control-manifest`
-has been run. All MVP-tier GDDs should be complete and reviewed.
-
----
-
-## 1. Parse Arguments
-
-**Modes:**
-- `/create-epics-stories all` — process all systems in layer order
-- `/create-epics-stories layer: foundation` — process Foundation layer only
-- `/create-epics-stories [system-name]` — process one specific system
-- No argument — ask the user which mode to use
-
-If no argument, use `AskUserQuestion`:
-- "What would you like to create epics for?"
- - Options: "All systems (Foundation → Presentation)", "Foundation layer only",
- "Core layer only", "A specific system", "Feature + Presentation layers"
-
----
-
-## 2. Load All Inputs
-
-### Step 2a — L0: Summary Scan
-
-Before full-reading any documents, Grep all GDDs for their `## Summary` sections:
-
-```
-Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5
-```
-
-For `all` mode: display a manifest of all Approved/Designed GDDs with their
-summaries so the user can confirm scope before the full load begins.
-
-For `layer:` or `[system-name]` modes: filter to only the target GDDs based
-on the Summary quick-reference line (Layer + Priority). Skip full-reading
-GDDs outside the requested scope entirely.
-
-### Step 2b — L1/L2: Full Document Load
-
-Read everything for the in-scope systems before generating any output:
-
-### Design Documents
-- `design/gdd/systems-index.md` — authoritative system list, layers, status
-- In-scope GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status
-- For each GDD, extract:
- - System name and layer (from systems-index.md)
- - All acceptance criteria (these become story acceptance criteria)
- - All technical requirements (these trace to ADR coverage)
- - Dependencies on other systems
-
-### Architecture Documents
-- `docs/architecture/architecture.md` — module ownership and API boundaries
-- All Accepted ADRs in `docs/architecture/adr-*.md` — read "GDD Requirements
- Addressed", "Implementation Guidelines", "Engine Compatibility", and
- "ADR Dependencies" sections
-- `docs/architecture/control-manifest.md` if it exists — extract layer-specific
- rules to embed in stories; also extract the `Manifest Version:` date from the
- header block (this gets embedded in every story)
-
-### TR Registry
-- `docs/architecture/tr-registry.yaml` if it exists — read all active entries,
- indexed by `id`. Used to resolve TR-IDs for each GDD requirement. If the
- registry does not exist, note it once; stories will use `TR-[system]-???`
- placeholders with a warning.
-
-### Engine Reference
-- `docs/engine-reference/[engine]/VERSION.md` — engine name + version + risk levels
-
-Report: "Loaded [N] GDDs, [M] ADRs, control manifest: [exists/missing],
-manifest version: [date or N/A], TR registry: [N entries or missing],
-engine: [name + version]."
-
----
-
-## 3. Determine Processing Order
-
-Process systems 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, process systems in the order they appear in systems-index.md.
-
-For each system, determine the corresponding epic:
-- Epic = one architectural module from `architecture.md` that implements this system
-- If a system doesn't map cleanly to a single module, present options to the user
-
----
-
-## 4. For Each System: Define the Epic
-
-Present to the user before creating stories:
-
-```
-## Epic [N]: [System Name]
-
-**Layer**: [Foundation / Core / Feature / Presentation]
-**GDD**: design/gdd/[filename].md
-**Architecture Module**: [module name from architecture.md]
-**GDD Requirements Traced by ADRs**: [list TR-IDs that have ADR coverage]
-**Untraceable Requirements**: [list TR-IDs with no ADR — these need ADRs first]
-**Governing ADRs**: [ADR-NNNN, ADR-MMMM, ...]
-**Engine Risk**: [LOW/MEDIUM/HIGH — highest risk among governing ADRs]
-```
-
-Ask: "Shall I break Epic [N]: [name] into stories?"
-- Options: "Yes, break it down", "Skip this epic", "Pause — I need to write ADRs first"
-
-If there are untraced requirements (no ADR covers them), warn:
-> "⚠️ [N] requirements in [system] have no ADR. Stories for these cannot embed
-> implementation guidance. Consider running `/architecture-decision` first, or
-> I can create stories with a placeholder note to add ADR guidance later."
-
----
-
-## 5. Break Each Epic into Stories
-
-For each epic, decompose the GDD's acceptance criteria into stories:
-
-**Story sizing rules:**
-- One story = one implementable behaviour from the GDD
-- Small enough to complete in a single focused session (~2-4 hours of focused work)
-- Self-contained — no story depends on in-progress work from another story in
- the same epic (stories within an epic run sequentially; they can depend on
- previous stories being DONE, not in-progress)
-
-**Story identification process:**
-1. Read every acceptance criterion in the GDD
-2. Group related criteria that require the same core implementation
-3. Each group = one story
-4. Order stories within the epic: foundation behaviour first, edge cases last
-
-**Story Type Classification** — assign each story a type based on its acceptance criteria:
-
-| Story Type | Assign when criteria reference... |
-|---|---|
-| **Logic** | Formulas, numerical thresholds, state transitions, AI decisions, calculations |
-| **Integration** | Two or more systems interacting, signals crossing boundaries, save/load round-trips |
-| **Visual/Feel** | Animation behaviour, VFX, "feels responsive", timing, screen shake, audio sync |
-| **UI** | Menus, HUD elements, buttons, screens, dialogue boxes, tooltips |
-| **Config/Data** | Balance tuning values, data file changes only — no new code logic |
-
-Mixed stories: assign the type that carries the highest implementation risk and note the secondary type.
-The Story Type determines what evidence is required before `/story-done` can mark the story Complete.
-
-For each story, map:
-- **GDD requirement**: Which specific acceptance criterion does this satisfy?
-- **TR-ID**: Look up the matching entry in `tr-registry.yaml` by normalizing the
- requirement text (lowercase, trimmed). Use the stable ID from the registry.
- If no matching entry exists, note `TR-[system]-???` and warn the user to run
- `/architecture-review` to register the ID before this story is assigned.
-- **Governing ADR**: Which ADR tells the programmer how to implement this?
- **Important — ADR status gate**: check the ADR's `Status:` field.
- - If `Status: Accepted` → embed normally.
- - If `Status: Proposed` → set story `Status: Blocked` and note:
- `BLOCKED: ADR-NNNN is still Proposed — story cannot be safely implemented
- until the ADR is Accepted. Run /architecture-decision to advance it.`
- - Do not embed implementation guidance from a Proposed ADR.
-- **Engine risk**: Inherited from the ADR's Knowledge Risk field
-- **Control manifest rules**: Which layer rules apply?
-
----
-
-## 6. Generate Story Files
-
-For each story, produce a story file embedding full context:
-
-```markdown
-# Story [NNN]: [title]
-
-> **Epic**: [epic name]
-> **Status**: Ready
-> **Layer**: [Foundation / Core / Feature / Presentation]
-> **Type**: [Logic | Integration | Visual/Feel | UI | Config/Data]
-> **Manifest Version**: [date from control-manifest.md header — or "N/A" if manifest not yet created]
-
-## Context
-
-**GDD**: `design/gdd/[filename].md`
-**Requirement**: `TR-[system]-NNN`
-*(Requirement text is stored in `docs/architecture/tr-registry.yaml` — look up by ID at review time)*
-
-**ADR Governing Implementation**: [ADR-NNNN: title]
-**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
-
-**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
-**Engine Notes**: [relevant text from the ADR's Engine Compatibility section,
-especially Post-Cutoff APIs Used and Verification Required fields]
-
-**Control Manifest Rules (this layer)**:
-- Required: [relevant required pattern from manifest]
-- Forbidden: [relevant forbidden approach from manifest]
-- Guardrail: [relevant performance guardrail]
-
----
-
-## Acceptance Criteria
-
-*From GDD `design/gdd/[filename].md`, scoped to this story:*
-
-- [ ] [criterion 1 — directly from GDD, scoped to this story's behaviour]
-- [ ] [criterion 2]
-- [ ] [performance criterion if applicable]
-
----
-
-## Implementation Notes
-
-*Derived from ADR-NNNN Implementation Guidelines:*
-
-[Specific guidance for the programmer. This should be the ADR's Implementation
-Guidelines section, filtered to what's relevant for this story. Do not
-paraphrase in ways that change meaning.]
-
----
-
-## Out of Scope
-
-*These are handled by neighbouring stories — do not implement here:*
-
-- [Story NNN+1]: [what it handles]
-- [Other epic story]: [what it handles]
-
-This boundary prevents scope creep and keeps stories independently reviewable.
-
----
-
-## Test Evidence
-
-**Required evidence** (based on Story Type):
-- Logic: `tests/unit/[system]/[story-slug]_test.[ext]` — must exist and pass
-- Integration: `tests/integration/[system]/[story-slug]_test.[ext]` OR playtest doc
-- Visual/Feel: `production/qa/evidence/[story-slug]-evidence.md` + sign-off
-- UI: `production/qa/evidence/[story-slug]-evidence.md` or interaction test
-- Config/Data: smoke check pass (`production/qa/smoke-*.md`)
-
-**Status**: [ ] Not yet created
-
----
-
-## Dependencies
-
-- Depends on: [Story NNN-1 must be DONE, or "None"]
-- Unlocks: [Story NNN+1, or "None"]
-```
-
----
-
-## 7. Lead-Programmer Architecture Review
-
-Before asking for approval, spawn a `lead-programmer` subagent via Task to review
-the drafted stories for the current epic. Provide:
-- The epic summary (layer, module, governing ADRs)
-- All drafted story files for this epic
-- The control manifest (if it exists)
-
-Ask the lead-programmer to check:
-- **Story boundaries**: Are any stories too large (should be split) or too small (should be merged)?
-- **ADR adherence**: Do the implementation notes in the stories faithfully reflect the ADR decisions? Flag any that drift or contradict.
-- **Dependency ordering**: Is the story sequence safe? Can each story be implemented independently once its prerequisite is done?
-- **Missing stories**: Are there any infrastructure concerns (interfaces, base classes, test hooks) that need their own story before others can proceed?
-- **Control manifest compliance**: Do any stories ask for patterns explicitly forbidden in the manifest?
-
-The lead-programmer produces one of:
-- **APPROVED** — proceed to user approval as-is
-- **REVISIONS NEEDED** — list of specific changes; revise the affected stories before proceeding
-- **BLOCKED** — a fundamental issue (missing ADR, wrong layer, circular dependency) that must be resolved first
-
-If REVISIONS NEEDED: make the changes and re-present the updated stories to the lead-programmer before requesting user approval. Do not ask the user to approve stories with known structural issues.
-
-## 8. Approval Before Writing
-
-For each epic, after stories pass lead-programmer review, present a summary:
-
-```
-Epic [N]: [name]
-Stories: [N total]
- Story 001: [title] — [1-line summary]
- Story 002: [title] — [1-line summary]
- ...
-```
-
-Ask: "May I write these [N] stories and the epic index to
-`production/epics/[epic-slug]/`?"
-
----
-
-## 8. Write Output Files
-
-After approval, write:
-
-### Story files
-`production/epics/[epic-slug]/story-[NNN]-[slug].md`
-
-### Epic index
-`production/epics/[epic-slug]/EPIC.md`:
-
-```markdown
-# Epic: [name]
-
-> **Layer**: [Foundation / Core / Feature / Presentation]
-> **GDD**: design/gdd/[filename].md
-> **Status**: Ready
-> **Stories**: [N total]
-
-## Overview
-
-[1 paragraph describing what this epic implements]
-
-## Stories
-
-| # | Story | Status | ADR |
-|---|-------|--------|-----|
-| 001 | [title] | Ready | ADR-NNNN |
-| 002 | [title] | Ready | ADR-MMMM |
-
-## Definition of Done
-
-This epic is complete when:
-- All stories are implemented and reviewed
-- All acceptance criteria from [GDD filename] are passing
-- 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/`
-- No Foundation or Core layer stories have open blockers
-```
-
-### Master epics index
-`production/epics/index.md` (create or update):
-
-```markdown
-# Epics Index
-
-Last Updated: [date]
-Engine: [name + version]
-
-| Epic | Layer | System | Stories | Status |
-|------|-------|--------|---------|--------|
-| [name] | Foundation | [system] | [N] | Ready |
-```
-
----
-
-## 9. Gate-Check Integration
-
-After writing all epics for the requested scope, remind the user:
-
-- **Foundation + Core complete**: Pre-Production → Production gate requires
- Foundation and Core layer epics. Run `/gate-check production` to validate.
-- **All layers complete**: Full epic coverage achieved. The sprint plan can now
- reference real story file paths instead of GDD references.
-
----
-
-## Collaborative Protocol
-
-1. **Load silently** — read all inputs before presenting the first epic
-2. **One epic at a time** — present each epic before creating stories; don't
- batch all epics and ask once
-3. **Warn on gaps** — flag untraced requirements before proceeding; let the user
- decide whether to pause for ADRs or proceed with placeholders
-4. **Ask before writing** — per-epic approval before writing story files
-5. **No invention** — all acceptance criteria come from GDDs; all implementation
- notes come from ADRs; all rules come from the control manifest. Never invent
- requirements or rules that don't trace to a source document.
-6. **Reference by TR-ID, not by quote** — embed the stable `TR-[system]-NNN` ID
- in the story, not the GDD requirement text. The text lives in the registry and
- is read fresh at review time. This prevents false deviation flags when GDD
- wording is clarified after the story was written.
-7. **Never embed Proposed ADRs** — if the governing ADR is Proposed, set the
- story status to Blocked. Embedding implementation guidance from an unaccepted
- ADR creates silent risk when the ADR changes.
diff --git a/.claude/skills/skill-test/SKILL.md b/.claude/skills/skill-test/SKILL.md
index 939e16ed..1fb0f6d4 100644
--- a/.claude/skills/skill-test/SKILL.md
+++ b/.claude/skills/skill-test/SKILL.md
@@ -232,7 +232,7 @@ For each skill:
from catalog (or mark as "never" if not in catalog)
- Assign priority:
- `critical` — gate-check, design-review, story-readiness, story-done, review-all-gdds, architecture-review
- - `high` — create-epics-stories, create-control-manifest, propagate-design-change, story-done
+ - `high` — create-epics, create-stories, dev-story, create-control-manifest, propagate-design-change, story-done
- `medium` — team-* skills, sprint-plan, sprint-status
- `low` — all others
@@ -259,7 +259,9 @@ review-all-gdds | NO | never | — | never
Top 5 Priority Gaps (no spec, critical/high priority):
1. /architecture-review — critical, no spec
2. /review-all-gdds — critical, no spec
-3. /create-epics-stories — high, no spec
+3. /create-epics — high, no spec
+4. /create-stories — high, no spec
+5. /dev-story — high, no spec
4. /propagate-design-change — high, no spec
5. /sprint-plan — medium, no spec
diff --git a/.claude/skills/story-readiness/SKILL.md b/.claude/skills/story-readiness/SKILL.md
index 006e6240..2001ab63 100644
--- a/.claude/skills/story-readiness/SKILL.md
+++ b/.claude/skills/story-readiness/SKILL.md
@@ -264,11 +264,11 @@ draft the missing sections for your approval."
If the user says yes for a specific story, draft only the missing sections
in conversation. Do not use Write or Edit tools — the user (or
-`/create-epics-stories`) handles writing.
+`/create-stories`) handles writing.
**Redirect rules:**
- If a story file does not exist at all: "This story file is missing entirely.
- Run `/create-epics-stories [system-name]` to generate it from the GDD and ADR."
+ Run `/create-epics [layer]` then `/create-stories [epic-slug]` to generate stories from the GDD and ADR."
- If a story has no GDD reference and the work appears small: "This story has
no GDD reference. If the change is small (under ~4 hours), run
`/quick-design [description]` to create a Quick Design Spec, then reference
diff --git a/README.md b/README.md
index 53bf8126..7b046228 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,7 @@ The result: you still make every decision, but now you have a team that asks the
| Category | Count | Description |
|----------|-------|-------------|
| **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
-| **Skills** | 52 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics-stories`, `/story-done`, etc.) |
+| **Skills** | 65 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) |
| **Hooks** | 9 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection |
| **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more |
| **Templates** | 36 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more |
@@ -92,7 +92,7 @@ The template includes agent sets for all three major engines. Use the set that m
## Slash Commands
-Type `/` in Claude Code to access all 52 skills:
+Type `/` in Claude Code to access all 65 skills:
**Onboarding & Navigation**
`/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt`
@@ -107,7 +107,7 @@ Type `/` in Claude Code to access all 52 skills:
`/create-architecture` `/architecture-decision` `/architecture-review` `/create-control-manifest`
**Stories & Sprints**
-`/create-epics-stories` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate`
+`/create-epics` `/create-stories` `/dev-story` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate`
**Reviews & Analysis**
`/design-review` `/code-review` `/balance-check` `/asset-audit` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check`
diff --git a/UPGRADING.md b/UPGRADING.md
index ad820064..f621369d 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -88,7 +88,7 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
| Category | Changes |
|----------|---------|
-| **New skills (15)** | `/ux-design`, `/ux-review`, `/help`, `/quick-design`, `/review-all-gdds`, `/story-readiness`, `/story-done`, `/sprint-status`, `/adopt`, `/create-architecture`, `/create-control-manifest`, `/create-epics-stories`, `/propagate-design-change`, `/content-audit`, `/architecture-review` |
+| **New skills (17)** | `/ux-design`, `/ux-review`, `/help`, `/quick-design`, `/review-all-gdds`, `/story-readiness`, `/story-done`, `/sprint-status`, `/adopt`, `/create-architecture`, `/create-control-manifest`, `/create-epics`, `/create-stories`, `/dev-story`, `/propagate-design-change`, `/content-audit`, `/architecture-review` |
| **New hook** | `log-agent-stop.sh` — completes agent audit trail (stop event to match start) |
| **New templates (8)** | `ux-spec.md`, `hud-design.md`, `accessibility-requirements.md`, `interaction-pattern-library.md`, `player-journey.md`, `difficulty-curve.md`, and 2 adoption plan templates |
| **New infrastructure** | `workflow-catalog.yaml` (7-phase pipeline, read by `/help`), `docs/architecture/tr-registry.yaml` (stable TR-IDs), `production/sprint-status.yaml` schema |
@@ -119,7 +119,9 @@ Best when: you didn't use git to set up the template (just downloaded a zip).
.claude/skills/adopt/SKILL.md
.claude/skills/create-architecture/SKILL.md
.claude/skills/create-control-manifest/SKILL.md
-.claude/skills/create-epics-stories/SKILL.md
+.claude/skills/create-epics/SKILL.md
+.claude/skills/create-stories/SKILL.md
+.claude/skills/dev-story/SKILL.md
.claude/skills/propagate-design-change/SKILL.md
.claude/skills/content-audit/SKILL.md
.claude/skills/architecture-review/SKILL.md
diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md
index 48cad81b..f35cc0e7 100644
--- a/docs/WORKFLOW-GUIDE.md
+++ b/docs/WORKFLOW-GUIDE.md
@@ -126,7 +126,7 @@ production/ # Sprint plans, milestones, releases
sprints/
milestones/
releases/
- stories/ # Story files (from /create-epics-stories)
+ epics/ # Epic and story files (from /create-epics + /create-stories)
playtests/ # Playtest reports
session-state/ # Ephemeral session state (gitignored)
session-logs/ # Session audit trail (gitignored)
@@ -586,18 +586,23 @@ that proves the core loop is fun.
### Phase 4 Pipeline
```
-/prototype --> /create-epics-stories --> /sprint-plan
- | | |
- v v v
- Throwaway Story files in First sprint with
- prototypes production/stories/ prioritized stories
- in prototypes/ from GDDs + ADRs + production/sprints/
- control manifest sprint-*.md
- |
- v
- /story-readiness
- (validates each story
- before pickup)
+/prototype --> /create-epics --> /create-stories --> /sprint-plan
+ | | | |
+ v v v v
+ Throwaway Epic files in Story files in First sprint with
+ prototypes production/ production/ prioritized stories
+ in prototypes/ epics/*/EPIC.md epics/*/story-*.md production/sprints/
+ (one per module) (one per behaviour) sprint-*.md
+ |
+ v
+ /story-readiness
+ (validates each story
+ before pickup)
+ |
+ v
+ /dev-story
+ (implements the story,
+ routes to right agent)
|
v
Vertical Slice
@@ -625,20 +630,27 @@ pollutes `src/`.
hardcoded values OK, no tests required -- but a README with hypothesis and
findings is mandatory.
-### Step 4.2: Create Stories From Design Artifacts
+### Step 4.2: Create Epics and Stories From Design Artifacts
```
-/create-epics-stories
+/create-epics layer: foundation
+/create-stories [epic-slug] # repeat for each epic
+/create-epics layer: core
+/create-stories [epic-slug] # repeat for each core epic
```
-This reads your GDDs, ADRs, and control manifest to generate implementable
-story files in `production/stories/`. Each story embeds:
+`/create-epics` reads your GDDs, ADRs, and architecture to define epic scope —
+one epic per architectural module. Then `/create-stories` breaks each epic into
+implementable story files in `production/epics/[slug]/`. Each story embeds:
- GDD requirement references (TR-IDs, not quoted text -- stays fresh)
- ADR references (only from Accepted ADRs; Proposed ADRs cause `Status: Blocked`)
- Control manifest version date (for staleness detection)
- Engine-specific implementation notes
- Acceptance criteria from the GDD
+Once stories exist, run `/dev-story [story-path]` to implement one — it routes
+automatically to the correct programmer agent.
+
### Step 4.3: Validate Stories Before Pickup
```
@@ -1395,7 +1407,9 @@ conflicts go to `producer`.
| Command | Purpose | Phase |
|---------|---------|-------|
-| `/create-epics-stories` | Break GDDs + ADRs into story files | 4 |
+| `/create-epics` | Translate GDDs + ADRs into epics (one per module) | 4 |
+| `/create-stories` | Break a single epic into story files | 4 |
+| `/dev-story` | Implement a story — routes to the correct programmer agent | 5 |
| `/sprint-plan` | Create or manage sprint plans | 4-5 |
| `/sprint-status` | Quick 30-line sprint snapshot | 5 |
| `/story-readiness` | Validate story is implementation-ready | 4-5 |
@@ -1482,7 +1496,7 @@ conflicts go to `producer`.
5. /architecture-review
6. /create-control-manifest
7. /gate-check technical-setup
-8. /create-epics-stories (break GDDs into stories)
+8. /create-epics layer: foundation + /create-stories [slug] (define epics, break into stories)
9. /sprint-plan new
10. /story-readiness -> implement -> /story-done (story lifecycle)
```
diff --git a/docs/architecture/tr-registry.yaml b/docs/architecture/tr-registry.yaml
index 97935084..92cab0e2 100644
--- a/docs/architecture/tr-registry.yaml
+++ b/docs/architecture/tr-registry.yaml
@@ -14,7 +14,7 @@
# the new TR-ID(s).
#
# WRITTEN BY: /architecture-review (appends new entries, never overwrites)
-# READ BY: /create-epics-stories (embed IDs in stories)
+# READ BY: /create-stories (embed IDs in stories)
# /story-done (look up current requirement text at review time)
# /story-readiness (validate TR-ID exists and is active)
#
diff --git a/docs/examples/session-adopt-brownfield.md b/docs/examples/session-adopt-brownfield.md
index 64bf0eee..143f9daf 100644
--- a/docs/examples/session-adopt-brownfield.md
+++ b/docs/examples/session-adopt-brownfield.md
@@ -61,7 +61,7 @@
>
> | Gap | Severity | Reason |
> |-----|----------|--------|
-> | No systems index | BLOCKING | `/design-system`, `/create-epics-stories`, `/gate-check` all require it |
+> | No systems index | BLOCKING | `/design-system`, `/create-stories`, `/gate-check` all require it |
> | GDD files not in template format | HIGH | Skills cannot reference TR-IDs from malformed GDDs |
> | No architecture docs | HIGH | Cannot run `/architecture-review` or `/create-control-manifest` |
> | No production tracking | MEDIUM | Sprint and story skills won't work, but not needed until production phase |
diff --git a/docs/examples/session-story-lifecycle.md b/docs/examples/session-story-lifecycle.md
index 9c2d6536..0df3df51 100644
--- a/docs/examples/session-story-lifecycle.md
+++ b/docs/examples/session-story-lifecycle.md
@@ -1,6 +1,6 @@
# Example Session: Full Story Lifecycle — /story-readiness → Implement → /story-done
-**Context:** Solo indie dev, mid-production sprint. The movement system GDD and architecture are complete. A story for movement's core implementation has been generated by `/create-epics-stories`.
+**Context:** Solo indie dev, mid-production sprint. The movement system GDD and architecture are complete. A story for movement's core implementation has been generated by `/create-stories`.
**Starting State:**
- `design/gdd/movement-system.md` — complete, all 8 sections
diff --git a/docs/examples/skill-flow-diagrams.md b/docs/examples/skill-flow-diagrams.md
index 172a9624..b5c1ddaa 100644
--- a/docs/examples/skill-flow-diagrams.md
+++ b/docs/examples/skill-flow-diagrams.md
@@ -39,7 +39,8 @@ PHASE 3: TECHNICAL SETUP
PHASE 4: PRE-PRODUCTION
/ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md
/ux-review ──────────────────────────────────────────────────► UX specs approved
- /create-epics-stories ───────────────────────────────────────► production/stories/STORY-*.md
+ /create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md
+ /create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.md
/prototype [core-mechanic] ──────────────────────────────────► prototypes/[name]/
/playtest-report ────────────────────────────────────────────► tests/playtest/vertical-slice.md
/sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-01.md
@@ -117,10 +118,15 @@ upstream GDDs (input, if any)
How a story gets from backlog to closed:
```
-/create-epics-stories
+/create-epics [layer: foundation]
│
- └── Output: production/stories/STORY-[SYS]-NNN.md
- (Status: backlog or blocked if ADR is Proposed)
+ └── Output: production/epics/[slug]/EPIC.md
+ │
+ ▼
+ /create-stories [epic-slug]
+ │
+ └── Output: production/epics/[slug]/story-NNN-[slug].md
+ (Status: Ready or Blocked if ADR is Proposed)
│
▼
/story-readiness [story]
diff --git a/tests/skills/catalog.yaml b/tests/skills/catalog.yaml
index 7c82b4e9..831f7c8f 100644
--- a/tests/skills/catalog.yaml
+++ b/tests/skills/catalog.yaml
@@ -51,7 +51,21 @@ skills:
priority: critical
# High — pipeline-critical skills
- - name: create-epics-stories
+ - name: create-epics
+ spec: ""
+ last_static: ""
+ last_static_result: ""
+ last_spec: ""
+ last_spec_result: ""
+
+ - name: create-stories
+ spec: ""
+ last_static: ""
+ last_static_result: ""
+ last_spec: ""
+ last_spec_result: ""
+
+ - name: dev-story
spec: ""
last_static: ""
last_static_result: ""