!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

Resolved above — use as-is; --review overrides review_mode. No block →
defaults in .claude/docs/config-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 /brainstorm first; it writes the one-page brief." 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 one-sentence pitch; scope = its MVP feature list;
     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 MVP feature, in Build order, each traced to the brief. No
   story is blocked on ADR grounds: this tier has none.

Read no GDD, control manifest, TR registry or ADR at minimal. Go to Phase 3.

standard and full: the epic and what governs it

1. The epic: production/epics/[epic-slug]/EPIC.md in full (its layer, GDD,
   governing ADRs, and the GDD Requirements table with TR-IDs).
2. The GDD: its sections by heading, never the whole file:
   bash .claude/scripts/md-section.sh extract design/gdd/[file].md "Acceptance Criteria",
   and the same for Formulas, Edge Cases and Detailed Design (exit 3: try
   Detailed Rules, the design standard's name for the same section); at full
   the other required sections too (list shows the headings).
3. The control manifest: the epic's layer only, and the version:
   bash .claude/scripts/md-section.sh extract docs/architecture/control-manifest.md "[Layer] Layer Rules",
   plus its Manifest Version line.
4. The TR registry: this system's entries only: in
   docs/architecture/tr-registry.yaml, the lines matching system: <slug>\s*$,
   with each entry's id above and its text below. The anchor keeps combat from
   matching combat-ai; \s* takes a Windows line ending.
5. The ADRs, every one the epic names (governing, or in its requirements table,
   Proposed ones included), in one call:

   bash .claude/scripts/adr-status.sh ADR-0001 ADR-0003 ...

   Each row gives the status, layer, version (the story's ADR Version stamp),
   depends_on, and missing sections. Then read only Summary, Decision (its
   Implementation Guidelines inside) and Engine Compatibility of each, with
   md-section.sh extract. Engine Notes is a story field taken from Engine
   Compatibility, not an ADR section. An ADR with none of these sections predates
   the template: read it once, and flag it for /architecture-decision retrofit [file].

A named ADR with no file (NOT_FOUND):

• full: stop before decomposing any story.
• standard: stop only when it is critical (Foundation layer); otherwise warn, go
  on, and write the stories it governs as Blocked until it exists.
• On stopping: "Epic references [ADR-NNNN: title] but no file for it was found in
  docs/architecture/. Check the epic's Governing ADRs list, or run
  /architecture-decision to create it. Cannot create stories until the
  referenced ADR files exist."

Report before drafting, with the real state, every ADR on its own with its
status:

Loaded: epic [name] · GDD [file] · manifest v[date], [layer] rules
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0003 Accepted · ADR-0004 Proposed · [ADR-NNNN missing]

Never say "all present" when one is missing, or name a manifest version when there
is none.

Phase 3: Type each story

Type	When its criteria reference
Logic	formulas, thresholds, state transitions, AI decisions, calculations
Integration	two or more systems, signals across boundaries, save/load round-trips
Visual/Feel	animation, VFX, "feels responsive", timing, screen shake, audio sync
UI	menus, HUD, buttons, screens, dialogue boxes, tooltips
Config/Data	balance values and data files only, no new logic

A mixed story takes the type with the highest implementation risk. The type sets
the evidence /story-done needs.

Phase 4: Draft the stories

Group the requirements that need the same core implementation into one story, at
the story_granularity load. Order: foundation behaviour first, edge cases later,
UI last. For each story:

• Requirement: the TR-ID from the registry, matched through the epic's GDD
  Requirements table. Only when no entry matches, write TR-[system]-??? and say
  so.
• ADR: the one that governs how to build it (the requirements table names it).
  • Accepted: embed it.
  • Proposed: Status: Blocked, with "BLOCKED: ADR-NNNN is Proposed — accept it
    with /architecture-decision accept ADR-NNNN once decided".
  • Deprecated or Superseded: Status: Blocked, with "BLOCKED: ADR-NNNN is
    [status] — point the story at [successor] (edit its ADR field;
    /create-stories never rewrites an existing story) before implementing".
  • An Accepted ADR whose depends_on names an ADR that is not Accepted: Blocked
    the same way, naming that ADR.
  • Several apply: list them all, the most direct first.
  • None applies: ADR: N/A — [reason], e.g. "pure data configuration". Never
    blank: blank means unchecked.
• ADR Version: the story's ADR Version is the ADR's ## Last Verified
  date, else its ## Date, else unversioned (the version column). /dev-story
  trusts the story's ADR summary while this still matches the ADR.
• Engine risk: from the ADR's Engine Compatibility (its knowledge risk).
• Estimate: propose a t-shirt size from the criteria and the files the story
  touches: S (a few hours), M (about a day) or L (several days). It is a
  proposal: Phase 6 shows it and the user can change it. /story-readiness fails
  a story whose Estimate is still the template's bracket, so never leave it.

Phase 5: QA lead review

Read the review_gate line above. skill-gates=skip (solo or lean): no review;
note "QL-STORY-READY skipped — [Solo | Lean] mode" in the Phase 6 list and the
closing block. skill-gates=run: read references/qa-lead-gate.md and
.claude/docs/director-gates.md, and run it now, before the Phase 6 ask. On a skip,
do not load it.

Phase 6: Show the stories, ask once

## Stories for Epic: [name]
ADRs: ADR-0001 Accepted · ADR-0002 Accepted · ADR-0004 Proposed   (every ADR, from Phase 2)

Story 001: [title] — Logic — ADR-0001 — Ready — Estimate M
  Covers: TR-[system]-001 ([one-line requirement])
  Test required: tests/unit/[system]/[slug]_test.[ext]

Story 002: [title] — Integration — ADR-0004 — BLOCKED (ADR-0004 is Proposed) — Estimate L
  Covers: TR-[system]-002, TR-[system]-003
  Test required: tests/integration/[system]/[slug]_test.[ext]

Story 003: [title] — Visual/Feel — ADR-0001 — Ready — Estimate S
  Covers: TR-[system]-004
  Evidence required: retained screenshot + sign-off in production/qa/evidence/[slug]-evidence.md

[N stories: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data; N Blocked]
QL-STORY-READY: [skipped — Solo mode | its verdicts]

At minimal, each line traces to Brief MVP feature N, there is no ADRs line, and
there is one story per MVP feature: no extra stories for brief items outside the
MVP list. Then
ask: "May I write these [N] stories to production/epics/[epic-slug]/, and
[create | update] production/epics/[epic-slug]/EPIC.md and update
production/epics/index.md?" Options: Yes, write all [N] / Not yet, I want to
adjust first; an adjustment can change any estimate. Name every file Phase 7 touches: create EPIC.md only when it
does not exist, and leave index.md out when it does not exist. Write nothing
before the yes.

Phase 7: Write

The story files

Each story is production/epics/[epic-slug]/story-[NNN]-[slug].md, laid out
as .claude/docs/templates/story.md. Never reuse a story number. Write each file
as a file, never through a shell command: a shell write skips the project's write
checks.

At minimal there is no GDD, ADR, TR registry or manifest. Fill these fields
exactly:

Field	Value at minimal
GDD	design/game-brief.md
Requirement	Brief MVP feature N, never a TR-ID
ADR Governing Implementation, ADR Decision Summary, ADR Version	N/A (minimal — no ADRs)
Manifest Version, Control Manifest Rules	N/A (minimal — no control manifest)
Engine	engine.name + engine.version
Risk	the level docs/engine-reference/<engine>/VERSION.md gives the pinned version (its timeline row, or its overall rating). No file or no level: NOT ASSESSED (no VERSION.md risk rating), never a guess. /dev-story reads NOT ASSESSED as HIGH
Engine Notes	none (no ADR engine-compatibility analysis at minimal)
Acceptance Criteria	from the brief's Player goal & fail state and the MVP feature, made concrete and testable; never invented from a bare bullet

At every tier:

• QA Test Cases: when the review was skipped, write
  *N/A — no qa-lead specs at this tier; implement against the Acceptance Criteria above*.
  Never improvise test cases.
• Test Evidence: qa.level governs it. At qa.level: minimal tests are
  waived (advisory), but a Visual/Feel or UI story's retained screenshot is not.
• Estimate: the size from Phase 6, with any change the user made.
• Dependencies: name each story this one needs by its path.
• Files: the code and test files the story is planned to create or change,
  under the code root and test root. /dev-story replaces them with the real list.

EPIC.md

At minimal with none yet, write the Phase 2 draft with the table
below. Otherwise replace its "Stories: Not yet created" line with the table, or on
a return visit append one row per new story and leave the rest of the file as it
is:

## Stories

| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
| 001 | [title] | Logic | Ready | ADR-0001 |
| 002 | [title] | Integration | Blocked | ADR-0004 |

production/epics/index.md

Set the epic's Stories cell to [N] stories,
the epic's total after this run. When the file does not exist, say so:
Epics index not updated: production/epics/index.md absent.

Phase 8: Close

If other epics in production/epics/ have no stories, list them. Then ask:
"[N] stories written to production/epics/[epic-slug]/. What next?" Options, those
that apply:

• Start implementing: /dev-story [first-story-path] at minimal,
  /story-readiness [first-story-path] otherwise (recommended)
• Create stories for [next epic]: /create-stories [slug] (only when an epic has
  none)
• Plan the sprint: /sprint-plan new (only when every epic has stories; never at
  minimal, where the brief's build order is the plan)
• Stop here for this session

Never start implementation or write code: this skill stops at the story files.
Acceptance criteria come from the GDD (the brief at minimal), implementation
notes from the ADRs, rules from the manifest; none are invented.

The run's last reply ends with this block, after the question above is
answered (repeat it if you showed it earlier):

Verdict: COMPLETE — [N] stories written to production/epics/[epic-slug]/ ([N] Ready, [N] Blocked)
Review: [QL-STORY-READY skipped — Solo mode | skipped — Lean mode | its verdicts]
Index: [production/epics/index.md updated | Epics index not updated: production/epics/index.md absent]
Next step: [/dev-story [first-story-path] | /story-readiness [first-story-path]]

When the user declines the write: Verdict: BLOCKED — user declined. No story files written.