@playcraft/cli 0.0.44 → 0.0.46

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

@@ -0,0 +1,258 @@
+# Developer Log
+
+## Upstream Intake
+
+> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.**
+
+| Doc                           | Read ✓  | One-line takeaway                                                           |
+| ----------------------------- | ------- | --------------------------------------------------------------------------- |
+| `docs/project-state.md`       | ☐       | {{stage, gates, devStatus}}                                                 |
+| `docs/implementation-plan.md` | ☐       | {{Feature 列表 + 依赖图 + 首关策略}}                                        |
+| `docs/design-brief.md`        | ☐       | {{rings 2+ only — ring 1 reads DESIGN.md instead}}                          |
+| `docs/layout-spec.md`         | ☐       | {{zones, assetMapping, atlas paths}}                                        |
+| `docs/atom-tree.json`         | ☐       | {{selected atom refs in meta.selectedAtoms + mediaGroups + revision trail}} |
+| `docs/atom-tree.md`           | ☐       | `Selected Atoms Summary` / `Selected Skill Notes` + acceptance              |
+| `docs/DESIGN.md`              | ☐       | {{player goal, core loop, fun source}}                                      |
+| `docs/style-exploration.md`   | ☐       | {{MC panel layout per scene}}                                               |
+| `docs/scaffold-manifest.md`   | ☐ / n/a | {{scaffold file → atom source mapping}}                                     |
+
+---
+
+## Spec Quick-Check
+
+> **Before coding**, confirm the spec is actually implementable in the current project.
+
+- **Required gameplay / UI contract paths complete**: {{yes/no}}
+- **Feature list can map onto current project structure**: {{yes/no}}
+- **Current blockers**: {{none / list}}
+- **If blocked, routeTo**: {{Game Designer / Artist / TA / none}}
+
+---
+
+## Skill Preflight
+
+> **Before coding**, read the Skills referenced in your atoms and record what they contribute.
+
+| selectedAtomRef        | Read path / source                     | 提供了什么               | 怎么用                                    | 注意         |
+| ---------------------- | -------------------------------------- | ------------------------ | ----------------------------------------- | ------------ |
+| {{selectedAtomRef}}    | {{SKILL / ref}}                        | {{一句话}}               | {{scaffold import / 参考设计 / 参考配置}} | {{关键约束}} |
+| `playable-placeholder` | `skills/playable-placeholder/SKILL.md` | Tier 2 图片/音频批量占位 | batch 生成 + sidecar                      | build 环必载 |
+
+### Fusion wiring (≥2 gameplay atoms only)
+
+> When `meta.selectedAtoms` includes **2+ `*.aigameplay` refs**, record how each mechanic is wired and how `autoPlay()` reaches both.
+
+| Gameplay atom | Wiring evidence (file / symbol)             | autoPlay touchpoint               |
+| ------------- | ------------------------------------------- | --------------------------------- |
+| {{atomA}}     | {{e.g. game/gameplay/match3.ts → trySwap}}  | {{e.g. publish autoPlay phase 1}} |
+| {{atomB}}     | {{e.g. game/gameplay/memory.ts → flipCard}} | {{e.g. publish autoPlay phase 2}} |
+
+---
+
+## Read / Load Log
+
+> **有代码也必须先读。** Record the actual files, skills, and runtime inputs you loaded before editing.
+
+| Type  | Path / Item | Why relevant | Read / Loaded ✓ | One-line takeaway |
+| ----- | ----------- | ------------ | --------------- | ----------------- |
+| code  | {{path}}    | {{reason}}   | ☐               | {{what matters}}  |
+| skill | {{skill}}   | {{reason}}   | ☐               | {{what matters}}  |
+| asset | {{path}}    | {{reason}}   | ☐               | {{what matters}}  |
+
+---
+
+## Skill-to-Prototype Assembly (Project Assembly Checkpoint)
+
+> **Mandatory before feature logic implementation.** Convert adopted Skill decisions into the smallest local playable spine before expanding features. This is a rework-prevention tool, not an audit form.
+
+### Assembly thinking
+
+#### What skill decisions am I inheriting?
+
+- {{object model / rule location / state flow / interaction boundary / asset organization}}
+
+#### What project-specific changes are required?
+
+- {{game size / contract paths / first-level requirement / UI states / runtime constraints}}
+
+#### What is the smallest playable spine before feature expansion?
+
+- {{load setup → render core objects → player action → feedback → rule resolution}}
+
+### Scaffold adoption
+
+| Scaffold / existing file | Atom / source | Skill decision carried by this file | Used by feature | Adopt / ignore-with-reason | Notes                            |
+| ------------------------ | ------------- | ----------------------------------- | --------------- | -------------------------- | -------------------------------- |
+| {{path}}                 | {{skillRef}}  | {{decision}}                        | {{feature}}     | {{adopt / reason}}         | {{how it shapes implementation}} |
+
+### Placeholder materialization
+
+> **Policy**: Tier 1 link → Tier 2 `placeholder:gen` (image) / `placeholder:gen-audio` (loaded MP3) → Tier 3 code-draw or event hook only. Load **`playable-placeholder`** skill before materialization.
+
+| Asset contract path | Tier / Source                                     | Size    | Generated / verified | Used by scene / feature | Notes                        |
+| ------------------- | ------------------------------------------------- | ------- | -------------------- | ----------------------- | ---------------------------- |
+| {{path}}            | {{Tier 1/2/3 — linked / placeholder / code-draw}} | {{WxH}} | ☐                    | {{scene / feature}}     | {{label / reason if Tier 3}} |
+
+- **Placeholder script**: `ta-workspace/scripts/gen-placeholders.mjs` {{created / updated / n/a}}
+- **Audio placeholder script**: `ta-workspace/scripts/gen-placeholder-audio.mjs` {{created / updated / n/a}}
+- **Placeholder run result**: {{success / partial / failed + reason}}
+- **Tier 3 code-draw exceptions**: {{list each with one-line why placeholder file was not viable, or "none"}}
+- **No runtime remote image URLs**: {{yes/no}}
+- **No code-draw substituting Tier 2 paths**: {{yes/no}}
+
+### Minimal prototype wiring baseline
+
+| Feature     | Skill / ref basis  | Skill-defined loop step                                     | Code entry / scaffold file | Asset paths | Baseline status     |
+| ----------- | ------------------ | ----------------------------------------------------------- | -------------------------- | ----------- | ------------------- |
+| {{feature}} | {{skillRef / ref}} | {{e.g. setup / player action / feedback / rule resolution}} | {{path}}                   | {{paths}}   | {{ready / blocked}} |
+
+- **Skill-defined minimal loop**: {{describe the smallest playable loop from the adopted Skill/ref; not necessarily full ad flow}}
+- **Closed-loop path ready for implementation**: {{yes/no}}
+- **Open blockers before coding**: {{none / list}}
+- **If I am about to rewrite scaffold from scratch, why is adaptation insufficient?** {{reason / n/a}}
+
+---
+
+## Implementation Plan
+
+> **development stage — mandatory before any `game/` edit.** Hook enforces on STOP.
+>
+> This section captures the Developer execution plan for the current run. Developer role ownership and boundaries live in `.claude/agents/developer.md`.
+
+### Architecture
+
+- **Engine**: {{engine}}
+- **Entry**: `game/index.html`
+- **Skill-defined minimal loop**: {{setup → player action → feedback → rule resolution, or the loop defined by adopted Skill/ref}}
+- **Ad experience flow**: {{Hook / Tutorial / Gameplay / EndCard / CTA if required by plan, otherwise list required scenes/states}}
+
+### Scene / Loop Asset Binding Plan
+
+| Scene / loop step            | Assets (assetMapping) | Atlas/Frame | Placeholder strategy                |
+| ---------------------------- | --------------------- | ----------- | ----------------------------------- |
+| {{scene or skill loop step}} | {{paths}}             | {{json}}    | {{Skill asset / placeholder color}} |
+
+### Scene navigation (for Reviewer ui_diff, if required by plan)
+
+| Required panel / state | Scene key | How to reach (URL param / button) |
+| ---------------------- | --------- | --------------------------------- |
+| {{panel/state}}        | {{key}}   | {{e.g. ?scene=main or button}}    |
+
+### PGS Strategy
+
+- **Gameplay type**: {{from DESIGN.md (+ design-brief in rings 2+) / adopted Skill}}
+- **Core rules**: {{from Skill recipe / ref source}}
+- **Minimal loop guarantee**: {{how the skill-defined loop can be completed locally}}
+- **First level guarantee**: {{if required by plan}}
+- **State machine**: {{states and transitions}}
+
+### Risk Checklist
+
+- [ ] Every assetMapping path used by current features is accounted for (Skill asset / placeholder noted)
+- [ ] Skill-defined minimal loop can run locally
+- [ ] Required scene navigation documented for all plan-required panels / states
+- [ ] First level guarantee covered if required by plan
+- [ ] CTA handler with platform fallbacks if required by plan
+- [ ] Zero external network requests
+- [ ] No open unexplained blockers
+
+---
+
+## Feature Checklist
+
+> Convert `docs/implementation-plan.md` into the real execution and acceptance checklist.
+
+| Order | Feature     | Source refs           | Dependencies | Existing code read? | Done when             | Status                                  |
+| ----- | ----------- | --------------------- | ------------ | ------------------- | --------------------- | --------------------------------------- |
+| 1     | {{feature}} | {{plan/design/skill}} | {{deps}}     | yes / no            | {{completion signal}} | todo / doing / done / partial / blocked |
+
+---
+
+## Feature Review
+
+> **Ready 判断前必须逐项 review。**
+
+| Feature     | Status                   | Verification         | Review notes                                                          | Remaining risk / blocker |
+| ----------- | ------------------------ | -------------------- | --------------------------------------------------------------------- | ------------------------ |
+| {{feature}} | {{done/partial/blocked}} | {{what was checked}} | {{did existing code + skill reading actually inform implementation?}} | {{none / issue}}         |
+
+### Review decision
+
+- **Checklist complete**: {{yes/no}}
+- **Unexplained partial / blocked items**: {{none / list}}
+- **Can enter ready check**: {{yes/no}}
+
+---
+
+## 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
+
+### development completion
+
+- **devUrl**: {{http://localhost:.../?debug=1}} ← always include `?debug=1` (shows the one-click clear debug button)
+- **devStatus**: {{ready / blocked_upstream / in_progress}}
+- **UI vs MC + layout-spec**: {{pass/fail — notes}}
+- **Scene navigation works**: {{yes/no}}
+- **Gameplay vs DESIGN.md + PGS**: {{pass/fail — notes}}
+- **Runtime** (CTA, audio, state machine): {{pass/fail — notes}}
+- **Feature checklist reviewed**: {{yes/no}}
+- **verify:contract**: {{pass/fail — log OK line}}
+- **verify:lifecycle** (ring 1 STOP required): {{pass/fail — phase path}}
+- **verify:firstwin** (ring 1 STOP required): {{pass/fail — log OK line}}
+- **verify:placeholders** (ring 1 STOP required): {{pass/fail — loaded asset paths exist}}
+- **Ready for ring:gate** (ring 1) / **Ready for Reviewer gameplay_conformance** (ring 2+): {{yes/no}}
+
+---
+
+## Skill Leverage
+
+> **STOP 前回顾**。说明哪些 Skill 参考真实影响了实现与判断。
+
+- 哪些 selected / additional Skill 在本轮真正被参考？{{列出 skillRef，如无则说明为何}}
+- 它们分别帮助了什么判断或实现？{{简述}}
+- 哪些 shortlisted Skill 最终未采用？{{是/否 + 原因}}
+
+---
+
+## Upstream blockers
+
+| Path     | Issue     | Resolution                               | routeTo                     | Status          |
+| -------- | --------- | ---------------------------------------- | --------------------------- | --------------- |
+| {{path}} | {{issue}} | fixed / replaced(reason) / escalated / — | TA / Artist / Game Designer | open / resolved |
+
+---
+
+## UI Rework Log
+
+> **ui_rework stage only.** 每轮只修 `logs/review-report.md` 中 `routeTo: Developer` 的 Action Items；不改游戏逻辑。
+
+### Round {{N}}
+
+| Action Item | Severity  | Fix applied                      | npm run dev result |
+| ----------- | --------- | -------------------------------- | ------------------ |
+| {{item}}    | {{level}} | {{what was changed + file/line}} | {{pass/fail}}      |
+
+- **Remaining open items**: {{count or "none"}}
+- **devUrl after fix**: {{http://localhost:.../?debug=1}}
+- **Handoff**: `Invoke @reviewer ui_diff`
+
+---
+
+## Per-Atom Delivery
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Phase**: development / ui_rework
+- **Output path**: {{file_path}}
+- **Notes**: {{notes}}

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

@@ -0,0 +1,194 @@
+# Five-Axis Analysis Framework
+
+> **When to read**: Game Designer may consult this as an **optional analytical tool** during design work. It is NOT a mandatory step-by-step checklist.
+>
+> **Stage relevance**:
+>
+> - **ring 1 `loop: clarify`**: Only **Axis 1 (Mechanic)** and **Axis 3 (Interaction Modality)** must be resolved — they define core playability (可解性) and time/operation budget. The other axes only need a rough direction signal (e.g. "2D", "L1 character present", "Competence arc").
+> - **ring 2 `loop: clarify` (after MC)**: Axis 2 (Dimension), Axis 4 (Narrative Level), and Axis 5 (Emotional Arc) get their full specification when visual direction is confirmed by MC selection.
+>
+> **This framework is a thinking aid, not a production template.** Game Designer should focus on gameplay first; use these axes to check coverage, not to fill out forms.
+
+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. Game Designer 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                                                            | Artist 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 Artist 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. Artist 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 (Artist 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                                                         | Artist 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 Artist needs character assets; Game Designer 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 Artist 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 Game Designer 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 + Artist 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-templates/threejs/templates/gen-placeholder-audio.template.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Batch spectral-audio placeholder generator for develop-stage asset materialization.
+ * Outputs per row: <stem>.mp3 + <stem>.json (+ <stem>.spectrogram.png in spectral mode).
+ * See skills/playable-placeholder/SKILL.md for full Developer workflow.
+ *
+ * Setup:
+ *   cp templates/gen-placeholder-audio.template.mjs ta-workspace/scripts/gen-placeholder-audio.mjs
+ *
+ * Run:
+ *   node ta-workspace/scripts/gen-placeholder-audio.mjs
+ *   # or: npm run placeholder:gen-audio -- --batch ta-workspace/tmp/placeholders.audio.batch.json
+ *
+ * Use when Preloader / load.audio already references contract MP3 paths but Artist has not delivered yet.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = process.cwd();
+const GEN_SCRIPT = join(ROOT, 'skills/_shared/scripts/gen-placeholder-audio.py');
+const BATCH_JSON = join(ROOT, 'ta-workspace/tmp/placeholders.audio.batch.json');
+
+// Derive from layout-spec.md → assetMapping audio rows + Preloader keys.
+const PLACEHOLDER_AUDIO = [
+  {
+    path: 'assets/audio/bgm/bgm_main.mp3',
+    label: 'bgm_main',
+    type: 'bgm',
+    role: 'bgm · 主背景音乐',
+  },
+  {
+    path: 'assets/audio/sfx/sfx_match.mp3',
+    label: 'sfx_match',
+    type: 'sfx',
+    role: 'sfx · 消除音效',
+  },
+  {
+    path: 'assets/audio/sfx/sfx_click.mp3',
+    label: 'sfx_click',
+    type: 'sfx',
+    role: 'ui sfx · 点击',
+  },
+  // Add one row per contract MP3 path the minimal prototype loads.
+];
+
+function runBatch() {
+  mkdirSync(dirname(BATCH_JSON), { recursive: true });
+  writeFileSync(BATCH_JSON, `${JSON.stringify(PLACEHOLDER_AUDIO, null, 2)}\n`, 'utf8');
+
+  const proc = spawnSync('python3', [GEN_SCRIPT, '--batch', BATCH_JSON], {
+    cwd: ROOT,
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  if (proc.status !== 0) {
+    process.exit(proc.status ?? 1);
+  }
+}
+
+runBatch();

package/project-templates/threejs/templates/gen-placeholders.template.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Batch placeholder generator for develop-stage asset materialization.
+ *
+ * Setup:
+ *   cp templates/gen-placeholders.template.mjs ta-workspace/scripts/gen-placeholders.mjs
+ *
+ * Run:
+ *   node ta-workspace/scripts/gen-placeholders.mjs
+ *   # or: npm run placeholder:gen
+ *
+ * Uses local gen-placeholder.py — outputs <stem>.webp + <stem>.json per row.
+ * See skills/playable-placeholder/SKILL.md for full Developer workflow.
+ * TA overwrites these files later — code should only reference contract paths.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = process.cwd();
+const GEN_SCRIPT = join(ROOT, 'skills/_shared/scripts/gen-placeholder.py');
+const BATCH_JSON = join(ROOT, 'ta-workspace/tmp/placeholders.batch.json');
+
+// Derive from layout-spec.md → assetMapping (or ring-1 minimal prototype list).
+// bg/fg: closest palette hex from layout-spec → palette.
+// label: elementId; role: optional purpose for TA (auto-inferred from prefix if omitted)
+// shape: auto | fill | rounded | circle | ellipse | diamond | ring | triangle-up | triangle-down
+const PLACEHOLDERS = [
+  {
+    path: 'assets/images/bg/bg_main.webp',
+    size: '750x1334',
+    bg: '1a1a2e',
+    fg: 'cccccc',
+    label: 'bg_main',
+    shape: 'fill',
+  },
+  {
+    path: 'assets/images/ui/btn_cta.webp',
+    size: '300x100',
+    bg: 'ff6b35',
+    fg: 'ffffff',
+    label: 'btn_cta',
+    shape: 'rounded',
+    role: 'CTA button · 主行动按钮',
+  },
+  {
+    path: 'assets/images/tiles/tile_gold.webp',
+    size: '128x128',
+    bg: 'ffcc00',
+    fg: '000000',
+    label: 'tile_gold',
+    shape: 'circle',
+  },
+  {
+    path: 'assets/images/tiles/tile_empty.webp',
+    size: '128x128',
+    bg: '333333',
+    fg: '888888',
+    label: 'tile_empty',
+    shape: 'circle',
+  },
+  // Add one row per missing visual resource expected by the minimal prototype.
+];
+
+function runBatch() {
+  mkdirSync(dirname(BATCH_JSON), { recursive: true });
+  writeFileSync(BATCH_JSON, `${JSON.stringify(PLACEHOLDERS, null, 2)}\n`, 'utf8');
+
+  const proc = spawnSync('python3', [GEN_SCRIPT, '--batch', BATCH_JSON], {
+    cwd: ROOT,
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  if (proc.status !== 0) {
+    process.exit(proc.status ?? 1);
+  }
+}
+
+runBatch();

package/project-templates/threejs/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 坐标不一致时，必须向 Game Designer 提问
+-->
+
+## 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:
+  - "已补充到 artist-log.md Style Intent Notes"
+  - "已更新 layout-spec.md zones 坐标"
+  - "Game Designer 裁决：以故事板为准，layout-spec 将修正"
+  - "双方同意保持现状，偏差在可接受范围"
+-->
+
+## Metrics
+
+| Metric                 | Value     |
+| ---------------------- | --------- |
+| Total questions raised | {{count}} |
+| Unresolved             | {{count}} |
+| By Artist              | {{count}} |
+| By TA                  | {{count}} |
+| By Developer           | {{count}} |
+| By Game Designer       | {{count}} |
+| By Reviewer            | {{count}} |
+
+<!--
+Game Designer monitors this table:
+  - If single Agent receives >3 questions → intent transmission fault, record in DAG Revisions
+  - If unresolved >3 at any time → Game Designer must intervene and assign priority
+  - If Reviewer finds unresolved questions at review stage → deduct Intent Transmission score
+-->