@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.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 (142) hide show
  1. package/README.md +79 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
package/README.md CHANGED
@@ -7,8 +7,7 @@ It owns:
7
7
 
8
8
  - dev server lifecycle commands
9
9
  - adapter sync and status
10
- - reference status and recovery warmup commands (fresh installed scaffolds warm
11
- the shared cache automatically)
10
+ - reference status and queries against the installed `@iwsdk/reference`
12
11
  - runtime-resolved MCP stdio access
13
12
  - direct runtime control commands
14
13
 
@@ -36,6 +35,84 @@ supports repository-scoped permissions, sync preapproves only IWSDK-managed MCP
36
35
  namespaces and skill loading. Copilot tool approval remains an explicit VS Code
37
36
  action because it has no supported repository config for that choice.
38
37
 
38
+ `adapter sync` also installs the project's agent guidance (below).
39
+
40
+ ## Agent guidance
41
+
42
+ `@iwsdk/core` ships the coding-agent guidance for its release: a managed block in
43
+ `AGENTS.md`, the IWSDK skills, path-scoped rules, and the project code-review
44
+ subagent. `iwsdk agents sync` installs it from the installed `@iwsdk/core`, so the
45
+ guidance always matches the IWSDK version in `node_modules`. Run it after
46
+ upgrading IWSDK, or in a project that added IWSDK by hand.
47
+
48
+ - Files IWSDK wrote and nobody edited are replaced; each carries a stamp with the
49
+ release and a content hash. Retired IWSDK skills and rules are removed.
50
+ - Files a developer edited, and same-named files IWSDK did not write, are reported
51
+ and left alone. `--force` replaces them.
52
+ - An existing `AGENTS.md` keeps its own text; IWSDK guidance lives between
53
+ `<!-- BEGIN iwsdk-agent-guidance -->` and `<!-- END iwsdk-agent-guidance -->`.
54
+ `CLAUDE.md` gets an `@AGENTS.md` import.
55
+ - Guidance written by releases before stamps is recognized by hash and upgraded.
56
+ - Each file is replaced as a whole, through a temporary copy, so an interrupted
57
+ sync never leaves a half-updated skill. Files written by a newer IWSDK release
58
+ are never rolled back, and an `AGENTS.md` whose markers are broken is left for
59
+ you to fix.
60
+ - A project that lists `@iwsdk/core` must have it installed; otherwise the
61
+ command asks you to install dependencies first. A project that does not list
62
+ it yet gets the copy bundled with the CLI.
63
+ - Without `--tools`, a project keeps the coding tools it already has guidance
64
+ for (a project with none gets all five). `--tools claude,codex` picks them.
65
+ - `iwsdk agents check` writes nothing and exits 1 when sync would change files,
66
+ for CI. Edited files are reported but are not drift.
67
+ - Run it as `npx @iwsdk/cli@latest agents sync` in apps whose installed
68
+ `@iwsdk/cli` predates the command.
69
+
70
+ The command prints a short notice on stderr naming the entry skill and every
71
+ skill path, so a coding agent can read the guidance in the same session that
72
+ installed it.
73
+
74
+ `iwsdk dev up` and `dev restart` keep the guidance current after an upgrade:
75
+ when the installed `@iwsdk/core` ships different guidance than the project has,
76
+ they refresh the files nobody edited and print what changed. They only report,
77
+ without writing, when `CI` is set, when `node_modules` holds a different
78
+ `@iwsdk/core` than the lockfile resolves (for example after switching branches
79
+ without installing), or when `iwsdk.config.json` sets
80
+ `"dev": { "agentGuidance": "warn" }`. `"off"` (or `IWSDK_AGENT_GUIDANCE=off`)
81
+ disables the check. They never install guidance into a project that has none.
82
+
83
+ For dependency bots, run the sync after the bump with dependencies installed,
84
+ for example with Renovate (self-hosted Renovate must also allow the commands):
85
+
86
+ ```json
87
+ {
88
+ "postUpgradeTasks": {
89
+ "commands": ["npm ci", "npx @iwsdk/cli@latest agents sync"],
90
+ "fileFilters": ["**/*"]
91
+ }
92
+ }
93
+ ```
94
+
95
+ Use your package manager's install in place of `npm ci`
96
+ (`pnpm install --frozen-lockfile`, `yarn install --immutable`).
97
+
98
+ ## Upgrading IWSDK
99
+
100
+ ```bash
101
+ npx @iwsdk/cli@latest upgrade [--to <version>] [--dry-run] [--no-install]
102
+ ```
103
+
104
+ `upgrade` sets every `@iwsdk/*` dependency in the release group to the CLI's
105
+ release (or `--to`), keeping `^` and `~` ranges and leaving `workspace:`,
106
+ `file:` and `catalog:` specs alone. It installs with the package manager found
107
+ from the nearest lockfile, aligns the `three` alias (in `package.json` or
108
+ `pnpm-workspace.yaml`) with the one `@iwsdk/core` uses, refreshes the agent
109
+ guidance the project already has, and checks `iwsdk.config.json` against the
110
+ new release. It writes to `.iwsdk/migrations/` (gitignored) the migration guide
111
+ for each release boundary crossed and `release-notes.md` with every change in
112
+ between, and names them in its output. Use `@latest`: migration guides and
113
+ release notes ship with the CLI, so the newest CLI covers every release,
114
+ whatever version the project starts from.
115
+
39
116
  - `iwsdk adapter status` reports MCP, instruction, and permission state.
40
117
  - `iwsdk adapter prune` removes managed MCP/permission entries and preserves
41
118
  editable instruction files.
@@ -22,11 +22,22 @@ export interface SyncAgentAdaptersOptions {
22
22
  command?: string;
23
23
  args?: string[];
24
24
  }
25
+ export type AdapterGuidanceResult = {
26
+ status: 'synced';
27
+ version: string;
28
+ origin: string;
29
+ changed: boolean;
30
+ skipped: string[];
31
+ } | {
32
+ status: 'unavailable';
33
+ code: string;
34
+ message: string;
35
+ };
25
36
  export declare function syncAgentAdapters({ workspaceRoot, tools, command, args, }: SyncAgentAdaptersOptions): Promise<{
26
37
  workspaceRoot: string;
27
38
  tools: AiTool[];
28
39
  serverNames: string[];
29
- createdInstructions: string[];
40
+ guidance: AdapterGuidanceResult;
30
41
  }>;
31
42
  export declare function pruneAgentAdapters({ workspaceRoot, tools, }: {
32
43
  workspaceRoot: string;
@@ -1 +1 @@
1
- {"version":3,"file":"agent-adapters.d.ts","sourceRoot":"","sources":["../src/agent-adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAAsB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAaxE,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;KAClC,CAAC;IACF,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;QAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AA6SD,wBAAsB,iBAAiB,CAAC,EACtC,aAAa,EACb,KAAK,EACL,OAAO,EACP,IAAI,GACL,EAAE,wBAAwB,GAAG,OAAO,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC,CAyBD;AAED,wBAAsB,kBAAkB,CAAC,EACvC,aAAa,EACb,KAAK,GACN,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AA8FD,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,oBAAoB,CAAC,CA0C/B;AAED,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0BvE"}
1
+ {"version":3,"file":"agent-adapters.d.ts","sourceRoot":"","sources":["../src/agent-adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,OAAO,EAAsB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAaxE,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;KAClC,CAAC;IACF,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;QAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAoVD,MAAM,MAAM,qBAAqB,GAC7B;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,wBAAsB,iBAAiB,CAAC,EACtC,aAAa,EACb,KAAK,EACL,OAAO,EACP,IAAI,GACL,EAAE,wBAAwB,GAAG,OAAO,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,qBAAqB,CAAC;CACjC,CAAC,CA6BD;AAED,wBAAsB,kBAAkB,CAAC,EACvC,aAAa,EACb,KAAK,GACN,EAAE;IACD,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AA8FD,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,oBAAoB,CAAC,CA0C/B;AAED,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0BvE"}
@@ -0,0 +1,312 @@
1
+ ---
2
+ name: iwsdk-build-model
3
+ description: Build or materially repair one reusable IWSDK 3D model as a glTF or deterministic parentless Three.js Object3D, including geometry, surface-relative detail, materials, semantic hierarchy, isolated inspection, and focused refinement. Does not arrange scenes, lighting, environment, or cameras; use iwsdk-compose-scene for those.
4
+ ---
5
+
6
+ # IWSDK Build Model
7
+
8
+ Create one reusable model, prove that it works from multiple viewpoints, and hand a
9
+ stable manifest asset to `iwsdk-compose-scene`. This skill owns object-local geometry,
10
+ materials, hierarchy, proportions, and detail. It does not own scene JSON or the
11
+ placement of one asset relative to another. When a scene needs several new models,
12
+ finish each one under this skill before beginning composition; support assets such as
13
+ display stands, architecture, and set dressing are still models.
14
+
15
+ UIKitML panels belong to `iwsdk-ui`, not this skill.
16
+
17
+ ## Fixed Boundaries
18
+
19
+ - Geometry and materials live in glTF or `src/scene-assets/*.scene-asset.ts`, never in
20
+ scene JSON.
21
+ - Register the result in the configured `src/assets.ts` default manifest export.
22
+ - A procedural export is a deterministic, parentless `Object3D` prototype. The editor
23
+ and application evaluate the manifest in separate realms, so do not use a `World`,
24
+ DOM state, timers, or shared object identity while defining it.
25
+ - Import Three.js classes from `@iwsdk/core`, never directly from `three`.
26
+ - For a new multi-file model, do not start `iwsdk dev up` until the first complete
27
+ asset module and manifest registration pass `npm run --if-present typecheck`. A live browser
28
+ evaluating half-written imports can leave HMR connected but not command-ready.
29
+ - Repetition inside one model belongs here. Repetition of placed manifest assets
30
+ belongs to `iwsdk-compose-scene` through prefabs or patterns.
31
+ - Use meters and keep the asset origin, forward axis, floor/contact plane, size
32
+ envelope, and attachment anchors explicit.
33
+
34
+ ## 1. Define The Model Contract
35
+
36
+ Turn the request into a short checklist before editing:
37
+
38
+ - silhouette and overall proportions;
39
+ - primary masses, secondary forms, and tertiary surface detail;
40
+ - required articulated or independently readable parts;
41
+ - negative spaces, support contacts, and plausible attachment points;
42
+ - material families and their visual separation;
43
+ - canonical front, back, side, top, and quarter views;
44
+ - exact named parts that merit focused inspection.
45
+
46
+ A single reference image proves only what is visible. Mark hidden geometry as an
47
+ assumption instead of pretending it is specified.
48
+
49
+ ## 2. Choose The Representation
50
+
51
+ Prefer, in order:
52
+
53
+ 1. an existing suitable manifest asset;
54
+ 2. a project-owned glTF with an inspectable hierarchy;
55
+ 3. an installable reusable asset or template;
56
+ 4. a deterministic procedural `Object3D` when controllable dimensions, semantic
57
+ subparts, articulation, or repeatable code-driven variation matter.
58
+
59
+ MetaVR and Drawcall Market can supply starting assets, but do not assume downloaded
60
+ models contain useful semantic parts. Inspect finalists before adopting them and copy
61
+ selected files into project-owned storage rather than persisting a transient CDN URL.
62
+
63
+ For substantial procedural work, keep a small construction library beside the model:
64
+ lofts/extrusions, bevelled primitives, mirrored duplication, surface frames, repeated
65
+ detail, and material factories. Build semantic named groups such as `Hull`, `Wing`,
66
+ `Nacelle`, `VentRow`, and `LandingGear`; unnamed meshes cannot be focused reliably.
67
+
68
+ ## 3. Build From Large To Small
69
+
70
+ Build in this order:
71
+
72
+ 1. silhouette and primary masses;
73
+ 2. proportion-defining secondary forms and negative spaces;
74
+ 3. joints, seams, supports, and functional connections;
75
+ 4. repeated tertiary detail;
76
+ 5. material separation and restrained finish.
77
+
78
+ Do not use tertiary detail to hide unresolved primary geometry. Reuse geometries and
79
+ materials where practical, but preserve names on inspection-critical groups.
80
+
81
+ ### Pass the clay-form gate before detailing
82
+
83
+ - Build continuous designed forms with lofted sections, tapered plates, or bevelled
84
+ transitions. Do not approximate a vehicle hull, nacelle, limb, or other dominant
85
+ form as an exposed pile of stock boxes and cylinders.
86
+ - A primitive is appropriate for an intentionally manufactured subpart such as a
87
+ bearing, fastener, pipe, hub, or recessed mechanism. Where a large secondary mass
88
+ meets the primary form, add a collar, root, socket, fillet-like fairing, overlap, or
89
+ other visible load path instead of letting the pieces merely intersect or hover.
90
+ - In the clay rows of the first complete preview, judge the primary and secondary forms
91
+ before accepting tertiary detail as finish. From front, side, top, and quarter views,
92
+ the silhouette, thickness changes, and transitions must remain intentional without
93
+ color, emission, or tiny greebles.
94
+ - Treat obvious primitive profiles, floating slabs, paper-thin structural plates,
95
+ unexplained gaps, and abrupt tangencies as correction-worthy model defects even
96
+ when the material preview looks polished.
97
+ - Detail quality is not object count. For one hero-scale asset, treat roughly 700
98
+ meshes or 100,000 rendered triangles as a review trigger rather than a target. Before
99
+ exceeding it, remove repeated micro-plates, bolts, or seams that do not improve the
100
+ silhouette, material boundary, or construction story. Spend geometry on continuous
101
+ profiles, root fairings, joints, and thickness changes that remain legible in clay.
102
+ - In the single correction round, fix the weakest primary transition, attachment, or
103
+ support first. Do not answer a merely sparse-looking render by multiplying tertiary
104
+ greebles; fewer well-integrated details beat dense primitive noise.
105
+
106
+ ### Keep iteration bounded
107
+
108
+ - Reuse the bundled construction library instead of emitting another geometry-helper
109
+ file into the conversation.
110
+ - Prefer two to six authored modules for a substantial model: shared materials/detail,
111
+ primary form, secondary assemblies, and a small root module. Split only at a real
112
+ ownership boundary or before a file grows past roughly 500 lines; do not create one
113
+ file and one tool round-trip per visible part.
114
+ - Once module boundaries are chosen, emit independent files together rather than
115
+ narrating and waiting between assemblies. Run one initial `npm run --if-present typecheck` after
116
+ all model modules and manifest registration exist; rerun it only after correcting
117
+ an actual error or before final delivery.
118
+ - In Claude Code, `Write` echoes the complete source back into the transcript. Use it
119
+ only for short files (roughly 80 lines or 8 KB). For longer new modules, use Bash
120
+ commands with single-quoted heredocs (`<<'EOF'`) so template literals, `$`, and
121
+ backticks remain literal and the success result stays short. Treat 100 source lines
122
+ or 10 KB as a hard transport limit for one tool call: create the file with `>` and
123
+ append later sections with `>>` in separate calls. End each call at the heredoc
124
+ delimiter; do not append command substitutions or validation to that same command.
125
+ A single logical correction may use several sequential tool calls—never combine
126
+ large replacements across multiple modules into one oversized patch script. Do not
127
+ put TypeScript template literals inside `node -e` or another shell-quoted one-liner.
128
+ Duplicated source payloads and quoting recovery waste context.
129
+ - After a write or edit succeeds, do not read the whole file back. Apply narrow edits;
130
+ avoid whole-file rewrites after initial creation.
131
+ - Claude Code's `Edit` result can retain the complete original file in the transcript.
132
+ Do not use `Edit` on a source file above roughly 120 lines. Use a narrowly scoped
133
+ scripted replacement that asserts exactly one match, writes the file once, and
134
+ prints only a short confirmation. This keeps a one-line correction from reloading
135
+ hundreds of source lines into context and every later cache read.
136
+ - Keep every agent-loop model preview at 640×480 or smaller. If a defect needs closer
137
+ inspection, use `focus` at the same pixel budget instead of raising the resolution.
138
+ Prefer the MCP preview, which persists the image and returns `screenshotPath`. Read
139
+ that file only when visual inspection is needed. Use one contact sheet rather than
140
+ several redundant views; use smaller sheets for support assets. Delivery and
141
+ benchmark captures may be larger, but do not feed duplicate high-resolution images
142
+ back into the model context.
143
+
144
+ ### Surface-relative detail is mandatory
145
+
146
+ For vents, plates, grilles, bolts, fins, decals, struts, or greebles attached to a
147
+ sloped or curved surface, establish one local frame:
148
+
149
+ For substantial procedural work, copy this skill's bundled starter library into the
150
+ project without reading or rewriting it:
151
+
152
+ ```bash
153
+ model_kit="$(find .claude/skills .agents/skills -path '*/iwsdk-build-model/assets/hardsurface.ts.template' -print -quit)"
154
+ mkdir -p src/scene-assets/lib
155
+ cp "$model_kit" src/scene-assets/lib/hardsurface.ts
156
+ ```
157
+
158
+ Do not `Read`, print, page through, or search the copied implementation. This public
159
+ surface is complete:
160
+
161
+ ```ts
162
+ surfaceFrame(origin: Vector3, normal: Vector3, tangentHint: Vector3): SurfaceFrame
163
+ placeOnSurface(object: Object3D, frame: SurfaceFrame, normalOffset?: number): void
164
+ mirrorSurfaceFrameX(frame: SurfaceFrame): SurfaceFrame
165
+ orientBasis(object: Object3D, xDir: Vector3, yDir: Vector3): void
166
+ alignSpan(object: Object3D, a: Vector3, b: Vector3, upHint?: Vector3): number
167
+ ensureOutwardWinding(geometry: BufferGeometry): BufferGeometry
168
+ mirrorGeometryX(geometry: BufferGeometry): BufferGeometry
169
+ bevelBox(width, height, depth, bevel?, cornerRadius?, curveSegments?): BufferGeometry
170
+ taperPlate(lengthX, widthYFront, widthYBack, thickness, bevel?): BufferGeometry
171
+ LoftSurface.tube(sections: TubeSection[]): LoftSurface
172
+ LoftSurface.blade(stations: BladeStation[]): LoftSurface
173
+ surface.point(along: number, theta: number): Vector3
174
+ surface.frame(along: number, theta: number): SurfaceFrame
175
+ surface.frameToward(along: number, outwardDirection: Vector3, samples?: number): SurfaceFrame
176
+ surface.build(
177
+ alongs: number[],
178
+ segments?: number,
179
+ caps?: boolean | {start?: boolean; end?: boolean},
180
+ ): BufferGeometry
181
+ sampleRange(from: number, to: number, count: number): number[]
182
+ makeRandom(seed: number): () => number
183
+ ```
184
+
185
+ The exact section shapes are
186
+ `{z, halfW, hUp, hDown?, cx?, cy?, power?}` for `TubeSection` and
187
+ `{x, leadZ, trailZ, thickUp, thickDown?, y?, power?}` for `BladeStation`.
188
+ `point`, `frame`, `frameToward`, and `build` take the same absolute `z` or `x`
189
+ coordinates supplied in those sections; do not normalize the sweep range. Passing
190
+ `true` as `caps` closes both ends and `false` leaves both open. `alignSpan()` assumes
191
+ a Y-up primitive, places it midway between `a` and `b`, aligns local +Y to that span,
192
+ and returns the span length; it does not resize the geometry.
193
+
194
+ It exports deterministic lofted tube/blade surfaces, matching surface frames,
195
+ bevelled blocks and plates, span/basis placement, mirrored winding repair, and seeded
196
+ randomness. Import the needed helpers instead of reimplementing that geometry layer.
197
+
198
+ `SurfaceFrame` has a fixed object-space mapping: `tangent` becomes local +X,
199
+ `bitangent` becomes local +Y, and `normal` becomes local +Z. For lofts, `frame()`
200
+ keeps the tangent along the sweep and `frameToward()` only chooses the sample whose
201
+ normal most closely faces the requested direction. `placeOnSurface()` sets both the
202
+ object position and quaternion. To rotate a mounted detail within the tangent plane,
203
+ place a wrapper on the frame and rotate the detail child around local Z; do not apply
204
+ an Euler rotation to the frame-aligned wrapper itself. These conventions are the
205
+ complete orientation contract; do not inspect the bundled implementation to infer
206
+ them.
207
+
208
+ Author the detail so local X/Y lie in the surface plane and local +Z is thickness.
209
+ Offset by `thickness / 2 - embedDepth` so the detail visibly contacts the surface.
210
+ Once a local parent frame is established, vary rows and columns in tangent/bitangent
211
+ coordinates.
212
+
213
+ Free `rotation.set(...)`, `rotation.x = ...`, or guessed Euler angles on an individual
214
+ surface detail are a defect unless the detail already lives under a correctly aligned
215
+ surface-frame parent. This rule prevents the common failure where a vent intended to
216
+ lie against a hull becomes a standing fin.
217
+
218
+ Mirror with complete matrices or mirrored local frames, not position-only copies.
219
+ Recalculate or validate winding and normals after custom indexed/non-indexed geometry.
220
+
221
+ ## 4. Validate The Asset
222
+
223
+ After the initial model and manifest pass typecheck, start the managed editor and use
224
+ the isolated model preview when it is command-ready. If valid source has
225
+ `browserConnected: true` but
226
+ `browserCommandReady: false` after an HMR error, call `browser_reload_page` once and
227
+ recheck before deeper diagnosis.
228
+
229
+ ```text
230
+ asset_render_preview
231
+ ```
232
+
233
+ ```bash
234
+ npx @iwsdk/cli asset render-preview \
235
+ --input-json '{"assetId":"ship","mode":"material"}' \
236
+ --output-file artifacts/ship-material.png
237
+ npx @iwsdk/cli asset render-preview \
238
+ --input-json '{"assetId":"ship","mode":"clay"}' \
239
+ --output-file artifacts/ship-clay.png
240
+ ```
241
+
242
+ The command renders one bounded contact sheet. Its default views are front, back,
243
+ right, top, and quarter. It also returns prototype-local bounds, framing bounds,
244
+ object/mesh/geometry/material counts, rendered triangles, named-part bounds, and
245
+ deterministic warnings for missing geometry or normals, invalid indices, non-finite
246
+ data, degenerate triangles, unnamed meshes, and unusual material sides.
247
+
248
+ The MCP response caps named-part paths and warning examples, reports full counts per
249
+ warning code, and omits part bounds to avoid flooding model context. Use CLI JSON when
250
+ complete named-part bounds or warning paths are required.
251
+
252
+ Visible transparent/additive effects are rendered but excluded from automatic framing.
253
+ Set `object.userData.iwsdkPreviewBounds = 'exclude'` for another visible effect that
254
+ must not determine the camera fit.
255
+
256
+ Always inspect the primary model. For simple support assets whose bounds and contact
257
+ plane are explicit, defer a separate preview when the first composed-scene render
258
+ will show them clearly; do not spend one model-render round-trip per trivial stand,
259
+ wall, or floor piece.
260
+
261
+ If any part looks implausible, frame it directly:
262
+
263
+ ```bash
264
+ npx @iwsdk/cli asset render-preview \
265
+ --input-json '{"assetId":"ship","mode":"clay","focus":"Ship/Hull/VentRow"}' \
266
+ --output-file artifacts/ship-vent-row.png
267
+ ```
268
+
269
+ Use the clay pass to separate geometry/attachment defects from lighting or authored
270
+ material response. A defect visible in clay belongs here. A defect that appears only
271
+ after scene lighting is applied routes to `iwsdk-compose-scene` for exposure/light
272
+ diagnosis first; return here only if the material assignment itself is wrong.
273
+
274
+ ## 5. Review And Refine
275
+
276
+ Review both material and clay rows for every substantial new or repaired model. Clay
277
+ is optional only for a simple support asset whose form and contact are already obvious
278
+ in the composed-scene render. Check:
279
+
280
+ 1. silhouette;
281
+ 2. proportions;
282
+ 3. continuous primary and secondary form transitions in clay;
283
+ 4. required parts;
284
+ 5. negative space;
285
+ 6. contacts, thickness, and surface attachment;
286
+ 7. material response and separation.
287
+
288
+ Inspect suspicious named subtrees with `focus`. Fix the highest-impact defect in the
289
+ owning asset module and rerun the preview. Default to at most two focused correction
290
+ rounds after the first complete model. Stop earlier on repeated defects, oscillation,
291
+ diagnostic plateau, missing source evidence, or a representation ceiling.
292
+
293
+ ## 6. Hand Off To Scene Composition
294
+
295
+ Before switching skills, inventory every visible element required by the requested
296
+ scene. Existing manifest assets may pass through unchanged; every missing or materially
297
+ changed model, including support and environment geometry, must complete this workflow
298
+ and have a stable manifest id. Do not leave asset-module authoring for the composition
299
+ phase.
300
+
301
+ Hand `iwsdk-compose-scene`:
302
+
303
+ - the stable manifest asset id;
304
+ - local origin, forward/up axes, and size envelope;
305
+ - floor/contact plane and named attachment anchors;
306
+ - intentional transparent/additive bounds exclusions;
307
+ - passing material and clay preview evidence;
308
+ - remaining assumptions or accepted gaps.
309
+
310
+ Do not compensate for a model-local defect with a scene transform. Do not start scene
311
+ lighting or camera iteration until the model passes isolated review.
312
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: 'IWSDK Build Model'
3
+ short_description: 'Build and inspect one reusable IWSDK 3D model'
4
+ default_prompt: 'Use $iwsdk-build-model to build or repair this model and prove it with isolated multi-view inspection.'