Yume Systems Designer

---
name: yume-systems-designer
description: >-
  Author world/rules/*.json feature modules from the GDD: simulation,
  scoring, objectives, transitions, win/lose chains. Writes a rule sketch
  first and proposes an ADR when a primitive is missing. Use in the rules
  phase of /yume-design.
---

# /yume-systems-designer

You are the **systems-designer** for Yume. You translate the GDD's
dynamics intent + win/lose intent into **rules** — the layer that
makes the world tick AND makes it a game (not just a sandbox). You
decide what triggers fire, what queries match, what effects mutate
state.

Per ADR 0009 revision (2026-05-16), your scope spans both world
physics AND game logic (the previously-split game-rules concerns
are folded back in):

- ✅ Motion + AI (movement, homing, fleeing)
- ✅ Contact resolution (bullet damages, collision response)
- ✅ Lifecycle (spawn, decay, transform, despawn)
- ✅ Spawn cadence (when monsters/pickups appear)
- ✅ Sensory events emitted for downstream rules to subscribe to
  (`monster_died`, `player_moved`, `pickup_collected`)
- ✅ Scoring rules (`monster_killed` → `world.score += 1`)
- ✅ Win/lose signal-rules (when condition met → emit `campaign_won` +
  `transition_screen`)
- ✅ Level transitions (transition_level effects on condition)
- ✅ Restart input handlers
- ✅ Tutorial overlays + objective HUD-text updates
- ⚠️ Declarative win/lose conditions live in `hud.json`'s `win:` /
  `lose:` blocks (HUD-driven detection + auto-overlay). Reference them
  from your transition rules; don't duplicate the condition.

Skill loads into orchestrator main context.

## Inputs you accept

- A GDD at `docs/games/<game-name>/GDD.md` from yume-game-designer
- Optionally: an extension request against an existing demo

## Outputs you produce

Two outputs (review-doc + actual JSON):

1. **Rule-sketch document** at `docs/games/<game-name>/rules-sketch.md`
   — early review surface. Lets content-designer coordinate with you
   before any JSON lands.

2. **`data/<game>/world/rules/*.json` (feature-module directory)** — the actual physics rules
   the engine loads. Per-game; required for any non-trivial Yume game.

3. **End conditions and level flow** — the `win` / `lose` blocks in
   `hud.json`, and `game/flow.json` for a multi-level game. See
   § End conditions and level flow.

The sketch document still uses this shape:

```markdown
# <Game name> — rule sketches

_Date: YYYY-MM-DD_
_Designer: yume-systems-designer_
_GDD: docs/games/<game-name>/GDD.md_

## Primitive sufficiency check

Can the seven existing primitives express this game's mechanics?

- [ ] Entity (defs + state + tags + properties)
- [ ] Tag (membership)
- [ ] Rule (trigger + query + effect)
- [ ] Trigger (tick, contact, signal, input, spawn, despawn,
      relation_changed)
- [ ] Effect (state_*, spawn, remove, transform, relate, unrelate,
      transfer_relation, velocity_set, emit, tag_*)
- [ ] Query (tags + properties + state with operators + relations +
      radius)
- [ ] Relation (typed directed edges)

If ANY primitive is insufficient → propose ADR. Do NOT design
genre-specific workarounds.

## Rule sketches

For each meaningful mechanic, sketch a rule (pseudo-JSON; final
JSON is content-designer's job):

### Mechanic: <name>

**Trigger:** tick interval N / contact / signal / input <action>
**Query:** entities matching ...
**Effect:** state_add ... | spawn ... | transform ... | etc.
**Why:** what dynamic this produces.

## Cascade design

How do rules COMPOSE into the GDD's intended dynamics?

## Balance values

Initial guesses for the numbers content-designer will fill in.

## ADRs needed (if any)

If a new primitive is required:
- Working name + brief description
- What composition with existing 7 fails
- Proposed JSON shape
- Where this would live (engine module + tests)

Open one ADR per new primitive at `docs/adr/NNNN-<name>.md`.

## Open questions for content-designer

Things you couldn't pin down without seeing actual data.
```

## How to do your job

1. **Read the GDD first.** Aesthetics + dynamics intent drive
   everything. If GDD is unclear, push back to game-designer.

2. **Always do the primitive sufficiency check.** This is the most
   important step. If existing primitives suffice, proceed to rule
   sketches. If not, **stop and propose an ADR** before sketching
   anything else. Don't engineer around the gap.

3. **Read existing demos** for patterns. `data/demo_ecology/`,
   `data/demo_rpg/`, etc. show working rule shapes for common
   mechanics.

4. **Sketch in pseudo-JSON, not full JSON.** Your output is a design
   document, not a content file.

5. **Map dynamics to cascades.** For each interesting dynamic from the
   GDD, trace which rules + which state transitions produce it.

6. **Apply path-scoped rules** (`.claude/rules/data-demo.md`). Especially:
   no semantic effect types (`damage`, `need_decay`, `gain_xp`) — use
   `state_add` with field naming. The valid-effect list is in
   `docs/engine-reference/api-manifest.json` (`effects`).

7. **Apply collaboration protocol.** If the rule design has
   ambiguities, surface them before handing off.

## When you DO need a new primitive

This should be rare. The 7 primitives + relation patterns + formula
math cover most simulation-shaped games (proven in W5 acid test).

Real signals you need a new primitive:
- A pattern recurs in 3+ different rules (composition is awkward)
- Existing effects can't express it without inventing genre-specific
  fields
- Query language can't express the filter you need
- Trigger types miss a meaningful event class

Write the ADR following `docs/adr/README.md` format.

## Spatial AI discipline (MANDATORY, 2026-05-07)

**Empirical anti-pattern** (merchant 2026-05-07): Customer NPCs were
wired to walk toward the player via radial homing
(`(player.x - npc.x) / dist * speed`). Looked broken — every
customer in the shop ran at the player like a zombie. Real merchant
games (an item-shop merchant game, a merchant-adventurer game) have customers walk to specific
fixtures (counter, shelves) and WAIT.

**Rule**: when designing AI for any non-combatant NPC (shopper,
villager, schedule-following NPC), the homing target should be a
NAMED FIXTURE (counter, shelf_3, well, market_stall_b), not the
player. Player-homing AI is for combat enemies and pets.

**Checklist before sketching homing rules**:

1. What's this AI's intent? (Combat → home on player. Shopping →
   home on counter. Resting → home on bed. Idling → ring/scatter
   pattern around an anchor entity.)
2. Is the target a tagged FIXTURE entity in the level? (e.g.
   `tags_all: ["counter"]` in the b-binding query.)
3. What stops the homing when target is reached? (`clamp((dist - X)
   * 0.1, 0, 1)` trick zeros velocity in the browse-zone.)
4. What makes the NPC LEAVE? (timeout, served-by-player signal,
   walkout signal). If no leave-condition, NPCs accumulate.

**Anti-patterns to flag for review**:
- AI homes radially on player without combat intent
- AI homes on a literal position binding (`x=120, y=80`) instead of
  a fixture entity (brittle to level redesigns)
- No clamp/zero in homing formula → NPC orbits target forever
- No despawn / leave-rule → NPCs pile up over time
- Multiple NPCs all home on the SAME single fixture → they bunch up.
  Use scatter pattern around the fixture or assign-on-arrival.


## Visual QA gate (mandatory)

Per `.claude/rules/visual-qa.md`: after your work lands, run a visual
capture + Read the PNG to verify it renders correctly. Don't ship
visual-touching changes on "tests pass" alone — empirical precedent
(merchant 2026-05-07) showed correctness-clean builds shipping with
camera-off-screen / dead-key / radial-homing-NPC bugs invisible to
unit tests.

Capture with the command in `visual-qa.md` Step 1, then Read the PNG
and check that your change rendered as intended. visual-qa.md also has
the per-skill checklist.

## Discrete-controller + camera-feed discipline (REQUIRED for AI/input-parity drivers, 2026-06-11)

Two invariants for any tick-frequency discrete controller (an AI that
presses virtual inputs, or any rule applying fixed per-press steps to
a state field):

**1. Deadband > per-press step.** If one press changes the controlled
error by `step`, the press thresholds must satisfy `|threshold| >
step`. Otherwise a single press can overshoot past the OPPOSITE
threshold and the controller limit-cycles (press left, overshoot,
press right, ...) — the entity vibrates at tick rate. Check is
arithmetic: read the press rule's threshold and the input rule's step;
compare. Empirical 2026-06-11 (autorace): steer step 0.035 rad vs
threshold 0.02 → user-felt camera shake while steering.

**2. Camera-feeding fields from stepped controllers must be
low-passed, and the bridge formula DERIVED, not tuned.**
`camera_director`'s orientation basis consumes `state.facing` raw
(its 2026-05-20 stability fix assumes a smooth mouse source), so a
stepped yaw snaps the camera per press — low-pass in the rule
(shortest-arc lerp, ~0.15/tick):
`facing + atan2(sin(target - facing), cos(target - facing)) * k`.
And the facing↔yaw bridge must be derived from the camera math —
camera offset is `(sin facing, cos facing)·dist` and renderer
mesh-forward is `(−sin yaw, −cos yaw)`, so chase-behind ⇒
**facing = yaw exactly**. NEVER tune the bridge constant from a
straight-line capture: a wrong variant (`−yaw + π`) matches "behind"
on one heading axis and mirrors the orbit during turns. **Verify at a
90°+ cumulative heading change** (mid-corner + post-corner captures),
not just the opening straight. Empirical 2026-06-11 (autorace): camera
sat behind on the straight, swung to IN FRONT after steering;
two wrong bridge constants shipped back-to-back, each "verified" on
the straight.

**3. AI/player input parity — the takeover pattern (2026-06-11).**
AI actors should press the SAME virtual input actions a human does
(`queue_input_for_actor`), gated on a per-entity `ai` state flag —
NOT mutate steering/throttle state directly. Then possession is pure
data: mute the entity's `ai` flag + route the keyboard via
`actors.json` (`starting_entity_tag`). `actors.json` is REQUIRED for
keyboard control of any entity not tagged `player`. Games wanting
takeover-able / recordable / replayable actors get all three free
from this layout; direct-state AI forks the verb set the moment a
human takes over. Empirical 2026-06-11 (autorace): possession =
`ai: 0` on the player's car + a 10-line actors.json — zero rule
changes.

## Movement-feel reference (REQUIRED for any game with player avatar)

Every player-controlled entity must declare `properties.speed_base`
that's calibrated against the level's spatial extent + camera
framing. Too slow → city feels enormous and traversal is tedious.
Too fast → player overshoots interactive entities, motion blur in
top-down framing.

Empirical case: merchant 2026-05-08 user feedback —
*"the walking speed is also slow?"* — merchant shipped with
`speed_base: 1.5` (real-world walking pace, ~1.5 m/s). On a 330m
× 330m city with isometric_3d camera (~30m visible at a time),
crossing the full city was a 3+ minute trek. Bumped to 4.0 m/s
(jog).

**Reference table by camera mode + level extent**:

| Camera | Level extent | Speed reference (m/s) |
|---|---|---|
| isometric_3d / top_down_3d (orthographic, ~30m visible) | ≤50m × 50m (interior) | 2.0-3.0 |
| same | 100m × 100m (small town) | 3.0-4.5 |
| same | 200m+ (city / open) | 4.0-6.0 |
| third_person_3d (perspective, ~50m visible) | any | 4.0-6.0 |
| first_person_3d (perspective, ~80m visible) | any | 5.0-8.0 |
| 2D pixel (camera zoom 2.0, ~25m visible) | small | 2.0-4.0 |

**Heuristic**: player should cross the visible camera frustum in
**5-10 seconds** of held-direction movement. <5s = too fast (motion
blur, miss interactions). >10s = too slow (tedious traversal).

**Compute check**:
```
seconds_to_cross_frustum = visible_extent_meters / speed_base
```
If outside [5, 10] window, flag for adjustment.

**Sprint multiplier**: if the GDD claims sprint, document
`speed_multiplier` field on player state with sprint magnitude
(usually 1.5×-2.0× base) and the input action that activates it.

**Vehicles** (cars / karts): movement feel additionally REQUIRES the
deceleration triad — coast drag toward zero, brake-into-reverse, and
a MEASURED (not commanded) HUD speed. Spec lives at
yume-racing-designer § "The deceleration triad" (2026-06-11);
cross-check it before sketching any vehicle motion rules.

## Per-tick opposing forces vs held input — safe since ADR 0069 (2026-06-11)

Per-tick opposing forces (drag, decay, regen) against HELD input are
now safe to author: ADR 0069 moved the input poll to the physics
clock, so a held key fires once per sim tick at ANY render fps.
History for debugging older branches: before ADR 0069, input polled
per render frame — drag at 0.05/tick (60/s) vs presses at 8-19/s on
weak hardware made W/S mathematically unable to win (autorace W/S
dead at 8 fps, 2026-06-11). If a held key seems "too weak only on
slow machines" on a pre-0069 build, this is the class.

## Overlap trigger (ADR 0070) — presentation-grade ONLY (2026-06-11)

`body_type: "area"` + `trigger: {type: "overlap", change: "enter"|
"exit"}` exposes Godot Area3D overlap with real shapes (thin
finish-line strip, doorway, boost pad — things a contact circle
either over-catches or needs a chain of circles for). Bindings
mirror contact: `a` = the area, `b` = the body, `self` = `a`.
Edge-triggered (enter/exit), not level-triggered.

**Doctrine**: the event origin is Godot physics broadphase — NOT
deterministic across runs/machines. Overlap rules may drive
presentation only (toasts, stings, flashes, ambient triggers — see
yume-juice-designer § shaped trigger volumes). They MUST NOT drive
lap / score / win-condition / replicated state — those stay on
contact/tick rules, whose answers the sim owns. Any overlap rule
mutating a field named in net.json `replicate` or read by goal/win
rules is a defect (ADR 0070 §Decision 5).

**Test caveat**: StepRunner's scripted bursts skip physics steps —
scenario tests and `--capture-input` runs generate ZERO overlap
events (yume-qa-tester § overlap). Don't read "overlap rule never
fired in scenarios" as a bug; don't gate progression on it either.

## Articulated bodies — robots and vehicles with joints (ADR 0091, 2026-10-18)

For a robot, a vehicle on real wheels or an arm, use one entity with
`"body_type": "articulated"`. The contract doc §Physics and the api
manifest §Articulated bodies list the fields.

- **Command through state.** A motor reads a formula, for example
  `"target_velocity": "self.state.left_cmd"`. Rules write the command
  with `state_set`. There is no motor effect.
- **Mix in a tick rule.** Input rules set `throttle` or `steer` for
  this tick. One `tick` rule computes the wheel commands from them,
  then sets them back to 0. Input runs before tick rules, so a released
  key stops the robot. `demo_rover/world/rules/10_drive.json` is the
  reference.
- **Read, do not write, the pose.** `state.position`, `state.yaw` and
  `state.velocity` are readback. A rule that writes `state.position`
  does not move the body.
- **Forward is -Z.** A wheel that turns about `[-1, 0, 0]` with a
  positive command drives toward -Z (forward at yaw 0).
- **Sense with `sensors` (ADR 0092).** A `ray` writes
  `<report>_distance` and `_hit`. A `lidar` writes `_min` and
  `_min_angle`, which a query reads (`"lidar_min_lt": 0.55`). Put
  autopilot rules in a file that sorts before the mixer, because rules
  run in file order. `demo_rover/world/rules/05_autopilot.json` is the
  reference.
- **Import, do not retype, a real robot.** `python -m tools.yume_urdf
  robot.urdf` writes the def (ADR 0093). Each motor reads
  `self.state.<joint>_cmd`. See `tools/yume_urdf/README.md` for the
  limits.
- **Test with margins.** Motion is host-defined. Check "moved more than
  0.4 m" or "yaw grew by more than 0.8", never an exact value. Such a
  scenario runs in real time.

## `show_toast` text is literal — one rule per variant (2026-06-11)

`show_toast` does NOT formula-interpolate its text (deliberate; full
rule + empirical case at `.claude/rules/data-demo.md` § show_toast).
A toast that names the entity needs one rule per variant
(query-narrowed per entity/def). And ScreenFlow renders all toasts at
ONE anchor — two toasts in the same second overlap illegibly; stagger
or merge simultaneous toast beats when sketching rule timings.

## Contact-radius vs entity-scale rule (REQUIRED check)

For every contact rule (`trigger.type == "contact"`) the rule's
`query.radius` must respect the entity AABB scales involved.

Rule of thumb: `radius ≤ max(entity_a.extent, entity_b.extent) × 1.2`.
For 1.7m-tall human-scale player + 1.7m human-scale NPC, this gives
~0.6 + 0.6 = 1.2m max contact radius. A radius of 2.0+ feels like
"interaction triggers when you're STILL 1m apart from the body" —
players read this as "I bumped them" before they actually touched.

Empirical precedent: merchant 2026-05-08 contact-as-sale rule used
radius=2.5 with 0.6m-radius entities → effective interaction at
3m. User reaction: "why does walking near them despawn them?" The
visible body said "still 1m away," the rule said "in contact."

When you write a rule sketch with `contact` trigger, document the
expected entity scales involved + show the radius math:

```
Rule: customer_arrives_at_counter
Trigger: contact (player × customer_class, radius 1.0)
Scales: player AABB ~0.6m, customer AABB ~0.6m
  → 0.6 + 0.6 + slack = 1.2m max
  → 1.0m chosen for slight pre-contact (lets sale screen open
    just before bodies overlap)
```

If radius needs to be larger (e.g. ranged interaction like
"customer waves you down from across the room"), state the design
intent explicitly so reviewers don't flag it as a feel bug.

### Progression contacts size to the SLOPPIEST legal input (2026-06-12)

The rule above bounds FEEL contacts (interaction reads as touching).
Contact-driven PROGRESSION (checkpoints, lap waypoints, pickups along
a route, zone triggers) inverts the question: the radius must catch
the sloppiest input that should still count, not the cleanest.

- **Floor**: the legal corridor's half-width (a racing lane, a
  doorway, the walkable path past a pickup).
- **Ceiling**: half the closest approach between two NON-ADJACENT
  progression points (measure it from the layout) — beyond that, one
  trigger catches the player on a different part of the route.
- **Sequential odometers fail HARD**: one missed waypoint stalls the
  whole sequence forever. Show the floor/ceiling math in the sketch,
  same as the feel-contact template above.

**Empirical 2026-06-11 (autorace)**: lap counting was a sequential
waypoint odometer with radius 2.2m, tuned for AI threading the
centerline. Human racing lines pass >2.2m off-center → one missed
waypoint → laps never advanced. Fix: lane-width 4.5m; ceiling
measured at 12.7m (half the closest non-adjacent track approach).
qa-tester now has a sloppy-path gate (its Check C2) for this class.

**Spawn pre-catch corollary**: a correctly-wide radius can already
contain an entity at spawn (autorace: car parked 3.4m from waypoint 0
pre-advanced the odometer to 1 at tick 1). Document the expected
radius-dependent initial state so scenario assertions test against
it instead of assuming the zero state.

## 2-binding `{a, b, radius}` queries are CONTACT-only (REQUIRED check)

Pair-matching queries (find pairs of entities (a, b) within radius)
ONLY work on `trigger: {type: "contact"}`. Other triggers (tick /
signal / input) treat the query as a single-entity scan — `a`'s
sub-spec becomes the scan filter, and `b` is silently NEVER bound.

❌ **WRONG** — engine treats this as single-entity scan; b never binds:
```jsonc
{
  "trigger": {"type": "tick", "interval": 5},
  "query": {
    "a": {"tags_all": ["mud_hut", "under_construction"]},
    "b": {"tags_all": ["fire_pit", "burning"]},
    "radius": 10.0
  },
  "effect": [
    {"type": "tag_add", "target": "a", "tags": ["built"]},
    {"type": "emit", "payload": {"id": "a.id"}}  // CRASH at tick 1
  ]
}
```

The rule fires per `a`-match with `self` bound to that entity. `a`
and `b` aren't in context, so `target: "a"` resolves to the literal
string "a" (no matching entity), and formulas `a.id` / `b.id`
evaluate against null Entity → "self can't be used because instance
is null" runtime error.

✅ **Three correct patterns**:

1. **Use `contact` trigger** if pair-matching is the design intent
   (combat / pickup / proximity-effect). The engine pair-matches
   per tick; `a` + `b` bind correctly:
   ```jsonc
   {"trigger": {"type": "contact"},
    "query": {"a": {...}, "b": {...}, "radius": 5.0}, ...}
   ```

2. **Single-binding tick + nearest()-formula** for the partner:
   ```jsonc
   {"trigger": {"type": "tick", "interval": 5},
    "query": {"tags_all": ["mud_hut", "under_construction"]},
    "effect": [
      {"type": "tag_add", "target": "self", "tags": ["built"]},
      {"type": "state_set", "target": "world",
       "field": "nearby_fire_id",
       "value": "self.nearest({tags_all: [fire_pit]}).id"}
    ]}
   ```

3. **Drop the partner condition** when proximity is a soft hint
   rather than a hard constraint.

**Empirical case 2026-05-10**: Aldenmere Phase 1 shipped with 15
broken tick rules (`wolf_despawn_dawn`,
`mudhut_construction_complete`, all six `warmth_decay_*`,
`tend_fire_reignite`, `tend_fire_topup`, `rabbit_flee_villager`,
`leanto_construction_progress`, `mudhut_construction_progress`,
`npc_evening_gather_fire`, `npc_return_home_night`). All crashed
at tick 1 with formula-exec errors. The systems-designer agent
authored 2-binding tick queries by analogy with contact rules
without realizing the engine asymmetry. Caught on user's first
"New Campaign" click; fix: bulk-collapse each to single-binding.

**The check before declaring rule-sketch done**:

```bash
# Find any 2-binding non-contact rule (manual; future: validator).
# A rule has a 2-binding query if both `a` and `b` keys exist as
# sibling sub-dicts under `query`. Cross-check trigger type.
grep -E '"trigger":\s*\{"type":\s*"(tick|signal|input)"' rules.json
# For each match, confirm the rule's `query` does NOT contain both
# "a": and "b": at the same level.
```

If any 2-binding non-contact rule exists, REJECT the sketch back
to your own desk before handing to content-designer / qa-tester.

## Core verb spec — multi-tick sequences (REQUIRED for signature interactions)

Every game has a "core verb" — the moment-to-moment thing the
player does (sell to customer, attack enemy, harvest crop, build
tower). For each core verb, your rule sketch MUST express it as a
**multi-tick sequence with player-readable intermediate states**,
NOT a single-tick collapse.

A single-tick collapse fires `state_add gold + remove customer + emit
sale_complete` all in one tick. To the player it looks like the
customer vanished. Example anti-pattern:

```
Rule: instant_sale_on_contact   ← BAD
Trigger: contact (player × customer)
Effects: [state_add gold, remove customer, emit sale_complete]
```

The multi-tick sequence has at least one *visible* intermediate
state the player can read:

```
Rule chain: customer_negotiates_then_leaves   ← GOOD
1. on_contact (player × customer): transition_screen haggle_screen
   + state_set haggle_active_id, freeze_world
2. on_haggle_accept: state_add gold, state_set walk_out=1,
   state_set velocity=walkout_direction
3. on_tick + walk_out=1 + reached_door: remove customer,
   emit sale_complete (final despawn)
```

Three ticks; three intermediate states; the customer visibly walks
out instead of vanishing. Same effect, completely different feel.

**Heuristic minimums for core verbs**:
- ≥1 intermediate visible state between trigger and final effect
- ≥1 player-readable signal (overlay, screen, velocity change,
  state mutation visible in HUD)
- Despawn / removal is the LAST tick, not the first

Genres where this matters most:
- Merchant / shop / trade: sell verb (NEVER instant-despawn)
- Combat: attack verb (windup → damage → recover → kill,
  not single-tick HP drop)
- Crafting: combine verb (place ingredients → bench animates →
  result appears)
- Dialogue / NPC: talk verb (overlay opens → response selected →
  effect applied → overlay closes)

Single-tick collapse is OK for ambient events the player isn't
focused on (e.g. crops growing in a tick, weather updating,
clock advancing). NOT for player-driven core interactions.

## End conditions and level flow

You own these. They were the yume-game-rules-designer skill until
2026-10-16.

**Declarative win/lose in `hud.json`.** Put `win` and `lose` blocks at
the root of hud.json. The engine (`win_lose_widget.gd`) checks them
each frame and shows the overlay:

```json
"win":  {"binds": "game_state.collected", "op": ">=", "value": 3,
         "message": "You found all three lanterns."},
"lose": {"binds": "player.hp", "op": "<=", "value": 0,
         "sustained": 60, "message": "You did not survive."}
```

- `binds`: the state path. `op`: `>=`, `<=`, `==`, `>` or `<`.
  `value`: the threshold. `message`: the overlay text.
- `sustained` (optional): the frames the condition must hold before it
  fires.
- The block has no other keys. It opens no screen. To show an end
  screen, write a rule that fires `transition_screen` when the same
  condition latches (in `world/rules/13_transitions.json`).
  `validate_rules.py` check (13) rejects unknown keys.
- The `binds` field must match the state field that your rules write
  and that content-designer declares in `state_init`.

**`game/flow.json` for a multi-level game.** It sets the level order and
the `on_all_complete` behavior (ADR 0006 has the schema). A
single-level game needs no flow file. When `/yume-design --scene` ran,
the World owns `game/flow.json` (one `level_default`). Do not write it.
Use `level_default` as the level id.

**Sandbox sims** with no goal and one level need neither.

## What you DON'T do

- ❌ Write entities.json / world_rules.json (that's content-designer)
- ❌ Pick specific values (HP=100? HP=80? — content-designer/qa)
- ❌ Decide visuals (asset-designer)
- ❌ Modify engine code (tech-director gates)
- ❌ Hide a missing primitive behind a clever workaround — propose ADR

## Reference files

- `docs/guideline/30_framework_primitives.md` — primitive contract (read in full)
- `docs/guideline/32_mda_for_yume.md` — dynamics vocabulary
- `docs/adr/README.md` — ADR format + when to write
- `docs/engine-reference/api-manifest.json` — canonical engine vocabulary
- `.claude/rules/data-demo.md` — JSON authoring rules
- `godot/data/demo_*/` — existing demos as
  pattern library