@playcraft/cli 0.1.53-beta → 0.1.54

package/project-template-v2/.claude/agents/refs/game-designer-gameplay-sufficiency.md

@@ -1,123 +0,0 @@
-# Gameplay Sufficiency Self-Check
-
-> **When to read**: Game Designer reads this after a candidate direction is selected and before writing final `docs/design.md`. This is a **blocking gate** — do not write the design contract until all angles pass.
->
-> **Pattern**: Modeled on Flow B's "玩法核心充分性 Review" — 8 angles covering MDA, Game Feel, visual readability, and Playable Ad flow completeness.
-
----
-
-## Purpose
-
-Verify that the chosen direction contains enough gameplay depth to support `docs/design.md`, module selection, and downstream production. This check prevents the common failure mode of "proceeding with a technically plausible but experientially shallow design."
-
-**Why before Five-Axis**: Five-Axis evaluation and Style Direction must serve the core gameplay. If the gameplay itself is underspecified, five-axis choices become disconnected from player experience.
-
----
-
-## 8-Angle Review Table
-
-For each angle, answer the core question. If the answer is unclear or only partially addressed by the chosen direction / draft design → mark ❌ and return to brainstorm for targeted clarification.
-
-| #   | Angle                  | Core Question                                                                            | ✅ Pass Signal                                                                                             | ❌ Fail Signal                                                                       |
-| --- | ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| 1   | **MDA / Mechanics**    | Core rules, player operations, legal/illegal actions — are they explicit?                | Can state: "player does X → system checks Y → result Z" with no ambiguity                                  | Only describes features/functions, never states rules                                |
-| 2   | **MDA / Dynamics**     | What strategy, rhythm, risk, or feedback loop emerges from consecutive play?             | Can describe: "after 3-5 operations, player experiences {tension/flow/escalation} because {mechanism}"     | Single operation is clear but no loop or decision pressure described                 |
-| 3   | **MDA / Aesthetics**   | Which 2-3 emotion types does this game primarily deliver?                                | Specific emotions named with source (e.g., "Sensation from cascade VFX + Challenge from near-win")         | Only "fun" / "exciting" / "engaging" without identifying emotion source              |
-| 4   | **Game Feel / Juice**  | Is the input → response → satisfaction chain planned?                                    | Each core interaction has: what feedback (visual + audio), when it fires, how it escalates on combo/streak | "Click something → something happens" — no feedback specifics                        |
-| 5   | **Visual Readability** | Can player instantly distinguish: clickable / unclickable / target / risk / progress?    | Direction or design describes HOW each gameplay state is visually communicated to the player               | Only describes art style or tech stack, not how visuals serve gameplay understanding |
-| 6   | **Level Progression**  | Do levels serve gameplay teaching and challenge escalation, or are they just data files? | Each level/stage has stated intent: "level 1 teaches X, level 2 tests Y, level 3 introduces Z"             | Only lists level count or says "difficulty increases" without per-level purpose      |
-| 7   | **Playable Ad Flow**   | Does Hook → Tutorial → Gameplay → EndCard form a 15-30s emotional closed loop?           | All four stages named with emotional beat, timing, and transition triggers                                 | Only describes the gameplay loop, no ad-specific rhythm (hook, CTA, sequel feeling)  |
-| 8   | **Data Derivation**    | Are data structures derived FROM gameplay rules, or do they drive/constrain gameplay?    | Rules/player-experience described first; data representation follows naturally                             | JSON schema / config format / solver algorithm appears before "how to play"          |
-
----
-
-## Output Format
-
-Write self-check results in handoff summary or internal notes. Do not add a full self-check table to `docs/design-brief.md`:
-
-```markdown
-### Gameplay Sufficiency Self-Check
-
-| Angle              | Result | Notes                                                                                                       |
-| ------------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
-| MDA / Mechanics    | ✅     | Tap to unscrew → color-match to hole → gravity release when all screws removed                              |
-| MDA / Dynamics     | ✅     | Buffer management creates "which screw to remove first" strategy                                            |
-| MDA / Aesthetics   | ✅     | Sensation (satisfying unscrew SFX + gravity cascade) + Challenge (buffer full = lose)                       |
-| Game Feel / Juice  | ❌     | Success cascade feedback not specified — need to define what happens on multi-release                       |
-| Visual Readability | ✅     | Color = screw-hole match affordance; glow = removable; grey = blocked                                       |
-| Level Progression  | ✅     | L1: single color; L2: two colors; L3: introduce blocking order                                              |
-| Playable Ad Flow   | ✅     | Hook: show stuck board → Tutorial: guided first screw → Gameplay: 3-level cascade → EndCard: "more puzzles" |
-| Data Derivation    | ✅     | Rules defined first; level JSON is just instantiation of rule parameters                                    |
-
-**Result**: 7/8 pass. ❌ Game Feel → return to Step 1 for targeted clarification on cascade feedback design.
-```
-
----
-
-## Decision
-
-- **All 8 ✅** → Proceed to Step 3 (Five-Axis Evaluation)
-- **Any ❌** → Return to Step 1 with specific angle as the brainstorm target. Ask user only about the gap (not re-do entire brainstorm).
-
----
-
-## Reference Frameworks (Condensed for Playable Ads)
-
-### MDA — 8 Aesthetics Taxonomy (Playable Ad Relevance)
-
-| #   | Type           | Relevance  | Role in Playable Ads                                              |
-| --- | -------------- | ---------- | ----------------------------------------------------------------- |
-| 1   | **Sensation**  | ⭐⭐⭐⭐⭐ | Core — visual juice + audio feedback is the baseline for every ad |
-| 2   | **Challenge**  | ⭐⭐⭐⭐⭐ | Core — "one more try" / near-win is the #1 conversion driver      |
-| 3   | **Submission** | ⭐⭐⭐⭐   | Casual/relaxing ads — low-pressure flow, "mindless but addictive" |
-| 4   | **Discovery**  | ⭐⭐⭐     | Puzzle/reveal ads — "aha, that's how it works!" moment            |
-| 5   | **Fantasy**    | ⭐⭐       | Theme wrapping only — 15s too short for deep immersion            |
-| 6   | **Expression** | ⭐⭐       | Dress-up/customization ads — niche                                |
-| 7   | **Narrative**  | ⭐         | Almost never fits in 30s                                          |
-| 8   | **Fellowship** | ⭐         | Playable ads are single-player                                    |
-
-**Design questions:**
-
-1. "Which 2-3 aesthetics does this game primarily deliver?"
-2. "What does the player feel at second 5? At second 15? At second 25?"
-3. "Can the player experience one complete emotional cycle in 15-30s?"
-
-### 5-Component Filter (Quick Scoring)
-
-Evaluate each core mechanic against 5 components:
-
-| Component        | Core Question                    | ⭐⭐⭐ (Excellent)             | ❌ (Fail)               |
-| ---------------- | -------------------------------- | ------------------------------ | ----------------------- |
-| **Clarity**      | Can player understand in 3s?     | Zero-tutorial comprehension    | 5s+ still confused      |
-| **Motivation**   | Why does player want to act?     | Can't stop, intrinsic drive    | "Why should I do this?" |
-| **Response**     | Feedback within 100ms?           | Multi-channel instant feedback | Action → silence        |
-| **Satisfaction** | Does success feel "juicy"?       | Want "one more time"           | Success feels empty     |
-| **Fit**          | Mechanic matches theme/audience? | Inseparable from the game      | Feels "bolted on"       |
-
-**Minimum bar for Playable Ads**: All 5 components ≥ ⭐⭐. Any ❌ = redesign needed.
-
-### Game Feel — 6-Component Diagnostic
-
-When something "feels off" but can't be named, check:
-
-| Component         | Symptom                              | Fix Direction                                                                   |
-| ----------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
-| Real-Time Control | Sluggish, unresponsive               | Reduce input delay; enable animation interrupts                                 |
-| Simulated Space   | Floaty, unpredictable movement       | Make physics internally consistent (can be unrealistic but MUST be predictable) |
-| Polish (Juice)    | Technically correct but lifeless     | Add particles, screen shake, squash/stretch, sound layers                       |
-| Metaphor          | Feedback feels "wrong" for the world | Align audio/visual feedback with what real-world physics would suggest          |
-| Juiciness         | Actions feel powerless               | Amplify output-to-input ratio; small tap → big response                         |
-| Mastery           | Gets boring fast                     | Ensure control depth allows skill expression over time                          |
-
-**Playable Ad note**: In 15-30s, focus on components 1-5. Component 6 (Mastery) manifests as "perceived depth" — player should feel "I could get better at this" which drives install.
-
----
-
-## Common Failure Patterns
-
-| Pattern                  | Example                                                                         | How to Fix                                                                              |
-| ------------------------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| **Feature-list design**  | "Has scoring, timer, 3 levels, power-ups" — no rules/emotions                   | Ask: "When player does X, what happens and how does it FEEL?"                           |
-| **Tech-first design**    | "Uses physics engine with rigid bodies and constraints" — no player perspective | Ask: "What does the PLAYER see and do? Forget the implementation."                      |
-| **Single-moment design** | "Player taps tiles to match" — no loop/escalation/arc                           | Ask: "After the 5th successful match, what's different? What pressure builds?"          |
-| **Borrowed assumption**  | "It's like Candy Crush" without specifying which aspects                        | Ask: "WHICH aspects of Candy Crush? Swap mechanic? Cascade? Level goals? Visual juice?" |

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

@@ -1,88 +0,0 @@
-# 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-v2/.claude/agents/refs/ta-atlas-deliverable-standard.md

@@ -1,67 +0,0 @@
-# TA Atlas Deliverable Standard
-
-> **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
-
-| 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 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).
-
-## 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: Artist MP3 → `playcraft audio compress/trim/loop/fade` → output **MP3**; verify with `playcraft audio info`.
-
-## Transparency requirements
-
-| Asset category                | Alpha required | Chroma key strategy                                  | Post-verify                               |
-| ----------------------------- | -------------- | ---------------------------------------------------- | ----------------------------------------- |
-| UI overlay (icons, text, HUD) | ✅ channels=4  | Per color conflict matrix (see ta-pipeline-cookbook) | Dark-bg overlay verify (no white/residue) |
-| VFX atlas (glow, particles)   | ✅ channels=4  | Blue screen #0000FF (VFX常含金/橙色)                 | Per-frame dark-bg verify                  |
-| Game element atlas (tiles)    | ✅ channels=4  | Per color conflict matrix                            | Dark-bg overlay verify                    |
-| Card/board piece (rect body)  | ❌ opaque OK   | N/A (white bg is part of the asset)                  | N/A                                       |
-| Full-screen background        | ❌ opaque OK   | N/A                                                  | Edge-to-edge full-coverage check          |
-| Digit strip                   | ✅ channels=4  | Blue screen #0000FF (digits often gold/white)        | Dark-bg overlay verify                    |
-
-**Color conflict matrix** — choose chroma key color to avoid edge residue:
-
-- Gold/yellow/orange/green assets → **blue screen #0000FF** (never green)
-- Blue/purple assets → **green screen #00FF00** (never blue)
-- Multi-color/rainbow → **magenta #FF00FF** (last resort)
-- All others → green screen #00FF00 (default)
-
-## 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  |
-| **Alpha check** | All transparent assets have `channels=4` (verified via `playcraft image info`) |
-| **Dark-bg OK**  | All transparent assets pass dark-background (#1A1A2E) overlay — no residue     |
-| **BG coverage** | Full-screen backgrounds: edge-to-edge, no fade/vignette/white corners          |
-
-## 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-v2/.claude/agents/refs/ta-batch-pipeline-recipes.md

@@ -1,120 +0,0 @@
-> 本文件是 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/
-```