| name | yume-design |
| description | Run the Yume text-to-game pipeline. Orchestrates 7 specialist skills (yume-game-designer → game-planner → systems-designer → content-designer → asset-designer → qa-tester, plus tech-director on demand) with optional user-approval gates. Skills load into orchestrator context (no subagent spawn — Tier 2.6 architecture). Flags - `--autonomous` skips approval gates and runs end-to-end. `--plan-only` stops after the planning phases (GDD + world-plan) so the user can review before any JSON is committed. `--with-assets` invokes AI-gen pipeline. `--style=pixel-art|low-poly-3d|ascii` art-style hint. `--name=<slug>` game folder name. |
/yume-design — text-to-game pipeline
Turn a prose game description into a runnable Yume game.
REVISION BANNER 2026-05-16 (ADR 0009 revision, tasks #109 + #110).
The file layout in this skill below still mentions the legacy
world/rules.json + game/goals.json split in several places.
Treat these as the CURRENT shape:
world/rules/*.json (directory of feature modules) — all rule
authoring goes here. Filename prefix (01_, 02_, ...) sets load
order. Engine globs + concatenates alpha-sorted.- Single-file
world/rules.json still works for small games
(chess, sokoban). Pick whichever fits the game's size.
game/goals.json is GONE. Its content moves to
world/rules/13_transitions.json (boot/day-boundary/win/lose
signal-rules) + world/rules/14_objectives.json (HUD-text
updates + tutorial overlays).- Declarative win:/lose: blocks live in
hud.json (HUD-driven
overlay; the engine evaluates them per-frame and shows the
win/lose panel automatically).
game/flow.json (multi-level progression) is unchanged.- Skill ownership: yume-systems-designer writes all rule files.
yume-game-rules-designer's scope shrinks to declarative HUD
win/lose blocks + game/flow.json. See each skill's own header.
Usage
/yume-design <prose description of the game>
/yume-design "a farming sim where moonlight grows crops faster" --style=pixel-art --name=<your-game>
/yume-design "a roguelike where vampires steal HP from light sources" --with-assets
/yume-design "explore a fortified river town and collect 5 lost relics" --scene --with-assets
Args (parsed from the user's prompt after /yume-design):
<prose> — the game description (free-form). Required.--style=<value> — pixel-art / low-poly-3d / ascii / realistic.
Defaults to user-stated preference in prose, else pixel-art.--name=<slug> — game folder name. Defaults to a slug derived from
the prose (auto-suggest: ask user to confirm).--scene — generate a 3D world for the game first (the World
layer, via compose_world): a semantic-map + heightmap-driven map
with biome ground, water, and placed environment props. The game's
mechanics then layer ONTO that world. Default: no generated world
(the game owns its own flat scene). Needs OPENAI_API_KEY — if
absent, the flag is DROPPED (graceful degrade to a flat code-draw
scene + a warning), never a crash. See Phase 0 step 2a.--with-assets — after the game is built, auto-run the AI asset
pipeline (tools.yume_assetgen) to replace code-draw visuals with
generated textures + meshes. Default: skip (code-draw fallback).
Needs an image key + TRIPO_API_KEY — if absent, the flag is
DROPPED (graceful degrade to code-draw visuals + a warning).
No API keys? You still get a game. The no-flag path is fully
key-free (code-drawn shapes). --scene/--with-assets are
best-effort: present keys → used; absent → dropped with a warning,
and you fall back to the code-draw game. Nothing hard-fails for lack
of a key (Phase 0 step 2a).
The three layers (ADR 0067). A game is World (the 3D stage,
--scene) + Game (mechanics, always) + Assets (the look,
--with-assets). Each layer writes only its own files, so they
compose without clobbering. Default (no flags) = a key-free
code-drawn single-player game. See the per-layer file-ownership
table in Phase W below.
What I do when invoked
I am the orchestrator. I do NOT write game content directly — I
load the 6 specialist skills in .claude/skills/yume-<role>/ one at a
time and execute their role instructions in my own (the orchestrator's)
context.
Skills, not subagents (Tier 2.6 architecture). Earlier versions
of this pipeline spawned subagents via Agent(subagent_type=...).
Some org auth policies disable subscription-backed subagent spawns
(organization has disabled Claude subscription access), which
breaks the pipeline. Skills load into the orchestrator's main
context — same role prompts, no auth boundary, lower latency, fewer
moving parts.
Autonomous mode. If the user passes --autonomous in the prompt,
skip the per-phase user-approval gates and walk all phases in one
shot, surfacing only on hard failure or at the final wrap. Default
(no flag) is interactive: pause after each phase for user approval.
Phase 0 — Setup (no skill load)
-
Parse the prose + flags. Detect --autonomous, --name=<slug>,
--style=<value>, --scene, --with-assets.
-
Auto-suggest a <name> slug from the prose (a 1-2 syllable
shorthand of the genre + theme) if --name= not given.
2a. API-key precheck (graceful degrade — NO crash without keys).
The gen flags need keys; the DEFAULT path needs none. Before
running, check env and drop any flag whose key is missing, with a
clear one-line warning — never hard-fail into a mid-pipeline crash:
| Flag | Needs | If missing |
|---|
--scene | OPENAI_API_KEY (gpt-image-2 for the semantic map + heightmap) | DROP --scene → the game uses a flat code-draw scene. Warn: "no OPENAI_API_KEY → skipping --scene (flat code-draw scene). Set the key for a generated 3D world." (Exception: a scene already on disk → keep --scene and run compose_scene --skip-gen to reuse the maps key-free.) |
--with-assets | an image key (OPENAI_API_KEY or GEMINI_API_KEY) and TRIPO_API_KEY (meshes) | DROP --with-assets → keep code-draw visuals. Warn: "no image/Tripo keys → skipping --with-assets (code-draw visuals). Set OPENAI_API_KEY + TRIPO_API_KEY for generated textures + meshes." |
The no-flag path is always key-free (code-drawn shapes via
data/shapes.json) — that is the fallback. Degrading to it must be
loud (the warning) but non-fatal. In interactive mode, surface the
degrade in the plan and let the user re-run with keys; autonomous
proceeds degraded.
-
State the plan: paths, phases (Phase W only if --scene SURVIVED
the precheck; Phase A only if --with-assets survived),
autonomous-or-interactive mode.
-
Interactive mode: wait for explicit go-ahead. Autonomous: proceed.
Phase W — World (only if --scene) — the 3D stage
Run BEFORE the game phases so the mechanics can layer onto a real
world. This is the World layer of ADR 0067 — the 3D scene PLUS the
default walk "play mode" (player + camera + movement). It reuses the
/yume-create-scene pipeline's compose_world (scene) and
compose_shell (the walkable explorer shell). See
.claude/skills/yume-create-scene/SKILL.md § "Used as the World layer."
-
Author the class catalog (the one LLM-in-the-loop step): invoke
yume-scene-class-catalog on the prose → /tmp/_class_catalog.json.
The catalog's scene brief is derived from the game's SETTING in the
prose (the town, the dungeon, the forest), NOT its mechanics. The
game's collectibles / NPCs / interactables are GAME-layer entities —
keep them OUT of the catalog.
-
Run the scene pipeline (image gen → semantic map → heightmap →
extract → scene + walk shell):
python3 -m tools.visual_layout.compose_scene <name> \
--catalog /tmp/_class_catalog.json
This runs compose_world (scene: scene.json ground/water,
entities/auto_gen.json defs + flat placements) + compose_shell
(the walk play mode: player player_input_anchor tagged player,
third-person camera written into scene.json, world/rules/10–13_shell_*
walk/jump/sprint, ui/input.json, the .tscn). Add --skip-gen to
reuse existing maps; do NOT pass --assets (Phase A runs
yume_assetgen once, after the game's asset-designer).
Non-walk game (shooter, top-down RTS): pass --no-shell instead,
and the game's systems-designer authors its own movement+camera.
-
The World layer now owns these files — the Game phases below must
NOT overwrite them (this is the entire anti-clobber contract):
| File | Owner | Game phases must… |
|---|
scene.json | World (compose_world ground/lighting + compose_shell camera) | NOT write it |
entities/auto_gen.json | World (map prop defs + placements) | NOT touch; game writes a separate entities/<slug>.json |
entities/player.json, world_clock.json, cameras.json, shell_singletons.json | World (shell) | NOT overwrite; REUSE the player-tagged player |
world/rules/10–13_shell_*.json | World (shell walk/camera) | leave for walk games; REPLACE only for non-walk movement |
screens.json | World (shell H-help overlay: controls + world.objective, toggled by toggle_help/H via global_inputs) | a game with its OWN screens APPENDS to screens + keeps global_inputs — don't overwrite. Set world_state.objective (via world/state.json {"state":{...}} or state_set target=world) so it shows in help. |
world/road_graph.json | World | read-only |
assets/{layouts,textures}/ | World | read-only |
ui/input.json | World (shell) | EXTEND (add game actions), don't clobber the shell's |
No levels/, game/flow.json, or world/state.json — compose_world
is scene-only + flat (ADR 0067). The engine globs entities/*.json +
world/rules/*.json and merges by id, so the game's
entities/<slug>.json (collectibles/NPCs/game-state singleton) and
extra world/rules/*.json (mechanics) spawn INTO the flat scene for
free — provided ids are disjoint from the map's <class>_NNN ids and
the shell's singleton ids.
-
No --scene? Skip this phase entirely; the game owns a flat
scene as before (the content/asset phases write scene.json normally;
game/flow.json only if multi-level).
Phase 0a — Multi-level detection
Read the GDD's "Level progression" or "Levels" section if present.
If the prose describes ≥2 levels (sokoban with N puzzles, TD with
multi-map campaign, RPG town→dungeon, roguelike floors), this is a
multi-level game and the file layout uses the levels/ directory
pattern (ADR 0006):
data/<name>/
├── scene.json # camera, tick, renderer
├── world/state.json # initial world_state
├── world/rules/*.json # how the world works + scoring + transitions + objectives (chain modules)
├── hud.json # declarative win:/lose: blocks live here (per ADR 0009 revision)
├── game/flow.json # level order + start
├── ui/hud.json + ui/input.json + ui/strings.json
├── audio/cues.json # @cues.X mappings
├── variants/<mode>.json # OPTIONAL difficulty/mode
├── entities/ # PERSISTENT defs (multi-level)
└── levels/
├── level_1/entities.json # level-scoped instances
├── level_1/rules.json # OPTIONAL per-level rules
├── level_2/...
└── ...
State the multi-level decision to the user (interactive) or proceed
(autonomous):
LEVELS DETECTED: 8 (sokoban-style puzzles)
- Pattern: levels/ directory + game/flow.json
- Persistent entities: player (carries cleared/score across levels)
- Per-level: walls, boxes, goals (cleared on transition)
- Transition rule: contact(player, goal) → transition_level "next"
Single-level games (most arena shooters, single-zone sims) use the
flat layout — no game/flow.json, no levels/ directory; entities and
rules live at the root.
Phase 0b — Layout planning (cross-cutting decision)
Before invoking any specialist skill, decide the file layout. All
downstream skills follow this plan; no skill-by-skill drift. Decisions
based on prose-estimated scope:
Entity layout:
- Small (estimated ≤ 8 entity defs): single
entities.json
- Medium (8-20 defs):
entities/ directory, one file per def, plus
entities/zz_instances.json for placements
- Large (20+ defs):
entities/ directory grouped by category subfolder
(e.g. entities/world/, entities/creatures/, entities/plants/),
with one entities/zz_instances.json at the root
Rules layout (ADR 0009 + revision 2026-05-16 — feature-module split):
world/rules/*.json — feature-module directory holding ALL rule
chains (motion, AI, contact, decay, lifecycle, scoring, transitions,
objectives, tutorials). yume-systems-designer owns all of these.
Engine globs the dir alpha-sorted at load. Per-feature splitting
(01_movement.json, 02_inventory.json, 13_transitions.json,
14_objectives.json, etc.) keeps each file scannable.- Smaller games (chess, sokoban) can still use single-file
world/rules.json — the engine accepts both layouts.
- Declarative
win: / lose: blocks live in hud.json — engine
evaluates per-frame and auto-shows the win/lose overlay.
game/flow.json — multi-level progression (level order + start).
yume-game-rules-designer owns this in its narrowed scope.- Per-level rules:
levels/<name>/rules.json (or levels/<name>/rules/*.json
directory form).
Always:
scene.json is single-file at root (camera/tick/renderer config)world/state.json holds initial world_state valuesui/hud.json + ui/input.json + ui/strings.json for UI layeraudio/cues.json maps semantic events → sound names (@-prefix
refs in rules)- New shapes append to
data/shapes.json root, NOT per-game
- Per-game scene
.tscn is a 12-line template stub (auto-written
by orchestrator at Phase 5; see template body in this doc)
- Universal
scenes/play.tscn works for any game via --game= arg
State the chosen layout to the user (interactive) or proceed with it
(autonomous). Pass layout to each skill in its arg payload so it
writes files in the right structure:
LAYOUT CHOSEN:
- entity_layout: medium → entities/ directory
- rules: world/rules/*.json feature modules (systems-designer)
- flow: game/flow.json (game-rules-designer, multi-level only)
- assets: code-draw shapes appended to data/shapes.json root
This step prevents per-skill drift — content-designer and asset-designer
both follow the orchestrator's chosen plan instead of inventing their own.
Phase 0c — Genre detection + dispatch
After layout planning, classify the prose's genre. Genre dispatch
unlocks strictest-layer specialist skills (genre-specific
designer + reviewer) that catch concerns the generic skills can't
see (FPS movement feel, TD path geometry, sim resource cycles, etc.).
Match keywords from the one-line pitch:
| Genre | Triggers | Designer | Reviewer |
|---|
| shooter | "shooter", "fps", "doom", "arena shooter", "twin-stick", "first-person" | yume-shooter-designer | yume-shooter-reviewer |
| merchant | "merchant", "shopkeeper", "item shop", "an item-shop merchant game", "trader", "a merchant-adventurer game" | yume-merchant-designer | yume-merchant-reviewer |
| racing | "racing", "kart", "drift", "lap", "time-attack", "combat racer" | yume-racing-designer | (future: yume-racing-reviewer) |
| td | "tower defense", "td", "lane defense", "wave defense" | (future: yume-td-designer) | (future: yume-td-reviewer) |
| sim | "sim", "ecology", "farming", "life sim", "harvest" | (future) | (future) |
| puzzle | "puzzle", "sokoban", "match", "block-push", "tile" | (future) | (future) |
| roguelike | "roguelike", "dungeon crawler", "rogue-lite" | (future) | (future) |
| (no match) | fallback | yume-game-designer only | yume-game-reviewer only |
State the detected genre to the user (interactive) or proceed
(autonomous):
GENRE DETECTED: shooter
- Specialist designer: yume-shooter-designer (FPS-specific GDD sections)
- Specialist reviewer: yume-shooter-reviewer (10 FPS axes, strictest)
- Generic floor: yume-game-designer + yume-game-reviewer (13 axes) still apply
If no genre matches, only generic skills run.
Phase 1 — game-designer (prose → GDD)
- Invoke the specialist designer if genre detected, else generic:
- Shooter:
Skill(skill="yume-shooter-designer", args=<prose + name>)
- Merchant:
Skill(skill="yume-merchant-designer", args=<prose + name>)
- Racing:
Skill(skill="yume-racing-designer", args=<prose + name>)
- TD/sim/puzzle/roguelike (when those skills land): same shape
- No genre:
Skill(skill="yume-game-designer", args=<prose + name>)
- Specialist designers PRODUCE the full GDD (generic MDA scaffolding
- genre-specific sections). They internalize the generic
game-designer's framework so they don't drop generic concerns.
- Output:
docs/games/<name>/GDD.md.
- Interactive: show GDD summary, ask "Approve? (y / edit / reject)".
Autonomous: proceed to Phase 1b.
Phase 1b — Generic game-reviewer (13-axis floor)
7a. Invoke yume-game-reviewer skill (always — the generic floor).
Skill(skill="yume-game-reviewer", args=<GDD path>).
7b. Skill produces docs/games/<name>/review.md with verdict.
7c. Verdict handling:
- accept → proceed to Phase 1b.5 (genre-strict reviewer if any).
- revise → re-invoke designer with revision requests. Loop
max 3 cycles. After 3, surface to user.
- reject → surface to user; pipeline halts.
7d. Why: generic 13-axis catches shallow GDDs at cheapest iteration
point. Genre-strict review runs after this passes.
Phase 1b.5 — Genre-strict reviewer (strictest gate)
7e. If a genre was detected in Phase 0c AND a specialist reviewer
exists, invoke it:
- Shooter: Skill(skill="yume-shooter-reviewer", args=<GDD path>)
7f. Specialist reviewer APPENDS a genre-review section to
review.md (doesn't replace the generic findings).
7g. Verdict handling — same as Phase 1b but stricter:
- accept → proceed to Phase 1c.
- revise → re-invoke specialist designer with genre-specific
revision requests. Loop max 3 cycles.
- reject → surface to user. Genre-claim mismatch is the most
common reject reason ("you said FPS but the GDD lacks N FPS
requirements").
7h. Why: generic floor + genre ceiling = both must accept. Genre
reviewer is the strictest layer: empirically, doomarena3d v2 +
v2.5 needed reactive fixes (walk speed, diagonal, blocks_motion,
weapons) that an FPS-aware reviewer would have caught at GDD
review.
Phase 1c — game-planner (GDD → world plan)
8a. Invoke yume-game-planner skill. Tool:
Skill(skill="yume-game-planner", args=<GDD path>).
8b. Skill produces docs/games/<name>/world-plan.md — named NPCs,
items, plants, events, day-1 onboarding flow.
8c. Interactive: show plan summary (cast count, item categories, key
events) — ask user to approve.
Autonomous: proceed.
Phase 1d — level-designer (spatial layout)
9a. Invoke yume-level-designer skill. Tool:
Skill(skill="yume-level-designer", args=<GDD + world-plan paths>).
9b. Skill produces docs/games/<name>/level-design.md — concrete
coordinates + rationale per placement (path, choke points, tower
slots, spawn zones, decoration).
9c. Interactive: show layout summary (dimensions, key placements) —
ask user to approve.
Autonomous: proceed.
9d. If --plan-only flag was set: stop here. Final summary lists
GDD path + review path + world-plan path + level-design path.
Tell user to re-invoke with --resume.
The plan + level-design are the single sources of truth for downstream:
- systems-designer references named entities + path lengths when
sketching rules (radius / cooldown / speed numbers).
- content-designer wires named entities into JSON at the EXACT
coordinates from level-design.md (no ad-hoc placement decisions).
- asset-designer reads visual hints + applies consistent style.
Phase 1e — domain-specialist designers (CONDITIONAL)
Three optional design specialists run BEFORE systems/content/game-rules
authors any JSON. Each is gated on whether the GDD signals its domain.
Order matters: combining-logic first (recipe table feeds economy),
then economy (pricing curves feed content placement), then story
(beats reference both).
Phase 1e.1 — combining-logic-designer (CONDITIONAL)
Trigger: GDD mentions any of crafting / alchemy / breeding / cooking /
chemistry / spell-combinations / key-combos / recipe / merge.
10a. Invoke yume-combining-logic-designer skill.
10b. Produces docs/games/<name>/combining-design.md — recipe table,
discovery model, yield rules, failure modes, primitive mapping.
10c. Interactive: show summary (recipe count, discovery model, key
risks). Autonomous: proceed.
If trigger absent: skip this phase entirely.
Phase 1e.2 — economy-designer (CONDITIONAL)
Trigger: GDD mentions any of currency / score / shop / trade /
progression / unlock / cost / level-up / XP / income / merchant.
Most non-trivial games trigger this.
11a. Invoke yume-economy-designer skill (read combining-design.md
too if Phase 1e.1 ran — recipe yields feed economy).
11b. Produces docs/games/<name>/economy-design.md — sources/sinks,
conversion ratios, currency design, pricing curves, pacing math,
adversarial-poke checklist.
11c. Interactive: show summary (resource count, currency layers, key
adversarial findings). Autonomous: proceed.
If trigger absent (pure simulation, no progression): skip.
Phase 1e.3 — story-planner (CONDITIONAL)
Trigger: GDD mentions any of campaign / acts / arc / story / NPC
evolution / scripted events / branches / endings / chronicle. Pure
sandboxes / arcades skip.
12a. Invoke yume-story-planner skill (reads level-design + economy
if present — beats often gate on level transitions or resource
thresholds).
12b. Produces docs/games/<name>/story-design.md — beats, character
arcs, act structure, branches, primitive mapping.
12c. Interactive: show summary (story shape, beat count, key risks).
Autonomous: proceed.
If trigger absent: skip.
Phase 2 — systems-designer (GDD → all rules)
Per ADR 0009 revision 2026-05-16, this skill now writes ALL rule
chains under world/rules/*.json (feature modules): motion, AI,
contact, decay, lifecycle, scoring, transitions, objectives, tutorial
overlays. Previously split with yume-game-rules-designer — scope
absorbed here.
- Invoke
yume-systems-designer skill. Tool:
Skill(skill="yume-systems-designer", args=<GDD path + resolved questions>).
- Skill produces
docs/games/<name>/rules-sketch.md + world/rules/*.json
feature modules under the data folder. May propose ADRs if new
primitives needed.
- If ADR proposed → escalate to tech-director:
Skill(skill="yume-tech-director", args=<ADR path + diff>).
On rejection → re-invoke systems-designer without the new primitive.
On accept → ADR status set to accepted, proceed.
- Interactive: show sketch + ADRs, ask approval. Autonomous: proceed.
Phase 3 — content-designer (entities + initial state)
Per ADR 0009 narrowed scope: this skill ONLY writes entity defs + initial
placements + world state. Rules are NOT written here.
- Invoke
yume-content-designer skill. Tool:
Skill(skill="yume-content-designer", args=<GDD + world-plan + level-design + sketch>).
- Skill writes
entities/*.json (defs + placements), world/state.json
(initial world state), levels/<name>/entities.json (multi-level
games), under data/demo_<name>/.
- Interactive: show file summary, ask approval. Autonomous: proceed.
--scene ownership guard (ADR 0067). When Phase W ran (walk
shell), the player + camera + movement already exist from the
shell (player_input_anchor, tagged player) — do NOT author a
player; the game's contact/interaction rules query the player tag.
Write the game's OWN entities (collectibles, NPCs, interactables, a
game_state singleton) with their initial_instances to
entities/<slug>.json — NOT to entities/auto_gen.json or the
shell's entities/{player,world_clock,cameras,shell_singletons}.json.
Put game-global state in the game_state singleton (not
world/state.json). Entity ids must not collide with the map's
<class>_NNN ids or the shell singleton ids.
Phase 3.5 — game-rules-designer (HUD win/lose + flow) — NARROWED scope
Post-ADR-0009-revision (2026-05-16), this phase covers only the
declarative win/lose surface + multi-level progression. Rule
authoring (scoring/transitions/objectives) moved to Phase 2's
yume-systems-designer scope.
- Invoke
yume-game-rules-designer skill. Tool:
Skill(skill="yume-game-rules-designer", args=<GDD + world/rules/*.json>).
- Skill writes:
- Declarative
win: / lose: blocks in hud.json (engine
evaluates per-frame, auto-shows the overlay).
game/flow.json (level sequence + on-all-complete) for
multi-level games.
For sandbox sims (no goals, single-level), this phase is SKIPPED.
- Interactive: show decisions, ask approval. Autonomous: proceed.
--scene ownership guard (ADR 0067). When Phase W ran, do NOT
write game/flow.json — the World owns it (a single level_default).
Win/lose blocks in hud.json are fine (game-owned); just reference
level_default as the level id. A --scene game is single-level by
construction (the generated world is one map).
Phase 4 — asset-designer (visuals + audio + UI strings)
Per ADR 0009 expanded scope: also writes audio/cues.json + ui/strings.json.
- Invoke
yume-asset-designer skill. Tool:
Skill(skill="yume-asset-designer", args=<GDD + entities path + style flag>).
- Skill updates
entity.visual.* + audio.* fields, writes scene.json,
hud.json, audio/cues.json (semantic event → sound mapping),
ui/strings.json (localizable HUD text), and asset_gen.json if
--with-assets.
- Interactive: show visual + audio + string choices, ask approval. Autonomous: proceed.
--scene ownership guard (ADR 0067). When Phase W ran, do NOT
write scene.json — the World owns the camera/lighting/ground/tick.
Set entity.visual.* on the game's own defs only; the map props keep
their World-authored visuals. (If the game needs a specific camera
mode the world didn't set, surface it — don't silently overwrite the
world's scene.json.)
Phase A — Assets (only if --with-assets) — generate the look
Run AFTER the asset-designer wrote asset_gen.json (which scans the
defs' *_prompt fields) and BEFORE QA, so the visual gate captures the
generated look, not the code-draw placeholders. This is the Assets
layer of ADR 0067 — it patches visual.* on existing defs in place;
it writes no new content files.
python3 -m tools.yume_assetgen <name>
- Generates textures (gpt-image-2 / nanobanana) + meshes (tripo3d) per
the manifest, writes them under
assets/generated/, and patches each
def's visual.albedo_texture / visual.model_3d to the new
res://… paths. (--dry-run to preview the plan; --init to scaffold
a manifest.) See tools/yume_assetgen/README.md.
- Generated assets use versioned filenames and are never deleted
or committed (gitignored, paid artifacts — memory:
never-delete / never-commit). Iterate by adding a variant suffix.
- After patching, the NEXT phase must
--headless --import before
capture (Godot errors "No loader found" otherwise — memory:
always-import-after-new-assets).
- No
--with-assets? Skip; the code-draw visuals from Phase 4 ship
as-is (the key-free default path).
Phase 5 — qa-tester (verify)
-
Write the scene file scenes/<name>_2d.tscn (or <name>_3d.tscn)
from the standard 12-line template. WorldBoot auto-mounts every
Director Node (GameShell, ScreenFlow, LightingDirector, …) — the
.tscn just pins data_root, picks the renderer, and places a Camera.
2D template (replace only <name>):
[gd_scene load_steps=2 format=3]
[ext_resource type="Script" path="res://scripts/engine/core/world.gd" id="1"]
[node name="World" type="Node"]
script = ExtResource("1")
data_root = "res://data/demo_<name>"
auto_start = true
verbose = true
renderer_script = "res://scripts/renderer_2d/entity_sprite_2d.gd"
[node name="Camera2D" type="Camera2D" parent="."]
position = Vector2(0, 0)
3D template (replace <name> + tune Camera3D position/projection):
[gd_scene load_steps=2 format=3]
[ext_resource type="Script" path="res://scripts/engine/core/world.gd" id="1"]
[node name="World" type="Node"]
script = ExtResource("1")
data_root = "res://data/demo_<name>"
auto_start = true
verbose = true
renderer_script = "res://scripts/renderer_3d/entity_mesh_3d.gd"
[node name="Camera3D" type="Camera3D" parent="."]
position = Vector3(0, 12, 0)
rotation = Vector3(-1.5708, 0, 0)
No GameShell / ScreenFlow / LightingDirector mounts in the .tscn —
WorldBoot creates them at boot. Sky/Sun/WorldEnvironment driven by
scene.json's lighting block via LightingDirector. Ground plane
driven by scene.json's ground.mesh block via GroundRenderer.
The universal scenes/play.tscn --game=<name> works for any 2D
game without writing a per-game .tscn; generating a per-game stub
is a UX shortcut (godot --path . scenes/<name>_2d.tscn directly).
-
Invoke yume-qa-tester skill. Tool:
Skill(skill="yume-qa-tester", args=<data folder + scene path + GDD path>).
-
Skill runs Godot headless, drains env.error_buffer, produces
docs/games/<name>/qa-report.md.
20b. Tier 2.6s — Game-specific scenario tests: content-designer should
have authored data/demo_<name>/tests.json covering 3-5 core verbs
(input → state change → expected cascade). qa-tester runs:
godot --headless scenes/scenario_test.tscn -- --game=demo_<name>.
These JSON tests catch behavior bugs the smoke test misses (e.g.,
"bullet doesn't move after fire"). Schema in
scripts/engine/scenario_runner.gd header.
-
Tier 2.6r — Visual QA: after headless smoke test, qa-tester
runs the game windowed with auto-capture (scripts/play.sh <name> --capture), reads the captured PNG, and verifies:
- Entities visible at expected scale (not collapsed at origin)
- Layout matches design intent (rings/scatters render correctly)
- HUD renders + lighting applied
- No obvious clipping / camera-in-wall / wrong-mode-for-content
Findings appended to qa-report.md alongside cascade verification.
21b. Tier 2.6r ext — Stage-driven Visual QA (2026-05-06): the
spawn-frame capture only catches static rendering bugs. For
GAMEPLAY-state bugs (HUD bindings only populate after sales,
haggle screen renders mid-customer-arrival, dungeon layout only
after East Gate transition), drive scripted input first then
capture. Use
--capture-input='action,seconds;...' flag on
capture_runner; the engine holds each action for the given
duration via Input.action_press/release then captures. Per-
system VQA examples in yume-qa-tester SKILL § "Stage-driven
visual QA". qa-tester captures both spawn-frame AND at least
one stage-frame for each major game system (movement, sale,
haggle UI, phase transition, debt-due splash, tier-up
celebration).
-
Autonomous fix-and-retry: if qa-tester reports a small mechanical
bug (ternary syntax, typo, missing field, position_scale mismatch),
the orchestrator may apply the fix inline and re-run. Tier 2.6a
structured engine errors + Tier 2.6r visual bug recognition make
this safe. Never invent new logic; only fix what the report
directly identifies. Limit: max 3 retry cycles before surfacing.
-
Interactive: show QA report + capture path, ask approval.
Autonomous: proceed.
Phase 5b — gdd-coverage-tracker (audit)
23a. MANDATORY in autonomous mode. After qa-tester reports
complete (correctness verified), run gdd-coverage-tracker:
Skill(skill="yume-gdd-coverage-tracker", args=<game-name>).
23b. Read its coverage.md output. Severity-weighted thresholds:
- REQUIRED = 100% AND IMPORTANT ≥ 90% AND NICE gaps all
documented → proceed to Phase 7 wrap-up.
- Any required ✗ OR important < 90% → LOOP: parse the gap
list as a checklist, hand items back to the right designer
(content / game-rules / asset / etc. per gap type), re-run
their phases, then re-run qa-tester + gdd-coverage-tracker.
Cap at 3 loop iterations.
- After 2 loops, any same required ✗ persists → STOP. The
gap is a structural / engine block, not a content gap. Read
the tracker's "GDD-revision proposal" section and surface
it to the user verbatim. User picks: (1) build engine
extension, (2) edit GDD to remove the promise, (3) accept
a substitute design. DO NOT pick on the user's behalf.
23c. NEVER declare accept to user before reading coverage.md.
If the user accepts a "with explicit GDD revisions" verdict,
reflect that in the final summary verbatim — never collapse
to "accept" alone. Future sessions need the audit trail.
23d. The principle: a GDD is a CONTRACT. Anything written in it
either lands in the build OR gets cut from the GDD with the
user's explicit acknowledgment. There is no silent-drop path.
Empirical case: merchant 2026-05-07 shipped at 32% coverage
with qa-tester verdict complete — that loophole is closed
by this gate.
Phase 6 — Optional: asset generation (only if --with-assets)
- Invoke the offline
yume assets generate <data_root> tool (Tier
2.5k — defer to its own workflow; not part of this skill).
- Re-run qa-tester + gdd-coverage-tracker to verify assets load
AND that coverage hasn't regressed.
Phase 7 — Wrap up
- Summarize what was built:
- Game name + folder
- Number of entities, rules
- Cascades verified
- Files added (data, scenes, docs, ADRs)
- Tell user how to run it:
godot --path . scenes/<name>_2d.tscn
godot --path . scenes/<name>_3d.tscn
- Suggest next steps (iteration: "want to add X?", "want to refine
Y?")
Parallel execution discipline (mid-session, deliverable-level)
The phase pipeline above is mostly sequential by design — each
phase's output is the next phase's input. But within a single
session (especially Tier A/B/C content sessions per a kingdom-sim
GDD), there are typically 3-7 deliverables that can be worked in
parallel because their file boundaries don't overlap.
Empirical case: kingdom-sim merchant Session 2 needs to ship 5
items. Sequential (single-thread) ~3-5 hours; pure parallel
(N agents) ~1.5-2 hours but high coordination cost; hybrid
~2-3 hours with each item handled by its best-fit thread.
When to use parallel builders vs foreground (me)
Classify each deliverable BEFORE starting:
| Profile | Example | Best handler |
|---|
| Cross-cutting: touches ≥3 files, depends on full state-machine context | "4 distinct daily phases" (touches physics + game/rules + hud + scene + screen flow + state) | Foreground (me/orchestrator) |
| Coupled-to-cross-cutting: requires another in-flight cross-cutting item to land first | "Customer wants matrix" depends on "phases distinct" landing | Foreground sequential after cross-cutting item |
| Self-contained UI: writes one screen + signal-chain rules with clean file boundary | "Real haggle gauge screen" | Builder agent (parallel) |
| Self-contained pattern demo: writes new entity defs + new rules, doesn't modify existing rules | "Hire-NPC template" | Builder agent (parallel) |
| Self-contained ai_policy: writes new actor policy script + new entity, doesn't change existing actors | "Multi-shop NPC competitor" | Builder agent (parallel) |
| New ADR / engine work: ADR doc + engine module + tests | "ADR 0026 party primitive" | Builder agent (parallel) — file boundary is engine/ |
Litmus test for "parallel-safe":
- Does this deliverable need to read state/files that another
deliverable also writes? (yes → sequential)
- Does it modify shared files (test_runner.gd, primitives doc)
that another agent will also modify? (yes → coordinate)
- Can I describe the deliverable's file-list in 1 sentence with
no overlaps? (yes → parallel-safe)
Sync race — parallel agents must NOT sync to YumeTemplate
CRITICAL constraint discovered Session 2 (2026-05-07): multiple
parallel agents each running cp -r /home/kamwoh/yume/godot/. /mnt/c/ .../YumeTemplate/ race to overwrite the SAME shared template
directory. If two agents run godot binaries against this shared
template at overlapping times, godot processes see mixed source
state — non-deterministic tests, corrupt captures, file-not-found
errors mid-load.
Rule: parallel agents WRITE source files only. They do NOT sync
to YumeTemplate. They do NOT run godot. The orchestrator (me) owns
the single integration sync + unit tests + visual QA across the
integrated state.
This is also why parallel agents stage their rules into files like
rules_haggle_staged.json — the orchestrator splices them into the
appropriate world/rules/<feature>.json chain module AFTER all agents
land, BEFORE the single sync.
Spawning parallel builder agents
When launching a builder subagent for parallel work, use this
prompt skeleton:
Build <deliverable name> for <game-name>.
WHY: <1-2 lines linking to GDD section>
YOUR FILES (own these, don't touch others):
- <path 1>
- <path 2>
...
DO NOT TOUCH (these are owned by me/other agents):
- <path A>
- <path B>
...
SHARED FILES — coordinate by appending only:
- <path X> — append your test sections at end, don't modify others'
- <path Y> — same, append-only
WHAT TO BUILD:
1. <step 1>
2. <step 2>
...
VERIFY:
- DO NOT sync to YumeTemplate. DO NOT run godot binary.
- DO NOT run unit tests or visual QA — orchestrator owns these
across the integrated state.
- After writing your files, verify they parse as valid JSON / GDScript
via Read/grep. That's your verification scope.
CONSTRAINTS:
- Per ADR 0021: expose Godot capabilities, don't reimplement
- Path-scoped rules in .claude/rules/ apply
- Visual QA gate per .claude/rules/visual-qa.md mandatory for
visual-touching changes — construct context-specific prompt
REPORT BACK:
- Files modified + lines changed
- Test count delta (baseline → new)
- Visual QA result (PASS/FAIL with specific evidence)
- If commit: commit hash. If not (shared-file conflict expected):
files staged for orchestrator to integrate.
Time budget: <estimate>. If blocker, surface — don't push through.
Integration after parallel agents complete
When agents finish:
- Read each agent's task-notification result
- For each agent that committed cleanly: pull the commit message
into your session understanding
- For each agent that staged files (didn't commit due to shared-
file conflicts): use
git add -p to take their hunks cleanly,
then commit yourself with attribution
- Run unit tests + visual QA on the integrated state
- Run gdd-coverage-tracker on the post-integration build
- If any [R] still ✗: loop back per Phase 5b discipline
When NOT to spawn parallel builders
- Designer phases (game-designer, planner, story-planner,
economy-designer, level-designer): these write design docs that
are coordination inputs to everything else. Run sequentially.
- Reviewer phases: read-only, but lock-stepped to design output
they're reviewing. Sequential.
- qa-tester + gdd-coverage-tracker: these run AFTER all build
work to evaluate the integrated state. Always last.
- Single-deliverable sessions: if the session has only 1-2
items, spawning agents adds overhead without payoff.
Pre-Session checklist
Before starting any content/build session:
- List the session's deliverables from the GDD's Tier plan
- Classify each: cross-cutting / coupled / self-contained / engine
- Identify file boundaries per item
- Pre-allocate ownership: foreground items + agent items
- Write each agent's prompt with explicit DO TOUCH / DO NOT TOUCH
file list
- Identify shared-file coordination items (test_runner.gd,
primitives doc, etc.) — pick a strategy (append-only, last-merge,
or me-as-integrator)
- Launch parallel agents in same message (multi-tool block)
- Begin foreground work in parallel
- Integrate when agents complete
This discipline replaces "vibes-based whether to spawn" with a
defensible decision framework. The merchant 2026-05-07 session
shipped ADR 0024 + 0025 by accidentally getting agents to step on
test_runner.gd; the integration recovery cost ~30 min. Pre-allocated
ownership prevents the recovery cost.
Failure modes + handling
| Failure | What I do |
|---|
| User rejects at any approval gate | Stop, ask what to change, re-invoke that stage |
| systems-designer needs new primitive | Escalate to tech-director. If rejected, ask user to descope |
| content-designer's JSON fails Rule.validate_all | Surface errors, hand back to content-designer with specifics |
| qa-tester reports broken cascades | Identify failure pattern (dead rule, missing query match, runaway), loop back to fix |
| Engine error during qa load | Surface error to user, often indicates content-designer schema bug |
| Tests broken after content add | Reject the content (regression) — should be impossible if rules are valid, but guard anyway |
Collaboration protocol enforcement
Apply Question → Options → Decision → Draft → Approval at each phase
boundary. Don't apply destructive operations (file writes, agent
invocations that modify state) without user go-ahead.
The user can abort at any approval gate; the partial output (GDD
without sketches, sketches without content, etc.) is still valid as
intermediate artifacts.
Reference docs (read FIRST when invoked)
I read these before invoking any agent, to ground myself in current
state:
docs/guideline/30_framework_primitives.md — primitive contractdocs/guideline/32_mda_for_yume.md — design vocabularydocs/guideline/31_text_to_game_pipeline.md — full pipeline architecture.claude/skills/yume-*/SKILL.md — specialist skills (loaded via Skill tool).claude/rules/ — path-scoped rule filestask_plan.md — current state of the framework
If reading any of these reveals the framework is in a broken state
(failing tests, half-landed primitive change, etc.) → surface to user
before starting. Don't generate against a broken baseline.
What I do NOT do
- ❌ Write GDDs, sketches, JSON, or QA reports myself. Always delegate
to the appropriate specialist agent.
- ❌ Skip approval gates to "save time."
- ❌ Modify engine code (only tech-director gates engine changes).
- ❌ Generate assets (Tier 2.5k tool, separate workflow).
- ❌ Promise specific genre support not validated by the W5 acid test
(visual novels, rhythm games, soft-body physics — out of scope).
Honest scope reminder
Yume covers simulation-shaped games: ecology, farming, RPG, shooter,
chess, survival, strategy, tower defense, roguelike, puzzle-with-state.
Out of scope: rhythm games, precision platformers, narrative-heavy
adventures, continuous physics simulation, networked multiplayer.
If the prose asks for one of these, I tell the user upfront before
spending agent calls.
Example invocation transcript
> /yume-design "a farming sim where moonlight grows crops faster"
I'll run the Yume text-to-game pipeline. Plan:
- Game name: '<auto-suggested-slug>' (from prose). OK?
- 6 stages: GDD → sketches → content → assets → QA → wrap
- Code-draw visuals (no --with-assets flag)
Approval to start?
> yes
[Phase 1: invoking yume-game-designer...]
[GDD written: docs/games/<game>/GDD.md]
GDD summary:
- Aesthetics: Submission + Sensation
- Dynamics: day/night cycle modulates crop growth; rot → fertilizer cycle
- Mechanics: ~6 entity types, ~10 rule sketches
- Open question: should night be a global state or distance from a
"moon" entity?
Approve GDD?
> yes, global state is fine
[Phase 2: invoking yume-systems-designer...]
...
Status
This skill is the orchestrator (Tier 2.5g, expanded for Tier 2.7
design-quality phases). The 8 specialist skills it invokes are at
.claude/skills/yume-<role>/:
yume-game-designer — Phase 1 (prose → GDD)yume-game-reviewer — Phase 1b (adversarial GDD critique)yume-game-planner — Phase 1c (GDD → world plan, named cast)yume-level-designer — Phase 1d (spatial layout + rationale)yume-combining-logic-designer — Phase 1e.1 (recipe systems — CONDITIONAL)yume-economy-designer — Phase 1e.2 (numeric balance + flows — CONDITIONAL)yume-story-planner — Phase 1e.3 (narrative beats + arcs — CONDITIONAL)yume-systems-designer — Phase 2 (ALL rules — world/rules/*.json feature modules, scope expanded per ADR 0009 revision 2026-05-16)yume-content-designer — Phase 3 (entities + initial state)yume-game-rules-designer — Phase 3.5 (declarative win/lose in hud.json + game/flow.json multi-level progression — NARROWED scope post-revision)yume-asset-designer — Phase 4 (visuals + audio cues + UI strings)yume-qa-tester — Phase 5 (headless + visual + scenario QA)yume-tech-director — invariant guardian, on-demand
Behavioral tests are Tier 2.5h — see tests/spec.md.
