@playcraft/cli 0.0.44 → 0.0.47

package/project-template/.claude/agents/refs/storyboard-generation-guide.md

@@ -0,0 +1,110 @@
+# Storyboard Generation Guide — MC 5-Panel 生产流程
+
+> **用途**：Orchestrator 在 **ring 3 `loop: clarify`** spawn storyboard subagent 时注入的执行指南。Subagent 按本文件流程，通过 Skill tool 加载具体规范，完成 Master Composite 生产。
+>
+> **产出终点**：≥2 套 MC 选项 + `style-exploration.md` § Master Composite 写入 + `artist-log.md` § Image Production Preflight 填写完毕。
+
+## 输入（由 Orchestrator 提供或 subagent 自行读取）
+
+| 文件                   | 关注内容                                                               |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `docs/design-brief.md` | 游戏类型、核心玩法、目标受众、Hook 策略、Style Direction、元素类型     |
+| `docs/DESIGN.md`       | 玩家体验契约、Experience Flow、元素种类                                |
+| `docs/atom-tree.json`  | `meta.selectedAtoms` 概览（了解哪些元素需要出现在 Panel 1）— if exists |
+
+> **Note**: `layout-spec.md` does not exist yet at ring 3 MC generation. Element types and style direction come from `design-brief.md` and `DESIGN.md`.
+
+---
+
+## Step 1 — Image Production Preflight
+
+**目标**：在生成任何图片前，系统性读取相关 Skills 并记录决策。
+
+**操作**：
+
+1. 使用 Skill tool 依次加载以下 Skills，每个读完后在 `logs/artist-log.md` § **Image Production Preflight** 标记 ✓ 并写一行决策摘要：
+
+| #   | Skill                        | 重点阅读段落                            | 决策内容                                   |
+| --- | ---------------------------- | --------------------------------------- | ------------------------------------------ |
+| 1   | `playcraft-storyboard`       | §0 尺寸原则、§1 五格内容、§3 模型白名单 | 布局选择（横排/网格）、分辨率档位（2K/4K） |
+| 2   | `playcraft-image-generation` | §3 模型选择决策树、§3.1 背景色幕策略    | 为 MC 选定模型（仅白名单内）               |
+| 3   | `playcraft-art-style-guide`  | 9 风格决策树                            | 为方案 A/B 各选定风格方向关键词            |
+| 4   | `playcraft-ad-psychology`    | Hook 类型 + 面板心理学映射              | Panel 2-5 的心理学策略选择                 |
+
+2. 在 `artist-log.md` 中确认：
+   - 每个 Skill 行 ✓ + 决策摘要
+   - 从 `docs/design-brief.md` / `docs/DESIGN.md` 统计的元素类型列表
+
+**禁止**：未完成 Preflight 就开始生成 MC。
+
+---
+
+## Step 2 — 生成 Master Composite（≥2 方案）
+
+**目标**：产出至少 2 套不同风格方向的 5-panel MC，供用户在 **ring 3 Ring Gate** 选择。
+
+**执行规范**（从 Skill 获得，此处仅为流程提示）：
+
+1. **Prompt 构造**：
+   - 按 `playcraft-storyboard` §2 Prompt 公式结构
+   - Panel 1（concept panel）：**必须包含 design-brief / DESIGN.md 中定义的所有 element type**
+   - Panels 2-5：根据 Step 1 选定的 Hook 心理学策略设计内容
+   - 游戏类型对应的 prompt 配方参考：`.claude/agents/refs/artist-master-composite-recipes.md`
+
+2. **生成参数**：
+   - 模型：**仅** `playcraft-storyboard` §3 白名单内（`mulerouter/gpt-image-2` 或 `mulerouter/nano-banana-2`）
+   - 尺寸：`--aspect-ratio 45:16 --width 3600 --height 1280`（2K）或 `--width 4096 --height 1455`（4K）
+   - 多方案差异来自 **prompt / 配色 / 构图 / 风格关键词**，不是换弱模型
+
+3. **生成后验收**（每张必做）：
+
+   ```bash
+   playcraft image info --input assets/images/storyboard/master_composite_option_[X].png
+   ```
+
+   - 总宽高比 width/height ≈ **2.81**（45:16）
+   - 单格推算 (width÷5) : height ≈ **9:16**（0.5625）
+   - 不合格 → **必须重生成**
+
+4. **输出命名**：
+   ```
+   assets/images/storyboard/master_composite_option_A.png
+   assets/images/storyboard/master_composite_option_B.png
+   ```
+
+---
+
+## Step 3 — 写入 style-exploration.md + 完成
+
+**目标**：将 MC 成果写入项目文档，为 ring 3 Ring Gate 准备材料。
+
+1. 在 `docs/style-exploration.md` 的 **Master Composite** 部分写入：
+   - 每套方案的图片路径
+   - 风格关键词
+   - 体验流文字说明（5 panels 的叙事逻辑）
+   - **此时不写 ASR 路径**（ASR 是后续 Artist 的工作）
+
+2. 确认所有 MC 文件已生成 + 验收通过。
+
+---
+
+## 完成条件
+
+| #   | 检查项               | 标准                                                         |
+| --- | -------------------- | ------------------------------------------------------------ |
+| 1   | Preflight            | `artist-log.md` § Image Production Preflight 4 行 Skill 均 ✓ |
+| 2   | MC 数量              | ≥2 方案（option_A + option_B 至少）                          |
+| 3   | MC 比例              | 每张 `playcraft image info` 验证通过（≈2.81）                |
+| 4   | Panel 1              | 包含 design-brief / DESIGN.md 所有 element type（目视）      |
+| 5   | style-exploration.md | MC 部分已写入路径 + 风格 + 体验流                            |
+| 6   | 模型合规             | 仅使用白名单模型（带 `mulerouter/` 前缀）                    |
+
+---
+
+## 注意事项
+
+- **不做 ASR** — 那是 Artist 在 ring 3 Ring Gate（MC 选定）后的工作
+- **不做音频** — 那是 Artist Phase 2 的工作
+- **不更新项目状态** — Orchestrator 负责通过 `npm run state:set` 做 handoff 更新
+- **英文 prompt** — 所有图片生成 prompt 使用英文
+- **JSON sidecar** — 生成后检查自动产生的 `.json` 文件，确认 aspectRatio/imageSize 正确

package/project-template/.claude/agents/refs/ta-atlas-deliverable-standard.md

@@ -1,7 +1,7 @@
 # TA Atlas Deliverable Standard
 
-> **When**: `stage: production` branch in `technical-artist.md` § Runtime.  
-> **Contract source**: `layout-spec.md` atlas groups + `assetMapping` (Gate #1 locked).
+> **When**: ring 4 `loop: build` Wave 2 branch in `technical-artist.md` § Runtime.  
+> **Contract source**: `layout-spec.md` atlas groups + `assetMapping` (ring 2 layout-spec lock).
 
 ## Defaults
 
@@ -15,7 +15,7 @@
 
 ## Atlas grouping rules
 
-1. Read PM's **atlas grouping table** in `layout-spec.md` (group name → elementIds → `atlasPath`).
+1. Read Game Designer's **atlas grouping table** in `layout-spec.md` (group name → elementIds → `atlasPath`).
 2. **≥2 elements in same group** → TA MUST deliver **one** `.webp` + `.json`; map each element via `frameId` in assetMapping.
 3. **Do not** split one group into scattered files.
 4. **Exceptions** (single file OK): full-screen background, digit strip, MC/ASR reference (non-runtime), animation-only atlases (one animation = one atlas).
@@ -28,7 +28,7 @@
    playcraft image convert --input atlas.png --output assets/images/tiles/tiles_atlas.webp --quality 85
    ```
 3. Validate sidecar JSON: frame count = element count in group; grid params in `ta-log.md`.
-4. Audio: Designer MP3 → `playcraft audio compress/trim/loop/fade` → output **MP3**; verify with `playcraft audio info`.
+4. Audio: Artist MP3 → `playcraft audio compress/trim/loop/fade` → output **MP3**; verify with `playcraft audio info`.
 
 ## Transparency requirements
 

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

@@ -1,34 +1,38 @@
-# TA Pipeline Cookbook
+---
+readWhen: 'Technical Artist Wave 2 only; read Step 0a first, then continue section by section'
+---
+
+# TA (Technical Artist, 技术美术) 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.
+> Read by Technical Artist at **production** Wave 2 entry (**Step 0a → 0 → 1 → 2** in order). **Prerequisite:** Production Pipeline Wave 1 (Artist Ph.2) = `done` — orchestrator invokes TA only after Artist 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).
+> **Purpose:** Understand what Game Designer locked, what Artist delivered, and what Wave 1 added — without re-reading everything in four docs (Game Designer/Artist keep them concise; narrative lives in style-exploration + artist-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
+npm run state:get -- --json  # current ring, gate route, 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/atom-tree.json      # selectedAtoms + mediaGroups only; no execution status
+cat docs/atom-tree.md        # reading guide + mediaGroups decisions
 cat docs/style-exploration.md
-cat logs/designer-log.md
+cat logs/artist-log.md
 ls assets/images/reference/   # MC + ASR paths
-ls assets/audio/              # Designer Ph.2 raw audio (if present)
+ls assets/audio/              # Artist 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      |
+| 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-tree.json`    | TA atom list + dependencies                                 |
+| `atom-tree.md`      | Acceptance Criteria + reading guide + mediaGroups decisions |
+| `style-exploration` | Confirmed MC path + per-panel visual intent                 |
+| `artist-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.
 
@@ -36,11 +40,11 @@ ls assets/audio/              # Designer Ph.2 raw audio (if present)
 
 ## 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.**
+> **Purpose:** `atom-tree.json` → `skillsMatch.mediaGroups` contains pre-matched reusable assets from the skills library. These assets are selected by temporary atom-selection / ref-flow, not Game Designer. **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'
+# 1. Read mediaGroups from atom-tree.json
+cat docs/atom-tree.json | jq '.meta.skillsMatch.mediaGroups'
 ```
 
 For each mediaGroup entry:
@@ -56,11 +60,7 @@ 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>" }
-```
+4. **Update production handoff** immediately: record the linked output path in `logs/ta-log.md` and `handoffContext` for Developer. Do not write execution status or output paths into `atom-tree.json`.
 
 5. **If NOT matched or quality insufficient** — proceed to Step 0 Skill Discovery + Step 1 generation as normal; document reason in `dagRevisions`:
 
@@ -76,7 +76,7 @@ cp $(playcraft skills read <mediaGroup_atomId> --path) <assetMapping_path>
 
 ---
 
-## Step 0 (Skill Discovery) → Enrich TA Skill Context
+## Step 0 (Skill Discovery)
 
 Before executing any atom, run two rounds of Skill Discovery:
 
@@ -100,10 +100,10 @@ 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:
+For every atom assigned to TA with a non-empty `skillRef` in `atom-tree.json` `meta.selectedAtoms`, read its generation recipe:
 
 ```bash
-# Read generation recipe from PM-assigned skillRef
+# Read generation recipe from Game Designer-assigned skillRef
 # Replace <skillRef> with the atom's skillRef value (e.g., jewel_tile.aiimage)
 playcraft skills scaffold <skillRef> --dry-run
 ```
@@ -121,11 +121,11 @@ playcraft skills scaffold jewel_tile.aiimage --dry-run
 #   model: gpt-image-2
 #   variants: blue sapphire / red ruby / green emerald / yellow topaz
 
-# Step 2: Generate using recipe prompt + Designer reference for style consistency
+# Step 2: Generate using recipe prompt + Artist 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
+  --reference-image assets/images/tiles/tile_01.png \      # Artist's approved sample
   --aspect-ratio 1:1 \
   --image-model gpt-image-2 \                              # recipe-recommended model
   --output assets/images/tiles/tile_02.png
@@ -133,24 +133,18 @@ playcraft tools generate-image \
 
 **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.
+If `skillRef` is `—` or empty for an atom, skip Part B for that atom and rely on Artist's Style Intent Notes alone.
 
 ---
 
-### Write findings into `docs/atom-plan.md` under `## TA Skill Context`
+### Optional: append concise findings into `docs/atom-tree.md` under `## Execution 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
+- Production approach: derive from Artist sample using reference-image
+- Watch Out: preserve recipe semantics, but let project style references dominate the final look
+- Notes: generated remaining tile colors from recipe prompt + MC / ASR reference
 ```
 
 ---
@@ -208,8 +202,8 @@ cat .claude/skills/playcraft-sprite-generation/SKILL.md
 # 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
+# Check what Artist has already delivered
+cat logs/artist-log.md
 ls assets/images/tiles/
 ls assets/images/bg/
 ls assets/images/ui/
@@ -225,7 +219,7 @@ 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
+ls assets/images/tiles/  # Artist's samples
 ```
 
 ### Step 3: Complete Missing Elements
@@ -235,17 +229,17 @@ ls assets/images/tiles/  # Designer's samples
 **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 提炼
+2. **Artist Style Intent Notes**（`logs/artist-log.md`）— 无 skillRef 或 recipe 不够具体 → 从 Style Intent Notes 提炼
 3. **design-brief StyleDirection** — 兜底，最通用
 
 **少量元素（逐个生成）**：
 
 ```bash
-# prompt = atom Skill recipe 模板（已在 TA Skill Context 中提取）+ Designer style notes
+# prompt = atom Skill recipe 模板（来自 atom-tree.md `Per-Skill Reading Notes`）+ Artist 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 样本（若有）
+  --reference-image assets/images/tiles/<artist_sample>.png \  # Artist 样本（若有）
   --output assets/images/tiles/<new_element>.png \
   --aspect-ratio 1:1 \
   --image-model <recipe recommended model, e.g.: gpt-image-2>
@@ -255,24 +249,23 @@ playcraft tools generate-image \
 
 ```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";
+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";
+const MODEL = 'google/gemini-3.1-flash-image-preview';
+const REF = 'assets/images/storyboard/master_composite_option_<selectedMcOption>.png';
+const REF2 = 'assets/images/tiles/<artist_sample>.png'; // Artist approved sample (add if available)
+const OUT = 'assets/images/tiles';
 
-// STYLE: atom Skill recipe base prompt (from TA Skill Context in atom-plan.md)
+// STYLE: atom Skill recipe base prompt (from atom-tree.md `Per-Skill Reading Notes`)
 // 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 BASE_PROMPT = '<atom Skill recipe base prompt from atom-tree.md Per-Skill Reading Notes>';
 
 const ELEMENTS = [
-  { name: "element_01", variant: "<specific variant, e.g.: blue sapphire>" },
-  { name: "element_02", variant: "<specific variant, e.g.: red ruby>" },
+  { 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
 ];
 
@@ -290,21 +283,18 @@ for (const el of ELEMENTS) {
   }
 
   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,
-  );
+  // prompt = BASE_PROMPT with variant filled in + Artist 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}"` : "") +
+        (existsSync(REF2) ? ` --reference-image "${REF2}"` : '') +
         ` --image-model "${MODEL}"` +
         ` --timeout 120`,
-      { stdio: "inherit" },
+      { stdio: 'inherit' },
     );
     done++;
   } catch (e) {
@@ -413,7 +403,7 @@ playcraft image overlay \
 | 验证失败现象               | 根因                           | 回退工具                                                                   |
 | -------------------------- | ------------------------------ | -------------------------------------------------------------------------- |
 | 色幕残留少量（边缘毛刺）   | tolerance 偏低                 | `remove-background --tolerance 40`（+15 递增重试）                         |
-| 色幕残留明显（大面积色块） | 素材色与色幕撞色               | **spec-gap** → PM 修改 bgStrategy → 用正确色幕重新生成                     |
+| 色幕残留明显（大面积色块） | 素材色与色幕撞色               | **spec-gap** → Game Designer 修改 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`                       |
@@ -455,6 +445,13 @@ playcraft image overlay \
 
 #### bgStrategy = full-coverage（全屏背景）
 
+> **Asset layering contract (Ring 4 — mandatory, test11 B11):**
+>
+> - MC / storyboard panels are **reference only** — never crop an entire gameplay panel (board + HUD + fake buttons) into `assets/images/bg/*`.
+> - Background = **clean plate** (gradient/atmosphere only). Generate separately or extract a **pure background region** without UI chrome.
+> - Runtime z-order: `background < tiles < HUD < overlay`. Developer draws interactive HUD; background must not duplicate it.
+> - Gate: `npm run verify:bg-clean` must pass before Ring 4 gate.
+
 ```bash
 playcraft image info --input <bg_asset>.png --json
 # 验证：尺寸精确匹配 layout-spec 要求
@@ -652,7 +649,7 @@ node ta-workspace/scripts/validate-sprite-sheet.mjs
 
 ### 3D Pipeline
 
-For material/texture swap while preserving symbols or 3D flip animations, see `refs/ta-3d-flip-recipe.md`.
+For material/texture swap while preserving symbols or 3D flip animations, see `.claude/agents/refs/ta-3d-flip-recipe.md`.
 
 **Option A: AI 3D Model Generation**
 
@@ -725,48 +722,48 @@ 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`.
+> **Moved from `agents/technical-artist.md`** — Spec Quick-Check through Compliance Gate, reference-image matrix, DAG edits. **Atlas/WebP defaults:** see `.claude/agents/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`
+- Every `assetMapping` entry has clear size/format requirements → if gaps: set `block_reason=spec-gap` + routed `next_orchestrator_action` via `npm run state:set`
+- `logs/artist-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:
+Artist'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 Coverage Matrix** — note which states are covered vs which need expansion; Sheet grid metadata table at the top has `rows × cols + cell W×H + padding` for pixel-coordinate computation
+3. Check `artist-log.md` § **ASR Coverage Matrix** — note which states are covered vs which need expansion; Sheet grid metadata table at the top has `rows × cols + cell W×H + padding` for pixel-coordinate computation
 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
+6. Representative quality insufficient → ICP request to Artist for supplementary samples
 
-**若 ASR crop 后不可抠**（白边/色幕残留/元素截断/格内场景底）→ **`routeTo: designer`** 重生成 ASR 对应格；**不要** TA 自行用 AI 重画整张 ASR。
+**若 ASR crop 后不可抠**（白边/色幕残留/元素截断/格内场景底）→ **`routeTo: artist`** 重生成 ASR 对应格；**不要** TA 自行用 AI 重画整张 ASR。
 
 **ASR 提取方法（按优先级）**：
 
-> ⚠️ **严禁对 ASR 网格布局图使用纯 text prompt 的 segment！** 使用 `designer-log` 中的槽位坐标 + `crop`。
+> ⚠️ **严禁对 ASR 网格布局图使用纯 text prompt 的 segment！** 使用 `artist-log` 中的槽位坐标 + `crop`。
 
-**优先路径：直接读 `atom-plan.json` → `atoms[].asrSlot`（最高优先级）**
+**优先路径：直接读 `atom-tree.json` → `meta.selectedAtoms.asrSlot`（最高优先级）**
 
-Designer 在 Phase 1 完成 ASR 后会把每个 VisualAtom 的网格坐标写到 `atom-plan.json` → `atoms[i].asrSlot: { sheet, row, col }`（详见 [`docs/team/atom-plan-format.md` § `asrSlot`](../../../docs/team/atom-plan-format.md#asrslot-字段可选--visualatom-基线绑定)）。TA 直接用这个字段 + `designer-log` § Sheet grid metadata，省去手翻 Coverage Matrix 的步骤：
+Artist 在 Phase 1 完成 ASR 后会把每个 VisualAtom 的网格坐标写到 `atom-tree.json` → `atoms[i].asrSlot: { sheet, row, col }`（详见 [`docs/team/atom-tree-format.md` § `asrSlot`](../../../docs/team/atom-tree-format.md#asrslot-字段可选--visualatom-基线绑定)）。TA 直接用这个字段 + `artist-log` § Sheet grid metadata，省去手翻 Coverage Matrix 的步骤：
 
 ```bash
-# 1) 从 atom-plan.json 读取所有有 asrSlot 的 VisualAtom
-cat docs/atom-plan.json | jq -r '
-  .atoms[]
+# 1) 从 atom-tree.json 读取所有有 asrSlot 的 VisualAtom
+cat docs/atom-tree.json | jq -r '
+  .meta.selectedAtoms
   | select(.asrSlot != null)
   | "\(.atomId)\t\(.asrSlot.sheet)\t\(.asrSlot.row)\t\(.asrSlot.col)"
 '
 # 输出格式: <atomId>\t<sheet>\t<row>\t<col>
 
-# 2) 从 designer-log.md § ASR Coverage Matrix § Sheet grid metadata 读 cellW / cellH / padding
+# 2) 从 artist-log.md § ASR Coverage Matrix § Sheet grid metadata 读 cellW / cellH / padding
 #    (单独读一次，缓存到 ta-log 备查)
 
 # 3) 计算像素坐标并 crop（脚本化 — ta-workspace/scripts/asr-extract.mjs）
@@ -783,11 +780,11 @@ cat docs/atom-plan.json | jq -r '
 
 ```
 ASR 是已知网格布局？（ui_state_sheet / element_state_sheet / element_state_sheet_*_2，行列分明）
-├─ atom-plan.json 有 asrSlot 字段 → 方法 0（推荐）: 上面脚本化批量 crop
+├─ atom-tree.json 有 asrSlot 字段 → 方法 0（推荐）: 上面脚本化批量 crop
 │
 ├─ 是但 asrSlot 缺失 → 方法 1: crop 直切（手动查 Coverage Matrix R#C#）
 │        1. playcraft image info --input assets/images/reference/ui_state_sheet_<X>.png  → 获取尺寸
-│        2. 从 designer-log § ASR Coverage Matrix 读取 Sheet grid 元数据 + 目标行列 (R#C#)
+│        2. 从 artist-log § ASR Coverage Matrix 读取 Sheet grid 元数据 + 目标行列 (R#C#)
 │           pixel coords:  x = (C-1) × (cellW + padding) + padding
 │                          y = (R-1) × (cellH + padding) + padding
 │        3. playcraft image crop --input <asr_sheet> --x <x> --y <y> --width <cellW> --height <cellH> --output <out>
@@ -799,7 +796,7 @@ ASR 是已知网格布局？（ui_state_sheet / element_state_sheet / element_st
 └─ 仅 MC 有该类型 → 方法 3: decompose-layers 或 segment --text（最后手段，见 playcraft-masking）
 ```
 
-> **若 Designer 没有填 `asrSlot`** — 不需要重新 invoke Designer，TA 可以手动从 `designer-log § ASR Coverage Matrix § Coverage` 反查 R#C# 并继续。在 ICP 中提示 PM/Designer 下次预填可加速。
+> **若 Artist 没有填 `asrSlot`** — 不需要重新 invoke Artist，TA 可以手动从 `artist-log § ASR Coverage Matrix § Coverage` 反查 R#C# 并继续。在 ICP 中提示 Game Designer/Artist 下次预填可加速。
 
 **常见踩坑**：
 
@@ -812,7 +809,7 @@ ASR 是已知网格布局？（ui_state_sheet / element_state_sheet / element_st
 
 > **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.
+Read artist-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)
 
@@ -856,7 +853,7 @@ assetMapping 路径所在目录？
 └─ 其他路径              → 按素材用途判断：叠加在其他图层上 = true，独立全屏 = false
 ```
 
-**卡牌/棋子等矩形实体例外**：虽然路径在 `tiles/`，但白色牌面是资产本体的一部分，不需要透明。TA 根据 `design-brief` 的 Style Direction + `designer-log` 的样本判断。
+**卡牌/棋子等矩形实体例外**：虽然路径在 `tiles/`，但白色牌面是资产本体的一部分，不需要透明。TA 根据 `design-brief` 的 Style Direction + `artist-log` 的样本判断。
 
 #### 2. 从元素色彩推导 bgStrategy（色幕选型）
 
@@ -864,7 +861,7 @@ assetMapping 路径所在目录？
 
 - `layout-spec.md` 的 Color Palette（elementId → hex color）
 - `design-brief.md` 的 Style Direction（整体色温描述）
-- `designer-log.md` 的样本（实际视觉参考）
+- `artist-log.md` 的样本（实际视觉参考）
 
 **色幕选型矩阵**：
 
@@ -1016,14 +1013,14 @@ done
 
 ### Step 1: Skill Discovery
 
-- Part A: `playcraft skills list/match` → find pipeline Skills → write to atom-plan `## TA Skill Context`
+- Part A: `playcraft skills list/match` → find pipeline Skills → optionally append concise notes to `atom-tree.md` `Execution 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
+Ring 3 style lock → TA starts
    │
    ├─ 0a: Upstream Intake
    ├─ 0b: Extract (E) — decompose-layers or segment references from composites
@@ -1033,32 +1030,32 @@ Gate #2 → TA starts
    │
    ├─ T: Transparency-aware generation (Step 1 with correct chroma key per 0e table)
    │    │
-   │    ├─ C₁: generate-3d (if referenceSource="designer-sample")
+   │    ├─ C₁: generate-3d (if referenceSource="artist-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)
+   │    └─ (extraction insufficient → ICP → Artist supplementary)
    │
    ├─ Step 4: Process (remove-bg per chroma → dark-bg verify each asset)
    │
-   ├─ D: Audio post-processing (independent, waits for Designer Ph.2 audio)
+   ├─ D: Audio post-processing (independent, waits for Artist 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`           |
+| 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     | `.claude/agents/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
 
@@ -1081,14 +1078,14 @@ Triggered per Stage A output that needs animation. Output: sprite sheet with gri
 
 ### Stage C: 3D Pipeline
 
-> **Read `refs/ta-3d-flip-recipe.md`** for material reskin and 3D flip workflows.
+> **Read `.claude/agents/refs/ta-3d-flip-recipe.md`** for material reskin and 3D flip workflows.
 
-- C₁ (referenceSource="designer-sample"): starts immediately after extraction
+- C₁ (referenceSource="artist-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:
+Independent track, waits only for Artist Ph.2 audio delivery:
 
 - `playcraft audio compress/trim/loop/fade` as needed per layout-spec requirements
 - Record all processing in `ta-log.md`
@@ -1124,7 +1121,7 @@ Independent track, waits only for Designer Ph.2 audio delivery:
 | 背景图四角有白色/褪色   | 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.
+**After compliance**: Write `logs/ta-log.md` manifest → mark atoms `✅ done` → update state with `npm run state:set`.
 
 ### Reference image rules
 

package/project-template/.claude/agents/refs/technical-artist-legacy-fallback.md

@@ -0,0 +1,14 @@
+# Technical Artist Legacy Fallback
+
+Use this reference only when `dispatchPacket` is null and `sliceState` is empty.
+
+This preserves the older production asset path for existing projects. It is not part of slice-axis dispatch.
+
+Legacy behavior:
+
+- Read `npm run state:get -- --json` and follow the disclosed current action.
+- Complete upstream intake before production asset work.
+- Produce asset readiness, manifests, and compliance evidence requested by the legacy task.
+- Route missing design, Artist, or Developer inputs instead of inventing them.
+
+When `sliceState` exists, return to the main Technical Artist role contract.