ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-06-27 04:51:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Release v0.4.0: UX pipeline, game-dev improvements

Browse Source 
## New Skills (9)
- /quick-design: lightweight spec path for small changes (bypasses full GDD pipeline)
- /story-readiness: validates stories are implementation-ready before pickup
- /story-done: end-of-story completion review (criteria verification, deviation check, status update)
- /sprint-status: fast 30-line sprint snapshot, read-only
- /ux-design: guided section-by-section UX spec authoring (screen/flow/HUD/patterns)
- /ux-review: UX spec validation with APPROVED/NEEDS REVISION/MAJOR REVISION verdict
- /architecture-review, /create-architecture, /create-control-manifest,
  /create-epics-stories, /propagate-design-change, /review-all-gdds (pipeline completion)

## New Templates (7)
- player-journey.md: 6-phase emotional arc, critical moments, retention hooks
- difficulty-curve.md: difficulty axes, onboarding ramp, cross-system interactions
- ux-spec.md: per-screen UX spec with states, interaction map, data requirements, events
- hud-design.md: whole-game HUD with philosophy, info architecture, element specs
- accessibility-requirements.md: project-wide accessibility tier commitment and audit
- interaction-pattern-library.md: 26 standard + game-specific patterns with full state specs
- architecture-traceability.md: GDD requirements to ADR coverage matrix

## Updated Skills & Templates
- gate-check: Vertical Slice hard gate, playtesting strengthened, UX artifacts required
- team-ui: full UX pipeline integration (/ux-design + /ux-review + accessibility-specialist)
- game-design-document: Game Feel section (input latency, animation frames, impact moments)
- implementation-agent-protocol: /story-done as explicit final step of every story
- architecture-decision, design-system: pipeline completion updates

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-03-10 16:15:34 +11:00
parent 392e3befec
commit b1cad29b68
27 changed files with 7568 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
.claude/skills/architecture-decision/SKILL.md
View File

@@ -8,15 +8,97 @@ allowed-tools: Read, Glob, Grep, Write
When this skill is invoked:
1. **Determine the next ADR number** by scanning `docs/architecture/` for
existing ADRs.
## 0. Load Engine Context (ALWAYS FIRST)
2. **Gather context** by reading related code and existing ADRs.
Before doing anything else, establish the engine environment:
3. **Guide the user through the decision** by asking clarifying questions if
the title alone is not sufficient.
1. Read `docs/engine-reference/[engine]/VERSION.md` to get:
- Engine name and version
- LLM knowledge cutoff date
- Post-cutoff version risk levels (LOW / MEDIUM / HIGH)
4. **Generate the ADR** following this format:
2. Identify the **domain** of this architecture decision from the title or
user description. Common domains: Physics, Rendering, UI, Audio, Navigation,
Animation, Networking, Core, Input, Scripting.
3. Read the corresponding module reference if it exists:
`docs/engine-reference/[engine]/modules/[domain].md`
4. Read `docs/engine-reference/[engine]/breaking-changes.md` — flag any
changes in the relevant domain that post-date the LLM's training cutoff.
5. Read `docs/engine-reference/[engine]/deprecated-apis.md` — flag any APIs
in the relevant domain that should not be used.
6. **Display a knowledge gap warning** before proceeding if the domain carries
MEDIUM or HIGH risk:
```
⚠️ ENGINE KNOWLEDGE GAP WARNING
Engine: [name + version]
Domain: [domain]
Risk Level: HIGH — This version is post-LLM-cutoff.
Key changes verified from engine-reference docs:
- [Change 1 relevant to this domain]
- [Change 2]
This ADR will be cross-referenced against the engine reference library.
Proceed with verified information only — do NOT rely solely on training data.
```
If no engine has been configured yet, prompt: "No engine is configured.
Run `/setup-engine` first, or tell me which engine you are using."
---
## 1. Determine the next ADR number
Scan `docs/architecture/` for existing ADRs to find the next number.
---
## 2. Gather context
Read related code, existing ADRs, and relevant GDDs from `design/gdd/`.
---
## 3. Guide the decision collaboratively
Ask clarifying questions if the title alone is not sufficient. For each major
section, present 2-4 options with pros/cons before drafting. Do not generate
the ADR until the key decision is confirmed by the user.
Key questions to ask:
- What problem are we solving? What breaks if we don't decide this now?
- What constraints apply (engine version, platform, performance budget)?
- What alternatives have you already considered?
- Which post-cutoff engine features (if any) does this decision depend on?
- **Which GDD systems motivated this decision?** For each, what specific
requirement (rule, formula, performance constraint, integration point) in
that GDD cannot be satisfied without this architectural decision?
If the decision is foundational (no GDD drives it directly), ask:
- Which GDD systems will this decision constrain or enable?
This GDD linkage becomes a mandatory "GDD Requirements Addressed" section
in the ADR. Do not skip it.
**Does this ADR have ordering constraints?** Ask:
- Does this decision depend on any other ADR that isn't yet Accepted? (If
so, this ADR cannot be safely implemented until that one is resolved.)
- Does accepting this ADR unlock or unblock any other pending decisions?
- Does this ADR block any specific epic or story from starting?
Record the answers in the **ADR Dependencies** section. If no ordering
constraints exist, write "None" in each field.
---
## 4. Generate the ADR
Following this format:
```markdown
# ADR-[NNNN]: [Title]
@@ -27,6 +109,26 @@ When this skill is invoked:
## Date
[Date of decision]
## Engine Compatibility
| Field | Value |
|-------|-------|
| **Engine** | [e.g. Godot 4.6] |
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input] |
| **Knowledge Risk** | [LOW / MEDIUM / HIGH — from VERSION.md] |
| **References Consulted** | [List engine-reference docs read, e.g. `docs/engine-reference/godot/modules/physics.md`] |
| **Post-Cutoff APIs Used** | [Any APIs from post-LLM-cutoff versions this decision depends on, or "None"] |
| **Verification Required** | [Specific behaviours to test before shipping, or "None"] |
## ADR Dependencies
| Field | Value |
|-------|-------|
| **Depends On** | [ADR-NNNN (must be Accepted before this can be implemented), or "None"] |
| **Enables** | [ADR-NNNN (this ADR unlocks that decision), or "None"] |
| **Blocks** | [Epic/Story name — cannot start until this ADR is Accepted, or "None"] |
| **Ordering Note** | [Any sequencing constraint that isn't captured above] |
## Context
### Problem Statement

384
.claude/skills/architecture-review/SKILL.md Normal file
View File

@@ -0,0 +1,384 @@
---
name: architecture-review
description: "Validates completeness and consistency of the project architecture against all GDDs. Builds a traceability matrix mapping every GDD technical requirement to ADRs, identifies coverage gaps, detects cross-ADR conflicts, verifies engine compatibility consistency across all decisions, and produces a PASS/CONCERNS/FAIL verdict. The architecture equivalent of /design-review."
argument-hint: "[focus: full | coverage | consistency | engine | single-gdd path/to/gdd.md]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: fork
agent: technical-director
---
# Architecture Review
The architecture review validates that the complete body of architectural decisions
covers all game design requirements, is internally consistent, and correctly targets
the project's pinned engine version. It is the quality gate between Technical Setup
and Pre-Production.
**Argument modes:**
- **No argument / `full`**: Full review — all phases
- **`coverage`**: Traceability only — which GDD requirements have no ADR
- **`consistency`**: Cross-ADR conflict detection only
- **`engine`**: Engine compatibility audit only
- **`single-gdd [path]`**: Review architecture coverage for one specific GDD
---
## Phase 1: Load Everything
Read all inputs before analysis:
### Design Documents
- All GDDs in `design/gdd/` — read every file completely
- `design/gdd/systems-index.md` — the authoritative list of systems
### Architecture Documents
- All ADRs in `docs/architecture/` — read every file completely
- `docs/architecture/architecture.md` if it exists
### Engine Reference
- `docs/engine-reference/[engine]/VERSION.md`
- `docs/engine-reference/[engine]/breaking-changes.md`
- `docs/engine-reference/[engine]/deprecated-apis.md`
- All files in `docs/engine-reference/[engine]/modules/`
### Project Standards
- `.claude/docs/technical-preferences.md`
Report a count: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."
---
## Phase 2: Extract Technical Requirements from Every GDD
For each GDD, read it and extract all **technical requirements** — things the
architecture must provide for the system to work. A technical requirement is any
statement that implies a specific architectural decision.
Categories to extract:
| Category | Example |
|----------|---------|
| **Data structures** | "Each entity has health, max health, status effects" → needs a component/data schema |
| **Performance constraints** | "Collision detection must run at 60fps with 200 entities" → physics budget ADR |
| **Engine capability** | "Inverse kinematics for character animation" → IK system ADR |
| **Cross-system communication** | "Damage system notifies UI and audio simultaneously" → event/signal architecture ADR |
| **State persistence** | "Player progress persists between sessions" → save system ADR |
| **Threading/timing** | "AI decisions happen off the main thread" → concurrency ADR |
| **Platform requirements** | "Supports keyboard, gamepad, touch" → input system ADR |
For each GDD, produce a structured list:
```
GDD: [filename]
System: [system name]
Technical Requirements:
TR-[GDD]-001: [requirement text] → Domain: [Physics/Rendering/etc]
TR-[GDD]-002: [requirement text] → Domain: [...]
```
This becomes the **requirements baseline** — the complete set of what the
architecture must cover.
---
## Phase 3: Build the Traceability Matrix
For each technical requirement extracted in Phase 2, search the ADRs:
1. Read every ADR's "GDD Requirements Addressed" section
2. Check if it explicitly references the requirement or its GDD
3. Check if the ADR's decision text implicitly covers the requirement
4. Mark coverage status:
| Status | Meaning |
|--------|---------|
| ✅ **Covered** | An ADR explicitly addresses this requirement |
| ⚠️ **Partial** | An ADR partially covers this, or coverage is ambiguous |
| ❌ **Gap** | No ADR addresses this requirement |
Build the full matrix:
```
## Traceability Matrix
| Requirement ID | GDD | System | Requirement | ADR Coverage | Status |
|---------------|-----|--------|-------------|--------------|--------|
| TR-combat-001 | combat.md | Combat | Hitbox detection < 1 frame | ADR-0003 | ✅ |
| TR-combat-002 | combat.md | Combat | Combo window timing | — | ❌ GAP |
| TR-inventory-001 | inventory.md | Inventory | Persistent item storage | ADR-0005 | ✅ |
```
Count the totals: X covered, Y partial, Z gaps.
---
## Phase 4: Cross-ADR Conflict Detection
Compare every ADR against every other ADR to detect contradictions. A conflict
exists when:
- **Data ownership conflict**: Two ADRs claim exclusive ownership of the same data
- **Integration contract conflict**: ADR-A assumes System X has interface Y, but
ADR-B defines System X with a different interface
- **Performance budget conflict**: ADR-A allocates N ms to physics, ADR-B allocates
N ms to AI, together they exceed the total frame budget
- **Dependency cycle**: ADR-A says System X initialises before Y; ADR-B says Y
initialises before X
- **Architecture pattern conflict**: ADR-A uses event-driven communication for a
subsystem; ADR-B uses direct function calls to the same subsystem
- **State management conflict**: Two ADRs define authority over the same game state
(e.g. both Combat ADR and Character ADR claim to own the health value)
For each conflict found:
```
## Conflict: [ADR-NNNN] vs [ADR-MMMM]
Type: [Data ownership / Integration / Performance / Dependency / Pattern / State]
ADR-NNNN claims: [...]
ADR-MMMM claims: [...]
Impact: [What breaks if both are implemented as written]
Resolution options:
1. [Option A]
2. [Option B]
```
### ADR Dependency Ordering
After conflict detection, analyse the dependency graph across all ADRs:
1. **Collect all `Depends On` fields** from every ADR's "ADR Dependencies" section
2. **Topological sort**: Determine the correct implementation order — ADRs with no
dependencies come first (Foundation), ADRs that depend on those come next, etc.
3. **Flag unresolved dependencies**: If ADR-A's "Depends On" field references an ADR
that is still `Proposed` or does not exist, flag it:
```
⚠️ ADR-0005 depends on ADR-0002 — but ADR-0002 is still Proposed.
ADR-0005 cannot be safely implemented until ADR-0002 is Accepted.
```
4. **Cycle detection**: If ADR-A depends on ADR-B and ADR-B depends on ADR-A (directly
or transitively), flag it as a `DEPENDENCY CYCLE`:
```
🔴 DEPENDENCY CYCLE: ADR-0003 → ADR-0006 → ADR-0003
This cycle must be broken before either can be implemented.
```
5. **Output recommended implementation order**:
```
### Recommended ADR Implementation Order (topologically sorted)
Foundation (no dependencies):
1. ADR-0001: [title]
2. ADR-0003: [title]
Depends on Foundation:
3. ADR-0002: [title] (requires ADR-0001)
4. ADR-0005: [title] (requires ADR-0003)
Feature layer:
5. ADR-0004: [title] (requires ADR-0002, ADR-0005)
```
---
## Phase 5: Engine Compatibility Cross-Check
Across all ADRs, check for engine consistency:
### Version Consistency
- Do all ADRs that mention an engine version agree on the same version?
- If any ADR was written for an older engine version, flag it as potentially stale
### Post-Cutoff API Consistency
- Collect all "Post-Cutoff APIs Used" fields from all ADRs
- For each, verify against the relevant module reference doc
- Check that no two ADRs make contradictory assumptions about the same post-cutoff API
### Deprecated API Check
- Grep all ADRs for API names listed in `deprecated-apis.md`
- Flag any ADR referencing a deprecated API
### Missing Engine Compatibility Sections
- List all ADRs that are missing the Engine Compatibility section entirely
- These are blind spots — their engine assumptions are unknown
Output format:
```
### Engine Audit Results
Engine: [name + version]
ADRs with Engine Compatibility section: X / Y total
Deprecated API References:
- ADR-0002: uses [deprecated API] — deprecated since [version]
Stale Version References:
- ADR-0001: written for [older version] — current project version is [version]
Post-Cutoff API Conflicts:
- ADR-0004 and ADR-0007 both use [API] with incompatible assumptions
```
---
## Phase 5b: Design Revision Flags (Architecture → GDD Feedback)
For each **HIGH RISK engine finding** from Phase 5, check whether any GDD makes an
assumption that the verified engine reality contradicts.
Specific cases to check:
1. **Post-cutoff API behaviour differs from training-data assumptions**: If an ADR
records a verified API behaviour that differs from the default LLM assumption,
check all GDDs that reference the related system. Look for design rules written
around the old (assumed) behaviour.
2. **Known engine limitations in ADRs**: If an ADR records a known engine limitation
(e.g. "Jolt ignores HingeJoint3D damp", "D3D12 is now the default backend"), check
GDDs that design mechanics around the affected feature.
3. **Deprecated API conflicts**: If Phase 5 flagged a deprecated API used in an ADR,
check whether any GDD contains mechanics that assume the deprecated API's behaviour.
For each conflict found, record it in the GDD Revision Flags table:
```
### GDD Revision Flags (Architecture → Design Feedback)
These GDD assumptions conflict with verified engine behaviour or accepted ADRs.
The GDD should be revised before its system enters implementation.
| GDD | Assumption | Reality (from ADR/engine-reference) | Action |
|-----|-----------|--------------------------------------|--------|
| combat.md | "Use HingeJoint3D damp for weapon recoil" | Jolt ignores damp — ADR-0003 | Revise GDD |
```
If no revision flags are found, write: "No GDD revision flags — all GDD assumptions
are consistent with verified engine behaviour."
Ask: "Should I flag these GDDs for revision in the systems index?"
- If yes: update the relevant systems' Status field to "Needs Revision (Architecture Feedback)"
and note the specific conflict in a comment. Ask for approval before writing.
---
## Phase 6: Architecture Document Coverage
If `docs/architecture/architecture.md` exists, validate it against GDDs:
- Does every system from `systems-index.md` appear in the architecture layers?
- Does the data flow section cover all cross-system communication defined in GDDs?
- Do the API boundaries support all integration requirements from GDDs?
- Are there systems in the architecture doc that have no corresponding GDD
(orphaned architecture)?
---
## Phase 7: Output the Review Report
```
## Architecture Review Report
Date: [date]
Engine: [name + version]
GDDs Reviewed: [N]
ADRs Reviewed: [M]
---
### Traceability Summary
Total requirements: [N]
✅ Covered: [X]
⚠️ Partial: [Y]
❌ Gaps: [Z]
### Coverage Gaps (no ADR exists)
For each gap:
❌ TR-[id]: [GDD] → [system] → [requirement]
Suggested ADR: "/architecture-decision [suggested title]"
Domain: [Physics/Rendering/etc]
Engine Risk: [LOW/MEDIUM/HIGH]
### Cross-ADR Conflicts
[List all conflicts from Phase 4]
### ADR Dependency Order
[Topologically sorted implementation order from Phase 4 — dependency ordering section]
[Unresolved dependencies and cycles if any]
### GDD Revision Flags
[GDD assumptions that conflict with verified engine behaviour — from Phase 5b]
[Or: "None — all GDD assumptions consistent with verified engine behaviour"]
### Engine Compatibility Issues
[List all engine issues from Phase 5]
### Architecture Document Coverage
[List missing systems and orphaned architecture from Phase 6]
---
### Verdict: [PASS / CONCERNS / FAIL]
PASS: All requirements covered, no conflicts, engine consistent
CONCERNS: Some gaps or partial coverage, but no blocking conflicts
FAIL: Critical gaps (Foundation/Core layer requirements uncovered),
or blocking cross-ADR conflicts detected
### Blocking Issues (must resolve before PASS)
[List items that must be resolved — FAIL verdict only]
### Required ADRs
[Prioritised list of ADRs to create, most foundational first]
```
---
## Phase 8: Write and Update Traceability Index
Ask: "May I write this review to `docs/architecture/architecture-review-[date].md`?"
Also ask: "May I update `docs/architecture/architecture-traceability.md` with the
current matrix? This is the living index that future reviews update incrementally."
The traceability index format:
```markdown
# Architecture Traceability Index
Last Updated: [date]
Engine: [name + version]
## Coverage Summary
- Total requirements: [N]
- Covered: [X] ([%])
- Partial: [Y]
- Gaps: [Z]
## Full Matrix
[Complete traceability matrix from Phase 3]
## Known Gaps
[All ❌ items with suggested ADRs]
## Superseded Requirements
[Requirements whose GDD was changed after the ADR was written]
```
---
## Phase 9: Handoff
After completing the review:
1. **Immediate actions**: List the top 3 ADRs to create (highest-impact gaps first,
Foundation layer before Feature layer)
2. **Gate guidance**: "When all blocking issues are resolved, run `/gate-check
pre-production` to advance"
3. **Rerun trigger**: "Re-run `/architecture-review` after each new ADR is written
to verify coverage improves"
---
## Collaborative Protocol
1. **Read silently** — do not narrate every file read
2. **Show the matrix** — present the full traceability matrix before asking for
anything; let the user see the state
3. **Don't guess** — if a requirement is ambiguous, ask: "Is [X] a technical
requirement or a design preference?"
4. **Ask before writing** — always confirm before writing the report file
5. **Non-blocking** — the verdict is advisory; the user decides whether to continue
despite CONCERNS or even FAIL findings

352
.claude/skills/create-architecture/SKILL.md Normal file
View File

@@ -0,0 +1,352 @@
---
name: create-architecture
description: "Guided, section-by-section authoring of the master architecture document for the game. Reads all GDDs, the systems index, existing ADRs, and the engine reference library to produce a complete architecture blueprint before any code is written. Engine-version-aware: flags knowledge gaps and validates decisions against the pinned engine version."
argument-hint: "[focus-area: full | layers | data-flow | api-boundaries | adr-audit]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
context: fork
agent: technical-director
---
# Create Architecture
This skill produces `docs/architecture/architecture.md` — the master architecture
document that translates all approved GDDs into a concrete technical blueprint.
It sits between design and implementation, and must exist before sprint planning begins.
**Distinct from `/architecture-decision`**: ADRs record individual point decisions.
This skill creates the whole-system blueprint that gives ADRs their context.
**Argument modes:**
- **No argument / `full`**: Full guided walkthrough — all sections, start to finish
- **`layers`**: Focus on the system layer diagram only
- **`data-flow`**: Focus on data flow between modules only
- **`api-boundaries`**: Focus on API boundary definitions only
- **`adr-audit`**: Audit existing ADRs for engine compatibility gaps only
---
## Phase 0: Load All Context
Before anything else, load the full project context in this order:
### 0a. Engine Context (Critical)
Read the engine reference library completely:
1. `docs/engine-reference/[engine]/VERSION.md`
→ Extract: engine name, version, LLM cutoff, post-cutoff risk levels
2. `docs/engine-reference/[engine]/breaking-changes.md`
→ Extract: all HIGH and MEDIUM risk changes
3. `docs/engine-reference/[engine]/deprecated-apis.md`
→ Extract: APIs to avoid
4. `docs/engine-reference/[engine]/current-best-practices.md`
→ Extract: post-cutoff best practices that differ from training data
5. All files in `docs/engine-reference/[engine]/modules/`
→ Extract: current API patterns per domain
If no engine is configured, stop and prompt:
> "No engine is configured. Run `/setup-engine` first. Architecture cannot be
> written without knowing which engine and version you are targeting."
### 0b. Design Context + Technical Requirements Extraction
Read all approved design documents and extract technical requirements from each:
1. `design/gdd/game-concept.md` — game pillars, genre, core loop
2. `design/gdd/systems-index.md` — all systems, dependencies, priority tiers
3. `.claude/docs/technical-preferences.md` — naming conventions, performance budgets,
allowed libraries, forbidden patterns
4. **Every GDD in `design/gdd/`** — for each, extract technical requirements:
- Data structures implied by the game rules
- Performance constraints stated or implied
- Engine capabilities the system requires
- Cross-system communication patterns (what talks to what, how)
- State that must persist (save/load implications)
- Threading or timing requirements
Build a **Technical Requirements Baseline** — a flat list of all extracted
requirements across all GDDs, numbered `TR-[gdd-slug]-[NNN]`. This is the
complete set of what the architecture must cover. Present it as:
```
## Technical Requirements Baseline
Extracted from [N] GDDs | [X] total requirements
| Req ID | GDD | System | Requirement | Domain |
|--------|-----|--------|-------------|--------|
| TR-combat-001 | combat.md | Combat | Hitbox detection per-frame | Physics |
| TR-combat-002 | combat.md | Combat | Combo state machine | Core |
| TR-inventory-001 | inventory.md | Inventory | Item persistence | Save/Load |
```
This baseline feeds into every subsequent phase. No GDD requirement should be
left without an architectural decision to support it by the end of this session.
### 0c. Existing Architecture Decisions
Read all files in `docs/architecture/` to understand what has already been decided.
List any ADRs found and their domains.
### 0d. Generate Knowledge Gap Inventory
Before proceeding, display a structured summary:
```
## Engine Knowledge Gap Inventory
Engine: [name + version]
LLM Training Covers: up to approximately [version]
Post-Cutoff Versions: [list]
### HIGH RISK Domains (must verify against engine reference before deciding)
- [Domain]: [Key changes]
### MEDIUM RISK Domains (verify key APIs)
- [Domain]: [Key changes]
### LOW RISK Domains (in training data, likely reliable)
- [Domain]: [no significant post-cutoff changes]
### Systems from GDD that touch HIGH/MEDIUM risk domains:
- [GDD system name] → [domain] → [risk level]
```
Ask: "This inventory identifies [N] systems in HIGH RISK engine domains. Shall I
continue building the architecture with these warnings flagged throughout?"
---
## Phase 1: System Layer Mapping
Map every system from `systems-index.md` into an architecture layer. The standard
game architecture layers are:
```
┌─────────────────────────────────────────────┐
│ PRESENTATION LAYER │ ← UI, HUD, menus, VFX, audio
├─────────────────────────────────────────────┤
│ FEATURE LAYER │ ← gameplay systems, AI, quests
├─────────────────────────────────────────────┤
│ CORE LAYER │ ← physics, input, combat, movement
├─────────────────────────────────────────────┤
│ FOUNDATION LAYER │ ← engine integration, save/load,
│ │ scene management, event bus
├─────────────────────────────────────────────┤
│ PLATFORM LAYER │ ← OS, hardware, engine API surface
└─────────────────────────────────────────────┘
```
For each GDD system, ask:
- Which layer does it belong to?
- What are its module boundaries?
- What does it own exclusively? (data, state, behaviour)
Present the proposed layer assignment and ask for approval before proceeding to
the next section. Write the approved layer map immediately to the skeleton file.
**Engine awareness check**: For each system assigned to the Core and Foundation
layers, flag if it touches a HIGH or MEDIUM risk engine domain. Show the relevant
engine reference excerpt inline.
---
## Phase 2: Module Ownership Map
For each module defined in Phase 1, define ownership:
- **Owns**: what data and state this module is solely responsible for
- **Exposes**: what other modules may read or call
- **Consumes**: what it reads from other modules
- **Engine APIs used**: which specific engine classes/nodes/signals this module
calls directly (with version and risk level noted)
Format as a table per layer, then as an ASCII dependency diagram.
**Engine awareness check**: For every engine API listed, verify against the
relevant module reference doc. If an API is post-cutoff, flag it:
```
⚠️ [ClassName.method()] — Godot 4.6 (post-cutoff, HIGH risk)
Verified against: docs/engine-reference/godot/modules/[domain].md
Behaviour confirmed: [yes / NEEDS VERIFICATION]
```
Get user approval on the ownership map before writing.
---
## Phase 3: Data Flow
Define how data moves between modules during key game scenarios. Cover at minimum:
1. **Frame update path**: Input → Core systems → State → Rendering
2. **Event/signal path**: How systems communicate without tight coupling
3. **Save/load path**: What state is serialised, which module owns serialisation
4. **Initialisation order**: Which modules must boot before others
Use ASCII sequence diagrams where helpful. For each data flow:
- Name the data being transferred
- Identify the producer and consumer
- State whether this is synchronous call, signal/event, or shared state
- Flag any data flows that cross thread boundaries
Get user approval per scenario before writing.
---
## Phase 4: API Boundaries
Define the public contracts between modules. For each boundary:
- What is the interface a module exposes to the rest of the system?
- What are the entry points (functions/signals/properties)?
- What invariants must callers respect?
- What must the module guarantee to callers?
Write in pseudocode or the project's actual language (from technical preferences).
These become the contracts programmers implement against.
**Engine awareness check**: If any interface uses engine-specific types (e.g.
`Node`, `Resource`, `Signal` in Godot), flag the version and verify the type
exists and has not changed signature in the target engine version.
---
## Phase 5: ADR Audit + Traceability Check
Review all existing ADRs from Phase 0c against both the architecture built in
Phases 1-4 AND the Technical Requirements Baseline from Phase 0b.
### ADR Quality Check
For each ADR:
- [ ] Does it have an Engine Compatibility section?
- [ ] Is the engine version recorded?
- [ ] Are post-cutoff APIs flagged?
- [ ] Does it have a "GDD Requirements Addressed" section?
- [ ] Does it conflict with the layer/ownership decisions made in this session?
- [ ] Is it still valid for the pinned engine version?
| ADR | Engine Compat | Version | GDD Linkage | Conflicts | Valid |
|-----|--------------|---------|-------------|-----------|-------|
| ADR-0001: [title] | ✅/❌ | ✅/❌ | ✅/❌ | None/[conflict] | ✅/⚠️ |
### Traceability Coverage Check
Map every requirement from the Technical Requirements Baseline to existing ADRs.
For each requirement, check if any ADR's "GDD Requirements Addressed" section
or decision text covers it:
| Req ID | Requirement | ADR Coverage | Status |
|--------|-------------|--------------|--------|
| TR-combat-001 | Hitbox detection per-frame | ADR-0003 | ✅ |
| TR-combat-002 | Combo state machine | — | ❌ GAP |
Count: X covered, Y gaps. For each gap, it becomes a **Required New ADR**.
### Required New ADRs
List all decisions made during this architecture session (Phases 1-4) that do
not yet have a corresponding ADR, PLUS all uncovered Technical Requirements.
Group by layer — Foundation first:
**Foundation Layer (must create before any coding):**
- `/architecture-decision [title]` → covers: TR-[id], TR-[id]
**Core Layer:**
- `/architecture-decision [title]` → covers: TR-[id]
---
## Phase 6: Missing ADR List
Based on the full architecture, produce a complete list of ADRs that should exist
but don't yet. Group by priority:
**Must have before coding starts (Foundation & Core decisions):**
- [e.g. "Scene management and scene loading strategy"]
- [e.g. "Event bus vs direct signal architecture"]
**Should have before the relevant system is built:**
- [e.g. "Inventory serialisation format"]
**Can defer to implementation:**
- [e.g. "Specific shader technique for water"]
---
## Phase 7: Write the Master Architecture Document
Once all sections are approved, write the complete document to
`docs/architecture/architecture.md`.
Ask: "May I write the master architecture document to `docs/architecture/architecture.md`?"
The document structure:
```markdown
# [Game Name] — Master Architecture
## Document Status
- Version: [N]
- Last Updated: [date]
- Engine: [name + version]
- GDDs Covered: [list]
- ADRs Referenced: [list]
## Engine Knowledge Gap Summary
[Condensed from Phase 0d inventory — HIGH/MEDIUM risk domains and their implications]
## System Layer Map
[From Phase 1]
## Module Ownership
[From Phase 2]
## Data Flow
[From Phase 3]
## API Boundaries
[From Phase 4]
## ADR Audit
[From Phase 5]
## Required ADRs
[From Phase 6]
## Architecture Principles
[3-5 key principles that govern all technical decisions for this project,
derived from the game concept, GDDs, and technical preferences]
## Open Questions
[Decisions deferred — must be resolved before the relevant layer is built]
```
---
## Phase 8: Handoff
After writing the document, provide a clear handoff:
1. **Run these ADRs next** (from Phase 6, prioritised): list the top 3
2. **Gate check**: "The master architecture document is complete. Run `/gate-check
pre-production` when all required ADRs are also written."
3. **Update session state**: Write a summary to `production/session-state/active.md`
---
## Collaborative Protocol
This skill follows the collaborative design principle at every phase:
1. **Load context silently** — do not narrate file reads
2. **Present findings** — show the knowledge gap inventory and layer proposals
3. **Ask before deciding** — present options for each architectural choice
4. **Get approval before writing** — each phase section is written only after
user approves the content
5. **Incremental writing** — write each approved section immediately; do not
accumulate everything and write at the end. This survives session crashes.
Never make a binding architectural decision without user input. If the user is
unsure, present 2-4 options with pros/cons before asking them to decide.

247
.claude/skills/create-control-manifest/SKILL.md Normal file
View File

@@ -0,0 +1,247 @@
---
name: create-control-manifest
description: "After architecture is complete, produces a flat actionable rules sheet for programmers — what you must do, what you must never do, per system and per layer. Extracted from all Accepted ADRs, technical preferences, and engine reference docs. More immediately actionable than ADRs (which explain why)."
argument-hint: "[update — regenerate from current ADRs]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: fork
agent: technical-director
---
# Create Control Manifest
The Control Manifest is a flat, actionable rules sheet for programmers. It
answers "what do I do?" and "what must I never do?" — organized by architectural
layer, extracted from all Accepted ADRs, technical preferences, and engine
reference docs. Where ADRs explain *why*, the manifest tells you *what*.
**Output:** `docs/architecture/control-manifest.md`
**When to run:** After `/architecture-review` passes and ADRs are in Accepted
status. Re-run whenever new ADRs are accepted or existing ADRs are revised.
---
## 1. Load All Inputs
### ADRs
- Glob `docs/architecture/adr-*.md` and read every file
- Filter to only Accepted ADRs (Status: Accepted) — skip Proposed, Deprecated,
Superseded
- Note the ADR number and title for every rule sourced
### Technical Preferences
- Read `.claude/docs/technical-preferences.md`
- Extract: naming conventions, performance budgets, approved libraries/addons,
forbidden patterns
### Engine Reference
- Read `docs/engine-reference/[engine]/VERSION.md` for engine + version
- Read `docs/engine-reference/[engine]/deprecated-apis.md` — these become
forbidden API entries
- Read `docs/engine-reference/[engine]/current-best-practices.md` if it exists
Report: "Loaded [N] Accepted ADRs, engine: [name + version]."
---
## 2. Extract Rules from Each ADR
For each Accepted ADR, extract:
### Required Patterns (from "Implementation Guidelines" section)
- Every "must", "should", "required to", "always" statement
- Every specific pattern or approach mandated
### Forbidden Approaches (from "Alternatives Considered" sections)
- Every alternative that was explicitly rejected — *why* it was rejected becomes
the rule ("never use X because Y")
- Any anti-patterns explicitly called out
### Performance Guardrails (from "Performance Implications" section)
- Budget constraints: "max N ms per frame for this system"
- Memory limits: "this system must not exceed N MB"
### Engine API Constraints (from "Engine Compatibility" section)
- Post-cutoff APIs that require verification
- Verified behaviours that differ from default LLM assumptions
- API fields or methods that behave differently in the pinned engine version
### Layer Classification
Classify each rule by the architectural layer of the system it governs:
- **Foundation**: Scene management, event architecture, save/load, engine init
- **Core**: Core gameplay loops, main player systems, physics/collision
- **Feature**: Secondary systems, secondary mechanics, AI
- **Presentation**: Rendering, audio, UI, VFX, shaders
If an ADR spans multiple layers, duplicate the rule into each relevant layer.
---
## 3. Add Global Rules
Combine rules that apply to all layers:
### From technical-preferences.md:
- Naming conventions (classes, variables, signals/events, files, constants)
- Performance budgets (target framerate, frame budget, draw call limits, memory ceiling)
### From deprecated-apis.md:
- All deprecated APIs → Forbidden API entries
### From current-best-practices.md (if available):
- Engine-recommended patterns → Required entries
### From technical-preferences.md forbidden patterns:
- Copy any "Forbidden Patterns" entries directly
---
## 4. Present Rules Summary Before Writing
Before writing the manifest, present a summary to the user:
```
## Control Manifest Preview
Engine: [name + version]
ADRs covered: [list ADR numbers]
Total rules extracted:
- Foundation layer: [N] required, [M] forbidden, [P] guardrails
- Core layer: [N] required, [M] forbidden, [P] guardrails
- Feature layer: ...
- Presentation layer: ...
- Global: [N] naming conventions, [M] forbidden APIs, [P] approved libraries
```
Ask: "Does this look complete? Any rules to add or remove before I write the manifest?"
---
## 5. Write the Control Manifest
Ask: "May I write this to `docs/architecture/control-manifest.md`?"
Format:
```markdown
# Control Manifest
> **Engine**: [name + version]
> **Last Updated**: [date]
> **ADRs Covered**: [ADR-NNNN, ADR-MMMM, ...]
> **Status**: [Active — regenerate with `/create-control-manifest update` when ADRs change]
This manifest is a programmer's quick-reference extracted from all Accepted ADRs,
technical preferences, and engine reference docs. For the reasoning behind each
rule, see the referenced ADR.
---
## Foundation Layer Rules
*Applies to: scene management, event architecture, save/load, engine initialisation*
### Required Patterns
- **[rule]** — source: [ADR-NNNN]
- **[rule]** — source: [ADR-NNNN]
### Forbidden Approaches
- **Never [anti-pattern]** — [brief reason] — source: [ADR-NNNN]
### Performance Guardrails
- **[system]**: max [N]ms/frame — source: [ADR-NNNN]
---
## Core Layer Rules
*Applies to: core gameplay loop, main player systems, physics, collision*
### Required Patterns
...
### Forbidden Approaches
...
### Performance Guardrails
...
---
## Feature Layer Rules
*Applies to: secondary mechanics, AI systems, secondary features*
### Required Patterns
...
### Forbidden Approaches
...
---
## Presentation Layer Rules
*Applies to: rendering, audio, UI, VFX, shaders, animations*
### Required Patterns
...
### Forbidden Approaches
...
---
## Global Rules (All Layers)
### Naming Conventions
| Element | Convention | Example |
|---------|-----------|---------|
| Classes | [from technical-preferences] | [example] |
| Variables | [from technical-preferences] | [example] |
| Signals/Events | [from technical-preferences] | [example] |
| Files | [from technical-preferences] | [example] |
| Constants | [from technical-preferences] | [example] |
### Performance Budgets
| Target | Value |
|--------|-------|
| Framerate | [from technical-preferences] |
| Frame budget | [from technical-preferences] |
| Draw calls | [from technical-preferences] |
| Memory ceiling | [from technical-preferences] |
### Approved Libraries / Addons
- [library] — approved for [purpose]
### Forbidden APIs ([engine version])
These APIs are deprecated or unverified for [engine + version]:
- `[api name]` — deprecated since [version] / unverified post-cutoff
- Source: `docs/engine-reference/[engine]/deprecated-apis.md`
### Cross-Cutting Constraints
- [constraint that applies everywhere, regardless of layer]
```
---
## 6. Suggest Next Steps
After writing the manifest:
- If epics/stories don't exist yet: "Run `/create-epics-stories` — programmers
can now use this manifest when writing story implementation notes."
- If this is a regeneration (manifest already existed): "Updated. Recommend
notifying the team of changed rules — especially any new Forbidden entries."
---
## Collaborative Protocol
1. **Load silently** — read all inputs before presenting anything
2. **Show the summary first** — let the user see the scope before writing
3. **Ask before writing** — always confirm before creating or overwriting the manifest
4. **Source every rule** — never add a rule that doesn't trace to an ADR, a
technical preference, or an engine reference doc
5. **No interpretation** — extract rules as stated in ADRs; do not paraphrase
in ways that change meaning

300
.claude/skills/create-epics-stories/SKILL.md Normal file
View File

@@ -0,0 +1,300 @@
---
name: create-epics-stories
description: "Translate approved GDDs + architecture + ADRs into implementable epics and stories. Each story embeds the GDD requirement it satisfies, the ADR governing implementation, acceptance criteria, engine compatibility notes, and control manifest rules. Programmers need nothing else to implement a story correctly."
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write
context: fork
agent: technical-director
---
# Create Epics & Stories
This skill translates the approved design and architecture into implementable
work units. Each **epic** maps to one architectural module. Each **story** is a
single implementable behaviour — small enough for one session, self-contained,
and fully traceable to the GDD requirement it satisfies and the ADR that governs
how to implement it.
**Output:** `production/epics/[epic-slug]/`
**When to run:** After `/architecture-review` passes and `/create-control-manifest`
has been run. All MVP-tier GDDs should be complete and reviewed.
---
## 1. Parse Arguments
**Modes:**
- `/create-epics-stories all` — process all systems in layer order
- `/create-epics-stories layer: foundation` — process Foundation layer only
- `/create-epics-stories [system-name]` — process one specific system
- No argument — ask the user which mode to use
If no argument, use `AskUserQuestion`:
- "What would you like to create epics for?"
- Options: "All systems (Foundation → Presentation)", "Foundation layer only",
"Core layer only", "A specific system", "Feature + Presentation layers"
---
## 2. Load All Inputs
Read everything before generating any output:
### Design Documents
- `design/gdd/systems-index.md` — authoritative system list, layers, status
- All GDDs in `design/gdd/` — read every file with "Approved" or "Designed" status
- For each GDD, extract:
- System name and layer (from systems-index.md)
- All acceptance criteria (these become story acceptance criteria)
- All technical requirements (these trace to ADR coverage)
- Dependencies on other systems
### Architecture Documents
- `docs/architecture/architecture.md` — module ownership and API boundaries
- All Accepted ADRs in `docs/architecture/adr-*.md` — read "GDD Requirements
Addressed", "Implementation Guidelines", "Engine Compatibility", and
"ADR Dependencies" sections
- `docs/architecture/control-manifest.md` if it exists — extract layer-specific
rules to embed in stories
### Engine Reference
- `docs/engine-reference/[engine]/VERSION.md` — engine name + version + risk levels
Report: "Loaded [N] GDDs, [M] ADRs, control manifest: [exists/missing],
engine: [name + version]."
---
## 3. Determine Processing Order
Process systems in dependency-safe layer order:
1. **Foundation** (no dependencies)
2. **Core** (depends on Foundation)
3. **Feature** (depends on Core)
4. **Presentation** (depends on Feature + Core)
Within each layer, process systems in the order they appear in systems-index.md.
For each system, determine the corresponding epic:
- Epic = one architectural module from `architecture.md` that implements this system
- If a system doesn't map cleanly to a single module, present options to the user
---
## 4. For Each System: Define the Epic
Present to the user before creating stories:
```
## Epic [N]: [System Name]
**Layer**: [Foundation / Core / Feature / Presentation]
**GDD**: design/gdd/[filename].md
**Architecture Module**: [module name from architecture.md]
**GDD Requirements Traced by ADRs**: [list TR-IDs that have ADR coverage]
**Untraceable Requirements**: [list TR-IDs with no ADR — these need ADRs first]
**Governing ADRs**: [ADR-NNNN, ADR-MMMM, ...]
**Engine Risk**: [LOW/MEDIUM/HIGH — highest risk among governing ADRs]
```
Ask: "Shall I break Epic [N]: [name] into stories?"
- Options: "Yes, break it down", "Skip this epic", "Pause — I need to write ADRs first"
If there are untraced requirements (no ADR covers them), warn:
> "⚠️ [N] requirements in [system] have no ADR. Stories for these cannot embed
> implementation guidance. Consider running `/architecture-decision` first, or
> I can create stories with a placeholder note to add ADR guidance later."
---
## 5. Break Each Epic into Stories
For each epic, decompose the GDD's acceptance criteria into stories:
**Story sizing rules:**
- One story = one implementable behaviour from the GDD
- Small enough to complete in a single focused session (~2-4 hours of focused work)
- Self-contained — no story depends on in-progress work from another story in
the same epic (stories within an epic run sequentially; they can depend on
previous stories being DONE, not in-progress)
**Story identification process:**
1. Read every acceptance criterion in the GDD
2. Group related criteria that require the same core implementation
3. Each group = one story
4. Order stories within the epic: foundation behaviour first, edge cases last
For each story, map:
- **GDD requirement**: Which specific acceptance criterion does this satisfy?
- **TR-ID**: The technical requirement ID (from `/architecture-review` traceability matrix, if run)
- **Governing ADR**: Which Accepted ADR tells the programmer how to implement this?
- **Engine risk**: Inherited from the ADR's Knowledge Risk field
- **Control manifest rules**: Which layer rules apply?
---
## 6. Generate Story Files
For each story, produce a story file embedding full context:
```markdown
# Story [NNN]: [title]
> **Epic**: [epic name]
> **Status**: Ready
> **Layer**: [Foundation / Core / Feature / Presentation]
## Context
**GDD**: `design/gdd/[filename].md`
**Requirement**: TR-[GDD]-[NNN]: [requirement text from GDD]
**ADR Governing Implementation**: [ADR-NNNN: title]
**ADR Decision Summary**: [1-2 sentence summary of what the ADR decided]
**Engine**: [name + version] | **Risk**: [LOW / MEDIUM / HIGH]
**Engine Notes**: [relevant text from the ADR's Engine Compatibility section,
especially Post-Cutoff APIs Used and Verification Required fields]
**Control Manifest Rules (this layer)**:
- Required: [relevant required pattern from manifest]
- Forbidden: [relevant forbidden approach from manifest]
- Guardrail: [relevant performance guardrail]
---
## Acceptance Criteria
*From GDD `design/gdd/[filename].md`, scoped to this story:*
- [ ] [criterion 1 — directly from GDD, scoped to this story's behaviour]
- [ ] [criterion 2]
- [ ] [performance criterion if applicable]
---
## Implementation Notes
*Derived from ADR-NNNN Implementation Guidelines:*
[Specific guidance for the programmer. This should be the ADR's Implementation
Guidelines section, filtered to what's relevant for this story. Do not
paraphrase in ways that change meaning.]
---
## Out of Scope
*These are handled by neighbouring stories — do not implement here:*
- [Story NNN+1]: [what it handles]
- [Other epic story]: [what it handles]
This boundary prevents scope creep and keeps stories independently reviewable.
---
## Dependencies
- Depends on: [Story NNN-1 must be DONE, or "None"]
- Unlocks: [Story NNN+1, or "None"]
```
---
## 7. Approval Before Writing
For each epic, after all stories are drafted, present a summary:
```
Epic [N]: [name]
Stories: [N total]
Story 001: [title] — [1-line summary]
Story 002: [title] — [1-line summary]
...
```
Ask: "May I write these [N] stories and the epic index to
`production/epics/[epic-slug]/`?"
---
## 8. Write Output Files
After approval, write:
### Story files
`production/epics/[epic-slug]/story-[NNN]-[slug].md`
### Epic index
`production/epics/[epic-slug]/EPIC.md`:
```markdown
# Epic: [name]
> **Layer**: [Foundation / Core / Feature / Presentation]
> **GDD**: design/gdd/[filename].md
> **Status**: Ready
> **Stories**: [N total]
## Overview
[1 paragraph describing what this epic implements]
## Stories
| # | Story | Status | ADR |
|---|-------|--------|-----|
| 001 | [title] | Ready | ADR-NNNN |
| 002 | [title] | Ready | ADR-MMMM |
## Definition of Done
This epic is complete when:
- All stories are implemented and reviewed
- All acceptance criteria from [GDD filename] are passing
- No Foundation or Core layer stories have open blockers
```
### Master epics index
`production/epics/index.md` (create or update):
```markdown
# Epics Index
Last Updated: [date]
Engine: [name + version]
| Epic | Layer | System | Stories | Status |
|------|-------|--------|---------|--------|
| [name] | Foundation | [system] | [N] | Ready |
```
---
## 9. Gate-Check Integration
After writing all epics for the requested scope, remind the user:
- **Foundation + Core complete**: Pre-Production → Production gate requires
Foundation and Core layer epics. Run `/gate-check production` to validate.
- **All layers complete**: Full epic coverage achieved. The sprint plan can now
reference real story file paths instead of GDD references.
---
## Collaborative Protocol
1. **Load silently** — read all inputs before presenting the first epic
2. **One epic at a time** — present each epic before creating stories; don't
batch all epics and ask once
3. **Warn on gaps** — flag untraced requirements before proceeding; let the user
decide whether to pause for ADRs or proceed with placeholders
4. **Ask before writing** — per-epic approval before writing story files
5. **No invention** — all acceptance criteria come from GDDs; all implementation
notes come from ADRs; all rules come from the control manifest. Never invent
requirements or rules that don't trace to a source document.
6. **Preserve exact quotes** — when embedding GDD requirements and ADR guidelines,
quote them exactly; do not paraphrase in ways that change meaning

65
.claude/skills/design-system/SKILL.md
View File

@@ -74,6 +74,71 @@ If any upstream dependencies are undesigned, warn:
> its interface. Consider designing it first, or we can define the expected
> contract and flag it as provisional."
### 2e: Technical Feasibility Pre-Check
Before asking the user to begin designing, load engine context and surface any
constraints or knowledge gaps that will shape the design.
**Step 1 — Determine the engine domain for this system:**
Map the system's category (from systems-index.md) to an engine domain:
| System Category | Engine Domain |
|----------------|--------------|
| Combat, physics, collision | Physics |
| Rendering, visual effects, shaders | Rendering |
| UI, HUD, menus | UI |
| Audio, sound, music | Audio |
| AI, pathfinding, behavior trees | Navigation / Scripting |
| Animation, IK, rigs | Animation |
| Networking, multiplayer, sync | Networking |
| Input, controls, keybinding | Input |
| Save/load, persistence, data | Core |
| Dialogue, quests, narrative | Scripting |
**Step 2 — Read engine context (if available):**
- Read `.claude/docs/technical-preferences.md` to identify the engine and version
- If engine is configured, read `docs/engine-reference/[engine]/VERSION.md`
- Read `docs/engine-reference/[engine]/modules/[domain].md` if it exists
- Read `docs/engine-reference/[engine]/breaking-changes.md` for domain-relevant entries
- Glob `docs/architecture/adr-*.md` and read any ADRs whose domain matches
(check the Engine Compatibility table's "Domain" field)
**Step 3 — Present the Feasibility Brief:**
If engine reference docs exist, present before starting design:
```
## Technical Feasibility Brief: [System Name]
Engine: [name + version]
Domain: [domain]
### Known Engine Capabilities (verified for [version])
- [capability relevant to this system]
- [capability 2]
### Engine Constraints That Will Shape This Design
- [constraint from engine-reference or existing ADR]
### Knowledge Gaps (verify before committing to these)
- [post-cutoff feature this design might rely on — mark HIGH/MEDIUM risk]
### Existing ADRs That Constrain This System
- ADR-XXXX: [decision summary] — means [implication for this GDD]
(or "None yet")
```
If no engine reference docs exist (engine not yet configured), show a short note:
> "No engine configured yet — skipping technical feasibility check. Run
> `/setup-engine` before moving to architecture if you haven't already."
**Step 4 — Ask before proceeding:**
Use `AskUserQuestion`:
- "Any constraints to add before we begin, or shall we proceed with these noted?"
- Options: "Proceed with these noted", "Add a constraint first", "I need to check the engine docs — pause here"
---
Use `AskUserQuestion`:
- "Ready to start designing [system-name]?"
- Options: "Yes, let's go", "Show me more context first", "Design a dependency first"

102
.claude/skills/gate-check/SKILL.md
View File

@@ -58,12 +58,16 @@ The project progresses through these stages:
**Required Artifacts:**
- [ ] Systems index exists at `design/gdd/systems-index.md` with at least MVP systems enumerated
- [ ] At least 1 GDD in `design/gdd/` (beyond game-concept.md and systems-index.md)
- [ ] All MVP-tier GDDs exist in `design/gdd/` and individually pass `/design-review`
- [ ] A cross-GDD review report exists in `design/gdd/` (from `/review-all-gdds`)
**Quality Checks:**
- [ ] GDD(s) pass design review (8 required sections present)
- [ ] System dependencies are mapped in the systems index
- [ ] All MVP GDDs pass individual design review (8 required sections, no MAJOR REVISION NEEDED verdict)
- [ ] `/review-all-gdds` verdict is not FAIL (cross-GDD consistency and design theory checks pass)
- [ ] All cross-GDD consistency issues flagged by `/review-all-gdds` are resolved or explicitly accepted
- [ ] System dependencies are mapped in the systems index and are bidirectionally consistent
- [ ] MVP priority tier is defined
- [ ] No stale GDD references flagged (older GDDs updated to reflect decisions made in later GDDs)
---
@@ -72,12 +76,32 @@ The project progresses through these stages:
**Required Artifacts:**
- [ ] Engine chosen (CLAUDE.md Technology Stack is not `[CHOOSE]`)
- [ ] Technical preferences configured (`.claude/docs/technical-preferences.md` populated)
- [ ] At least 1 Architecture Decision Record in `docs/architecture/`
- [ ] Engine reference docs exist in `docs/engine-reference/`
- [ ] At least 3 Architecture Decision Records in `docs/architecture/` covering
Foundation-layer systems (scene management, event architecture, save/load)
- [ ] Engine reference docs exist in `docs/engine-reference/[engine]/`
- [ ] Master architecture document exists at `docs/architecture/architecture.md`
- [ ] Architecture traceability index exists at `docs/architecture/architecture-traceability.md`
- [ ] `/architecture-review` has been run (a review report file exists in `docs/architecture/`)
- [ ] `design/accessibility-requirements.md` exists with accessibility tier committed
- [ ] `design/ux/interaction-patterns.md` exists (pattern library initialized, even if minimal)
**Quality Checks:**
- [ ] Architecture decisions cover core systems (rendering, input, state management)
- [ ] Technical preferences have naming conventions and performance budgets set
- [ ] Accessibility tier is defined and documented (even "Basic" is acceptable — undefined is not)
- [ ] At least one screen's UX spec started (often the main menu or core HUD is designed during Technical Setup)
- [ ] All ADRs have an **Engine Compatibility section** with engine version stamped
- [ ] All ADRs have a **GDD Requirements Addressed section** with explicit GDD linkage
- [ ] No ADR references APIs listed in `docs/engine-reference/[engine]/deprecated-apis.md`
- [ ] All HIGH RISK engine domains (per VERSION.md) have been explicitly addressed
in the architecture document or flagged as open questions
- [ ] Architecture traceability matrix has **zero Foundation layer gaps**
(all Foundation requirements must have ADR coverage before Pre-Production)
**Engine Validation** (read `docs/engine-reference/[engine]/VERSION.md` first):
- [ ] ADRs that touch post-cutoff engine APIs are flagged with Knowledge Risk: HIGH/MEDIUM
- [ ] `/architecture-review` engine audit shows no deprecated API usage
- [ ] All ADRs agree on the same engine version (no stale version references)
---
@@ -87,11 +111,44 @@ The project progresses through these stages:
- [ ] At least 1 prototype in `prototypes/` with a README
- [ ] First sprint plan exists in `production/sprints/`
- [ ] All MVP-tier GDDs from systems index are complete
- [ ] Master architecture document exists at `docs/architecture/architecture.md`
- [ ] At least 3 ADRs covering Foundation-layer decisions exist in `docs/architecture/`
- [ ] Control manifest exists at `docs/architecture/control-manifest.md`
(generated by `/create-control-manifest` from Accepted ADRs)
- [ ] Epics and stories defined in `production/epics/` with at least Foundation
and Core layer epics present (use `/create-epics-stories layer: foundation`
and `/create-epics-stories layer: core` to create them)
- [ ] Vertical Slice build exists and is playable (not just scope-defined)
- [ ] Vertical Slice has been playtested with at least 3 sessions (internal OK)
- [ ] Vertical Slice playtest report exists at `production/playtests/` or equivalent
- [ ] UX specs exist for key screens: main menu, core gameplay HUD (at `design/ux/`), pause menu
- [ ] HUD design document exists at `design/ux/hud.md` (if game has in-game HUD)
- [ ] All key screen UX specs have passed `/ux-review` (verdict APPROVED or NEEDS REVISION accepted)
**Quality Checks:**
- [ ] Prototype validates the core loop hypothesis
- [ ] Sprint plan references real work items from GDDs
- [ ] Vertical slice scope is defined
- [ ] **Core loop fun is validated** — playtest data confirms the central mechanic is enjoyable, not just functional. Explicitly check the Vertical Slice playtest report.
- [ ] UX specs cover all UI Requirements sections from MVP-tier GDDs
- [ ] Interaction pattern library documents patterns used in key screens
- [ ] Accessibility tier from `design/accessibility-requirements.md` is addressed in all key screen UX specs
- [ ] Sprint plan references real story file paths from `production/epics/`
(not just GDDs — stories must embed GDD req ID + ADR reference)
- [ ] **Vertical Slice is COMPLETE**, not just scoped — the build demonstrates the full core loop end-to-end. At least one complete [start → challenge → resolution] cycle works.
- [ ] Architecture document has no unresolved open questions in Foundation or Core layers
- [ ] All ADRs have Engine Compatibility sections stamped with the engine version
- [ ] All ADRs have ADR Dependencies sections (even if all fields are "None")
- [ ] `/bmad-bmm-check-implementation-readiness` has been run or equivalent manual
validation confirms GDDs + architecture + epics are coherent
- [ ] **Core fantasy is delivered** — at least one playtester independently described an experience that matches the Player Fantasy section of the core system GDDs (without being prompted).
**Vertical Slice Validation** (FAIL if any item is NO):
- [ ] A human has played through the core loop without developer guidance
- [ ] The game communicates what to do within the first 2 minutes of play
- [ ] No critical "fun blocker" bugs exist in the Vertical Slice build
- [ ] The core mechanic feels good to interact with (this is a subjective check — ask the user)
> **Note**: If any Vertical Slice Validation item is FAIL, the verdict is automatically FAIL
> regardless of other checks. Advancing without a validated Vertical Slice is the #1 cause of
> production failure in game development (per GDC postmortem data from 155 projects).
---
@@ -102,13 +159,21 @@ The project progresses through these stages:
- [ ] All core mechanics from GDD are implemented (cross-reference `design/gdd/` with `src/`)
- [ ] Main gameplay path is playable end-to-end
- [ ] Test files exist in `tests/`
- [ ] At least 1 playtest report (or `/playtest-report` has been run)
- [ ] At least 3 distinct playtest sessions documented in `production/playtests/`
- [ ] Playtest reports cover: new player experience, mid-game systems, and difficulty curve
- [ ] Fun hypothesis from Game Concept has been explicitly validated or revised
**Quality Checks:**
- [ ] Tests are passing (run test suite via Bash)
- [ ] No critical/blocker bugs in any bug tracker or known issues
- [ ] Core loop plays as designed (compare to GDD acceptance criteria)
- [ ] Performance is within budget (check technical-preferences.md targets)
- [ ] Playtest findings have been reviewed and critical fun issues addressed (not just documented)
- [ ] No "confusion loops" identified — no point in the game where >50% of playtesters got stuck without knowing why
- [ ] Difficulty curve matches the Difficulty Curve design doc (if one exists at `design/difficulty-curve.md`)
- [ ] All implemented screens have corresponding UX specs (no "designed in-code" screens)
- [ ] Interaction pattern library is up-to-date with all patterns used in implementation
- [ ] Accessibility compliance verified against committed tier in `design/accessibility-requirements.md`
---
@@ -229,9 +294,26 @@ Based on the verdict, suggest specific next steps:
- **No game concept?** → `/brainstorm` to create one
- **No systems index?** → `/map-systems` to decompose the concept into systems
- **Missing design docs?** → `/reverse-document` or delegate to `game-designer`
- **Missing ADRs?** → `/architecture-decision`
- **Small design change needed?** → `/quick-design` for changes under ~4 hours (bypasses full GDD pipeline)
- **No UX specs?** → `/ux-design [screen name]` to author specs, or `/team-ui [feature]` for full pipeline
- **UX specs not reviewed?** → `/ux-review [file]` or `/ux-review all` to validate
- **No accessibility requirements doc?** → create `design/accessibility-requirements.md` using the accessibility-requirements template
- **No interaction pattern library?** → `/ux-design patterns` to initialize it
- **GDDs not cross-reviewed?** → `/review-all-gdds` (run after all MVP GDDs are individually approved)
- **Cross-GDD consistency issues?** → fix flagged GDDs, then re-run `/review-all-gdds`
- **Missing ADRs?** → `/architecture-decision` for individual decisions
- **No master architecture doc?** → `/create-architecture` for the full blueprint
- **ADRs missing engine compatibility sections?** → Re-run `/architecture-decision`
or manually add Engine Compatibility sections to existing ADRs
- **Missing control manifest?** → `/create-control-manifest` (requires Accepted ADRs)
- **Missing epics/stories?** → `/create-epics-stories all` (requires control manifest)
- **Stories not implementation-ready?** → `/story-readiness` to validate stories before developers pick them up
- **Tests failing?** → delegate to `lead-programmer` or `qa-tester`
- **No playtest data?** → `/playtest-report`
- **Less than 3 playtest sessions?** → Run more playtests before advancing. Use `/playtest-report` to structure findings.
- **No Difficulty Curve doc?** → Consider creating one at `design/difficulty-curve.md` before polish
- **No player journey document?** → create `design/player-journey.md` using the player journey template
- **Need a quick sprint check?** → `/sprint-status` for current sprint progress snapshot
- **Performance unknown?** → `/perf-profile`
- **Not localized?** → `/localize`
- **Ready for release?** → `/launch-checklist`

213
.claude/skills/propagate-design-change/SKILL.md Normal file
View File

@@ -0,0 +1,213 @@
---
name: propagate-design-change
description: "When a GDD is revised, scans all ADRs and the traceability index to identify which architectural decisions are now potentially stale. Produces a change impact report and guides the user through resolution."
argument-hint: "[path/to/changed-gdd.md]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
context: fork
agent: technical-director
---
# Propagate Design Change
When a GDD changes, architectural decisions written against it may no longer be
valid. This skill finds every affected ADR, compares what the ADR assumed against
what the GDD now says, and guides the user through resolution.
**Usage:** `/propagate-design-change design/gdd/combat-system.md`
---
## 1. Validate Argument
A GDD path argument is **required**. If missing, fail with:
> "Usage: `/propagate-design-change design/gdd/[system].md`
> Provide the path to the GDD that was changed."
Verify the file exists. If not, fail with:
> "[path] not found. Check the path and try again."
---
## 2. Read the Changed GDD
Read the current GDD in full.
---
## 3. Read the Previous Version
Run git to get the previous committed version:
```bash
git show HEAD:design/gdd/[filename].md
```
If the file has no git history (new file), report:
> "No previous version in git — this appears to be a new GDD, not a revision.
> Nothing to propagate."
If git returns the previous version, do a conceptual diff:
- Identify sections that changed (new rules, removed rules, modified formulas,
changed acceptance criteria, changed tuning knobs)
- Identify sections that are unchanged
- Produce a change summary:
```
## Change Summary: [GDD filename]
Date of revision: [today]
Changed sections:
- [Section name]: [what changed — new rule, removed rule, formula modified, etc.]
Unchanged sections:
- [Section name]
Key changes affecting architecture:
- [Change 1 — likely to affect ADRs]
- [Change 2]
```
---
## 4. Load Architecture Inputs
Read all ADRs in `docs/architecture/`:
- For each ADR, read the full file
- Extract the "GDD Requirements Addressed" table
- Note which GDD documents and requirement IDs each ADR references
Read `docs/architecture/architecture-traceability.md` if it exists.
Report: "Loaded [N] ADRs. [M] reference [gdd filename]."
---
## 5. Impact Analysis
For each ADR that references the changed GDD:
Compare the ADR's "GDD Requirements Addressed" entries against the changed sections
of the GDD. For each referenced requirement:
1. **Locate the requirement** in the current GDD — does it still exist?
2. **Compare**: What did the GDD say when the ADR was written vs. what it says now?
3. **Assess the ADR decision**: Is the architectural decision still valid?
Classify each affected ADR as one of:
| Status | Meaning |
|--------|---------|
| ✅ **Still Valid** | The GDD change doesn't affect what this ADR decided |
| ⚠️ **Needs Review** | The GDD change may affect this ADR — human judgment needed |
| 🔴 **Likely Superseded** | The GDD change directly contradicts what this ADR assumed |
For each affected ADR, produce an impact entry:
```
### ADR-NNNN: [title]
Status: [Still Valid / Needs Review / Likely Superseded]
What the ADR assumed about this GDD:
"[relevant quote from the ADR's GDD Requirements Addressed section]"
What the GDD now says:
"[relevant quote from the current GDD]"
Assessment:
[Explanation of whether the ADR decision is still valid, and why]
Recommended action:
[Keep as-is | Review and update | Mark Superseded and write new ADR]
```
---
## 6. Present Impact Report
Present the full impact report to the user before asking for any action. Format:
```
## Design Change Impact Report
GDD: [filename]
Date: [today]
Changes detected: [N sections changed]
ADRs referencing this GDD: [M]
### Not Affected
[ADRs referencing this GDD whose decisions remain valid]
### Needs Review ([count])
[ADRs that may need updating]
### Likely Superseded ([count])
[ADRs whose assumptions are now contradicted]
```
---
## 7. Resolution Workflow
For each ADR marked "Needs Review" or "Likely Superseded", ask the user what to do:
Ask for each ADR in turn:
> "ADR-NNNN ([title]) — [status]. What would you like to do?"
> Options:
> - "Mark Superseded (I'll write a new ADR)" — updates ADR status line to `Superseded by: [pending]`
> - "Update in place (minor revision)" — opens the ADR for editing; note what to revise
> - "Keep as-is (the change doesn't actually affect this decision)"
> - "Skip for now (revisit later)"
For ADRs marked **Superseded**:
- Update the ADR's Status field: `Superseded by ADR-[next number] (pending — see change-impact-[date]-[system].md)`
- Ask: "May I update the status in [ADR filename]?"
---
## 8. Update Traceability Index
If `docs/architecture/architecture-traceability.md` exists:
- Add the changed GDD requirements to the "Superseded Requirements" table:
```markdown
## Superseded Requirements
| Date | GDD | Requirement | Changed To | ADRs Affected | Resolution |
|------|-----|-------------|------------|---------------|------------|
| [date] | [gdd] | [old requirement text] | [new requirement text] | ADR-NNNN | [Superseded/Updated/Valid] |
```
Ask: "May I update the traceability index?"
---
## 9. Output Change Impact Document
Ask: "May I write the change impact report to `docs/architecture/change-impact-[date]-[system-slug].md`?"
The document contains:
- The change summary from step 3
- The full impact analysis from step 5
- Resolution decisions made in step 7
- List of ADRs that need to be written or updated
---
## 10. Follow-Up Actions
Based on the resolution decisions, suggest:
- **ADRs marked Superseded**: "Run `/architecture-decision [title]` to write the
replacement ADR. Then re-run `/propagate-design-change` to verify coverage."
- **ADRs to update in place**: List the specific fields to update in each ADR
- **If many ADRs affected**: "Run `/architecture-review` after all ADRs are updated
to verify the full traceability matrix is still coherent."
---
## Collaborative Protocol
1. **Read silently** — compute the full impact before presenting anything
2. **Show the full report first** — let the user see the scope before asking for action
3. **Ask per-ADR** — don't batch decisions; each affected ADR may need different treatment
4. **Ask before writing** — always confirm before modifying any file
5. **Non-destructive** — never delete ADR content; only add "Superseded by" notes

263
.claude/skills/quick-design/SKILL.md Normal file
View File

@@ -0,0 +1,263 @@
---
name: quick-design
description: "Lightweight design spec for small changes — tuning adjustments, minor mechanics, balance tweaks. Skips full GDD authoring when a system GDD already exists or the change is too small to warrant one. Produces a Quick Design Spec that embeds directly into story files."
argument-hint: "[brief description of the change]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit
context: fork
---
# Quick Design
This is the **lightweight design path** for changes that don't need a full GDD.
Full GDD authoring via `/design-system` is the heavyweight path. Use this skill
for work under approximately 4 hours of implementation — tuning adjustments,
minor behavioral tweaks, small additions to existing systems, or standalone
features too small to warrant a full document.
**Output:** `design/quick-specs/[name]-[date].md`
**When to run:** Anytime a change is too small for `/design-system` but too
meaningful to implement without a written rationale.
---
## 1. Classify the Change
First, read the argument and determine which category this change falls into:
- **Tuning** — changing numbers or balance values in an existing system with no
behavioral change (most minimal path). Example: "increase jump height from 5
to 6 units", "reduce enemy patrol speed by 10%".
- **Tweak** — a small behavioral change to an existing system that introduces no
new states, branches, or systems. Example: "make dash invincible on frame 1",
"allow combo to cancel into roll".
- **Addition** — adding a small mechanic to an existing system that may introduce
1-2 new states or interactions. Example: "add a parry window to the block
mechanic", "add a charge variant to the basic attack".
- **New Small System** — a standalone feature small enough that it has no
existing GDD and is under approximately one week of implementation work.
Example: "achievement popup system", "simple day/night visual cycle".
If the change does NOT fit these categories — it introduces a new system with
significant cross-system dependencies, requires more than one week of
implementation, or fundamentally alters an existing system's core rules — stop
and redirect to `/design-system` instead.
Present the classification to the user and confirm it is correct before
proceeding. If there is no argument, ask the user to describe the change.
---
## 2. Context Scan
Before drafting anything, read the relevant context:
- Search `design/gdd/` for the GDD most relevant to this change. Read the
sections that this change would affect.
- Read `design/gdd/systems-index.md` to understand where this system sits in
the dependency graph and what tier it belongs to.
- Check `design/quick-specs/` for any prior quick specs that touched this
system — avoid contradicting them.
- If this is a Tuning change, also check `assets/data/` for the data file that
holds the relevant values.
Report what was found: "Found GDD at [path]. Relevant section: [section name].
No conflicting quick specs found." (or note any conflicts found.)
---
## 3. Draft the Quick Design Spec
Use the appropriate spec format for the change category.
### For Tuning changes
Produce a single table:
```markdown
# Quick Design Spec: [Title]
**Type**: Tuning
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md` — Tuning Knobs section
**Date**: [today]
## Change
| Parameter | Old Value | New Value | Rationale |
|-----------|-----------|-----------|-----------|
| [param] | [old] | [new] | [why] |
## Tuning Knob Mapping
Maps to GDD Tuning Knob: [knob name and its documented range].
New value is [within / at the edge of / outside] the documented range.
[If outside: explain why the range should be extended.]
## Acceptance Criteria
- [ ] [Parameter] reads [new value] from `assets/data/[file]`
- [ ] Behavior difference is observable in [specific context]
- [ ] No regression in [related behavior]
```
### For Tweak and Addition changes
```markdown
# Quick Design Spec: [Title]
**Type**: [Tweak / Addition]
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md`
**Date**: [today]
## Change Summary
[1-2 sentences describing what changes and why.]
## Motivation
[Why is this change needed? What player experience problem does it solve?
Reference the relevant MDA aesthetic or player feedback if applicable.]
## Design Delta
Current GDD says (quoting `design/gdd/[filename].md`, [section]):
> [exact quote of the relevant rule or description]
This spec changes that to:
[New rule or description, written with the same precision as a GDD Detailed
Rules section. A programmer should be able to implement from this text alone.]
## New Rules / Values
[Full unambiguous statement of the replacement content. If this introduces
new states, list them. If it introduces new parameters, define their ranges.]
## Affected Systems
| System | Impact | Action Required |
|--------|--------|-----------------|
| [system] | [how it is affected] | [update GDD / update data file / no action] |
## Acceptance Criteria
- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]
- [ ] No regression: [the original behavior this must not break]
## GDD Update Required?
[Yes / No]
[If yes: which file, which section, and what the update should say.]
```
### For New Small System changes
Use a trimmed GDD structure. Include only the sections that are directly
necessary — skip Player Fantasy, full Formulas, and Edge Cases unless the
system specifically requires them.
```markdown
# Quick Design Spec: [Title]
**Type**: New Small System
**Scope**: [1-2 sentence description of what this system does and doesn't do]
**Date**: [today]
**Estimated Implementation**: [hours]
## Overview
[One paragraph a new team member could understand. What does this system do,
when does it activate, and what does it produce?]
## Core Rules
[Unambiguous rules for the system. Use numbered lists for sequential behavior
and bullet lists for conditions. Be precise enough that a programmer can
implement without asking questions.]
## Tuning Knobs
| Knob | Default | Range | Category | Rationale |
|------|---------|-------|----------|-----------|
| [name] | [value] | [min–max] | [feel/curve/gate] | [why this default] |
All values must live in `assets/data/[appropriate-file].json`, not hardcoded.
## Acceptance Criteria
- [ ] [Functional criterion: does the right thing]
- [ ] [Functional criterion: handles the edge case]
- [ ] [Experiential criterion: feels right — what a playtest validates]
- [ ] [Regression criterion: does not break adjacent system]
## Systems Index
This system is not currently in `design/gdd/systems-index.md`.
[If it should be added: suggest which layer and priority tier.]
[If it is too small to track: state "This system is below systems-index
tracking threshold — quick spec is sufficient."]
```
---
## 4. Approval and Filing
Present the draft to the user in full. Then ask:
"May I write this Quick Design Spec to
`design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md`?"
Use today's date in the filename. The title should be a kebab-case description
of the change (e.g., `jump-height-tuning-2026-03-10`,
`parry-window-addition-2026-03-10`).
If yes, create the `design/quick-specs/` directory if it does not exist, then
write the file.
If a GDD update is required (flagged in the spec), ask separately after
writing the quick spec:
"This spec modifies rules in [System Name]. May I update
`design/gdd/[filename].md` — specifically the [section name] section?"
Show the exact text that would be changed (old vs. new) before asking. Do not
make GDD edits without explicit approval.
---
## 5. Handoff
After writing the file, output:
```
Quick Design Spec written to: design/quick-specs/[filename].md
Type: [Tuning / Tweak / Addition / New Small System]
System: [system name]
GDD update: [Required — pending approval / Applied / Not required]
Next step: This spec is ready for `/story-readiness` validation before
implementation. Reference this spec in the story's GDD Reference field.
```
### Pipeline Notes
Quick Design Specs **bypass** `/design-review` and `/review-all-gdds` by
design. They are for small, low-risk, well-scoped changes where the cost of
the full review pipeline exceeds the risk of the change itself.
Redirect to the full pipeline if any of the following are true:
- The change adds a new system that belongs in the systems index
- The change significantly alters cross-system behavior or a system's
contracts with other systems
- The change introduces new player-facing mechanics that affect the
game's MDA aesthetic balance
- Implementation is likely to exceed one week of work
In those cases: "This change has grown beyond quick-spec scope. I recommend
using `/design-system` to author a full GDD for this."

440
.claude/skills/review-all-gdds/SKILL.md Normal file
View File

@@ -0,0 +1,440 @@
---
name: review-all-gdds
description: "Holistic cross-GDD consistency and game design review. Reads all system GDDs simultaneously and checks for contradictions between them, stale references, ownership conflicts, formula incompatibilities, and game design theory violations (dominant strategies, economic imbalance, cognitive overload, pillar drift). Run after all MVP GDDs are written, before architecture begins."
argument-hint: "[focus: full | consistency | design-theory | since-last-review]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash
context: fork
agent: game-designer
---
# Review All GDDs
This skill reads every system GDD simultaneously and performs two complementary
reviews that cannot be done per-GDD in isolation:
1. **Cross-GDD Consistency** — contradictions, stale references, and ownership
conflicts between documents
2. **Game Design Holism** — issues that only emerge when you see all systems
together: dominant strategies, broken economies, cognitive overload, pillar
drift, competing progression loops
**This is distinct from `/design-review`**, which reviews one GDD for internal
completeness. This skill reviews the *relationships* between all GDDs.
**When to run:**
- After all MVP-tier GDDs are individually approved
- After any GDD is significantly revised mid-production
- Before `/create-architecture` begins (architecture built on inconsistent GDDs
inherits those inconsistencies)
**Argument modes:**
- **No argument / `full`**: Both consistency and design theory passes
- **`consistency`**: Cross-GDD consistency checks only (faster)
- **`design-theory`**: Game design holism checks only
- **`since-last-review`**: Only GDDs modified since the last review report (git-based)
---
## Phase 1: Load Everything
Read all design documents before any analysis:
1. `design/gdd/game-concept.md` — game vision, core loop, MVP definition
2. `design/gdd/game-pillars.md` if it exists — design pillars and anti-pillars
3. `design/gdd/systems-index.md` — authoritative system list, layers, dependencies, status
4. **Every system GDD in `design/gdd/`** — read completely (skip game-concept.md
and systems-index.md — those are read above)
For `since-last-review` mode: run `git log --name-only` to identify GDDs
modified since the last review report file was written. Only load those GDDs
plus any GDDs they depend on.
Report: "Loaded [N] system GDDs covering [M] systems. Pillars: [list]. Anti-pillars: [list]."
If fewer than 2 system GDDs exist, stop:
> "Cross-GDD review requires at least 2 system GDDs. Write more GDDs first,
> then re-run `/review-all-gdds`."
---
## Phase 2: Cross-GDD Consistency
Work through every pair and group of GDDs to find contradictions and gaps.
### 2a: Dependency Bidirectionality
For every GDD's Dependencies section, check that every listed dependency is
reciprocal:
- If GDD-A lists "depends on GDD-B", check that GDD-B lists GDD-A as a dependent
- If GDD-A lists "depended on by GDD-C", check that GDD-C lists GDD-A as a dependency
- Flag any one-directional dependency as a consistency issue
```
⚠️ Dependency Asymmetry
combat.md lists: Depends On → health-system.md
health-system.md does NOT list combat.md as a dependent
→ One of these documents has a stale dependency section
```
### 2b: Rule Contradictions
For each game rule, mechanic, or constraint defined in any GDD, check whether
any other GDD defines a contradicting rule for the same situation:
Categories to scan:
- **Health and damage**: Does any GDD say damage floor is 1? Does any other say
armour can reduce damage to 0? These contradict.
- **Resource ownership**: If two GDDs both define how a shared resource (gold,
stamina, mana) accumulates or depletes, do they agree?
- **State transitions**: If GDD-A describes what happens when a character dies,
does GDD-B's description of the same event agree?
- **Timing**: If GDD-A says "X happens on the same frame", does GDD-B assume
it happens asynchronously?
- **Stacking rules**: If GDD-A says status effects stack, does GDD-B assume
they don't?
```
🔴 Rule Contradiction
combat.md: "Minimum damage after armour reduction is 1"
status-effects.md: "Poison ignores armour and can reduce health by any amount,
including to 0"
→ These rules directly contradict. Which GDD is authoritative?
```
### 2c: Stale References
For every cross-document reference (GDD-A mentions a mechanic, value, or
system name from GDD-B), verify the referenced element still exists in GDD-B
with the same name and behaviour:
- If GDD-A says "combo multiplier from the combat system feeds into score", check
that the combat GDD actually defines a combo multiplier that outputs to score
- If GDD-A references "the XP curve defined in progression.md", check that
progression.md actually has an XP curve, not a flat-level system
- If GDD-A was written before GDD-B and assumed a mechanic that GDD-B later
designed differently, flag GDD-A as containing a stale reference
```
⚠️ Stale Reference
inventory.md (written first): "Item weight uses the encumbrance formula
from movement.md"
movement.md (written later): Defines no encumbrance formula — uses a flat
carry limit instead
→ inventory.md references a formula that doesn't exist
```
### 2d: Data and Tuning Knob Ownership Conflicts
Two GDDs should not both claim to own the same data or tuning knob. Scan all
Tuning Knobs sections across all GDDs and flag duplicates:
```
⚠️ Ownership Conflict
combat.md Tuning Knobs: "base_damage_multiplier — controls damage scaling"
progression.md Tuning Knobs: "damage_multiplier — scales with player level"
→ Two GDDs define multipliers on the same output. Which owns the final value?
This will produce either a double-application bug or a design conflict.
```
### 2e: Formula Compatibility
For GDDs whose formulas are connected (output of one feeds input of another),
check that the output range of the upstream formula is within the expected
input range of the downstream formula:
- If combat.md outputs damage values between 1–500, and the health system is
designed for health values between 10–100, a one-hit kill is almost always
possible — is that intended?
- If the economy GDD expects item prices between 1–1000 gold, and the
progression GDD generates gold at a rate of 50–5000 per session, the
economy will either be trivially easy or permanently locked — is that intended?
Flag incompatibilities as CONCERNS (design judgment needed, not necessarily wrong):
```
⚠️ Formula Range Mismatch
combat.md: Max damage output = 500 (at max level, max gear)
health-system.md: Base player health = 100, max health = 250
→ Late-game combat can one-shot a max-health player in a single hit.
Is this intentional? If not, either damage ceiling or health ceiling needs adjustment.
```
### 2f: Acceptance Criteria Cross-Check
Scan Acceptance Criteria sections across all GDDs for contradictions:
- GDD-A criteria: "Player cannot die from a single hit"
- GDD-B criteria: "Boss attack deals 150% of player max health"
These acceptance criteria cannot both pass simultaneously.
---
## Phase 3: Game Design Holism
Review all GDDs together through the lens of game design theory and player
psychology. These are issues that individual GDD reviews cannot catch because
they require seeing all systems at once.
### 3a: Progression Loop Competition
A game should have one dominant progression loop that players feel is "the
point" of the game, with supporting loops that feed into it. When multiple
systems compete equally as the primary progression driver, players don't know
what the game is about.
Scan all GDDs for systems that:
- Award the player's primary resource (XP, levels, prestige, unlocks)
- Define themselves as the "core" or "main" loop
- Have comparable depth and time investment to other systems doing the same
```
⚠️ Competing Progression Loops
combat.md: Awards XP, unlocks abilities, is described as "the core loop"
crafting.md: Awards XP, unlocks recipes, is described as "the primary activity"
exploration.md: Awards XP, unlocks map areas, described as "the main driver"
→ Three systems all claim to be the primary progression loop and all award
the same primary currency. Players will optimise one and ignore the others.
Consider: one primary loop with the others as support systems.
```
### 3b: Player Attention Budget
Count how many systems require active player attention simultaneously during
a typical session. Each actively-managed system costs attention:
- Active = player must make decisions about this system regularly during play
- Passive = system runs automatically, player sees results but doesn't manage it
More than 3-4 simultaneously active systems creates cognitive overload for most
players. Present the count and flag if it exceeds 4 concurrent active systems:
```
⚠️ Cognitive Load Risk
Simultaneously active systems during combat:
1. combat.md — combat decisions (active)
2. stamina-system.md — stamina management (active)
3. status-effects.md — status tracking (active)
4. inventory.md — mid-combat item use (active)
5. ability-system.md — ability cooldown management (active)
6. companion-ai.md — companion command decisions (active)
→ 6 simultaneously active systems during the core loop.
Research suggests 3-4 is the comfortable limit for most players.
Consider: which of these can be made passive or simplified?
```
### 3c: Dominant Strategy Detection
A dominant strategy makes other strategies irrelevant — players discover it,
use it exclusively, and find the rest of the game boring. Look for:
- **Resource monopolies**: One strategy generates a resource significantly
faster than all others
- **Risk-free power**: A strategy that is both high-reward and low-risk
(if high-risk strategies exist, they need proportionally higher reward)
- **No trade-offs**: An option that is superior in all dimensions to all others
- **Obvious optimal path**: If any progression choice is "clearly correct",
the others aren't real choices
```
⚠️ Potential Dominant Strategy
combat.md: Ranged attacks deal 80% of melee damage with no risk
combat.md: Melee attacks deal 100% damage but require close range
→ Unless melee has a significant compensating advantage (AOE, stagger,
resource regeneration), ranged is dominant — higher safety, only 20% less
damage. Consider what melee offers that ranged cannot.
```
### 3d: Economic Loop Analysis
Identify all resources across all GDDs (gold, XP, crafting materials, stamina,
health, mana, etc.). For each resource, map its **sources** (how players gain
it) and **sinks** (how players spend it).
Flag dangerous economic conditions:
| Condition | Sign | Risk |
|-----------|------|------|
| **Infinite source, no sink** | Resource accumulates indefinitely | Late game becomes trivially easy |
| **Sink, no source** | Resource drains to zero | System becomes unavailable |
| **Source >> Sink** | Surplus accumulates | Resource becomes meaningless |
| **Sink >> Source** | Constant scarcity | Frustration and gatekeeping |
| **Positive feedback loop** | More resource → easier to earn more | Runaway leader, snowball |
| **No catch-up** | Falling behind accelerates deficit | Unrecoverable states |
```
🔴 Economic Imbalance: Unbounded Positive Feedback
gold economy:
Sources: monster drops (scales with player power), merchant selling (unlimited)
Sinks: equipment purchase (one-time), ability upgrades (finite count)
→ After equipment and abilities are purchased, gold has no sink.
Infinite surplus. Gold becomes meaningless mid-game.
Add ongoing gold sinks (upkeep, consumables, cosmetics, gambling).
```
### 3e: Difficulty Curve Consistency
When multiple systems scale with player progression, they must scale in
compatible directions and at compatible rates. Mismatched scaling curves
create unintended difficulty spikes or trivialisations.
For each system that scales over time, extract:
- What scales (enemy health, player damage, resource cost, area size)
- How it scales (linear, exponential, stepped)
- When it scales (level, time, area)
Compare all scaling curves. Flag mismatches:
```
⚠️ Difficulty Curve Mismatch
combat.md: Enemy health scales exponentially with area (×2 per area)
progression.md: Player damage scales linearly with level (+10% per level)
→ By area 5, enemies have 32× base health; player deals ~1.5× base damage.
The gap widens indefinitely. Late areas will become inaccessibly difficult
unless the curves are reconciled.
```
### 3f: Pillar Alignment
Every system should clearly serve at least one design pillar. A system that
serves no pillar is "scope creep by design" — it's in the game but not in
service of what the game is trying to be.
For each GDD system, check its Player Fantasy section against the design pillars.
Flag any system whose stated fantasy doesn't map to any pillar:
```
⚠️ Pillar Drift
fishing-system.md: Player Fantasy — "peaceful, meditative activity"
Pillars: "Brutal Combat", "Tense Survival", "Emergent Stories"
→ The fishing system serves none of the three pillars. Either add a pillar
that covers it, redesign it to serve an existing pillar, or cut it.
```
Also check anti-pillars — flag any system that does what an anti-pillar
explicitly says the game will NOT do:
```
🔴 Anti-Pillar Violation
Anti-Pillar: "We will NOT have linear story progression — player defines their path"
main-quest.md: Defines a 12-chapter linear story with mandatory sequence
→ This system directly violates the defined anti-pillar.
```
### 3g: Player Fantasy Coherence
The player fantasies across all systems should be compatible — they should
reinforce a consistent identity for what the player IS in this game. Conflicting
player fantasies create identity confusion.
```
⚠️ Player Fantasy Conflict
combat.md: "You are a ruthless, precise warrior — every kill is earned"
dialogue.md: "You are a charismatic diplomat — violence is always avoidable"
exploration.md: "You are a reckless adventurer — diving in without a plan"
→ Three systems present incompatible identities. Players will feel the game
doesn't know what it wants them to be. Consider: do these fantasies serve
the same core identity from different angles, or do they genuinely conflict?
```
---
## Phase 4: Output the Review Report
```
## Cross-GDD Review Report
Date: [date]
GDDs Reviewed: [N]
Systems Covered: [list]
---
### Consistency Issues
#### Blocking (must resolve before architecture begins)
🔴 [Issue title]
[What GDDs are involved, what the contradiction is, what needs to change]
#### Warnings (should resolve, but won't block)
⚠️ [Issue title]
[What GDDs are involved, what the concern is]
---
### Game Design Issues
#### Blocking
🔴 [Issue title]
[What the problem is, which GDDs are involved, design recommendation]
#### Warnings
⚠️ [Issue title]
[What the concern is, which GDDs are affected, recommendation]
---
### GDDs Flagged for Revision
| GDD | Reason | Type | Priority |
|-----|--------|------|----------|
| combat.md | Rule contradiction with status-effects.md | Consistency | Blocking |
| inventory.md | Stale reference to nonexistent formula | Consistency | Blocking |
| fishing.md | No pillar alignment | Design Theory | Warning |
---
### Verdict: [PASS / CONCERNS / FAIL]
PASS: No blocking issues. Warnings present but don't prevent architecture.
CONCERNS: Warnings present that should be resolved but are not blocking.
FAIL: One or more blocking issues must be resolved before architecture begins.
### If FAIL — required actions before re-running:
[Specific list of what must change in which GDD]
```
---
## Phase 5: Write Report and Flag GDDs
Ask: "May I write this review to `design/gdd/gdd-cross-review-[date].md`?"
If any GDDs are flagged for revision:
Ask: "Should I update the systems index to mark these GDDs as needing revision?"
- If yes: for each flagged GDD, update its Status field in systems-index.md
to "Needs Revision (Cross-GDD Review)" with a short note on why.
Ask approval before writing.
---
## Phase 6: Handoff
After the report is written:
- **If FAIL**: "Resolve the blocking issues in the flagged GDDs, then re-run
`/review-all-gdds` to confirm they're cleared before starting architecture."
- **If CONCERNS**: "Warnings are present but not blocking. You may proceed to
`/create-architecture` and resolve warnings in parallel, or resolve them now
for a cleaner baseline."
- **If PASS**: "GDDs are internally consistent. Run `/create-architecture` to
begin translating the design into an engine-aware technical blueprint."
Gate reminder: `/gate-check technical-setup` now requires a PASS or CONCERNS
verdict from this review before architecture work can begin.
---
## Collaborative Protocol
1. **Read silently** — load all GDDs before presenting anything
2. **Show everything** — present the full consistency and design theory analysis
before asking for any action
3. **Distinguish blocking from advisory** — not every issue needs to block
architecture; be clear about which do
4. **Don't make design decisions** — flag contradictions and options, but never
unilaterally decide which GDD is "right"
5. **Ask before writing** — confirm before writing the report or updating the
systems index
6. **Be specific** — every issue must cite the exact GDD, section, and text
involved; no vague warnings

167
.claude/skills/sprint-status/SKILL.md Normal file
View File

@@ -0,0 +1,167 @@
---
name: sprint-status
description: "Fast sprint status check. Reads the current sprint plan, scans story files for status, and produces a concise progress snapshot with burndown assessment and emerging risks. Run at any time during a sprint for quick situational awareness."
argument-hint: "[sprint-number or blank for current]"
user-invocable: true
allowed-tools: Read, Glob, Grep
---
# Sprint Status
This is a fast situational awareness check, not a sprint review. It reads the
current sprint plan and story files, scans for status markers, and produces a
concise snapshot in under 30 lines. For detailed sprint management, use
`/sprint-plan update` or `/milestone-review`.
**This skill is read-only.** It never proposes changes, never asks to write
files, and makes at most one concrete recommendation.
---
## 1. Find the Sprint
- If an argument is given (e.g., `/sprint-status 3`), search
`production/sprints/` for a file matching `sprint-03.md`, `sprint-3.md`,
or similar. Report which file was found.
- If no argument is given, find the most recently modified file in
`production/sprints/` and treat it as the current sprint.
- If `production/sprints/` does not exist or is empty, report: "No sprint
files found. Start a sprint with `/sprint-plan new`." Then stop.
Read the sprint file in full. Extract:
- Sprint number and goal
- Start date and end date
- All story or task entries with their priority (Must Have / Should Have /
Nice to Have), owner, and estimate
---
## 2. Calculate Days Remaining
Using today's date and the sprint end date from the sprint file, calculate:
- Total sprint days (end minus start)
- Days elapsed
- Days remaining
- Percentage of time consumed
If the sprint file does not include explicit dates, note "Sprint dates not
found — burndown assessment skipped."
---
## 3. Scan Story Status
For each story or task referenced in the sprint plan:
1. If the entry references a story file path, check if the file exists.
Read the file and scan for status markers: DONE, COMPLETE, IN PROGRESS,
BLOCKED, NOT STARTED (case-insensitive).
2. If the entry has no file path (inline task in the sprint plan), scan the
sprint plan itself for status markers next to that entry.
3. If no status marker is found, classify as NOT STARTED.
4. If a file is referenced but does not exist, classify as MISSING and note it.
Optionally (fast check only — do not do a deep scan): grep `src/` for a
directory or file name that matches the story's system slug to check for
implementation evidence. This is a hint only, not a definitive status.
---
## 4. Burndown Assessment
Calculate:
- Tasks complete (DONE or COMPLETE)
- Tasks in progress (IN PROGRESS)
- Tasks blocked (BLOCKED)
- Tasks not started (NOT STARTED or MISSING)
- Completion percentage: (complete / total) * 100
Assess burndown by comparing completion percentage to time consumed percentage:
- **On Track**: completion % is within 10 points of time consumed % or ahead
- **At Risk**: completion % is 10-25 points behind time consumed %
- **Behind**: completion % is more than 25 points behind time consumed %
If dates are unavailable, skip the burndown assessment and report "On Track /
At Risk / Behind: unknown — sprint dates not found."
---
## 5. Output
Keep the total output to 30 lines or fewer. Use this format:
```markdown
## Sprint [N] Status — [Today's Date]
**Sprint Goal**: [from sprint plan]
**Days Remaining**: [N] of [total] ([% time consumed])
### Progress: [complete/total] tasks ([%])
| Story / Task | Priority | Status | Owner | Blocker |
|----------------------|------------|-------------|---------|----------------|
| [title] | Must Have | DONE | [owner] | |
| [title] | Must Have | IN PROGRESS | [owner] | |
| [title] | Must Have | BLOCKED | [owner] | [brief reason] |
| [title] | Should Have| NOT STARTED | [owner] | |
### Burndown: [On Track / At Risk / Behind]
[1-2 sentences. If behind: which Must Haves are at risk. If on track: confirm
and note any Should Haves the team could pull.]
### Must-Haves at Risk
[List any Must Have stories that are BLOCKED or NOT STARTED with less than
40% of sprint time remaining. If none, write "None."]
### Emerging Risks
[Any risks visible from the story scan: missing files, cascading blockers,
stories with no owner. If none, write "None identified."]
### Recommendation
[One concrete action, or "Sprint is on track — no action needed."]
```
---
## 6. Fast Escalation Rules
Apply these rules before outputting, and place the flag at the TOP of the
output if triggered (above the status table):
**Critical flag** — if Must Have stories are BLOCKED or NOT STARTED and
less than 40% of the sprint time remains:
```
SPRINT AT RISK: [N] Must Have stories are not complete with [X]% of sprint
time remaining. Recommend replanning with `/sprint-plan update`.
```
**Completion flag** — if all Must Have stories are DONE:
```
All Must Haves complete. Team can pull from Should Have backlog.
```
**Missing stories flag** — if any referenced story files do not exist:
```
NOTE: [N] story files referenced in the sprint plan are missing.
Run `/story-readiness sprint` to validate story file coverage.
```
---
## Collaborative Protocol
This skill is read-only. It reports observed facts from files on disk.
- It does not update the sprint plan
- It does not change story status
- It does not propose scope cuts (that is `/sprint-plan update`)
- It makes at most one recommendation per run
For more detail on a specific story, the user can read the story file directly
or run `/story-readiness [path]`.
For sprint replanning, use `/sprint-plan update`.
For end-of-sprint retrospective, use `/milestone-review`.

248
.claude/skills/story-done/SKILL.md Normal file
View File

@@ -0,0 +1,248 @@
---
name: story-done
description: "End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint."
argument-hint: "[story-file-path]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Edit
---
# Story Done
This skill closes the loop between design and implementation. Run it at the end
of implementing any story. It ensures every acceptance criterion is verified
before the story is marked done, GDD and ADR deviations are explicitly
documented rather than silently introduced, code review is prompted rather than
forgotten, and the story file reflects actual completion status.
**Output:** Updated story file (Status: Complete) + surfaced next story.
---
## Phase 1: Find the Story
**If a file path is provided** (e.g., `/story-done production/epics/core/story-damage-calculator.md`):
read that file directly.
**If no argument is provided:**
1. Check `production/session-state/active.md` for the currently active story.
2. If not found there, read the most recent file in `production/sprints/` and
look for stories marked IN PROGRESS.
3. If multiple in-progress stories are found, use `AskUserQuestion`:
- "Which story are we completing?"
- Options: list the in-progress story file names.
4. If no story can be found, ask the user to provide the path.
---
## Phase 2: Read the Story
Read the full story file. Extract and hold in context:
- **Story name and ID**
- **GDD Requirement ID(s)** referenced
- **ADR reference(s)** referenced
- **Acceptance Criteria** — the complete list (every checkbox item)
- **Implementation files** — files listed under "files to create/modify"
- **Engine notes** — any engine-specific constraints noted
- **Definition of Done** — if present, the story-level DoD
- **Estimated vs actual scope** — if an estimate was noted
Also read:
- The referenced GDD section — just the acceptance criteria and key rules, not
the full document
- The referenced ADR(s) — just the Decision and Consequences sections
---
## Phase 3: Verify Acceptance Criteria
For each acceptance criterion in the story, attempt verification using one of
three methods:
### Automatic verification (run without asking)
- **File existence check**: `Glob` for files the story said would be created.
- **Test pass check**: if a test file path is mentioned, run it via `Bash`.
- **No hardcoded values check**: `Grep` for numeric literals in gameplay code
paths that should be in config files.
- **No hardcoded strings check**: `Grep` for player-facing strings in `src/`
that should be in localization files.
- **Dependency check**: if a criterion says "depends on X", check that X exists.
### Manual verification with confirmation (use `AskUserQuestion`)
- Criteria about subjective qualities ("feels responsive", "animations play correctly")
- Criteria about gameplay behaviour ("player takes damage when...", "enemy responds to...")
- Performance criteria ("completes within Xms") — ask if profiled or accept as assumed
Batch up to 4 manual verification questions into a single `AskUserQuestion` call:
```
question: "Does [criterion]?"
options: "Yes — passes", "No — fails", "Not tested yet"
```
### Unverifiable (flag without blocking)
- Criteria that require a full game build to test (end-to-end gameplay scenarios)
- Mark as: `DEFERRED — requires playtest session`
---
## Phase 4: Check for Deviations
Compare the implementation against the design documents.
Run these checks automatically:
1. **GDD rules check**: Read the GDD section referenced in the story. `Grep` the
implemented files for key function names, data structures, or class names
mentioned in the GDD. If the GDD specifies a formula, check for recognizable
variable names from that formula.
2. **ADR constraints check**: Read the referenced ADR's Decision section. Check
for forbidden patterns from `docs/architecture/control-manifest.md` (if it
exists). `Grep` for patterns explicitly forbidden in the ADR.
3. **Hardcoded values check**: `Grep` the implemented files for numeric literals
in gameplay logic that should be in data files.
4. **Scope check**: Did the implementation touch files outside the story's stated
scope? (files not listed in "files to create/modify")
For each deviation found, categorize:
- **BLOCKING** — implementation contradicts the GDD or ADR (must fix before
marking complete)
- **ADVISORY** — implementation drifts slightly from spec but is functionally
equivalent (document, user decides)
- **OUT OF SCOPE** — additional files were touched beyond the story's stated
boundary (flag for awareness — may be valid or scope creep)
---
## Phase 5: Code Review Prompt
After criteria verification and deviation check, use `AskUserQuestion`:
```
question: "Implementation verified. Run /code-review on the changed files?"
options:
- "Yes — run /code-review now"
- "Skip — I'll review manually"
- "Skip — already reviewed"
```
If "Yes": list the files to review and say:
"Run `/code-review [file1] [file2]` to review the implementation before
marking complete."
Do not run code-review inline — surface it and let the developer decide when
to invoke it.
---
## Phase 6: Present the Completion Report
Before updating any files, present the full report:
```markdown
## Story Done: [Story Name]
**Story**: [file path]
**Date**: [today]
### Acceptance Criteria: [X/Y passing]
- [x] [Criterion 1] — auto-verified (test passes)
- [x] [Criterion 2] — confirmed
- [ ] [Criterion 3] — FAILS: [reason]
- [?] [Criterion 4] — DEFERRED: requires playtest
### Deviations
[NONE] OR:
- BLOCKING: [description] — [GDD/ADR reference]
- ADVISORY: [description] — user accepted / flagged for tech debt
### Scope
[All changes within stated scope] OR:
- Extra files touched: [list] — [note whether valid or scope creep]
### Verdict: COMPLETE / COMPLETE WITH NOTES / BLOCKED
```
**Verdict definitions:**
- **COMPLETE**: all criteria pass, no blocking deviations
- **COMPLETE WITH NOTES**: all criteria pass, advisory deviations documented
- **BLOCKED**: failing criteria or blocking deviations must be resolved first
If the verdict is **BLOCKED**: do not proceed to Phase 7. List what must be
fixed. Offer to help fix the blocking items.
---
## Phase 7: Update Story Status
Ask before writing: "May I update the story file to mark it Complete and log
the completion notes?"
If yes, edit the story file:
1. Update the status field: `Status: Complete`
2. Add a `## Completion Notes` section at the bottom:
```markdown
## Completion Notes
**Completed**: [date]
**Criteria**: [X/Y passing] ([any deferred items listed])
**Deviations**: [None] or [list of advisory deviations]
**Code Review**: [Pending / Complete / Skipped]
```
3. If advisory deviations exist, ask: "Should I log these as tech debt in
`docs/tech-debt-register.md`?"
---
## Phase 8: Surface the Next Story
After completion, help the developer keep momentum:
1. Read the current sprint plan from `production/sprints/`.
2. Find stories that are:
- Status: READY or NOT STARTED
- Not blocked by other incomplete stories
- In the Must Have or Should Have tier
Present:
```
### Next Up
The following stories are ready to pick up:
1. [Story name] — [1-line description] — Est: [X hrs]
2. [Story name] — [1-line description] — Est: [X hrs]
Run `/story-readiness [path]` to confirm a story is implementation-ready
before starting.
```
If no more stories are ready in this sprint:
"No more stories ready in this sprint. Consider running `/sprint-status` to
assess sprint health."
If all Must Have stories are complete:
"All Must Have stories are complete. Consider running `/milestone-review` or
pulling from the Should Have list."
---
## Collaborative Protocol
- **Never mark a story complete without user approval** — Phase 7 requires an
explicit "yes" before any file is edited.
- **Never auto-fix failing criteria** — report them and ask what to do.
- **Deviations are facts, not judgments** — present them neutrally; the user
decides if they are acceptable.
- **BLOCKED verdict is advisory** — the user can override and mark complete
anyway; document the risk explicitly if they do.
- Use `AskUserQuestion` for the code review prompt and for batching manual
criteria confirmations.

222
.claude/skills/story-readiness/SKILL.md Normal file
View File

@@ -0,0 +1,222 @@
---
name: story-readiness
description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps."
argument-hint: "[story-file-path or 'all' or 'sprint']"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: fork
---
# Story Readiness
This skill validates that a story file contains everything a developer needs
to begin implementation — no mid-sprint design interruptions, no guessing,
no ambiguous acceptance criteria. Run it before assigning a story.
**This skill is read-only.** It never edits story files. It reports findings
and asks whether the user wants help filling gaps.
**Output:** Verdict per story (READY / NEEDS WORK / BLOCKED) with a specific
gap list for each non-ready story.
---
## 1. Parse Arguments
- **Specific path** (e.g., `/story-readiness production/epics/combat/story-001-basic-attack.md`):
validate that single story file.
- **`sprint`**: read the current sprint plan from `production/sprints/` (most
recent file), extract every story path it references, validate each one.
- **`all`**: glob `production/epics/**/*.md`, exclude `EPIC.md` index files,
validate every story file found.
- **No argument**: ask the user which scope to validate.
If no argument is given, use `AskUserQuestion`:
- "What would you like to validate?"
- Options: "A specific story file", "All stories in the current sprint",
"All stories in production/epics/", "Stories for a specific epic"
Report the scope before proceeding: "Validating [N] story files."
---
## 2. Load Supporting Context
Before checking any stories, load reference documents once (not per-story):
- `design/gdd/systems-index.md` — to know which systems have approved GDDs
- `docs/architecture/control-manifest.md` — to know which manifest rules exist
(if the file does not exist, note it as missing once; do not re-flag per story)
- The current sprint file (if scope is `sprint`) — to identify Must Have /
Should Have priority for escalation decisions
---
## 3. Story Readiness Checklist
For each story file, evaluate every item below. A story is READY only if all
items pass or are explicitly marked N/A with a stated reason.
### Design Completeness
- [ ] **GDD requirement referenced**: The story includes a `design/gdd/` path
and quotes or links a specific requirement, acceptance criterion, or rule from
that GDD — not just the GDD filename. A link to the document without tracing
to a specific requirement does not pass.
- [ ] **Requirement is self-contained**: The acceptance criteria in the story
are understandable without opening the GDD. A developer should not need to
read a separate document to understand what DONE means.
- [ ] **Acceptance criteria are testable**: Each criterion is a specific,
observable condition — not "implement X" or "the system works correctly".
Bad example: "Implement the jump mechanic." Good example: "Jump reaches
max height of 5 units within 0.3 seconds when jump is held."
- [ ] **No acceptance criteria require judgment calls**: Criteria like
"feels responsive" or "looks good" are not testable without a defined
benchmark. These must be replaced with specific observable conditions or
playtest protocols.
### Architecture Completeness
- [ ] **ADR referenced or N/A stated**: The story references at least one
Accepted ADR, OR explicitly states "No ADR applies" with a brief reason.
A story with no ADR reference and no explicit N/A note fails this check.
- [ ] **Engine notes present**: For any post-cutoff engine API this story
is likely to touch, implementation notes or a verification requirement are
included. If the story clearly does not touch engine APIs (e.g., it is a
pure data/config change), "N/A — no engine API involved" is acceptable.
- [ ] **Control manifest rules noted**: Relevant layer rules from the control
manifest are referenced, OR "N/A — manifest not yet created" is stated.
This item auto-passes if `docs/architecture/control-manifest.md` does not
exist yet (do not penalize stories written before the manifest was created).
### Scope Clarity
- [ ] **Estimate present**: The story includes a size estimate (hours,
points, or a t-shirt size). A story with no estimate cannot be planned.
- [ ] **In-scope / Out-of-scope boundary stated**: The story states what
it does NOT include, either in an explicit Out of Scope section or in
language that makes the boundary unambiguous. Without this, scope creep
during implementation is likely.
- [ ] **Story dependencies listed**: If this story depends on other stories
being DONE first, those story IDs are listed. If there are no dependencies,
"None" is explicitly stated (not just omitted).
### Open Questions
- [ ] **No unresolved design questions**: The story does not contain text
flagged as "UNRESOLVED", "TBD", "TODO", "?", or equivalent markers in
any acceptance criterion, implementation note, or rule statement.
- [ ] **Dependency stories are not in DRAFT**: For each story listed as a
dependency, check if the file exists and does not have a DRAFT status. A
story that depends on a DRAFT or missing story is BLOCKED, not just
NEEDS WORK.
### Definition of Done
- [ ] **At least 3 testable acceptance criteria**: Fewer than 3 suggests
the story is either trivially small (should it be a story?) or under-specified.
- [ ] **Performance budget noted if applicable**: If this story touches any
part of the gameplay loop, rendering, or physics, a performance budget or
a "no performance impact expected — [reason]" note is present.
- [ ] **Test strategy noted**: The story states whether verification is by
unit test, manual test, or playtest. "Acceptance criteria verified by
[test type]" is sufficient.
---
## 4. Verdict Assignment
Assign one of three verdicts per story:
**READY** — All checklist items pass or have explicit N/A justifications.
The story can be assigned immediately.
**NEEDS WORK** — One or more checklist items fail, but all dependency stories
exist and are not DRAFT. The story can be fixed before assignment.
**BLOCKED** — One or more dependency stories are missing or in DRAFT state,
OR a critical design question (flagged UNRESOLVED in a criterion or rule) has
no owner. The story cannot be assigned until the blocker is resolved. Note:
a story that is BLOCKED may also have NEEDS WORK items — list both.
---
## 5. Output Format
### Single story output
```
## Story Readiness: [story title]
File: [path]
Verdict: [READY / NEEDS WORK / BLOCKED]
### Passing Checks (N/[total])
[list passing items briefly]
### Gaps
- [Checklist item]: [exact description of what is missing or wrong]
Fix: [specific text needed to resolve this gap]
### Blockers (if BLOCKED)
- [What is blocking]: [story ID or design question that must resolve first]
```
### Multiple story aggregate output
```
## Story Readiness Summary — [scope] — [date]
Ready: [N] stories
Needs Work: [N] stories
Blocked: [N] stories
### Ready Stories
- [story title] ([path])
### Needs Work
- [story title]: [primary gap — one line]
- [story title]: [primary gap — one line]
### Blocked Stories
- [story title]: Blocked by [story ID / design question]
---
[Full detail for each non-ready story follows, using the single-story format]
```
### Sprint escalation
If the scope is `sprint` and any Must Have stories are NEEDS WORK or BLOCKED,
add a prominent warning at the top of the output:
```
WARNING: [N] Must Have stories are not implementation-ready.
[List them with their primary gap or blocker.]
Resolve these before the sprint begins or replan with `/sprint-plan update`.
```
---
## 6. Collaborative Protocol
This skill is read-only. It never proposes edits or asks to write files.
After reporting findings, offer:
"Would you like help filling in the gaps for any of these stories? I can
draft the missing sections for your approval."
If the user says yes for a specific story, draft only the missing sections
in conversation. Do not use Write or Edit tools — the user (or
`/create-epics-stories`) handles writing.
**Redirect rules:**
- If a story file does not exist at all: "This story file is missing entirely.
Run `/create-epics-stories [system-name]` to generate it from the GDD and ADR."
- If a story has no GDD reference and the work appears small: "This story has
no GDD reference. If the change is small (under ~4 hours), run
`/quick-design [description]` to create a Quick Design Spec, then reference
that spec in the story."
- If a story's scope has grown beyond its original sizing: "This story appears
to have expanded in scope. Consider splitting it or escalating to the producer
before implementation begins."

96
.claude/skills/team-ui/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: team-ui
description: "Orchestrate the UI team: coordinates ux-designer, ui-programmer, and art-director to design, implement, and polish a user interface feature from wireframe to final."
description: "Orchestrate the UI team through the full UX pipeline: from UX spec authoring through visual design, implementation, review, and polish. Integrates with /ux-design, /ux-review, and studio UX templates."
argument-hint: "[UI feature description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion, TodoWrite
@@ -16,6 +16,13 @@ The user must approve before moving to the next phase.
- **ux-designer** — User flows, wireframes, accessibility, input handling
- **ui-programmer** — UI framework, screens, widgets, data binding, implementation
- **art-director** — Visual style, layout polish, consistency with art bible
- **accessibility-specialist** — Audits accessibility compliance at Phase 4
**Templates used by this pipeline:**
- `ux-spec.md` — Standard screen/flow UX specification
- `hud-design.md` — HUD-specific UX specification
- `interaction-pattern-library.md` — Reusable interaction patterns
- `accessibility-requirements.md` — Committed accessibility tier and requirements
## How to Delegate
@@ -23,48 +30,89 @@ Use the Task tool to spawn each team member as a subagent:
- `subagent_type: ux-designer` — User flows, wireframes, accessibility, input handling
- `subagent_type: ui-programmer` — UI framework, screens, widgets, data binding
- `subagent_type: art-director` — Visual style, layout polish, art bible consistency
- `subagent_type: accessibility-specialist` — Accessibility compliance audit
Always provide full context in each agent's prompt (feature requirements, existing UI patterns, platform targets). Launch independent agents in parallel where the pipeline allows it (e.g., Phase 4 review agents can run simultaneously).
## Pipeline
### Phase 1: UX Design
Delegate to **ux-designer**:
- Define the user flow for this feature (entry points, states, exit points)
- Create wireframes for each screen/state
- Specify interaction patterns: how does keyboard/mouse AND gamepad navigate this?
- Define accessibility requirements: text sizes, contrast, colorblind safety
- Identify data the UI needs to display (what game state does it read?)
- Output: UX spec with wireframes and interaction map
### Phase 1a: Context Gathering
Before designing anything, read and synthesize:
- `design/gdd/game-concept.md` — platform targets and intended audience
- `design/player-journey.md` — player's state and context when they reach this screen
- All GDD UI Requirements sections relevant to this feature
- `design/ux/interaction-patterns.md` — existing patterns to reuse (not reinvent)
- `design/accessibility-requirements.md` — committed accessibility tier (e.g., Basic, Enhanced, Full)
Summarize the context in a brief for the ux-designer: what the player is doing, what they need, what constraints apply, and which existing patterns are relevant.
### Phase 1b: UX Spec Authoring
Invoke `/ux-design [feature name]` skill OR delegate directly to ux-designer to produce `design/ux/[feature-name].md` following the `ux-spec.md` template.
If designing the HUD, use the `hud-design.md` template instead of `ux-spec.md`.
> **Notes on special cases:**
> - For HUD design specifically, invoke `/ux-design` with `argument: hud` (e.g., `/ux-design hud`).
> - For the interaction pattern library, run `/ux-design patterns` once at project start and update it whenever new patterns are introduced during later phases.
Output: `design/ux/[feature-name].md` with all required spec sections filled.
### Phase 1c: UX Review
After the spec is complete, invoke `/ux-review design/ux/[feature-name].md`.
**Gate**: Do not proceed to Phase 2 until the verdict is APPROVED. If the verdict is NEEDS REVISION, the ux-designer must address the flagged issues and re-run the review. The user may explicitly accept a NEEDS REVISION risk and proceed, but this must be a conscious decision — present the specific concerns via `AskUserQuestion` before asking whether to proceed.
### Phase 2: Visual Design
Delegate to **art-director**:
- Review wireframes against the art bible
- Define visual treatment: colors, typography, spacing, animations
- Specify asset requirements (icons, backgrounds, decorative elements)
- Ensure consistency with existing UI screens
- Output: visual design spec with style notes
- Review the full UX spec (flows, wireframes, interaction patterns, accessibility notes) — not just the wireframe images
- Apply visual treatment from the art bible: colors, typography, spacing, animation style
- Check that visual design preserves accessibility compliance: verify color contrast ratios, and confirm color is never the only indicator of state (shape, text, or icon must reinforce it)
- Specify all asset requirements needed from the art pipeline: icons at specified sizes, background textures, fonts, decorative elements — with precise dimensions and format requirements
- Ensure consistency with existing implemented UI screens
- Output: visual design spec with style notes and asset manifest
### Phase 3: Implementation
Delegate to **ui-programmer**:
- Implement the UI following the UX spec and visual design
- Ensure UI NEVER owns or modifies game state — display only, events for actions
- All text through localization system — no hardcoded strings
- Support both input methods (keyboard/mouse + gamepad)
- Implement accessibility features (text scaling, colorblind mode support)
- Implement the UI following the UX spec and visual design spec
- **Use patterns from `design/ux/interaction-patterns.md`** — do not reinvent patterns that are already specified. If a pattern almost fits but needs modification, note the deviation and flag it for ux-designer review.
- **UI NEVER owns or modifies game state** — display only; emit events for all player actions
- All text through the localization system — no hardcoded player-facing strings
- Support both input methods (keyboard/mouse AND gamepad)
- Implement accessibility features per the committed tier in `design/accessibility-requirements.md`
- Wire up data binding to game state
- **If any new interaction pattern is created during implementation** (i.e., something not already in the pattern library), add it to `design/ux/interaction-patterns.md` before marking implementation complete
- Output: implemented UI feature
### Phase 4: Review (parallel)
Delegate in parallel:
- **ux-designer**: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility.
- **ux-designer**: Verify implementation matches wireframes and interaction spec. Test keyboard-only and gamepad-only navigation. Check accessibility features function correctly.
- **art-director**: Verify visual consistency with art bible. Check at minimum and maximum supported resolutions.
- **accessibility-specialist**: Verify compliance against the committed accessibility tier documented in `design/accessibility-requirements.md`. Flag any violations as blockers.
All three review streams must report before proceeding to Phase 5.
### Phase 5: Polish
- Address review feedback
- Verify animations are skippable and respect motion preferences
- Confirm UI sounds trigger through audio event system
- Address all review feedback
- Verify animations are skippable and respect the player's motion reduction preferences
- Confirm UI sounds trigger through the audio event system (no direct audio calls)
- Test at all supported resolutions and aspect ratios
- **Verify `design/ux/interaction-patterns.md` is up to date** — if any new patterns were introduced during this feature's implementation, confirm they have been added to the library
- **Confirm all HUD elements respect the visual budget** defined in `design/ux/hud.md` (element count, screen region allocations, maximum opacity values)
## Quick Reference — When to Use Which Skill
- `/ux-design` — Author a new UX spec for a screen, flow, or HUD from scratch
- `/ux-review` — Validate a completed UX spec before implementation
- `/team-ui [feature]` — Full pipeline from concept through polish (calls `/ux-design` and `/ux-review` internally)
- `/quick-design` — Small UI changes that don't need a full new UX spec
## Output
A summary report covering: UX spec status, visual design status, implementation status, accessibility compliance, input method support, and any outstanding issues.
A summary report covering: UX spec status, UX review verdict, visual design status, implementation status, accessibility compliance, input method support, interaction pattern library update status, and any outstanding issues.

756
.claude/skills/ux-design/SKILL.md Normal file
View File

@@ -0,0 +1,756 @@
---
name: ux-design
description: "Guided, section-by-section UX spec authoring for a screen, flow, or HUD. Reads game concept, player journey, and relevant GDDs to provide context-aware design guidance. Produces ux-spec.md (per screen/flow) or hud-design.md using the studio templates."
argument-hint: "[screen/flow name] or 'hud' or 'patterns'"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion
context: fork
agent: ux-designer
---
When this skill is invoked:
## 1. Parse Arguments & Determine Mode
Three authoring modes exist based on the argument:
| Argument | Mode | Output file |
|----------|------|-------------|
| `hud` | HUD design | `design/ux/hud.md` |
| `patterns` | Interaction pattern library | `design/ux/interaction-patterns.md` |
| Any other value (e.g., `main-menu`, `inventory`) | UX spec for a screen or flow | `design/ux/[argument].md` |
| No argument | Ask the user | (see below) |
**If no argument is provided**, do not fail — ask instead. Use `AskUserQuestion`:
- "What are we designing today?"
- Options: "A specific screen or flow (I'll name it)", "The game HUD", "The interaction pattern library", "I'm not sure — help me figure it out"
If the user selects "I'll name it" or types a screen name, normalize it to kebab-case
for the filename (e.g., "Main Menu" becomes `main-menu`).
---
## 2. Gather Context (Read Phase)
Read all relevant context **before** asking the user anything. The skill's value
comes from arriving informed.
### 2a: Required Reads
- **Game concept**: Read `design/gdd/game-concept.md` — if missing, warn:
> "No game concept found. Run `/brainstorm` first to establish the game's
> foundation before designing UX."
> Continue anyway if the user asks.
### 2b: Player Journey
Read `design/player-journey.md` if it exists. For each relevant section, extract:
- Which journey phase(s) does this screen appear in?
- What is the player's emotional state on arrival at this screen?
- What player need is this screen serving in the journey?
- What critical moments (from the journey map) does this screen deliver?
If the player journey file does not exist, note the gap and proceed:
> "No player journey map found at `design/player-journey.md`. Designing without it
> means we'll be making assumptions about player context. Consider running a player
> journey session after this spec is drafted."
### 2c: GDD UI Requirements
Glob `design/gdd/*.md` and grep for `UI Requirements` sections. Read any GDD whose
UI Requirements section references this screen by name or category.
These GDD UI Requirements are the **requirements input** to this spec. Collect them
as a list of constraints the spec must satisfy.
If designing the HUD, read ALL GDD UI Requirements sections — the HUD aggregates
requirements from every system.
### 2d: Existing UX Specs
Glob `design/ux/*.md` and note which screens already have specs. For screens that
will link to or from the current screen, read their navigation/flow sections to
find the entry and exit points this spec must match.
### 2e: Interaction Pattern Library
If `design/ux/interaction-patterns.md` exists, read the pattern catalog index
(the list of pattern names and their one-line descriptions). Do not read full
pattern details — just the catalog. This tells you which patterns already exist
so you can reference them rather than reinvent them.
### 2f: Art Bible
Check for `docs/art-bible.md` or `design/art-bible.md`. If found, read the
visual direction section. UX layout must align with the aesthetic commitments
already made.
### 2g: Accessibility Requirements
Check for `design/accessibility-requirements.md`. If found, read it. The spec
must satisfy the accessibility tier committed to there.
### 2h: Present Context Summary
Before any design work, present a brief summary to the user:
> **Designing: [Screen/Flow Name]**
> - Mode: [UX Spec / HUD Design / Pattern Library]
> - Journey phase(s): [from player-journey.md, or "unknown — no journey map"]
> - GDD requirements feeding this spec: [count and names, or "none found"]
> - Related screens already specced: [list, or "none yet"]
> - Known patterns available: [count, or "no pattern library yet"]
> - Accessibility tier: [from requirements doc, or "not yet defined"]
Then ask: "Anything else I should read before we start, or shall we proceed?"
---
## 3. Create File Skeleton
Once the user confirms, **immediately** create the output file with empty section
headers. This ensures incremental writes have a target and work survives interruptions.
Ask: "May I create the skeleton file at `design/ux/[filename].md`?"
---
### Skeleton for UX Spec (screen or flow)
```markdown
# UX Spec: [Screen/Flow Name]
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Journey Phase(s)**: [from context]
> **Template**: UX Spec
---
## Purpose & Player Need
[To be designed]
---
## Player Context on Arrival
[To be designed]
---
## Layout Specification
### Information Hierarchy
[To be designed]
### Layout Zones
[To be designed]
### Component Inventory
[To be designed]
### ASCII Wireframe
[To be designed]
---
## States & Variants
[To be designed]
---
## Interaction Map
[To be designed]
---
## Data Requirements
[To be designed]
---
## Accessibility
[To be designed]
---
## Open Questions
[To be designed]
```
---
### Skeleton for HUD Design
```markdown
# HUD Design
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Template**: HUD Design
---
## HUD Philosophy
[To be designed]
---
## Information Architecture
### Full Information Inventory
[To be designed]
### Categorization
[To be designed]
---
## Layout Zones
[To be designed]
---
## HUD Elements
[To be designed]
---
## Dynamic Behaviors
[To be designed]
---
## Platform & Input Variants
[To be designed]
---
## Accessibility
[To be designed]
---
## Open Questions
[To be designed]
```
---
### Skeleton for Interaction Pattern Library
```markdown
# Interaction Pattern Library
> **Status**: In Design
> **Author**: [user + ux-designer]
> **Last Updated**: [today's date]
> **Template**: Interaction Pattern Library
---
## Overview
[To be designed]
---
## Pattern Catalog
[To be designed]
---
## Patterns
[Individual pattern entries added here as they are defined]
---
## Gaps & Patterns Needed
[To be designed]
---
## Open Questions
[To be designed]
```
---
After writing the skeleton, update `production/session-state/active.md` with:
- Task: Designing [screen/flow name] UX spec
- Current section: Starting (skeleton created)
- File: design/ux/[filename].md
---
## 4. Section-by-Section Authoring
Walk through each section in order. For **each section**, follow this cycle:
```
Context -> Questions -> Options -> Decision -> Draft -> Approval -> Write
```
1. **Context**: State what this section needs to contain and surface any relevant
constraints from context gathered in Phase 2.
2. **Questions**: Ask what is needed to draft this section. Use `AskUserQuestion`
for constrained choices, conversational text for open-ended exploration.
3. **Options**: Where design choices exist, present 2-4 approaches with pros/cons.
Explain reasoning in conversation, then use `AskUserQuestion` to capture the decision.
4. **Decision**: User picks an approach or provides custom direction.
5. **Draft**: Write the section content in conversation for review. Flag provisional
assumptions explicitly.
6. **Approval**: "Does this capture it? Any changes before I write it to the file?"
7. **Write**: Use `Edit` to replace the `[To be designed]` placeholder with approved
content. Confirm the write.
After writing each section, update `production/session-state/active.md`.
---
### Section Guidance: UX Spec Mode
#### Section A: Purpose & Player Need
This section is the foundation. Every other decision flows from it.
**Questions to ask**:
- "What player goal does this screen serve? What is the player trying to DO here?"
- "What would go wrong if this screen didn't exist or was hard to use?"
- "Complete this sentence: 'The player arrives at this screen wanting to ___.' "
Cross-reference the player journey context gathered in Phase 2. The stated purpose
must align with the journey phase and emotional state.
---
#### Section B: Player Context on Arrival
**Questions to ask**:
- "When in the game does a player first encounter this screen?"
- "What were they just doing immediately before reaching this screen?"
- "What emotional state should the design assume? (calm, stressed, curious, time-pressured)"
- "Do players arrive at this screen voluntarily, or are they sent here by the game?"
Offer to map this against the journey phases if the player journey doc exists.
---
#### Section C: Layout Specification
This is the largest and most interactive section. Work through it in sub-sections:
**Sub-section 1 — Information Hierarchy** (establish this before any layout):
- Ask the user to list every piece of information this screen must communicate.
- Then ask them to rank the items: "What is the single most important thing a player
needs to see first? What is second? What can be discovered rather than immediately visible?"
- Present the resulting hierarchy for approval before moving to zones.
**Sub-section 2 — Layout Zones**:
- Based on the information hierarchy, propose rough screen zones (header, content
area, action bar, sidebar, etc.).
- Offer 2-3 zone arrangements with rationale for each. Reference platform and
input context gathered from game concept.
- Ask: "Do any of these match your mental image, or shall we build a custom arrangement?"
**Sub-section 3 — Component Inventory**:
- For each zone, list the UI components it contains. For each component, note:
- Component type (button, list, card, stat display, input field, etc.)
- Content it displays
- Whether it is interactive
- If it uses an existing pattern from the library (reference by pattern name)
- If it introduces a new pattern (flag for later addition to the library)
**Sub-section 4 — ASCII Wireframe**:
- Offer to generate an ASCII wireframe based on the zone layout and component list.
- Use `AskUserQuestion`: "Want an ASCII wireframe as part of this spec?"
- Options: "Yes, include one", "No, I'll attach a separate file"
- If yes, produce the wireframe in conversation first. Ask for feedback before
writing it to file.
---
#### Section D: States & Variants
Guide the user to think beyond the happy path.
**Questions to ask** (work through these one at a time):
- "What does this screen look like the very first time a player sees it, when there
is no data yet? (empty state)"
- "What happens when something goes wrong — an error, a failed action, a missing
resource? (error state)"
- "Is there ever a loading wait on this screen? If so, what does it show? (loading state)"
- "Are there any player progression states that change what this screen shows? For
example, locked content, premium content, or tutorial-mode overlays?"
- "Does this screen behave differently on any supported platform? (platform variant)"
Present the collected states as a table for approval:
| State / Variant | Trigger | What Changes |
|-----------------|---------|--------------|
| Default | Normal load | — |
| Empty | No data available | [content area description] |
| [etc.] | [trigger] | [changes] |
---
#### Section E: Interaction Map
For each interactive component identified in the Layout Specification, define:
- The action (tap, click, press, hold, scroll, drag)
- The platform input(s) that trigger it (mouse click, gamepad A, keyboard Enter)
- The immediate feedback (visual, audio, haptic)
- The outcome (navigation target, state change, data write)
Ask up front: "Which input methods does this game target? I'll tailor the
interaction map to those." Reference game concept for platform targets.
Work through components one at a time rather than asking for all at once.
For navigation actions (going to another screen), verify the target matches
an existing UX spec or note it as a spec dependency.
---
#### Section F: Data Requirements
Cross-reference the GDD UI Requirements sections gathered in Phase 2.
For each piece of information the screen displays, ask:
- "Where does this data come from? Which system owns it?"
- "Does this screen need to write data back, or is it read-only?"
- "Is any of this data time-sensitive or real-time? (health bars, cooldown timers)"
Flag any case where the UI would need to own or manage game state as an architectural
concern. UX specs define what the UI needs; they do not dictate how the data is
delivered. That is an architecture decision.
Present the data requirements as a table:
| Data | Source System | Read / Write | Notes |
|------|--------------|--------------|-------|
| [item] | [system] | Read | — |
| [item] | [system] | Write | [concern if any] |
---
#### Section G: Accessibility
Cross-reference `design/accessibility-requirements.md` if it exists.
Walk through the ux-designer agent's standard checklist for this screen:
- Keyboard-only navigation path through all interactive elements
- Gamepad navigation order (if applicable)
- Text contrast and minimum readable font sizes
- Color-independent communication (no information conveyed by color alone)
- Screen reader considerations for any non-text elements
- Any motion or animation that needs a reduced-motion alternative
Use `AskUserQuestion` to surface any open questions on accessibility tier:
- "Has the accessibility tier been committed to for this project?"
- Options: "Yes, read from requirements doc", "Not yet — let's flag it as a question", "Skip accessibility section for now"
---
### Section Guidance: HUD Design Mode
HUD design follows a different order from UX spec mode. Begin with philosophy;
do not touch layout until the information architecture is complete.
#### Section A: HUD Philosophy
Ask the user to describe the game's relationship with on-screen information in
1-2 sentences.
Offer framing examples to help:
- "Nearly HUD-free — atmosphere requires unobstructed immersion (e.g., Hollow Knight, Firewatch)"
- "Minimal but present — only critical information visible, everything else contextual (e.g., Dark Souls)"
- "Information-dense — all decision-relevant data always visible (e.g., Diablo IV, StarCraft II)"
- "Adaptive — HUD density responds to combat state, exploration mode, menus (e.g., God of War)"
This philosophy becomes the design constraint for every subsequent HUD decision.
If a proposed element conflicts with the stated philosophy, surface that conflict.
---
#### Section B: Information Architecture
Complete this before any layout work. Do not skip it.
**Step 1 — Full information inventory**:
Pull all information from GDD UI Requirements sections gathered in Phase 2.
Present the full list: "These are all the things your game systems say they need
to communicate to the player on screen."
**Step 2 — Categorization**:
For each item, ask the user to categorize it:
| Category | Description |
|----------|-------------|
| **Must Show** | Always visible, player needs it for core decisions |
| **Contextual** | Visible only when relevant (in combat, near interactable, etc.) |
| **On Demand** | Player must actively request it (toggle, hold button) |
| **Hidden** | Communicated through world/audio, never on-screen text |
Use `AskUserQuestion` to step through items in groups of 3-4, not all at once.
This is the most consequential design decision in the HUD — do not rush it.
**Conflict check**: If the information philosophy (Section A) says "nearly HUD-free"
but the Must Show list is growing long, surface the conflict explicitly:
> "The current Must Show list has [N] items. That may conflict with the HUD-free
> philosophy. Options: reduce the Must Show list, revise the philosophy, or define
> a hybrid approach where HUD is absent in exploration and present in combat."
---
#### Section C: Layout Zones
Only after the information architecture is approved, design layout zones.
Base layout on:
- Which items are Must Show (they drive the permanent zone decisions)
- Where player attention naturally goes during gameplay (center-screen for action games,
corners for strategy games)
- Platform and aspect ratio targets
Offer 2-3 zone arrangements. Include rationale based on the HUD philosophy and the
categorization from Section B.
---
#### Section D: HUD Elements
For each element in the layout, specify:
- Element name and category (Must Show / Contextual / On Demand)
- Content displayed
- Visual form (bar, number, icon, counter, map)
- Update behavior (real-time, event-driven, player-queried)
- Contextual trigger (if not always visible)
- Animation behavior (does it pulse when low? Fade in? Slam in?)
Work element by element. Reference the interaction pattern library if relevant patterns
exist for status displays, resource bars, or cooldown indicators.
---
#### Sections E, F, G: Dynamic Behaviors, Platform Variants, Accessibility
These follow the same structure as the UX spec equivalents. See UX Spec section
guidance for D (States/Variants), E (Interactions), and G (Accessibility).
For the HUD specifically, emphasize:
- Dynamic Behaviors: what causes the HUD to change density mid-gameplay?
- Platform Variants: does mobile/console require different element sizes or positions?
---
### Section Guidance: Interaction Pattern Library Mode
Pattern library authoring is additive and catalog-driven, not linear.
#### Phase 1: Catalog Existing Patterns
Glob `design/ux/*.md` (excluding `interaction-patterns.md`) and read the Component
Inventory and Interaction Map sections of each spec. Extract every interaction
pattern used.
Present the extracted list: "Based on existing UX specs, these patterns are already
in use in the game:"
- [Pattern name]: used in [screen], [screen]
- [etc.]
Ask: "Are there patterns you know exist but aren't in existing specs yet? List any
additional ones now."
---
#### Phase 2: Formalize Each Pattern
For each pattern (existing or new), document:
```markdown
### [Pattern Name]
**Category**: Navigation / Input / Feedback / Data Display / Modal / Overlay / [other]
**Used In**: [list of screens]
**Description**: [One paragraph explaining what this pattern is and when to use it]
**Specification**:
- [Component behavior]
- [Input mapping]
- [Visual/audio feedback]
- [Accessibility requirements for this pattern]
**When to Use**: [Conditions where this pattern is appropriate]
**When NOT to Use**: [Conditions where another pattern is more appropriate]
**Reference**: [Screenshot path or ASCII example, if available]
```
Work through patterns in groups. Offer: "Shall I draft the first batch based on what
I've found in the existing specs, or do you want to define them one by one?"
---
#### Phase 3: Identify Gaps
After cataloging known patterns, ask:
- "Are there screens or interactions planned that would need patterns not yet
in this library?"
- "Are there any patterns in existing specs that feel inconsistent with each
other and should be consolidated?"
Document gaps in the Gaps section for follow-up.
---
## 5. Cross-Reference Check
Before marking the spec as ready for review, run these checks:
**1. GDD requirement coverage**: Does every GDD UI Requirement that references
this screen have a corresponding element in this spec? Present any gaps.
**2. Pattern library alignment**: Are all interaction patterns used in this spec
referenced by name? If a new pattern was invented during this spec session, flag
it for addition to the pattern library:
> "This spec uses [pattern name], which isn't in the pattern library yet.
> Want to add it now, or flag it as a gap?"
**3. Navigation consistency**: Do the entry/exit points in this spec match the
navigation map in any related specs? Flag mismatches.
**4. Accessibility coverage**: Does the spec address the accessibility tier
committed to in `design/accessibility-requirements.md`? If not, flag open questions.
**5. Empty states**: Does every data-dependent element have an empty state defined?
Flag any that don't.
Present the check results:
> **Cross-Reference Check: [Screen Name]**
> - GDD requirements: [N of M covered / all covered]
> - New patterns to add to library: [list or "none"]
> - Navigation mismatches: [list or "none"]
> - Accessibility gaps: [list or "none"]
> - Missing empty states: [list or "none"]
---
## 6. Handoff
When all sections are approved and written:
### 6a: Update Session State
Update `production/session-state/active.md` with:
- Task: [screen-name] UX spec
- Status: Complete (or In Review)
- File: design/ux/[filename].md
- Sections: All written
- Next: [suggestion]
### 6b: Suggest Next Step
Use `AskUserQuestion`:
- "The spec is complete. What's next?"
- Options:
- "Run `/ux-review` to validate this spec"
- "Design another screen"
- "Update the interaction pattern library with new patterns from this spec"
- "Stop here for this session"
### 6c: Cross-Link Related Specs
If other UX specs link to or from this screen, note which ones should reference
this spec. Do not edit those files without asking — just name them.
---
## 7. Recovery & Resume
If the session is interrupted (compaction, crash, new session):
1. Read `production/session-state/active.md` — it records the current screen
and which sections are complete.
2. Read `design/ux/[filename].md` — sections with real content are done;
sections with `[To be designed]` still need work.
3. Resume from the next incomplete section — no need to re-discuss completed ones.
This is why incremental writing matters: every approved section survives any
disruption.
---
## 8. Specialist Agent Routing
This skill uses `ux-designer` as the primary agent (set in frontmatter). For
specific sub-topics, additional context or coordination may be needed:
| Topic | Coordinate with |
|-------|----------------|
| Visual aesthetics, color, layout feel | `art-director` — UX spec defines zones; art defines how they look |
| Implementation feasibility (engine constraints) | `ui-programmer` — before finalizing component inventory |
| Gameplay data requirements | `game-designer` — when data ownership is unclear |
| Narrative/lore visible in the UI | `narrative-director` — for flavor text, item names, lore panels |
| Accessibility tier decisions | `ux-designer` (owns this) |
When delegating to another agent via the Task tool:
- Provide: screen name, game concept summary, the specific question needing expert input
- The agent returns analysis to this session
- This session presents the agent's output to the user
- The user decides; this session writes to file
- Agents do NOT write to files directly — this session owns all file writes
---
## Collaborative Protocol
This skill follows the collaborative design principle at every step:
1. **Question -> Options -> Decision -> Draft -> Approval** for every section
2. **AskUserQuestion** at every decision point (Explain -> Capture pattern):
- Phase 2: "Ready to start, or need more context?"
- Phase 3: "May I create the skeleton?"
- Phase 4 (each section): design questions, approach options, draft approval
- Phase 5: "Run cross-reference check? What's next?"
3. **"May I write to [filepath]?"** before the skeleton and before each section write
4. **Incremental writing**: Each section is written to file immediately after approval
5. **Session state updates**: After every section write
**Aesthetic deference**: When layout or visual choices come down to personal taste,
present the options and ask. Do not select a layout because it is "standard" — always
confirm. The user is the creative director.
**Conflict surfacing**: When a GDD requirement and the available screen real estate
conflict, surface the conflict and present resolution options. Never silently drop
a requirement. Never silently expand the layout without flagging it.
**Never** auto-generate the full spec and present it as a fait accompli.
**Never** write a section without user approval.
**Never** contradict an existing approved UX spec without flagging the conflict.
**Always** show where decisions come from (GDD requirements, player journey, user choices).

259
.claude/skills/ux-review/SKILL.md Normal file
View File

@@ -0,0 +1,259 @@
---
name: ux-review
description: "Validates a UX spec, HUD design, or interaction pattern library for completeness, accessibility compliance, GDD alignment, and implementation readiness. Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict with specific gaps."
argument-hint: "[file-path or 'all' or 'hud' or 'patterns']"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: fork
agent: ux-designer
---
## Overview
Validates UX design documents before they enter the implementation pipeline.
Acts as the quality gate between UX Design and Visual Design/Implementation in
the `/team-ui` pipeline.
**Run this skill:**
- After completing a UX spec with `/ux-design`
- Before handing off to `ui-programmer` or `art-director`
- Before the Pre-Production to Production gate check (which requires key screens
to have reviewed UX specs)
- After major revisions to a UX spec
**Verdict levels:**
- **APPROVED** — spec is complete, consistent, and implementation-ready
- **NEEDS REVISION** — specific gaps found; fix before handoff but not a full redesign
- **MAJOR REVISION NEEDED** — fundamental issues with scope, player need, or
completeness; needs significant rework
---
## Phase 1: Parse Arguments
- **Specific file path** (e.g., `/ux-review design/ux/inventory.md`): validate
that one document
- **`all`**: find all files in `design/ux/` and validate each
- **`hud`**: validate `design/ux/hud.md` specifically
- **`patterns`**: validate `design/ux/interaction-patterns.md` specifically
- **No argument**: ask the user which spec to validate
For `all`, output a summary table first (file | verdict | primary issue) then
full detail for each.
---
## Phase 2: Load Cross-Reference Context
Before validating any spec, load:
1. The accessibility tier committed to in `design/accessibility-requirements.md`
(if it exists)
2. The interaction pattern library at `design/ux/interaction-patterns.md` (if
it exists)
3. The GDDs referenced in the spec's header (read their UI Requirements sections)
4. The player journey map at `design/player-journey.md` (if it exists) for
context-arrival validation
---
## Phase 3A: UX Spec Validation Checklist
Run all checks against a `ux-spec.md`-based document.
### Completeness (required sections)
- [ ] Document header present with Status, Author, Platform Target
- [ ] Purpose & Player Need — has a player-perspective need statement (not
developer-perspective)
- [ ] Player Context on Arrival — describes player's state and prior activity
- [ ] Navigation Position — shows where screen sits in hierarchy
- [ ] Entry & Exit Points — all entry sources and exit destinations documented
- [ ] Layout Specification — zones defined, component inventory table present
- [ ] States & Variants — at minimum: loading, empty/populated, and error states
documented
- [ ] Interaction Map — covers all target input methods (check platform target
in header)
- [ ] Data Requirements — every displayed data element has a source system and owner
- [ ] Events Fired — every player action has a corresponding event or null
explanation
- [ ] Transitions & Animations — at least enter/exit transitions specified
- [ ] Accessibility Requirements — screen-level requirements present
- [ ] Localization Considerations — max character counts for text elements
- [ ] Acceptance Criteria — at least 5 specific testable criteria
### Quality Checks
**Player Need Clarity**
- [ ] Purpose is written from player perspective, not system/developer perspective
- [ ] Player goal on arrival is unambiguous ("The player arrives wanting to ___")
- [ ] The player context on arrival is specific (not just "they opened the
inventory")
**Completeness of States**
- [ ] Error state is documented (not just happy path)
- [ ] Empty state is documented (no data scenario)
- [ ] Loading state is documented if the screen fetches async data
- [ ] Any state with a timer or auto-dismiss is documented with duration
**Input Method Coverage**
- [ ] If platform includes PC: keyboard-only navigation is fully specified
- [ ] If platform includes console/gamepad: d-pad navigation and face button
mapping documented
- [ ] No interaction requires mouse-like precision on gamepad
- [ ] Focus order is defined (Tab order for keyboard, d-pad order for gamepad)
**Data Architecture**
- [ ] No data element has "UI" listed as the owner (UI must not own game state)
- [ ] Update frequency is specified for all real-time data (not just "realtime" —
what triggers update?)
- [ ] Null handling is specified for all data elements (what shows when data is
unavailable?)
**Accessibility**
- [ ] Accessibility tier from `accessibility-requirements.md` is matched or exceeded
- [ ] If Basic tier: no color-only information indicators
- [ ] If Standard tier+: focus order documented, text contrast ratios specified
- [ ] If Comprehensive tier+: screen reader announcements for key state changes
- [ ] Colorblind check: any color-coded elements have non-color alternatives
**GDD Alignment**
- [ ] Every GDD UI Requirement referenced in the header is addressed in this spec
- [ ] No UI element displays or modifies game state without a corresponding GDD
requirement
- [ ] No GDD UI Requirement is missing from this spec (cross-check the referenced
GDD sections)
**Pattern Library Consistency**
- [ ] All interactive components reference the pattern library (or note they are
new patterns)
- [ ] No pattern behavior is re-specified from scratch if it already exists in
the pattern library
- [ ] Any new patterns invented in this spec are flagged for addition to the
pattern library
**Localization**
- [ ] Character limit warnings present for all text-heavy elements
- [ ] Any layout-critical text has been flagged for 40% expansion accommodation
**Acceptance Criteria Quality**
- [ ] Criteria are specific enough for a QA tester who hasn't seen the design docs
- [ ] Performance criterion present (screen opens within Xms)
- [ ] Resolution criterion present
- [ ] No criterion requires reading another document to evaluate
---
## Phase 3B: HUD Validation Checklist
Run all checks against a `hud-design.md`-based document.
### Completeness
- [ ] HUD Philosophy defined
- [ ] Information Architecture table covers ALL systems with UI Requirements in GDDs
- [ ] Layout Zones defined with safe zone margins for all target platforms
- [ ] Every HUD element has a full specification (zone, visibility trigger, data
source, priority)
- [ ] HUD States by Gameplay Context covers at minimum: exploration, combat,
dialogue/cutscene, paused
- [ ] Visual Budget defined (max simultaneous elements, max screen %)
- [ ] Platform Adaptation covers all target platforms
- [ ] Tuning Knobs present for player-adjustable elements
### Quality Checks
- [ ] No HUD element covers the center play area without a visibility rule to
hide it
- [ ] Every information item that exists in any GDD is either in the HUD or
explicitly categorized as "hidden/demand"
- [ ] All color-coded HUD elements have colorblind variants
- [ ] HUD elements in the Feedback & Notification section have queue/priority
behavior defined
- [ ] Visual Budget compliance: total simultaneous elements is within budget
### GDD Alignment
- [ ] All systems in `design/gdd/systems-index.md` with UI category have
representation in HUD (or justified absence)
---
## Phase 3C: Pattern Library Validation Checklist
- [ ] Pattern catalog index is current (matches actual patterns in document)
- [ ] All standard control patterns are specified: button variants, toggle,
slider, dropdown, list, grid, modal, dialog, toast, tooltip, progress bar,
input field, tab bar, scroll
- [ ] All game-specific patterns needed by current UX specs are present
- [ ] Each pattern has: When to Use, When NOT to Use, full state specification,
accessibility spec, implementation notes
- [ ] Animation Standards table present
- [ ] Sound Standards table present
- [ ] No conflicting behaviors between patterns (e.g., "Back" behavior consistent
across all navigation patterns)
---
## Phase 4: Output the Verdict
```markdown
## UX Review: [Document Name]
**Date**: [date]
**Reviewer**: ux-review skill
**Document**: [file path]
**Platform Target**: [from header]
**Accessibility Tier**: [from header or accessibility-requirements.md]
### Completeness: [X/Y sections present]
- [x] Purpose & Player Need
- [ ] States & Variants — MISSING: error state not documented
### Quality Issues: [N found]
1. **[Issue title]** [BLOCKING / ADVISORY]
- What's wrong: [specific description]
- Where: [section name]
- Fix: [specific action to take]
### GDD Alignment: [ALIGNED / GAPS FOUND]
- GDD [name] UI Requirements — [X/Y requirements covered]
- Missing: [list any uncovered GDD requirements]
### Accessibility: [COMPLIANT / GAPS / NON-COMPLIANT]
- Target tier: [tier]
- [list specific accessibility findings]
### Pattern Library: [CONSISTENT / INCONSISTENCIES FOUND]
- [findings]
### Verdict: APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED
**Blocking issues**: [N] — must be resolved before implementation
**Advisory issues**: [N] — recommended but not blocking
[For APPROVED]: This spec is ready for handoff to `/team-ui` Phase 2
(Visual Design).
[For NEEDS REVISION]: Address the [N] blocking issues above, then re-run
`/ux-review`.
[For MAJOR REVISION NEEDED]: The spec has fundamental gaps in [areas].
Recommend returning to `/ux-design` to rework [sections].
```
---
## Phase 5: Collaborative Protocol
This skill is READ-ONLY — it never edits or writes files. It reports findings only.
After delivering the verdict:
- For **APPROVED**: suggest running `/team-ui` to begin implementation coordination
- For **NEEDS REVISION**: offer to help fix specific gaps ("Would you like me to
help draft the missing error state?") — but do not auto-fix; wait for user
instruction
- For **MAJOR REVISION NEEDED**: suggest returning to `/ux-design` with the
specific sections to rework
Never block the user from proceeding — the verdict is advisory. Document risks,
present findings, let the user decide whether to proceed despite concerns. A user
who chooses to proceed with a NEEDS REVISION spec takes on the documented risk.