game-architect

name	game-architect
description	Validate codebase architecture and organization before releases. Use when user asks to 'check architecture', 'validate structure', 'pre-release check', or before versioning.

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

1. Run full validation: ./scripts/validate_all.sh
2. Review violations: Check output for ✗ markers
3. Fix issues: Refactor code to correct layer
4. Re-validate: Ensure all checks pass
5. 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

1. Create design doc in design_docs/planned/next/
2. Use sprint-planner skill to create sprint plan in sprints/
3. Execute sprint (sprint tracks implementation progress via checkboxes)
4. 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