@genex-ai/cli-demo 0.93.0 → 0.94.0-dev.249

package/templates/skills/genex-game-director/references/design-contract.md

@@ -1,109 +1,126 @@
 # The design contract — DESIGN.md
 
-Write `DESIGN.md` at the game project root before any rendering code, from the
-template below. Plain game language, readable by the player, committed to the
-game's repo (it travels into remixes). It is a working document, not paperwork:
-it replaces the plan you would otherwise post only in chat, and it is the
-recovery point after any long break — sub-agents read it by path, and so do
-you when a session resumes.
-
-Rules the director enforces about this file:
-
-- Create it right after the scope check, before the concept generation; fill
-  sections as decisions land and keep it current (stale is worse than short).
-- **The Build plan & status section is the compass.** Numbered milestones,
-  each with a status mark, and a `Now:` line naming the current one. Update
-  it the moment a milestone starts or finishes — a milestone is done only
-  when its work reached a `genex preview` (mark it `→ previewed`). After any
-  context compaction or session resume, this section — not memory — says
-  where the build is; continue from `Now:`. When the plan first lands, tell
-  the player in one plain line that it's locked in and lives in `DESIGN.md`.
-- **The Modules table is the delegation contract, and "Built by" is a
-  per-game DECISION, not a default you copy.** While drafting the plan, walk
-  the modules once and decide what can run in parallel and what must stay
-  serial for THIS game — dependencies decide (an arena can be a parallel row
-  in one game and the serial spine of another). Write the call into each row
-  with a one-line reason. When your platform has sub-agents, independent
-  modules default to parallel; building everything serially needs a stated
-  reason. One row per independent lane, and a row's "Owns files" set never
-  overlaps another row's — one writer per file. If a planned-parallel module
-  gets built inline, say why in one line. Verification is never a module
-  row: the milestone smoke pass belongs to the director (the scaffold prompt
-  owns its ceilings).
-- **The Assets table is the budget**: the asset list falls out of Content
-  (enemies → models, an arena → a ground texture, outdoors → a skybox).
-  Status flow per row: `proposed → planned → generating (id) → landed (URL) →
-  wired`. Workers generate only their own rows already marked `planned`; new
-  wants enter as `proposed` for the main agent to approve; the asset shepherd
-  flips statuses and never enqueues. Re-rolls follow the player's notes only.
-  The `Wired?` column exists because "generated but never wired in" is the
-  most common way finished art gets lost — a row isn't done at `landed`.
-  And no eternal `proposed`: at every preview/publish, every `proposed` row
-  gets promoted or cancelled with one visible line — never silently parked.
-- Shrinking any Content line is a question to the player first, never a
-  silent cut.
+`DESIGN.md` is durable project memory, not a startup questionnaire. Create it
+for a new project or substantial multi-step request; for an existing project,
+read it first and update only what the latest request changes. A small focused
+fix may use the existing file without expanding unrelated sections.
+
+Write in plain language the player can read. Commit the file with the project
+so it survives a long pause, context compaction, handoff, and remix.
+
+## Rules
+
+- **Requested outcome is the destination.** Record what the player ultimately
+  asked for. A milestone or step-by-step working mode may change build order,
+  but may not silently shrink that destination.
+- **Working mode describes this run:** `whole coordinated build`, `step by
+  step`, or `focused change`. A clear later request may change the mode and
+  replace `Now:` immediately without replaying discovery.
+- **The Build plan & status section is the compass.** Keep the exact
+  `## Build plan & status` heading and `Now:` marker. Use `▶ in progress`,
+  `✅ → previewed`, `⏸ paused`, and `⬜ open/next` truthfully. A milestone is
+  complete only when its result reached `genex preview`; a pause does not erase
+  the commitment.
+- **Open commitments preserve unfinished promises.** Requested work remains
+  open until completed, explicitly cancelled, or re-scoped by the player.
+  Open work prevents a false claim that the full requested outcome is done,
+  but never blocks an explicit preview or publish request: run the owning flow
+  and say plainly what remains.
+- **Ask only about a real reduction.** If completing a request would require
+  lowering its content, world, or quality target, ask one scope question.
+  Otherwise choose sensible implementation details and continue.
+- **Modules are conditional.** Use the Modules table for a whole coordinated
+  build or another useful parallel split. Dependencies decide parallel versus
+  serial, file ownership never overlaps, and focused work does not create
+  unrelated module rows.
+- **The Assets table is the paid-generation budget and ledger.** Keep the exact
+  status flow `proposed → planned → generating (id) → landed (URL) → wired`.
+  A landed asset is unfinished until wired or visibly cancelled. Preserve
+  generation IDs, permanent URLs, local outputs, and wiring state across
+  compaction.
+- **Code-built procedural assets use their own truthful status flow:**
+  `proposed → planned → building (blockout | detail | material | runtime) →
+  landed (<local TypeScript path>) → wired`. They never invent a provider
+  generation ID. A generated reference image is a separate normal Assets row.
+- Sections are request-driven. Gameplay, content, UI, assets, world,
+  multiplayer, character/animation, tools, modules, and procedural assets
+  appear only when the request or existing project uses them.
+- Preserve every machine-readable marker an invoked pipeline owns, including
+  `HUD lane:`, `Menu video:`, HUD stage IDs and paths, `Player character:`,
+  asset generation IDs/URLs, and wiring state.
+- A private reference attachment is a build input. Do not upload, publish, or
+  commit it without the player's explicit permission.
+
+When the document first lands, tell the player in one plain line that you
+recorded what they asked for in `DESIGN.md` and will keep it current. Do not
+call the plan “locked”; the player may redirect the work at any time.
 
 ## Template
 
 ```markdown
-# <Game name> — Design
+# <Project name> — Design
 
 _Living document — the agent keeps this current; changes land in the log at
 the bottom._
 
-## Concept
-One paragraph: what the game is, what playing it feels like.
-Concept image: <asset URL> (standing — shown <date>; player said
-<yes | nothing — pick stands | change → looped>)
+## Requested outcome
+<The player's final target, in their language. Preserve it until they change
+or explicitly re-scope it.>
 
-## Core loop
-- **You do:** <primary verb — drive, shoot, build…>
+## Build plan & status
+Working mode: <whole coordinated build | step by step | focused change>
+Now: ▶ <number/name of the current milestone or focused task>
+Done when: <one plain, observable condition for the current work>
+1. <milestone> — ✅ → previewed
+2. <milestone> — ▶ in progress (<main agent | sub-agent>)
+3. <milestone> — ⏸ paused (<reason>)
+4. <milestone> — ⬜ open/next
+(Keep only milestones the request earns. Update `Now:` immediately when the
+player redirects the work.)
+
+## Open commitments
+- [ ] <requested promise not yet complete>
+- [ ] <another promise>
+(Remove only when completed; otherwise mark explicitly cancelled or re-scoped
+in Decisions & changes.)
+
+## Core loop (gameplay requests only)
+- **You do:** <primary verb>
 - **To:** <objective>
 - **Under pressure from:** <what pushes back>
-- **You earn:** <reward / progression>
+- **You earn:** <reward/progression, when requested>
 - **You lose when:** <fail state> → **and retry by:** <restart shape>
 
-## Build plan & status
-Now: ▶ <number + name of the milestone in progress>
-1. <milestone> — ✅ → previewed
-2. <milestone> — ▶ in progress (<who: main agent | sub-agent>)
-3. <milestone> — ⬜ (<parallel: sub-agent | serial: main agent — one-line why>)
-(One line per milestone; update on every start/finish; done requires its
-preview. This section is the post-compaction compass — resume from `Now:`.)
-
-## Content (only when the request names plural content or a content genre)
-Every plural noun from the request becomes a countable line:
-- Quests: <N>, chained by <how>
-- Locations: <named list>
-- Enemies: <N kinds, which are bosses>
-- Grows: <levels/gear/abilities> · Earn/spend: <economy>
-- Ten minutes in, I am: <one honest sentence>
-
-## Screens & UI
-Screens: <loader, menu, HUD, pause, win/lose…> · Style brief: <one line>
-References: <2–3 named games> · Menu archetype: <name>
-HUD lane: <sprites (…) | CSS (…, one-line justification)> — mandatory line;
-the concept decides it (director §5) and the preview preflight checks for it
-Menu video: <yes (the default for every game) | declined (player's reason)>
-
-## Assets — the generation plan AND the budget
-| Asset            | Kind        | Status                          | Wired? |
-|------------------|-------------|---------------------------------|--------|
-| Concept + HUD    | image       | landed → <URL>                  | n/a    |
-| <main surface>   | texture     | generating (<id>)               | —      |
-| <hero model>     | model       | planned                         | —      |
-| Background music | music       | planned (one ~90s looping track)| —      |
-| Menu still       | image       | enqueued on concept landing (<id>) | —   |
-| Menu video       | video       | waits: yes / next preview after still / style-only-left | — |
-| Logotype         | image       | enqueued on concept landing (<id>) | —   |
+## Content commitments (only when requested)
+Record only promises present in the request or essential to its stated genre.
+Make each promise countable or otherwise observable:
+- <commitment>: <target and acceptance>
+- <commitment>: <target and acceptance>
+
+## World & scale (only when relevant)
+Intended scale: <request-derived size/shape>
+Terrain/ground: <request-derived form>
+Boundaries: <what the player encounters at the edge>
+Locations: <requested named/countable locations>
+(A requested large/open world is never silently replaced by one small flat
+plane hidden by fog. Do not impose fixed kilometer, chunk, biome, or POI
+defaults.)
+
+## Screens & UI (only when the UI/HUD/menu lane is invoked)
+Screens: <only the requested/required states> · Style brief: <one line>
+HUD lane: <sprites (…) | CSS (…, one-line justification)>
+Menu video: <yes | declined (player's reason) | still fallback (reason)>
+
+## Assets — the generation plan AND budget (only when used)
+| Asset | Kind | Status | Wired? |
+|---|---|---|---|
+| <asset> | <model/image/texture/…> | planned | — |
+| <asset> | <kind> | generating (<id>) | — |
+| <asset> | <kind> | landed → <URL> | yes/no |
 Status flow: proposed → planned → generating (id) → landed (URL) → wired.
-(Optionally note the prompt gist per row — it makes style-change re-rolls one
-command.)
 
 **HUD pipeline state (sprites lane) — keep this current; it is how the
-pipeline survives a context compaction.** One row per stage with its
-generation id / output path, so a resumed session knows exactly where the
-chain stopped and what fires next:
+pipeline survives a context compaction.**
 - Stage-1 mockup: <id → URL>
 - Stage-2 sheet: <id → URL>
 - Cleaned sheet: <id → URL>
@@ -111,100 +128,34 @@ chain stopped and what fires next:
 - Masks: <public/assets/hud/…-mask.png + sidecars>
 - Next stage: <what fires next, one line>
 
-## World & scale
-<Size in numbers if open world; arena bounds otherwise. Streamed terrain? y/n>
-
-## Multiplayer
-<single-player | ongoing world (connect) | fresh matches (matchmake: quorum,
-teams, backfill…)> — and why. Play-button rule: nothing connects before the
-click (when a Play screen exists).
-
-## Modules — the build split
-("Built by" is decided per game while drafting the plan — dependencies
-decide, with a one-line reason per row; the rows below are only a SHAPE.)
-| Module | Owns files | Built by | Done when |
+## Procedural assets (only for editable code-built references)
+| Asset | Reference | Status | Wired? |
 |---|---|---|---|
-| Boot & identity | src/main.ts, src/genex-boot.ts | main agent (only writer of shared boot) | boots, tier wired, initEmbed runs |
-| World/terrain | src/world/** | parallel: sub-agent (no dependency on combat) | walkable, matches World & scale |
-| Quests & dialogue data | src/content/** | parallel: sub-agent (pure data) | counts match Content lines |
-| Enemies/AI | src/enemies/** | serial: main agent (tuned against movement feel) | roster matches Content |
-| HUD chain (style-dependent) | src/ui/** | parallel: sub-agent on concept landing | all screens from Screens & UI |
-
-## Decisions & changes
-- <date> — <one-liner per decision, including anything the player said no or
-  yes to>
-```
-
-## Filled example (a small arena shooter)
-
-```markdown
-# Rustyard — Design
-
-## Concept
-A scrap-robot arena shooter: you skate a magnetized junkyard bot around a
-crusher pit, blasting rival bots into spare parts before the magnet cycle
-pulls everything in. Fast, crunchy, thirty-second lives.
-Concept image: https://assets.genex.technology/g/rustyard/concept.png
-(standing — shown 2026-07-20; player said yes)
-
-## Core loop
-- **You do:** skate + shoot
-- **To:** outscore three rival bots before the magnet cycle ends
-- **Under pressure from:** rivals hunting you; the pit's edges electrify as
-  the cycle counts down
-- **You earn:** scrap for hits → speed/armor pickups mid-round
-- **You lose when:** your bot breaks → **and retry by:** one key, instant
-  respawn, same round
-
-## Build plan & status
-Now: ▶ 3. Rival AI feels dangerous
-1. Arena skeleton + movement — ✅ → previewed
-2. Shooting + scrap scoring — ✅ → previewed
-3. Rival AI feels dangerous — ▶ main agent
-4. HUD sprite swap — ⬜ parallel: sub-agent (concept landed, chain enqueued)
-5. Magnet cycle + pickups — ⬜ parallel: sub-agent (own files, no AI dependency)
-6. Menus, music, publish floors — ⬜
-
-## Screens & UI
-Screens: loader, title menu, HUD (health, scrap, cycle timer), pause,
-win/lose. Style brief: oily metal, warning-stripe accents, stencil type.
-References: <three named AAA games>. Menu archetype: hangar pan.
-HUD lane: sprites (stencil-cut metal meters + riveted scrap counter — ornate
-material chrome, CSS can't pass for it)
-Menu video: yes
-
-## Assets
-| Asset            | Kind    | Status                     | Wired? |
-|------------------|---------|----------------------------|--------|
-| Concept + HUD    | image   | landed → <URL>             | n/a    |
-| Junkyard ground  | texture | landed → <URL>             | yes    |
-| Player bot       | model   | generating (gen_8f2k)      | —      |
-| Rival bot        | model   | planned                    | —      |
-| Overcast sky     | skybox  | landed → <URL>             | yes    |
-| Blaster zap      | sfx     | landed → <URL>             | yes    |
-| Menu still       | image   | landed → <URL>             | —      |
-| Menu video       | video   | waiting (still landed — fires at yes / next preview / style-only-left) | — |
-| Logotype         | image   | generating (gen_9t3m)      | —      |
-
-HUD pipeline state: Stage-1 mockup gen_7a1x → URL · Stage-2 sheet gen_7b2y →
-URL · cleaned gen_7c3z → URL · extracted public/assets/hud/ · masks derived ·
-next: wire masked fills
-
-## World & scale
-One 60×60 m arena, walled; no streaming.
-
-## Multiplayer
-Single-player v1 (rivals are host-free local AI). Revisit after publish.
-
-## Modules
+| <object> | <private local path or separate Genex asset row> | building (blockout) | — |
+Status flow: proposed → planned → building (blockout | detail | material |
+runtime) → landed (<local TypeScript path>) → wired.
+
+## Player character & animation (only when used)
+Player character: <generated character id/status | VRM — explicit reason>
+Character generations: <concept/preview/final IDs and URLs>
+Animation: <catalog actions or generated motion IDs, bindings/manifests,
+validation still open>
+
+## Multiplayer (only when 2+ players share a world)
+<ongoing world (connect) | fresh matches (matchmake: quorum, teams,
+backfill…)> — and why.
+Play-button rule: nothing connects before the click when a Play screen exists.
+Verification still open: <two-identity/netcode evidence>
+
+## Modules (whole coordinated mode or another useful split only)
 | Module | Owns files | Built by | Done when |
 |---|---|---|---|
-| Boot & identity | src/main.ts | main agent (shared boot) | boots, tier wired, initEmbed runs |
-| Arena & pickups | src/world/** | parallel: sub-agent (independent of AI) | walkable, magnet cycle fires |
-| Rival AI | src/enemies/** | serial: main agent (tuned vs player feel) | 3 rivals hunt + shoot |
-| HUD chain | src/ui/** | parallel: sub-agent on concept landing | all 5 screens live |
+| <request-derived stream> | <disjoint paths> | <parallel/serial + reason> | <observable result> |
+
+## Verification evidence
+- <preview URL/date and what it proves>
+- <browser capture, interaction, phone, multiplayer, or owning-skill evidence>
 
 ## Decisions & changes
-- 2026-07-20 — player picked concept candidate 2; asked for "more sparks".
-- 2026-07-20 — sparks added as the ambient-motion loop, not particles-everywhere.
+- <date> — <decision, assumption, explicit cancellation, or player re-scope>
 ```