| 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 headerdesign/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:
- Group related criteria that require the same core implementation
- Each group = one story
- 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 normallyStatus: 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:
- Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
- Persist current draft to
.ags/project/reviews/.tmp/[type]-[slug]-iter[N]-draft.md.
- 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.
- Aggregator (
producer by default; skill-designated lead where the skill specifies one) merges findings from internal + external, drops nitpicks + below-floor.
- 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
- Read before presenting — load all inputs silently before showing story list
- Ask once — present all epic stories in one summary, not one at a time
- Warn on blocked stories — flag any story with Proposed ADR before writing
- Ask before writing — approval for full story set before writing files
- No invention — criteria from GDDs, notes from ADRs, rules from manifest
- 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.
