# Understanding the Lifecycle of a Story from Creation to Completion in Claude Code Game Studios

> Discover the six-phase story lifecycle in Claude Code Game Studios. Learn about documentation-first development, automated checks, and machine-readable tracking from creation to completion. Improve your workflow today.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: deep-dive
- Published: 2026-04-16

---

**The lifecycle of a story from creation to completion in Claude Code Game Studios follows a six-phase, gate-based pipeline that enforces documentation-first development, automated quality checks, and machine-readable sprint tracking.**

Every gameplay feature in the [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios) repository is treated as a **story** that progresses through a strictly defined lifecycle. This system ensures that code is never written before design and architecture decisions are documented, and that no story reaches completion without validating every acceptance criterion against the Game Design Document (GDD) and Architecture Decision Records (ADR).

## The Six Phases of the Story Lifecycle

### Phase 1: Epic and Story Creation

The lifecycle begins when designers group related functionality into an **epic** and decompose it into concrete, testable stories.

- **Slash command**: `/create-epics [layer]` followed by `/create-stories [epic-slug]`
- **Primary artifacts**:
  - `production/epics/<slug>/EPIC.md` — Contains the epic-level vision, scope, and links to its child stories.
  - `production/epics/<slug>/story-NNN-<slug>.md` — Individual story definitions with acceptance criteria.
- **Validation**: The skill writes the markdown skeleton and sets the **Status** field to `proposed`.

### Phase 2: Readiness Gate

Before any code is written, the story must pass a hard **readiness gate** that verifies documentation completeness.

- **Slash command**: `/story-readiness <path-to-story>`
- **Validation checks**:
  1. Design completeness — Linked GDD sections exist and are current.
  2. Architecture completeness — Relevant ADR decisions are recorded.
  3. Scope clarity — Acceptance criteria are unambiguous and testable.
  4. Definition of Done — Exit criteria are explicitly defined.
- **Output**: The agent annotates the story file with results and sets **Status** to `READY`, `NEEDS WORK`, or `BLOCKED`. See the concrete example in [[`docs/examples/session-story-lifecycle.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/examples/session-story-lifecycle.md)](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/examples/session-story-lifecycle.md).

### Phase 3: Development Kickoff

Once marked **READY**, the story is routed to the appropriate programmer agent (gameplay, engine, UI, etc.).

- **Slash command**: `/dev-story <path-to-story>`
- **Process**:
  - The agent reads the story, GDD, ADR, and control-manifest.
  - It proposes a file structure (e.g., `src/gameplay/movement/…`).
  - The developer approves the layout before any files are written.
- **Routing**: The command automatically routes to the correct specialist (e.g., `gameplay-programmer`) based on the story tags.

### Phase 4: Implementation and Iterative Checks

The programmer writes code, tests, and can invoke additional quality gates during the sprint.

- **Optional slash commands**:
  - `/code-review [path]` — Runs lint and static analysis.
  - `/scope-check` — Verifies no scope creep against the original story.
  - `/test-evidence-review` — Validates unit/integration test coverage.
- **Artifacts**: Updated source files under `src/…` and test files under `tests/…`.

### Phase 5: Completion Gate

The final gate verifies every acceptance criterion before updating sprint tracking.

- **Slash command**: `/story-done <path-to-story>`
- **Validation**:
  - Cross-checks the story against GDD, ADR, and control-manifest.
  - Runs auto-checks for hard-coded values.
  - Validates unit-test results.
  - Flags any **DEFERRED** criteria.
- **Artifacts**:
  - Story file updated with **Status: Complete** (or **Complete with Notes** if deferred items exist).
  - [`production/sprint-status.yaml`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/production/sprint-status.yaml) updated with machine-readable sprint snapshot.
- **Next-story surfacing**: The agent prints the next story that is `ready-for-dev`, maintaining sprint flow.

### Phase 6: Sprint Loop Continuation

The system automatically surfaces the next ready story, creating a continuous flow of work.

- **Mechanism**: The output of `/story-done` lists the next unblocked story.
- **Status transition**: The next story’s **Status** is already `ready-for-dev`, allowing immediate feeding to `/dev-story`.

## Key Files and Artifacts in the Story Lifecycle

The lifecycle is enforced through specific file conventions and machine-readable artifacts:

| File Path | Purpose |
|-----------|---------|
| `production/epics/<slug>/EPIC.md` | Epic-level vision, scope, and story links. |
| `production/epics/<slug>/story-*.md` | Individual story definitions with acceptance criteria and status. |
| [`production/sprint-status.yaml`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/production/sprint-status.yaml) | Machine-readable snapshot of current sprint health. |
| [`docs/examples/session-story-lifecycle.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/examples/session-story-lifecycle.md) | Concrete walkthrough of gates in action. |
| [`docs/examples/skill-flow-diagrams.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/examples/skill-flow-diagrams.md) | Visual pipeline diagram. |
| [`docs/WORKFLOW-GUIDE.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/WORKFLOW-GUIDE.md) | Narrative description of the full 7-phase workflow. |

## Practical Example: Running the Full Lifecycle

Below is a typical command sequence a developer runs in a Claude Code session, paired with the resulting story file structure:

```bash

# 1. Create an epic for the movement system

/create-epics core-mechanics

# → writes production/epics/movement/EPIC.md

# 2. Split the epic into concrete stories

/create-stories movement

# → creates production/epics/movement/story-001-movement.md

# 3. Run the readiness gate

/story-readiness production/epics/movement/story-001-movement.md

# → updates Status to READY or lists gaps

# 4. Begin implementation

/dev-story production/epics/movement/story-001-movement.md

# → proposes src/gameplay/movement/... structure

# 5. Final verification and closure

/story-done production/epics/movement/story-001-movement.md

# → Status: Complete, updates sprint-status.yaml, prints next story

```

A minimal story file generated by `/create-stories` contains:

```markdown

# STORY-MOV-001 – Implement CharacterBody2D movement with terrain modifiers

Status: proposed
Epic: movement
GDD: design/gdd/movement-system.md
ADR: docs/architecture/movement-adr-001.md
Acceptance Criteria:
- Walk speed correct on normal ground
- Run speed correct
- Roll invincibility frames work
- Terrain modifiers apply correctly
Control Manifest Version: 2026-03-10

```

## Summary

- The **lifecycle of a story from creation to completion** in Claude Code Game Studios consists of six rigid phases: Epic Creation, Readiness Gate, Development Kickoff, Implementation, Completion Gate, and Sprint Loop Continuation.
- **Documentation-first enforcement** requires every story to reference a GDD section and ADR before coding begins, verified by the `/story-readiness` gate.
- **Hard quality gates** (`/story-readiness`, `/code-review`, `/story-done`) prevent progression unless design completeness, architecture alignment, and acceptance criteria are validated.
- **Machine-readable tracking** via [`production/sprint-status.yaml`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/production/sprint-status.yaml) enables external CI and dashboard integration.
- **Automatic next-story surfacing** after `/story-done` maintains continuous sprint flow without manual triage.

## Frequently Asked Questions

### What triggers the transition from "proposed" to "ready-for-dev" status?

The transition occurs when the `/story-readiness` command validates four specific dimensions: design completeness (linked GDD sections exist), architecture completeness (relevant ADRs are recorded), scope clarity (acceptance criteria are unambiguous), and definition of done (exit criteria are explicit). Only when the skill reports **READY** does the status field update to `ready-for-dev`.

### How does the system prevent scope creep during implementation?

During the **Implementation & Iterative Checks** phase, developers can invoke the `/scope-check` command, which verifies that the current code changes align with the original story definition and have not expanded beyond the accepted acceptance criteria. Additionally, the `/code-review` and `/test-evidence-review` gates enforce that only planned functionality is committed.

### What happens if an acceptance criterion cannot be verified at completion time?

If a criterion depends on future integration work or external systems, the `/story-done` command allows the story to be closed with **Status: Complete with Notes**. The deferred criteria are explicitly flagged and logged for inclusion in the dependent story, ensuring traceability while preventing the current sprint from being blocked.

### Where does the system store the machine-readable sprint status?

The canonical machine-readable artifact is [`production/sprint-status.yaml`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/production/sprint-status.yaml), located in the repository root under the `production/` directory. This file is automatically updated by the `/story-done` skill and provides a structured snapshot of current story statuses (proposed, ready-for-dev, in-progress, complete) that external CI pipelines and dashboards can parse without scanning individual markdown files.