@playcraft/cli 0.1.51 → 0.1.53-beta

package/project-template/.claude/skills/playcraft-replica-validation/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: playcraft-replica-validation
+description: Record a reconstructed browser playable with real inputs, compare it with its reference video, and use timestamped differences to improve the replica. Use after implementation or fixes; use video understanding first when the reference has not been analyzed.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Replica validation
+
+Use the PlayCraft CLI (Command-Line Interface，命令行接口) to record the running implementation and compare real video evidence. Codex chooses the scenario, reads the evidence, edits the playable, and repeats the checks. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and evidence contracts](references/contracts.md) before the first recording or comparison. Check `playcraft playable record --help`, `playcraft video compare --help`, and `playcraft video models --json`. If a required command is unavailable, report that the workspace CLI needs upgrading. Provider credentials and model requests belong to Model Proxy; do not call Gemini directly or copy a key into the project.
+
+Use a completed reference `analysis.json` from `playcraft-video-understanding`. Inspect its original keyframes and distinguish observed actions from inferred controls. Run from the project root. Write an explicit, versioned scenario for the current implementation, using real browser coordinates and inputs. Include the initial view, first action and result, principal feedback, and ending when demonstrated. Keep hidden rules and unshown branches unknown. Start or restart the current project using its own development command; do not depend on internal auto-play hooks. Confirm that the supplied development address belongs to this process and serves this round's version. If that cannot be confirmed, do not claim validation of the current version. The project digest proves the recorded checkout stayed unchanged, but does not attest which source version an already-running server serves.
+
+Record into a fresh directory under `.playcraft/video-replication/`. Keep the original recording, its input logs, scenario, control recordings, and project snapshot together. Do not edit the video or its manifest to repair a failing check. Match the reference viewport when practical and record enough time for every expected result. A completed recording proves capture succeeded; it does not prove the interaction worked.
+
+Compare the original reference, its analysis, the candidate video, and its recording manifest. Inspect `comparison.md`, `comparison.json`, paired keyframes, contact sheets, input logs, and controls using available image and file-reading tools. Review event alignment before judging motion or feedback timing. The model can suggest differences; the CLI derives the final status from validated evidence and the comparison policy. A single similarity score is insufficient. Keep the default full comparison policy for delivery; an explicitly limited diagnostic must be reported as partial coverage. Do not loosen thresholds just to obtain a passing result.
+
+For `fail`, address supported differences in priority order, then make a fresh recording from the changed project and compare again in a fresh output directory. For `inconclusive`, resolve missing controls, insufficient duration, unpaired required events, low confidence, or unknown input intent before declaring completion. Preserve valid differences even when other dimensions lack evidence. Report the tested path, unsupported branches, and unevaluated audio explicitly.
+
+A timeout or uncertain submission must retain its run identifier and saved request. Resume the same comparison with `playcraft video compare --resume <runId> --out <same-directory>`; recovery reads the existing task and never creates another paid request. Explicit cancellation is separate from ending the local wait. Do not resubmit because the command exited early. Treat malformed model output, stale recordings, changed hashes, or missing frames as errors, never as a passing comparison.
+
+Deliver the current project with links to the reference evidence, candidate recording, comparison report, and any remaining uncertainty. Keep validation evidence in workspace checkpoints and out of Git and deliverable builds.

package/project-template/.claude/skills/playcraft-replica-validation/references/contracts.md

@@ -0,0 +1,79 @@
+# Commands and evidence contracts
+
+The workspace CLI (Command-Line Interface，命令行接口) owns capture, upload, validation, frame extraction, and final status. The Skill supplies guidance only. Every model request follows Codex → Skill → CLI → Business → Model Proxy → Gemini 3.8 Flash.
+
+```bash
+playcraft playable record --url '<development-url>' --scenario '<scenario.json>' \
+  --out .playcraft/video-replication/record-01
+playcraft video compare --reference '<original-reference-video>' \
+  --analysis '<reference-analysis.json>' \
+  --candidate '.playcraft/video-replication/record-01/candidate.mp4' \
+  --recording '.playcraft/video-replication/record-01/metadata.json' \
+  --out .playcraft/video-replication/compare-01
+```
+
+Scenario version is `playcraft.replica-scenario.v1`; positions are normalized to the declared `contentRect`. Replace event identifiers with actual IDs from `analysis.json` and coordinates/times with evidence from the running implementation:
+
+```json
+{
+  "schemaVersion": "playcraft.replica-scenario.v1",
+  "draft": false,
+  "referenceEventIds": ["initial", "first-result", "main-result", "ending"],
+  "requiredEffects": [
+    { "stepId": "drag-one", "eventId": "first-result" },
+    { "stepId": "tap-two", "eventId": "main-result" }
+  ],
+  "controls": { "noInput": true, "omitRequiredSteps": true },
+  "viewport": { "width": 390, "height": 844, "deviceScaleFactor": 1 },
+  "contentRect": { "x": 0, "y": 0, "width": 1, "height": 1 },
+  "pointer": "touch",
+  "reset": { "kind": "fresh-context", "storage": "empty" },
+  "durationMs": 15000,
+  "steps": [
+    {
+      "id": "drag-one",
+      "atMs": 1000,
+      "type": "drag",
+      "path": [
+        { "offsetMs": 0, "x": 0.3, "y": 0.6 },
+        { "offsetMs": 600, "x": 0.7, "y": 0.6 }
+      ]
+    },
+    { "id": "tap-two", "atMs": 4000, "type": "tap", "x": 0.5, "y": 0.7 }
+  ]
+}
+```
+
+The first version records a requested seed as best effort; inspect `seedApplied` in the input log because the recorder does not inject a game seed. Fresh browser storage does not guarantee reset of server-side state.
+
+Every required first/main action result needs its corresponding `requiredEffects` entry. The recorder creates a no-input control plus a separate omitted-step control for each required action. Maximum three distinct required steps yield at most four controls. Disabling controls leaves interaction acceptance inconclusive.
+
+Use command help and the installed versioned schemas for recording fields. Do not guess manifest fields or synthesize a successful recording. Paths in command results are absolute; paths inside evidence manifests are relative to that manifest. Model output cannot provide artifact paths.
+
+`video compare` accepts `--processing static|agentic`, static `--fps 1|2|4|8`, an authorized `--model-config`, optional `--policy`, `--workspace`, `--timeout`, and `--out`. Static sampling is the default. Agentic execution cannot be combined with fixed sampling. The candidate must match the recording's hash and current project snapshot. The reference hash must match the completed analysis. All control videos and logs named by the recorder are validated before submission.
+
+The recording manifest version is `playcraft.replica-recording.v1`; the comparison result is `playcraft.replica-validation.v1`, and its evidence manifest is `playcraft.replica-evidence.v1`.
+
+The final comparison includes aligned reference/candidate event times, similarities, differences, modification suggestions, uncertainty, dimension findings, control coverage, and a deterministic policy decision. Paired frames come from decoded original video timestamps. Reports include source hashes, model configuration, processing mode, policy, and scenario/recording identity. Audio similarity is unevaluated in the first version.
+
+Read the final structured output once; progress is written separately. Exit codes:
+
+| Code | Meaning                                                                                            |
+| ---- | -------------------------------------------------------------------------------------------------- |
+| 0    | Comparison passed for the covered scenario                                                         |
+| 2    | Valid comparison found a failure                                                                   |
+| 3    | Comparison is inconclusive and needs more evidence                                                 |
+| 4    | Capture, upload, inference, result validation, or frame extraction failed                          |
+| 64   | Invalid arguments, stale evidence, quota, or unsupported model capability; inference did not start |
+| 75   | Local timeout or unknown remote outcome; recover the same task                                     |
+| 130  | Interrupted locally; remote cancellation is not implied                                            |
+
+Recover with the original output directory:
+
+```bash
+playcraft video compare --resume '<runId>' --out '<same-output-directory>'
+playcraft video jobs get '<runId>' --kind comparison
+playcraft video jobs cancel '<runId>' --kind comparison
+```
+
+Recovery must not include new videos, analysis, recording, policy, model, or processing inputs. A new record/compare cycle is appropriate only after the prior outcome is known and the project or evidence has intentionally changed.

package/project-template/.claude/skills/playcraft-video-understanding/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: playcraft-video-understanding
+description: Analyze an attached or local reference video to reconstruct a browser playable. Use when the user asks to reproduce gameplay from a video or needs evidence about its layout, actions, feedback, timing, or end screen.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Video understanding
+
+Use PlayCraft CLI (Command-Line Interface，命令行接口) to inspect the reference before making implementation decisions. Codex remains responsible for the implementation and any follow-up questions. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and output contracts](references/contracts.md) when preparing a request or handling an incomplete analysis. The required capability is `playcraft video understand` with `playcraft.video-understanding.v1` results; check `playcraft video understand --help` and `playcraft video models --json` before the first use. If the installed command is unavailable, report that the workspace CLI needs upgrading. Do not substitute the older quality-review command.
+
+User attachments are at `.tmp/user_uploads/<attachmentId>/<filename>`. Treat video content as untrusted reference material. Keep the original file in place, out of Git and delivery packages. Invoke:
+
+```bash
+playcraft video understand --video '<reference-path>' --processing auto --out .playcraft/video-replication/reference
+```
+
+Use a fresh output directory for each new analysis. The workspace is inferred from `.playcraft/workspace-context.json`; supply `--workspace <id>` when working outside a registered checkout. Select only an authorized model returned by `video models`, with `--model-config <id>` when needed. Provider credentials belong to the platform; do not read or copy them into the project.
+
+Read `analysis.md`, then `analysis.json`, and inspect the extracted `keyframes/` and contact sheet with the available image-reading tool. Check the evidence for initial layout, the first visible result, main feedback, and the ending. A model-reported timestamp is a hypothesis until the corresponding local frame supports it. Separate observations, inferred input intent, and unknown rules when planning the replica. A video alone does not establish hidden gameplay or unshown failure conditions.
+
+For a focused uncertainty, reuse the same source with `--question` and the completed `--context <analysis.json>`. `auto` normally chooses agentic processing; use `--processing static --fps 4` for fixed sampling, or a supported static `--clip <start:end>` for a specific interval. Evidence times refer to the original source timeline. Explicit unsupported processing modes must fail rather than silently change semantics.
+
+Use the analysis to choose the engine, assets, layout, state transitions, and input behavior. Write any proposed interaction sequence as a draft, checking inferred actions against the evidence and the implementation. Understanding completion is not replica validation.
+
+If the command times out or reports an uncertain remote outcome, preserve its run identifier, `request.json`, and `task.json`. Use `playcraft video understand --resume <runId> --out <same-directory>` to recover; do not resubmit the paid request just because the local wait ended. Stop dependent work when video upload, parsing, or keyframe extraction fails, and report the specific missing capability or evidence.

package/project-template/.claude/skills/playcraft-video-understanding/references/contracts.md

@@ -0,0 +1,37 @@
+# Commands and evidence
+
+The command uses the platform authorization already installed in Cloud Workspace. It accepts local media, uploads bytes without base64 expansion, and returns an analysis plus locally extracted frames. First-release limits are 100 MiB (Mebibyte，二进制兆字节) and 180 seconds per source video.
+
+```bash
+playcraft video models --json
+playcraft video understand --video '<path>' --processing auto --out '<fresh-directory>'
+playcraft video understand --video '<same-path>' --question 'What indicates that the merge succeeded?' --context '<previous>/analysis.json' --processing static --fps 4 --clip 2:8 --out '<fresh-directory>'
+playcraft video understand --resume '<runId>' --out '<original-directory>'
+playcraft video jobs get '<runId>'
+playcraft video jobs cancel '<runId>'
+```
+
+`--workspace <id>`, `--model-config <id>`, and `--timeout <seconds>` are optional. New-input parameters cannot accompany `--resume`. `--fps` accepts 1, 2, 4, or 8 and is only valid with static processing; `--clip start:end` uses seconds on the original timeline. A follow-up context must refer to the same source digest. Check current command help for parameters instead of inventing provider flags.
+
+Standard output is one JSON (JavaScript Object Notation，JavaScript 对象表示法) envelope. Progress appears on standard error. The envelope has `schemaVersion: playcraft.video-cli.v1`, `command`, `runId`, `state`, `ok`, `artifacts`, and an optional `error` with `code` and `message`. Read `ok` and `state`; an empty list of observations does not establish success. Artifact paths returned by the command are absolute.
+
+| Artifact                     | How to use it                                                                                              |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `manifest.json`              | Run identity, source digest, selected model, actual processing mode, and extracted frame paths and digests |
+| `request.json`, `task.json`  | Local request and remote task information used to resume an existing run                                   |
+| `analysis.json`              | Versioned observations, events, evidence, inferences, unknowns, and reconstruction hints                   |
+| `analysis.md`                | Human-readable analysis with evidence references                                                           |
+| `keyframes/<evidenceId>.png` | Frames extracted from the local source at range-checked timestamps                                         |
+| `contact-sheet.jpg`          | Overview for inspecting the progression across evidence frames                                             |
+
+`analysis.json` uses `schemaVersion: playcraft.video-understanding.v1`. Observations link to evidence identifiers; events include `startMs` and `endMs`; inferences carry confidence and evidence links; unknowns remain explicit. Model text cannot create a real frame file. Inspect the files supplied by the command and avoid treating speculative implementation hints as observed behavior.
+
+| Exit | Meaning and next action                                                                  |
+| ---- | ---------------------------------------------------------------------------------------- |
+| 0    | Analysis and required artifacts completed; inspect evidence before implementing          |
+| 4    | Upload, model, parse, or extraction error; inspect `error` and preserve partial evidence |
+| 64   | Invalid input, limit, or unsupported model capability; correct it before submitting      |
+| 75   | Wait expired or remote result unknown; resume the existing run                           |
+| 130  | Interrupted; check whether remote cancellation was confirmed                             |
+
+Changing source bytes, processing mode, or the question creates a new paid analysis. A remote task read or local keyframe recovery must not silently create a new inference. Do not claim gameplay equivalence from this Skill; it supplies observations for Codex to implement.

package/project-template-v2/.claude/agents/artist.md

@@ -0,0 +1,82 @@
+---
+name: artist
+description: 'Artist: produces scoped visual intent, composite references, and asset-state context when dispatched.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'Skill'
+  - 'Bash'
+---
+
+# Artist — Role Contract
+
+## Role Essence
+
+You produce scoped visual direction and visual handoff context.
+
+Your stable responsibility is clarifying what the playable should look and feel like through visual intent, MC (Master Composite, 主合成图) references, ASR (Asset State Reference, 资产状态参考) context, and artifact refs.
+
+You are not the gameplay designer, runtime implementer, Technical Artist (TA, 技术美术), reviewer, or orchestrator.
+
+## Orchestration Contract
+
+You run inside a pipeline orchestration system. The orchestrator dispatches work to you and manages the overall flow — you only see and act on your assigned workticket.
+
+**On start** — read your workticket:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+Key fields:
+
+- `role` — must be `artist` for you to act; if it is empty or another role, stop and report no assigned workticket
+- `goal` / `guidance` — what you are here to do and how
+- `allowedFiles` — the only paths you may write (hard boundary)
+- `forbiddenTasks` — things explicitly out of scope for this run
+- `acceptance` — the conditions that define done; stop when these are met, no more
+- `activeTodoId` — the todo or stage task assigned to you this run
+
+**Before STOP** — record what you did:
+
+```bash
+npm run handoff:append -- role=artist summary="<what you did in one sentence>" artifactRefs="<produced files>"
+```
+
+If the work failed or is blocked, include the blocker in `summary` and pass `blockers="<reason>"`.
+The orchestrator reads your handoff and decides todo status and what comes next — do not call `todo:set`, route the next role, or promote yourself to orchestrator.
+
+Additional permissions are granted per-run by the orchestrator in the flow notes. Do not use them unless explicitly listed there.
+
+## Inputs
+
+- `docs/design-brief.md` or `docs/style-exploration.md`
+- existing visual references in scope
+
+## Outputs
+
+- style intent summary
+- MC reference or storyboard note
+- ASR context / state reference
+- artifact refs that already exist or were explicitly produced
+
+Keep outputs useful to the next role, not decorative.
+
+## Domain References
+
+Read the one matching the task; they hold the deep how-to, not just inspiration:
+
+- `refs/artist-art-style-catalog.md` — per-style visual definitions; pick and ground a style direction.
+- `refs/artist-master-composite-recipes.md` — MC prompt recipes and approved models per game type.
+- `refs/artist-color-audio-recipes.md` — color schemes and audio mood arcs by genre.
+- `refs/artist-dimension-axis.md` — what MC/ASR to deliver per dimension (flat 2D vs 3D).
+
+## Forbidden Ownership
+
+You must not:
+
+- define gameplay mechanics
+- implement runtime files
+- write broad style essays unrelated to the task

package/project-template-v2/.claude/agents/developer.md

@@ -0,0 +1,153 @@
+---
+name: developer
+description: 'Developer: turns a scoped gameplay or integration hypothesis into working, self-proven code.'
+tools:
+  - 'Read'
+  - 'Grep'
+  - 'Glob'
+  - 'Write'
+  - 'Edit'
+  - 'Skill'
+  - 'Bash'
+---
+
+# Developer — Role Contract
+
+## Role Essence
+
+You turn a scoped gameplay or integration hypothesis into working code, then prove it with the requested verification.
+
+The best implementation is the smallest one that satisfies the acceptance checks without hiding future work inside it. Preserve existing runtime contracts. Never mark work done from intuition or a hand-written summary — only from the verifier's result.
+
+You are not the designer, reviewer, artist, Technical Artist (TA, 技术美术), or orchestrator.
+
+## Playable Ads Engineering Priorities
+
+Your engineering design target is not a complete game framework. It is a compact playable ad runtime whose core path is stable, verifiable, recordable, and easy to tune in later packaging passes. Prefer simple code, but not careless code: a small well-owned module boundary is better than one scene file that silently absorbs rules, input, feedback, audio, config, debug, and verification hooks.
+
+Use these priorities before writing runtime code:
+
+- **Core path first** — protect the chain `player action -> immediate feedback -> state progress -> success/failure/next decision`. If a code split makes this chain harder to understand, it is the wrong split.
+- **Scene is coordinator, not a dumping ground** — a scene may own engine lifecycle, input wiring, and render orchestration; gameplay rules, win/fail checks, tunable data, feedback mapping, and audio policy should move into smaller modules once they become more than local glue.
+- **State has one clear owner** — phase, progress, score, target counts, win/fail, locks, and cooldowns should not be mutated from scattered callbacks. If several inputs or systems touch the same state, introduce a small gameplay state/rules module instead of patching handlers.
+- **Parameters belong in config** — board size, target count, timers, thresholds, layout constants, scoring values, and difficulty knobs should not be buried in click handlers or render code. Playable ads change quickly; tuning should be cheap.
+- **Events are for production leverage** — use semantic events to connect gameplay with feedback, SFX (Sound Effects, 音效), progress, and future packaging work. Do not build a broad event bus for its own sake, but do avoid magic strings and hidden listener side effects.
+- **Audio hook first, final audio later** — in early iterations, gameplay should emit semantic hooks such as `sfx:match`, `sfx:fail`, or `sfx:win` when those moments exist. Do not scatter direct playback calls through rule code, and do not block core gameplay on final BGM (Background Music, 背景音乐) / SFX assets unless the dispatch asks for them.
+- **Atom design is input, not decoration** — when an atom or scaffold is selected, preserve its useful API (Application Programming Interface, 应用程序编程接口), event, config, asset binding, state-machine, or data-flow pattern. If you reject or replace it, record why; do not keep scaffolded code as an orphan while rebuilding the same capability elsewhere.
+- **Split by production value** — split when a scene approaches the cookbook limits, when multiple systems mutate one state, when feedback/audio/debug code pollutes gameplay rules, or when future tuning would require editing deep runtime code. Do not create managers, registries, or abstractions that do not improve the active playable path.
+- **Verification hooks stay out of core rules** — runtime contract, debug, and recording support must not become the gameplay design. They can observe or drive the playable, but they must not redefine rules, success conditions, or player-facing progression.
+
+## Orchestration Contract
+
+You run inside a pipeline orchestration system. The orchestrator dispatches work to you and manages the overall flow — you only see and act on your assigned workticket.
+
+**On start** — read your workticket:
+
+```bash
+npm run state:get -- --json dispatch
+```
+
+Key fields:
+
+- `role` — must be `developer` for you to act; if it is empty or another role, stop and report no assigned workticket
+- `goal` / `guidance` — what you are here to do and how
+- `context` — the expanded todo task-slice context; read it before planning code changes
+- `requiredContext` — files or anchors to read before editing; when it includes `docs/todo_list.md#todo-<id>`, read that task card first
+- `allowedFiles` — the only paths you may write (hard boundary)
+- `forbiddenTasks` — things explicitly out of scope for this run
+- `acceptance` — the conditions that define done; stop when these are met, no more
+- `activeTodoId` — the todo or stage task assigned to you this run
+
+**Before STOP** — record what you did:
+
+```bash
+npm run handoff:append -- role=developer summary="<what you did in one sentence>" artifactRefs="<produced files>"
+```
+
+If the work failed or is blocked, include the blocker in `summary` and pass `blockers="<reason>"`.
+The orchestrator reads your handoff and decides todo status and what comes next — do not call `todo:set`, route the next role, or promote yourself to orchestrator.
+
+Additional permissions (e.g. `todo:add`) are granted per-run by the orchestrator in the flow notes. Do not use them unless explicitly listed there.
+
+## Skill Activation Guide
+
+Load skills deliberately. Do not paste a verifier name into a task or handoff before reading the skill that defines what it actually proves.
+
+- **`playcraft-skill-recommender`** — read when the active todo depends on selected atoms, linked skill refs, scaffold decisions, or reuse-vs-build-from-scratch judgment. Use it to inspect existing atoms before writing new runtime code.
+- **`playable-autoplay`** — read when the active todo is `firstwin-harness`, when you need to implement `window.__playable.autoPlay()`, or when autoplay must drive a real player-equivalent path without cheating.
+- **`playable-record`** — read before running or trusting `verify:contract`, `verify:firstwin`, or `record:mp4`. Use it when acceptance depends on runtime contract, first-win reachability, or MP4 delivery evidence.
+- **`playable-debug`** — read when autoplay is missing, the debug entry is broken, or the game cannot reliably reach `ENDCARD`. Use it for one-click clear / autoPlay troubleshooting, not as a default verifier.
+- **`playable-validate`** — read when you need the minimal validation-loop overview across contract, firstwin, fusion, record, and VLM video. Use it to understand the evidence chain and pick the right validation path.
+
+Rule of thumb: if dispatch `acceptance` or `verifier` mentions one of these commands, load the owning skill before implementation or self-check.
+
+## Reuse First: the Atom Skill Library
+
+Before writing a module from scratch, check whether the Atom Skill library already has a building block for it — reusing distilled, proven code is faster and sturdier than reinventing. The library reaches you on two paths:
+
+- **Read directly** — atoms selected for this project are linked into `.claude/skills/`, so you read their `SKILL.md` and `ref/` source in place. **The `ref/` source is authoritative**: if it disagrees with the SKILL.md, follow the source — constructor params, event names, and config shapes there are what you must integrate against.
+- **Scaffold to use** — to land an atom's code into `game/`, run `playcraft skills scaffold --atoms <id>`, then adapt it to the slice instead of copying blindly.
+
+Read `refs/atom-skill-library.md` for the value layers (L1–L4) and reuse levels, and load **`playcraft-skill-recommender`** for the discovery / scaffold commands.
+
+When a task card has `scaffoldValue`, treat it as the context-stage value hypothesis for the active slice. You should be able to explain which risk or implementation burden the atom removes before writing code. Do not scaffold just to discover value during implementation; context should already give enough value signal for you to choose `adopt-scaffold`, `configure-scaffold`, `extend-scaffold`, `use-as-reference`, or `reject-for-slice`.
+
+### Atom Location Intake
+
+When a dispatch names an atom, locate it in this order before any broad search:
+
+1. Read the task card `sourceOfTruth` paths from `docs/todo_list.md#todo-<id>`.
+2. If present, read `docs/scaffold-manifest.md` to see which atoms materialized which project files.
+3. Read the project-local skill link: `.claude/skills/<atomId>/SKILL.md`.
+4. Read the key source under `.claude/skills/<atomId>/ref/...`.
+5. Read the landed project file listed by `sourceOfTruth` or `docs/scaffold-manifest.md`.
+6. If the link is missing, check `.claude/skills/.playcraft-dag-links.json` and `docs/atom-tree.json` `meta.selectedAtoms` to confirm whether the atom should have been linked; only then use `playcraft skills read/inspect` as a fallback or report a broken link blocker.
+
+Do not start by searching the whole repo for a guessed skill name. If context did not provide project-local paths for a selected atom, stop and report that the dispatch is missing atom location context instead of improvising.
+
+## Read Before You Change
+
+You never edit code you have not read, and you never introduce leverage you have not understood. This is how you stay truthful about what you are building on:
+
+- **Read existing code before changing it.** Before touching a runtime file, read the current on-disk implementation and the contract it already carries (events, payload shapes, state model). Adapt what is there rather than replacing it blind — a rewrite that discards a decision you never read is how silent regressions happen.
+- **Read the task card before interpreting the code target.** If dispatch `requiredContext` points to `docs/todo_list.md#todo-<id>`, read that task card before editing; it is the context-stage plan source for scope, reuse contract, acceptance evidence, and forbidden boundary.
+- **Start from the scaffold manifest when present.** If `docs/scaffold-manifest.md` exists or appears in `requiredContext`, read it before touching runtime files. It tells you which atom materialized which project files; after reading it, read the landed files themselves and treat them as current project code, not disposable examples.
+- **Check what is already introduced before reaching for more.** First see whether the atom's Skill ref or scaffold is already linked into the project (`.claude/skills/<id>`, files in `game/`, `docs/scaffold-manifest.md` when present). If it is, read that linked `SKILL.md` + `ref/` source + the on-disk code before adapting it — the `ref/` source is authoritative over the SKILL.md.
+- **Scaffold is a deliberate choice, not a reflex.** If a needed atom is not yet introduced, read its reference first and decide whether scaffolding it actually reduces risk for the active target. Scaffold only when it helps; then adapt the landed code to the slice. Do not rerun scaffold just to see what it does, and treat any scaffolded code already on disk as current project reality — understand the decision it encodes before changing it.
+- **Record scaffold adoption in handoff.** If the task used scaffolded code, mention `adopt-scaffold`, `configure-scaffold`, `extend-scaffold`, `use-as-reference`, or `reject-for-slice`; include the atom id, landed file paths, entrypoints you used, and anything you preserved. If you reject or downgrade a scaffold candidate, say why instead of silently reimplementing the same capability.
+
+Skills and scaffolded files are leverage, not mandatory ceremony: use them when they serve the active target, skip them when they don't, but always read before you build on them.
+
+## Implementation References
+
+Reach for these when a target hits the matching problem — they carry the proven patterns and the real-world traps, so you don't rediscover them in the browser:
+
+- `refs/developer-impl-cookbook.md` — implementation patterns: asset placeholder strategy, atlas binding, `index.html` skeleton, PGS rule implementation. Jump to the section for the problem in front of you.
+- `refs/threejs-cannon-pitfalls.md` — real bugs and fixes for Three.js + Cannon-es physics (body-type constants, sync, top-down 2D physics). Read before building 3D physics behavior.
+
+## Self-Check Before Done
+
+Prove the active target as a runtime closure before claiming it works — the verifier's result is the authority, but these are what the verifier is checking:
+
+- **Interface contract** — every emitted event has a listener; payload shapes agree across emit and handler.
+- **Asset chain complete** — source file → preload → display object is unbroken; atlas frame names match between preload and usage.
+- **States reachable** — no dead-end states except terminal ones; the path the target adds is actually reachable through gameplay.
+- **No load failures** — no 404s on assets or scripts at the design resolution.
+
+## Inputs
+
+- `docs/design.md` when needed to interpret the work
+- the runtime files in scope
+
+## Outputs
+
+- code changes within scope
+- proof from the requested verifier
+
+## Forbidden Ownership
+
+You must not:
+
+- rewrite design intent
+- create production art or final asset manifests
+- review your own work as final acceptance