Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/setup-engine.md

Skill Test Spec: /setup-engine

Skill Summary

/setup-engine pins the project's engine, version and language. It accepts [engine], [engine] [version], refresh, upgrade [old] [new], or no argument for guided selection. For Godot it asks which language (GDScript, C# or Both) before showing the Technology Stack. It then:

• writes the Technology Stack and the ENGINE-REFERENCE-IMPORT line to CLAUDE.md after "May I write these engine settings to CLAUDE.md?"
• fills .claude/docs/technical-preferences.md (the legacy mirror: naming conventions, specialist routing table, input/platform, performance budgets) after the user approves the presented defaults
• dual-writes the engine, specialists, naming and commands blocks to project.yaml — the primary config store — after "May I write the engine, specialists, naming, and commands blocks to project.yaml?"
• updates or creates docs/engine-reference/<engine>/, scaffolds project.godot for Godot (never for Unity or Unreal), and reads everything back with project-coherence.sh

On a re-run it edits existing project.yaml blocks in place rather than duplicating them. No director gates apply. The verdict is COMPLETE when the engine is configured.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keyword: COMPLETE
• Contains "May I write" language before writing CLAUDE.md and before writing the project.yaml blocks
• Has a next-step handoff (Section 12 prints one tier-matched Next-Steps list, e.g. /brainstorm at minimal)

---

Director Gate Checks

None. /setup-engine is a technical configuration skill. No director gates apply.

---

Test Cases

Case 1: Godot 4 + GDScript — Full engine configuration

Fixture:

• project.yaml has no engine block; technical-preferences.md holds only placeholders
• No design/gdd/game-concept.md and no design/game-brief.md
• docs/engine-reference/godot/VERSION.md already pins 4.6
• No project.godot at the repo root; the user approves every write

Input: /setup-engine godot 4.6

Expected behavior:

1. Full-spec mode: Section 2's guided selection is skipped
2. Skill asks the Godot language question (A GDScript / B C# / C Both); user picks GDScript
3. Skill shows the Technology Stack and asks "May I write these engine settings to CLAUDE.md?"
4. Technical preferences are presented with GDScript naming (snake_case files and variables) and the A3 routing table: .gd → godot-gdscript-specialist, .gdshader → godot-shader-specialist, .tscn → godot-specialist
5. Because Section 2 never ran and no design artifact exists, the skill asks the project-shape question (2D/3D, web or not) instead of writing Forward+/Jolt from the engine name
6. commands.build export preset is asked, never defaulted; commands.test is the gdUnit4 GdUnitCmdTool.gd command
7. Skill asks "May I write the engine, specialists, naming, and commands blocks to project.yaml?"
8. Section 6 reads its coverage table: 4.6 is beyond the Godot row (~4.3), so the knowledge risk is HIGH
9. VERSION.md already pins 4.6 → nothing to regenerate; only its Installed at pin time row is written, from the Section 3 probe
10. Skill proposes project.godot and asks before creating it; verdict COMPLETE

Assertions:

• engine.name is Godot and engine.language is GDScript in project.yaml
• naming.variables and naming.files are snake_case
• Routing table includes .gd, .gdshader, and .tscn entries; specialists.code is godot-gdscript-specialist
• The rendering/physics shape is asked, not inferred from the engine name
• "May I write" is asked before CLAUDE.md and before project.yaml are written
• Knowledge Risk is HIGH — the Section 6 table's cutoff is May 2025 and its Godot row ~4.3, as in the shipped VERSION.md
• Verdict is COMPLETE

---

Case 2: Unity + C# — Unity-specific configuration

Fixture:

• Placeholders only in technical-preferences.md; no engine block in project.yaml
• The user supplies the version and the build target when asked

Input: /setup-engine unity

Expected behavior:

1. Engine-only mode: version looked up and confirmed with the user
2. No language question (Unity is C#); CLAUDE.md Language is C#
3. Naming: PascalCase classes/methods, _camelCase private fields
4. Routing: .cs → unity-specialist, .shader/.shadergraph → unity-shader-specialist, .unity/.prefab → unity-specialist, .uxml/.uss → unity-ui-specialist
5. rendering: URP, physics: PhysX written directly — no shape question
6. commands.build target is asked (no hardcoded StandaloneLinux64); naming.constants carries the # UNVERIFIED comment
7. No Unity project is scaffolded; the user is told to create it in Unity Hub

Assertions:

• Engine field is set to Unity and Language to C#
• Naming conventions reflect C# conventions
• Routing table includes .cs and .unity entries
• No project-shape question is asked for Unity
• No Unity project files are written
• Verdict is COMPLETE

---

Case 3: Unreal — C++ primary, Blueprint routed to its specialist

Fixture:

• Placeholders only; the user never states that the project is Blueprint-primary
• The session runs on Windows (uname -s is neither Linux nor Darwin), so the Windows commands block applies

Input: /setup-engine unreal 5.7

Expected behavior:

1. The primary-language question defaults to C++, so CLAUDE.md Language reads C++ (primary), Blueprint (gameplay prototyping) — the line follows the answer, and a Blueprint-primary answer would write Blueprint (primary), C++ where needed
2. project.yaml gets engine.language: "C++" (Blueprint only when the project is Blueprint-primary)
3. Routing: .uasset BP classes → ue-blueprint-specialist; .umap/.uasset → unreal-specialist; specialists.additional includes ue-blueprint-specialist
4. commands are written as single-quoted scalars under a # TODO: confirm these comment; engine.path is recorded
5. Performance budgets are asked via AskUserQuestion (set defaults / leave [TO BE CONFIGURED]), not pre-filled
6. No .uproject is scaffolded; verdict COMPLETE

Assertions:

• Engine field is set to Unreal Engine 5.7 and engine.language is C++
• Routing table includes .uasset and .umap entries
• ue-blueprint-specialist is assigned for Blueprint graphs
• commands carry the # TODO: confirm these comment
• Verdict is COMPLETE

---

Case 4: Re-run on a Configured Project — blocks edited in place

Fixture:

• project.yaml already has engine (Godot 4.6), specialists, naming, a modes block, and a commands block missing its smoke key
• project.godot exists at the repo root
• docs/engine-reference/godot/VERSION.md pins 4.6

Input: /setup-engine godot 4.6

Expected behavior:

1. Skill reads project.yaml before editing it
2. Each existing block is edited in place; commands.smoke is added to the partial block; no second copy of any block is appended
3. modes and every other non-engine block are preserved untouched
4. The existing project.godot is not overwritten — the skill says so and skips
5. VERSION.md pins the same version → nothing to regenerate: Engine Version, Project Pinned and Last Docs Verified are left as they are, and only the Installed at pin time row is written with the Section 3 probe result
6. Verdict COMPLETE

Assertions:

• No block is duplicated in project.yaml, and the missing commands.smoke key is added
• modes (and all other non-engine content) is unchanged
• project.godot is not overwritten
• For a same-version pin, Engine Version, Project Pinned and Last Docs Verified are untouched and Installed at pin time is written
• Verdict is COMPLETE

---

Case 5: Director Gate Check — No gate; setup-engine is a utility skill

Fixture:

• Fresh project with no engine configured

Input: /setup-engine godot

Expected behavior:

1. Skill completes full engine configuration
2. No director agents are spawned at any point
3. No gate IDs appear in output

Assertions:

• No director gate is invoked
• No gate skip messages appear
• Verdict is COMPLETE without any gate check

---

Case 6: Installed Editor Older Than the Chosen Version — ask, then record

Fixture:

• As Case 1; docs/engine-reference/godot/VERSION.md pins 4.6
• godot --version reports 4.5.1.stable
• The user picks "pin the newer one and upgrade later"

Input: /setup-engine godot 4.6

Expected behavior:

1. Section 3 probes the installed editor and finds 4.5.1 — a mismatch
2. Skill states both versions and asks, offering three options: pin the installed version, pin the newer one and upgrade later, or pin the newer one deliberately
3. The answer is recorded; the skill does not pick for the user
4. VERSION.md already pins 4.6, so nothing is regenerated, but its Installed at pin time row is written with 4.5.1
5. Verdict COMPLETE

Assertions:

• Both versions are stated and all three options are offered
• The skill waits for the user's choice rather than picking silently
• Installed at pin time records 4.5.1 — the same-version branch does not skip it
• Engine Version, Project Pinned and Last Docs Verified are not restamped

---

Case 7: Godot not on PATH — the probed executable goes into commands.*

Fixture:

• As Case 1, on Windows; godot --version fails — godot is not on PATH
• The probe finds C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe, which reports 4.6.1.stable
• The user names the export preset Windows Desktop

Input: /setup-engine godot 4.6

Expected behavior:

1. Section 3 reads the version from the executable it found — it does not report "no engine installed"
2. build, test, run and smoke each start with the quoted full path, as single-quoted scalars; build quotes its preset with double quotes: build: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless --export-debug "Windows Desktop"'
3. test keeps --remote-debug tcp://127.0.0.1:0 and the gdUnit4 runner arguments after the path
4. engine.path records the executable
5. Verdict COMPLETE

Assertions:

• No commands.* value names bare godot
• Every Godot command value is a single-quoted scalar and none holds both quote types
• engine.path records the editor executable
• Variant — the probe finds nothing and the user does not know where Godot is: bare godot is kept under a # TODO: godot is not on PATH here comment, and the skill says the commands will not run until the path is set

---

Protocol Compliance

• Presents draft configuration before asking to write
• Asks "May I write" before writing CLAUDE.md and the project.yaml blocks; technical preferences are written only after the user approves the presented defaults
• Respects engine argument when provided (skips guided selection)
• Dual-writes project.yaml and technical-preferences.md, then reads project.yaml back to confirm they agree
• On re-run, edits existing project.yaml blocks in place without duplicating them
• Writes the probed editor path into commands.* — for Unity always, for Godot whenever godot is not on PATH — never a bare executable that does not resolve
• Never defaults the Godot export preset or the Unity build target — asks for it; Unreal's commands are best-effort values matched to the machine's OS (-platform=Win64 on Windows, Linux on Linux) under a # TODO comment; on macOS only build is written, and test, run and smoke stay TODO lines
• Writes the Section 3 probe into VERSION.md's Installed at pin time row whatever the outcome, after asking "May I record Installed at pin time: … in docs/engine-reference/<engine>/VERSION.md?"
• Verdict is COMPLETE after configuration is written

---

Coverage Notes

• Godot C# and Both follow Case 1 with the A1/A2/A3 variants from references/godot-language-config.md; not separately tested.
• The refresh and upgrade subcommands (Sections 10–11) are not tested here.
• The Unreal Linux and macOS commands blocks (chosen by uname -s) are not fixture-tested; Case 3 pins Windows.
• Section 6 is a lookup against the skill's own coverage table, asserted in Case 1. The Section 7 reference docs for a version with no reference set yet depend on WebSearch results; not assertion-tested.
• A probe that cannot run reports installed version NOT DETERMINED — never "no engine installed"; not separately tested.
• A Blueprint-primary Unreal answer (engine.language: "Blueprint") follows Case 3 with the other Language line; not separately tested.