@playcraft/cli 0.0.41 → 0.0.43

package/project-template/.claude/skills/playcraft-asset-state-sheet/SKILL.md

@@ -14,6 +14,23 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 - **仅在 Gate #2a 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
 - **禁止**为未选中的 MC 方案生成 ASR
 - 两张板均使用已确认 MC 作 `--reference-image`，且 `--image-model` 与 MC 一致
+- **生成 ASR 前必读** `playcraft-image-generation` Skill §3（色幕矩阵）— 格内元素须可抠
+
+## 0.1 Sheet 底色 + 格内抠图（必读）
+
+> **整图 opaque 是预期行为** — ASR PNG 本身**不需要**也**不应**交付透明 PNG。TA 负责 `crop → remove-background → WebP atlas`。  
+> Designer 的职责是：让 **每个格内的单元素** 在 crop 后能被 TA 可靠抠图。
+
+| 层级                  | 规则                                                                              |
+| --------------------- | --------------------------------------------------------------------------------- |
+| **Sheet canvas**      | 不透明；默认 **中性灰 `#808080` flat background**（整板统一，禁止渐变/场景/纹理） |
+| **Sheet 备选**        | 若全板元素均非金/橙/绿，可用 **统一绿幕 `#00FF00`** 整板底色                      |
+| **Cell 内容**         | **单元素 isolated、居中**；禁止格内地面/阴影/白盒/场景/context                    |
+| **金/橙/黄/绿元素格** | 该格背景用 **蓝幕 `#0000FF`**（见 `playcraft-image-generation` 色幕矩阵）         |
+| **蓝/紫元素格**       | 该格背景用 **绿幕 `#00FF00`**                                                     |
+| **Designer 禁止**     | 对 ASR 做 `remove-background` 量产；那是 TA 在 `production` 的工作                |
+
+**错误示例（必须重生成）**：格内白底方块、渐变底、整屏 HUD 截屏、两元素叠在同一格、元素带地面阴影。
 
 ## 1. 交付物：两张状态参考板
 
@@ -24,6 +41,8 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 
 `[X]` = `selectedMcOption`（A/B/C）。
 
+**多板扩展**（`unique element types > 12` 或 Layer1 槽位 > 12）：允许追加 `element_state_sheet_[X]_2.png`；Coverage Matrix 的 `sheet` 列填 `element_2`。详见 `docs/team/atom-plan-format.md` § `asrSlot`.
+
 ### UI State Reference Sheet — 放什么
 
 - CTA 按钮、安装条、HUD 条、进度/分数框、手指引导、高亮框、徽章、弹窗底板等
@@ -35,11 +54,23 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 ### Element State Reference Sheet — 放什么
 
 - 棋子、牌面、角色、道具、匹配特效关键帧等（MC 概念面板里出现的玩法元素）
-- 每个元素类型 **2–3 个代表状态**（完整全集由 TA 在 `production` 扩展），例如：
+- 每个元素 **type** 至少 **1 个代表态** 占物理槽位；同 type 的 color 变体可标 `CoverageLayer: ta-extends`（见 `designer-deliverable-spec.md`）
+- 每 type **2–3 个代表状态** 优先（完整全集由 TA 在 `production` 扩展），例如：
   - `tile_gold`: idle | selected | matched
   - `panda_char`: idle | happy | win
 
-**元素总数**：每张板独立统计，每板 **8–12 个状态槽**（宁可少槽、加大间距，也不要重叠）。
+**物理槽位预算**：每张板 **8–12 个状态槽**（宁可少槽、加大间距，也不要重叠）。  
+**Coverage Matrix 100% 行** ≠ 每行都有物理槽位 — 见 §1.1 三层覆盖。
+
+### 1.1 三层覆盖（与 Coverage Matrix 对齐）
+
+| CoverageLayer  | 含义                                        | Matrix 填写                              |
+| -------------- | ------------------------------------------- | ---------------------------------------- |
+| **on-asr**     | 该 contract id 在 ASR PNG 有物理槽位 `R#C#` | `ASR sheet` + `Grid`                     |
+| **mc-crop**    | MC Panel 1 可见、ASR 无槽位                 | `ASR sheet` = `MC-crop` + Panel 区域说明 |
+| **ta-extends** | 颜色变体 / 额外状态，TA 从 ASR 或 MC 扩展   | `TA extends? = yes` + Style Intent 一句  |
+
+**硬规则**：每种 **element type** 至少在 **on-asr** 或 **mc-crop** 有一处代表态；禁止全部 `ta-extends` 且 MC/ASR 均无参考。
 
 ## 2. 布局策略 — 规则网格、零重叠
 
@@ -64,17 +95,21 @@ Row 2: [char idle]   [char happy]      [char win]       (empty)
 
 ## 3. Prompt 模板
 
+**生成前**：按 `playcraft-image-generation` §3 为每格元素选定 cell 背景色（灰/绿/蓝幕）。
+
 **UI 板** — 在 prompt 中显式写 `UI component state reference sprite sheet`：
 
 ```
 UI component state reference sprite sheet for [GAME_TYPE] playable ad.
-3840x1152 canvas, [BG_COLOR] flat background.
+3840x2160 canvas, solid flat #808080 gray background on entire sheet. NO gradient, NO scene.
 
 STRICT LAYOUT: orthographic grid, fixed non-overlapping cells. Each UI widget state in exactly one cell, 80px margin, 100px column gap, 120px row gap. NO overlapping.
 
+Each cell: ONE isolated UI widget, centered, no drop shadow on floor, no white box behind widget, no scene context.
+
 Row 1 — CTA / HUD:
-- CTA install button, default state: ...
-- CTA install button, pressed state: ...
+- Cell 1: CTA install button, default state, isolated, centered ...
+- Cell 2: CTA install button, pressed state, isolated, centered ...
 ...
 
 Art style: [SAME as Master Composite]. Front-facing UI, crisp edges, consistent lighting.
@@ -84,18 +119,21 @@ Art style: [SAME as Master Composite]. Front-facing UI, crisp edges, consistent
 
 ```
 Gameplay element state reference sprite sheet for [GAME_TYPE].
-[same STRICT LAYOUT block]
+3840x2160 canvas, solid flat #808080 gray background on entire sheet. NO gradient, NO scene.
+
+STRICT LAYOUT: [same as UI sheet]
+
+Each cell: ONE isolated game element, centered. Gold/orange/yellow elements: cell background solid bright blue #0000FF. Blue/purple elements: cell background solid bright green #00FF00. NO white box, NO ground shadow, NO scene.
 
 Row 1 — Core tiles/items:
-- [Element] idle: ...
-- [Element] selected: ...
-- [Element] matched: ...
+- Cell 1: [Element type A] idle, isolated, centered ...
+- Cell 2: [Element type A] selected, isolated, centered ...
 ...
 
 Art style: [SAME as Master Composite].
 ```
 
-**Prompt 必须包含**：`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素。
+**Prompt 必须包含**：`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素、`isolated`、`NO white box`、`NO scene`.
 
 ## 4. 生成命令
 
@@ -117,25 +155,41 @@ playcraft tools generate-image \
   --image-model <与 MC 相同> \
   --aspect-ratio 16:9 \
   --image-size 4K
+
+# 元素板溢出时（可选第二张）
+playcraft tools generate-image \
+  --prompt "<Element sheet part 2 prompt>" \
+  --output assets/images/reference/element_state_sheet_[X]_2.png \
+  --reference-image assets/images/storyboard/master_composite_option_[X].png \
+  --image-model <与 MC 相同> \
+  --aspect-ratio 16:9 \
+  --image-size 4K
 ```
 
 ## 5. 核查清单
 
-| #   | 核查项 | 标准                                     |
-| --- | ------ | ---------------------------------------- |
-| 1   | 时机   | `selectedMcOption` 已设置                |
-| 2   | 数量   | UI 板 + 元素板各一张                     |
-| 3   | 视觉   | 两板均无重叠；有重叠则重生成             |
-| 4   | 语义   | UI 板无玩法棋子；元素板无整屏 HUD 截屏   |
-| 5   | 清单   | `designer-log` 含每张板的状态→槽位映射表 |
+| #   | 核查项       | 标准                                                                           |
+| --- | ------------ | ------------------------------------------------------------------------------ |
+| 1   | 时机         | `selectedMcOption` 已设置                                                      |
+| 2   | 数量         | UI 板 + 元素板各至少一张                                                       |
+| 3   | 视觉         | 两板均无重叠；有重叠则重生成                                                   |
+| 4   | 语义         | UI 板无玩法棋子；元素板无整屏 HUD 截屏                                         |
+| 5   | 格内可抠     | 目视：无白盒/场景底/格内渐变；金橙元素格用蓝幕                                 |
+| 6   | 整图 opaque  | 预期行为 — 不要求透明 PNG                                                      |
+| 7   | 清单         | `designer-log` § **ASR Coverage Matrix** 100% contract 行 + `CoverageLayer` 列 |
+| 8   | 网格元数据   | Sheet grid 表：rows × cols + cell W×H + padding（非 `{{placeholder}}`）        |
+| 9   | type 代表态  | 每种 element type 至少在 on-asr 或 mc-crop 有一处                              |
+| 10  | asrSlot 镜像 | on-asr 行已写入 `atom-plan.json` → `atoms[].asrSlot`                           |
 
 ## 6. 与 TA 的协作协议
 
-Designer：风格与 MC 一致；在 `designer-log.md` 标注每张 ASR **已覆盖的状态** vs **TA 需扩展的状态**。
+Designer：风格与 MC 一致；在 `designer-log.md` § **ASR Coverage Matrix** 标注 **CoverageLayer** 与 **TA 需扩展的状态**。
 
 TA 提取（详见 `playcraft-masking`）：
 
-| 来源图               | 推荐方式                   | 说明                                                                                |
-| -------------------- | -------------------------- | ----------------------------------------------------------------------------------- |
-| **ASR**（规则网格）  | `playcraft image crop`     | 槽位坐标来自 `designer-log` ASR State Inventory；**禁止**对 ASR 用纯 text `segment` |
-| **Master Composite** | `decompose-layers` 或 crop | ASR 未覆盖的类型从此补提取                                                          |
+| 来源图               | 推荐方式                   | 说明                                                                                                                                             |
+| -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **ASR**（规则网格）  | `playcraft image crop`     | 槽位坐标来自 `designer-log` § **ASR Coverage Matrix**（含 Sheet grid 元数据）或 `atom-plan.json` → `asrSlot`；**禁止**对 ASR 用纯 text `segment` |
+| **Master Composite** | `decompose-layers` 或 crop | `mc-crop` 层从此补提取                                                                                                                           |
+
+**若 TA crop 后仍不可抠**（白边/色幕残留/元素被截断）→ `routeTo: designer` 重生成 ASR 格，**非** TA 自行重画 ASR。

package/project-template/.claude/skills/playcraft-image-generation/SKILL.md

@@ -135,7 +135,18 @@ playcraft tools generate-image \
 
 > **IEGG LiteLLM** 在 fallback 链中排第一，但 Azure gpt-image 最大约 1536px 宽 — 达不到 5×9:16 横排。故事板请用 **`mulerouter/gpt-image-2`**（跳过 litellm）+ `--width 3600 --height 1280`（或 4096×1455）。
 
-**Phase 1（概念图）**：纯文生图，`--image-size 4K` + 优先 gpt-image-2 追求质量。
+### Master Composite（MC）模型白名单
+
+Designer 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
+
+| 允许                       | 禁止（MC）                                          |
+| -------------------------- | --------------------------------------------------- |
+| `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
+| `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
+
+完整 prompt / 尺寸规范见 **`playcraft-storyboard`** skill。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+
+**Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
 **Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
 
 ### --reference-image 路径支持
@@ -172,17 +183,24 @@ playcraft image sprite-sheet \
 
 ## 3. 背景处理决策树
 
-> **核心原则**：先确定素材类型，再决定是否需要去背景，再决定 prompt 应该写什么。
+> **核心原则**：先确定素材类型，再决定是否需要去背景，再按素材主色调选择色幕颜色，最后做去背景 + 深色背景验证。
 
 ```
 生成的素材需要做什么？
 │
-├─ 需要透明背景的独立元素（角色、道具、图标）？
+├─ 需要透明背景的独立元素（角色、道具、图标、文字图片、HUD、VFX）？
 │   ├─ 检查模型 ALPHA 列（playcraft tools list-image-models）
 │   ├─ ALPHA = yes → prompt 加 "transparent background, PNG with alpha"
-│   └─ ALPHA = no  → 绿幕策略：
-│       ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
-│       └─ 后处理：remove-background（floodfill，tolerance 25）
+│   └─ ALPHA = no  → 色幕策略（按素材主色调选择）：
+│       ├─ 素材为金色/黄色/橙色/绿色 → 蓝幕 #0000FF
+│       │   ├─ prompt 末尾加 "on solid bright blue #0000FF background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       ├─ 素材为蓝色/紫色/靛蓝 → 绿幕 #00FF00
+│       │   ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       └─ 其他颜色 → 绿幕 #00FF00（默认）
+│           ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│           └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
 │
 ├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
 │   ├─ 不要去背景！白色牌面就是牌的一部分
@@ -190,21 +208,72 @@ playcraft image sprite-sheet \
 │   └─ 后处理：直接 resize（skipRemoveBg = true）
 │
 └─ 场景背景（天空、地面、全屏图）？
-    └─ 不做背景处理，直接 resize
+    ├─ 不做背景处理，直接 resize
+    └─ ⚠️ prompt 必须加 "full bleed, edge to edge, no vignette, no fade"
+       → 后处理验证：四角四边颜色一致，无褪色/白色
 ```
 
-### 为什么需要绿幕策略？
+### 为什么需要色幕策略？
+
+**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。绿色背景 + 任何游戏素材 = 极少撞色，抠图几乎完美。与影视 chroma-key 原理相同。
+### 色幕选型矩阵（Color Conflict Avoidance）
+
+> ⚠️ **不要默认全用绿幕！** 金色素材 + 绿幕 = 绿色与金色色相接近，floodfill 会在边缘残留绿色，或误删金色像素。
+
+| 素材主色调            | ❌ 禁用 | ✅ 推荐          | 原因                                       |
+| --------------------- | ------- | ---------------- | ------------------------------------------ |
+| 金色/黄色/橙色/琥珀色 | 绿幕    | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），边缘残留绿色 |
+| 绿色/翠绿/青色        | 绿幕    | **蓝幕 #0000FF** | 同色系，无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕    | **绿幕 #00FF00** | 同色系冲突                                 |
+| 红色/粉色/白色/黑色   | —       | 绿幕或蓝幕均可   | 与两者色相距离都大                         |
+| 多色/彩虹             | —       | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）       |
 
 ### Prompt 后缀速查表
 
-| 素材类型              | prompt 建议后缀                                                     | 后处理                           | skipRemoveBg |
-| --------------------- | ------------------------------------------------------------------- | -------------------------------- | ------------ |
-| 独立元素（需透明）    | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) | `false`      |
-| 卡牌/棋子（矩形本体） | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                      | `true`       |
-| UI 按钮/面板          | `"flat UI element, no shadow, clean edges"`                         | trim + resize                    | `true`       |
-| 场景背景              | `"full scene, edge to edge"`                                        | 只做 resize                      | `true`       |
+| 素材类型                   | prompt 建议后缀                                                     | 后处理                                      | skipRemoveBg |
+| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------- | ------------ |
+| 独立元素（需透明，非金色） | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（金/黄/橙/绿色）  | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（多色/彩虹）      | `"on solid bright magenta #FF00FF background, isolated, centered"`  | remove-background (tolerance 20) → 深色验证 | `false`      |
+| VFX 特效（发光/粒子）      | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 逐帧验证 | `false`      |
+| 卡牌/棋子（矩形本体）      | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                                 | `true`       |
+| UI 按钮/面板               | `"flat UI element, no shadow, clean edges"`                         | trim + resize                               | `true`       |
+| 场景背景                   | `"full scene, full bleed, edge to edge, no vignette, no fade"`      | resize → 四角全覆盖检查                     | `true`       |
+
+### 去背景后必做：深色背景渲证
+
+> 每个需要透明的资产，去背景后**必须**在深色背景上叠合验证。这一步是防止白底/色幕残留/黑块的最后防线。
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
+```
+
+**不通过时的修复**：见 `ta-pipeline-cookbook.md` Step 0e §3 及 Compliance Gate 失败修复表。
+
+---
+
+## 3.1 ASR 专用分支（Designer · Gate #2b）
+
+> **Read `playcraft-asset-state-sheet` Skill first.** ASR 是制作期参考板，不是 runtime 透明资产。
+
+| 阶段              | Designer                              | TA                            |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| ASR 整图          | **opaque**（灰底或统一色幕）— 正常    | —                             |
+| ASR 格内元素      | **isolated** + 按色幕矩阵选 cell 背景 | `crop` 后 `remove-background` |
+| remove-background | **禁止** — Designer 不做              | production Wave 2             |
+
+**Designer ASR prompt 要点**：
+
+1. Sheet canvas：`solid flat #808080` 或整板统一绿幕（非渐变）
+2. 每格：`ONE isolated element, centered, NO white box, NO scene, NO ground shadow`
+3. 金/橙/黄/绿元素格 → cell 背景 `#0000FF`；蓝/紫 → `#00FF00`
+4. 生成后**目视**格内可抠性 — 不要求 `channels=4`（那是 TA 后处理产物）
 
 ---
 

package/project-template/.claude/skills/playcraft-storyboard/SKILL.md

@@ -91,10 +91,23 @@ Total image exactly [3600] pixels wide by [1280] pixels tall (five 720x1280 cell
 
 ## 3. 生成命令
 
+### MC 模型白名单（强制）
+
+Master Composite **只允许**下列高质量模型（须带 **provider 前缀**，禁止裸模型名）：
+
+| 用途     | `--image-model`            | 说明                                              |
+| -------- | -------------------------- | ------------------------------------------------- |
+| **首选** | `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI；默认 Option A                |
+| **备选** | `mulerouter/nano-banana-2` | Gemini 3.1 Flash Image；Option B/C 或需不同画风时 |
+
+**禁止**用于 MC：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及 `list-image-models` 中未列入上表的模型。
+
+多方案（A/B/C）应用 **不同 prompt / 美术方向** 探索，**不得**用低档模型换方案——质量门槛对所有 MC 选项相同。
+
 ```bash
 playcraft tools generate-image \
   --prompt "<Section 2>" \
-  --output assets/images/storyboard/master_composite_option_[N].png \
+  --output assets/images/storyboard/master_composite_option_A.png \
   --image-model mulerouter/gpt-image-2 \
   --aspect-ratio 45:16 \
   --image-size 2K \
@@ -102,15 +115,21 @@ playcraft tools generate-image \
   --height 1280
 ```
 
-> **必须**使用 `mulerouter/gpt-image-2`（或已配置的 `302/...`）。**禁止**裸 `gpt-image-2`——fallback 会先走 `iegg-litellm`，成功时只能出 **1536×1024**，五格竖屏会被压扁。CLI 会在保存后自动校验像素，不合格直接失败。
+Option B 示例（仍须白名单内）：
+
+```bash
+  --image-model mulerouter/nano-banana-2 \
+```
+
+> **必须**带 `mulerouter/` 前缀。**禁止**裸 `gpt-image-2`——fallback 会先走 `iegg-litellm`，成功时只能出 **1536×1024**，五格竖屏会被压扁。CLI 会在保存后自动校验像素，不合格直接失败。
 
 **4K 档**：`--image-size 4K --width 4096 --height 1455`
 
-| 参数                   | 要求                                                  |
-| ---------------------- | ----------------------------------------------------- |
-| `--aspect-ratio`       | **`45:16`**（5 个 9:16 横排）；**禁止 `1:1`、`10:3`** |
-| `--width` / `--height` | **3600×1280**（2K）或 **4096×1455**（4K）             |
-| `--image-model`        | **`mulerouter/gpt-image-2`**（强制，勿用裸模型名）    |
+| 参数                   | 要求                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| `--aspect-ratio`       | **`45:16`**（5 个 9:16 横排）；**禁止 `1:1`、`10:3`**                                     |
+| `--width` / `--height` | **3600×1280**（2K）或 **4096×1455**（4K）                                                 |
+| `--image-model`        | **`mulerouter/gpt-image-2`** 或 **`mulerouter/nano-banana-2`** only（强制 provider 前缀） |
 
 ### 生成后验收（强制）
 

package/project-template/.claude/skills/playcraft-workflow/SKILL.md

@@ -22,10 +22,59 @@ triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查
    - `gate_pending` 非 null 且 `waiting_for: user_gate` 时：**只跑 Gate**，不得 invoke 子 Agent
    - `subagent_stop: true` 时：只执行 `next_orchestrator_action`
    - Gate #1 / #2a / #2b：`AskUserQuestion`（子 Agent 更新 handoff 后 STOP）
-   - Gate #3：Reviewer 通过后展示 **devUrl**（用户只点链，不跑 `npm run dev`）
+   - **Gate #1 / #2b 前**：先 invoke `@reviewer design_check`（软性 checklist）
+   - Gate #3：Reviewer `load_check` 通过后展示 **devUrl**（用户只点链；玩法由用户判断）
    - Gate / handoff 细则：`docs/team/collaboration.md` § Gate Protocol、§ Agent Handoff
-6. `devStatus: ready` → `@reviewer`；`devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
-7. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
+6. `devStatus: ui_ready` → `@reviewer ui_diff`；`ui_rework` → 按 report 修复 → 再 `@reviewer ui_diff`
+7. `devStatus: ready` → `@reviewer load_check` → Gate #3
+8. `devStatus: blocked_upstream` → 按 `devBlockers.routeTo` 调度 TA/Designer → 再 `@developer`
+9. 当前交付终点 = 用户在 Dev URL 验收通过（`done`），**不要求** `playcraft build`
+
+### ⚠️ Orchestrator 调度原则：传 WHAT 不传 HOW
+
+**Orchestrator 不是全知全能的指挥官。** 不要在调度时给子 Agent 写详细步骤——子 Agent 有完整的 `.claude/agents/<role>.md` + `refs/` + 相关 Skills。
+
+**正确的调度方式：**
+
+```
+@technical-artist
+目标：完成 atom-plan.json 中所有 assignTo: TA 的 atoms。
+注意：atom-plan.json → skillsMatch.mediaGroups 有 3 个预制图片资产可复用，优先 link。
+```
+
+**错误的调度方式（越俎代庖）：**
+
+```
+@technical-artist
+1. 先生成 tile_01.png，用绿幕...
+2. 然后 remove-background --tolerance 25...
+3. 接着 resize 到 128x128...
+```
+
+**原则：**
+
+- Orchestrator 只传递 **目标 + 约束 + 关键提醒**（如 mediaGroups 可用）
+- 子 Agent 自己读 `refs/` + Skills 找到正确方法论
+- Orchestrator 在 sub-agent STOP 后 **验证结果**（atom status 是否更新、Context 是否填写）
+
+### Orchestrator STOP 后验证清单
+
+Sub-agent STOP 返回后，Orchestrator 必须验证：
+
+```bash
+# 检查 atom status 是否全部更新
+cat docs/atom-plan.json | jq '[.atoms[] | select(.assignTo == "<agent>") | select(.status == "pending")] | length'
+# 应该 = 0（所有该 agent 的 atom 都已 done / skipped）
+
+# 检查 Context 是否填写
+grep -c "Pending" docs/atom-plan.md
+# 对应 agent 的 Context 区不应包含 "Pending"
+
+# 检查 actualOutput 文件是否存在
+cat docs/atom-plan.json | jq '.atoms[] | select(.assignTo == "<agent>" and .status == "done") | .actualOutput' | xargs -I {} test -f {}
+```
+
+如果验证失败 → 不转入下一阶段，而是要求该 agent 补全。
 
 ### Single-Agent Mode（降级模式，当 sub-agent 不可用时）
 
@@ -33,7 +82,7 @@ triggers: 构建游戏,开始开发,创建项目,选择组件,选择 skill,查
 
 - 每进入一个新阶段时，先完整读取对应 `.claude/agents/<role>.md` 的所有指令
 - 不可跳过任何阶段的必选产出（特别是 TA 的完整素材生产——UI 图、VFX、精灵图都必须生产）
-- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `integration` 启动后 30s 内
+- 必须执行 Spec Quick-Check：TA 在 production Wave 2 启动后 30s 内；Developer 在 `ui_pass` 启动后 30s 内
 - PM 定稿后运行 `playcraft skills link --from-atom-plan`；Developer 优先读 `.claude/skills/<atomId>/SKILL.md`，仅断链时用 `playcraft skills read`
 
 ---
@@ -238,13 +287,47 @@ Skills 路径真源：`playcraft.config.json` → `agent.skillsDir`（**不要**
 
 ### 各 Agent 的读写职责
 
-| Agent                | 读取                                     | 写入                                                  |
-| -------------------- | ---------------------------------------- | ----------------------------------------------------- |
-| **PM**               | design-brief, layout-spec                | `atom-plan.json`（skillsMatch + atoms[]）             |
-| **Designer**         | `atoms[]` + design-brief                 | `atom-plan.md` § Asset Skill Context                  |
-| **Technical Artist** | `atoms[]` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status`   |
-| **Developer**        | `atoms[]` + Context 区 + design-brief    | `atom-plan.md` § Impl Skill Context；`atoms[].status` |
-| **Reviewer**         | JSON + MD（只读）                        | 不写                                                  |
+| Agent                | 读取                                                     | 写入                                                                            |
+| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| **PM**               | design-brief, layout-spec                                | `atom-plan.json`（skillsMatch + atoms[]）                                       |
+| **Designer**         | `atoms[]` + `mediaGroups` + design-brief                 | `atom-plan.md` § Asset Skill Context；`atoms[].status` + `atoms[].actualOutput` |
+| **Technical Artist** | `atoms[]` + `mediaGroups` + Asset Context + designer-log | `atom-plan.md` § TA Skill Context；`atoms[].status` + `atoms[].actualOutput`    |
+| **Developer**        | `atoms[]` + Context 区 + design-brief                    | `atom-plan.md` § Impl Skill Context；`atoms[].status` + `atoms[].actualOutput`  |
+| **Reviewer**         | JSON + MD（只读）                                        | 不写                                                                            |
+
+### ⚠️ Status Update 纪律（所有 Agent 必须遵守）
+
+每个 Agent 完成 atom 后 **立即** 更新 `atom-plan.json`：
+
+```json
+{
+  "atomId": "<id>",
+  "status": "done",
+  "actualOutput": "<deliverable_path>"
+}
+```
+
+- **Designer**: `actualOutput` = 文件路径 或 `"ASR:<sheet>:<region>"` (when covered by ASR)
+- **TA**: `actualOutput` = `"assets/images/<path>.webp"` (final WebP contract path)
+- **Developer**: `actualOutput` = `"game/<path>.ts"` (implementation file)
+
+**atom-plan 不是 PM 的一次性输出文档，而是贯穿全流程的活依赖追踪系统。**
+
+### mediaGroups 使用纪律（Designer + TA 必须遵守）
+
+`skillsMatch.mediaGroups` 包含 PM 通过 `playcraft skills match` 找到的可复用预制资产。
+
+**流程**：
+
+```
+Designer/TA 读 mediaGroups
+  ├─ 匹配当前 atom？
+  │   ├─ 是 → `playcraft skills link --atom <atomId>` → 后处理 → status=done
+  │   └─ 否 / 质量不够 → 记录跳过原因到 dagRevisions → 正常生产流程
+  └─ mediaGroups 为空？→ 正常生产流程
+```
+
+**禁止**：忽略 mediaGroups 中存在匹配的预制资产而从零生成（浪费 token + 引入不一致风险）。
 
 ### 为什么这样设计能避免冲突
 
@@ -297,22 +380,28 @@ Reviewer:
 
 `aiimage` / `aiaudio` Skill 没有 `ref/` 代码文件，只有 `manifest.json` 中的 `generation` 字段（prompt、aspectRatio、duration 等）。Designer 和 TA 读取这些参数作为生成基准，通过 `playcraft image *`、`playcraft tools generate-image` 等 CLI 命令执行，不复制任何文件到项目。
 
-### Production 串行编排（production-serial-v1）
+**Reviewer（convergence-v1）**
+
+- **`design_check`**：Gate #1 / #2b 前 — 文档完整性 checklist（无需浏览器）
+- **`ui_diff`**：读取 **`playwright-cli`** skill — 截图 vs MC 各面板
+- **`load_check`**：读取 **`playwright-cli`** skill — 页面加载 + console 无 Error
+
+### Production 串行编排（convergence-v1）
 
 Gate #2b 通过后 **严格串行**（见 `workflow-changelog.md`）：
 
 ```
-Wave 1 Designer Ph.2 → Wave 2 TA → integration Developer
+Wave 1 Designer Ph.2 → Wave 2 TA → ui_pass Developer → ui_review (Reviewer ui_diff) → gameplay_pass Developer → load_check → Gate #3
 ```
 
-Developer 仅在 `integration` 写入 `game/**`，此时 TA 已交付合同路径上的真实资产。
+Developer 在 **`ui_pass`** 写入 UI shell（无核心玩法）；**`gameplay_pass`** 叠加玩法逻辑。TA 已交付合同路径上的真实资产。
 
 ### 避免重复 Scaffold 的规则
 
 同一个 Skill 不应被多次 Scaffold 到同一目录：
 
 - PM 在 `atom-plan.json` → `atoms[]` 标注 `skillRef`（若有）+ 调度元信息（assignTo/dependsOn/priority/parallelGroup/referenceSource）
-- Developer 在 `integration` 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
+- Developer 在 **`ui_pass`** 开始时，按 `atoms[]` 中 `assignTo: Developer` 批量 scaffold 一次
 - **不要在实现单个 Atom 时反复 scaffold** — 先统一 scaffold 所有依赖，再逐一实现
 
 ---