new-game-scaffold

Files (79)

• SKILL.md
• shared.json · assets/
• developer-request.md · examples/
• games.json · examples/lights-out/
• scaffold-plan.txt · examples/lights-out/
• app-settings.ts · examples/white-label/
• games.json · examples/white-label/
• checker.md · references/
• ids-and-names.md · references/
• new-game-checklist.md · references/
• white-label-apps.md · references/
• check-game-scaffold.mjs · scripts/
• check-lib.mjs · scripts/
• app-checks.mjs · scripts/lib/
• app-modules.mjs · scripts/lib/
• app-skeleton.mjs · scripts/lib/
• game-catalogs.mjs · scripts/lib/
• game-checks.mjs · scripts/lib/
• games-contract.mjs · scripts/lib/
• json-text.mjs · scripts/lib/
• scaffold-plan.mjs · scripts/lib/
• ship-placeholders.mjs · scripts/lib/
• scaffold-game.mjs · scripts/
• selftest.mjs · scripts/
• games.json · templates/contracts/
• games.schema.json · templates/contracts/
• find-generator.test.ts · templates/scripts/games/
• find-generator.ts · templates/scripts/games/
• new-game.ts · templates/scripts/games/
• package.json · tests/bases/app/
• ar.json · tests/bases/app/src/i18n/catalogs/
• en.json · tests/bases/app/src/i18n/catalogs/
• tsconfig.json · tests/bases/app/
• lights-out.yaml · tests/bases/complete-game/.maestro/games/
• levels.json · tests/bases/complete-game/contracts/
• _layout.tsx · tests/bases/complete-game/src/app/
• game-registry.ts · tests/bases/complete-game/src/games/
• intent-to-move.ts · tests/bases/complete-game/src/games/lights-out/canvas/
• lights-out-board.tsx · tests/bases/complete-game/src/games/lights-out/canvas/
• lights-out-surface.ts · tests/bases/complete-game/src/games/lights-out/canvas/
• lights-out-levels.ts · tests/bases/complete-game/src/games/lights-out/levels/
• lights-out-game.test.ts · tests/bases/complete-game/src/games/lights-out/
• lights-out-game.ts · tests/bases/complete-game/src/games/lights-out/
• lights-out-hosted.ts · tests/bases/complete-game/src/games/lights-out/
• apply-move.ts · tests/bases/complete-game/src/games/lights-out/rules/
• create.ts · tests/bases/complete-game/src/games/lights-out/rules/
• lights-out-engine.ts · tests/bases/complete-game/src/games/lights-out/rules/
• lights-out-persistence.ts · tests/bases/complete-game/src/games/lights-out/rules/
• lights-out-stats.ts · tests/bases/complete-game/src/games/lights-out/rules/
• lights-out-tuning.ts · tests/bases/complete-game/src/games/lights-out/rules/
• lights-out-types.ts · tests/bases/complete-game/src/games/lights-out/rules/
• list-moves.ts · tests/bases/complete-game/src/games/lights-out/rules/
• outcome.ts · tests/bases/complete-game/src/games/lights-out/rules/
• lights-out-testing.ts · tests/bases/complete-game/src/games/lights-out/testing/
• lights-out.golden.test.ts · tests/bases/complete-game/test/goldens/canvas/
• balance.sim.test.ts · tests/bases/complete-game/test/sims/lights-out/
• package.json · tests/bases/monorepo/apps/sliding-puzzle/
• games.json · tests/bases/monorepo/contracts/
• package.json · tests/bases/monorepo/
• BrandSans-OFL.txt · tests/bases/monorepo/packages/brand/fonts/
• …and 19 more

SKILL.md (first lines)

# New game scaffold

Turns "the next game is chosen" into a declared, named, translated starting point written by a script,
then walks the game through the build order of the games skills and proves, with a second script, that
the finished game has every part, agrees with its declaration and (when it is its own white-label app)
carries no placeholder a store would see. The game lives in `src/games/<game-id>/` of the one Expo
app; when multi-package, one game can also be one app in `apps/<game-id>/`.

## Rules that must hold

1. **Start every game with `scaffold-game.mjs`, never by copying another game's folder.** Why: a copied
   game keeps the other game's ids, catalog keys, saved-run namespace and settings in corners; the
   script fills every id form from one id and never overwrites a file.
2. **The game id is kebab-case, starts with a letter, and never changes after release; every
   identifier derives from it by one rule** (folder, `identity.id`, catalog namespace `<id>.`, saved
   runs, `<Pascal>` types, `<CONST>_` constants). Why: the id is inside every saved run on every
   device, and a leading digit is not a valid Android package part.
3. **The game's design notes are data in `contracts/games.json`, and the code must agree with them:**
   class, pan mode, levels and pack layout, daily, endless, hints, continue, every way of losing. Hints
   and continue have no default; a daily-only or endless-only game declares `levels: null` (its
   `contracts/levels.json` entry has `packCount` 0). Why: a declaration that promises a hint or a
   continue the rules lack ships a dead button; the complete check loads the module and compares it
   with the entry, and holds `contracts/levels.json` (level-generation-and-solvers) to the same pack
   layout.
4. **Every catalog of the app carries the game's keys:** `<id>.name`, one `<id>.lose.<reason>` per
   declared way of losing and every `<id>.*` key the game's code names, the same keys in every locale,
   no empty text; approved copy (`contracts/copy-source.json`) wins and retired keys are gone. Why: a
   missing key is a broken screen in one language, found by a player.
5. **Never overwrite.** `--write` writes nothing when any value conflicts; a game or app that exists is
   completed with `--add-missing`, which adds absent files, keys and entries and never changes a value.
   Why: an existing game holds decisions nobody wants silently reset.
6. **No template placeholder is left** (`__GAME_ID__`, `__GAME_PASCAL__`, `__GAME_CAMEL__`,
   `__GAME_CONST__`, any `__UPPER_SNAKE__`) in the game folder or its app, nor in the game's sims,
   board golden and E2E flows; generated native folders, build output and Pods are never scanned. Why: a placeholder compiles in a string and ships.
7. **Build the parts in the documented order, each with its own skill, and finish with
   `check-game-scaffold.mjs . --game <id> --stage complete`.** It never skips: every part, the
   evidence (sims, a pixel golden, an E2E flow), the hosted binding `<id>-hosted.ts` registered as
   `createGameHost(<CONST>_HOSTED, ...)` in `<gamesDir>/game-registry.ts`, the declared ways of losing
   and, for a white-label app, its real root and entry (polyfills, then `expo-router/entry`) instead of
   the placeholder entry. Why: nobody reads every file of a game; the gate proves nothing is missing and names the
   skill for each missing part.
8. **The game module loads headless** (pure TypeScript through `<id>-game.ts`). Why: bots, solvers,
   goldens and this check run it in Node; a React Native import in its graph breaks all of them.
9. **`npm run new-game` and the skill write identical bytes** (`scripts/games/new-game.ts` forwards to
   the installed generator); a declared `new-game` script runs a file that exists. Why: two generators
   drift.
10. **When multi-package, every white-label app lists the same dependency set at the same versions.**
    Why: native modules autolink per app and `expo install --check` sees only the app's own list; a
    drift crashes at launch or compiles two copies of one native module.
11. **When multi-package, an app's config is one composer statement, its per-app values live in
    `app-settings.ts` (read only by `app.config.ts`, never `null`), its native folders are ignored
    anchored, its Metro cache is keyed on `EXPO_PUBLIC_*`, and its fonts are byte-for-byte copies.**
    Why: native settings come only from the composer and plugins; `null` reached the device as `{}`;
    an unkeyed cache shipped development transforms in a production export (verified on SDK 57).
12. **When multi-package, store ids derive from one prefix and account-bound values stay documented
    placeholders until a human supplies them;** the complete stage fails `ship-placeholder` on each by
    name, and no option turns one into a pass. Why: a placeholder bundle id, privacy link or sample ad
    id in a store build is a rejected review or ads nobody is paid for.

## Workflow

1. **Design notes first.** Read [references/new-game-checklist.md](references/new-game-checklist.md)
   ("Before code"). Agree with the developer: the id ([references/ids-and-names.md](references/ids-and-names.md)),
   the name, class, pan mode, levels and packs, daily, endless, hints, continue, the ways of losing.
   Ask for hints and continue; never assume them.
2. **Plan the start:** `node ${CLAUDE_SKILL_DIR}/scripts/scaffold-game.mjs . --game <id> --name "<Name>"
   --hints none|solver --continue none|once [--levels 3x30] [--daily] [--endless] [--pan-mode swipe]
   [--class realtime] [--lose-reason <slug>]...` Read the plan (compare
   [examples/lights-out/scaffold-plan.txt](examples/lights-out/scaffold-plan.txt)). A `conflict` means
   the game exists: use `--add-missing`. When multi-package and the game is its own app, add `--app`
   after reading [references/white-label-apps.md](references/white-label-apps.md); a `deps-lockstep`
   failure is fixed first with dependency-management.
3. **Write it:** the same command with `--write` (white-label: then `npm install`). Once per repo,
   copy `templates/scripts/games/` and add `"new-game": "node scripts/games/new-game.ts"` to
   `package.json`.
4. **Check the start:** `node ${CLAUDE_SKILL_DIR}/scripts/check-game-scaffold.mjs . --game <id>` until
   `RESULT: PASS`; for a white-label app also `npx expo config --json` in `apps/<id>` per variant,
   `npx tsc --noEmit -p apps/<id>` and `npx eslint --max-warnings 0 apps/<id>`. Commit on its own.
5. **Build the game in order** (the table in the checklist): kit and rules (game-rules-engine, using
   the placeholder table the scaffold printed), real-time sim (realtime-game-loop), bot sims
   (game-balance-and-bots), levels (level-generation-and-solvers), canvas surface and golden
   (skia-canvas-rendering), intent function (canvas-gestures-and-hit-testing), the module, texts
   (i18n-strings-and-catalogs), the hosted binding and its registry factory (game-session-host),
   how-to-play, sounds and haptics (optional), for a white-label app its icon and splash
   (icons-app-icon-and-splash) and root (app-startup-and-bootstrap), the E2E flow on a named iOS
   simulator and a named Android emulator (e2e-maestro), screen parity (design-visual-parity). Each
   step test-first with its own check.
6. **Prove it complete:** `node ${CLAUDE_SKILL_DIR}/scripts/check-game-scaffold.mjs . --game <id> --stage complete`;
   fix every line ([references/checker.md](references/checker.md)) and rerun until `RESULT: PASS`,
   then `npm run verify`. A white-label app before the human steps ends with exactly its
   `ship-placeholder` lines: that is the finished state before those steps, never a pass.
7. **Report and hand over:** what a player can now do, the open human steps with the placeholder each
   replaces (one message shaped like [examples/developer-request.md](examples/developer-request.md)),
   the non-blocking ones (play-test, native review), what could not be verified without a device.
   Uploads and store-console changes are outward-facing: stop and ask first.

## Definition of done

- [ ] The game was started by `scaffold-game.mjs` with its real hints and continue, and its entry in
      `contracts/games.json` says what the rules do.
- [ ] `check-game-scaffold.mjs . --game <id>` passed before any game code was written.
- [ ] Every part exists and was built test-first by its skill; `npm run verify` is green.
- [ ] White-label: the app type-checks, lints and `npx expo config --json` works for every variant;
      the open placeholders are listed in the report as human steps.
- [ ] `node ${CLAUDE_SKILL_DIR}/scripts/check-game-scaffold.mjs . --game <id> --stage complete` prints `RESULT: PASS`
      (white-label before the human steps: only `ship-placeholder` lines, reported as open steps).

The scaffold stage may print `SKIP src/i18n/catalogs [catalog-missing-key] not yet created
(i18n-strings-and-catalogs creates it)` in an app without catalogs; an app with no game prints
`NOT APPLICABLE: the app has no game (...)`. The complete stage never skips.

## Anti-patterns

- **`cp -R src/games/<other> src/games/<new>` and search-and-replace.** Old ids, keys and tuning
  survive; scaffold, then copy the rules template with the printed placeholder table.
- **Declaring `hints: solver` or `continue: once` "for later".** The complete check fails the mismatch;
  declare what the rules do today and change both together.
- **Renaming a game id after release.** Every saved run and statistic is keyed on it; keep the id and
  change only the display name.

From zakariaf/ReactNative-Skills, MIT.

More from zakariaf/ReactNative-Skills