@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/templates/review-report.template.md

@@ -0,0 +1,275 @@
+# Review Report
+
+> Fill **one section** matching the review mode orchestrator invoked: `design_check` | `execution_plan_check` | `gameplay_conformance` | `ui_diff` | `load_check` | `playable_validate`.
+
+## Review Mode
+
+**{{design_check / execution_plan_check/ gameplay_conformance / ui_diff / load_check / playable_validate}}** — {{ISO timestamp}}
+
+## Verdict
+
+**{{pass / fail}}**
+
+## Ring DoD Fields
+
+> Orchestrator runs `npm run ring:gate -- --iteration N` **after** Reviewer STOP. Only **Reviewer evidence** fields must be `pass`/`fail` before STOP; **runner-owned script** fields stay `pending` until `ring:gate` executes verifiers.
+
+| Field          | Owner    | Value                                           |
+| -------------- | -------- | ----------------------------------------------- |
+| iteration      | both     | {{1 / 2 / 3 / 4}}                               |
+| blockingIssues | Reviewer | {{0..N}}                                        |
+| failRouteTo    | Reviewer | {{developer / reviewer / game-designer / none}} |
+| failReason     | Reviewer | {{one-line summary}}                            |
+
+### Reviewer evidence (pass/fail required before STOP — ring 2+ only)
+
+> Ring 1 `lifecycle` and `firstLevelWin` are script-owned (`npm run verify:lifecycle`, `npm run verify:firstwin`). Hook enforces these only when active for the current ring.
+
+| Field               | Value                                                          |
+| ------------------- | -------------------------------------------------------------- |
+| gameplayConformance | {{pass / fail / pending / n-a — ring 2+ gameplay_conformance}} |
+| hookCta             | {{pass / fail / pending / n-a — ring 3+ playable_validate}}    |
+| uiDiff              | {{pass / fail / pending / n-a — ring 4 ui_diff only}}          |
+
+### Runner-owned script fields (leave pending until ring:gate)
+
+> `gate-runner.mjs` runs npm verifiers and writes results — Reviewer must **not** pre-fill pass/fail.
+
+| Field           | Verifier script         | Value                       |
+| --------------- | ----------------------- | --------------------------- |
+| contract        | verify:contract         | pending                     |
+| lifecycle       | verify:lifecycle        | pending (ring 1+)           |
+| firstLevelWin   | verify:firstwin         | pending (ring 1+)           |
+| oneClickEndcard | record:mp4 → ENDCARD    | pending (ring 2+)           |
+| verifyUi        | verify:ui               | pending / n-a               |
+| fullPlaythrough | record:mp4 full session | pending / n-a               |
+| visualDiff      | verify:visual           | pending / n-a (ring 4)      |
+| assetBudget     | verify:ui:assets        | pending / n-a               |
+| atomConformance | verify:atom-conformance | pending / n-a (ring 4 only) |
+
+---
+
+## design_check (ring 1 clarify / ring 3 verify ASR)
+
+### Ring context
+
+**{{ring 1 — design package / ring 3 — ASR handoff pack}}**
+
+### Contract Checks
+
+| Item                                   | Pass?      | Notes       |
+| -------------------------------------- | ---------- | ----------- |
+| Required files exist                   | {{yes/no}} | {{details}} |
+| Required sections non-empty            | {{yes/no}} | {{details}} |
+| Gate-specific mandatory fields present | {{yes/no}} | {{details}} |
+| Evidence files present                 | {{yes/no}} | {{details}} |
+
+### Blocking Issues
+
+| #     | Issue           | routeTo                |
+| ----- | --------------- | ---------------------- |
+| {{n}} | {{description}} | game-designer / artist |
+
+### Evidence
+
+| Evidence               | Path / note | Present?   |
+| ---------------------- | ----------- | ---------- |
+| Primary contract doc   | {{path}}    | {{yes/no}} |
+| Secondary contract doc | {{path}}    | {{yes/no}} |
+| Supporting artifact    | {{path}}    | {{yes/no}} |
+
+### Outcome
+
+{{pass → orchestrator may run ring:gate / fail → route back to agent}}
+
+---
+
+## execution_plan_check (ring 2 clarify)
+
+### Ring context
+
+**ring 2 — layout-spec + atom-tree + implementation-plan package**
+
+### Contract Checks
+
+| Item                                                                               | Pass?          | Notes       |
+| ---------------------------------------------------------------------------------- | -------------- | ----------- |
+| `layout-spec.md` exists and is structurally complete                               | {{yes/no}}     | {{details}} |
+| `atom-tree.json` exists and is structurally complete                               | {{yes/no}}     | {{details}} |
+| Optional `atom-tree.md` reading guide exists if downstream roles need it           | {{yes/no/n-a}} | {{details}} |
+| `implementation-plan.md` exists and is structurally complete                       | {{yes/no}}     | {{details}} |
+| `layout-spec` `assetMapping` is non-empty                                          | {{yes/no}}     | {{details}} |
+| `implementation-plan` features cover acceptance criteria                           | {{yes/no}}     | {{details}} |
+| Chain coherence is traceable (`layout-spec` → `atom-tree` → `implementation-plan`) | {{yes/no}}     | {{details}} |
+
+### Blocking Issues
+
+| #     | Issue           | routeTo                                |
+| ----- | --------------- | -------------------------------------- |
+| {{n}} | {{description}} | game-designer / ref-flow / plan-writer |
+
+### Evidence
+
+| Evidence            | Path / note                    | Present?       |
+| ------------------- | ------------------------------ | -------------- |
+| Layout contract     | `docs/layout-spec.md`          | {{yes/no}}     |
+| Atom manifest       | `docs/atom-tree.json`          | {{yes/no}}     |
+| Atom companion      | `docs/atom-tree.md` (optional) | {{yes/no/n-a}} |
+| Execution blueprint | `docs/implementation-plan.md`  | {{yes/no}}     |
+
+### Outcome
+
+{{pass → orchestrator may run ring:gate --iteration 2 / fail → route back to producing subagent}}
+
+---
+
+## gameplay_conformance (ring DoD: gameplayConformance — ring 2+ review-backed gate)
+
+### devUrl
+
+{{http://...?debug=1}}
+
+### Check A: Design Drift
+
+| #   | 检查项                     | 结果                 | 详情        |
+| --- | -------------------------- | -------------------- | ----------- |
+| 1   | 核心玩法循环               | {{✅ / ❌ Blocking}} | {{details}} |
+| 2   | 规则体系                   | {{✅ / ❌ Blocking}} | {{details}} |
+| 3   | 胜负条件                   | {{✅ / ❌ Blocking}} | {{details}} |
+| 4   | Experience Flow 四阶段可达 | {{✅ / ❌}}          | {{details}} |
+| 5   | 首关保证                   | {{✅ / ❌ Blocking}} | {{details}} |
+
+**Summary**: {{N}} Blocking / {{M}} Non-blocking
+
+### Check B: Skill Leverage Evidence
+
+| skillRef | Used / consulted? | Notes                 |
+| -------- | ----------------- | --------------------- |
+| {{ref}}  | {{yes/no}}        | {{reason if skipped}} |
+
+### Check C: Path Verification
+
+| Path                | Screenshot                  | Result      |
+| ------------------- | --------------------------- | ----------- |
+| Hook → Tutorial     | `logs/conform-hook.png`     | {{✅ / ❌}} |
+| Tutorial → Gameplay | `logs/conform-gameplay.png` | {{✅ / ❌}} |
+| Gameplay → EndCard  | `logs/conform-endcard.png`  | {{✅ / ❌}} |
+
+### Overall
+
+- **Result**: {{PASS / FAIL}}
+- **gameplayConformance**: {{pass / fail}} — set `logs/review-report.md` § Ring DoD Fields (review-backed gate, ring 2+)
+- **Blocking Issues**: {{count}} — {{summary}}
+- **Non-blocking Notes**: {{count}} — {{summary}}
+
+### Outcome
+
+{{pass → `conformance: passed`, handoff `Invoke @reviewer load_check` / fail → route Developer}}
+
+---
+
+## ui_diff (MC screenshot comparison)
+
+### devUrl
+
+{{http://...?debug=1}}
+
+### Structured Visual Rubric
+
+> **MUST** fill after Reading each screenshot PNG. Evidence must describe visible content, not disk file sizes. Static `verify:ui` PASS is not enough for this section.
+
+| Check ID        | Result (PASS/FAIL) | Evidence (screenshot path + what you see) | recommendedSkill | alphaStrategy |
+| --------------- | ------------------ | ----------------------------------------- | ---------------- | ------------- |
+| bg_clean        | {{PASS/FAIL}}      | {{e.g. logs/ui-diff-game.png — ...}}      | {{playable-art / playable-verify-ui / n-a}} | {{chroma / opaque / n-a}} |
+| no_double_board | {{PASS/FAIL}}      | {{...}}                                   | {{...}}          | {{dual-bg-diff / rgb-alpha-split / n-a}} |
+| no_hud_ghost    | {{PASS/FAIL}}      | {{...}}                                   | {{playable-art / playable-verify-ui / n-a}} | {{rgb-alpha-split / n-a}} |
+| no_fake_ui      | {{PASS/FAIL}}      | {{...}}                                   | {{...}}          | {{...}}       |
+| tile_silhouette | {{PASS/FAIL}}      | {{...}}                                   | {{playable-art / playable-fx-decompose / n-a}} | {{chroma / rgb-alpha-split / overlay-diff / n-a}} |
+| text_no_overlap | {{PASS/FAIL}}      | {{...}}                                   | {{playable-verify-ui / n-a}} | {{n-a}} |
+| mc_layout       | {{PASS/FAIL}}      | {{...}}                                   | {{playable-verify-ui / artist / n-a}} | {{n-a}} |
+
+### Scene comparisons
+
+| Scene | Screenshot            | MC reference | Severity                 | Match?     | routeTo                 | recommendedSkill | alphaStrategy | Fix suggestion |
+| ----- | --------------------- | ------------ | ------------------------ | ---------- | ----------------------- | ---------------- | ------------- | -------------- |
+| hook  | logs/ui-diff-hook.png | {{mc path}}  | {{critical/major/minor}} | {{yes/no}} | {{developer/ta/artist}} | {{playable-art / playable-fx-peak / playable-fx-decompose / playable-verify-ui / n-a}} | {{chroma / dual-bg-diff / rgb-alpha-split / black-add / n-a}} | {{fix}} |
+
+### Summary
+
+- **uiReworkRound**: {{0–5}}
+- **Blocking issues**: {{count critical + major}}
+- **Minor only**: {{yes/no — does not block pass}}
+- **visionEvidence**: {{validate/vision/vision-evidence.json / degraded / n-a}} — {{does it support current FAIL? yes/no + one-line reason}}
+
+### Action Items
+
+| #     | Severity     | routeTo   | recommendedSkill | alphaStrategy | Action           |
+| ----- | ------------ | --------- | ---------------- | ------------- | ---------------- |
+| {{n}} | {{severity}} | {{agent}} | {{skill}}        | {{strategy}}  | {{specific fix}} |
+
+---
+
+## load_check (ring verify — pre-Ring Gate)
+
+### devUrl
+
+{{http://...?debug=1}}
+
+### Checks
+
+| Check                  | Pass?      | Notes                     |
+| ---------------------- | ---------- | ------------------------- |
+| Page loads ≤10s        | {{yes/no}} | {{load time}}             |
+| No console Error logs  | {{yes/no}} | {{error summary or none}} |
+| game/index.html exists | {{yes/no}} | —                         |
+
+### Screenshot
+
+`logs/load-check.png`
+
+### Outcome
+
+{{pass → orchestrator runs npm run ring:gate -- --iteration N / fail → route Developer}}
+
+---
+
+## playable_validate (Loop 3 deep optimization)
+
+### devUrl / MP4
+
+- **MP4**: `recordings/playable-YYYYMMDD-HHmmss.mp4`
+- **Baseline**: {{path to previous MP4 or "none"}}
+- **Report**: `validate/PLAYABLE-YYYYMMDD-HHmmss.md`
+
+### Findings
+
+| Time      | Visible symptom | Severity     | routeTo                 | recommendedSkill | alphaStrategy | Status         |
+| --------- | --------------- | ------------ | ----------------------- | ---------------- | ------------- | -------------- |
+| {{MM:SS}} | {{description}} | {{P0/P1/P2}} | {{developer/ta/artist}} | {{playable-art / playable-fx-peak / playable-fx-decompose / playable-verify-ui / n-a}} | {{chroma / dual-bg-diff / rgb-alpha-split / black-add / chroma-video / dual-bg-video / rgb-alpha-video / opaque-video / n-a}} | {{open/fixed}} |
+
+### Vision Evidence
+
+- **Path**: `validate/vision/vision-evidence.json` / degraded / n-a
+- **Annotated evidence**: {{paths to annotated PNG/MP4 frames}}
+- **Supports current FAIL?**: {{yes/no}} — {{visible evidence summary}}
+
+### Regression vs baseline
+
+- **改善**: {{...}}
+- **仍存**: {{...}}
+- **回归**: {{...}}
+
+### Overall
+
+- **Result**: {{PASS / FAIL}}
+- **P0**: {{count}} | **P1**: {{count}} | **P2**: {{count}}
+
+### Outcome
+
+{{pass → optimizationStatus: passed, handoff orchestrator Ring Gate / fail → route per routeTo, re-enter ring 4 verify}}
+
+---
+
+## Summary
+
+{{one paragraph overall assessment for this review mode}}

package/project-templates/phaser/templates/style-exploration.template.md

@@ -0,0 +1,93 @@
+# Style Exploration
+
+> Artist Phase 1 output (`designer-handoff-v2`). **Ring 3** style lock via **Master Composite (MC)** + **ASR** after user selects an MC option at Ring Gate.
+
+## Style Direction Summary
+
+- **Art style**: {{art_style_from_brief}}
+- **Color mood**: {{color_mood}}
+- **Element theme**: {{element_theme}}
+- **References**: {{reference_games_or_styles}}
+- **Emotional Arc**: {{emotional_arc_from_brief}}
+
+## Options
+
+### Option {{A/B/C}}: {{option_name}}
+
+**Keywords**: {{3-5 keywords}}
+**Color temperature**: {{warm/cold/neutral}}
+**Art approach**: {{1-2 sentences}}
+**Alignment with design-brief**: {{brief alignment}}
+
+#### Master Composite (ring 3 clarify — MC options)
+
+| File                                                         | Description                                                 |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| `assets/images/storyboard/master_composite_option_{{a}}.png` | 5×9:16 panels: concept + Hook + Onboarding + End Card + CTA |
+
+**MC prompt** (summary or path to sidecar `.json`):
+
+```
+{{master_composite_prompt_summary}}
+```
+
+#### Panels (embedded in MC — not separate files)
+
+| Panel # | Label              | Time    | Visual intent                             |
+| ------- | ------------------ | ------- | ----------------------------------------- |
+| 1       | Main Gameplay      | —       | Full UI + all element types + static text |
+| 2       | Key Hook           | 0-3s    | {{hook intent}}                           |
+| 3       | Onboarding HUD     | 3-10s   | {{tutorial intent}}                       |
+| 4       | End Card           | 25-30s  | {{end card intent}}                       |
+| 5       | CTA Always Visible | in-game | {{persistent CTA}}                        |
+
+#### Experience Flow Design
+
+**Emotional Arc Visualization**:
+
+- Hook → {{visual signals}}
+- Tutorial → {{visual signals}}
+- Gameplay Peak → {{near-win signals}}
+- End Card → {{resolution signals}}
+
+**Near-Win Visual Composition**: {{description}}
+
+**Attention Guidance per Stage**: Hook / Tutorial / Gameplay / End Card — {{paths}}
+
+**Audio-Emotion Rhythm** (for Phase 2 BGM/SFX): {{per-stage audio notes}}
+
+---
+
+<!-- Repeat per option (2–3). Ring 3 Ring Gate: user picks A/B/C. Ring 3 build: add ASR + Motion Notes below for selected option only. -->
+
+## Selected option (after ring 3 Ring Gate — MC selection)
+
+- **Selected**: {{A/B/C}}
+- **MC path**: `assets/images/storyboard/master_composite_option_{{X}}.png`
+
+### ASR (ring 3 build)
+
+| File                                                    | Role                    |
+| ------------------------------------------------------- | ----------------------- |
+| `assets/images/reference/ui_state_sheet_{{X}}.png`      | UI component states     |
+| `assets/images/reference/element_state_sheet_{{X}}.png` | Gameplay element states |
+
+Detail tables: `logs/artist-log.md` § ASR Coverage Matrix.
+
+### Motion Notes (ring 3 build)
+
+| Transition          | Type                | Duration | Notes |
+| ------------------- | ------------------- | -------- | ----- |
+| Hook → Tutorial     | {{fade/zoom/swipe}} | {{~ms}}  |       |
+| Tutorial → Gameplay |                     |          |       |
+| Gameplay → End Card |                     |          |       |
+
+## Recommendation
+
+{{Which option and why — ties to Game Designer Emotional Arc}}
+
+## User Decision
+
+- **Selected option**: {{A/B/C}}
+- **User feedback**: {{adjustments}}
+- **Confirmed MC**: `assets/images/storyboard/master_composite_option_{{X}}.png`