Game Architect

Validates Stapledon's Voyage codebase against the three-layer architecture and organization standards.

Quick Start

# Full validation (all checks - run before releases)
.claude/skills/game-architect/scripts/validate_all.sh --full

# Quick validation (core checks only - faster)
.claude/skills/game-architect/scripts/validate_all.sh --quick

# Individual checks (core)
.claude/skills/game-architect/scripts/check_file_sizes.sh       # Files under 800 lines
.claude/skills/game-architect/scripts/check_layer_boundaries.sh # No game logic in engine/
.claude/skills/game-architect/scripts/check_structure.sh        # Files in correct locations
.claude/skills/game-architect/scripts/check_import_cycles.sh    # No circular imports

# Individual checks (extended)
.claude/skills/game-architect/scripts/check_complexity.sh       # Function size, nesting
.claude/skills/game-architect/scripts/check_ailang_sync.sh      # AILANG ↔ Go types match
.claude/skills/game-architect/scripts/check_api_stability.sh    # sim_gen API unchanged
.claude/skills/game-architect/scripts/check_coverage.sh         # Test coverage
.claude/skills/game-architect/scripts/check_dependencies.sh     # Package import graph
.claude/skills/game-architect/scripts/pre_release_check.sh      # Build, tests, TODOs

When to Use This Skill

Invoke this skill when:

Before tagging a version release
After major refactoring
User asks "check architecture" or "validate structure"
Periodic codebase health checks
After adding new files/directories

Architecture Rules

The Key Question: AILANG or Engine?

Ask: Does this affect gameplay outcomes?

| If YES → AILANG | If NO → Engine OK | |-----------------|-------------------| | Position, health, inventory | Decorative particles | | NPC behavior, dialogue | Screen transitions | | Time dilation, velocity | Shader effects | | Planet data, civilizations | UI layout math | | Game mode, decisions | Asset loading |

AILANG owns WHAT is happening (state, logic, decisions)
Engine owns HOW it looks (rendering, animation, polish)

Four-Layer Separation

| Layer | Location | Purpose | Allowed Content | |-------|----------|---------|-----------------| | Source | sim/*.ail | Game logic (AILANG) | Types, pure functions | | Generated | sim_gen/*.go | Generated from AILANG | Game types (OK - generated) | | Game Views | game_views/*.go | Game-specific rendering | DomeRenderer, DeckStack | | Engine | engine/*.go | Generic rendering (reusable) | DrawCmd, Camera, Assets | | Entry | cmd/*.go | Wiring | Main, game loop |

Engine Genericization (Critical)

Goal: Engine should work unchanged for ANY AILANG game.

Before adding to engine/, ask: Could a different game use this unchanged?

| If YES | If NO | |--------|-------| | → OK for engine/ | → Put in game_views/ |

engine/ must be generic:

✅ DrawCmd rendering (any variant)
✅ Asset loading, camera, shaders
❌ Deck names (Core, Engineering, Bridge)
❌ Planet names (Saturn, Earth)
❌ Crew roles (pilot, comms, scientist)
❌ Game-specific state types

sim_gen/ is fine:

Generated from AILANG - game types belong there
Never manually edit

game_views/ for game-specific rendering:

DomeRenderer (solar system viz)
DeckStackRenderer (5-deck ship)
Any code using sim_gen types beyond DrawCmd

Layer Boundaries (Critical)

engine/ must NOT contain:

Game state (positions, health, time) - use AILANG
Game logic (NPC AI, decisions) - use AILANG
Hardcoded game data (planet configs) - use AILANG
Game-specific types (DeckType, DomeViewState) - use game_views/

engine/ CAN contain:

Generic DrawCmd rendering
Decorative particles (no gameplay impact)
Screen transition animations
Shader/visual effects
UI layout helpers

File Size Limits

| Threshold | Action | |-----------|--------| | > 800 lines | Error - must split file | | > 600 lines | Warning - consider splitting | | > 100 lines/function | Warning - extract functions |

Workflow

Run full validation: ./scripts/validate_all.sh
Review violations: Check output for ✗ markers
Fix issues: Refactor code to correct layer
Re-validate: Ensure all checks pass
Proceed with release: Once clean

Checks Performed

Core Checks (blocking)

| Script | Purpose | |--------|---------| | check_file_sizes.sh | Max 800 lines/file, warn at 600 | | check_layer_boundaries.sh | No game logic in engine/, no rendering in sim_gen/ | | check_structure.sh | Files in correct directories | | check_import_cycles.sh | No circular package dependencies | | pre_release_check.sh | Build, tests, TODOs, debug code |

Extended Checks (warnings)

| Script | Purpose | |--------|---------| | check_complexity.sh | Function size (<100 lines), nesting depth, param count | | check_ailang_sync.sh | AILANG types match sim_gen Go types | | check_api_stability.sh | sim_gen exports haven't changed unexpectedly | | check_coverage.sh | Test coverage for critical paths | | check_dependencies.sh | Package import graph, layer violations |

API Stability

The API stability check maintains a baseline of sim_gen exports:

# Update baseline after intentional API changes
.claude/skills/game-architect/scripts/check_api_stability.sh --update

Design Doc Management

Track implementation progress of design docs through sprint files:

# Audit design docs - check which have sprints
.claude/skills/game-architect/scripts/audit_design_docs.sh

Design Doc Workflow

Create design doc in design_docs/planned/next/
Use sprint-planner skill to create sprint plan in sprints/
Execute sprint (sprint tracks implementation progress via checkboxes)
When sprint complete, move doc to design_docs/implemented/vX_Y_Z/

Audit Output

The audit script checks:

Which design docs have corresponding sprint files
Sprint completion percentage (via checkbox counting)
Orphan sprints (sprints without design docs)

Design docs WITHOUT sprints need planning before implementation.

Resources

Architecture Rules - Detailed layer boundaries and examples