create-stories
/create-stories
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.
- Author
- wyx135230 ↗
- Repository
- Codex-Game-Studios ↗
- Licence
- MIT
- Last repository change
- 03.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Phase 1: Epic and settings
- Phase 2: Load the inputs
- Phase 3: Type each story
- Phase 4: Draft the stories
- Phase 5: QA lead review
- Phase 6: Show the stories, ask once
- Phase 7: Write
- Phase 8: Close
SKILL.md preview
---
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."
---
Read `.codex/docs/runtime.md` before executing this workflow. Arguments are the text following the skill invocation; substitute them where `$ARGUMENTS` appears.
Before proceeding, run this command from the repository root and use its output:
```bash
bash ".codex/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 `.codex/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 `.codex/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 .codex/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 .codex/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 .codex/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
`.codex/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 `.codex/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:
```markdown
## 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.`
Files in this package (3)
- CONTRACT.md 9 KB
- SKILL.md 16 KB
- references/qa-lead-gate.md 3 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · wyx135230/Codex-Game-Studios | 100 | MIT |
| T-X-R/codex-game-studio | 100 | MIT |
| Junghyeon0710/codex-game-studios | 100 | MIT |
| Donchitos/Claude-Code-Game-Studios | 100 | MIT |
| wyx135230/Codex-Game-Studios | 100 | MIT |
| idrisawad/Opencode-Game-Studios | 100 | MIT |
| chatquill/claude-code-websites | 90 | MIT |
Database snapshot: 13.11.2026 · package version d10260ab270f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100user-stories
Breaks an epic, spec, or feature into well-formed user stories with Given/When/Then acceptance criteria, applies INVEST, and splits stories that are too big. Use when a PM says "break this epic into stories", "write user stories", needs "acceptance criteria for X", wants to… - 95user-stories
Write INVEST-compliant user stories with Given-When-Then acceptance criteria. Use when writing user stories, creating acceptance criteria, or during /design Step 4. - 100create-user-stories
Generate user story map with BDD acceptance criteria when the user asks to create user stories, write stories, or break down a feature into stories - 90bmad-create-epics-and-stories
Break requirements into epics and user stories. Use when the user says "create the epics and stories list - 90bmad-create-epics-and-stories
Break requirements into epics and user stories. Use when the user says "create the epics and stories list - 100pm-workflow-problem-to-stories
Multi-skill workflow chain that takes a user problem (with optional prototype/mockup) and produces a full delivery-ready backlog: Lightweight PRD per Epic, sequenced Epics, and User Stories with acceptance criteria. Extends pm-workflow-problem-to-prd by adding Epic carving,…