@playcraft/cli 0.0.41 → 0.0.43

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

@@ -8,17 +8,24 @@
 - [ ] `selectedMcOption` set (Gate #2a passed)
 - [ ] MC path: `assets/images/storyboard/master_composite_option_[X].png`
 - [ ] ASR paths exist and pass zero-overlap visual check
+- [ ] ASR cells: isolated elements, no white box / scene inside cells (whole sheet opaque is OK)
+- [ ] § **Image Production Preflight** filled (Phase 1 — three Skills read)
 
-## 1. ASR Coverage Matrix (100%)
+## 1. ASR Coverage Matrix (100% rows)
 
 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).
+1. List every `elementId` from `layout-spec.md` § Asset Mapping (atlas `frameId` groups = 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`.
+3. **Row count** must equal assetMapping + static text id count (verify before STOP).
+4. For each row, set **CoverageLayer** = `on-asr` | `mc-crop` | `ta-extends`.
+5. For each row: `ASR sheet` = `ui` | `element` | `element_2` | `MC-crop` | `ICP-pending`.
+6. `TA extends?` = `no` only when on-asr shows final representative state; else `yes`.
+7. **Sheet grid metadata** table filled with real numbers (not `{{placeholder}}`).
 
-**Stop rule**: any row missing → do not set `#2b` pending.
+**Type representative rule**: each distinct **elementType** (Matrix column or `layout-spec` § Element Type Registry) must have at least one row with CoverageLayer `on-asr` or `mc-crop`.
+
+**Stop rule**: any contract row missing → do not set `#2b` pending.
 
 ## 2. Palette Locked
 
@@ -50,9 +57,9 @@ In `docs/style-exploration.md` under confirmed option:
 ```
 For each atom-plan row where assignTo = Designer:
 ├─ VisualAtom + covered in Coverage Matrix?
-│   └─ yes → status=done, actualOutput=ASR:...
+│   └─ yes → status=done, actualOutput=ASR:... (on-asr rows → asrSlot in atom-plan.json)
 ├─ AudioAtom?
-│   └─ deliver MP3 at path → done
+│   └─ deliver MP3 at path → done (Phase 2 only)
 ├─ Gap / TA extract failed (ICP)?
 │   └─ generate one PNG → done with path, or blocked until answered
 └─ Never: done with only "will extract later"
@@ -60,9 +67,10 @@ For each atom-plan row where assignTo = Designer:
 
 ## 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                                                      |
+| File                                                    | Contains                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `docs/style-exploration.md`                             | MC paths, Motion Notes, Experience Flow                                   |
+| `logs/designer-log.md`                                  | Image Production Preflight, Coverage Matrix, Palette Locked, Style Intent |
+| `assets/images/reference/ui_state_sheet_[X].png`        | exists                                                                    |
+| `assets/images/reference/element_state_sheet_[X].png`   | exists                                                                    |
+| `assets/images/reference/element_state_sheet_[X]_2.png` | if types > 12 / overflow                                                  |

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

@@ -2,35 +2,27 @@
 
 > 本文件供 Designer 在生成 Master Composite 时按需查阅。核心规则见 `playcraft-storyboard` skill。
 
-## 模型多样性策略
+## 模型策略（MC 专用 — 仅高质量模型）
 
-每个风格方案使用**不同的图片模型**，探索不同视觉可能性。先运行：
+Master Composite **禁止**使用低档或实验性模型。生成前可运行 `playcraft tools list-image-models` 核对 capability，但 **MC 只允许下表**：
 
-```bash
-playcraft tools list-image-models
-```
-
-### 推荐分配策略
+| 允许 `--image-model`           | 典型分配                                        |
+| ------------------------------ | ----------------------------------------------- |
+| **`mulerouter/gpt-image-2`**   | Option A（主推）；Option C 可复用 + 不同 prompt |
+| **`mulerouter/nano-banana-2`** | Option B；或 A/B 各用一模型做画风对比           |
 
-| 方案                   | 推荐模型类型                                        | 原因                               |
-| ---------------------- | --------------------------------------------------- | ---------------------------------- |
-| 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`               | 不同画风，提供对比参考             |
+**禁止用于 MC**：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及上表以外的任何模型。
 
-> 若只有 1-2 个方案，仍建议用不同模型生成同一方案，对比后选最佳。
+> 多方案差异应来自 **prompt / 配色 / 构图**，不是换弱模型。ASR 双板 `--image-model` 须与已选 MC **完全一致**（见 `playcraft-asset-state-sheet` skill）。
 
-### 模型特性速查
+### 模型特性速查（仅白名单内）
 
-| 模型                             | 特点                                     | 适合风格               |
-| -------------------------------- | ---------------------------------------- | ---------------------- |
-| `gpt-image-2`                    | 细节丰富、光影真实、多 provider fallback | 写实、半写实、精细卡通 |
-| `gemini-3.1-flash-image-preview` | 色彩鲜艳、构图清晰、速度快               | 明亮卡通、休闲风       |
-| `hy-image-v3.0`                  | 亚洲审美偏向、角色设计好                 | IP 风格、Q 版角色      |
-| `flux-kontext-pro`               | 艺术感强、风格独特                       | 手绘风、艺术插画       |
-| `nano-banana-2`                  | 快速、适合探索                           | 简洁图形、平面设计风   |
+| 模型                       | 特点                          | 适合                                |
+| -------------------------- | ----------------------------- | ----------------------------------- |
+| `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI、中文元素 | 写实、半写实、精细卡通、麻将/汉字类 |
+| `mulerouter/nano-banana-2` | 色彩、构图、速度快            | 明亮卡通、简洁 UI、快速迭代第二方案 |
 
-> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型，先用 `list-image-models` 确认。
+> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型；白名单内两模型均支持图生图。
 
 ---
 
@@ -56,7 +48,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot showing normal gameplay in
 
 [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-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -80,7 +72,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot with character dodging obst
 
 [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-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -104,7 +96,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot showing active gameplay wit
 
 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-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -128,7 +120,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot with active combat, 'Play N
 
 [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-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -184,7 +176,7 @@ Master Composite 是 Phase 1 的**第一张生成图**，通常无前序图可
 playcraft tools generate-image \
   --prompt "<5-panel prompt>" \
   --output assets/images/storyboard/master_composite_option_A.png \
-  --image-model gpt-image-2 \
+  --image-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -197,7 +189,7 @@ 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-model mulerouter/nano-banana-2 \
   --image-size 4K
 ```
 

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

@@ -1,15 +1,26 @@
 # 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.
+> **Scope**: After **Step 1 — Skill Discovery** in `agents/designer.md`, follow this document for **image production** (MC + ASR) through Gate #2b STOP. **Exit criteria**: see `agents/designer.md` Goals § Success criteria.
 >
 > **Deliverable shapes & tables**: `refs/designer-deliverable-spec.md`.
 
 **Trigger**: `project-state.md` stage = `style_exploration`
 
+## Step 1.5 — Image Production Preflight (before MC option B+ or before ASR)
+
+Fill `logs/designer-log.md` § **Image Production Preflight**:
+
+1. Read `playcraft-storyboard`, `playcraft-asset-state-sheet`, `playcraft-image-generation` (§3 + §3.1)
+2. Mark each Skill row ✓ with one-line decision summary
+3. Read `layout-spec.md` — count assetMapping rows + note Element Type Registry (if present)
+
+**Do not generate ASR until this section is complete.**
+
 ## 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`）
+- **Panel 1 must show every element type** from `layout-spec` (or Element Type Registry)
+- 每个方案用不同 prompt/美术方向（模型均用白名单，见 `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` / 实际像素正确
 
@@ -22,16 +33,35 @@
 ## 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` 检查；若槽位重叠，必须重生成
+- **Re-read** `playcraft-asset-state-sheet` + `playcraft-image-generation` §3.1 (cell chroma / isolated)
+- 输出：`ui_state_sheet_[X].png` + `element_state_sheet_[X].png`（类型 >12 时可加 `element_state_sheet_[X]_2.png`）
+- `--reference-image` = `master_composite_option_[selectedMcOption].png`；`--image-model` 与 MC 一致
+- Prompt：sheet `#808080` 或统一色幕；每格 **one isolated element**；金/橙格用蓝幕
+- 生成后 `playcraft image info`；目视：零重叠、格内无白盒/场景底
+- **Do not** `remove-background` on ASR — TA handles post-crop
 
 ## 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
+2. 更新 `logs/designer-log.md`：
+   - **ASR Coverage Matrix** — 100% contract rows + **CoverageLayer** column
+   - 每种 **elementType** ≥1 行 `on-asr` 或 `mc-crop`
+   - **Palette Locked**、Style Intent / Anti-Pattern
+   - Mirror `on-asr` rows → `atom-plan.json` → `atoms[].asrSlot`
+3. **Self-check before STOP**:
+
+```bash
+# MC ratio
+playcraft image info --input assets/images/storyboard/master_composite_option_[X].png
+
+# Count contract rows (adjust grep to your layout-spec format)
+grep -c 'elementId\|"id":' docs/layout-spec.md   # approximate — Matrix row count must match
+
+# ASR files exist
+ls assets/images/reference/ui_state_sheet_[X].png assets/images/reference/element_state_sheet_[X].png
+```
+
+4. 更新 handoff + `gates.#2b = pending`
+5. **STOP** — 禁止 Phase 2 音频与批量视觉样本 PNG

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

@@ -96,7 +96,7 @@ Set `project-state.md`:
 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`
+5. Only then set `devStatus: ui_ready` (after `ui_pass`) or `devStatus: ready` (after `gameplay_pass`) and handoff `next_orchestrator_action: "Invoke @reviewer ui_diff"` (or `load_check`)
 
 ## Dev ready checklist (`devStatus: ready` — all required)
 

package/project-template/.claude/agents/refs/developer-phase1-flow.md

@@ -1,211 +1,136 @@
-# Developer Integration Flow — Gameplay + Assets (L2)
+# Developer Flow — ui_pass + gameplay_pass (L2)
 
-> **Trigger**: `docs/project-state.md` stage = `integration`. Agent context + STOP rules: [`../developer.md`](../developer.md).
-> **Prerequisites**: Production Pipeline Wave 1 (Designer Ph.2) + Wave 2 (TA) both `done`; TA Compliance green; contract paths have real files on disk.
+> **Trigger**: `docs/project-state.md` stage = `ui_pass`, `ui_rework`, or `gameplay_pass`.
+> Agent context + STOP rules: [`../developer.md`](../developer.md).
 
-> **Before implementation**, read [`developer-impl-cookbook.md`](./developer-impl-cookbook.md) for PGS patterns, `index.html` skeleton, CTA handler, and **atlas binding** (`atlasPath` + `frameId` + WebP + JSON sidecar). Dev ready gate: [`developer-dev-handoff.md`](./developer-dev-handoff.md).
+---
 
-## Step 0: Upstream Intake (mandatory, before Spec Quick-Check)
+# Part A: ui_pass (UI shell only)
 
-> **Purpose:** Know what happened before `integration` — PM contracts, Designer visual lock, TA delivery — so gameplay and UI match intent.
+> **Goal:** Runnable UI matching MC — scene switching, asset binding, simple states. **No core gameplay rules.**
 
-Read each file (Read tool or shell), then fill **`logs/developer-log.md` § Upstream Intake** before any `game/` edit or Spec Quick-Check.
+## Step 0: Upstream Intake (mandatory)
 
-```bash
-cat docs/project-state.md
-cat docs/design-brief.md
-cat docs/layout-spec.md
-cat docs/atom-plan.json docs/atom-plan.md
-cat docs/style-exploration.md
-cat logs/designer-log.md
-cat logs/ta-log.md
-# Spot-check contract paths exist:
-ls assets/images/ assets/audio/ assets/bundles/ assets/models/ 2>/dev/null | head
-```
+Read each file; fill **`logs/developer-log.md` § Upstream Intake** before any `game/` edit.
 
-| Doc                 | You need from it (one line in developer-log)       |
+| Doc                 | You need from it                                   |
 | ------------------- | -------------------------------------------------- |
-| `project-state`     | Pipeline complete, `devBlockers`, dev fields       |
-| `design-brief`      | Gameplay type, flow, first-level success, Near-Win |
+| `project-state`     | Wave 2 done, stage `ui_pass`, dev fields           |
+| `design-brief`      | Experience flow scene names (for navigation only)  |
 | `layout-spec`       | Zones, elementIds, assetMapping, atlasPath/frameId |
-| `atom-plan.json`    | Developer atoms, `skillRef`, `dependsOn`（机器源） |
-| `atom-plan.md`      | Acceptance criteria + Impl/Asset/TA Context        |
-| `style-exploration` | MC + experience flow — input for Step 2 mapping    |
-| `designer-log`      | Palette / motion / ASR coverage notes              |
-| `ta-log`            | Compliance status, atlas params                    |
-
-**MUST NOT** proceed to Step 1 until every row is ticked with a concrete takeaway.
-
----
+| `atom-plan.json`    | Developer atoms, skillRef, dependsOn               |
+| `atom-plan.md`      | Acceptance + Impl Context                          |
+| `style-exploration` | MC panels — primary UI reference                   |
+| `designer-log`      | Palette / motion notes                             |
+| `ta-log`            | Compliance / atlas params                          |
 
-## Step 1: Spec Quick-Check (30s, mandatory)
+## Step 1: Spec Quick-Check (30s)
 
-> Formerly Step 0a.
+- Every referenced `elementId` exists in `assetMapping`
+- Gaps → `spec-gap` in project-state → wait for PM
 
-Before any implementation, validate Layout Spec:
+## Step 2: Experience Flow → Code Mapping
 
-- Every GameplayAtom's referenced `elementId` exists in `assetMapping`
-- Every code-referenced path has a corresponding assetMapping entry
-- If gaps found → write `spec-gap` to `project-state.md`, wait for PM to supplement (≤ 5 min)
+Write to `developer-log.md` — map MC panels to scenes (Hook / Tutorial / EndCard / CTA). See template.
 
-## Step 2: Experience Flow Visual Mapping (mandatory)
+## Step 3: Skill Preflight + Scaffold
 
-> Formerly Step 0c.
+Per `atom-plan.json` Developer `skillRef` entries — read `.claude/skills/<skillRef>/` or CLI fallback; run `playcraft skills scaffold --out ./game` once.
 
-**Read `docs/style-exploration.md` Master Composite + experience flow design before any implementation.**
+Fill **`§ Skill Preflight`** in developer-log.
 
-The Master Composite is five 9:16 panels in one image: **Panel 1 = concept panel** (Main Gameplay — full UI + all element types); **Panels 2–5 = storyboard** (Hook, Onboarding, End Card, CTA). TA extracts from concept panel / ASR state sheets; study each panel for per-stage visual intent.
+## Step 3b: UI Pass Plan (mandatory before `game/` edits)
 
-Write to `logs/developer-log.md` "Experience Flow → Code Mapping":
+Write **`logs/developer-log.md` § UI Pass Plan**:
 
-| Storyboard Frame          | Scene/State      | Code Location             | Visual Intent                                           |
-| ------------------------- | ---------------- | ------------------------- | ------------------------------------------------------- |
-| Hook (0-3s)               | `scene.hook`     | `game/scenes/hook.ts`     | {{from storyboard: contrast, pace, first interaction}}  |
-| Tutorial (3-10s)          | `scene.tutorial` | `game/scenes/tutorial.ts` | {{from storyboard: low pressure, guaranteed success}}   |
-| Gameplay+NearWin (10-25s) | `scene.gameplay` | `game/scenes/gameplay.ts` | {{from storyboard: core mechanic, near-win visual cue}} |
-| EndCard (25-30s)          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{from storyboard: CTA prominence, unresolved emotion}} |
+1. **Architecture** — engine, entry, scene flow
+2. **Scene-Asset Binding Plan** — verify every path with `ls`
+3. **Scene navigation** — how Reviewer reaches each MC panel (URL param or button)
+4. **Risk Checklist** — all `[x]`
 
-**Rules**:
+**Forbidden in ui_pass:** PGS rules, scoring, elimination, win/lose, Near-Win logic.
 
-- Every scene file MUST have a top comment: `// Visual reference: Master Composite (frame: [position])`
-- If storyboard visuals conflict with layout-spec zones → storyboard takes precedence; ask PM in `intent-clarifications.md`
-- Visual Intent captures EMOTION and ATTENTION FLOW, not just mechanics
+Hook validates § UI Pass Plan on STOP.
 
-## Step 3: 读活 DAG + Skill Discovery + 统一 Scaffold（必须先做，只做一次）
+## Step 4: Implement UI shell
 
-> Formerly Step 0b.
+- Bind **real** assets at contract paths (WebP atlas + JSON sidecar)
+- Implement scenes + `index.html` skeleton (see [`developer-impl-cookbook.md`](./developer-impl-cookbook.md))
+- Scene switching only — static/simple interactive states OK
+- Text-as-image per `playcraft-text-rendering` skill
 
-**第一步：读取骨架与已有上下文**
+## Step 5: Dev self-check (ui_pass)
 
 ```bash
-cat docs/design-brief.md    # gameplayType, engine, StyleDirection
-cat docs/atom-plan.json     # atoms[] skillRef + dependsOn
-cat docs/atom-plan.md       # Asset Skill Context + acceptance criteria
+npm run dev
 ```
 
-**第二步：读取 PM 已标注的 skillRef 内容（必须）**
-
-> **Skill 获取优先级**（见 [`atom-plan-format.md`](../../../docs/team/atom-plan-format.md)）：
->
-> 1. **Project Skills**（PM 已执行 `playcraft skills link`）：`.claude/skills/<skillRef>/SKILL.md` + `ref/`
-> 2. **兜底**：软链不存在或断链 → `playcraft skills read <skillRef>`（自动读 `playcraft.config.json` → `skillsDir`）
-> 3. `skillRef` 为空 → 独立 `playcraft skills match` 搜索
-> 4. 完全无匹配 → `playcraft-research` 后自行实现
+- All MC-reachable scenes render with real assets
+- No white screen; layout matches zones
+- Record devUrl in developer-log
 
-对 `atoms[]` 中每个 `assignTo: Developer` 且 `skillRef` 非空的 atom，逐一读取 Recipe：
+## Step 6: ui_pass STOP
 
-```bash
-# 优先：项目内软链（PM 应在 Gate #1 前已 link）
-test -f .claude/skills/memory_match.aigameplay/SKILL.md && echo "linked OK"
+- `devStatus: ui_ready` (not `ready`)
+- handoff: `Invoke @reviewer ui_diff`
+- **Do not** set mainline `stage`
 
-# 读 Recipe（二选一，link 正常时用文件路径即可）
-cat .claude/skills/memory_match.aigameplay/SKILL.md
-
-# 仅当上面 test 失败时兜底：
-playcraft skills read memory_match.aigameplay
-```
+---
 
-**访问 ref/ 文件**（同样优先 Project Skills）：
+# Part B: ui_rework
 
-```bash
-cat .claude/skills/memory_match.aigameplay/ref/pgs-schema.json
+1. Read `logs/review-report.md` UI Diff section
+2. Fix only Action Items with `routeTo: Developer`
+3. Re-run `npm run dev` → `devStatus: ui_ready` → handoff `Invoke @reviewer ui_diff`
 
-# 兜底：playcraft skills read 输出的 skillDir，或 playcraft.config.json 中的 skillsDir
-# cat <skillsDir>/memory_match.aigameplay/ref/pgs-schema.json
-```
+If `routeTo: ta` or `designer` — STOP; orchestrator invokes them first.
 
-不读 SKILL.md 就 scaffold 或实现 = 丢弃 PM 的规则蓝图。Skill Preflight 须记录每个 `skillRef` 用的是 `linked` 还是 `cli-fallback`。
+---
 
-**STOP 门槛**：`logs/developer-log.md` 的 **§ Skill Preflight** 必须已填（每个 `skillRef` 一行 + CLI 输出摘要）。未填则不得编辑 `game/**`，不得将 atom 标为 `done`，handoff 不得写 Ph.1 完成。
+# Part C: gameplay_pass (core gameplay)
 
-**第三步：补充搜索你域内的 Skills**
+> **Prerequisites:** `uiReviewStatus: passed` (or max ui rework rounds). **Do not rewrite UI layout.**
 
-```bash
-# 按引擎 + 玩法类型搜索（可发现 PM 未找到的组件层 Skill）
-playcraft skills match --engine <engine> --intent "<gameplayType>,rules,algorithm" --json
-# 搜索代码组件层
-playcraft skills match --engine <engine> --intent "<layout>,<ui_components>,<state>" --json
-# 列出配置封包
-playcraft skills list --category config --json
-```
+## Step 0: Read UI baseline
 
-**第四步：富集 `## Impl Skill Context`（写入 atom-plan.md）**
+- Confirm `devStatus` was `ui_ready` / UI diff passed
+- Read existing `game/` scenes — extend, do not replace layout
 
-```markdown
-### {{atom_id}} — {{slot_name}}
+## Step 1: Gameplay Pass Plan (mandatory)
 
-- 实现方案：（简述，基于 SKILL.md Recipe）
-- 匹配 Skills：`memory_match.aigameplay` — 提供 PGS 规则 schema + reducer 接口约束
-- ref 文件：ref/pgs-schema.json（规则骨架）、ref/reducer.template.ts（接口模板）
-- Scaffold 路径：game/gameplay/reducer.ts
-- 实现决策：与 Skill 模板的差异点（如网格从 4×4 改为 4×3）
-```
+Write **`logs/developer-log.md` § Gameplay Pass Plan**:
 
-**第五步：统一 Scaffold（一次性执行，不拆分）**
+1. **PGS Strategy** — rules from design-brief + Skill recipe
+2. **First level guarantee** — how tutorial/config ensures win
+3. **State machine** — Hook → Tutorial → Gameplay → EndCard transitions with logic
+4. **Risk Checklist** — all `[x]`
 
-```bash
-playcraft skills scaffold \
-  --engine <engine> \
-  --atoms <skillRef1>,<skillRef2>,<skillRef3> \
-  --out ./game
-```
+Hook validates § Gameplay Pass Plan on STOP.
 
-注：scaffold 对标注了 `merge-json` 的文件（package.json / tsconfig.json）会自动合并而非覆盖。
+## Step 2: Implement GameplayAtom + ConfigAtom
 
-若某 Atom 本地无结果：参阅 `playcraft-research` SKILL → 执行定向网络研究 → 写入 Impl Skill Context → 标注"候选新 Skill" → 基于研究方案实现。
+- Write testCases FIRST
+- Core rules, scoring, Near-Win, CTA handler
+- First level MUST guarantee player success
 
-## Step 4: Validate Prerequisites
+## Step 3: Dev self-check (gameplay_pass)
 
 ```bash
-ls docs/project-state.md docs/design-brief.md docs/layout-spec.md docs/atom-plan.md
-```
-
-Verify: stage is `integration`, Production Pipeline Wave 2 = `done`, you have atoms with `assignTo: Developer`, Layout Spec has element IDs / grid size / zones.
-
-**Use real assets on disk** at Asset Contract paths from `assetMapping` (TA Wave 2 must have completed):
-
-```
-Layout Spec assetMapping:
-  { elementId: "strawberry", visualAsset: "assets/images/tiles/strawberry_atlas.webp", frameId: "strawberry_01" }
-
-Your code:
-  loadAtlas('assets/images/tiles/strawberry_atlas.webp', 'assets/images/tiles/strawberry_atlas.json', 'strawberry_01')
-
-If file missing → devStatus: blocked_upstream, routeTo TA (do not placeholder)
+npm run dev
 ```
 
-## Step 5: Implement GameplayAtom + ConfigAtom
-
-- **GameplayAtom**: entities from `colorPalette.tileColors[].id`, rules from design-brief flow, write testCases FIRST
-- **ConfigAtom**: number of levels, difficulty progression, score targets — **first level MUST guarantee player success**
-
-## Text-as-Image Rendering
-
-**All visible text in the game is image assets — no font files, no CSS text.** Static text is loaded as images from `layout-spec.md` `textAssets` paths. Dynamic numbers use a Digit Sprite Strip with runtime frame-cutting.
+- Gameplay loop works; CTA fires; audio loads
+- Record devUrl
 
-> **Invoke the `playcraft-text-rendering` skill** for the full spec, rendering code templates (Canvas 2D + PlayCanvas), alignment helpers, and per-role responsibilities.
+## Step 4: gameplay_pass STOP
 
-## Step 6: Write index.html Skeleton
+- `devStatus: ready`
+- handoff: `Invoke @reviewer load_check`
+- **Do not** set Gate #3 or `stage: done`
 
-> **Read [`developer-impl-cookbook.md`](./developer-impl-cookbook.md)** for the complete skeleton with multi-platform CTA handler.
-
-Key requirements: viewport meta with `user-scalable=no`, CTA handler with mraid/FbPlayableAd/ExitApi fallbacks, all CSS/JS inline.
-
-## Step 7: Early Dev smoke (recommended)
-
-After scaffold + core scenes exist:
-
-```bash
-cat package.json   # confirm scripts.dev exists
-npm run dev
-```
-
-Fix fatal errors early. Record devUrl in `developer-log.md` when useful.
-
-## Step 8: Integration completion
+---
 
-> **Exit criteria**: see [`../developer.md`](../developer.md) → **Goals** → `integration` row.
+## Shared references
 
-1. All GameplayAtom + ConfigAtom marked `done` in `atom-plan.json` `atoms[]`
-2. `developer-log.md` includes Experience Flow → Code Mapping + **UI/gameplay self-check notes**
-3. Complete [`developer-dev-handoff.md`](./developer-dev-handoff.md) → `devStatus: ready` + devUrl → handoff `Invoke @reviewer` — **do not** set `stage: review` yourself.
+- PGS patterns, CTA, atlas binding: [`developer-impl-cookbook.md`](./developer-impl-cookbook.md)
+- Dev ready gate details: [`developer-dev-handoff.md`](./developer-dev-handoff.md)

package/project-template/.claude/agents/refs/pm-workflow-detail.md

@@ -141,7 +141,9 @@ Design the shared contract between Designer, TA, and Developer:
 3. **Asset specifications** — size, format, naming for each type
 4. **Asset mapping** — element ID → file path (the integration bridge)
 
-**Critical**: `assetMapping` paths are **locked after Gate #1**. No agent may unilaterally change paths — this is the Asset Contract: TA fills paths in production Wave 2; Developer binds **real files** in `integration` after TA Compliance green.
+**Critical**: `assetMapping` paths are **locked after Gate #1**. No agent may unilaterally change paths — this is the Asset Contract: TA fills paths in production Wave 2; Developer binds **real files** in `ui_pass` after TA Compliance green.
+
+**Transparency**: TA auto-derives transparency requirements from `assetMapping` path conventions (`bg/` = opaque, `ui/`/`vfx/`/`txt/` = needs alpha, `tiles/` = needs alpha unless card faces). PM does NOT need to define transparency fields — chroma key selection and background removal are TA's technical domain. See `ta-pipeline-cookbook.md` Step 0e.
 
 ---
 
@@ -161,6 +163,22 @@ Single-element groups stay as single-file paths; do not invent atlases for one t
 
 ---
 
+## Element Type Registry + ASR budget (Gate #1)
+
+After atlas groups, add **§ Element Type Registry** in `layout-spec.md`:
+
+- Group variant elementIds under a shared `typeId` (e.g. `tile` → red/blue/green ids)
+- Count **unique types** — target **≤ 20** for playable ads
+- ASR physical slot budget: ~12 ui + ~12 element states; overflow → second element sheet or mc-crop/ta-extends plan
+- If user request implies >20 types, PM degrades or splits variants to TA-extends in Gate #1 options
+
+Pre-Write checklist addition:
+
+- [ ] Element Type Registry present; unique type count documented
+- [ ] Variant-only ids marked for TA-extends in Designer handoff notes (optional one line in atom-plan.md)
+
+---
+
 ## Step 7: Experience Flow Design
 
 Design each stage with four fields — from "what happens" to "what the player feels" (MDA player perspective):
@@ -242,7 +260,7 @@ playcraft skills link --from-atom-plan --prune
 - `validate-atom-plan`：PM 定稿前手动跑；**PM STOP** 时 hook 再拦一层（invalid skillRef 无法 STOP）。
 - `link`：读取 `atom-plan.json` 中所有非空 `skillRef`。
 
-**PM does not** pre-fill `atom-plan.md` § Impl Skill Context — **Developer** in `integration`.
+**PM does not** pre-fill `atom-plan.md` § Impl Skill Context — **Developer** in `ui_pass` / `gameplay_pass`.
 
 ### 8e. `atom-plan.md`（可选）
 
@@ -403,6 +421,10 @@ Scheduling:
 - [ ] Every group with **≥ 2** raster elements names **one** `.webp` + **one** `.json` path in `assetMapping`
 - [ ] Audio entries specify **`.mp3`** paths where applicable
 
+**Transparency (no PM action needed)**:
+
+- [ ] `assetMapping` paths follow directory conventions (`bg/` for backgrounds, `ui/` for overlays, `vfx/` for effects, `txt/` for text images, `tiles/` for game elements) — TA derives transparency requirements from these paths automatically
+
 ---
 
 ## Design North Star