@iwsdk/create 0.4.1 → 0.5.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.
- package/README.md +103 -41
- package/dist/cli.js +1003 -3418
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
- package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
- package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
- package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
- package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
- package/dist/guidance/claude/.claude/settings.json +19 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/CLAUDE.md +142 -0
- package/dist/guidance/codex/.codex/config.toml +2 -0
- package/dist/guidance/common/AGENTS.md +151 -0
- package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
- package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
- package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
- package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
- package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
- package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
- package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
- package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/gitignore.template +45 -0
- package/dist/template/common/index.html +16 -0
- package/dist/template/common/nvmrc.template +1 -0
- package/dist/template/common/public/audio/chime.mp3 +0 -0
- package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common/public/textures/webxr.png +0 -0
- package/dist/template/common/public/ui/welcome.uikitml +98 -0
- package/dist/template/common/src/assets.ts +54 -0
- package/dist/template/common/src/components.ts +11 -0
- package/dist/template/common/src/index.ts +19 -0
- package/dist/template/common/src/panel.ts +38 -0
- package/dist/template/common/src/robot-component.ts +10 -0
- package/dist/template/common/src/robot.ts +38 -0
- package/dist/template/common/src/vite-env.d.ts +2 -0
- package/dist/template/common/tsconfig.json +15 -0
- package/dist/template/common/vite.config.ts +27 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/gitignore.template +45 -0
- package/dist/template/common-js/index.html +16 -0
- package/dist/template/common-js/nvmrc.template +1 -0
- package/dist/template/common-js/public/audio/chime.mp3 +0 -0
- package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common-js/public/textures/webxr.png +0 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
- package/dist/template/common-js/src/assets.js +45 -0
- package/dist/template/common-js/src/components.js +9 -0
- package/dist/template/common-js/src/index.js +14 -0
- package/dist/template/common-js/src/panel.js +31 -0
- package/dist/template/common-js/src/robot-component.js +8 -0
- package/dist/template/common-js/src/robot.js +37 -0
- package/dist/template/common-js/vite.config.js +25 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
- package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
- package/package.json +23 -17
- package/scripts/verify-release-ready.mjs +76 -0
- package/LICENSE +0 -21
|
@@ -0,0 +1,364 @@
|
|
|
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 |
|