@iwsdk/create 0.5.3 → 1.0.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 (106) hide show
  1. package/dist/cli.js +7223 -215
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/package.json +8 -7
  82. package/scripts/verify-release-ready.mjs +25 -0
  83. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  89. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  94. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  100. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  105. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  106. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -1,364 +0,0 @@
1
- ---
2
- name: iwsdk-planner
3
- description: IWSDK experience pipeline and planning guide. Use when building a new IWSDK app/game end-to-end, planning new IWSDK features, designing systems/components, reviewing IWSDK code architecture, or when the user asks about IWSDK patterns, ECS design, signals, or reactive programming. Runs a phased ideation → design → grounding → architecture → build → verify → ship pipeline, orchestrating sub-agents per phase where the harness supports them.
4
- argument-hint: '[experience idea, or feature to plan]'
5
- ---
6
-
7
- # IWSDK Experience Pipeline
8
-
9
- You are an expert IWSDK (Immersive Web SDK) architect and producer. This skill
10
- turns an idea ("a VR bowling game", "an AR plant identifier") into a specced,
11
- designed, grounded, built, and verified IWSDK app through explicit phases —
12
- each phase producing reviewable artifacts on disk before the next begins.
13
-
14
- ## Choose Your Mode
15
-
16
- | Situation | Mode |
17
- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |
18
- | New experience/game/app from an idea, or a large feature epic (multi-system) | **PIPELINE** — run the phases below |
19
- | Small feature in an existing app, an architecture question, a code review | **QUICK** — jump to [Quick Planning](#quick-planning-single-features) |
20
-
21
- When in doubt: if the work needs a spec the user should react to, use PIPELINE.
22
-
23
- ## Operating Principles
24
-
25
- 1. **Artifacts over conversation.** Every phase writes files under `design/`
26
- in the project. Files are the source of truth; the conversation is not.
27
- Anyone (including a fresh agent) must be able to resume from disk alone.
28
- 2. **Phase gates.** Do not start phase N+1 until phase N's artifact exists and
29
- its gate is satisfied. Record progress in `design/PIPELINE.md` (template
30
- below). Skipping a phase is allowed only if the user asks for it — record
31
- the skip and why.
32
- 3. **Sub-agents where available, inline where not.** If your harness has a
33
- sub-agent/Task tool, fan phases out as described in each phase's playbook —
34
- parallel agents for independent artifacts, one agent per research domain,
35
- disjoint file ownership for build agents. If not, do the same steps
36
- yourself, sequentially. The artifacts and gates are identical either way.
37
- 4. **The developer is a collaborator, not an oracle.** Ask real questions at
38
- ideation and at gates (use a structured question tool such as
39
- AskUserQuestion when available — batched, with opinionated defaults). If
40
- the user is absent or asked you to proceed autonomously, choose defaults
41
- and mark every such decision `[ASSUMED]` in the artifact, then continue.
42
- 5. **Ground before you build.** No implementation before every mechanic in the
43
- spec is mapped to IWSDK built-ins or explicitly classified as custom work
44
- (Phase 3). Rebuilding something IWSDK provides is the #1 failure mode.
45
- 6. **Verify with the runtime, not vibes.** "It compiles" is not a gate.
46
- Milestones pass only when the live app (dev server + emulated XR input +
47
- ECS assertions + screenshots) demonstrates the behavior.
48
-
49
- ## Pipeline State File
50
-
51
- Create `design/PIPELINE.md` at the start; update it at every phase boundary:
52
-
53
- ```markdown
54
- # <Project Name> — Pipeline State
55
-
56
- | Phase | Status | Artifact | Notes |
57
- | -------------- | ----------- | --------------------------------- | ------------------------------ |
58
- | 0 Preflight | done | (this file, Capabilities below) | |
59
- | 1 Ideation | done | design/GAME_SPEC.md | approved by user / assumptions |
60
- | 2 Design | in-progress | design/deck.html, design/concept/ | |
61
- | 3 Grounding | pending | design/TECH_PLAN.md | |
62
- | 4 Architecture | pending | design/ARCHITECTURE.md | |
63
- | 5 Build | pending | src/, milestone log below | |
64
- | 6 Verify | pending | design/VERIFICATION.md | |
65
- | 7 Ship | pending | review report, build, deploy | |
66
-
67
- ## Capabilities (Phase 0 findings)
68
-
69
- - interactive questions: yes (AskUserQuestion) | no (autonomous)
70
- - sub-agents: yes (Task tool) | no
71
- - slide/HTML preview: artifact tool | file only
72
- - image generation: <tool name> | none (SVG fallback)
73
- - iwsdk CLI: <version> | pending scaffold · reference: ready|warmup-needed|unavailable
74
- - runtime verify: managed headed browser ready | blocked because <why>
75
-
76
- ## Milestone Log
77
-
78
- - M0 <date>: scaffold renders — screenshot design/verify/m0.png
79
- ```
80
-
81
- **Resuming:** if `design/PIPELINE.md` exists, read it plus the artifacts of
82
- completed phases, then continue from the first non-done phase. Never redo a
83
- done phase unless the user changes the requirements behind it.
84
-
85
- ---
86
-
87
- ## Phase 0 — Preflight (capability & environment probe)
88
-
89
- Goal: know what this harness and machine can do, so later phases degrade
90
- gracefully instead of failing mid-flight.
91
-
92
- Probe and record in `design/PIPELINE.md` (Capabilities section):
93
-
94
- 1. **Interaction** — can you ask the user structured questions and get answers
95
- (e.g. AskUserQuestion tool)? If the user said "build it, don't ask me", or
96
- no question tool exists and the user is unresponsive, set `autonomous`.
97
- 2. **Sub-agents** — do you have a Task/agent-spawning tool? Note limits you
98
- know (e.g. sub-agents usually cannot keep background processes alive — the
99
- main agent must own dev servers).
100
- 3. **Presentation** — can you render/publish HTML (artifact tool)? Can you
101
- generate images (any image-gen tool)? Fallback: hand-authored SVG + local
102
- HTML files.
103
- 4. **Toolchain** — `node --version` (needs >=20.19 <21, >=22.12 <23, or >=24);
104
- is there an existing IWSDK app here or are we scaffolding fresh?
105
- 5. **IWSDK tooling** — only if an app already exists, and always from its
106
- directory (never a bare shell/monorepo root — `npx iwsdk` outside an app
107
- resolves to an unrelated npm package): `npx iwsdk status`,
108
- `npx iwsdk reference status`. Fresh installed scaffolds initialize this
109
- shared cache during creation. If an older/existing app still reports warmup
110
- needed and you have network, start `npx iwsdk reference warmup` **in the
111
- background now** (~210 MB download) so it's ready by Phase 3. If it fails, note the
112
- docs fallback (see `references/grounding.md`). **Scaffolding fresh?**
113
- Skip these probes, record `iwsdk CLI: pending scaffold`, and rely on the
114
- Scaffold Checkpoint below to run them right after ideation.
115
-
116
- Gate: Capabilities section filled in. This phase never asks the user anything.
117
-
118
- ## Phase 1 — Ideation (idea → spec)
119
-
120
- Goal: lock the idea into `design/GAME_SPEC.md` — the single document that says
121
- what we are building, for whom, on what device, at what scope.
122
-
123
- Playbook: `references/ideation.md` (question bank, spec template, worked
124
- example).
125
-
126
- Procedure:
127
-
128
- 1. Restate the user's idea in 2–3 sentences. State the genre, the fantasy,
129
- and the obvious open questions.
130
- 2. Ask **batched** question rounds (3–4 questions each, each with 2–4
131
- opinionated options + your recommended default; structured question tools
132
- typically cap a call at 4 questions — split a bigger round into two
133
- calls rather than dropping questions). Round 1: platform & mode
134
- (VR/AR/browser-first/dual), core loop, scale/comfort. Round 2: mechanics
135
- detail, art/audio direction, scope tier. Stop when the axes in the
136
- template are pinned — usually 2 rounds, 3 max. In `autonomous` mode:
137
- answer every question yourself with the most defensible default, mark
138
- `[ASSUMED]`, and keep a "Questions I would have asked" appendix.
139
- 3. Write `design/GAME_SPEC.md` from the template: pitch, pillars, core loop,
140
- mechanics list, platform/mode, space & locomotion needs, UI surfaces,
141
- audio moments, art direction, scope tiers (MVP / target / stretch),
142
- non-goals, success criteria (each criterion must be _observable_ — you
143
- will assert it in Phase 6).
144
- 4. Present a compact summary and get sign-off (or record `[ASSUMED]` set).
145
-
146
- Gate: spec exists; every mechanic is named; success criteria observable;
147
- user approved or assumptions documented.
148
-
149
- ### Scaffold Checkpoint (fresh projects only)
150
-
151
- Ideation locks the platform axes — scaffold **now**, before Phase 2, so the
152
- project directory exists for every later artifact and tool:
153
-
154
- 1. Scaffold with `@iwsdk/create` using the spec's mode/features
155
- (`references/build-milestones.md` has the flag menu); `cd` into the app.
156
- 2. Move any `design/` files created so far into `<app>/design/` — from here
157
- on, everything lives in the app root. Do the move BEFORE fanning out
158
- Phase 2/3 agents (or brief them with the final app paths) — agents
159
- writing to a stale staging path while you move it lose work.
160
- 3. Run the deferred Phase 0 probes (`npx iwsdk status`, `npx iwsdk reference
161
- status`). Creation initializes the reference cache before returning. Only if
162
- status still reports warmup required should you run `npx iwsdk reference
163
- warmup` and treat a failure as a scaffold/setup defect.
164
- 4. Do **not** modify app code yet — Phase 5's M0 verifies the untouched
165
- scaffold. Never scaffold a nested app inside an existing IWSDK app.
166
-
167
- ## Phase 2 — Design (spec → deck + concept art)
168
-
169
- Goal: make the spec _visible_ so the developer can react to a look and a
170
- layout, not a wall of text. Everything here is presentational — no code.
171
-
172
- Playbook: `references/design-deck.md` (deck outline, HTML/SVG conventions,
173
- concept-art briefs, capability ladder).
174
-
175
- Fan out (parallel sub-agents if available, else sequential):
176
-
177
- - **Deck agent** → `design/deck.html`: self-contained slide deck (inline CSS,
178
- arrow-key navigation) covering pitch, pillars, core loop diagram, mechanics,
179
- level layout, interaction model, art/audio direction, scope, tech snapshot.
180
- - **Concept-art agent** → `design/concept/*.svg`: 2–4 hand-authored SVG
181
- pieces (key moment, environment mood, UI mock). Use an image-generation
182
- tool instead if Phase 0 found one.
183
- - **Layout agent** → `design/concept/layout.svg`: top-down play-space diagram
184
- with dimensions in meters (XR scale is real scale — a desk is 0.75 m high).
185
-
186
- Each agent reads `design/GAME_SPEC.md`; give them the file path, not a paste.
187
- Present results (artifact tool if available, else file paths + one-line
188
- descriptions). Ask for reactions if interactive; else proceed.
189
-
190
- Gate: deck + at least one concept piece exist and match the spec.
191
-
192
- Phases 2 and 3 both consume only the spec. They may run **concurrently** only
193
- when `npx iwsdk reference status` already reports ready. Otherwise, let Phase 2
194
- run while warmup finishes, then confirm readiness (or select the documented
195
- fallback) before launching Phase 3. Both phases must be done before Phase 4.
196
-
197
- ## Phase 3 — Grounding (spec → IWSDK reality)
198
-
199
- Goal: `design/TECH_PLAN.md` — every mechanic mapped to concrete IWSDK API
200
- surface, so Phase 5 is assembly rather than discovery.
201
-
202
- Playbook: `references/grounding.md` (reference CLI protocol, docs fallback
203
- ladder, domain→API map, TECH_PLAN template). API ground truth:
204
- `references/api-reference.md`.
205
-
206
- Procedure:
207
-
208
- 1. Enforce the reference barrier: confirm `npx iwsdk reference status` is
209
- ready, or record which fallback from `references/grounding.md` will supply
210
- API evidence. Never fan out grounding agents while warmup is still running.
211
- 2. Derive research domains from the spec (typically: input & interaction,
212
- physics, locomotion, UI, audio, environment/lighting, assets/levels, and
213
- AR-specific surfaces if applicable).
214
- 3. Fan out one research agent per domain (or do them in sequence). Each
215
- agent: reads the spec + `references/grounding.md`, queries the reference
216
- system (`npx iwsdk reference search|api|components|systems|examples`) or
217
- the documented fallbacks, and returns table rows:
218
- `mechanic → classification (BUILT-IN | CONFIGURE | CUSTOM) → exact IWSDK
219
- pieces (components/systems/feature flags) → custom work remaining → risks`.
220
- 4. Merge into `design/TECH_PLAN.md`: `iwsdk.config.json` world/feature block,
221
- the mechanics table, custom system specs (queries, priorities, globals),
222
- asset manifest (see Asset Strategy in `references/build-milestones.md`),
223
- and a risk list with mitigations.
224
- 5. Audit against the reinvention-risk table in `references/api-reference.md`:
225
- anything classified CUSTOM that IWSDK already provides gets reclassified.
226
-
227
- Gate: no mechanic left unclassified; feature flags decided with prerequisites
228
- checked (e.g. locomotion requires collision geometry); every CUSTOM item has
229
- a sketched query/system design; asset list complete.
230
-
231
- ## Phase 4 — Architecture (tech plan → build plan)
232
-
233
- Goal: `design/ARCHITECTURE.md` — the file-by-file, milestone-by-milestone
234
- construction plan.
235
-
236
- Playbook: `references/build-milestones.md` (template, scaffold flags,
237
- milestone rules, sub-agent file-ownership rules).
238
-
239
- Contents: scaffold command (exact `@iwsdk/create` flags) or existing-app
240
- delta; file tree (one system per file); component schemas (names, fields,
241
- Types); systems table (name, queries, priority band: 0–9 input / 10–19 sim /
242
- 20–29 visual sync / 30+ UI); globals signals; milestone plan — M0 "scaffold
243
- renders" through M-final, each with a **demo criterion** (what you can see)
244
- and **assertions** (what you will check via the CLI in Phase 6).
245
-
246
- Gate: every spec mechanic traces to a milestone; every milestone has demo
247
- criterion + assertions; user approved (or `[ASSUMED]`).
248
-
249
- ## Phase 5 — Build (milestone loop)
250
-
251
- Goal: working code, one verified milestone at a time.
252
-
253
- Playbook: `references/build-milestones.md`. API ground truth while coding:
254
- `references/api-reference.md` — follow its best practices (stateless systems,
255
- signals, cleanup, `createTransformEntity`, AssetManager, feature-flag
256
- hygiene) and its anti-pattern list.
257
-
258
- Rules:
259
-
260
- - M0 baseline first: the app scaffolded at the Scaffold Checkpoint — or,
261
- when already inside a generated/existing IWSDK app (the common case for
262
- this skill), that app adopted as-is ("existing-app delta" in
263
- `references/build-milestones.md`; never scaffold a nested app). Run the
264
- verify loop once end-to-end (dev server up, screenshot, XR enter) _before_
265
- writing gameplay code. A broken baseline poisons every later diagnosis.
266
- - **The main agent owns the dev server** and everything stateful (`iwsdk dev
267
- up/down`, ports, browser). Sub-agents write code; they may run `npx tsc
268
- --noEmit` but must not start servers.
269
- - Parallel sub-agents only for genuinely independent modules, each owning a
270
- disjoint set of files; the main agent owns shared files (`src/index.ts`,
271
- component registry wiring) and integrates.
272
- - After each milestone: `npx tsc --noEmit` → verify loop (Phase 6 subset for
273
- this milestone's assertions) → update Milestone Log in `design/PIPELINE.md`
274
- (+ commit — confirm once at Phase 5 start, or `[ASSUMED]` in autonomous
275
- mode; see `references/build-milestones.md`).
276
- - When something fails, debug with the runtime tools (ecs pause/step/
277
- snapshot/diff, browser logs), not by staring at code — see
278
- `references/verification.md`.
279
-
280
- Gate (per milestone): demo criterion observed + assertions pass + typecheck
281
- clean.
282
-
283
- ## Phase 6 — Verify (whole-app pass)
284
-
285
- Goal: `design/VERIFICATION.md` — evidence, per success criterion from the
286
- spec, that the app does what the spec says.
287
-
288
- Playbook: `references/verification.md` (the exact CLI loop, input-simulation
289
- cheat sheet, assertion patterns, known traps, recovery ladder).
290
-
291
- Run the full loop against the finished app: typecheck → dev up → connectivity
292
- → browser screenshot → XR enter → clean console → per-criterion scenario
293
- (simulate inputs, assert via `ecs query`/`snapshot`/`diff`/screenshots/log
294
- patterns). Record each criterion PASS/FAIL with the evidence (command +
295
- output + screenshot path). Fix and re-run failures; a criterion the runtime
296
- cannot demonstrate goes back to Phase 5, or gets renegotiated with the user.
297
- Autonomous mode: after 2–3 focused fix cycles on a stubborn criterion, stop
298
- looping — record it as FAIL under "Deferred / known gaps" in
299
- `design/VERIFICATION.md` with the attempted evidence, mark the spec item
300
- `[FAILED — deferred]`, and proceed to Phase 7 with the failure stated
301
- prominently in the close-out report.
302
-
303
- Gate: all MVP success criteria PASS with recorded evidence — or each failure
304
- explicitly deferred with evidence of the attempts (autonomous mode).
305
-
306
- ## Phase 7 — Review & Ship
307
-
308
- 1. **Review** — run the `iwsdk-project-code-reviewer` agent (ships with IWSDK
309
- projects) over the code; apply Critical/Warning fixes; re-run the Phase 6
310
- assertions touched by the fixes. No agent tool, or the agent file missing?
311
- Review the diff yourself against `references/api-reference.md` — the
312
- Anti-Patterns list, the reinvention-risk table, and the Performance
313
- Tips — and record findings in the close-out report.
314
- 2. **Performance sanity** — VR frame budget is 11–14 ms: check for per-frame
315
- allocations, unthrottled queries, oversized textures (the reviewer flags
316
- most of these).
317
- 3. **Build** — `npm run build`; confirm `dist/` contains the changes
318
- (`grep` a distinctive pattern in `dist/assets/*.js`).
319
- 4. **Ship** — per user preference: static deploy of `dist/` (e.g.
320
- `npx gh-pages -d dist`), zip delivery, or just the local build
321
- (autonomous default: local build only; list deploy options in the
322
- close-out report).
323
- 5. **Close out** — final report: what was built vs the spec (including every
324
- `[ASSUMED]` decision), evidence summary, known gaps / stretch items, and a
325
- short retro (what to do differently next time) appended to
326
- `design/PIPELINE.md`.
327
-
328
- ---
329
-
330
- ## Quick Planning (single features)
331
-
332
- For a contained feature in an existing app, skip the pipeline and run this
333
- checklist (details in `references/api-reference.md`):
334
-
335
- 1. **Feature flags** — what built-ins does this need (locomotion, physics,
336
- grabbing, spatialUI, sceneUnderstanding…) and are their prerequisites met
337
- (e.g. locomotion needs collision geometry)?
338
- 2. **Check the reinvention-risk table** — is this already a built-in?
339
- 3. **Ground it** — `npx iwsdk reference search/api/examples` for the pieces
340
- you'll touch (protocol in `references/grounding.md`).
341
- 4. **Components** — what data, what Types, tag vs data components?
342
- 5. **Queries & reactivity** — how do systems find entities; qualify/
343
- disqualify subscriptions over polling; signals for state.
344
- 6. **Lifecycle** — who creates/destroys entities; `destroy()` vs `dispose()`;
345
- level persistence.
346
- 7. **Priority band** — 0–9 input, 10–19 sim, 20–29 visual sync, 30+ UI.
347
- 8. **VR vs AR vs browser** — behavior per mode; input per mode.
348
- 9. **Audio & feedback** — what plays on which interaction.
349
- 10. **Assets** — Asset Strategy in `references/build-milestones.md`.
350
- 11. **Verify plan** — which CLI assertions will prove it works
351
- (`references/verification.md`).
352
-
353
- Then implement following the best practices and verify with the runtime loop.
354
-
355
- ## Reference Files
356
-
357
- | File | Load when |
358
- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
359
- | `references/api-reference.md` | grounding, coding, reviewing — the API ground truth |
360
- | `references/ideation.md` | Phase 1 — question bank + GAME_SPEC template |
361
- | `references/design-deck.md` | Phase 2 — deck/concept-art briefs + templates |
362
- | `references/grounding.md` | Phase 3 / Quick step 3 — reference CLI + fallbacks + TECH_PLAN template |
363
- | `references/build-milestones.md` | Phases 4–5 — scaffold flags, architecture template, milestone & sub-agent rules, asset strategy |
364
- | `references/verification.md` | Phases 5–7 — runtime verify loop, input simulation, traps |
@@ -1,243 +0,0 @@
1
- # Phases 4–5 Playbook — Architecture & Milestone Build
2
-
3
- ## Scaffolding (new apps)
4
-
5
- Use `@iwsdk/create` — never hand-roll project structure. Infer flags from the
6
- TECH_PLAN, don't hardcode.
7
-
8
- Flag menu (choose one per pair — this is NOT a runnable command):
9
-
10
- ```text
11
- --mode vr | --mode ar # XR apps; or --no-xr for browser-first
12
- --physics | --no-physics
13
- --grabbing | --no-grabbing
14
- --locomotion | --no-locomotion
15
- --scene-understanding | --no-scene-understanding # AR only
16
- --yes # ALWAYS for agents — without it, interactive
17
- # prompts hang AND the feature flags are ignored
18
- ```
19
-
20
- Runnable example (VR game, physics + grabbing, stationary):
21
-
22
- ```bash
23
- npx @iwsdk/create@latest bowling-vr --yes --mode vr --physics --grabbing --no-locomotion
24
- ```
25
-
26
- If `@latest` misbehaves, fall back to the version pinned by the project or the
27
- current release documented on iwsdk.dev.
28
-
29
- Notes:
30
-
31
- - `--no-xr` (the legacy alias for `--target browser`) scaffolds `xr: false`,
32
- browser locomotion, canvas pointer input, and browser interaction support.
33
- Camera look remains intentionally app-owned because first-person, orbit,
34
- editor, and follow cameras need different behavior. For a first-person app,
35
- adapt the pointer-lock pattern in `examples/browser-first/src/mouselook.ts`.
36
- - Dual-runtime (VR + browser testable): scaffold `--mode vr`, then set
37
- `xr: { offer: 'once' }`, `input: { canvasPointerEvents: true }`,
38
- `locomotion: { browserControls: true }`.
39
- - Generated apps come with: `npm run dev` (= `iwsdk dev up --open
40
- --foreground`), a `dev:runtime` script (required by the CLI — never remove
41
- it), the Vite dev plugin, starter src (`index.ts`, `panel.ts`, `robot.ts`),
42
- `public/ui/welcome.uikitml`, and AI configs (CLAUDE.md, skills, MCP
43
- adapters). Delete starter content you don't use (robot etc.) at M1, not M0
44
- — M0 verifies the untouched baseline.
45
- - Existing app instead of scaffold: write an "existing-app delta" section —
46
- current feature flags vs needed, files to add/change.
47
-
48
- ## Asset Strategy
49
-
50
- In priority order:
51
-
52
- 1. **Code-built primitives** (default for MVP): Box/Sphere/Cylinder/Cone/
53
- Torus geometries + `MeshStandardMaterial` from `@iwsdk/core` — zero
54
- sourcing risk, fine for stylized art directions. Compose "models" from
55
- grouped primitives under one `createTransformEntity`.
56
- 2. **Assets already in the project** (`public/gltf/…` from the starter, or
57
- user-provided). List them in the manifest with paths.
58
- 3. **Asset search tooling, if present** — if the environment has an asset
59
- MCP (e.g. a `meta_assets_search`-style tool) or the user offers a source,
60
- download GLB/GLTF into `public/gltf/<name>/` and record license/origin.
61
- 4. **Ask the user** (interactive mode) for must-have hero assets.
62
-
63
- Never invent asset paths; never reference files you haven't created or
64
- verified. All runtime loading goes through `AssetManager` (manifest in
65
- `World.create` for preload, `AssetManager.loadGLTF` for on-demand) — never
66
- raw loaders. Audio: short mp3s; the starter ships `public/audio/chime.mp3`
67
- you can reuse for MVP feedback.
68
-
69
- ## ARCHITECTURE.md template
70
-
71
- ```markdown
72
- # <Title> — Architecture
73
-
74
- ## Scaffold
75
-
76
- Command: <exact @iwsdk/create line, or existing-app delta>
77
-
78
- ## File tree (one system per file; no barrel index)
79
-
80
- src/
81
- index.ts # World.create + registrations + scene setup only
82
- components/<x>.ts # createComponent defs (group related)
83
- systems/<x>.ts # one system per file
84
- public/ui/<panel>.uikitml
85
- public/{gltf,audio,textures}/…
86
-
87
- ## Components
88
-
89
- | Component | Field | Type | Default | Notes |
90
-
91
- ## Systems
92
-
93
- | System | Priority | Queries | Purpose |
94
- <band rule: 0–9 input · 10–19 simulation · 20–29 visual sync · 30+ UI/ambient>
95
-
96
- ## Entity placement (from design/concept/layout.svg)
97
-
98
- | Entity | Components | Position [x,y,z] | Notes |
99
-
100
- ## Globals
101
-
102
- | Key | Type | Purpose |
103
-
104
- ## Milestones
105
-
106
- ### M0 — scaffold renders
107
-
108
- Demo: app serves; scene renders; XR session enters.
109
- Assertions: screenshot non-black; `xr enter` ok; console clean.
110
-
111
- ### M1 — <core mechanic vertical slice>
112
-
113
- Demo: <observable behavior>
114
- Assertions: <specific ecs/screenshot/log checks>
115
-
116
- ### M2…Mn — <one mechanic or surface each>
117
-
118
- ### M-final — all MVP success criteria pass (Phase 6 full run)
119
- ```
120
-
121
- Milestone rules: 3–6 milestones; each independently demoable; core-loop
122
- mechanic first (riskiest feel-work earliest); UI and audio get their own
123
- milestone unless trivial; every spec success criterion mapped to exactly one
124
- milestone's assertions.
125
-
126
- ## Runtime-hitch hardening defaults (build these in from M1)
127
-
128
- The managed dev runtime steps physics on the raw frame delta. Reloads, screenshots,
129
- debug snapshots, backgrounded windows, and CI can all hitch; a single multi-second
130
- step tunnels thin colliders and pops stacked contacts. Defaults that avoid a day of
131
- debugging:
132
-
133
- - **Solid-block static colliders** (0.3 m+ thick), never thin plates; extend
134
- the floor under/behind every play area as a catch surface; add invisible
135
- containment walls so nothing rolls out of the world.
136
- - **Spawn-gate dynamic bodies**: hold spawns until N consecutive stable
137
- frames (e.g. 5 frames under 50 ms) so first steps can't tunnel them.
138
- - **Physics-on-demand for precarious arrangements** (stacks, pyramids,
139
- dominoes): keep them body-less until the moment gameplay needs them
140
- knockable; re-park body-less on reset.
141
- - **Self-healing bounds recovery**: a system that returns escaped dynamics
142
- to their spawn poses.
143
- - **Check physical support when translating design layouts**: a layout
144
- drawn for looks (e.g. cans spaced wide apart) may leave upper items
145
- unsupported — stacking needs contact (can spacing ≈ 2·radius).
146
-
147
- ## The Milestone Loop (Phase 5)
148
-
149
- For each milestone:
150
-
151
- 1. **Brief** — restate demo criterion + assertions (from ARCHITECTURE.md).
152
- 2. **Implement** — following `api-reference.md` best practices. Key habits:
153
- imports from `@iwsdk/core` (never `three` for standard classes — one
154
- Three instance only), `createTransformEntity` (never `scene.add`),
155
- queries + qualify/disqualify subscriptions (never entity arrays), config
156
- signals + `.peek()` in `update()`, `cleanupFuncs` for every subscription,
157
- module-scope scratch vectors (no per-frame allocations).
158
- 3. **Typecheck** — `npx tsc --noEmit`. Fix everything; zero-error baseline
159
- makes later breakage attributable.
160
- 4. **Verify** — run this milestone's assertions live (`verification.md` has
161
- the loop). First milestone verifies the _scaffold before edits_.
162
- 5. **Record** — Milestone Log entry in `design/PIPELINE.md` with evidence
163
- paths. Per-milestone commits (message: `M<n>: <demo criterion>`) are this
164
- pipeline's intended checkpointing — confirm once with the user at Phase 5
165
- start, or record `[ASSUMED] auto-commit milestones` in autonomous mode.
166
- If your harness forbids unrequested commits, skip them and note in
167
- PIPELINE.md that the "revert to last green commit" recovery rung is
168
- unavailable.
169
- 6. Broken? Debug with runtime tools (`ecs pause/step/snapshot/diff`,
170
- `browser logs`) before touching code. Revert to last green commit if a
171
- milestone turns into a swamp; re-plan the milestone instead of thrashing.
172
-
173
- ## Sub-agent rules for build fan-out
174
-
175
- - Parallelize only **genuinely independent modules** (e.g. audio system vs
176
- UI panel vs environment theming). Core-loop code is usually sequential.
177
- - Each sub-agent owns a **disjoint file set**, stated explicitly in its
178
- brief. Nobody but the main agent touches `src/index.ts`, `package.json`,
179
- or `vite.config.ts`.
180
- - Sub-agent brief = paths to GAME_SPEC/TECH_PLAN/ARCHITECTURE + the
181
- **absolute app-root path** (run all commands from there — sub-agent
182
- working directories often reset between calls) + the path to
183
- `references/api-reference.md` with the
184
- instruction to follow its best practices and anti-pattern list + owned
185
- files + its milestone's assertions + "run `npx tsc --noEmit` before
186
- returning; do NOT start dev servers or install packages".
187
- - Sub-agents cannot keep background processes alive — the **main agent owns
188
- the dev server** (`iwsdk dev up/down`), does all runtime verification, and
189
- integrates results.
190
- - After integrating parallel work: typecheck + verify loop before the next
191
- fan-out. Two unverified fan-outs deep is how projects sink.
192
-
193
- ## Common `iwsdk.config.json` world shapes
194
-
195
- ```jsonc
196
- // VR game (stationary or room-scale)
197
- {
198
- "world": {
199
- "xr": { "mode": "vr", "offer": "once" },
200
- "features": {
201
- "physics": true,
202
- "grabbing": true,
203
- "locomotion": false,
204
- "spatialUI": true
205
- }
206
- }
207
- }
208
-
209
- // Dual-runtime VR + browser-testable (recommended for agent-built apps —
210
- // lets you and CI verify in a plain browser tab too)
211
- {
212
- "world": {
213
- "xr": { "mode": "vr", "offer": "once" },
214
- "input": { "canvasPointerEvents": true },
215
- "features": {
216
- "physics": true,
217
- "grabbing": true,
218
- "spatialUI": true,
219
- "locomotion": { "browserControls": true }
220
- }
221
- }
222
- }
223
-
224
- // AR placement app
225
- {
226
- "world": {
227
- "xr": {
228
- "mode": "ar",
229
- "features": { "planeDetection": true, "hitTest": true }
230
- },
231
- "features": {
232
- "locomotion": false,
233
- "sceneUnderstanding": true,
234
- "environmentRaycast": true,
235
- "grabbing": true
236
- }
237
- }
238
- }
239
- ```
240
-
241
- Only enable what the TECH_PLAN grounded — every stray flag is overhead and a
242
- prerequisite trap (locomotion without collision geometry = player falls
243
- through the world). Full option reference: `api-reference.md` §18–19.