@playcraft/cli 0.0.39 → 0.0.41

package/project-template/.claude/agents/refs/reviewer-six-dimension-eval.md

@@ -0,0 +1,286 @@
+# Reviewer: Six-Dimension Evaluation & Scoring
+
+> **Read before scoring and for the full audit loop.** Contains: Dev walkthrough; **Steps 0–0b + Phases 1–5** (DAG, layout, TA log, psychology, technical checks, six dimensions, DAG revisions); **scoring + veto**; **Rework mechanism** (rounds, severity, routing).
+
+**Developer alignment**: Style Consistency + Intent Fidelity → **Dev UI match**; Experience Flow + Difficulty Balance → **Dev gameplay match**; technical checks + veto items → runtime in Dev. **Dev walkthrough pass ≠ optional.** Build is not required for review pass.
+
+---
+
+## Dev walkthrough (before six-dimension scoring)
+
+Perform in browser at **devUrl** from `project-state.md` (start with `npm run dev` if down).
+
+### UI match (maps to Style Consistency + Intent Fidelity)
+
+| Check                       | Compare against                                                 |
+| --------------------------- | --------------------------------------------------------------- |
+| Layout / zones / hierarchy  | `layout-spec.md`                                                |
+| Color, mood, MC fidelity    | `style-exploration.md`, Gate #2 MC (concept panel + storyboard) |
+| Per-stage visual intent     | Storyboard panels 2–5 in style-exploration                      |
+| Text-as-image, sprites, VFX | Live Dev vs approved design                                     |
+
+### Gameplay match (maps to Experience Flow + Difficulty Balance)
+
+| Check                                 | Compare against                    |
+| ------------------------------------- | ---------------------------------- |
+| Hook → Tutorial → Gameplay → End Card | `design-brief.md` experience flow  |
+| First level guaranteed success        | PGS / atom-plan (**veto** if fail) |
+| Near-Win, difficulty, CTA timing      | design-brief + Dev playthrough     |
+
+Record pass/fail summary in `project-state.reviewerDevNotes` and `reviewerDevCheck`.
+
+---
+
+## Phase 4: Six-Dimension Experience Evaluation
+
+Simulate the player walking through Hook → Tutorial → Gameplay → End Card:
+
+### 1. Experience Flow (experienceFlow)
+
+| Checkpoint          | Criteria                                                                                                                                              |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hook (0-3s)         | Immediate visual/interactive hook? Attention captured in 3s? Does it match the Hook frame in `style-exploration.md` storyboard?                       |
+| Tutorial (3-10s)    | Clear? Player understands core mechanic in 2-3 steps? Does it align with the Tutorial storyboard frame intent (low-pressure, guide elements visible)? |
+| Gameplay (10-25s)   | Smooth loop? Good pacing? No dead ends? Is Near-Win designed as specified in design-brief — with a visible solution?                                  |
+| End Card (25-30s)   | Natural CTA transition? Button visible and clickable? Does it create sequel feeling (not closure) as designed in EndCard storyboard frame?            |
+| Total duration      | Fits within 15-30 seconds?                                                                                                                            |
+| Storyboard fidelity | Does the final playable match the emotional arc and visual composition described in the Experience Flow Design section of `style-exploration.md`?     |
+
+### 2. Creative Appeal (creativeAppeal)
+
+| Checkpoint           | Criteria                                          |
+| -------------------- | ------------------------------------------------- |
+| Hook strength        | Does opening visual stop the user from scrolling? |
+| Freshness            | Differentiated or template-feeling?               |
+| Emotional connection | Curiosity/excitement/satisfaction triggered?      |
+| Memorability         | What sticks after playing?                        |
+
+### 3. Style Consistency (styleConsistency)
+
+| Checkpoint          | Criteria                                                                                         |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| Concept fidelity    | Do final assets match the approved **concept panel** (Panel 1) from style-exploration.md?        |
+| Storyboard fidelity | Do Hook/Tutorial/Gameplay/EndCard stages visually match storyboard panels 2–5?                   |
+| Visual internal     | Background, characters, UI belong to same style? Colors unified?                                 |
+| Audio internal      | BGM and SFX harmonious?                                                                          |
+| Cross-media         | Visual style and audio atmosphere match? Does audio-emotion rhythm match Experience Flow Design? |
+| Gameplay-style      | Gameplay pacing matches visual/audio rhythm?                                                     |
+
+### 4. Intent Fidelity (intentFidelity)
+
+| Checkpoint      | Criteria                                            |
+| --------------- | --------------------------------------------------- |
+| Gameplay type   | Actual gameplay matches design-brief selection?     |
+| Visual style    | Matches intentTags?                                 |
+| Experience flow | Follows design-brief experienceFlow?                |
+| Level config    | Matches levelConfig (number of levels, difficulty)? |
+| Atom coverage   | Every atom in plan is implemented?                  |
+
+### 5. Difficulty Balance (difficultyBalance)
+
+| Checkpoint          | Criteria                                                     |
+| ------------------- | ------------------------------------------------------------ |
+| First level success | **GUARANTEED?** (veto item — automatic fail if not)          |
+| Difficulty curve    | Progressive? No sudden spikes?                               |
+| Frustration control | Failure gives positive feedback ("try again" not "give up")? |
+| Completability      | Can finish within time limit?                                |
+
+### 6. Intent Transmission (intentTransmission)
+
+**Check `docs/intent-clarifications.md`:**
+
+- Any unresolved Open Questions? (deduct 1 point per unresolved question)
+- Any Agent received >3 questions? (intent transmission fault)
+
+**Check `logs/ta-log.md`:**
+
+- Style Interpretation table exists?
+- Any low-confidence items without corresponding clarifications?
+- Micro-Batch Validation scores all >= 3?
+
+**Check `logs/developer-log.md`:**
+
+- Experience Flow → Code Mapping exists?
+- All scenes have storyboard frame references?
+- Code visual implementation matches storyboard intent?
+
+**Scoring calibration (1–5):**
+
+- 5: Zero open clarifications, TA self-check all pass, Developer mapping complete
+- 4: 1–2 resolved clarifications, no quality impact
+- 3: Unresolved clarifications exist, or TA has low-confidence items
+- 2: Multiple unresolved clarifications, or Developer missing visual mapping
+- 1: Severe intent transmission failure, downstream agents made major wrong assumptions
+
+---
+
+## Scoring
+
+Each dimension: 1–5 points. **Maximum total: 30** (6 × 5).
+
+| Score | Meaning                                                | Calibration Example                             |
+| ----- | ------------------------------------------------------ | ----------------------------------------------- |
+| 5     | Excellent — exceeds expectations, ready to ship        | Polished feel, strong hook, perfect consistency |
+| 4     | Good — meets standard, minor tweaks then ship          | Solid execution, one small inconsistency        |
+| 3     | Acceptable — basically works, needs improvement        | Functional but generic                          |
+| 2     | Below standard — obvious problems, partial redo needed | Major style clash or broken flow                |
+| 1     | Seriously deficient — directional error, full redo     | Wrong gameplay, broken entry, no CTA            |
+
+**Total ≥ 24**: Pass — proceed to Gate #3 (orchestrator)
+**Total 18–23**: Conditional pass — fix issues then re-review
+**Total < 18**: Fail — route back to responsible agent(s)
+
+**VETO ITEMS (automatic fail regardless of score):**
+
+- First level does NOT guarantee success
+- Zero CTA implementation
+- External network requests present
+- Entry file (index.html) missing
+
+---
+
+## Full review process (L2)
+
+> Invoked from `agents/reviewer.md` — execute in order before final verdict.
+
+### Step 0: Dev preview (mandatory)
+
+1. Read `docs/project-state.md` → **Dev Preview**: `devUrl`, `devStatus`.
+2. If `devStatus` ≠ `ready` → **fail fast** (route Developer; do not score experience).
+3. If Dev server not reachable → run `npm run dev`, refresh `devUrl` in project-state.
+4. Open **devUrl** in browser; complete **UI match** + **gameplay match** (checklists in § Dev walkthrough above).
+5. Record summary in `project-state.md`: `reviewerDevCheck` (`passed` / `failed`), `reviewerDevNotes`.
+
+**Do not** require `playcraft build`. **Do not** ask the user to run terminal commands.
+
+### Step 0b: Validator Skill Discovery
+
+```bash
+playcraft skills list --category validator --json
+playcraft skills match --intent "validator,balance,quality" --json
+```
+
+For matched Validator Skills: read the SKILL.md, apply its checklist, record results in `review-report.md` per its format.
+
+### Phase 1: DAG Completeness Audit
+
+For each atom in `docs/atom-plan.md`:
+
+- `done` → verify `actualOutput` file exists on disk
+- `skipped` → verify reason is documented
+- `blocked` → verify blocker is documented
+
+### Phase 2: Layout Spec Compliance
+
+**Layout Spec is the shared contract. Verify ALL THREE production agents comply.**
+
+| Check                                                    | Route Issue To                        |
+| -------------------------------------------------------- | ------------------------------------- |
+| Asset sizes match `assetSpec`                            | TA (completions) / Designer (samples) |
+| Filenames match `assetMapping`                           | TA (completions) / Designer (samples) |
+| All assetMapping entries have files                      | **TA** (compliance gate)              |
+| Sprite sheet JSON paired with every atlas / sheet        | **TA**                                |
+| Element IDs in code match `colorPalette.tileColors[].id` | Developer                             |
+| Zone coordinates in scene match `zones[].rect`           | Developer                             |
+| Every asset is used; every code reference has a file     | TA + Developer                        |
+
+### Phase 2.5: TA Compliance Report Audit
+
+Read `logs/ta-log.md` and verify: log exists and complete, Asset Coverage table fully filled and all PASS, Spec Compliance Summary passes, Compliance Verdict is PASS. (Note: file size is NOT a TA compliance concern — size optimization happens at build time.)
+
+### Phase 2.6: Ad Psychology Audit
+
+> **Invoke the `playcraft-ad-psychology` skill** and use its four psychological hooks, 60-30-10 color rule, and CTA specs as evaluation criteria for Creative Appeal and Experience Flow dimensions.
+
+Key checks against ad-psychology principles:
+
+- Hook frame uses highest contrast + dynamic composition (Curiosity Gap)?
+- Tutorial uses simplified layout + warm tone + large gesture icons (Instant Gratification)?
+- Gameplay shows Near-Win state, NOT victory state (Progress Illusion)?
+- EndCard shows unresolved reward + prominent CTA, NOT satisfaction (FOMO)?
+- CTA button color is the ONLY accent color in the scene (60-30-10 rule)?
+- CTA touch target ≥ 48×48 px, contrast ratio ≥ 4.5:1?
+
+### Phase 3: Automated Technical Checks
+
+> **Invoke the `playcraft-build-optimizer` skill** for the compliance verification checklist (file size limits, external request detection, CTA API implementation, audio autoplay rules) and platform-specific requirements.
+
+```bash
+# Total project size
+du -sh .
+
+# Asset samples (adjust globs to project)
+playcraft image info assets/images/bg/*.webp
+playcraft image info assets/images/tiles/*.webp
+playcraft audio info --input assets/audio/bgm/*.mp3
+playcraft audio info --input assets/audio/sfx/*.mp3
+
+# Entry file exists
+ls game/index.html
+
+# Check for external requests
+grep -r "http://" game/ || echo "No http:// found"
+grep -r "https://" game/ || echo "No https:// found"
+grep -r "fetch(" game/ || echo "No fetch() found"
+
+# CTA implementation
+grep -r "onCTAClick\|mraid\|FbPlayableAd\|ExitApi" game/
+```
+
+### Phase 4: Six-Dimension Experience Evaluation
+
+> **Before starting Phase 4, read from the top of this document** (all six dimensions including Intent Transmission + scoring thresholds).
+
+Six dimensions: **Experience Flow** / **Creative Appeal** / **Style Consistency** / **Intent Fidelity** / **Difficulty Balance** / **Intent Transmission** — each scored 1–5. **Total ≥ 24/30 = pass**; 18–23 conditional; &lt; 18 fail.
+
+**Veto items (automatic fail)**: first level not guaranteed success / no CTA / external requests / missing index.html.
+
+### Phase 5: DAG Revision Audit
+
+For each entry in DAG Revisions: is the modification reasonable? properly documented? did it deviate from original intent?
+
+---
+
+## Rework mechanism
+
+### Rework rules
+
+| Rule               | Detail                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Failure budget** | `rework_round` in `{0, 1}` → allow rework (+1 on fail). `rework_round == 2` on fail → **forced Gate #3** (3rd review failure; user decides) |
+| **Parallel fixes** | If multiple agents have issues, route to all in parallel                                                                                    |
+| **Incremental**    | Fix only the problem parts, not redo everything                                                                                             |
+| **No re-gating**   | Rework goes directly back to Reviewer, no Gate #1/#2 re-approval                                                                            |
+
+### Severity levels
+
+| Severity   | Definition                            | Handling                     |
+| ---------- | ------------------------------------- | ---------------------------- |
+| `critical` | Non-functional / white screen / crash | Must fix, cannot skip        |
+| `major`    | Noticeable experience defect but runs | Rework fix, max 1 round      |
+| `minor`    | Aesthetic suggestion / tweak          | Log but do not block Gate #3 |
+
+### Feedback routing
+
+| Issue Type                                     | Route To             |
+| ---------------------------------------------- | -------------------- |
+| Direction / experience flow issues             | PM                   |
+| Creative sample quality                        | Designer             |
+| Asset completeness / compliance / sprite sheet | **Technical Artist** |
+| Gameplay logic bug / parameter imbalance       | Developer            |
+| Dev runtime / integration technical issue      | Developer            |
+
+### Rework flow
+
+```
+Issues found → review-report.md with severity + target + specific fix instructions
+    │
+    ├──→ Routed agents fix in parallel (incremental)
+    │
+    └──→ Developer Ph.2 fixes + Dev re-check
+              │
+              └──→ Reviewer re-checks
+                        │
+                   ┌────┴────┐
+                   Pass    Fail → round 2 or forced Gate #3
+```

package/project-template/.claude/agents/refs/ta-3d-flip-recipe.md

@@ -0,0 +1,85 @@
+# TA 3D Flip & Material Reskin Recipe
+
+> Read by Technical Artist when dealing with:
+> - Material/texture swap while preserving symbols (mahjong white→ice/metal/wood)
+> - Card/tile flip animations (16-frame sprite sheets)
+> - Any task requiring the 3D white model pipeline
+
+---
+
+## Option C: Material Reskin — Preserve Symbols, Swap Base Texture
+
+**THE most common TA task for sprite sheet style variants.**
+- Use when: mahjong white→ice, white→metal, white→wood
+- Key insight: symbols are face textures, base material is a separate layer
+
+```bash
+# Step 1: Split the original sprite sheet into individual tiles
+playcraft image sprite-split \
+  --input assets/images/tiles/original_sheet.png \
+  --output-dir assets/images/tiles/split_frames \
+  --auto-detect --hint "mahjong tiles, uniform grid"
+# → 44 individual PNGs + split-meta.json
+
+# Step 2: Generate ONE new base material texture (reused for all tiles)
+playcraft tools generate-image \
+  --prompt "ice crystal frosted glass texture, blue-white cold, seamless, top-down" \
+  --output assets/textures/ice_base.png
+
+# Step 3: Create white model with new base material
+playcraft 3d apply-texture \
+  --model plane \
+  --texture assets/textures/ice_base.png \
+  --output assets/models/ice_tile_base.glb
+
+# Step 4: For EACH tile — render white model + original symbol as face texture
+# (Uses the software rasterizer from playcraft-3d-flip-sprite SKILL)
+# face texture = the split frame from Step 1 (preserves symbol exactly)
+node render.mjs assets/models/ice_tile_base.glb \
+  assets/images/tiles/reskinned/tile_001.png \
+  assets/images/tiles/split_frames/frame_r0_c0.png
+# Repeat for all 44 tiles — write a ta-workspace script for this step
+
+# Step 5: Reassemble into sprite sheet (same grid as original)
+playcraft image sprite-sheet \
+  --inputs assets/images/tiles/reskinned/tile_001.png,tile_002.png,... \
+  --output assets/images/tiles/ice_sheet \
+  --columns <original_columns> \
+  --cell-width <W> --cell-height <H>
+```
+
+**Style switching efficiency**:
+- To switch to METAL: only redo Step 2 (new texture) + Step 3-5
+- To switch to WOOD: same — just one new base texture
+- Symbols never change, never touch AI regeneration
+
+---
+
+## Option D: Batch 3D Flip Sprite Sheet (e.g., 34 mahjong flip animations)
+
+Read `playcraft-3d-flip-sprite` SKILL for the full rendering pipeline.
+(Software rasterizer: no Puppeteer/headless-gl needed)
+
+**Per-tile workflow**: white model GLB + face texture → 16-frame flip sprite sheet
+
+```
+1. Flatten base GLB (remove surface geometry of original design)
+2. Generate face texture per tile variant
+3. Render 16-frame flip animation with soft rasterizer
+4. Output sprite sheet PNG
+```
+
+See `.claude/skills/playcraft-3d-flip-sprite/` for complete instructions.
+
+---
+
+## Mahjong Tile Example: All 4 Workflows Compared
+
+| Scenario | Method | When |
+|---------|--------|------|
+| One concept mockup → all 34 tiles | Sprite Generation (AI batch with reference-image) | Starting from scratch |
+| Existing white tiles → Ice style (symbols preserved) | 3D path (Option C above) | Material/texture swap |
+| Existing white tiles → Metal style | 3D path (swap ice→metal texture, rerun Step 3-5) | Style variant |
+| Existing tiles → Pixel art style (symbols redrawn) | Sprite Remix (per-frame AI) | Full creative restyle |
+| Existing tiles → Darker mood | Image Processing (`tint` + `overlay`) | Color/mood shift |
+| Flip animation (16 frames per tile) | Option D (3D flip sprite, playcraft-3d-flip-sprite SKILL) | Animation |

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

@@ -0,0 +1,46 @@
+# TA Atlas Deliverable Standard
+
+> **When**: `stage: production` branch in `technical-artist.md` § Runtime.  
+> **Contract source**: `layout-spec.md` atlas groups + `assetMapping` (Gate #1 locked).
+
+## Defaults
+
+| Asset type          | Delivery format                                                                              |
+| ------------------- | -------------------------------------------------------------------------------------------- |
+| Runtime images      | **WebP** (`.webp`) — not PNG for final runtime assets                                        |
+| Multi-element class | **One atlas per logical group** → `.webp` + `.json` sidecar (`playcraft image sprite-sheet`) |
+| Single large asset  | One `.webp` (full-screen bg, etc.)                                                           |
+| Audio (BGM/SFX)     | **MP3** only after TA post-process                                                           |
+| Digit strip         | Single horizontal **WebP** at `layout-spec` path (not merged into UI atlas)                  |
+
+## Atlas grouping rules
+
+1. Read PM'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).
+
+## Production pipeline
+
+1. Spec Quick-Check → Style Interpretation → micro-batch (≥3) per group.
+2. Batch generate frames → `playcraft image sprite-sheet` → convert to **WebP** if needed:
+   ```bash
+   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`.
+
+## Compliance (TA)
+
+| Check          | Pass criteria                                                                 |
+| -------------- | ----------------------------------------------------------------------------- |
+| Atlas coverage | Every runtime element resolves to atlas+frame or single webp path             |
+| Sidecar        | `.json` exists beside each multi-element atlas                                |
+| Format         | WebP for images; MP3 for audio (unless layout-spec explicit exception)        |
+| ta-log         | One manifest row per atlas group: path, frames, cols/frameW/frameH/frameCount |
+
+## Developer handoff
+
+Developer loads `atlasPath` once, uses `frameId` from layout-spec / JSON — not per-element file paths for grouped assets.
+
+See also: `ta-pipeline-cookbook.md`, `playcraft-sprite-generation` SKILL (final delivery extension = `.webp`).

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

@@ -0,0 +1,120 @@
+> 本文件是 batch/pipeline 的实用配方集。选型决策树和基础语法见 `playcraft-batch-pipeline` skill。
+
+# Batch / Pipeline 实用配方集
+
+---
+
+## Batch 配方
+
+### 批量 resize + 转换格式
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw_tiles/ \
+  --output-dir assets/images/tiles/ \
+  --glob "*.png" \
+  --steps "resize --width 128 --height 128, trim" \
+  --parallel 8
+```
+
+### 批量去背（绿幕）
+
+```bash
+playcraft image batch \
+  --input-dir assets/images/raw_sprites/ \
+  --output-dir assets/images/sprites/ \
+  --steps "remove-background --method floodfill --tolerance 40" \
+  --parallel 4
+```
+
+### 批量统一色调（制作主题变体）
+
+```bash
+# 生成蓝色主题版本
+playcraft image batch \
+  --input-dir assets/images/tiles/ \
+  --output-dir assets/images/tiles_blue_theme/ \
+  --steps "tint --color #4466BB" \
+  --parallel 6
+```
+
+### 断点续传（大批量任务中断后恢复）
+
+```bash
+# 第一次运行中断了
+playcraft image batch \
+  --input-dir assets/images/raw/ \
+  --output-dir assets/images/processed/ \
+  --steps "resize --width 256 --height 256, grayscale" \
+  --parallel 4 \
+  --skip-existing    # 再次运行时跳过已完成的文件
+```
+
+---
+
+## Pipeline 配方
+
+### 配方 A: 去背 + 统一尺寸 + 合并精灵图
+
+```yaml
+# ta-workspace/tile_pipeline.yaml
+input:
+  dir: assets/images/raw_tiles/
+  glob: "*.png"
+
+steps:
+  - command: remove-background
+    method: floodfill
+    tolerance: 40
+  - command: trim
+    threshold: 10
+  - command: resize
+    width: 128
+    height: 128
+  - command: pad
+    all: 4
+
+output:
+  dir: ta-workspace/tmp/tiles_processed/
+
+assemble:
+  sprite-sheet:
+    output: assets/images/tiles_atlas
+    columns: 6
+    padding: 2
+```
+
+```bash
+playcraft image pipeline --config ta-workspace/tile_pipeline.yaml
+```
+
+### 配方 B: 多个主题色版本
+
+为同一套素材生成不同色调的主题变体：
+
+```bash
+# 蓝色主题
+playcraft image pipeline --config ta-workspace/theme_blue.yaml
+
+# 红色主题（修改 tint color 即可）
+sed 's/#4466BB/#BB4444/' ta-workspace/theme_blue.yaml > ta-workspace/theme_red.yaml
+playcraft image pipeline --config ta-workspace/theme_red.yaml
+```
+
+### 配方 C: 批量缩略图生成
+
+```yaml
+input:
+  dir: assets/images/concept/
+  glob: "*.png"
+steps:
+  - command: resize
+    width: 240
+    height: 240
+    fit: cover
+  - command: convert
+    format: webp
+    quality: 80
+output:
+  dir: assets/images/thumbnails/
+```