@babylonjs-toolkit/agent 1.1.0

package/skills/bt-hero/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: bt-hero
+description: "The Babylon Toolkit Hero Skill is the one-shot builder for bt-design's 3D-Hero-Scroll pattern. Give it a plain-language idea, an existing hero image/video, explicit answers, or any combination — it uses what you gave, asks only the questions you didn't answer, records everything in a repeatable hero brief file, and builds the cinematic scroll-scrubbed hero immediately via bt-design. Composable into the spec workflow by mentioning it inside a bt-spec brief (`Use bt-hero to create ...`). Use when the user wants a 3D scroll hero/landing page (e.g. `bt-hero a mustang with a race driver`)."
+dependencies: bt-design
+---
+
+Turn a plain-language idea — or an existing hero image/video, or any combination — into a cinematic scroll-scrubbed 3D hero page, **in one shot**. This skill owns the **intake** (gathering the creative decisions into a hero brief) and the **build** (via bt-design). The **mechanics** — engine, footage pipeline, calibration, verification — are owned by bt-design's 3D-Hero-Scroll reference (`bt-design/references/3d-hero-scroll.md`); never restate, re-implement, or override them here.
+
+Always adhere to any rules or requirements set out in the project's agent instructions (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md) when responding.
+
+Use the user's message after the skill name as the `arguments`.
+
+---
+
+# Invocation — free-form, any combination
+
+```
+/bt-hero <anything>
+```
+
+`arguments` is free-form. It may contain, in any mix:
+
+- **an idea sentence** — `create a Mustang GT Shelby decked out for racing, with a race driver — desert dawn to red-rock canyon to night dunes, NFS-style game site`
+- **a path to an existing hero image or video** — `@my-hero.jpg`, `@footage/run.mp4`
+- **explicit slot answers** — `HUD 0→220 MPH`, `sweep: hero`, `no jump nav`, `call it SIDEWINDER`
+- **a previously written brief file** — `@_specs/<name>_hero-brief.md` (rebuilds it exactly, asking nothing)
+- **nothing at all** — full interview
+
+Whatever is present is used verbatim; the intake resolves the rest (Step 1). **There are no route keywords and no confirmation gates: `/bt-hero` builds, one shot.** The only permitted stop is the safety stop in Step 3.
+
+**To spec it instead of one-shotting it**, the user invokes bt-spec and mentions this skill in the feature brief — e.g. `/bt-spec Redesign the starter template … Use bt-hero to create a <idea>`. See *Inside the spec loop* at the end. bt-hero never orchestrates bt-spec itself.
+
+---
+
+## The three-tier contract (what gets asked vs. what is decided)
+
+Every piece of a 3D hero scroll belongs to exactly one tier. This is the rule that keeps the intake small and the output deterministic:
+
+- **Tier 1 — Invariants.** How the mechanic works. Owned by bt-design's reference and templates; never asked, never in the brief, never overridable: muted footage, the all-intra scrub encode, blob preload, veiled cuts, film-speed autoplay, cancel semantics, the `HS_CONFIG`/markup syntax, and the **verification protocol — which always runs, without being requested.**
+- **Tier 2 — Defaults.** Sensible values supplied silently; the user may override any of them in their input (recorded in the brief's `Overrides` section): aspect ratio (default 16:9), clip duration (**backend-derived — probe the configured video model's real output; never assume a number**), the 4-beat REVEAL → MOTION → SHIFT → FINALE arc, `sweep: page`, controls all-on (`sweep: page`) / HUD+PLAY (`sweep: hero`), the scroll-length formula, poster = first film frame.
+- **Tier 3 — Creative slots.** The only things intake deals in — the eight slots below.
+
+If it's how the mechanic works → Tier 1. If it's a value that could legitimately differ per project → Tier 2. If it's a creative decision about *this* product → Tier 3.
+
+---
+
+## Step 1 — Intake: use what was given, fill the rest
+
+Parse `arguments` into the eight slots:
+
+1. **The star** — what travels through the film? Car, character, product, creature, the camera itself. *(The only mandatory slot — but an image/video path can satisfy it if its subject is clear.)*
+2. **The look** — the hero anchor: a described look for the star, or the provided image/video path. *(Default: derived from the star.)*
+3. **The journey** — where it starts, what it travels through, how it ends; mapped onto the beat arc — a **beat** is one chapter of the film, one generated clip. Explicit beats, or more/fewer than four, are fine. *(Default: an arc invented to fit the star.)*
+4. **The gauge (HUD)** — the number that climbs as you scroll: speed, depth, altitude, RPM, distance, watts… "None" = no HUD. *(Default: suggested from the star; never invent a metric that doesn't fit — prefer none.)*
+5. **The controls** — PLAY autoplay button (and its label) · TOP/END jump nav — keep or drop. *(Default: per sweep, Tier 2.)*
+6. **The sweep** — after the film: **page** = PLAY glides on through the whole page to the bottom (default) · **hero** = stops at the film's end. 
+7. **The brand & words** — name, tagline, up to ~3 count-up stats, a feature moment, a closing line. *(Default: invented to match the star; never a fixed house style.)*
+8. **Below the journey** — what the rest of the page is. With `sweep: page` it **must be designed to the film's brand and exit tone**, never left as a stock template — and this is precisely **where the scroll-scrubbed hero settles into the full-bleed console home view**: the film is the entrance, the console home (tile wall, edge-anchored HUD/menu, focus states) is the destination it lands into (bt-design's *scroll is the transport* handoff). Build it **full-bleed / full page width** — edge-to-edge console-UI composition per bt-design's *Layout Philosophy — Full-Bleed Console UI*, not a centered fixed-width marketing column (unless the input asks for a contained treatment). *(Default: restyle the page's existing content to the film's exit tone.)*
+
+Then resolve every unfilled slot by exactly one of two paths:
+
+- **Enough to fly** — the input contains a usable star (an idea sentence, or an image/video whose subject is clear): fill every remaining slot from its default, ask **nothing**, and proceed. This is the one-shot path.
+- **Not enough to fly** — empty input, or fragments with no discernible star: ask **only the unanswered questions** — inline, conversationally, as ONE compact numbered list (never one-at-a-time interrogation, never a structured question UI). Tell the user loose prose, partial answers, and "you pick" are all fine. What they answer is used; what they skip gets the default. Then proceed — do not re-confirm.
+
+**Footage feasibility check:** if there is no provided footage AND no image/video generation backend configured (KIE MCP, Higgsfield, built-in generation, …), STOP — this pattern is wrong without footage; recommend a static hero instead (per the bt-design reference intake).
+
+## Step 2 — Write the hero brief (the save file)
+
+Write the resolved slots to `_specs/<feature-name>_hero-brief.md` (create `_specs/` if needed). The brief is the **record**, not a gate: the user never has to touch it, but `/bt-hero @<brief-file>` later must rebuild the same hero with zero questions — that is what makes a hero repeatable, shareable, and tweakable (edit a line, re-run). Record **only Tier 3 answers and explicit Tier 2 overrides** — never Tier 1 mechanics; the brief describes the film, not the engine.
+
+```markdown
+---
+feature: <feature-name>
+type: hero-brief
+status: draft
+---
+
+# Hero Brief — <Title>
+
+## 1. The Star
+<what travels through the film — the one clear subject every asset references>
+
+## 2. Footage Source
+- Mode: generate | provided
+- Anchor: <image-generation prompt for the hero anchor> | <path/to/existing-image-or-video>
+
+## 3. The Journey
+| # | Arc | Beat |
+|---|--------|------|
+| 1 | REVEAL | <how the star is revealed> |
+| 2 | MOTION | <the star in motion> |
+| 3 | SHIFT  | <terrain/scene/lighting change> |
+| 4 | FINALE | <the closing image> |
+
+## 4. HUD
+- Metric: <name> | none
+- Range: 0 → <max> <unit>
+- Segments: <one per beat, named after the beats>
+
+## 5. Controls
+- PLAY: yes ("<label>") | no
+- TOP/END jump nav: yes | no
+
+## 6. Sweep
+- sweep: page | hero
+<!-- Behavioral config — carry VERBATIM into any downstream spec (bt-spec Step 2.6).
+     Never collapse into a route/scope classifier. -->
+
+## 7. Brand & Overlays
+- Name / wordmark: <...>
+- Tagline: <...>
+- Count-up stats: <A · B · C>
+- Feature moment: <...>
+- Closing line: <...>
+- Palette / type direction: <derived from the star unless specified>
+
+## 8. Below the Journey
+<what the rest of the page is; designed to the film's exit tone when sweep: page>
+
+## Tier-2 Overrides
+<only values the user explicitly changed, e.g. "aspect: 21:9" — otherwise "none">
+
+## Defaults In Effect
+<the Tier-2 defaults applied, listed for the record — aspect, beat count, sweep origin (user/default), controls, clip duration source (backend-probed)>
+```
+
+## Step 3 — Build (one shot)
+
+Show the filled brief as a **compact for-the-record report** — which slots came from the user's words, which from defaults — and continue **straight into the build. Do not stop to ask anything.** The user can always interrupt; the brief is on disk if they want to tweak and re-run.
+
+**The one safety stop:** if the build would replace an existing landing page / hero / substantial work that is **not recoverable** (no committed git state covering it), pause, say exactly what would be lost, and wait. If it is committed and recoverable, note that fact and proceed. This is the only stop one-shot mode is allowed.
+
+**Where the hero lands (target resolution — derived, never asked unless ambiguous):**
+- **Default target: the app's home/entry page — the root route's PAGE component, never the router shell.** In **Babylon Toolkit projects** that is **`src/pages/Home.tsx` + `Home.css`** — the Home page is deliberately pulled out of `app.tsx`, and `app.tsx` + `src/routing/**` are a READ-ONLY shell that must not be edited (it already routes `/` to `Home`). In other React (Vite/TypeScript) hosts, resolve the `/` route's element (falling back to `App.tsx` only when the app has no router and the page truly lives there) and replace its existing hero (or its top-of-page block) with the `<HeroScroll>` journey, honoring the reference's sticky constraint (no transformed/overflow-clipped ancestors). For non-React hosts, the entry `index.html`. Slot 8 governs everything below the journey: with `sweep: page` the below-journey content is redesigned to the film's brand and exit tone (an unqualified `/bt-hero` therefore redesigns the whole landing page); with `sweep: hero` nothing below the journey is touched beyond the handoff seam.
+- **The user may name a different target** in their input ("on the /demo route", "in marketing/landing.html") — use it.
+- **No app at all** (empty/near-empty folder): scaffold the minimal host first — default a React + Vite + TypeScript starter, or whatever the user's input names — then build the hero into it, and say that's what happened.
+
+Then build by following bt-design's 3D-Hero-Scroll protocol end-to-end:
+
+1. **Load the sibling bt-design skill, then read its `references/3d-hero-scroll.md` in full — before writing any code.** Two hosts, two mechanisms. Where skills are loaded with a tool (the Babylon Toolkit App Builder platform): call `load_skill('bt-design')`, then fetch the reference with `read_skill_resource` using a path from the resource list the load returns — never a guessed path. Where skills are files on disk (Claude Code): read `bt-design/references/3d-hero-scroll.md` from the same skills directory, `~/.claude/skills/` or the project's `.claude/skills/`. If bt-design is already in your context, skip the load and go straight to the reference. For Babylon Toolkit projects, the project's Agent Reference rule applies as usual (fetch it first if not already in context; if using the KIE MCP servers, its `web-kie-servers.md` sub-document too).
+2. **Copy the drop-in templates** from `bt-design/templates/3d-hero-scroll/` for the host type (React/TS or plain HTML) — never re-implement the engine from memory.
+3. Run the footage pipeline (anchor → chained beats → concat → scrub encode), wire-up, and calibration exactly as the reference specifies, configured from the brief's slots.
+4. **Run the reference's verification protocol (§5) in a real browser. This is unconditional** — the hero is not done until it passes; never report done without it.
+5. If the project keeps a `SPEC.md`, record the shipped hero per the project's working agreement.
+
+When the build lands, set the brief's `status:` to `built`. The brief is the source of truth for the creative slots; the bt-design reference is the source of truth for the mechanics — on any conflict, mechanics win; flag it rather than bending the engine.
+
+---
+
+## Inside the spec loop (composition with bt-spec — bt-hero never initiates this)
+
+When a **bt-spec / bt-plan / bt-execute** run encounters this skill named in its brief (e.g. `/bt-spec Redesign the starter template … **Use bt-hero to create a <idea>**`), bt-hero contributes **intake only** — the spec loop owns the build and verification:
+
+- **bt-spec:** run Steps 1–2 above (intake → hero brief file), then treat the hero brief **plus bt-design's 3D-Hero-Scroll reference** as the sibling-skill pattern per bt-spec's *Step 2.6*: carry the brief's behavioral config (`sweep`, controls) **verbatim** into the feature spec's Functional Requirements, and reference the brief file from the spec. Intake questions (if the brief text isn't "enough to fly") are asked during spec authoring, not deferred.
+- **bt-plan:** normal sibling-skill rules — copy + configure the bt-design templates (never re-implement); every brief behavior becomes a task with observable Acceptance.
+- **bt-execute:** its verifier gates every checkbox, including the sibling-skill behaviors (`sweep`, controls, degradation).
+
+In that flow, do **not** run Step 3's build here — the plan's tasks build it.

package/skills/bt-landing/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: bt-landing
+description: "The Babylon Toolkit Landing Page Skill is the one-shot builder for bt-design's landing page redesign pattern. Give it a plain-language idea, and the skill will generate the landing page, splash screen, preloader and custom overlays."
+dependencies: bt-design
+---
+
+Turn a plain-language idea into a complete redesign of the game's entire frontend shell: the landing page, the splash screen, the preloader, and the custom in-game overlay — all four surfaces as ONE cohesive design.
+
+Always adhere to any rules or requirements set out in the project's agent instructions (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md) when responding.
+
+Use the user's message after the skill name as the `arguments`.
+
+---
+
+# Invocation — design brief
+
+```
+/bt-landing <design brief>
+```
+
+`arguments` is free-form design brief text: a whole new direction ("dark synthwave, neon grid, VHS grain"), a targeted change ("keep the layout, swap the palette to desert sunset and redo the splash"), or nothing at all. **This skill is built to be re-run** — if the last design missed, run it again with a sharper brief; each run REPLACES the previous design completely (unless the brief says to keep parts of it).
+
+- **With a brief:** the brief is the design direction. Honor every specific it names; invent boldly where it is silent.
+- **Without a brief:** derive the direction from the game itself — its title, genre, GameMode, and any art already in the project. Commit to a BOLD aesthetic per the bt-design skill's Design Thinking section.
+- **On a NEW project (the first build turn):** the platform invokes this procedure automatically with the project brief, and pre-loads bt-design alongside it. Same steps, no difference — the prerequisite below is already satisfied, so do not re-load it.
+
+# Prerequisite — load bt-design FIRST, before anything else
+
+**This procedure is built on the bt-design skill's standards and is incomplete without them.** Several steps below defer to bt-design by name (Design Thinking, the full-bleed console UI vocabulary, typography and motion). Those references are instructions to *use* that skill's content, not decoration — designing "to bt-design's standards" without having read them produces generic output that misses the point of running this skill at all.
+
+So, as your FIRST action:
+
+- **If bt-design is already in your context** (a "Skills — already in context" block names it, or you loaded it earlier in this conversation) — proceed straight to Step 0. Do not re-load it.
+- **Otherwise, load it now.** Where skills are loaded with a tool (the Babylon Toolkit App Builder platform), call `load_skill('bt-design')`. Where skills are files on disk (Claude Code), read the sibling `bt-design/SKILL.md` from the same skills directory — `~/.claude/skills/` or the project's `.claude/skills/`.
+
+One load, before you write anything. Loading is cheap; discovering halfway through a redesign that you are missing the standards means redrafting the whole thing.
+
+# Step 0 — discover the project facts (never guess them)
+
+Before writing anything, read what is true in THIS project:
+
+- **The play contract:** find the registered GameMode class (look in `src/scripts/*.ts` for `RegisterClass`, and at `src/babylon/globals.ts`'s registration block). Gameplay is entered ONLY via `navigate('/play', { gameMode: '<RegisteredModeClass>', sceneUrl?, ...selections })` through `useUnifiedNavigation`. The redesign may move, restyle, multiply, or remove play buttons — but this call must survive, exactly, with the project's real class name.
+- **Images on disk:** list what exists under `src/assets/` and `public/` (including `public/assets/generated/`). Import from these or none — never invent an asset path.
+- **The chrome location:** `src/chrome/` — `loading.tsx`, `splash.tsx` + `splash.css`, `overlay.tsx` + `overlay.css`. This folder is a WRITE zone that sits OUTSIDE the read-only `src/babylon`, so its framework imports go through `'../babylon/…'` (e.g. `import GameManager from '../babylon/globals'`) and its bundled logo imports through `'../assets/…'`.
+
+# Step 1 — the design system (`DESIGN.md` at the project root)
+
+The project's committed design direction lives in ONE file: **`DESIGN.md`**, at the project root. Read it before designing anything — this step is what makes ten projects come out looking like ten different games instead of ten flavors of the same one, and what keeps every later edit to THIS project coherent with what already shipped.
+
+- **If `DESIGN.md` has real content** — it IS the design system. Every surface this run touches honors its palette, typography, motion language, and tone; your own instincts defer to it. The brief still outranks it: when the brief names a new direction ("dark synthwave, neon grid, VHS grain"), the new direction wins — and you REWRITE `DESIGN.md` to match as part of this run. The file always records what actually shipped, never what used to be true.
+- **If `DESIGN.md` does not exist, is empty, or is only a placeholder** — **CREATE it now (replacing the placeholder wholesale), BEFORE writing any page or chrome code.** A placeholder is recognizable by content, not just by size: the starter template ships one whose Design Overview says *"There are no special design instructions."* (followed by a "Non-design note" link section that is explicitly not guidance) — that file is EMPTY for this step's purposes, as is any DESIGN.md with blank/boilerplate headings, TODO markers, or no committed values (no hex codes, no font names). Committing the direction to the file first is the point: a direction decided mid-draft drifts back to defaults; a direction written down gets built.
+
+**What `DESIGN.md` must contain** — short, concrete, buildable; a design system, not an essay:
+
+- **Direction** — one sentence naming the aesthetic lens and the tone extreme it commits to (per bt-design's Design Thinking), e.g. "sun-bleached desert-rally poster: grainy, analog, high-noon", "cold orbital-station UI: precise, monochrome, quietly threatening".
+- **Palette** — actual hex values with roles: dominant, surface, 1–2 sharp accents, text tones. Dominant-with-sharp-accents, never a timid evenly-distributed spread.
+- **Typography** — display face and body face BY NAME (distinctive and characterful — never Inter/Roboto/Arial/system fonts).
+- **Motion** — the motion language: what animates, easing character, tempo (e.g. "slow drifts + hard snaps", "spring physics everywhere", "near-still, light flickers only").
+- **Atmosphere** — background and texture rules: grain, gradient meshes, geometry, scanlines, layered transparency — whatever this direction uses instead of flat fills.
+- **Voice** — one line on copy tone for labels and flavor text (a racer barks, a horror game whispers).
+
+**Anti-convergence rule (why this file exists):** you cannot see the other projects this platform has built, so left to instinct you will converge on the same dark-hero-plus-glow-accent design every time. When WRITING a fresh `DESIGN.md`, pick the direction for THIS game and deliberately pass on the first, most obvious treatment for its genre — vary light against dark, loud against restrained, ornate against brutal. If the direction you are about to commit would look at home on any generic game site, it is the wrong one.
+
+# Step 2 — the landing page (`src/pages/Home.tsx` + `Home.css`)
+
+Rewrite BOTH files COMPLETELY, as a landing page designed from scratch for this game. Nothing from the previous page survives unless the brief explicitly says to keep it — no starter hero, no demo buttons, no Vite/React/Babylon links, no footer, no engine/toolkit attribution of any kind. Reach gameplay through the play contract from Step 0.
+
+**FULL-PAGE-WIDTH — the Layout law, checked at the CSS level, not a preference:**
+
+- FORBIDDEN on the page root, the hero, and every top-level section: `max-width` with auto margins (`margin: 0 auto` / `margin-inline: auto`), fixed pixel widths, and any wrapper div whose job is to center a column. `.home { max-width: 1200px; margin: 0 auto }` is THE recurring failure — a website column, not a game frontend.
+- REQUIRED: root and every section `width: 100%`; backgrounds, hero art, and bars touch BOTH viewport edges (`background-size: cover` / `object-fit: cover` — an image's natural width must never decide the page width); UI clusters anchored to the viewport edges, never floated in a centered box.
+- The ONLY permitted `max-width` is a readable measure (~60–75ch) on a TEXT element inside a section that itself runs edge-to-edge.
+- SELF-CHECK before finishing: re-read your Home.css — any structural container with `max-width` + auto margins means the task is failed; fix it first. At 1920px there must be NO empty margin strip on either side of the hero.
+- Responsive from ~320px to ~2560px, no horizontal scrollbar at any width, nothing clipped or overlapping.
+
+Design to the bt-design skill's standards — the ones you loaded in the Prerequisite — **through the lens `DESIGN.md` commits to (Step 1)**: full-bleed console UI, the file's palette and typography, real motion in the file's motion language. `src/pages/` and `src/components/` stay Babylon-free — never import `GameManager` or any Babylon module there; navigation goes through `useUnifiedNavigation`.
+
+# Step 3 — the chrome (`src/chrome/**`): splash, preloader, overlay — ALL THREE, one theme
+
+REDESIGN — do not reskin — all three surfaces to the SAME design language as the landing page (the `DESIGN.md` system from Step 1: typography, palette, motion). Doing only the overlay and stopping is the classic miss: the splash and preloader are the two that ship with the Babylon logo + spinner, so skipping them leaves engine branding in the user's game.
+
+1. **Preloader** — `src/chrome/loading.tsx`. First thing on screen, before the app mounts.
+2. **Splash / loading screen** — `src/chrome/splash.tsx` + `splash.css`. Shown while the 3D scene loads.
+3. **Initial overlay** — `src/chrome/overlay.tsx` + `overlay.css`. The in-game HUD layer — retheme it to match (a title/brand corner, a frame); the full HUD grows later with gameplay.
+
+**The splash must NEVER be derived from the default Babylon splash (centered logo + spinner) — recoloring the default IS the failure.** Think out of the box: design the loading experience as a scene in this game's world, with a progress metaphor native to THIS game — a racer's start-lights counting down, a fuel gauge filling, a platformer's level assembling tile by tile, a warp drive charging — driven by the real progress value, not a bare bar under a logo. Atmosphere worth watching: staggered reveals, ambient motion, flavor text in the game's voice. There is no limit to what you can do here.
+
+**ENGINE CONTRACT — splash element IDs are LAW (STRONGLY ENFORCED, zero exceptions):** the engine's runtime code shows and hides the splash screen and writes its label/status text by looking up these EXACT DOM ids/names — it cannot find renamed elements, and if it can't find them the splash NEVER hides and the scene underneath is never revealed:
+
+- `xbabylonjsSplashScreen` — the main splash screen panel (the root element the engine shows/hides)
+- `babylonjsLoadingDiv` — the loading container element
+- `babylonjsLoadingText` — the loading label element (the engine writes its text content)
+- `babylonjsLoadingDivStyle` — the injected style element for the loading div
+- `xbabylonjsStatusTextDiv` — the status text element (the engine writes its text content)
+
+Any redesign of the splash MUST keep every one of these elements present with its id/name byte-for-byte unchanged — never rename, remove, duplicate, or conditionally unmount them. All the creativity happens AROUND this skeleton: restyle them via CSS that targets these ids, nest new decorative elements inside or beside them, reposition and re-animate them freely — but the ids themselves are engine wiring, exactly like the `"OnLoadProgress"` subscription below. Because the engine writes label text into `babylonjsLoadingText` and `xbabylonjsStatusTextDiv` at runtime, those two must remain real text-bearing elements (style the text; don't replace the element with an image or empty it via JS). SELF-CHECK before finishing: grep the redesigned splash for all five ids — any one missing means the task is FAILED; fix it first.
+
+**LIGHTWEIGHT is a hard constraint, not a style choice.** The splash and preloader ARE the progress info — they exist to COVER loading, so they must paint instantly and show progress immediately. Build their creativity from what renders in the first frame: CSS gradients, keyframe animation, typography, particles, inline SVG, canvas-drawn effects, at most small image assets (a compact logo, a texture tile). Do NOT put multi-megabyte generated hero art, photography, or video on these surfaces — a splash that loads its own heavy image defeats itself. Heavy art belongs on the landing page, behind a styled fallback.
+
+**IMPORTS AND FRAMEWORK WIRING ARE COPIED, NEVER RE-DERIVED (STRONGLY ENFORCED):** you are restyling these files, not re-authoring them. Before you write `splash.tsx` / `overlay.tsx` / `loading.tsx`, READ the file you are about to replace and carry its **entire import block** — and every `GameManager`, `EventBus` and `useUnifiedNavigation` line — across **unchanged, character for character**. Rewrite only markup, styles and copy. Do not retype an import from memory, do not "tidy" it, do not change default vs named form, path, or ordering. If a single import in your new file differs from the original's, you have introduced a build error. Concretely: **`GameManager` is a DEFAULT export** — `import GameManager from '../babylon/globals'`, never `import { GameManager } from '../babylon/globals'` (that exact slip has shipped a project that would not compile). The framework's export shape is not something to infer; it is something to copy. SELF-CHECK before finishing: diff your new import block against the original's — they must be identical.
+
+**Keep ONLY each surface's wiring; replace ALL of the visuals:**
+
+- `loading.tsx` re-exports `babylonLogo` / `spinnerLogo` that `splash.tsx` imports — keep those exports (or update `splash.tsx`'s import to match).
+- `splash.tsx` keeps its `GameManager.EventBus` `"OnLoadProgress"` subscription — that is REAL load progress; drive your metaphor from it.
+- `overlay.tsx` keeps `pointer-events: none` on its container so input reaches the canvas; only genuinely interactive elements get `pointer-events: auto`.
+- Never delete image files from disk (`public/babylon.png` + `public/spinner.png` are framework-required, whatever your design shows).
+- `src/chrome/**` runs in the viewer context, so it MAY import `GameManager`/`EventBus` and `useUnifiedNavigation` — through `'../babylon/…'` paths (Step 0).
+
+The Layout law from Step 2 binds these surfaces too — full-bleed, responsive, edge-to-edge.
+
+# Step 4 — bespoke art (when media generation is available)
+
+If the platform's `generate_image` / `generate_video` tools are available on this turn, use them to make the design beautiful: a hero background, a logo/wordmark, splash-adjacent accents (16:9 for wide heroes, 1:1 for badges/logos; png when alpha matters). Make ALL generate calls FIRST, in ONE parallel round, before writing any files; reference the returned `/assets/generated/…` paths exactly as returned (the one exception to never-invent-an-asset-path) — the renders land in the background, so every surface must look finished while they do (styled color/gradient fallback behind each image, never a blank box). At most ONE short looping hero video, and only if it truly elevates the design — video costs the user hundreds of credits. If the tools are absent, design with CSS + the images on disk instead.
+
+Generated art goes on the LANDING PAGE — never on the splash/preloader (Step 3's lightweight rule). Art direction for every generate call comes from `DESIGN.md` — prompt the renders in its palette and atmosphere so the art belongs to the same design as the CSS around it.
+
+# Step 5 — finish clean
+
+- Zero unresolved imports after the rewrite (every import points at a file that exists).
+- No Toolkit/BabylonJS/engine branding anywhere in the user-facing design.
+- The play contract fires with the project's REAL GameMode class.
+- All four surfaces read as one designed product, not four separate efforts.
+- `DESIGN.md` records the direction that actually shipped — freshly written if it was missing/placeholder, rewritten if the brief redirected it, untouched if this run honored it as-is. A shipped design the file does not describe is a failed Step 1.
+
+State in one short paragraph what design direction you committed to (it is now also in `DESIGN.md`), so the next `/bt-landing` run can be briefed against it.

package/skills/bt-plan/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: bt-plan
+description: "The Babylon Toolkit Plan Skill creates the detailed technical plan for the specified feature spec file. Use when asked to plan or produce implementation tasks for an existing spec. Also supports a Quick Plan mode: when given only a brief (no spec file), it interviews the user to build a mini-spec and plans from that. Always planning-only — it writes the plan file and stops; execution is the separate bt-execute skill."
+allowed-tools: Read, Grep, Glob, Write, WebFetch(domain:raw.githubusercontent.com), Agent, Task
+---
+
+Create a detailed technical implmentation plan for the specified feature spec and save in the _specs folder as `<feature-name>_plan.md`. Always generate implmentation tasks or steps (prefer to call them tasks).
+
+Use the user’s message after the skill name as the `arguments`.
+
+---
+
+# Invocation
+
+```
+/bt-plan <feature-spec> <optional-brief>
+```
+- **`<feature-spec>`** — the feature spec file to create a plan for. This is the *blueprint*.
+- **`<optional-brief>`** — the brief or instructions for generating the plan. This is the *variable*.
+- Never guess a file path or URL. Resolve the arguments as follows:
+  - **Both a spec file and a brief** → normal full planning.
+  - **A spec file only** → normal full planning; the brief defaults to "Generate a detailed implementation plan".
+  - **A brief only, no spec file** → **Quick Plan mode** (see below). Do not ask *for a spec file* — treat the brief as the feature request. But because there is no spec, **interview the user with clarifying questions** to pin down the requirements before finalizing the plan.
+  - **Neither** → ask the user for at least a brief before starting.
+
+Example:
+```
+/bt-plan → @feature_spec.md → "Generate a detailed implementation plan"
+/bt-plan → "add a settings toggle to mute all game audio"   # no spec file → Quick Plan mode, automatically
+```
+
+---
+
+## Quick Plan mode (no feature spec file)
+
+> 🛑 **"Quick" refers ONLY to skipping the spec file — never to skipping steps, and NEVER to executing the plan.**
+> Quick Plan is still **PLANNING MODE**. It ends the moment `_specs/<feature-name>_plan.md` is written. Do **NOT** implement any task, do **NOT** edit application/source files, do **NOT** run builds or tests, and do **NOT** continue into the tasks you just wrote — not even the first one, not even if the tasks look small, obvious, or trivially automatable. The user executes tasks separately with the **bt-execute** skill, deliberately, with a clean context between steps. Auto-executing destroys that workflow.
+
+When invoked with a brief but **no feature spec file**, produce a plan from the brief. Do not stop to ask *for a spec file* — instead **interview the user** to build a **mini-spec** from their answers, then plan from that mini-spec exactly as you would from a real spec file. A spec is largely the product of that Q&A; skipping the file must not mean skipping the questions. Everything the skill would normally read from the feature spec is supplied by sensible defaults only as a **last-resort fallback** for anything left unanswered:
+
+| Normally from the spec | Quick Plan default |
+| --- | --- |
+| Feature name (for `<feature-name>_plan.md`) | Derive a short kebab-case name from the brief (e.g. "mute all game audio" → `mute-game-audio`). |
+| Full feature requirements | Use the brief itself as the requirements, expanded by the Step 1 codebase analysis. |
+| `spec_impact: yes/no` | **Infer** it from the Step 1 analysis: `yes` if the feature adds/changes a system, convention, dependency, or architectural decision; otherwise `no`. |
+| `Project Spec Alignment` section | Derive alignment directly from root `SPEC.md` + the analysis. |
+
+**The one and only difference in Quick Plan mode is operating without a spec file** — the interview produces a mini-spec that stands in for it. Everything else is identical to a normal run: Step 1's comprehensive codebase analysis (including reading root `SPEC.md`) runs in full, the plan document has the same structure, the SPEC.md write-back task is still appended when the inferred `spec_impact` is `yes`, and the run still **STOPS after writing the plan file**. Nothing about Quick Plan grants permission to implement.
+
+Emit one visible status line when this path is taken: `⚡ [bt-plan] Quick Plan mode — no feature spec file; interviewing, then planning from the brief`.
+
+### Finishing a Quick Plan (hard stop)
+
+After writing `_specs/<feature-name>_plan.md`, **STOP**. Your final response must be a short summary of the plan plus the exact next-step hint below — and nothing else. Do not begin T1. Do not offer to "go ahead and start". If the user wants execution, they will invoke bt-execute themselves:
+
+```
+Plan written to _specs/<feature-name>_plan.md
+Run a single task with `bt-execute _specs/<feature-name>_plan.md T1`, or every task with `bt-execute _specs/<feature-name>_plan.md ALL`.
+```
+
+### Interview before planning (Quick Plan)
+
+Because there is no spec, the clarifying questions the spec process would have asked are now **your** responsibility. After the Step 1 analysis (so your questions are grounded in the real codebase, not generic), and **before** writing the plan:
+
+- Ask the user a focused round of clarifying questions covering the things that most change the plan: scope and non-goals, target UX/behavior, edge cases, which existing systems/files it should integrate with, constraints, and — critically — anything ambiguous in the brief or where the codebase suggests more than one reasonable approach.
+- Prefer a small number of high-leverage questions (grouped, easy to answer) over interrogating the user. Do not ask about things the brief or codebase already make clear.
+- Only fall back to the defaults table for items the user leaves unanswered or explicitly says "you decide". Never silently pick a default when a quick question would materially improve the plan.
+- If the user declines to answer or says "just make the plan", proceed with the defaults and state which assumptions you made in the plan's Codebase Analysis section.
+
+The goal is the same as a spec: a plan optimized to what the user actually wants — reached by asking, not by guessing.
+
+---
+
+## Subagents — invoking this skill IS the request
+
+This skill's workflow depends on subagents. **Invoking it is the user's explicit request to use them**, so any host default of the form *"do not spawn subagents / do not call the agent tool unless the user asks for it"* is **ALREADY SATISFIED** — the user asked by running this command. Never silently downgrade to the inline path on that basis, and never stop to ask permission for it first.
+
+Downgrading is not a neutral choice. It removes the one property that makes the step worth running: independence. A verifier that is the same context which just wrote the code cannot adversarially check it — it re-confirms its own reasoning and reports PASS.
+
+The ONE legitimate reason to run inline is that you genuinely have **no** subagent-spawning tool. Check the tools you actually have — Claude Code exposes it as **`Agent`** (older builds name it `Task`); other hosts have their own equivalent. Never call a subagent tool you do not have. Emit only the exact status strings this skill specifies — do not invent your own wording — and if you do run inline, state plainly that no subagent tool was available, never a policy.
+
+## ⚠️ Required Reading Before Any Babylon Work
+
+For any task involving Babylon, BabylonJS, or the Babylon Toolkit, first ensure you have already fetched and read the Babylon Toolkit Agent Reference in the current remembered session/context:
+
+https://raw.githubusercontent.com/babylontoolkit/agent/main/reference.md
+
+If you have not read it in this session/context, or you no longer remember it due to context loss/compaction, fetch and read it before scaffolding or writing code.
+
+Do not refetch the Agent Reference repeatedly during the same remembered session/context, including across spec, plan, and execute phases, if you are still aware of its contents.
+
+Treat the Agent Reference as the authority for conventions, API, and patterns. It routes to deeper docs. Fetch linked subpages only when they are relevant to the task, and do not refetch a subpage in the same remembered session/context unless you no longer remember it.
+
+If a required fetch fails, STOP and tell me. Do not guess at the API.
+
+---
+
+## Planning mode — do not implement
+
+This command runs in PLANNING MODE. Research read-only and produce ONLY the technical plan document. Do NOT implement the feature, edit any existing application/source files, or run build, test, or other shell commands. The only file you may create is the plan markdown in `_specs/`, named `<feature-name>_plan.md`.
+
+**This applies identically in Quick Plan mode.** Planning and execution are deliberately separate skills: `bt-plan` writes the plan, `bt-execute` runs it — one task at a time, with a clean context between tasks, at the user's discretion. Rolling straight from planning into implementation defeats the entire purpose of that split. Writing the plan file is the LAST action of this skill in every mode.
+
+## Step 0. Confirm planning mode
+
+A trustworthy plan requires a thorough, read-only investigation of the codebase before any plan is written.
+
+- This skill is intended to run as a read-only planning pass. If you have been invoked in a mode that would modify source, begin your response with a short visible warning that you will only produce the plan document, then continue.
+- Either way, you MUST still perform the comprehensive analysis in Step 1 with full rigor. Never skip it.
+
+## Step 1. Comprehensive project analysis (REQUIRED before any plan)
+
+This analysis can be **fanned out**. First check whether you actually have a subagent-spawning tool, and **emit one visible status line** so the user can see the path chosen — either `🔀 [bt-plan] subagent tool detected — fanning out analysis to N read-only subagents` or `➡️ [bt-plan] no subagent tool — analyzing sequentially`. If a subagent-spawning tool is available to you (e.g. Claude Code's `Agent`, Lovable's subagent tool, or your host's equivalent — check the tools you actually have; if there is none, or you are unsure, do the analysis yourself sequentially), launch up to 3 parallel **read-only** exploration subagents and divide the eight investigation points below among them (for example: one maps structure/build and dependencies; one extracts the real conventions and the closest existing feature to mirror; one lists integration points and constraints). Each subagent returns concise conclusions — findings and file paths, not file dumps — which you synthesize into the `## Codebase Analysis` section. Exploration subagents need not re-read the Agent Reference. Never call a subagent tool you do not actually have.
+
+Before writing a single implementation step, investigate the actual codebase read-only. This is mandatory — do NOT generate any plan content until this analysis is complete. Read and search the repo to discover, not assume:
+
+1. Read the referenced feature spec in full (from `_specs/` or the file named in `arguments`), **and read the project `SPEC.md` at the repository root in full.** SPEC.md is the source of truth for the durable architecture, systems, conventions, and decisions — the plan MUST conform to it. Note the feature spec's `spec_impact` field and its `Project Spec Alignment` section. **In Quick Plan mode there is no feature spec file** — treat the brief as the feature request, still read root `SPEC.md` in full, and *infer* the `spec_impact` and Project Spec Alignment from the analysis per the Quick Plan defaults table. If the plan you are about to write would conflict with SPEC.md (contradict a decision, cross a system boundary, break a convention), STOP and flag the conflict to the user before writing the plan; do not silently override the project spec.
+2. Map the project: top-level structure, entry points, how the app is built and run (build scripts, test runner, package manifests).
+3. Identify the conventions actually used in this repo: naming, file/folder organization, state management, styling, error handling, testing patterns.
+4. Find the closest existing feature(s) or modules to the one being planned and study how they are implemented — the plan should follow these patterns.
+5. List the concrete integration points the feature will touch: files, modules, APIs, data models, routes, config.
+6. Note relevant dependencies already available (and their versions) versus anything new that would be required.
+7. Capture any constraints from the project's agent instructions (AGENTS.md / CLAUDE.md / .github/copilot-instructions.md) and the feature spec.
+8. If the feature builds on a **sibling-skill pattern** (e.g. bt-design's 3D-Hero-Scroll), read that sub-skill's reference **and its templates**. *(How to read one: where skills are loaded with a tool — the Babylon Toolkit App Builder platform — call `load_skill('<name>')`, then fetch its references and templates with `read_skill_resource` using the paths the load returns, never a guessed path. Where skills are files on disk — Claude Code — read them from the same skills directory, `~/.claude/skills/` or the project's `.claude/skills/`. Skip the load for anything already in your context.)* The plan MUST **copy and configure the sub-skill's template engine — never re-implement it from memory**; re-implementation is exactly how documented behaviors (`sweep`, veiled cuts, the preload gate, HUD auto-hide, graceful degradation) silently get dropped. Turn every behavioral-config requirement the spec records (e.g. `sweep: page`) into a concrete task whose Acceptance asserts that behavior in observable terms.
+
+If the spec or codebase is too ambiguous to analyze responsibly, stop and ask the user rather than guessing.
+
+## Step 2. Write the plan
+
+Only after Step 1 is complete, write the plan markdown to `_specs/` as `<feature-name>_plan.md`. The document MUST open with a `## Codebase Analysis` section that summarizes the findings from Step 1 (cite the real files/modules you inspected) — this is the evidence that the analysis happened. This section MUST include a short **SPEC.md alignment** note: which SPEC.md sections the plan conforms to, and whether the feature is spec-impacting (carry over the feature spec's `spec_impact`, or in Quick Plan mode the value you inferred, and say it was inferred). A plan without a grounded analysis section is invalid; do not produce one.
+
+Then write the implementation as an ordered checklist of discrete tasks. Use GitHub-style checkboxes so progress can be tracked directly in the file — one task per line, numbered T1, T2, T3 … in dependency order, each small enough to be implemented and verified on its own:
+
+```markdown
+## Tasks
+
+- [ ] **T1** — <short task title>
+  - Files: `path/one`, `path/two`
+  - Details: <what to do>
+  - Acceptance: <how to know it is done>
+- [ ] **T2** — <short task title>
+  - Files: `...`
+  - Details: <...>
+  - Acceptance: <...>
+```
+
+When a task implements a **sibling-skill pattern**, its **Acceptance** must assert the skill-defined behavior in observable terms — e.g. for `sweep: page`, "PLAY auto-scrolls through to the document bottom and END jumps there", not merely "the hero renders". A plausible-looking result that dropped a documented behavior must fail acceptance. Prefer copying the sub-skill's template files as an early task (e.g. "T1 — copy + wire the 3D-Hero-Scroll engine") so later tasks only configure it.
+
+### SPEC.md write-back task (required when the feature is spec-impacting)
+
+If the feature is spec-impacting (`spec_impact: yes`, or your analysis found it adds/changes a system, convention, dependency, or architectural decision), the plan MUST end with an explicit final task that updates the project spec, so the write-back is tracked and independently verified like any other task — never left as a soft afterthought:
+
+```markdown
+- [ ] **T<n>** — Update SPEC.md to match what was built
+  - Files: `SPEC.md`
+  - Details: Update the specific SPEC.md section(s) named in the feature spec's Project Spec Alignment — e.g. add/modify the affected Game System, record the new Convention or Decision (with rationale), and add any new Dependency + version. Follow SPEC.md's "How to update this spec" contract: **replace/merge** the current-state sections (Architecture, Game Systems, Conventions, Dependencies) — removing seed placeholders on first real content — and **append** to the Decisions log (never delete; supersede with a newer entry).
+  - Acceptance: SPEC.md accurately describes the architecture/systems/conventions/dependencies as actually implemented by the tasks above; no section contradicts the shipped code; new dependencies are listed.
+```
+
+Make this the LAST task so it captures the true final state. If the feature is genuinely not spec-impacting (`spec_impact: no`), omit this task, but state in the Codebase Analysis that no SPEC.md change is required.
+
+Finally, include this exact `## How to execute this plan` section verbatim in the document so the plan is self-describing no matter how it is later run:
+
+```markdown
+## How to execute this plan
+
+Each task above is a checkbox. To implement:
+- Run a single task with the bt-execute command (e.g. `bt-execute <this-file> T<n>`), run every remaining task in order with `bt-execute <this-file> ALL` (resumable — it skips tasks already checked), or implement the whole plan from a prompt like "implement the plan at <this-file>".
+- Work the tasks top to bottom unless a task notes a different dependency order.
+- When a task is fully implemented and its **Acceptance** criteria are met, mark it complete by editing this file and changing that task's `- [ ]` to `- [x]`.
+- Stop and report if a task cannot be completed. Do NOT check a box for partial, skipped, or unverified work.
+```