@playcraft/cli 0.0.44 → 0.0.47

package/project-template/.claude/skills/brainstorming/scripts/stop-server.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Stop the brainstorm server and clean up
+# Usage: stop-server.sh <session_dir>
+#
+# Kills the server process. Only deletes session directory if it's
+# under /tmp (ephemeral). Persistent directories (.superpowers/) are
+# kept so mockups can be reviewed later.
+
+SESSION_DIR="$1"
+
+if [[ -z "$SESSION_DIR" ]]; then
+  echo '{"error": "Usage: stop-server.sh <session_dir>"}'
+  exit 1
+fi
+
+STATE_DIR="${SESSION_DIR}/state"
+PID_FILE="${STATE_DIR}/server.pid"
+
+if [[ -f "$PID_FILE" ]]; then
+  pid=$(cat "$PID_FILE")
+
+  # Try to stop gracefully, fallback to force if still alive
+  kill "$pid" 2>/dev/null || true
+
+  # Wait for graceful shutdown (up to ~2s)
+  for i in {1..20}; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      break
+    fi
+    sleep 0.1
+  done
+
+  # If still running, escalate to SIGKILL
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -9 "$pid" 2>/dev/null || true
+
+    # Give SIGKILL a moment to take effect
+    sleep 0.1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    echo '{"status": "failed", "error": "process still running"}'
+    exit 1
+  fi
+
+  rm -f "$PID_FILE" "${STATE_DIR}/server.log"
+
+  # Only delete ephemeral /tmp directories
+  if [[ "$SESSION_DIR" == /tmp/* ]]; then
+    rm -rf "$SESSION_DIR"
+  fi
+
+  echo '{"status": "stopped"}'
+else
+  echo '{"status": "not_running"}'
+fi

package/project-template/.claude/skills/brainstorming/scripts/wait-for-selection.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Wait for the user to confirm a selection in the browser companion.
+# Usage: wait-for-selection.sh <state_dir> [--timeout <seconds>]
+#
+# For single-select screens: resolves automatically when the user clicks an option.
+# For multi-select screens:  resolves when the user clicks the Confirm button.
+#
+# Outputs the confirm event as JSON to stdout on success (exit 0).
+# Exits 1 on timeout (default: 300s).
+# Exits 2 if the server has stopped.
+
+STATE_DIR="$1"
+TIMEOUT=300
+shift
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --timeout)
+      TIMEOUT="$2"
+      shift 2
+      ;;
+    *)
+      echo "{\"error\": \"Unknown argument: $1\"}" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$STATE_DIR" ]]; then
+  echo "{\"error\": \"Usage: wait-for-selection.sh <state_dir> [--timeout <seconds>]\"}" >&2
+  exit 1
+fi
+
+EVENTS_FILE="$STATE_DIR/events"
+SERVER_STOPPED="$STATE_DIR/server-stopped"
+
+DEADLINE=$(($(date +%s) + TIMEOUT))
+
+while true; do
+  # Check if server has stopped
+  if [[ -f "$SERVER_STOPPED" ]]; then
+    echo "{\"error\": \"server-stopped\"}" >&2
+    exit 2
+  fi
+
+  # Check for a confirm or reject event
+  if [[ -f "$EVENTS_FILE" ]] && [[ -s "$EVENTS_FILE" ]]; then
+    terminal_line=$(grep -E '"type":"(confirm|reject)"' "$EVENTS_FILE" | tail -1)
+    if [[ -n "$terminal_line" ]]; then
+      echo "$terminal_line"
+      exit 0
+    fi
+  fi
+
+  # Check timeout
+  if [[ $(date +%s) -ge $DEADLINE ]]; then
+    echo "{\"error\": \"timeout\"}" >&2
+    exit 1
+  fi
+
+  sleep 0.25
+done

package/project-template/.claude/skills/brainstorming/spec-document-reviewer-prompt.md

@@ -0,0 +1,49 @@
+# Spec Document Reviewer Prompt Template
+
+Use this template when dispatching a spec document reviewer subagent.
+
+**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
+
+**Dispatch after:** Spec document is written to docs/superpowers/specs/
+
+```
+Task tool (general-purpose):
+  description: "Review spec document"
+  prompt: |
+    You are a spec document reviewer. Verify this spec is complete and ready for planning.
+
+    **Spec to review:** [SPEC_FILE_PATH]
+
+    ## What to Check
+
+    | Category | What to Look For |
+    |----------|------------------|
+    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
+    | Consistency | Internal contradictions, conflicting requirements |
+    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+    | YAGNI | Unrequested features, over-engineering |
+
+    ## Calibration
+
+    **Only flag issues that would cause real problems during implementation planning.**
+    A missing section, a contradiction, or a requirement so ambiguous it could be
+    interpreted two different ways — those are issues. Minor wording improvements,
+    stylistic preferences, and "sections less detailed than others" are not.
+
+    Approve unless there are serious gaps that would lead to a flawed plan.
+
+    ## Output Format
+
+    ## Spec Review
+
+    **Status:** Approved | Issues Found
+
+    **Issues (if any):**
+    - [Section X]: [specific issue] - [why it matters for planning]
+
+    **Recommendations (advisory, do not block approval):**
+    - [suggestions for improvement]
+```
+
+**Reviewer returns:** Status, Issues (if any), Recommendations

package/project-template/.claude/skills/brainstorming/visual-companion.md

@@ -0,0 +1,309 @@
+# Visual Companion Guide
+
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+
+## When to Use
+
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
+
+**Use the browser** when the content itself is visual:
+
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
+
+**Use the terminal** when the content is text or tabular:
+
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
+
+A question _about_ a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start server with persistence (mockups saved to project)
+scripts/start-server.sh --project-dir /path/to/project
+
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
+
+**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code (macOS / Linux):**
+
+```bash
+# Default mode works — the script backgrounds the server itself
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Claude Code (Windows):**
+
+```bash
+# Windows auto-detects and uses foreground mode, which blocks the tool call.
+# Use run_in_background: true on the Bash tool call so the server survives
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+
+**Codex:**
+
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Gemini CLI:**
+
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect, then block on `wait-for-selection.sh`:**
+   - Tell the user the URL and briefly describe what's on screen (e.g., "Showing 3 layout options")
+   - Immediately run `scripts/wait-for-selection.sh "$STATE_DIR"` — this blocks until the user acts in the browser
+   - **Do not end your turn asking the user to return to the terminal.** The script unblocks automatically.
+
+   ```bash
+   scripts/wait-for-selection.sh "$STATE_DIR"
+   # returns JSON like:
+   # {"type":"confirm","choices":[{"choice":"a","text":"Single Column"}],"other":"","timestamp":...}
+   # {"type":"reject","timestamp":...}
+   ```
+
+3. **Parse the result and continue:**
+   - `type === "confirm"` — `choices` has selected options (may be empty if user only typed), `other` has free-text input (may be empty)
+   - `type === "reject"` — user declined; treat as "none of these, let's reconsider"
+   - Either way, **continue immediately** without asking the user to type anything in the terminal
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros">
+    <h4>Pros</h4>
+    <ul>
+      <li>Benefit</li>
+    </ul>
+  </div>
+  <div class="cons">
+    <h4>Cons</h4>
+    <ul>
+      <li>Drawback</li>
+    </ul>
+  </div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field" />
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+scripts/stop-server.sh $SESSION_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

package/project-template/.claude/skills/playcraft-ad-psychology/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-ad-psychology
-description: 可玩广告心理设计指南。涵盖四大心理钩子（好奇心缺口/FOMO/即时满足/进度错觉）、60-30-10 色彩法则、CTA 设计规范、各阶段情感设计目标与常见错误。按游戏类型配色方案和音频情绪弧参数见 refs/designer-color-audio-recipes.md。
+description: 可玩广告心理设计指南。涵盖四大心理钩子（好奇心缺口/FOMO/即时满足/进度错觉）、60-30-10 色彩法则、CTA 设计规范、各阶段情感设计目标与常见错误。按游戏类型配色方案和音频情绪弧参数见 refs/artist-color-audio-recipes.md。
 triggers: 广告心理,ad psychology,钩子,hook设计,FOMO,近胜,near-win,CTA设计,色彩法则,60-30-10,颜色策略,配色方案,情感弧,emotional arc,安装率,CTR,转化率,EndCard设计,进度条设计,游戏广告设计
 ---
 
@@ -141,7 +141,7 @@ CTA 按钮与其背景的对比度必须 **≥ 4.5:1**（WCAG AA 标准）。
 - 浅黄 #FFFF99 / 白色背景 → 对比度 ~1.2:1 ❌（不合规）
 ```
 
-快速验证工具：告诉 Designer 用 `playcraft tools research --query "color contrast checker [color1] vs [color2]"` 快速查询。
+快速验证工具：告诉 Artist 用 `playcraft tools research --query "color contrast checker [color1] vs [color2]"` 快速查询。
 
 ### 文案优先级
 
@@ -179,4 +179,4 @@ CTA 按钮与其背景的对比度必须 **≥ 4.5:1**（WCAG AA 标准）。
 
 按游戏类型的配色方案（休闲消除、策略战争、益智解谜、RPG 奇幻，含 hex 值与情感定位）和完整音频情绪弧设计参数（BGM 各阶段 BPM、垂直重编排、SFX 时长标准、音频-视觉对齐检查清单）：
 
-详见 `refs/designer-color-audio-recipes.md`。
+详见 `refs/artist-color-audio-recipes.md`。

package/project-template/.claude/skills/playcraft-art-style-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-art-style-guide
-description: 可玩广告美术风格选择与应用指南。涵盖 9 种主流风格的视觉特征、选型决策树（按游戏类型/受众/品牌调性）、风格对生产流水线的影响、以及各风格的 prompt 核心策略。Designer 在 Phase 1 确定美术方向前必读。
+description: 可玩广告美术风格选择与应用指南。涵盖 9 种主流风格的视觉特征、选型决策树（按游戏类型/受众/品牌调性）、风格对生产流水线的影响、以及各风格的 prompt 核心策略。Artist 在 Phase 1 确定美术方向前必读。
 triggers: 美术风格,art style,像素风,pixel art,写实,realistic,卡通,cartoon,扁平,flat,科技风,tech,科幻,sci-fi,赛博朋克,cyberpunk,奇幻,fantasy,中国风,chinese,水彩,watercolor,手绘,Q版,chibi,风格选择,style direction,视觉风格
 ---
 
@@ -15,7 +15,7 @@ triggers: 美术风格,art style,像素风,pixel art,写实,realistic,卡通,car
 - **文件体积**：像素风天然小，写实风天然大——直接影响 5MB 预算分配
 - **TA 管线**：像素风需要整数倍缩放 + 限色板；写实风需要高分辨率 + 精细抠图
 
-**风格决策时机**：PM 在 `design-brief.md` 的 StyleDirection 中定义方向，Designer 在 Phase 1 具体化并生成样本验证。
+**风格决策时机**：Game Designer 在 `design-brief.md` 的 StyleDirection 中定义方向，Artist 在 Phase 1 具体化并生成样本验证。
 
 ---
 
@@ -120,4 +120,4 @@ triggers: 美术风格,art style,像素风,pixel art,写实,realistic,卡通,car
 
 每种风格的完整 prompt 示例、模型推荐、TA 管线详细配置、常见错误与修正：
 
-> **Read `refs/designer-art-style-catalog.md`**
+> **Read `refs/artist-art-style-catalog.md`**

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

@@ -1,6 +1,6 @@
 ---
 name: playcraft-asset-state-sheet
-description: PlayCraft 资产状态参考精灵图板（ASR / Asset State Reference Sheet）生成指南。Designer 在 Gate #2a 后输出两张 4K 参考精灵图：UI 组件状态板 + 玩法元素状态板，供 TA crop 量产。
+description: PlayCraft 资产状态参考精灵图板（ASR / Asset State Reference Sheet）生成指南。Artist 在 ring 3 Ring Gate（MC 选定）后输出两张 4K 参考精灵图：UI 组件状态板 + 玩法元素状态板，供 TA crop 量产。
 triggers: ASR,asset state reference,state reference sheet,UI state sheet,element state sheet,组件状态图,状态精灵图,精灵图板,参考精灵图,authoring sprite sheet,design handoff sheet,TA参考图,状态参考板,playcraft-asset-state-sheet
 ---
 
@@ -11,7 +11,7 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 
 ## 0. 前置条件（硬门禁）
 
-- **仅在 Gate #2a 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
+- **仅在 ring 3 Ring Gate 通过、`selectedMcOption` 已写入 `project-state.md` 之后** 才能生成 ASR
 - **禁止**为未选中的 MC 方案生成 ASR
 - 两张板均使用已确认 MC 作 `--reference-image`，且 `--image-model` 与 MC 一致
 - **生成 ASR 前必读** `playcraft-image-generation` Skill §3（色幕矩阵）— 格内元素须可抠
@@ -19,7 +19,7 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 ## 0.1 Sheet 底色 + 格内抠图（必读）
 
 > **整图 opaque 是预期行为** — ASR PNG 本身**不需要**也**不应**交付透明 PNG。TA 负责 `crop → remove-background → WebP atlas`。  
-> Designer 的职责是：让 **每个格内的单元素** 在 crop 后能被 TA 可靠抠图。
+> Artist 的职责是：让 **每个格内的单元素** 在 crop 后能被 TA 可靠抠图。
 
 | 层级                  | 规则                                                                              |
 | --------------------- | --------------------------------------------------------------------------------- |
@@ -28,7 +28,7 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 | **Cell 内容**         | **单元素 isolated、居中**；禁止格内地面/阴影/白盒/场景/context                    |
 | **金/橙/黄/绿元素格** | 该格背景用 **蓝幕 `#0000FF`**（见 `playcraft-image-generation` 色幕矩阵）         |
 | **蓝/紫元素格**       | 该格背景用 **绿幕 `#00FF00`**                                                     |
-| **Designer 禁止**     | 对 ASR 做 `remove-background` 量产；那是 TA 在 `production` 的工作                |
+| **Artist 禁止**       | 对 ASR 做 `remove-background` 量产；那是 TA 在 `production` 的工作                |
 
 **错误示例（必须重生成）**：格内白底方块、渐变底、整屏 HUD 截屏、两元素叠在同一格、元素带地面阴影。
 
@@ -41,7 +41,7 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 
 `[X]` = `selectedMcOption`（A/B/C）。
 
-**多板扩展**（`unique element types > 12` 或 Layer1 槽位 > 12）：允许追加 `element_state_sheet_[X]_2.png`；Coverage Matrix 的 `sheet` 列填 `element_2`。详见 `docs/team/atom-plan-format.md` § `asrSlot`.
+**多板扩展**（`unique element types > 12` 或 Layer1 槽位 > 12）：允许追加 `element_state_sheet_[X]_2.png`；Coverage Matrix 的 `sheet` 列填 `element_2`。详见 `docs/team/atom-tree-format.md` § `asrSlot`.
 
 ### UI State Reference Sheet — 放什么
 
@@ -54,7 +54,7 @@ triggers: ASR,asset state reference,state reference sheet,UI state sheet,element
 ### Element State Reference Sheet — 放什么
 
 - 棋子、牌面、角色、道具、匹配特效关键帧等（MC 概念面板里出现的玩法元素）
-- 每个元素 **type** 至少 **1 个代表态** 占物理槽位；同 type 的 color 变体可标 `CoverageLayer: ta-extends`（见 `designer-deliverable-spec.md`）
+- 每个元素 **type** 至少 **1 个代表态** 占物理槽位；同 type 的 color 变体可标 `CoverageLayer: ta-extends`（见 `artist-deliverable-spec.md`）
 - 每 type **2–3 个代表状态** 优先（完整全集由 TA 在 `production` 扩展），例如：
   - `tile_gold`: idle | selected | matched
   - `panda_char`: idle | happy | win
@@ -133,7 +133,17 @@ Row 1 — Core tiles/items:
 Art style: [SAME as Master Composite].
 ```
 
-**Prompt 必须包含**：`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素、`isolated`、`NO white box`、`NO scene`.
+**元素板额外约束（test11 B10/B12）**：
+
+```
+UNIFORM SILHOUETTE: All gameplay elements of the same category (e.g. all match-3 gems) MUST share the
+identical outer silhouette and occupy the same visual scale in every cell. NO mixing hex/diamond/square/drop shapes.
+
+REGULAR GRID: Equal cell width and height, equal spacing — TA re-measures from pixels after generation;
+do NOT trust API-reported grid metadata without calibration.
+```
+
+**Prompt 必须包含**：`sprite sheet` 或 `state reference sheet`、`STRICT LAYOUT`、`non-overlapping cells`、具体 gap 像素、`isolated`、`NO white box`、`NO scene`、**`UNIFORM SILHOUETTE`**（元素板）。
 
 ## 4. 生成命令
 
@@ -168,28 +178,28 @@ playcraft tools generate-image \
 
 ## 5. 核查清单
 
-| #   | 核查项       | 标准                                                                           |
-| --- | ------------ | ------------------------------------------------------------------------------ |
-| 1   | 时机         | `selectedMcOption` 已设置                                                      |
-| 2   | 数量         | UI 板 + 元素板各至少一张                                                       |
-| 3   | 视觉         | 两板均无重叠；有重叠则重生成                                                   |
-| 4   | 语义         | UI 板无玩法棋子；元素板无整屏 HUD 截屏                                         |
-| 5   | 格内可抠     | 目视：无白盒/场景底/格内渐变；金橙元素格用蓝幕                                 |
-| 6   | 整图 opaque  | 预期行为 — 不要求透明 PNG                                                      |
-| 7   | 清单         | `designer-log` § **ASR Coverage Matrix** 100% contract 行 + `CoverageLayer` 列 |
-| 8   | 网格元数据   | Sheet grid 表：rows × cols + cell W×H + padding（非 `{{placeholder}}`）        |
-| 9   | type 代表态  | 每种 element type 至少在 on-asr 或 mc-crop 有一处                              |
-| 10  | asrSlot 镜像 | on-asr 行已写入 `atom-plan.json` → `atoms[].asrSlot`                           |
+| #   | 核查项       | 标准                                                                         |
+| --- | ------------ | ---------------------------------------------------------------------------- |
+| 1   | 时机         | `selectedMcOption` 已设置                                                    |
+| 2   | 数量         | UI 板 + 元素板各至少一张                                                     |
+| 3   | 视觉         | 两板均无重叠；有重叠则重生成                                                 |
+| 4   | 语义         | UI 板无玩法棋子；元素板无整屏 HUD 截屏                                       |
+| 5   | 格内可抠     | 目视：无白盒/场景底/格内渐变；金橙元素格用蓝幕                               |
+| 6   | 整图 opaque  | 预期行为 — 不要求透明 PNG                                                    |
+| 7   | 清单         | `artist-log` § **ASR Coverage Matrix** 100% contract 行 + `CoverageLayer` 列 |
+| 8   | 网格元数据   | Sheet grid 表：rows × cols + cell W×H + padding（非 `{{placeholder}}`）      |
+| 9   | type 代表态  | 每种 element type 至少在 on-asr 或 mc-crop 有一处                            |
+| 10  | asrSlot 镜像 | on-asr 行已写入 `atom-tree.json` → `meta.selectedAtoms.asrSlot`              |
 
 ## 6. 与 TA 的协作协议
 
-Designer：风格与 MC 一致；在 `designer-log.md` § **ASR Coverage Matrix** 标注 **CoverageLayer** 与 **TA 需扩展的状态**。
+Artist：风格与 MC 一致；在 `artist-log.md` § **ASR Coverage Matrix** 标注 **CoverageLayer** 与 **TA 需扩展的状态**。
 
 TA 提取（详见 `playcraft-masking`）：
 
-| 来源图               | 推荐方式                   | 说明                                                                                                                                             |
-| -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **ASR**（规则网格）  | `playcraft image crop`     | 槽位坐标来自 `designer-log` § **ASR Coverage Matrix**（含 Sheet grid 元数据）或 `atom-plan.json` → `asrSlot`；**禁止**对 ASR 用纯 text `segment` |
-| **Master Composite** | `decompose-layers` 或 crop | `mc-crop` 层从此补提取                                                                                                                           |
+| 来源图               | 推荐方式                   | 说明                                                                                                                                           |
+| -------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ASR**（规则网格）  | `playcraft image crop`     | 槽位坐标来自 `artist-log` § **ASR Coverage Matrix**（含 Sheet grid 元数据）或 `atom-tree.json` → `asrSlot`；**禁止**对 ASR 用纯 text `segment` |
+| **Master Composite** | `decompose-layers` 或 crop | `mc-crop` 层从此补提取                                                                                                                         |
 
-**若 TA crop 后仍不可抠**（白边/色幕残留/元素被截断）→ `routeTo: designer` 重生成 ASR 格，**非** TA 自行重画 ASR。
+**若 TA crop 后仍不可抠**（白边/色幕残留/元素被截断）→ `routeTo: artist` 重生成 ASR 格，**非** TA 自行重画 ASR。