How to Create and Manage Epics and Stories in the Sprint Pipeline

Use slash-commands /create-epics and /create-stories to automatically generate traceable epics and decompose them into implementation-ready stories, then validate readiness with /story-readiness and plan sprints using /sprint-plan.

The Claude Code Game Studios repository (Donchitos/Claude-Code-Game-Studios) provides a structured sprint pipeline that transforms high-level design documents into concrete development tasks. This workflow ensures every architectural decision is traceable from initial concept through implementation, using specialized slash-commands to manage epics and stories across the production lifecycle.

Understanding the Epic and Story Workflow

From Design to Implementation

The sprint pipeline follows a strict progression from user experience design to active development. According to the workflow guide at docs/WORKFLOW-GUIDE.md, the standard sequence is:

/ux-design → /prototype → /create-epics → /create-stories → /sprint-plan

Each slash-command generates specific artifacts that feed into the next phase, ensuring that no implementation work begins without proper architectural context and traceability identifiers.

Creating Epics with /create-epics

Epic Structure and Content

After UX specifications and architecture decision records (ADRs) are approved, run /create-epics to generate epic-level work items. This command processes the approved design artifacts and creates a dedicated directory for each architectural module at production/epics/[slug]/EPIC.md.

Each generated epic file contains:

• The architectural layer (e.g., foundation, combat, UI)
• Links to governing GDD (Game Design Document) sections
• Relevant ADRs and engine-risk assessments
• A placeholder for linked stories

The skill also maintains a master index at production/epics/index.md and automatically reminds you to execute /create-stories for every generated epic to ensure complete decomposition.

Producer Gate Review

The epic creation process includes a Producer Gate that validates the completeness of design artifacts before generating the epic file. This gate checks that all prerequisite UX and architecture documents are present and approved, preventing premature epic creation that lacks necessary context.

Decomposing Epics into Stories with /create-stories

Story Classification and Traceability

Once epics exist, use /create-stories [epic-slug] to decompose architectural modules into implementable stories. This command, defined in .claude/skills/create-stories/SKILL.md, reads the epic file, associated GDD sections, governing ADRs, and the control manifest to generate comprehensive story drafts.

The skill automatically validates that every referenced ADR exists in the repository, ensuring architectural compliance. Each story is classified by type for routing purposes:

• Logic – Core game mechanics and algorithms
• Integration – System interconnections and API implementations
• Visual/Feel – Art, animation, and player feedback
• UI – Interface components and user interactions
• Config/Data – Balancing values, content tables, and settings

Every generated story includes a TR-ID (Traceability Requirement ID), references to governing ADRs, detailed acceptance criteria, and test evidence requirements.

QA-Lead Gate for Story Readiness

Before files are written to disk, the optional QL-STORY-READY gate can be triggered to ensure acceptance criteria are testable and unambiguous. This quality checkpoint verifies that stories meet the definition of ready before they enter the sprint backlog, reducing rework during implementation.

Managing the Sprint Pipeline

Verifying Story Readiness with /story-readiness

Before beginning implementation, run /story-readiness <story-path> to verify design completeness, ADR status, and manifest version compliance. This command validates that all prerequisite documentation is current and that the story meets the team's definition of ready. A "Ready" verdict authorizes the transition from planning to active development.

Starting Development with /dev-story

Once a story passes readiness checks, execute /dev-story to route the work to the appropriate programmer agent based on the story type (Logic, Integration, Visual/Feel, UI, or Config/Data). This command ensures that implementation tasks are automatically assigned to agents with the correct specialization, maintaining efficient workflow distribution.

Planning Sprints with /sprint-plan

When every epic in the current architectural layer has at least one associated story, run /sprint-plan to generate the sprint backlog. This command creates two essential files:

• production/sprints/sprint-XX.md – Human-readable sprint backlog with story order, dependencies, and estimates
• production/sprint-status.yaml – Machine-readable status file for automated tracking

The sprint plan aggregates story dependencies and effort estimates, enabling the team to start execution with full visibility into the work sequence.

Enforcing Quality Gates with /gate-check

Throughout the pipeline, /gate-check enforces that required artifacts exist before advancing between phases (e.g., pre-production to production). This command surfaces missing stories or incomplete epics as blocking concerns that must be resolved before the workflow can proceed, ensuring rigorous quality control at every transition.

Summary

• Use /create-epics after UX and architecture approval to generate traceable epics at production/epics/[slug]/EPIC.md, each representing one architectural module with embedded GDD and ADR references.
• Run /create-stories [epic-slug] to decompose epics into classified stories (Logic, Integration, Visual/Feel, UI, Config/Data) with TR-IDs and acceptance criteria, passing through the optional QA-lead readiness gate.
• Validate with /story-readiness before implementation, then route to specialized agents using /dev-story based on story classification.
• Plan sprints with /sprint-plan after all epics in the current layer have stories, generating production/sprints/sprint-XX.md and production/sprint-status.yaml.
• Enforce transitions with /gate-check to ensure no phase advances without complete artifacts.

Frequently Asked Questions

What is the difference between an epic and a story in the Claude Code Game Studios pipeline?

An epic represents a high-level architectural module (such as combat or inventory systems) and is stored at production/epics/[slug]/EPIC.md, containing links to GDD sections, ADRs, and engine-risk assessments. A story is a concrete, implementable work item generated by /create-stories that includes specific acceptance criteria, TR-IDs for traceability, and classification by type (Logic, Integration, Visual/Feel, UI, or Config/Data).

How does the QA-lead gate ensure story quality before implementation?

The QA-lead gate (QL-STORY-READY) automatically triggers during the /create-stories execution to verify that acceptance criteria are testable, unambiguous, and complete before any story files are written to disk. This prevents defective stories from entering the sprint backlog and reduces rework during the implementation phase by enforcing the definition of ready at the point of creation.

What files are generated when planning a sprint with /sprint-plan?

Executing /sprint-plan generates two critical artifacts: production/sprints/sprint-XX.md, which contains the human-readable sprint backlog including story order, dependencies, and effort estimates; and production/sprint-status.yaml, which provides a machine-readable status file used for automated tracking and CI/CD integration. These files collectively enable the team to begin execution with full visibility into the work sequence and dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}