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
1---2name: game-architect3description: Validate codebase architecture and organization before releases. Use when user asks to 'check architecture', 'validate structure', 'pre-release check', or before versioning.4---5
6# Game Architect
7
8Validates Stapledon's Voyage codebase against the three-layer architecture and organization standards.
9
10## Quick Start
11
12```bash
13# Full validation (all checks - run before releases)
14.claude/skills/game-architect/scripts/validate_all.sh --full
15
16# Quick validation (core checks only - faster)
17.claude/skills/game-architect/scripts/validate_all.sh --quick
18
19# Individual checks (core)
20.claude/skills/game-architect/scripts/check_file_sizes.sh # Files under 800 lines
21.claude/skills/game-architect/scripts/check_layer_boundaries.sh # No game logic in engine/
22.claude/skills/game-architect/scripts/check_structure.sh # Files in correct locations
23.claude/skills/game-architect/scripts/check_import_cycles.sh # No circular imports
24
25# Individual checks (extended)
26.claude/skills/game-architect/scripts/check_complexity.sh # Function size, nesting
27.claude/skills/game-architect/scripts/check_ailang_sync.sh # AILANG ↔ Go types match
28.claude/skills/game-architect/scripts/check_api_stability.sh # sim_gen API unchanged
29.claude/skills/game-architect/scripts/check_coverage.sh # Test coverage
30.claude/skills/game-architect/scripts/check_dependencies.sh # Package import graph
31.claude/skills/game-architect/scripts/pre_release_check.sh # Build, tests, TODOs
32```
33
34## When to Use This Skill
35
36Invoke this skill when:
37- Before tagging a version release
38- After major refactoring
39- User asks "check architecture" or "validate structure"
40- Periodic codebase health checks
41- After adding new files/directories
42
43## Architecture Rules
44
45### The Key Question: AILANG or Engine?
46
47**Ask:** Does this affect gameplay outcomes?
48
49| If YES → AILANG | If NO → Engine OK |
50|-----------------|-------------------|
51| Position, health, inventory | Decorative particles |
52| NPC behavior, dialogue | Screen transitions |
53| Time dilation, velocity | Shader effects |
54| Planet data, civilizations | UI layout math |
55| Game mode, decisions | Asset loading |
56
57```
58AILANG owns WHAT is happening (state, logic, decisions)
59Engine owns HOW it looks (rendering, animation, polish)
60```
61
62### Four-Layer Separation
63
64| Layer | Location | Purpose | Allowed Content |
65|-------|----------|---------|-----------------|
66| **Source** | `sim/*.ail` | Game logic (AILANG) | Types, pure functions |
67| **Generated** | `sim_gen/*.go` | Generated from AILANG | Game types (OK - generated) |
68| **Game Views** | `game_views/*.go` | Game-specific rendering | DomeRenderer, DeckStack |
69| **Engine** | `engine/*.go` | Generic rendering (reusable) | DrawCmd, Camera, Assets |
70| **Entry** | `cmd/*.go` | Wiring | Main, game loop |
71
72### Engine Genericization (Critical)
73
74**Goal:** Engine should work unchanged for ANY AILANG game.
75
76**Before adding to engine/, ask:** Could a different game use this unchanged?
77
78| If YES | If NO |
79|--------|-------|
80| → OK for `engine/` | → Put in `game_views/` |
81
82**engine/ must be generic:**
83- ✅ DrawCmd rendering (any variant)
84- ✅ Asset loading, camera, shaders
85- ❌ Deck names (Core, Engineering, Bridge)
86- ❌ Planet names (Saturn, Earth)
87- ❌ Crew roles (pilot, comms, scientist)
88- ❌ Game-specific state types
89
90**sim_gen/ is fine:**
91- Generated from AILANG - game types belong there
92- Never manually edit
93
94**game_views/ for game-specific rendering:**
95- DomeRenderer (solar system viz)
96- DeckStackRenderer (5-deck ship)
97- Any code using sim_gen types beyond DrawCmd
98
99### Layer Boundaries (Critical)
100
101**engine/ must NOT contain:**
102- Game state (positions, health, time) - use AILANG
103- Game logic (NPC AI, decisions) - use AILANG
104- Hardcoded game data (planet configs) - use AILANG
105- Game-specific types (DeckType, DomeViewState) - use game_views/
106
107**engine/ CAN contain:**
108- Generic DrawCmd rendering
109- Decorative particles (no gameplay impact)
110- Screen transition animations
111- Shader/visual effects
112- UI layout helpers
113
114### File Size Limits
115
116| Threshold | Action |
117|-----------|--------|
118| > 800 lines | **Error** - must split file |
119| > 600 lines | **Warning** - consider splitting |
120| > 100 lines/function | **Warning** - extract functions |
121
122## Workflow
123
1241. **Run full validation**: `./scripts/validate_all.sh`
1252. **Review violations**: Check output for ✗ markers
1263. **Fix issues**: Refactor code to correct layer
1274. **Re-validate**: Ensure all checks pass
1285. **Proceed with release**: Once clean
129
130## Checks Performed
131
132### Core Checks (blocking)
133
134| Script | Purpose |
135|--------|---------|
136| `check_file_sizes.sh` | Max 800 lines/file, warn at 600 |
137| `check_layer_boundaries.sh` | No game logic in engine/, no rendering in sim_gen/ |
138| `check_structure.sh` | Files in correct directories |
139| `check_import_cycles.sh` | No circular package dependencies |
140| `pre_release_check.sh` | Build, tests, TODOs, debug code |
141
142### Extended Checks (warnings)
143
144| Script | Purpose |
145|--------|---------|
146| `check_complexity.sh` | Function size (<100 lines), nesting depth, param count |
147| `check_ailang_sync.sh` | AILANG types match sim_gen Go types |
148| `check_api_stability.sh` | sim_gen exports haven't changed unexpectedly |
149| `check_coverage.sh` | Test coverage for critical paths |
150| `check_dependencies.sh` | Package import graph, layer violations |
151
152### API Stability
153
154The API stability check maintains a baseline of sim_gen exports:
155
156```bash
157# Update baseline after intentional API changes
158.claude/skills/game-architect/scripts/check_api_stability.sh --update
159```
160
161## Design Doc Management
162
163Track implementation progress of design docs through sprint files:
164
165```bash
166# Audit design docs - check which have sprints
167.claude/skills/game-architect/scripts/audit_design_docs.sh
168```
169
170### Design Doc Workflow
171
1721. **Create design doc** in `design_docs/planned/next/`
1732. **Use sprint-planner skill** to create sprint plan in `sprints/`
1743. **Execute sprint** (sprint tracks implementation progress via checkboxes)
1754. **When sprint complete**, move doc to `design_docs/implemented/vX_Y_Z/`
176
177### Audit Output
178
179The audit script checks:
180- Which design docs have corresponding sprint files
181- Sprint completion percentage (via checkbox counting)
182- Orphan sprints (sprints without design docs)
183
184Design docs WITHOUT sprints need planning before implementation.
185
186## Resources
187
188- [Architecture Rules](resources/architecture_rules.md) - Detailed layer boundaries and examples
majiayu000