ags-create-stories

name	ags-create-stories
description	Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /ags-create-epics for each epic.
argument-hint	[epic-slug | epic-path]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Task, AskUserQuestion
agent	lead-programmer

Language: Talk to user in language from .ags/project/user-interaction.md. Fall back to English if file missing. Files on disk always English per .ags/rules/user-interaction.md.

Create Stories

Single implementable behaviour — small enough for one focused session, self-contained, traceable to a GDD requirement and ADR. Developers pick up stories. Architects define epics.

Run per epic, not per layer. Foundation epics first, then Core — matching dependency order.

Output: .ags/project/epics/[epic-slug]/story-NNN-[slug].md files

Previous step: /ags-create-epics [system] Next step after stories exist: /ags-story-readiness [story-path] then /ags-dev-story [story-path]

---

1. Parse Argument

• /ags-create-stories [epic-slug] — e.g. /ags-create-stories combat
• /ags-create-stories .ags/project/epics/combat/EPIC.md — full path also accepted
• No argument — ask: "Which epic would you like to break into stories?" Glob .ags/project/epics/*/EPIC.md and list available epics with their status.

---

2. Load Everything for This Epic

Read in full:

• .ags/project/epics/[epic-slug]/EPIC.md — epic overview, governing ADRs, GDD requirements table
• The epic's GDD (design/gdd/[filename].md) — read all 8 sections, especially Acceptance Criteria, Formulas, and Edge Cases
• All governing ADRs listed in the epic — read the Decision, Implementation Guidelines, Engine Compatibility, and Engine Notes sections
• design/architecture/control-manifest.md — extract rules for this epic's layer; note the Manifest Version date from the header
• design/architecture/tr-registry.yaml — load all TR-IDs for this system

ADR existence validation: After reading the governing ADRs list from the epic, confirm each ADR file exists on disk. If any ADR file cannot be found, stop immediately before decomposing any story:

"Epic references [ADR-NNNN: title] but design/architecture/[adr-file].md was not found. Check the filename in the epic's Governing ADRs list, or run /ags-architecture-decision to create it. Cannot create stories until all referenced ADR files are present."

Do not proceed to Step 3 until all referenced ADR files are confirmed present.

Report: "Loaded epic [name], GDD [filename], [N] governing ADRs (all confirmed present), control manifest v[date]."

---

3. Classify Stories by Type

Story Type Classification — assign each story a type based on its acceptance criteria:

Story Type	Assign when criteria reference...
Logic	Formulas, numerical thresholds, state transitions, AI decisions, calculations
Integration	Two or more systems interacting, signals crossing boundaries, save/load round-trips
Visual/Feel	Animation behaviour, VFX, "feels responsive", timing, screen shake, audio sync
UI	Menus, HUD elements, buttons, screens, dialogue boxes, tooltips
Config/Data	Balance tuning values, data file changes only — no new code logic

Mixed stories: assign the type that carries the highest implementation risk. The type determines what test evidence is required before /ags-story-done can close the story.

---

4. Decompose the GDD into Stories

For each GDD acceptance criterion:

1. Group related criteria that require the same core implementation
2. Each group = one story
3. Order stories: foundational behaviour first, edge cases last, UI last

Story sizing rule: one story = one focused session (~2-4 hours). If a group of criteria would take longer, split into two stories.

Design Principles Check (per .ags/rules/design-principles.md):

• §1 YAGNI — every story must trace to a GDD acceptance criterion. Do not create stories for speculative scaffolding, "future-proofing", or systems with no current playtest need. Cut stories that do not satisfy a current acceptance criterion.
• §6 Fail Fast — for stories that load content / config / data, acceptance criteria must include validation behaviour on malformed / missing input (loud failure, not silent fallback).

For each story, determine:

• GDD requirement: which acceptance criterion(ia) does this satisfy?
• TR-ID: look up in tr-registry.yaml. Use the stable ID. If no match, use TR-[system]-??? and warn.
• Governing ADR: which ADR governs how to implement this?
  • Status: Accepted → embed normally
  • Status: Proposed → set story Status: Blocked with note: "BLOCKED: ADR-NNNN is Proposed — run /ags-architecture-decision to advance it"
• Story Type: from Step 3 classification
• Engine risk: from the ADR's Knowledge Risk field

---

4b. Internal Review Loop (QA Lead Story Readiness)

After decomposing all stories (Step 4 complete) but before presenting them for write approval, spawn qa-lead via Task using gate QL-STORY-READY (.ags/rules/director-gates.md).

Pass: the full story list with acceptance criteria, story types, and TR-IDs; the epic's GDD acceptance criteria for reference.

Loop exit condition. Single iteration where every story reaches ADEQUATE (no GAPS / INADEQUATE / critical / high / medium findings). Non-clean → user revises affected stories' acceptance criteria, re-spawn QL-STORY-READY. No iteration cap.

Record iteration count.

After ADEQUATE: for every Logic and Integration story, ask the qa-lead to produce concrete test case specifications — one per acceptance criterion — in this format:

Test: [criterion text]
  Given: [precondition]
  When: [action]
  Then: [expected result / assertion]
  Edge cases: [boundary values or failure states to test]

For Visual/Feel and UI stories, produce manual verification steps instead:

Manual check: [criterion text]
  Setup: [how to reach the state]
  Verify: [what to look for]
  Pass condition: [unambiguous pass description]

These test case specs are embedded directly into each story's ## QA Test Cases section. The developer implements against these cases. The programmer does not write tests from scratch — QA has already defined what "done" looks like.

---

Combined Review Loop (parallel external Codex)

Per .ags/rules/review-workflow.md. The internal review section above runs in parallel with external Codex inside one loop. Each iteration:

1. Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
2. Persist current draft to .ags/project/reviews/.tmp/[type]-[slug]-iter[N]-draft.md.
3. Spawn in one message, in parallel (multiple Task calls + one Bash invocation):
   • All internal reviewer Tasks listed above.
   • /ags-external-review [type] [draft-path] --embedded-parallel --iteration [N] --min-severity [floor] — Codex unavailable returns skipped: codex-unavailable; aggregator logs skip in decisions-log and continues with internal pool only.
4. Aggregator (producer by default; skill-designated lead where the skill specifies one) merges findings from internal + external, drops nitpicks + below-floor.
5. Loop exit: filtered set empty → proceed to write approval. Non-empty → surface aggregated kept findings, user revises draft, N++, repeat.

No iteration cap. No user-confirm gate before external — it runs every iteration automatically. Record final iteration count for the decisions-log entry written at skill completion.

---

5. Present Stories for Review

Before writing any files, present the full story list:

## Stories for Epic: [name]

Story 001: [title] — Logic — ADR-NNNN
  Covers: TR-[system]-001 ([1-line summary of requirement])
  Test required: tests/unit/[system]/[slug]_test.[ext]

Story 002: [title] — Integration — ADR-MMMM
  Covers: TR-[system]-002, TR-[system]-003
  Test required: tests/integration/[system]/[slug]_test.[ext]

Story 003: [title] — Visual/Feel — ADR-NNNN
  Covers: TR-[system]-004
  Evidence required: .ags/project/qa/evidence/[slug]-evidence.md

[N stories total: N Logic, N Integration, N Visual/Feel, N UI, N Config/Data]

Use AskUserQuestion:

• Prompt: "May I write these [N] stories to .ags/project/epics/[epic-slug]/?"
• Options: [A] Yes — write all [N] stories / [B] Not yet — I want to review or adjust first

---

6. Write Story Files

For each story, write .ags/project/epics/[epic-slug]/story-[NNN]-[slug].md:

# Story [NNN]: [title]

> **Epic**: [epic name]
> **Status**: Ready
> **Layer**: [Foundation / Core / Feature / Presentation]
> **Type**: [Logic | Integration | Visual/Feel | UI | Config/Data]
> **Manifest Version**: [date from control-manifest.md header]

## Context

**GDD**: `design/gdd/[filename].md`
**Requirement**: `TR-[system]-NNN`
*(Requirement text lives in `design/architecture/tr-registry.yaml` — read fresh at review time)*

**ADR Governing Implementation**: [ADR-NNNN: title]
**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]

**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
**Engine Notes**: [from ADR Engine Compatibility section — post-cutoff APIs, verification required]

**Control Manifest Rules (this layer)**:
- Required: [relevant required pattern]
- Forbidden: [relevant forbidden pattern]
- Guardrail: [relevant performance guardrail]

---

## Acceptance Criteria

*From GDD `design/gdd/[filename].md`, scoped to this story:*

- [ ] [criterion 1 — directly from GDD]
- [ ] [criterion 2]
- [ ] [performance criterion if applicable]

---

## Implementation Notes

*Derived from ADR-NNNN Implementation Guidelines:*

[Specific, actionable guidance from the ADR. Do not paraphrase in ways that
change meaning. This is what the programmer reads instead of the ADR.]

---

## Out of Scope

*Handled by neighbouring stories — do not implement here:*

- [Story NNN+1]: [what it handles]

---

## QA Test Cases

*Written by qa-lead at story creation. The developer implements against these — do not invent new test cases during implementation.*

**[For Logic / Integration stories — automated test specs]:**

- **AC-1**: [criterion text]
  - Given: [precondition]
  - When: [action]
  - Then: [assertion]
  - Edge cases: [boundary values / failure states]

**[For Visual/Feel / UI stories — manual verification steps]:**

- **AC-1**: [criterion text]
  - Setup: [how to reach the state]
  - Verify: [what to look for]
  - Pass condition: [unambiguous pass description]

---

## Test Evidence

**Story Type**: [type]
**Required evidence**:
- Logic: `tests/unit/[system]/[story-slug]_test.[ext]` — must exist and pass
- Integration: `tests/integration/[system]/[story-slug]_test.[ext]` OR playtest doc
- Visual/Feel: `.ags/project/qa/evidence/[story-slug]-evidence.md` + sign-off
- UI: `.ags/project/qa/evidence/[story-slug]-evidence.md` or interaction test
- Config/Data: smoke check pass (`.ags/project/qa/smoke-*.md`)

**Status**: [ ] Not yet created

---

## Dependencies

- Depends on: [Story NNN-1 must be DONE, or "None"]
- Unlocks: [Story NNN+1, or "None"]

Also update .ags/project/epics/[epic-slug]/EPIC.md

Replace the "Stories: Not yet created" line with a populated table:

## Stories

| # | Story | Type | Status | ADR |
|---|-------|------|--------|-----|
| 001 | [title] | Logic | Ready | ADR-NNNN |
| 002 | [title] | Integration | Ready | ADR-MMMM |

---

7. After Writing

Use AskUserQuestion to close with context-aware next steps:

Check:

• Are there other epics in .ags/project/epics/ without stories yet? List them.
• Is this the last epic? If so, include /ags-create-epics as an option.

Widget:

• Prompt: "[N] stories written to .ags/project/epics/[epic-slug]/. What next?"
• Options (include all that apply):
  • [A] Start implementing — run /ags-story-readiness [first-story-path] (Recommended)
  • [B] Create stories for [next-epic-slug] — run /ags-create-stories [slug] (only if other epics have no stories yet)
  • [C] Plan the sprint — run /ags-create-epics (only if all epics have stories)
  • [D] Stop here for this session

Note in output: "Work through stories in order — each story's Depends on: field tells you what must be DONE before you can start it."

---

Collaborative Protocol

1. Read before presenting — load all inputs silently before showing story list
2. Ask once — present all epic stories in one summary, not one at a time
3. Warn on blocked stories — flag any story with Proposed ADR before writing
4. Ask before writing — approval for full story set before writing files
5. No invention — criteria from GDDs, notes from ADRs, rules from manifest
6. Never start implementation — stops at story file level

After writing (or declining):

• Verdict: COMPLETE — [N] stories written to .ags/project/epics/[epic-slug]/. Run /ags-story-readiness → /ags-dev-story to begin implementation.
• Verdict: BLOCKED — user declined. No story files written.