@playcraft/cli 0.0.40 → 0.0.41

package/project-template/CLAUDE.md

@@ -0,0 +1,240 @@
+# PlayCraft Playable Ads Project
+
+## Mission
+
+> **构建超高品质的可玩广告。** 品质优先，不惜体积与时长。打造让玩家沉浸、让广告主满意的顶级 HTML5 迷你游戏体验。每一个环节都追求极致——从视觉到交互，从音感到节奏，从第一秒的 Hook 到最后一个 CTA。
+
+## What You're Building
+
+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`, `reworkRound`
+- 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 `integration`)
+
+## Stage Model
+
+```
+pm → style_exploration → production → integration → review ⇄ rework → done
+```
+
+| Stage               | Active Agent(s)                       | Completion                                                               |
+| ------------------- | ------------------------------------- | ------------------------------------------------------------------------ |
+| `pm`                | PM                                    | Gate #1 passed                                                           |
+| `style_exploration` | Designer Phase 1                      | Gate #2b passed (MC + ASR confirmed)                                     |
+| `production`        | Designer Ph.2 → **TA** (serial waves) | Production Pipeline Wave 1 + Wave 2 both `done`                          |
+| `integration`       | **Developer** (full impl + integrate) | `devStatus: ready` + devUrl (no open upstream blockers)                  |
+| `review`            | Reviewer                              | Six-dimension score ≥ 24/30, or 2nd rework forced; Dev UI+gameplay check |
+| `rework`            | Routed agent(s) in parallel           | Fixes done → `integration` → `review`                                    |
+| `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) Intent delivery audit 2) Player experience (UI + gameplay fidelity) 3) Actionable verdict     | `@reviewer` — quality gate before Gate #3          |
+
+### 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 → **you** `AskUserQuestion` → user confirms gameplay + style direction
+2. **Gate #2a (MC selection)** — Designer produces MC options → **you** `AskUserQuestion` → set `selectedMcOption`
+3. **Gate #2b (MC + ASR final)** — Designer produces ASR sheets (UI + element) + docs → **you** `AskUserQuestion` → then `stage: production`
+4. **Gate #3 (Dev delivery)** — Reviewer passes → **you** share **devUrl** → user accepts in browser (user never runs `npm run dev`)
+
+**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** (`integration`): bind real assets at contract paths → **`npm run dev`** → self-check → `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** (`integration` start): every GameplayAtom reference exists in assetMapping
+- Gaps → `spec-gap` in project-state.md → PM auto-supplements within 5 min
+
+**Rework Loop** — Max 2 iterations (`reworkRound` in project-state):
+
+- Reviewer routes issues by target agent (can be parallel)
+- Severity: `critical` (must fix) / `major` (1 round) / `minor` (log only)
+- After 2 rounds → forced Gate #3, user decides
+
+**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.
+
+## User interaction model
+
+Three phases — **do not ask the user to run terminal commands** for preview.
+
+| 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 |
+
+## Dev preview protocol
+
+**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.
+
+| Role                   | Runs `npm run dev`?              | Responsibility                                                                                   |
+| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **Developer**          | **Yes** (throughout integration) | **Final owner of Dev outcome** — UI, gameplay, assets must pass in Dev before `devStatus: ready` |
+| **Reviewer**           | **Yes**                          | Independent check: **① UI vs MC/layout-spec ② gameplay vs design-brief/PGS**                     |
+| **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                                                                       |
+
+### Developer upstream rework
+
+When Developer finds **missing or substandard** Designer/TA output in Dev:
+
+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: ready` + **devUrl**.
+
+**Never** set `devStatus: ready` with placeholders, open `devBlockers`, or silent skips.
+
+### Gate #3 (orchestrator only)
+
+1. `reviewerDevCheck: passed` (or Reviewer overall pass).
+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`.
+
+**Current delivery endpoint = user acceptance in Dev.** `playcraft build` is **future**, not required for `done`.
+
+## Orchestration Protocol
+
+When you receive a user request to create a playable ad, determine your execution mode first.
+
+### Multi-Agent Mode (default, preferred)
+
+If sub-agent invocation is available (Claude Code `@agent` syntax), **you are the orchestrator**. Do NOT role-play all agents yourself in one session.
+
+### 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`                                   |
+| `Run Gate #2a`                                | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` (stage stays `style_exploration`) |
+| `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=integration` / invoke `@developer` | Production Pipeline Wave 2 `done` → `stage: integration`                                           |
+| `Invoke @reviewer`                            | `stage: review`                                                                                    |
+| `Set stage=rework`                            | `stage: rework`, invoke per review-report                                                          |
+| `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`        | Gate #1 `AskUserQuestion` → 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` | Gate #2b confirm → `stage: production` → invoke `@designer` Ph.2 only                        |
+| `production`        | Designer Wave 1 `done`                | Invoke `@technical-artist` (Wave 2)                                                          |
+| `production`        | TA Wave 2 `done` (Compliance green)   | `stage: integration` → invoke `@developer` (Skill Preflight + PGS + assets + dev)            |
+| `integration`       | `devStatus: ready`                    | Invoke `@reviewer`                                                                           |
+| `integration`       | `devStatus: blocked_upstream`         | Re-invoke `@technical-artist` / `@designer` per `devBlockers` → then `@developer`            |
+| `review`            | Fail + `reworkRound` &lt; 2           | `stage: rework` → parallel invoke per Action Items → `@developer` re-integrate → `@reviewer` |
+| `rework`            | Fixes done + `devStatus: ready`       | `stage: integration` or invoke `@reviewer` directly per reviewer rules                       |
+| `review`            | Pass (≥24/30) or 2nd rework forced    | Gate #3: present **devUrl** via `AskUserQuestion`                                            |
+
+**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.
+
+## 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/)
+```
+
+## 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 (`integration`) — never invoke `@developer` during `production`
+8. Rework max 2 rounds — then forced Gate #3
+9. Dev delivery: Developer owns Dev quality; user only opens orchestrator devUrl 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/team/agent-conduct.md

@@ -0,0 +1,105 @@
+# Agent Conduct — MUST / NEVER
+
+> Single source for enforceable behavior. When this conflicts with workflow shortcuts, **this wins** (except where an agent Goals § Core responsibilities explicitly overrides for that role).
+>
+> Gate flow detail: [collaboration.md § Gate Protocol](collaboration.md#gate-protocol-orchestrator-only). STOP fields: [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
+
+## Invoke protocol (all sub-agents)
+
+On every invoke, in order:
+
+1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML (routing truth — not Progress Checkpoint alone).
+2. Read **this role's `## Runtime`** in `.claude/agents/<role>.md` → pick **one** branch.
+3. Read `refs/` or SKILL **only when** Runtime or that branch says so — do not read long Workflow first.
+4. On STOP: complete [§ STOP sync checklist](collaboration.md#stop-sync-checklist).
+
+## All roles (including Orchestrator)
+
+|              | Rule                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Read `docs/project-state.md` before any work; parse `## Agent handoff` YAML; resume from Progress Checkpoint when present |
+| **MUST**     | Update `docs/project-state.md` Progress Checkpoint when finishing a major step                                            |
+| **MUST**     | On STOP: update `## Agent handoff` (`subagent_stop: true`, `next_orchestrator_action` required)                           |
+| **MUST NOT** | Change `layout-spec.md` `assetMapping` paths after Gate #1 without PM + user-approved contract change                     |
+| **MUST NOT** | Treat `playcraft build` as required for `done` — endpoint is **user acceptance at devUrl**                                |
+| **MUST NOT** | Ask the **user** to run `npm run dev` (Gate #3 = open orchestrator-provided link only)                                    |
+
+## Orchestrator only
+
+|              | Rule                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MUST**     | Be the **only** role that uses `AskUserQuestion` toward the user (Gate #1, #2a, #2b, #3)                                                         |
+| **MUST**     | After any sub-agent STOP, read `## Agent handoff` in `project-state.md` before spawn / resume / Gate                                             |
+| **MUST**     | If `gate_pending` is non-null and `waiting_for: user_gate`, run **only** the matching Gate (`AskUserQuestion`) — **do not** invoke sub-agents    |
+| **MUST**     | If `subagent_stop: true` and `waiting_for: orchestrator`, execute **only** `next_orchestrator_action`                                            |
+| **MUST**     | Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, set `subagent` to target role)                                        |
+| **MUST NOT** | Role-play all five agents in one session when sub-agent invoke is available                                                                      |
+| **MUST NOT** | Skip Gate #2a / #2b while gates are `pending`                                                                                                    |
+| **MUST NOT** | Invoke `@technical-artist` before Production Pipeline Wave 1 (Designer Ph.2) is `done`                                                           |
+| **MUST NOT** | Invoke `@developer` or set `stage: integration` before Production Pipeline Wave 2 (TA) is `done`                                                 |
+| **MUST NOT** | Spawn `@developer` during `stage: production` (serial workflow: Designer → TA → Developer)                                                       |
+| **MUST NOT** | Advance mainline `stage` when a sub-agent could do it — **orchestrator owns** `stage` transitions (see collaboration.md § Stage field ownership) |
+
+## Sub-agents only (PM, Designer, TA, Developer, Reviewer)
+
+|              | Rule                                                                                                                          |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **MUST NOT** | Use `AskUserQuestion` or present Gate choices to the user                                                                     |
+| **MUST**     | On Gate-ready materials: sync `gates.#N = pending` + handoff (`gate_pending`, `waiting_for: user_gate`) → **STOP**            |
+| **MUST**     | Run Spec Quick-Check within 30s: TA when starting production Wave 2; Developer when starting `integration`                    |
+| **MUST NOT** | Continue producing while `subagent_stop: true` and `waiting_for: orchestrator` (resume only when orchestrator clears handoff) |
+| **MUST NOT** | Change mainline `stage` (orchestrator only — see collaboration.md § Stage field ownership)                                    |
+| **MUST NOT** | Skip required logs (`designer-log`, `ta-log`, `developer-log`, `review-report`)                                               |
+| **MUST**     | Complete [STOP sync checklist](collaboration.md#stop-sync-checklist) on every STOP                                            |
+
+### PM (four-doc discipline)
+
+|              | Rule                                                                                                                                                                                                                                                                                           |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Keep **四件套** contract-only: playable decisions in `design-brief` (no hex — palette in `layout-spec`); paths/zones/specs in `layout-spec`; DAG in **`atom-plan.json`**; acceptance one-liners in **`atom-plan.md`**; status/handoff in `project-state` — **key fields only**, no prose dumps |
+| **MUST**     | Before Gate #1: `playcraft skills match --json` → `docs/atom-plan.json` → `skillsMatch`; bind `GameplayAtom`/`ConfigAtom` `skillRef` only from `skillsMatch.items` (or `null` + `dagRevisions` gap); run `playcraft skills validate-atom-plan`                                                 |
+| **MUST NOT** | Paste long research, full prompts, MC/ASR narrative, or generation logs into the four docs — point downstream to `style-exploration.md` / `logs/designer-log.md` instead                                                                                                                       |
+| **MUST NOT** | Put `playcraft-*` in `skillRef`, or use atomIds absent from `skillsMatch.items` without `dagRevisions` — format: [`atom-plan-format.md`](atom-plan-format.md)                                                                                                                                  |
+| **MUST NOT** | Duplicate the same fact across multiple four-doc files — one canonical home per fact (see `collaboration.md` § Four-doc discipline); Gate #1: no Atom List / DAG Order in `atom-plan.md`; no hex in `design-brief`; no Emotion Target in Experience Flow                                       |
+
+### Designer (four-doc discipline)
+
+|              | Rule                                                                                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Put visual narrative, Handoff Pack, ASR tables, and generation notes in **`style-exploration.md`** + **`logs/designer-log.md`** — not in PM's four docs                   |
+| **MUST NOT** | Edit `design-brief.md` or `layout-spec.md` except ICP-driven contract fixes (paths/palette deltas) — do not rewrite gameplay or duplicate PM contracts                    |
+| **MUST**     | When PM needs a contract delta, write **one-line deltas** (e.g. Palette Locked vs layout-spec) in `designer-log.md`; PM patches layout-spec if user/orchestrator approves |
+
+### Technical Artist
+
+|              | Rule                                                                                                                                                                                                                                        |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Before any asset generation in production Wave 2: complete **Upstream Intake** in `logs/ta-log.md` — Read (tool or `cat`) **四件套** + `docs/style-exploration.md` + `logs/designer-log.md`; tick every row; note one-line takeaway per doc |
+| **MUST**     | Execute `refs/ta-pipeline-cookbook.md` **Step 0a → Step 0** in order after intake                                                                                                                                                           |
+| **MUST NOT** | Start bulk generation or write `ta-log` Style Interpretation until Upstream Intake is complete                                                                                                                                              |
+| **MUST NOT** | Mark TA wave `done` without Upstream Intake + Style Interpretation sections filled                                                                                                                                                          |
+| **MUST**     | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (Claude `SubagentStop` + Cursor `subagentStop` — see `.claude/hooks/README.md`)                                                                                                 |
+
+### Developer
+
+|              | Rule                                                                                                                                                                                                                                                                                                            |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **MUST**     | Before Spec Quick-Check or any `game/` work in `integration`: complete **Upstream Intake** in `logs/developer-log.md` — Read **四件套** + `docs/style-exploration.md` + `logs/designer-log.md` + `logs/ta-log.md`; tick every row; one-line takeaway per doc (what happened upstream + what you will implement) |
+| **MUST**     | Execute `refs/developer-phase1-flow.md` **Step 0 → Step 1** in order after intake                                                                                                                                                                                                                               |
+| **MUST NOT** | Start Skill Preflight or edit `game/**` until Upstream Intake is complete                                                                                                                                                                                                                                       |
+| **MUST**     | Before any `game/` implementation in Ph.1: for each non-empty `skillRef`, read Recipe + `ref/` from `.claude/skills/<skillRef>/` when link exists; else `playcraft skills read` + Package Skills Root (fallback); then `playcraft skills scaffold` — log access mode in `developer-log.md` § Skill Preflight    |
+| **MUST**     | Base gameplay/config on Skill Recipe + `ref/` templates; deviations only with rationale in `## Impl Skill Context`                                                                                                                                                                                              |
+| **MUST**     | Own Dev preview quality at **devUrl** before Reviewer / Gate #3                                                                                                                                                                                                                                                 |
+| **MUST NOT** | Write or edit `game/**` in `integration` until Skill Preflight is complete (orchestrator may pass `skillRefs` in invoke prompt)                                                                                                                                                                                 |
+| **MUST NOT** | Set `devStatus: ready` while `devBlockers` has open items                                                                                                                                                                                                                                                       |
+| **MUST NOT** | Use placeholder assets or silently skip `blocked` atoms                                                                                                                                                                                                                                                         |
+| **MUST NOT** | Record Impl Skill Context as "referenced" without having read that `skillRef`'s SKILL.md + `ref/` (via Project Skills or CLI fallback)                                                                                                                                                                          |
+| **MUST**     | Pass **`.claude/hooks/validate-workflow-stop.mjs`** on STOP (same hook as TA — enforced for `developer` role)                                                                                                                                                                                                   |
+
+### Reviewer
+
+|              | Rule                                                                                                                                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **MUST**     | Dev walkthrough at **devUrl** before six-dimension scoring                                                                                                                                             |
+| **MUST NOT** | Modify production files (only `logs/review-report.md` + `project-state` checkpoint)                                                                                                                    |
+| **MUST**     | On fail: increment `reworkRound`, route Action Items in `review-report.md`, set handoff `next_orchestrator_action` for orchestrator to set `stage: rework` — **do not** write `stage: rework` yourself |

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

@@ -0,0 +1,62 @@
+# Agent Runtime Matrix
+
+Fake-invoke reference: `(stage, gates snapshot, 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).
+
+## PM
+
+| stage        | gates            | handoff                           | Expected                         | Forbidden                                      |
+| ------------ | ---------------- | --------------------------------- | -------------------------------- | ---------------------------------------------- |
+| `pm`         | `#1` pending     | `gate_pending: "1"`, `user_gate`  | Orchestrator runs Gate #1 only   | Invoke designer before Gate #1 pass            |
+| `pm`         | `#1` not started | —                                 | Write four docs → pending → STOP | Skip four docs; set `stage: style_exploration` |
+| `production` | `#1` passed      | spec-gap                          | Patch layout/atom ≤5 min → STOP  | Re-open Gate #1                                |
+| any          | —                | `subagent_stop`, pm, orchestrator | Reply already STOPPED            | Rewrite four docs                              |
+
+## Designer
+
+| stage               | gates                                | handoff              | Expected                                                         | Forbidden                                       |
+| ------------------- | ------------------------------------ | -------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
+| `style_exploration` | `#2a` not passed                     | —                    | Phase 1 Skill Discovery → style-exploration-flow → `#2a` pending | Skip Skill Discovery; MC before art-style-guide |
+| `style_exploration` | `#2a` pending                        | `gate_pending: "2a"` | Orchestrator Gate #2a only                                       | User A/B/C in chat                              |
+| `style_exploration` | `#2a` passed, `selectedMcOption` set | —                    | ASR 双板 + docs → `#2b` pending                                  | Regenerate MC options                           |
+| `style_exploration` | `#2b` pending                        | `gate_pending: "2b"` | Orchestrator Gate #2b                                            | Phase 2 audio                                   |
+| `production`        | `#2b` passed                         | —                    | Ph.2 atoms + audio → track done STOP                             | Set `stage`                                     |
+| `rework`            | —                                    | routeTo Designer     | Fix report paths → STOP                                          | Full style re-exploration                       |
+
+## Technical Artist
+
+| stage         | gates                     | handoff                        | Expected                                                                     | Forbidden                                      |
+| ------------- | ------------------------- | ------------------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------- |
+| `production`  | `#2b` passed, Wave 1 done | —                              | Spec check → bulk → **webp atlas+json** Compliance → STOP when TA atoms done | Start before Designer Wave 1 done; set `stage` |
+| `integration` | —                         | `blocked_upstream`, routeTo TA | Fix listed paths → STOP                                                      | `npm run dev`                                  |
+| `rework`      | —                         | Action Items TA                | Scoped fixes → STOP                                                          | Redefine MC                                    |
+
+## Developer
+
+| stage         | gates | handoff                 | Expected                                                                              | Forbidden                                         |
+| ------------- | ----- | ----------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `production`  | —     | —                       | **Do not run** — orchestrator invokes Developer only in `integration`                 | Any `game/**` work in `production`                |
+| `integration` | —     | —                       | Spec Quick-Check → Skill Preflight → PGS/scenes → bind assets → `npm run dev` → ready | Skip Spec Quick-Check; `stage: review` self-write |
+| `integration` | —     | ready + invoke reviewer | STOP handoff                                                                          | Skip Reviewer invoke                              |
+| `rework`      | —     | —                       | Fix Developer Action Items → re-integrate                                             | `playcraft build` as done                         |
+
+## Reviewer
+
+| stage    | gates | handoff | Expected                                       | Forbidden             |
+| -------- | ----- | ------- | ---------------------------------------------- | --------------------- |
+| `review` | —     | —       | Dev walkthrough → **六维度 ≥24/30, no vetoes** | Edit production files |
+| `review` | —     | pass    | `reviewerDevCheck: passed`, Gate #3 handoff    | `AskUserQuestion`     |
+| `review` | —     | fail    | `reworkRound` +1, handoff rework               | Write `stage: rework` |
+
+## Orchestrator
+
+| handoff                                     | Expected                                                       | Forbidden                      |
+| ------------------------------------------- | -------------------------------------------------------------- | ------------------------------ |
+| `gate_pending` + `user_gate`                | Gate `AskUserQuestion` only                                    | Invoke sub-agent               |
+| `subagent_stop` + `orchestrator`            | Execute `next_orchestrator_action`                             | Skip handoff read              |
+| Before invoke                               | Reset handoff fields                                           | Leave `subagent_stop: true`    |
+| `Invoke @reviewer` in action                | Also set `stage: review`                                       | Invoke without stage sync      |
+| `Run Gate #2a`                              | `gates.#2a = passed`, set `selectedMcOption`, resume @designer | Jump to production without #2b |
+| `Invoke @technical-artist`                  | Wave 1 done → invoke TA                                        | Invoke TA before Wave 1 done   |
+| `Set stage=integration` / invoke @developer | Wave 2 done → `stage: integration`                             | Jump to integration early      |

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

@@ -0,0 +1,74 @@
+# Atom Plan 格式（JSON 主 + Markdown 辅）
+
+> Gate #1 起，**机器可读主文件**为 `docs/atom-plan.json`；`docs/atom-plan.md` 仅承载各角色富集的 Context 与 DAG Revisions。
+
+## Skills 包路径（不在 atom-plan 里写死）
+
+**真源**：项目根 `playcraft.config.json` → `agent.skillsDir`（`playcraft create` 时可配置）。
+
+```json
+{
+  "agent": {
+    "dir": ".",
+    "skillsDir": "/path/to/your/skills/skills"
+  }
+}
+```
+
+`playcraft skills match` / `link` / `read` / `validate-atom-plan` 均按该配置（及 `AGENT_SKILLS_PATHS`、默认 `node_modules` 等）解析，**无需**在 `atom-plan.json` 重复填写 `packageSkillsRoot`。若误填了与 config 不一致的路径，校验会给出 warning。
+
+## 文件分工
+
+| 文件                    | 谁写                    | 内容                                                                                                                 |
+| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `docs/atom-plan.json`   | **PM**（Gate #1）       | `skillsMatch`（`playcraft skills match --json` 原文）、`atoms[]`（排期 DAG + `skillRef`）                            |
+| `docs/atom-plan.md`     | PM 骨架 + 各 Agent 富集 | Gate #1：**仅** `## Acceptance Criteria` + 空 Context 占位 + `## DAG Revisions`；**不要** Atom List / DAG Order 镜像 |
+| `playcraft.config.json` | 项目初始化              | `agent.skillsDir` — skills 库磁盘路径                                                                                |
+
+## PM Gate #1 流程
+
+```bash
+# 确认 playcraft.config.json 已配置 agent.skillsDir（或依赖 node_modules/@playcraft/skills）
+
+playcraft skills match --intent "<gameplayType>,<mechanic>,<keywords>" --json \
+  > /tmp/skills-match.json
+# 包一层写入 docs/atom-plan.json（见下方 jq 示例）
+
+playcraft skills validate-atom-plan
+playcraft skills link --from-atom-plan --prune
+```
+
+PM **STOP** 时 hook `validate-atom-plan.mjs` 会再次校验：所有非空 `skillRef` ∈ skills 库，且在 `skillsMatch.items` 中。
+
+### 最小 atom-plan.json 骨架（无需 cp template）
+
+```bash
+jq -n \
+  --argfile sm /tmp/skills-match.json \
+  '{
+    schemaVersion: 1,
+    skillsMatch: $sm,
+    atoms: [],
+    dagRevisions: []
+  }' > docs/atom-plan.json
+```
+
+再编辑 `atoms[]`；`atom-plan.md` 仍可从 `templates/atom-plan.template.md` 复制（Context 区）。
+
+## skillRef 规则
+
+- 仅 **GameplayAtom** / **ConfigAtom** 可有 `skillRef`
+- 必须为 `*.aigameplay` 或 `*.aiconfig`
+- 禁止 `playcraft-*`（平台管线 skill 在 `.claude/skills/playcraft-*`）
+- 禁止编造未出现在 `skillsMatch.items` 的 atomId（除非 `dagRevisions` 记录 `skills-match-gap`）
+
+## 下游如何读
+
+| 角色                     | 读 JSON                  | 读 MD                    | Skills 路径                                      |
+| ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------ |
+| Orchestrator / Developer | `atoms[]`、`skillsMatch` | `## Impl Skill Context`  | `playcraft.config.json` + `.claude/skills/` 软链 |
+| TA                       | `atoms[]`                | `## TA Skill Context`    | 同上                                             |
+| Designer                 | `atoms[]`                | `## Asset Skill Context` | 同上                                             |
+| Reviewer                 | 两者只读                 | 两者只读                 | —                                                |
+
+Developer 软链：`.claude/skills/<skillRef>/`（`playcraft skills link --from-atom-plan`）。断链时用 `playcraft skills read <skillRef>`（自动读 config，勿手抄 node_modules 路径）。