@playcraft/cli 0.0.40 → 0.0.41

package/project-template/.claude/agents/refs/designer-deliverable-spec.md

@@ -0,0 +1,167 @@
+# Designer — Deliverable spec (designer-handoff-v2)
+
+> **When to read**: Before generating Master Composite, ASR, audio, or digit strip. Cross-reference `playcraft-storyboard`, `playcraft-asset-state-sheet`, `playcraft-text-rendering`, `playcraft-image-generation`, and `refs/designer-handoff-v2-checklist.md`.
+
+## Resolution Strategy
+
+AI image models support up to **4K output** (~4096px per side). Individual game assets only need **~720p**. Pack multiple assets into one generation for style consistency and fewer API calls. TA achieves per-asset dimensions via crop/resize from MC/ASR.
+
+All image generation MUST use maximum supported resolution.
+
+## Text-as-Image Strategy
+
+All visible text is image assets — **zero font files**. Static text is baked into the MC concept panel; dynamic numbers use a Digit Sprite Strip.
+
+> **Invoke `playcraft-text-rendering`** for static-text extraction (TA default) and digit strip (Designer Phase 2).
+
+### Static text (default)
+
+| Step                           | Role                                        |
+| ------------------------------ | ------------------------------------------- |
+| Bake into MC                   | Designer (concept panel)                    |
+| Extract to `layout-spec` paths | TA (`crop` / `segment`)                     |
+| Extract fails                  | ICP → Designer **one isolated PNG** per row |
+
+### Background (default)
+
+| Step                                  | Role                                                             |
+| ------------------------------------- | ---------------------------------------------------------------- |
+| Extract from MC concept panel         | TA → `layout-spec` bg path                                       |
+| 2.5D / hero bg needs dedicated sample | PM marks VisualAtom `assignTo: Designer` → ICP isolated PNG only |
+
+## Phase 1 Deliverables
+
+Gate #2a: **one MC per option** + Experience Flow text. Gate #2b (after `selectedMcOption`): **ASR dual sheets** + **Handoff Pack** (below).
+
+| #   | Deliverable                       | Format | Spec                                                       |
+| --- | --------------------------------- | ------ | ---------------------------------------------------------- |
+| 1   | **Master Composite**              | PNG 4K | 5 panels: concept + 4 storyboard scenes                    |
+| 2a  | **UI State Reference Sheet**      | PNG 4K | UI/HUD per interaction state                               |
+| 2b  | **Element State Reference Sheet** | PNG 4K | Gameplay elements per event/special state                  |
+| 3   | **Experience Flow Design**        | Text   | `style-exploration.md`                                     |
+| 4   | **Gate #2b Handoff Pack**         | Text   | `designer-log.md` + Motion Notes in `style-exploration.md` |
+
+> **ASR** = authoring-time reference sprite sheets. **Not** runtime `.webp` + `.json` atlases (TA in `production`).
+
+Every generation outputs a sidecar `.json` (prompt + parameters).
+
+---
+
+### Deliverable 1: Master Composite
+
+> **Skills**: `playcraft-storyboard` + `refs/designer-master-composite-recipes.md`
+
+| #   | Panel              | Content                                              |
+| --- | ------------------ | ---------------------------------------------------- |
+| 1   | Main Gameplay      | Full game shot: all element types + static text + UI |
+| 2   | Key Hook           | 0–3s highlight                                       |
+| 3   | Onboarding HUD     | Tutorial + finger                                    |
+| 4   | End Card           | Win + Install CTA                                    |
+| 5   | CTA Always Visible | In-game CTA persistent                               |
+
+Paths: `assets/images/storyboard/master_composite_option_[A|B|C].png`
+
+**MC options count**: ≥2 before Gate #2a (see option table in prior spec — 2 or 3 by clarity).
+
+---
+
+### Deliverable 2: ASR
+
+> **Skill**: `playcraft-asset-state-sheet`
+
+Only after `selectedMcOption` is set. `--reference-image` = confirmed MC.
+
+```
+assets/images/reference/ui_state_sheet_[X].png
+assets/images/reference/element_state_sheet_[X].png
+```
+
+---
+
+### Gate #2b Handoff Pack (mandatory before `#2b` STOP)
+
+> **Checklist**: `refs/designer-handoff-v2-checklist.md`
+
+#### 1. ASR Coverage Matrix (`logs/designer-log.md`)
+
+One row per contract item from `layout-spec.md`:
+
+| Contract id                     | Type   | ASR sheet    | Grid    | State(s)     | TA extends? |
+| ------------------------------- | ------ | ------------ | ------- | ------------ | ----------- |
+| `elementId` from assetMapping   | visual | ui / element | row,col | e.g. default | yes/no      |
+| `staticTextId` from Text Assets | text   | ui / MC crop | —       | baked        | yes/no      |
+
+**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row. Empty ASR slot → `TA extends? = yes` + note in Style Intent Notes.
+
+#### 2. Palette Locked (`logs/designer-log.md`)
+
+- 6–10 hex swatches sampled from confirmed MC (background, accent, CTA, key elements).
+- One line: **delta vs `layout-spec` Color Palette** (match / PM update needed).
+
+#### 3. Motion Notes (`docs/style-exploration.md`)
+
+Per transition (Hook→Tutorial, Tutorial→Gameplay, Gameplay→EndCard):
+
+| Field            | Example                                      |
+| ---------------- | -------------------------------------------- |
+| Transition type  | fade / zoom / swipe / burst                  |
+| Duration band    | ~200ms / ~500ms / ~1s                        |
+| Audio cue tie-in | optional ref to Experience Flow audio rhythm |
+
+No per-frame animation assets — VFX/Animation atoms remain TA.
+
+#### 4. Style Intent + Anti-Pattern Notes
+
+Existing `designer-log` sections — required for TA Step 0c.
+
+---
+
+### Phase 1 exception: True 3D
+
+When `design-brief` dimension = True 3D, Designer also delivers (Phase 1, same Gate #2b):
+
+- 2D reference texture PNG at path noted in `designer-log` (see `refs/designer-dimension-axis.md`).
+- TA runs `generate-3d`; Designer does **not** output GLB.
+
+---
+
+## Phase 2 Deliverables — Audio + Digit + Atom status
+
+**Designer does not batch-export visual samples at `assetMapping` paths in v2.** Visual baseline = Phase 1 MC + ASR.
+
+| #   | Deliverable            | Format | Spec                                  |
+| --- | ---------------------- | ------ | ------------------------------------- |
+| 1   | **BGM**                | MP3    | Mood matches locked MC                |
+| 2   | **SFX**                | MP3    | One per interaction in `assetMapping` |
+| 3   | **Digit sprite strip** | PNG    | `layout-spec` `textAssets.digitStrip` |
+| 4   | **VisualAtom status**  | —      | See below                             |
+
+### VisualAtom rules (`atom-plan.json` → `atoms[]`)
+
+For each `assignTo: Designer` VisualAtom:
+
+| Condition                           | `status`  | `actualOutput`                                                                      |
+| ----------------------------------- | --------- | ----------------------------------------------------------------------------------- |
+| Type covered in ASR Coverage Matrix | `done`    | `ASR:ui_state_sheet_[X]:R{row}C{col}` or `ASR:element_state_sheet_[X]:R{row}C{col}` |
+| Not covered; ICP gap                | `blocked` | ICP id + path when file delivered                                                   |
+| ICP supplementary PNG delivered     | `done`    | file path                                                                           |
+
+**Forbidden**: mark VisualAtom `done` without ASR row or supplementary file.
+
+Run **`playcraft-style-qa` §1** only for **ICP supplementary** image files (not for ASR sheets themselves).
+
+### TA ownership in Phase 2 (not Designer)
+
+- Static text extraction → contract paths
+- Background webp
+- VisualAtom completions, sprite sheets, 3D, VFX, atlases
+
+### Bundle Structure (audio)
+
+```
+assets/bundles/<atomId>.aiaudio/
+  ├── manifest.json
+  └── <filename>.mp3
+```
+
+Supplementary images (ICP only): `.aiimage/` bundle format.

package/project-template/.claude/agents/refs/designer-dimension-axis.md

@@ -0,0 +1,27 @@
+# Designer Dimension Axis Workflow
+
+> Read in Phase 1 after confirming Dimension Axis from `docs/design-brief.md`. **designer-handoff-v2**: visual baseline = MC + ASR (not scattered sample PNGs). TA handles mass production.
+
+## Flat 2D (Standard)
+
+- **MC** concept panel shows all element types + UI + static text.
+- **ASR** element sheet: 2–3 states per type (idle / selected / matched).
+- TA: bg extract, completions, atlases, VFX.
+
+## 2.5D Visual (Depth Layers)
+
+- MC concept panel: perspective scene + layered elements.
+- ASR: angled sprites in element sheet; note depth layers in Style Intent Notes.
+- Background: default **TA extract from MC**; dedicated bg sample only if PM atom `assignTo: Designer` via ICP.
+
+## Isometric
+
+- ASR element sheet: representative isometric tiles (2–3 states).
+- Optional: `playcraft tools search-image` for reference.
+- TA: remaining tiles, atlas, animation.
+
+## True 3D
+
+- Designer does **not** output GLB.
+- Phase 1 Gate #2b: 2D reference texture PNG (path in `designer-log`) per `designer-deliverable-spec.md` § Phase 1 exception.
+- TA: `generate-3d`, GLB, flip sprites.

package/project-template/.claude/agents/refs/designer-handoff-v2-checklist.md

@@ -0,0 +1,68 @@
+# Designer Handoff v2 — Gate #2b checklist
+
+> Read at **Step 5** of `designer-style-exploration-flow.md` before `gates.#2b = pending` STOP.
+
+## Prerequisites
+
+- [ ] `workflowSpecVersion` = `designer-handoff-v2` in `project-state.md` (or migrating per `workflow-changelog.md`)
+- [ ] `selectedMcOption` set (Gate #2a passed)
+- [ ] MC path: `assets/images/storyboard/master_composite_option_[X].png`
+- [ ] ASR paths exist and pass zero-overlap visual check
+
+## 1. ASR Coverage Matrix (100%)
+
+In `logs/designer-log.md` § ASR Coverage Matrix:
+
+1. List every `elementId` from `layout-spec.md` § Asset Mapping (and atlas `frameId` groups count as one row per logical element).
+2. List every static text `id` from § Text Assets → Static Text.
+3. For each row: `ASR sheet` = `ui` | `element` | `MC-crop` | `ICP-pending`.
+4. `TA extends?` = `no` only when ASR shows final representative state; else `yes`.
+
+**Stop rule**: any row missing → do not set `#2b` pending.
+
+## 2. Palette Locked
+
+```markdown
+## Palette Locked (from MC option [X])
+
+| Role       | Hex       | Notes |
+| ---------- | --------- | ----- |
+| bg_primary | #**\_\_** |       |
+| accent     | #**\_\_** |       |
+| cta        | #**\_\_** |       |
+| element_1  | #**\_\_** |       |
+
+**Delta vs layout-spec**: match | PM update: <one line>
+```
+
+## 3. Motion Notes
+
+In `docs/style-exploration.md` under confirmed option:
+
+| Transition          | Type | Duration | Notes |
+| ------------------- | ---- | -------- | ----- |
+| Hook → Tutorial     |      |          |       |
+| Tutorial → Gameplay |      |          |       |
+| Gameplay → End Card |      |          |       |
+
+## 4. Phase 2 VisualAtom decision tree
+
+```
+For each atom-plan row where assignTo = Designer:
+├─ VisualAtom + covered in Coverage Matrix?
+│   └─ yes → status=done, actualOutput=ASR:...
+├─ AudioAtom?
+│   └─ deliver MP3 at path → done
+├─ Gap / TA extract failed (ICP)?
+│   └─ generate one PNG → done with path, or blocked until answered
+└─ Never: done with only "will extract later"
+```
+
+## 5. Files to verify before STOP
+
+| File                                                  | Contains                                                    |
+| ----------------------------------------------------- | ----------------------------------------------------------- |
+| `docs/style-exploration.md`                           | MC paths, Motion Notes, Experience Flow                     |
+| `logs/designer-log.md`                                | Coverage Matrix, Palette Locked, Style Intent, Anti-Pattern |
+| `assets/images/reference/ui_state_sheet_[X].png`      | exists                                                      |
+| `assets/images/reference/element_state_sheet_[X].png` | exists                                                      |

package/project-template/.claude/agents/refs/designer-master-composite-recipes.md

@@ -0,0 +1,216 @@
+# Master Composite — 游戏类型 Prompt 配方 & 参考
+
+> 本文件供 Designer 在生成 Master Composite 时按需查阅。核心规则见 `playcraft-storyboard` skill。
+
+## 模型多样性策略
+
+每个风格方案使用**不同的图片模型**，探索不同视觉可能性。先运行：
+
+```bash
+playcraft tools list-image-models
+```
+
+### 推荐分配策略
+
+| 方案                   | 推荐模型类型                                        | 原因                               |
+| ---------------------- | --------------------------------------------------- | ---------------------------------- |
+| Option A（最精细方案） | `gpt-image-2`                                       | 最高质量，细节最丰富，适合主推方案 |
+| Option B（风格化方案） | `gemini-3.1-flash-image-preview` 或 `hy-image-v3.0` | 风格更鲜明、艺术感更强             |
+| Option C（探索方案）   | `flux-kontext-pro` 或 `nano-banana-2`               | 不同画风，提供对比参考             |
+
+> 若只有 1-2 个方案，仍建议用不同模型生成同一方案，对比后选最佳。
+
+### 模型特性速查
+
+| 模型                             | 特点                                     | 适合风格               |
+| -------------------------------- | ---------------------------------------- | ---------------------- |
+| `gpt-image-2`                    | 细节丰富、光影真实、多 provider fallback | 写实、半写实、精细卡通 |
+| `gemini-3.1-flash-image-preview` | 色彩鲜艳、构图清晰、速度快               | 明亮卡通、休闲风       |
+| `hy-image-v3.0`                  | 亚洲审美偏向、角色设计好                 | IP 风格、Q 版角色      |
+| `flux-kontext-pro`               | 艺术感强、风格独特                       | 手绘风、艺术插画       |
+| `nano-banana-2`                  | 快速、适合探索                           | 简洁图形、平面设计风   |
+
+> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型，先用 `list-image-models` 确认。
+
+---
+
+## 游戏类型 Prompt 配方
+
+以下模板可直接复制修改。所有模板遵循 skill 中的 5 面板并排结构 + 编号标签。
+
+### Match-3 消除游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a match-3 puzzle game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — colorful candy gem grid on [BG_DESCRIPTION], all gem types visible ([TYPE_LIST]), HUD strip showing score and moves counter, 'Play Now' CTA button at bottom. [MASCOT_DESCRIPTION].
+
+Panel 2 '2. Key Hook': Gems exploding in chains, dynamic burst VFX, score [HIGH_SCORE], combo text visible, vivid colors, dramatic moment, high contrast, minimal UI.
+
+Panel 3 '3. Onboarding HUD': Finger tap icon pointing at two matching gems, soft glow highlight on target pair, simplified board, score reset, friendly guidance arrow, speech bubble with hint text.
+
+Panel 4 '4. End Card': Victory celebration — [DARK_BG], '[WIN_TEXT]', treasure chest with rewards, reward amount visible, 'Install Now' CTA button prominent, confetti.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot showing normal gameplay in progress, with 'Play Now' CTA button clearly visible at bottom-right during active play, proving CTA is always accessible.
+
+[STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI (HUD bar, score display, buttons). Consistent art style across all panels. Thin vertical dividers between panels. Each panel has its numbered label at the top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model [MODEL] \
+  --image-size 4K
+```
+
+---
+
+### 跑酷 / 平台跳跃游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for an endless runner game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — character running through [ENVIRONMENT], coin trail ahead, obstacles visible, HUD showing distance and coins collected, 'Play Now' button at bottom.
+
+Panel 2 '2. Key Hook': Character at maximum speed, motion blur, dynamic camera angle, dramatic lighting, speed lines, high contrast, minimal HUD.
+
+Panel 3 '3. Onboarding HUD': Jump arrow icon showing first obstacle, character highlighted with glow, simple environment, clear guidance text bubble.
+
+Panel 4 '4. End Card': Dark background, distance record display, 'Install Now' CTA button prominent, reward chest, achievement badges.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot with character dodging obstacles, 'Play Now' button clearly visible at bottom-right during active play.
+
+[STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI. Consistent art style across all panels. Thin vertical dividers. Numbered labels at top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model [MODEL] \
+  --image-size 4K
+```
+
+---
+
+### 卡牌 / 麻将游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a Mahjong Solitaire game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — Mahjong tile grid on dark green felt table, tiles with Chinese symbols, cute mascot character, HUD showing score and timer, 'Play Now' button at bottom. Rich warm lighting.
+
+Panel 2 '2. Key Hook': Near-win combo state — high score, combo text with golden sparkles, most tiles matched with golden borders, mascot excited expression, warm amber glow, dramatic tension.
+
+Panel 3 '3. Onboarding HUD': Clean simplified board, finger tap icon pointing at two matching tiles, speech bubble 'Tap matching tiles', score reset, progress indicator, mascot encouraging smile.
+
+Panel 4 '4. End Card': Victory — dark elegant background, '恭喜通关!' text in gold, treasure chest, reward amount with coin icon, 'Install Now' CTA button in contrasting color, golden confetti.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot showing active gameplay with tiles on board, score and timer visible, 'Play Now' button clearly visible at bottom-right during play.
+
+Premium casual style, warm amber lighting, traditional Chinese aesthetic with modern UI, glossy tile surfaces. All 5 panels portrait-oriented, left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model [MODEL] \
+  --image-size 4K
+```
+
+---
+
+### 射击 / 动作游戏
+
+```bash
+playcraft tools generate-image \
+  --prompt "Mobile game UI design sheet, 5 panels side by side in a horizontal row, each panel is a complete portrait-oriented mobile game screenshot for a casual shooting game. Each panel has a numbered label at the top.
+
+Panel 1 '1. Main Gameplay': Complete game screenshot — player aiming at enemies in [ENVIRONMENT], weapon visible, HUD showing ammo/health/score, 'Play Now' button at bottom.
+
+Panel 2 '2. Key Hook': Target reticle locking on enemy, muzzle flash, dramatic action lighting, high contrast, speed lines, minimal HUD.
+
+Panel 3 '3. Onboarding HUD': Aim crosshair tutorial overlay, slow-motion visual hint, simple enemy highlighted with marker, guidance text.
+
+Panel 4 '4. End Card': Dark background, victory text, loot box with rewards, 'Install Now' CTA button prominent.
+
+Panel 5 '5. CTA Always Visible': Mid-game screenshot with active combat, 'Play Now' button clearly visible at bottom-right during play.
+
+[STYLE_KEYWORDS]. All 5 panels portrait-oriented left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels at top." \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model [MODEL] \
+  --image-size 4K
+```
+
+---
+
+## 故障恢复
+
+### 问题：模型拒绝生成（content policy）
+
+```bash
+# 移除触发审查的词语，改用间接描述
+# "explosion, fire, destruction" → "dramatic burst effect, particle shower, vivid energy release"
+```
+
+### 问题：面板内容混淆（相邻面板之间内容串了）
+
+```bash
+# 方案 1：强化编号标签
+"Panel 1 '1. Main Gameplay' (leftmost):..., Panel 2 '2. Key Hook' (second from left):..."
+
+# 方案 2：加描述性分隔符
+"5 panels separated by clear vertical white dividers. Each panel has bold numbered header."
+```
+
+### 问题：面板间风格不统一
+
+```bash
+# 强化风格约束词
+# 原始："Consistent art style across all panels."
+# 强化版："All 5 panels MUST use identical art style, color palette, and character design. Same rendering style throughout. All panels depict the SAME game."
+```
+
+### 问题：某帧内容不清晰
+
+发现某帧表达不清晰时，**不必重新生成整张**，而是在 `style-exploration.md` 的 Experience Flow Design 章节补充文字说明。
+
+### 问题：Concept Panel 缺少某些元素类型
+
+```bash
+# 方案 1：在 prompt Panel 1 段明确列出 "all [N] element types visible: [逐个列出]"
+# 方案 2：接受当前 MC，由 ASR 双板补足（ASR 是 TA 的主要提取源）
+```
+
+---
+
+## Reference-Image 与多方案策略
+
+### 首个方案（无 reference）
+
+Master Composite 是 Phase 1 的**第一张生成图**，通常无前序图可作 reference：
+
+```bash
+playcraft tools generate-image \
+  --prompt "<5-panel prompt>" \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model gpt-image-2 \
+  --image-size 4K
+```
+
+### 后续方案（可选 reference）
+
+后续方案可用已生成的方案 A 作为风格参考：
+
+```bash
+playcraft tools generate-image \
+  --prompt "<方案 B prompt>" \
+  --output assets/images/storyboard/master_composite_option_B.png \
+  --reference-image assets/images/storyboard/master_composite_option_A.png \
+  --image-model [不同模型] \
+  --image-size 4K
+```
+
+### 输出命名规范
+
+```
+assets/images/storyboard/master_composite_option_A.png  ← 方案 A
+assets/images/storyboard/master_composite_option_B.png  ← 方案 B
+assets/images/storyboard/master_composite.png           ← Gate #2 确认后复制
+```
+
+Gate #2 确认后：
+
+```bash
+cp assets/images/storyboard/master_composite_option_[X].png assets/images/storyboard/master_composite.png
+```

package/project-template/.claude/agents/refs/designer-style-exploration-flow.md

@@ -0,0 +1,37 @@
+# Designer — Style exploration flow (Phase 1, steps 2–5)
+
+> **Scope**: After **Step 1 — Skill Discovery** in `agents/designer.md`, follow this document for MC generation through Gate #2b STOP. **Exit criteria** for Phase 1: see `agents/designer.md` Goals § Success criteria.
+>
+> **Deliverable shapes & tables**: `refs/designer-deliverable-spec.md`.
+
+**Trigger**: `project-state.md` stage = `style_exploration`
+
+## Step 2 — Generate Master Composite only (one image per option A/B[/C])
+
+- Follow `playcraft-storyboard` skill：**每格完整 9:16 H5**；`45:16` + `--width 3600 --height 1280`（2K）或 `4096×1455`（4K）；**禁止 `1:1` / `10:3`**
+- 每个方案用不同模型（见 `refs/designer-master-composite-recipes.md`）
+- 生成后立即 `playcraft image info`：总比例 **width/height ≈ 2.81**，**(width÷5)/height ≈ 0.5625**；不合格则重生成
+- **Review the auto-generated `.json` sidecar** — 确认 `aspectRatio` / `imageSize` / 实际像素正确
+
+## Step 3 — Gate #2a package（MC 选型材料）
+
+1. 写入 `docs/style-exploration.md` 的 **Master Composite 部分**（每套方案的路径、风格关键词、体验流文字说明；**此时不写 ASR 路径**）
+2. 更新 handoff + `gates.#2a = pending`（见 `agents/designer.md` **Runtime**）
+3. **STOP** — 禁止 ASR（资产状态参考精灵图板）
+
+## Step 4 — Generate ASR sheets（仅针对 `project-state.selectedMcOption`）
+
+- Read `selectedMcOption` from `docs/project-state.md` — if missing, **STOP**
+- Follow `playcraft-asset-state-sheet` skill
+- 输出两张 4K 板：`ui_state_sheet_[X].png` + `element_state_sheet_[X].png`（见 `designer-deliverable-spec.md` §2）
+- `--reference-image` = `master_composite_option_[selectedMcOption].png`
+- 生成后 `playcraft image info` 检查；若槽位重叠，必须重生成
+
+## Step 5 — Gate #2b Handoff Pack
+
+> **Checklist**: `refs/designer-handoff-v2-checklist.md`
+
+1. 补全 `docs/style-exploration.md`（ASR 路径、**Motion Notes**、Experience Flow）
+2. 更新 `logs/designer-log.md`：**ASR Coverage Matrix**（100% contract rows）、**Palette Locked**、Style Intent / Anti-Pattern
+3. 更新 handoff + `gates.#2b = pending`
+4. **STOP** — 禁止 Phase 2 音频与批量视觉样本 PNG

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

@@ -0,0 +1,109 @@
+# Developer Dev Handoff (L2)
+
+Use during **Phase 2 integration** and before marking `devStatus: ready`.
+
+## Dev command
+
+```bash
+cat package.json   # read scripts.dev (webpack / vite / etc.)
+npm run dev
+```
+
+- **Not** `playcraft start` — Dev is the project's `scripts.dev`.
+- Record the URL from terminal output (e.g. `http://localhost:5173`) in `project-state.md` → `devUrl`.
+- Prefer leaving the server running for Reviewer; if it stops, Reviewer or orchestrator may restart and refresh `devUrl`.
+
+## Dev iteration rhythm
+
+During integration, repeat:
+
+1. Change code / wire assets
+2. `npm run dev` (restart if HMR is insufficient)
+3. Self-check UI + gameplay + runtime (checklists below)
+4. Log in `developer-log.md` → **Dev self-check**
+5. If upstream issue → blockers + ICP + STOP (orchestrator routes TA/Designer)
+
+**Do not** wait until the last minute for a single Dev pass.
+
+## UI checklist (vs MC + layout-spec)
+
+| Check                                              | Source                                  |
+| -------------------------------------------------- | --------------------------------------- |
+| Zones and hierarchy match layout-spec              | `docs/layout-spec.md`                   |
+| Colors / mood match approved style                 | `docs/style-exploration.md`, Gate #2 MC |
+| Element placement matches storyboard Visual Intent | Master Composite frames                 |
+| Text-as-image assets visible, correct aspect       | `assetMapping` paths                    |
+| No broken images / wrong sprites / style drift     | Dev browser                             |
+| Mobile viewport (e.g. 750×1334) acceptable         | Dev browser resize                      |
+
+## Gameplay checklist (vs design-brief + PGS)
+
+| Check                                      | Source                 |
+| ------------------------------------------ | ---------------------- |
+| Hook → Tutorial → Gameplay → End Card flow | `docs/design-brief.md` |
+| Rules, scoring, win/lose match PM contract | design-brief + PGS     |
+| **First level guaranteed success**         | atom-plan / PGS        |
+| Near-Win and difficulty feel as specified  | design-brief           |
+| CTA on End Card                            | runtime test           |
+
+## Runtime checklist
+
+- No white screen or blocking console errors
+- Full playthrough without dead ends
+- BGM/SFX at correct events
+- State machine stable; CTA handler fires (`mraid` / `FbPlayableAd` / `ExitApi` as applicable)
+
+## devUrl recording
+
+In `docs/project-state.md` → **Dev Preview**:
+
+| Field            | When                                                 |
+| ---------------- | ---------------------------------------------------- |
+| `devUrl`         | After `npm run dev` shows listening URL              |
+| `devStatus`      | `pending` → `ready` or `blocked_upstream` / `failed` |
+| `devStartedBy`   | `developer`                                          |
+| `devLastChecked` | ISO timestamp after each meaningful Dev pass         |
+
+Also note devUrl in `docs/developer-log.md` → **Dev self-check**.
+
+## Upstream blocker template
+
+Add to `developer-log.md` → **## Upstream blockers**:
+
+```markdown
+| Path              | Issue   | Expected                           | routeTo | Status |
+| ----------------- | ------- | ---------------------------------- | ------- | ------ |
+| assets/ui/foo.png | missing | 256×256 PNG per layout-spec zone A | TA      | open   |
+```
+
+In `docs/intent-clarifications.md`:
+
+- **Context**: what Dev showed (screenshot description or path)
+- **Gap**: vs MC / contract / design-brief
+- **Acceptance**: exact path, dimensions, style, or audio mood required
+- **routeTo**: TA | Designer | PM
+
+Set `project-state.md`:
+
+- `devStatus: blocked_upstream`
+- `devBlockers`: same rows as log
+
+**STOP** after filing — wait for orchestrator to re-invoke upstream role, then **re-run Dev loop**.
+
+## After rework — re-verify checklist
+
+1. Confirm blocker paths exist on disk (`ls`, `playcraft image info` if needed)
+2. `npm run dev`
+3. Re-run UI + gameplay + runtime checklists for affected areas
+4. Close blocker rows (`status: resolved`) or escalate if still wrong
+5. Only then set `devStatus: ready` and stage → `review`
+
+## Dev ready checklist (`devStatus: ready` — all required)
+
+- [ ] UI checklist pass in Dev
+- [ ] Gameplay checklist pass in Dev
+- [ ] Runtime checklist pass in Dev
+- [ ] No open rows in Upstream blockers / `devBlockers`
+- [ ] `devUrl` recorded and server reachable
+- [ ] `developer-log.md` Dev self-check complete
+- [ ] **Not** required: `playcraft build`, user running terminal commands