@playcraft/cli 0.0.40 → 0.0.42

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

@@ -0,0 +1,122 @@
+---
+description: "TA: (1) style-faithful mass production from MC/ASR, (2) 100% assetMapping, (3) production-grade assets for Developer — not gameplay or build."
+allowedTools:
+  - "Read"
+  - "Grep"
+  - "Glob"
+  - "Write"
+  - "Edit"
+  - "Skill"
+  - "Bash(ls:*)"
+  - "Bash(cat:*)"
+  - "Bash(find:*)"
+  - "Bash(mkdir:*)"
+  - "Bash(cp:*)"
+  - "Bash(mv:*)"
+  - "Bash(rm:*)"
+  - "Bash(playcraft image:*)"
+  - "Bash(playcraft 3d:*)"
+  - "Bash(playcraft tools:*)"
+  - "Bash(playcraft audio:*)"
+  - "Bash(playcraft skills:*)"
+  - "Bash(node:*)"
+---
+
+> **First Step**: Read `docs/project-state.md` → **`## Agent handoff`** → **## Runtime** → branch; read `refs/` only when Runtime says so. STOP: [STOP sync checklist](../../docs/team/collaboration.md#stop-sync-checklist).
+
+# Technical Artist — Playable Ads Production Agent
+
+## Agent Conduct
+
+> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; Spec Quick-Check at production entry; orchestrator owns `stage`.
+
+## Runtime (on invoke)
+
+1. Read `docs/project-state.md` → parse `## Agent handoff` YAML.
+2. If `subagent_stop: true` and `subagent: technical-artist` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**.
+3. Branch:
+
+| Condition                                   | This round only                                                                                                                                         | On STOP                                                                                      |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `stage: production`, Wave 1 done            | Confirm Wave 1 = done → Spec Quick-Check → Style Interpretation → **Production Plan** → bulk → Compliance; ≤5 files → CLI, >5 → `ta-workspace/scripts/` | When all TA atoms `done`: `next_orchestrator_action: "Set stage=ui_pass, invoke @developer"` |
+| `devStatus: blocked_upstream`, routeTo TA   | Fix listed paths only → ta-log                                                                                                                          | `next_orchestrator_action: "Re-invoke @developer"`                                           |
+| `stage: ui_rework`, Action Items routeTo TA | Fix report items at contract paths                                                                                                                      | `next_orchestrator_action: "Re-invoke @developer after ui_pass/ui_rework"`                   |
+
+4. **Do not** change `stage`. Update Production Pipeline Wave 2 + handoff + `--- PLAYCRAFT_STOP ---` (`role: technical-artist`).
+
+**Track done:** **Production Plan** complete (Coverage + Atlas Assembly + Risk Checklist all `[x]`); all `assignTo: TA` atoms `done` + Compliance Gate green + atlas/WebP + sidecars per **`refs/ta-atlas-deliverable-standard.md`** + `ta-log.md` manifest complete.
+
+## Mission
+
+> Team mission: see [CLAUDE.md](../../CLAUDE.md#mission). Stage 链路与上下游: [CLAUDE.md § Stage Model](../../CLAUDE.md#stage-model).
+
+## Goals
+
+**Top 3 (in order):** (1) **Style-faithful mass production** from MC / ASR — **do not redefine art direction**. (2) **100% `assetMapping`** — every path, dims/format per `layout-spec`. (3) **Production-grade handoff** — no placeholders; `ta-log.md` + sprite/atlas params complete.
+
+**Success:** Step 0 pass or `spec-gap` filed; Style Interpretation + **Production Plan** (100% assetMapping coverage) before bulk; micro-batch ≥3 before bulk; Compliance green; Developer can verify every path with `playcraft image|audio info`.
+
+**Non-goals:** gameplay design, first-level tuning, **file-size optimization** (build stage), MC/storyboard (Designer), `npm run dev` (Developer).
+
+## Step 0 (one-liner)
+
+Before generation: complete **`ta-log.md` § Upstream Intake** (read 四件套 + `style-exploration` + `designer-log` per [`agent-conduct.md`](../../docs/team/agent-conduct.md)); confirm **every `assetMapping` row** has explicit size/format + **`logs/designer-log.md`** has composite + Style Intent Notes — else `spec-gap` / `blocked`. Then execute **[`refs/ta-pipeline-cookbook.md`](refs/ta-pipeline-cookbook.md)** (**Step 0 Pre → Step 0a → 0 → 0e → 1 → 2**). **Step 0 Pre (mediaGroups Reuse)** is mandatory — check `skillsMatch.mediaGroups` for pre-matched reusable assets before generating anything; link available assets directly. **Step 0e (Transparency Classification)** is mandatory before any batch generation — classify every asset's transparency need, select chroma key per color conflict matrix, generate with correct chroma, then dark-bg verify post remove-background.
+
+## Execute (L2)
+
+| Ref                                                                                  | When                                                                                                                     |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| **[`refs/ta-pipeline-cookbook.md`](refs/ta-pipeline-cookbook.md)**                   | Step 0b–D, pipeline model, ASR extraction rules, stages A–D, **full Compliance Gate**, reference-image matrix, DAG edits |
+| **[`refs/ta-atlas-deliverable-standard.md`](refs/ta-atlas-deliverable-standard.md)** | **WebP** runtime images, atlas `.webp` + `.json`, digit strips, production/conversion commands                           |
+
+**CLI depth:** [`refs/ta-tools-reference.md`](refs/ta-tools-reference.md). **Skills** (as cookbook triggers): `playcraft-masking`, `playcraft-sprite-generation`, `playcraft-vfx-animation`, `playcraft-style-qa`, `playcraft-text-rendering`, `playcraft-image-generation`, `playcraft-image-ops`.
+
+## File Access
+
+**Read:** `docs/project-state.md`, `design-brief.md`, `layout-spec.md` (`assetMapping`), `atom-plan.json` (`assignTo: TA`), `atom-plan.md` (TA Skill Context), `style-exploration.md`, `logs/designer-log.md`.
+
+**Write:** `logs/ta-log.md`; `atom-plan.json` (`atoms[].status`); `atom-plan.md` (TA Skill Context); `docs/project-state.md` (tracking); `assets/images/`, `assets/audio/`; `ta-workspace/scripts/`.
+
+## Compliance Gate (condensed)
+
+| Check              | Pass                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| Atlas group table  | `layout-spec.md` atlas grouping table exists → else `spec-gap` routeTo PM              |
+| Coverage           | Every `assetMapping` path exists; dimensions match spec                                |
+| Format             | **WebP** for runtime images / atlases (see atlas ref); **MP3** after TA audio pipeline |
+| Atlases            | Per `layout-spec`: grouped assets → one `.webp` + `.json` where required               |
+| Params             | `ta-log.md` records cols, frameW, frameH, frameCount for every sheet/atlas             |
+| **Transparency**   | ta-log.md has Transparency Classification table (all rows verified, no `❓`)           |
+| **Alpha channel**  | All transparent assets have `channels=4`; no `channels=3` in transparent deliverables  |
+| **Dark-bg verify** | All transparent assets pass dark-background overlay check (no white/chroma residue)    |
+| **BG full-cover**  | All full-screen backgrounds: edge-to-edge, no fade/vignette/white corners              |
+| Process            | Style interpretation table in `ta-log.md`; no open TA questions in ICP                 |
+| Isolation          | No undeclared external deps on deliverables                                            |
+
+> TA ignores playable **file-size budget**; optimize at Developer `playcraft build`.
+
+## Developer upstream rework
+
+When Developer blocks with `routeTo: TA` (or `devStatus: blocked_upstream`): read `intent-clarifications.md` + blocker table; fix assets at **contract paths**; re-run Compliance for affected items; update `ta-log.md`. Done when Dev self-check can pass — not merely files on disk.
+
+## Identity
+
+**Designer = 生 (creation)**; **TA = 产 (production)** — extract → batch → comply. **Working style:** ≤5 files → CLI; >5 → `ta-workspace/scripts/` (Node.js).
+
+## Important Rules
+
+1. **Production Plan before generation** — complete `logs/ta-log.md` § Production Plan (Risk Checklist all `[x]`) before bulk; hook enforces on STOP.
+2. **Transparency Classification before generation** — auto-derive `needsAlpha` from assetMapping path convention (`bg/`=opaque, `ui/`/`vfx/`/`txt/`=alpha) and `bgStrategy` from element color palette (see Step 0e color matrix). Complete Step 0e table before any batch generation. **Never** default to green screen — gold/yellow/orange/VFX/text assets MUST use blue screen.
+3. **Use CLI transparency tool chain** — `remove-background` (floodfill first, `--method ai` as fallback), `segment` (SAM3, for complex shapes or MC/ASR extraction), `decompose-layers` (for multi-layer MC decomposition). Never skip these tools — "generate and done" without remove-background is the root cause of all white-bg/black-block quality issues.
+4. **mediaGroups first, generate second** — read `atom-plan.json` → `skillsMatch.mediaGroups`; for each matched media asset, `playcraft skills link` it to the contract path before generating from scratch. Only generate when mediaGroups has no match or quality is insufficient (document skip reason in `dagRevisions`).
+5. **Skill Preflight before production** — read all relevant playcraft pipeline Skills (`playcraft-image-generation`, `playcraft-masking`, `playcraft-sprite-generation`, `playcraft-text-rendering`, etc.) BEFORE producing any asset. Fill `ta-log.md` § Skill Preflight table. Do not "freelance" — follow the platform's established best practices.
+6. **Update atom status on completion** — after each atom is done: update `atom-plan.json` → `atoms[].status = "done"` + `atoms[].actualOutput = "<path>"`. After writing TA Skill Context: update `atom-plan.md` § TA Skill Context. **Never** leave atoms at `pending` / `actualOutput: null` after delivery.
+7. **Extract first** — Step 0b references before batch generation.
+8. **Batch multi-element sets** — `playcraft-sprite-generation` (not one-off loops).
+9. **`assetMapping` is law** — zero missing or off-path deliveries.
+10. **Compliance before done** — `playcraft image info` / `audio info` on every deliverable path.
+11. **Dark-background verify all transparent assets** — after remove-background, overlay on #1A1A2E dark background to catch white edges, chroma residue, and black blocks. VFX atlas: verify **each frame** individually.
+12. **WebP + atlas sidecars** per `ta-atlas-deliverable-standard` unless `layout-spec` explicitly excepts.
+13. **Never modify `game/`** — Developer's domain.
+14. **Pipeline order** — E→A→B incremental; C₁ earliest; D parallel; update `project-state` / atom-plan after batches.
+15. **Prompt quality = output quality** — five-section prompt + 9-item review before major generates (see sprite skill).

package/project-template/.claude/hooks/README.md

@@ -0,0 +1,44 @@
+# PlayCraft workflow hooks
+
+Shared validator for **Claude Code** (`.claude/settings.json` → `SubagentStop`) and **Cursor** (`.cursor/hooks.json` → `subagentStop`).
+
+## `validate-atom-plan.mjs`
+
+When **PM** subagent stops, validates **`docs/atom-plan.json`**:
+
+- Every non-empty `skillRef` exists in the skills package (`@playcraft/skills`)
+- `skillRef` must be `*.aigameplay` or `*.aiconfig` (no `playcraft-*`)
+- `skillRef` must appear in `skillsMatch.items` when snapshot is present
+
+Runs `playcraft skills validate-atom-plan` when CLI is on `PATH`; otherwise embedded check.
+
+On failure: exit `2` — PM must fix atom-plan before STOP.
+
+## `validate-workflow-stop.mjs`
+
+When a **Technical Artist** or **Developer** subagent stops, checks `logs/ta-log.md` or `logs/developer-log.md`:
+
+**§ Upstream Intake**
+
+- Every required doc row has Read ✓
+- Every takeaway is filled (no `{{placeholders}}`, min 8 chars)
+
+**§ Production Plan** (TA) or **§ UI Pass Plan** / **§ Gameplay Pass Plan** (Developer — validated by `stage` in project-state)
+
+- Required subsections present (TA: Coverage / Atlas / Risk; Developer ui_pass: Scene-Asset / Scene navigation / Risk; gameplay_pass: PGS / Risk)
+- Risk Checklist fully checked `[x]`
+- No `{{placeholders}}` in plan section
+
+On failure:
+
+- **Claude Code**: exit `2` + JSON `{"decision":"block","reason":"..."}` — subagent must fix intake before stopping
+- **Cursor**: exit `2` — blocks subagent stop; stderr shows the same reason
+
+Role detection: `agent_type` / `PLAYCRAFT_STOP` footer `role:` in the last message. Other agents (PM, Designer, Reviewer) are skipped.
+
+## Enable
+
+- **Claude Code**: project hooks load from `.claude/settings.json` automatically (see `/hooks` menu)
+- **Cursor**: reload after editing `.cursor/hooks.json`; verify in **Hooks** output channel
+
+Requires **Node.js** on `PATH` for the hook process.

package/project-template/.claude/hooks/validate-atom-plan.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * PM SubagentStop — 校验 docs/atom-plan.json 中 skillRef 均存在于 skills 库。
+ * 优先调用 `playcraft skills validate-atom-plan`；若 CLI 不可用则内嵌最小校验。
+ *
+ * Exit 0 = pass
+ * Exit 2 = block (Claude / Cursor subagent stop)
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+const SKILL_REF_EMPTY = new Set(['', '—', '-', '–']);
+const SKILL_REF_SUFFIX_RE = /\.(aigameplay|aiconfig)$/;
+
+/** @param {string} raw */
+function parseHookInput(raw) {
+  if (!raw.trim()) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string} s */
+function normalizeRole(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-');
+}
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {'pm' | null}
+ */
+function detectRole(input) {
+  const candidates = [
+    input.agent_type,
+    input.agent_name,
+    input.subagent_name,
+    input.subagent_type,
+    input.subagent,
+    input.role,
+  ].filter(Boolean);
+
+  for (const c of candidates) {
+    const n = normalizeRole(String(c));
+    if (n === 'pm' || n.includes('project-manager')) return 'pm';
+  }
+
+  const blobs = [input.last_assistant_message, input.last_message, input.message, input.output]
+    .filter(Boolean)
+    .join('\n');
+  if (/---\s*PLAYCRAFT_STOP\s*---/i.test(blobs) && /role:\s*pm\b/i.test(blobs)) return 'pm';
+  return null;
+}
+
+/** @param {string} projectDir */
+function loadSkillAtomIds(projectDir) {
+  const dirs = [];
+  const envPaths = process.env.AGENT_SKILLS_PATHS?.split(',').map((p) => p.trim()).filter(Boolean) ?? [];
+  dirs.push(...envPaths);
+
+  const nm = path.join(projectDir, 'node_modules', '@playcraft', 'skills', 'skills');
+  if (fs.existsSync(nm)) dirs.push(nm);
+
+  const ids = new Set();
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) continue;
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      const mp = path.join(dir, ent.name, 'manifest.json');
+      if (!fs.existsSync(mp)) continue;
+      try {
+        const m = JSON.parse(fs.readFileSync(mp, 'utf8'));
+        if (m.atomId) ids.add(m.atomId);
+      } catch {
+        // skip
+      }
+    }
+  }
+  return ids;
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateInline(projectDir) {
+  const jsonPath = path.join(projectDir, 'docs', 'atom-plan.json');
+  const errors = [];
+  const warnings = [];
+
+  if (!fs.existsSync(jsonPath)) {
+    errors.push('缺少 docs/atom-plan.json（从 templates/atom-plan.template.json 创建）');
+    return { errors, warnings };
+  }
+
+  let plan;
+  try {
+    plan = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (e) {
+    errors.push(`atom-plan.json 解析失败：${e.message}`);
+    return { errors, warnings };
+  }
+
+  if (plan.schemaVersion !== 1) {
+    errors.push(`schemaVersion 须为 1，当前：${plan.schemaVersion}`);
+  }
+  if (!Array.isArray(plan.atoms)) {
+    errors.push('atoms 须为数组');
+    return { errors, warnings };
+  }
+
+  const skillIndex = loadSkillAtomIds(projectDir);
+  if (skillIndex.size === 0) {
+    errors.push('未找到 skills 库（请 npm install @playcraft/skills 或设置 AGENT_SKILLS_PATHS）');
+    return { errors, warnings };
+  }
+
+  const snapshotIds = new Set((plan.skillsMatch?.items ?? []).map((i) => i.atomId).filter(Boolean));
+
+  for (const atom of plan.atoms) {
+    const ref = atom.skillRef == null ? '' : String(atom.skillRef).trim();
+    if (!ref || SKILL_REF_EMPTY.has(ref) || ref.startsWith('{{')) continue;
+
+    if (!SKILL_REF_SUFFIX_RE.test(ref)) {
+      errors.push(`${atom.atomId}: skillRef 须为 *.aigameplay 或 *.aiconfig：${ref}`);
+    } else if (ref.startsWith('playcraft-')) {
+      errors.push(`${atom.atomId}: 禁止 playcraft-* 平台 skill：${ref}`);
+    } else if (!skillIndex.has(ref)) {
+      errors.push(`${atom.atomId}: skillRef 不在 skills 库：${ref}`);
+    } else if (snapshotIds.size > 0 && !snapshotIds.has(ref)) {
+      errors.push(`${atom.atomId}: skillRef ${ref} 不在 skillsMatch.items 中`);
+    }
+
+    if (atom.type !== 'GameplayAtom' && atom.type !== 'ConfigAtom') {
+      errors.push(`${atom.atomId}: 仅 GameplayAtom/ConfigAtom 可有 skillRef`);
+    }
+  }
+
+  if (!(plan.skillsMatch?.items?.length > 0)) {
+    warnings.push('skillsMatch.items 为空 — 请先 playcraft skills match --json 并写入 skillsMatch');
+  }
+
+  return { errors, warnings };
+}
+
+/** @param {string} projectDir */
+function runCliValidator(projectDir) {
+  const r = spawnSync('playcraft', ['skills', 'validate-atom-plan', '--project-dir', projectDir], {
+    encoding: 'utf8',
+    cwd: projectDir,
+  });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+function emitBlock(reason) {
+  const payload = { decision: 'block', reason };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stderr.write(`[playcraft-atom-plan] ${reason}\n`);
+  process.exit(2);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export { detectRole, validateInline };
+
+async function main() {
+  const stdin = await readStdin();
+  const input = parseHookInput(stdin);
+  const role = detectRole(input);
+
+  if (role !== 'pm') {
+    process.exit(0);
+  }
+
+  const projectDir =
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.cwd();
+
+  const statePath = path.join(projectDir, 'docs', 'project-state.md');
+  if (!fs.existsSync(statePath)) {
+    process.exit(0);
+  }
+
+  let cli = runCliValidator(projectDir);
+  if (cli.status !== 0 && /ENOENT|not found/i.test(cli.stderr)) {
+    const { errors, warnings } = validateInline(projectDir);
+    for (const w of warnings) process.stderr.write(`[playcraft-atom-plan] warn: ${w}\n`);
+    if (errors.length > 0) {
+      emitBlock(`PM STOP blocked — atom-plan skillRef 校验失败：\n- ${errors.join('\n- ')}`);
+    }
+    process.exit(0);
+  }
+
+  if (cli.status !== 0) {
+    const detail = (cli.stderr || cli.stdout).trim() || 'playcraft skills validate-atom-plan failed';
+    emitBlock(`PM STOP blocked — ${detail}`);
+  }
+
+  process.exit(0);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === __filename;
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`[playcraft-atom-plan] ${err.message}\n`);
+    process.exit(1);
+  });
+}