@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/docs/team/atom-tree-format.md

@@ -0,0 +1,114 @@
+# Atom Tree Format
+
+`docs/atom-tree.json` is the canonical machine-readable selection and product contract for the playable.
+
+Ring 1 uses it as a compact selection manifest. Rings 2+ may grow the optional product tree as more gameplay, layout, and production detail is disclosed:
+
+```text
+docs/atom-tree.json
+├── meta.engineDecision       required in ring 1
+├── meta.skillsMatch          required in ring 1
+├── meta.selectedAtoms        required in ring 1
+├── meta.selectionRevisions   optional revision log
+├── meta.rings                required gate metadata
+├── engine                    required engine atom
+├── globals                   optional ring 2+
+├── scenes                    optional ring 2+
+└── review                    optional review evidence
+```
+
+## Required Shape
+
+```jsonc
+{
+  "meta": {
+    "atomTreeSchemaVersion": 1,
+    "gate": 1,
+    "engineDecision": {
+      "mode": "explicit|inferred|unset",
+      "engine": "phaser",
+      "engineAtom": "phaser.aicomponent",
+      "adapter": "phaser",
+      "reason": "2D tile puzzle + tween/input/UI-heavy playable",
+      "runtimeContract": "window.__playable",
+    },
+    "skillsMatch": {
+      "engine": "phaser",
+      "engineSource": "explicit|inferred",
+      "intent": ["match3", "grid"],
+      "items": [{ "atomId": "match3_core.aigameplay" }],
+      "mediaGroups": [],
+    },
+    "selectedAtoms": ["match3_core.aigameplay", "phaser.aicomponent"],
+    "selectionRevisions": [],
+    "rings": {
+      "1": {
+        "goal": "first playable loop",
+        "requiredPaths": ["engine"],
+        "verifiers": ["contract", "lifecycle", "firstLevelWin", "placeholders"],
+        "acceptanceKeys": ["contract", "lifecycle", "firstLevelWin", "placeholders"],
+      },
+    },
+  },
+  "engine": "phaser.aicomponent",
+  "globals": {},
+  "scenes": [],
+  "review": {},
+}
+```
+
+## Field Rules
+
+- `meta.engineDecision` records the chosen engine root and the scaffold adapter. If engine choice is ambiguous, ask one question or set `designerAutoDecide=true` before scaffold.
+- `meta.skillsMatch` is written by `playcraft skills init-atom-tree`.
+- `meta.selectedAtoms` is the only source used by `playcraft skills link --from-atom-tree`.
+- `meta.rings[N]` defines the minimum verifiable slice for ring gate.
+- `engine` is required for scaffold. `globals` and `scenes` describe the product/content tree only when the current ring discloses enough detail.
+- `review` stores structured review evidence when needed.
+
+## Engine Adapter Boundary
+
+Fast Ring 1 assembly is selection-driven, not Phaser-specific:
+
+```text
+user intent
+→ skills match
+→ meta.engineDecision
+→ compact selectedAtoms
+→ selected engine adapter
+→ scaffold/runtime wiring
+→ neutral verifier contract
+```
+
+Examples:
+
+| engineAtom               | adapter      | Typical first scaffold                                      |
+| ------------------------ | ------------ | ----------------------------------------------------------- |
+| `phaser.aicomponent`     | `phaser`     | 2D (Two-Dimensional, 二维) scene, pointer input, tween loop |
+| `threejs.aicomponent`    | `threejs`    | 3D (Three-Dimensional, 三维) scene, camera, raycast input   |
+| `playcanvas.aicomponent` | `playcanvas` | PlayCanvas scene/app bridge                                 |
+| `canvas2d.aicomponent`   | `canvas2d`   | Canvas loop + pointer input                                 |
+
+All adapters must expose the same neutral runtime contract: `window.__playable`.
+Do not attach harness methods such as `start()` or `autoPlay()` to the engine object itself.
+
+## Companion Markdown
+
+`docs/atom-tree.md` is optional and generated with:
+
+```bash
+playcraft skills gen-atom-tree-md
+```
+
+It is only a reading guide for selected Skills. Do not use it as a second contract.
+
+## Do Not Add
+
+- `assignTo`
+- workflow `status`
+- `actualOutput`
+- implementation steps
+- chat history
+- implementation step tracking
+
+Those belong in `implementation-plan.md`, `project-state.md`, and role logs.

package/project-templates/phaser/docs/team/collaboration.md

@@ -0,0 +1,391 @@
+# Agent Collaboration Reference
+
+> **Workflow spec**: `growth-rings-v1` — four growth rings, each with inner loops `clarify → build → verify → Ring Gate`.
+
+## Role Quick Index
+
+Each role only needs specific sections of this document. Use this table to skip to what matters for you.
+
+| Role                 | Read these sections                                                                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Orchestrator**     | All (this is your primary protocol doc)                                                                                                        |
+| **dispatchPacket**   | Machine dispatch unit: `role + doWhat + flow + sliceId` from `npm run state:get`; supersedes ring-loop invoke wording when active slice exists |
+| **Game Designer**    | § STOP sync checklist, § Agent Handoff, § Four-doc discipline, § Spec Gap Protocol, § ICP                                                      |
+| **Developer**        | § STOP sync checklist, § Agent Handoff, § Developer in build loop, § Spec Gap Protocol, § Spec Quick-Check, § ICP, § Upstream rework routing   |
+| **Artist**           | § STOP sync checklist, § Agent Handoff, § Four-doc discipline, § ICP, § MC five panels                                                         |
+| **Technical Artist** | § STOP sync checklist, § Agent Handoff, § Four-doc discipline, § Spec Quick-Check, § ICP                                                       |
+| **Reviewer**         | § STOP sync checklist, § Agent Handoff, § UI rework sequence                                                                                   |
+
+---
+
+## Glossary
+
+Canonical terms used across `CLAUDE.md`, agent L1 files, and `refs/`. Prefer the **Canonical** column in new edits.
+
+| Canonical                        | Also called                                | Meaning                                                                                                                                                                                                                                                                                                                    |
+| -------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Growth ring** (iteration 1..4) | iteration, ring                            | Outer loop climbing the atom-tree: engine root → periphery → hook/CTA → production                                                                                                                                                                                                                                         |
+| **Inner loop**                   | clarify / build / verify                   | Per-ring collaboration cycle before Ring Gate                                                                                                                                                                                                                                                                              |
+| **Ring Gate**                    | user_gate, ring acceptance                 | One orchestrator-only user acceptance per ring after objective DoD passes (`npm run ring:gate`)                                                                                                                                                                                                                            |
+| **Ring DoD**                     | ringDoD, objective DoD                     | Machine-checkable verifiers per ring (`verify:contract`, `verify:lifecycle`, `verify:firstwin`, `record:mp4`, `verify:ui`, `playable_validate`, `ui_diff`, `verify:ui:assets`, …)                                                                                                                                          |
+| **Ring 1 package** (minimal)     | playable seed + compact atom selection     | Ring 1 clarify deliverable: a concise `docs/DESIGN.md` playable seed (player action, immediate feedback, progress signal, first win, semantic placeholders, engine hint). Then a temporary ref-flow subagent creates compact `atom-tree.*` selection for scaffold only; no design-brief/layout/full product tree in ring 1 |
+| **Handoff Context**              | shared working memory                      | Structured `handoffContext` in `docs/project-state.json`. `state:get` exposes it as `contextPacket`; agents read it before artifact refs and write it on STOP. Markdown docs remain contracts/evidence, not the default cross-role memory.                                                                                 |
+| **Asset Contract**               | Asset Path Contract, assetMapping contract | `layout-spec.md` `assetMapping` paths — **locked only after ring 4** (`assetMappingLocked: true`)                                                                                                                                                                                                                          |
+| **devUrl**                       | Dev URL, preview link                      | Local Dev server URL from `npm run dev`; orchestrator shares at each Ring Gate; user never runs dev themselves. **Always append `?debug=1`** so the on-screen one-click clear (debug) button is shown — every shared/recorded devUrl must carry `?debug=1`                                                                 |
+| **Artist depth by ring**         | —                                          | Ring 1–2: placeholder; Ring 3: ASR + style lock; Ring 4 Wave 1: audio + digit                                                                                                                                                                                                                                              |
+| **ASR Coverage Matrix**          | —                                          | `artist-log` table: every contract id → ASR slot; mandatory before ring 3 verify                                                                                                                                                                                                                                           |
+| **Palette Locked**               | —                                          | MC-sampled hex in `artist-log`; delta vs `layout-spec`                                                                                                                                                                                                                                                                     |
+| **growth-rings-v1**              | workflow spec version                      | Current workflow; supersedes `convergence-v1`, `production-serial-v1`, waterfall stages                                                                                                                                                                                                                                    |
+| **design_check**                 | Reviewer mode (legacy)                     | Soft checklist — completeness only; use sparingly in growth-rings; prefer ring DoD verifiers                                                                                                                                                                                                                               |
+| **gameplay_conformance**         | Reviewer mode (ring 2+ review-backed DoD)  | Verify DESIGN.md conformance + Skill usage evidence + playwright-cli path reachability; fill `gameplayConformance: pass/fail` in § Ring DoD Fields — `ring:gate` enforces it like `hookCta`/`uiDiff`                                                                                                                       |
+| **ui_diff**                      | Reviewer mode                              | Browser screenshots vs locked ASR; routes UI rework (max 5 rounds) during ring 4 verify                                                                                                                                                                                                                                    |
+| **load_check**                   | Reviewer mode                              | Page loads + no console errors; no gameplay walkthrough                                                                                                                                                                                                                                                                    |
+| **playable_validate**            | Reviewer mode                              | Ring 3+: hook/CTA + headed MP4 rules                                                                                                                                                                                                                                                                                       |
+| **Production Pipeline**          | serial waves in `project-state`            | Ring 4 only: Wave 1 Artist (audio + digit) → Wave 2 TA (bulk production)                                                                                                                                                                                                                                                   |
+| **Four-doc discipline**          | 四件套写作纪律                             | Game Designer/Artist: contracts only in four docs; narrative in style-exploration + artist-log; TA/Dev intake: agent-conduct + log templates                                                                                                                                                                               |
+| **TA Step 0 / 1 / 2**            | (not "Phase")                              | **TA cookbook only**: Step 0 = Skill Discovery; Step 1 = Asset Completion; Step 2 = Technical Pipeline — TA runs all three in one ring 4 build invoke                                                                                                                                                                      |
+| **uiReworkRound**                | —                                          | Counts **ui_diff failures** (0 → 5 max) during ring 4 verify; at 5 → orchestrator decision                                                                                                                                                                                                                                 |
+| **ICP**                          | Intent Clarification Protocol              | Async agent Q&A in `docs/intent-clarifications.md`; orchestrator does not interrupt user                                                                                                                                                                                                                                   |
+| **MC**                           | Master Composite                           | Five 9:16 panels in one image: concept panel + Hook / Onboarding / End Card / CTA storyboards (ring 3+)                                                                                                                                                                                                                    |
+| **ASR**                          | Asset State Reference Sheet                | UI + element state reference sheets; ring 3 build output; TA crop source in ring 4                                                                                                                                                                                                                                         |
+| **archivedRings**                | non-regression snapshot                    | Prior rings' passed DoD; must stay green when advancing iteration                                                                                                                                                                                                                                                          |
+| **Single developer build owner** | Developer                                  | Developer owns every ring's `build` loop: intake, read/load, implementation, integration, `devStatus` / `devUrl` / `devBlockers`                                                                                                                                                                                           |
+
+## Mission vs Role vs Workflow
+
+| Layer            | Location                         | Purpose                                                                               |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------- |
+| **Team Mission** | `CLAUDE.md` § Mission            | Shared vision — why we build playable ads                                             |
+| **Role Card**    | `.claude/agents/<role>.md`       | Who the role is, what it owns, boundaries, success criteria, workflow interface       |
+| **Workflow**     | `refs/` + dispatch-specific docs | How to execute the current task; varies by iteration/loop and orchestrator assignment |
+
+When instructions conflict: role ownership in the role card wins over workflow shortcuts. Enforceable MUST/NEVER: [agent-conduct.md](agent-conduct.md).
+
+## Ring Gate Protocol (Orchestrator-Only)
+
+Only the **Orchestrator** (main session) may use `AskUserQuestion` for **Ring Gate** confirmations. Sub-agents prepare materials, update `project-state`, then **STOP**.
+
+**Slice axis first**: When `state:get` reports `dispatchMode: true`, orchestrator dispatches by **`dispatchPacket` only** — do not tell subagents "Ring N build/verify". Ring Gate runs only after slice queue + objective DoD allow (see Knife 9).
+
+**Objective DoD first**: Before any Ring Gate, orchestrator runs `npm run ring:gate -- --iteration N`. The script spawns verifiers, checks non-regression of prior rings, and sets `ringGateCanAskUser`. If it fails, route back to the owning agent — **do not** ask the user.
+
+**Exception**: Game Designer uses `AskUserQuestion` for gameplay brainstorm/clarification during `loop: clarify` — this is requirement gathering, NOT a Ring Gate.
+
+### Ring 1 engine scaffold (orchestrator, before build)
+
+After Game Designer ring 1 clarify STOP and **before** invoking `@developer`:
+
+```bash
+temporary ref-flow atom-selection subagent       # creates compact docs/atom-tree.json
+playcraft skills validate-atom-tree-selection
+playcraft remix init-template --from-atom-tree
+npm install && npm run verify:contract && npm run verify:lifecycle
+```
+
+- Writes `game/` from `engine-packs/{phaser|threejs}`, `.playcraft-engine`, and `docs/scaffold-manifest.md`.
+- `npm run workflow:doctor` **BLOCKED** if `.playcraft-engine` ≠ `meta.engineDecision.adapter`, or if marker missing during ring 1 `loop: build`.
+- **Do not** silently overwrite `game/` during selection — engine scaffold is always explicit via `init-template`.
+
+See [core-model.md § Command Contract](core-model.md#command-contract) and [harness-legacy-deprecation.md](harness-legacy-deprecation.md).
+
+### Per-ring flow
+
+| Step | Loop    | Agent(s)                                        | STOP → next                                                                                                                                                                                           |
+| ---- | ------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | clarify | `@game-designer` → temporary ref-flow selector  | Orchestrator → ring 1: context packet + compact atom selection → `init-template` + `verify:contract` first → `loop: build` → `@developer`                                                             |
+| 2    | build   | `@developer` (+ Artist/TA per ring)             | Ring 1: Developer self-gate (`verify:contract` + `verify:lifecycle` + `verify:firstwin` + `verify:placeholders`) → `loop: verify` → orchestrator `ring:gate`; ring 2+: → `loop: verify` → `@reviewer` |
+| 3    | verify  | ring 1: orchestrator only; ring 2+: `@reviewer` | Orchestrator → `npm run ring:gate -- --iteration N`                                                                                                                                                   |
+| 4    | —       | **Orchestrator only**                           | If pass → Ring Gate `AskUserQuestion` at devUrl → archive ring → `iteration+1`, `loop: clarify`                                                                                                       |
+
+### Ring DoD by iteration
+
+| Ring  | Objective DoD (via `ring:gate`)                                                                                                     |
+| ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **1** | `verify:contract` + `verify:lifecycle` (HOOK → autoPlay → ENDCARD) + `verify:firstwin` + `verify:placeholders`                      |
+| **2** | Ring 1 DoD + disclosed UI / MP4 evidence gates                                                                                      |
+| **3** | Ring 2 DoD + Reviewer `playable_validate` (hook/CTA)                                                                                |
+| **4** | Ring 3 DoD + Reviewer `ui_diff` + `verify:ui:assets` + `verify:atom-conformance` (when present) + `verify:visual` (when ASR locked) |
+
+After ring 4 Ring Gate pass → project **done** (user accepts devUrl; not `playcraft build`).
+
+Sub-agent pattern: **write artifacts → update `handoffContext` + routing handoff + ringDoD → STOP (no user questions).**
+
+## Agent Handoff
+
+State lives in **`docs/project-state.json`** (machine source of truth). `docs/project-state.md` is a GENERATED, read-only view (including the `## Agent handoff` YAML fence) re-rendered after every write. **Read with `npm run state:get`, write with `npm run state:set` / `npm run ring:gate`. Never open or hand-edit the markdown.**
+
+There are two handoff layers:
+
+- `handoffContext` = shared working memory for the next role. It records ring summary, last role decisions/evidence, next role facts, stable shared decisions, and blockers.
+- `handoff` YAML fields = routing flags for STOP / resume / Ring Gate.
+
+Agents read `contextPacket` from `state:get` first, then open only required files or artifact refs named in that packet. Logs and markdown docs are traceable evidence, not the default memory every role must reload.
+
+| Field                      | Writer                                                                                            | Meaning                                                                                                                                         |
+| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `iteration`                | Orchestrator on ring advance                                                                      | Current growth ring 1..4                                                                                                                        |
+| `loop`                     | Orchestrator on loop transition                                                                   | `clarify` \| `build` \| `verify`                                                                                                                |
+| `ringGoal`                 | Orchestrator / Designer on clarify                                                                | Human-readable ring scope                                                                                                                       |
+| `ringGate`                 | Sub-agent on verify STOP                                                                          | `pending` until orchestrator confirms user acceptance                                                                                           |
+| `ringDoD`                  | Sub-agents + `ring:gate` runner                                                                   | Objective verifier status map                                                                                                                   |
+| `archivedRings`            | Orchestrator on Ring Gate pass                                                                    | Non-regression snapshot of prior rings                                                                                                          |
+| `subagent`                 | Sub-agent on STOP                                                                                 | Role that just finished (`game-designer`, temporary `skill-selector`/`ref-flow`, `artist`, `technical-artist`, `developer`, `reviewer`, `none`) |
+| `subagent_stop`            | Sub-agent on STOP                                                                                 | `true` = do not continue until orchestrator acts                                                                                                |
+| `waiting_for`              | Sub-agent: `orchestrator` on STOP; Orchestrator: `user_gate` only after `ringGateCanAskUser: yes` | `user_gate` = Ring Gate only; `orchestrator` = wait for invoke; `none` = active work                                                            |
+| `next_orchestrator_action` | Sub-agent on STOP (**required**)                                                                  | One sentence: the **only** legal next step for orchestrator                                                                                     |
+| `last_completed_by`        | Sub-agent on STOP                                                                                 | Same as `subagent` or action label                                                                                                              |
+| `block_reason`             | Optional                                                                                          | Why pipeline cannot advance                                                                                                                     |
+
+### `handoffContext` structure
+
+| Field             | Writer                       | Meaning                                                                                  |
+| ----------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
+| `ring`            | Orchestrator / gate runner   | Current ring summary, goal, and passed DoD (Definition of Done, 完成定义)                |
+| `lastRole`        | Stopping sub-agent           | Previous role summary, key decisions, `artifactRefs`, validation results, blockers       |
+| `nextRole`        | Stopping sub-agent           | Next role, must-know facts, required files, forbidden full-read files, artifact refs     |
+| `sharedDecisions` | Roles as decisions stabilize | Cross-role stable facts: engine, core action, semantic placeholders, asset contract refs |
+| `openQuestions`   | Any role                     | Only unresolved questions that block the next step                                       |
+
+**Orchestrator loop:** read handoff → if `waiting_for: user_gate` and `ringGateCanAskUser: yes` → Ring Gate only → else if `subagent_stop` → execute `next_orchestrator_action` → reset handoff before invoke.
+
+**Sub-agent verify STOP:** set `waiting_for: orchestrator` and `next_orchestrator_action: npm run ring:gate -- --iteration N` — **never** `waiting_for: user_gate`.
+
+**Sub-agent loop:** read handoff → if already stopped for this role → refuse duplicate work → else read role card + workflow → update handoff → append `--- PLAYCRAFT_STOP ---` footer.
+
+### Updating handoff (use `state:set`, never hand-edit md)
+
+Agents **must** update state via the CLI helper — do **not** use `python3 -c`, `sed`, or edit `docs/project-state.md`/`.json` by hand (error-prone, and md edits are overwritten on the next render):
+
+```bash
+npm run state:get -- iteration loop subagent_stop waiting_for
+npm run state:set -- contextRole=game-designer contextSummary="Playable seed locked: tap target -> immediate feedback -> first win" contextNextRole=ref-flow contextArtifactRefs=docs/DESIGN.md contextCoreAction="tap target" contextSemanticPlaceholders="player;target;feedback;reward" contextMustKnow="Use DESIGN.md as playable seed only; select engine + compact gameplay trunk" contextRequiredFiles="docs/DESIGN.md"
+npm run state:set -- subagent_stop=true waiting_for=orchestrator next_orchestrator_action="Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection" last_completed_by=game-designer
+```
+
+- Values with spaces: quote the whole `key=value` in shell, or pass as `next_orchestrator_action="npm run ring:gate -- --iteration 1"`.
+- Keys route automatically: handoff keys → handoff block; `devStatus` / `devUrl` / `loadCheck` / `uiReviewStatus` / … → Dev Preview; `ringGate*` → Ring Gate Runner. The renderer always emits every table, so a write never silently no-ops on a missing row.
+- Structured sub-operations: `npm run state:set -- --checkpoint "ring 1 self-gate passed" --by developer` appends a Progress Checkpoint; `npm run state:set -- --wave id=1 owner=artist status=done` sets a Production Pipeline wave row.
+- Read single keys with `npm run state:get -- --json waiting_for next_orchestrator_action` to avoid pulling the whole state.
+- Full context patch: `npm run state:set -- handoffContextPatch='{"lastRole":{"validation":["verify:firstwin pass"]}}'`.
+
+## Developer in `build` loop
+
+`developer` is the **build-loop owner** for every growth ring.
+
+During `loop: build`, Developer is responsible for:
+
+- upstream intake and Spec Quick-Check (depth scales per ring)
+- read/load of current on-disk code, scaffolded code, linked assets, and Skill refs
+- placeholder materialization (`playable-placeholder` skill) in rings 1–3
+- implementation and integration
+- feature-checklist review (ring 2+)
+- `npm run dev`, `devStatus`, `devUrl`, and `devBlockers`
+
+`logs/developer-log.md` is the development truth log: intake, read/load notes, feature checklist, verification, blockers, and readiness rationale.
+
+## STOP sync checklist
+
+On every sub-agent STOP, update **in order** (see [agent-conduct.md § Invoke protocol](agent-conduct.md#invoke-protocol-all-sub-agents)):
+
+1. **handoff** — `npm run state:set -- subagent_stop=true waiting_for=orchestrator next_orchestrator_action="…" last_completed_by=<role>` — **do not** transition `iteration` / `loop`.
+2. **ringDoD** — set fields Reviewer or build loop completed (`npm run state:set -- …` or `npm run ring:gate`).
+3. **Progress Checkpoint** — `npm run state:set -- --checkpoint "<action/outcome>" --by <role>` (programmatic append; never hand-write a table row).
+4. **Production Pipeline** — when ring 4 build, `npm run state:set -- --wave id=N owner=<role> status=done notes="…"` when a wave completes.
+5. **Plan convergence (TA / Developer / Reviewer / Game Designer)** — required logs and handoff fields complete. Hook `validate-workflow-stop.mjs` enforces on STOP.
+
+Example Production Pipeline (ring 4):
+
+| Wave | Agent            | Status | Notes                           |
+| ---- | ---------------- | ------ | ------------------------------- |
+| 1    | Artist           | done   | Ph.2: BGM + SFX + digit strip   |
+| 2    | Technical Artist | done   | All TA atoms + Compliance green |
+
+Checkpoint is a **human log** for evidence — **not** the routing source (`handoff`) or shared working memory (`handoffContext`).
+
+## Iteration field ownership
+
+| Field / transition                             | Writer                                     |
+| ---------------------------------------------- | ------------------------------------------ |
+| `iteration`, `loop`, `ringGoal`                | **Orchestrator only** (on handoff execute) |
+| `ringGate: passed` + `archivedRings` update    | **Orchestrator** after Ring Gate pass      |
+| `ringDoD` verifier fields                      | Sub-agents + `ring:gate` runner            |
+| `selectedMcOption`                             | Orchestrator during ring 3 style lock      |
+| `assetMappingLocked: true`                     | Orchestrator after ring 4 Ring Gate pass   |
+| `devStatus`, `devUrl`, `devBlockers`           | Developer                                  |
+| `uiReviewStatus`, `uiReworkRound`, `loadCheck` | Reviewer                                   |
+
+Sub-agents **MUST NOT** change `iteration` or `loop`. They request orchestrator via `next_orchestrator_action`.
+
+## UI rework sequence (ring 4 verify, orchestrator-owned)
+
+During ring 4 `loop: verify`:
+
+1. **Reviewer** (`ui_diff`) — screenshots vs locked ASR → fail: UI Diff Report in `review-report.md`, `uiReworkRound` +1, handoff `next_orchestrator_action: "Invoke routed agents per review-report, then @reviewer ui_diff"` → STOP.
+2. **Orchestrator** — invoke `@developer` / `@technical-artist` / `@artist` per Action Items (`routeTo`).
+3. **Fix agents** — apply fixes → handoff `Invoke @reviewer ui_diff` → STOP.
+4. **Orchestrator** — invoke `@reviewer ui_diff` again; on pass → `npm run ring:gate -- --iteration 4` → Ring Gate.
+
+Max **5** UI rework rounds (`uiReworkRound`). At 5 → orchestrator decision (proceed to Ring Gate or escalate to user).
+
+Gameplay quality = user judgment at Ring Gate — Reviewer checks conformance + load safety only.
+
+## Optimization sequence (optional, ring 4+)
+
+Optional deep pass after ring 4 `ui_diff` pass and before final Ring Gate (or user requests "optimize"):
+
+1. **Orchestrator** — invoke `@reviewer playable_validate` (may already be part of ring 3 DoD).
+2. **Reviewer** — `verify:ui` → `record:mp4` headed → video validate rules → write report + routeTo → STOP.
+3. **Orchestrator** — route fixes or proceed to Ring Gate.
+
+Max **3** optimization rounds (at 3 → orchestrator decision).
+
+## Spec Gap Protocol
+
+`spec-gap` means an upstream contract hole is blocking downstream work.
+
+| Trigger role | Typical trigger                                              | Required action                                                      |
+| ------------ | ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| TA           | Missing size/format/path/atlas clarity in `layout-spec.md`   | Write `spec-gap` into `project-state.md` and route to Game Designer  |
+| Developer    | Missing contract path, unclear asset binding, atom ambiguity | Record blocker in `devBlockers` / handoff and route to Game Designer |
+
+Rules:
+
+- Raise within quick-check, not after long speculative work.
+- Game Designer patches the relevant contract document.
+- Use `block_reason: spec-gap` when the pipeline must pause.
+
+## Intent Clarification Protocol (ICP)
+
+Primary file: `docs/intent-clarifications.md`
+
+- Continue with reasonable assumptions when safe.
+- Use ICP when ambiguity materially affects direction, quality, or delivery.
+- Game Designer arbitrates gameplay/spec intent conflicts.
+- Orchestrator does not interrupt the user for internal ICP traffic.
+
+| Need                                                 | Route               |
+| ---------------------------------------------------- | ------------------- |
+| Contract ambiguity, gameplay vs spec conflict        | `@game-designer`    |
+| Missing visual sample / supplementary isolated asset | `@artist`           |
+| Asset production / format / atlas / extraction issue | `@technical-artist` |
+| Runtime binding / implementation path issue          | `@developer`        |
+
+## Master Composite — five panels
+
+| Name                  | Panel | Role                                                                     |
+| --------------------- | ----- | ------------------------------------------------------------------------ |
+| **Concept panel**     | 1     | All key element types + static text + full UI; TA primary extract source |
+| **Storyboard panels** | 2–5   | Hook / Onboarding / End Card / CTA — Developer scene reference           |
+
+Produced during ring 3 style direction (storyboard subagent or Artist flow).
+
+## User interaction model (three phases)
+
+| Phase                | User                                                                                           | Agents                                                                                           |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **A — Choose**       | Game Designer brainstorms during `loop: clarify`; **Orchestrator** confirms each **Ring Gate** | Sub-agents STOP when loop complete; minimal user interruption during build                       |
+| **B — Produce**      | Not interrupted for terminal commands                                                          | Serial ring 4: Artist Wave 1 → TA Wave 2 → Developer integration; UI rework during ring 4 verify |
+| **C — Dev delivery** | Open **devUrl** (with `?debug=1`) from orchestrator at each **Ring Gate**                      | Developer owns dev preview; Reviewer conformance; user judges fun/quality at Ring Gate           |
+
+**User never runs `npm run dev`.** Delivery endpoint = Dev URL acceptance (`done`), not `playcraft build`.
+
+## Agent responsibility matrix (priority order)
+
+| #        | Game Designer                                            | Artist                                                       | Technical Artist                                     | Developer                                                  | Reviewer                                           |
+| -------- | -------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------- |
+| **1**    | Experience contracts per ring (`DESIGN`, layout-spec, …) | Placeholder (ring 1–2) → ASR/style (ring 3) → audio (ring 4) | Style-faithful mass production (ring 4)              | Build-loop convergence + dev preview ownership             | `gameplay_conformance` + `load_check` every verify |
+| **2**    | Zero-ambiguity specs (depth grows per ring)              | ASR Coverage Matrix, Palette Locked (ring 3+)                | 100% `assetMapping` at spec (ring 4)                 | Placeholder-first assets (rings 1–3); integration (ring 4) | `playable_validate` (ring 3+), `ui_diff` (ring 4)  |
+| **3**    | ICP; spec-gap arbitration                                | Style Intent Notes; respond to rework routes                 | Bulk production; respond on `routeTo: ta` in ui_diff | `devUrl` / `devBlockers`; route upstream via ICP           | Fill Ring DoD Fields; increment `uiReworkRound`    |
+| **Last** | —                                                        | —                                                            | —                                                    | `playcraft build` = **future**, not `done`                 | —                                                  |
+
+Full detail: `.claude/agents/<role>.md` § Goals.
+
+## Project Directory — What Exists vs What Agents Create
+
+```
+<project-root>/                     ← playcraft create <name> 初始化后
+│
+├── CLAUDE.md                       ✅ 协作总纲 (growth-rings-v1)
+├── .claude/agents/                 ✅ 5 个 Agent 指令 + refs/
+├── docs/team/agent-conduct.md      ✅ MUST/NEVER 行为契约
+├── templates/                      ✅ 只读模板
+│
+├── docs/project-state.json         ⏳ state-store machine truth
+├── docs/project-state.md           ⏳ generated read-only view
+├── docs/DESIGN.md                  ⏳ Ring 1 clarify（唯一交付物）
+├── docs/design-brief.md            ⏳ Ring 2+ 过程日志（Ring 1 不创建）
+├── docs/atom-tree.json             ⏳ 逐环增长
+├── docs/layout-spec.md             ⏳ Ring 2+ clarify
+├── docs/implementation-plan.md     ⏳ Ring 2+ build 前
+├── docs/style-exploration.md       ⏳ Ring 3+
+│
+├── game/**                         ⏳ Developer build loop
+├── assets/**                       ⏳ Artist + TA (深度随环递进)
+└── logs/*.md                       ⏳ 各角色工作日志
+```
+
+## Directory Conventions
+
+```
+<project-root>/
+├── docs/                  Design documents
+├── assets/                Visual/audio/model assets
+├── game/                  Runtime code (Developer)
+├── logs/                  Work logs + review report
+├── ta-workspace/          TA batch scripts + temp
+└── templates/             Read-only reference templates
+```
+
+## File Read/Write Matrix
+
+| File/Directory              | Game Designer    | Artist              | **TA**                   | Developer                     | Reviewer         |
+| --------------------------- | ---------------- | ------------------- | ------------------------ | ----------------------------- | ---------------- |
+| `docs/project-state.json`   | via `state:set`  | via `state:set`     | via `state:set`          | via `state:set` / `dev:start` | via `state:set`  |
+| `docs/project-state.md`     | Generated view   | Do not edit/open    | Do not edit/open         | Do not edit/open              | Do not edit/open |
+| `docs/design-brief.md`      | Create           | Read                | Read                     | Read                          | Read             |
+| `docs/layout-spec.md`       | Create (ring 2+) | **Read (contract)** | **Read (contract)**      | **Read (contract)**           | Read             |
+| `docs/atom-tree.json`       | Read             | Read                | Read                     | Read                          | Read             |
+| `docs/style-exploration.md` | —                | Create (ring 3+)    | **Read**                 | Read                          | Read             |
+| `assets/images/`            | —                | **Create**          | **Create (completions)** | Read                          | Read             |
+| `assets/audio/`             | —                | **Create**          | **Post-process**         | Read                          | Read             |
+| `game/`                     | —                | —                   | —                        | **Create / Update**           | Read             |
+| `logs/artist-log.md`        | —                | Create+Update       | Read                     | Read                          | Read             |
+| `logs/ta-log.md`            | —                | —                   | **Create**               | Read                          | Read             |
+| `logs/developer-log.md`     | —                | —                   | —                        | Create+Update                 | Read             |
+| `logs/review-report.md`     | —                | —                   | —                        | —                             | Create           |
+
+## Four-doc discipline
+
+| Layer                | Files                                                 | Writer                             | Content rule                                      |
+| -------------------- | ----------------------------------------------------- | ---------------------------------- | ------------------------------------------------- |
+| **Contracts**        | `project-state`, `DESIGN`, `layout-spec`, `atom-tree` | Game Designer + temporary ref-flow | Key fields only — no process chatter in contracts |
+| **Visual narrative** | `style-exploration`, `logs/artist-log`                | Artist                             | MC/ASR intent, Handoff Pack, Coverage Matrix      |
+| **Production proof** | `logs/ta-log`, `logs/developer-log`                   | TA / Developer                     | Upstream Intake + pipeline / implementation logs  |
+
+Enforceable rules: [agent-conduct.md](agent-conduct.md).
+
+## Spec Quick-Check
+
+Within 30 seconds at loop entry:
+
+| Checker   | When                            | Checks                                                        | On Gap                                                                       |
+| --------- | ------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| TA        | Ring 4 build, Wave 2 (TA entry) | Every assetMapping entry has clear size/format specs          | Write `spec-gap` to project-state.md, Game Designer supplements within 5 min |
+| Developer | Any `loop: build` start         | Every GameplayAtom reference exists in assetMapping (ring 2+) | Same                                                                         |
+
+## Upstream rework routing (Dev blockers)
+
+| `routeTo`         | Trigger                                                              | Orchestrator action                                 |
+| ----------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| **TA**            | Missing file, wrong size/format, style drift in mass-produced assets | Re-invoke `@technical-artist` → then `@developer`   |
+| **Artist**        | Wrong/missing sample, audio mood, supplementary art                  | Re-invoke `@artist` → then `@developer`             |
+| **Game Designer** | Contract ambiguity, gameplay vs spec conflict                        | `@game-designer` arbitrates ICP → then `@developer` |
+
+Developer sets `devStatus: blocked_upstream` and **STOPs** until rework completes.
+
+## Selection Revision Protocol
+
+- **Default**: follow current shortlist from `atom-tree.*`
+- **Allowed**: refine `meta.selectedAtoms`, `skillsMatch`, reusable media when new evidence appears
+- **Record where**: `docs/atom-tree.json` + `docs/atom-tree.md` § Revision Notes
+- **Stop for direction changes**: switching gameplay/style/product direction → report back

package/project-templates/phaser/docs/team/core-model.md

@@ -0,0 +1,85 @@
+# Core Model — Atom Tree as the Single Structured Contract
+
+## One Structured Source
+
+```text
+Product Contract
+├── atom-tree.json          ←唯一结构化真源
+├── DESIGN.md              ←人读体验契约
+└── layout-spec.md          ←人读路径/资产契约
+
+Execution Layer
+├── implementation-plan.md
+├── project-state.md
+└── role logs
+
+Optional Reading Guide
+└── atom-tree.md            ←由 atom-tree 生成，不是 handoff 必需文件
+```
+
+## Responsibilities
+
+| File                          | Purpose                                                                 | Contains                                                                                               | Must not contain                  |
+| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| `docs/atom-tree.json`         | Selected Skill contract first; product/content blueprint when disclosed | `meta.skillsMatch`, `meta.selectedAtoms`, `meta.rings`, `engine`, optional `globals`/`scenes`/`review` | role chatter, implementation logs |
+| `docs/DESIGN.md`              | Human-readable player promise                                           | core loop, first-level win, hook/CTA, constraints                                                      | duplicated selected Skill catalog |
+| `docs/layout-spec.md`         | Human-readable layout and asset paths                                   | zones, assetMapping, palette, sizes                                                                    | execution tracking / atom status  |
+| `docs/implementation-plan.md` | Developer execution plan                                                | feature order, module decisions, risks, acceptance path                                                | duplicated product tree           |
+| `docs/project-state.json`     | Workflow cursor machine truth                                           | iteration, loop, ringDoD, handoff, blockers, **sliceState**, dispatch via `state:get`                  | product/source-of-truth decisions |
+| `docs/project-state.md`       | Generated state view                                                    | rendered state tables for humans                                                                       | manual edits or required reading  |
+
+## Slice queue (execution axis)
+
+Structured product truth remains `atom-tree.json` + human docs. **Daily dispatch** when seeded:
+
+- `sliceState.slices[]` — minimal playable slices (`sliceId`, `role`, `doWhat`, `flow`, `verifier`, …)
+- `state:get` → `dispatchPacket` — orchestrator invoke unit; **not** ring loop names
+- Ring `meta.rings[N]` — budget / required paths / acceptance keys for outer gates, not subagent self-routing
+
+## Atom Tree Meaning
+
+`docs/atom-tree.json` is the only structured handoff file.
+
+It answers:
+
+- What playable content exists when disclosed: engine, globals, scenes, layers, entities, rules, media.
+- Which engine root was chosen and which scaffold adapter should be used: `meta.engineDecision`.
+- Which Skill matches were considered: `meta.skillsMatch`.
+- Which reusable atoms are selected and linked: `meta.selectedAtoms`.
+- Which ring slice is currently required: `meta.rings[N].requiredPaths`.
+- Which objective verifiers prove the ring: `meta.rings[N].verifiers` / `acceptanceKeys`.
+
+## Engine-Neutral Fast Path
+
+Fast assembly must not hard-code a single engine. The invariant is:
+
+```text
+atom-tree engine root → engine adapter scaffold → window.__playable contract → shared verifier
+```
+
+`phaser.aicomponent`, `threejs.aicomponent`, `playcanvas.aicomponent`, and future engine atoms may initialize differently. They are unified only at the runtime contract and verifier boundary. Harness methods belong on `window.__playable`; engine objects such as Phaser.Game must stay unmodified.
+
+## Command Contract
+
+- Initialize: `playcraft skills init-atom-tree --intent "..."`
+- Apply engine scaffold: `playcraft remix init-template --from-atom-tree` (reads `meta.engineDecision.adapter`, writes `game/` + `.playcraft-engine`)
+- Select: `playcraft skills select-atom --id "<atomId>"`
+- Validate: `playcraft skills validate-atom-tree-selection`
+- Link: `playcraft skills link --from-atom-tree --prune`
+- Optional guide: `playcraft skills gen-atom-tree-md`
+
+**Ring 1 agent chain (legacy growth-rings — when no active slice):**
+
+```text
+@game-designer → seed sliceState + design-brief + DESIGN.md (slice-axis primary)
+  OR legacy: temporary ref-flow atom-selection subagent
+playcraft remix init-template --from-atom-tree
+npm install && npm run verify:contract
+→ orchestrator dispatches @developer via dispatchPacket (not "Ring 1 build" wording)
+```
+
+## Boundaries
+
+- `atom-tree.json` may contain structural dependencies and selected atom refs.
+- `atom-tree.json` must not become a task tracker with `assignTo`, `status`, or `actualOutput`.
+- `atom-tree.md` is generated reading guidance only; if it disagrees with `atom-tree.json`, the JSON wins.

package/project-templates/phaser/docs/team/game-designer-migration-todo.md

@@ -0,0 +1,8 @@
+# Game Designer migration todo (growth-rings-v1)
+
+> **Status**: Superseded by growth-rings-v1 migration (2026-06). Kept for audit trail only.
+
+| Location                                               | Legacy item               | Resolution in growth-rings-v1                                     | Status |
+| ------------------------------------------------------ | ------------------------- | ----------------------------------------------------------------- | ------ |
+| `.claude/agents/game-designer.md`                      | Gate #1 Deliverable Card  | Ring 1 clarify deliverables in role card + collaboration glossary | done   |
+| `.claude/agents/refs/game-designer-workflow-detail.md` | Atlas grouping at Gate #1 | Atlas grouping at ring 2 layout-spec lock                         | done   |