/create-architecture

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] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash, AskUserQuestion, Task
model: sonnet
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.

Resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean`

See `.claude/docs/director-gates.md` for the full check pattern.

**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]

Use `AskUserQuestion`:

• Prompt: "One or more engine domains are HIGH RISK — the LLM's knowledge may be unreliable for these areas. Architectural recommendations in these domains should be cross-referenced with the engine docs before being acted on. How would you like to proceed?"
• Options:
• `[A] Proceed — flag HIGH RISK domains throughout the output`
• `[B] Let me check the engine reference first — pause here`
• `[C] Show me which domains are HIGH RISK and why`

---

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