@playcraft/cli 0.0.40 → 0.0.42

package/project-template/templates/developer-log.template.md

@@ -0,0 +1,134 @@
+# Developer Log
+
+## Upstream Intake
+
+> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.**
+
+| Doc                         | Read ✓ | One-line takeaway                         |
+| --------------------------- | ------ | ----------------------------------------- |
+| `docs/project-state.md`     | ☐      | {{e.g. ui_pass, Wave 2 done}}             |
+| `docs/design-brief.md`      | ☐      | {{e.g. flow scenes for navigation}}       |
+| `docs/layout-spec.md`       | ☐      | {{e.g. zones, assetMapping, atlas paths}} |
+| `docs/atom-plan.json`       | ☐      | {{e.g. Developer atoms + skillRefs}}      |
+| `docs/atom-plan.md`         | ☐      | Impl Skill Context + acceptance           |
+| `docs/style-exploration.md` | ☐      | {{e.g. MC panel layout per scene}}        |
+| `logs/designer-log.md`      | ☐      | {{e.g. palette locked, motion notes}}     |
+| `logs/ta-log.md`            | ☐      | {{e.g. compliance green, atlas params}}   |
+
+---
+
+## Skill Preflight
+
+> **Before any `game/` edits (ui_pass).** See `refs/developer-phase1-flow.md` Step 3.
+
+| skillRef     | access                | `ref/` files read (paths) | `scaffold` included |
+| ------------ | --------------------- | ------------------------- | ------------------- |
+| {{skillRef}} | linked / cli-fallback | {{paths}}                 | yes / no            |
+
+---
+
+## UI Pass Plan
+
+> **ui_pass only — mandatory before UI implementation.** Hook enforces on STOP.
+
+### Architecture
+
+- **Engine**: {{engine}}
+- **Entry**: `game/index.html`
+- **Scene flow**: Hook → Tutorial → EndCard → CTA (navigation only in ui_pass)
+
+### Scene-Asset Binding Plan
+
+| Scene    | Assets (assetMapping) | Atlas/Frame | On disk? |
+| -------- | --------------------- | ----------- | -------- |
+| hook     | {{paths}}             | {{json}}    | {{y/n}}  |
+| tutorial | {{paths}}             | {{json}}    | {{y/n}}  |
+| endcard  | {{paths}}             | {{json}}    | {{y/n}}  |
+
+### Scene navigation (for Reviewer ui_diff)
+
+| MC panel   | Scene key   | How to reach (URL param / button)  |
+| ---------- | ----------- | ---------------------------------- |
+| Concept    | {{initial}} | {{e.g. ?scene=main or default}}    |
+| Hook       | hook        | {{e.g. ?scene=hook}}               |
+| Onboarding | tutorial    | {{e.g. button or ?scene=tutorial}} |
+| EndCard    | endcard     | {{...}}                            |
+| CTA        | cta         | {{...}}                            |
+
+### Risk Checklist (ui_pass)
+
+- [ ] Every assetMapping path verified on disk
+- [ ] Scene navigation documented for all 5 MC panels
+- [ ] No core gameplay rules in ui_pass scope
+- [ ] No external network dependencies
+
+---
+
+## Gameplay Pass Plan
+
+> **gameplay_pass only — mandatory before PGS / rules implementation.**
+
+### PGS Strategy
+
+- **Gameplay type**: {{from design-brief}}
+- **Core rules**: {{from Skill recipe}}
+- **First level guarantee**: {{how tutorial ensures win}}
+- **State machine**: {{states and transitions}}
+
+### Risk Checklist (gameplay_pass)
+
+- [ ] UI shell unchanged unless open UI Diff items
+- [ ] testCases written before rule implementation
+- [ ] First level guarantees player success
+- [ ] CTA handler with platform fallbacks
+- [ ] Zero external network requests
+
+---
+
+## Experience Flow → Code Mapping
+
+| Storyboard Frame | Scene/State      | Code Location             | Visual Intent |
+| ---------------- | ---------------- | ------------------------- | ------------- |
+| Hook             | `scene.hook`     | `game/scenes/hook.ts`     | {{intent}}    |
+| Tutorial         | `scene.tutorial` | `game/scenes/tutorial.ts` | {{intent}}    |
+| Gameplay         | `scene.gameplay` | `game/scenes/gameplay.ts` | {{intent}}    |
+| EndCard          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{intent}}    |
+
+---
+
+## Dev self-check
+
+### ui_pass completion
+
+- **devUrl**: {{http://localhost:...}}
+- **devStatus**: ui_ready
+- **UI vs MC + layout-spec**: {{pass/fail — notes}}
+- **Scene navigation works**: {{yes/no}}
+- **Ready for Reviewer ui_diff**: {{yes/no}}
+
+### gameplay_pass completion
+
+- **devUrl**: {{http://localhost:...}}
+- **devStatus**: ready
+- **Gameplay vs design-brief + PGS**: {{pass/fail — notes}}
+- **Runtime** (CTA, audio, state machine): {{pass/fail — notes}}
+- **Ready for Reviewer load_check**: {{yes/no}}
+
+---
+
+## Upstream blockers
+
+| Path     | Issue     | Expected       | routeTo            | Status          |
+| -------- | --------- | -------------- | ------------------ | --------------- |
+| {{path}} | {{issue}} | {{acceptance}} | TA / Designer / PM | open / resolved |
+
+---
+
+## Per-Atom Delivery
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Phase**: ui_pass / gameplay_pass
+- **Output path**: {{file_path}}
+- **Notes**: {{notes}}

package/project-template/templates/five-axis-framework.md

@@ -0,0 +1,186 @@
+# Five-Axis Analysis Framework
+
+> **When to read**: PM reads this during Step 4 (Five-Axis Evaluation).
+> Every playable ad request must be classified along all five orthogonal axes before generating options.
+
+The five axes are **orthogonal** — each is an independent decision. The same Match-3 game can be Flat 2D or 2.5D, Tap-only or Drag, L0 or L1, Competence Arc or Challenge Arc. PM evaluates all five internally, then presents 2-3 complete options (covering all axes) for the user to choose from.
+
+---
+
+## Axis 1 — Mechanic (Gameplay Fusion Types)
+
+| Type | Definition | Tutorial Overhead | Risk |
+|------|-----------|-------------------|------|
+| **Single** | One mechanic, no fusion | Baseline | None |
+| **Type A — Visual Fusion** | Mechanics unchanged; elements re-skinned to another game's visual language | None | Very Low |
+| **Type B1 — Passive Borrowing** | Primary mechanic + secondary mechanic auto-triggers (no extra user gesture) | Minimal | Low |
+| **Type B2 — Active Borrowing** | Primary mechanic + secondary mechanic requires user activation (1.5 core gestures) | Slight increase | Medium |
+| **Type C — Sequential Fusion** | Two mechanic sets appear in sequence (includes rotation/alternating mode) | High | High |
+| **Type D — Parallel Fusion** | Two mechanic sets active simultaneously, sharing the screen | Extreme | Extreme (almost never viable for ads) |
+
+### Pseudo-Fusion Technique
+
+When the user insists on Type C/D, recommend pseudo-fusion: **visually appear as two systems, but the underlying mechanic is single**. Example: Match-3 elimination count drives a monster HP bar — the user only performs match-3 the entire time, but perceives "elimination + combat."
+
+### Decision Rules
+
+```
+User prompt contains fusion intent?
+  YES → Classify A / B1 / B2 / C / D
+    Type C/D → Auto-generate downgrade option (pseudo-fusion B1) as recommended
+  NO → Single gameplay → PGS priority check:
+    1. Implemented PGS (Match-3, Triple Match, Path Elimination, Arrow Pick Match) — lowest risk
+    2. Existing Skill (ball_sort, bubble_shooter, etc.) — medium risk
+    3. Needs new development — highest risk
+```
+
+---
+
+## Axis 2 — Dimension (Gameplay Dimension Spectrum)
+
+| Dimension | Description | Designer Impact | Developer Impact | Risk Delta |
+|-----------|------------|----------------|-----------------|------------|
+| **Flat 2D** | Pure 2D sprites, no depth | Standard 2D illustration assets | Standard 2D logic | None |
+| **2.5D Visual** | 3D rendered look, but game logic remains 2D grid (depth is decorative) | 3D-feel rendering / model textures, ~3x cost | Logic stays 2D, add depth rendering | +Medium |
+| **Isometric** | Fixed 45° angle, depth is aesthetic not mechanic | Isometric assets, strict pixel alignment required | Isometric coordinate transforms | +Low |
+| **True 3D** | Z-axis is a live mechanic (rotation/depth participates in interaction) | Full 3D models via AI (`generate-3d`) or white model + texture pipeline; 3–5x cost | 3D engine, physics, camera management; all existing PGS invalidated | +High (tool support available, not BLOCKED) |
+
+### Key Judgment
+
+Is the dimension upgrade "purely visual decoration" (2.5D Visual) or "Z-axis participates in mechanics" (True 3D)? The former only affects Designer asset cost; the latter requires entirely new PGS — fundamentally different risk profiles.
+
+### True 3D Tool Support (Available as of 2026-05)
+
+True 3D is **High Risk** but no longer blocked. Designer has two asset pipelines:
+
+**Pipeline A — AI Generation (best quality, ~1–5 min per model)**
+```bash
+playcraft tools generate-3d --prompt "low-poly wooden crate" --output assets/models/crate.glb
+playcraft 3d optimize --input crate.glb --output crate_opt.glb
+```
+
+**Pipeline B — White Model + Texture (fastest, predictable UV)**
+```bash
+playcraft 3d list-models                             # sphere, cube, cylinder, cone, torus, plane, capsule
+playcraft tools generate-image --prompt "texture" --output tex.png
+playcraft 3d apply-texture --model cube --texture tex.png --output crate.glb
+```
+
+### Decision Rules
+
+```
+Z-axis is a live mechanic (rotation/depth affects gameplay)?
+  → True 3D — tool pipeline available (Pipeline A or B above)
+              still recommend generating 2.5D Visual option as fallback
+3D visual feel but 2D interaction grid?
+  → 2.5D Visual (Designer cost ~3x, Developer logic unchanged)
+Fixed isometric perspective?
+  → Isometric
+Otherwise → Flat 2D (default, zero additional risk)
+```
+
+---
+
+## Axis 3 — Interaction Modality
+
+| Modality | Description | Tutorial Time | Audience Width | Risk Delta |
+|----------|------------|--------------|---------------|------------|
+| **Tap Only** | Single-finger single-tap | ≤1s | Broadest (includes elderly, children) | None |
+| **Tap + Swipe** | Tap + directional swipe | ~3s | Broad | +Low |
+| **Drag** | Press-hold and drag to target | ~5s | Medium | +Low |
+| **Tap + Hold** | Tap + long-press with timing | ~5s | Medium | +Medium |
+| **Multi-touch** | Two or more fingers simultaneously | ≥10s | Very narrow | +Extreme (almost never viable for ads) |
+
+### Key Insight
+
+The **same mechanic** can have different interaction implementations. Arrow gameplay can be "tap a cell" (Tap Only) or "drag to draw a path" (Drag) — Tutorial time differs by 5x, audience width differs dramatically.
+
+### Decision Rules
+
+```
+What gesture does the mechanic naturally map to?
+  → Select the most natural modality
+Does a simpler modality (Tap Only) serve the mechanic adequately?
+  → If yes, prefer simpler — wider audience, shorter tutorial
+Multi-touch required?
+  → Flag as high risk for 30s ad; recommend single-touch alternative
+Note tutorial time budget: Tap=1s / Tap+Swipe=3s / Drag=5s / Tap+Hold=5s
+```
+
+---
+
+## Axis 4 — Narrative Level
+
+| Level | Definition | Designer Impact | Tutorial Method | 30s Fitness |
+|-------|-----------|----------------|----------------|------------|
+| **L0 Pure Mechanic** | No character, no story, pure gameplay showcase | No character assets | Highlight hints + text | High (concise) |
+| **L1 Character Present** | Protagonist exists but no plot ("help the kitten match!") | 1 character sprite set needed | Character performs demo action | **Highest (recommended)** |
+| **L2 Scenario Wrapper** | Character + problem scenario ("princess trapped, clear obstacles") | Protagonist + scenario narrative assets | Character dialogue + demo | Medium (must be tight) |
+| **L3 Story-Driven** | Narrative is core, mechanics serve the story | Heavy story assets + storyboards | Cinematic storytelling | Low (almost never fits 30s) |
+
+### Key Insights
+
+- **L1 is the sweet spot for playable ads** — emotional connection without time overhead.
+- L1+ means Designer needs character assets; PM must define character concept.
+- L3 is **incompatible with 30s format** — auto-downgrade to L2 with explanation.
+
+### Decision Rules
+
+```
+User mentions character / hero / story? → L1 or L2
+Game genre typically story-heavy (RPG, adventure)? → L2 recommended
+No character signal, generic product? → L0 or L1
+Default for playable ads: L1
+L2+: flag that Designer needs character asset set
+L3: auto-downgrade to L2 — incompatible with 30s format
+```
+
+---
+
+## Axis 5 — Emotional Arc
+
+| Arc Type | Player Journey | Hook Design | Gameplay Feel | EndCard Tone |
+|----------|---------------|-------------|--------------|-------------|
+| **Competence** | Confused → Learned → "I'm smart!" | Show "looks hard but has a pattern" | Generous, guarantee success | "Easy and fun, keep playing" |
+| **Challenge** | Looks hard → All-out effort → Achievement | Create difficult scenario | Difficulty ramp, allow failure | "Think you can beat it?" |
+| **Curiosity** | What is this? → Aha! → Surprise | Show counter-intuitive mechanic | Full of surprises | "More to explore" |
+| **Relaxation** | Enter flow → Enjoy rhythm → Satisfaction | Serene, beautiful imagery | Steady pace, low pressure | "Come relax anytime" |
+| **Urgency** | Crisis → Frantic action → Narrow escape | Emergency scene, countdown | High pressure, fast pace | "One more round!" |
+
+### Key Principle
+
+The Emotional Arc is the **unified throughline** across Hook → Tutorial → Gameplay → EndCard. If the Hook creates curiosity but Gameplay delivers relaxation, the experience fractures. The arc must be locked at the PM stage; all downstream Agents execute along this arc.
+
+### Decision Rules
+
+```
+Map user motivation type (JTBD) to arc:
+  Stress Relief → Relaxation or Competence Arc
+  Challenge/Mastery → Challenge Arc
+  Collection/Growth → Competence Arc
+  Creativity/Expression or Immersion/Escape → Curiosity Arc
+  Time pressure / urgency game → Urgency Arc
+Select ONE arc. Lock it as the throughline for all 4 stages.
+```
+
+---
+
+## Option Generation (After All Five Axes)
+
+After completing all five internal classifications, generate 2-3 complete options:
+
+```
+Each option includes:
+  - Mechanic Axis (type + PGS coverage)
+  - Dimension Axis (type + Designer impact)
+  - Interaction Modality (modality + tutorial time estimate)
+  - Narrative Level (level + asset impact)
+  - Emotional Arc (arc type + Hook/EndCard tone)
+  - Overall Risk Rating (Low / Medium / High / Extreme)
+
+Option A (recommended) = lowest-risk viable option, listed first
+Option B = stronger visual/experience but with extra cost
+Option C = user's original request (if extreme risk, mark with warning)
+
+User only needs to answer "choose A/B/C" or "agree with recommendation"
+```

package/project-template/templates/intent-clarifications.template.md

@@ -0,0 +1,58 @@
+# Intent Clarifications
+
+> **Living Document**: Agent 间异步澄清的共享空间。
+> 所有 Agent 可读；提问 Agent 和目标 Agent 可写。
+> 不阻塞流水线 — 提问 Agent 先用合理推断继续，回答到达后评估是否调整。
+
+## Open Questions
+
+| #     | From           | To               | Atom/Topic           | Question              | Raised At      | Status |
+| ----- | -------------- | ---------------- | -------------------- | --------------------- | -------------- | ------ |
+| {{n}} | {{agent_name}} | {{target_agent}} | {{atom_id_or_topic}} | {{specific_question}} | {{stage_name}} | open   |
+
+<!--
+Status values:
+  open     — 等待目标 Agent 回答
+  pending  — 目标 Agent 已看到，正在处理
+  answered — 目标 Agent 已回答，提问 Agent 尚未确认
+  resolved — 双方达成一致，已移入 Resolved 表
+
+Rules:
+  - 提问必须具体，不能是"风格不对"这种模糊描述
+  - 必须引用具体文件路径或 atomId，方便目标 Agent 定位
+  - Confidence = low 的风格解读问题必须写入此表
+  - Developer 发现故事板与 layout-spec 坐标不一致时，必须向 PM 提问
+-->
+
+## Resolved
+
+| #     | From           | To               | Question Summary     | Answer          | Resolution              | Closed By      |
+| ----- | -------------- | ---------------- | -------------------- | --------------- | ----------------------- | -------------- |
+| {{n}} | {{agent_name}} | {{target_agent}} | {{one_line_summary}} | {{answer_text}} | {{how_it_was_resolved}} | {{agent_name}} |
+
+<!--
+Resolution examples:
+  - "已补充到 designer-log.md Style Intent Notes"
+  - "已更新 layout-spec.md zones 坐标"
+  - "PM 裁决：以故事板为准，layout-spec 将修正"
+  - "双方同意保持现状，偏差在可接受范围"
+-->
+
+## Metrics
+
+| Metric                 | Value     |
+| ---------------------- | --------- |
+| Total questions raised | {{count}} |
+| Unresolved             | {{count}} |
+| By Designer            | {{count}} |
+| By TA                  | {{count}} |
+| By Developer           | {{count}} |
+| By PM                  | {{count}} |
+| By Reviewer            | {{count}} |
+
+<!--
+PM monitors this table:
+  - If single Agent receives >3 questions → intent transmission fault, record in DAG Revisions
+  - If unresolved >3 at any time → PM must intervene and assign priority
+  - If Reviewer finds unresolved questions at review stage → deduct Intent Transmission score
+-->

package/project-template/templates/layout-spec.template.md

@@ -0,0 +1,146 @@
+# Layout Spec
+
+<!--
+  PM owns paths + specs (Gate #1 lock). CONTRACT only — zones, palette ids, assetMapping, atlas table, WxH/format.
+  Do NOT add: storyboard prose, Style Intent Notes, TA logs (→ designer-log / ta-log).
+-->
+
+> Shared contract between Designer, TA, and Developer. All MUST follow this document.
+
+## Screen
+
+- Orientation: {{portrait/landscape}}
+- Resolution: {{width}} x {{height}}
+- Safe area: top {{top_safe}}px, bottom {{bottom_safe}}px
+
+## Zones
+
+| id          | role          | rect (x, y, w, h)          | owner                       |
+| ----------- | ------------- | -------------------------- | --------------------------- |
+| {{zone_id}} | {{zone_role}} | {{x}}, {{y}}, {{w}}, {{h}} | {{Designer/Developer/both}} |
+
+<!--
+Add one row per zone. Common zones:
+- header: HUD (score/progress), usually at top
+- board: Main game area (grid/play field)
+- footer: Extended background area
+- endcard: CTA region, usually at bottom
+
+ASCII diagram (update to match your zones):
+┌─────────────────────────┐ y=0
+│  {{zone_1}}             │ {{h1}}px
+├─────────────────────────┤
+│  {{zone_2}}             │ {{h2}}px
+├─────────────────────────┤
+│  {{zone_3}}             │ {{h3}}px
+└─────────────────────────┘
+-->
+
+## Color Palette
+
+### Element Colors
+
+| id             | hex           | label            |
+| -------------- | ------------- | ---------------- |
+| {{element_id}} | {{hex_color}} | {{display_name}} |
+
+<!--
+- Element IDs are used by Developer in PGS config
+- Hex colors guide Designer's generation prompts
+- Labels are human-readable names for the elements
+- Typically 4-6 elements for a playable ad
+-->
+
+### Other Colors
+
+- Background: primary `{{bg_primary_hex}}`, secondary `{{bg_secondary_hex}}`
+- UI: text `{{ui_text_hex}}`, accent `{{ui_accent_hex}}`
+
+## Asset Spec
+
+| Type            | Dimensions            | Format |
+| --------------- | --------------------- | ------ |
+| tileSize        | {{tile_w}}x{{tile_h}} | webp   |
+| backgroundSize  | {{bg_w}}x{{bg_h}}     | webp   |
+| iconSize        | {{icon_w}}x{{icon_h}} | webp   |
+| audio (BGM/SFX) | —                     | mp3    |
+
+<!--
+Default runtime formats: images WebP, audio MP3. TA delivers atlas groups as .webp + .json sidecar.
+-->
+
+## Atlas grouping (Gate #1 — PM defines)
+
+| groupId | elementIds       | atlasPath                            | sidecarPath                          |
+| ------- | ---------------- | ------------------------------------ | ------------------------------------ |
+| tiles   | {{id1}}, {{id2}} | assets/images/tiles/tiles_atlas.webp | assets/images/tiles/tiles_atlas.json |
+| ui      | {{id3}}, {{id4}} | assets/images/ui/ui_atlas.webp       | assets/images/ui/ui_atlas.json       |
+
+<!--
+Rules: ≥2 elements in same logical class (tiles / ui / vfx) → ONE webp+json atlas.
+Single large assets (full-screen bg) → one webp path only. Digit strip → separate webp (see Text Assets).
+Each elementId in assetMapping uses atlasPath + frameId OR single visualAsset path.
+-->
+
+## Asset Mapping
+
+| elementId      | visualAsset / atlas                   | frameId | sfx                                   |
+| -------------- | ------------------------------------- | ------- | ------------------------------------- |
+| {{element_id}} | assets/images/tiles/tiles_atlas.webp  | tile_01 | {{sfx_path_or_dash}}                  |
+| —              | assets/images/bg/{{bg_filename}}.webp | —       | —                                     |
+| —              | assets/images/ui/{{ui_element}}.webp  | —       | —                                     |
+| —              | assets/images/txt/{{text}}.webp       | —       | —                                     |
+| —              | assets/images/vfx/{{vfx}}.webp        | —       | —                                     |
+| —              | —                                     | —       | assets/audio/sfx/{{sfx_filename}}.mp3 |
+| —              | —                                     | —       | assets/audio/bgm/{{bgm_filename}}.mp3 |
+
+<!--
+CRITICAL: This mapping is the integration contract!
+- Designer saves files at EXACTLY these paths
+- Developer references EXACTLY these paths in code
+- Path mismatch = integration failure
+- Use "—" for cells that don't apply
+
+Transparency convention (TA auto-derives from path — PM does NOT define):
+  assets/images/bg/   → opaque, full-screen background (TA verifies edge-to-edge)
+  assets/images/ui/   → needs alpha (TA applies chroma key + remove-background)
+  assets/images/txt/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/vfx/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/tiles/ → needs alpha by default (except card faces / board pieces)
+  assets/audio/       → N/A (not image)
+
+TA determines chroma key color (green/blue/magenta) based on element color palette
+and color conflict rules — see ta-pipeline-cookbook.md Step 0e.
+-->
+
+## Text Assets
+
+All visible text is rendered as image assets — no font files in the final build.
+
+### Static Text (baked into Master Composite concept panel)
+
+| id          | text content    | asset path                              | notes                    |
+| ----------- | --------------- | --------------------------------------- | ------------------------ |
+| {{text_id}} | {{text_string}} | assets/images/ui/{{text_filename}}.webp | TA extracts from concept |
+
+<!--
+Common static text: game title, CTA button label, tutorial instructions, "YOU WIN", stage labels.
+Designer includes all static text in the Master Composite concept panel.
+TA extracts each text element using segment and saves to the specified path.
+-->
+
+### Digit Sprite Strip (for dynamic numbers)
+
+- **Characters**: `{{digit_characters}}`
+- **Cell size**: {{cell_w}}x{{cell_h}}
+- **Asset path**: `assets/images/ui/digits.webp`
+
+<!--
+PM defines the character set based on what dynamic text the game needs.
+Common sets:
+- Score only: "0123456789"
+- Score + timer: "0123456789:."
+- Score + multiplier: "0123456789x+,."
+Designer generates a single horizontal strip image with all characters in order.
+Developer slices by character index at runtime (char_x = index * cell_w).
+-->