npm - @playcraft/cli - Versions diffs - 0.0.44 → 0.0.46 - Mend

@playcraft/cli 0.0.44 → 0.0.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (984) hide show

package/project-template/CLAUDE.md CHANGED Viewed

@@ -1,280 +1,84 @@
 # PlayCraft Playable Ads Project
-## Mission
+## L0 Quickstart
-> **构建超高品质的可玩广告。** 品质优先，不惜体积与时长。打造让玩家沉浸、让广告主满意的顶级 HTML5 迷你游戏体验。每一个环节都追求极致——从视觉到交互，从音感到节奏，从第一秒的 Hook 到最后一个 CTA。
+You are building a playable ad: a self-contained HTML5 mini-game. Daily work is driven by a **slice queue** (`dispatchPacket`); **growth rings** are the outer budget, convergence boundary, and user Ring Gate.
-## What You're Building
+Start every turn with the smallest possible context:
-A **playable ad** — a self-contained HTML5 mini-game that runs inside an ad slot.
-It hooks the player in 3 seconds, delivers a compressed gameplay experience, then drives to an install CTA.
-### Hard Constraints (non-negotiable)
-- **First level guarantees player success** — tutorial must be unlosable
-- **Hook decides everything** — first 3 seconds are the lifeline
-## Project State
-**Always read `docs/project-state.md` first.** Parse **`## Agent handoff`** (YAML) before any orchestration or sub-agent work. It tracks:
-- Current stage and active agent(s)
-- Gates (#1, #2a, #2b, #3), `selectedMcOption`, `uiReworkRound`
-- Handoff: `subagent_stop`, `gate_pending`, `next_orchestrator_action`
-- Completed checkpoints (resume from here, not from scratch)
-- File index pointing to all design docs and assets
-- Production Pipeline serial waves (Designer Ph.2 → TA → Developer in `ui_pass` / `gameplay_pass`)
-## Stage Model
-```
-pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done
+```bash
+npm run workflow:doctor
+npm run state:get
 ```
-| Stage               | Active Agent(s)                       | Completion                                                                |
-| ------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
-| `pm`                | PM                                    | Gate #1 passed (after Reviewer `design_check`)                            |
-| `style_exploration` | Designer Phase 1                      | Gate #2b passed (MC + ASR; after Reviewer `design_check`)                 |
-| `production`        | Designer Ph.2 → **TA** (serial waves) | Production Pipeline Wave 1 + Wave 2 both `done`                           |
-| `ui_pass`           | **Developer** (UI shell only)         | `devStatus: ui_ready` + devUrl; light logic only (no core gameplay rules) |
-| `ui_review`         | Reviewer (`ui_diff`)                  | Browser screenshots vs MC panels pass (or max 5 `ui_rework` rounds)       |
-| `ui_rework`         | Developer (+ TA/Designer on demand)   | Fixes per UI Diff Report → re-enter `ui_review`                           |
-| `gameplay_pass`     | **Developer** (core gameplay)         | `devStatus: ready` + devUrl; Reviewer `load_check` → Gate #3              |
-| `done`              | —                                     | Gate #3 passed (user accepts at devUrl)                                   |
-## Agent Team
-5 specialized agents, each with full instructions in `.claude/agents/<name>.md` (see **Goals** § Core responsibilities in each file).
-| Agent                | Top 3 responsibilities (priority order)                                                          | Invoke when                                        |
-| -------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
-| **PM**               | 1) Experience + gameplay design 2) Zero-ambiguity contracts 3) Gates + ICP                       | `@pm` — start project, spec gaps                   |
-| **Designer**         | 1) Gate #2 visual+narrative (MC = Developer UI spec) 2) TA-ready handoff 3) Audio + digit strip  | `@designer` — style exploration, audio             |
-| **Technical Artist** | 1) Style-faithful mass production 2) 100% assetMapping 3) Production-grade assets for Developer  | `@technical-artist` — asset pipeline               |
-| **Developer**        | 1) Dev UI matches MC 2) Dev gameplay matches PM 3) Dev preview owner — **final owner of devUrl** | `@developer` — integrate, `npm run dev` self-check |
-| **Reviewer**         | 1) `design_check` before Gates 2) `ui_diff` (screenshots vs MC) 3) `load_check` before Gate #3   | `@reviewer` — design / UI / load convergence       |
-### PM is the project owner
-PM is accountable for **intent and contracts** (Layout Spec + Atom Plan, degradation decisions). **User-facing Gate dialogue** is handled by the **Orchestrator** (you), not sub-agents — see [agent-conduct.md](docs/team/agent-conduct.md).
-### Gates (Orchestrator-Only)
-Full protocol: [docs/team/collaboration.md § Gate Protocol](docs/team/collaboration.md#gate-protocol-orchestrator-only).
-1. **Gate #1 (Direction)** — PM prepares four docs → **Reviewer `design_check`** → **you** `AskUserQuestion` → user confirms gameplay + style direction
-2. **Gate #2a (MC selection)** — Designer produces MC options → **you** `AskUserQuestion` → set `selectedMcOption` (no Reviewer pre-check)
-3. **Gate #2b (MC + ASR final)** — Designer produces ASR sheets (UI + element) + docs → **Reviewer `design_check`** → **you** `AskUserQuestion` → then `stage: production`
-4. **Gate #3 (Dev delivery)** — Reviewer `load_check` pass → **you** share **devUrl** → user accepts in browser (user never runs `npm run dev`; gameplay judged by user)
-**Master Composite** — five 9:16 panels in one image: **Panel 1 = concept panel** (Main Gameplay, all element types); **Panels 2–5 = storyboard** (Hook, Onboarding, End Card, CTA). See collaboration.md § MC five panels.
-### Key Mechanisms
-**Asset Contract** — Layout Spec `assetMapping` paths are locked after Gate #1:
-- **TA** produces files at these exact paths (production Wave 2)
-- **Developer** (`ui_pass`): bind real assets, scene switching, simple states → **`npm run dev`** → `devStatus: ui_ready` + devUrl
-- **Developer** (`gameplay_pass`): add core gameplay on verified UI → `devStatus: ready` + devUrl (see Dev Preview Protocol)
-**Spec Quick-Check** — 30s validation per wave:
-- **TA** (production Wave 2 start): every assetMapping entry has clear size/format specs
-- **Developer** (`ui_pass` start): every GameplayAtom reference exists in assetMapping
-- Gaps → `spec-gap` in project-state.md → PM auto-supplements within 5 min
-**UI Rework Loop** — Max 5 iterations (`uiReworkRound` in project-state):
-- Reviewer `ui_diff` routes issues by target agent (`developer` / `ta` / `designer`)
-- Severity: `critical` / `major` (must fix) / `minor` (log only, does not block pass)
-- After 5 rounds → orchestrator decision (proceed to `gameplay_pass` or escalate to user)
-**Gameplay delivery** — No AI rework loop. Reviewer `load_check` only (page loads, no console errors). Gameplay quality = **user at Gate #3**.
-**Intent Clarification Protocol (ICP)** — Agent-to-agent async Q&A during production:
-- Any agent writes questions to `docs/intent-clarifications.md`; target agent answers
-- Non-blocking: asker continues with reasonable assumption, adjusts if needed after answer
-- PM monitors: >3 open questions or single agent receiving >3 questions → intent transmission fault
-- Designer adds Style Intent Notes + Anti-Pattern Notes to `designer-log.md` to reduce TA ambiguity
-- TA runs Style Interpretation Check + Micro-Batch Validation before batch production
-- Developer maps storyboard frames to code scenes in `developer-log.md`
-- **Developer is the final owner of the Dev preview outcome** — if Dev shows missing/wrong assets, Developer routes rework to TA/Designer via ICP (see Dev Preview Protocol)
-### Designer vs Technical Artist
-Designer = **"生"** (creative generation): **Master Composite** (concept panel + four storyboard panels), **ASR** (UI + element state reference sheets), all audio (BGM + SFX).
-TA = **"产"** (production pipeline): extract from MC/ASR (via `crop` / `segment`), complete full asset set, runtime atlases, 3D, VFX, post-processing.
+`state:get` tells you the current `iteration`, `loop`, `currentAction`, `next_orchestrator_action`, `contextPacket`, current required files, allowed tasks, forbidden tasks, current verifiers, and next commands. **Use `state:get` as your handoff summary — never open or hand-edit `docs/project-state.md`.** Read `contextPacket` first, then only the files `state:get` lists as required. Pull deeper docs only when the current action names them.
-## User interaction model
+> **State is programmatic.** `docs/project-state.json` is the machine source of truth, including `handoffContext` shared working memory; `docs/project-state.md` is a GENERATED, read-only view re-rendered after every write. **Read state with `npm run state:get`; write state with `npm run state:set` (or `npm run ring:gate` / STOP hooks).** Do not edit the markdown by hand — your edits will be overwritten on the next write, and the tables you need always exist because the renderer emits them.
-Three phases — **do not ask the user to run terminal commands** for preview.
+## Non-Negotiables
-| Phase                  | Who talks to user                         | User does                                                       |
-| ---------------------- | ----------------------------------------- | --------------------------------------------------------------- |
-| **A — Choose**         | **Orchestrator only** (`AskUserQuestion`) | Gate #1, #2a, #2b — no sub-agent user prompts                   |
-| **B — Produce**        | Nobody (ICP is agent-to-agent)            | Nothing                                                         |
-| **C — Deliver in Dev** | **Orchestrator**                          | Gate #3: open **devUrl** you provide; accept or request changes |
+- First level must guarantee player success.
+- Runtime must start at `HOOK`.
+- `autoPlay()` must progress from player-reachable actions to `ENDCARD`; do not fake victory by directly setting `ENDCARD`, repainting the whole board into a win, or calling a win screen directly.
+- For Ring 1, do not create internal Task lists (`TaskCreate` / `TaskUpdate` / …). **You are the orchestrator** — dispatch role subagents via `Task` / `@game-designer` / temporary ref-flow atom-selection subagent / `@developer`; do **not** role-play Designer, atom selector, or Developer inline in one session.
+- Use project scripts only: `npm run ...` or repository-provided `playcraft ...`; never use `npx`.
+- Typecheck with `npm run typecheck`.
+- Harness pass standard is `window.__playable`; legacy `window.__game` scene hooks are migration-only.
+- User Ring Gate is orchestrator-only.
+- Follow `state:get` output, not remembered Ring instructions.
-## Dev preview protocol
+## Slice-axis dispatch (primary — orchestrator)
-**Dev** = local preview via **`npm run dev`** at project root (implementation is whatever `package.json` → `scripts.dev` defines). **Not** `playcraft start` unless the project script explicitly uses it.
+When `npm run state:get -- --json dispatchPacket dispatchMode recommendedNextAction` returns **`dispatchMode: true`**:
-| Role                   | Runs `npm run dev`?                              | Responsibility                                                                                       |
-| ---------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| **Developer**          | **Yes** (throughout `ui_pass` + `gameplay_pass`) | **Final owner of Dev outcome** — UI shell then gameplay at devUrl                                    |
-| **Reviewer**           | **Yes** if needed                                | **`playwright-cli`**: `design_check` (docs), `ui_diff` (screenshots vs MC), `load_check` (no errors) |
-| **You (orchestrator)** | Only if dev server stopped                       | Keep devUrl valid for Gate #3; **user only clicks the link**                                         |
-| **PM / Designer / TA** | No                                               | Fix assets when Developer blocks upstream (see below)                                                |
-| **User**               | **Never**                                        | Gate #3: click devUrl only                                                                           |
+1. **Dispatch unit** = `role + doWhat + flow + sliceId` from `dispatchPacket` — not ring loop names.
+2. Invoke subagents with **packet scope only**; never say "Ring 1 build" or ask them to self-identify Ring / Gate / Loop.
+3. After STOP: trust **`sliceState`** + STOP hook (`verify:slice` / `verify:slice-artist` / `verify:slice-ta`, then `slice:set`) — not handoff markdown as authority.
+4. **`ring:gate`** still runs for objective DoD and user Ring Gate; it aggregates slice queue terminal state but does **not** replace per-slice verify on STOP.
-### Developer upstream rework
+When **`dispatchPacket` is null** (`dispatchMode: false`): use the legacy growth-ring path below until Designer seeds `sliceState`.
-When Developer finds **missing or substandard** Designer/TA output in Dev:
+## Current Workflow
-1. Log blockers in `developer-log.md` + `project-state.md` (`devStatus: blocked_upstream`, `devBlockers`).
-2. Write `docs/intent-clarifications.md` with paths, gap vs MC/spec, and acceptance criteria.
-3. Mark affected atoms `blocked` in `atom-plan.md`.
-4. **You** re-invoke `@technical-artist` and/or `@designer` for targeted rework → then `@developer` again.
-5. Developer re-runs `npm run dev` until no open blockers → `devStatus: ui_ready` (after `ui_pass`) or `devStatus: ready` (after `gameplay_pass`) + **devUrl**.
+1. Read state with `npm run state:get` (never open the generated `docs/project-state.md`).
+2. If `dispatchMode: true` → follow `recommendedNextAction` / `dispatchPacket`; else follow `next_orchestrator_action`.
+3. Keep work inside the current slice (dispatch mode) or current ring (legacy).
+4. After a sub-agent stops, run verifiers from `state:get` (per-slice verify before ring gate when slices are active).
+5. When `ring:gate` says `canAskUser: yes`, the orchestrator asks the user to accept the dev URL.
-**Never** set `devStatus: ui_ready` or `ready` with placeholders, open `devBlockers`, or silent skips.
+## Ring 1 Dispatch Path (legacy growth-rings — orchestrator)
-### Gate #3 (orchestrator only)
+When `state:get` reports `iteration: 1`, **stay orchestrator** — invoke role subagents; do not inline their work.
-1. Reviewer `load_check: passed` (page loads within 10s, console has no Error-level logs).
-2. Read **devUrl** from `project-state.md`; if dev server down, run `npm run dev` and refresh devUrl (user still only opens the link).
-3. `AskUserQuestion`: show devUrl + accept / request changes (route to PM/Designer/TA/Developer).
-4. User accepts → `stage: done`, `gates.#3 = passed`.
+| `loop`                | Orchestrator does                                                                                                                                                                                                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clarify`             | **Invoke `@game-designer`** — ring 1 clarify (single concise `docs/DESIGN.md`). Do not write `DESIGN.md` yourself.                                                                                                                                                                 |
+| (after GD STOP)       | **Spawn a temporary ref-flow atom-selection subagent** — create the minimal ring 1 atom-tree package: engine decision, compact gameplay trunk, selected atoms, and ring 1 verifier metadata. Do not make main orchestrator select atoms inline.                                    |
+| (after selector STOP) | Run scaffold gate: `validate-atom-tree-selection` → `init-template --from-atom-tree` → `npm install` → `npm run verify:contract` → `npm run verify:lifecycle`. Set `loop: build`, then **Invoke `@developer`**.                                                                    |
+| `build`               | **Invoke `@developer`** — ring 1 build only the smallest verifiable playable spine (placeholder art, one player-reachable action loop, `window.__playable`). Developer self-gates with `verify:contract` + `verify:lifecycle` + `verify:firstwin` + `verify:placeholders` on STOP. |
+| `verify`              | Run `npm run ring:gate -- --iteration 1` (no `@reviewer` in ring 1).                                                                                                                                                                                                               |
-**Current delivery endpoint = user acceptance in Dev.** `playcraft build` is **future**, not required for `done`.
+Follow `next_orchestrator_action` from handoff when `subagent_stop: true`. See `docs/team/collaboration.md` § Ring 1 engine scaffold.
-## Orchestration Protocol
+## Deeper References
-When you receive a user request to create a playable ad, determine your execution mode first.
+Use these only when the current action needs them:
-### Multi-Agent Mode (default, preferred)
+| Need                                           | Read                                      |
+| ---------------------------------------------- | ----------------------------------------- |
+| Full collaboration and Ring Gate protocol      | `docs/team/collaboration.md`              |
+| Role conduct and MUST/NEVER rules              | `docs/team/agent-conduct.md`              |
+| Runtime model and `window.__playable` boundary | `docs/team/core-model.md`                 |
+| Post-stop verification matrix                  | `docs/team/agent-runtime-matrix.md`       |
+| Atom-tree schema and Skill selection           | `docs/team/atom-tree-format.md`           |
+| Legacy harness migration                       | `docs/team/harness-legacy-deprecation.md` |
-If sub-agent invocation is available (Claude Code `@agent` syntax), **you are the orchestrator**. Do NOT role-play all agents yourself in one session.
+## Directory Map
-### Orchestrator startup (every turn)
-1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML + Gates table.
-2. If `gate_pending` is non-null and `waiting_for: user_gate` → run **only** that Gate (`AskUserQuestion`) — **do not** invoke sub-agents.
-3. If `subagent_stop: true` and `waiting_for: orchestrator` → execute **only** `next_orchestrator_action`.
-4. Confirm `stage` matches last passed gate before advancing.
-5. Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target).
-See `docs/team/collaboration.md` § Agent Handoff, § Stage field ownership, § Rework sequence.
-### Stage sync on handoff
-When executing `next_orchestrator_action`, **also** update mainline `stage` / gates:
-| `next_orchestrator_action` contains       | Orchestrator **must** write                                                                        |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `Run Gate #1`                             | After user pass: `gates.#1 = passed`, `stage: style_exploration`                                   |
-| `Invoke @reviewer design_check Gate #1`   | Before Gate #1 — Reviewer soft checklist on four docs                                              |
-| `Run Gate #2a`                            | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` (stage stays `style_exploration`) |
-| `Invoke @reviewer design_check Gate #2b`  | Before Gate #2b — Reviewer soft checklist on MC + ASR                                              |
-| `Run Gate #2b`                            | `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only                            |
-| `Invoke @technical-artist`                | Production Pipeline Wave 1 `done` → invoke TA (Wave 2)                                             |
-| `Set stage=ui_pass` / invoke `@developer` | Production Pipeline Wave 2 `done` → `stage: ui_pass`                                               |
-| `Invoke @reviewer ui_diff`                | `stage: ui_review`; Developer `devStatus: ui_ready`                                                |
-| `Set stage=ui_rework`                     | `stage: ui_rework` + invoke routed agents per UI Diff Report                                       |
-| `Set stage=gameplay_pass`                 | UI convergence pass → `stage: gameplay_pass` → invoke `@developer`                                 |
-| `Invoke @reviewer load_check`             | `devStatus: ready` → Reviewer load_check before Gate #3                                            |
-| `Run Gate #3`                             | `gates.#3 = pending` → user accept → `stage: done`, `gates.#3 = passed`                            |
-**Stage transition table:**
-| Current Stage       | Trigger                               | Your Action                                                                                           |
-| ------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| (start)             | User prompt received                  | Invoke `@pm`                                                                                          |
-| `pm`                | PM STOP + `gates.#1 = pending`        | Invoke `@reviewer` `design_check` Gate #1 → pass → Gate #1 → on pass invoke `@designer`               |
-| `style_exploration` | Designer STOP + `gates.#2a = pending` | Gate #2a `AskUserQuestion` → set `selectedMcOption` → resume `@designer`                              |
-| `style_exploration` | Designer STOP + `gates.#2b = pending` | Invoke `@reviewer` `design_check` Gate #2b → pass → Gate #2b → `stage: production` → `@designer` Ph.2 |
-| `production`        | Designer Wave 1 `done`                | Invoke `@technical-artist` (Wave 2)                                                                   |
-| `production`        | TA Wave 2 `done` (Compliance green)   | `stage: ui_pass` → invoke `@developer` (UI shell only)                                                |
-| `ui_pass`           | `devStatus: ui_ready`                 | `stage: ui_review` → invoke `@reviewer` `ui_diff`                                                     |
-| `ui_pass`           | `devStatus: blocked_upstream`         | Re-invoke `@technical-artist` / `@designer` per `devBlockers` → then `@developer`                     |
-| `ui_review`         | Fail + `uiReworkRound` &lt; 5         | `stage: ui_rework` → invoke routed agents → `@developer` → `@reviewer` `ui_diff`                      |
-| `ui_review`         | Pass or 5 rounds reached              | `stage: gameplay_pass` → invoke `@developer` (gameplay)                                               |
-| `gameplay_pass`     | `devStatus: ready`                    | Invoke `@reviewer` `load_check` → Gate #3 devUrl                                                      |
-| `gameplay_pass`     | `load_check` fail                     | Re-invoke `@developer` → `@reviewer` `load_check`                                                     |
-| `done`              | Gate #3 passed                        | Project complete                                                                                      |
-**How to invoke sub-agents:**
-- Each `@agent-name` corresponds to `.claude/agents/<name>.md`
-- Sub-agents read `project-state.md` + **`## Agent handoff`**; follow each agent's **Runtime** section
-- Sub-agents update handoff + gates and **STOP** — they do **not** `AskUserQuestion` or change mainline `stage`
-- You read handoff between every invoke (startup checklist above)
-- **Only you** run Gate #1 / #2a / #2b / #3 user interactions
-**Requires sub-agent invoke** (`@pm`, `@designer`, `@technical-artist`, `@developer`, `@reviewer`). Do not role-play all five roles in one session — use Claude Code or Cursor agent spawn.
-### Dispatching Principle (WHAT not HOW)
-**你不是全知全能的指挥官。** Sub-agent 有完整的 `.claude/agents/<role>.md` + `refs/` + Skills。
-**调度时只传递：**
-1. **目标**（atoms to complete, stage entry condition）
-2. **关键约束/提醒**（如 `mediaGroups` 有可用预制资产、`skillRef` 列表）
-3. **上游状态**（which Waves done, which files exist）
-**禁止在调度消息中：**
-- 编写详细生产步骤（agent 自己读 refs/ + Skills 决定 HOW）
-- 越俎代庖选择 prompt / model / 工具参数
-- 替 agent 做 Skill Preflight 或 Transparency Classification
-### Post-STOP Verification (阶段转换前必须)
-Sub-agent STOP 后，**先验证再转阶段**：
-| 验证项                        | 失败处理          |
-| ----------------------------- | ----------------- |
-| 所有 atoms `status ≠ pending` | 要求补全          |
-| `actualOutput` 文件存在       | 要求补全          |
-| `atom-plan.md` Context 非空   | 要求回填          |
-| Skill Preflight 已完成        | 拒绝 STOP，重新入 |
-| mediaGroups 处置已记录        | 要求补充          |
-验证失败 → **不转阶段**，re-invoke 该 agent 补全。详见 `.cursor/rules/playcraft-orchestrator.mdc`。
-## Directory Layout
-```
-docs/           Design documents (project-state, design-brief, layout-spec, atom-plan, style-exploration)
-assets/         images/{bg,tiles,ui,vfx,storyboard,reference}  audio/{bgm,sfx}  models/  bundles/
-game/           gameplay/  config/  scenes/  index.html
-logs/           designer-log / ta-log / developer-log / review-report
-templates/      Read-only reference templates
-ta-workspace/   TA batch scripts (scripts/) + temp files (logs/, tmp/)
+```text
+docs/      project-state, DESIGN, ring-specific specs
+game/      runtime implementation
+logs/      developer/reviewer/artist/TA logs
+assets/    placeholder and production media
+skills/    local verifier, record, art, and workflow scripts
 ```
-## Golden Rules
-Project-level principles (full MUST/NEVER: [docs/team/agent-conduct.md](docs/team/agent-conduct.md)):
-1. First level must guarantee player success
-2. Hook decides everything — first 3 seconds
-3. Quality first — do not compromise quality for file size or play time
-4. Style Gate (#2a + #2b) cannot be skipped — no production without confirmed MC + ASR
-5. Layout Spec is the sole three-way alignment mechanism — do not violate
-6. Asset Contract paths are immutable after Gate #1
-7. Production serial: Designer Ph.2 → TA → Developer (`ui_pass` → `gameplay_pass`) — never invoke `@developer` during `production`
-8. UI rework max 5 rounds (`uiReworkRound`) — then orchestrator decision or proceed to `gameplay_pass`
-9. Dev delivery: Developer owns Dev quality; Reviewer `load_check` + user gameplay judgment at Gate #3
-10. No `playcraft build` for `done` — endpoint is `devStatus: ready` + user devUrl acceptance
-## Detailed References
-| Document                                                                 | Contents                                             |
-| ------------------------------------------------------------------------ | ---------------------------------------------------- |
-| [docs/team/agent-conduct.md](docs/team/agent-conduct.md)                 | MUST/NEVER behavior contract                         |
-| [docs/team/collaboration.md](docs/team/collaboration.md)                 | Gate Protocol, directory tree, R/W matrix, MC panels |
-| [docs/team/core-model.md](docs/team/core-model.md)                       | Remix = DAG(Atom[]) model                            |
-| [docs/team/platform-capabilities.md](docs/team/platform-capabilities.md) | `playcraft` CLI by role                              |

package/project-template/docs/DESIGN.md ADDED Viewed

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

package/project-template/docs/intent-clarifications.md ADDED Viewed

@@ -0,0 +1,58 @@
+# Intent Clarifications
+> **Living Document**: Agent 间异步澄清的共享空间。
+> 所有 Agent 可读；提问 Agent 和目标 Agent 可写。
+> 不阻塞流水线 — 提问 Agent 先用合理推断继续，回答到达后评估是否调整。
+## Open Questions
+| #     | From           | To               | Atom/Topic           | Question              | Raised At      | Status |
+| ----- | -------------- | ---------------- | -------------------- | --------------------- | -------------- | ------ |
+| {{n}} | {{agent_name}} | {{target_agent}} | {{atom_id_or_topic}} | {{specific_question}} | {{stage_name}} | open   |
+<!--
+Status values:
+  open     — 等待目标 Agent 回答
+  pending  — 目标 Agent 已看到，正在处理
+  answered — 目标 Agent 已回答，提问 Agent 尚未确认
+  resolved — 双方达成一致，已移入 Resolved 表
+Rules:
+  - 提问必须具体，不能是"风格不对"这种模糊描述
+  - 必须引用具体文件路径或 atomId，方便目标 Agent 定位
+  - Confidence = low 的风格解读问题必须写入此表
+  - Developer 发现故事板与 layout-spec 坐标不一致时，必须向 Game Designer 提问
+-->
+## Resolved
+| #     | From           | To               | Question Summary     | Answer          | Resolution              | Closed By      |
+| ----- | -------------- | ---------------- | -------------------- | --------------- | ----------------------- | -------------- |
+| {{n}} | {{agent_name}} | {{target_agent}} | {{one_line_summary}} | {{answer_text}} | {{how_it_was_resolved}} | {{agent_name}} |
+<!--
+Resolution examples:
+  - "已补充到 artist-log.md Style Intent Notes"
+  - "已更新 layout-spec.md zones 坐标"
+  - "Game Designer 裁决：以故事板为准，layout-spec 将修正"
+  - "双方同意保持现状，偏差在可接受范围"
+-->
+## Metrics
+| Metric                 | Value     |
+| ---------------------- | --------- |
+| Total questions raised | {{count}} |
+| Unresolved             | {{count}} |
+| By Artist              | {{count}} |
+| By TA                  | {{count}} |
+| By Developer           | {{count}} |
+| By Game Designer       | {{count}} |
+| By Reviewer            | {{count}} |
+<!--
+Game Designer monitors this table:
+  - If single Agent receives >3 questions → intent transmission fault, record in DAG Revisions
+  - If unresolved >3 at any time → Game Designer must intervene and assign priority
+  - If Reviewer finds unresolved questions at review stage → deduct Intent Transmission score
+-->

package/project-template/docs/pipeline-overview.md ADDED Viewed

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