@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md

@@ -0,0 +1,1108 @@
+# TA Pipeline Cookbook
+
+> Read by Technical Artist at **production** Wave 2 entry (**Step 0a → 0 → 1 → 2** in order). **Prerequisite:** Production Pipeline Wave 1 (Designer Ph.2) = `done` — orchestrator invokes TA only after Designer wave completes.
+
+## Step 0a — Upstream Intake (mandatory, before Skill Discovery)
+
+> **Purpose:** Understand what PM locked, what Designer delivered, and what Wave 1 added — without re-reading everything in four docs (PM/Designer keep them concise; narrative lives in style-exploration + designer-log).
+
+Read each file (Read tool or shell), then fill **`logs/ta-log.md` § Upstream Intake** before any generation.
+
+```bash
+cat docs/project-state.md    # stage, gates, Pipeline waves, spec-gap
+cat docs/design-brief.md     # experience flow, Style Direction, gameplay — prompt + QA context
+cat docs/layout-spec.md      # assetMapping, atlas groups, dimensions (contract)
+cat docs/atom-plan.json      # assignTo: TA, dependsOn
+cat docs/atom-plan.md        # TA Skill Context
+cat docs/style-exploration.md
+cat logs/designer-log.md
+ls assets/images/reference/   # MC + ASR paths
+ls assets/audio/              # Designer Ph.2 raw audio (if present)
+```
+
+| Doc                 | You need from it (one line in ta-log)                |
+| ------------------- | ---------------------------------------------------- |
+| `project-state`     | Current wave, blockers, `selectedMcOption`           |
+| `design-brief`      | Hook→EndCard beats + Style Direction for completions |
+| `layout-spec`       | Every path you must fill + atlas groups              |
+| `atom-plan.json`    | TA atom list + dependencies                          |
+| `atom-plan.md`      | TA Skill Context                                     |
+| `style-exploration` | Confirmed MC path + per-panel visual intent          |
+| `designer-log`      | Handoff Pack, Style Intent Notes, ASR inventory      |
+
+**MUST NOT** start Step 0 Skill Discovery or Step 1 gap table until Upstream Intake rows are ticked.
+
+---
+
+## Step 0 Pre: mediaGroups Asset Reuse (mandatory, before any generation)
+
+> **Purpose:** `atom-plan.json` → `skillsMatch.mediaGroups` contains pre-matched reusable assets from the skills library. These assets have already been validated by PM's `playcraft skills match`. **TA MUST check and link available media assets before generating anything from scratch.**
+
+```bash
+# 1. Read mediaGroups from atom-plan.json
+cat docs/atom-plan.json | jq '.skillsMatch.mediaGroups'
+```
+
+For each mediaGroup entry:
+
+1. **Check if the mediaGroup matches a TA-assigned atom** — compare `atomId` / description with atoms in your production list
+2. **If matched → link the asset directly**:
+
+```bash
+# Link the pre-matched asset to the contract path
+playcraft skills link --atom <atomId> --output <assetMapping_path>
+# OR manually copy from skills library:
+cp $(playcraft skills read <mediaGroup_atomId> --path) <assetMapping_path>
+```
+
+3. **Post-process the linked asset** (resize, convert, transparency) — linked assets still need format compliance
+4. **Update atom status** immediately:
+
+```json
+{ "atomId": "<id>", "status": "done", "actualOutput": "<assetMapping_path>" }
+```
+
+5. **If NOT matched or quality insufficient** — proceed to Step 0 Skill Discovery + Step 1 generation as normal; document reason in `dagRevisions`:
+
+```markdown
+### mediaGroup Skip — {{atomId}}
+
+- **mediaGroup atomId**: {{mg_atomId}}
+- **reason**: {{quality issue / style mismatch / wrong dimensions}}
+- **action**: generate from scratch using Step 1 pipeline
+```
+
+**STOP gate**: `ta-log.md` must contain a "mediaGroups Reuse" section listing each mediaGroup's disposition (linked / skipped + reason) before proceeding to generation.
+
+---
+
+## Step 0 (Skill Discovery) → Enrich TA Skill Context
+
+Before executing any atom, run two rounds of Skill Discovery:
+
+---
+
+### Part A — Pipeline Skill Discovery（工作流决策）
+
+```bash
+# Find relevant aiimage Skills for completion pipeline
+playcraft skills list --category visual --json
+playcraft skills match --intent "<style>,<element_type>,sprite,atlas" --json
+
+# Find 3D Skills if needed
+playcraft skills match --intent "3d,sprite,flip,render" --json
+
+# Find validator Skills for compliance check
+playcraft skills list --category validator --json
+```
+
+---
+
+### Part B — Atom Skill Recipe Read（生成参数提取）
+
+For every atom assigned to TA with a non-empty `skillRef` in `atom-plan.json` `atoms[]`, read its generation recipe:
+
+```bash
+# Read generation recipe from PM-assigned skillRef
+# Replace <skillRef> with the atom's skillRef value (e.g., jewel_tile.aiimage)
+playcraft skills scaffold <skillRef> --dry-run
+```
+
+The scaffold output reveals the atom Skill's **Recipe** section: prompt template, aspect ratio, recommended model, variant directions. Use this as your **base prompt** for Stage A completions, then add `--reference-image` for style consistency.
+
+**Example workflow** — atom `tile_02` has `skillRef: jewel_tile.aiimage`:
+
+```bash
+# Step 1: Read the recipe
+playcraft skills scaffold jewel_tile.aiimage --dry-run
+# → Output:
+#   prompt: "isometric jewel tile, {color} gemstone, faceted crystal, soft glow, game UI style"
+#   aspectRatio: 1:1
+#   model: gpt-image-2
+#   variants: blue sapphire / red ruby / green emerald / yellow topaz
+
+# Step 2: Generate using recipe prompt + Designer reference for style consistency
+playcraft tools generate-image \
+  --prompt "isometric jewel tile, red ruby, faceted crystal, soft glow, game UI style" \
+  --reference-image assets/images/storyboard/master_composite_option_<selectedMcOption>.png \   # style anchor
+  --reference-image assets/images/tiles/tile_01.png \      # Designer's approved sample
+  --aspect-ratio 1:1 \
+  --image-model gpt-image-2 \                              # recipe-recommended model
+  --output assets/images/tiles/tile_02.png
+```
+
+**Key principle**: The atom Skill provides the **semantic description** (what the element is); `--reference-image` enforces **visual style** (how it matches this project's look). Both are necessary.
+
+If `skillRef` is `—` or empty for an atom, skip Part B for that atom and rely on Designer's Style Intent Notes alone.
+
+---
+
+### Write findings into `docs/atom-plan.md` under `## TA Skill Context`
+
+```markdown
+### {{atom_id}} — {{slot_name}}
+
+- **Production approach**: (e.g., "derive from Designer sample using reference-image")
+- **Atom Skill recipe** (`skillRef: jewel_tile.aiimage`):
+  - Base prompt template: "isometric jewel tile, {color} gemstone, faceted crystal, soft glow"
+  - aspectRatio: 1:1
+  - Recommended model: gpt-image-2
+  - Variant directions: blue / red / green / yellow
+- **Matched pipeline Skills**: `playcraft-sprite-sheet` — sprite frame merging workflow
+- **Pipeline decision**: "generate 5 remaining tile colors using recipe prompt + master*composite_option*[X] / ASR crop reference"
+- **Candidate new Skill**: `mahjong_tile_set.aiimage` — full 34-tile batch production
+```
+
+---
+
+### Part C — Mandatory Skill Preflight（管线 Skill 读取）
+
+> **Purpose:** TA 在生产前必须阅读相关的 playcraft 管线 Skill，确保使用平台既定最佳实践而非"凭经验自由发挥"。
+
+**必读 Skills（按产出类型）：**
+
+| 产出类型        | 必读 Skill                                                               | 不读的后果                   |
+| --------------- | ------------------------------------------------------------------------ | ---------------------------- |
+| 任何图片生成    | `playcraft-image-generation`（§3 背景决策树、模型选择、reference-image） | 所有透明度问题               |
+| 需要透明的素材  | `playcraft-masking`（remove-background / segment / decompose-layers）    | 白底、黑块、色残留           |
+| 精灵图 / Atlas  | `playcraft-sprite-generation`（单帧生成→合并，非 AI 直出网格）           | 帧尺寸不均、无 alpha、帧出血 |
+| VFX 动画帧      | `playcraft-vfx-animation`                                                | 发光效果黑块                 |
+| 批量 (>5 元素)  | `playcraft-batch-pipeline`                                               | 风格不一致、参数丢失         |
+| 文字 / 数字渲染 | `playcraft-text-rendering`（绿幕策略 + 描边保护）                        | 文字白底、数字变绿           |
+| 风格一致性验证  | `playcraft-style-qa`                                                     | 风格偏离 MC / ASR            |
+
+**执行方式：**
+
+```bash
+# Read each relevant skill before production
+cat .claude/skills/playcraft-image-generation/SKILL.md
+cat .claude/skills/playcraft-masking/SKILL.md
+cat .claude/skills/playcraft-sprite-generation/SKILL.md
+# ... additional skills per atom type
+```
+
+**STOP 门槛**：`logs/ta-log.md` 的 **§ Skill Preflight** 必须列出每个已读 Skill + 关键决策摘要（一行）。未填则不得执行 Step 1 批量生成。
+
+```markdown
+## Skill Preflight
+
+| Skill                       | 已读 | 关键决策摘要                                          |
+| --------------------------- | ---- | ----------------------------------------------------- |
+| playcraft-image-generation  | ✅   | 使用 gpt-image-2；所有透明素材 chroma key + ref-image |
+| playcraft-masking           | ✅   | floodfill 优先 (tolerance=25)；复杂形状用 segment     |
+| playcraft-sprite-generation | ✅   | 单帧生成→去背→resize→合并；禁止 AI 直出网格           |
+| playcraft-text-rendering    | ✅   | 文字必须蓝幕；描边保护 + tolerance 降到 20            |
+```
+
+---
+
+## Step 1 (Asset Completion)
+
+> **生图前请先阅读 `playcraft-image-generation` Skill**（包含模型选择决策树、reference-image 工作流和错误恢复策略）。
+
+> **精灵图生产原则**：所有动画序列帧必须「单帧生成 → 去背景 → resize → sprite-sheet 合并」，严禁让 AI 直接生成网格图后切割（帧尺寸不均、无 alpha、帧出血）。详见本节末尾"Sprite Sheet Pipeline"。
+
+### Step 1: Map the Gap
+
+```bash
+# Read the full expected asset list from layout-spec
+cat docs/layout-spec.md   # assetMapping defines EVERY file that must exist
+
+# Check what Designer has already delivered
+cat logs/designer-log.md
+ls assets/images/tiles/
+ls assets/images/bg/
+ls assets/images/ui/
+```
+
+Build a gap table: for each `assetMapping` entry, check if the file exists. Missing files are your production list.
+
+### Step 2: Identify Style Reference
+
+```bash
+# The confirmed concept mockup is your master reference
+cat docs/style-exploration.md  # find confirmed option path
+# e.g., assets/images/storyboard/master_composite_option_<selectedMcOption>.png
+
+# Also use any approved samples as secondary references
+ls assets/images/tiles/  # Designer's samples
+```
+
+### Step 3: Complete Missing Elements
+
+**规则：超过 5 个元素 → 写 Node.js 脚本；5 个以内 → 直接命令行。**
+
+**Prompt 来源优先级**（写 prompt 前先确认）：
+
+1. **atom Skill recipe**（Step 0 Part B 已提取）— 有 skillRef → 用 recipe 的 prompt 模板，替换变量
+2. **Designer Style Intent Notes**（`logs/designer-log.md`）— 无 skillRef 或 recipe 不够具体 → 从 Style Intent Notes 提炼
+3. **design-brief StyleDirection** — 兜底，最通用
+
+**少量元素（逐个生成）**：
+
+```bash
+# prompt = atom Skill recipe 模板（已在 TA Skill Context 中提取）+ Designer style notes
+playcraft tools generate-image \
+  --prompt "<recipe base prompt, e.g.: isometric jewel tile, red ruby, faceted crystal, soft glow, game UI style>" \
+  --reference-image assets/images/storyboard/master_composite_option_<selectedMcOption>.png \   # 风格锚定
+  --reference-image assets/images/tiles/<designer_sample>.png \  # Designer 样本（若有）
+  --output assets/images/tiles/<new_element>.png \
+  --aspect-ratio 1:1 \
+  --image-model <recipe recommended model, e.g.: gpt-image-2>
+```
+
+**批量元素（10+ 个）→ 必须用 ta-workspace 脚本**：
+
+```javascript
+// Write this to ta-workspace/scripts/gen-elements.mjs, then run: node ta-workspace/scripts/gen-elements.mjs
+import { execSync } from "child_process";
+import { existsSync, mkdirSync } from "fs";
+
+// MODEL: from atom Skill recipe (Step 0 Part B) or fallback to gemini-flash
+const MODEL = "google/gemini-3.1-flash-image-preview";
+const REF =
+  "assets/images/storyboard/master_composite_option_<selectedMcOption>.png";
+const REF2 = "assets/images/tiles/<designer_sample>.png"; // Designer approved sample (add if available)
+const OUT = "assets/images/tiles";
+
+// STYLE: atom Skill recipe base prompt (from TA Skill Context in atom-plan.md)
+// e.g., "isometric jewel tile, {color} gemstone, faceted crystal surface, soft glow, game UI style"
+// Replace {color} / {variant} per element
+const BASE_PROMPT = "<atom Skill recipe base prompt from TA Skill Context>";
+
+const ELEMENTS = [
+  { name: "element_01", variant: "<specific variant, e.g.: blue sapphire>" },
+  { name: "element_02", variant: "<specific variant, e.g.: red ruby>" },
+  // ... all elements to generate, using recipe variant directions
+];
+
+mkdirSync(OUT, { recursive: true });
+let done = 0,
+  skipped = 0,
+  failed = 0;
+
+for (const el of ELEMENTS) {
+  const outPath = `${OUT}/${el.name}.png`;
+  if (existsSync(outPath)) {
+    console.log(`[SKIP] ${el.name}`);
+    skipped++;
+    continue;
+  }
+
+  console.log(`[GEN ] ${el.name}`);
+  // prompt = BASE_PROMPT with variant filled in + Designer style anchor via --reference-image
+  const prompt = BASE_PROMPT.replace("{variant}", el.variant).replace(
+    "{color}",
+    el.variant,
+  );
+  try {
+    execSync(
+      `playcraft tools generate-image` +
+        ` --prompt "${prompt}"` +
+        ` --output "${outPath}" --aspect-ratio 1:1` +
+        ` --reference-image "${REF}"` +
+        (existsSync(REF2) ? ` --reference-image "${REF2}"` : "") +
+        ` --image-model "${MODEL}"` +
+        ` --timeout 120`,
+      { stdio: "inherit" },
+    );
+    done++;
+  } catch (e) {
+    console.error(`[FAIL] ${el.name}:`, e.message);
+    failed++;
+  }
+}
+console.log(`Done: ${done} | Skipped: ${skipped} | Failed: ${failed}`);
+if (failed > 0) process.exit(1);
+```
+
+**Same-type elements → same model + same reference → consistent style.**
+
+**结构相似变体（卡牌/棋子/图标集）→ Edit 模型路径**：
+
+当元素结构相同、只改局部（换花色、换数字、换颜色）时，Edit 模型路径比重新生成更快且局部一致性更强：
+
+```
+Phase 1：高质量模型生成 1 张完美基图
+  → gpt-image-2 / gemini-flash（反复生成直到满意）
+
+Phase 2：用参考图 + prompt 批量生成变体
+  → 任何 text+image 或 image→image 模型均支持 --reference-image
+  → 将基图作为 --reference-image，prompt 中描述变体差异
+```
+
+使用脚本模板：
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs \
+   ta-workspace/scripts/gen-<name>-variants.mjs
+# 修改 CONFIG.baseImage / CONFIG.editModel / VARIANTS[] 后运行
+node ta-workspace/scripts/gen-<name>-variants.mjs
+```
+
+### Step 4: Process Assets（去背景 + resize + 验证）
+
+> **必须先查阅 Step 0e Transparency Classification 表**，按 `bgStrategy` 列执行。不要凭直觉判断是否需要去背景。
+
+#### 处理管线总览
+
+```
+按 bgStrategy 分流：
+│
+├─ opaque → 直接 resize（skipRemoveBg = true）
+│
+├─ full-coverage → resize → 全覆盖验证（四角四边）
+│
+├─ greenscreen / bluescreen / magenta → 完整去背管线：
+│   1. playcraft image remove-background --method floodfill --tolerance 25
+│   2. playcraft image info --json → 确认 channels=4
+│   3. playcraft image overlay (深色背景验证)
+│   4. 验证失败? → 回退工具链（见下方）
+│   5. playcraft image resize → playcraft image convert --format webp
+│
+└─ segment → 提取管线：
+    1. playcraft image crop (已知坐标) 或 segment --boxes (需精确蒙版)
+    2. 若整图分层 → playcraft image decompose-layers
+    3. playcraft image info --json → 确认 channels=4
+    4. playcraft image overlay (深色背景验证)
+    5. playcraft image resize → playcraft image convert --format webp
+```
+
+#### bgStrategy = opaque（卡牌/棋子/矩形实体）
+
+```bash
+playcraft image resize --input <file>.png --output <file>.png --width <W> --height <H> --fit contain
+```
+
+批量处理使用 `process-batch.template.mjs` 并设置 `CONFIG.skipRemoveBg = true`。
+
+#### bgStrategy = greenscreen / bluescreen / magenta（需要透明的元素）
+
+> ⚠️ **不要跳过去背景步骤！** 按 Step 0e 表中的 bgStrategy 选用正确的工具。
+
+**Step 4a — 去背景（第一选择：floodfill）**：
+
+```bash
+playcraft image remove-background \
+  --input <raw_asset>.png \
+  --output <processed_asset>.png \
+  --method floodfill \
+  --tolerance 25
+```
+
+**Step 4b — 验证 alpha 通道**：
+
+```bash
+playcraft image info --input <processed_asset>.png --json
+# 确认: channels == 4（若 channels == 3，说明输出格式错误，确保 .png 后缀）
+```
+
+**Step 4c — 深色背景渲染验证**：
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed_asset>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视确认：边缘干净、无色幕残留、无白色/黑色伪影
+```
+
+**Step 4d — 验证失败时的回退工具链**：
+
+| 验证失败现象               | 根因                           | 回退工具                                                                   |
+| -------------------------- | ------------------------------ | -------------------------------------------------------------------------- |
+| 色幕残留少量（边缘毛刺）   | tolerance 偏低                 | `remove-background --tolerance 40`（+15 递增重试）                         |
+| 色幕残留明显（大面积色块） | 素材色与色幕撞色               | **spec-gap** → PM 修改 bgStrategy → 用正确色幕重新生成                     |
+| 复杂边缘/不规则形状        | floodfill 无法处理复杂轮廓     | `playcraft image segment --boxes '[[x1,y1,x2,y2]]'`（精确框选，SAM3 分割） |
+| 毛发/半透明/渐变边缘       | floodfill 是硬边缘算法         | `playcraft image remove-background --method ai`（AI 语义去背景）           |
+| 去背过度（元素被挖掉）     | tolerance 过高或素材含近色区域 | 降低 tolerance 到 15-20 → 仍不行则 `segment --boxes`                       |
+| VFX 帧出现黑色不透明块     | 发光/粒子未用色幕生成          | 用蓝幕重新生成每一帧，然后 `remove-background`                             |
+| 白底/白边残留              | 未使用色幕策略直接白底生成     | 用正确色幕重新生成（不要试图在白底上去背景）                               |
+| 背景图四角褪色/白边        | prompt 未加 edge-to-edge       | 重新生成，prompt 加 `"full bleed, edge to edge, no vignette"`              |
+
+#### bgStrategy = segment（从 MC/ASR 提取）
+
+使用 PlayCraft CLI 提供的分割工具链提取，不做 AI 重新生成：
+
+```bash
+# 方法 1: crop 直切（ASR 已知网格布局，最可靠）
+playcraft image crop \
+  --input assets/images/reference/element_state_sheet_X.png \
+  --x <x> --y <y> --width <w> --height <h> \
+  --output <extracted>.png
+
+# 方法 2: SAM3 语义分割（需精确蒙版时）
+playcraft image segment \
+  --input assets/images/storyboard/master_composite.png \
+  --boxes '[[x1,y1,x2,y2]]' \
+  --output-dir ta-workspace/tmp/seg/
+# → 使用 00_rgba.png（已带透明通道）
+
+# 方法 3: 整图分层（需要从 MC 拆出多个层）
+playcraft image decompose-layers \
+  --input assets/images/storyboard/master_composite.png \
+  --output-dir ta-workspace/tmp/layers \
+  --num-layers 4
+
+# 提取后仍需深色背景验证
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <extracted>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+```
+
+#### bgStrategy = full-coverage（全屏背景）
+
+```bash
+playcraft image info --input <bg_asset>.png --json
+# 验证：尺寸精确匹配 layout-spec 要求
+# 目视检查：四角四边颜色一致，无褪色/渐变/白色边缘/暗角
+```
+
+#### 批量处理
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mjs \
+   ta-workspace/scripts/process-<name>.mjs
+# 修改 CONFIG：
+#   skipRemoveBg = true  (bgStrategy=opaque/full-coverage)
+#   skipRemoveBg = false (bgStrategy=greenscreen/bluescreen/magenta)
+#   removeBgTolerance = 25
+node ta-workspace/scripts/process-<name>.mjs
+```
+
+---
+
+## Step 2 (Technical Production Pipeline)
+
+### Pipeline Selection — 先判断再动手
+
+**Before choosing any specific pipeline, analyze the task's nature.**
+
+| Task Nature                                                                           | Best Pipeline                                          | Why                                               |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------- |
+| **concept/mockup → generate complete asset set**                                      | Sprite Generation (`playcraft-sprite-generation`)      | AI direct generation with reference-image         |
+| **Structure identical, change local details only** (cards suit/rank, icon set symbol) | Edit Model Pipeline (`gen-edit-variants.template.mjs`) | 1 base image × N edits; local consistency highest |
+| **Change material/texture, preserve symbols exactly** (mahjong white→ice/metal/wood)  | 3D white model + texture swap                          | Symbols stay 100% intact as face texture          |
+| **Full creative restyle** (symbols also redesigned)                                   | Sprite Remix (per-frame AI)                            | AI creativity needed for new symbol style         |
+| **Pure color/mood shift**                                                             | Image Processing (tint/blur/grayscale)                 | Simplest, no frame splitting needed               |
+| **Add animation to static elements**                                                  | `animate` presets                                      | Built-in motion presets                           |
+| **Add VFX effects** (explosion, sparkle)                                              | `use-vfx` presets                                      | Pre-built VFX sprite sheets                       |
+| **Remix existing sprite sheet preserving grid layout**                                | Sprite Remix (split→regen→reassemble)                  | Grid topology preserved                           |
+
+**Core decision rule:**
+
+```
+Do you have a complete asset set already, or just a concept/mockup?
+  │
+  ├── JUST A CONCEPT → Sprite Generation pipeline (AI batch generate → smart split → assemble)
+  │
+  └── HAVE EXISTING ASSETS → Need to transform them
+       │
+       ├── Preserve symbols EXACTLY?
+       │    ├── YES → Can swap base material/texture?
+       │    │    ├── YES → 3D white model + texture swap (see ta-3d-flip-recipe.md)
+       │    │    └── NO  → Image Processing (tint/overlay/filter)
+       │    │
+       │    └── NO (symbols also redesigned) → Sprite Remix (per-frame AI)
+       │
+       └── Just color/mood shift? → Image Processing (tint/blur/grayscale)
+```
+
+### Sprite Sheet Pipeline
+
+**JSON 输出规则（必须了解，直接影响 Compliance Gate 和 Developer 集成）：**
+
+| 命令           | JSON 输出        | 网格参数来源                                        | ta-log 记录要求                           |
+| -------------- | ---------------- | --------------------------------------------------- | ----------------------------------------- |
+| `sprite-sheet` | 自动生成 `.json` | JSON 文件本身                                       | 填"见 JSON"                               |
+| `animate`      | **无**           | stdout `Layout: Nx × Ny \| Frame size: WxH`         | **必填** columns/frameW/frameH/frameCount |
+| `use-vfx`      | **无**           | `playcraft image list-vfx --json` 的 frames/columns | **必填** 同上                             |
+
+```bash
+# Scenario A: Generate animation frames from a static image
+playcraft image animate \
+  --input assets/images/tiles/<element>.png \
+  --preset bounce    # spin|bounce|pulse|shake|float|blink|swing|wobble|flip
+  --frames 8 \
+  --output assets/images/tiles/<element>_anim.png \
+  --columns 4
+# → produces <element>_anim.png ONLY (NO JSON)
+# → stdout prints: "Layout: 4x2 | Frame size: 128x128"
+# → RECORD these params in ta-log.md Sprite Grid Params section immediately
+
+# Scenario B: Merge separately generated frames (PREFERRED for animation sequences)
+# Frame filenames MUST be zero-padded: f00.png, f01.png... NOT f0.png, f1.png...
+# sprite-sheet sorts by filename (dictionary order): f0 < f10 < f2 without zero-padding
+playcraft image sprite-sheet \
+  --inputs assets/images/frames/f00.png,f01.png,f02.png \
+  --output assets/images/tiles/<element>_sheet \
+  --columns 4 \
+  --cell-width 64 --cell-height 64
+# → produces <element>_sheet.png + <element>_sheet.json (auto-generated)
+
+# Scenario C: VFX preset sprite sheets
+playcraft image list-vfx --json   # shows frames + columns for each preset
+playcraft image use-vfx \
+  --preset explosion_small \
+  --output assets/images/vfx/explosion.png \
+  --tint "#FF4400" \
+  --scale 1.5
+# → produces explosion.png ONLY (NO JSON)
+# → record from list-vfx: explosion_small has frames=8, columns=4
+
+# Scenario D: Remix / reskin existing sprite sheet
+playcraft image sprite-split \
+  --input assets/images/<source_sheet>.png \
+  --output-dir assets/images/frames_split \
+  --rows 4 --columns 8 --frame-width 100 --frame-height 100
+
+playcraft image sprite-sheet \
+  --input-dir assets/images/frames_remix_nobg/ \
+  --sort name \
+  --output assets/images/<remixed_sheet> \
+  --columns 8 --cell-width 100 --cell-height 100
+
+# Scenario E: Large batch (10+ frames) → write ta-workspace Node.js script
+# See playcraft-image-generation Skill for Node.js templates.
+```
+
+---
+
+### AI 生成精灵图网格的风险警告
+
+**严禁**让 AI 直接生成 `NxM 网格图` 后用 `sprite-split` 切割来得到动画帧。这是动画序列帧生产的错误做法：
+
+```
+❌ 错误做法（动画序列帧）：
+   AI 直接生成 "4x2 grid of bouncing tile, 8 frames" 网格图
+   → sprite-split 切割
+   失败原因：
+   · AI 不理解"网格约束"——每格内容大小不均匀，引擎按固定步长裁剪时错位
+   · 帧出血（frame bleeding）——相邻格内容互相污染边缘，padding=0 时线性过滤加剧
+   · 无 alpha 通道——AI 默认输出 RGB，透明区域变黑色
+   · 帧间视觉不一致——AI 对每格独立理解，角色比例/光照在帧间随机变化
+
+✅ 正确做法（动画序列帧）：
+   1. AI 生成单帧参考图（带绿幕背景：prompt 末尾加 "on solid bright green #00FF00 background"）
+   2. 去背景（remove-background --tolerance 25）→ resize（统一到精确尺寸）
+   3. 对每帧执行步骤 1-2（同模型 + 同 reference，保证风格一致）
+   4. sprite-sheet 合并（几何精确 + 自动输出 JSON）
+
+例外（静态元素集，不是动画）：
+   gpt-image-2 精灵图直出策略（playcraft-image-generation Skill §1.2）
+   适用于：麻将牌面、扑克牌面、Match-3 元素集等「同一静态元素的变体集合」
+   不适用于：动画序列帧（bounce/walk/attack 等）
+```
+
+---
+
+### 精灵图技术验证（Compliance Gate 前必做）
+
+每张精灵图在进入 Compliance Gate 前，必须通过技术验证。不能仅检查"文件是否存在"。
+
+**快速手动验证（所有精灵图）：**
+
+```bash
+# 1. 数学验算：实际尺寸 = 声明的网格参数推算值
+playcraft image info assets/images/tiles/tile_anim.png --json
+# 验证：
+#   width  == columns × frameWidth                      （animate padding 固定为 0）
+#   height == ceil(frameCount / columns) × frameHeight
+#   channels == 4   （如果是 3，说明没有 alpha 通道，透明区域会渲染为黑色）
+
+# 2. 帧名排序警告（sprite-sheet 命令）
+# sprite-sheet 按文件名字典序排帧，数字后缀必须补零对齐
+# ❌ f0.png f1.png f2.png ... f10.png → 字典序: f0 f1 f10 f2（f10 排在 f2 前面！）
+# ✅ f00.png f01.png f02.png ... f10.png → 正确排序
+ls ta-workspace/frames/ | sort   # 确认排序正确
+
+# 3. JSON 内容验证（仅 sprite-sheet 命令输出）
+cat assets/images/tiles/tile_sheet.json | python3 -m json.tool
+# 验证：
+#   frames 中 key 数量 == frameCount
+#   meta.size.w/h == 实际图片尺寸
+#   每个 frame.x/y/w/h 坐标覆盖了正确区域
+```
+
+**自动化验证脚本（批量验证，推荐）：**
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/validate-sprite-sheet.template.mjs \
+   ta-workspace/scripts/validate-sprite-sheet.mjs
+# 编辑 SHEETS 数组，填入所有精灵图的 source/columns/frameWidth/frameHeight/frameCount
+node ta-workspace/scripts/validate-sprite-sheet.mjs
+# → 输出每张图的通过/失败详情 + 汇总
+# → 失败时 exit code = 1，将问题写入 ta-workspace/logs/sprite-validate.log
+```
+
+**常见失败及修复：**
+
+| 失败现象               | 原因                                        | 修复                                    |
+| ---------------------- | ------------------------------------------- | --------------------------------------- |
+| 实际宽度 ≠ cols×frameW | frameWidth 记录错误，或帧图片 resize 不正确 | 确认所有帧已 resize 到完全相同的 W×H    |
+| channels = 3           | 去背景步骤缺失或输出格式为 JPEG             | 确认使用 remove-background + 输出为 PNG |
+| JSON 帧数不匹配        | sprite-sheet 命令未接收到所有输入帧         | 检查 --inputs 列表是否完整              |
+| 帧顺序错乱             | 文件名未补零（f1.png 排在 f10.png 后面）    | 重命名帧文件：f00.png f01.png...        |
+| 帧内容抽查发现空帧     | 裁剪坐标超出图片范围                        | 确认 padding 参数与实际生成命令一致     |
+
+---
+
+### 3D Pipeline
+
+For material/texture swap while preserving symbols or 3D flip animations, see `refs/ta-3d-flip-recipe.md`.
+
+**Option A: AI 3D Model Generation**
+
+```bash
+playcraft tools generate-3d \
+  --input assets/images/storyboard/master_composite_option_<selectedMcOption>.png \
+  --output assets/models/tile \
+  --name tile_base
+
+playcraft 3d info assets/models/tile_base.glb
+playcraft 3d optimize \
+  --input assets/models/tile_base.glb \
+  --output assets/models/tile_base_opt.glb \
+  --texture-size 512
+```
+
+**Option B: White Model + Texture (fastest)**
+
+```bash
+playcraft tools generate-image \
+  --prompt "<texture description, top-down, diffuse map>" \
+  --output assets/textures/tile_face.png
+
+playcraft 3d apply-texture \
+  --model cube \        # sphere|cube|cylinder|cone|torus|plane|capsule
+  --texture assets/textures/tile_face.png \
+  --output assets/models/tile.glb
+```
+
+### Image Post-Processing Pipeline
+
+```bash
+# Standard element pipeline: Generate → Resize → Remove bg → Convert
+playcraft tools generate-image --prompt "..." --output <raw>.png
+playcraft image resize --input <raw>.png --output <spec>.png --width W --height H --fit contain
+playcraft image remove-background --input <spec>.png --output <nobg>.png
+playcraft image convert --input <nobg>.png --output <final>.webp --quality 85
+
+# Color variants (reuse same base element)
+playcraft image tint --input <base>.png --output <variant_blue>.png --color "#0055FF"
+playcraft image tint --input <base>.png --output <variant_red>.png  --color "#FF2200"
+
+# Pixel art style
+playcraft image pixelate --input <src>.png --output <px>.png --pixel-size 8
+
+# Overlay (UI composite)
+playcraft image overlay --base bg.png --overlay icon.png --output composite.png --x 100 --y 200
+```
+
+### Audio Post-Processing Pipeline
+
+```bash
+# Compress BGM to budget
+playcraft audio compress --input assets/audio/bgm/bgm.mp3 --output assets/audio/bgm/bgm.mp3
+
+# Trim SFX to target duration
+playcraft audio trim --input assets/audio/sfx/match.mp3 --output assets/audio/sfx/match.mp3 --end 1.5
+
+# Make BGM seamlessly loopable
+playcraft audio loop --input assets/audio/bgm/bgm.mp3 --output assets/audio/bgm/bgm.mp3
+
+# Add fade out
+playcraft audio fade --input assets/audio/bgm/bgm.mp3 --output assets/audio/bgm/bgm.mp3 --fade-out 2.0
+
+# Verify
+playcraft audio info --input assets/audio/bgm/bgm.mp3
+```
+
+---
+
+## TA agent workflow (L1 → L2 detail)
+
+> **Moved from `agents/technical-artist.md`** — Spec Quick-Check through Compliance Gate, reference-image matrix, DAG edits. **Atlas/WebP defaults:** see `refs/ta-atlas-deliverable-standard.md`.
+
+### Step 0: Spec Quick-Check (30s)
+
+Validate inputs before any work:
+
+- Every `assetMapping` entry has clear size/format requirements → if gaps: `spec-gap` in project-state.md
+- `logs/designer-log.md` exists with Composite path + Style Intent Notes → if missing: `blocked`
+
+### Step 0b: Extract Representative Samples
+
+> **Invoke `playcraft-masking` skill** for segment/remove-background decision tree.
+
+Designer's **ASR sheets** (UI + element state reference) contain **representative states** (2-3 per type), not full sets. Your job:
+
+1. From **ASR** (preferred): `crop` each state slot → `resize` to spec → these become your `--reference-image` for Stage A batch generation
+2. From **Master Composite** (fallback): extract elements not covered in ASR
+3. Check `designer-log.md` **ASR State Inventory** — note which states are covered vs which need expansion
+4. Background: generate clean bg using composite as `--reference-image`
+5. Text assets: → **invoke `playcraft-text-rendering` skill**
+6. Representative quality insufficient → ICP request to Designer for supplementary samples
+
+**ASR 提取方法（按优先级）**：
+
+> ⚠️ **严禁对 ASR 网格布局图使用纯 text prompt 的 segment！** 使用 `designer-log` 中的槽位坐标 + `crop`。
+
+```
+ASR 是已知网格布局？（ui_state_sheet / element_state_sheet，行列分明）
+├─ 是 → 方法 1: crop 直切（最可靠，零歧义）
+│        1. playcraft image info --input assets/images/reference/ui_state_sheet_<X>.png  → 获取尺寸
+│        2. 从 designer-log ASR State Inventory 读取行列与 bbox
+│        3. playcraft image crop --input <asr_sheet> --x <x> --y <y> --width <w> --height <h> --output <out>
+│        4. 对有背景底色的元素：crop 后再 remove-background --method floodfill
+│
+├─ 元素位置不规则但 bbox 已知 → 方法 2: segment --boxes（精确框选）
+│        segment --input <asr_sheet> --boxes '[[x1,y1,x2,y2]]' --output-dir <dir>
+│
+└─ 仅 MC 有该类型 → 方法 3: decompose-layers 或 segment --text（最后手段，见 playcraft-masking）
+```
+
+**常见踩坑**：
+
+- ❌ `segment --text "apple tile icon"` → SAM3 可能只切出苹果图案，丢失 tile 方块底板
+- ❌ `segment --text "panda character"` → 图上有 panda face tile + panda 角色，会返回多个 instance，score 最高的不一定是你要的
+- ✅ `playcraft image crop --x 50 --y 50 --width 400 --height 400` → 精确、零歧义
+- ✅ `segment --boxes '[[50,50,450,450]]'` → 框选已知位置的元素
+
+### Step 0c: Style Interpretation Check
+
+> **Invoke `playcraft-style-qa` skill** for methodology.
+
+Read designer-log Style Intent Notes → write interpretation table to `ta-log.md` → confidence low = blocked, medium = proceed with caution, high = proceed.
+
+### Step 0d: Production Plan (mandatory, before any generation)
+
+> **Purpose:** Converge on full asset coverage and pipeline order before bulk production.
+
+Write `logs/ta-log.md` § **Production Plan** with:
+
+1. **Coverage Plan** — one row per `layout-spec` `assetMapping` entry (contract path, pipeline type, reference source, priority)
+2. **Atlas Assembly Plan** — one row per atlas group from layout-spec grouping table (output `.webp` + `.json`, frameIds, grid layout)
+3. **Pipeline Order** — numbered steps (Extract → Complete → Process → Assemble → Verify)
+4. **Risk Checklist** — all items checked `[x]`
+
+**Rules:**
+
+- Coverage Plan row count must equal `assetMapping` entry count (no gaps)
+- Atlas groups must match layout-spec § atlas grouping table
+- **MUST NOT** start Step 1 bulk generation until Risk Checklist is fully checked
+- `validate-workflow-stop.mjs` blocks STOP if Plan is incomplete
+
+---
+
+### Step 0e: Asset Transparency Classification (mandatory, before any generation)
+
+> **Purpose:** 根据 `layout-spec.md` 的 `assetMapping` 路径约定 + 元素色彩分析，自动推导每个资产的透明度需求和色幕策略，确定完整的处理管线。**此步骤在 Production Plan 完成后、Step 1 批量生成前执行。**
+
+**根因认知**：当前所有 AI 模型均不支持原生透明 PNG（`ALPHA = no`）。不做透明度处理 → 所有素材"生成就完事" → UI 叠加元素白底、VFX 黑块、HUD 数字白底、图标白底等系统性问题。**PlayCraft CLI 提供了完整的透明度工具链（`remove-background` / `segment` / `decompose-layers`），TA 必须显式使用。**
+
+#### 1. 从路径约定推导 needsAlpha
+
+遍历 `layout-spec.md` 的 `assetMapping`，根据**路径目录**自动判断每个资产是否需要透明背景：
+
+```
+assetMapping 路径所在目录？
+│
+├─ assets/images/bg/     → needsAlpha = false（全屏背景，不透明）
+├─ assets/images/ui/     → needsAlpha = true （UI 叠加层，必须透明）
+├─ assets/images/txt/    → needsAlpha = true （文字图片，必须透明）
+├─ assets/images/vfx/    → needsAlpha = true （特效精灵图，必须透明）
+├─ assets/images/tiles/  → needsAlpha = true （默认；除非是卡牌/棋子矩形实体）
+├─ assets/audio/         → N/A（非图片）
+└─ 其他路径              → 按素材用途判断：叠加在其他图层上 = true，独立全屏 = false
+```
+
+**卡牌/棋子等矩形实体例外**：虽然路径在 `tiles/`，但白色牌面是资产本体的一部分，不需要透明。TA 根据 `design-brief` 的 Style Direction + `designer-log` 的样本判断。
+
+#### 2. 从元素色彩推导 bgStrategy（色幕选型）
+
+对每个 `needsAlpha = true` 的资产，根据元素主色调选择色幕颜色。色调信息来源：
+
+- `layout-spec.md` 的 Color Palette（elementId → hex color）
+- `design-brief.md` 的 Style Direction（整体色温描述）
+- `designer-log.md` 的样本（实际视觉参考）
+
+**色幕选型矩阵**：
+
+| 元素主色调            | ❌ 禁用色幕  | ✅ 推荐色幕      | 原因                                                 |
+| --------------------- | ------------ | ---------------- | ---------------------------------------------------- |
+| 金色/黄色/橙色/琥珀色 | 绿幕 #00FF00 | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），floodfill 残留绿色边缘 |
+| 绿色/翠绿/青色        | 绿幕 #00FF00 | **蓝幕 #0000FF** | 同色系，floodfill 无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕 #0000FF | **绿幕 #00FF00** | 同色系冲突                                           |
+| 红色/粉色/白色/黑色   | —            | 绿幕或蓝幕均可   | 与两者色相距离都大                                   |
+| 多色/彩虹             | —            | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）                 |
+
+**特殊规则**（不按元素色彩，按资产类型固定）：
+
+| 资产类型               | 固定色幕         | 原因                                                 |
+| ---------------------- | ---------------- | ---------------------------------------------------- |
+| VFX 发光/粒子/选中高亮 | **蓝幕 #0000FF** | VFX 普遍含暖色调（金色火焰、橙色爆炸），绿幕必出残留 |
+| 文字/数字图片          | **蓝幕 #0000FF** | 文字常为金色/白色/浅色，绿幕边缘污染                 |
+| 全屏背景               | N/A（不去背景）  | prompt 加 `"full bleed, edge to edge, no vignette"`  |
+| 矩形实体（卡牌/棋子）  | N/A（不去背景）  | 白底是资产本身，skipRemoveBg = true                  |
+
+#### 3. 填写 Transparency Classification 表
+
+```markdown
+## Transparency Classification
+
+| assetMapping path             | needsAlpha | bgStrategy    | 去背工具（第一选择）                  | 回退工具                                    | 验证方法             | 验证结果 |
+| ----------------------------- | ---------- | ------------- | ------------------------------------- | ------------------------------------------- | -------------------- | -------- |
+| assets/images/bg/bg_main.webp | false      | full-coverage | N/A                                   | N/A                                         | 边缘全覆盖检查       | ❓       |
+| assets/images/ui/btn_cta.webp | true       | greenscreen   | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/ui/digits.webp  | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/vfx/glow.webp   | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes`                           | 逐帧深色背景 overlay | ❓       |
+| assets/images/tiles/tile.webp | true       | greenscreen   | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/txt/title.webp  | true       | bluescreen    | `remove-background --floodfill -t 25` | `remove-bg --method ai`                     | 深色背景 overlay     | ❓       |
+```
+
+#### 4. 去背工具链（按 bgStrategy 执行）
+
+> **PlayCraft CLI 提供了完整的透明度处理工具链，TA 必须按决策树显式使用，不能跳过去背景步骤。**
+
+| bgStrategy    | 生成 prompt 后缀                                                    | 第一选择去背工具                                   | 回退工具（第一选择效果不好时）                     |
+| ------------- | ------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- |
+| greenscreen   | `"on solid bright green #00FF00 background, isolated, centered"`    | `playcraft image remove-background --tolerance 25` | `playcraft image segment --boxes` 或 `--method ai` |
+| bluescreen    | `"on solid bright blue #0000FF background, isolated, centered"`     | `playcraft image remove-background --tolerance 25` | `playcraft image segment --boxes` 或 `--method ai` |
+| magenta       | `"on solid bright magenta #FF00FF background, isolated, centered"`  | `playcraft image remove-background --tolerance 20` | `playcraft image remove-background --method ai`    |
+| extract       | 无特殊后缀（从 MC/ASR 提取）                                        | `playcraft image crop` 或 `segment --boxes`        | `playcraft image decompose-layers`（整图分层）     |
+| full-coverage | `"full scene, full bleed, edge to edge, no vignette, no fade"`      | N/A（不去背景）                                    | N/A                                                |
+| opaque        | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | N/A（不去背景）                                    | N/A                                                |
+
+**工具选型决策树**（TA 必须按此执行，不可跳步）：
+
+```
+needsAlpha = true?
+├─ 是 → 按色幕选型矩阵确定色幕颜色
+│       → Step A: 生成时 prompt 加色幕后缀
+│       → Step B: playcraft image remove-background --method floodfill --tolerance 25
+│       → Step C: playcraft image info --json → channels == 4?
+│           ├─ channels=4 → Step D: 深色背景 overlay 验证
+│           │   ├─ 通过 → ✅ 记录结果
+│           │   └─ 边缘有残留 → 回退工具链：
+│           │       ├─ 纯色残留少量 → 调高 tolerance (25→40→60) 重试
+│           │       ├─ 复杂边缘/不规则形状 → playcraft image segment --boxes (SAM3)
+│           │       ├─ 毛发/半透明/复杂背景 → playcraft image remove-background --method ai
+│           │       └─ 仍然不行 → playcraft image segment --text (最后手段)
+│           └─ channels=3 → 输出可能是 JPEG，确保 --output 为 .png 后缀
+│
+├─ needsAlpha = true 且从 MC/ASR 提取（非 AI 生成）?
+│   → 优先: playcraft image crop (已知网格布局/坐标)
+│   → 次选: playcraft image segment --boxes (已知大致位置，需精确蒙版)
+│   → 回退: playcraft image segment --text (位置未知，描述要极其具体)
+│   → 整图分层: playcraft image decompose-layers (需拆出多层时)
+│   → Step D: 深色背景 overlay 验证
+│
+├─ needsAlpha = false（full-coverage 全屏背景）?
+│   → 不做去背景
+│   → 验证：playcraft image info 确认尺寸 → 四角四边颜色一致，无褪色/白色/渐变
+│
+└─ needsAlpha = false（opaque 矩形实体）?
+    → 不做去背景，直接 resize（skipRemoveBg = true）
+```
+
+#### 4. 验证清单（生成后必做）
+
+**每个 `needsAlpha=true` 的资产，去背景后必须做以下验证：**
+
+```bash
+# A. Alpha 通道检查 — channels 必须 = 4
+playcraft image info --input <asset>.png --json
+# 验证: channels == 4 (若 channels == 3，说明没有 alpha 通道)
+
+# B. 深色背景渲染验证 — 在 #1A1A2E 深色底上叠合查看
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <asset>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留、无黑块、边缘干净
+
+# C. 背景图全覆盖检查（仅 bgStrategy=full-coverage）
+playcraft image info --input <bg_asset>.png --json
+# 验证：尺寸精确匹配 layout-spec 要求
+# 目视检查：四角四边颜色一致，无褪色/渐变/白色边缘
+```
+
+**验证用深色底图生成（一次即可，全项目复用）**：
+
+```bash
+# 生成 512x512 深色验证底图
+node -e "
+const sharp = require('sharp');
+sharp({ create: { width: 512, height: 512, channels: 4, background: { r: 26, g: 26, b: 46, alpha: 1 } } })
+  .png().toFile('ta-workspace/tmp/dark_verify_bg.png');
+"
+```
+
+**批量验证脚本（>5 个透明资产时推荐）**：
+
+```bash
+# 为每个需要透明的资产批量叠合验证
+for f in assets/images/ui/*.png assets/images/vfx/*.png assets/images/txt/*.png; do
+  name=$(basename "$f" .png)
+  playcraft image overlay \
+    --base ta-workspace/tmp/dark_verify_bg.png \
+    --overlay "$f" \
+    --output "ta-workspace/tmp/verify_${name}.png" \
+    --gravity center
+  echo "[VERIFY] $name → ta-workspace/tmp/verify_${name}.png"
+done
+# 逐张目视检查输出，发现问题立即记录到 ta-log
+```
+
+#### 5. 写入 ta-log.md
+
+在 `logs/ta-log.md` § Transparency Classification 表中填写验证结果：
+
+```markdown
+## Transparency Classification
+
+| #   | Contract Path                 | needsAlpha | bgStrategy    | 去背工具                         | 验证结果                    |
+| --- | ----------------------------- | ---------- | ------------- | -------------------------------- | --------------------------- |
+| 1   | assets/images/ui/btn_cta.webp | true       | greenscreen   | remove-background floodfill t=25 | ✅ channels=4, 深色验证通过 |
+| 2   | assets/images/txt/title.webp  | true       | bluescreen    | remove-background floodfill t=25 | ✅ channels=4, 深色验证通过 |
+| 3   | assets/images/ui/icons.webp   | true       | segment       | segment --boxes + crop           | ✅ channels=4, 深色验证通过 |
+| 4   | assets/images/bg/bg_main.webp | false      | full-coverage | N/A                              | ✅ 全覆盖检查通过           |
+```
+
+**MUST NOT** 进入 Step 1 批量生成，除非 Transparency Classification 表完成且无 `❓` 未决项。
+
+---
+
+### Step 1: Skill Discovery
+
+- Part A: `playcraft skills list/match` → find pipeline Skills → write to atom-plan `## TA Skill Context`
+- Part B: `playcraft skills scaffold <skillRef> --dry-run` for each atom → extract prompt/model params  
+  (See **Step 0** above for bash examples.)
+
+### Pipeline model (E → T → A → B → C → D)
+
+```
+Gate #2 → TA starts
+   │
+   ├─ 0a: Upstream Intake
+   ├─ 0b: Extract (E) — decompose-layers or segment references from composites
+   ├─ 0c: Style Interpretation Check
+   ├─ 0d: Production Plan
+   ├─ 0e: Transparency Classification ← NEW (classify all assets, select chroma key per color matrix)
+   │
+   ├─ T: Transparency-aware generation (Step 1 with correct chroma key per 0e table)
+   │    │
+   │    ├─ C₁: generate-3d (if referenceSource="designer-sample")
+   │    │
+   │    ├─ A: Batch Element Generation (sprite sheet per type, chroma key per 0e)
+   │    │    │
+   │    │    ├──→ B: animate / sprite-sheet / use-vfx (VFX always blue screen)
+   │    │    └──→ C₂: apply-texture (if referenceSource="ta-completion")
+   │    │
+   │    └─ (extraction insufficient → ICP → Designer supplementary)
+   │
+   ├─ Step 4: Process (remove-bg per chroma → dark-bg verify each asset)
+   │
+   ├─ D: Audio post-processing (independent, waits for Designer Ph.2 audio)
+   │
+   └─ All done → Compliance Gate (incl. Transparency checks)
+```
+
+### Pipeline selection (quick)
+
+| Situation                          | Pipeline                        | Skill/Ref                     |
+| ---------------------------------- | ------------------------------- | ----------------------------- |
+| Multi-element batch (>3 same type) | Sprite sheet one-shot → split   | `playcraft-sprite-generation` |
+| Add animation to static element    | animate presets → sprite-sheet  | `playcraft-vfx-animation`     |
+| Add VFX (glow/particle/trail)      | use-vfx presets                 | `playcraft-vfx-animation`     |
+| 3D model + texture                 | generate-3d → apply-texture     | `refs/ta-3d-flip-recipe.md`   |
+| Color/mood shift only              | Image processing (tint/overlay) | `playcraft-image-ops`         |
+| Background removal                 | floodfill / AI / SAM3           | `playcraft-masking`           |
+
+### Stage A: Batch Element Generation
+
+> **Invoke the `playcraft-sprite-generation` skill** for the complete workflow.
+
+| Step           | Action                                                         | Done when                                    |
+| -------------- | -------------------------------------------------------------- | -------------------------------------------- |
+| A.1 Define     | Write spec (count/grid/sizes/full element list) to `ta-log.md` | List count = assetMapping count              |
+| A.2 Prompt     | Write five-section prompt to `ta-log.md`                       | Follows Scene/Canvas/Set/Details/Constraints |
+| A.3 Review     | 9-item checklist                                               | All pass                                     |
+| A.4 Generate   | One-shot full sprite sheet                                     | Image + .json sidecar output                 |
+| A.5 Verify+Fix | Check each cell → fix errors with targeted regen               | Error ≤ 30% fixed; >30% redo from A.2        |
+| A.6 Split      | Crop + replace fixes + final verify                            | File count = list count, dims match          |
+
+### Stage B: Animation + VFX
+
+> **Invoke `playcraft-vfx-animation` skill** for preset catalog, decision tree, and game-type recipes.
+
+Triggered per Stage A output that needs animation. Output: sprite sheet with grid params recorded in `ta-log.md`.
+
+### Stage C: 3D Pipeline
+
+> **Read `refs/ta-3d-flip-recipe.md`** for material reskin and 3D flip workflows.
+
+- C₁ (referenceSource="designer-sample"): starts immediately after extraction
+- C₂ (referenceSource="ta-completion"): waits for Stage A output
+
+### Stage D: Audio Post-Processing
+
+Independent track, waits only for Designer Ph.2 audio delivery:
+
+- `playcraft audio compress/trim/loop/fade` as needed per layout-spec requirements
+- Record all processing in `ta-log.md`
+
+### Compliance Gate (full checklist)
+
+| Check                                   | Criteria                                                                                                               |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| All assetMapping files exist            | Zero missing                                                                                                           |
+| Image dimensions match assetSpec        | Exact match                                                                                                            |
+| Image format                            | **WebP** for runtime deliverables per `ta-atlas-deliverable-standard`; PNG/JPG only if layout-spec explicitly requires |
+| Sprite / atlas grid params              | In ta-log.md (cols/frameW/frameH/frameCount); `.json` beside each atlas                                                |
+| **Transparency Classification**         | ta-log.md has Transparency Classification table; all rows have 验证结果 (no `❓`)                                      |
+| **Alpha channel (transparent)**         | All assets marked 需要透明=✅ have `channels=4` (`playcraft image info --json`)                                        |
+| **Dark-bg render verify (transparent)** | All transparent assets verified on #1A1A2E dark background — no white edge, no chroma residue, no black blocks         |
+| **Background full-coverage**            | All full-screen backgrounds: edges extend to all four sides, no fade/vignette/white corners                            |
+| **Atlas per-frame verify**              | Each frame in atlas verified individually on dark background (especially VFX glow/particle frames)                     |
+| Audio format                            | MP3 after TA post-process                                                                                              |
+| No external dependencies                | Standalone files                                                                                                       |
+| Style Interpretation completed          | ta-log.md has interpretation table                                                                                     |
+| No open TA questions                    | intent-clarifications.md clear                                                                                         |
+
+> **TA 阶段不管体积。** 品质和规格合规是唯一目标。体积优化在 Developer build 阶段。
+
+**Transparency compliance 不通过的常见原因及修复**：
+
+| 失败现象                | 根因                                 | 修复                                              |
+| ----------------------- | ------------------------------------ | ------------------------------------------------- |
+| channels=3（无 alpha）  | 去背景步骤遗漏，或输出为 JPEG        | 对原图执行 remove-background，确保输出 PNG        |
+| 深色验证见白边          | 生成时未用色幕，白底未完全去除       | 用正确色幕重新生成 + remove-background            |
+| 深色验证见绿色/蓝色残留 | 色幕选型错误（素材色与色幕撞色）     | 按色幕选型矩阵换用另一种色幕重新生成              |
+| VFX 帧出现黑色不透明块  | 发光/粒子生成时未加色幕              | 用蓝幕重新生成每一帧                              |
+| 背景图四角有白色/褪色   | prompt 未约束 edge-to-edge           | prompt 加 "full bleed, edge to edge, no vignette" |
+| 文字/数字图底色未去除   | 未分类为"需要透明"，直接 resize 交付 | 回查 Transparency Classification → 补做去背景流程 |
+
+**After compliance**: Write `logs/ta-log.md` manifest → mark atoms `✅ done` → update project-state.md.
+
+### Reference image rules
+
+| CAPABILITY    | `--reference-image` | Models                                    |
+| ------------- | ------------------- | ----------------------------------------- |
+| `text+image`  | ✅ optional         | gpt-image-2, nano-banana-2, gemini-flash  |
+| `image→image` | ✅ required         | qwen-image-edit-max, wan2.6-image         |
+| `text→image`  | ❌ not supported    | hy-image-lite, qwen-image-max, flux-2-pro |
+
+**Same model for same element set** — consistency requires identical model across a batch.
+
+### DAG modification protocol
+
+- Redundant atom → `⏭️ skipped`
+- Missing asset → add row, assign to TA
+- Direction changes → **STOP and report**
+- Always append to DAG Revisions