@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/docs/DESIGN.md

@@ -0,0 +1,65 @@
+# {Game Name} — Ring 1 Core Gameplay Contract
+
+<!--
+  Ring 1 only. This file is the single Game Designer deliverable for the first
+  ring. It defines what the player can do, why the core loop is fun, how the
+  game starts at HOOK, and how the first level is guaranteed winnable.
+
+  Do not add layout-spec, production assets, CTA (Call to Action, 行动召唤)
+  polish, ASR (Asset State Reference, 资产状态参考), full MP4 (MPEG-4 Part 14,
+  视频容器格式), or multi-level progression here. Those are disclosed by
+  state:get in later rings.
+-->
+
+**Date**: {YYYY-MM-DD}
+**Engine**: {phaser / threejs / undecided}
+
+---
+
+## 1. Player Promise
+
+{Describe the playable in 3-5 sentences from the player's point of view. Focus on what the player sees, what they can do, and the first satisfying outcome.}
+
+---
+
+## 2. Core Loop
+
+### 2.1 One Player-Available Action Chain
+
+> **Player sees**: {what object / board / target is visible}
+> **Player does**: {tap / drag / aim / choose}
+> **Game responds**: {immediate feedback and state change}
+> **Next decision**: {what new information lets the player act again}
+
+### 2.2 Loop Evolution
+
+{Describe what changes after 3-5 successful actions: more confidence, combo payoff, clearer goal, or rising tension.}
+
+---
+
+## 3. Core Rules
+
+### 3.1 Valid Actions
+
+- {Action}: valid when {condition}; result is {state change / feedback}.
+
+### 3.2 Invalid Actions
+
+- {Invalid action}: game responds with {non-blocking feedback}; the first-level win path remains available.
+
+### 3.3 Win / Lose
+
+- **Win**: {condition}; player reaches `ENDCARD`.
+- **Lose**: {condition, or "not present in first level"}.
+
+---
+
+## 4. First-Level Win Strategy
+
+{Explain the exact mechanism that makes the first level winnable: constrained setup, guided target, simplified rules, generous timing, or locked failure path. Do not only write "guaranteed win".}
+
+---
+
+## 5. Ring 1 HOOK Entry
+
+{Describe the starting HOOK state that is visible immediately when the game loads. It should be enough for `verify:lifecycle` to observe `HOOK`, then for `autoPlay()` to advance through player-reachable actions to `ENDCARD`.}

package/project-templates/phaser/docs/intent-clarifications.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
+-->

package/project-templates/phaser/docs/pipeline-overview.md

@@ -0,0 +1,69 @@
+# PlayCraft Pipeline Overview (growth-rings-v1)
+
+> **Workflow spec**: `growth-rings-v1` — supersedes waterfall stages (`pm → storyboard → development → …`).
+
+## Slice-axis dispatch (harness v1)
+
+When `docs/project-state.json` has an **active slice** (`sliceState.activeSliceId` ≠ `none`):
+
+```text
+orchestrator → state:get dispatchPacket → invoke role(doWhat, flow, sliceId) → verify:slice → slice:set → STOP
+```
+
+- **Orchestrator** is the sole dispatcher; `state:get` `currentAction` / `recommendedNextAction` are slice-first (not "Ring N build").
+- **Ring** = outer budget, non-regression boundary, convergence, and user Ring Gate — not subagent daily axis.
+- **Legacy fallback**: empty slice queue → ring:loop handoff matrix below still applies.
+
+## Growth rings
+
+```
+Ring 1  playable seed → semantic spine  clarify → [temporary ref-flow + init-template + verify:contract + verify:lifecycle] → build → verify → Ring Gate
+Ring 2  gameplay skeleton + layout intent clarify → build → verify → Ring Gate
+Ring 3  Hook/CTA + ad wrapper + style context clarify → build → verify → Ring Gate
+Ring 4  production assets + integration  clarify → build → verify → Ring Gate → done
+```
+
+## Engine scaffold (ring 1 only)
+
+| Step                    | Command                                          | Owner                                                                 |
+| ----------------------- | ------------------------------------------------ | --------------------------------------------------------------------- |
+| Atom-tree metadata      | `playcraft skills init-atom-tree --intent "..."` | temporary ref-flow subagent                                           |
+| Engine `game/` skeleton | `playcraft remix init-template --from-atom-tree` | Orchestrator (legacy: before first `@developer` in ring 1 build loop) |
+| Contract probe          | `npm run verify:contract`                        | Orchestrator gate, then Developer                                     |
+| Lifecycle probe         | `npm run verify:lifecycle`                       | Orchestrator gate, then Developer                                     |
+| Placeholder probe       | `npm run verify:placeholders`                    | Developer                                                             |
+
+Supported adapters (v1): **phaser**, **threejs**. Unified harness surface: **`window.__playable`**.
+
+## Role × loop matrix
+
+| Ring | clarify                                                      | build                                      | verify                                                           |
+| ---- | ------------------------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------------- |
+| 1    | Game Designer playable seed → temporary ref-flow selector    | Developer (semantic placeholder spine)     | script-owned `ring:gate`                                         |
+| 2    | Game Designer (periphery + layout intent) → ref/plan context | Developer (gameplay skeleton)              | Reviewer + `verify:ui`                                           |
+| 3    | Game Designer Hook/CTA intent + Artist MC/ASR context        | Developer (ad wrapper + style integration) | Reviewer + `playable_validate`                                   |
+| 4    | Spec-gap only                                                | Artist W1 → TA W2 → Developer              | Reviewer `ui_diff` + `verify:visual` + `verify:atom-conformance` |
+
+## Objective DoD (ring:gate)
+
+| Ring | Script verifiers                                                                | Review verifiers                 |
+| ---- | ------------------------------------------------------------------------------- | -------------------------------- |
+| 1    | `verify:contract`, `verify:lifecycle`, `verify:firstwin`, `verify:placeholders` | script-owned                     |
+| 2    | Ring 1 DoD + disclosed UI / MP4 evidence gates                                  | `gameplay_conformance`           |
+| 3    | same                                                                            | + `playable_validate` (hook/CTA) |
+| 4    | + `verify:visual`, `verify:ui:assets`, `verify:atom-conformance`                | `ui_diff` evidence               |
+
+## Orchestrator decision shortcuts
+
+1. Every turn: `npm run workflow:doctor` (optional `--strict` in CI)
+2. Sub-agent STOP → read `contextPacket` + routing handoff → execute `next_orchestrator_action` only
+3. **Legacy ring 1 scaffold** (when `dispatchPacket` is null): ref-flow selection + `init-template --from-atom-tree` + `verify:contract` + `verify:lifecycle` before `@developer`
+4. Before Ring Gate: `npm run ring:gate -- --iteration N` must pass
+5. Ring Gate pass → archive `archivedRings` + ring context snapshot, then `iteration+1`, `loop: clarify`
+6. `done` = user accepts devUrl at ring 4 Ring Gate — not `playcraft build`
+
+## Key docs
+
+- [CLAUDE.md](../CLAUDE.md) — orchestration protocol
+- [docs/team/collaboration.md](team/collaboration.md) — Ring Gate Protocol, handoff
+- [docs/team/agent-runtime-matrix.md](team/agent-runtime-matrix.md) — fake-invoke matrix

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

@@ -0,0 +1,211 @@
+# 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 1** — engine-root + core gameplay (placeholder art)
+
+`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      | pending | `npm run verify:contract`     | Engine boots; neutral runtime contract wired (`window.__playable`) |
+| lifecycle     | pending | `npm run verify:lifecycle`    | Ring 1: starts at HOOK and autoPlay reaches ENDCARD without MP4    |
+| firstLevelWin | pending | `npm run verify:firstwin`     | Ring 1: headless autoPlay reaches ENDCARD (first level winnable)   |
+| placeholders  | pending | `npm run verify:placeholders` | Ring 1: semantic placeholder files exist for loaded asset paths    |
+
+> 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   | 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                                                   |
+
+<!--
+Examples (copy structure on STOP — do not leave nulls):
+
+Slice-axis Designer STOP (seed queue):
+  subagent: game-designer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: clarify
+  next_orchestrator_action: "Invoke @developer per dispatchPacket (slice core-action-feedback-v1)"
+  last_completed_by: game-designer
+
+Slice-axis Developer STOP (after verify:slice + slice:set verified):
+  subagent: developer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: build
+  next_orchestrator_action: "Invoke @developer per dispatchPacket for next pending slice, or npm run ring:gate when queue drained"
+  last_completed_by: developer
+
+Ring 1 clarify STOP (Designer — legacy, no sliceState):
+  subagent: game-designer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: clarify
+  next_orchestrator_action: "Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection"
+  last_completed_by: game-designer
+
+Ring 1 atom-tree STOP (temporary ref-flow selector):
+  subagent: skill-selector
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: clarify
+  next_orchestrator_action: "Run scaffold gate, then invoke @developer (legacy ring 1 build loop, or dispatchPacket when slice queue exists)"
+  last_completed_by: skill-selector
+
+Ring 1 build STOP (Developer):
+  subagent: developer
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: build
+  next_orchestrator_action: "npm run ring:gate -- --iteration 1"
+  last_completed_by: developer
+
+Ring 1 verify (orchestrator — no Reviewer invoke):
+  subagent: none
+  subagent_stop: true
+  waiting_for: orchestrator
+  loop: verify
+  next_orchestrator_action: "npm run ring:gate -- --iteration 1"
+  last_completed_by: developer
+
+Ring 2+ verify STOP (Reviewer — after load_check pass):
+
+Orchestrator after ring:gate pass (ringGateCanAskUser: yes):
+  subagent: none
+  subagent_stop: true
+  waiting_for: user_gate
+  loop: verify
+  next_orchestrator_action: "Run Ring Gate AskUserQuestion for iteration 1"
+  last_completed_by: orchestrator
+
+Ring Gate pass → iteration 2:
+  iteration: 2
+  ringGoal: gameplay + periphery (HUD / flow skeleton)
+  loop: clarify
+  ringGate: pending
+  ringDoD: resolved by state:get / ring-config for the active iteration
+  archivedRings: { 1: { contract: passed, lifecycle: passed, firstLevelWin: passed } }
+-->
+
+<!--
+  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)
+
+> Current-ring files only. Future Ring files stay hidden until `state:get` discloses them.
+
+### Current Package (Ring 1 — engine root + core gameplay)
+
+| 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/gameplay/`                          | PGS + state machine                                     | {{status}} |
+| `game/config/`                            | Level configuration                                     | {{status}} |
+| `game/scenes/`                            | Scene definitions                                       | {{status}} |
+| `game/index.html`                         | Entry point                                             | {{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.

package/project-templates/phaser/docs/scaffold-manifest.md

@@ -0,0 +1,10 @@
+# Scaffold Manifest
+
+| Field           | Value                    |
+| --------------- | ------------------------ |
+| adapter         | phaser                   |
+| appliedAt       | 2026-06-17T06:17:58.177Z |
+| mode            | bake                     |
+| runtimeContract | window.\_\_playable      |
+
+Applied by `playcraft remix init-template`.

package/project-templates/phaser/docs/team/agent-conduct.md

@@ -0,0 +1,67 @@
+# Agent Conduct — MUST / NEVER
+
+> Single source for enforceable behavior. When this conflicts with workflow shortcuts, **this wins** (except where an agent Goals § Core responsibilities explicitly overrides for that role).
+>
+> Ring Gate flow: [collaboration.md § Ring Gate Protocol](collaboration.md#ring-gate-protocol-orchestrator-only). STOP fields: [§ STOP sync checklist](collaboration.md#stop-sync-checklist). Hook enforcement: `.claude/hooks/validate-workflow-stop.mjs`.
+
+## Invoke protocol (all sub-agents)
+
+On every invoke, in order:
+
+1. Run `npm run state:get` → read `contextPacket` first, then the handoff summary (routing truth — not Progress Checkpoint alone). `docs/project-state.md` is a generated view; never open or hand-edit it.
+2. Read **this role's L1 role card** in `.claude/agents/<role>.md` to understand role ownership, boundaries, and current workflow interface.
+3. Read the specific workflow / `refs/` / SKILL documents **only when** the current task or workflow interface says so — do not load long workflow docs by default.
+4. On STOP: complete [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
+
+## All roles (including Orchestrator)
+
+|              | Rule                                                                                                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Run `npm run state:get` before any work (never open the generated `docs/project-state.md`); start from `contextPacket`, then follow required files          |
+| **MUST**     | Append a Progress Checkpoint when finishing a major step via `npm run state:set -- --checkpoint "…" --by <role>`                                            |
+| **MUST**     | On STOP: write `handoffContext` for the next role, then `npm run state:set -- subagent_stop=true next_orchestrator_action="…"` (context + routing required) |
+| **MUST NOT** | Change `layout-spec.md` `assetMapping` paths after ring 4 (`assetMappingLocked: true`) without Game Designer + user-approved contract change                |
+| **MUST NOT** | Treat `playcraft build` as required for `done` — endpoint is **user acceptance at devUrl**                                                                  |
+| **MUST NOT** | Ask the **user** to run `npm run dev` (Ring Gate = open orchestrator-provided link only)                                                                    |
+
+## Orchestrator only
+
+|              | Rule                                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Be the **only** role that uses `AskUserQuestion` for **Ring Gate** confirmations (one per growth ring)                                                                                            |
+| **MUST**     | After any sub-agent STOP, run `npm run state:get` to read `contextPacket` and routing handoff before spawn / resume / Ring Gate                                                                   |
+| **MUST**     | After any sub-agent STOP, verify: `handoffContext` complete, ring DoD evidence complete, logs filled, required preflight done                                                                     |
+| **MUST**     | If `waiting_for: user_gate` and `subagent_stop: true` and `ringGateCanAskUser: yes`, run **only** Ring Gate (`AskUserQuestion`) — **do not** invoke sub-agents                                    |
+| **MUST**     | If `subagent_stop: true` and `waiting_for: orchestrator`, execute **only** `next_orchestrator_action`                                                                                             |
+| **MUST**     | Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target role)                                                                                         |
+| **MUST**     | Dispatch = WHAT + skill refs + constraints only; do NOT write detailed production steps for sub-agents                                                                                            |
+| **MUST**     | Before Ring Gate: run `npm run ring:gate -- --iteration N` — do **not** ask user until the script returns pass                                                                                    |
+| **MUST**     | Before **ring 1 `loop: build`**: ensure `playcraft remix init-template --from-atom-tree` has run, `.playcraft-engine` matches `meta.engineDecision.adapter`, and `npm run verify:contract` passes |
+| **MUST**     | After ring 1 Game Designer STOP, spawn a temporary ref-flow atom-selection subagent before scaffold; do not select atoms inline as orchestrator                                                   |
+| **MUST**     | Archive Ring Gate snapshots through `ring:gate` / state helpers so the next ring inherits stable decisions, not prior-ring process noise                                                          |
+| **MUST NOT** | Role-play all five agents in one session when sub-agent invoke is available                                                                                                                       |
+| **MUST NOT** | Advance `iteration` without archiving prior ring in `archivedRings` (non-regression)                                                                                                              |
+| **MUST NOT** | Invoke `@technical-artist` before ring 4 Artist Wave 1 is `done`                                                                                                                                  |
+| **MUST NOT** | Advance `iteration` when a sub-agent could do it — **orchestrator owns** `iteration` / `loop` transitions                                                                                         |
+| **MUST NOT** | Advance to next iteration if post-STOP verification fails (required package, logs/evidence, Skill Preflight)                                                                                      |
+
+## Sub-agents only (Game Designer, Artist, TA, Developer, Reviewer)
+
+|              | Rule                                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST NOT** | Use `AskUserQuestion` for Ring Gate choices or final confirmations (Ring Gates remain orchestrator-only)                                                                                          |
+| **EXCEPT**   | Game Designer MAY use `AskUserQuestion` for gameplay brainstorm/clarification during `loop: clarify`                                                                                              |
+| **MUST**     | On verify-loop completion: sync `handoffContext` verdict + `ringGate: pending` + handoff (`waiting_for: orchestrator`, `next_orchestrator_action: npm run ring:gate -- --iteration N`) → **STOP** |
+| **MUST**     | Run Spec Quick-Check within 30s: TA when starting ring 4 build; Developer when starting any `loop: build`                                                                                         |
+| **MAY**      | Append concise downstream notes to `atom-tree.md` when actual reading/usage differs from the initial selection                                                                                    |
+| **MUST**     | Check `atom-tree.json` → `mediaGroups` for reusable assets before generating from scratch (Artist/TA)                                                                                             |
+| **MUST**     | Complete Skill Preflight (read relevant platform Skills) before production — TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight`; Artist: `artist-log § Skill Preflight` |
+| **MUST NOT** | Continue producing while `subagent_stop: true` and `waiting_for: orchestrator` (resume only when orchestrator clears handoff)                                                                     |
+| **MUST NOT** | Change `iteration` or `loop` (orchestrator only)                                                                                                                                                  |
+| **MUST NOT** | Skip required logs (`artist-log`, `ta-log`, `developer-log`, `review-report`)                                                                                                                     |
+| **MUST NOT** | Ignore `mediaGroups` matches and generate from scratch when a pre-matched asset exists — link/reuse first, skip only with documented reason                                                       |
+| **MUST**     | Complete [STOP sync checklist](collaboration.md#stop-sync-checklist) on every STOP, including structured `handoffContext`                                                                         |
+
+## Tool Surface Policy
+
+Role cards should list only the tools that role actually owns. Long command catalogs belong in role refs or Skills. If a command family moves to a specialist role, remove it from upstream roles instead of duplicating it.

package/project-templates/phaser/docs/team/agent-runtime-matrix.md

@@ -0,0 +1,80 @@
+# Agent Runtime Matrix
+
+> **Workflow spec**: `growth-rings-v1` — four growth rings, each with inner loops `clarify → build → verify → Ring Gate`. Legacy waterfall stages (`pm`, `storyboard`, `planning`, `development`, …) are **removed**.
+
+Fake-invoke reference: `(iteration, loop, contextPacket + handoff snapshot) → expected behavior / forbidden behavior`.
+
+See also: [agent-conduct.md](agent-conduct.md), [collaboration.md](collaboration.md) § Agent Handoff.
+
+## Game Designer
+
+| iteration | loop                  | handoff               | Expected                                                                               | Forbidden                                                                                          |
+| --------- | --------------------- | --------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| 1         | clarify               | no prior seed         | design-brief discovery + DESIGN seed + seed developer slice queue in sliceState → STOP | Full layout/style/CTA/plan/atom graph in ring 1; over-questioning; reverse-engineering hooks/gates |
+| 2         | clarify               | ring 1 archived       | Add gameplay periphery + layout intent context; deepen only disclosed contracts → STOP | Rewriting the seed or loading production docs                                                      |
+| 3         | clarify               | ring 2 archived       | Add Hook/CTA (Call To Action, 行动号召) intent and hand off style/storyboard context   | Starting production asset generation                                                               |
+| 4         | clarify/build routing | spec gap only         | Resolve contract gaps only when routed                                                 | Re-opening core gameplay without an explicit blocker                                               |
+| any       | —                     | `subagent_stop: true` | Reply **Already STOPPED**                                                              | Rewrite other agents' logs                                                                         |
+
+## Temporary Ref-flow Atom Selection
+
+| iteration | loop    | handoff              | Expected                                                                                                                                  | Forbidden                                                       |
+| --------- | ------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| 1         | clarify | after Game Designer  | Create compact `docs/atom-tree.json`; select engine + best gameplay trunk; validate; write engine/atoms handoff context; STOP to scaffold | Asking user; editing DESIGN/game; full product tree or planning |
+| 2+        | clarify | when explicitly sent | Deepen atom reading + implementation context from disclosed specs                                                                         | Filling execution status fields or replacing runtime owner work |
+
+## Developer
+
+| iteration | loop   | handoff                  | Expected                                                                                                                                                                                                                                                                                                                                                                                                     | Forbidden                                                                                                                                                                                                     |
+| --------- | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| any       | build  | contextPacket            | Skills auto-linked on atom-tree save (no manual `skills link`) → fill § Skill Preflight → load `playable-placeholder` skill → Tier 1 link → Tier 2 `placeholder:gen` + `placeholder:gen-audio` → Tier 3 fallback → `verify:placeholders` pass → keep one-click clear debug button (`?debug=1`) wired → `devStatus: ready` + `devUrl?debug=1` + feature status/validation/blockers in `handoffContext` → STOP | Code-draw instead of placeholder; editing `game/**` before § Skill Preflight filled (PreToolUse gate blocks it); removing the `?debug=1` clear button; devUrl without `?debug=1`; AI art/audio; visual polish |
+| 1         | build  | seed + compact atom-tree | Engine root + semantic placeholder playable spine; run `verify:contract` + `verify:lifecycle` + `verify:firstwin` (also enforces the `?debug=1` one-click clear button) + `verify:placeholders`; minimal docs only → STOP → `ring:gate`                                                                                                                                                                      | Require layout-spec / implementation-plan; invoke Reviewer; build full game shell                                                                                                                             |
+| 2         | build  | layout/plan disclosed    | Expand complete gameplay skeleton from layout intent + implementation context                                                                                                                                                                                                                                                                                                                                | Production visual polish or ad wrapping                                                                                                                                                                       |
+| 3         | build  | Hook/CTA disclosed       | Integrate Hook/CTA and ad packaging skeleton                                                                                                                                                                                                                                                                                                                                                                 | Bulk production assets                                                                                                                                                                                        |
+| 4         | build  | TA Wave 2 done           | Wire all TA assets: `TILE_KEYS`, loaders, bg layer; `verify:asset-code-sync` → STOP → `@reviewer ui_diff`                                                                                                                                                                                                                                                                                                    | Skip TA deliverables; invoke ui_diff before integration                                                                                                                                                       |
+| any       | verify | —                        | **Do not run** — Developer does not own verify loop                                                                                                                                                                                                                                                                                                                                                          | Run Reviewer modes                                                                                                                                                                                            |
+
+## Artist
+
+| iteration | loop   | handoff           | Expected                                                                                                               | Forbidden             |
+| --------- | ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| 1–2       | build  | —                 | No formal visual production; only placeholder-support notes when explicitly routed → STOP                              | ASR production        |
+| 3         | build  | Hook/CTA intent   | Style + MC (Master Composite, 主合成图) / ASR (Asset State Reference, 资产状态参考表) context → Skill Preflight → STOP | Production-grade PNGs |
+| 3         | verify | ASR context       | ASR coverage validation (ring 3 verify) → STOP                                                                         | Modify `game/`        |
+| 4         | build  | production wave 1 | Audio + digit strip + production handoff context (Wave 1) → STOP                                                       | TA bulk production    |
+
+## Technical Artist
+
+| iteration | loop   | handoff            | Expected                                                                                                                                                                              | Forbidden                                                 |
+| --------- | ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| 4         | build  | Artist Wave 1 done | Upstream Intake + Production Plan + bulk assets + production manifest / assetMapping fulfilment / compliance context → STOP → **`Invoke @developer (Ring 4 production integration)`** | Before Artist Wave 1; STOP → `@reviewer ui_diff` directly |
+| 4         | verify | routed findings    | Fix `ui_diff` routed items → STOP                                                                                                                                                     | Modify unrelated `game/` systems                          |
+
+## Reviewer
+
+| iteration | loop   | handoff                             | Expected                                                                                                                                            | Forbidden                                          |
+| --------- | ------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| any       | verify | `devStatus: ready`                  | ring 2+: `gameplay_conformance` (fill `gameplayConformance: pass/fail` — review-backed DoD gate) + `load_check` + structured verdict context → STOP | Judge subjective fun; ring 1 verify (script-owned) |
+| 3+        | verify | —                                   | `playable_validate` for hook/CTA → STOP                                                                                                             | Modify production files                            |
+| 4         | verify | TA + **developer integration** done | `ui_diff`: Read screenshots + Structured Visual Rubric; `uiDiff` pass/fail → STOP                                                                   | Advance `iteration`; pass on size tables only      |
+
+## Orchestrator
+
+| handoff                                                                      | Expected                                                                                                       | Forbidden                                |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `waiting_for: user_gate` + `subagent_stop: true` + `ringGateCanAskUser: yes` | Run **only** Ring Gate `AskUserQuestion`                                                                       | Invoke sub-agent / run `ring:gate` first |
+| `subagent_stop: true` + `waiting_for: orchestrator`                          | Execute **only** `next_orchestrator_action`                                                                    | Skip handoff read                        |
+| Before Ring Gate                                                             | `npm run ring:gate -- --iteration N` must pass                                                                 | Ask user before ring:gate                |
+| Ring 1 → build                                                               | atom-selection STOP + `init-template --from-atom-tree` + `verify:contract` + `verify:lifecycle` + marker match | Invoke `@developer` early                |
+| Ring Gate pass                                                               | Archive ring in `archivedRings`, `iteration+1`, `loop: clarify`                                                | Skip non-regression archive              |
+
+## Post-STOP verification (before iteration advance)
+
+| 验证项            | 方法                                                    | 失败处理            |
+| ----------------- | ------------------------------------------------------- | ------------------- |
+| Ring DoD complete | `npm run ring:gate -- --iteration N` exit 0             | Re-invoke agents    |
+| Non-regression    | `archivedRings` contains all prior rings                | Do not advance      |
+| `devStatus` ready | `devUrl` present (with `?debug=1`), `devBlockers` empty | Re-invoke developer |
+| Handoff coherence | `next_orchestrator_action` matches iteration/loop       | Re-invoke           |
+
+See [`agent-conduct.md`](agent-conduct.md) § Orchestrator only for the full MUST/NEVER list.