@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/phaser/templates/ta-log.template.md

@@ -0,0 +1,394 @@
+# Technical Artist Log
+
+## Upstream Intake
+
+> **Step 0a — mandatory before Skill Discovery or any generation.** Read each doc; one-line takeaway proves you understood upstream work. Game Designer/Artist keep **四件套** short — detail is in `style-exploration` + this project's `artist-log`.
+
+| Doc                         | Read ✓ | One-line takeaway (what matters for TA this round)      |
+| --------------------------- | ------ | ------------------------------------------------------- |
+| `docs/project-state.md`     | ☐      | {{e.g. Wave 1 done, selectedMcOption=B}}                |
+| `docs/design-brief.md`      | ☐      | {{e.g. Competence arc, match-3, Hook=wrong-move tease}} |
+| `docs/layout-spec.md`       | ☐      | {{e.g. 42 assetMapping rows, 3 atlas groups}}           |
+| `docs/atom-tree.json`       | ☐      | {{e.g. 18 TA atoms, C₁ refs artist-sample}}             |
+| `docs/atom-tree.md`         | ☐      | Reading guide + mediaGroups decisions                   |
+| `docs/style-exploration.md` | ☐      | {{e.g. MC path + storyboard EndCard tone}}              |
+| `logs/artist-log.md`        | ☐      | {{e.g. Palette Locked delta, Style Intent Notes}}       |
+
+```bash
+# Optional paste: ls assets/images/reference/ + key contract dirs after read
+{{intake_ls_snippet}}
+```
+
+---
+
+## Delivery Summary
+
+- **Assigned atoms**: {{total_assigned}}
+- **Completed**: {{total_completed}}
+- **Skipped**: {{total_skipped}}
+- **Blocked**: {{total_blocked}}
+- **Artist samples received**: {{artist_sample_count}} files
+- **TA-completed elements**: {{ta_completed_count}} files
+
+---
+
+## mediaGroups Reuse
+
+> **Step 0 Pre — mandatory before Skill Discovery.** Filter `atom-tree.json` → `meta.skillsMatch.mediaGroups` by `extension`; TA is responsible for **`.aiimage` + `.aisprite`** (Artist handles `.aiaudio`).
+
+| mediaGroup atomId | extension          | Matches TA atom? | Disposition   | Reason (if skipped)             | Output path (if linked) |
+| ----------------- | ------------------ | ---------------- | ------------- | ------------------------------- | ----------------------- |
+| {{mg_atomId}}     | .aiimage/.aisprite | {{atom_id / —}}  | linked / skip | {{style mismatch / wrong dims}} | {{path / —}}            |
+
+<!--
+  TA scope (this table):
+    .aiimage  — single-shot image bundles (bg, single ui element, single tile)
+    .aisprite — sprite-sheet bundles (multi-frame: tile sets, vfx, animations)
+
+  Out of TA scope (do NOT fill rows for these — Artist owns them):
+    .aiaudio — BGM / SFX → see artist-log.md § mediaGroups Reuse
+
+  Filter command:
+    cat docs/atom-tree.json | jq '.meta.skillsMatch.mediaGroups[] | select(.extension == ".aiimage" or .extension == ".aisprite")'
+
+  Disposition rules:
+    linked → playcraft skills link → post-process (resize/convert/transparency) → status=done
+    skip   → quality / style / wrong dimensions → document reason → generate from scratch
+
+  This section MUST be filled before proceeding to Step 0 Skill Discovery.
+-->
+
+---
+
+## Skill Preflight
+
+> **Step 0 Part C — mandatory before production.** Read all relevant playcraft pipeline Skills.
+
+| Skill                       | 已读 | 关键决策摘要                                              |
+| --------------------------- | ---- | --------------------------------------------------------- |
+| playcraft-image-generation  | ☐    | {{model choice, reference-image strategy, background}}    |
+| playcraft-masking           | ☐    | {{floodfill tolerance, segment fallback, method-ai case}} |
+| playcraft-sprite-generation | ☐    | {{single-frame→merge workflow, batch threshold}}          |
+| playcraft-text-rendering    | ☐    | {{blue screen for text, stroke protection}}               |
+| playcraft-vfx-animation     | ☐    | {{per-frame generation, blue screen for VFX}}             |
+| playcraft-batch-pipeline    | ☐    | {{>5 elements → script, reference anchoring}}             |
+| playcraft-style-qa          | ☐    | {{dark-bg verify, MC consistency check}}                  |
+
+<!--
+  MUST be filled before Step 1 bulk generation. Each row: ✅ after reading + one-line decision summary.
+  Without this table → no bulk generation → no STOP.
+-->
+
+---
+
+## Style Interpretation
+
+> **Step 0c — Mandatory before any completion work.**
+> Read `logs/artist-log.md` Style Intent Notes, write your interpretation here.
+
+| #     | Artist Intent (Quote from artist-log.md) | My Interpretation     | Confidence      | Action            |
+| ----- | ---------------------------------------- | --------------------- | --------------- | ----------------- |
+| {{n}} | "{{artist_quote}}"                       | {{my_interpretation}} | high/medium/low | proceed / clarify |
+
+<!--
+Confidence rules (atom-granularity — hold only the affected asset type, not the whole Wave 2):
+  high    → proceed with completion
+  medium  → proceed, but include style interpretation in --reference-image prompt
+  low     → HOLD that asset type only: write question to docs/intent-clarifications.md
+           (routeTo: artist if style ambiguity; routeTo: game-designer if contract ambiguity)
+           → continue producing OTHER asset types where confidence ≥ medium
+           → resume the held type only after ICP answer (or Artist supplementary PNG per
+             artist-deliverable-spec.md § "ICP supplementary PNG — when (and only when)")
+
+You may STOP only when EVERY remaining asset type is held at confidence=low — otherwise keep
+making progress on the producible ones in parallel with the ICP wait.
+-->
+
+## Production Plan
+
+> **Step 0d — mandatory before any asset generation.** Plan WHAT to produce, in WHAT order, using WHAT pipeline.
+
+### Coverage Plan
+
+| assetMapping id | Contract path             | Pipeline               | Reference source  | Priority        |
+| --------------- | ------------------------- | ---------------------- | ----------------- | --------------- |
+| {{elementId}}   | {{path from layout-spec}} | {{extract/generate/…}} | {{MC/ASR/sample}} | {{high/normal}} |
+
+<!--
+One row per layout-spec assetMapping entry. Row count must match assetMapping count (no gaps).
+-->
+
+### Atlas Assembly Plan
+
+| Atlas group | Output path (.webp + .json)     | Elements (frameIds)  | Layout       |
+| ----------- | ------------------------------- | -------------------- | ------------ |
+| {{tiles}}   | {{assets/images/tiles/…_atlas}} | {{tile_01..tile_06}} | {{3x2 grid}} |
+
+<!--
+Must match layout-spec § atlas grouping table.
+-->
+
+### Pipeline Order
+
+1. Extract: crop MC/ASR reference elements (Stage E)
+2. Complete: batch generate remaining elements (Stage A)
+3. Process: resize + format convert to WebP (Stage B)
+4. Assemble: build atlases with JSON sidecars (Stage C)
+5. Verify: Compliance Gate on all paths
+
+### Risk Checklist
+
+- [ ] Every assetMapping entry in Coverage Plan (no gaps)
+- [ ] Atlas groups match layout-spec grouping table
+- [ ] MC + ASR reference images accessible
+- [ ] Style Interpretation confidence ≥ medium for all asset types
+- [ ] Transparency Classification table complete (Step 0e below)
+
+**MUST NOT** start bulk generation until every Risk Checklist item is checked `[x]`.
+
+---
+
+## Transparency Classification
+
+> **Step 0e — mandatory before any generation.** TA auto-derives `needsAlpha` from path convention + `alphaStrategy` from element color palette and edge softness. See `ta-pipeline-cookbook.md` Step 0e and `skills/playable-art/references/alpha-postprocess.md` for full rules.
+
+| #     | assetMapping path | needsAlpha     | alphaStrategy                                      | Prompt strategy              | Postprocess tool                                      | Fallback                           | Dark-bg verify | 验证结果    |
+| ----- | ----------------- | -------------- | -------------------------------------------------- | ---------------------------- | ----------------------------------------------------- | ---------------------------------- | -------------- | ----------- |
+| {{n}} | {{path}}          | {{true/false}} | {{chroma / dual-bg-diff / rgb-alpha-split / black-add / opaque}} | {{green key / RGB+A / etc.}} | {{remove-bg / extract-alpha-split / dual-bg / N/A}} | {{rgb-alpha-split / black-add / N/A}} | {{clean / fail}} | {{✅ / ❓}} |
+
+<!--
+TA auto-derives transparency — does NOT depend on Game Designer fields.
+
+needsAlpha derivation (from assetMapping path):
+  images/bg/    → false (full-screen background)
+  images/ui/    → true  (UI overlay)
+  images/txt/   → true  (text image)
+  images/vfx/   → true  (VFX sprite)
+  images/tiles/ → true  (default; unless card/board rect body → false)
+
+alphaStrategy derivation:
+  Hard-edge UI/text/sprite    → chroma (choose green/blue/magenta by palette conflict)
+  Soft antialias/shadow       → rgb-alpha-split first; dual-bg-diff only when geometry is fixed
+  VFX glow/particle/ring      → black-add when ADD blend is acceptable; otherwise rgb-alpha-split
+  Full-screen background      → opaque
+
+chroma key color derivation:
+  Gold/yellow/orange/amber   → bluescreen (NEVER green — color bleed)
+  Green/teal/cyan            → bluescreen (NEVER green — same family)
+  Blue/indigo/purple         → greenscreen (NEVER blue — same family)
+  Multi-color/rainbow        → magenta (last resort)
+  Red/pink/white/black       → greenscreen or bluescreen (both safe)
+
+TA tool chain (must use, never skip):
+  1st: playcraft image remove-background --method floodfill --tolerance 25
+  2nd: python3 skills/playable-art/scripts/extract-alpha-split.py (RGB+A side-by-side)
+  3rd: python3 skills/playable-art/scripts/extract-dual-bg-alpha.py (matched dual backgrounds)
+  4th: playcraft image segment --boxes (complex edges, known position)
+  5th: playcraft image remove-background --method ai (hair/transparency)
+  6th: playcraft image segment --text (unknown position, last resort)
+  Extract: playcraft image crop (grid) or decompose-layers (multi-layer MC)
+
+Post-verify: overlay on #1A1A2E dark bg to check:
+  ✅ No white edges, no chroma residue, no black blocks, clean edges
+  ❌ If any issue → escalate through fallback tool chain
+-->
+
+**MUST NOT** proceed to Step 1 bulk generation if any row has `❓ pending` in 验证结果.
+
+### Video Alpha Classification
+
+| #     | video path | videoAlphaStrategy                                      | Matte source            | Validator evidence | Fallback             |
+| ----- | ---------- | ------------------------------------------------------- | ----------------------- | ------------------ | -------------------- |
+| {{n}} | {{path}}   | {{chroma-video / dual-bg-video / rgb-alpha-video / opaque-video}} | {{green / dual / alpha / n-a}} | {{MP4 timestamp + symptom}} | {{rerender / still sprite / n-a}} |
+
+<!--
+Video alpha is a production convention in this template, not a full codec pipeline.
+Validator feedback must still route symptoms:
+  green edge / matte spill → chroma-video key conflict
+  double subject / shimmer → dual-bg-video geometry drift
+  alpha timing mismatch → rgb-alpha-video matte alignment
+  black box around glow → use black-add still frames or VFX clean harness
+-->
+
+---
+
+## Style Reference
+
+- **Master reference (MC)**: `assets/images/storyboard/master_composite_option_{{selectedMcOption}}.png`
+- **ASR references**: `ui_state_sheet_{{selectedMcOption}}.png`, `element_state_sheet_{{selectedMcOption}}.png`
+- **Artist samples used as reference**: {{artist_sample_paths}}
+- **Reference model used**: `{{model_name}}` (must be `google/` native for style-consistent completions)
+
+---
+
+## Asset Completion Log
+
+> Records all elements derived from Artist samples.
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Completion type**: {{derived_from_sample | sprite_sheet | 3d_render | animation | vfx}}
+- **Source samples**: {{artist_sample_paths}}
+- **Elements completed**:
+  | File | Dimensions | Size | Notes |
+  |------|-----------|------|-------|
+  | {{path}} | {{WxH}} | {{size}} | {{notes}} |
+- **Pipeline**:
+  ```
+  {{step 1: e.g., generate-image --reference-image ...}}
+  {{step 2: e.g., image remove-background ...}}
+  {{step 3: e.g., image resize ...}}
+  ```
+- **Model used**: {{model_name}}
+- **Reference images**: {{reference_image_paths}}
+
+<!-- Repeat for each completion atom -->
+
+---
+
+## Technical Pipeline Log
+
+> Records all technical production work (sprite sheets, 3D, animation, VFX, post-processing).
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Pipeline type**: {{sprite_sheet | 3d_model | animation_frames | vfx | image_processing | audio_processing}}
+- **Input**: {{input_files}}
+- **Output**: {{output_files}}
+- **Commands executed**:
+  ```bash
+  {{command 1}}
+  {{command 2}}
+  ```
+- **Result**:
+  | File | Format | Dimensions | Size | Frame Count |
+  |------|--------|-----------|------|-------------|
+  | {{path}} | {{format}} | {{WxH}} | {{size}} | {{N or —}} |
+
+<!--
+For sprite_sheet / animation_frames / vfx pipeline types, fill the Sprite Grid Params section below.
+JSON is only auto-generated by `sprite-sheet` command. `animate` and `use-vfx` produce PNG only.
+-->
+
+- **Sprite Grid Params** _(animation_frames / vfx 必填；sprite_sheet 填"见 JSON")_:
+  - columns: {{N or "见 JSON"}}
+  - frameWidth: {{W}}px _(or "见 JSON")_
+  - frameHeight: {{H}}px _(or "见 JSON")_
+  - frameCount: {{N or "见 JSON"}}
+  - padding: {{0 or N}}px
+  - JSON available: {{yes — `<path>.json` (sprite-sheet) / no — params above are source of truth (animate/use-vfx)}}
+  - Dimensions verified: {{width = cols×frameW ✅ / ❌ mismatch}} | {{channels = 4 ✅ / ❌ no alpha}}
+
+<!-- Repeat for each pipeline atom -->
+
+---
+
+## Micro-Batch Validation
+
+> **Per asset type — first 2 completions must pass validation before continuing batch production.**
+> Compare each completion side-by-side with the Artist sample.
+
+### {{asset_type}} (e.g., tiles / ui / bg / vfx)
+
+| Batch | Files         | Consistency Score (1-5) | Deviation Items    | Adjustments Made |
+| ----- | ------------- | ----------------------- | ------------------ | ---------------- |
+| {{n}} | {{file_list}} | {{score}}               | {{deviation_list}} | {{adjustments}}  |
+
+<!--
+Consistency Score criteria:
+  5 — Perfect match: could be mistaken for original artist sample
+  4 — Good match: minor differences only visible on close inspection
+  3 — Acceptable match: style is recognizable but some attributes drift
+  2 — Poor match: obvious style deviation, needs significant adjustment
+  1 — Mismatch: completely different style, STOP and ask Artist
+
+Score < 3 → STOP this asset type, write question to docs/intent-clarifications.md
+-->
+
+---
+
+## Compliance Gate Results
+
+> Completed after Artist Ph.2 is confirmed done. Verify all assetMapping entries.
+
+### Asset Coverage Check
+
+| assetMapping Entry | Expected Path        | File Exists? | Dimensions | Size     | Status        |
+| ------------------ | -------------------- | ------------ | ---------- | -------- | ------------- |
+| {{elementId}}      | {{visualAsset_path}} | {{Yes/No}}   | {{WxH}}    | {{size}} | {{PASS/FAIL}} |
+
+<!--
+Fill one row per entry in layout-spec.md assetMapping.
+Every row must be PASS before advancing to integration.
+-->
+
+### Spec Compliance Summary
+
+| Check                      | Target                                                     | Actual     | Result        |
+| -------------------------- | ---------------------------------------------------------- | ---------- | ------------- |
+| Background dimensions      | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| Tile dimensions            | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| UI element dimensions      | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| **Text dimensions**        | `images/txt/*` per `layout-spec` text spec (W×H per label) | {{actual}} | {{PASS/FAIL}} |
+| **Digit Strip dimensions** | `images/txt/digits*` cellW × cellH × frameCount (0–9 = 10) | {{actual}} | {{PASS/FAIL}} |
+| Background file size       | < 500KB                                                    | {{actual}} | {{PASS/FAIL}} |
+| Tile file size             | < 100KB per tile                                           | {{actual}} | {{PASS/FAIL}} |
+| BGM file size              | < 300KB                                                    | {{actual}} | {{PASS/FAIL}} |
+| SFX file size              | < 50KB per SFX                                             | {{actual}} | {{PASS/FAIL}} |
+| Total assets size          | ≤ 2-3MB                                                    | {{actual}} | {{PASS/FAIL}} |
+| Sprite sheet JSON paired   | Every .png sheet has .json                                 | {{yes/no}} | {{PASS/FAIL}} |
+
+<!--
+  Text dimensions: every `images/txt/*` asset must match per-label W×H from layout-spec § Static text (or atlas grouping for text atlas).
+  Digit Strip dimensions: digit sprite (typically `images/txt/digits.webp` or `images/ui/digits.webp`) must satisfy:
+    - frameCount = 10 (0–9) — for score / countdown / level display
+    - width  == cellW × frameCount (when laid out as a single row)
+    - height == cellH (single-row strip)  OR  width × height matches multi-row grid in JSON sidecar
+    - channels = 4 (alpha for overlay)
+  If digit strip is split across multiple paths (e.g. small + large) each needs its own row.
+-->
+
+### Transparency Compliance
+
+| Check                        | Target                                             | Actual     | Result        |
+| ---------------------------- | -------------------------------------------------- | ---------- | ------------- |
+| Classification table         | All rows filled, no ❓ pending                     | {{status}} | {{PASS/FAIL}} |
+| Alpha channels (transparent) | All transparent assets channels=4                  | {{count}}  | {{PASS/FAIL}} |
+| Dark-bg verify (transparent) | All transparent assets clean on #1A1A2E overlay    | {{count}}  | {{PASS/FAIL}} |
+| Alpha strategy recorded      | Every transparent asset has alphaStrategy + fallback | {{status}} | {{PASS/FAIL}} |
+| Video alpha strategy         | Every video asset has videoAlphaStrategy or opaque-video | {{status}} | {{PASS/FAIL}} |
+| BG full-coverage             | All backgrounds edge-to-edge, no fade/white corner | {{status}} | {{PASS/FAIL}} |
+| Atlas per-frame verify       | VFX/atlas each frame verified on dark bg           | {{status}} | {{PASS/FAIL}} |
+| Chroma residue               | Zero color residue from chroma key removal         | {{status}} | {{PASS/FAIL}} |
+
+### Compliance Verdict
+
+- **Overall**: {{PASS / FAIL}}
+- **Blockers** (if any): {{list of FAIL items that block integration}}
+- **Ready for Reviewer ui_diff**: {{Yes / No — pending fixes}}
+
+---
+
+## Handoff to Developer
+
+Summary of what TA delivers to Developer:
+
+| Asset Type          | Count | Paths                  | Notes                 |
+| ------------------- | ----- | ---------------------- | --------------------- |
+| Background images   | {{N}} | `assets/images/bg/`    | {{notes}}             |
+| Tile/element images | {{N}} | `assets/images/tiles/` | {{notes}}             |
+| UI elements         | {{N}} | `assets/images/ui/`    | {{notes}}             |
+| Sprite sheet atlas  | {{N}} | `assets/images/*/`     | Each has paired .json |
+| Animation frames    | {{N}} | `assets/images/*/`     | {{notes}}             |
+| VFX sprite sheets   | {{N}} | `assets/images/vfx/`   | {{notes}}             |
+| 3D GLB models       | {{N}} | `assets/models/`       | {{notes}}             |
+| BGM audio           | {{N}} | `assets/audio/bgm/`    | {{notes}}             |
+| SFX audio           | {{N}} | `assets/audio/sfx/`    | {{notes}}             |
+
+**All files path-match `layout-spec.md` assetMapping**: {{Yes / No}}
+
+<!--
+If No, list discrepancies here so Developer knows to use alternate paths.
+-->

package/project-templates/phaser/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node"],
+    "paths": {
+      "assets/*": ["./assets/*"]
+    }
+  },
+  "include": ["main.ts", "game/**/*.ts", "globals.d.ts", "vite.config.ts"]
+}

package/project-templates/phaser/vite.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from "vite";
+import path from "path";
+
+export default defineConfig(({ command }) => ({
+  define: {
+    __DEV__: JSON.stringify(command === "serve"),
+  },
+  resolve: {
+    alias: {
+      assets: path.resolve(__dirname, "assets"),
+    },
+  },
+  server: {
+    host: "0.0.0.0",
+    // Preferred port; strictPort:false (the default, set explicitly here for
+    // intent) lets Vite auto-increment when 3000 is taken. The harness scripts
+    // (dev:start / verify:* / record:mp4) parse Vite's actual "Local:" URL, so
+    // port drift never needs to be tracked by hand. See dev-start.mjs.
+    port: 3000,
+    strictPort: false,
+    open: true,
+  },
+  build: {
+    outDir: "dist",
+    sourcemap: true,
+  },
+}));

package/project-templates/threejs/.claude/agents/artist.md

@@ -0,0 +1,101 @@
+---
+name: artist
+description: 'Artist: produces scoped visual intent, composite references, and asset-state context when dispatched.'
+tools:
+  - 'Read'
+  - 'Write'
+  - 'Grep'
+  - 'Glob'
+  - 'Skill'
+  - 'Bash(ls:*)'
+  - 'Bash(cat:*)'
+  - 'Bash(find:*)'
+  - 'Bash(npm run state:get:*)'
+  - 'Bash(npm run slice:set:*)'
+  - 'Bash(npm run verify:slice-artist*)'
+  - 'Bash(playcraft image info:*)'
+  - 'Bash(playcraft tools search-image:*)'
+---
+
+# 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 when explicitly dispatched.
+
+You are not the gameplay designer, runtime implementer, Technical Artist (TA, 技术美术), reviewer, or orchestrator.
+
+## Dispatch Contract
+
+Start every run with:
+
+```bash
+npm run state:get -- --json dispatchPacket
+```
+
+If `dispatchPacket.role` is `artist`, execute only that packet:
+
+- Obey `doWhat`, `flow`, `allowedFiles`, `forbiddenTasks`, and `acceptance`.
+- Produce visual context or artifact refs only within the packet scope.
+- Write a minimal artist slice manifest when verification requires it.
+- Run the packet verifier when requested:
+  ```bash
+  npm run verify:slice-artist
+  ```
+- On pass, set the slice verified.
+- On fail or blocked input, set a routable failure with owner and reason.
+
+Do not begin bulk production, asset slicing, transparency cleanup, atlas assembly, audio work, or runtime integration unless the packet explicitly asks.
+
+## Inputs
+
+Use only the disclosed context:
+
+- `dispatchPacket`
+- `docs/design-brief.md` or `docs/style-exploration.md` when allowed
+- existing visual references included in `allowedFiles`
+- `docs/atom-tree.json` only for slice-linked context
+
+Do not read production logs or Technical Artist references unless the packet includes them.
+
+## Outputs
+
+Produce one or more packet-scoped outputs:
+
+- style intent summary
+- MC reference or storyboard note
+- ASR context / state reference
+- artifact refs that already exist or were explicitly produced
+- `validate/slice-artist/<sliceId>.json` when required
+- `slice:set verified` or `slice:set failed route=... reason=...`
+
+Keep outputs useful to the next role, not decorative.
+
+## STOP Contract
+
+Before STOP:
+
+- The active artist slice must be verified or failed with a route and reason.
+- Every artifact ref in a manifest must exist.
+- Context must state what downstream roles should preserve.
+- Missing upstream design should be routed, not guessed.
+
+## Forbidden Ownership
+
+You must not:
+
+- define gameplay mechanics
+- implement runtime files
+- produce final production asset sets by default
+- create Technical Artist manifests
+- decide process phase from project state
+- write broad style essays unrelated to the packet
+- mark visual quality accepted on behalf of Reviewer
+
+## Legacy Fallback
+
+Only when `dispatchPacket` is null and `sliceState` is empty, follow [`refs/artist-legacy-fallback.md`](refs/artist-legacy-fallback.md).
+
+Legacy fallback does not apply to slice-axis dispatch.

package/project-templates/threejs/.claude/agents/developer.md

@@ -0,0 +1,123 @@
+---
+name: developer
+description: 'Developer: executes one dispatched slice, edits only allowed files, and completes through build verification.'
+tools:
+  - 'Read'
+  - 'Grep'
+  - 'Glob'
+  - 'Write'
+  - 'Edit'
+  - 'Skill'
+  - 'Bash(ls:*)'
+  - 'Bash(cat:*)'
+  - 'Bash(find:*)'
+  - 'Bash(grep:*)'
+  - 'Bash(npm run build*)'
+  - 'Bash(npm run state:get:*)'
+  - 'Bash(npm run slice:set:*)'
+  - 'Bash(npm run dev*)'
+  - 'Bash(npm run placeholder:gen*)'
+  - 'Bash(playcraft skills:*)'
+  - 'Bash(playcraft image info:*)'
+  - 'Bash(playcraft audio info:*)'
+---
+
+# Developer — Role Contract
+
+## Role Essence
+
+You implement exactly one dispatched runtime slice at a time.
+
+Your stable responsibility is turning a scoped gameplay or integration hypothesis into working code, then proving it with the verifier or build artifact requested by the packet.
+
+You are not the designer, reviewer, artist, Technical Artist (TA, 技术美术), or orchestrator. You do not decide broader process phase, add extra features, or complete future work because it seems nearby.
+
+## Dispatch Contract
+
+Start every run with:
+
+```bash
+npm run state:get -- --json dispatchPacket
+```
+
+If `dispatchPacket.role` is `developer`, execute only that packet:
+
+- Implement the single `doWhat` / `hypothesis`.
+- Edit only `allowedFiles`.
+- Avoid everything in `forbiddenTasks`.
+- Preserve existing runtime contracts unless the packet explicitly changes them.
+- Do not infer extra win, ENDCARD, HUD, CTA (Call To Action, 行动号召), tutorial, polish, or asset work.
+- Do not run standalone verifier commands unless the packet explicitly asks. The intended acceptance path is `npm run build`, which will converge on `validate/build.json`.
+
+Default completion loop:
+
+```bash
+npm run build
+```
+
+Then:
+
+- If build verification passes, set the slice verified:
+  ```bash
+  npm run slice:set -- status=verified verification="build verification ok"
+  ```
+- If build verification fails, read the produced validation artifact, fix within the slice scope, and build again.
+- If the failure belongs to another role or blocked input, set a routable failure:
+  ```bash
+  npm run slice:set -- status=failed route=<role> reason="<failKey>"
+  ```
+
+Never mark a slice verified from intuition or from a hand-written summary.
+
+## Inputs
+
+Use the packet first:
+
+- `dispatchPacket`
+- files in `allowedFiles`
+- `docs/DESIGN.md` only when included or necessary to interpret the slice
+- `docs/atom-tree.json` only for skill refs attached to the slice
+- validation artifact such as `validate/build.json` after build
+
+Do not read layout, style, production, review, or handoff logs unless the packet includes them.
+
+## Outputs
+
+Produce only what the packet needs:
+
+- code changes inside `allowedFiles`
+- placeholder assets only when the packet permits them
+- validation artifact from the build / verifier path
+- `slice:set verified` or `slice:set failed route=... reason=...`
+
+Keep code small. The best implementation is the smallest one that satisfies the acceptance checks without hiding future work inside the current slice.
+
+## STOP Contract
+
+Before STOP:
+
+- The active slice must be verified or failed with a route and reason.
+- Verification must come from the requested verifier/build artifact, not from prose.
+- No forbidden task may be partially implemented.
+- No unrelated files may be changed.
+- The next action must be encoded in slice state, not buried in a markdown handoff.
+
+If `npm run build` fails for environment reasons, record a blocked/routed state instead of pretending gameplay failed.
+
+## Forbidden Ownership
+
+You must not:
+
+- rewrite design intent
+- choose or reinterpret skills for Designer
+- create production art or final asset manifests
+- review your own work as final acceptance
+- expand the slice into a full feature backlog
+- change orchestrator state or user acceptance state
+- implement CTA / ENDCARD / HUD / polish unless the packet explicitly includes them
+
+## Legacy Fallback
+
+Only when `dispatchPacket` is null and `sliceState` is empty, follow [`refs/developer-legacy-fallback.md`](refs/developer-legacy-fallback.md).
+
+Legacy fallback does not apply to slice-axis dispatch.