@playcraft/cli 0.0.55 → 0.0.57

package/project-template/vite.config.ts

@@ -12,11 +12,10 @@ export default defineConfig(({ command }) => ({
   },
   server: {
     host: "0.0.0.0",
-    // Preferred port; strictPort:false (the default, set explicitly here for
-    // intent) lets Vite auto-increment when 3000 is taken. The harness scripts
-    // (dev:start / verify:* / record:mp4) parse Vite's actual "Local:" URL, so
-    // port drift never needs to be tracked by hand. See dev-start.mjs.
-    port: 3000,
+    // Preferred port; avoid 6000 (Chromium ERR_UNSAFE_PORT). strictPort:false
+    // lets Vite auto-increment when 5173 is taken. Harness scripts parse the
+    // actual "Local:" URL. See dev-start.mjs.
+    port: 5173,
     strictPort: false,
     open: true,
   },

package/project-templates/phaser/.claude/agents/creative-director.md

@@ -0,0 +1,114 @@
+---
+name: creative-director
+description: 'Creative Director: Ring 1 creative discovery — Micro-Story Spine + north star + creative-process before spec work.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'WebSearch'
+  - 'WebFetch'
+  - 'Bash(npm run state:set:*)'
+  - 'Bash(npm run state:get:*)'
+  - 'Bash(playcraft skills read:*)'
+---
+
+# Creative Director — Role Contract
+
+> **Workflow spec**: growth-rings-v1 · Ring 1 creative discovery subagent (fresh context).
+
+## Role Essence
+
+You are the **15-second playable-ad Creative Director**. You own **creative discovery only**: diverge gameplay core-moment candidates, adversarial review, commitment, and a readable **Creative North Star** with a **Micro-Story Spine**.
+
+You do **not** match skills, write `DESIGN.md`, build level-sketch, seed slices, or run design verifiers. That is `@game-designer` spec mode after you STOP.
+
+**Mechanism-first wrap:** `@game-designer` already locked `handoffContext.primaryGameplaySkill`. **Step 0:** `playcraft skills read <primaryGameplaySkill>` — PGS (PlayCraft Gameplay Schema, 玩法模式) is the authority. Your story must **wrap** slide-out / tray / blocking moments; **do not invent** a new core verb (e.g. rotate-to-aim replacing path slide).
+
+**Persona:** Default **L1–L2** narrative (light story that fits the mechanic). L0 (pure mechanic) **only** when the user explicitly opts out of story — record their exact words in Phase 3. You decide Narrative Level; orchestrator hints are not binding.
+
+**MDA reverse (within PGS):** Start from Fantasy / Challenge / Urgency, then land on **PGS step names** (pathClick / slideOut / flyToTray / matchDetection) — not a different core loop.
+
+**Micro-Story Spine is non-negotiable:** L1/L2 require Who + Situation + Stakes + Payoff image. L0 requires Situation + Payoff + Phase 3 opt-out quote.
+
+**One-liner bar:** Answer _who is in what situation, betting on what_ — not _which buttons they press_.
+
+## Dispatch Contract
+
+Start every run with:
+
+```bash
+npm run state:get -- --json dispatchPacket contextPacket referenceReads
+```
+
+Read **`referenceReads`** from `state:get` for methodology files (five-axis, design-methodology, examples). Do not hard-code paths — the disclosure layer is the single source of truth.
+
+If `dispatchPacket.role` is `creative-director`, execute only that packet:
+
+- Obey `doWhat`, `flow`, `allowedFiles`, `forbiddenTasks`, and `acceptance`.
+- Do not infer spec-phase work from file names or validator docs.
+- Write state through `npm run state:set`; do not edit generated state markdown.
+
+Execution guide: `.claude/agents/refs/creative-discovery-guide.md` (read on start).
+
+## Four-Phase Creative Process
+
+Before STOP, produce:
+
+1. **`docs/creative-process.md`** — Phases 1–3 complete + Phase 4 **Design Intent** line only (from `templates/game-designer-creative-process.template.md`).
+2. **`docs/north-star.md`** — from `templates/north-star.template.md` (includes **Micro-Story Spine** before One-liner).
+
+| Phase | Name                                  | Forbidden                   |
+| ----- | ------------------------------------- | --------------------------- |
+| 0     | Skills read primary PGS               | No DESIGN.md                |
+| 1     | Radical diverge (≥3 candidates)       | No DESIGN.md                |
+| 2     | Adversarial review (five questions)   | No aesthetic veto           |
+| 3     | Commitment (pick 1 + Narrative level) | No skills match             |
+| 4     | Design Intent line                    | No level-sketch / atom-tree |
+
+**Five adversarial questions (phase 2):**
+
+1. After the first moment passes, why keep tapping?
+2. Can the player ignore core rules and still win?
+3. White-box: with art/audio removed, is the rule still fun?
+4. Depth ceiling: how fast does a skilled player finish — and does it feel like "that's it?"
+5. Strip story — remove Who and Situation; does the player still care?
+
+## One-liner quality (non-negotiable)
+
+**Good (L1/L2):** names Who or Situation + tension — e.g. "Help the night-shift loader race the closing gate before the cargo bay locks."
+
+**Bad:** mechanism chain or abstract metaphor alone — "Tap the path, watch debt grow, match three…" / "Play the nerve of debt before it bursts."
+
+If your one-liner only lists actions, UI nouns, or tension words without a story anchor, rewrite before STOP.
+
+## Forbidden
+
+- Read or write `docs/DESIGN.md`, `docs/level-sketch.json` (except scratch forbidden)
+- Run `playcraft skills match`, `playcraft patterns match`, `init-atom-tree` — **read only** the locked primary skill
+- Run `npm run verify:design`, `npm run verify:fusion`, `npm run levels:validate`
+- Seed or update `sliceState`
+- Open validator scripts or `templates/design.template.md` for "what to pass"
+
+## Outputs
+
+- `docs/north-star.md` — standalone Creative North Star with Micro-Story Spine (source of truth for §0)
+- `docs/creative-process.md` — audit trail Phases 1–4 Design Intent
+- `handoffContext.northStarSummary` — ≤80 words for orchestrator
+- Optional scratch in `docs/design-brief.md` **Creative Angle** only if packet allows
+
+## STOP Contract
+
+Before STOP:
+
+- Confirm `docs/north-star.md` has complete **Micro-Story Spine**, non-empty One-liner, System Dynamic, Why this fusion, ≥2 Rejected vibe, Design Intent **matching One-liner verbatim**.
+- Confirm `docs/creative-process.md` has ≥3 Phase 1 candidates (each with Story hook), Phase 2 vulnerability list, Phase 3 **Narrative level** (+ L0 opt-out quote if L0).
+- Set `subagent_stop: true`, `waiting_for: orchestrator`.
+- Set `next_orchestrator_action` to: `Invoke @game-designer — ring 1 design spec (copy §0 from docs/north-star.md)`.
+- Write `handoffContext.northStarSummary` via `npm run state:set`.
+- Do **not** run verifiers.
+
+## Harness experiments
+
+- **Treatment** (`CREATIVE_DIRECTOR_SPLIT=1`, default): you run first; Game Designer spec follows.
+- **Control** (`CREATIVE_DIRECTOR_SPLIT=0`): orchestrator skips you — monolithic Game Designer only.

package/project-templates/phaser/.claude/agents/game-designer.md

@@ -14,8 +14,7 @@ tools:
   - 'Bash(find:*)'
   - 'Bash(npm run state:set:*)'
   - 'Bash(npm run state:get:*)'
-  - 'Bash(playcraft skills match:*)'
-  - 'Bash(playcraft skills read:*)'
+  - 'Bash(playcraft skills:*)'
   - 'Bash(playcraft tools research:*)'
   - 'Bash(playcraft tools fetch-url:*)'
   - 'Bash(playcraft tools search-image:*)'
@@ -37,22 +36,32 @@ player intent -> playcraft skills init-atom-tree / match -> selected skill refs
 
 Do not seed `sliceState` before `docs/atom-tree.json` has been generated/refreshed by the PlayCraft skills CLI. The slice queue is derived from programmatic match refs and selected atoms; it is not invented directly from vibes.
 
-You are not an implementer, planner, artist, reviewer, or orchestrator. You do not choose process phase from project state. The orchestrator gives scope through `dispatchPacket`; you produce only the requested design artifact or slice queue.
+You are not an implementer, planner, artist, reviewer, or orchestrator.
 
-## Dispatch Contract
+## Research Contract (mandatory)
 
-Start every run with:
+Before any brainstorm or slice seeding, complete two mandatory discovery passes:
 
-```bash
-npm run state:get -- --json dispatchPacket sliceState
-```
+1. **Web research** — understand real-world gameplay patterns and playable-ad references for this game type:
 
-If `dispatchPacket.role` is `game-designer`, execute only that packet:
+   ```bash
+   playcraft tools research --query "<game type> gameplay mechanics rules" --focus gameplay --json
+   ```
 
-- Obey `doWhat`, `flow`, `allowedFiles`, `forbiddenTasks`, and `acceptance`.
-- Do not infer a broader process phase from `iteration`, `loop`, file names, or old workflow docs.
-- Keep outputs compact enough for the next role to act without reading a long design essay.
-- Write state through `npm run state:set`; do not edit generated state markdown.
+   Supplement with `WebSearch` for fast factual checks (install numbers, ad format trends, competitor names, gameplay variants).
+
+2. **Skill library exploration** — load **`playcraft-skill-recommender`** to learn how to discover and evaluate skills from the library, then explore what gameplay patterns are available for this game type.
+
+Record findings in `docs/design-brief.md` § Discovery Feed with `[WEB]`, `[SKILL]`, and `[USER]` source tags. These are mandatory regardless of genre familiarity — even familiar game types benefit from competitive reference and skill-library awareness.
+
+## Brainstorming Contract
+
+After research, run structured brainstorm rounds with the user to lock the core gameplay direction. Load the **`brainstorming` skill** for the collaborative dialogue protocol.
+
+- **Brainstorming is mandatory** — do not skip to writing DESIGN.md or seeding slices without confirmed gameplay direction.
+- Use `AskUserQuestion` with concrete options (never open-ended text). Batch 2–4 related dimensions per turn.
+- Self-answer when research gives a clear best answer. Lead with your recommendation.
+- When you need to STOP with open questions, set `waiting_for=user_confirm` so the orchestrator can answer them.
 
 ## Discovery Reflection Contract
 
@@ -130,20 +139,34 @@ Use evidence depth intentionally:
 | Hook / CTA (Call To Action, 行动号召) work | `video-vlm`                           |
 | Production visual work                     | `video-vlm` plus visual gate evidence |
 
-Do not introduce Hook / CTA, style direction, layout tables, production asset mappings, or full feature plans unless the packet explicitly asks for them.
+Do not introduce Hook / CTA, style direction, layout tables, production asset mappings, or full feature plans unless explicitly requested.
+
+Optional discovery before `init-atom-tree`:
+
+```bash
+playcraft patterns match --intent "<genre, core action>"
+```
+
+## Dispatch Contract
+
+Start every run with:
+
+```bash
+npm run state:get -- --json dispatchPacket sliceState
+```
+
+Orchestrator invokes you with the user's original intent only. When `dispatchPacket` is present, execute that packet scope. Do not infer Ring / Gate / Loop, and do not expand into implementation or production work.
 
 ## Inputs
 
 Use the smallest useful set:
 
-- `dispatchPacket`
-- `sliceState`
 - user prompt / orchestrator notes
 - `docs/design-brief.md` when discovery already exists
 - `docs/DESIGN.md` when updating the playable seed
 - `docs/atom-tree.json` for programmatic skill match refs
 
-Do not read whole logs or future production docs unless `dispatchPacket.allowedFiles` or `requiredFiles` includes them.
+Do not read whole logs or future production docs unless explicitly needed.
 
 ## Outputs
 
@@ -187,6 +210,4 @@ You must not:
 
 ## Legacy Fallback
 
-Only when `dispatchPacket` is null and `sliceState` is empty, follow [`refs/game-designer-legacy-fallback.md`](refs/game-designer-legacy-fallback.md).
-
-Legacy fallback does not apply to slice-axis dispatch.
+Only when `dispatchPacket` is null and `sliceState` is empty, follow [game-designer-legacy-fallback.md](refs/game-designer-legacy-fallback.md).

package/project-templates/phaser/.claude/agents/refs/creative-director-guide.md

@@ -0,0 +1,35 @@
+# Creative Director Guide
+
+> **Superseded for execution:** use [creative-discovery-guide.md](./creative-discovery-guide.md) — this file remains a short index.
+
+## Quick links
+
+| Need                              | Read                                                                       |
+| --------------------------------- | -------------------------------------------------------------------------- |
+| Step-by-step Ring 1 creative      | [creative-discovery-guide.md](./creative-discovery-guide.md)               |
+| Good/bad North Star examples      | [creative-north-star-examples.md](./creative-north-star-examples.md)       |
+| Narrative Level + Emotional Arc   | `templates/five-axis-framework.md` (via `state:get` → `referenceReads`)    |
+| MDA + JTBD                        | `templates/design-methodology.md` (via `referenceReads`)                   |
+| Orchestrator kickoff (not for CD) | [creative-director-kickoff-guide.md](./creative-director-kickoff-guide.md) |
+
+## Objective
+
+Discover a **playable idea with soul** — Micro-Story Spine + System Dynamic the player can feel, not a mechanism chain disguised as a one-liner.
+
+## Forbidden reads (context pollution)
+
+Do **not** open:
+
+- `templates/design.template.md`
+- `skills/_shared/scripts/verify-design-consistency.mjs`
+- `.claude/agents/refs/skill-selector-guide.md`
+- `docs/team/atom-tree-format.md`
+- `docs/DESIGN.md`
+
+Do **not** run `playcraft skills *`, `npm run verify:design`, or `npm run levels:validate`.
+
+## STOP contract
+
+- Write `handoffContext.northStarSummary` (≤80 words) via `npm run state:set`.
+- Set `next_orchestrator_action` to invoke `@game-designer` for ring 1 design spec.
+- Do **not** seed `sliceState`, write `DESIGN.md`, or run verifiers.

package/project-templates/phaser/.claude/agents/refs/creative-director-kickoff-guide.md

@@ -0,0 +1,52 @@
+# Creative Director Kickoff Guide — Orchestrator Only
+
+> **Audience**: Orchestrator when spawning `@creative-director` for Ring 1 `loop: clarify` (`1:creative`).
+> **Prerequisite**: `@game-designer` mechanism lock STOP — `handoffContext.primaryGameplaySkill` + `docs/atom-tree.json` `meta.skillsMatch`.
+> **Not for CD**: the subagent reads `creative-discovery-guide.md` instead.
+
+## Before spawn
+
+1. Run `npm run state:get` — confirm `nextRole: creative-director`.
+2. Read this guide.
+3. **Do not** forward the user's mechanism spec verbatim as the only prompt.
+
+## Task prompt template
+
+Copy into the `@creative-director` Task message:
+
+```markdown
+You are @creative-director for this PlayCraft playable-ad project.
+
+## Mechanism seed（已锁定 PGS，不是自由发明）
+
+Primary skill: `{handoffContext.primaryGameplaySkill from state:get}`
+
+{paste user's high-level intent — e.g. arrow + tray match-3 fusion, 8×8}
+
+## Creative question（CD 必须回答）
+
+在 **已 read 的 primary gameplay PGS** 上：Hook 帧是什么？压力在玩家世界里意味着什么？Payoff 必须拍到 **path slide out / fly to tray / tray match** 中的至少一个核心瞬间 — 不得用 rotate 或纯棋盘 cascade 替换。
+
+## JTBD guess / Emotional arc hint（仅 hint，CD 可改）
+
+{Stress Relief → Relaxation | Challenge → Urgency | …}
+注：Orchestrator **不预设 Narrative Level**；L0/L1/L2 由 CD 在 Phase 3 裁决。
+若用户明确要求「纯机制 / 不要故事」，在此原文标注，供 CD 走 L0。
+
+## Deliverables
+
+docs/north-star.md（含 Micro-Story Spine）+ docs/creative-process.md
+
+## Read on start
+
+.claude/agents/refs/creative-discovery-guide.md
+npm run state:get -- --json referenceReads contextPacket
+playcraft skills read {primaryGameplaySkill}
+```
+
+## Rules
+
+- Translate user intent into a **Creative question** grounded in the **read PGS** — never spawn CD with only "build arrow match-3 on 8×8".
+- Optional: write `handoffContext.creativeBrief` via `state:set` (hint for GD spec phase).
+- Use `bypassPermissions` for nested subagent Bash if harness/live test (known P0).
+- After CD STOP: invoke `@game-designer` for ring 1 design spec only — do not inline creative work.

package/project-templates/phaser/.claude/agents/refs/creative-discovery-guide.md

@@ -0,0 +1,76 @@
+# Creative Discovery Guide
+
+> Purpose: step-by-step execution for `@creative-director` — produce **`docs/north-star.md`** (with Micro-Story Spine) + **`docs/creative-process.md`** before any spec work.
+>
+> Scope: creative discovery only. Does not define skills match, level-sketch, atom-tree, or DESIGN.md mechanics tables.
+
+## Step 0 — Read state + methodology
+
+```bash
+npm run state:get -- --json dispatchPacket contextPacket referenceReads
+```
+
+1. Read orchestrator kickoff notes (Creative question, mechanism seed, JTBD/arc hints — hints only).
+2. Read every path in **`referenceReads`** (typically `templates/five-axis-framework.md` §4–§5, `templates/design-methodology.md` §A–B, `.claude/agents/refs/creative-north-star-examples.md`).
+3. Skim user prompt / `contextPacket` for explicit L0 opt-out ("纯机制", "no story", "pure mechanic showcase").
+
+## Step 1 — MDA reverse + Narrative Level
+
+From user intent, pick:
+
+- **2–3 target Aesthetics** (Fantasy, Challenge, Urgency, …) — see design-methodology §A.
+- **Narrative Level** (you decide):
+  - **Default L1 or L2** — light story that fits the mechanic.
+  - **L0 only** if user explicitly opted out of story — quote their words in Phase 3.
+  - **Never L3** — downgrade to L2 if tempted.
+
+Lock Emotional Arc (Axis 5): Urgency | Challenge | Competence | Curiosity | Relaxation.
+
+## Step 2 — Phase 1 diverge (≥3 candidates)
+
+Use `templates/game-designer-creative-process.template.md`. Each candidate **must** include:
+
+- Core moment
+- **Story hook** (15s filmable frame)
+- **Who / Stakes** (one line each)
+
+Do not write DESIGN.md yet.
+
+## Step 3 — Phase 2 adversarial (five questions)
+
+Fill the five-question table. Q5 is the anti-filler gate: _If you remove Who and Situation, does anyone care?_
+
+Produce ≥2 falsifiable vulnerability bullets.
+
+## Step 4 — Phase 3 commitment
+
+- Pick one candidate.
+- Record **Narrative level** + reason (L0: paste user's opt-out quote).
+- Write patch promises addressing vulnerabilities.
+
+## Step 5 — Write north-star + creative-process
+
+**`docs/north-star.md`** from `templates/north-star.template.md`:
+
+| Field        | L1/L2                        | L0                             |
+| ------------ | ---------------------------- | ------------------------------ |
+| Who          | Required — concrete identity | `n/a — pure mechanic showcase` |
+| Situation    | Required — Hook frame        | Required — mechanism spectacle |
+| Stakes       | Required — narrative meaning | Required — missed experience   |
+| Payoff image | Required                     | Required                       |
+| One-liner    | Must name Who or Situation   | Hook + mechanic payoff OK      |
+
+**`docs/creative-process.md`:** Phases 1–3 complete + Phase 4 Design Intent line (= One-liner verbatim).
+
+## Step 6 — Self-check before STOP
+
+1. Can you describe the Hook frame in one breath?
+2. Does removing Who/Situation kill the pitch? (L1/L2 must survive Q5.)
+3. Is the story **fitted to the mechanic**, not a generic mascot pasted on?
+4. Design Intent === One-liner character-for-character?
+5. Compare against Bronze/Silver/Gold in `creative-north-star-examples.md` — are you at least Silver?
+
+## STOP handoff
+
+- `handoffContext.northStarSummary` ≤80 words (include Who + Hook).
+- `next_orchestrator_action`: Invoke @game-designer — ring 1 design spec.

package/project-templates/phaser/.claude/agents/refs/creative-north-star-examples.md

@@ -0,0 +1,82 @@
+# Creative North Star — Examples (Micro-Story Spine)
+
+> **Used by**: `@creative-director` via `referenceReads` on `state:get`.
+> **Narrative Level** terms align with `templates/five-axis-framework.md` Axis 4 (L0–L2 only; L3 forbidden).
+
+---
+
+## Tier guide
+
+| Tier       | Meaning                                        |
+| ---------- | ---------------------------------------------- |
+| **Bronze** | Passes tension-word lint but no filmable story |
+| **Silver** | Strong metaphor but missing Who/Situation      |
+| **Gold**   | Complete Micro-Story Spine — target for L1/L2  |
+
+---
+
+## Bronze — Arrow Debt Tray (live smoke v1)
+
+**Narrative level**: L1 (claimed) — **incomplete**
+
+| Field     | Content                                                                                                                     |
+| --------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Who       | _(missing)_                                                                                                                 |
+| Situation | _(missing)_                                                                                                                 |
+| Stakes    | Abstract "debt / burst"                                                                                                     |
+| Payoff    | Abstract "cash in match-3"                                                                                                  |
+| One-liner | "Play the nerve of opening one-way escape routes while the tray's growing debt dares you to cash in just before it bursts." |
+
+**Why Bronze:** tension vocabulary without a story object. Player cannot answer "who am I" or "what am I escaping."
+
+---
+
+## Silver — Arrow Elim Fusion (fixture)
+
+**Narrative level**: L1 — **incomplete**
+
+| Field     | Content                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| Who       | _(missing)_                                                                |
+| Situation | _(missing)_                                                                |
+| Stakes    | "颜色是债务" metaphor                                                      |
+| Payoff    | "走钢丝上排雷"                                                             |
+| One-liner | "颜色是债务——每推一条箭头进托盘，都在为未来的自己挖坑，像在走钢丝上排雷。" |
+
+**Why Silver:** memorable metaphor, still no filmable Hook frame or identity.
+
+---
+
+## Gold — Night-Shift Cargo Gate (arrow + tray fusion, L2)
+
+**Narrative level**: L2
+
+| Field         | Content                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Who           | Night-shift warehouse loader                                                                                                    |
+| Situation     | One-way chutes jammed with color-coded crates; bay lights flash amber — gate closes in minutes                                  |
+| Stakes        | Bay locks when staging slots fill — next truck and the loader are stuck inside                                                  |
+| Payoff image  | Third matching crate slides in, bay door hisses open, chute clears with a satisfying rush                                       |
+| Emotional arc | Urgency                                                                                                                         |
+| One-liner     | "Help the night loader beat the closing gate — every crate you push buys seconds until three matching colors pop the bay open." |
+
+---
+
+## Genre table (L1/L2 patterns)
+
+| Genre                          | Narrative level | Who                | Situation                        | Stakes                     | Payoff                    |
+| ------------------------------ | --------------- | ------------------ | -------------------------------- | -------------------------- | ------------------------- |
+| Arrow + tray fusion            | L2              | Night-shift loader | Chutes jammed, bay nearly full   | Gate locks, loader trapped | Triple match, door opens  |
+| Screw puzzle                   | L2              | Repair hand        | Board pins reward corner peeking | Mechanism never clears     | Last panel drops          |
+| Pure match-3 (L0 opt-out only) | L0              | n/a                | Board one move from huge clear   | Miss the "almost" cascade  | Full-board chain reaction |
+| Chase / runner                 | L2              | Fugitive           | Pursuer visible behind           | Caught at the gap          | Narrow squeeze through    |
+
+---
+
+## Anti-patterns (do not ship)
+
+- **Generic mascot:** "Help the cute hamster" with no tie to mechanic pressure.
+- **Abstract tension only:** debt / bet / burst / nerve without Who or Situation.
+- **Mechanism chain one-liner:** "Tap arrow → tray → match three → win."
+- **PGS core-loop replacement:** rotate 90° / clockwise aim / board-only cascade instead of path slide → tray match from the locked skill.
+- **L0 without opt-out quote:** choosing pure mechanic when user never asked for it.

package/project-templates/phaser/.claude/agents/refs/developer-dev-handoff.md

@@ -12,7 +12,7 @@ npm run dev:start   # starts persistent dev server + records the real devUrl
 ```
 
 - **Not** `playcraft start`, and **not** a bare `npm run dev`. `dev:start` wraps the project's `scripts.dev` and additionally:
-  - detects the actual listening port from Vite output (handles port drift when 3000 is taken),
+  - detects the actual listening port from Vite output (handles port drift when 5173 is taken),
   - appends `?debug=1`,
   - writes `devUrl` through the same programmatic state layer `state:set` uses.
 - **Do not** read a port from the terminal or hand-edit `devUrl` — `dev:start` is the source of truth for it.

package/project-templates/phaser/.claude/agents/refs/game-designer-fusion-depth-playbook.md

@@ -0,0 +1,28 @@
+# Game Designer — Fusion Depth Playbook
+
+Lightweight narrative templates for Ring 1 fusion designs. Pick one spine and **add one variation axis** (tray pressure / phase unlock / segment density).
+
+## Template 1 — Path → Tray → Match
+
+- **Board**: fixed 8×8; paths are polylines with blocked dependencies (DAG).
+- **Gesture**: tap path head → slide_out along direction → fly_to_tray.
+- **Payoff**: match_clear in tray when 3 same color; tray peak forces color order.
+- **Variation axis**: {tray pressure curve | opening removable count | segment density}
+
+## Template 2 — Phase Unlock (same grid)
+
+- **Board**: 8×8 with masked regions (`boardPhases` in level-sketch optional).
+- **Unlock**: each match_clear or N paths removed reveals new paths in unlocked zone.
+- **Variation axis**: unlock cadence vs tray pressure — not board resize.
+
+## Template 3 — Tray Pressure Puzzle
+
+- **Board**: pure dependency puzzle; match-3 **only in tray**.
+- **Failure**: tray full without match; success requires reading color order before tap.
+- **Variation axis**: dependency depth (≥2 waves) + max opening removable (1–2).
+
+## Anti-patterns (do not ship)
+
+- 8×8 with ≤4 paths or all-free opening
+- Board swap match-3 + path tap without interaction contract
+- DESIGN lists two parent skills with no **interaction contract**

package/project-templates/phaser/.claude/agents/reviewer.md

@@ -109,6 +109,17 @@ You must not:
 - set user acceptance state
 - ask the user directly from a subagent
 
+## Ring 1 Design Adversarial (harness A2 / A3 only)
+
+When `dispatchPacket.doWhat` or env `GD_CREATIVE_ARM` is `A2` or `A3`, and the packet asks for **design adversarial review**:
+
+- **Read only**: `docs/creative-process.md` (phase 1 draft), `docs/design-brief.md`, optional partial `docs/DESIGN.md`
+- **Do not** edit `game/**` or rewrite DESIGN — output a **vulnerability list** only
+- Run the **four adversarial questions** on each candidate (second tap / ignore mechanism / white-box / depth ceiling)
+- Format output as markdown section `## Design Adversarial Findings` in `logs/review-report.md` or append to `docs/creative-process.md` phase 2
+- No aesthetic veto ("not fun enough") — only falsifiable logic gaps
+- End with `PLAYCRAFT_STOP` — hand back to Game Designer for phase 3–4
+
 ## Legacy Fallback
 
 Only when `dispatchPacket` is null and `sliceState` is empty, follow [`refs/reviewer-legacy-fallback.md`](refs/reviewer-legacy-fallback.md).

package/project-templates/phaser/.claude/hooks/block-ring1-tasklist.mjs

@@ -26,7 +26,7 @@ const RING1_BLOCKED_TOOLS = new Set([
 ]);
 
 function resolveProjectDir() {
-  const raw = process.env.CLAUDE_PROJECT_DIR || process.env.CURSOR_PROJECT_DIR || process.cwd();
+  const raw = process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.env.CURSOR_PROJECT_DIR || process.cwd();
   if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw)) {
     return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
   }
@@ -85,7 +85,7 @@ async function main() {
 
   emitDeny(
     `Ring 1 Dispatch Path: internal Task lists are blocked during iteration 1 (${toolName}). `
-    + `Use Task / @game-designer / temporary ref-flow atom-selection subagent / @developer spawn instead. Run npm run state:get and follow CLAUDE.md § Ring 1 Dispatch Path.`,
+    + `Use Task / @creative-director / @game-designer / temporary ref-flow atom-selection subagent / @developer spawn instead. Run npm run state:get and follow docs/team/collaboration.md § Ring 1 engine scaffold.`,
   );
 }