Game Architect

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?

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

Four-Layer Separation

Engine Genericization (Critical)

Goal: Engine should work unchanged for ANY AILANG game.

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

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

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)

Extended Checks (warnings)

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