@playcraft/cli 0.0.39 → 0.0.41

package/project-template/.claude/agents/refs/pm-workflow-detail.md

@@ -0,0 +1,545 @@
+# PM Workflow Detail
+
+> Read before executing Steps 1-8. Contains the full step-by-step analysis flow, interaction mode selection, five-axis framework application, Style Direction specification, scheduling metadata guide, and Pre-Write Validation Checklist.
+
+---
+
+## Step 1: Intent Assessment — 9 Dimensions
+
+Read the user's prompt and internally assess all 9 dimensions:
+
+| Dimension               | Example Signals                                                        | Critical? |
+| ----------------------- | ---------------------------------------------------------------------- | --------- |
+| **Gameplay type**       | "match-3", "puzzle", "parkour"                                         | Yes       |
+| **Visual style**        | "cartoon", "realistic", "pixel art", "flat design"                     | Yes       |
+| **Element theme**       | "fruits", "gems", "candy", "animals"                                   | Yes       |
+| **Color mood**          | "warm", "cold", "vibrant", "pastel", "dark"                            | Medium    |
+| **Target product**      | "casual puzzle game", "RPG", "e-commerce"                              | Medium    |
+| **Target platform**     | "Facebook", "TikTok", "Unity Ads"                                      | Medium    |
+| **Target audience**     | "casual gamers", "women 25-45", "kids"                                 | Low       |
+| **Reference/benchmark** | "like Royal Match", "similar to Candy Crush"                           | Bonus     |
+| **User Motivation Job** | stress-relief / challenge / collection / creativity / immersion (JTBD) | Medium    |
+
+**User Motivation Job inference**: explicit signal words → classify directly; game genre implies strongly (strategy RPG → challenge); no signal → default to stress-relief (broadest audience).
+
+---
+
+## Step 2: Interaction Mode Selection
+
+### Advisor Mode (Default)
+
+**Core principle**: Complete internal analysis first, then write **Gate #1 option packages** for the orchestrator (see **Interaction Modes** § below). User selects via orchestrator `AskUserQuestion` — **not** by PM sub-agent.
+
+```
+IF information is sufficient (gameplay + style + theme are clear):
+  → Write 1 recommended full package in checkpoint for orchestrator Gate #1
+
+ELIF some dimension is ambiguous (e.g., style unclear):
+  → Complete internal judgment on other dimensions
+  → Document 2-3 options per ambiguous dimension in Gate #1 package
+
+ELIF information is minimal (e.g., "make a playable ad" or only "麻将对对碰"):
+  → Complete five-axis analysis, generate 2-3 complete directions
+  → Document Option A / B / C in Gate #1 package (each covers all five axes + risk/tutorial/audience)
+```
+
+**NEVER**: ask the user directly (no `AskUserQuestion` on PM), open-ended chat questions, skip `gates.#1 = pending` STOP.
+
+**ALWAYS**: 2-4 labeled options in checkpoint; mark recommendation; STOP after four docs + `gates.#1 = pending`; decide professionally only for **uncared** dimensions.
+
+### Direct Intent Mode
+
+Triggered only when **≥ 3 axes** are explicitly locked (naming a genre alone does not count):
+
+| Trigger                                                | Behavior                                                                                            |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Specified gameplay type only ("麻将对对碰", "match-3") | Mechanic locked → **stay in Advisor Mode** for other axes                                           |
+| Specified visual style ("cyberpunk", "pixel art")      | Style axis locked                                                                                   |
+| Specified emotion/experience ("urgency", "relaxing")   | Emotional arc axis locked                                                                           |
+| ≥ 3 axes clearly specified                             | Skip multi-round option picking; **one** recommended package in Gate #1 checkpoint for orchestrator |
+
+**Threshold**: ≥ 3 axes with clear directives → Direct Intent Mode. Otherwise → Advisor Mode.
+
+---
+
+## Step 3: Classify Dimensions
+
+For each dimension:
+
+- **cared**: User explicitly mentioned or strongly implied
+- **uncared**: User didn't mention — you decide with professional judgment
+- **locked**: User explicitly specified, cannot change
+
+---
+
+## Step 4: Five-Axis Internal Evaluation + Option Generation
+
+> **Before this step**: read `templates/design-methodology.md` and `templates/five-axis-framework.md` for the full classification tables and decision rules.
+
+### Five-Axis Framework
+
+| Axis              | Decision Range                                            | Downstream Impact                 | 30s Ad Default           |
+| ----------------- | --------------------------------------------------------- | --------------------------------- | ------------------------ |
+| **Mechanic**      | Single / Type A / B1 / B2 / C / D                         | Developer DAG structure           | Single or Type B1        |
+| **Dimension**     | Flat 2D / 2.5D Visual / Isometric / True 3D               | TA pipeline complexity            | Flat 2D                  |
+| **Interaction**   | Tap / Tap+Swipe / Drag / Tap+Hold / Multi-touch           | Tutorial time budget              | Tap Only                 |
+| **Narrative**     | L0-L3                                                     | Designer/TA character asset needs | L1                       |
+| **Emotional Arc** | Competence / Challenge / Curiosity / Relaxation / Urgency | Hook strategy                     | Competence or Relaxation |
+
+Run the five-axis analysis internally (mechanic → dimension → interaction → narrative → emotional arc), then generate 2-3 complete options per the rules in `five-axis-framework.md`.
+
+**Option format** — each option covers all 5 axes:
+
+```
+Option A (recommended): Mechanic=... + Dimension=... + Interaction=... + Narrative=... + Arc=...
+  → Risk: Low | Tutorial: ~Xs | PGS coverage: yes/no
+Option B: ...
+Option C: ...
+```
+
+Document options in Progress Checkpoint for orchestrator Gate #1. Write four files reflecting recommended option; set `gates.#1 = pending` → STOP.
+
+---
+
+## Step 5: Style Direction — Critical Output
+
+**This is your most important creative contribution.** Don't just write "tropical cartoon" — write a Style Direction that a Designer can actually execute.
+
+When unfamiliar with a style, research first:
+
+```bash
+playcraft tools research --query "<style> mobile game art style characteristics" --focus visual --json
+playcraft tools search-image --query "<style keywords> game screenshot" --json
+```
+
+Style Direction must include these **explicit fields** (not implicit in Art Style):
+
+1. **Dimension**: Flat 2D / 2.5D Visual / Isometric / True 3D — with rationale and downstream impact
+2. **Interaction Modality**: Tap Only / Tap+Swipe / Drag / Tap+Hold — with tutorial time and audience width
+3. **Emotional Arc**: Competence / Challenge / Curiosity / Relaxation / Urgency — how it threads through all 4 stages
+4. **Emotional Arc Intent Table**: per-stage emotional beat + visual signal + audio signal
+
+Plus the established 6 elements:
+
+| Element          | Bad Example     | Good Example                                                                                                                                                                                                     |
+| ---------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Art style        | "cartoon"       | "2D flat illustration with soft shadows, rounded corners on all elements, slight 3D depth via subtle gradients — similar to Candy Crush Saga's tile style but less glossy"                                       |
+| Color strategy   | "bright colors" | "High saturation (70-90%) warm palette. Background uses deep greens (#1A6B3C → #0D4D2B gradient). Elements use pure primaries with white highlight on upper-left. UI accent in gold (#FFD700) for premium feel." |
+| Visual hierarchy | (missing)       | "Board is the visual focus (occupies 47% of screen). Background is atmospheric but low-contrast to not compete. HUD is minimal — just score + progress, white on semi-transparent dark."                         |
+| Element design   | "fruit icons"   | "Fruits rendered as cute characters with tiny faces (2 dot eyes + small smile). Each fruit has its signature color as 80% of area with white specular highlight. Consistent 8px rounded corners."                |
+| Mood/feeling     | "fun"           | "Cheerful and rewarding. Every interaction should feel juicy — elements should look like they want to be tapped. Overall vibe: relaxing tropical vacation, not stressful competition."                           |
+| References       | (none)          | "Visual reference: Tropicats, Royal Match board style. NOT like: Bejeweled (too glossy/3D), Tetris (too geometric)"                                                                                              |
+
+---
+
+## Step 6: Layout Spec Design
+
+Design the shared contract between Designer, TA, and Developer:
+
+1. **Space division** — screen zones with exact positions
+2. **Color definition** — element colors, UI, background
+3. **Asset specifications** — size, format, naming for each type
+4. **Asset mapping** — element ID → file path (the integration bridge)
+
+**Critical**: `assetMapping` paths are **locked after Gate #1**. No agent may unilaterally change paths — this is the Asset Contract: TA fills paths in production Wave 2; Developer binds **real files** in `integration` after TA Compliance green.
+
+---
+
+## Atlas grouping at Gate #1
+
+**Before** `gates.#1 = passed`, the PM **MUST** define atlas groups in `layout-spec.md` so TA/Developer share one contract for packed sheets (not a pile of lone PNGs).
+
+| Domain    | Grouping rule                                                                               | Contract                                                                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Tiles** | Elements that belong on the same board/grid layer (e.g. all match tiles, all mahjong faces) | If **≥ 2** raster elements share a group → **one** atlas: **`.webp` + sidecar `.json`** (frame layout / pivots) under a single path pair in `assetMapping` |
+| **UI**    | HUD, buttons, icons that ship together                                                      | Same: **≥ 2** elements → one **webp + json** atlas path                                                                                                    |
+| **VFX**   | Sprite sequences / particles authored as sheets                                             | Same: **≥ 2** frames or elements in one effect family → one **webp + json** atlas path                                                                     |
+
+**Defaults**: image atlas **format = WebP** (`*.webp`); standalone single assets may still use `*.webp` or `*.png` only if the spec states why. **Audio** contract: deliver **MP3** (`*.mp3`) for BGM/SFX in `assetMapping` unless a template explicitly requires another container.
+
+Single-element groups stay as single-file paths; do not invent atlases for one texture.
+
+---
+
+## Step 7: Experience Flow Design
+
+Design each stage with four fields — from "what happens" to "what the player feels" (MDA player perspective):
+
+**Hook (0-3s)**
+
+- **Narrative Task**: What cognitive gap to open? (make the user wonder what happens next)
+- **Emotion Target**: What should the user feel at second 3? (curiosity / mild anxiety / surprise)
+- **Mechanic Expression**: What specific visual/action triggers the emotion?
+- **Trigger Type**: Near-Win / Failure Display / Success Demo / Unexpected Conflict / Reward Reveal
+
+**Tutorial (3-10s)**
+
+- **Narrative Task**: Build "I learned it" mastery feeling; set expectation for upcoming challenge
+- **Emotion Target**: Low-pressure control (flow theory: zero-skill users must start in the flow zone)
+- **Mechanic Expression**: How to guide first interaction? gesture animation / character demo / highlight
+- **Success Guarantee**: ✅ First interaction must succeed at 100%
+
+**Gameplay (10-25s)**
+
+- **Narrative Task**: Push toward emotional peak; make user feel "I'm about to win"
+- **Emotion Target**: Flow (3-5 operations) → Near-Win trigger → emotional peak
+- **Near-Win Design**: Which step triggers it, what scenario, how long to sustain, must have a solution
+- **Mechanic Expression**: Core loop, levels, difficulty curve
+
+**End Card (25-30s)**
+
+- **Narrative Task**: Do NOT close the gap — create "the story isn't over" sequel feeling
+- **Emotion Target**: Satisfaction + incompleteness (curiosity gap closure happens post-install)
+- **CTA Emotion Logic**: Sequel feeling / reward inheritance / more challenges, NOT "download." "Continue playing" > "Download now"
+
+---
+
+## Step 8: Atom Plan — JSON 主文件 + Markdown 富集
+
+**Order is strict:** `atom-plan.json`（skillsMatch + atoms）→ `validate-atom-plan` → optional `atom-plan.md` 镜像 → `link`.
+
+### 8a. 初始化 JSON
+
+```bash
+cp templates/atom-plan.template.json docs/atom-plan.json
+cp templates/atom-plan.template.md docs/atom-plan.md
+```
+
+### 8b. Run skills match → `skillsMatch`
+
+```bash
+playcraft skills match --intent "<gameplayType>,<mechanic>,<keywords>" --json
+# 可选：playcraft skills list --category config --json
+```
+
+- 推荐省略 `--engine`（CLI 按 intent 自动选 phaser/threejs）；若已定引擎则显式 `--engine <threejs|phaser>`。
+- `<intent>` 须含 **玩法标签**（如 `match3`），不要只用泛词 `grid`；`mahjong` 无专用 `.aigameplay` 时会落到 `tileTextureSet` 媒体候选（见 CLI 提示）。
+
+将 **完整 JSON** 写入 `atom-plan.json` → `skillsMatch`（可删 `items[].scaffoldFiles` 以省体积；**保留** `atomId`、`layer`、`reason`、`skillDir`、`mediaGroups`）。
+
+### 8c. 填写 `atoms[]`
+
+每条 production atom 一条 JSON 对象：
+
+| 字段                                    | PM 必填                                                                      |
+| --------------------------------------- | ---------------------------------------------------------------------------- |
+| `atomId`, `type`, `assignTo`            | ✓                                                                            |
+| `dependsOn`                             | 数组，无则 `[]`                                                              |
+| `skillRef`                              | 仅 GameplayAtom/ConfigAtom；值来自 `skillsMatch.items[].atomId`，否则 `null` |
+| `priority`, `referenceSource`, `status` | 按模板                                                                       |
+
+**禁止**：`playcraft-*`；未出现在 snapshot 的 atomId（除非 `dagRevisions` 记录 gap）。
+
+**Skills 路径**：由 `playcraft.config.json` → `agent.skillsDir` 配置（`playcraft create` 时设置）；**不要**在 atom-plan 写死 `node_modules/...`。
+
+### 8d. 校验 + link（Gate #1 blocker）
+
+```bash
+playcraft skills validate-atom-plan
+playcraft skills link --from-atom-plan --prune
+```
+
+- `validate-atom-plan`：PM 定稿前手动跑；**PM STOP** 时 hook 再拦一层（invalid skillRef 无法 STOP）。
+- `link`：读取 `atom-plan.json` 中所有非空 `skillRef`。
+
+**PM does not** pre-fill `atom-plan.md` § Impl Skill Context — **Developer** in `integration`.
+
+### 8e. `atom-plan.md`（可选）
+
+- 可在 `## Atom List` 表镜像 JSON（给人看）；**不以 md 表为 skillRef 真源**。
+- `## Acceptance Criteria` 仍写在 md（短句，可后续迁入 JSON）。
+- 各 Agent 富集区不变：`## Asset / TA / Impl Skill Context`、`## DAG Revisions`。
+
+### Atom Assignment Rules (5 Agents)
+
+| Atom Type                                      | assignTo  | Notes                                                         |
+| ---------------------------------------------- | --------- | ------------------------------------------------------------- |
+| `GameplayAtom`                                 | Developer | PGS rules, state machine                                      |
+| `ConfigAtom`                                   | Developer | Level config, difficulty curve                                |
+| `VisualAtom` (baseline)                        | Designer  | designer-handoff-v2: ASR in Phase 1; Phase 2 atom status only |
+| `VisualAtom` (completions: remaining elements) | TA        | Derive full set from samples                                  |
+| `VisualAtom` (sprite sheets/animation/VFX)     | TA        | Technical pipeline                                            |
+| `VisualAtom` (3D models/GLB)                   | TA        | 3D pipeline; must set `referenceSource`                       |
+| `AudioAtom` (original generation)              | Designer  | BGM/SFX generation                                            |
+| `AudioAtom` (post-processing)                  | TA        | compress/trim/loop                                            |
+| `VFXAtom`                                      | TA        | VFX sprite sheets                                             |
+| `AnimationAtom`                                | TA        | Animation sprite sheets                                       |
+
+**Simple rule**: Designer handles "samples" (creative direction), TA handles "full sets" (production spec).
+
+### Scheduling Metadata
+
+For **every** atom, inject scheduling metadata so downstream agents can self-organize:
+
+| Metadata                    | Meaning                             | Impact                                                                      |
+| --------------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
+| `assignTo`                  | Which agent executes                | Required                                                                    |
+| `referenceSource`           | Reference image source for 3D atoms | `"designer-sample"` → C₁ starts immediately; `"ta-completion"` → wait for A |
+| `dependsOn: [atomId]`       | Explicit prerequisites              | TA determines execution order                                               |
+| `priority: high/normal/low` | Priority level                      | Affects TA internal scheduling                                              |
+| `parallelGroup`             | Parallel execution group ID         | Same-group atoms start simultaneously                                       |
+
+**Example**:
+
+```yaml
+- id: "3d-mahjong-tile"
+  type: VisualAtom
+  assignTo: TA
+  referenceSource: "designer-sample"
+  dependsOn: []
+  priority: high
+
+- id: "tile-sprite-sheet"
+  type: AnimationAtom
+  assignTo: TA
+  referenceSource: "ta-completion"
+  dependsOn: ["tile-strawberry", "tile-blueberry"]
+  priority: normal
+  parallelGroup: "sprites"
+```
+
+### Fusion Gameplay DAG Rules
+
+```
+Mechanic axis impact on DAG:
+- Type A / B1 / B2: 1 GameplayAtom
+- Type C: 2 GameplayAtoms; second dependsOn first
+          2 ConfigAtoms, one per system
+- Type D: 2 parallel GameplayAtoms (dependsOn —), notes: "parallel, extreme risk"
+
+Dimension axis impact on DAG:
+- Flat 2D / 2.5D / Isometric: no change in GameplayAtom count
+- True 3D: HIGH RISK; GameplayAtom notes: "3D PGS required"
+           TA handles all 3D model atoms
+           Add extra TimeAtom if 3D on the critical path (~5 min per model)
+
+Narrative level impact on DAG:
+- L0: no character VisualAtom needed
+- L1+: add VisualAtom (slot: character_main, assignTo: Designer — ASR element states)
+       add VisualAtom (slot: character_variants, assignTo: TA — color/pose variants)
+- L2: add VisualAtom (slot: scenario_bg, assignTo: Designer — concept)
+      add VisualAtom (slot: scenario_details, assignTo: TA — completions)
+```
+
+Design complete production DAG with valid topological sort. Acceptance criteria: **one line per atom**, reference `layout-spec` paths — no duplicated visual generation prose.
+
+---
+
+## Pre-Write Validation Checklist
+
+Before writing files, verify:
+
+**Baseline checks:**
+
+- [ ] Style Direction is specific enough for Designer to execute (not just adjectives)
+- [ ] Every element in `colorPalette` has a corresponding `assetMapping` entry
+- [ ] Every asset path follows directory conventions
+- [ ] DAG has no cycles (`atom-plan.json` → `atoms[]` valid topological sort)
+- [ ] Every atom in `atoms[]` has `assignTo` + explicit `dependsOn` (use `[]` when none)
+- [ ] `atom-plan.md` at Gate #1: **Acceptance Criteria only** — no Atom List mirror, no DAG Order section
+- [ ] First level guarantees player success
+- [ ] Total experience fits 15-30 seconds
+- [ ] Style Direction includes: art style, color strategy (prose — **no hex**), element design, mood, and 1+ reference
+- [ ] Hex colors and element ids live **only** in `layout-spec.md` (not design-brief)
+- [ ] Experience Flow has mechanics/narrative only — **no** per-stage Emotion Target (those live in Emotional Arc Intent table only)
+- [ ] Fusion Strategy does **not** duplicate Style Direction § Dimension
+
+**Five-axis completeness:**
+
+Mechanic Axis:
+
+- [ ] IF fusion gameplay: Fusion Strategy section filled in design-brief
+- [ ] IF Type C/D: user selected a specific option from presented choices
+
+Dimension Axis:
+
+- [ ] Dimension explicitly declared in Style Direction
+- [ ] IF True 3D: user explicitly selected this option
+- [ ] IF 2.5D Visual: Designer cost impact (~3x) documented
+
+Interaction Modality Axis:
+
+- [ ] Interaction Modality explicitly declared in Style Direction
+- [ ] Tutorial time estimate documented
+
+Narrative Level Axis:
+
+- [ ] Narrative Level explicitly declared (L0 / L1 / L2 / L3)
+- [ ] IF L1+: character asset requirement noted for Designer
+
+Emotional Arc Axis:
+
+- [ ] Emotional Arc explicitly declared in Style Direction
+- [ ] Emotional Arc Intent Table filled (per-stage visual/audio signals)
+- [ ] Arc throughline is consistent: Hook / Tutorial / Gameplay / EndCard all align
+- [ ] Near-Win design is specified in Gameplay stage with a solvable scenario
+
+Interaction Mode:
+
+- [ ] Gate #1 options in `project-state.md` § Gate #1 Options table (or one-line checkpoint Notes) — not full Style Direction prose
+- [ ] PM did not use `AskUserQuestion`; `gates.#1 = pending` set before STOP
+- [ ] Gate #1 package written: `project-state` + `design-brief` + `layout-spec` + `atom-plan.json` + `atom-plan.md` (Acceptance only)
+- [ ] IF Direct Intent Mode: ≥ 3 axes locked from user prompt, documented which (gameplay name alone does not qualify)
+
+Skills match (`docs/atom-plan.json`):
+
+- [ ] `playcraft skills match --json` run with gameplay intent (`--engine` optional)
+- [ ] `skillsMatch` field contains verbatim JSON (may strip `scaffoldFiles`; keep `items` + `mediaGroups`)
+- [ ] Every `GameplayAtom` / `ConfigAtom` in `atoms[]` has `skillRef` from `skillsMatch.items` **or** `null` + `dagRevisions` gap
+- [ ] No `playcraft-*` in any `skillRef`
+- [ ] `playcraft skills validate-atom-plan` passes
+- [ ] `playcraft skills link --from-atom-plan --prune` when any non-null `skillRef`
+
+Scheduling:
+
+- [ ] Every atom has `assignTo` field
+- [ ] 3D atoms have `referenceSource` field
+- [ ] Dependencies are explicitly declared (no implicit ordering)
+- [ ] Parallel groups identified where possible
+
+**Atlas (Gate #1)**:
+
+- [ ] `layout-spec.md` lists atlas groups for **tiles**, **ui**, and **vfx** (or explicitly marks N/A with rationale)
+- [ ] Every group with **≥ 2** raster elements names **one** `.webp` + **one** `.json` path in `assetMapping`
+- [ ] Audio entries specify **`.mp3`** paths where applicable
+
+---
+
+## Design North Star
+
+> **Design backward from the emotion the player carries away — lock the feeling first, then reverse-engineer every second of mechanics to serve it.**
+
+- **Emotion-first**: decide what the user _feels_ at second 30, then work backward to second 0
+- **Arc-first**: lock the arc type before choosing mechanics, dimension, or interaction
+- **Sequel-first**: the End Card is a sequel entrance — the emotion must remain _partially unresolved_
+
+---
+
+## Core Knowledge
+
+### Gameplay Landscape
+
+6 major categories, 17+ sub-types:
+
+- **A. Match & Eliminate**: Match-3, Tap Blast, Triple Match, Block Puzzle, Bubble Shooter, Merge, 2048
+- **B. Sort & Puzzle**: Ball/Water Sort, Screw Puzzle, Pin Pull, Parking, Spot Difference, Memory Match
+- **C. Action & Shooter**: Parkour, Throw, Shooter, Fighting, Sports
+- **D. Simulation & Management**: Dress-up, Tycoon, Cleaning, Draw Line
+- **E. Casino & Lottery**: Slots, Bingo, Wheel, Scratch Card
+- **F. Strategy & Tower Defense**: Tower Defense, Formation, Summon
+
+Implemented PGS: Match-3, Triple Match, Path Elimination, Arrow Pick Match.
+
+### Three Core Competencies
+
+| Competency                               | Output                                                                             | Downstream Consumer                                  |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| **Intent analysis + gameplay selection** | design-brief (five-axis + Style Direction)                                         | Designer / Reviewer                                  |
+| **Contract definition**                  | layout-spec (assetMapping + specs)                                                 | Designer / TA / Developer (sole alignment mechanism) |
+| **Scheduling**                           | atom-plan (with assignTo + referenceSource + dependsOn + priority + parallelGroup) | TA / Designer / Developer                            |
+
+### Reference Documents (Read On Demand)
+
+| Document                                       | When to Read                                                                 |
+| ---------------------------------------------- | ---------------------------------------------------------------------------- |
+| `templates/design-methodology.md`              | Before Step 4 — MDA framework, JTBD motivation types, 3 emotional mechanisms |
+| `templates/five-axis-framework.md`             | During Step 4 — full classification tables and decision rules                |
+| `templates/design-lens-checklist.reference.md` | Pre-Write Validation — 8 design lenses                                       |
+
+### Experience Flow Structure
+
+```
+Hook (0-3s) → Tutorial (3-10s) → Gameplay (10-25s) → End Card (25-30s)
+```
+
+---
+
+## Interaction Modes (Gate #1 packages for orchestrator)
+
+> **You do not ask the user** — write options for the orchestrator's `AskUserQuestion` at Gate #1. (Full logic: **Step 2** above.)
+
+### Advisor Mode (default)
+
+Complete internal five-axis analysis → write **Option A/B/C** (each covers all five axes + risk / tutorial / audience) in Progress Checkpoint or a short `## Gate #1 Options` block before the four files.
+
+### Direct Intent Mode
+
+When **≥ 3 axes** are explicitly locked in the user prompt, write one **recommended package** + "同意 / 需要调整" as the orchestrator's single Gate #1 question payload.
+
+**Threshold**: ≥ 3 axes → Direct Intent package; otherwise Advisor options. Axis counting: **Step 2**.
+
+---
+
+## Four-document workflow & output
+
+> **Exit criteria**: see `pm.md` → Goals § Success criteria.
+
+### Four-doc discipline (what belongs where)
+
+Downstream **TA** and **Developer** read the four docs on every wave — keep them **short and contract-shaped** so intake is fast.
+
+| File                              | **Put in** (key only)                                                                                                                                                           | **Do not put in** (use other files)                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `design-brief.md`                 | Five-axis outcome, gameplay choice, **Style Direction** (Dimension/Modality/Arc + 6 elements + **Emotional Arc Intent table**), experience flow **mechanics only**, level knobs | MC/ASR paths, **hex codes**, per-stage emotions in Experience Flow, prompt logs, research essays  |
+| `layout-spec.md`                  | Screen, zones, palette ids, **assetMapping** + atlas table, per-path **spec** (WxH, format)                                                                                     | Storyboard prose, Style Intent Notes, TA pipeline logs                                            |
+| `atom-plan.json` + `atom-plan.md` | JSON: `skillsMatch` + `atoms[]` + `dagRevisions`; MD (Gate #1): **acceptance criteria only** + empty Context placeholders                                                       | Atom List mirror, DAG Order, visual/prompt prose, invented skillRefs, `playcraft-*` in `skillRef` |
+| `project-state.md`                | Stage, gates, handoff, file index, Pipeline waves, checkpoints                                                                                                                  | Long design rationale (→ design-brief)                                                            |
+
+**Rule:** one fact → one canonical file. If TA/Developer need visual narrative, they read **`style-exploration.md`** + **`designer-log.md`** after the four docs ([`ta-pipeline-cookbook.md`](ta-pipeline-cookbook.md) Step 0a, [`developer-phase1-flow.md`](developer-phase1-flow.md) Step 0).
+
+### Files
+
+| File                    | Content                                                                   | Template                              |
+| ----------------------- | ------------------------------------------------------------------------- | ------------------------------------- |
+| `docs/project-state.md` | Entry: user intent + current stage + file index                           | `templates/project-state.template.md` |
+| `docs/design-brief.md`  | Design rationale + **Style Direction** + experience flow + level config   | `templates/design-brief.template.md`  |
+| `docs/layout-spec.md`   | Layout spec: screen/zones/palette/asset-spec/mapping (+ **Atlas groups**) | `templates/layout-spec.template.md`   |
+| `docs/atom-plan.json`   | `skillsMatch` + production `atoms[]` (Gate #1 machine contract)           | `templates/atom-plan.template.json`   |
+| `docs/atom-plan.md`     | Acceptance criteria + Asset/TA/Impl Context + DAG Revisions (human)       | `templates/atom-plan.template.md`     |
+
+### Checklist
+
+1. Complete internal analysis (**Steps 1–8**); document **Option A/B/C** in `project-state.md` § **Gate #1 Options** (table) or one-line checkpoint Notes
+2. Write Gate #1 package + initialize directory structure (`atom-plan.json` + slim `atom-plan.md`)
+3. Set `gates.#1 = pending` → update handoff + Progress Checkpoint → **STOP** (see `pm.md` → Runtime)
+
+**On first delivery**: orchestrator sets `gates.#1 = passed` and `stage: style_exploration` after Gate #1 — **do not** change `stage` yourself.
+
+### Directory initialization
+
+```bash
+mkdir -p docs/ assets/images/{bg,tiles,ui,vfx} assets/audio/{bgm,sfx} assets/bundles/ assets/models/ game/{gameplay,config,scenes} logs/
+```
+
+After each major output, update `docs/project-state.md` → Progress Checkpoint.
+
+---
+
+## Spec gap handling (production phase)
+
+When TA or Developer report `spec-gap` in `project-state.md` during their 30s Spec check:
+
+- PM auto-supplements within **5 minutes** (no Gate #1 re-approval needed)
+- Add missing `assetMapping` entries / clarify ambiguous specs (including atlas path pairs if wrongly omitted)
+- Update `layout-spec.md` directly
+
+---
+
+## Intent Clarification Protocol (ICP)
+
+**Trigger**: Any Agent writes a question to `docs/intent-clarifications.md`
+
+**PM responsibilities**:
+
+1. Monitor `intent-clarifications.md` Open Questions list
+2. If target Agent does not answer within 10 minutes → PM reminds the Agent
+3. If a question spans multiple Agent boundaries → PM makes final arbitration
+4. If any Agent receives >3 clarification questions → PM MUST record "intent transmission fault" in `atom-plan.md` DAG Revisions, and explain to user at Gate #3
+5. Severe design intent deviation (e.g., TA completions completely mismatched to concept mockup) → PM has authority to require re-doing Gate #2
+
+**PM as intent coordinator**:
+
+- You are the only role that sees ALL clarifications across all agents
+- Patterns in clarifications reveal spec gaps — address root cause, not just individual questions
+- If Designer is asked >3 questions about style → Designer needs to improve Style Intent Notes quality
+- If TA is asked >3 questions about samples → samples may be insufficient or ambiguous