Claude-Code-Game-Studios/.claude/skills/create-stories/SKILL.md

name, description, argument-hint, user-invocable, allowed-tools, context, agent

name	description	argument-hint	user-invocable	allowed-tools	context	agent
create-stories	Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.	[epic-slug | epic-path] [--review full|lean|solo]	true	Read, Glob, Grep, Write	fork	lead-programmer

Create Stories

A story is a single implementable behaviour — small enough to complete in one focused session, self-contained, and fully traceable to a GDD requirement and an ADR decision. Stories are what developers pick up. Epics are what architects define.

Run this skill per epic, not per layer. Run it for Foundation epics first, then Core, and so on — matching the dependency order.

Output: production/epics/[epic-slug]/story-NNN-[slug].md files

Previous step: /create-epics [system] Next step after stories exist: /story-readiness [story-path] then /dev-story [story-path]

---

1. Parse Argument

Extract --review [full|lean|solo] if present and store as the review mode override for this run (see .claude/docs/director-gates.md).

• /create-stories [epic-slug] — e.g. /create-stories combat
• /create-stories production/epics/combat/EPIC.md — full path also accepted
• No argument — ask: "Which epic would you like to break into stories?" Glob production/epics/*/EPIC.md and list available epics with their status.

---

2. Load Everything for This Epic

Read in full:

• production/epics/[epic-slug]/EPIC.md — epic overview, governing ADRs, GDD requirements table
• The epic's GDD (design/gdd/[filename].md) — read all 8 sections, especially Acceptance Criteria, Formulas, and Edge Cases
• All governing ADRs listed in the epic — read the Decision, Implementation Guidelines, Engine Compatibility, and Engine Notes sections
• docs/architecture/control-manifest.md — extract rules for this epic's layer; note the Manifest Version date from the header
• docs/architecture/tr-registry.yaml — load all TR-IDs for this system

Report: "Loaded epic [name], GDD [filename], [N] governing ADRs, control manifest v[date]."

---

3. Classify Stories by Type

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. The type determines what test evidence is required before /story-done can close the story.

---

4. Decompose the GDD into Stories

For each GDD acceptance criterion:

1. Group related criteria that require the same core implementation
2. Each group = one story
3. Order stories: foundational behaviour first, edge cases last, UI last

Story sizing rule: one story = one focused session (~2-4 hours). If a group of criteria would take longer, split into two stories.

For each story, determine:

• GDD requirement: which acceptance criterion(ia) does this satisfy?
• TR-ID: look up in tr-registry.yaml. Use the stable ID. If no match, use TR-[system]-??? and warn.
• Governing ADR: which ADR governs how to implement this?
  • Status: Accepted → embed normally
  • Status: Proposed → set story Status: Blocked with note: "BLOCKED: ADR-NNNN is Proposed — run /architecture-decision to advance it"
• Story Type: from Step 3 classification
• Engine risk: from the ADR's Knowledge Risk field

---

4b. QA Lead Story Readiness Gate

After decomposing all stories (Step 4 complete) but before presenting them for write approval, spawn qa-lead via Task using gate QL-STORY-READY (.claude/docs/director-gates.md).

Pass: the full story list with acceptance criteria, story types, and TR-IDs; the epic's GDD acceptance criteria for reference.

Present the QA lead's assessment. For each story flagged as GAPS or INADEQUATE, revise the acceptance criteria before proceeding — stories with untestable criteria cannot be implemented correctly. Once all stories reach ADEQUATE, proceed to Step 5.

---

5. Present Stories for Review

Before writing any files, present the full story list:

## Stories for Epic: [name]

Story 001: [title] — Logic — ADR-NNNN
  Covers: TR-[system]-001 ([1-line summary of requirement])
  Test required: tests/unit/[system]/[slug]_test.[ext]

Story 002: [title] — Integration — ADR-MMMM
  Covers: TR-[system]-002, TR-[system]-003
  Test required: tests/integration/[system]/[slug]_test.[ext]

Story 003: [title] — Visual/Feel — ADR-NNNN
  Covers: TR-[system]-004
  Evidence required: production/qa/evidence/[slug]-evidence.md

[N stories total: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data]

Ask: "May I write these [N] stories to production/epics/[epic-slug]/?"

---

6. Write Story Files

For each story, write production/epics/[epic-slug]/story-[NNN]-[slug].md:

# 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]

## Context

**GDD**: `design/gdd/[filename].md`
**Requirement**: `TR-[system]-NNN`
*(Requirement text lives in `docs/architecture/tr-registry.yaml` — read fresh 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**: [from ADR Engine Compatibility section — post-cutoff APIs, verification required]

**Control Manifest Rules (this layer)**:
- Required: [relevant required pattern]
- Forbidden: [relevant forbidden pattern]
- Guardrail: [relevant performance guardrail]

---

## Acceptance Criteria

*From GDD `design/gdd/[filename].md`, scoped to this story:*

- [ ] [criterion 1 — directly from GDD]
- [ ] [criterion 2]
- [ ] [performance criterion if applicable]

---

## Implementation Notes

*Derived from ADR-NNNN Implementation Guidelines:*

[Specific, actionable guidance from the ADR. Do not paraphrase in ways that
change meaning. This is what the programmer reads instead of the ADR.]

---

## Out of Scope

*Handled by neighbouring stories — do not implement here:*

- [Story NNN+1]: [what it handles]

---

## Test Evidence

**Story Type**: [type]
**Required evidence**:
- 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"]

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

Replace the "Stories: Not yet created" line with a populated table:

## Stories

| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
| 001 | [title] | Logic | Ready | ADR-NNNN |
| 002 | [title] | Integration | Ready | ADR-MMMM |

---

7. After Writing

Tell the user:

"[N] stories written to production/epics/[epic-slug]/.

To start implementation:

1. Run /story-readiness [story-path] to confirm the first story is ready
2. Run /dev-story [story-path] to implement it
3. Run /code-review [changed files] after implementation
4. Run /story-done [story-path] to close it

Work through stories in order — each story's Depends on: field tells you what must be DONE before you can start it."

---

Collaborative Protocol

1. Read before presenting — load all inputs silently before showing the story list
2. Ask once — present all stories for the epic in one summary, not one at a time
3. Warn on blocked stories — flag any story with a Proposed ADR before writing
4. Ask before writing — get approval for the full story set before writing files
5. No invention — acceptance criteria come from GDDs, implementation notes from ADRs, rules from the manifest
6. Never start implementation — this skill stops at the story file level

After writing (or declining):

• Verdict: COMPLETE — [N] stories written to production/epics/[epic-slug]/. Run /story-readiness → /dev-story to begin implementation.
• Verdict: BLOCKED — user declined. No story files written.