@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/agents/refs/designer-style-exploration-flow.md

@@ -0,0 +1,37 @@
+# Designer — Style exploration flow (Phase 1, steps 2–5)
+
+> **Scope**: After **Step 1 — Skill Discovery** in `agents/designer.md`, follow this document for MC generation through Gate #2b STOP. **Exit criteria** for Phase 1: see `agents/designer.md` Goals § Success criteria.
+>
+> **Deliverable shapes & tables**: `refs/designer-deliverable-spec.md`.
+
+**Trigger**: `project-state.md` stage = `style_exploration`
+
+## Step 2 — Generate Master Composite only (one image per option A/B[/C])
+
+- Follow `playcraft-storyboard` skill：**每格完整 9:16 H5**；`45:16` + `--width 3600 --height 1280`（2K）或 `4096×1455`（4K）；**禁止 `1:1` / `10:3`**
+- 每个方案用不同模型（见 `refs/designer-master-composite-recipes.md`）
+- 生成后立即 `playcraft image info`：总比例 **width/height ≈ 2.81**，**(width÷5)/height ≈ 0.5625**；不合格则重生成
+- **Review the auto-generated `.json` sidecar** — 确认 `aspectRatio` / `imageSize` / 实际像素正确
+
+## Step 3 — Gate #2a package（MC 选型材料）
+
+1. 写入 `docs/style-exploration.md` 的 **Master Composite 部分**（每套方案的路径、风格关键词、体验流文字说明；**此时不写 ASR 路径**）
+2. 更新 handoff + `gates.#2a = pending`（见 `agents/designer.md` **Runtime**）
+3. **STOP** — 禁止 ASR（资产状态参考精灵图板）
+
+## Step 4 — Generate ASR sheets（仅针对 `project-state.selectedMcOption`）
+
+- Read `selectedMcOption` from `docs/project-state.md` — if missing, **STOP**
+- Follow `playcraft-asset-state-sheet` skill
+- 输出两张 4K 板：`ui_state_sheet_[X].png` + `element_state_sheet_[X].png`（见 `designer-deliverable-spec.md` §2）
+- `--reference-image` = `master_composite_option_[selectedMcOption].png`
+- 生成后 `playcraft image info` 检查；若槽位重叠，必须重生成
+
+## Step 5 — Gate #2b Handoff Pack
+
+> **Checklist**: `refs/designer-handoff-v2-checklist.md`
+
+1. 补全 `docs/style-exploration.md`（ASR 路径、**Motion Notes**、Experience Flow）
+2. 更新 `logs/designer-log.md`：**ASR Coverage Matrix**（100% contract rows）、**Palette Locked**、Style Intent / Anti-Pattern
+3. 更新 handoff + `gates.#2b = pending`
+4. **STOP** — 禁止 Phase 2 音频与批量视觉样本 PNG

package/project-template/.claude/agents/refs/developer-dev-handoff.md

@@ -0,0 +1,109 @@
+# Developer Dev Handoff (L2)
+
+Use during **Phase 2 integration** and before marking `devStatus: ready`.
+
+## Dev command
+
+```bash
+cat package.json   # read scripts.dev (webpack / vite / etc.)
+npm run dev
+```
+
+- **Not** `playcraft start` — Dev is the project's `scripts.dev`.
+- Record the URL from terminal output (e.g. `http://localhost:5173`) in `project-state.md` → `devUrl`.
+- Prefer leaving the server running for Reviewer; if it stops, Reviewer or orchestrator may restart and refresh `devUrl`.
+
+## Dev iteration rhythm
+
+During integration, repeat:
+
+1. Change code / wire assets
+2. `npm run dev` (restart if HMR is insufficient)
+3. Self-check UI + gameplay + runtime (checklists below)
+4. Log in `developer-log.md` → **Dev self-check**
+5. If upstream issue → blockers + ICP + STOP (orchestrator routes TA/Designer)
+
+**Do not** wait until the last minute for a single Dev pass.
+
+## UI checklist (vs MC + layout-spec)
+
+| Check                                              | Source                                  |
+| -------------------------------------------------- | --------------------------------------- |
+| Zones and hierarchy match layout-spec              | `docs/layout-spec.md`                   |
+| Colors / mood match approved style                 | `docs/style-exploration.md`, Gate #2 MC |
+| Element placement matches storyboard Visual Intent | Master Composite frames                 |
+| Text-as-image assets visible, correct aspect       | `assetMapping` paths                    |
+| No broken images / wrong sprites / style drift     | Dev browser                             |
+| Mobile viewport (e.g. 750×1334) acceptable         | Dev browser resize                      |
+
+## Gameplay checklist (vs design-brief + PGS)
+
+| Check                                      | Source                 |
+| ------------------------------------------ | ---------------------- |
+| Hook → Tutorial → Gameplay → End Card flow | `docs/design-brief.md` |
+| Rules, scoring, win/lose match PM contract | design-brief + PGS     |
+| **First level guaranteed success**         | atom-plan / PGS        |
+| Near-Win and difficulty feel as specified  | design-brief           |
+| CTA on End Card                            | runtime test           |
+
+## Runtime checklist
+
+- No white screen or blocking console errors
+- Full playthrough without dead ends
+- BGM/SFX at correct events
+- State machine stable; CTA handler fires (`mraid` / `FbPlayableAd` / `ExitApi` as applicable)
+
+## devUrl recording
+
+In `docs/project-state.md` → **Dev Preview**:
+
+| Field            | When                                                 |
+| ---------------- | ---------------------------------------------------- |
+| `devUrl`         | After `npm run dev` shows listening URL              |
+| `devStatus`      | `pending` → `ready` or `blocked_upstream` / `failed` |
+| `devStartedBy`   | `developer`                                          |
+| `devLastChecked` | ISO timestamp after each meaningful Dev pass         |
+
+Also note devUrl in `docs/developer-log.md` → **Dev self-check**.
+
+## Upstream blocker template
+
+Add to `developer-log.md` → **## Upstream blockers**:
+
+```markdown
+| Path              | Issue   | Expected                           | routeTo | Status |
+| ----------------- | ------- | ---------------------------------- | ------- | ------ |
+| assets/ui/foo.png | missing | 256×256 PNG per layout-spec zone A | TA      | open   |
+```
+
+In `docs/intent-clarifications.md`:
+
+- **Context**: what Dev showed (screenshot description or path)
+- **Gap**: vs MC / contract / design-brief
+- **Acceptance**: exact path, dimensions, style, or audio mood required
+- **routeTo**: TA | Designer | PM
+
+Set `project-state.md`:
+
+- `devStatus: blocked_upstream`
+- `devBlockers`: same rows as log
+
+**STOP** after filing — wait for orchestrator to re-invoke upstream role, then **re-run Dev loop**.
+
+## After rework — re-verify checklist
+
+1. Confirm blocker paths exist on disk (`ls`, `playcraft image info` if needed)
+2. `npm run dev`
+3. Re-run UI + gameplay + runtime checklists for affected areas
+4. Close blocker rows (`status: resolved`) or escalate if still wrong
+5. Only then set `devStatus: ready` and stage → `review`
+
+## Dev ready checklist (`devStatus: ready` — all required)
+
+- [ ] UI checklist pass in Dev
+- [ ] Gameplay checklist pass in Dev
+- [ ] Runtime checklist pass in Dev
+- [ ] No open rows in Upstream blockers / `devBlockers`
+- [ ] `devUrl` recorded and server reachable
+- [ ] `developer-log.md` Dev self-check complete
+- [ ] **Not** required: `playcraft build`, user running terminal commands

package/project-template/.claude/agents/refs/developer-impl-cookbook.md

@@ -0,0 +1,134 @@
+# Developer Implementation Cookbook
+
+> Read before writing index.html (Phase 1 Step 4) and during Phase 2 asset integration. Contains index.html skeleton, CTA handler patterns, and integration binding checklist.
+
+## Atlas binding (Phase 1 + Phase 2)
+
+When `layout-spec` (or atom-plan handoff) defines **`atlasPath` + `frameId`** for an element or tile set, treat it as the source of truth for sprite geometry — **not** ad-hoc single-file crops.
+
+- **Load the atlas image** as **WebP** at the path given by `atlasPath` (or the paired TA-delivered file beside the JSON).
+- **Load the frame map** from the **JSON sidecar** shipped with the atlas (frame rectangles / pivots / names keyed by `frameId`).
+- **Phase 1**: stub or procedural placeholders are acceptable only where the contract is path + id; still wire code to read `atlasPath` / `frameId` so Phase 2 is a file drop-in.
+- **Phase 2**: verify WebP + JSON exist at the contract paths, then bind textures using `frameId` → sub-rect from the sidecar (same pattern in Integration checklist below).
+
+---
+
+## index.html Skeleton (Phase 1)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
+    <title>Playable Ad</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+      canvas {
+        display: block;
+        width: 100%;
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <canvas id="game"></canvas>
+    <script>
+      // Game initialization — asset loading will be added in Phase 2
+      // Gameplay logic from game/gameplay/
+      // Config from game/config/
+
+      // CTA handler (required — multi-platform fallback)
+      function onCTAClick() {
+        if (typeof mraid !== "undefined") {
+          mraid.open("{{store_url}}");
+        } else if (typeof FbPlayableAd !== "undefined") {
+          FbPlayableAd.onCTAClick();
+        } else if (typeof ExitApi !== "undefined") {
+          ExitApi.exit();
+        } else {
+          window.open("{{store_url}}");
+        }
+      }
+    </script>
+  </body>
+</html>
+```
+
+**Phase 2 additions**: add asset loading (inline base64 or relative paths), connect gameplay logic, wire audio triggers, ensure ALL resources are inline (zero external requests).
+
+---
+
+## Phase 2: Asset Integration Binding Checklist
+
+Connect Designer's assets to gameplay code:
+
+| Check                                                                | Source                 |
+| -------------------------------------------------------------------- | ---------------------- |
+| Every `tileColors[].id` has image file at `assetMapping.visualAsset` | layout-spec + `ls`     |
+| Board position = `zones["board"].rect`                               | layout-spec            |
+| Tile size = `assetSpec.tileSize`                                     | layout-spec            |
+| All sfx files exist per `assetMapping`                               | layout-spec + `ls`     |
+| Background at correct path                                           | layout-spec + `ls`     |
+| Sprite sheet atlas bound with JSON frame data                        | atom-plan + TA handoff |
+
+**Binding pattern**:
+
+1. Load images at paths from `assetMapping`; for atlas-backed assets, load **WebP atlas + JSON sidecar** and resolve **`frameId`** from `layout-spec` (see § Atlas binding).
+2. Bind visuals to game entities: element ID → texture (or atlas sub-rect)
+3. Bind audio to gameplay events: match → sfx, level complete → success sfx
+4. Position elements per `zones[].rect` coordinates
+
+---
+
+## Phase 2: Dev iteration (integration complete)
+
+| Requirement                          | How to Verify                                                 |
+| ------------------------------------ | ------------------------------------------------------------- |
+| Entry point: `game/index.html`       | `ls game/index.html`                                          |
+| All asset references: relative paths | Read game code                                                |
+| No Node.js APIs                      | Code review                                                   |
+| No dynamic imports or CDN references | `grep -r "import(" game/`                                     |
+| Zero external requests in Dev        | Browser console + `grep -r "http" game/`                      |
+| UI + gameplay + runtime in Dev       | `npm run dev` + checklists in `refs/developer-dev-handoff.md` |
+| No open upstream blockers            | `developer-log.md` + `project-state.devBlockers`              |
+
+```bash
+npm run dev
+# Record devUrl in project-state.md; leave server running for Reviewer when possible
+```
+
+> **`playcraft build` is not required** for `devStatus: ready` or project `done`. See `refs/developer-dev-handoff.md` for Dev ready checklist.
+
+---
+
+## PGS Implementation Pattern
+
+```
+1. Load reference: playcraft skills match --engine <engine> --intent "<gameplay>" --json
+2. Write PGS JSON:
+   - entities[] — from layout-spec colorPalette.tileColors[].id
+   - rules[] — from design-brief experience flow
+   - algorithm{} — matching/gravity/refill logic
+   - testCases[] — write FIRST, then implement rules
+3. Validate logic passes all testCases
+```
+
+Key constraints (all from layout-spec, NOT invented):
+
+- Grid dimensions = `zones["board"].rect` / `assetSpec.tileSize`
+- Element types = `colorPalette.tileColors[]`
+- Element IDs = `colorPalette.tileColors[].id`

package/project-template/.claude/agents/refs/developer-phase1-flow.md

@@ -0,0 +1,136 @@
+# Developer Flow — ui_pass + gameplay_pass (L2)
+
+> **Trigger**: `docs/project-state.md` stage = `ui_pass`, `ui_rework`, or `gameplay_pass`.
+> Agent context + STOP rules: [`../developer.md`](../developer.md).
+
+---
+
+# Part A: ui_pass (UI shell only)
+
+> **Goal:** Runnable UI matching MC — scene switching, asset binding, simple states. **No core gameplay rules.**
+
+## Step 0: Upstream Intake (mandatory)
+
+Read each file; fill **`logs/developer-log.md` § Upstream Intake** before any `game/` edit.
+
+| Doc                 | You need from it                                   |
+| ------------------- | -------------------------------------------------- |
+| `project-state`     | Wave 2 done, stage `ui_pass`, dev fields           |
+| `design-brief`      | Experience flow scene names (for navigation only)  |
+| `layout-spec`       | Zones, elementIds, assetMapping, atlasPath/frameId |
+| `atom-plan.json`    | Developer atoms, skillRef, dependsOn               |
+| `atom-plan.md`      | Acceptance + Impl Context                          |
+| `style-exploration` | MC panels — primary UI reference                   |
+| `designer-log`      | Palette / motion notes                             |
+| `ta-log`            | Compliance / atlas params                          |
+
+## Step 1: Spec Quick-Check (30s)
+
+- Every referenced `elementId` exists in `assetMapping`
+- Gaps → `spec-gap` in project-state → wait for PM
+
+## Step 2: Experience Flow → Code Mapping
+
+Write to `developer-log.md` — map MC panels to scenes (Hook / Tutorial / EndCard / CTA). See template.
+
+## Step 3: Skill Preflight + Scaffold
+
+Per `atom-plan.json` Developer `skillRef` entries — read `.claude/skills/<skillRef>/` or CLI fallback; run `playcraft skills scaffold --out ./game` once.
+
+Fill **`§ Skill Preflight`** in developer-log.
+
+## Step 3b: UI Pass Plan (mandatory before `game/` edits)
+
+Write **`logs/developer-log.md` § UI Pass Plan**:
+
+1. **Architecture** — engine, entry, scene flow
+2. **Scene-Asset Binding Plan** — verify every path with `ls`
+3. **Scene navigation** — how Reviewer reaches each MC panel (URL param or button)
+4. **Risk Checklist** — all `[x]`
+
+**Forbidden in ui_pass:** PGS rules, scoring, elimination, win/lose, Near-Win logic.
+
+Hook validates § UI Pass Plan on STOP.
+
+## Step 4: Implement UI shell
+
+- Bind **real** assets at contract paths (WebP atlas + JSON sidecar)
+- Implement scenes + `index.html` skeleton (see [`developer-impl-cookbook.md`](./developer-impl-cookbook.md))
+- Scene switching only — static/simple interactive states OK
+- Text-as-image per `playcraft-text-rendering` skill
+
+## Step 5: Dev self-check (ui_pass)
+
+```bash
+npm run dev
+```
+
+- All MC-reachable scenes render with real assets
+- No white screen; layout matches zones
+- Record devUrl in developer-log
+
+## Step 6: ui_pass STOP
+
+- `devStatus: ui_ready` (not `ready`)
+- handoff: `Invoke @reviewer ui_diff`
+- **Do not** set mainline `stage`
+
+---
+
+# Part B: ui_rework
+
+1. Read `logs/review-report.md` UI Diff section
+2. Fix only Action Items with `routeTo: Developer`
+3. Re-run `npm run dev` → `devStatus: ui_ready` → handoff `Invoke @reviewer ui_diff`
+
+If `routeTo: ta` or `designer` — STOP; orchestrator invokes them first.
+
+---
+
+# Part C: gameplay_pass (core gameplay)
+
+> **Prerequisites:** `uiReviewStatus: passed` (or max ui rework rounds). **Do not rewrite UI layout.**
+
+## Step 0: Read UI baseline
+
+- Confirm `devStatus` was `ui_ready` / UI diff passed
+- Read existing `game/` scenes — extend, do not replace layout
+
+## Step 1: Gameplay Pass Plan (mandatory)
+
+Write **`logs/developer-log.md` § Gameplay Pass Plan**:
+
+1. **PGS Strategy** — rules from design-brief + Skill recipe
+2. **First level guarantee** — how tutorial/config ensures win
+3. **State machine** — Hook → Tutorial → Gameplay → EndCard transitions with logic
+4. **Risk Checklist** — all `[x]`
+
+Hook validates § Gameplay Pass Plan on STOP.
+
+## Step 2: Implement GameplayAtom + ConfigAtom
+
+- Write testCases FIRST
+- Core rules, scoring, Near-Win, CTA handler
+- First level MUST guarantee player success
+
+## Step 3: Dev self-check (gameplay_pass)
+
+```bash
+npm run dev
+```
+
+- Gameplay loop works; CTA fires; audio loads
+- Record devUrl
+
+## Step 4: gameplay_pass STOP
+
+- `devStatus: ready`
+- handoff: `Invoke @reviewer load_check`
+- **Do not** set Gate #3 or `stage: done`
+
+---
+
+## Shared references
+
+- PGS patterns, CTA, atlas binding: [`developer-impl-cookbook.md`](./developer-impl-cookbook.md)
+- Dev ready gate details: [`developer-dev-handoff.md`](./developer-dev-handoff.md)