diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md index f36cb69..966f5fe 100644 --- a/.claude/docs/quick-start.md +++ b/.claude/docs/quick-start.md @@ -92,7 +92,9 @@ Ask yourself: "What department would handle this in a real studio?" | `/architecture-decision` | Creates an ADR | | `/architecture-review` | Validate all ADRs, dependency ordering, GDD traceability | | `/create-control-manifest` | Flat programmer rules sheet from Accepted ADRs | -| `/create-epics-stories` | Break GDDs + ADRs into implementable story files | +| `/create-epics` | Translate GDDs + ADRs into epics (one per architectural module) | +| `/create-stories` | Break a single epic into implementable story files | +| `/dev-story` | Read a story and implement it — routes to the correct programmer agent | | `/sprint-plan` | Creates or updates sprint plans | | `/sprint-status` | Quick 30-line sprint snapshot | | `/story-readiness` | Validate a story is implementation-ready before pickup | diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index a82cf46..502a5db 100644 --- a/.claude/docs/skills-reference.md +++ b/.claude/docs/skills-reference.md @@ -43,7 +43,9 @@ | Command | Purpose | |---------|---------| -| `/create-epics-stories` | Translate GDDs + ADRs + manifest into implementable story files | +| `/create-epics` | Translate GDDs + ADRs into epics — one per architectural module | +| `/create-stories` | Break a single epic into implementable story files | +| `/dev-story` | Read a story and implement it — routes to the correct programmer agent | | `/sprint-plan` | Generate or update a sprint plan; initializes sprint-status.yaml | | `/sprint-status` | Fast 30-line sprint snapshot (reads sprint-status.yaml) | | `/story-readiness` | Validate a story is implementation-ready before pickup (READY/NEEDS WORK/BLOCKED) | diff --git a/.claude/skills/adopt/SKILL.md b/.claude/skills/adopt/SKILL.md index 0d2352e..f7773c4 100644 --- a/.claude/skills/adopt/SKILL.md +++ b/.claude/skills/adopt/SKILL.md @@ -116,7 +116,7 @@ If `design/gdd/systems-index.md` exists: 1. **Parenthetical status values** — Grep for any Status cell containing parentheses: `"Needs Revision ("`, `"In Progress ("`, etc. - These break exact-string matching in `/gate-check`, `/create-epics-stories`, + These break exact-string matching in `/gate-check`, `/create-stories`, and `/architecture-review`. **BLOCKING.** 2. **Valid status values** — check that Status column values are only from: @@ -240,7 +240,7 @@ Stories audited: [N] Gap counts: BLOCKING: [N] — template skills will malfunction without these fixes - HIGH: [N] — unsafe to run /create-epics-stories or /story-readiness + HIGH: [N] — unsafe to run /create-stories or /story-readiness MEDIUM: [N] — quality degradation LOW: [N] — optional improvements @@ -350,7 +350,7 @@ If ADRs are missing Status fields: If GDDs are missing Acceptance Criteria: > "The most important GDD gap is missing Acceptance Criteria — without these, -> `/create-epics-stories` can't generate stories. Shall I start with +> `/create-stories` can't generate stories. Shall I start with > `design/gdd/[highest-priority-system].md` using `/design-system retrofit`?" Use `AskUserQuestion`: diff --git a/.claude/skills/content-audit/SKILL.md b/.claude/skills/content-audit/SKILL.md index 0c4ba82..1b9dd22 100644 --- a/.claude/skills/content-audit/SKILL.md +++ b/.claude/skills/content-audit/SKILL.md @@ -181,7 +181,7 @@ After writing the report, ask: > "Would you like to create backlog stories for any of the content gaps?" If yes: for each system the user selects, suggest a story title and point them -to `/create-epics-stories` or `/quick-design` depending on the size of the gap. +to `/create-stories [epic-slug]` or `/quick-design` depending on the size of the gap. ### --summary mode diff --git a/.claude/skills/create-control-manifest/SKILL.md b/.claude/skills/create-control-manifest/SKILL.md index a427378..003f532 100644 --- a/.claude/skills/create-control-manifest/SKILL.md +++ b/.claude/skills/create-control-manifest/SKILL.md @@ -235,7 +235,7 @@ These APIs are deprecated or unverified for [engine + version]: After writing the manifest: -- If epics/stories don't exist yet: "Run `/create-epics-stories` — programmers +- If epics/stories don't exist yet: "Run `/create-epics layer: foundation` then `/create-stories [epic-slug]` — programmers can now use this manifest when writing story implementation notes." - If this is a regeneration (manifest already existed): "Updated. Recommend notifying the team of changed rules — especially any new Forbidden entries." diff --git a/.claude/skills/create-epics-stories/SKILL.md b/.claude/skills/create-epics-stories/SKILL.md deleted file mode 100644 index fdfcc38..0000000 --- a/.claude/skills/create-epics-stories/SKILL.md +++ /dev/null @@ -1,407 +0,0 @@ ---- -name: create-epics-stories -description: "DEPRECATED — use /create-epics then /create-stories instead. This skill has been split into two focused skills: /create-epics (architect-level scoping, one per layer) and /create-stories (lead-programmer story breakdown, one per epic)." -argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]" -user-invocable: true -allowed-tools: Read, Glob, Grep, Write, Task -context: fork -agent: technical-director ---- - -# Create Epics & Stories — DEPRECATED - -> **This skill has been superseded.** Use the two-skill workflow instead: -> -> 1. `/create-epics layer: foundation` — define Foundation epics (technical-director) -> 2. `/create-stories [epic-slug]` — break each epic into stories (lead-programmer) -> 3. `/create-epics layer: core` — define Core epics -> 4. `/create-stories [epic-slug]` — break each Core epic into stories -> -> **Why the split?** Epics are architectural scope decisions (technical-director's domain). -> Stories are implementation decomposition (lead-programmer's domain). Mixing them in one -> skill caused the wrong agent to own the wrong decisions. -> -> **To implement a story** once stories exist, use `/dev-story [story-path]`. - ---- - -This skill translates the approved design and architecture into implementable -work units. Each **epic** maps to one architectural module. Each **story** is a -single implementable behaviour — small enough for one session, self-contained, -and fully traceable to the GDD requirement it satisfies and the ADR that governs -how to implement it. - -**Output:** `production/epics/[epic-slug]/` - -**When to run:** After `/architecture-review` passes and `/create-control-manifest` -has been run. All MVP-tier GDDs should be complete and reviewed. - ---- - -## 1. Parse Arguments - -**Modes:** -- `/create-epics-stories all` — process all systems in layer order -- `/create-epics-stories layer: foundation` — process Foundation layer only -- `/create-epics-stories [system-name]` — process one specific system -- No argument — ask the user which mode to use - -If no argument, use `AskUserQuestion`: -- "What would you like to create epics for?" - - Options: "All systems (Foundation → Presentation)", "Foundation layer only", - "Core layer only", "A specific system", "Feature + Presentation layers" - ---- - -## 2. Load All Inputs - -### Step 2a — L0: Summary Scan - -Before full-reading any documents, Grep all GDDs for their `## Summary` sections: - -``` -Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5 -``` - -For `all` mode: display a manifest of all Approved/Designed GDDs with their -summaries so the user can confirm scope before the full load begins. - -For `layer:` or `[system-name]` modes: filter to only the target GDDs based -on the Summary quick-reference line (Layer + Priority). Skip full-reading -GDDs outside the requested scope entirely. - -### Step 2b — L1/L2: Full Document Load - -Read everything for the in-scope systems before generating any output: - -### Design Documents -- `design/gdd/systems-index.md` — authoritative system list, layers, status -- In-scope GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status -- For each GDD, extract: - - System name and layer (from systems-index.md) - - All acceptance criteria (these become story acceptance criteria) - - All technical requirements (these trace to ADR coverage) - - Dependencies on other systems - -### Architecture Documents -- `docs/architecture/architecture.md` — module ownership and API boundaries -- All Accepted ADRs in `docs/architecture/adr-*.md` — read "GDD Requirements - Addressed", "Implementation Guidelines", "Engine Compatibility", and - "ADR Dependencies" sections -- `docs/architecture/control-manifest.md` if it exists — extract layer-specific - rules to embed in stories; also extract the `Manifest Version:` date from the - header block (this gets embedded in every story) - -### TR Registry -- `docs/architecture/tr-registry.yaml` if it exists — read all active entries, - indexed by `id`. Used to resolve TR-IDs for each GDD requirement. If the - registry does not exist, note it once; stories will use `TR-[system]-???` - placeholders with a warning. - -### Engine Reference -- `docs/engine-reference/[engine]/VERSION.md` — engine name + version + risk levels - -Report: "Loaded [N] GDDs, [M] ADRs, control manifest: [exists/missing], -manifest version: [date or N/A], TR registry: [N entries or missing], -engine: [name + version]." - ---- - -## 3. Determine Processing Order - -Process systems in dependency-safe layer order: -1. **Foundation** (no dependencies) -2. **Core** (depends on Foundation) -3. **Feature** (depends on Core) -4. **Presentation** (depends on Feature + Core) - -Within each layer, process systems in the order they appear in systems-index.md. - -For each system, determine the corresponding epic: -- Epic = one architectural module from `architecture.md` that implements this system -- If a system doesn't map cleanly to a single module, present options to the user - ---- - -## 4. For Each System: Define the Epic - -Present to the user before creating stories: - -``` -## Epic [N]: [System Name] - -**Layer**: [Foundation / Core / Feature / Presentation] -**GDD**: design/gdd/[filename].md -**Architecture Module**: [module name from architecture.md] -**GDD Requirements Traced by ADRs**: [list TR-IDs that have ADR coverage] -**Untraceable Requirements**: [list TR-IDs with no ADR — these need ADRs first] -**Governing ADRs**: [ADR-NNNN, ADR-MMMM, ...] -**Engine Risk**: [LOW/MEDIUM/HIGH — highest risk among governing ADRs] -``` - -Ask: "Shall I break Epic [N]: [name] into stories?" -- Options: "Yes, break it down", "Skip this epic", "Pause — I need to write ADRs first" - -If there are untraced requirements (no ADR covers them), warn: -> "⚠️ [N] requirements in [system] have no ADR. Stories for these cannot embed -> implementation guidance. Consider running `/architecture-decision` first, or -> I can create stories with a placeholder note to add ADR guidance later." - ---- - -## 5. Break Each Epic into Stories - -For each epic, decompose the GDD's acceptance criteria into stories: - -**Story sizing rules:** -- One story = one implementable behaviour from the GDD -- Small enough to complete in a single focused session (~2-4 hours of focused work) -- Self-contained — no story depends on in-progress work from another story in - the same epic (stories within an epic run sequentially; they can depend on - previous stories being DONE, not in-progress) - -**Story identification process:** -1. Read every acceptance criterion in the GDD -2. Group related criteria that require the same core implementation -3. Each group = one story -4. Order stories within the epic: foundation behaviour first, edge cases last - -**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 and note the secondary type. -The Story Type determines what evidence is required before `/story-done` can mark the story Complete. - -For each story, map: -- **GDD requirement**: Which specific acceptance criterion does this satisfy? -- **TR-ID**: Look up the matching entry in `tr-registry.yaml` by normalizing the - requirement text (lowercase, trimmed). Use the stable ID from the registry. - If no matching entry exists, note `TR-[system]-???` and warn the user to run - `/architecture-review` to register the ID before this story is assigned. -- **Governing ADR**: Which ADR tells the programmer how to implement this? - **Important — ADR status gate**: check the ADR's `Status:` field. - - If `Status: Accepted` → embed normally. - - If `Status: Proposed` → set story `Status: Blocked` and note: - `BLOCKED: ADR-NNNN is still Proposed — story cannot be safely implemented - until the ADR is Accepted. Run /architecture-decision to advance it.` - - Do not embed implementation guidance from a Proposed ADR. -- **Engine risk**: Inherited from the ADR's Knowledge Risk field -- **Control manifest rules**: Which layer rules apply? - ---- - -## 6. Generate Story Files - -For each story, produce a story file embedding full context: - -```markdown -# 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 — or "N/A" if manifest not yet created] - -## Context - -**GDD**: `design/gdd/[filename].md` -**Requirement**: `TR-[system]-NNN` -*(Requirement text is stored in `docs/architecture/tr-registry.yaml` — look up by ID 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**: [relevant text from the ADR's Engine Compatibility section, -especially Post-Cutoff APIs Used and Verification Required fields] - -**Control Manifest Rules (this layer)**: -- Required: [relevant required pattern from manifest] -- Forbidden: [relevant forbidden approach from manifest] -- Guardrail: [relevant performance guardrail] - ---- - -## Acceptance Criteria - -*From GDD `design/gdd/[filename].md`, scoped to this story:* - -- [ ] [criterion 1 — directly from GDD, scoped to this story's behaviour] -- [ ] [criterion 2] -- [ ] [performance criterion if applicable] - ---- - -## Implementation Notes - -*Derived from ADR-NNNN Implementation Guidelines:* - -[Specific guidance for the programmer. This should be the ADR's Implementation -Guidelines section, filtered to what's relevant for this story. Do not -paraphrase in ways that change meaning.] - ---- - -## Out of Scope - -*These are handled by neighbouring stories — do not implement here:* - -- [Story NNN+1]: [what it handles] -- [Other epic story]: [what it handles] - -This boundary prevents scope creep and keeps stories independently reviewable. - ---- - -## Test Evidence - -**Required evidence** (based on Story Type): -- 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: `production/qa/evidence/[story-slug]-evidence.md` + sign-off -- UI: `production/qa/evidence/[story-slug]-evidence.md` or interaction test -- Config/Data: smoke check pass (`production/qa/smoke-*.md`) - -**Status**: [ ] Not yet created - ---- - -## Dependencies - -- Depends on: [Story NNN-1 must be DONE, or "None"] -- Unlocks: [Story NNN+1, or "None"] -``` - ---- - -## 7. Lead-Programmer Architecture Review - -Before asking for approval, spawn a `lead-programmer` subagent via Task to review -the drafted stories for the current epic. Provide: -- The epic summary (layer, module, governing ADRs) -- All drafted story files for this epic -- The control manifest (if it exists) - -Ask the lead-programmer to check: -- **Story boundaries**: Are any stories too large (should be split) or too small (should be merged)? -- **ADR adherence**: Do the implementation notes in the stories faithfully reflect the ADR decisions? Flag any that drift or contradict. -- **Dependency ordering**: Is the story sequence safe? Can each story be implemented independently once its prerequisite is done? -- **Missing stories**: Are there any infrastructure concerns (interfaces, base classes, test hooks) that need their own story before others can proceed? -- **Control manifest compliance**: Do any stories ask for patterns explicitly forbidden in the manifest? - -The lead-programmer produces one of: -- **APPROVED** — proceed to user approval as-is -- **REVISIONS NEEDED** — list of specific changes; revise the affected stories before proceeding -- **BLOCKED** — a fundamental issue (missing ADR, wrong layer, circular dependency) that must be resolved first - -If REVISIONS NEEDED: make the changes and re-present the updated stories to the lead-programmer before requesting user approval. Do not ask the user to approve stories with known structural issues. - -## 8. Approval Before Writing - -For each epic, after stories pass lead-programmer review, present a summary: - -``` -Epic [N]: [name] -Stories: [N total] - Story 001: [title] — [1-line summary] - Story 002: [title] — [1-line summary] - ... -``` - -Ask: "May I write these [N] stories and the epic index to -`production/epics/[epic-slug]/`?" - ---- - -## 8. Write Output Files - -After approval, write: - -### Story files -`production/epics/[epic-slug]/story-[NNN]-[slug].md` - -### Epic index -`production/epics/[epic-slug]/EPIC.md`: - -```markdown -# Epic: [name] - -> **Layer**: [Foundation / Core / Feature / Presentation] -> **GDD**: design/gdd/[filename].md -> **Status**: Ready -> **Stories**: [N total] - -## Overview - -[1 paragraph describing what this epic implements] - -## Stories - -| # | Story | Status | ADR | -|---|-------|--------|-----| -| 001 | [title] | Ready | ADR-NNNN | -| 002 | [title] | Ready | ADR-MMMM | - -## Definition of Done - -This epic is complete when: -- All stories are implemented and reviewed -- All acceptance criteria from [GDD filename] are passing -- All Logic and Integration stories have passing test files in `tests/` -- All Visual/Feel and UI stories have evidence docs with sign-off in `production/qa/evidence/` -- No Foundation or Core layer stories have open blockers -``` - -### Master epics index -`production/epics/index.md` (create or update): - -```markdown -# Epics Index - -Last Updated: [date] -Engine: [name + version] - -| Epic | Layer | System | Stories | Status | -|------|-------|--------|---------|--------| -| [name] | Foundation | [system] | [N] | Ready | -``` - ---- - -## 9. Gate-Check Integration - -After writing all epics for the requested scope, remind the user: - -- **Foundation + Core complete**: Pre-Production → Production gate requires - Foundation and Core layer epics. Run `/gate-check production` to validate. -- **All layers complete**: Full epic coverage achieved. The sprint plan can now - reference real story file paths instead of GDD references. - ---- - -## Collaborative Protocol - -1. **Load silently** — read all inputs before presenting the first epic -2. **One epic at a time** — present each epic before creating stories; don't - batch all epics and ask once -3. **Warn on gaps** — flag untraced requirements before proceeding; let the user - decide whether to pause for ADRs or proceed with placeholders -4. **Ask before writing** — per-epic approval before writing story files -5. **No invention** — all acceptance criteria come from GDDs; all implementation - notes come from ADRs; all rules come from the control manifest. Never invent - requirements or rules that don't trace to a source document. -6. **Reference by TR-ID, not by quote** — embed the stable `TR-[system]-NNN` ID - in the story, not the GDD requirement text. The text lives in the registry and - is read fresh at review time. This prevents false deviation flags when GDD - wording is clarified after the story was written. -7. **Never embed Proposed ADRs** — if the governing ADR is Proposed, set the - story status to Blocked. Embedding implementation guidance from an unaccepted - ADR creates silent risk when the ADR changes. diff --git a/.claude/skills/skill-test/SKILL.md b/.claude/skills/skill-test/SKILL.md index 939e16e..1fb0f6d 100644 --- a/.claude/skills/skill-test/SKILL.md +++ b/.claude/skills/skill-test/SKILL.md @@ -232,7 +232,7 @@ For each skill: from catalog (or mark as "never" if not in catalog) - Assign priority: - `critical` — gate-check, design-review, story-readiness, story-done, review-all-gdds, architecture-review - - `high` — create-epics-stories, create-control-manifest, propagate-design-change, story-done + - `high` — create-epics, create-stories, dev-story, create-control-manifest, propagate-design-change, story-done - `medium` — team-* skills, sprint-plan, sprint-status - `low` — all others @@ -259,7 +259,9 @@ review-all-gdds | NO | never | — | never Top 5 Priority Gaps (no spec, critical/high priority): 1. /architecture-review — critical, no spec 2. /review-all-gdds — critical, no spec -3. /create-epics-stories — high, no spec +3. /create-epics — high, no spec +4. /create-stories — high, no spec +5. /dev-story — high, no spec 4. /propagate-design-change — high, no spec 5. /sprint-plan — medium, no spec diff --git a/.claude/skills/story-readiness/SKILL.md b/.claude/skills/story-readiness/SKILL.md index 006e624..2001ab6 100644 --- a/.claude/skills/story-readiness/SKILL.md +++ b/.claude/skills/story-readiness/SKILL.md @@ -264,11 +264,11 @@ draft the missing sections for your approval." If the user says yes for a specific story, draft only the missing sections in conversation. Do not use Write or Edit tools — the user (or -`/create-epics-stories`) handles writing. +`/create-stories`) handles writing. **Redirect rules:** - If a story file does not exist at all: "This story file is missing entirely. - Run `/create-epics-stories [system-name]` to generate it from the GDD and ADR." + Run `/create-epics [layer]` then `/create-stories [epic-slug]` to generate stories from the GDD and ADR." - If a story has no GDD reference and the work appears small: "This story has no GDD reference. If the change is small (under ~4 hours), run `/quick-design [description]` to create a Quick Design Spec, then reference diff --git a/README.md b/README.md index 53bf812..7b04622 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ The result: you still make every decision, but now you have a team that asks the | Category | Count | Description | |----------|-------|-------------| | **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production | -| **Skills** | 52 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics-stories`, `/story-done`, etc.) | +| **Skills** | 65 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) | | **Hooks** | 9 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection | | **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more | | **Templates** | 36 | Document templates for GDDs, UX specs, ADRs, sprint plans, HUD design, accessibility, and more | @@ -92,7 +92,7 @@ The template includes agent sets for all three major engines. Use the set that m ## Slash Commands -Type `/` in Claude Code to access all 52 skills: +Type `/` in Claude Code to access all 65 skills: **Onboarding & Navigation** `/start` `/help` `/project-stage-detect` `/setup-engine` `/adopt` @@ -107,7 +107,7 @@ Type `/` in Claude Code to access all 52 skills: `/create-architecture` `/architecture-decision` `/architecture-review` `/create-control-manifest` **Stories & Sprints** -`/create-epics-stories` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate` +`/create-epics` `/create-stories` `/dev-story` `/sprint-plan` `/sprint-status` `/story-readiness` `/story-done` `/estimate` **Reviews & Analysis** `/design-review` `/code-review` `/balance-check` `/asset-audit` `/content-audit` `/scope-check` `/perf-profile` `/tech-debt` `/gate-check` diff --git a/UPGRADING.md b/UPGRADING.md index ad82006..f621369 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -88,7 +88,7 @@ Best when: you didn't use git to set up the template (just downloaded a zip). | Category | Changes | |----------|---------| -| **New skills (15)** | `/ux-design`, `/ux-review`, `/help`, `/quick-design`, `/review-all-gdds`, `/story-readiness`, `/story-done`, `/sprint-status`, `/adopt`, `/create-architecture`, `/create-control-manifest`, `/create-epics-stories`, `/propagate-design-change`, `/content-audit`, `/architecture-review` | +| **New skills (17)** | `/ux-design`, `/ux-review`, `/help`, `/quick-design`, `/review-all-gdds`, `/story-readiness`, `/story-done`, `/sprint-status`, `/adopt`, `/create-architecture`, `/create-control-manifest`, `/create-epics`, `/create-stories`, `/dev-story`, `/propagate-design-change`, `/content-audit`, `/architecture-review` | | **New hook** | `log-agent-stop.sh` — completes agent audit trail (stop event to match start) | | **New templates (8)** | `ux-spec.md`, `hud-design.md`, `accessibility-requirements.md`, `interaction-pattern-library.md`, `player-journey.md`, `difficulty-curve.md`, and 2 adoption plan templates | | **New infrastructure** | `workflow-catalog.yaml` (7-phase pipeline, read by `/help`), `docs/architecture/tr-registry.yaml` (stable TR-IDs), `production/sprint-status.yaml` schema | @@ -119,7 +119,9 @@ Best when: you didn't use git to set up the template (just downloaded a zip). .claude/skills/adopt/SKILL.md .claude/skills/create-architecture/SKILL.md .claude/skills/create-control-manifest/SKILL.md -.claude/skills/create-epics-stories/SKILL.md +.claude/skills/create-epics/SKILL.md +.claude/skills/create-stories/SKILL.md +.claude/skills/dev-story/SKILL.md .claude/skills/propagate-design-change/SKILL.md .claude/skills/content-audit/SKILL.md .claude/skills/architecture-review/SKILL.md diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 48cad81..f35cc0e 100644 --- a/docs/WORKFLOW-GUIDE.md +++ b/docs/WORKFLOW-GUIDE.md @@ -126,7 +126,7 @@ production/ # Sprint plans, milestones, releases sprints/ milestones/ releases/ - stories/ # Story files (from /create-epics-stories) + epics/ # Epic and story files (from /create-epics + /create-stories) playtests/ # Playtest reports session-state/ # Ephemeral session state (gitignored) session-logs/ # Session audit trail (gitignored) @@ -586,18 +586,23 @@ that proves the core loop is fun. ### Phase 4 Pipeline ``` -/prototype --> /create-epics-stories --> /sprint-plan - | | | - v v v - Throwaway Story files in First sprint with - prototypes production/stories/ prioritized stories - in prototypes/ from GDDs + ADRs + production/sprints/ - control manifest sprint-*.md - | - v - /story-readiness - (validates each story - before pickup) +/prototype --> /create-epics --> /create-stories --> /sprint-plan + | | | | + v v v v + Throwaway Epic files in Story files in First sprint with + prototypes production/ production/ prioritized stories + in prototypes/ epics/*/EPIC.md epics/*/story-*.md production/sprints/ + (one per module) (one per behaviour) sprint-*.md + | + v + /story-readiness + (validates each story + before pickup) + | + v + /dev-story + (implements the story, + routes to right agent) | v Vertical Slice @@ -625,20 +630,27 @@ pollutes `src/`. hardcoded values OK, no tests required -- but a README with hypothesis and findings is mandatory. -### Step 4.2: Create Stories From Design Artifacts +### Step 4.2: Create Epics and Stories From Design Artifacts ``` -/create-epics-stories +/create-epics layer: foundation +/create-stories [epic-slug] # repeat for each epic +/create-epics layer: core +/create-stories [epic-slug] # repeat for each core epic ``` -This reads your GDDs, ADRs, and control manifest to generate implementable -story files in `production/stories/`. Each story embeds: +`/create-epics` reads your GDDs, ADRs, and architecture to define epic scope — +one epic per architectural module. Then `/create-stories` breaks each epic into +implementable story files in `production/epics/[slug]/`. Each story embeds: - GDD requirement references (TR-IDs, not quoted text -- stays fresh) - ADR references (only from Accepted ADRs; Proposed ADRs cause `Status: Blocked`) - Control manifest version date (for staleness detection) - Engine-specific implementation notes - Acceptance criteria from the GDD +Once stories exist, run `/dev-story [story-path]` to implement one — it routes +automatically to the correct programmer agent. + ### Step 4.3: Validate Stories Before Pickup ``` @@ -1395,7 +1407,9 @@ conflicts go to `producer`. | Command | Purpose | Phase | |---------|---------|-------| -| `/create-epics-stories` | Break GDDs + ADRs into story files | 4 | +| `/create-epics` | Translate GDDs + ADRs into epics (one per module) | 4 | +| `/create-stories` | Break a single epic into story files | 4 | +| `/dev-story` | Implement a story — routes to the correct programmer agent | 5 | | `/sprint-plan` | Create or manage sprint plans | 4-5 | | `/sprint-status` | Quick 30-line sprint snapshot | 5 | | `/story-readiness` | Validate story is implementation-ready | 4-5 | @@ -1482,7 +1496,7 @@ conflicts go to `producer`. 5. /architecture-review 6. /create-control-manifest 7. /gate-check technical-setup -8. /create-epics-stories (break GDDs into stories) +8. /create-epics layer: foundation + /create-stories [slug] (define epics, break into stories) 9. /sprint-plan new 10. /story-readiness -> implement -> /story-done (story lifecycle) ``` diff --git a/docs/architecture/tr-registry.yaml b/docs/architecture/tr-registry.yaml index 9793508..92cab0e 100644 --- a/docs/architecture/tr-registry.yaml +++ b/docs/architecture/tr-registry.yaml @@ -14,7 +14,7 @@ # the new TR-ID(s). # # WRITTEN BY: /architecture-review (appends new entries, never overwrites) -# READ BY: /create-epics-stories (embed IDs in stories) +# READ BY: /create-stories (embed IDs in stories) # /story-done (look up current requirement text at review time) # /story-readiness (validate TR-ID exists and is active) # diff --git a/docs/examples/session-adopt-brownfield.md b/docs/examples/session-adopt-brownfield.md index 64bf0ee..143f9da 100644 --- a/docs/examples/session-adopt-brownfield.md +++ b/docs/examples/session-adopt-brownfield.md @@ -61,7 +61,7 @@ > > | Gap | Severity | Reason | > |-----|----------|--------| -> | No systems index | BLOCKING | `/design-system`, `/create-epics-stories`, `/gate-check` all require it | +> | No systems index | BLOCKING | `/design-system`, `/create-stories`, `/gate-check` all require it | > | GDD files not in template format | HIGH | Skills cannot reference TR-IDs from malformed GDDs | > | No architecture docs | HIGH | Cannot run `/architecture-review` or `/create-control-manifest` | > | No production tracking | MEDIUM | Sprint and story skills won't work, but not needed until production phase | diff --git a/docs/examples/session-story-lifecycle.md b/docs/examples/session-story-lifecycle.md index 9c2d653..0df3df5 100644 --- a/docs/examples/session-story-lifecycle.md +++ b/docs/examples/session-story-lifecycle.md @@ -1,6 +1,6 @@ # Example Session: Full Story Lifecycle — /story-readiness → Implement → /story-done -**Context:** Solo indie dev, mid-production sprint. The movement system GDD and architecture are complete. A story for movement's core implementation has been generated by `/create-epics-stories`. +**Context:** Solo indie dev, mid-production sprint. The movement system GDD and architecture are complete. A story for movement's core implementation has been generated by `/create-stories`. **Starting State:** - `design/gdd/movement-system.md` — complete, all 8 sections diff --git a/docs/examples/skill-flow-diagrams.md b/docs/examples/skill-flow-diagrams.md index 172a962..b5c1dda 100644 --- a/docs/examples/skill-flow-diagrams.md +++ b/docs/examples/skill-flow-diagrams.md @@ -39,7 +39,8 @@ PHASE 3: TECHNICAL SETUP PHASE 4: PRE-PRODUCTION /ux-design [screen/hud/patterns] ────────────────────────────► design/ux/*.md /ux-review ──────────────────────────────────────────────────► UX specs approved - /create-epics-stories ───────────────────────────────────────► production/stories/STORY-*.md + /create-epics [layer] ───────────────────────────────────────► production/epics/*/EPIC.md + /create-stories [epic-slug] ─────────────────────────────────► production/epics/*/story-*.md /prototype [core-mechanic] ──────────────────────────────────► prototypes/[name]/ /playtest-report ────────────────────────────────────────────► tests/playtest/vertical-slice.md /sprint-plan new ────────────────────────────────────────────► production/sprints/sprint-01.md @@ -117,10 +118,15 @@ upstream GDDs (input, if any) How a story gets from backlog to closed: ``` -/create-epics-stories +/create-epics [layer: foundation] │ - └── Output: production/stories/STORY-[SYS]-NNN.md - (Status: backlog or blocked if ADR is Proposed) + └── Output: production/epics/[slug]/EPIC.md + │ + ▼ + /create-stories [epic-slug] + │ + └── Output: production/epics/[slug]/story-NNN-[slug].md + (Status: Ready or Blocked if ADR is Proposed) │ ▼ /story-readiness [story] diff --git a/tests/skills/catalog.yaml b/tests/skills/catalog.yaml index 7c82b4e..831f7c8 100644 --- a/tests/skills/catalog.yaml +++ b/tests/skills/catalog.yaml @@ -51,7 +51,21 @@ skills: priority: critical # High — pipeline-critical skills - - name: create-epics-stories + - name: create-epics + spec: "" + last_static: "" + last_static_result: "" + last_spec: "" + last_spec_result: "" + + - name: create-stories + spec: "" + last_static: "" + last_static_result: "" + last_spec: "" + last_spec_result: "" + + - name: dev-story spec: "" last_static: "" last_static_result: ""