create-stories 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 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

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 for this epic's system (per .claude/docs/workflow-modes.md) — use the system_overrides row for if the block lists one, else the project value. is the epic slug / its GDD system. The tier sets which prerequisites block — see the note in Step 2.

storygranularity — it sets each story's AC load: 5–10 ACs covering a whole feature at coarse, 2–4 ACs covering one task at balanced (default), 1 AC** at fine (the story name is the AC restatement). Group or split ACs into stories to hit the target.

docs.density — it controls the depth of each story's prose (context, implementation notes, ADR summary), not the AC count (that is story_granularity) and never the AC text itself. modes.rigor sets it alongside workflow; set docs.density explicitly to vary story prose alone: terse = notes as bullets, no preamble; balanced = short context paragraph + notes (default); thorough = full context, implementation guidance, and ADR rationale. The embedded TR-ID reference, ADR Version stamp, and acceptance criteria are structural and are never trimmed by density.

minimal branch and synthesize the epic from design/game-brief.md. At standard/full, ask "Which epic would you like to break into stories?" and Glob production/epics/*/EPIC.md to list available epics with their status.

• /create-stories [epic-slug] — e.g. /create-stories combat
• /create-stories production/epics/combat/EPIC.md — full path also accepted
• No argument — at minimal there are no epics yet (Option A): skip to Step 2's

**If that glob returns nothing at standard/full, stop — do not build a

question with no options.** Report:

"No epics found under production/epics/. Run /create-epics layer: foundation

first — an epic is what this skill decomposes."

The zero-epic path is load-bearing. Asking which epic and globbing to

list them leaves an AskUserQuestion with nothing to offer when the glob is

empty. Route to /create-epics instead — it is named as Previous step

in this skill's own header.

Note what this skill guarded and what it did not. Step 2's ADR validation is

thorough: three tiers, each with its own stop condition, and an explicit

message naming the missing file. That is the deepest input. The first

input — does an epic exist at all — went unchecked. Guarding the far end of a

chain while leaving the near end open is the shape to watch for.

At minimal this does not apply: there are deliberately no epics, and the

branch above synthesizes one from the brief.

2. Load Everything for This Epic

minimal tier — synthesize the epic from the brief (Option A). At

minimal there is no /create-epics step and no EPIC.md. Instead:

1. Read design/game-brief.md in full (it is one page).

2. Synthesize an implicit epic: write a lightweight

production/epics//EPIC.md, where is the brief's slugified

working title (mvp if untitled) — goal = the brief's one-sentence pitch,

scope = its MVP feature list, ordering = its Build order. Keep it terse;

this is the container /dev-story and /sprint-status expect.

3. Generate one coarse story per MVP feature (Step 3+), in Build-order

sequence, each traced to the brief (not a GDD/TR-ID). Leave stories unblocked

on ADR grounds — none exist at this tier.

Skip the GDD, control-manifest, TR-registry, and ADR reads below (none exist at

minimal), then continue to Step 3 with the synthesized epic.

For standard/full (a /create-epics epic exists), read in full (these are small):

• production/epics/[epic-slug]/EPIC.md — epic overview, governing ADRs, GDD requirements table
• The epic's GDD (design/gdd/[filename].md) — at full read all 8 sections; at standard the 5 required sections (+ conditional Formulas); at minimal the GDD may not exist — work from the epic brief + acceptance criteria. Always prioritise Acceptance Criteria, Formulas, and Edge Cases where present.
• docs/architecture/control-manifest.md — grep only this epic's layer (Grep pattern="^## Layer Rules" path="docs/architecture/control-manifest.md" output_mode="content" -A 40) plus the header Manifest Version date, not a full read of all layers
• docs/architecture/tr-registry.yaml — grep only this system's entries (Grep pattern="system: " path="docs/architecture/tr-registry.yaml" output_mode="content" -B1 -A5, or id: TR--), not the whole cross-system registry

Load each governing ADR by section — never with an unbounded full read. A substantial ADR exceeds the 25k-token Read cap, and a capped read's only recovery is paging through the remainder — the most expensive possible way to read a file (measured at 103k tokens on a 34k-token ADR vs ~54k for targeted reads of the same file). Per ADR:

1. Map the headings (cheap — line numbers only):

Grep pattern="^## |^### Implementation Guidelines" path="docs/architecture/[adr-file].md" output_mode="content" -n

numbers from the map to set Read(offset, limit) spans that end where the next section begins:

1. Bounded-read exactly the sections this skill consumes, using the line

Guidelines subsection) — these feed the story's ADR Decision Summary and Implementation Notes.

• ## Summary and ## Decision (including its ### Implementation

Notes fields. (Engine Notes is a story field derived from this section — it is not an ADR section name; do not search for one.)

• ## Engine Compatibility — feeds the story's Engine, Risk, and Engine

1. Capture the ## Last Verified date:

Grep pattern="^## (Last Verified|Date)" path="docs/architecture/[adr-file].md" output_mode="content" -A 1

Use Last Verified, falling back to Date, then to unversioned if both are absent. This becomes the story's ADR Version stamp — /dev-story uses it to decide whether it can trust this story's distilled summary instead of re-opening the ADR.

Skip Context, Alternatives Considered, Consequences, Risks, and any Amendments Log unless a section you loaded explicitly cross-references one of their entries — then take only the referenced entry with one more bounded read. If the heading map comes back empty (a nonstandard ADR predating the template), fall back to one full Read — and if that read truncates at the cap, do not page through the remainder; grep for the story-relevant content directly and flag the ADR for /architecture-decision [file] retrofit.

ADR existence validation (tier-gated — resolved in Step 1): After reading the governing ADRs list from the epic, confirm each referenced ADR file exists on disk.