@playcraft/cli 0.0.44 → 0.0.46

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

@@ -0,0 +1,198 @@
+# Layout Spec
+
+<!--
+  Game Designer owns paths + specs (ring 2 clarify lock). CONTRACT only — zones, palette ids, assetMapping, atlas table, WxH/format.
+  Do NOT add: storyboard prose, Style Intent Notes, TA logs (→ artist-log / ta-log).
+
+  **Slice-axis Ring 2**: layout **intent only** — Screen + Zones (+ optional palette ids).
+  Skip Asset Spec, Atlas grouping, Element Type Registry, Asset Mapping, and Text Assets until Ring 3+ or orchestrator discloses production lock.
+-->
+
+> Shared contract between Artist, 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}} | {{Artist/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 Artist'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 (ring 2 clarify — Game Designer 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.
+-->
+
+Single-element groups stay as single-file paths; do not invent atlases for one texture.
+
+---
+
+## Element Type Registry (ASR capacity budget)
+
+Group `assetMapping` elementIds by **visual type** before ring 2 layout-spec lock. Artist needs **one representative per type** on ASR or MC Panel 1; color variants are `ta-extends`.
+
+| typeId   | elementIds (variants)        | Notes                           |
+| -------- | ---------------------------- | ------------------------------- |
+| {{type}} | {{id_a}}, {{id_b}}, {{id_c}} | e.g. tile colors share one type |
+
+**Budget**: aim for **≤ 20 unique types** and **≤ ~24 ASR physical slots** (ui board ~12 + element board ~12). If types > 12, plan `element_state_sheet_[X]_2.png` or extra `mc-crop` + `ta-extends` rows.
+
+Artist Coverage Matrix **elementType** column should match `typeId` here.
+
+---
+
+## 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!
+- Artist 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 — Game Designer does NOT define):
+  assets/images/bg/   → opaque, full-screen background (TA verifies edge-to-edge)
+  assets/images/ui/   → needs alpha (TA chooses chroma / dual-bg-diff / rgb-alpha-split)
+  assets/images/txt/  → needs alpha (TA chooses chroma / rgb-alpha-split)
+  assets/images/vfx/  → needs alpha (TA chooses rgb-alpha-split / black-add / chroma)
+  assets/images/tiles/ → needs alpha by default (except card faces / board pieces)
+  assets/audio/       → N/A (not image)
+
+TA records alphaStrategy in logs/ta-log.md:
+  chroma          → hard-edge assets on green/blue/magenta flat background
+  dual-bg-diff    → two geometry-identical renders with different flat backgrounds
+  rgb-alpha-split → left RGB (Red Green Blue, 红绿蓝) + right Alpha grayscale matte
+  black-add       → black-backed VFX (Visual Effects, 视觉特效) played with ADD blend
+  opaque          → no alpha needed
+
+Video assets use videoAlphaStrategy:
+  chroma-video / dual-bg-video / rgb-alpha-video / opaque-video
+
+See skills/playable-art/references/alpha-postprocess.md.
+-->
+
+## 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.
+Artist 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}}` _(typical "0123456789" — frameCount = 10)_
+- **Cell size**: {{cell_w}}x{{cell_h}}
+- **Asset path**: `assets/images/txt/digits.webp` _(recommended: text-class lives under `images/txt/` per Transparency Classification)_
+- **Sidecar path (optional)**: `assets/images/txt/digits.json` _(only when laid out as multi-row grid; single-row strip can omit)_
+- **Layout**: single-row horizontal strip (default) — total width = `cell_w × frameCount`, height = `cell_h`
+- **Alpha**: required (channels = 4); TA uses `chroma` bluescreen or `rgb-alpha-split` (text typically gold/white — avoid green key)
+
+<!--
+Game Designer defines the character set based on what dynamic text the game needs.
+
+Common sets (always include digits 0–9 first, then any symbols):
+- Score only:         "0123456789"                 (frameCount = 10)
+- Score + timer:      "0123456789:."               (frameCount = 12)
+- Score + multiplier: "0123456789x+,."             (frameCount = 14)
+
+Path convention (TA Transparency Classification + Compliance Gate):
+- `assets/images/txt/digits.webp`   — preferred (text class → bluescreen, channels=4)
+- `assets/images/txt/digits_{{label}}.webp` — when multiple digit styles exist (score / countdown / level)
+- Legacy `assets/images/ui/digits.webp` works but TA must still classify it as text (bluescreen, not greenscreen).
+
+Layout (default single horizontal row):
+- Total width  = cell_w × frameCount
+- Total height = cell_h
+- Cell origin (0-based, row-major): x = index × cell_w, y = 0
+- Developer slices at runtime: char_x = index × cell_w
+
+Multi-row digit grid (rare — e.g. small + large digits in one sheet) MUST supply a `.json` sidecar
+describing each frame; Compliance Gate then checks dimensions against that sidecar.
+
+Compliance Gate (TA verifies before STOP):
+- frameCount = character count above
+- total width × height matches the layout (single-row or sidecar)
+- channels = 4 (alpha)
+- dark-bg verify: no chroma residue around digit edges
+-->

package/project-templates/phaser/templates/plan.template.md

@@ -0,0 +1,80 @@
+# Implementation Plan — {Game Name} (Slice Queue Explain View)
+
+<!--
+  NOT the daily dispatch axis — sliceState.slices[] + dispatchPacket drive execution.
+
+  This file is an optional human-readable explain view of the active slice queue:
+  - what each slice proves
+  - why slices are ordered this way
+  - which atoms/skills inform each slice (without mirroring the full atom graph)
+
+  Do:
+  - map sliceId → outcome → acceptance hints
+  - note engine/atom context that informed slice boundaries
+  - keep Ring 1 to 1–3 developer slices max
+  - Ring 2: 2–4 developer periphery slices (HUD / flow / tutorial hints — not full backlog)
+
+  Do not:
+  - replace sliceState or dispatchPacket
+  - dump file trees or TS interfaces
+  - compress the entire atom-tree into one Ring 1 mega-plan
+  - duplicate DESIGN.md or design-brief discovery prose
+-->
+
+**Slice queue source of truth**: `docs/project-state.json` → `sliceState` (via `npm run state:get -- --json dispatchPacket sliceState`)
+
+**Engine**: {engine or undecided}
+**Active slices (human summary)**: {list sliceIds in dispatch order}
+
+---
+
+## 1. Slice map (explain view)
+
+| sliceId                   | role      | doWhat (summary)               | verifier     | blockedBy / notes |
+| ------------------------- | --------- | ------------------------------ | ------------ | ----------------- |
+| {core-action-feedback-v1} | developer | {tap → feedback → progress +1} | verify:slice | first slice       |
+| {…}                       | developer | {…}                            | verify:slice | {optional}        |
+
+---
+
+## 2. Atom / skill context (not the full graph)
+
+> Full structured contract: `docs/atom-tree.json` (`meta.selectedAtoms`, `meta.skillsMatch`).
+> Ring 1 activated scope: `meta.activatedSlices[]` — do not expand to full product tree in one ring.
+
+| sliceId | Relevant atoms / skills        | Why it matters for this slice only |
+| ------- | ------------------------------ | ---------------------------------- |
+| {…}     | {engine atom / gameplay trunk} | {one line}                         |
+
+---
+
+## 3. Deferred to later rings
+
+- Layout / assetMapping → Ring 2+ (`layout-spec.md`)
+- Hook / CTA packaging → Ring 3+
+- Production assets → Ring 4
+- Full feature backlog → only after slice queue proves playable spine
+
+---
+
+## 4. Legacy feature sections (Ring 2+ only)
+
+<!--
+  Below sections apply when the project exits pure slice-axis Ring 1 seeding.
+  Do not fill Feature 详细清单 in Ring 1 — use slice map above instead.
+-->
+
+### Feature: {name — Ring 2+}
+
+- **Outcome**: {player-visible result}
+- **Depends On**: {sliceId or feature}
+- **Acceptance**: {2–4 verifiable checks}
+
+---
+
+## 5. Self-check
+
+- [ ] Slice map matches `sliceState.slices[]` ordering and roles
+- [ ] Ring 1 does not contain layout/style/CTA production plan
+- [ ] Atom-tree is referenced, not copied wholesale into this file
+- [ ] No TS interface / pseudo-code / file tree dump

package/project-templates/phaser/templates/project-state.template.md

@@ -0,0 +1,136 @@
+# Project State
+
+> **Agent entry**: run `npm run state:get` first. Use its summary (`iteration`, `loop`, `nextCommands`, required/deferred files). Do **not** read this entire file during Ring 1 — the handoff YAML block below is the machine source of truth.
+
+## Workflow spec
+
+| Field                   | Value                                                                 |
+| ----------------------- | --------------------------------------------------------------------- |
+| **templateVersion**     | `0.3.2-alpha.0`                                                       |
+| **workflowSpecVersion** | `growth-rings-v1`                                                     |
+| **Template Changelog**  | [CHANGELOG.md](../CHANGELOG.md)                                       |
+| **Workflow Changelog**  | [docs/team/workflow-changelog.md](../docs/team/workflow-changelog.md) |
+
+## Ring Gate Scope
+
+| Field            | Value                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| ringGatePolicy   | `ring gate checks objective DoD verifiers + non-regression of prior rings + user-decision readiness only` |
+| ringGateExcludes | `subjective quality judgment, gameplay fun, final visual taste, user preference choice`                   |
+
+## Settings
+
+| Field                  | Value   | Description                                                                                  |
+| ---------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| **designerAutoDecide** | `false` | When `true`, Game Designer may self-decide simple/obvious questions without asking the user. |
+
+<!--
+  designerAutoDecide:
+    false (default) = Designer asks the user every brainstorm question via AskUserQuestion.
+    true            = Designer may auto-decide questions that have an obvious best answer based on
+                      genre convention, research, or hard constraints. Auto-decisions are logged in
+                      design-brief.md as [AGENT-AUTO] with reasoning. The user can override any
+                      auto-decision in subsequent rounds.
+
+  Only affects brainstorm questions. Ring Gate confirmations remain orchestrator-only regardless.
+-->
+
+<!--
+  growth-rings-v1: Four growth rings climb the atom-tree from engine root upward.
+  Each ring runs clarify → build → verify inner loops with full role collaboration.
+  Objective DoD verifiers replace pre-development document packages.
+-->
+
+## User Intent
+
+> {{user_intent — ≤2 sentences; do NOT restate Style Direction or five-axis tables from design-brief}}
+
+## Current Iteration
+
+> **Human-readable view.** The machine source of truth is the `## Agent handoff` YAML block below (`iteration:` + `loop:` + `ringGate:` + `ringDoD:`). `workflow-doctor` and agents read that block; keep this prose in sync for humans.
+
+**Iteration {{current_iteration}}** — {{iteration_description}}
+
+`1 (engine-root → core gameplay)` → `2 (gameplay + periphery)` → `3 (playable ad hook/CTA)` → `4 (production + architecture)` → `done`
+
+Each iteration runs inner loops: `clarify` → `build` → `verify` → **Ring Gate** (user acceptance) → next iteration.
+
+<!-- Iteration definitions: see CLAUDE.md § Growth-Ring Model -->
+
+## Ring DoD (current iteration)
+
+> Objective Definition-of-Done for the **current** growth ring. Orchestrator runs `npm run ring:gate -- --iteration N` to update verifier status.
+> **Human-readable view.** Machine source of truth is `ringDoD:` in the `## Agent handoff` YAML block.
+
+| Check         | Status             | Verifier                      | Notes                                                                                                           |
+| ------------- | ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| contract      | {{passed/pending}} | `npm run verify:contract`     | Engine boots; neutral runtime contract wired (`window.__playable`)                                              |
+| lifecycle     | {{passed/pending}} | `npm run verify:lifecycle`    | Ring 1: starts at HOOK and autoPlay reaches ENDCARD without MP4                                                 |
+| firstLevelWin | {{passed/pending}} | `npm run verify:firstwin`     | Ring 1: headless autoPlay reaches ENDCARD (first level winnable)                                                |
+| placeholders  | {{passed/pending}} | `npm run verify:placeholders` | Ring 1+: every `load.*` path exists on disk + `assets/images/` non-empty (placeholder-first, no pure code-draw) |
+
+> Future-ring DoD checks are hidden at Ring 1. Run `npm run state:get` after each loop/ring transition to see the active verifier set.
+
+## Ring Gate
+
+> Only the **orchestrator** runs `AskUserQuestion` toward the user. Sub-agents set `ringGate: pending` and STOP.
+> One Ring Gate per iteration replaces the old six waterfall gates.
+
+| Field      | Value              | Notes                                                                       |
+| ---------- | ------------------ | --------------------------------------------------------------------------- |
+| ringGate   | {{passed/pending}} | Orchestrator confirms after all ring DoD checks pass + user plays at devUrl |
+| iteration  | {{1..4}}           | Current growth ring                                                         |
+| canAskUser | {{yes/no}}         | Set by `ring:gate` runner — only `yes` when all DoD checks pass             |
+
+## Agent handoff
+
+> Sub-agents and orchestrator **must** read/write this block before STOP or invoke. See `docs/team/collaboration.md` § Agent Handoff.
+> This block is the **single machine-readable source of truth** for `iteration`, `loop`, `ringGate`, and `ringDoD`.
+
+```yaml
+iteration: 1
+ringGoal: engine-root + core gameplay (placeholder art)
+loop: clarify
+subagent: none
+subagent_stop: false
+waiting_for: orchestrator
+ringGate: pending
+ringDoD: { contract: pending, lifecycle: pending, firstLevelWin: pending, placeholders: pending }
+archivedRings: {}
+next_orchestrator_action: null
+last_completed_by: null
+block_reason: null
+```
+
+## Handoff Context
+
+> Structured shared working memory. Machine source of truth is `handoffContext` in `docs/project-state.json`; agents read it through `npm run state:get -- --json contextPacket`.
+
+| Area                        | Value                                                  |
+| --------------------------- | ------------------------------------------------------ |
+| ring.summary                | Ring 1 starts as a semantic placeholder playable demo. |
+| lastRole.role               | none                                                   |
+| lastRole.summary            | No sub-agent has completed work yet.                   |
+| nextRole.role               | orchestrator                                           |
+| nextRole.mustKnow           | Run state:get and follow currentAction / nextCommands. |
+| shared.engine               | unset                                                  |
+| shared.coreAction           | unset                                                  |
+| shared.semanticPlaceholders | none                                                   |
+| openQuestions               | none                                                   |
+
+> Handoff examples: see [collaboration.md](../docs/team/collaboration.md#agent-handoff) and use `npm run state:set` to update keys. Ring 1 clarify routes Game Designer → temporary ref-flow atom selection → scaffold gate → Developer.
+
+<!--
+  Deferred human tables (Ring Gate Runner, Archived Rings, Dev Preview, Progress Checkpoint, …)
+  are updated by npm run state:set / ring:gate. Full field reference: docs/team/collaboration.md
+-->
+
+## File Index (current ring)
+
+| File                                      | Description                                             | Status     |
+| ----------------------------------------- | ------------------------------------------------------- | ---------- |
+| [DESIGN.md](docs/DESIGN.md)               | Player experience contract: core loop + first-level win | {{status}} |
+| [developer-log.md](logs/developer-log.md) | Developer work log + devUrl                             | {{status}} |
+| `game/`                                   | Runtime implementation                                  | {{status}} |
+
+> Hidden until later Rings: `docs/design-brief.md`, `docs/layout-spec.md`, `docs/implementation-plan.md`, `docs/style-exploration.md`, `logs/artist-log.md`, `logs/ta-log.md`, `logs/review-report.md`, production pipeline.