@opengamehq/skills 1.4.0 → 1.6.0

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 (383) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/README.md +12 -4
  3. package/dist/.claude-plugin/marketplace.json +26 -0
  4. package/dist/skills/manifest.json +1407 -143
  5. package/dist/skills/opengame-accessibility/CHANGELOG.md +4 -0
  6. package/dist/skills/opengame-accessibility/SKILL.md +48 -32
  7. package/dist/skills/opengame-all-in-one/CHANGELOG.md +25 -0
  8. package/dist/skills/opengame-all-in-one/SKILL.md +195 -0
  9. package/dist/skills/opengame-all-in-one/references/opengame-accessibility/README.md +102 -0
  10. package/dist/skills/opengame-all-in-one/references/opengame-api/README.md +108 -0
  11. package/dist/skills/opengame-all-in-one/references/opengame-assets/README.md +168 -0
  12. package/dist/skills/opengame-all-in-one/references/opengame-assets/references/pipeline.md +164 -0
  13. package/dist/skills/opengame-all-in-one/references/opengame-audio/README.md +238 -0
  14. package/dist/skills/opengame-all-in-one/references/opengame-audio/helpers/audio-chain.js +325 -0
  15. package/dist/skills/opengame-all-in-one/references/opengame-audio/references/mix-notes.md +125 -0
  16. package/dist/skills/opengame-all-in-one/references/opengame-audio/references/qa-without-ears.md +177 -0
  17. package/dist/skills/opengame-all-in-one/references/opengame-capture/README.md +128 -0
  18. package/dist/skills/opengame-all-in-one/references/opengame-capture/references/pipeline.md +114 -0
  19. package/dist/skills/opengame-all-in-one/references/opengame-capture/references/threejs.md +161 -0
  20. package/dist/skills/opengame-all-in-one/references/opengame-characters/README.md +180 -0
  21. package/dist/skills/opengame-all-in-one/references/opengame-characters/references/first-person-body.md +108 -0
  22. package/dist/skills/opengame-all-in-one/references/opengame-characters/references/integration.md +144 -0
  23. package/dist/skills/opengame-all-in-one/references/opengame-characters/references/player-og.md +160 -0
  24. package/dist/skills/opengame-all-in-one/references/opengame-cli/README.md +190 -0
  25. package/dist/skills/opengame-all-in-one/references/opengame-deploy/README.md +229 -0
  26. package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/json-events.md +63 -0
  27. package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/manifest.md +90 -0
  28. package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/packaging.md +120 -0
  29. package/dist/skills/opengame-all-in-one/references/opengame-depth/README.md +154 -0
  30. package/dist/skills/opengame-all-in-one/references/opengame-enemies/README.md +155 -0
  31. package/dist/skills/opengame-all-in-one/references/opengame-enemies/references/pacing-and-bots.md +108 -0
  32. package/dist/skills/opengame-all-in-one/references/opengame-enemies/references/threejs.md +193 -0
  33. package/dist/skills/opengame-all-in-one/references/opengame-front-end/README.md +185 -0
  34. package/dist/skills/opengame-all-in-one/references/opengame-front-end/references/launch.md +50 -0
  35. package/dist/skills/opengame-all-in-one/references/opengame-front-end/references/menus.md +81 -0
  36. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/README.md +181 -0
  37. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/helpers/spring.js +146 -0
  38. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/references/feel-numbers.md +142 -0
  39. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/references/killcam.md +88 -0
  40. package/dist/skills/opengame-all-in-one/references/opengame-jam/README.md +121 -0
  41. package/dist/skills/opengame-all-in-one/references/opengame-lighting/README.md +141 -0
  42. package/dist/skills/opengame-all-in-one/references/opengame-lighting/helpers/light-pool.js +185 -0
  43. package/dist/skills/opengame-all-in-one/references/opengame-loading/README.md +135 -0
  44. package/dist/skills/opengame-all-in-one/references/opengame-loading/helpers/loading-count.mjs +115 -0
  45. package/dist/skills/opengame-all-in-one/references/opengame-loading/references/threejs.md +141 -0
  46. package/dist/skills/opengame-all-in-one/references/opengame-look/README.md +181 -0
  47. package/dist/skills/opengame-all-in-one/references/opengame-look/references/matching-a-reference.md +73 -0
  48. package/dist/skills/opengame-all-in-one/references/opengame-look/references/painterly.md +69 -0
  49. package/dist/skills/opengame-all-in-one/references/opengame-look/references/post-and-lens.md +73 -0
  50. package/dist/skills/opengame-all-in-one/references/opengame-maps/README.md +74 -0
  51. package/dist/skills/opengame-all-in-one/references/opengame-maps/references/map-spec.md +77 -0
  52. package/dist/skills/opengame-all-in-one/references/opengame-mobile/README.md +86 -0
  53. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/README.md +183 -0
  54. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/briefs.md +293 -0
  55. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/day-one-questions.md +46 -0
  56. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/edge-cases.md +27 -0
  57. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/filmable.md +244 -0
  58. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/finishing.md +126 -0
  59. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/measure.md +282 -0
  60. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-capture.md +151 -0
  61. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-gates.md +84 -0
  62. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-genres.md +198 -0
  63. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-grammar.md +320 -0
  64. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-ops.md +127 -0
  65. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/og-snipers-record.md +110 -0
  66. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/owner-eye.md +214 -0
  67. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/reference-study.md +293 -0
  68. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/song.md +64 -0
  69. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/README.md +193 -0
  70. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/briefs.md +293 -0
  71. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/day-one-questions.md +46 -0
  72. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/filmable.md +244 -0
  73. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/measure.md +282 -0
  74. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-capture.md +151 -0
  75. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-gates.md +84 -0
  76. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-genres.md +198 -0
  77. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-grammar.md +320 -0
  78. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-ops.md +127 -0
  79. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/og-snipers-record.md +110 -0
  80. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/owner-eye.md +214 -0
  81. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/reference-study.md +293 -0
  82. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/song.md +64 -0
  83. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/README.md +174 -0
  84. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/briefs.md +293 -0
  85. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/day-one-questions.md +46 -0
  86. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/filmable.md +244 -0
  87. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/finishing.md +126 -0
  88. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/measure.md +282 -0
  89. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-capture.md +151 -0
  90. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-gates.md +84 -0
  91. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-genres.md +198 -0
  92. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-grammar.md +320 -0
  93. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-ops.md +127 -0
  94. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/og-snipers-record.md +110 -0
  95. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/owner-eye.md +214 -0
  96. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/reference-study.md +293 -0
  97. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/song.md +64 -0
  98. package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/README.md +139 -0
  99. package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/references/bot-lobbies.md +71 -0
  100. package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/references/netcode.md +165 -0
  101. package/dist/skills/opengame-all-in-one/references/opengame-performance/README.md +177 -0
  102. package/dist/skills/opengame-all-in-one/references/opengame-performance/helpers/landing-pacer.mjs +86 -0
  103. package/dist/skills/opengame-all-in-one/references/opengame-performance/references/measuring.md +123 -0
  104. package/dist/skills/opengame-all-in-one/references/opengame-performance/references/webgpu.md +86 -0
  105. package/dist/skills/opengame-all-in-one/references/opengame-production/README.md +192 -0
  106. package/dist/skills/opengame-all-in-one/references/opengame-production/references/team.md +107 -0
  107. package/dist/skills/opengame-all-in-one/references/opengame-production/references/templates.md +153 -0
  108. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/README.md +170 -0
  109. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/cheap-tells.md +43 -0
  110. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/judges.md +95 -0
  111. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/review-prompt.md +32 -0
  112. package/dist/skills/opengame-all-in-one/references/opengame-rhythm/README.md +134 -0
  113. package/dist/skills/opengame-all-in-one/references/opengame-rhythm/references/charting.md +109 -0
  114. package/dist/skills/opengame-all-in-one/references/opengame-rhythm/references/timing.md +92 -0
  115. package/dist/skills/opengame-all-in-one/references/opengame-router/README.md +54 -0
  116. package/dist/skills/opengame-all-in-one/references/opengame-router/references/process.md +38 -0
  117. package/dist/skills/opengame-all-in-one/references/opengame-scene-audit/README.md +136 -0
  118. package/dist/skills/opengame-all-in-one/references/opengame-scene-audit/helpers/scene-audit.js +677 -0
  119. package/dist/skills/opengame-all-in-one/references/opengame-sdk/README.md +283 -0
  120. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/engines.md +93 -0
  121. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/frame.md +107 -0
  122. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/identity.md +111 -0
  123. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/leaderboards.md +115 -0
  124. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/radio.md +71 -0
  125. package/dist/skills/opengame-all-in-one/references/opengame-stability/README.md +112 -0
  126. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/README.md +160 -0
  127. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/archetypes.md +113 -0
  128. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/briefs.md +273 -0
  129. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/core.md +129 -0
  130. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/craft.md +299 -0
  131. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/edge-cases.md +27 -0
  132. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/filmable.md +244 -0
  133. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/finishing.md +126 -0
  134. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/gates.md +184 -0
  135. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/measure.md +282 -0
  136. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/music.md +148 -0
  137. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/og-clash-record.md +133 -0
  138. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/ops.md +154 -0
  139. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/owner-eye.md +214 -0
  140. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/review.md +141 -0
  141. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/title.md +92 -0
  142. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/README.md +172 -0
  143. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/archetypes.md +113 -0
  144. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/briefs.md +273 -0
  145. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/core.md +129 -0
  146. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/craft.md +299 -0
  147. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/edge-cases.md +27 -0
  148. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/filmable.md +244 -0
  149. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/finishing.md +126 -0
  150. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/gates.md +184 -0
  151. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/measure.md +282 -0
  152. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/music.md +148 -0
  153. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/og-clash-record.md +133 -0
  154. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/ops.md +154 -0
  155. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/owner-eye.md +214 -0
  156. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/reference-set.md +92 -0
  157. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/review.md +141 -0
  158. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/title.md +92 -0
  159. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/README.md +141 -0
  160. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/archetypes.md +113 -0
  161. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/briefs.md +273 -0
  162. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/core.md +129 -0
  163. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/craft.md +299 -0
  164. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/edge-cases.md +27 -0
  165. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/filmable.md +244 -0
  166. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/finishing.md +126 -0
  167. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/gates.md +184 -0
  168. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/measure.md +282 -0
  169. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/music.md +148 -0
  170. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/og-clash-record.md +133 -0
  171. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/ops.md +154 -0
  172. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/owner-eye.md +214 -0
  173. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/review.md +141 -0
  174. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/title.md +92 -0
  175. package/dist/skills/opengame-all-in-one/references/opengame-verification/README.md +197 -0
  176. package/dist/skills/opengame-all-in-one/references/opengame-verification/helpers/browser-evidence.mjs +74 -0
  177. package/dist/skills/opengame-all-in-one/references/opengame-weapons/README.md +179 -0
  178. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/handling-numbers.md +114 -0
  179. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/reloads-and-hands.md +96 -0
  180. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/sights-and-scopes.md +98 -0
  181. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/threejs.md +240 -0
  182. package/dist/skills/opengame-all-in-one/references/opengame-world-physics/README.md +141 -0
  183. package/dist/skills/opengame-all-in-one/references/opengame-world-physics/references/measured-failures.md +79 -0
  184. package/dist/skills/opengame-api/CHANGELOG.md +12 -0
  185. package/dist/skills/opengame-api/SKILL.md +40 -13
  186. package/dist/skills/opengame-assets/CHANGELOG.md +11 -0
  187. package/dist/skills/opengame-assets/SKILL.md +79 -31
  188. package/dist/skills/opengame-assets/references/pipeline.md +67 -0
  189. package/dist/skills/opengame-audio/CHANGELOG.md +11 -0
  190. package/dist/skills/opengame-audio/SKILL.md +129 -41
  191. package/dist/skills/opengame-audio/references/mix-notes.md +44 -1
  192. package/dist/skills/opengame-audio/references/qa-without-ears.md +177 -0
  193. package/dist/skills/opengame-capture/CHANGELOG.md +10 -0
  194. package/dist/skills/opengame-capture/SKILL.md +44 -20
  195. package/dist/skills/opengame-capture/references/pipeline.md +33 -1
  196. package/dist/skills/opengame-capture/references/threejs.md +17 -1
  197. package/dist/skills/opengame-characters/CHANGELOG.md +15 -0
  198. package/dist/skills/opengame-characters/SKILL.md +94 -39
  199. package/dist/skills/opengame-characters/references/first-person-body.md +108 -0
  200. package/dist/skills/opengame-characters/references/player-og.md +1 -1
  201. package/dist/skills/opengame-cli/CHANGELOG.md +16 -0
  202. package/dist/skills/opengame-cli/SKILL.md +13 -11
  203. package/dist/skills/opengame-deploy/CHANGELOG.md +24 -0
  204. package/dist/skills/opengame-deploy/SKILL.md +47 -21
  205. package/dist/skills/opengame-deploy/references/json-events.md +6 -5
  206. package/dist/skills/opengame-deploy/references/manifest.md +3 -2
  207. package/dist/skills/opengame-deploy/references/packaging.md +29 -26
  208. package/dist/skills/opengame-depth/CHANGELOG.md +8 -0
  209. package/dist/skills/opengame-depth/SKILL.md +61 -33
  210. package/dist/skills/opengame-enemies/CHANGELOG.md +10 -0
  211. package/dist/skills/opengame-enemies/SKILL.md +96 -40
  212. package/dist/skills/opengame-enemies/references/pacing-and-bots.md +108 -0
  213. package/dist/skills/opengame-enemies/references/threejs.md +59 -0
  214. package/dist/skills/opengame-front-end/CHANGELOG.md +4 -0
  215. package/dist/skills/opengame-front-end/SKILL.md +85 -39
  216. package/dist/skills/opengame-front-end/references/menus.md +42 -8
  217. package/dist/skills/opengame-game-feel/CHANGELOG.md +11 -0
  218. package/dist/skills/opengame-game-feel/SKILL.md +95 -47
  219. package/dist/skills/opengame-game-feel/references/feel-numbers.md +59 -0
  220. package/dist/skills/opengame-game-feel/references/killcam.md +88 -0
  221. package/dist/skills/opengame-jam/CHANGELOG.md +12 -0
  222. package/dist/skills/opengame-jam/SKILL.md +59 -37
  223. package/dist/skills/opengame-lighting/CHANGELOG.md +9 -0
  224. package/dist/skills/opengame-lighting/SKILL.md +85 -34
  225. package/dist/skills/opengame-loading/CHANGELOG.md +4 -0
  226. package/dist/skills/opengame-loading/SKILL.md +78 -38
  227. package/dist/skills/opengame-loading/helpers/loading-count.mjs +115 -0
  228. package/dist/skills/opengame-loading/references/threejs.md +32 -7
  229. package/dist/skills/opengame-look/CHANGELOG.md +9 -0
  230. package/dist/skills/opengame-look/SKILL.md +122 -51
  231. package/dist/skills/opengame-look/references/matching-a-reference.md +73 -0
  232. package/dist/skills/opengame-look/references/painterly.md +69 -0
  233. package/dist/skills/opengame-look/references/post-and-lens.md +10 -3
  234. package/dist/skills/opengame-maps/CHANGELOG.md +9 -0
  235. package/dist/skills/opengame-maps/SKILL.md +78 -0
  236. package/dist/skills/opengame-maps/references/map-spec.md +77 -0
  237. package/dist/skills/opengame-mobile/CHANGELOG.md +4 -0
  238. package/dist/skills/opengame-mobile/SKILL.md +18 -18
  239. package/dist/skills/opengame-montage-make/CHANGELOG.md +5 -0
  240. package/dist/skills/opengame-montage-make/SKILL.md +187 -0
  241. package/dist/skills/opengame-montage-make/references/briefs.md +293 -0
  242. package/dist/skills/opengame-montage-make/references/day-one-questions.md +46 -0
  243. package/dist/skills/opengame-montage-make/references/edge-cases.md +27 -0
  244. package/dist/skills/opengame-montage-make/references/filmable.md +244 -0
  245. package/dist/skills/opengame-montage-make/references/finishing.md +126 -0
  246. package/dist/skills/opengame-montage-make/references/measure.md +282 -0
  247. package/dist/skills/opengame-montage-make/references/montage-capture.md +151 -0
  248. package/dist/skills/opengame-montage-make/references/montage-gates.md +84 -0
  249. package/dist/skills/opengame-montage-make/references/montage-genres.md +198 -0
  250. package/dist/skills/opengame-montage-make/references/montage-grammar.md +320 -0
  251. package/dist/skills/opengame-montage-make/references/montage-ops.md +127 -0
  252. package/dist/skills/opengame-montage-make/references/og-snipers-record.md +110 -0
  253. package/dist/skills/opengame-montage-make/references/owner-eye.md +214 -0
  254. package/dist/skills/opengame-montage-make/references/reference-study.md +293 -0
  255. package/dist/skills/opengame-montage-make/references/song.md +64 -0
  256. package/dist/skills/opengame-montage-plan/CHANGELOG.md +5 -0
  257. package/dist/skills/opengame-montage-plan/SKILL.md +197 -0
  258. package/dist/skills/opengame-montage-plan/references/briefs.md +293 -0
  259. package/dist/skills/opengame-montage-plan/references/day-one-questions.md +46 -0
  260. package/dist/skills/opengame-montage-plan/references/filmable.md +244 -0
  261. package/dist/skills/opengame-montage-plan/references/measure.md +282 -0
  262. package/dist/skills/opengame-montage-plan/references/montage-capture.md +151 -0
  263. package/dist/skills/opengame-montage-plan/references/montage-gates.md +84 -0
  264. package/dist/skills/opengame-montage-plan/references/montage-genres.md +198 -0
  265. package/dist/skills/opengame-montage-plan/references/montage-grammar.md +320 -0
  266. package/dist/skills/opengame-montage-plan/references/montage-ops.md +127 -0
  267. package/dist/skills/opengame-montage-plan/references/og-snipers-record.md +110 -0
  268. package/dist/skills/opengame-montage-plan/references/owner-eye.md +214 -0
  269. package/dist/skills/opengame-montage-plan/references/reference-study.md +293 -0
  270. package/dist/skills/opengame-montage-plan/references/song.md +64 -0
  271. package/dist/skills/opengame-montage-review-and-improve/CHANGELOG.md +5 -0
  272. package/dist/skills/opengame-montage-review-and-improve/SKILL.md +178 -0
  273. package/dist/skills/opengame-montage-review-and-improve/references/briefs.md +293 -0
  274. package/dist/skills/opengame-montage-review-and-improve/references/day-one-questions.md +46 -0
  275. package/dist/skills/opengame-montage-review-and-improve/references/filmable.md +244 -0
  276. package/dist/skills/opengame-montage-review-and-improve/references/finishing.md +126 -0
  277. package/dist/skills/opengame-montage-review-and-improve/references/measure.md +282 -0
  278. package/dist/skills/opengame-montage-review-and-improve/references/montage-capture.md +151 -0
  279. package/dist/skills/opengame-montage-review-and-improve/references/montage-gates.md +84 -0
  280. package/dist/skills/opengame-montage-review-and-improve/references/montage-genres.md +198 -0
  281. package/dist/skills/opengame-montage-review-and-improve/references/montage-grammar.md +320 -0
  282. package/dist/skills/opengame-montage-review-and-improve/references/montage-ops.md +127 -0
  283. package/dist/skills/opengame-montage-review-and-improve/references/og-snipers-record.md +110 -0
  284. package/dist/skills/opengame-montage-review-and-improve/references/owner-eye.md +214 -0
  285. package/dist/skills/opengame-montage-review-and-improve/references/reference-study.md +293 -0
  286. package/dist/skills/opengame-montage-review-and-improve/references/song.md +64 -0
  287. package/dist/skills/opengame-multiplayer/CHANGELOG.md +15 -0
  288. package/dist/skills/opengame-multiplayer/SKILL.md +143 -0
  289. package/dist/skills/opengame-multiplayer/references/bot-lobbies.md +71 -0
  290. package/dist/skills/opengame-multiplayer/references/netcode.md +165 -0
  291. package/dist/skills/opengame-performance/CHANGELOG.md +8 -0
  292. package/dist/skills/opengame-performance/SKILL.md +106 -65
  293. package/dist/skills/opengame-performance/helpers/landing-pacer.mjs +86 -0
  294. package/dist/skills/opengame-performance/references/measuring.md +51 -0
  295. package/dist/skills/opengame-performance/references/webgpu.md +86 -0
  296. package/dist/skills/opengame-production/CHANGELOG.md +13 -0
  297. package/dist/skills/opengame-production/SKILL.md +119 -54
  298. package/dist/skills/opengame-production/references/team.md +107 -0
  299. package/dist/skills/opengame-production/references/templates.md +106 -16
  300. package/dist/skills/opengame-quality-bar/CHANGELOG.md +10 -0
  301. package/dist/skills/opengame-quality-bar/SKILL.md +94 -42
  302. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +14 -7
  303. package/dist/skills/opengame-quality-bar/references/judges.md +95 -0
  304. package/dist/skills/opengame-quality-bar/references/review-prompt.md +10 -5
  305. package/dist/skills/opengame-rhythm/CHANGELOG.md +5 -0
  306. package/dist/skills/opengame-rhythm/SKILL.md +138 -0
  307. package/dist/skills/opengame-rhythm/references/charting.md +109 -0
  308. package/dist/skills/opengame-rhythm/references/timing.md +92 -0
  309. package/dist/skills/opengame-router/CHANGELOG.md +8 -0
  310. package/dist/skills/opengame-router/SKILL.md +14 -7
  311. package/dist/skills/opengame-scene-audit/CHANGELOG.md +15 -0
  312. package/dist/skills/opengame-scene-audit/SKILL.md +64 -47
  313. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +97 -19
  314. package/dist/skills/opengame-sdk/CHANGELOG.md +12 -0
  315. package/dist/skills/opengame-sdk/SKILL.md +26 -9
  316. package/dist/skills/opengame-sdk/references/engines.md +2 -2
  317. package/dist/skills/opengame-sdk/references/identity.md +10 -11
  318. package/dist/skills/opengame-stability/CHANGELOG.md +4 -0
  319. package/dist/skills/opengame-stability/SKILL.md +59 -27
  320. package/dist/skills/opengame-trailer-make/CHANGELOG.md +5 -0
  321. package/dist/skills/opengame-trailer-make/SKILL.md +164 -0
  322. package/dist/skills/opengame-trailer-make/references/archetypes.md +113 -0
  323. package/dist/skills/opengame-trailer-make/references/briefs.md +273 -0
  324. package/dist/skills/opengame-trailer-make/references/core.md +129 -0
  325. package/dist/skills/opengame-trailer-make/references/craft.md +299 -0
  326. package/dist/skills/opengame-trailer-make/references/edge-cases.md +27 -0
  327. package/dist/skills/opengame-trailer-make/references/filmable.md +244 -0
  328. package/dist/skills/opengame-trailer-make/references/finishing.md +126 -0
  329. package/dist/skills/opengame-trailer-make/references/gates.md +184 -0
  330. package/dist/skills/opengame-trailer-make/references/measure.md +282 -0
  331. package/dist/skills/opengame-trailer-make/references/music.md +148 -0
  332. package/dist/skills/opengame-trailer-make/references/og-clash-record.md +133 -0
  333. package/dist/skills/opengame-trailer-make/references/ops.md +154 -0
  334. package/dist/skills/opengame-trailer-make/references/owner-eye.md +214 -0
  335. package/dist/skills/opengame-trailer-make/references/review.md +141 -0
  336. package/dist/skills/opengame-trailer-make/references/title.md +92 -0
  337. package/dist/skills/opengame-trailer-plan/CHANGELOG.md +5 -0
  338. package/dist/skills/opengame-trailer-plan/SKILL.md +176 -0
  339. package/dist/skills/opengame-trailer-plan/references/archetypes.md +113 -0
  340. package/dist/skills/opengame-trailer-plan/references/briefs.md +273 -0
  341. package/dist/skills/opengame-trailer-plan/references/core.md +129 -0
  342. package/dist/skills/opengame-trailer-plan/references/craft.md +299 -0
  343. package/dist/skills/opengame-trailer-plan/references/edge-cases.md +27 -0
  344. package/dist/skills/opengame-trailer-plan/references/filmable.md +244 -0
  345. package/dist/skills/opengame-trailer-plan/references/finishing.md +126 -0
  346. package/dist/skills/opengame-trailer-plan/references/gates.md +184 -0
  347. package/dist/skills/opengame-trailer-plan/references/measure.md +282 -0
  348. package/dist/skills/opengame-trailer-plan/references/music.md +148 -0
  349. package/dist/skills/opengame-trailer-plan/references/og-clash-record.md +133 -0
  350. package/dist/skills/opengame-trailer-plan/references/ops.md +154 -0
  351. package/dist/skills/opengame-trailer-plan/references/owner-eye.md +214 -0
  352. package/dist/skills/opengame-trailer-plan/references/reference-set.md +92 -0
  353. package/dist/skills/opengame-trailer-plan/references/review.md +141 -0
  354. package/dist/skills/opengame-trailer-plan/references/title.md +92 -0
  355. package/dist/skills/opengame-trailer-review-and-improve/CHANGELOG.md +5 -0
  356. package/dist/skills/opengame-trailer-review-and-improve/SKILL.md +145 -0
  357. package/dist/skills/opengame-trailer-review-and-improve/references/archetypes.md +113 -0
  358. package/dist/skills/opengame-trailer-review-and-improve/references/briefs.md +273 -0
  359. package/dist/skills/opengame-trailer-review-and-improve/references/core.md +129 -0
  360. package/dist/skills/opengame-trailer-review-and-improve/references/craft.md +299 -0
  361. package/dist/skills/opengame-trailer-review-and-improve/references/edge-cases.md +27 -0
  362. package/dist/skills/opengame-trailer-review-and-improve/references/filmable.md +244 -0
  363. package/dist/skills/opengame-trailer-review-and-improve/references/finishing.md +126 -0
  364. package/dist/skills/opengame-trailer-review-and-improve/references/gates.md +184 -0
  365. package/dist/skills/opengame-trailer-review-and-improve/references/measure.md +282 -0
  366. package/dist/skills/opengame-trailer-review-and-improve/references/music.md +148 -0
  367. package/dist/skills/opengame-trailer-review-and-improve/references/og-clash-record.md +133 -0
  368. package/dist/skills/opengame-trailer-review-and-improve/references/ops.md +154 -0
  369. package/dist/skills/opengame-trailer-review-and-improve/references/owner-eye.md +214 -0
  370. package/dist/skills/opengame-trailer-review-and-improve/references/review.md +141 -0
  371. package/dist/skills/opengame-trailer-review-and-improve/references/title.md +92 -0
  372. package/dist/skills/opengame-verification/CHANGELOG.md +11 -0
  373. package/dist/skills/opengame-verification/SKILL.md +113 -48
  374. package/dist/skills/opengame-weapons/CHANGELOG.md +11 -0
  375. package/dist/skills/opengame-weapons/SKILL.md +129 -55
  376. package/dist/skills/opengame-weapons/references/handling-numbers.md +42 -0
  377. package/dist/skills/opengame-weapons/references/reloads-and-hands.md +96 -0
  378. package/dist/skills/opengame-weapons/references/sights-and-scopes.md +98 -0
  379. package/dist/skills/opengame-weapons/references/threejs.md +71 -0
  380. package/dist/skills/opengame-world-physics/CHANGELOG.md +9 -0
  381. package/dist/skills/opengame-world-physics/SKILL.md +55 -24
  382. package/dist/skills/opengame-world-physics/references/measured-failures.md +28 -1
  383. package/package.json +1 -1
@@ -0,0 +1,86 @@
1
+ # three.js on WebGPU: what costs a frame
2
+
3
+ What Last Contact (LC) measured while running three.js `WebGPURenderer` with TSL node
4
+ materials, plus what OS learned about Chrome's upload staging. Check each item against
5
+ the three.js version in your `package.json`: several are behaviours of one release, and
6
+ the version is named where it matters.
7
+
8
+ ## Draws cost main-thread time, so count them
9
+
10
+ Each draw costs about 15-40 µs of main thread per pass in LC's measurements. At 120 fps
11
+ that allows about 150 draws in view across all passes. Turning shadows or rain off bought
12
+ LC nothing and halving the pixels took a pass only from 35.6 to 32.5 ms, so cut draws
13
+ before triangles or resolution. The draw counts and budgets are in `SKILL.md`.
14
+
15
+ ## Graphs are keyed by node objects
16
+
17
+ - three.js keys a compiled pipeline by the node graph's object identity. Two materials
18
+ built from new but identical nodes compile twice: 99 of LC's 237 graphs before the menu
19
+ were repeats.
20
+ - Build graphs from the same node objects and read per-material values through
21
+ `reference("material.userData.x")` (or uniforms set per material), so materials that
22
+ differ only in values share one pipeline. LC's world went from 120 to 78 graphs.
23
+ - In LC's version, `InstancedMesh` put the mesh UUID into the graph key, so every
24
+ instanced mesh compiled its own pipeline. A plain mesh with per-instance matrices read
25
+ as attributes in `positionNode` shares one.
26
+ - A TSL graph cost LC 20-700 ms of main thread wherever it was built. Warm it before the
27
+ menu, one unbuilt material per slice.
28
+ - Read the compiled WGSL when a material misbehaves. In LC, a `.toVar()` of a built-in
29
+ first asked for inside one branch left the view direction zero in every other branch,
30
+ and every lamp-lit plain weapon drew green.
31
+
32
+ ## What `compileAsync` does not cover
33
+
34
+ - `renderer.compileAsync(scene, camera)` compiles for the pass that draws to the canvas.
35
+ Passes into render targets (shadow maps, post, a scope view, a portrait) compile on
36
+ their first real draw unless you warm them by drawing through them.
37
+ - three.js created a shadow depth texture on its first shadow draw (347 device errors in
38
+ LC's log until shadows were warmed).
39
+ - Toggling a light's `visible` or `castShadow` rebuilds every lit material in view, because
40
+ the light set is in the key. Keep a fixed light set from boot.
41
+ - Warm frames must not feed auto exposure: LC's warm frames blacked the title.
42
+ - Timestamp query pools overflowed under load in LC's runs. Treat missing GPU timings as
43
+ missing, not as zero.
44
+
45
+ ## Uniforms
46
+
47
+ - Put per-frame uniforms shared by many materials (camera, time, fog) in the render
48
+ group, so they are written once a frame. LC's GPU buffer writes went from 1,211-1,240
49
+ (248 KB) a frame to 115-138 (55 KB).
50
+ - In three.js 0.185.1 the uniform-group cache did not clear its "already added" set, so on
51
+ a camera jump the view matrix was left out of the writes and 197 draws went through the
52
+ previous frame's camera (a floating soldier, a frame of the player's own torso).
53
+ - Probe uniform writes at the GPU's door (wrap the device's write calls), not the page's
54
+ copy: a probe of the page's copy read 0 lost writes of 28,452 while the GPU lost 220.
55
+ "Keep a copy at the writer."
56
+
57
+ ## The upload ring
58
+
59
+ - Chromium puts `writeTexture` and `writeBuffer` bytes into one per-page transfer ring. A
60
+ call that needs more room than is free blocks the main thread
61
+ (`RingBuffer::Alloc -> WaitForToken` in a trace) until the GPU process drains. On a GPU
62
+ shared with a screen recorder or a second browser, the GPU process falls behind and every
63
+ large write can stall a frame for hundreds of milliseconds.
64
+ - A buffer created with `mappedAtCreation: true`, filled, unmapped and copied with
65
+ `copyBufferToTexture`, or `copyExternalImageToTexture` for an `ImageBitmap`, avoids the
66
+ ring. LC's numbers are in `SKILL.md`.
67
+ - OS found Chrome keeping a staging region sized to any write over 4 MB for the life of
68
+ the page, so split every upload into writes of 4 MB or less.
69
+ - three.js builds a geometry's GPU buffers on the frame that first draws it. A warm-up
70
+ that draws every hidden mesh at once builds them all in one frame; trickle them.
71
+
72
+ ## Pacing
73
+
74
+ - `device.queue.onSubmittedWorkDone()` resolves when the GPU has finished the work
75
+ submitted so far. Called once per frame, it tells you when each frame landed, which is
76
+ what [../helpers/landing-pacer.mjs](../helpers/landing-pacer.mjs) records. On WebGL 2,
77
+ a `fenceSync` polled with `clientWaitSync` at zero timeout does the same job, but it is
78
+ not the same instrument; compare like with like.
79
+ - Find the backend you got: `renderer.backend.isWebGPUBackend` after `await
80
+ renderer.init()`. The WebGL 2 fallback must be booted in a gate (`opengame-stability`).
81
+
82
+ ## Testing several pages on one GPU
83
+
84
+ Five headless browsers in one test job lost LC's WebGPU device ("A valid external Instance
85
+ reference no longer exists"); three at most held. Run a second GPU page on purpose when
86
+ measuring pacing, and never more than the GPU can hold when you are not.
@@ -0,0 +1,192 @@
1
+ > Carried from `opengame-production` 1.1.0. Read it when: Run a browser game build with one or many agents so the owner's notes land in few rounds. Covers the bar set in the first hour, an ask register built from raw messages and ranked by repeats, a lead that never blocks, a ranked gap table, streams that own their paths, publishing as a script, design for loss, a team sized to the model pool and job slots, and updates that show their evidence. Use when a game takes many rounds of owner notes, several agents share it, or fixes never reach builds.
2
+
3
+
4
+ # Production
5
+
6
+ A game built over many rounds of an owner's feedback loses most of its rounds to
7
+ process. OC took about 190 numbered builds in 7 days. About 75 of them never became an
8
+ accepted build, about 40 for agent or process reasons, about 22 for engine limits and
9
+ about 10 for changes of taste. The owner asked "are you there", "work faster" or "how
10
+ are we still on" this round more than 80 times. To run the loop in fewer rounds, front-load the bar,
11
+ keep one record of what the owner asked, integrate in one place, and show only what a
12
+ build the owner can open proves.
13
+
14
+ Three later games ran bigger teams and confirmed it. OS shipped about 500 builds in 13
15
+ days with 6 to 30 workers and met none of its numeric targets. LC ran up to 14 streams
16
+ through about 324 lead sittings in four and a half days. OH built a rhythm game with up
17
+ to seven agents in about 70 hours. In all three, infrastructure and process cost more
18
+ days than craft: outages took about 37 of LC's 98 hours and about 36 of OH's last 67, and
19
+ one blocking question idled 15 OS workers for 7.5 hours. What fixed each failure was a
20
+ script that enforced the rule, not the rule written down.
21
+
22
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. The
23
+ templates for the register, a brief, a handover, a delivery, a round receipt and a status
24
+ update are in [references/templates.md](references/templates.md). The small tools a team
25
+ on one machine needs (a slot queue, a sync script, a job start and wait pair, retention, a
26
+ preview service, a publish script) are described in [references/team.md](references/team.md).
27
+
28
+ ## The first hour
29
+
30
+ Settle these with the owner before the first build, and write them into one bar file
31
+ that every agent reads. Where the owner has not decided, propose a value and mark it
32
+ proposed.
33
+
34
+ 1. **Concept art per screen.** One hero frame at the player's camera for the title,
35
+ each menu, loading, each play area, the HUD, the boss, death and results. A canon
36
+ sheet per character: turnarounds fix identity, scene paintings only composition.
37
+ 2. **The reference games.** One named shipped game per area, with a saved frame per
38
+ screen at the same camera as the concept (see `opengame-quality-bar`).
39
+ 3. **Frame rate and devices.** A floor and a typical frame rate for desktop and for
40
+ phones, on named devices and browsers. Mainstream phones, not the oldest. A real
41
+ phone on the desk from the first playable (see `opengame-mobile`).
42
+ 4. **Budgets.** Bytes and seconds to the title and to play, first visit and returning;
43
+ tab memory; draw calls, lights and enemies on screen; paid generation spend. Check
44
+ the engine's fixed caps (lights, models, particles, handles) against what the
45
+ concept needs now (see `opengame-stability`).
46
+ 5. **Iconic items.** Anything players will compare with a version they know. Collect
47
+ its reference before anyone models it.
48
+ 6. **The loop.** The ask register file, the decisions file, the latest playable
49
+ address, the build clock, the status interval, the agent count and which model pools
50
+ they draw on, the heavy-job cap and the compute share with any other project on the
51
+ machine, the path ownership table. Who owns the frame, who owns the renderer, who
52
+ integrates.
53
+ 7. **Calibration and the owner's path.** Ask the owner to score one comparison sheet 0
54
+ to 10, so the critic can be held to the owner's eye from round one, and write down how
55
+ the owner plays: window size, saved settings, input device, line speed (see
56
+ `opengame-verification`).
57
+
58
+ In OC each of these was found late. The first-person lens sat at 66.5 degrees against the
59
+ concepts' 50-55. A 32-light cap met 218 fire sites. The first written budget came at R79
60
+ (360 MB to the title, a 3.5 GB tab) against the owner's ask of a tab under 500 MB. The
61
+ latest playable address arrived on day 5, and the first real iPhone crash reports came
62
+ after launch. LC's owner gave the standing orders in the first message ("dont ask me any
63
+ questions and dont stop until ur done updates every 30 mins"), and OH's lead built the
64
+ first playable alone in 65 minutes before splitting the work.
65
+
66
+ ## Rules
67
+
68
+ ### The owner's bar is written down before the first build
69
+ - **Invariant:** Concept frames per screen, the reference games, the frame-rate floor and target devices, and the budgets are in one bar file before the first build, and every spec number lives in that file and nowhere else.
70
+ - **Technique:** Work through the first-hour list with the owner. Other documents link to the bar file instead of copying its numbers. When the owner raises or changes the bar, update the file that day and add a register row quoting the change. Keep the owner's standing rules in one rules file every brief points at, beside a list of what only the owner can decide.
71
+ - **Reference configuration:** OC's kickoff asked for "60fps minimum but up to 120/240fps", and the first written budget came at R79. Boss HP in code was 60,000 against a spec of 400,000; the boss had 3 phases against 4; gate angles changed 3 times across 3 agents. The character canon said 2.2 heads tall where the turnaround measured 2.7. LC wrote the owner's goal ("the most realistic zombies game") at the head of its design document 44 seconds after the message, and into every brief after. OH kept the owner's rules in a shared rules file and an "Only you can decide" list.
72
+ - **Applies when:** Every game an owner will review over more than a few rounds.
73
+ - **Verify:** Grep the repository for each spec number: it appears in the bar file and in the code that reads it. A new agent answers "what is the phone frame-rate floor" from the file alone.
74
+
75
+ ### Done means it shows in a build the owner can open
76
+ - **Invariant:** Nothing is reported to the owner as done until it is seen or heard in a promoted build at the latest playable address, reached through the real menu, with a capture as proof.
77
+ - **Technique:** Track each change through written, merged, built, seen in the built round, and promoted. Report only the last two as done and call the rest in progress. New visible work goes in off behind a flag, a default flips only as `opengame-verification` describes under "Main is what the owner plays", and anything worse in play is taken back at once, aloud. Declare a launch build only when every top-priority register row is closed with proof from that build.
78
+ - **Reference configuration:** OC's reports of work never seen in a build are in `opengame-verification`. One register sync closed 4 of about 330 rows. "Launch build" was declared at R164, R181, R184, R186, R187, R193 and R196. LC kept a take-back flag for every default and a batch take-back address for the last half hour of defaults; retiring take-backs to save bytes removed the way back.
79
+ - **Applies when:** Every report to an owner, every round.
80
+ - **Verify:** Every "done" in a status update links a capture from the promoted build that the same update names.
81
+
82
+ ### The ask register is built from the raw messages and ranked by repeats
83
+ - **Invariant:** Every owner message maps to a row in one file that stays when any agent's memory is gone: a unique id, the owner's exact words written as a rule for every instance, every date the owner repeated it, the owner's screenshot and conditions, a status only evidence from the exact build can raise, and superseded asks marked "do not revive". Work is ranked by repeat count, and a repeat marks the last fix as failed.
84
+ - **Technique:** Have a subagent export every raw owner turn (not docs, commit messages or summaries), build the rows, and re-run after each burst; file a repeat under its existing id. A predecessor's "done" enters as "verify". Pin each note to the owner's screenshot before editing. Send each new note to its owning agent twice: as a row and request file, and as an immediate message quoting the owner. Check a relayed decision against the owner's own message before acting on it. Each confirmed ruling becomes a regression test run before publish. Close the most-repeated rows before taking new scope.
85
+ - **Reference configuration:** OC built its register on day 5 from 384 owner messages over several agent threads (179 requirements); "66 of 67 inherited acceptance rows remain open" after about 25 handoffs, one orchestrator told workers the owner had asked "several times" for a plain rifle when the owner had not, and new game modes were added while the frame-rate floor and phone boot were still open. OS's owner asked four times: "There are so many feature requests ... I don't know if, with compaction, you're just losing all those". A catalogue OS built from docs and git gave 153 rows with 12 done; re-reading 423 owner messages gave 128 items, 53 of them "done" claims nobody had checked. At one point 1 of 122 OS asks was verified live while hands had been asked 14 times, invisible walls 10 and spawns 8: "The register was an audit, not a gate." An LC note sent only as a file sat unread for an hour until the owner asked again; acknowledgement then took 1-3 minutes and a ruling 4-10.
86
+ - **Applies when:** Every project with more than one agent session or more than a day of owner notes in chat.
87
+ - **Verify:** Ten random owner messages each map to a row with a status and evidence, the five most-repeated rows cite current-build evidence, and every open row appears in some running agent's brief.
88
+
89
+ ### The lead never blocks, and standing steers come from the owner's latest words
90
+ - **Invariant:** The loop never waits on a person, an owner message reaches the lead within minutes, and no scheduled steer, goal file or brief contradicts the owner's latest explicit instruction.
91
+ - **Technique:** Ask in plain text with a recommended default and a deadline, keep working on the safe part, and make reversible calls yourself, saying what you decided. Brief every agent to decide, record and go on. Workers report on completion or a real blocker, and every message that needs no answer ends "no reply needed, continue your round". When the owner changes process, edit the goal file and every scheduled steer in the same turn, quoting the owner, drop queued heartbeats, and say aloud that the newer word overrules the older order. Give a deadline with its fallback in one sentence. Keep scheduled steers slower than the lead's own turns. Never end a turn idle, or only to say you are waiting, while the owner expects continuous work.
92
+ - **Reference configuration:** One OS blocking question held the lead 7 h 27 min while 15 workers sat idle; three decisions were asked about 25 times before "u dont need to wait for those decisions on me", and later "Stonasking me qesutions just get it done!". OH's owner, after three idle turn ends: "ok i dont see any work happening?". A 10-minute OS heartbeat repeated an old judge rule 162 times after the owner changed the judges, with 146 copies still queued at handover. Mid-round messages ended three OS workers' rounds until the "no reply needed" line, which was then sent 121 times. LC's lead briefs opened "Do not ask anyone questions and do not wait for an answer: decide, say what you decided, go on", a deadline read "On main within the hour, or take back whichever of tonight's defaults causes it and say so", and 27 LC steers corrected or withdrew an earlier one, each told to the owner the same round.
93
+ - **Applies when:** Every lead that runs scheduled steers or workers for an owner who gives live notes.
94
+ - **Verify:** Owner messages wait under 2 minutes in the queue, each live steer and brief cites the id of the newest owner instruction it carries out, and a search of live steers for superseded ids finds none.
95
+
96
+ ### A ranked gap table steers the loop, and at launch it becomes a blocker table
97
+ - **Invariant:** Each round works the highest-impact open gap game-wide, re-scored from fresh evidence that covers what the judges score, with a cap on attempts per defect. A fault reported or failed twice gets a found cause before a third patch, and when the owner says ship, the table becomes launch blockers with owners and numeric bars.
98
+ - **Technique:** Rank gaps by measured point cost and the owner's repeat count. Before a third attempt at one defect, run a diagnostic that names the mesh, shader, light or material drawing it ("Hide one thing at a time" in `opengame-verification`), and write the cause as a test that must reproduce it; after the cap, change approach or park the item and say so. Time-box every chase in jobs ("one more job, then it stands"). Once the last panel's top fixes have landed, judge only what changed. At launch, ship edits nobody has seen right default-off, and production waits for the owner's go.
99
+ - **Reference configuration:** Seven OS panels over all 17 maps, run on one-map smokes, scored 1.09-1.21 and each named the same next map, which stayed untouched for 11 h. OS's eight-row launch blocker table (for example, renderer memory growth of 300 MB or less over 45 min) was its clearest steering move. LC mended its spawn fault four times with four flags before the cause on the owner's path was found in 34 minutes; a reload took about ten mends before a fused handle was found, and ten jobs aimed at a muzzle hidden behind the ground stopped only at a two-job cap. The overnight loop on one sub-part and OH's stall rule are in `opengame-quality-bar`.
100
+ - **Applies when:** Any hill-climb, overnight loop or launch push.
101
+ - **Verify:** The round log shows the ranked table, attempt counters per defect, coverage and per-dimension deltas, and the second report of a fault carries a reproduction and a named cause before any change.
102
+
103
+ ### Batch the owner's feedback and sweep the class
104
+ - **Invariant:** Each owner message or play session becomes register rows, each fix covers every instance of its class, and the batch lands in one round instead of one item per round.
105
+ - **Technique:** Read the whole batch before starting. Name each item's class and list its members. Split the batch across workers in parallel, integrate it in one round, and reply per item with the round and a capture. When tuning a value the owner disliked, change one variable at a time.
106
+ - **Reference configuration:** OC's owner sent a 50-item play-test list on day 2. "we should NOT just be fixing things piecemeal if i send you one example you should be sweeping to make sure by yourself that doesnt exist with anything else of the same thing." The class sweep and OC's gun numbers are in `opengame-quality-bar`. Difficulty swung from "not even killing me" to death in 0.37 s, then settled at 3 hits to down once changes were made one at a time. On day 7: "im not gonna answer any more questions, ive asked for this to be fixed many times". LC's damage, softened for scripted players, went from "the zombeis take so long ot kill u?" to two hits to "it should be 3".
107
+ - **Applies when:** Every owner message with more than one item, and every report about one member of a set.
108
+ - **Verify:** The reply to a batch lists every item with its round and capture, and each class fix links a sheet of all its members.
109
+
110
+ ### Parallel streams start from a typed contract, own their paths and talk in files
111
+ - **Invariant:** Many agents can work in one game at once without breaking each other or the build: a typed contract fixes the seams, each stream owns its paths, and requests and status pass as files anyone can read cold.
112
+ - **Technique:** Commit the contract alone first (the shared registry, events and design constants), with stubs so the game boots from the first commit, and get the engine booting before anything else, since nobody can see work before it does. Change the contract by addition only. Keep a path ownership table; a stream edits only its own paths, and a cross-area need goes to that area's owner as a request file stating what, why and the exact interface, closed by a line in the reader's status, never by deleting another stream's file. Put small typed hooks at seams so two agents can build against each other at once. Each stream keeps a status file in a fixed shape the owner can read cold. Prefer building against the contract over waiting.
113
+ - **Reference configuration:** LC ran ten streams, later fourteen, in one checkout from a contract committed alone with its stubs; it ended with about 1,900 request files, and other streams' request files were deleted six times before the closing-line rule held. OH split its work into four file-owned passes plus a music studio, with typed hooks such as `loading(share)` and `struck(lane, kind, at)`, because "Broad eleven-item passes were touching many things lightly". An LC cross-stream deadlock left a hand off in 2,003 of 2,003 frames while each side's unit test stubbed the other.
114
+ - **Applies when:** Two or more agents in one codebase.
115
+ - **Verify:** The main build boots at every commit, no request older than a day is unanswered, and every commit's paths match its stream's row in the ownership table.
116
+
117
+ ### Every change lands through one controlled path, and the shared tree always boots
118
+ - **Invariant:** No agent loses, overwrites or commits another agent's unfinished work, nobody rewrites shared history, and anyone can cut a release from the shared tree at any moment because no half-written file, debug probe, missing reference or unseen default reaches it. Changes land through one controlled path: one integrator, or path-named commits through one locked sync tool.
119
+ - **Technique:** Choose the landing path on day one. With an integrator, workers deliver small patches against a named base and never edit the integration tree, and the integrator merges, sends back stale-base deliveries and has a different agent review each one. Run one worker per stream and one integration root at a time, with a lock file for the root. With path-owned commits, every commit names its paths and one locked sync script does all pulling and pushing. Either way, never stash, rebase, reset, restore, clean or add everything in a shared tree; check and act in separate calls; diff a shared file before committing it; write files through a temporary file and a rename; land a model re-export with its materials and reference check in one job; run a compile-and-boot check before an edit lands; refuse tagged debug probes in a release; never hard-link snapshots to a tree a build rewrites; keep raw captures out of the repository; and leave repairs to the repository's internals to the lead.
120
+ - **Reference configuration:** OC once had 19 workers staging patches while 66 of 67 gates stayed open for 18 h, a stale-base delivery reverted a feature and broke 2 builds, two roots once ran at once for 27 min, and with two teams sharing builds rounds went from about every 15 min to about every 40; from R138 one integrator with a review per delivery ran the loop, every review found a real bug, and film notes reached 10 of 11 shipped in about 36 h. OS's integrator lost about 2 h 45 min to five tree breaks in one evening ("there's no verified safe state to fall back to"); a build read a weapons table while it was being written and every gunsmith showed 0 rifles; 90 snapshots hard-linked to the live cook were rewritten (15.3 GB); 43.5 GB of untracked captures delayed owner messages by 40-60 min. LC took the other path: 2,317 commits in four days from up to 12 agents, zero merges and two index-lock collisions in 36,117 shell calls. When the rule slipped, an LC status file was cut from 276,119 to 9,780 bytes by a script that opened it for writing before reading it, and one lead committed over another's half-written file four times in two hours. OH ran seven agents on one tree with commits by path. "Gates beat instructions: after the second repeat, the lead wrote a check script" (OS).
121
+ - **Applies when:** Any build with more than one agent writing code; with three or more on one tree the mechanical gates stop being optional.
122
+ - **Verify:** Plant a debug tag, a missing reference and a half-written file: each gate refuses. After a teammate's commit, `git status` still shows your own files, and every merge or commit names its base or its paths.
123
+
124
+ ### Rounds are frozen snapshots on a fixed clock, each with a receipt
125
+ - **Invariant:** Each round is built from an instant copy of the integrated source taken at a set time, nobody edits that copy, and the round's receipt says what is in it.
126
+ - **Technique:** Cut on a clock agreed with the owner. Take the snapshot as a commit or a copy-on-write clone so the freeze lasts seconds. A change that misses the cut goes in the next round. Write a receipt per round with the source commit, build id, file hashes, the register rows it addresses and its test results. Promote only after a smoke test through the real menu with real input.
127
+ - **Reference configuration:** OC agreed a 25-min build clock with sub-minute snapshot freezes, after code freezes of about 20 min per build had slowed the loop. An optic fix landed 9 min after the R91 snapshot and shipped a round late; one cut came 2 h late while private builds held the slots; snapshots failed when source changed during the build at R166, R186 and R189-R190. OC built from frozen source clones from R90, checked 701 artifacts per build from R108, and smoke-tested 60-90 s of normal play before promotion. LC's preview rebuilt from main every 240 s, skipped a failing commit and kept the last good build up; OH built captures and publishes from snapshots of the committed head, so no agent's save could change a running job.
128
+ - **Applies when:** Every project with more than a handful of rounds.
129
+ - **Verify:** For any promoted round, the receipt's hashes match the served files and the snapshot time is later than every commit in it.
130
+
131
+ ### Publishing is a script: menu-path smoke, soak, exact hash, one publisher
132
+ - **Invariant:** The live build moves only through a script that refuses without a passing receipt for that exact snapshot (a smoke through the real menus, a GPU tour and a soak with real play, all before publish), live stays within a round or two of the newest passing build, and a page never mixes files from two publishes.
133
+ - **Technique:** A short headless smoke through title, loadout, level pick, lobby and match, whose receipt every agent attaches to every completion report. The publish script hashes the served build from outside, refuses an older round, a dirty tree or a shader error, and has one lock-holding publisher. Cut releases from a source snapshot and serve each publish under its own stamped path, swapping atomically and keeping old hashed files for a few hours for pages still loading. Track judge acceptance apart from publishing, so a bar no build can reach never freezes the preview. A private preview rebuilt from main on a timer is the same script at a smaller size: it builds, boots, skips a failing commit, and leaves the gate on each default ("Main is what the owner plays" in `opengame-verification`); the full smoke and soak still run before anything reaches players. Urgency never skips the gate. The serving half is in `opengame-deploy`.
134
+ - **Reference configuration:** An OS direct-load capture looked healthy (5,328 requests) while the gunsmith showed 0 rifles, unnoticed for about 4 h. After "we CANT HAVE THE GAME CRASH EVER!!! ... we need to get to the latest live build asap", an OS build went live 3 minutes later with no evidence and the owner hit a crash and a hang ("I should have held it. I'm sorry."); another passed quick checks and corrupted memory live, so the soak moved before publish, and a later one crashed after about a minute of fighting. OS's smoke took about 90 s. Judge-gating froze OS's preview on one build for 8 h 40 min while candidates moved 28 rounds on. 79 newer-build files once reached an old OS page; stamped paths then pinned 3,568 of 3,568. An atomic swap ended LC's 404s, which had drawn an old model all session.
135
+ - **Applies when:** Any live preview or production page an owner or player uses.
136
+ - **Verify:** Publish with no receipt, an older round or a dirty tree: the script exits non-zero each time. A publish during a page load leaves 0 mixed files, and the live id equals the newest gated id.
137
+
138
+ ### One latest playable address
139
+ - **Invariant:** One permanent address always opens the newest promoted build, every round also keeps its own address, and the sender opens a link before sending it.
140
+ - **Technique:** Serve builds from a supervised server on a fixed host and port, started outside any agent session so agent restarts leave it running. Promotion moves the latest address to the new round; older rounds stay at their own paths for comparison and rollback. Label an unpromoted build as untested when you share it. Show the build id on screen in the game.
141
+ - **Reference configuration:** OC's owner asked which localhost was the latest about 12 times. A latest address existed only from day 5, and it was then down for 3 days. "Localhost not up" was reported 6 times, agent restarts killed preview servers up to 9 times a day, 20-40 min each, and the stable build was not promoted from R96 to R137. The owner: "every time a new round is ready show me the build link where i can play it". An older OS worktree republished an old build over the shared pointer and live ran 20-30 builds behind ("not lag like 20-30 behind"). LC's preview ran as a supervised service in its own clone, wrote the commit and build time it served, and logged the visiting browser's family so the lead knew when the owner was playing.
142
+ - **Applies when:** Every project where the owner plays builds.
143
+ - **Verify:** Restart every agent session: the latest address still serves the newest promoted build, and its on-screen build id matches the last receipt.
144
+
145
+ ### Design for loss: agents are disposable, and the status head is the memory
146
+ - **Invariant:** Any agent, session, provider or machine can stop at any moment without losing work or decisions, because the work is committed or saved as a patch, each agent's current state sits at the top of its status file where its successor reads first, and a stopped agent is resumed in its own thread from those files rather than replaced blind.
147
+ - **Technique:** Commit or save a patch after every job, and keep scripts and state out of temporary directories. Size each agent's job budget to its context (a few jobs, then a handover), since pictures fill context fast. Write the handover at the top of the status file before the context fills: the owner's open notes in the owner's words and where each stands, what is on main and seen (with paths), what is behind which flag and unseen, rulings in their exact words, the next commands, and the agent's own mistakes. While an agent runs, the lead appends its successor's orders to a rulings file, so the next one starts bound by them. After an outage, resume each agent in its own thread with a fixed take-stock (the time, its status head, its own diff, its job marks, recent commits) and decide for each uncommitted change whether it was booted. Run builds and long jobs detached from agent sessions, with deadlines inside the agent host's limits. Amend a brief through the channel that briefed that agent.
148
+ - **Reference configuration:** OC had about 25 whole-team usage-limit deaths in about 7 days, each stopping 8-25 agents in the middle of edits with 27-211 dirty files; about 36 of the 160 hours before launch made no progress, and each new wave spent 20-60 min re-auditing. About 37 of LC's 98 hours went to outages (an 8-hour gateway failure, an 8.4-hour machine crash, a 20.7-hour provider stop), and about 36 of OH's last 67. LC ran about 324 lead sittings, a median of 76 minutes; 19% ended because memory filled (81% of reads were pictures), and leads replaced at 520k-900k tokens were productive within the hour. After LC's first outage new leads were started and had to find the old ones' uncommitted work; after the long stop eight were resumed in place and checked their files byte for byte against their last booted job. OH's reboot recovery took about 5 minutes; 257 OS builds came from an uncommitted tree for 73 h until one 683-file checkpoint. OC commits every 20-30 min.
149
+ - **Applies when:** Every build that uses agents on metered or shared accounts, or runs longer than a day.
150
+ - **Verify:** Stop every agent at a random moment: resumed or fresh agents continue from the files alone, lose no more than the commit interval, and their first status head says what they found.
151
+
152
+ ### Size the team to the model pool and the job slots, and keep the lead out of the workers' failure domain
153
+ - **Invariant:** The number of agents running at once stays under what the model pool sustains, no single rate limit or outage stops the lead and every worker together, a dead provider reaches the owner within one update interval, and every status line comes from a check made just before it.
154
+ - **Technique:** Cap concurrent agents below the pool's limit, counting nested reviewers and judges, and keep the lead on a different account or pool from its workers. Start agents in staggered waves, since each begins with a heavy read, and tell each to plan and make few, large tool calls. Match workers to the job slots: more workers than slots means queues, not speed. Confirm each launched task actually started, and keep a registry of running agents and the asks each owns; on handover, adopt or cancel the old workers by id. Keep the lead doing hands-on work as well as steering. During an outage, say so in the next update rather than going quiet.
155
+ - **Reference configuration:** Ten LC agents at once hit the account-wide rate limit three times in a day, and eleven sessions tripped it where two waves of 6 and 4 did not; LC's cap became eight, with other streams parked and their next orders written. OS's account-wide walls cost about 3 h, 3.5 h and 2 h 45 min; with 20 workers and the lead on one account, a 5-hour limit hit 14 minutes after the lead named the risk, and about 40 heartbeats fired into a dead provider with no alert. OS's later rule was at most 3 workers per account or pool, none on the lead's. On OC, cutting from 20 agents to 17 did not prevent the next usage-limit death, and the root later capped itself at 4. One OS build agent failed 0.26 s after launch while its asks were reported "in flight" overnight, and the lead twice reported "all 14 running" from stale checks. OS's owner: "shouldnt u eb doing owkr here on this machine too?".
156
+ - **Applies when:** Any multi-agent run longer than one rate-limit window.
157
+ - **Verify:** In a drill, cut one pool partway through a round: the lead still posts, requeues and resumes workers from the repository, and each status line names the time of the check behind it.
158
+
159
+ ### Heavy jobs are slotted, capped, watched to the end, and timed in a quiet window
160
+ - **Invariant:** Builds, browsers, captures and renders each hold one slot under a time cap, free it on every exit path, never queue for a slot while holding one, and are watched by their launcher until the result is read; no agent ends a turn with its own job pending, and every performance number comes from a run with no competing heavy work.
161
+ - **Technique:** Run heavy jobs through one first-come slot queue whose count someone set from the hardware, with an urgent lane only for a capture that gates a fix to something the owner saw broken, and a quiet lane that drains every slot for timings. One job per agent at a time, with everything for one look in that job. Detach the process, never the watching: wait in your own turn with bounded waits on the job's end mark or receipt. Put timeouts inside the slot, never around the queue, which would count the wait. Reap tagged orphans only after checking their identity. Move builds that need no GPU to CPU machines. Agree the compute share between teams in writing, log competing CPU and GPU load with every perf run and reject runs over the limit, and interleave A/B pairs inside a quiet window, leaving screenshot frames out of timing.
162
+ - **Reference configuration:** OC's 16-core machine ran at load averages of 150-361 with 19-36 jobs waiting for 3-6 slots (the cap "was just a default"), free disk fell to 400 MB and killed a run, jobs hit their own timeouts while waiting and the owner's own play lagged, and the game and film teams agreed a 45/45/10 split after more than 40 h of contention, with quiet windows blocking builds for 20-60 min each. LC's four slots for eight leads gave a 41-minute queue and "one look an hour"; one job per lead of at most ten minutes cut the median wait from 279 s to about 100-140 s, though blocking waits were still 20% of lead wall time; LC's quiet lane required a load under 6 and the GPU under 15%. The OS lead sent the stay-in-your-turn correction 41 times in 5 days ("the chain's result reaches no one"); a nested call held a slot idle 83 min, priority queues left normal jobs waiting about 8.5 h, and a timeout wrapped around the queue killed at least five jobs. Moving OS's dev builds to CPU machines took releases from 422-1,057 s to 134 s. The perf-run rejection rule is in `opengame-verification`.
163
+ - **Applies when:** Every project running several agents, browsers or renders on one machine.
164
+ - **Verify:** Each perf result prints the load and competing CPU and GPU during its run, the queue log shows every wait, and at every turn end the slot status lists no job owned by a finished agent.
165
+
166
+ ### A shared machine is kept by rules: disk lines, retention with receipts, the neighbour's share
167
+ - **Invariant:** The project never stops for disk it could have planned for, never deletes evidence someone cites or masters it cannot regenerate, never takes more than its agreed share of a machine another project uses, and never spends money or slots by accident.
168
+ - **Technique:** Two disk lines from day one: below the lower one, stop; between them, run only jobs that write little. A retention tool that runs as a dry run by default, keeps anything marked to keep, anything cited and anything recent, keeps the newest few builds per lane, archives captures with checksums before removing them, never follows links or touches source masters, and writes a receipt; never delete by age alone. Measure unique bytes before blaming a writer. Agree a split of slots with any other project in numbers, confirm it by reading that project's own state, and never touch its files. Treat every tool's help flag as untested, and give new tools a dry run first.
169
+ - **Reference configuration:** LC's single 12 GB stop line halted streams "again and again" until it became two (stop under 6 GB; between 6 and 12 GB only jobs writing under 1 GB); its cache grew 0.5 TiB a day until a retention tool removed 446 GiB of builds; audio deleted its own masters for space and every check passed while nobody measured the loss. OS's retention scripts deleted cited evidence three times in a day, and running one tool's help flag pruned 14 GB for real; on LC a generation tool's help flag bought 77 voice readings. OH freed 147.9 GiB with a dry-run-first tool, and took two of six slots after the owner's "let the last contact game know it can use 4 and u can use 2", confirmed by reading the other project's count file.
170
+ - **Applies when:** Any project on a machine, disk or GPU it shares with other agents or other projects.
171
+ - **Verify:** `df` is logged before each heavy job and stays above the lower line across a day, every deletion has a receipt, and the slot count matches the agreed split.
172
+
173
+ ### Reference first for iconic items
174
+ - **Invariant:** An item players will compare with something they know (a real weapon or vehicle, a known creature, an item from the creator's own earlier game or spec) is built from measured reference before its first build and judged side by side with it under one camera. Where another studio designed the thing, the reference sets the reads players expect (size, silhouette class, how it handles), and the shipped design, name and files are original.
175
+ - **Technique:** Collect a reference model or several orthographic views first. Extract proportions and a materials list, match the reference camera, compare silhouettes from the side, top and back, and write a beat-by-beat spec for how it animates. Keep reference files and trademarked names out of the shipped build, and ship original names.
176
+ - **Reference configuration:** OC's wonder weapon went through about 14 builds made from a texture sheet and a 64 px icon, and the owner rejected all of them in one message. The agent: "I built the earlier version without enough reference work." It passed only after the owner sent 6 images and the proportions were measured; the numbers are in `opengame-weapons`.
177
+ - **Applies when:** Every item the owner or players will compare with a version they already know.
178
+ - **Verify:** A split-view sheet shows reference and build under one camera with the silhouette overlap.
179
+
180
+ ### Owner updates show their evidence, one link and one thing to try
181
+ - **Invariant:** The owner hears from the project at an agreed interval, and each update opens with the playable link and the build it serves, says whether the sender booted it, separates what was seen from what was only reported, counted or tested, names one thing to try, and leads with corrections and outages.
182
+ - **Technique:** Agree the interval in the first hour. Open with the link, the commit served and its build time, and whether you booted it plain. Then a one-line verdict; what you saw yourself, apart from what you are taking from someone else's report; what is still not right; what is running and what is waiting; take-back flags worth trying; spend. Name one thing to try (a level, a song, a weapon, a setting) and what to look or listen for. Lead with any correction you owe and with any outage. Say every time what nobody could hear, play by hand or watch at speed. Explain jargon, put images in the message, and offer a default with a one-line way out. Skip an update with no news, and never go quiet past the interval.
183
+ - **Reference configuration:** OC's owner asked for updates every 10-15 min, about 60% of one transcript was heartbeat boilerplate ("why do you keep sayin gno change?"), and one agent spent about 11 h reporting an old blocked status. LC sent 174 updates on a 30-minute schedule, each opening with the link, the commit served and whether the director had booted it, and told the owner about each of about 44 of its own errors the same round ("A correction I owe you: part of the freeze fix made things worse, and I told you it held."; "You have had no update for about eight hours; that was a failure, not a quiet stretch."). "Nobody has played by hand or heard anything" appeared 53 times. OH's owner: "when u send links pls have expert for the links to try" and "whats a good song i should test now?"; OH kept "Confirmed in captures" apart from "Published, not yet checked by me". OS's owner still asked where things stood at least 8 times.
184
+ - **Applies when:** Every project where the owner waits on rounds.
185
+ - **Verify:** The update log has no gap longer than the agreed interval, and each update has the link, the build it serves, one thing to try and each claim graded by its evidence.
186
+
187
+ ### The dev log is a typed contract
188
+ - **Invariant:** A dev log or progress page the owner reads never shows stale, empty or reworded data without saying so: each field has a type, the owner's words stay exact, and every link resolves.
189
+ - **Technique:** Give the log a schema and check it on every change: scores numeric or marked not yet scored, owner requests matched against the raw messages, a media field for every sample, states from a fixed list. Check every link and the preview address on each build. Close a note's state only with evidence from the build. Run the judge panel when the team's own marks say every dimension is close, and say on the page when it has not run.
190
+ - **Reference configuration:** LC's board read "This round has no scores yet" for 5 h because the scores were null; 18 voice samples had no slot in the schema and were never linked; the preview link and budget were stale at a machine move; owner requests were reworded; one task was marked done for a rejected effect. At the end 86 of 105 LC quality notes still read "in progress", and the chat updates carried more than the page.
191
+ - **Applies when:** Any long build with a progress page, dev log or tracker the owner reads.
192
+ - **Verify:** A schema check of the log's data runs on every change and fails on a null score, a reworded quote or a dead link.
@@ -0,0 +1,107 @@
1
+ # Tools for a team of agents on one machine
2
+
3
+ Each of these is small (tens of lines) and each replaced a written rule that agents kept
4
+ breaking. They are described here so you can write them for your own machine; none of
5
+ them needs anything beyond a shell, `flock`, git and Node. Numbers are from OS, LC and OH,
6
+ which ran 6 to 30 agents on one shared GPU machine.
7
+
8
+ ## The slot queue
9
+
10
+ A first-come queue in front of the machine's heavy-job slots, for every browser, build,
11
+ render, bake and capture.
12
+
13
+ - Each waiter writes a queue file named by priority, arrival time and its PID. Dead
14
+ waiters are swept by checking their PID is alive. The first live waiter takes one of N
15
+ slot files with a non-blocking `flock` and then `exec`s the job, so the kernel frees the
16
+ slot when the job exits, whatever way it exits.
17
+ - N comes from a count file someone set from the hardware. Never raise it to get a job
18
+ through faster; if another project shares the machine, the split is agreed and both
19
+ sides read the same file.
20
+ - An urgent lane that jumps the queue, granted only for a capture that gates a fix to
21
+ something the owner saw broken. A quiet lane that waits until every slot is free and
22
+ the machine's load and GPU use are low, then takes them all for a timing run (LC: load
23
+ under 6 and GPU under 15%, for at most 10 minutes).
24
+ - It prints "slot N after Ns" when it grants, the only wait telemetry LC had. LC's median
25
+ wait fell from 279 s to about 100-140 s once each lead ran one job at a time.
26
+ - Put any timeout inside the slot, around the job. A timeout around the queue counts the
27
+ wait, and on OS it killed at least five jobs that had not started.
28
+ - A priority lane needs ageing: on OS, unflagged work starved for 8.5 h under release
29
+ priority until normal jobs were promoted after 60 minutes.
30
+
31
+ ## Starting a job and waiting for it
32
+
33
+ A pair of commands every agent types instead of a loop written by hand (LC's leads typed the
34
+ loop about 2,400 times).
35
+
36
+ - `start NAME -- command`: runs the command through the slot queue, detached from the
37
+ agent's shell, records its PID, the commit of the tree it built from, and writes a
38
+ began mark, then an ended mark with the exit status beside its log.
39
+ - `wait NAME --max SECONDS`: returns within the agent host's tool limit with the job's
40
+ state, so the agent polls it from inside its own turn. A notification may never wake a
41
+ turn that has ended, so a job left behind an ended turn reaches nobody.
42
+ - Build from an archive of the commit plus your own files at the moment the slot is
43
+ granted, never from the shared working tree, or an edit made while queued changes what
44
+ runs.
45
+
46
+ ## The sync script
47
+
48
+ The only way any agent pulls or pushes, when streams commit their own paths.
49
+
50
+ - Takes a lock with a timeout, fetches, merges without an editor (aborting and retrying
51
+ on a conflict, a few times), and pushes.
52
+ - Unstages any path left staged for more than a few seconds, since one stray staged path
53
+ blocked every merge on LC.
54
+ - Commits elsewhere always name their paths (`git add -- paths` and `git commit -- paths`
55
+ in one line). With that, LC made 2,317 commits in four days with zero merge conflicts.
56
+
57
+ ## Retention
58
+
59
+ - A dry run by default; the real run needs a flag.
60
+ - Keeps anything marked to keep, anything a document or report cites, anything younger
61
+ than a few hours, and the newest few builds per lane.
62
+ - Archives captures older than a day with a checksum verified on the archive copy before
63
+ removing the original. Never follows links and never touches source material or
64
+ masters. Writes a receipt listing every path removed.
65
+ - LC's removed 446 GiB of builds; OH's freed 147.9 GiB. OS's earlier scripts, which
66
+ deleted by age, removed cited evidence three times in one day.
67
+
68
+ ## The preview service
69
+
70
+ - A supervised user service in its own clone, outside every agent session, so restarts
71
+ and outages leave it running.
72
+ - Every few minutes: fetch, move to the main branch's tip, build. A failing commit is
73
+ skipped and the last good build stays up. It writes the commit and build time it is
74
+ serving where the game can show them.
75
+ - Swaps the served folder atomically and keeps the previous build's hashed files for a
76
+ few hours, so a page still loading never mixes two builds.
77
+ - Logs only the visiting browser's family, so the lead knows when the owner is playing.
78
+
79
+ ## The publish script
80
+
81
+ For a project that publishes release trains rather than main's tip.
82
+
83
+ - Refuses without a passing receipt for that exact snapshot: a short smoke through the
84
+ real menus (OS's took about 90 s), a GPU tour, and a soak with minutes of real play.
85
+ - Refuses an older round, a dirty tree or a shader compile error. A step passes only when
86
+ its exit status and the receipt it wrote this run agree; any disagreement is incomplete
87
+ (one OS tour exited 1 while its receipt said ok).
88
+ - Holds a lock, so there is one publisher. Serves each publish under its own stamped
89
+ path. After publishing, hashes what the server returns from outside and compares it
90
+ with the receipt.
91
+
92
+ ## What each failure taught, in one table
93
+
94
+ | Failure | Game | What fixed it |
95
+ | --- | --- | --- |
96
+ | Every worker and the lead on one account; a rate limit stopped all of them | OS, LC | At most a few workers per pool, the lead on another pool, staggered starts |
97
+ | A scheduled steer kept an old instruction for 10 hours | OS | Steers regenerated from the owner's latest words in the same turn |
98
+ | Half-finished edits broke the shared build about 15 times in two days | OS | Temporary file and rename, a compile-and-boot check before landing, debug tags refused |
99
+ | Snapshots hard-linked to the live build were rewritten | OS | Snapshots copied, never linked; tainted snapshots refused |
100
+ | Raw captures in the repository slowed every agent's start | OS | Captures kept outside the repository |
101
+ | 257 builds from an uncommitted tree | OS | Hourly checkpoints by the lead |
102
+ | A build published with no evidence put a crash in the owner's hands | OS | Soak before publish, receipts decide |
103
+ | One blocking question held the team for 7.5 hours | OS | Ask in plain text with a default and keep working |
104
+ | A status file wiped by a script that opened it for writing first | LC | Read, then write to a temporary file, then rename |
105
+ | One lead committed over another's half-written file | LC | Commits name their paths; check and act in separate calls |
106
+ | New leads started after an outage could not find the old ones' work | LC | Resume each agent in its own thread with a take-stock |
107
+ | A tool's help flag ran a real prune, and another's bought voice readings | OS, LC | Dry runs first; help flags treated as untested |
@@ -0,0 +1,153 @@
1
+ # Templates
2
+
3
+ Plain files on disk, so a fresh agent can pick them up after a usage limit, an outage or
4
+ a restart. Keep them in the repository beside the bar file.
5
+
6
+ ## Ask register row
7
+
8
+ One row per ask. The quote is the owner's own words, copied from the raw message, never
9
+ from a summary. Rebuild the rows from an export of every owner message after each burst.
10
+
11
+ ```
12
+ | id | first | repeats | quote | rule for every instance | priority | status | round | evidence |
13
+ | A-41 | 18 Oct | 19 Oct, 21 Oct | "never load any low poly versions of guns ANYWHERE" | no gun on any path shows a stand-in | P0 | partial | R92 | sheets/r92-guns.png (box spin still shows a stand-in) |
14
+ | A-58 | 20 Oct | | "make the hud bigger" (superseded by A-77, "hud way too big now") | do not revive | | closed | | |
15
+ ```
16
+
17
+ Status is one of open, in progress, verify, fixed, partial, not fixed, cannot check yet.
18
+ "Fixed" needs a capture from a promoted round, taken by someone who did not build the fix.
19
+ A predecessor's "done" enters as "verify". A repeat goes in the repeats column of the
20
+ existing row and marks the last fix as failed. A relayed request gets a row only after
21
+ someone finds the owner's own message for it.
22
+
23
+ ## Decisions file
24
+
25
+ Dated, in the owner's words, pasted into every judge, generator and worker brief.
26
+
27
+ ```
28
+ Owner decisions. Must not reverse even if critics ask.
29
+ 2026-10-21 "the default rifle spawns with the rainbow camo for new players"
30
+ 2026-10-22 "one wide door on the warehouse, not two"
31
+ Spec facts. Do not penalise: no HUD in cinematics; the night is black where nothing is lit.
32
+ ```
33
+
34
+ ## A brief for a lead or worker
35
+
36
+ What a new agent reads first. Short, ordered, and complete enough that it never needs to
37
+ ask.
38
+
39
+ ```
40
+ You are the <stream> lead of <game>: <genre, renderer, players>. You own <paths>; you never
41
+ edit <neighbours' paths>. You answer by request files and the head of your status file.
42
+ Do not ask anyone questions and do not wait for an answer: decide, say what you decided,
43
+ go on.
44
+
45
+ THE OWNER'S WORDS (in force): "<goal, exact>"; <date>: "<note, exact>" (<measured state>).
46
+ The owner plays <exact path: build, saved settings, window, line, input>. Main is what the
47
+ owner plays; anything found worse in play is taken back at once.
48
+
49
+ WHERE IT STANDS: on main, each with its take-back flag: <x>. Off: <y, why>. Not done: <z>.
50
+ Budgets: <bytes before the menu; frame time; memory>.
51
+
52
+ READ FIRST, in order: the team rules, the ownership table, the rulings written for you
53
+ (they bind), the head of your status file, your request files newer than a day.
54
+
55
+ RULES IN SHORT: open every capture yourself at full size; heavy jobs only through the slot
56
+ queue, one at a time, under the cap, waited for inside your turn; never signal a process
57
+ you did not start and check; no credential printed; nothing bought without a dry run;
58
+ commits name your paths; a default only with its take-back flag and a plain boot of the
59
+ tree that was booted; never time through a tool that changes the game; commit after every
60
+ job; after a few jobs, write the handover.
61
+
62
+ YOUR WORK, IN ORDER: JOB ONE: <the owner's oldest open note, with its pass test>. JOB TWO:
63
+ ... LAST JOB: the handover.
64
+
65
+ NOT YOURS: <neighbour: what, paths>. Ask by request file.
66
+
67
+ REPORT, after every job: what nobody could see or hear, first; what is wrong; what you
68
+ saw and what you did not; every flag with its take-back; budgets before and after; every
69
+ command, so the next agent can repeat it; what needs the lead's word.
70
+ ```
71
+
72
+ ## Handover
73
+
74
+ At the top of the stream's status file, written before the context fills.
75
+
76
+ ```
77
+ HANDOVER <time UTC> <agent>
78
+ Owner's open notes: A-41 (partial: box spin still shows a stand-in), A-57 (not started)
79
+ On main and seen: hip sizes per class (captures/r164-hip.png)
80
+ Behind a flag, unseen: ?optic2 (new scope housing), take-back ?optic0
81
+ Rulings in force: "hands never change size" (owner, 21 Oct)
82
+ Next commands: <exact commands, in order>
83
+ Pipeline notes: the bake needs the slot for about 6 min; run it alone
84
+ My mistakes this sitting: reported A-41 fixed from a test before opening the capture
85
+ ```
86
+
87
+ ## Take-stock after an outage
88
+
89
+ Each stopped agent runs this in its own thread before doing anything else.
90
+
91
+ ```
92
+ 1. The time now, in UTC.
93
+ 2. The head of my status file and my unanswered request files.
94
+ 3. My uncommitted changes, my own paths only: for each, was it booted? If yes, commit it
95
+ as the tree that was booted; if not, keep it behind its flag off or take it out.
96
+ 4. My slot jobs from before the stop: read their end marks and logs. Never signal a
97
+ process I cannot verify as my own job's.
98
+ 5. Commits since the stop, from everyone.
99
+ ```
100
+
101
+ ## Delivery note
102
+
103
+ What a worker hands the integrator with each patch, when there is one integrator.
104
+
105
+ ```
106
+ stream: weapons-optics
107
+ base: 3f2a9c1 (or the sha256 of each file the patch was written against)
108
+ files: src/weapons/optics.ts, assets/guns/manifest.json
109
+ register rows: A-41, A-57
110
+ pair condition: scope housing visible AND no new shimmer in the scoped pan
111
+ proof: captures from the worker's private copy, with the build id on screen
112
+ known gaps: third-person view not captured
113
+ ```
114
+
115
+ The integrator sends back any delivery whose base is older than the current
116
+ integration tree for the same files.
117
+
118
+ ## Round receipt
119
+
120
+ Written when the round is cut, before anyone tests it.
121
+
122
+ ```
123
+ round: R164
124
+ snapshot: 2026-10-20T23:40Z, source commit 8e01d77
125
+ build id shown in game: R164-8e01d77
126
+ files: manifest of path and sha256 for every shipped file
127
+ addresses rows: A-12 (fixed), A-41 (partial), A-57 (not fixed)
128
+ smoke test: menu to match to results through real input, result and log path
129
+ soak: every level through the real picker, a full match, result and log path
130
+ promoted: yes, latest playable now points here
131
+ ```
132
+
133
+ After a deploy, hash what the server returns and compare it with this manifest.
134
+
135
+ ## Status update
136
+
137
+ Sent at the agreed interval. Images go in the message itself.
138
+
139
+ ```
140
+ Play: <latest playable address>, serving R164 (8e01d77), built 23:58Z. I booted it plain: in play, no errors.
141
+ Try: the warehouse level with the rifle, and listen for the reload on the second magazine.
142
+ Verdict: hip sizes are right; the phone still reloads at the end of the load bar.
143
+ Seen myself: hip size per gun class matches the reference frame (sheet attached)
144
+ Taken from the weapons lead's film, not opened by me: the new bolt animation
145
+ Still not right: real iPhone reloads at the end of the load bar; cause narrowed to texture memory
146
+ Running: phone memory fix, reload sweep. Waiting: nothing on you.
147
+ Flags worth trying, each gives the old behaviour back: ?optic2 (take back with ?optic0)
148
+ Nobody has heard the new reload sounds or played on a pad.
149
+ Decided without asking: kept Ultra as the default and added a one-step fallback to High
150
+ ```
151
+
152
+ Leave out hashes beyond the one served, internal stream names and heartbeats with no
153
+ news. Lead with a correction you owe or an outage before anything else.