Claude-Code-Game-Studios/docs/examples/session-story-lifecycle.md

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

Starting State:

• design/gdd/movement-system.md — complete, all 8 sections
• docs/architecture/movement-adr-001.md — Status: Accepted
• production/sprints/sprint-03.md — lists STORY-MOV-001 in backlog
• production/stories/STORY-MOV-001.md — exists but not yet validated
• No implementation code yet

Session Duration: ~50 minutes Turns: 13 Outcome: Story validated ready, implemented, verified complete with /story-done

---

Phase 1: Story Readiness Check

Turn 1: User Runs Readiness Check

User:

/story-readiness production/stories/STORY-MOV-001.md

Turn 2: Agent Validates the Story

Agent (via /story-readiness):

Reading production/stories/STORY-MOV-001.md...

STORY-MOV-001: Implement CharacterBody2D movement with terrain modifiers

Running 4 validation checks:

1. Design Completeness

• GDD referenced: design/gdd/movement-system.md ✅
• GDD section coverage: Detailed Rules ✅, Formulas ✅, Edge Cases ✅
• TR-IDs embedded: TR-MOV-001 through TR-MOV-008 ✅

2. Architecture Completeness

• ADR referenced: docs/architecture/movement-adr-001.md ✅
• ADR status: Accepted ✅ (Would be BLOCKED if Proposed)
• Control manifest version in story: 2026-03-10 — current manifest is 2026-03-10 ✅

3. Scope Clarity

• Acceptance criteria: 9 items, all measurable ✅
• Out-of-scope items listed: swimming, climbing ✅
• Ambiguities found: 1
  • ⚠️ Story says "roll direction follows last input direction" but GDD says "roll in movement direction" — these conflict when player stops and immediately rolls. Clarify before pickup.

4. Definition of Done

• Tests required: unit tests for formula functions ✅
• Integration signal: on_stamina_event must fire correctly ✅

---

Verdict: NEEDS WORK

One ambiguity must be resolved before implementation starts. Would you like to resolve it now so I can mark the story as ready?

Turn 3: User Resolves the Ambiguity

User:

Roll uses last movement direction. If player is standing still, roll uses facing direction instead.

Turn 4: Agent Updates the Story

Agent:

Updating the story's Detailed Rules section:

Roll direction: last movement direction. If velocity is zero at roll input, roll uses current facing direction.

May I write this to production/stories/STORY-MOV-001.md and set Status to ready-for-dev?

User:

Yes

Agent writes update. Story status: ready-for-dev.

Verdict: READY Story is implementation-ready. Pick it up when you're ready to build.

---

Phase 2: Implementation

Turn 5: User Starts Implementation

User:

Let's implement STORY-MOV-001. I'm ready to start coding.

Turn 6: Agent Reads Story and ADR

Agent (gameplay-programmer):

Reading production/stories/STORY-MOV-001.md, design/gdd/movement-system.md, and docs/architecture/movement-adr-001.md...

Architecture (from ADR-001):

• MovementComponent.gd — attached to player scene, not a singleton
• Terrain modifier lookup via TerrainLayer.get_modifier(tile_position) helper
• Stamina events via signal (not direct call to StaminaSystem)

My proposed file structure:

src/gameplay/movement/
  movement_component.gd       # CharacterBody2D logic, state machine
  terrain_modifier_table.gd   # Const table: terrain_type -> {speed_mod, drain_mod}
tests/unit/
  test_movement_formulas.gd   # Unit tests for speed/drain calculations

May I proceed with this structure?

User:

Yes

Turn 7: Agent Implements and Shows Key Code

Agent:

Implementing movement_component.gd. Key excerpt for your review before I write the file:

class_name MovementComponent
extends Node

signal stamina_event(type: String, amount: float)

@export var base_walk_speed: float = 120.0
@export var run_multiplier: float = 1.7
@export var stamina_drain_walk: float = 2.0
@export var stamina_drain_run: float = 6.0
@export var stamina_cost_roll: float = 15.0

var _is_carrying_heavy: bool = false

func _physics_process(delta: float) -> void:
    var terrain_mod := _get_terrain_modifier()
    var effective_speed := _calculate_speed(terrain_mod)
    # ...

All values are @export — none hardcoded. Is this the direction you want?

User:

Looks good. Write it.

Turn 8–9: Agent Writes Files and Tests

Agent writes:

• src/gameplay/movement/movement_component.gd
• src/gameplay/movement/terrain_modifier_table.gd
• tests/unit/test_movement_formulas.gd

Agent:

Files written. Running available linting checks...

No errors. Tests file created with 6 unit tests covering:

• Walk speed formula (3 terrain types)
• Run speed formula
• Stamina drain calculation
• Roll stamina cost (with and without zero-velocity edge case)

Manual testing needed for: invincibility frames, slope blocking, terrain integration (requires running scene).

---

Phase 3: Story Completion

Turn 10: User Tests Manually and Runs /story-done

User:

I've tested it in the scene — everything works. /story-done production/stories/STORY-MOV-001.md

Turn 11: Agent Runs Completion Review

Agent (via /story-done):

Reading story, GDD, ADRs...

Phase 1: Story Located ✅ production/stories/STORY-MOV-001.md

Phase 2: Acceptance Criteria Verification

#	Criterion	Verification	Status
1	Walk speed correct on normal ground	Auto: formula unit tests pass	✅ AUTO
2	Run speed correct	Auto: formula unit tests pass	✅ AUTO
3	Run cancels at stamina 0	Manual: user confirmed	✅ MANUAL
4	Roll invincibility frames work	Manual: user confirmed	✅ MANUAL
5	Terrain modifiers apply correctly	Manual: user confirmed	✅ MANUAL
6	Heavy carry disables run	Auto: not yet testable (inventory not integrated)	⏳ DEFERRED
7	Stamina signals fire correctly	Auto: integration test pending	⏳ DEFERRED
8	No hardcoded values	Auto: grep for magic numbers → 0 found	✅ AUTO
9	Slopes >45° block movement	Manual: user confirmed	✅ MANUAL

Phase 3: GDD/ADR Deviations

Scanning implementation against TR-IDs...

• TR-MOV-001 through TR-MOV-007: ✅ Implemented as specified
• TR-MOV-008 (heavy carry signal): ⚠️ ADVISORY — deferred to inventory integration story. Not a deviation, just unverifiable now.

Phase 4: Manifest Staleness Check

Story control manifest version 2026-03-10 matches current manifest 2026-03-10. ✅

Phase 5: Code Review Prompt

Suggest running /code-review src/gameplay/movement/ before marking complete. Not blocking.

---

Completion Report: COMPLETE WITH NOTES

Story is complete. Two criteria deferred to inventory integration — log as deferred, not blocked.

May I update the story status to Status: Complete and add Completion Notes, and update production/sprint-status.yaml?

User:

Yes

Turn 12: Agent Closes the Story

Agent writes:

• Story Status: Complete + Completion Notes (deferred criteria noted)
• production/sprint-status.yaml — STORY-MOV-001 set to done

Agent:

STORY-MOV-001 closed.

Deferred criteria logged (will auto-surface in inventory integration story):

• Heavy carry disables run (requires inventory signal)
• Stamina signal integration test (requires stamina system)

Next ready story from sprint:

• STORY-MOV-002: Stamina system — this is the logical next story (downstream dep now unblocked)
• STORY-HUD-001: Movement HUD indicators — also unblocked

Run /story-readiness on whichever you pick up next.

---

What This Example Demonstrates

• Readiness gate catches real issues: the roll direction ambiguity would have caused a late implementation decision without /story-readiness
• ADR status is a hard gate: if movement-adr-001.md had been Proposed instead of Accepted, story would be BLOCKED and implementation wouldn't start
• Deferred criteria: not every acceptance criterion can be verified at story close — /story-done tracks deferred items rather than blocking completion
• TR-ID references: story stores TR-MOV-001 IDs, not quoted GDD text — avoids false deviation flags when GDD wording is cleaned up later
• sprint-status.yaml: single source of truth for sprint state, updated by /story-done and read by /sprint-status
• Manifest version check: ensures story's implementation guidance hasn't drifted from current architecture decisions