create-threenative 0.2.18 → 0.2.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/agent-docs/references/assertion-reference.md +1 -1
  2. package/agent-docs/references/capability-reference.md +792 -5
  3. package/agent-docs/references/kit-racing.md +4 -2
  4. package/agent-docs/references/performance-basics.md +2 -1
  5. package/agent-docs/references/terrain-authoring.md +25 -7
  6. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  7. package/dist/index.js +268 -237
  8. package/dist/quality.d.ts +5 -1
  9. package/dist/quality.js +75 -6
  10. package/dist/terrain-kit.js +1 -1
  11. package/dist/threenative.js +7 -5
  12. package/dist/web-engine-post-effects.js +6 -0
  13. package/dist/web-engine-runtime.js +407 -38
  14. package/package.json +6 -6
  15. package/template-assets/assets/floor-fern-0.glb +0 -0
  16. package/template-assets/assets/floor-litter-0.glb +0 -0
  17. package/template-assets/assets/floor-log-0.glb +0 -0
  18. package/template-assets/assets/floor-log-1.glb +0 -0
  19. package/template-assets/assets/floor-stump-0.glb +0 -0
  20. package/template-assets/assets/floor-twig-0.glb +0 -0
  21. package/template-assets/patches/three@0.187.0.patch +108 -21
  22. package/template-assets/quality/eslint.config.js +1 -1
  23. package/templates/action-rpg/package.json +7 -7
  24. package/templates/action-rpg/src/loot/drops.ts +3 -7
  25. package/templates/action-rpg/src/render/camera.ts +2 -2
  26. package/templates/action-rpg/src/render/clouds.ts +3 -1
  27. package/templates/action-rpg/src/render/materials.ts +3 -2
  28. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  29. package/templates/action-rpg/src/scenes/Play.ts +1 -15
  30. package/templates/adventure/AGENTS.md +3 -3
  31. package/templates/adventure/CLAUDE.md +3 -3
  32. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  33. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  34. package/templates/adventure/package.json +7 -7
  35. package/templates/adventure/playtests/grass.playtest.json +61 -0
  36. package/templates/adventure/playtests/performance.playtest.json +1 -1
  37. package/templates/adventure/playtests/survives.playtest.json +2 -2
  38. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  39. package/templates/adventure/src/entities/LockOn.ts +42 -4
  40. package/templates/adventure/src/entities/Warden.ts +12 -3
  41. package/templates/adventure/src/level/Vale.ts +241 -16
  42. package/templates/adventure/src/render/camera.ts +2 -2
  43. package/templates/adventure/src/render/foliage.ts +64 -20
  44. package/templates/adventure/src/render/grass.ts +325 -0
  45. package/templates/adventure/src/render/materials.ts +3 -2
  46. package/templates/adventure/src/render/palette.ts +3 -0
  47. package/templates/adventure/src/render/touch-controls.ts +4 -1
  48. package/templates/adventure/src/scenes/Play.ts +96 -1
  49. package/templates/collectathon/package.json +7 -7
  50. package/templates/collectathon/src/level/Course.ts +2 -7
  51. package/templates/collectathon/src/level/terrain.ts +2 -1
  52. package/templates/collectathon/src/render/camera.ts +2 -2
  53. package/templates/collectathon/src/render/ground.ts +4 -4
  54. package/templates/collectathon/src/render/hero.ts +1 -1
  55. package/templates/collectathon/src/render/materials.ts +0 -1
  56. package/templates/collectathon/src/render/sky.ts +4 -3
  57. package/templates/kart/package.json +6 -6
  58. package/templates/kart/src/entities/Kart.ts +2 -1
  59. package/templates/kart/src/render/course.ts +2 -1
  60. package/templates/kart/src/track/Course.ts +3 -1
  61. package/templates/minimal/package.json +6 -6
  62. package/templates/minimal/src/render/camera.ts +2 -2
  63. package/templates/minimal/src/render/clouds.ts +3 -1
  64. package/templates/minimal/src/render/materials.ts +3 -2
  65. package/templates/minimal/src/render/touch-controls.ts +7 -6
  66. package/templates/platformer/package.json +7 -7
  67. package/templates/platformer/playtests/collect.playtest.json +4 -1
  68. package/templates/platformer/src/level/Stage.ts +2 -6
  69. package/templates/platformer/src/scenes/Play.ts +2 -1
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/puzzle/src/entities/Warden.ts +3 -3
  72. package/templates/puzzle/src/render/camera.ts +2 -2
  73. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  74. package/templates/racing/AGENTS.md +2 -2
  75. package/templates/racing/CLAUDE.md +2 -2
  76. package/templates/racing/CREDITS.md +29 -0
  77. package/templates/racing/assets/engine-loop.wav +0 -0
  78. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  79. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  80. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  81. package/templates/racing/assets/nitro-burst.wav +0 -0
  82. package/templates/racing/assets/tyre-squeal.wav +0 -0
  83. package/templates/racing/package.json +7 -7
  84. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  85. package/templates/racing/playtests/drift.playtest.json +100 -0
  86. package/templates/racing/playtests/hud.playtest.json +117 -0
  87. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  88. package/templates/racing/playtests/nitro.playtest.json +158 -0
  89. package/templates/racing/playtests/outcome.playtest.json +4 -4
  90. package/templates/racing/playtests/performance.playtest.json +1 -1
  91. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  92. package/templates/racing/src/audio/engine.ts +138 -0
  93. package/templates/racing/src/entities/CarBody.ts +83 -10
  94. package/templates/racing/src/entities/Drift.ts +243 -0
  95. package/templates/racing/src/entities/LineDriver.ts +2 -2
  96. package/templates/racing/src/entities/Nitro.ts +72 -0
  97. package/templates/racing/src/entities/RacingCar.ts +86 -21
  98. package/templates/racing/src/entities/Rival.ts +35 -21
  99. package/templates/racing/src/game.ts +6 -0
  100. package/templates/racing/src/gauges.ts +74 -0
  101. package/templates/racing/src/render/camera.ts +29 -4
  102. package/templates/racing/src/render/clouds.ts +3 -1
  103. package/templates/racing/src/render/effects.ts +244 -0
  104. package/templates/racing/src/render/materials.ts +43 -8
  105. package/templates/racing/src/render/shapes.ts +37 -0
  106. package/templates/racing/src/render/skids.ts +84 -0
  107. package/templates/racing/src/render/touch-controls.ts +10 -10
  108. package/templates/racing/src/scenes/Race.ts +277 -25
  109. package/templates/racing/src/state.ts +35 -0
  110. package/templates/racing/src/style.css +3 -0
  111. package/templates/racing/src/track/Ranking.ts +8 -4
  112. package/templates/racing/src/track/Track.ts +132 -58
  113. package/templates/racing/src/track/TrackSector.ts +19 -1
  114. package/templates/racing/src/track/circuit.ts +21 -15
  115. package/templates/racing/src/ui/GameUi.tsx +0 -2
  116. package/templates/racing/src/ui/Hud.tsx +417 -50
  117. package/templates/racing/threenative.config.ts +15 -0
  118. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  119. package/templates/rain/package.json +6 -6
  120. package/templates/rain/src/render/noise-volume.ts +2 -1
  121. package/templates/rain/src/state.ts +3 -1
  122. package/templates/rain/src/ui/GameUi.tsx +1 -1
  123. package/templates/rain/src/ui/automation.ts +10 -8
  124. package/templates/rain/src/ui/tempest.ts +3 -4
  125. package/templates/rts/package.json +6 -6
  126. package/templates/rts/src/sim/terrain.ts +1 -0
  127. package/templates/rts/src/sim/types.ts +1 -0
  128. package/templates/runner/package.json +7 -7
  129. package/templates/runner/src/render/clouds.ts +3 -1
  130. package/templates/runner/src/render/materials.ts +3 -2
  131. package/templates/runner/src/render/touch-controls.ts +7 -6
  132. package/templates/runner/src/scenes/Run.ts +4 -9
  133. package/templates/sailing/package.json +7 -7
  134. package/templates/sailing/src/render/touch-controls.ts +7 -6
  135. package/templates/shooter/package.json +7 -7
  136. package/templates/shooter/src/render/clouds.ts +3 -1
  137. package/templates/snow/package.json +7 -7
  138. package/templates/snow/src/entities/Explorer.ts +6 -12
  139. package/templates/snow/src/render/bootPrint.ts +3 -1
  140. package/templates/snow/src/render/camera.ts +3 -2
  141. package/templates/snow/src/render/scenery.ts +3 -3
  142. package/templates/snow/src/render/touch-controls.ts +7 -6
  143. package/templates/snow/src/render/weather.ts +3 -5
  144. package/templates/snow/src/terrain.ts +2 -1
  145. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  146. package/templates/starter/package.json +7 -7
  147. package/templates/starter/src/entities/Player.ts +10 -2
  148. package/templates/starter/src/render/camera.ts +2 -2
  149. package/templates/starter/src/render/clouds.ts +3 -1
  150. package/templates/starter/src/render/materials.ts +3 -2
  151. package/templates/starter/src/render/touch-controls.ts +7 -6
  152. package/templates/starter/src/scenes/Play.ts +1 -14
  153. package/templates/tower-defense/package.json +7 -7
  154. package/templates/tower-defense/src/render/shapes.ts +1 -2
  155. package/templates/tower-defense/src/scenes/Battle.ts +3 -8
  156. package/template-assets/terrain/alpine/assets.json +0 -12
  157. package/template-assets/terrain/alpine/bake.mjs +0 -6
  158. package/template-assets/terrain/alpine/credits.json +0 -164
  159. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  160. package/template-assets/terrain/alpine/recipe.json +0 -119
  161. package/template-assets/terrain/alpine/surface.json +0 -53
  162. package/template-assets/terrain/coastal/assets.json +0 -11
  163. package/template-assets/terrain/coastal/bake.mjs +0 -6
  164. package/template-assets/terrain/coastal/credits.json +0 -117
  165. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  166. package/template-assets/terrain/coastal/recipe.json +0 -113
  167. package/template-assets/terrain/coastal/surface.json +0 -41
  168. package/template-assets/terrain/desert/assets.json +0 -12
  169. package/template-assets/terrain/desert/bake.mjs +0 -6
  170. package/template-assets/terrain/desert/credits.json +0 -164
  171. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  172. package/template-assets/terrain/desert/recipe.json +0 -108
  173. package/template-assets/terrain/desert/surface.json +0 -54
  174. package/template-assets/terrain/forest/assets.json +0 -65
  175. package/template-assets/terrain/forest/bake.mjs +0 -8
  176. package/template-assets/terrain/forest/credits.json +0 -225
  177. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  178. package/template-assets/terrain/forest/recipe.json +0 -350
  179. package/template-assets/terrain/forest/surface.json +0 -79
  180. package/template-assets/terrain/tundra/assets.json +0 -12
  181. package/template-assets/terrain/tundra/bake.mjs +0 -6
  182. package/template-assets/terrain/tundra/credits.json +0 -164
  183. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  184. package/template-assets/terrain/tundra/recipe.json +0 -277
  185. package/template-assets/terrain/tundra/surface.json +0 -54
  186. package/templates/racing/src/ui/Menu.tsx +0 -7
@@ -14,7 +14,7 @@ This repository owns the car feel, track, race rules, rescue, HUD, and look; `sr
14
14
 
15
15
  ## Commands and map
16
16
 
17
- `src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller at a constant pace. Keep `playtests/survives.playtest.json` as the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
17
+ `src/track/Track.ts` owns the circuit, its collision layers and the grid; `Lap.ts` orders `Area3D` gates and counts a lap on the car's **measured** travel direction; `TrackSector.ts` ray-probes the road and rescues from it; `Ranking.ts` ranks route progress. `src/entities/CarBody.ts` builds the one chassis both cars drive — a `VehicleBody3D` whose wheels are read off the four **named** wheel groups in `shapes.ts`. `RacingCar.ts` turns input into `engineForce` / `brake` / `steering` and nothing else; `Rival.ts` is that same car under a pure-pursuit controller, five of them on a staggered six-car grid (`GRID_SLOTS` in `circuit.ts`), each at its own constant pace from `RIVALS`, the player last. `Drift.ts` is the drift: Shift with the wheel turned at speed kicks the tail out, full lock above `DRIFT.looseSpeed` lets it go by itself, and both lower the rear grip through `VehicleBody3D.setWheelFrictionSlip`. `Nitro.ts` is the tank Space burns, filled by driving and about four times faster by drifting. `gauges.ts` is the gearbox readout — six bands, and Need for Speed: Most Wanted's capped needle fall with a 55/45 blend — and `audio/engine.ts` is the car's sound over one `AudioBus`: the bed pitched from that needle, the tyre squeal opened by the slip angle, a burst on the nitro button. Controls: WASD or arrows drive, Shift drifts and brakes, Space is nitro, P is the autopilot, R restarts. Keep `playtests/survives.playtest.json` as the smoke proof, and on a touch device `src/render/touch-controls.ts` adds the stick and buttons.
18
18
 
19
19
  **Two things about the vehicle are invisible in the API.** `suspensionStiffness` is a frequency squared, so the strut sags `gravity / (4 * stiffness)` and Godot's default of 20 bottoms it out, and a positive steering angle turns the chassis toward its own `-z` — so the input is negated once and the visual front wheels take that same signed angle. `CarBody.ts` carries every other number.
20
20
 
@@ -23,4 +23,6 @@ This repository owns the car feel, track, race rules, rescue, HUD, and look; `sr
23
23
 
24
24
  Generated conventions call `normaliseToMetres` for authored vehicle scale; the four `VehicleBody3D` wheels own floor contact, so no car gets `GroundSnap`. `input.vector("move").y` is +up and means throttle, and `+x` is right.
25
25
 
26
- `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/boost and outcome text so a brighter road or sky does not erase the readouts.
26
+ `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce). The shared look comes from core through `src/render/quality.ts`: the filmic curve and metered auto exposure are enabled by default. The bridge flushes about 100 ms; keep speed/lap in state and frame feedback in Three.js. Racing keeps its deliberate gather, SSR and sharpening overrides in `quality.ts`: reflected rough tarmac and sharpening produced unstable speckles/bands, and the game retains its 33 ms / 30 FPS budget. The curve and meter stay enabled. The HUD uses the existing opaque `bg-panel` behind race, position, speed/time/gear and revs/nitro and outcome text so a brighter road or sky does not erase the readouts; a banked drift's score pops up under it for 1.6 s, keyed on `driftsBanked` so two identical scores in a row still count as two, and counted in **game** seconds by `DRIFT.popupSeconds` — the drift owns that clock and publishes it as `driftPopup`, so a pause freezes the popup instead of ageing it while the car stands still.
27
+
28
+ **Sound is authored, not licensed.** `tools/make-racing-audio.mjs` bakes `assets/engine-loop.wav`, `tyre-squeal.wav` and `nitro-burst.wav` from maths — an engine bed pitched live from 0.62× to 2.05× has to be tonal and exactly periodic, which a recording is not — and `CREDITS.md` records why no downloaded clip fits. Both beds are declared loops with `crossFadeMs: 0` in `threenative.config.ts`, so the asset pass measures their seams and fails the build on a click. One named native gap: the host binds a source's `playbackRate` as a passive parameter, so on native the bed plays at rate 1 with the same volume, squeal and burst. `node tools/make-racing-audio.mjs --check` re-bakes and compares against the committed bytes.
@@ -134,7 +134,8 @@ change a line.
134
134
  `pnpm check` runs the strict typecheck, ESLint and a Biome format check, and `pnpm test` runs it
135
135
  first. ESLint fails on a floating Promise and on an async callback given to a synchronous slot, and
136
136
  it warns when a `new Vector3()`-style math constructor runs directly inside `Scene.update`,
137
- `Scene.render` or a `ctx.beforeRender` callback. That warning is a prompt to measure, not a
137
+ `Scene.render`, an entity's `update`/`fixedUpdate`/`tick`/`step` method or a `ctx.beforeRender`
138
+ callback. That warning is a prompt to measure, not a
138
139
  finding: reuse an instance the scene owns only if `TN_FRAME_BUDGET` shows allocation pressure.
139
140
  It does not follow helper calls, so a quiet result is not proof a frame allocates nothing. A
140
141
  suppression needs a reason: `// eslint-disable-next-line <rule> -- <why>`. Lint does not prove a
@@ -18,13 +18,30 @@ sky, props and colliders. `@threenative/terrain` ships them under `starter/<worl
18
18
 
19
19
  ```sh
20
20
  cp -r node_modules/@threenative/terrain/starter/forest src/terrain/forest
21
- node src/terrain/forest/bake.mjs --out assets/terrain/forest
21
+ npm install --save-dev tsx
22
+ node src/terrain/forest/bake.mjs
22
23
  ```
23
24
 
24
- Then `await addForest(ctx, player)` in `Scene.load` and `ctx.add(forestDaylight(ctx.camera))` in
25
- `Scene.enter`; the kit's `README.md` says what each file decides. Edit `recipe.json` for layout,
26
- `COLLIDERS` in `world.ts` for what stops the player, `surface.json` and `sky.ts` for the look, and
27
- re-run the bake. The bake writes the engine's `WorldCells` package (`bakeWorldPackage`).
25
+ Then start the game on its scene: `defineGame({ ...FOREST_GAME, plugins: [rapier()], scenes:
26
+ { forest: ForestScene }, start: "forest" })`, both from `./terrain/forest/scene.js`. The kit's
27
+ `README.md` says what each file decides: the landform in `bake.mjs`, what grows where in
28
+ `biome.data.json`, every art path in `world/terrainAssets.ts`, and the look in `render/biomes.ts`.
29
+
30
+ Asked for another environment (a desert, a taiga, a coast, a real place)? Copy the forest kit
31
+ under the new name and change its data and look, not its bake or scene:
32
+ `node_modules/@threenative/terrain/docs/authoring/new-environment.md` is the step-by-step guide.
33
+
34
+ ## Name a region, not just a biome
35
+
36
+ The terrain MCP's `terrain_generate` reads a region word and cooks that region's own world: its real
37
+ ground from a survey, and its plant community — several species, each baked at more than one seed —
38
+ on the starter's own surface, understorey, road and water. The words today are `european` and
39
+ `europe` (a Central European beech wood), `boreal`, `taiga`, `nordic` and `scandinavian`,
40
+ `mediterranean` and `tuscan`, and `pacific northwest` and `cascadia`. The reply's `decided.region`
41
+ names the row behind it, `decided.ground` the survey it stands on with the attribution its source
42
+ requires, and `unused` the words nothing answered to. A tree word in a region request moves that
43
+ species to the front of the canopy and leaves the rest; `kit`, `biome` and `ground` still win over
44
+ the row.
28
45
 
29
46
  ## Generate once, play the bake
30
47
 
@@ -127,8 +144,9 @@ patches. Editor imports, workers, watchers and the document stay out of the game
127
144
  runtime. Bake committed data before handing it to the game. The editor's GLB action and
128
145
  `prepareWorldGLTF` from `@threenative/terrain/export` prepares the resolved world for
129
146
  Node `cookTerrainWorld({ preparedWorld: prepared.json })` from `@threenative/assets` (terrain,
130
- props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. The full
131
- operation list, units and patch rules ship in `node_modules/@threenative/terrain/AGENT_GUIDE.md`.
147
+ props, final transforms, embedded PBR maps); the root `encodeGLB` stays terrain-only. Start at
148
+ `node_modules/@threenative/terrain/README.md`; the full operation list, units and patch rules ship in
149
+ `node_modules/@threenative/terrain/docs/authoring/recipes.md`.
132
150
 
133
151
  For individual props, save `placementOverrides` in the authoring document, keyed
134
152
  by evaluated placement `id`. Each entry contains `position: [x,y,z]`, a unit
@@ -29,6 +29,19 @@ and **References**. Each needs a value or explicit `none` with a reason; a blank
29
29
  section blocks approval. Required texture search/download is step 5, after plan approval;
30
30
  record planned asset needs here without claiming assets have already been selected or downloaded.
31
31
 
32
+ List every asset under **Asset slots** in `.agent/prd/PRD.md`, one row each: name, route, status
33
+ (`placeholder` or `final`), and scale with bounding box. Pick the route per slot:
34
+
35
+ - `procedural` (default): terrain, vegetation, simple or repeated shapes, and every first version.
36
+ - `pre-made`: a generic prop that looks the same in any game, such as a wooden chair. Record its licence.
37
+ - `custom`: an identity asset the player remembers this game by, such as the hero or a signature
38
+ vehicle. It is generated, then cleaned up, rigged and baked before it is `final`.
39
+
40
+ The code loads each slot from one stable path, so a swap replaces the file and leaves gameplay code
41
+ alone. Phase 1 (first playable) uses `procedural` and `pre-made` slots only. Phase 2 (polish) replaces
42
+ identity slots with `custom` ones, one at a time, after the user approves the gameplay or when the
43
+ judge's top gap is a placeholder. The visual judge does not score a `placeholder` slot on its looks.
44
+
32
45
  Write the concise plan to `.agent/prd/PRD.md`, its short player-facing summary to
33
46
  `.agent/prd/SUMMARY.md`, and implementation tasks to `.agent/tasks.json`. Tasks must be ordered,
34
47
  bounded to about 10 minutes each, carry a concrete pass check, and start with `"passes": false`.
@@ -50,3 +63,14 @@ Start implementation only after explicit approval and a clear execution instruct
50
63
  "execute", "implement", "build it", or an equivalent phrase. One message may contain both. After
51
64
  that handoff, execute the approved tasks without silently expanding the scope; repeat capability
52
65
  discovery only when the requested mechanics or target platforms change.
66
+
67
+ ## Execution goal
68
+
69
+ At the handoff, start a `/goal` (or the host's persistent-goal equivalent) so execution continues
70
+ across turns. The goal text always carries both conditions:
71
+
72
+ - **Done:** every task in `.agent/tasks.json` has `"passes": true`.
73
+ - **Stop:** the first of these ends the goal: the visual judge passes its bar, three judge rounds in a
74
+ row show no score gain, the cost cap is reached, or the user says stop or accepts the result.
75
+
76
+ Start a goal only with its Stop condition. A goal without one keeps working after the user is done.