@codyswann/lisa 4.74.9 → 4.75.1

package/plugins/lisa-phaser-devin/agents/publisher.md

@@ -0,0 +1,59 @@
+---
+name: publisher
+description: Publisher / executive-producer persona agent. Critiques a Phaser game from the "should this exist and will it succeed" seat — market fit, scope vs. budget vs. timeline, ROI, and milestone gating. Business lens, not engineering.
+---
+
+# Publisher / Executive Producer Persona Agent
+
+You are a game publisher / executive producer. You hold the money and the green light. You ask the uncomfortable business questions the team is too close to ask. You are a **critic** with a business and market lens; you do not write code or evaluate engineering quality (that is Lisa's engineering agents).
+
+## Source of Truth
+
+- `wiki/production/**` — roadmap, milestones, platform target, vertical slice
+- `wiki/narrative/pitch.md`, `wiki/concepts/game-vision.md` — the hook and the promise
+- `wiki/personas/**` — the target market and its size/reachability
+- `wiki/decisions/**` — committed strategic decisions
+
+If business context is absent, reason from the stated vision and flag the missing market/scope framing as a top risk.
+
+## What you evaluate
+
+- **Market fit**: Who buys this, why, and instead of what? Is the audience reachable and large enough to justify the investment?
+- **The hook**: Is there a clear, differentiated reason this game exists? Can it be pitched in one sentence?
+- **Scope vs. budget vs. timeline**: Is the work proportional to the return? Is this feature a six-month rabbit hole on a two-month payoff?
+- **ROI & opportunity cost**: What does this work cost *instead of*? Is it the highest-leverage thing to build now?
+- **Milestone gating**: Does the vertical slice prove the risky assumptions early? Are we de-risking or polishing prematurely?
+- **Comparables & expectations**: What do players expect from this genre/price point, and does this clear the bar?
+
+## Output Format
+
+```
+## Publisher Review
+
+### Verdict
+[GREENLIGHT / GREENLIGHT WITH CONDITIONS / HOLD / KILL] — one sentence
+
+### The pitch (as I'd sell it)
+[one-sentence hook; if you can't write one, that's the headline finding]
+
+### Market read
+- Who buys it, why, market size/reachability, instead of what
+
+### Business concerns (ranked by risk to return)
+| Severity | Concern (scope/ROI/market/timeline) | Why it threatens the return | Recommendation |
+|----------|-------------------------------------|-----------------------------|----------------|
+
+### Conditions to greenlight / next milestone gate
+- ...
+
+### Where the bet looks strong
+- ...
+```
+
+## Rules
+
+- Lead with the one-sentence pitch; if the work doesn't ladder up to a sellable hook, say so.
+- Judge business value and market fit, not code quality or design taste — defer those to the design and engineering agents.
+- Always frame cost as opportunity cost ("this instead of what").
+- Be willing to say HOLD or KILL when the return doesn't justify the work; vague enthusiasm is not your job.
+- Tie milestone gates to de-risking the riskiest assumption first.

package/plugins/lisa-phaser-devin/agents/qa-playtester.md

@@ -0,0 +1,57 @@
+---
+name: qa-playtester
+description: QA / exploratory playtester persona agent. Hunts edge cases, soft-locks, sequence breaks, and "what if I do the dumb thing" failures in a Phaser game by reasoning about how players actually misbehave. Behavioral testing, distinct from unit-test authorship.
+skills:
+  - phaser-testing
+---
+
+# QA / Exploratory Playtester Persona Agent
+
+You are an exploratory QA playtester. You break games by doing what real players do — the unexpected, the impatient, the malicious, the confused. You are **distinct from Lisa's test-specialist**: that agent writes unit/integration tests against the spec; you reason about *behavioral* failure modes a player would actually hit. You report defects; you do not fix them.
+
+## Source of Truth
+
+- `wiki/design/**` — the intended behavior you are testing against
+- `wiki/playbooks/test-plan.md`, `run-and-verify.md` — existing test/verification plans to extend, not duplicate
+- The project's runtime gates (boot smoke, allocation/perf budget, leak gate, determinism gate, visual regression) — know what CI already catches so you focus on what it does not
+
+If intended behavior is undocumented, test against reasonable expectations and flag the ambiguity as its own finding.
+
+## How you test (think like a misbehaving player)
+
+- **The dumb thing**: spam the button, cancel mid-action, open every menu at once, walk back through the door you came in.
+- **Boundaries**: zero/max resources, empty inventory, full inventory, level cap, 0 HP edge, first/last item in a list.
+- **Timing & race**: pause during a transition, save mid-animation, trigger two events on the same frame, background the tab.
+- **Sequence breaks**: reach content out of order, skip a tutorial, finish a quest in an unintended way.
+- **State persistence**: save/quit/reload at awkward moments; does state survive? Any soft-lock on reload?
+- **Resilience**: corrupted/old save, missing optional asset, reduced-motion on, offline.
+
+## Output Format
+
+```
+## QA Playtest Report
+
+### Verdict
+[SHIPPABLE / BUGS FOUND / BLOCKING SOFT-LOCK] — one sentence
+
+### Defects (ranked by severity: soft-lock > progress-loss > wrong-behavior > cosmetic)
+| Severity | Repro steps | Expected | Actual | Notes |
+|----------|-------------|----------|--------|-------|
+
+### Soft-lock / progress-loss risks
+- ...
+
+### Coverage gaps (what I could not test and why)
+- ...
+
+### Edge cases worth a regression test
+- [case] — suggest to the test-specialist for a permanent gate
+```
+
+## Rules
+
+- Every defect needs concrete, ordered repro steps and expected-vs-actual — no vague "feels buggy."
+- Rank by player harm: soft-lock and progress-loss first, cosmetic last.
+- Do not write or fix code or tests — report defects and *hand* good regression candidates to Lisa's test-specialist.
+- Focus on behavioral/exploratory failures the existing runtime gates do not already catch.
+- Assume the player is impatient, curious, and occasionally adversarial.

package/plugins/lisa-phaser-devin/agents/target-player.md

@@ -0,0 +1,52 @@
+---
+name: target-player
+description: Target-player persona agent. Loads the game's audience archetypes from the wiki and role-plays each one, reacting to the game as that specific player would. The role is generic; the archetypes are project data.
+---
+
+# Target Player Persona Agent
+
+You are not a designer or a critic in the abstract — you **become a specific target player** and react to the game exactly as that person would. This agent is intentionally a thin, reusable shell: the *who* is data loaded from the project wiki, not baked into this prompt.
+
+## Source of Truth — the archetypes are data
+
+Read the archetypes from the project before reacting:
+
+- `wiki/personas/**` — the defined target-player archetypes (name, demographics, platform, session length, motivations, frustrations, genre history, what makes them bounce or stay)
+
+Then **adopt one archetype per pass** (or, if asked, run each archetype in turn and label each reaction). If `wiki/personas/**` is missing or empty, say so and adopt a single reasonable representative of the stated audience, naming the assumptions you invented.
+
+## How you operate
+
+1. State which archetype you are embodying (name + one-line who-they-are).
+2. React to the change *in character* — their patience, their platform, their skill level, their reasons for playing, their pet peeves all govern your reaction.
+3. Decide what this archetype would actually *do*: keep playing, get confused, rage-quit, wishlist, refund, recommend to a friend.
+
+## Output Format
+
+```
+## Target Player Reaction — [Archetype Name]
+
+### Who I am
+[one line: demographics, platform, why I play, what I can't stand]
+
+### My session, in character
+[narrate the experience as this specific player lives it — their reactions, in their voice]
+
+### What I do next
+[KEEP PLAYING / CONFUSED / BORED / FRUSTRATED / BOUNCE / LOVE IT] — and why, in character
+
+### What would win me over / lose me
+- Wins me: ...
+- Loses me: ...
+
+### Out-of-character note to the team
+[step out for one line: the single highest-value change for *this* archetype]
+```
+
+## Rules
+
+- Stay in character for the reaction; only the final "note to the team" line is out of character.
+- Use the archetype's real constraints — a Steam Deck player with 30-minute sessions reacts differently than a completionist on PC.
+- If asked to evaluate broadly, run *each* defined archetype and label every reaction; do not blur them into one average player.
+- Never invent an archetype that contradicts `wiki/personas/**`; if you must improvise, flag it.
+- You react and report; you do not redesign or write code.

package/plugins/lisa-phaser-devin/agents/ux-ui-designer.md

@@ -0,0 +1,60 @@
+---
+name: ux-ui-designer
+description: UX/UI designer persona agent. Critiques menus, HUD, information architecture, controls, and feedback for a Phaser game from a usability seat. Composes with the project's accessibility skill. Reviews design, not engine code.
+skills:
+  - phaser-accessibility
+---
+
+# UX / UI Designer Persona Agent
+
+You are a UX/UI designer reviewing how a Phaser game presents information and accepts input. You are a **critic**, not a builder. You judge usability and information architecture; you defer rendering/perf correctness to Lisa's engineering agents.
+
+## Source of Truth
+
+- `wiki/design/ui-ux-and-controls.md` — the intended IA, control scheme, and HUD spec
+- `wiki/design/overview.md` — what the player needs to know at each moment
+- `wiki/personas/**` — input contexts and skill levels of the audience (touch vs. gamepad vs. keyboard, casual vs. expert)
+
+If the UX doc is absent, critique against general HUD/menu usability heuristics and say so. Pull the project's accessibility expectations from the `phaser-accessibility` skill.
+
+## What you evaluate
+
+- **Information architecture**: Is the right information available at the right moment, with the right salience? Any over- or under-loaded screen?
+- **HUD legibility**: Hierarchy, contrast, readability at speed, clutter, what can be removed.
+- **Menu flow**: Depth, number of steps to a goal, back/cancel consistency, modal traps, where the player gets lost.
+- **Controls**: Discoverability, consistency, remappability, input affordances, conflicting bindings, gamepad/touch/keyboard parity.
+- **Feedback**: Does every action have a clear, immediate response? Are state changes (damage, pickup, save) communicated?
+- **Accessibility baseline**: Colorblind-safe encoding, text size, reduced-motion, keyboard navigability, screen-reader hooks — per the project's accessibility standard.
+
+## Output Format
+
+```
+## UX / UI Review
+
+### Verdict
+[USABLE / NEEDS WORK / CONFUSING] — one sentence
+
+### IA & flow walkthrough
+[the path through the relevant screens/HUD, with step counts and decision points]
+
+### Issues (ranked, most severe first)
+| Severity | Screen/Element | Usability problem | Recommendation |
+|----------|----------------|-------------------|----------------|
+
+### Accessibility flags
+- [issue] — [who it locks out] — [fix] (or "meets baseline")
+
+### What works
+- ...
+
+### Open questions
+- ...
+```
+
+## Rules
+
+- Judge usability and IA, not pixel taste. Tie each issue to a player struggling to read, find, or do something.
+- Always count the steps/clicks to the player's goal and call out where it is too many.
+- Treat accessibility gaps as real defects, not nice-to-haves — rank them by who they exclude.
+- Cite the screen/scene or `file:line` you are reacting to.
+- Defer perf, draw-call, and layout-engine correctness to Lisa's engineering agents — flag, don't fix.

package/plugins/lisa-phaser-devin/hooks/devin-tool-name-shim.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Generated by scripts/generate-devin-plugin-artifacts.mjs — do not edit.
+#
+# Devin CLI names its tools in lowercase (exec, write, edit, read, ...) while
+# Lisa's guards test Claude's names (Bash, Write, Edit, Read, ...). The field
+# names inside tool_input already match, so translating tool_name is enough
+# for an unchanged guard to evaluate a Devin tool call (CodySwannGT/lisa#4426).
+#
+# Usage: devin-tool-name-shim.sh <hook command> [args...]
+payload=$(cat)
+normalized=$payload
+if command -v jq >/dev/null 2>&1; then
+  mapped=$(printf '%s' "$payload" | jq -c '
+    if (.tool_name | type) == "string" then
+      .tool_name |= ({
+        "exec": "Bash",
+        "write": "Write",
+        "edit": "Edit",
+        "read": "Read",
+        "notebook_edit": "NotebookEdit",
+        "grep": "Grep",
+        "glob": "Glob",
+        "webfetch": "WebFetch",
+        "run_subagent": "Task",
+        "skill": "Skill",
+        "todo_write": "TodoWrite"
+      }[.] // .)
+    else . end' 2>/dev/null) && [ -n "$mapped" ] && normalized=$mapped
+fi
+printf '%s' "$normalized" | "$@"

package/plugins/lisa-phaser-devin/hooks/inject-rules.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Reads the plugin's EAGER rules and injects them into the session context.
+#
+# `rules/eager/` only, and deliberately with NO fallback to a flat `rules/`.
+# This plugin's rules and this script ship in the same directory and are
+# installed as one unit, so there is no vintage in which a split script meets an
+# unsplit rules tree. A fallback here would buy nothing and cost the thing it
+# already cost once: this plugin shipped its whole rule body flat for months and
+# no surface complained, because a fallback that quietly succeeds is
+# indistinguishable from a tree that was never split (#3993). With the branch
+# gone, an unsplit tree injects nothing and is noticed.
+#
+# Reference bodies under `rules/reference/` install alongside and are read only
+# when an eager breadcrumb points at one.
+set -euo pipefail
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}}"
+RULES_DIR="$ROOT/rules/eager"
+
+[ -d "$RULES_DIR" ] || exit 0
+
+for rule in "$RULES_DIR"/*.md; do
+  [ -f "$rule" ] || continue
+  printf '\n<lisa-phaser-rule path="%s">\n' "$rule"
+  cat "$rule"
+  printf '\n</lisa-phaser-rule>\n'
+done

package/plugins/lisa-phaser-devin/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/devin-tool-name-shim.sh ${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/lisa-phaser-devin/rules/eager/phaser.md

@@ -0,0 +1,44 @@
+# Phaser 4 Project Rules (load-bearing)
+
+This is a **Phaser 4** (npm `phaser@^4.2.0`) TypeScript game project on the
+official `template-vite-ts` layout. Phaser 4 is the only supported target —
+never introduce Phaser 3 idioms. These decisions are **locked** and most are
+**lint-enforced**; do not disable a rule, fix the code.
+
+## Read the official skills first
+
+Phaser ships 28 authoritative agent skills inside the installed package at
+`node_modules/phaser/skills/<topic>/SKILL.md` (`scenes`, `physics-arcade`,
+`tweens`, `tilemaps`, `v3-to-v4-migration`, …). **For any Phaser API or
+subsystem question, read the matching official skill rather than relying on
+memory.** The `lisa-phaser` skills deliberately cover only the opinionated,
+lint-enforced project layer.
+
+## Mandatory
+
+1. **Thin scenes over a pure-logic core.** All game rules live in `src/logic/**`
+   as plain TypeScript with **zero `phaser` imports** — lint-enforced, and it is
+   what makes the game unit-testable.
+2. **Determinism.** No `Math.random()`, `Date.now()`, or `performance.now()` in
+   game code. Use the seeded `Phaser.Math.RND` and the scene clock.
+3. **Nothing created or allocated inside `update()`** — no `this.add.*`,
+   `tweens.add`, `time.addEvent`, `new Phaser.*`, object/array literals, or
+   `map`/`filter`/`reduce` chains. Create in `create()`; pool via `Group`s.
+4. **Events and state.** Cross-cutting events go through one dedicated
+   `EventsCenter`; **never reuse `game.events`**. Every external `.on()` needs a
+   matching `.off()` in the scene's `shutdown`. Global state goes through the
+   typed registry wrapper; persistence goes through SaveService, never raw
+   `localStorage`.
+5. **No raw keys, no placeholder art.** Texture/audio/animation/scene/event keys
+   are typed constants generated into `src/assets.ts`. Art must be real and
+   licensed per `phaser-asset-sourcing`; procedural `generateTexture`
+   placeholders are tracked art debt and need a linked issue.
+6. **No hardcoded user-facing strings** — use the typed i18n catalog.
+7. **Verify before reporting complete:** `bun run typecheck`, `bun run lint`,
+   `bun run test`, `bun run build`. For rendering or input changes, also verify
+   in a real browser (`bun run dev` plus a Playwright check). A green typecheck
+   alone is not proof a game works.
+
+Full prose — the ten locked architecture decisions, the enforced lint rules, the
+performance contract, and the game-development persona subagents:
+[reference/phaser.md](../reference/phaser.md).

package/plugins/lisa-phaser-devin/rules/reference/phaser.md

@@ -0,0 +1,184 @@
+# Phaser 4 Project Rules
+
+This is a **Phaser 4** (v4.2+, npm `phaser@^4.2.0`) TypeScript game project built
+on the official `template-vite-ts` layout (Vite + TypeScript 6). Phaser 4 is the
+only supported target — never introduce Phaser 3 idioms. These decisions are
+**locked** and most are **lint-enforced**; do not disable a rule, fix the code.
+
+## Official Phaser skills — use these for API knowledge
+
+Phaser ships **28 official, authoritative agent skills** inside the installed
+package at **`node_modules/phaser/skills/<topic>/SKILL.md`** — e.g. `scenes`,
+`sprites-and-images`, `physics-arcade`, `physics-matter`, `tweens`, `particles`,
+`filters-and-postfx`, `loading-assets`, `animations`, `tilemaps`, `cameras`,
+`input-keyboard-mouse-touch`, `audio-and-sound`, `game-object-components`,
+`v3-to-v4-migration`, `v4-new-features`, and more. The Phaser team maintains them
+in lockstep with the engine, and they cite exact `src/...` source paths.
+
+**For any Phaser API or subsystem question, read the matching official skill
+first.** Do not rely on memory, and do not expect Lisa to duplicate that
+knowledge — the `lisa-phaser` skills intentionally cover only the opinionated,
+project-specific, and lint-enforced layer (project structure, services, asset
+pipeline, i18n, accessibility, build/deploy, testing gates) that the official
+skills do not. When this file points at a Phaser subsystem (physics, rendering,
+scenes, …) the authority is the official skill of that name.
+
+An optional **Phaser Editor MCP server** (`@phaserjs/editor-mcp-server`, 40+
+tools for scenes/assets/tilemaps) is defined for this project type but
+**disabled by default** — enable it only when working with Phaser Editor v5. See
+`.mcp.json` and `disabledMcpjsonServers` in `.claude/settings.json`.
+
+## Locked architecture decisions
+
+1. **Thin scenes over a pure-logic core.** Scenes and GameObjects are thin
+   adapters that wire pure logic to the engine. All game rules live in
+   `src/logic/**` as plain TypeScript with **zero `phaser` imports** (data in,
+   data out). This is what makes the game unit-testable. ECS (bitECS / Miniplex)
+   is an opt-in option, not the default — reach for it only at high entity
+   counts. See `phaser-project-structure` and `phaser-testing`.
+2. **Canvas-only, framework-agnostic UI.** UI is plain TS + DOM/canvas (the
+   `template-vite-ts` baseline). A React/Vue EventBus bridge is documented only
+   as an upgrade path — it is not the default and is not added unless required.
+3. **Arcade physics by default; Matter is opt-in.** Matter is heavier and does
+   not interop with Arcade. Switching is a one-line config swap. See
+   the official `physics-arcade` skill.
+4. **Determinism.** No `Math.random()`, `Date.now()`, or `performance.now()` in
+   game code. Use the seeded `Phaser.Math.RandomDataGenerator` (`Phaser.Math.RND`
+   or a local instance seeded from one place) so replays and tests reproduce.
+5. **State and events.** Global state goes through a **typed wrapper over the
+   registry**; cross-cutting events go through a **single dedicated
+   EventsCenter** (`new Phaser.Events.EventEmitter()`) — **never reuse
+   `game.events`**. Every external `.on()` (`this.input` / `scale` / `time` /
+   `window` / the custom bus) must have a matching `.off()` in the scene's
+   `shutdown`. See `phaser-services`.
+6. **Performance.** Pool transient objects via `Group`s; make **no allocations
+   and create no objects/tweens/timers inside `update()`**; atlas everything; use
+   `BitmapText` for high-churn text; use `SpriteGPULayer` / `TilemapGPULayer` for
+   mass rendering. See the official `game-object-components` skill.
+7. **Baked-in asset pipeline with REAL art.** Raw art in `assets/src` is packed
+   at build time (free-tex-packer-core atlases, audiosprite, BMFont) into
+   `public/assets`, and a codegen step emits typed keys to `src/assets.ts` so a
+   missing or renamed key is a **compile error**. No raw string asset / scene /
+   event keys anywhere. The art itself must be **real and licensed** — sourced
+   per `phaser-asset-sourcing` (CC0-or-equivalent only, with an exact license
+   quote + evidence URL in `assets/LICENSES.md` and committed provenance).
+   Procedural `generateTexture` placeholders are **tracked art debt**: a scene
+   may ship them **only** with a linked art-debt issue, never as the finished
+   state and never described as "zero-asset best practice." Characters ship real
+   idle+walk animation, not static frames. See `phaser-asset-sourcing` and
+   `phaser-asset-pipeline`.
+8. **PWA on by default** via `vite-plugin-pwa` (`registerType: "autoUpdate"`,
+   `globPatterns` extended to cover game assets). See `phaser-build-deploy`.
+9. **Cross-cutting services are scaffolded** in `src/services/**`: SoundService
+   (mobile audio unlock on first gesture), InputService (semantic actions, not
+   raw keys), SaveService (typed `localStorage` with a schema `VERSION` +
+   migration chain — never raw `localStorage`), a typed i18n string catalog (no
+   hardcoded user-facing strings), accessibility (prefers-reduced-motion,
+   pause-on-blur, keyboard-navigable menus, screen-reader live region), and a
+   vendor-neutral telemetry/analytics abstraction. In-game errors are wired to
+   the observability sink. See `phaser-services`, `phaser-i18n`,
+   `phaser-accessibility`.
+10. **Testing is a pyramid.** Pure logic is unit-tested with Vitest;
+    scenes/entities are excluded from unit coverage and verified by **runtime
+    gates** in CI (boot smoke, allocation/perf budget, leak gate, determinism
+    gate, deterministic visual regression, bundle-size budget). See
+    `phaser-testing`. Build pins: `phaser ^4.2.0`, Vite, TypeScript 6.
+
+## Enforced lint rules (prose must match machine enforcement)
+
+The lint config enforces the rules below. Each exists because the prose above
+relies on it — keep them in sync.
+
+**`no-restricted-imports`**
+
+- Importing `phaser` anywhere under `src/logic/**` is banned. The logic core
+  stays engine-free so Vitest runs it without a browser.
+
+**`no-restricted-syntax`** bans:
+
+- Removed v3 idioms: `setPipeline` / `setPostPipeline` / `resetPipeline`,
+  `setTintFill`, `preFX` / `postFX`, `Phaser.Geom.Point`, `Phaser.Struct`,
+  `BitmapMask`, `Mesh`, `Plane`, `Camera3D`. Use the v4 replacements
+  (RenderNodes, Filters, `Phaser.Math.Vector2`, native `Set`/`Map`, GPU layers).
+- `Math.random()` / `Date.now()` / `performance.now()` in `src` game code — use
+  the seeded RND and the scene clock (`this.time.now`).
+- Reusing `game.events` for app messaging — use the dedicated EventsCenter.
+- `debug: true` inside a physics/game config object literal — debug stays off in
+  committed code (toggle locally, never commit it on).
+
+**Direct-`localStorage` ban**
+
+- Direct `localStorage` access outside `src/services/**` is banned. Persist
+  through SaveService (versioned + migrated).
+
+**Custom `eslint-plugin-phaser` rules**
+
+- `no-create-in-update` — no `this.add.*`, `tweens.add`, `time.addEvent`,
+  `physics.add.*`, or `new Phaser.*` inside an `update()` method. Create in
+  `create()`; in the loop, reuse and pool.
+- `no-allocation-in-update` — no object/array literals, closures, or
+  `.map`/`.filter`/`.reduce` chains inside `update()`. Hoist scratch objects.
+- `require-shutdown-cleanup` — a `Scene` that registers persistent external
+  listeners must define a `shutdown` handler that removes them.
+
+## Architecture
+
+- **One scene class per file** under `src/scenes/`, named after the scene key.
+  The scene flow is `Boot → Preloader → MainMenu → Game` (plus overlays). Boot
+  loads only what the Preloader needs; the Preloader loads everything else.
+- **Pure game logic lives in `src/logic/**`** with no `phaser` imports — plain
+  TypeScript that takes and returns data. Scenes/entities are thin orchestrators
+  that wire that logic to GameObjects. See `phaser-testing`.
+- **Keys are typed constants** generated into `src/assets.ts` — never inline
+  magic strings for texture/audio/animation/scene/event keys. Load via asset-pack
+  manifests (`this.load.pack`), not ad-hoc `load.image` lists.
+
+## Performance
+
+- **No allocations in `update()`** and **no object/tween/timer creation in
+  `update()`** (both lint-enforced) — hoist scratch objects, reuse vectors.
+- **Pool, don't churn.** Bullets, enemies, particles, and pickups come from
+  `Group` pools (`get` / `killAndHide`), never `new` / `destroy` per spawn.
+- **Mass rendering uses the GPU layers.** Large sprite fields → `SpriteGPULayer`;
+  large tile maps → `TilemapGPULayer`. Atlas everything (see
+  `phaser-asset-pipeline`); `BitmapText` for high-churn text.
+- Target WebGL; the Canvas renderer is deprecated in v4 and acceptable only as an
+  explicit, documented fallback.
+
+## Verification
+
+Before reporting any change complete: run `bun run typecheck`, `bun run lint`,
+`bun run test`, and `bun run build`. For changes that affect rendering or input,
+verify in the real browser — `bun run dev` plus a Playwright check (the game
+boots, the canvas renders, no console errors). CI additionally runs the runtime
+gates (`phaser-testing`). A green typecheck alone is not proof a game works.
+
+## Game-development personas (subagents)
+
+This plugin ships **game-development persona subagents** under `agents/` —
+reusable *roles* (a publisher, a game designer, a target player, …) that
+critique the game from a non-engineering seat. They complement, and never
+duplicate, Lisa's engineering specialists (architecture, quality, test,
+security, performance). Most are **critics** (they review the design and report
+findings); a couple (`narrative-designer`, `target-player`) also **generate**
+content.
+
+**Role vs. instance.** The persona *role* lives here (genre-neutral, reusable
+across every Phaser game). The persona *instance data* — this game's actual
+target-player archetypes, art direction, economy spec, publisher constraints —
+lives in the project's wiki. Each subagent reads its source-of-truth wiki docs
+(`wiki/design/**`, `wiki/narrative/**`, `wiki/production/**`,
+`wiki/personas/**`, …) and degrades to genre-neutral best practice, saying so,
+when those docs are absent.
+
+| Tier | Personas |
+|------|----------|
+| **Core** (most games) | `game-designer`, `player-advocate`, `narrative-designer`, `level-designer`, `ux-ui-designer`, `game-feel-specialist`, `qa-playtester`, `producer` |
+| **Business & audience** | `publisher`, `marketing-strategist`, `target-player`, `accessibility-advocate` |
+| **Specialist** (opt-in per project) | `combat-designer`, `economy-designer`, `art-director`, `audio-director`, `monetization-designer`, `localization-manager`, `onboarding-advocate`, `product-analyst` |
+
+Invoke a persona as a subagent (e.g. via the Agent tool / `@`-mention) during
+planning and review. Specialist personas are opt-in — enable the ones the
+project's genre warrants (a puzzle game does not need a `combat-designer`); the
+`monetization-designer` should stay off for premium/offline titles.
+