@babylonjs-toolkit/agent 1.1.0

package/skills/bt-prototype/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: bt-prototype
+description: "The Babylon Toolkit Prototype Skill fans out subagents to build N fundamentally-different, jaw-dropping landing-page prototypes for a game theme — each a self-contained frontend candidate for the project's starter template, so the user can pick one and continue building their real front end from it. Every prototype re-imagines the same game world (anchored to attached level/model screenshots) through a different design lens, using advanced visual craft: high-quality 3D, otherworldly animation, exceptional palettes, novel type. Design directions can be seeded from the public motionsites.ai catalog or the awwwards.com showcase (technique harvest, never cloning). Use when the user wants a batch of stunning game landing-page prototypes to choose from (e.g. `bt-prototype --count:10 AAA Need For Speed style racing`)."
+dependencies: bt-design
+---
+
+Build **N radically-different, mind-blowing landing-page prototypes** for a single game theme, as **candidate front-ends** the user will browse and pick one from to continue their real project. This is a **batch, autonomous fan-out**: launch subagents, one per prototype, each self-contained in its own folder. The quality bar is the Original Fable spirit — *go nuts, out-of-the-box, fundamentally different, mind-blowing* — applied to game front-ends: high-quality 3D tactics, otherworldly beautiful animation, exceptional color palettes, novel/interesting type, and whatever else best shows off advanced design skill.
+
+The **mechanics of any 3D-scroll hero** are owned by **bt-hero** / bt-design's 3D-Hero-Scroll reference — never re-implement them here. This skill owns the **batch**: intake, direction spread, fan-out, per-prototype asset pipeline, and the iteration-pass quality gate.
+
+**Load bt-design before you plan the directions.** Every prototype is built to its *Layout Philosophy — Full-Bleed Console UI* and its *scroll is the transport* rule, both named by section below; the standards have to be in context for the batch to share one bar. Where skills are loaded with a tool (the Babylon Toolkit App Builder platform), call `load_skill('bt-design')`, and fetch its bundled references with `read_skill_resource` using the paths the load returns — never a guessed path. Where skills are files on disk (Claude Code), read `bt-design/SKILL.md` from the same skills directory, `~/.claude/skills/` or the project's `.claude/skills/`. If it is already in your context, skip the load. Each subagent needs the standards too — brief them with the direction AND the loaded design standards, since a subagent does not inherit your context.
+
+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
+
+```
+/bt-prototype [--type:html|react] [--count:N] [--motionsites] [--awwwards[:forensic]] [--3d-hero-scroll] <theme> <attached screenshots + notes>
+```
+
+**Flags** (all optional; `--flag:value` or `--flag`):
+
+- **`--type: html | react`** — output kind. `html` = plain HTML/CSS/JS; `react` = `.tsx`/CSS + supporting files. **Default: `html`.**
+- **`--count: N`** — how many prototypes to build. **Default: `10`.**
+- **`--motionsites`** — seed the direction spread from the **public** [motionsites.ai](https://motionsites.ai/) catalog: read it, pick N genuinely-different design directions, re-imagine each for the theme. *(Public catalog only — the paid copy-paste prompts are gated and are never scraped. If the user wants a specific paid one, they download it and hand the text over for adaptation.)*
+- **`--awwwards`** — seed the direction spread from the **public** [awwwards.com](https://www.awwwards.com/) showcase: harvest award-winning sites' **technique vocabulary** (motion system, scroll choreography, layout archetype, WebGL approach) and **palette language**, then re-imagine each fully for the theme. **`--awwwards:forensic`** additionally routes each direction through bt-copycat's live-site reconnaissance for a deeper mechanics study. See *Sourcing directions from awwwards* — including the inspiration-vs-cloning line, which is not optional.
+- **`--3d-hero-scroll`** — the prototypes that suit a cinematic hero are built with **bt-hero**. Because this is a non-interactive batch, **every bt-hero answer must be pre-specified** (in `arguments` or derived up front) so bt-hero never stops to ask mid-batch. See *The 3D-hero-scroll batch rule* below.
+
+`--motionsites` and `--awwwards` may be combined — split the N directions across both sources for a wider spread.
+
+**`<theme>`** — the game theme every prototype re-imagines (e.g. *AAA Need For Speed–style racing*). **The one required input.** If it's missing, ask once, then run.
+
+**Attached screenshots** — level shots, car/character models, environment art. These are the **truth anchor for the game's world** (see *Screenshots are the world anchor*).
+
+**Examples:**
+```
+/bt-prototype --type:react --count:25 --motionsites AAA Need For Speed style racing  [attached: track + car model screenshots]
+```
+```
+/bt-prototype --3d-hero-scroll  Cosmic horror survival game, derelict space station  [attached: level screenshots]
+```
+```
+/bt-prototype --type:react --count:12 --awwwards --motionsites  Neon cyberpunk street-racing  [attached: city + car screenshots]
+```
+
+**To spec it instead of one-shotting the batch**, the user invokes bt-spec and names this skill in the brief — e.g. `/bt-spec Create 25 prototype landing pages for my game using bt-prototype --type:react --count:25 --motionsites <theme>`. See *Inside the spec loop*. bt-prototype never orchestrates bt-spec itself.
+
+---
+
+## ⚠️ Required reading before any build
+
+For any Babylon / BabylonJS / Babylon Toolkit work, ensure the **Agent Reference** is already read in this session/context (fetch `https://raw.githubusercontent.com/babylontoolkit/agent/main/reference.md` first if not; and its `web-kie-servers.md` sub-document if using the KIE MCP servers). If a required fetch fails, STOP and tell the user. Do not refetch what you already remember.
+
+If the project keeps a root **SPEC.md**, read it first and conform to its architecture/conventions; record the shipped prototypes per the project's working agreement when the batch lands.
+
+---
+
+## Screenshots are the world anchor
+
+Every prototype must feel like it belongs to **this** game — same cars, tracks, materials, lighting, mood — while being **fundamentally different from the others** in layout and technique. **Same world, N different lenses on it.**
+
+From the attached screenshots, extract and carry into every prototype: the **palette** (dominant + accent colors sampled from the art), the **environment mood** (biome, time of day, weather, atmosphere), the **hero subject silhouettes** (vehicle/character forms), **materials & lighting** (metallics, emissive, neon, grime, dust), and any **signature motifs**. Generated/borrowed assets must match these anchors, not drift into generic stock. If no screenshots are attached, derive the world from the theme text and say so.
+
+The **difference** between prototypes is in the *design language* — layout, motion system, typographic voice, interaction model, 3D approach — never in contradicting the game's established world.
+
+---
+
+## Step 1 — Parse & intake
+
+1. Read the flags (`--type`, `--count`, `--motionsites`, `--awwwards[:forensic]`, `--3d-hero-scroll`) and the `<theme>`. Apply defaults (`html`, `10`).
+2. **Theme gate:** if no theme is discernible, ask **once** — one short inline question — then proceed. This is the only interactive stop; once the batch starts, it runs autonomously.
+3. Ingest attached screenshots into a world anchor (above). Note the host: React (Vite/TS) vs plain HTML, per `--type` and any existing project.
+4. **Asset-backend check:** the Fable-grade bar assumes asset generation is available. Confirm what's configured — KIE MCP (image/video/Kling), Higgsfield, GPT Image 2 keys, Pinterest source. If none is available, say so and proceed with hand-authored CSS/SVG/WebGL craft rather than silently producing flat pages.
+
+## Step 2 — Compose the direction spread (N genuinely-different lenses)
+
+Before building anything, decide the **N distinct directions** so the batch doesn't converge on one look. Each direction names a different *design language*: layout archetype, motion system, typographic voice, and 3D/animation approach. Spread across techniques — e.g. cinematic 3D scroll, WebGL particle field, editorial/brutalist type, glassmorphic HUD, kinetic-type reveal, immersive full-bleed video, generative/otherworldly motion, retro-future dashboard — pick what fits **this** theme, don't checklist blindly.
+
+- **With `--motionsites`:** fetch the public catalog, pick N cards that are genuinely different from each other (vary category + hero style), and record which catalog entry inspired each direction — for traceability, **not** copying. Re-imagine each fully for the theme.
+- **With `--awwwards`:** see *Sourcing directions from awwwards* below.
+- **With neither:** invent the N directions from the theme + world anchor.
+
+**Full-bleed console UI is the baseline for every direction.** These are **game front-ends**, so each prototype defaults to a **full-page-width, full-viewport, edge-to-edge** layout that feels like a modern console dashboard / AAA game menu (Xbox / PS5), per bt-design's *Layout Philosophy — Full-Bleed Console UI* section — every view owns the whole viewport, full-bleed atmosphere, UI anchored to the edges with a TV-safe gutter, console focus/selection states. The directions still vary the *design language* (motion system, type voice, 3D approach) on top of that shared full-bleed baseline; they do **not** vary down to a centered fixed-width marketing column unless a specific direction deliberately calls for a contained treatment (e.g. an editorial/long-form lens) — and when one does, note it in `_directions.md` and still keep a full-bleed backdrop behind the contained element.
+
+**Full-bleed does not mean a single locked screen — these are landing pages, so scroll stays first-class** (bt-design's *scroll is the transport, not the enemy* rule). Full-viewport views scroll between and through each other, and any **3D-hero-scroll direction plays its cinematic scroll, then settles into the full-bleed console home view at the end** (the sweep-into-console handoff) rather than dead-ending or dropping into a stock template. Compose each view full-bleed; let scroll carry the user between them.
+
+Write the plan to `_prototypes/_directions.md` (id, name, one-line design language, inspiration source + attribution if any, whether it's a 3D-hero-scroll direction). This is the batch's manifest.
+
+## Sourcing directions from awwwards
+
+Awwwards is a **directory of real, live, award-winning websites** — which makes it far richer than a template gallery, and also means it carries obligations a template gallery doesn't.
+
+**What's public and fetchable** (verified): the `/websites/` listing gives each winner's name, **live site URL**, award type (Site of the Day / Developer / Honorable Mention), studio, and date. Each entry page `/sites/<slug>` gives **color-palette swatches**, **technique tags** (e.g. WebGL, Animation, Webflow), categories, jury scores, and a named "Elements" breakdown of specific techniques (e.g. "infinite fullscreen slider").
+
+**Respect robots.txt.** Fetch only `/websites/` and `/sites/<slug>`. Awwwards disallows the search/filter endpoints — never request `/websites/?…` (filtered), `/search-websites`, `/gallery/`, `/tag/`, `/inspiration/search`, `/elements/*`, or `/directory/search/…`. Page politely; don't hammer the site.
+
+### ⚠️ The line: harvest technique, never clone the work
+
+Every awwwards entry is a **real, copyrighted, credited work by a named studio.** Batch-reproducing them is not the goal and is not acceptable output.
+
+| HARVEST (the vocabulary) | NEVER TAKE (the work) |
+| --- | --- |
+| Motion system & scroll choreography *as a technique* | Their layout, verbatim |
+| Layout archetype (split-screen, full-bleed, editorial grid) | Their copy, logo, branding, imagery |
+| WebGL / 3D approach and interaction model | Their assets, fonts, exact palette hexes |
+| Palette *language* (e.g. "monochrome + one hot accent") | Their identity or subject matter |
+| Typographic voice (e.g. "oversized condensed grotesk") | Anything that makes it recognizably *theirs* |
+
+Each direction must be **re-imagined 100% for the user's game world** (the theme + screenshot world anchor). A viewer should recognize the *craft level and technique*, never the source site. **Attribute** each direction's inspiration in `_directions.md` (site name, studio, URL) — for traceability and credit, not because a copy was made.
+
+### Selection
+
+Pick N winners that are genuinely different from one another — vary technique tags, layout archetype, and palette language, not just subject. Prefer entries whose techniques actually serve a **game front-end** (immersive 3D, cinematic scroll, high-motion heroes) over, say, a corporate SaaS layout. Record for each: site name, studio, URL, its technique tags, and the one-line design language you're extracting.
+
+### `--awwwards:forensic` (deeper study, explicit opt-in)
+
+With `:forensic`, each selected direction additionally runs the sibling **bt-copycat** skill's Phase-1 forensic reconnaissance against the **live URL** (real-browser study of scroll choreography, load sequence, animation timing, spatial rhythm) to extract its *mechanics* precisely. The harvest/never-take table still governs the output: bt-copycat's "mechanics are sacred, skin is the variable" split applies, and the **skin is always the user's game world**. This is a knowing opt-in because it is slower, hits real sites, and studies them closely.
+
+If the user wants a genuine faithful rebuild of **one specific** award-winning site, that is not this flag — point them at **`/bt-copycat <url> <re-imagining brief>`**, the deliberate, single-site, user-chosen tool.
+
+## Step 3 — Fan out (one subagent per prototype)
+
+Build the N prototypes **in parallel via subagents** — if a subagent-spawning/workflow tool is available (Claude Code's `Task`/Agent, a Workflow, or the host's equivalent), launch one per prototype (cap concurrency to what the host allows; queue the rest). If no subagent tool is available, build them sequentially yourself. Never call a subagent tool you don't have.
+
+Each prototype subagent gets: its **direction**, the **theme**, the **world anchor** (screenshots + extracted palette/mood/silhouettes), the **`--type`**, and the **asset workflows** available. It must:
+
+1. **Own its folder.** Create `_prototypes/<NN-slug>/` and put **everything self-contained inside it** — markup, styles, scripts, and all generated/downloaded assets. No shared globals; a prototype is copy-out-able on its own.
+2. **Build to the Fable bar for its lens** — advanced 3D tactics, otherworldly animation, exceptional palette, novel type. Not a template with the colors swapped; a distinct, *mind-blowing* execution of that direction for this game. **Full-bleed console UI by default** (bt-design's *Layout Philosophy*): fill the whole viewport edge-to-edge like a console dashboard / game menu, not a centered fixed-width website — unless this direction is the noted contained exception.
+3. **Produce assets** via any mix of the available workflows: Pinterest pulls for reference, **GPT Image 2** for stills, **KIE MCP servers / Higgsfield (Kling, etc.)** for motion/video, hand-authored WebGL/SVG/CSS. All assets stay faithful to the world anchor and live in the prototype's folder.
+4. **3D-hero-scroll directions:** follow *The 3D-hero-scroll batch rule* below.
+5. Run its own **iteration passes** (Step 4) before returning.
+
+## The 3D-hero-scroll batch rule
+
+When `--3d-hero-scroll` is set (or a direction inherently calls for the cinematic hero), that prototype is built via **bt-hero → bt-design's 3D-Hero-Scroll protocol** — copy the templates, run the footage pipeline, calibrate, verify. **But this is a batch: bt-hero must never prompt.** So all of bt-hero's creative slots must be **pre-resolved before the subagent starts** — the star, look/anchor, journey/beats, HUD, controls, sweep, brand/overlays, and below-the-journey are derived from the theme + world anchor + direction and written into a hero brief (`_prototypes/<NN-slug>/_hero-brief.md`) up front. The subagent runs bt-hero's build against that brief with **zero questions** ("enough to fly," always). If a slot genuinely can't be resolved without the user, resolve it with a sensible default and note it — do **not** pause the batch.
+
+## Step 4 — Iteration passes (the quality gate)
+
+No prototype is "ok'd" until it has had **at least three iteration passes**. An iteration pass is a **fine-toothed-comb review** of the finished prototype looking for design problems and **opportunities to improve/complexify** — spacing/rhythm, contrast, motion timing and easing, hierarchy, type detail, asset quality, responsiveness, the small touches that separate stunning from fine — followed by actually applying the improvements. Each pass should measurably raise the craft, not just rubber-stamp. Record a one-line note per pass in the prototype's folder (`_notes.md`) so the passes are auditable, not assumed.
+
+For prototypes with real interaction (3D scroll, WebGL, video heroes), a pass **must** include a real-browser check (chrome-devtools): it loads, the hero/animation runs, nothing errors, it degrades gracefully. A prototype that looks right in source but breaks in the browser fails the pass.
+
+## Step 5 — Report & record
+
+When the batch lands, report a compact index: each prototype's id, direction/design-language, folder path, whether it's a 3D-hero-scroll build, and its inspiration source (if `--motionsites`). Point the user at how to preview them and remind them the purpose is to **pick one as the starter front-end** — adoption means porting the chosen prototype into **`src/pages/Home.tsx` + `Home.css`** (the landing page's real home; `app.tsx` + `src/routing/**` are a read-only shell and never receive the design), following the bt-landing skill's rules. If the project keeps `SPEC.md`, record the batch per the project's working agreement.
+
+---
+
+## Inside the spec loop (composition with bt-spec — bt-prototype never initiates this)
+
+When a **bt-spec / bt-plan / bt-execute** run encounters this skill named in its brief (e.g. `/bt-spec Create 25 prototype landing pages … **using bt-prototype --count:25 --motionsites <theme>**`), bt-prototype contributes **intake + direction spread**; the spec loop owns the batch build and verification:
+
+- **bt-spec:** run Steps 1–2 (intake → the direction manifest `_directions.md`), then treat that manifest **plus bt-design's 3D-Hero-Scroll reference** (for any `--3d-hero-scroll` directions) as the sibling-skill pattern per bt-spec's *Step 2.6*: each direction becomes a feature-spec requirement, and the 3D-hero brief's behavioral config (`sweep`, controls) is carried **verbatim**. Pre-resolve all bt-hero slots at spec time so nothing prompts later.
+- **bt-plan:** normal sibling-skill rules — each prototype is a task; copy + configure bt-design templates for 3D-hero directions (never re-implement); Acceptance is observable ("prototype NN renders its direction, self-contained in its folder, passes 3 iteration passes").
+- **bt-execute:** its verifier gates each prototype, including the 3D-hero-scroll behaviors and the iteration-pass evidence.
+
+In that flow, do **not** run Step 3's fan-out here — the plan's tasks build the batch.

package/skills/bt-spec/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: bt-spec
+description: "The Babylon Toolkit Spec Skill creates a feature spec file and branch from a short idea. Use when asked to spec out, plan, or scaffold a new feature."
+allowed-tools: Read, Grep, Glob, Write, WebFetch(domain:raw.githubusercontent.com), Bash(git switch:*), Agent, Task
+---
+
+You are helping to spin up a new feature spec for this application, from a short idea provided in the user input below. 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
+
+```
+/bt-spec <feature-brief>
+```
+- **`<feature-brief>`** — the short idea or brief for the feature spec. This is the *variable*.
+- If missing, ask for it before starting. Never guess a file path or URL.
+
+Example:
+```
+/bt-spec → "Generate a detailed implementation plan for the new feature"
+```
+
+---
+
+## 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.
+
+---
+
+## ⚠️ The Project Specification (SPEC.md) — read before drafting
+
+The project's **SPEC.md** at the repository root is the source of truth for the project: it defines the durable architecture, game systems, conventions, and decisions. **Read it before drafting any feature spec.**
+
+- Align the feature idea to the existing architecture, systems, and conventions in SPEC.md. The feature spec you produce must be derived from and constrained by SPEC.md.
+- **If the feature idea conflicts with SPEC.md** (contradicts an architectural decision, a system boundary, or a convention), STOP and flag the conflict to the user before writing the spec. Do not silently override the project spec.
+- **Classify the feature's `spec_impact`:** it is `yes` if implementing the feature would add or change a game system, a convention, a dependency, or an architectural decision recorded in SPEC.md — otherwise `no`. This drives whether the plan will include a SPEC.md write-back task, so classify honestly.
+- **If SPEC.md is missing or is still a stub with no real content, STOP and ask the user FIRST — before generating the feature spec — whether to create a default project `SPEC.md` from the fallback scaffold** (the scaffold is defined in *Validate The Project Spec* under Step 4). Do not draft the feature spec until they answer.
+  - **If the user says yes:** create `SPEC.md` at the repository root from the fallback scaffold, then continue — treat the newly written SPEC.md as the source of truth and align the feature spec to it (this is the normal path; the project now has a spec to grow).
+  - **If the user says no:** continue **without** a project-level SPEC.md, and record this note in the feature spec: `"No project SPEC.md content yet — following existing codebase conventions."`
+
+---
+
+## Planning mode — do not implement
+
+This command runs in PLANNING MODE. Research read-only and produce ONLY the spec document (plus, where git is available, its branch). Do NOT implement the feature, edit any existing application/source files, or run build, test, or other shell commands. The only files you may create are the feature spec markdown described below and — **only if the user opts in** when the project `SPEC.md` is missing/stub (see *The Project Specification* above) — the project `SPEC.md` written from the fallback scaffold. Creating that `SPEC.md` from the scaffold is the sole exception to "do not edit other files", and only with the user's yes.
+
+## High level behavior
+
+Your job will be to turn the user input above into:
+
+- A human friendly feature title in kebab-case (e.g. new-heist-form)
+- A safe branch name (e.g. project/feature/new-heist-form) — always RECORDED in the spec header; actually cut only where git is available
+- A detailed markdown spec file under the _specs/ directory
+
+Then save the spec file to disk and print a short summary of what you did.
+
+## Step 1. Check the working tree (only where git is available)
+
+**Git is optional for this skill, and its absence is normal — not a degraded environment.** Some hosts
+run this skill in a sandbox with no git binary and a restricted shell (for example the Babylon Toolkit
+App Builder, where the project's real branching and commits are performed by the host against the
+user's own repository, not from inside the sandbox). The spec file is the deliverable; the branch is a
+convenience where the tooling happens to support it.
+
+- **If git is available:** check the current branch and stop if the working directory has uncommitted,
+  unstaged, or untracked files. Tell the user to commit or stash before proceeding.
+- **If git is NOT available** (no binary, or the shell refuses the command): skip this step entirely and
+  continue to Step 2. Do not abort, do not ask the user to install anything, and do not report it as a
+  problem or a limitation — record the branch name as spec metadata as described in Step 3 and carry on.
+  Say nothing about git in your summary; the user asked for a spec, not a branch.
+
+## Step 2. Parse the arguments
+
+From `arguments`, extract:
+
+1. `feature_title`  
+   - A short, human readable title in Title Case.  
+   - Example: "Card Component for Dashboard Stats".
+
+2. `feature_slug`  
+   - A git safe slug.  
+   - Rules:  
+     - Lowercase 
+     - Kebab-case 
+     - Only `a-z`, `0-9` and `-`  
+     - Replace spaces and punctuation with `-`  
+     - Collapse multiple `-` into one  
+     - Trim `-` from start and end  
+     - Maximum length 40 characters  
+   - Example: `card-component` or `card-component-dashboard`.
+
+3. `branch_name`  
+   - Format: `project/feature/<feature_slug>`  
+   - Example: `project/feature/card-component`.
+
+If you cannot infer a sensible `feature_title` and `feature_slug`, ask the user to clarify instead of guessing.
+
+## Step 2.4 Research the codebase read-only (fan out where possible)
+
+A spec that guesses at the codebase produces a plan that guesses at the codebase. Before drafting any
+requirement, investigate read-only: the project `SPEC.md` (in full), `DESIGN.md` where the feature has a
+UI, any sibling-skill protocol the feature is built on (Step 2.6), the closest existing feature to
+mirror, the real conventions in use, and the concrete integration points the feature will touch.
+
+This research can be **fanned out**. Emit one visible status line so the user sees the path chosen —
+either `🔀 [bt-spec] subagent tool detected — fanning out research to N read-only subagents` or
+`➡️ [bt-spec] no subagent tool — researching sequentially`. If a subagent-spawning tool is available
+(see *Subagents — invoking this skill IS the request* above), launch up to 3 **read-only** subagents and
+divide the targets among them — for example: one reads `SPEC.md` + `DESIGN.md` and reports the sections
+this feature must conform to; one finds the closest existing feature and extracts the conventions to
+mirror; one lists integration points, constraints, and existing dependencies. Each returns concise
+conclusions — findings and file paths, not file dumps — which you synthesize yourself.
+
+Two hard rules, because this skill is planning-only: every subagent is **read-only** (it may read,
+search and report; it may NOT edit files, write files, or run build/test/shell commands), and **you**
+write the spec — a subagent never drafts spec content. Research subagents need not re-read the Agent
+Reference. If anything they report contradicts `SPEC.md`, that is a finding to raise with the user, not
+something to silently resolve.
+
+## Step 2.5 Apply the project design system (DESIGN.md)
+
+This project's design system is defined in the `DESIGN.md` file at the repository root. `DESIGN.md` is the single source of truth for all design decisions — do NOT pull styling from Figma, external links, or invent your own values. (Figma may be used in a separate process to author `DESIGN.md`, but specs reference `DESIGN.md`, never Figma directly.)
+
+If the feature has any UI or visual surface:
+
+1. Read `DESIGN.md`. If it is missing or has no real design system yet, record this note in the spec and continue: `"No DESIGN.md design system found — follow the existing UI conventions already in the codebase."`
+2. Identify the parts of the design system relevant to this feature and cite them, by name, in the spec — for example:
+   - Layout and spacing scale
+   - Typography tokens (font family, size, weight)
+   - Color tokens and semantic roles (primary, surface, border, error, etc.)
+   - Border radius, shadows, elevation
+   - Shared components, icons, buttons and inputs the feature should reuse
+3. Summarise these as 3 to 8 concise bullet points that reference the `DESIGN.md` tokens and components by name, so implementation stays consistent with the system.
+
+If the feature is purely non-visual (no UI), note that no design system tokens apply and continue.
+
+## Step 2.6 Honor sibling-skill patterns (read the sub-skill's protocol)
+
+Some features are built on a deterministic pattern **owned by a sibling skill** — e.g. bt-design's **3D-Hero-Scroll** (scroll-scrubbed cinematic hero), bt-atlas texture variants, bt-convert conversions. When the feature matches such a pattern, that sub-skill — not your own paraphrase of the brief — is the authority for how the feature must behave. Skipping this step is how a documented behavior silently disappears from the spec.
+
+1. **Detect the pattern — or an explicitly named builder skill.** Decide whether the feature matches a sibling-skill pattern. If it does, **read that sub-skill's SKILL.md and the relevant reference BEFORE drafting Functional Requirements.** *(How to read a sibling skill: where skills are loaded with a tool — the Babylon Toolkit App Builder platform — call `load_skill('<name>')`, then fetch its bundled references with `read_skill_resource` using the paths the load returns, never a guessed path. Where skills are files on disk — Claude Code — read `<name>/SKILL.md` and its `references/` from the same skills directory, `~/.claude/skills/` or the project's `.claude/skills/`. Skip the load for anything already in your context; on a tool host the per-response load budget is small, so spend it on the skills this feature actually needs.)* (For 3D-scroll / scroll-scrubbed / cinematic-hero features, read bt-design's `references/3d-hero-scroll.md`.) **If the brief explicitly names a sibling _builder_ skill** — e.g. "…**using bt-hero** to create …" or "…**using bt-prototype** --count:25 …" — read that skill's SKILL.md and run **its own intake step** (bt-hero Steps 1–2 → a hero brief; bt-prototype Steps 1–2 → the `_directions.md` manifest), then fold that output into this spec. The builder contributes intake only; this spec loop owns the build and verification. Resolve any of the builder's intake questions here, at spec time, so nothing prompts downstream.
+2. **Capture the required behavioral config verbatim.** Record the pattern's required config/behavior as explicit Functional Requirements, using the sub-skill's **own names and defaults, unchanged** — do not rename, omit, or invent defaults. Example (3D-Hero-Scroll): `sweep: page|hero`, default **`page`** — PLAY glides through to the document bottom and END jumps there, and the whole landing page is swept and must share the film's design system. If the sub-skill specifies a default, the spec inherits it unless the brief explicitly overrides it (state the override and why).
+3. ⚠️ **Never collapse a sub-skill's behavioral setting into a route/DOM-scope classifier.** A feature's *scope* (which route or surface it targets) is a **different axis** from a sub-skill's *behavioral options*. Keep them separate and name the behavior with the sub-skill's own term. Concretely: a 3D-hero's `sweep` is NOT "which page the feature lives on" — record `sweep` as its own requirement; do **not** fold it under a "reach / scope / routing" heading, where it will be lost or inverted.
+4. **List optional controls in/out.** Record which of the pattern's optional controls/features are included or omitted (with the sub-skill's defaults), so the plan and execute phases can verify them.
+
+If the feature matches no sibling-skill pattern, note that and continue.
+
+## Step 3. Record the branch name (and switch to it where git is available)
+
+The `branch_name` derived from the `arguments` is **always** recorded in the spec header, so the plan
+and execute phases have a stable name to refer to regardless of host.
+
+- **If git is available:** before making any content, switch to a new branch using that name. If the name
+  is already taken, append a version number: e.g. `project/feature/card-component-01`
+- **If git is NOT available:** the recorded name in the spec header IS the deliverable for this step. This
+  is the expected outcome on such hosts — do not mention it as missing, unavailable, or a fallback.
+
+## Step 4. Draft the spec content
+
+Create a markdown spec document that Plan mode can use directly and save it in the _specs folder as `<feature_slug>_spec.md`. Use the exact structure as defined in the feature spec template file @FEATURE.md located at the project root. The template includes a required `spec_impact` header field and a `Project Spec Alignment` section — fill both in from your SPEC.md read above (cite the SPEC.md sections the feature relies on, describe how it fits the architecture, and for `spec_impact: yes` state exactly what will change in SPEC.md and in which section). Do not add technical implementation details such as code examples. If the feature spec template file is missing, create a new feature spec file with the following sections:
+```
+# Feature Spec Template
+
+> This is the template bt-spec uses to author `_specs/<feature_slug>_spec.md`.
+> Copy this structure verbatim. A feature spec is derived **from** and constrained
+> **by** the project [SPEC.md](SPEC.md) — the `Project Spec Alignment` section and
+> the `spec_impact` header field are required, not optional.
+
+---
+
+# Spec for <feature-name>
+
+branch: project/feature/<feature-name>
+design_system: DESIGN.md
+spec_impact: <yes|no>   # yes if this feature adds/changes a system, convention, dependency, or architectural decision in SPEC.md
+
+## Summary
+<one-paragraph description of the feature>
+
+## Project Spec Alignment (from SPEC.md — REQUIRED)
+- SPEC.md sections this feature relies on or must conform to: <cite by name, e.g. "Game Systems › Inventory", "Conventions">
+- How this feature fits the existing architecture: <...>
+- **spec_impact = yes** → what will change in SPEC.md and which section(s): <architecture / system / convention / decision / dependency + the new state>
+- **spec_impact = no** → confirm this feature introduces no architectural, system, convention, or dependency change.
+- Conflicts with SPEC.md (if any): <describe; these must be resolved/flagged before planning>
+
+## Functional Requirements
+- ...
+<!-- If this feature is built on a sibling-skill pattern (e.g. bt-design
+     3D-Hero-Scroll), record that pattern's REQUIRED behavioral config here as
+     explicit requirements, using the sub-skill's own names + defaults verbatim
+     (e.g. `sweep: page` — PLAY/END sweep to the document bottom). Keep such
+     behavior SEPARATE from the feature's route/DOM scope; never fold a
+     behavioral setting under a "reach/scope/routing" heading. (See bt-spec
+     Step 2.6.) -->
+
+## Design System Reference (from DESIGN.md, only if the feature has UI)
+- DESIGN.md tokens/components this feature uses: ...
+- Layout / spacing / typography notes: ...
+- Key visual constraints: ...
+- Sibling-skill behavioral config (if any), e.g. 3D-Hero-Scroll `sweep`: ...
+
+## Possible Edge Cases
+- ...
+
+## Acceptance Criteria
+- ...
+
+## Open Questions
+- ...
+
+## Testing Guidelines
+Create a test file(s) in the ./tests folder for the new feature, and create meaningful tests for the following cases, without going too heavy:
+- ...
+```
+
+### Validate The Project Spec
+
+This is the **fallback scaffold** referenced by the prompt-first decision in *The Project Specification* (top of this skill). When the project's **SPEC.md** is missing or is still a stub and **the user answered yes**, write exactly this content to `SPEC.md` at the repository root *before* drafting the feature spec, then align the feature to it. If the user answered **no**, skip creating it and record the "No project SPEC.md content yet…" note in the feature spec instead. The default project spec scaffold:
+```
+# Project Spec
+
+> **This is the source of truth for the project.** It defines the durable,
+> cross-feature architecture, systems, conventions, and decisions. Feature specs
+> in `_specs/` are derived **from** and constrained **by** this document.
+>
+> **Read this before speccing, planning, or executing any feature.** If a request
+> conflicts with this spec, flag it before proceeding. When a landed feature
+> changes anything below, update this file to match what was built.
+
+---
+
+## Architecture & Module Layout  _(current-state — replace/merge)_
+_Top-level structure, entry points, how the app is built and run. How modules are
+organized and depend on each other._
+
+- _(Seed placeholder — replaced on first real content.)_
+
+## Game Systems  _(current-state — replace/merge)_
+_Each system, its responsibility, and its boundaries (what it owns vs. what it
+delegates). One subsection per system._
+
+- _(Seed placeholder — replaced on first real content.)_
+
+## Conventions  _(current-state — replace/merge)_
+_Naming, file/folder organization, script-component patterns, state management,
+styling, error handling, testing patterns actually used in this repo._
+
+- Prefer ESM imports throughout.
+- Use Babylon Toolkit script component patterns rather than ad-hoc BabylonJS wiring, per the Agent Reference.
+- Keep game systems modular.
+
+## Decisions  _(append-only log)_
+_Architectural decisions and their rationale — the "why", so future features don't
+relitigate settled choices. Append new entries; supersede rather than delete._
+
+- _(Record decisions here as they are made, newest last.)_
+
+## Dependencies  _(current-state — replace/merge)_
+_Runtime and build dependencies with versions, and why each is here. Nothing new
+lands without an entry._
+
+- **BabylonJS** — engine.
+- **Babylon Toolkit** — Unity-style script components, scene management.
+
+---
+
+## How to update this spec
+
+This file is an initial **seed scaffold**. Sections carry a mode tag in their
+heading — follow it exactly when writing back:
+
+- **`(current-state — replace/merge)`** — Architecture, Game Systems, Conventions,
+  Dependencies. These describe *what is true now*. On the first real content,
+  **remove the seed placeholder** and write the actual content. On later features,
+  **merge/replace** so the section keeps matching the shipped code — never leave
+  stale text, never let it contradict reality.
+- **`(append-only log)`** — Decisions. **Append** a new entry (newest last);
+  preserve history. To reverse a past decision, add a new entry that supersedes it
+  — do not delete the old one.
+
+Add a new Game System as its own subsection under Game Systems. Record every new
+dependency (with version + why) under Dependencies as part of the task that
+introduces it.
+
+## How this spec stays true (the spec-driven loop)
+
+- **bt-spec (read down):** reads this file, aligns the feature to it, flags
+  conflicts, and records a `spec_impact` classification in the feature spec.
+- **bt-plan (read down):** treats this file as a required analysis input; the plan
+  must conform. For spec-impacting features it appends an explicit
+  **`Update SPEC.md`** task so the write-back is tracked.
+- **bt-execute (write up):** reads this file before each task, flags any divergence
+  from reality, and runs the `Update SPEC.md` task through the same verifier gate
+  as every other task — this file is never allowed to silently drift.
+```
+
+## Step 5. Final output to the user
+
+After the file is saved, respond to the user with a short summary in this exact format:
+
+Branch: <branch_name>
+Spec file: _specs/<feature_slug>_spec.md
+Title: <feature_title>
+
+Do not repeat the full spec in the chat output unless the user explicitly asks to see it. The main goal is to save the spec file and report where it lives and what branch name to use.