Claude-Code-Game-Studios/docs/examples/session-design-system-skill.md

Example Session: Using /design-system to Author a GDD

Context: Solo indie dev, week 3 of project. /map-systems already ran and produced design/gdd/systems-index.md. The movement system is listed as MVP tier, Foundation priority.

Starting State:

• design/gdd/game-concept.md exists (survival-crafting game, 2D, Godot 4.6)
• design/gdd/systems-index.md exists (15 systems identified, movement is first in design order)
• No per-system GDDs written yet
• No upstream dependencies for movement (it is the foundation)

Session Duration: ~60 minutes Turns: 14 Outcome: Complete design/gdd/movement-system.md with all 8 required sections written to file, ready for /design-review

---

Turn 1: User Invokes the Skill

User:

/design-system movement

Turn 2: Agent Loads Context and Presents the Plan

Agent (game-designer, via /design-system):

I'm loading context before we start:

• Read design/gdd/game-concept.md — survival-crafting, exploration-heavy, lone survivor stranded on alien planet
• Read design/gdd/systems-index.md — movement is Foundation / MVP, no upstream deps, downstream: combat, exploration, stamina
• No prior GDD found for movement — starting fresh

Technical Feasibility Pre-Check:

Domain	Signal
Engine	Godot 4.6 — CharacterBody2D with move_and_slide() is well-supported
Physics	Jolt is now the default in 4.6 — 2D movement unaffected, but note for future 3D work
Downstream risk	Stamina system listed as downstream dep — movement must expose a stamina callback hook

The GDD template has 8 required sections. We'll go one at a time: Overview → Player Fantasy → Detailed Rules → Formulas → Edge Cases → Dependencies → Tuning Knobs → Acceptance Criteria

I'll show you a draft of each section, you approve or revise, then I write it to the file before we move on.

Creating the file skeleton now with empty section headers — may I write design/gdd/movement-system.md with placeholders?

User:

Yes

Agent writes design/gdd/movement-system.md with 8 empty section headers.

---

Turn 3: Section 1 — Overview

Agent:

Section 1 draft — Overview:

The movement system is the player's primary interface with the world. It governs how the lone survivor walks, runs, rolls, and traverses alien terrain. Movement is physically grounded — the planet has heavier-than-Earth gravity, and the survivor is physically exhausted — but remains responsive enough to stay out of the player's way. The system feeds directly into exploration pacing, combat positioning, and the stamina system.

Does this capture what you want?

User:

Good but add something about the terrain — surfaces slow you down or have friction modifiers.

Agent:

Revised:

The movement system is the player's primary interface with the world. It governs how the lone survivor walks, runs, rolls, and traverses alien terrain. Movement is physically grounded — the planet has heavier-than-Earth gravity, and the survivor is physically exhausted — but remains responsive enough to stay out of the player's way. Terrain surfaces apply friction and speed modifiers (slick rock, sand, shallow water) that make navigation a meaningful skill. The system feeds directly into exploration pacing, combat positioning, and the stamina system.

May I write this to Section 1 in the file?

User:

Yes

Agent writes Section 1 to file.

---

Turn 4: Section 2 — Player Fantasy

Agent:

Section 2 draft — Player Fantasy:

The player should feel like a tired but capable survivor — not a superhero, not helpless. Early game movement is deliberate and taxing; the player earns fluency over time. When traversing alien terrain, the goal is careful navigation with moments of urgency (running from threats, leaping a gap). The fantasy is "I know this terrain" — every surface type becomes readable and manageable as the player internalizes the friction system.

Approve, revise, or change direction?

User:

Love it. Write it.

Agent writes Section 2 to file.

---

Turn 5: Section 3 — Detailed Rules

Agent:

Section 3 draft — Detailed Rules:

Base States:

• Walk (default): Full directional control, moderate speed, low stamina drain
• Run (hold Shift): Faster, medium stamina drain per second — cancels automatically when stamina hits 0
• Roll/Dodge (tap Space): Quick burst in movement direction, brief invincibility frames, high stamina cost (flat)
• Idle: Zero movement input, stamina regenerates at full rate

Terrain Modifiers:

• Normal ground: 1.0x speed multiplier, standard friction
• Sand/loose soil: 0.8x speed, 1.1x stamina drain (harder to move)
• Slick rock (wet): 1.1x speed, reduced stop friction (player overshoots)
• Shallow water (ankle-deep): 0.7x speed, no friction modifier
• Deep water: movement disabled, replaced by swimming (separate system, out of scope)

Collision:

• CharacterBody2D + move_and_slide(); wall slide enabled
• Slopes up to 45° walked normally; >45° blocked
• One-way platforms supported (drop-through with Down + Jump)

A lot here — want me to trim or expand anything?

User:

Add that running is disabled when carrying a heavy object (like a large resource chunk).

Agent:

Added to Run rule:

• Run (hold Shift): Faster, medium stamina drain per second — cancels automatically when stamina hits 0. Disabled when carrying heavy objects (signals broadcast by inventory system).

Write to file?

User:

Yes

Agent writes Section 3 to file.

---

Turn 6: Section 4 — Formulas

Agent:

Section 4 draft — Formulas:

Let me define variables first, then the formulas:

Variable	Type	Description
base_walk_speed	float	Base walk speed in px/s (tunable)
run_multiplier	float	Run speed = walk × this
terrain_speed_mod	float	Per-terrain multiplier (0.7–1.1)
stamina_drain_walk	float	Stamina units/sec while walking
stamina_drain_run	float	Stamina units/sec while running
stamina_cost_roll	float	Flat stamina cost per roll
terrain_drain_mod	float	Per-terrain stamina drain multiplier

Effective Speed:

effective_speed = base_walk_speed × run_multiplier (if running, else 1.0) × terrain_speed_mod

Stamina Drain (per second):

drain_per_sec = stamina_drain_walk (or stamina_drain_run if running) × terrain_drain_mod

Roll Stamina Cost (flat):

stamina_after_roll = current_stamina - stamina_cost_roll
(clamped to 0 — roll still executes, but player lands with 0 stamina)

Approve or adjust variable names/formulas?

User:

Looks right. Write it.

Agent writes Section 4 to file.

---

Turn 7–9: Sections 5, 6, 7

(These follow the same pattern — agent drafts, user approves or requests minor tweaks, agent writes each section to file before moving on. Abbreviated here.)

Section 5 — Edge Cases covered:

• Player rolls into a wall (animation completes, no movement bonus)
• Stamina hits 0 mid-run (transitions to walk, no lurch)
• Two terrain types overlapping (lower multiplier wins)
• Roll on slick rock (still applies slick friction to stopping, not to the roll itself)

Section 6 — Dependencies covered:

• Stamina system (downstream): movement exposes on_stamina_event(type: String, amount: float) signal
• Inventory system (downstream): listens to carrying_heavy_object_changed(is_heavy: bool) signal
• Input system: movement direction from InputMap — standard Godot action names (ui_left, ui_right, etc.)
• Terrain layer: tile metadata drives terrain modifier lookup

Section 7 — Tuning Knobs covered:

• base_walk_speed (default: 120 px/s)
• run_multiplier (default: 1.7)
• Per-terrain speed and drain modifiers (table of 4 terrain types)
• stamina_drain_walk, stamina_drain_run, stamina_cost_roll

---

Turn 10: Section 8 — Acceptance Criteria

Agent:

Section 8 draft — Acceptance Criteria:

These are the testable conditions that prove this system is complete:

• Player walks at base_walk_speed on normal ground (measured with debug overlay)
• Player runs at base_walk_speed × run_multiplier on normal ground
• Run automatically cancels when stamina reaches 0, no input required
• Roll executes with correct invincibility frames (verify via hitbox debug mode)
• Each terrain type applies the correct speed modifier (QA table in sprint plan)
• Carrying heavy object disables run (test with inventory integration)
• Stamina system receives on_stamina_event signals during walk, run, and roll
• All movement values come from exported variables — no hardcoded numbers in code

Does this cover what "done" means to you?

User:

Add one for slopes — make sure >45 degree slopes block movement.

Agent:

Added:

• Slopes ≤45° traversed normally; slopes >45° block movement (player slides back)

Write to file?

User:

Yes. Write it.

Agent writes Section 8 to file.

---

Turn 11: Completion Summary

Agent:

All 8 sections written to design/gdd/movement-system.md.

GDD Status:

• ✅ Overview
• ✅ Player Fantasy
• ✅ Detailed Rules
• ✅ Formulas
• ✅ Edge Cases
• ✅ Dependencies (exposes 2 signals: stamina_event, carrying_heavy)
• ✅ Tuning Knobs
• ✅ Acceptance Criteria

Key decisions made:

• Terrain modifiers as tile metadata (not code constants)
• Rolling has a flat stamina cost (not per-second)
• Heavy carry disables run (signal-driven, not hardcoded check)

Recommended next step: Run /design-review design/gdd/movement-system.md before moving to the next system in your queue (stamina is next in dependency order, per systems-index).

The review will validate completeness, internal consistency, and catch anything that needs revision before you build on this GDD.

---

What This Example Demonstrates

• Incremental file writing: each section written to disk immediately after approval — a session crash loses at most one in-progress section
• Template population: the GDD template's 8 sections become concrete content through dialogue, not bulk generation
• Dependency signaling: agent proactively surfaces downstream signal contracts (stamina, inventory) during the Dependencies section
• Technical feasibility pre-check: agent notes Jolt physics change before design starts, not after implementation breaks
• Section-by-section cycle: no full draft dumped at once — each section is a small, reviewable unit
• Recovery: if the session crashes, the agent re-reads the file on restart and resumes from the first empty section