/create-stories

name: create-stories
description: "Breaks one epic into implementable stories with acceptance criteria. Use when the user wants stories for an epic or the next batch of work to build. Not for turning the whole design into epics."
argument-hint: "[epic-slug | epic-path] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Agent, AskUserQuestion, Bash(bash "*/.claude/skills/create-stories/../../hooks/yaml-helper.sh" resolve_config *), Bash(bash .claude/scripts/adr-status.sh *), Bash(bash .claude/scripts/md-section.sh extract *), Bash(bash .claude/scripts/md-section.sh list *)
model: sonnet

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,review_gate,automation,workflow,docs.density,story_granularity,qa.level,system_overrides,engine_values,engine_row`

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

**Engine and roots** come from the `engine_values` and `engine_row` lines, never from anything else in context. `name=unset` means no engine is set: never assume one (not Godot, not web). The Engine field reads `not set (/setup-engine picks one; web for a new project)`, test paths take no engine's naming, and code and test roots are the ones `engine_row` gives (`unset` stays `unset`, per `.claude/docs/code-root-resolution.md`).

Ask with the question tool. Without one, list the options numbered and end your turn to wait. A skipped or dismissed question is not an answer: ask again in plain text.

Create Stories

A story is one implementable behaviour: small enough for the size `story_granularity` sets, self-contained, and traced to a requirement and the decision that governs it. Run this skill once per epic, in dependency order: Foundation epics first, then Core, Feature, Presentation.

**Writes:** `production/epics/[epic-slug]/story-NNN-[slug].md`, the epic's `EPIC.md` Stories table, and its row in `production/epics/index.md`. **Next:** `/dev-story [story-path]` at `workflow: minimal`; otherwise `/story-readiness [story-path]`, then `/dev-story`.

Asks follow `.claude/docs/automation-modes.md` (collaborative always asks, guided asks on major choices, autonomous logs and goes on; `automation_always_ask` categories always ask).

Checklist (copy it and tick as you go):

- [ ] Phase 1: epic found, tier resolved
- [ ] Phase 2: inputs loaded, each ADR's status reported
- [ ] Phase 3-4: stories drafted, typed, Ready or Blocked
- [ ] Phase 5: QA lead review run, or its skip noted
- [ ] Phase 6: story list shown, one ask to write
- [ ] Phase 7: stories, EPIC.md and index.md written (or index absence said)
- [ ] Phase 8: next step asked, closing block printed

Phase 1: Epic and settings

**Tier.** `workflow` for the epic's system: the `system_overrides` row for the epic slug (its GDD system) if there is one, else the project value.

**`story_granularity`** sets each story's acceptance-criteria load. Group or split criteria to hit it:

| `story_granularity` | ACs per story | Size | |---|---|---| | `coarse` (default, `rigor: minimal`) | 5-10 | a whole feature, multi-day | | `balanced` (`rigor: standard`) | 2-4 | one task, about one session | | `fine` | 1 | one criterion; the story name restates it |

**`docs.density`** sets the depth of each story's prose (context, implementation notes, ADR summary), never the AC count or the AC text: `terse` (default) = bullet notes, no preamble; `balanced` = a short context paragraph plus notes; `thorough` = full context, guidance and ADR rationale. The TR-ID, ADR Version and acceptance criteria are never trimmed.

**Which epic.** The text typed after the skill name, with any `--review <mode>` pair removed: an epic slug (`combat`) or a path (`production/epics/combat/EPIC.md`). With nothing typed, the epic the user's request names ("the loot epic") counts as named.

• **Named, but no `EPIC.md` there:** at `standard` and `full`, stop: "No epic at

`production/epics/[slug]/EPIC.md`. Run `/create-epics` to create it, or check the slug with `ls production/epics/`." Never decompose from a guess. At `minimal`, say this tier needs no `/create-epics` epic, take Phase 2's `minimal` branch, and name the slug it uses.

• **Blank, at `minimal`:** take Phase 2's `minimal` branch.
• **Blank, at `standard` or `full`:** list `production/epics/*/EPIC.md` with each

status, then ask: "Which epic would you like to break into stories?" with one option per epic. **No epics found:** stop and say "No epics found under `production/epics/`. Run `/create-epics layer: foundation` first." Never ask a question with no options.

Phase 2: Load the inputs

`minimal`: build the epic from the brief

1. **No `design/game-brief.md`:** stop. "There is no brief to build stories from yet: run `/prototype` and say the game in one line; it writes the one-page brief and a first build (`/brainstorm` first if you have no idea yet)." When the code root already holds the game (10 or more source files), name `/reverse-document design [code root]` instead. 2. Read `design/game-brief.md` in full (one page). 3. **The epic.** `<slug>` is the brief's working title, slugified (`mvp` if it has none), or the epic the user named.

• `production/epics/<slug>/EPIC.md` exists: it is the epic. Use its scope, still

traced to the brief, and never rewrite it.

• It does not: draft one, written in Phase 7 only after the Phase 6 ask names

it. Goal = the brief's pitch; scope = its Features list (MVP in briefs from before 1.3.0); order = its **Build order**. Keep it terse.

• Stories already in the folder (a return visit): never rewrite an existing

`story-*.md`. Add stories only for brief items they do not cover, or new ones the user names, and number on from the highest existing `story-NNN`. 4. **One story per Features item not built yet (`[ ]`), in Build order**, each traced to the brief. An