create-architecture skill

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,workflow,docs.density

Resolved above — use as-is; --review overrides review_mode. No block → defaults in .claude/docs/config-resolution.md.

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.

See .claude/docs/director-gates.md for the full check pattern. Individual gate definitions live in .claude/docs/director-gates/[gate-id].md — the spawned agent reads its own gate file; do not read it in the parent session.

Every AskUserQuestion call follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automationalwaysask categories always prompt).

docs.density — it controls per-section depth, where workflow controls which sections exist. modes.rigor sets both together; set docs.density explicitly to vary depth alone: terse = layer diagrams + decision bullets, no essays; balanced = diagrams + paragraph explanations of layer choices (default); thorough = full prose with rationale, trade-offs, and alternatives considered per layer. Apply it to every section you author.

workflow (see .claude/docs/workflow-modes.md):

boundaries, full ADR audit.

• full — full architecture: all layers, module ownership, data flow, API

• standard — simplified: system layer map + critical ADR list only.
• minimal — not required. Can still be run voluntarily.

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 four project-wide engine documents in full — they are small, and every part of each is used:

→ Extract: engine name, version, LLM cutoff, post-cutoff risk levels

1. docs/engine-reference/[engine]/VERSION.md

→ Extract: all HIGH and MEDIUM risk changes

1. docs/engine-reference/[engine]/breaking-changes.md

→ Extract: APIs to avoid

1. docs/engine-reference/[engine]/deprecated-apis.md

→ Extract: post-cutoff best practices that differ from training data

1. docs/engine-reference/[engine]/current-best-practices.md

Then read only the module docs whose domain this game actually uses — not the whole modules/ directory:

then match against the domains present in design/gdd/systems-index.md (the same domain vocabulary the ADR template uses: Physics, Rendering, UI, Audio, Navigation, Animation, Networking, Core, Input). Read the matching modules; skip the rest. → Extract: current API patterns per domain

1. docs/engine-reference/[engine]/modules/ — glob it to establish what exists,

A game with no multiplayer system does not need the networking module loaded to write its architecture, and loading it costs the same as one that does. If the domain match is ambiguous, read the module — a missed engine constraint is far more expensive here than a redundant read, because this phase is where those constraints get baked into the architecture.

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

Load the 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

Check both exist before reading either. Neither is optional here, and both need an absence branch — §0a stops for an unconfigured engine, and these two matter just as much:

• systems-index.md absent — stop:

"No systems index found. Run /map-systems first. An architecture written

without it invents layers for systems nobody mapped, and every ADR, epic and

story downstream inherits that invention."

At minimal the index is not required (§ tier note above) — say so and proceed from the brief instead.

/brainstorm. At minimal, read design/game-brief.md in its place; if that is absent too, stop — there is no design record to architect against.

• game-concept.md absent — at standard/full, stop and point at

Present-but-empty is the case that most looks like present.

• Either present but empty or still template placeholders — treat as absent.

Do not proceed on a partial read and note it later. This phase is where design assumptions get baked into ADRs, and an assumption made here is re-derived by everything downstream rather than re-checked.

key absent or empty, fall back to .claude/docs/technical-preferences.md); allowed libraries and forbidden patterns from .claude/docs/technical-preferences.md (not migrated to project.yaml)

1. Project config — naming. and performance. from project.yaml (for any

sections that carry them, not from whole files. Establish the denominator first (glob design/gdd/.md, count N**), then:

1. Every GDD in design/gdd/ — extract technical requirements from the

Grep pattern="^## (Detailed Rules|Detailed Design|Formulas|Dependencies|Tuning Knobs|Acceptance Criteria)" glob="design/gdd/*.md" output_mode="content" -A 40

Overview and Player Fantasy are narrative and imply no architecture; the scanned set is where rules, numbers, and cross-system contracts live. Accept either ## Detailed Rules or ## Detailed Design — the design standard and the GDD template disagree on the name and they denote the same section.

Full-read a GDD when it matched zero sections (it predates the template — a zero-match means "unstructured", never "no requirements") or when a scanned section refers to material outside itself. Never treat an absent section as an absent requirement: report any GDD that contributed nothing, rather than letting it drop silently out of the baseline below.

For each, extract:

• 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