blendops 0.0.0-stage → 1.1.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 (485) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/LICENSE +21 -0
  3. package/README.md +208 -2
  4. package/bin/blendops.mjs +4 -0
  5. package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
  6. package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
  7. package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
  8. package/bundles/claude-desktop-manual/README.md +70 -0
  9. package/bundles/claude-desktop-manual/SKILL.md +62 -0
  10. package/bundles/claude-desktop-manual/manifest.json +278 -0
  11. package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
  12. package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
  13. package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
  14. package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
  15. package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
  16. package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
  17. package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
  18. package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
  19. package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
  20. package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
  21. package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
  22. package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
  23. package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
  24. package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
  25. package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
  26. package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
  27. package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
  28. package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
  29. package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
  30. package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
  31. package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
  32. package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
  33. package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
  34. package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
  35. package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
  36. package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
  37. package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
  38. package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
  39. package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
  40. package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
  41. package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
  42. package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
  43. package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
  44. package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
  45. package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
  46. package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
  47. package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
  48. package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
  49. package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
  50. package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
  51. package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
  52. package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
  53. package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
  54. package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
  55. package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
  56. package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
  57. package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
  58. package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
  59. package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
  60. package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
  61. package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
  62. package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
  63. package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
  64. package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
  65. package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
  66. package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
  67. package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
  68. package/bundles/generic-project-local/BLENDOPS.md +71 -0
  69. package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
  70. package/bundles/generic-project-local/README.md +73 -0
  71. package/bundles/generic-project-local/ROLLBACK.md +66 -0
  72. package/bundles/generic-project-local/manifest.json +66 -0
  73. package/bundles/skill-package/README.md +54 -0
  74. package/bundles/skill-package/blendops/LICENSE.txt +21 -0
  75. package/bundles/skill-package/blendops/SKILL.md +50 -0
  76. package/bundles/skill-package/blendops/agents/README.md +61 -0
  77. package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
  78. package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
  79. package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
  80. package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
  81. package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
  82. package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
  83. package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
  84. package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
  85. package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
  86. package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
  87. package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
  88. package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
  89. package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
  90. package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
  91. package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
  92. package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
  93. package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
  94. package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
  95. package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
  96. package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
  97. package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
  98. package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
  99. package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
  100. package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
  101. package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
  102. package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
  103. package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
  104. package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
  105. package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
  106. package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
  107. package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
  108. package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
  109. package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
  110. package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
  111. package/bundles/skill-package/blendops/references/skill-map.md +32 -0
  112. package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
  113. package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
  114. package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
  115. package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
  116. package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
  117. package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
  118. package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
  119. package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
  120. package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
  121. package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
  122. package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
  123. package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
  124. package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
  125. package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
  126. package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
  127. package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
  128. package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
  129. package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
  130. package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
  131. package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
  132. package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
  133. package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
  134. package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
  135. package/docs/README.md +276 -0
  136. package/docs/examples/glb-web-handoff/README.md +174 -0
  137. package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
  138. package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
  139. package/docs/knowledge-and-recipe-catalog.md +236 -0
  140. package/docs/recipes/README.md +27 -0
  141. package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
  142. package/docs/workflows/README.md +14 -0
  143. package/docs/workflows/full-non-blender-user-workflow.md +210 -0
  144. package/docs/workflows/product-hero-workflow.md +92 -0
  145. package/laws/README.md +32 -0
  146. package/laws/evidence-before-done.md +37 -0
  147. package/laws/no-arbitrary-python-interface.md +32 -0
  148. package/laws/non-blender-user-language.md +32 -0
  149. package/laws/official-runtime-only.md +78 -0
  150. package/package.json +103 -4
  151. package/packs/README.md +11 -0
  152. package/packs/product-hero-v0/PACK.md +114 -0
  153. package/registry/catalog-index.json +21344 -0
  154. package/registry/compatibility-matrix.json +533 -0
  155. package/registry/contract-context-fields.json +391 -0
  156. package/registry/knowledge-catalog.json +4648 -0
  157. package/registry/knowledge-sources.json +438 -0
  158. package/registry/recipe-catalog.json +2565 -0
  159. package/registry/runtime-capability-policy.json +525 -0
  160. package/registry/runtime-operations.json +4468 -0
  161. package/registry/skills.json +10231 -0
  162. package/registry/workflow-graph.json +7390 -0
  163. package/schemas/adapter-compatibility-matrix.schema.json +166 -0
  164. package/schemas/contract-context-fields.schema.json +147 -0
  165. package/schemas/execution-plan.schema.json +325 -0
  166. package/schemas/glb-web-handoff-manifest.schema.json +744 -0
  167. package/schemas/knowledge-record.schema.json +460 -0
  168. package/schemas/knowledge-source-registry.schema.json +268 -0
  169. package/schemas/operation-execution-ledger.schema.json +348 -0
  170. package/schemas/recipe-record.schema.json +469 -0
  171. package/schemas/runtime-capability-policy.schema.json +184 -0
  172. package/schemas/runtime-evidence-packet.schema.json +211 -0
  173. package/schemas/runtime-operations.schema.json +535 -0
  174. package/schemas/runtime-qualification-report.schema.json +540 -0
  175. package/schemas/runtime-session.schema.json +350 -0
  176. package/schemas/scene-spec.schema.json +624 -0
  177. package/schemas/skill-contract.schema.json +402 -0
  178. package/schemas/skill-eval.schema.json +509 -0
  179. package/scripts/build-knowledge-catalog.mjs +2376 -0
  180. package/scripts/compile-scene-plan.mjs +1945 -0
  181. package/scripts/export-claude-skills.mjs +634 -0
  182. package/scripts/generate-glb-handoff-report.mjs +2376 -0
  183. package/scripts/inspect-glb.mjs +1627 -0
  184. package/scripts/install-skills.mjs +5443 -0
  185. package/scripts/runtime-orchestrator.mjs +7713 -0
  186. package/scripts/validate-capability-policy.mjs +531 -0
  187. package/scripts/validate-evidence-packet.mjs +256 -0
  188. package/skills/README.md +315 -0
  189. package/skills/_template/SKILL.md +296 -0
  190. package/skills/acceptance-criteria-builder/EVAL.md +25 -0
  191. package/skills/acceptance-criteria-builder/SKILL.md +257 -0
  192. package/skills/acceptance-criteria-builder/contract.json +205 -0
  193. package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
  194. package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
  195. package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
  196. package/skills/asset-discovery/EVAL.md +81 -0
  197. package/skills/asset-discovery/SKILL.md +252 -0
  198. package/skills/asset-discovery/contract.json +291 -0
  199. package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
  200. package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
  201. package/skills/asset-discovery/references/license-confidence-table.md +41 -0
  202. package/skills/asset-fallback-strategy/EVAL.md +34 -0
  203. package/skills/asset-fallback-strategy/SKILL.md +248 -0
  204. package/skills/asset-fallback-strategy/contract.json +190 -0
  205. package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
  206. package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
  207. package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
  208. package/skills/asset-library-plan/EVAL.md +28 -0
  209. package/skills/asset-library-plan/SKILL.md +263 -0
  210. package/skills/asset-library-plan/contract.json +177 -0
  211. package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
  212. package/skills/asset-library-plan/references/metadata-schema.md +62 -0
  213. package/skills/asset-library-plan/references/naming-rules.md +51 -0
  214. package/skills/asset-license-checker/EVAL.md +33 -0
  215. package/skills/asset-license-checker/SKILL.md +245 -0
  216. package/skills/asset-license-checker/contract.json +172 -0
  217. package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
  218. package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
  219. package/skills/asset-license-checker/references/license-source-rules.md +38 -0
  220. package/skills/asset-style-check/EVAL.md +26 -0
  221. package/skills/asset-style-check/SKILL.md +238 -0
  222. package/skills/asset-style-check/contract.json +251 -0
  223. package/skills/asset-style-check/references/drift-classification.md +40 -0
  224. package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
  225. package/skills/asset-style-check/references/style-axes.md +46 -0
  226. package/skills/blender-brainstorming/EVAL.md +79 -0
  227. package/skills/blender-brainstorming/SKILL.md +228 -0
  228. package/skills/blender-brainstorming/contract.json +115 -0
  229. package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
  230. package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
  231. package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
  232. package/skills/blender-recipe-decomposer/EVAL.md +35 -0
  233. package/skills/blender-recipe-decomposer/SKILL.md +258 -0
  234. package/skills/blender-recipe-decomposer/contract.json +152 -0
  235. package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
  236. package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
  237. package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
  238. package/skills/blender-troubleshooting/EVAL.md +78 -0
  239. package/skills/blender-troubleshooting/SKILL.md +263 -0
  240. package/skills/blender-troubleshooting/contract.json +352 -0
  241. package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
  242. package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
  243. package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
  244. package/skills/blendops-help/EVAL.md +67 -0
  245. package/skills/blendops-help/SKILL.md +312 -0
  246. package/skills/blendops-help/contract.json +229 -0
  247. package/skills/blendops-help/references/lifecycle-phases.md +91 -0
  248. package/skills/blendops-help/references/quick-start-prompts.md +65 -0
  249. package/skills/blendops-help/references/routing-decision-tree.md +57 -0
  250. package/skills/bridge-conflicts/EVAL.md +83 -0
  251. package/skills/bridge-conflicts/SKILL.md +246 -0
  252. package/skills/bridge-conflicts/contract.json +145 -0
  253. package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
  254. package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
  255. package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
  256. package/skills/camera-composition/EVAL.md +32 -0
  257. package/skills/camera-composition/SKILL.md +196 -0
  258. package/skills/camera-composition/contract.json +180 -0
  259. package/skills/camera-composition/references/camera-presets.md +30 -0
  260. package/skills/camera-composition/references/camera-rubric.md +24 -0
  261. package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
  262. package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
  263. package/skills/character-portrait/EVAL.md +42 -0
  264. package/skills/character-portrait/SKILL.md +245 -0
  265. package/skills/character-portrait/contract.json +205 -0
  266. package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
  267. package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
  268. package/skills/character-portrait/references/style-consistency-rules.md +41 -0
  269. package/skills/cli-appendix-job-outline/EVAL.md +26 -0
  270. package/skills/cli-appendix-job-outline/SKILL.md +252 -0
  271. package/skills/cli-appendix-job-outline/contract.json +147 -0
  272. package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
  273. package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
  274. package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
  275. package/skills/color-management-decision/EVAL.md +28 -0
  276. package/skills/color-management-decision/SKILL.md +254 -0
  277. package/skills/color-management-decision/contract.json +162 -0
  278. package/skills/color-management-decision/references/look-comparison.md +44 -0
  279. package/skills/color-management-decision/references/per-channel-rules.md +49 -0
  280. package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
  281. package/skills/composition-quality-checker/EVAL.md +38 -0
  282. package/skills/composition-quality-checker/SKILL.md +260 -0
  283. package/skills/composition-quality-checker/contract.json +221 -0
  284. package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
  285. package/skills/composition-quality-checker/references/composition-rules.md +58 -0
  286. package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
  287. package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
  288. package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
  289. package/skills/cycles-vs-eevee-decision/contract.json +142 -0
  290. package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
  291. package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
  292. package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
  293. package/skills/done-criteria/EVAL.md +33 -0
  294. package/skills/done-criteria/SKILL.md +225 -0
  295. package/skills/done-criteria/contract.json +199 -0
  296. package/skills/done-criteria/references/done-vs-perfect.md +56 -0
  297. package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
  298. package/skills/done-criteria/references/stop-condition-templates.md +39 -0
  299. package/skills/environment-shot/EVAL.md +44 -0
  300. package/skills/environment-shot/SKILL.md +237 -0
  301. package/skills/environment-shot/contract.json +162 -0
  302. package/skills/environment-shot/references/depth-layering-rules.md +49 -0
  303. package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
  304. package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
  305. package/skills/glb-animation-handoff/EVAL.md +39 -0
  306. package/skills/glb-animation-handoff/SKILL.md +271 -0
  307. package/skills/glb-animation-handoff/contract.json +247 -0
  308. package/skills/glb-animation-handoff/references/animation-types.md +36 -0
  309. package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
  310. package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
  311. package/skills/glb-web-handoff/EVAL.md +33 -0
  312. package/skills/glb-web-handoff/SKILL.md +212 -0
  313. package/skills/glb-web-handoff/contract.json +171 -0
  314. package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
  315. package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
  316. package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
  317. package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
  318. package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
  319. package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
  320. package/skills/intent-to-3d-brief-writer/contract.json +195 -0
  321. package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
  322. package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
  323. package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
  324. package/skills/interior-scene/EVAL.md +44 -0
  325. package/skills/interior-scene/SKILL.md +261 -0
  326. package/skills/interior-scene/contract.json +277 -0
  327. package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
  328. package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
  329. package/skills/interior-scene/references/interior-camera-rules.md +47 -0
  330. package/skills/lighting-material-plan/EVAL.md +32 -0
  331. package/skills/lighting-material-plan/SKILL.md +194 -0
  332. package/skills/lighting-material-plan/contract.json +213 -0
  333. package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
  334. package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
  335. package/skills/lighting-material-plan/references/material-portability.md +25 -0
  336. package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
  337. package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
  338. package/skills/lighting-quality-checker/EVAL.md +41 -0
  339. package/skills/lighting-quality-checker/SKILL.md +247 -0
  340. package/skills/lighting-quality-checker/contract.json +187 -0
  341. package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
  342. package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
  343. package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
  344. package/skills/material-quality-checker/EVAL.md +40 -0
  345. package/skills/material-quality-checker/SKILL.md +261 -0
  346. package/skills/material-quality-checker/contract.json +244 -0
  347. package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
  348. package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
  349. package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
  350. package/skills/mobile-glb-budget/EVAL.md +40 -0
  351. package/skills/mobile-glb-budget/SKILL.md +264 -0
  352. package/skills/mobile-glb-budget/contract.json +309 -0
  353. package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
  354. package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
  355. package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
  356. package/skills/output-format-decision/EVAL.md +27 -0
  357. package/skills/output-format-decision/SKILL.md +222 -0
  358. package/skills/output-format-decision/contract.json +179 -0
  359. package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
  360. package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
  361. package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
  362. package/skills/pack-prerequisite-checker/EVAL.md +26 -0
  363. package/skills/pack-prerequisite-checker/SKILL.md +272 -0
  364. package/skills/pack-prerequisite-checker/contract.json +214 -0
  365. package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
  366. package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
  367. package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
  368. package/skills/path-one-host-outline/EVAL.md +26 -0
  369. package/skills/path-one-host-outline/SKILL.md +251 -0
  370. package/skills/path-one-host-outline/contract.json +167 -0
  371. package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
  372. package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
  373. package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
  374. package/skills/plain-language-response/EVAL.md +33 -0
  375. package/skills/plain-language-response/SKILL.md +194 -0
  376. package/skills/plain-language-response/contract.json +242 -0
  377. package/skills/plain-language-response/references/caveat-language.md +25 -0
  378. package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
  379. package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
  380. package/skills/plain-language-response/references/status-summary-templates.md +50 -0
  381. package/skills/polycount-budget-checker/EVAL.md +40 -0
  382. package/skills/polycount-budget-checker/SKILL.md +251 -0
  383. package/skills/polycount-budget-checker/contract.json +196 -0
  384. package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
  385. package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
  386. package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
  387. package/skills/pre-handoff-verification/EVAL.md +84 -0
  388. package/skills/pre-handoff-verification/SKILL.md +252 -0
  389. package/skills/pre-handoff-verification/contract.json +295 -0
  390. package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
  391. package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
  392. package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
  393. package/skills/preview-report/EVAL.md +39 -0
  394. package/skills/preview-report/SKILL.md +254 -0
  395. package/skills/preview-report/contract.json +141 -0
  396. package/skills/preview-report/references/handoff-recipients.md +41 -0
  397. package/skills/preview-report/references/report-schema.md +60 -0
  398. package/skills/preview-report/references/truth-label-rules.md +36 -0
  399. package/skills/product-grid-scene-planner/EVAL.md +42 -0
  400. package/skills/product-grid-scene-planner/SKILL.md +246 -0
  401. package/skills/product-grid-scene-planner/contract.json +257 -0
  402. package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
  403. package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
  404. package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
  405. package/skills/product-hero-scene-planner/EVAL.md +33 -0
  406. package/skills/product-hero-scene-planner/SKILL.md +227 -0
  407. package/skills/product-hero-scene-planner/contract.json +228 -0
  408. package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
  409. package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
  410. package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
  411. package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
  412. package/skills/r3f-component-plan/EVAL.md +43 -0
  413. package/skills/r3f-component-plan/SKILL.md +290 -0
  414. package/skills/r3f-component-plan/contract.json +171 -0
  415. package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
  416. package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
  417. package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
  418. package/skills/recipe-fit-assessor/EVAL.md +28 -0
  419. package/skills/recipe-fit-assessor/SKILL.md +266 -0
  420. package/skills/recipe-fit-assessor/contract.json +220 -0
  421. package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
  422. package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
  423. package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
  424. package/skills/render-export-evidence/EVAL.md +86 -0
  425. package/skills/render-export-evidence/SKILL.md +339 -0
  426. package/skills/render-export-evidence/contract.json +206 -0
  427. package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
  428. package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
  429. package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
  430. package/skills/resolution-aspect-decision/EVAL.md +26 -0
  431. package/skills/resolution-aspect-decision/SKILL.md +246 -0
  432. package/skills/resolution-aspect-decision/contract.json +160 -0
  433. package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
  434. package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
  435. package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
  436. package/skills/runtime-attempt-report/EVAL.md +26 -0
  437. package/skills/runtime-attempt-report/SKILL.md +268 -0
  438. package/skills/runtime-attempt-report/contract.json +176 -0
  439. package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
  440. package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
  441. package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
  442. package/skills/runtime-path-picker/EVAL.md +26 -0
  443. package/skills/runtime-path-picker/SKILL.md +268 -0
  444. package/skills/runtime-path-picker/contract.json +191 -0
  445. package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
  446. package/skills/runtime-path-picker/references/decision-tree.md +29 -0
  447. package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
  448. package/skills/runtime-readiness/EVAL.md +33 -0
  449. package/skills/runtime-readiness/SKILL.md +218 -0
  450. package/skills/runtime-readiness/contract.json +190 -0
  451. package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
  452. package/skills/runtime-readiness/references/evidence-examples.md +23 -0
  453. package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
  454. package/skills/runtime-setup/EVAL.md +33 -0
  455. package/skills/runtime-setup/SKILL.md +209 -0
  456. package/skills/runtime-setup/contract.json +171 -0
  457. package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
  458. package/skills/runtime-setup/references/setup-summary-template.md +33 -0
  459. package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
  460. package/skills/scene-readiness/EVAL.md +33 -0
  461. package/skills/scene-readiness/SKILL.md +195 -0
  462. package/skills/scene-readiness/contract.json +198 -0
  463. package/skills/scene-readiness/references/blocker-catalog.md +24 -0
  464. package/skills/scene-readiness/references/not-run-handling.md +22 -0
  465. package/skills/scene-readiness/references/quality-rubric.md +23 -0
  466. package/skills/scene-readiness/references/verdict-language.md +22 -0
  467. package/skills/scope-guard/EVAL.md +33 -0
  468. package/skills/scope-guard/SKILL.md +222 -0
  469. package/skills/scope-guard/contract.json +171 -0
  470. package/skills/scope-guard/references/options-language-template.md +51 -0
  471. package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
  472. package/skills/scope-guard/references/scope-addition-classification.md +55 -0
  473. package/skills/stage-gates/EVAL.md +40 -0
  474. package/skills/stage-gates/SKILL.md +257 -0
  475. package/skills/stage-gates/contract.json +490 -0
  476. package/skills/stage-gates/references/failed-gate-handling.md +42 -0
  477. package/skills/stage-gates/references/gate-template.md +46 -0
  478. package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
  479. package/skills/workflow-stage-router/EVAL.md +25 -0
  480. package/skills/workflow-stage-router/SKILL.md +259 -0
  481. package/skills/workflow-stage-router/contract.json +150 -0
  482. package/skills/workflow-stage-router/references/milestone-model.md +20 -0
  483. package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
  484. package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
  485. package/skills.sh.json +102 -0
@@ -0,0 +1,290 @@
1
+ ---
2
+ name: r3f-component-plan
3
+ description: Plan the React Three Fiber component shape (props, refs, Suspense, useGLTF cache, animation hooks) before delivering a GLB to a web team.
4
+ ---
5
+
6
+ # r3f-component-plan
7
+
8
+ ## Purpose
9
+ Translate a planned GLB delivery into the exact public surface a React Three Fiber component should expose, so the web engineer's contract is locked before code is written.
10
+
11
+ ## Quick start
12
+ - enumerate the props the consumer needs (color, animation name, scale, onLoaded)
13
+ - decide ref shape (forwardRef, imperative methods)
14
+ - decide Suspense boundary location
15
+ - decide useGLTF caching + cleanup strategy
16
+ - decide animation hook contract (auto-play, manual control)
17
+
18
+ ## When to use
19
+ - the GLB will ship to a web app using React Three Fiber
20
+ - before the web team writes the component
21
+ - when "I'll just import the GLB" needs more rigor (multiple clips, prop overrides, lazy loading)
22
+
23
+ ## When not to use
24
+ <!-- blendops:generated:start exclusions -->
25
+ - consumers using vanilla Three.js (different API) → use `../glb-web-handoff/SKILL.md` (different API)
26
+ - consumers using Babylon / model-viewer (different stack) → use `../glb-animation-handoff/SKILL.md` (different stack)
27
+ - the GLB is rendered server-side (e.g. AR pre-render); no React component needed → use `../plain-language-response/SKILL.md` (Delegates out-of-scope requests to plain-language-response)
28
+ <!-- blendops:generated:end exclusions -->
29
+
30
+ ## Trigger phrases
31
+ <!-- blendops:generated:start triggers -->
32
+ - "how should the React component look"
33
+ - "what props should I expose"
34
+ - "ref shape for the model"
35
+ - "we use react-three-fiber"
36
+ <!-- blendops:generated:end triggers -->
37
+
38
+ ## Prerequisites / readiness
39
+ - GLB delivery contract known (clips, materials, variants)
40
+ - target React/Three.js/R3F versions known (or assume current stable)
41
+ - consumer team's preferred state-management style noted (Zustand / context / props)
42
+
43
+ ## Input schema
44
+
45
+ ### Required inputs
46
+
47
+ | Input | Why it is required |
48
+ |---|---|
49
+ | GLB delivery contract (from `glb-web-handoff`) | Defines available variants, nodes, and delivery constraints |
50
+ | Animation contract (from `glb-animation-handoff`) | Defines clip names, triggers, loop/chain rules, and blend durations |
51
+ | R3F version (`8` vs `9`) | Hook signatures change between R3F 8 and R3F 9 and require explicit caveats |
52
+ | Use case (hero / configurator / interactive view) | Determines Suspense placement, fallback behavior, and instance policy |
53
+ | Customization scope | Determines which props and ref methods are exposed |
54
+
55
+ ### Optional inputs
56
+
57
+ | Input | Use |
58
+ |---|---|
59
+ | Performance budget (from `mobile-glb-budget`) | Informs `useGLTF` shared caching vs per-instance policy within pinned ceilings |
60
+ | Existing consumer state pattern | Aligns prop and callback shapes with the consumer team's state flow |
61
+
62
+ ### Assumptions to confirm
63
+ - Animation clip contracts are already locked via `glb-animation-handoff`.
64
+ - Memory and asset ceilings are already pinned via `mobile-glb-budget`.
65
+ - Target R3F major version (8 or 9) is identified, or caveats for both are documented.
66
+
67
+ ## Output schema
68
+
69
+ ### Primary output
70
+ A locked React Three Fiber component shape spec (no generated component implementation code) containing:
71
+ - Props table (name, type, default, purpose)
72
+ - Ref interface (imperative methods exposed, or explicit "none")
73
+ - Suspense placement (inside vs outside component boundary)
74
+ - `useGLTF` caching policy (shared vs per-instance)
75
+ - Animation hook contract (aligned with `glb-animation-handoff`)
76
+ - Cleanup contract (unmount behavior)
77
+ - Error / fallback contract (what renders if GLB load fails)
78
+ - Minimal usage example (consumer call-site shape only, not component implementation code)
79
+
80
+ ### Secondary output
81
+ - R3F version compatibility caveats (specifically R3F 8 vs 9 hook signature differences)
82
+ - explicit boundary notes referencing `glb-animation-handoff`, `mobile-glb-budget`, and `glb-web-handoff`
83
+
84
+ ### Evidence / caveat output
85
+
86
+ ```txt
87
+ Runtime status: Not Run | Attempted | Produced | Verified | Failed
88
+ Artifact status: Not Produced | Produced | Verified | Failed
89
+ Evidence used: <links, paths, logs, or "none">
90
+ Limitations: <known gaps>
91
+ ```
92
+
93
+ Default is `Runtime status: Not Run` and `Artifact status: Not Produced`. Truth states are downgrade-only and never upgraded by this skill, as web runtime belongs to the consumer team.
94
+
95
+ ## Required laws
96
+ - `../../laws/evidence-before-done.md`
97
+ - `../../laws/non-blender-user-language.md`
98
+ - `../../laws/no-arbitrary-python-interface.md`
99
+ - `../../laws/official-runtime-only.md`
100
+
101
+ ## Official runtime boundary
102
+
103
+ This skill produces **planning specs only**. It does not generate component code, run a web app, or claim that the resulting component will perform correctly without measured load tests. Web-side implementation is owned by the consumer team.
104
+
105
+ If runtime is involved, refer to `../../docs/runtime-stack-strategy.md` for the 2-path + CLI appendix model. R3F lives entirely on the web side and does not interact with Blender at runtime.
106
+
107
+ ## Operating procedure
108
+
109
+ 1. Read the upstream animation contract (`glb-animation-handoff`) and performance ceilings (`mobile-glb-budget`).
110
+ 2. Enumerate consumer customization points into the props table (name, type, default, purpose).
111
+ 3. Define the ref interface for imperative controls (or mark "none required").
112
+ 4. Specify Suspense boundary placement and the error / fallback contract.
113
+ 5. Specify the `useGLTF` caching policy and the unmount cleanup contract.
114
+ 6. Specify the animation hook contract matching `glb-animation-handoff` triggers and add R3F 8/9 hook signature caveats.
115
+ 7. Provide a minimal call-site usage example (never generate the component implementation code).
116
+ 8. Record truth states (`Runtime status: Not Run`, `Artifact status: Not Produced` default; downgrade-only) and hand off to `glb-web-handoff` (and `plain-language-response` for final user wording).
117
+
118
+ ## Decision tree
119
+
120
+ ```txt
121
+ Animation clips present but uncontracted?
122
+ → Hand off to glb-animation-handoff first
123
+ Performance or memory ceilings unpinned?
124
+ → Hand off to mobile-glb-budget first
125
+ Multiple instances vs single instance?
126
+ → Document useGLTF caching policy (shared cache vs per-instance) and unmount cleanup contract
127
+ Interactive animation triggers required?
128
+ → Expose declarative trigger props and/or ref interface aligned with glb-animation-handoff
129
+ R3F version 8 vs 9 unknown?
130
+ → Document hook signature caveats for both R3F 8 and R3F 9
131
+ GLB load or network failure possible?
132
+ → Lock explicit Suspense placement + error boundary / fallback contract
133
+ ```
134
+
135
+ ## Playbooks
136
+
137
+ ### Playbook A: Hero single instance
138
+
139
+ * Props table: transform props (`scale`, `position`, `rotation`) and `onLoaded` callback.
140
+ * Ref interface: none required (or root reference only).
141
+ * Suspense placement: around component boundary with explicit placeholder fallback.
142
+ * `useGLTF` caching policy: standard single-instance cache policy with explicit unmount cleanup contract.
143
+ * Animation hook contract: auto-play idle clip per `glb-animation-handoff`.
144
+ * Error / fallback contract: fallback visual if asset fetch fails.
145
+
146
+ ### Playbook B: Interactive configurator
147
+
148
+ * Props table: `variant`, `colorOverride`, `animationName`, `onVariantChange`, `onError`.
149
+ * Ref interface: `playAction(name)`, `setVariant(name)`.
150
+ * Suspense placement: section-level boundary with loading fallback.
151
+ * `useGLTF` caching policy: shared cache policy aligned with `mobile-glb-budget` ceilings and explicit unmount cleanup.
152
+ * Animation hook contract: controlled transitions per `glb-animation-handoff` with R3F 8/9 hook signature caveats.
153
+ * Error / fallback contract: error boundary fallback prop.
154
+
155
+ ### Playbook C: Multi-instance product grid item
156
+
157
+ * Props table: `src`, `instanceId`, `activeClip`, `onSelect`.
158
+ * Ref interface: `playAction(name)`, `stopAction()`.
159
+ * Suspense placement: grid or card boundary with lightweight fallback contract.
160
+ * `useGLTF` caching policy: shared asset cache policy paired with explicit unmount cleanup contract, bounded by `mobile-glb-budget`.
161
+ * Error / fallback contract: per-card fallback state on load error.
162
+
163
+ ## Mode handling
164
+
165
+ ### Text-only mode
166
+
167
+ Produce the complete R3F component shape spec and minimal call-site usage example; do not generate component implementation code. Set `Runtime status: Not Run` and `Artifact status: Not Produced`.
168
+
169
+ ### Runtime-ready mode
170
+
171
+ Web runtime belongs to the consumer team, not BlendOps. Keep `Runtime status: Not Run` and `Artifact status: Not Produced` as the planning default; truth states are downgrade-only and never upgraded by this skill.
172
+
173
+ ### Blocked runtime mode
174
+
175
+ If the consumer R3F version or upstream contracts are incomplete, document R3F 8/9 hook signature caveats, keep truth states at `Runtime status: Not Run` and `Artifact status: Not Produced` (or downgrade to `Failed` if blocked), and name required upstream handoffs.
176
+
177
+ ## Validation checklist
178
+
179
+ * [ ] Props table complete (name, type, default, purpose)
180
+ * [ ] Ref interface specified (or explicitly marked "no imperative methods needed")
181
+ * [ ] Suspense placement explicit
182
+ * [ ] `useGLTF` caching policy explicit
183
+ * [ ] Animation hook contract explicit and aligned with `glb-animation-handoff`
184
+ * [ ] Cleanup contract explicit
185
+ * [ ] Error / fallback contract explicit
186
+ * [ ] Minimal call-site usage example included (without generating component implementation code)
187
+ * [ ] R3F 8/9 hook signature caveats documented
188
+ * [ ] No performance promises without measurement
189
+ * [ ] Truth states set to `Runtime status: Not Run` and `Artifact status: Not Produced` (downgrade-only, never upgraded)
190
+ * [ ] Next handoff skill named (`glb-web-handoff` / `plain-language-response`)
191
+
192
+ ## Pass / Warn / Fail rubric
193
+
194
+ | Verdict | Criteria |
195
+ |---|---|
196
+ | Pass | Complete component shape spec (props, ref, Suspense, `useGLTF` cache policy, animation hook contract, cleanup, error/fallback, minimal usage example), R3F 8/9 caveats noted, truth states downgrade-only, handoffs named. |
197
+ | Warn | Spec present but Suspense placement, cleanup policy, or R3F 8/9 version caveats are incomplete. |
198
+ | Fail | Generates component implementation code, claims runtime performance, upgrades truth states, invents R3F runtime internals as BlendOps facts, blurs color/material/animation/budget ownership, or omits error/fallback/ref contracts. |
199
+
200
+ ## Failure handling
201
+
202
+ * If the user asks for full React component implementation code → refuse code generation; explain that this skill outputs the locked component shape spec and minimal usage example for the web team to implement.
203
+ * If R3F version (8 vs 9) is unknown → include hook signature caveats for both versions.
204
+ * If animation clip details are missing → hand off to `glb-animation-handoff` instead of inventing clip hooks.
205
+ * If memory or instance ceilings are unknown → hand off to `mobile-glb-budget`.
206
+ * If material or color encoding questions arise → hand off to `color-management-decision` and `material-quality-checker`.
207
+
208
+ ## Troubleshooting
209
+
210
+ | Problem | Response |
211
+ |---|---|
212
+ | Material or color appearance mismatch reported | Do not diagnose texture/color encoding here; hand off to `color-management-decision` and `material-quality-checker`. |
213
+ | Animation clip names or transitions mismatch | Verify the animation hook contract against `glb-animation-handoff` and check R3F 8 vs 9 hook signature caveats. |
214
+ | Multi-instance memory or frame budget concerns | Hand off to `mobile-glb-budget` to pin ceilings, and clarify the `useGLTF` caching and unmount cleanup contracts in the spec. |
215
+ | Asset delivery, compression, or packaging mismatch | Hand off to `glb-web-handoff` for web delivery packaging details. |
216
+
217
+ ## Best practices
218
+
219
+ * Prefer declarative props and callbacks over implicit internal state.
220
+ * Lock all eight spec elements (props, ref, Suspense, `useGLTF` cache policy, animation hook contract, cleanup, error/fallback, minimal call-site usage example) before web engineering starts.
221
+ * Document R3F 8 vs 9 hook signature differences as explicit caveats rather than asserting runtime guarantees.
222
+ * Respect strict role boundaries with `glb-animation-handoff`, `mobile-glb-budget`, `glb-web-handoff`, and `plain-language-response`.
223
+
224
+ ## Good examples
225
+
226
+ * "Component spec `ProductHeroModel` (R3F 8/9 caveat: verify hook signatures for target major version): Props `{ src: string, scale?: number = 1, animationName?: 'idle' | 'open' = 'idle', variant?: string, onLoaded?: () => void }`; Ref `{ playAction(name: string): void }`; Suspense: wrapped at parent section boundary; `useGLTF` policy: shared cache; Animation hook: bound to `glb-animation-handoff` clip contract; Cleanup: stop active mixer actions and release instance resources on unmount; Error/fallback: render `fallback` prop inside error boundary; Minimal usage: `<ErrorBoundary fallback={<FallbackCard />}><Suspense fallback={<Loader />}><ProductHeroModel ref={modelRef} src=\"/model.glb\" animationName=\"idle\" /></Suspense></ErrorBoundary>`. `Runtime status: Not Run`, `Artifact status: Not Produced`. Next: `glb-web-handoff`."
227
+
228
+ ## Bad examples
229
+ - "Just useGLTF and render." — no props, no ref, no Suspense, no error path.
230
+ - "Will be smooth." — no measurement, no ceiling.
231
+
232
+ ## User-facing response template
233
+
234
+ ```txt
235
+ Component name: <PascalCase>
236
+ R3F version caveat: <R3F / 8 9 caveats hook signature>
237
+
238
+ Props table:
239
+ <name> | <type> | <default> | <purpose>
240
+
241
+ Ref interface:
242
+ <method>(args): <returnType> (or "none")
243
+
244
+ Suspense placement: <component boundary / page section / app root>
245
+ useGLTF caching policy: <shared cache / per-instance>
246
+ Animation hook contract: <aligned with glb-animation-handoff>
247
+ Cleanup contract: <unmount cleanup policy>
248
+ Error / fallback contract: <error boundary + fallback behavior>
249
+
250
+ Minimal usage example (call-site only, no component code):
251
+ <Suspense + Component ErrorBoundary call-site>
252
+
253
+ Runtime status: Not Run | Attempted | Produced | Verified | Failed
254
+ Artifact status: Not Produced | Produced | Verified | Failed
255
+ Evidence used: <links, paths, logs, or "none">
256
+ Limitations: <gaps>
257
+ Next: glb-web-handoff (then plain-language-response)
258
+ ```
259
+
260
+ ## Anti-patterns
261
+
262
+ * Generating React Three Fiber component implementation code instead of a shape spec.
263
+ * Promising runtime performance without measurement.
264
+ * Presenting unverified R3F internals (hook implementation details, scene cloning APIs, HMR behavior) as BlendOps facts.
265
+ * Blurring boundaries into color/texture validation (`color-management-decision`, `material-quality-checker`), animation contracts (`glb-animation-handoff`), budgets (`mobile-glb-budget`), or web delivery packaging (`glb-web-handoff`).
266
+ * Using `Artifact status: Not Run` or upgrading truth states instead of keeping `Runtime status: Not Run` and `Artifact status: Not Produced` downgrade-only.
267
+
268
+ ## Cross-skill handoff
269
+ <!-- blendops:generated:start handoffs -->
270
+ - [upstream_reference] Animation contract → `../glb-animation-handoff/SKILL.md`
271
+ - [upstream_reference] Performance budget ceilings → `../mobile-glb-budget/SKILL.md`
272
+ - [upstream_reference] Color and material checks (color-management-decision) → `../color-management-decision/SKILL.md`
273
+ - [upstream_reference] Color and material checks (material-quality-checker) → `../material-quality-checker/SKILL.md`
274
+ - [upstream_reference] Web delivery packaging → `../glb-web-handoff/SKILL.md`
275
+ - [progression] Final user-facing response → `../plain-language-response/SKILL.md`
276
+ <!-- blendops:generated:end handoffs -->
277
+
278
+ ## Non-goals
279
+
280
+ * Generate React or Three.js component implementation code.
281
+ * Run web apps or execute React Three Fiber at runtime.
282
+ * Claim or verify web runtime performance.
283
+ * Upgrade truth states (web runtime belongs to the consumer team, not BlendOps).
284
+ * Own animation contracts, performance budgets, color/material validation, or web delivery packaging.
285
+
286
+ ## References
287
+ - `references/component-shape-patterns.md`
288
+ - `references/suspense-placement-rules.md`
289
+ - `references/usegltf-caching-rules.md`
290
+ - `../../docs/skill-system.md`
@@ -0,0 +1,171 @@
1
+ {
2
+ "$schema": "../../schemas/skill-contract.schema.json",
3
+ "id": "r3f-component-plan",
4
+ "version": "1.0.0",
5
+ "category": "evidence-and-handoff",
6
+ "role": "r3f-component-contract-architect",
7
+ "purpose": "Plan the React Three Fiber component shape (props, refs, Suspense, useGLTF cache, animation hooks) before delivering a GLB to a web team.",
8
+ "capabilityTier": "L0",
9
+ "triggers": [
10
+ "how should the React component look",
11
+ "what props should I expose",
12
+ "ref shape for the model",
13
+ "we use react-three-fiber"
14
+ ],
15
+ "exclusions": [
16
+ {
17
+ "condition": "consumers using vanilla Three.js (different API)",
18
+ "delegateTo": "glb-web-handoff",
19
+ "reason": "different API"
20
+ },
21
+ {
22
+ "condition": "consumers using Babylon / model-viewer (different stack)",
23
+ "delegateTo": "glb-animation-handoff",
24
+ "reason": "different stack"
25
+ },
26
+ {
27
+ "condition": "the GLB is rendered server-side (e.g. AR pre-render); no React component needed",
28
+ "delegateTo": "plain-language-response",
29
+ "reason": "Delegates out-of-scope requests to plain-language-response"
30
+ }
31
+ ],
32
+ "inputs": {
33
+ "required": [
34
+ {
35
+ "name": "glb_delivery_contract",
36
+ "type": "object",
37
+ "description": "Locked GLB node hierarchy, material slots, and compression spec from glb-web-handoff"
38
+ },
39
+ {
40
+ "name": "r3f_version_and_use_case",
41
+ "type": "object",
42
+ "description": "Target @react-three/fiber major version (8 vs 9) and interactive component use case"
43
+ }
44
+ ],
45
+ "optional": [
46
+ {
47
+ "name": "animation_clip_contract",
48
+ "type": "object",
49
+ "description": "Optional clip names, triggers, and crossfade rules from glb-animation-handoff"
50
+ }
51
+ ]
52
+ },
53
+ "outputs": {
54
+ "primary": [
55
+ "r3f_component_props_and_ref_spec",
56
+ "suspense_caching_and_dispose_contract",
57
+ "consumer_call_site_usage_outline"
58
+ ],
59
+ "truthStatePolicy": {
60
+ "runtimeDefault": "Not Run",
61
+ "artifactDefault": "Not Produced",
62
+ "mutationRule": "downgrade_only"
63
+ }
64
+ },
65
+ "handoffs": [
66
+ {
67
+ "target": "glb-animation-handoff",
68
+ "type": "upstream_reference",
69
+ "label": "Animation contract",
70
+ "when": {
71
+ "all": [
72
+ {
73
+ "field": "artifact.hasAnimation",
74
+ "operator": "equals",
75
+ "value": true
76
+ },
77
+ {
78
+ "field": "stage.current",
79
+ "operator": "equals",
80
+ "value": "animation_handoff"
81
+ }
82
+ ]
83
+ }
84
+ },
85
+ {
86
+ "target": "mobile-glb-budget",
87
+ "type": "upstream_reference",
88
+ "label": "Performance budget ceilings",
89
+ "when": {
90
+ "all": [
91
+ {
92
+ "field": "artifact.type",
93
+ "operator": "equals",
94
+ "value": "glb"
95
+ },
96
+ {
97
+ "field": "budget.pinned",
98
+ "operator": "equals",
99
+ "value": false
100
+ }
101
+ ]
102
+ }
103
+ },
104
+ {
105
+ "target": "color-management-decision",
106
+ "type": "upstream_reference",
107
+ "label": "Color and material checks (color-management-decision)",
108
+ "when": {
109
+ "all": [
110
+ {
111
+ "field": "decision.colorLocked",
112
+ "operator": "equals",
113
+ "value": false
114
+ }
115
+ ]
116
+ }
117
+ },
118
+ {
119
+ "target": "material-quality-checker",
120
+ "type": "upstream_reference",
121
+ "label": "Color and material checks (material-quality-checker)",
122
+ "when": {
123
+ "all": [
124
+ {
125
+ "field": "quality.domain",
126
+ "operator": "equals",
127
+ "value": "material"
128
+ },
129
+ {
130
+ "field": "quality.verdict",
131
+ "operator": "equals",
132
+ "value": "not_run"
133
+ }
134
+ ]
135
+ }
136
+ },
137
+ {
138
+ "target": "glb-web-handoff",
139
+ "type": "upstream_reference",
140
+ "label": "Web delivery packaging",
141
+ "when": {
142
+ "all": [
143
+ {
144
+ "field": "artifact.type",
145
+ "operator": "equals",
146
+ "value": "glb"
147
+ },
148
+ {
149
+ "field": "handoff.consumerStack",
150
+ "operator": "equals",
151
+ "value": "web_glb"
152
+ }
153
+ ]
154
+ }
155
+ },
156
+ {
157
+ "target": "plain-language-response",
158
+ "type": "progression",
159
+ "label": "Final user-facing response",
160
+ "when": {
161
+ "all": [
162
+ {
163
+ "field": "stage.current",
164
+ "operator": "equals",
165
+ "value": "final_communication"
166
+ }
167
+ ]
168
+ }
169
+ }
170
+ ]
171
+ }
@@ -0,0 +1,54 @@
1
+ # Component shape patterns for R3F GLB consumers
2
+
3
+ ## Pattern A — Static hero (no interactivity)
4
+
5
+ **Props**: `src`, `scale`, `position`, `rotation`, `onLoaded?`
6
+ **Ref**: not needed
7
+ **Suspense**: at component boundary
8
+ **useGLTF**: shared cache
9
+ **Animation**: single idle clip, auto-play on mount, loop forever
10
+
11
+ ## Pattern B — Hover / click activation
12
+
13
+ **Props**: `src`, `scale`, `defaultClip`, `activeClip`, `triggerEvent` (`hover` | `click` | `scroll`)
14
+ **Ref**: `{ playAction(name, opts), stopAction(name) }`
15
+ **Suspense**: at component boundary, fallback `<mesh>` placeholder
16
+ **useGLTF**: shared cache
17
+ **Animation**: defaultClip auto-plays; activeClip plays on trigger; crossfade per `glb-animation-handoff` contract
18
+
19
+ ## Pattern C — Configurator with variants
20
+
21
+ **Props**: `src`, `variant`, `colorOverrides?`, `onVariantChange?`, `animationName?`
22
+ **Ref**: `{ playAction(name), setVariant(name), captureScreenshot() }`
23
+ **Suspense**: at page section level (whole configurator)
24
+ **useGLTF**: shared cache + `useGLTF.preload(src)` on app boot
25
+ **Animation**: optional; primarily driven by variant changes
26
+
27
+ ## Pattern D — Scroll-driven scrub
28
+
29
+ **Props**: `src`, `scrollProgress` (0..1), `clipName`
30
+ **Ref**: `{ setTime(seconds) }`
31
+ **Suspense**: at section boundary
32
+ **useGLTF**: per-instance (each scroll target has its own loaded scene)
33
+ **Animation**: single clip, manually scrubbed via `mixer.setTime`
34
+
35
+ ## Pattern E — AR + R3F dual
36
+
37
+ **Props**: `src`, `iosSrc?` (USDZ for iOS Quick Look), `arOnly?: boolean`
38
+ **Ref**: `{ enterAR() }`
39
+ **Suspense**: at component boundary
40
+ **useGLTF**: shared cache for R3F path
41
+ **Animation**: same contract, but consumer must verify AR Quick Look behavior independently
42
+
43
+ ## How to choose
44
+
45
+ | User intent | Pattern |
46
+ |---|---|
47
+ | Static product shot | A |
48
+ | "It does something on hover" | B |
49
+ | "Color and trim swap" | C |
50
+ | "Animates as you scroll" | D |
51
+ | "Also works in AR" | E |
52
+
53
+ ## Related skill
54
+ `../SKILL.md`
@@ -0,0 +1,50 @@
1
+ # Suspense placement rules
2
+
3
+ ## Three placement levels
4
+
5
+ ### 1. Component boundary (most common)
6
+ ```
7
+ <Suspense fallback={<Placeholder/>}>
8
+ <Model src="..." />
9
+ </Suspense>
10
+ ```
11
+ - Use when the GLB is a self-contained unit (hero card, single mesh).
12
+ - Fallback is local to the component.
13
+ - Pro: keeps the rest of the page interactive while the GLB loads.
14
+
15
+ ### 2. Page section
16
+ - Use when multiple GLBs share a configurator-like UI section.
17
+ - Fallback covers the whole section.
18
+ - Pro: avoids layout shift between staggered loads.
19
+ - Con: section appears empty until all sub-models load.
20
+
21
+ ### 3. App root (rare)
22
+ - Use only when GLB load is critical to the entire app's first paint.
23
+ - Almost never the right answer for a marketing site or commerce page.
24
+
25
+ ## When to use which
26
+
27
+ | Use case | Placement |
28
+ |---|---|
29
+ | Hero card | Component boundary |
30
+ | Configurator with one model | Component boundary |
31
+ | Configurator with many models | Page section |
32
+ | Critical onboarding scene | App root (very rare) |
33
+
34
+ ## Fallback rules
35
+
36
+ - Always provide a meaningful fallback. `null` is the worst option for UX (sudden content pop-in).
37
+ - For hero cards: a static image preview or a low-poly placeholder mesh.
38
+ - For configurators: a skeleton or spinner.
39
+ - For AR: a "Tap to view in AR" CTA while loading.
40
+
41
+ ## Error boundary pairing
42
+
43
+ `Suspense` handles loading; it does **not** handle errors. Always pair with an error boundary:
44
+
45
+ - Use `react-error-boundary` or a custom class component.
46
+ - Show a friendly fallback with retry.
47
+ - Log the error so the consumer team can capture failure rates.
48
+
49
+ ## Related skill
50
+ `../SKILL.md`
@@ -0,0 +1,53 @@
1
+ # useGLTF caching rules
2
+
3
+ `useGLTF` (from `@react-three/drei`) memoizes loaded GLBs by URL. Choose caching policy explicitly.
4
+
5
+ ## Shared cache (default useGLTF behavior)
6
+
7
+ ```
8
+ const { scene } = useGLTF('/hero.glb')
9
+ ```
10
+
11
+ - One fetch per URL across the entire app session.
12
+ - Fastest for repeat use of the same model.
13
+ - **Caveat**: cloning is needed if multiple instances render the same scene; raw `scene` is shared by reference. Use `SkeletonUtils.clone(scene)`.
14
+
15
+ ## Per-instance load
16
+
17
+ - Avoid `useGLTF` cache when each instance must have an independent animation state, materials, or modifications.
18
+ - Use `useLoader(GLTFLoader, src)` directly instead.
19
+ - More memory; slower repeat load; better isolation.
20
+
21
+ ## Preloading
22
+
23
+ ```
24
+ useGLTF.preload('/hero.glb')
25
+ ```
26
+
27
+ - Call at app boot or before navigation to a section that will use the model.
28
+ - Reduces fallback time on first render.
29
+ - Pair with `<link rel="preload" as="fetch" href="/hero.glb" crossorigin>` in HTML for browser-level fetching.
30
+
31
+ ## Cache busting
32
+
33
+ - The cache is keyed by URL string. Add a version query (`/hero.glb?v=2`) to force reload.
34
+ - Hot module reload preserves the cache; if a `.glb` file changes, change the URL.
35
+
36
+ ## Memory rules
37
+
38
+ - Each cached GLB stays in memory until manual eviction (`useGLTF.clear(src)`).
39
+ - For long-lived single-page apps: consider clearing on route change.
40
+ - For configurators with many variants: shared cache is the right answer; the alternative blows up memory.
41
+
42
+ ## When to choose what
43
+
44
+ | Use case | Cache policy |
45
+ |---|---|
46
+ | Single instance, single page | Shared (default) |
47
+ | Multiple instances, same model | Shared + `SkeletonUtils.clone()` |
48
+ | Independent animation state per instance | Per-instance load |
49
+ | Configurator (many variants, single instance at a time) | Shared + preload |
50
+ | Long-running SPA with many GLBs | Shared + manual cache eviction on route change |
51
+
52
+ ## Related skill
53
+ `../SKILL.md`
@@ -0,0 +1,28 @@
1
+ # EVAL — recipe-fit-assessor
2
+
3
+ ## Text-only eval prompt
4
+
5
+ User wants a cinematic interior dining room hero for a furniture brand website (still image + optional GLB spin). Assess recipe/pack fit.
6
+
7
+ ## Expected behavior
8
+
9
+ - Recognize overlap with interior architectural planner + product-adjacent hero patterns
10
+ - Recommend `product-hero-v0` only if product-centric; else interior-focused workflow entry
11
+ - Partial fit notes if GLB spin is optional
12
+ - Hand off to `intent-to-3d-brief-writer`
13
+
14
+ ## Pass / Warn / Fail criteria
15
+
16
+ - Pass: verdict + gaps + next skill + catalog citation
17
+ - Warn: vague deliverable type not clarified
18
+ - Fail: asserts a pack fits with contradictory constraints unstated
19
+
20
+ ## Sample passing response outline
21
+
22
+ - Fit verdict
23
+ - Gap bullets
24
+ - Next skill
25
+
26
+ ## Sample failing response outline
27
+
28
+ - "Use product hero" with no interior caveat