@playcraft/cli 0.0.44 → 0.0.46

package/project-template/docs/team/agent-runtime-matrix.md

@@ -1,94 +1,80 @@
 # Agent Runtime Matrix
 
-> **Workflow spec**: `convergence-v1` (see [`workflow-changelog.md`](workflow-changelog.md)). Legacy stages `integration` / `review` / `rework` and fields `reworkRound` / `reviewerDevCheck` are **removed** — replaced by `ui_pass` / `ui_review` / `ui_rework` / `gameplay_pass` and `uiReworkRound` / `devStatus` / `loadCheck`.
+> **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: `(stage, gates snapshot, handoff snapshot) → expected behavior / forbidden behavior`.
+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, [workflow-consistency-checklist.md](workflow-consistency-checklist.md).
+See also: [agent-conduct.md](agent-conduct.md), [collaboration.md](collaboration.md) § Agent Handoff.
 
-## PM
+## Game Designer
 
-| stage        | gates            | handoff                               | Expected                                                                                            | Forbidden                                      |
-| ------------ | ---------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| `pm`         | `#1` not started | —                                     | Write four docs (project-state, design-brief, layout-spec, atom-plan) → `gates.#1 = pending` → STOP | Skip four docs; set `stage: style_exploration` |
-| `pm`         | `#1 = pending`   | `gate_pending: "1"`, `user_gate`      | Orchestrator runs Reviewer `design_check` Gate #1 → then Gate #1 only                               | Invoke designer before Gate #1 pass            |
-| `production` | `#1 = passed`    | `block_reason: spec-gap`              | Patch `layout-spec` / `atom-plan` per spec-gap entry ≤ 5 min → STOP                                 | Re-open Gate #1; rewrite four docs             |
-| any          | —                | `subagent: pm`, `subagent_stop: true` | Reply **Already STOPPED** — do nothing                                                              | Rewrite four docs                              |
+| 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                                                                         |
 
-## Designer
+## Temporary Ref-flow Atom Selection
 
-| stage                       | gates                                  | handoff                                         | Expected                                                                                                             | Forbidden                                                          |
-| --------------------------- | -------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `style_exploration`         | `#2a` not passed                       | —                                               | Phase 1 Skill Discovery → MC ≥2 options → `gates.#2a = pending` → STOP                                               | Skip Skill Discovery; MC before art-style-guide                    |
-| `style_exploration`         | `#2a = pending`                        | `gate_pending: "2a"`, `user_gate`               | Orchestrator runs Gate #2a only                                                                                      | Present A/B/C choice to user in chat                               |
-| `style_exploration`         | `#2a = passed`, `selectedMcOption` set | —                                               | ASR 双板 (UI + element) + Handoff Pack → `gates.#2b = pending` → STOP                                                | Regenerate MC options                                              |
-| `style_exploration`         | `#2b = pending`                        | `gate_pending: "2b"`, `user_gate`               | Orchestrator runs Reviewer `design_check` Gate #2b → then Gate #2b                                                   | Start Phase 2 audio before Gate #2b pass                           |
-| `production`                | `#2b = passed`                         | —                                               | Ph.2: audio + digit strip + VisualAtom status (ASR-covered → done) → STOP when all `assignTo: Designer` atoms `done` | Set mainline `stage`; batch produce element PNGs at `assetMapping` |
-| `ui_rework`                 | —                                      | `block_reason: routeTo Designer`                | Fix report paths only (audio mood, ICP supplementary PNG) → STOP                                                     | Full style re-exploration                                          |
-| `ui_pass` / `gameplay_pass` | —                                      | `devStatus: blocked_upstream`, routeTo Designer | Upstream blocker fixes per `developer-log` → STOP                                                                    | Modify `game/`                                                     |
+| 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 |
 
-## Technical Artist
+## Developer
 
-| stage                       | gates                       | handoff                                             | Expected                                                                                                                                                            | Forbidden                                      |
-| --------------------------- | --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| `production`                | `#2b = passed`, Wave 1 done | —                                                   | Step 0a Upstream Intake → Step 0 Pre mediaGroups → Skill Preflight → Style Interpretation → Production Plan → Step 0e Transparency → bulk → Compliance green → STOP | Start before Designer Wave 1 done; set `stage` |
-| `ui_pass`                   | —                           | `devStatus: blocked_upstream`, routeTo TA           | Fix listed paths only → re-Compliance affected items → STOP                                                                                                         | Run `npm run dev`; design new elements         |
-| `ui_rework`                 | —                           | Action Items routeTo TA                             | Fix `ui_diff` report items at contract paths → STOP                                                                                                                 | Redefine MC; modify `game/`                    |
-| `ui_pass` / `gameplay_pass` | —                           | `subagent: technical-artist`, `subagent_stop: true` | Reply **Already STOPPED**                                                                                                                                           | Continue producing                             |
+| 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                                                                                                                                                                                            |
 
-## Developer
+## 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
 
-| stage           | gates | handoff                        | Expected                                                                                                                                         | Forbidden                                                                                       |
-| --------------- | ----- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `production`    | —     | —                              | **Do not run** — orchestrator invokes Developer only in `ui_pass` / `gameplay_pass` / `ui_rework`                                                | Any `game/**` work in `production`                                                              |
-| `ui_pass`       | —     | —                              | Upstream Intake → Spec Quick-Check → Skill Preflight → UI Pass Plan → bind real assets → `npm run dev` → `devStatus: ui_ready` + `devUrl` → STOP | Implement gameplay rules (PGS / scoring / win-lose); set `devStatus: ready`                     |
-| `ui_pass`       | —     | `devStatus: ui_ready`          | Handoff `next_orchestrator_action: "Invoke @reviewer ui_diff"` → STOP                                                                            | Skip Reviewer invoke; advance to `gameplay_pass`                                                |
-| `ui_review`     | —     | —                              | **Do not run** — Reviewer's turn                                                                                                                 | Edit `game/**`                                                                                  |
-| `ui_rework`     | —     | Action Items routeTo Developer | Fix UI Diff Report items → re-run `npm run dev` → `devStatus: ui_ready` → STOP                                                                   | Rewrite UI shell; mark `ui_ready` with open `devBlockers`                                       |
-| `gameplay_pass` | —     | —                              | Gameplay Pass Plan → PGS + state machine + first-level success → `npm run dev` → `devStatus: ready` + `devUrl` → STOP                            | Rewrite UI layout (unless open `ui_diff` items); set `devStatus: ready` with open `devBlockers` |
-| `gameplay_pass` | —     | `devStatus: ready`             | Handoff `next_orchestrator_action: "Invoke @reviewer load_check"` → STOP                                                                         | Treat `playcraft build` as required for `done`                                                  |
-| any             | —     | `devStatus: blocked_upstream`  | Write `devBlockers` (path, issue, routeTo TA/Designer/PM), STOP for orchestrator to re-invoke upstream                                           | Use placeholder assets; silently skip atoms                                                     |
+| 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
 
-| stage                         | gates           | handoff                                          | Expected                                                                                                                                                    | Forbidden                                                                 |
-| ----------------------------- | --------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `pm`                          | `#1 = pending`  | invoked as `design_check Gate #1`                | Soft checklist on four docs (completeness only) → write `review-report.md` → STOP                                                                           | Judge subjective design quality                                           |
-| `style_exploration`           | `#2b = pending` | invoked as `design_check Gate #2b`               | Soft checklist on MC + ASR + Handoff Pack → STOP                                                                                                            | Re-judge `#2a` selection                                                  |
-| `ui_review`                   | —               | invoked as `ui_diff` after `devStatus: ui_ready` | `playwright-cli` screenshots vs MC panels → UI Diff Report with `routeTo: developer/ta/designer` per item; increment `uiReworkRound` on fail (max 5) → STOP | Set `stage: ui_rework` (orchestrator's job); perform gameplay walkthrough |
-| `gameplay_pass`               | —               | invoked as `load_check` after `devStatus: ready` | Page loads ≤ 10s + no Error-level console logs → set `loadCheck: passed` → STOP                                                                             | Gameplay walkthrough; judge fun-ness                                      |
-| `ui_review` / `gameplay_pass` | —               | result pass                                      | `next_orchestrator_action`: `Set stage=gameplay_pass, invoke @developer` (after `ui_diff` pass) or `Run Gate #3` (after `load_check` pass)                  | `AskUserQuestion`; modify production files                                |
-| `ui_review`                   | —               | result fail                                      | `uiReworkRound` +1; `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"` → STOP                                        | Write mainline `stage: ui_rework`                                         |
+| 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                                    |
-| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `gate_pending` non-null + `waiting_for: user_gate`  | Run **only** that Gate (`AskUserQuestion`); update `gates.#N = passed`                                         | Invoke sub-agent                             |
-| `subagent_stop: true` + `waiting_for: orchestrator` | Execute **only** `next_orchestrator_action`                                                                    | Skip handoff read                            |
-| Before invoke                                       | Reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target)                          | Leave `subagent_stop: true`                  |
-| `Invoke @reviewer ui_diff` in action                | Also set `stage: ui_review`                                                                                    | Invoke without stage sync                    |
-| `Set stage=ui_rework`                               | Set `stage: ui_rework` + invoke routed agents per `review-report.md`                                           | Let Reviewer write `stage`                   |
-| `Set stage=gameplay_pass`                           | After `ui_review` pass (or `uiReworkRound == 5`): set `stage: gameplay_pass` + `@developer`                    | Skip `gameplay_pass`                         |
-| `Invoke @reviewer load_check`                       | After `devStatus: ready`: set Reviewer mode                                                                    | Skip `load_check` before Gate #3             |
-| `Run Gate #2a`                                      | Set `gates.#2a = passed`, set `selectedMcOption`, resume `@designer`                                           | Jump to `production` without #2b             |
-| `Run Gate #2b`                                      | Set `gates.#2b = passed`, set `stage: production`, invoke `@designer` Ph.2 only                                | Spawn `@technical-artist` before Wave 1 done |
-| `Invoke @technical-artist`                          | Wave 1 done → invoke TA (Wave 2)                                                                               | Invoke TA before Wave 1 done                 |
-| `Set stage=ui_pass, invoke @developer`              | Wave 2 `done` + Compliance green → set `stage: ui_pass` → invoke `@developer`                                  | Jump to `ui_pass` before Wave 2 done         |
-| `Run Gate #3`                                       | After `load_check: passed`: `AskUserQuestion` with `devUrl` → user accept → `stage: done`, `gates.#3 = passed` | Treat `playcraft build` as required          |
-
-## Post-STOP verification (before stage transition)
-
-Orchestrator MUST verify each item before advancing `stage` / invoking the next agent. Failure → re-invoke the same agent to fix, do **not** advance.
-
-| 验证项                           | 方法                                                                                                                     | 失败处理            |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------- |
-| Atom status updated              | `atom-plan.json` → that agent's all atoms `status ≠ pending`                                                             | Re-invoke to fill   |
-| `actualOutput` files exist       | `atoms[].actualOutput` path on disk                                                                                      | Re-invoke           |
-| Skill Context filled             | `atom-plan.md` corresponding section has no `(Pending …)`                                                                | Re-invoke           |
-| Skill Preflight done             | Designer: `designer-log § Skill Preflight`; TA: `ta-log § Skill Preflight`; Developer: `developer-log § Skill Preflight` | Reject STOP (hook)  |
-| Plan section complete (TA / Dev) | `ta-log § Production Plan` or `developer-log § UI Pass Plan` / `Gameplay Pass Plan` Risk Checklist all `[x]`             | Reject STOP (hook)  |
-| mediaGroups disposition recorded | Designer/TA: each `.aiaudio` / `.aiimage` / `.aisprite` entry → linked or skipped + reason                               | Re-invoke           |
-| `devStatus` consistency          | `devStatus: ui_ready` / `ready` requires `devBlockers` empty                                                             | Re-invoke developer |
+| 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.

package/project-template/docs/team/atom-tree-format.md

@@ -0,0 +1,169 @@
+# 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
+```
+
+## Mental Model
+
+Treat `atom-tree` as the structured handoff between design, Skill selection, engine scaffold, and ring verification.
+
+It answers:
+
+- what the broader Skill match discovered
+- which Skills were actually selected as reusable atoms
+- which engine adapter should scaffold the runnable base
+- which selected Skill is the gameplay trunk closest to the current design
+- how important hard deps / role slots organize around that trunk
+- which product/content tree nodes and ring slices are currently in scope
+- where downstream readers should start reading before implementation
+- which role slots were resolved, skipped, or truly missing
+
+It does **not** answer:
+
+- who executes what
+- dependency order between implementation tasks
+- delivery tracking / status
+- detailed feature sequencing
+- file/module allocation or source-level architecture
+
+Those concerns belong elsewhere:
+
+- `docs/design-brief.md` / `docs/DESIGN.md` / `docs/layout-spec.md` = product and asset contract
+- `docs/atom-tree.json` = structured product tree + selected Skill contract
+- `docs/atom-tree.md` = selected Skill reading guide and role-resolution companion
+- `docs/implementation-plan.md` = Developer execution plan
+- `docs/project-state.md` + role logs = runtime status / handoff / delivery progress
+
+## 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.
+
+Good `atom-tree.md` guidance should explain:
+
+- which Skill is the gameplay trunk
+- what each selected atom is mainly useful for
+- what to read first and what decision that reading should support
+- which selected atoms are read-only references, adapted patterns, or scaffold candidates
+- which role slots were resolved as `use`, `skip`, or `miss`
+- where actual misses remain after reading and supplementary search
+
+Keep gameplay organization narration in `docs/atom-tree.md`; do not mirror it into JSON.
+
+## Relationship to `implementation-plan.md`
+
+`atom-tree` and `implementation-plan` are deliberately separate.
+
+- `docs/atom-tree.json` tells the system what was matched, what was selected, which engine scaffold to use, and which product/ring contract is current.
+- `docs/atom-tree.md` tells humans what is worth reading in those selected Skills and how they organize around the gameplay trunk.
+- `docs/implementation-plan.md` tells Developer how the game will actually be implemented as player-visible Features.
+
+If a detail sounds like feature sequencing, dependency mapping for implementation, architecture, scene breakdown, source file ownership, or execution order, keep it out of `atom-tree.*` and put it in `docs/implementation-plan.md`.
+
+## Do Not Add
+
+- `assignTo`
+- workflow `status`
+- `actualOutput`
+- implementation steps
+- chat history
+- implementation step tracking
+- feature sequencing
+- source file ownership
+- architecture decisions
+
+Those belong in `implementation-plan.md`, `project-state.md`, and role logs.