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

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 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).

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 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	Machine-readable snapshot of current sprint health.
docs/examples/session-story-lifecycle.md	Concrete walkthrough of gates in action.
docs/examples/skill-flow-diagrams.md	Visual pipeline diagram.
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:

# 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:

# 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 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, 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.

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