@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/threejs/skills/_shared/scripts/workflow-doctor.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+/**
+ * Read-only workflow doctor for PlayCraft growth-rings harness.
+ *
+ * Checks iteration, inner loop, ringGate, ringDoD, and handoff consistency.
+ */
+
+import { access, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  LOOPS,
+  RING_GOALS,
+  allDoDPassed,
+  isPassed,
+  normalizeIteration,
+  ringDoDKeysForIteration,
+} from './ring-config.mjs';
+import { normalizeDevBlockers, readState, stateExists } from './state-store.mjs';
+import { analyzeBudget } from './context-budget.mjs';
+
+const VALID_WAITING_FOR = new Set(['orchestrator', 'user_gate', 'none']);
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, strict: false };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const value = arg.slice(7);
+      opts.root = value.startsWith('/') ? value : resolve(process.cwd(), value);
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--strict' || arg === '--enforce') {
+      opts.strict = true;
+    }
+  }
+  return opts;
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function cleanValue(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw || raw === 'null') return null;
+  return raw.replace(/^['"]|['"]$/g, '');
+}
+
+/** Build a cleaned handoff string map from structured state. */
+function handoffFromState(state) {
+  const handoff = {};
+  for (const [key, value] of Object.entries(state.handoff || {})) {
+    handoff[key] = cleanValue(value);
+  }
+  return handoff;
+}
+
+function deriveIteration(handoff) {
+  const fromYaml = cleanValue(handoff.iteration);
+  if (fromYaml && !fromYaml.startsWith('{{')) {
+    const n = normalizeIteration(fromYaml);
+    if (n) return n;
+  }
+  return null;
+}
+
+function deriveLoop(handoff) {
+  const fromYaml = cleanValue(handoff.loop);
+  if (fromYaml && !fromYaml.startsWith('{{') && LOOPS.includes(fromYaml)) return fromYaml;
+  return null;
+}
+
+function deriveRingGate(handoff) {
+  const fromYaml = cleanValue(handoff.ringGate);
+  if (fromYaml && !fromYaml.startsWith('{{')) return fromYaml.toLowerCase();
+  return null;
+}
+
+const SUB_AGENT_HANDOFF_ROLES = new Set([
+  'game-designer',
+  'artist',
+  'technical-artist',
+  'developer',
+  'reviewer',
+]);
+
+function routesToUpstream(action) {
+  return /game-designer|artist|technical-artist|developer|reviewer/i.test(String(action || ''));
+}
+
+function nextAction(iteration, loop, ringGate, handoff) {
+  if (handoff.waiting_for === 'user_gate' && handoff.subagent_stop === 'true') {
+    return `Run Ring Gate AskUserQuestion for iteration ${iteration}`;
+  }
+  if (handoff.subagent_stop === 'true' && handoff.waiting_for === 'orchestrator') {
+    return handoff.next_orchestrator_action || 'Execute next_orchestrator_action (missing value)';
+  }
+
+  if (iteration === 1 && loop === 'clarify') {
+    return 'Invoke @game-designer — clarify engine root + core gameplay for ring 1';
+  }
+  if (loop === 'build') {
+    return 'Invoke @developer — implement current ring slice (placeholder art OK)';
+  }
+  if (loop === 'verify') {
+    return `Invoke @reviewer gameplay_conformance, then npm run ring:gate -- --iteration ${iteration}`;
+  }
+  if (isPassed(ringGate) && iteration < 4) {
+    return `Advance to iteration ${iteration + 1}, loop: clarify`;
+  }
+  if (isPassed(ringGate) && iteration === 4) {
+    return 'Project workflow complete (iteration 4 ring gate passed)';
+  }
+  return `Resolve ring ${iteration} (${RING_GOALS[iteration] || 'unknown'}) before invoking another agent`;
+}
+
+export async function diagnose(root, options = {}) {
+  const strict = options.strict === true;
+  const strictStop = options.strict === 'stop' || options.strictStop === true;
+  const errors = [];
+  const warnings = [];
+
+  if (!stateExists(root)) {
+    return {
+      ok: false,
+      root,
+      errors: ['Missing docs/project-state.json or generated markdown view — run npm run ensure:project'],
+      warnings,
+      nextAction: 'Run npm run ensure:project',
+    };
+  }
+
+  const state = readState(root);
+  const handoff = handoffFromState(state);
+  const iteration = deriveIteration(handoff);
+  const loop = deriveLoop(handoff);
+  const ringGate = deriveRingGate(handoff);
+  const ringDoD = state.ringDoD || {};
+  const archivedRings = state.archivedRings || {};
+  const devBlockers = normalizeDevBlockers(state.devPreview?.devBlockers);
+
+  if (!iteration) {
+    errors.push('iteration is missing or invalid (expected 1..4)');
+  }
+
+  if (!loop) {
+    errors.push('loop is missing or invalid (expected clarify|build|verify)');
+  } else if (!LOOPS.includes(loop)) {
+    errors.push(`Unknown loop: ${loop}`);
+  }
+
+  if (!ringGate || ringGate.includes('{{')) {
+    warnings.push('ringGate status is missing or still a placeholder');
+  } else if (!['pending', 'passed', 'failed'].includes(ringGate)) {
+    warnings.push(`ringGate status is non-standard: ${ringGate}`);
+  }
+
+  if (!Object.keys(handoff).length) {
+    errors.push('Agent handoff YAML block is missing');
+  } else {
+    if (!VALID_WAITING_FOR.has(handoff.waiting_for || '')) {
+      errors.push(`Invalid waiting_for: ${handoff.waiting_for}`);
+    }
+    if (!['true', 'false'].includes(handoff.subagent_stop || '')) {
+      errors.push(`Invalid subagent_stop: ${handoff.subagent_stop}`);
+    }
+    if (handoff.waiting_for === 'user_gate' && handoff.subagent_stop !== 'true') {
+      warnings.push('waiting_for=user_gate but subagent_stop is not true');
+    }
+    if (handoff.subagent_stop === 'true' && !handoff.next_orchestrator_action) {
+      errors.push('subagent_stop=true requires next_orchestrator_action');
+    }
+  }
+
+  // Non-regression: archived prior rings must remain passed
+  if (iteration && iteration > 1) {
+    for (let ring = 1; ring < iteration; ring += 1) {
+      const snapshot = archivedRings[ring];
+      const keys = ringDoDKeysForIteration(ring, root);
+      if (!snapshot) {
+        errors.push(`Non-regression: ring ${ring} not archived before entering iteration ${iteration}`);
+      } else if (!allDoDPassed(snapshot, keys)) {
+        errors.push(`Non-regression: ring ${ring} archived DoD is incomplete`);
+      }
+    }
+  }
+
+  // Current ring DoD keys should be present
+  if (iteration) {
+    const activeKeys = ringDoDKeysForIteration(iteration, root);
+    for (const key of activeKeys) {
+      const status = ringDoD[key];
+      if (!status || status.includes('{{')) {
+        warnings.push(`ringDoD.${key} is missing or placeholder`);
+      }
+    }
+    if (loop === 'verify' && !allDoDPassed(ringDoD, activeKeys)) {
+      warnings.push(`loop=verify but ring ${iteration} DoD not all passed — run npm run ring:gate`);
+    }
+  }
+
+  if (strict || strictStop) {
+    if (String(state.devPreview?.devStatus || '').toLowerCase() === 'ready' && devBlockers.length > 0) {
+      errors.push('Strict: devStatus=ready but devBlockers is not empty');
+    }
+    if (handoff.block_reason === 'spec-gap' && !routesToUpstream(handoff.next_orchestrator_action)) {
+      errors.push(
+        'Strict: block_reason=spec-gap requires next_orchestrator_action routed to an upstream owner',
+      );
+    }
+    if (iteration && iteration > 1 && ringGate === 'passed' && loop !== 'clarify') {
+      const prev = archivedRings[iteration - 1];
+      if (!prev) {
+        errors.push(
+          strictStop
+            ? `Illegal transition: ring ${iteration - 1} not archived while ringGate=passed`
+            : `Strict: ring ${iteration - 1} not archived while ringGate=passed`,
+        );
+      }
+    }
+    if (loop === 'verify' && ringGate === 'passed' && iteration && iteration < 4) {
+      errors.push(
+        strictStop
+          ? 'Illegal transition: ringGate passed but still in verify loop — advance iteration and reset loop to clarify'
+          : 'Strict: ringGate passed but still in verify loop — advance iteration/loop first',
+      );
+    }
+    if (strictStop && handoff.subagent_stop === 'true' && handoff.waiting_for === 'user_gate') {
+      const canAsk = cleanValue(state.ringGateRunner?.ringGateCanAskUser)?.toLowerCase() ?? null;
+      const subRole = cleanValue(handoff.subagent);
+      const lastBy = cleanValue(handoff.last_completed_by);
+      if (canAsk !== 'yes') {
+        errors.push(
+          'Illegal handoff: waiting_for=user_gate requires ringGateCanAskUser=yes — run npm run ring:gate first',
+        );
+      }
+      if (
+        (subRole && SUB_AGENT_HANDOFF_ROLES.has(subRole)) ||
+        (lastBy && SUB_AGENT_HANDOFF_ROLES.has(lastBy))
+      ) {
+        errors.push(
+          'Illegal handoff: sub-agents must not set waiting_for=user_gate — use waiting_for=orchestrator and route ring:gate via next_orchestrator_action',
+        );
+      }
+    }
+  }
+
+  if (strict) {
+    const budget = analyzeBudget(root);
+    for (const warning of budget.warnings) {
+      warnings.push(`context:budget ${warning}`);
+    }
+  }
+
+  if (strict) {
+    for (const w of [...warnings]) {
+      errors.push(`Strict: ${w}`);
+    }
+    warnings.length = 0;
+  }
+
+  // Engine adapter vs on-disk scaffold (.playcraft-engine)
+  const atomTreePath = join(root, 'docs', 'atom-tree.json');
+  if (await exists(atomTreePath)) {
+    try {
+      const atomTree = JSON.parse(await readFile(atomTreePath, 'utf8'));
+      const adapter = cleanValue(atomTree?.meta?.engineDecision?.adapter);
+      const markerPath = join(root, '.playcraft-engine');
+      const hasMarker = await exists(markerPath);
+      const onDisk = hasMarker ? (await readFile(markerPath, 'utf8')).trim().toLowerCase() : null;
+
+      if (adapter && hasMarker && onDisk && onDisk !== adapter) {
+        errors.push(
+          `Engine scaffold mismatch: meta.engineDecision.adapter=${adapter} but .playcraft-engine=${onDisk} — run playcraft remix init-template --from-atom-tree`,
+        );
+      } else if (adapter && !hasMarker && iteration === 1 && loop === 'build') {
+        errors.push(
+          `Missing .playcraft-engine — run playcraft remix init-template --from-atom-tree before ring 1 build`,
+        );
+      } else if (adapter && !hasMarker) {
+        warnings.push(
+          `meta.engineDecision.adapter=${adapter} but .playcraft-engine missing — run playcraft remix init-template --from-atom-tree`,
+        );
+      }
+    } catch {
+      warnings.push('Could not parse docs/atom-tree.json for engine adapter check');
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    root,
+    iteration,
+    loop,
+    ringGate,
+    ringDoD,
+    archivedRings,
+    handoff,
+    errors,
+    warnings,
+    nextAction:
+      errors.length > 0
+        ? 'Resolve workflow state before invoking another agent'
+        : nextAction(iteration, loop, ringGate, handoff),
+  };
+}
+
+function printHuman(result) {
+  const mark = result.ok ? 'OK' : 'BLOCKED';
+  console.log(`[workflow:doctor] ${mark}`);
+  if (result.iteration) console.log(`iteration: ${result.iteration}`);
+  if (result.loop) console.log(`loop: ${result.loop}`);
+  if (result.ringGate) console.log(`ringGate: ${result.ringGate}`);
+  console.log(`next: ${result.nextAction}`);
+  if (result.errors.length) {
+    console.log('\nErrors:');
+    for (const item of result.errors) console.log(`- ${item}`);
+  }
+  if (result.warnings.length) {
+    console.log('\nWarnings:');
+    for (const item of result.warnings) console.log(`- ${item}`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await diagnose(resolve(opts.root), { strict: opts.strict });
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(result.ok ? 0 : 2);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main().catch((error) => {
+    console.error(`[workflow:doctor] ${error.message}`);
+    process.exit(1);
+  });
+}

package/project-templates/threejs/skills/playable-animate/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: playable-animate
+description: Polish Phaser/HTML5 playable game animations, timing, sequencing, easing, and interaction feel. Use when Codex is asked to improve entrance animations, tile/card motion, combo/reward feedback, input responsiveness during animations, animation pacing, or to diagnose animation that feels slow, strange, overlapping, blocked, or visually wrong in mobile playable ads and mini-games.
+---
+
+# Playable Animation Polish
+
+Use this skill to make playable ad animation feel intentional, readable, and responsive.
+
+## Workflow
+
+1. Inspect the animation call sites and config before changing timing.
+2. Define the user-visible animation story: what starts first, what overlaps, what must appear last.
+3. Separate visual completion from interaction unlock; particles and aftermath effects should not block the next click.
+4. Prefer named config values over scattered literals.
+5. Verify in the browser with a fresh load and one fast repeat interaction.
+
+## Rules
+
+- Sequence by game logic, not array order.
+- For stacked boards, preserve layer meaning: base first, top/tutorial pieces last unless the user asks otherwise.
+- For multi-direction entry, group by direction within each layer so directions can start together.
+- When groups should finish together, calculate each group's stagger from its item count.
+- Avoid overshoot easing for precise placement. Use non-overshooting easing such as `Cubic.easeOut` unless bounce-back is intended.
+- Cancel delayed tweens/timers when new animation state supersedes old state.
+- **Do not let sprite-sheet parameters mask semantic problems.** If the shape (e.g., starburst vs. xianyun) or edge softness is wrong, switch to procedural/graphics-based FX rather than tuning scale/alpha forever.
+- **Choreograph in phases**, not single tweens: anticipation → attack → sustain → decay. Each phase should be visually distinct in the recording.
+- **Prefer meaning over size.** A combo number that grows without cap will eventually dominate the frame; use color, glow, stroke, and surrounding particles instead of endless scale.
+- **Match effects must respect the object's identity.** When tiles shatter, fragments should still read as tile pieces (faces, characters, edges) rather than generic golden shards.
+
+## References
+
+- Read [references/entrance-sequencing.md](references/entrance-sequencing.md) for layered board/card/tile entrance choreography.
+- Read [references/interaction-timing.md](references/interaction-timing.md) for input locks, aftermath timing, and fast-feel fixes.
+
+---
+
+## Performance 与 Input Lock
+
+> 原 `playable-performance-interaction` 已并入。
+
+1. 复现：load / 入场 / match / 刷新 / combo / endcard 哪一段卡顿或点不动
+2. 分类：**input lock**（动画 guard） vs **CPU/GC**（粒子/碎片 churn） vs **渲染 dirty**
+3. 最小 fix + 一键通关或录屏验证
+
+规则：
+
+- 「点不动」常为 input lock，不一定是慢代码
+- 粒子 aftermath **不应**阻塞下一手 gameplay
+- match 高峰 pool 碎片/emitter；避免无状态变化的重复 render 突变
+
+详见 [references/diagnosis-checklist.md](references/diagnosis-checklist.md)、[references/board-refresh.md](references/board-refresh.md)。

package/project-templates/threejs/skills/playable-animate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Playable Animation Polish'
+  short_description: 'Polish playable animation feel.'
+  default_prompt: "Polish this playable game's animations, timing, sequencing, easing, and input feel."

package/project-templates/threejs/skills/playable-animate/references/board-refresh.md

@@ -0,0 +1,30 @@
+# Board Refresh Optimization
+
+Use this reference for match games, tile boards, and layered occlusion.
+
+## Static Geometry
+
+- Precompute relationships that do not change during gameplay.
+- For layered boards, precompute which tile indices can block each tile.
+- Precompute left/right neighbors for side-block rules.
+- At refresh time, inspect only matched/active state.
+
+## State Updates
+
+- Combine related state updates into one setter when possible.
+- Skip render mutations if state did not change.
+- Avoid alpha-only blocked states if it creates visual noise.
+- Keep matched tiles hidden and excluded from hit tests.
+
+## Effects And GC
+
+- Pool shards and flashes created on every match.
+- Limit overlapping particle emitters.
+- Destroy or recycle pooled objects on scene shutdown.
+- Avoid creating fallback graphics during normal runtime when atlas art exists.
+
+## Input Locks
+
+- Set `isProcessing` only for the minimum period needed to prevent invalid double actions.
+- Unlock after game state and board refresh are ready.
+- Let shatter, glow, dust, toast, and reward effects finish independently.

package/project-templates/threejs/skills/playable-animate/references/diagnosis-checklist.md

@@ -0,0 +1,25 @@
+# Diagnosis Checklist
+
+Use this checklist for playable lag and interaction complaints.
+
+## Classify The Symptom
+
+- Load stutter: asset decode, atlas size, boot scene.
+- Entrance stutter: too many tweens, long stagger, expensive graphics.
+- Match stutter: object creation, particles, shatter effects, board refresh.
+- "Click invalid": input guard, scene phase, `isProcessing`, tutorial mode, overlay hit area.
+- End card stutter: large overlays, particles, scale tweens.
+
+## Inspect
+
+- Search for `setTimeout`, `setInterval`, `delayedCall`, `tweens.add`, `add.graphics`, `add.particles`, and `destroy`.
+- Check whether callbacks survive scene transitions.
+- Check whether a function allocates arrays or objects every click.
+- Check whether a state setter mutates rendering even when the value did not change.
+
+## Verify
+
+- Use browser console logs and runtime errors.
+- Run syntax checks for changed JS files.
+- Run project verification scripts when present.
+- Use autoplay or scripted interactions to stress repeated matches.

package/project-templates/threejs/skills/playable-animate/references/entrance-sequencing.md

@@ -0,0 +1,33 @@
+# Entrance Sequencing
+
+Use these patterns for board, card, tile, and stacked-object entrance animations.
+
+## Layered Boards
+
+- Start from the user's mental model of construction.
+- For stacked boards, build lower layers first and save top/tutorial pieces for last.
+- If layers overlap in time, make later layers start after the previous layer is visibly underway.
+- Keep a single total timing budget so the intro does not feel slow.
+
+## Directional Entry
+
+- Four-corner entry usually feels better than left/right entry for centered boards.
+- Assign each object to the corner matching its final quadrant.
+- Within a layer, split entries into corner groups.
+- Start all corner groups in a layer at the same time.
+- Sort each corner group from farthest-from-center to nearest-to-center for a gathering effect.
+
+## Same Start, Same End
+
+When several groups must finish together:
+
+1. Choose `entryTotal`, the group's timing window.
+2. Set `maxDelay = entryTotal - singleTweenDuration`.
+3. For each group, calculate `stagger = maxDelay / (group.length - 1)`.
+4. For groups with one item, place that item at `maxDelay` if it should appear at the end of the window.
+
+## Easing
+
+- Avoid `Back.easeOut` when overshooting the target looks wrong.
+- Use `Cubic.easeOut` or `Sine.easeOut` for clean landings.
+- Reserve elastic/back easing for celebratory UI, not precise board assembly.

package/project-templates/threejs/skills/playable-animate/references/interaction-timing.md

@@ -0,0 +1,23 @@
+# Interaction Timing
+
+Use this checklist when animation makes a playable feel unresponsive.
+
+## Diagnose
+
+- Check whether input is blocked by an explicit flag such as `isProcessing`.
+- Check delayed callbacks that reset interaction state.
+- Distinguish visual aftermath from gameplay state readiness.
+- Inspect fast repeat interactions, not only one happy-path click.
+
+## Fix
+
+- Mark matched/removed objects and refresh board state as soon as the game state is visually clear enough.
+- Unlock input shortly after actionable state updates, even if particles continue.
+- Keep reward, dust, shatter, and glow effects asynchronous.
+- Avoid using long `aftermathMs` values as interaction lock durations.
+
+## Validate
+
+- Click immediately after a match animation hides the tiles.
+- Verify the next valid interaction is accepted.
+- Check console logs for late callbacks after scene transitions.