@playcraft/cli 0.0.39 → 0.0.41

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

@@ -0,0 +1,111 @@
+---
+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 Production Pipeline Wave 1 = done → Spec Quick-Check → Style Interpretation → bulk → Compliance; ≤5 files → CLI, >5 → `ta-workspace/scripts/` | When all TA atoms `done`: `next_orchestrator_action: "Set stage=integration, invoke @developer"` |
+| `devStatus: blocked_upstream`, routeTo TA | Fix listed paths only → ta-log                                                                                                                        | `next_orchestrator_action: "Re-invoke @developer"`                                               |
+| `stage: rework`, Action Items routeTo TA  | Fix report items at contract paths                                                                                                                    | `next_orchestrator_action: "Re-invoke @developer after integration"`                             |
+
+4. **Do not** change `stage`. Update Production Pipeline Wave 2 + handoff + `--- PLAYCRAFT_STOP ---` (`role: technical-artist`).
+
+**Track done:** 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 + 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 0a → 0 → 1 → 2**).
+
+## 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             |
+| 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. **Extract first** — Step 0b references before batch generation.
+2. **Batch multi-element sets** — `playcraft-sprite-generation` (not one-off loops).
+3. **`assetMapping` is law** — zero missing or off-path deliveries.
+4. **Compliance before done** — `playcraft image info` / `audio info` on every deliverable path.
+5. **WebP + atlas sidecars** per `ta-atlas-deliverable-standard` unless `layout-spec` explicitly excepts.
+6. **Never modify `game/`** — Developer's domain.
+7. **Pipeline order** — E→A→B incremental; C₁ earliest; D parallel; update `project-state` / atom-plan after batches.
+8. **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,36 @@
+# 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)
+
+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);
+  });
+}

package/project-template/.claude/hooks/validate-workflow-stop.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft workflow STOP validator — shared by Claude Code (SubagentStop) and Cursor (subagentStop).
+ * Ensures TA / Developer filled logs/<role>-log.md § Upstream Intake before subagent may stop.
+ *
+ * Exit 0 = pass
+ * Exit 2 = block (Claude: decision block; Cursor: block stop)
+ * stdout (Claude): {"decision":"block","reason":"..."} on failure
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+const INTAKE_HEADING = '## Upstream Intake';
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+const MIN_TAKEAWAY_LEN = 8;
+
+const TA_REQUIRED_DOCS = [
+  'docs/project-state.md',
+  'docs/design-brief.md',
+  'docs/layout-spec.md',
+  'docs/atom-plan.json',
+  'docs/atom-plan.md',
+  'docs/style-exploration.md',
+  'logs/designer-log.md',
+];
+
+const DEV_REQUIRED_DOCS = [...TA_REQUIRED_DOCS, 'logs/ta-log.md'];
+
+const ROLE_LOG = {
+  'technical-artist': { log: 'logs/ta-log.md', docs: TA_REQUIRED_DOCS, label: 'Technical Artist' },
+  developer: { log: 'logs/developer-log.md', docs: DEV_REQUIRED_DOCS, label: 'Developer' },
+};
+
+/** @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 {'technical-artist' | 'developer' | 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.includes('technical-artist') || n === 'ta') return 'technical-artist';
+    if (n === 'developer' || n === 'dev') return 'developer';
+  }
+
+  const blobs = [
+    input.last_assistant_message,
+    input.last_message,
+    input.message,
+    input.output,
+  ]
+    .filter((v) => typeof v === 'string')
+    .join('\n');
+
+  const stopMatch = blobs.match(/---\s*PLAYCRAFT_STOP\s*---[\s\S]*?role:\s*([^\s\n]+)/i);
+  if (stopMatch) {
+    const r = normalizeRole(stopMatch[1]);
+    if (r in ROLE_LOG) return /** @type {keyof ROLE_LOG} */ (r);
+  }
+
+  return null;
+}
+
+/** @param {string} cell */
+function isReadChecked(cell) {
+  const t = cell.trim();
+  if (/[✓✔☑]/.test(t)) return true;
+  if (/\[x\]/i.test(t)) return true;
+  if (/^(yes|done|true|read)$/i.test(t)) return true;
+  return false;
+}
+
+/**
+ * @param {string} content
+ * @returns {{ rows: { doc: string, read: string, takeaway: string }[], errors: string[] }}
+ */
+function parseUpstreamIntake(content) {
+  const errors = [];
+  const start = content.indexOf(INTAKE_HEADING);
+  if (start === -1) {
+    return { rows: [], errors: [`Missing "${INTAKE_HEADING}" section`] };
+  }
+
+  const after = content.slice(start + INTAKE_HEADING.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  const rows = [];
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|\s*---/.test(trimmed)) continue;
+    if (/^\|\s*Doc\s*\|/i.test(trimmed)) continue;
+
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+
+    if (parts.length < 3) continue;
+
+    const doc = parts[0].replace(/^`/, '').replace(/`$/, '').trim();
+    if (!doc.startsWith('docs/') && !doc.startsWith('logs/')) continue;
+
+    rows.push({ doc, read: parts[1], takeaway: parts[2] });
+  }
+
+  if (rows.length === 0) {
+    errors.push('Upstream Intake table has no data rows');
+  }
+
+  return { rows, errors };
+}
+
+/**
+ * @param {string} content
+ * @param {string[]} requiredDocs
+ */
+function validateIntakeContent(content, requiredDocs) {
+  const { rows, errors } = parseUpstreamIntake(content);
+  const byDoc = new Map(rows.map((r) => [r.doc, r]));
+
+  for (const doc of requiredDocs) {
+    const row = byDoc.get(doc);
+    if (!row) {
+      errors.push(`Missing row for ${doc}`);
+      continue;
+    }
+    if (!isReadChecked(row.read)) {
+      errors.push(`${doc}: mark Read column (✓) after reading`);
+    }
+    const takeaway = row.takeaway.trim();
+    if (!takeaway || PLACEHOLDER_RE.test(takeaway) || takeaway.length < MIN_TAKEAWAY_LEN) {
+      errors.push(`${doc}: add a concrete one-line takeaway (≥${MIN_TAKEAWAY_LEN} chars, no {{placeholders}})`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * @param {string} projectDir
+ * @param {'technical-artist' | 'developer'} role
+ */
+function validateRole(projectDir, role) {
+  const cfg = ROLE_LOG[role];
+  const logPath = path.join(projectDir, cfg.log);
+
+  if (!fs.existsSync(logPath)) {
+    return [
+      `${cfg.label}: create ${cfg.log} from templates/${path.basename(cfg.log).replace('.md', '.template.md')} and complete § Upstream Intake before STOP.`,
+    ];
+  }
+
+  const content = fs.readFileSync(logPath, 'utf8');
+  return validateIntakeContent(content, cfg.docs);
+}
+
+/** @param {string} projectDir */
+function resolveProjectDir(projectDir) {
+  const statePath = path.join(projectDir, 'docs/project-state.md');
+  if (!fs.existsSync(statePath)) {
+    return { skip: true, reason: 'no docs/project-state.md' };
+  }
+  return { skip: false };
+}
+
+function emitBlock(reason) {
+  const payload = { decision: 'block', reason };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stderr.write(`[playcraft-workflow-stop] ${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,
+  parseUpstreamIntake,
+  validateIntakeContent,
+  validateRole,
+  TA_REQUIRED_DOCS,
+  DEV_REQUIRED_DOCS,
+};
+
+async function main() {
+  const stdin = await readStdin();
+  const input = parseHookInput(stdin);
+  const role = detectRole(input);
+
+  if (!role) {
+    process.exit(0);
+  }
+
+  const projectDir =
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.cwd();
+
+  const { skip } = resolveProjectDir(projectDir);
+  if (skip) {
+    process.exit(0);
+  }
+
+  const errors = validateRole(projectDir, role);
+  if (errors.length > 0) {
+    const reason = `${ROLE_LOG[role].label} STOP blocked — fix logs/${role === 'technical-artist' ? 'ta' : 'developer'}-log.md § Upstream Intake:\n- ${errors.join('\n- ')}`;
+    emitBlock(reason);
+  }
+
+  process.exit(0);
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === __filename;
+
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`[playcraft-workflow-stop] validator error: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/project-template/.claude/settings.json

@@ -0,0 +1,32 @@
+{
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "pm",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-atom-plan.mjs"
+            ],
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "technical-artist|developer",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate-workflow-stop.mjs"
+            ],
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/project-template/.claude/settings.local.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "PlayCraft project template — local permission hints. Sub-agents PM/Designer must not use AskUserQuestion; gates are orchestrator-only. See docs/team/agent-conduct.md."
+}