Claude-Code-Game-Studios/.claude/skills/setup-engine/references/5.5-project-yaml.md

/setup-engine — Section 5.5: Populate project.yaml

Part of /setup-engine. SKILL.md names when to read this file; the settings it resolved and the rules under its later headings still apply here.

5.5 Populate project.yaml (Primary Config Store)

In this file:

• 5.5.1 Build the four blocks
• 5.5.2 Write the blocks to project.yaml
• 5.5.3 Verify the dual-write

v1.1: project.yaml at the repo root is the primary store for project configuration. The .claude/docs/technical-preferences.md file written in Section 5 is kept as a legacy mirror for backward compatibility. This step is a dual-write — the same engine facts go into both files, and project.yaml wins when a skill reads a key present in both.

After technical-preferences.md is written and approved, dual-write the structured config into project.yaml. Four blocks are written: engine, specialists, naming, and commands.

5.5.1 Build the four blocks

Derive every value from the engine and language already chosen in Sections 3–4. Do NOT re-ask for the engine, version or language — reuse those decisions.

That is not a blanket "never ask". rendering and physics below depend on two further inputs — target platform and 2D-vs-3D — which Section 2 collects on only one of the four entry paths. When they were never collected, ask; the unavailable-branch under the project-shape table says how.

engine block:

engine:
  name: "<Godot|Unity|Unreal>"
  version: "<version from Section 3>"
  language: "<GDScript|C#|C++|Blueprint>"
  rendering: "<engine default — see table>"
  physics: "<engine default — see table>"

On Godot these two values depend on the answers Section 2 already collected — the target platform and 2D-vs-3D — so do not pick them from the engine name alone. On Unity and Unreal the table has a single any row and the engine name is sufficient; take those rows directly.

Engine	Project shape	rendering default	physics default
Godot 4.x	2D · web target	Compatibility	Godot Physics 2D
Godot 4.x	2D · non-web	Forward+	Godot Physics 2D
Godot 4.x	3D · web target	Compatibility	Jolt
Godot 4.x	3D · non-web	Forward+	Jolt
Unity	any	URP	PhysX
Unreal	any	Lumen + Nanite (deferred)	Chaos

Why this table has a shape column and the others do not. Both Godot defaults were wrong for a 2D browser game, and both were wrong from data this skill had already collected and then discarded.

• Jolt is Godot's default 3D engine. docs/engine-reference/godot/modules/physics.md: "Jolt Physics is the DEFAULT 3D engine" and "2D physics UNCHANGED (still Godot Physics 2D)". Writing Jolt on a 2D project sends the implementer to tune a backend their game does not use.
• Forward+ is desktop-focused. docs/engine-reference/godot/modules/rendering.md: Forward+ is "Full featured, desktop-focused"; Compatibility is "OpenGL 3.3 / WebGL 2, broadest hardware support" — the browser path.

If Section 2's platform answer was Multiple platforms including web, use the web row: the renderer must work everywhere the game ships.

Godot only — Unity and Unreal have one row each, keyed any. Shape cannot change rendering or physics for those two, so do not run the resolution below for them: asking an operator a question whose answer you will discard is exactly what §5.5.1 opens by forbidding. On Unity write URP/PhysX and on Unreal write Lumen + Nanite (deferred)/Chaos straight from the table.

Section 2 did not necessarily run — check before reading its answers. Target platform and 2D-vs-3D are collected under Questions 2–6, only if no prior engine experience. Three of the four entry paths never reach them: /setup-engine <engine> <version> and /setup-engine <engine> skip Section 2 outright, and guided mode skips the matrix as soon as the user names an engine they have worked in before. Only guided mode answered None or Multiple collects both.

Resolve each input in this order and stop at the first that answers:

1. Section 2's answers, if that path ran.
2. The design artifact — design/gdd/game-concept.md at standard/full, design/game-brief.md at minimal. Section 2 already extracts platform targets from these; extract 2D-vs-3D the same way when it is stated.
3. Ask. Do not infer the shape from the engine name, and do not write a row you could not justify:
   • Prompt: "rendering and physics depend on the project's shape, which hasn't been established yet. Is this 2D or 3D, and does it ship to web?"
   • Options: 2D · non-web / 2D · web / 3D · non-web / 3D · web, plus Leave as [TO BE CONFIGURED] — a legitimate answer here, revisited via /settings once the concept exists.

[TO BE CONFIGURED] is a valid value for both keys. A wrong Jolt on a 2D project is worse than an unset one, because nothing downstream questions it.

• rendering and physics are engine-typical defaults — tell the user they can be changed later via /settings if the project uses a different setup.
• For Godot Both, write language: "GDScript" (the primary gameplay language); the C# usage is recorded in technical-preferences.md.
• For Unreal, write language: "C++" — or "Blueprint" only if the project is Blueprint-primary. Blueprint as a secondary tool does not change this value.

specialists block — copy directly from the routing table chosen in Section 5 (A3 in references/godot-language-config.md for Godot):

Engine / language	code	shader	ui	additional
Godot — GDScript	godot-gdscript-specialist	godot-shader-specialist	godot-specialist	[godot-gdextension-specialist]
Godot — C#	godot-csharp-specialist	godot-shader-specialist	godot-specialist	[godot-gdextension-specialist]
Godot — Both	godot-gdscript-specialist	godot-shader-specialist	godot-specialist	[godot-csharp-specialist, godot-gdextension-specialist]
Unity	unity-specialist	unity-shader-specialist	unity-ui-specialist	[unity-dots-specialist, unity-addressables-specialist]
Unreal	unreal-specialist	unreal-specialist	ue-umg-specialist	[ue-gas-specialist, ue-blueprint-specialist, ue-replication-specialist]

specialists:
  code: "<code specialist>"
  shader: "<shader specialist>"
  ui: "<ui specialist>"
  additional: ["<...>"]

naming block — enum values (NOT the prose form used in technical-preferences.md). Use the column matching the engine and, for Godot, the language:

Field	Godot GDScript	Godot C#	Unity	Unreal
classes	PascalCase	PascalCase	PascalCase	PascalCase
variables	snake_case	camelCase	camelCase	PascalCase
constants	SCREAMING_SNAKE	PascalCase	SCREAMING_SNAKE	SCREAMING_SNAKE
signals	past_tense	on_event_name	PascalCase On<Event>	PascalCase On<Event>
files	snake_case	PascalCase	PascalCase	PascalCase
scenes	snake_case	PascalCase	PascalCase	PascalCase

The Unreal column is sourced, not inherited from the table's generic shape. variables: camelCase and signals: on_event_name are the two rows that shape would produce, and both are wrong for Unreal. Checked against this repo's pinned reference: docs/engine-reference/unreal/ contains zero camelCase variable declarations and uses PascalCase throughout (int32 Health;, FVector ServerPosition;), and the word "signal" never appears in it at all — it is Godot vocabulary. Unreal has delegates and events, and the reference's handlers are PascalCase On<Event>.

Two caveats kept rather than smoothed over. (1) classes: PascalCase is incomplete for Unreal, not wrong: UE requires a mandatory type prefix (U/A/F/E/I/T) that this enum cannot express, so an Unreal project's coding standards must state it separately. (2) scenes is a category mismatch — Unreal has Levels and Maps under World Partition, not scenes — left in place because the key is shared across engines and renaming it is a schema change, not a value fix.

The blast radius is limited: naming.* is currently a documented-but-unread setting, so wrong values misinform a human reading project.yaml rather than driving any automated check — today. That is a reason to get them right now, while it is cheap.

Three further rules for this table.

The Unity build row must not hardcode -buildTarget StandaloneLinux64. A hardcoded target gives every Unity project a Linux build command, whatever platform it actually ships on. The row reads <TARGET>: ask the operator for the build target and write the value they give. The correct -buildTarget identifiers are not sourceable from docs/engine-reference/unity/, so this skill must not emit one from recall — the same call made for /security-audit's save patterns and for Unity's release dates. A wrong-but-plausible default is worse than an explicit question: it produces a commands.build that runs, succeeds, and builds the wrong artifact.

-buildTarget alone builds nothing. It switches the active platform and exits 0 (verified on 6000.3.23f1). The row also needs a player-build flag, -build<PLATFORM>Player <output path> — for Windows 64-bit, -buildWindows64Player Builds/Win64/<Game>.exe (verified: exit 0 and an .exe; exit 1 on a compile error or when no scene is in the build settings). Ask which platform, and confirm any other platform's flag against Unity's command-line documentation rather than recalling one.

The Godot build row must not hardcode 'Linux/X11' either — same defect, same remedy. A Godot export preset name is project-defined: it is whatever string the operator typed into export_presets.cfg, and the shipped defaults are per-platform (Windows Desktop, macOS, Web, Linux/X11). Writing 'Linux/X11' gives a Windows-targeting project a build command that fails with Unknown export preset, and gives a project that does have a Linux preset a command that silently builds the wrong platform. The row reads <PRESET>: ask the operator which export preset to build and write the value they give, exactly as the Unity row does. If no presets exist yet — common, since /setup-engine usually runs before the Godot project has any — write [TO BE CONFIGURED] and say so, rather than guessing a name that does not exist.

The constants row must not contradict this skill's own prose. The table says SCREAMING_SNAKE for Unity; the Unity section of this same file says "Constants: PascalCase or UPPER_SNAKE_CASE". Both cannot be authoritative, and an agent following one produces config the other rejects. The row is left unchanged pending sourcing rather than picked by preference — neither docs/engine-reference/unity/ nor unreal/ contains a SCREAMING_SNAKE constant to confirm or refute it, and the Unreal run flagged the same row as wrong for Unreal on the same grounds. Resolve by adding a naming section to the engine references, then correct table and prose together. Until then, treat naming.constants as unverified for Unity and Unreal.

Write that caveat into project.yaml, do not leave it here. On Unity and Unreal, emit the constants line with a trailing comment:

naming:
  constants: SCREAMING_SNAKE   # UNVERIFIED — not sourceable from
                               # docs/engine-reference/<engine>/; confirm before relying on it

Without it, a value the skill knows is unsourced is recorded as flatly as classes: PascalCase, which is sourced, and the reader of the primary config store cannot tell them apart. The commands block nine lines below already does exactly this with its # TODO: confirm these line — this is the same pattern, applied to the value that needs it just as much.

For Godot Both, use the GDScript column — .gd files dominate gameplay scripting; .cs files follow C# conventions per-file (see A2 in references/godot-language-config.md).

naming:
  classes: <value>
  variables: <value>
  constants: <value>
  signals: <value>
  files: <value>
  scenes: <value>

commands block — engine-default shell commands, simple-string form:

Engine	build	test	run	smoke
Godot	godot --headless --export-debug '<PRESET>' (ASK — do not default)	godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode	godot --path . --windowed --resolution 1280x720	godot --headless --quit-after 5
Unity	"<Unity editor>" -batchmode -quit -projectPath . -buildTarget <TARGET> -build<PLATFORM>Player Builds/<Target>/<Game>.exe (ASK — do not default)	"<Unity editor>" -batchmode -runTests -projectPath . -testPlatform EditMode -testResults test-results/editmode.xml	Builds/<Target>/<Game>.exe -screen-width 1280 -screen-height 720 -screen-fullscreen 0	"<Unity editor>" -batchmode -quit -projectPath . -logFile -

What each exit code proves — every row verified on the pinned engines. Godot test exits 0 when all pass, 100 on a failure, 101 when all pass but nodes leaked (a warning, not a failure), 105 when a test script does not parse, and 103 / 104 when gdUnit4 cannot run at all (headless refused, Godot older than 4.3). Keep --remote-debug tcp://127.0.0.1:0: without it a script error opens Godot's interactive debugger and the run waits at a debug> prompt forever instead of exiting. Run godot --headless --path . --import before it on a fresh clone: with no .godot/ class cache, GdUnitCmdTool.gd did not load and the run exits 1 having run nothing. Unity test exits 0 / 2, and a results file with testcasecount="0" means no test was compiled — not a pass. It runs Edit Mode only: Play Mode tests under Assets/Tests/PlayMode/ need a second run into their own results file (-testPlatform PlayMode -testResults test-results/playmode.xml), which /smoke-check makes whenever that folder holds tests and CI runs as its own step. Unity smoke exits 1 on a compile error, 0 when clean. Godot smoke exits 0 even on a parse error — it is a boot check: read its output for SCRIPT ERROR. It also needs run/main_scene set: without one it prints Can't run project: no main scene defined and never exits, so run it under a timeout. Unity smoke compiles only the editor-side assemblies; an error that exists only in a player build (an Editor/ script without its own assembly) shows up in build, not here. The real Godot parse check is godot --headless --path . --import, then godot --headless --path . -s res://.claude/scripts/godot-parse-check.gd -- res://<file>.gd … (exit 1 when a script does not load). --check-only is not one: it fails valid code that names an autoload. <Unity editor> is the editor executable's full path, quoted. Never write bare Unity: on PATH that name may be Unity's separate CLI, which rejects -batchmode with exit 2 — the same code as a failed test.

commands.run is the one the run-and-observe step depends on. It must launch the game, windowed, at a fixed resolution — never the editor, and never with a headless / batch / null-RHI flag, which exist to skip rendering. /dev-story Phase 6 step 4 appends the per-engine capture flags to it (.claude/docs/run-and-observe.md). smoke is Unity's parse check, test feeds /smoke-check; build is the one row you must ask for.

YAML quoting rule — applies to EVERY command value. yaml-helper.sh — the parser every config read in this framework goes through — decodes no escape sequences: neither \" inside a double-quoted scalar nor '' inside a single-quoted scalar. It takes the first matching quote character as the end of the value and discards the rest, so "he said \"hi\" now" parses as he said \. Verified against the parser, not inferred. The rule is load-bearing: /smoke-check and /dev-story run these values, /settings reads and writes them through this parser, and the same holds for every other quoted value in project.yaml. Pick the quote style that needs no escaping:

• value contains a single quote ' (e.g. the Godot build above) → wrap it in a double-quoted YAML scalar: "... 'Linux/X11' ..."
• value contains a double quote " (e.g. the Unreal test/smoke below) → wrap it in a single-quoted YAML scalar: '... "Quit" ...'
• value contains neither → use a double-quoted scalar for consistency. Never use a quote style that forces an escape (\" or '') — the parser truncates the value at the escape. A value containing BOTH quote types cannot be represented for this parser; rewrite the command to drop one.

Godot / Unity — write the table values directly, substituting the operator's answer for <PRESET> / <TARGET> / <PLATFORM>, and the editor's full path for <Unity editor>. Godot's build contains a single quote, so it takes a double-quoted scalar (Windows Desktop below is the example answer, not a default — write what the operator said):

commands:
  build: "godot --headless --export-debug 'Windows Desktop'"
  test: "godot --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode"
  run: "godot --path . --windowed --resolution 1280x720"
  smoke: "godot --headless --quit-after 5"

Write bare godot only when Section 3's godot --version ran — that is, godot is on PATH. Otherwise (the usual case on Windows and macOS) substitute the executable the probe found or the user gave — a Windows Godot_v<version>-stable_win64.exe, macOS /Applications/Godot.app/Contents/MacOS/Godot — as its full path, in double quotes, for the leading godot in all four values, exactly as <Unity editor> is. The value then holds double quotes, so it takes a single-quoted scalar, and build quotes its preset with double quotes too, so no value holds both quote types. Godot not on PATH, installed under C:/Program Files/Godot/:

commands:
  build: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless --export-debug "Windows Desktop"'
  test: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless -s -d --remote-debug tcp://127.0.0.1:0 res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://tests --ignoreHeadlessMode'
  run: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --path . --windowed --resolution 1280x720'
  smoke: '"C:/Program Files/Godot/Godot_v4.6.1-stable_win64.exe" --headless --quit-after 5'

If the probe found no executable and the user does not know where it is, keep bare godot, put # TODO: godot is not on PATH here — set the editor's full path via /settings above the block, and say so: those commands will not run until one of the two is fixed.

For Unity, probe the Hub install (C:/Program Files/Unity/Hub/Editor/<version>/Editor/Unity.exe on Windows, /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity on macOS, /home/<user>/Unity/Hub/Editor/<version>/Editor/Unity on Linux) or ask. Write the expanded absolute path — a ~ inside quotes is not expanded, and the command then exits 127. The quoted path puts double quotes in the command, so the value takes a single-quoted scalar:

commands:
  test: '"C:/Program Files/Unity/Hub/Editor/6000.3.23f1/Editor/Unity.exe" -batchmode -runTests -projectPath . -testPlatform EditMode -testResults test-results/editmode.xml'
  smoke: '"C:/Program Files/Unity/Hub/Editor/6000.3.23f1/Editor/Unity.exe" -batchmode -quit -projectPath . -logFile -'

Also write engine.path if the editor is not on PATH. Agents and /smoke-check read it to find the editor, but a command is run as written — engine.path is never spliced into commands.* at run time, which is why the full path goes into the commands above — and on Windows and macOS none of the three engines installs onto PATH by default (on macOS the editor is inside an app bundle, e.g. /Applications/Godot.app/Contents/MacOS/Godot). Ask for or probe the install location and record it — the editor executable for Godot and Unity, the engine folder (<UE root>) for Unreal:

engine:
  path: "C:/Program Files/Epic Games/UE_5.7"   # omit if the editor is on PATH

This is not cosmetic. Without it, an agent reports "no editor on this machine" and ships C++ it never compiled — on a machine where that engine WAS installed. Nothing in the project told it where to look, so absence of a path read as absence of an engine.

For Unreal, UE build/test commands vary by version and project setup. Write best-effort values and add a # TODO comment so the user knows to confirm them. Substitute the engine's install folder for <UE root> (the value you record as engine.path) — none of the editor binaries is on PATH. The commands embed double quotes, so they take single-quoted scalars. Write the block for the machine the project is developed on (uname -s: Linux, Darwin = macOS, anything else = Windows). The Windows block was run on UE 5.7; the Linux and macOS lines come from Epic's documentation, recorded with their sources in docs/engine-reference/unreal/current-best-practices.md ("Command Line").

Windows:

commands:
  # TODO: confirm these for your UE version and project — adjust via /settings
  build: '"<UE root>/Engine/Binaries/DotNET/AutomationTool/AutomationTool.exe" BuildCookRun -project="$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -platform=Win64 -build -cook'
  test: '"<UE root>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -ExecCmds="Automation RunTests <project>.; Quit" -unattended -nullrhi -stdout -FullStdOutLogOutput'
  run: '"<UE root>/Engine/Binaries/Win64/UnrealEditor.exe" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -game -windowed -ResX=1280 -ResY=720'
  smoke: '"<UE root>/Engine/Binaries/Win64/UnrealEditor-Cmd.exe" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -game -nullrhi -unattended -stdout -ExecCmds="Quit"'

Linux — the editor binary is Engine/Binaries/Linux/UnrealEditor, the build scripts are shell scripts:

commands:
  # TODO: confirm these for your UE version and project — adjust via /settings
  build: '"<UE root>/Engine/Build/BatchFiles/RunUAT.sh" BuildCookRun -project="$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -platform=Linux -build -cook'
  test: '"<UE root>/Engine/Binaries/Linux/UnrealEditor" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -ExecCmds="Automation RunTests <project>.; Quit" -unattended -nullrhi -stdout -FullStdOutLogOutput'
  run: '"<UE root>/Engine/Binaries/Linux/UnrealEditor" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -game -windowed -ResX=1280 -ResY=720'
  smoke: '"<UE root>/Engine/Binaries/Linux/UnrealEditor" "$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -game -nullrhi -unattended -stdout -ExecCmds="Quit"'

macOS — only the build is sourced. Epic documents the UnrealEditor.app bundle but no command-line editor inside it, so write build and leave the other three as TODO lines rather than a guessed path; /smoke-check reports NOT ASSESSED for tests until the user sets commands.test:

commands:
  # TODO: confirm this for your UE version and project — adjust via /settings
  build: '"<UE root>/Engine/Build/BatchFiles/RunUAT.sh" BuildCookRun -project="$(pwd -W 2>/dev/null || pwd)/<project>.uproject" -platform=Mac -build -cook'
  # TODO: test, run and smoke — no documented command-line editor on macOS.
  # Set them via /settings to the editor command you run for this project.

On Windows, build calls AutomationTool directly: from Git Bash, RunUAT.bat fails ('C:\Program' is not recognized) whenever the project path has a space. AutomationTool.exe runs on the machine's .NET 8 runtime; RunUAT.bat brings its own SDK, so with no space in the path and no .NET 8 installed, use it. -build builds the editor target too (verified on 5.7).

Three details are load-bearing. The project path is absolute: UE 5.7 does not find a relative <project>.uproject and exits 1 (Project file not found) before anything runs. $(pwd -W 2>/dev/null || pwd) gives the C:/… form in Git Bash and the plain path elsewhere, run from the project root; $PWD alone fails when MSYS_NO_PATHCONV is set. smoke needs -game: without it UnrealEditor-Cmd boots the editor, where a bare Quit console command only ends a play-in-editor session — the process stays resident and the command never returns; with -game the same line boots headless and exits in seconds. test needs the ; Quit inside the Automation string: the automation runner handles that trailing Quit itself and exits the editor once the tests finish, and without it the run also never returns. Its filter runs every test whose full name contains <project>. — a substring match, not a prefix — so name tests <project>.[System].[Scenario] as qa-tester does. If the project's name is also an engine area — Audio, Core, Input, Test, System, Engine, Editor, AI, Math — <project>. also runs hundreds to thousands of the engine's own tests; give the tests a distinct root (say <project>Game.) and put the same root in the filter. This form exits 255 on a failing test AND on a filter that matches nothing (No automation tests matched, verified on 5.7), so /smoke-check reads the output, not the exit code. smoke carries -stdout for the same reason: without it a failed boot prints nothing. Do not swap in -TestExit="Automation Test Queue Empty": that form exits 0 on a failing test unless its report JSON is parsed.

5.5.2 Write the blocks to project.yaml

Show the user the full set of four blocks and ask:

"May I write the engine, specialists, naming, and commands blocks to project.yaml?"

Wait for confirmation, then apply based on the file's current state:

• project.yaml does not exist — create it with the Write tool using this v1.1 template (the four blocks appended after framework; replace <...> and the date):

  # CCGS project configuration — single source of truth for project settings.
  # Schema: grep the `## <key>` section of .claude/docs/effects-map.md —
  # it is ~31k tokens whole, ~900 per section. Do not open it entire.
  
  schema_version: 1
  
  framework:
    version: 1.1.3
    last_upgraded: <today's date>
  
  engine:
    name: "<...>"
    version: "<...>"
    language: "<...>"
    rendering: "<...>"
    physics: "<...>"
  
  specialists:
    code: "<...>"
    shader: "<...>"
    ui: "<...>"
    additional: ["<...>"]
  
  naming:
    classes: <...>
    variables: <...>
    constants: <...>
    signals: <...>
    files: <...>
    scenes: <...>
  
  commands:
    build: "<...>"
    test: "<...>"
    run: "<...>"
    smoke: "<...>"
  

  Do not seed modes.review_mode here. It is a rigor-fronted knob — modes.rigor supplies its value, so an explicit value would shadow the rigor expansion and pin the review mode regardless of the project's rigor.

• project.yaml exists — Read it first (the Edit tool requires the file to have been read this session), then, processing the blocks in the order engine → specialists → naming → commands, for each block:

  • Block absent — insert the whole block, appended after the last existing top-level block.
  • Block already present (a re-run of /setup-engine) — Edit the existing keys in place, and add any keys the block is missing (a partial block must end up with its full key set). Do NOT add a second copy of the block.

Unreal on macOS is the exception in both cases: commands.test, run and smoke are written as the TODO comment lines from the macOS block — never as <...> placeholders or a guessed path — and a re-run leaves them unset until the user sets them.

Preserve all other content in project.yaml (schema_version, framework, modes, project, etc.) — only the four blocks are touched.

5.5.3 Verify the dual-write

Read project.yaml back and confirm the four blocks are present and that engine.name, engine.language, and the naming values match what was written to technical-preferences.md. If they diverge, report the discrepancy to the user and stop — a split config corrupts skill and hook reads.

---