@playcraft/cli 0.0.39 → 0.0.41

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

@@ -0,0 +1,699 @@
+# 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 (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
+```
+
+---
+
+## 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 + 验证）
+
+> **先判断素材类型，再决定是否需要去背景**（参见 playcraft-image-generation Skill 4.5 节背景处理决策树）
+
+**卡牌 / 棋子 / UI 面板（矩形本体，不需要透明背景）**：
+
+```bash
+# 直接 resize，不做去背景（白色牌面就是牌的一部分！）
+playcraft image resize --input <file>.png --output <file>.png --width <W> --height <H> --fit contain
+```
+
+批量处理使用 `process-batch.template.mjs` 并设置 `CONFIG.skipRemoveBg = true`。
+
+**独立元素（角色/道具/图标，需要透明背景）→ 绿幕策略**：
+
+生图时 prompt 末尾加 `"on solid bright green #00FF00 background, isolated, centered"`（当前所有模型 ALPHA = no，无原生透明输出），然后：
+
+```bash
+# 绿幕抠图（tolerance=25 对绿色效果最好）
+playcraft image remove-background --input in.png --output out.png --tolerance 25
+```
+
+**批量处理 → ta-workspace 脚本模板**：
+
+```bash
+cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mjs \
+   ta-workspace/scripts/process-<name>.mjs
+# 修改 CONFIG（特别是 skipRemoveBg 和 removeBgTolerance）后运行
+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 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 → A → B → C → D)
+
+```
+Gate #2 → TA starts
+   │
+   ├─ E: Extract (Step 0b) — decompose-layers or segment references from composites
+   │    │
+   │    ├─ C₁: generate-3d (if referenceSource="designer-sample")
+   │    │
+   │    ├─ A: Batch Element Generation (sprite sheet per type)
+   │    │    │
+   │    │    ├──→ B: animate / sprite-sheet / use-vfx
+   │    │    └──→ C₂: apply-texture (if referenceSource="ta-completion")
+   │    │
+   │    └─ (extraction insufficient → ICP → Designer supplementary)
+   │
+   ├─ D: Audio post-processing (independent, waits for Designer Ph.2 audio)
+   │
+   └─ All done → Compliance Gate
+```
+
+### 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                                                |
+| 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 阶段。
+
+**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