Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/pipeline/create-stories.md

Skill Test Spec: /create-stories

Skill Summary

/create-stories breaks a single epic into developer-ready story files. At standard/full workflow it reads production/epics/[epic-slug]/EPIC.md, the epic's GDD, the governing ADRs (section-bounded reads, never unbounded), this layer's rules from the control manifest and this system's entries in the TR registry. At minimal it synthesizes an implicit epic from design/game-brief.md instead, and writes that epic's EPIC.md only after the write ask names it.

Each story is classified by type (Logic / Integration / Visual/Feel / UI / Config/Data), which fixes its required test evidence. A story governed by a Proposed ADR is set Status: Blocked. In full review mode qa-lead is spawned once with gate QL-STORY-READY (verdicts ADEQUATE / GAPS / INADEQUATE) and returns test-case specs for ADEQUATE stories; GAPS go to the user (Revise / Accept / Discuss), INADEQUATE blocks the story until it is revised; in lean/solo the gate is skipped with a note. All stories are presented in one summary and the skill asks once — "May I write these [N] stories to production/epics/[epic-slug]/, and update production/epics/[epic-slug]/EPIC.md and production/epics/index.md?" — then writes story-NNN-[slug].md files and updates the epic's EPIC.md and production/epics/index.md. Verdicts: COMPLETE or BLOCKED (user declined).

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: COMPLETE, BLOCKED
• Contains "May I write" collaborative protocol language (one approval for the full story set)
• Has a next-step handoff at the end (/story-readiness, /dev-story)
• Documents story Status: Blocked when governing ADR is Proposed
• Documents QL-STORY-READY gate: active in full mode, skipped in lean/solo

---

Director Gate Checks

In full mode: qa-lead is spawned once via Agent with gate QL-STORY-READY after all stories are decomposed and before the write ask. It returns a verdict per story (ADEQUATE / GAPS / INADEQUATE) plus Given/When/Then specs (Logic, Integration) or manual verification steps (Visual/Feel, UI) for ADEQUATE stories. GAPS → AskUserQuestion with Revise flagged criteria / Accept and proceed / Discuss further — nothing is revised before the user chooses. INADEQUATE → blocking: the story is revised with the user (or dropped and named) before the write ask. NOT ASSESSED [missing input] → never read as ADEQUATE: the input is supplied and the verdict re-requested, or the story is written without qa-lead specs and marked QL-STORY-READY: NOT ASSESSED — [input] in the story list.

In lean mode: QL-STORY-READY is skipped. Output notes: "QL-STORY-READY skipped — Lean mode."

In solo mode: QL-STORY-READY is skipped. Output notes: "QL-STORY-READY skipped — Solo mode."

---

Test Cases

Case 1: Happy Path — Epic with 3 stories, all ADRs Accepted

Fixture:

• project.yaml: engine.name: Godot, modes.workflow: full, modes.review_mode: lean, modes.story_granularity: fine (one story per acceptance criterion)
• production/epics/combat/EPIC.md exists with 3 GDD requirements and its governing ADRs listed
• The epic's GDD exists with exactly one acceptance criterion per requirement (one is a damage formula)
• All governing ADR files exist with ## Status Accepted
• docs/architecture/control-manifest.md exists
• docs/architecture/tr-registry.yaml has TR-IDs for all 3 requirements
• production/epics/index.md has a row for the epic with Not yet created

Input: /create-stories combat

Expected behavior:

1. Reads EPIC.md and the GDD in full; greps this layer's ## <layer> Layer Rules from the manifest and this system's TR-registry entries; loads each ADR by heading map + bounded reads
2. Reports "Loaded epic [name], GDD [filename], [N] governing ADRs [status], [manifest status]."
3. Classifies each story by type (the damage-formula story is Logic)
4. Notes "QL-STORY-READY skipped — Lean mode."
5. Presents the story list (title, type, ADR, covered TR-IDs, test/evidence path)
6. Asks once: "May I write these 3 stories to production/epics/combat/, and update production/epics/combat/EPIC.md and production/epics/index.md?"
7. Writes story-001-[slug].md … story-003-[slug].md, updates the EPIC.md Stories table and the index row to 3 stories
8. Asks what next, recommending /story-readiness [first-story-path]; Verdict: COMPLETE

Assertions:

• Exactly 3 stories are drafted — one per acceptance criterion at fine
• Each story file has the header fields Epic, Status, Layer, Type, Manifest Version, and a Context block with GDD, Requirement: TR-[system]-NNN, ADR Governing Implementation, ADR Version, Engine/Risk
• Each story has Acceptance Criteria, QA Test Cases, Test Evidence and Dependencies sections
• The formula story is typed Logic with evidence path tests/unit/[system]/… (the Godot test root)
• "QL-STORY-READY skipped — Lean mode." appears and each QA Test Cases section reads "N/A — no qa-lead specs at this tier…" (no improvised test cases)
• "May I write" is asked once, after the full list is shown, and names the 3 stories, EPIC.md and production/epics/index.md
• Files are named production/epics/combat/story-NNN-[slug].md
• Skill does NOT start implementation

---

Case 2: Failure Path — Named epic does not exist

Fixture:

• project.yaml: modes.workflow: full
• production/epics/ contains other epics but no nonexistent-epic/ directory

Input: /create-stories nonexistent-epic

Expected behavior:

1. Skill looks for production/epics/nonexistent-epic/EPIC.md — not found
2. Skill outputs a clear error naming that path
3. Skill recommends /create-epics (the Previous step) or checking the slug against the epics under production/epics/
4. No story files are created and no epic is synthesized from the brief

Assertions:

• Skill outputs a clear error naming production/epics/nonexistent-epic/EPIC.md
• No story files, EPIC.md or index row are written
• Skill recommends /create-epics
• Skill does NOT fall through to the minimal brief-synthesis branch at full

---

Case 3: Blocked Story — ADR is Proposed

Fixture:

• project.yaml: modes.workflow: full, modes.review_mode: solo, modes.story_granularity: fine
• EPIC.md exists with 2 requirements, one acceptance criterion each; both governing ADR files exist
• Requirement 1 is governed by an ADR with ## Status Accepted
• Requirement 2 is governed by ADR-0007 with ## Status Proposed

Input: /create-stories [epic-slug]

Expected behavior:

1. Both ADR files exist, so the full-tier existence check passes
2. Skill reads each governing ADR's status and finds ADR-0007 Proposed
3. Story 2 is drafted with Status: Blocked and the note "BLOCKED: ADR-0007 is Proposed — accept it with /architecture-decision accept ADR-0007 once decided"
4. Story 1 is drafted with Status: Ready
5. The blocked story is flagged in the story list before the single "May I write" ask

Assertions:

• The ADR status is taken from the ADR's ## Status section, not assumed
• Story 2 has Status: Blocked and the note names ADR-0007 and /architecture-decision accept — never a bare /architecture-decision, which starts a new ADR
• Variant — ADR-0007's ## Status reads Superseded by ADR-0009: story 2 is still Status: Blocked, and its note names ADR-0009 as the ADR to point it at
• Story 1 has Status: Ready — the blocked ADR does not affect it
• The blocked story is flagged before write approval, not discovered after writing
• Both story files are written (blocked stories are still written — just flagged)

---

Case 4: Edge Case — No argument provided

Fixture:

• project.yaml: modes.workflow: standard
• production/epics/ contains 2 epic subdirectories, each with an EPIC.md

Input: /create-stories (no argument)

Expected behavior:

1. Skill detects no argument at standard
2. Globs production/epics/*/EPIC.md
3. Asks via AskUserQuestion: "Which epic would you like to break into stories?" with the 2 epics (and their status) as options
4. Decomposes only the epic the user picks

Assertions:

• Skill asks "Which epic would you like to break into stories?" rather than erroring
• Both epics from the glob are offered as options
• No story files are written before the user picks
• Skill does NOT silently pick an epic without user input
• Skill does NOT take the minimal brief-synthesis branch at standard

Fixture (no epics):

• project.yaml: modes.workflow: standard
• production/epics/ holds no EPIC.md

Expected behavior (no epics):

1. The glob returns nothing, so the skill stops: "No epics found under production/epics/. Run /create-epics layer: foundation first — an epic is what this skill decomposes."

Assertions (no epics):

• No "Which epic…" question is asked with an empty option list
• The stop names /create-epics and nothing is written

---

Case 5: Director Gate — Full mode, one story returns GAPS from QL-STORY-READY

Fixture:

• project.yaml: modes.workflow: full, modes.review_mode: full, modes.story_granularity: fine
• EPIC.md exists with 2 requirements, one acceptance criterion each; both governing ADRs Accepted
• QL-STORY-READY returns ADEQUATE for story 1 and GAPS for story 2 (one vague acceptance criterion)
• At the GAPS question the user picks Revise flagged criteria

Input: /create-stories [epic-slug]

Expected behavior:

1. Both stories are decomposed
2. qa-lead is spawned once with QL-STORY-READY for the whole story list
3. The assessment is presented: story 1 ADEQUATE with its test-case specs; story 2 GAPS naming the vague criterion
4. AskUserQuestion for story 2: Revise flagged criteria / Accept and proceed / Discuss further
5. On Revise: story 2's revised criteria are drafted and shown; specs for story 2 alone are re-requested in one follow-up call
6. Once both are ADEQUATE, the story list is presented and the single write ask is made; each story's QA Test Cases section holds the qa-lead specs

Assertions:

• qa-lead is spawned once for all stories (not once per story, and not a second time for story 1's specs); the only follow-up call covers story 2 alone
• Per-story verdicts use ADEQUATE / GAPS / INADEQUATE and name the failing criterion
• The GAPS verdict goes to the user with the three options — story 2's criteria are not revised before the user chooses
• Story 2's revised criteria are shown before the write ask; it carries no specs until ADEQUATE
• Had the user picked Accept and proceed, story 2 would be written with its criteria unchanged and its QA Test Cases reading *Test cases not yet defined — run /qa-plan to generate them.*
• Story 1's QA Test Cases section contains Given/When/Then (Logic/Integration) or Setup/Verify/Pass condition (Visual/Feel, UI) blocks from the gate
• No "QL-STORY-READY skipped" note appears in full mode

---

Case 6: Minimal tier — epic synthesized from the brief, then a return visit

Fixture:

• project.yaml: engine.name: Godot, engine.version: "4.6", and no modes keys — modes.rigor defaults to minimal, so workflow, qa.level and the review mode resolve to minimal / minimal / solo
• design/game-brief.md with working title "Lantern Keeper", a Player goal & fail state, 2 MVP features and a Build order
• docs/engine-reference/godot/VERSION.md is absent
• No production/epics/ directory

Input: /create-stories

Expected behavior:

1. No argument at minimal takes Step 2's minimal branch and reads the brief; nothing stops for the absent GDD, ADRs, control manifest or TR registry
2. Drafts production/epics/lantern-keeper/EPIC.md without writing it
3. Notes "QL-STORY-READY skipped — Solo mode."
4. Presents 2 stories, one per MVP feature in Build order, and asks once to write them and create production/epics/lantern-keeper/EPIC.md (no index.md — it does not exist)
5. Writes EPIC.md and both stories; prints Epics index not updated: production/epics/index.md absent
6. Recommends /dev-story [first-story-path] — no /story-readiness, no /sprint-plan option

Assertions:

• Nothing, EPIC.md included, is written before the single write ask, and that ask names EPIC.md
• Each story reads Requirement: Brief MVP feature N, N/A (minimal — no ADRs) in its ADR fields and N/A (minimal — no control manifest) as its Manifest Version
• Each story's Risk is NOT ASSESSED (no VERSION.md risk rating) — never a guessed level
• Each QA Test Cases section reads the "N/A — no qa-lead specs at this tier…" line
• The index line names production/epics/index.md, not the systems index

Fixture (return visit):

• As above after that run: production/epics/lantern-keeper/ holds EPIC.md (a 2-row Stories table), story-001-… and story-002-…; the brief now lists a 3rd MVP feature

Expected behavior (return visit):

1. Reads the existing stories and EPIC.md; drafts one story for the new feature
2. Asks once, naming the new story and the EPIC.md update; writes story-003-[slug].md and appends one row to the Stories table

Assertions (return visit):

• story-001 and story-002 are unchanged
• The new story is numbered 003, on from the highest existing number
• EPIC.md keeps its two rows and every other section; exactly one row is appended

Fixture (an EPIC.md with no stories yet):

• As the first fixture, but /create-epics was run anyway, so production/epics/lantern-keeper/EPIC.md exists (scope from the brief, Stories "Not yet created") and the folder holds no story files

Expected behavior (an EPIC.md with no stories yet):

1. The existing EPIC.md is the epic: no new one is drafted from the brief
2. The write ask names the 2 stories and says update EPIC.md, not create

Assertions (an EPIC.md with no stories yet):

• Every section of the existing EPIC.md other than its Stories table is unchanged
• The Step 5 ask says update EPIC.md

---

Protocol Compliance

• All context (EPIC, GDD, ADRs, manifest layer rules, TR registry entries) loaded before drafting stories
• Story list shown in full before the "May I write" ask
• "May I write" asked once for the full story set, not once per story, naming every file it touches (stories, EPIC.md, production/epics/index.md when present)
• Blocked stories flagged before write approval — not discovered after writing
• TR-IDs reference the registry — requirement text is not embedded inline in story files
• Control manifest rules quoted per-story from the manifest, not invented
• Ends with next-step handoff: /story-readiness → /dev-story (/dev-story directly at minimal)

---

Coverage Notes

• At minimal, the "run /brainstorm first" stop when no brief exists and a named epic slug that does not exist (the minimal branch is taken instead of /create-epics) are not given fixtures.
• The full missing-ADR-file stop and the standard critical/non-critical ADR split are not separately tested.
• INADEQUATE (the story is revised with the user, or dropped and named) and a NOT ASSESSED gate answer are not given fixtures.
• Integration story test evidence (playtest doc alternative) follows the same approval pattern as Logic stories — not independently fixture-tested.
• Story sizing is pinned to fine in Cases 1, 3 and 5 so the story counts are determinate; coarse and balanced grouping, and prose depth per docs.density, are not fixture-locked.
• The existing-QA-plan substitution prompt (Use QA-plan specs / Use qa-lead specs / Skip) is not tested.