@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/.claude/hooks/snapshot-milestone.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft milestone snapshot hook.
+ *
+ * Triggered on SubagentStop. Reads project-state.md
+ * → Agent handoff YAML to detect key milestones, then runs snapshot.mjs to archive
+ * current project state.
+ *
+ * Milestones (only snapshot once each):
+ *   - ring-1-archived   iteration >= 2 or archivedRings contains ring 1
+ *   - ring-2-archived   iteration >= 3 or archivedRings contains ring 2
+ *   - ring-3-archived   iteration >= 4 or archivedRings contains ring 3
+ *   - dev-ready         devStatus: ready (Dev Preview table)
+ *   - ring-4-done       ringGateVerdict pass on iteration 4
+ *
+ * Exit 0 always — snapshot failures are non-blocking.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function resolveProjectDir() {
+  const raw =
+    process.env.CODEBUDDY_PROJECT_DIR ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.CURSOR_PROJECT_DIR ||
+    process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw)) {
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  }
+  return path.resolve(raw);
+}
+
+function readProjectState(projectDir) {
+  const statePath = path.join(projectDir, 'docs', 'project-state.md');
+  if (!fs.existsSync(statePath)) return null;
+  return fs.readFileSync(statePath, 'utf8');
+}
+
+/**
+ * Parse the `## Agent handoff` YAML block from project-state.md.
+ */
+function parseHandoff(content) {
+  const fenceStart = content.indexOf('```yaml');
+  if (fenceStart === -1) return null;
+
+  const afterFence = content.indexOf('\n', fenceStart);
+  if (afterFence === -1) return null;
+
+  const fenceEnd = content.indexOf('```', afterFence);
+  if (fenceEnd === -1) return null;
+
+  const yamlBlock = content.slice(afterFence, fenceEnd);
+
+  const result = {};
+  for (const line of yamlBlock.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = trimmed.slice(0, colonIdx).trim();
+    let value = trimmed.slice(colonIdx + 1).trim();
+
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    if (value === 'true') result[key] = true;
+    else if (value === 'false') result[key] = false;
+    else if (value === 'null' || value === '') result[key] = null;
+    else result[key] = value;
+  }
+  return result;
+}
+
+/** @param {string} content */
+function parseIteration(content) {
+  const handoff = parseHandoff(content);
+  if (handoff?.iteration) {
+    const n = Number(handoff.iteration);
+    if (Number.isFinite(n) && n >= 1) return n;
+  }
+  const m = content.match(/^\s*iteration:\s*(\d+)\s*$/im);
+  return m ? Number(m[1]) : 1;
+}
+
+/** @param {string} content @param {number} ring */
+function hasArchivedRing(content, ring) {
+  const lineMatch = content.match(/^\s*archivedRings:\s*(.+)\s*$/im);
+  if (lineMatch && new RegExp(`\\b${ring}\\s*:`).test(lineMatch[1])) {
+    return true;
+  }
+  const tableRe = new RegExp(`^\\|\\s*${ring}\\s*\\|`, 'm');
+  return tableRe.test(content);
+}
+
+/** @param {string} content */
+function parseDevStatus(content) {
+  const m = content.match(/^\|\s*devStatus\s*\|\s*(\w+)\s*\|/im);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/** @param {string} content */
+function parseRingGateVerdict(content) {
+  const m = content.match(/^\|\s*ringGateVerdict\s*\|\s*(\w+)\s*\|/im);
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * Determine which milestones have been reached based on current state.
+ * @param {string} content
+ */
+function detectMilestones(content) {
+  const milestones = [];
+  const iteration = parseIteration(content);
+
+  if (iteration >= 2 || hasArchivedRing(content, 1)) {
+    milestones.push('ring-1-archived');
+  }
+  if (iteration >= 3 || hasArchivedRing(content, 2)) {
+    milestones.push('ring-2-archived');
+  }
+  if (iteration >= 4 || hasArchivedRing(content, 3)) {
+    milestones.push('ring-3-archived');
+  }
+
+  if (parseDevStatus(content) === 'ready') {
+    milestones.push('dev-ready');
+  }
+
+  if (iteration >= 4 && parseRingGateVerdict(content) === 'pass') {
+    milestones.push('ring-4-done');
+  }
+
+  return milestones;
+}
+
+function loadSnapshotState(projectDir) {
+  const statePath = path.join(projectDir, '.claude', 'hooks', '.snapshot-state.json');
+  try {
+    if (fs.existsSync(statePath)) {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+function saveSnapshotState(projectDir, state) {
+  const statePath = path.join(projectDir, '.claude', 'hooks', '.snapshot-state.json');
+  const dir = path.dirname(statePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+function resolveSnapshotScript() {
+  const local = path.resolve(__dirname, '..', 'snapshot.mjs');
+  if (fs.existsSync(local)) return local;
+
+  const candidate = path.resolve(__dirname, '..', '..', '..', 'snapshot.mjs');
+  if (fs.existsSync(candidate)) return candidate;
+
+  return null;
+}
+
+function runSnapshot(projectDir, label) {
+  const snapshotScript = resolveSnapshotScript();
+
+  if (!snapshotScript) {
+    process.stderr.write('[snapshot-milestone] snapshot script not found\n');
+    return false;
+  }
+
+  const result = spawnSync('node', [
+    snapshotScript,
+    '--project', projectDir,
+    '--name', label,
+    '--force',  // non-interactive hook — skip active-CLI check
+  ], {
+    encoding: 'utf8',
+    timeout: 120_000,  // git add/commit may be slower than zip
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  if (result.status !== 0) {
+    process.stderr.write(`[snapshot-milestone] snapshot failed (${label}): ${result.stderr}\n`);
+    return false;
+  }
+
+  process.stderr.write(`[snapshot-milestone] snapshot committed: ${label}\n`);
+  return true;
+}
+
+function main() {
+  const projectDir = resolveProjectDir();
+  const content = readProjectState(projectDir);
+
+  if (!content) {
+    process.exit(0);
+  }
+
+  const currentMilestones = detectMilestones(content);
+
+  if (currentMilestones.length === 0) {
+    process.exit(0);
+  }
+
+  const snapshotState = loadSnapshotState(projectDir);
+  let anyNew = false;
+
+  for (const milestone of currentMilestones) {
+    if (snapshotState[milestone]) {
+      continue;
+    }
+
+    anyNew = true;
+    const ok = runSnapshot(projectDir, milestone);
+    if (ok) {
+      snapshotState[milestone] = new Date().toISOString();
+    }
+  }
+
+  if (anyNew) {
+    saveSnapshotState(projectDir, snapshotState);
+  }
+
+  process.exit(0);
+}
+
+main();

package/project-template-v2/.claude/hooks/user-prompt.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * PlayCraft User Prompt Hook — fires on every UserPromptSubmit.
+ *
+ * Actions:
+ *   1. Increment turn counter, log to logs/hook.log
+ *   2. Snapshot (always, for full audit trail)
+ *      Output goes to ../ to avoid nesting.
+ *
+ * Claude Code / CodeBuddy version — uses CODEBUDDY_PROJECT_DIR / CLAUDE_PROJECT_DIR.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function resolveProjectDir() {
+  const raw = process.env.CODEBUDDY_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  if (process.platform === 'win32' && /^\/[a-zA-Z]\//.test(raw))
+    return raw[1].toUpperCase() + ':' + raw.slice(2).replace(/\//g, '\\');
+  return path.resolve(raw);
+}
+
+function loadState(projectDir) {
+  const p = path.join(projectDir, '.claude', 'logs', 'session.json');
+  try { if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch {}
+  return { turns: 0 };
+}
+
+function saveState(projectDir, state) {
+  const d = path.join(projectDir, '.claude', 'logs');
+  fs.mkdirSync(d, { recursive: true });
+  fs.writeFileSync(path.join(d, 'session.json'), JSON.stringify(state, null, 2));
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString('utf8');
+  try { return raw.trim() ? JSON.parse(raw) : null; }
+  catch { return null; }
+}
+
+function sanitize(text, maxLen = 20) {
+  return (text || '')
+    .replace(/[^\w一-鿿 -]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, maxLen)
+    .replace(/-$/, '');
+}
+
+// ── snapshot ─────────────────────────────────────────────────────────────────
+
+function runSnapshot(projectDir, state, promptText) {
+  const snapScript = path.join(__dirname, '..', 'snapshot.mjs');
+
+  if (!fs.existsSync(snapScript)) {
+    console.error('[snap] script not found');
+    return null;
+  }
+
+  const prefix = sanitize(promptText, 20);
+  const snapName = prefix ? `prompt_${prefix}` : `prompt_turn-${state.turns}`;
+
+  const r = spawnSync('node', [
+    snapScript, '--project', projectDir, '--name', snapName, '--force',
+  ], { encoding: 'utf8', timeout: 120_000, stdio: 'pipe' });
+
+  if (r.status !== 0) {
+    console.error(`[snap] failed: ${r.stderr?.slice(0, 200)}`);
+    return false;
+  }
+  const m = r.stdout.match(/Hash:\s*(\S+)/);
+  const hash = m ? m[1] : null;
+  if (hash) console.error(`[snap] ${hash}`);
+  return true;
+}
+
+// ── log ──────────────────────────────────────────────────────────────────────
+
+function writeHookLog(projectDir, entry) {
+  const logPath = path.join(projectDir, 'logs', 'hook.log');
+  const dir = path.dirname(logPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(logPath, entry + '\n');
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const payload = await readStdin();
+  if (!payload) return;
+  const promptText = payload.prompt || payload.user_prompt || '';
+  if (!promptText) return;
+
+  const projectDir = resolveProjectDir();
+  const state = loadState(projectDir);
+  state.turns += 1;
+  state.lastPromptAt = new Date().toISOString();
+
+  const ts = new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' });
+  const preview = promptText.replace(/\n/g, '\\n').slice(0, 300);
+
+  // Snapshot (always)
+  const snapped = runSnapshot(projectDir, state, promptText);
+  if (snapped) state.lastSnapAt = ts;
+
+  // Detailed log entry
+  const lines = [
+    '─'.repeat(60),
+    `[${ts}] PROMPT #${state.turns}`,
+    `    Input : ${preview}`,
+    `    Snapshot: ${snapped ? 'ok' : 'FAILED'}`,
+    '─'.repeat(60),
+  ];
+  writeHookLog(projectDir, lines.join('\n'));
+
+  console.error(`prompt #${state.turns} logged`);
+  saveState(projectDir, state);
+}
+
+main().catch(e => { process.stderr.write('[user-prompt] ' + e.message + '\n'); process.exitCode = 1; });

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

@@ -0,0 +1,33 @@
+{
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "hooks": {
+    "SubagentStop": [
+      {
+        "matcher": "artist|technical-artist|developer|reviewer|game-designer|skill-selector",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/snapshot-milestone.mjs"],
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/user-prompt.mjs"],
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/project-template-v2/.claude/skills/brainstorming/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: brainstorming
+description: 'Collaborative ideation for new creative concepts and game design. Use when exploring gameplay directions, clarifying vague creative ideas, or making design decisions from scratch. Not for implementation, code changes, workflow coordination, or routine modifications.'
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. ~~**Offer visual companion**~~ — **SKIPPED in this project.** All brainstorm questions are text/option-based. Do not offer or use the browser visual mode.
+3. **Ask clarifying questions** — self-answer what context already tells you, batch related questions, only ask the user what you genuinely need
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — at confidence threshold, present full design at once; otherwise section-by-section for uncertain areas
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+8. **User reviews written spec** — ask user to review the spec file before proceeding
+9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Spec self-review\n(fix inline)";
+    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "User reviews spec?" -> "Write design doc" [label="changes requested"];
+    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
+}
+```
+
+**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- Focus on understanding: purpose, constraints, success criteria
+- **Always use the `AskUserQuestion` tool for terminal questions** — never ask questions as plain text. It renders as a clickable option card with a built-in "Other" free-text input, so every question automatically supports both selection and custom responses with a single confirm action.
+  - Single-select (default): for mutually exclusive choices
+  - `multiSelect: true`: when multiple answers are valid (e.g., "which features do you want?")
+
+**Self-answering & batched questions:**
+
+Not every question needs to go to the user. Apply these strategies to reduce round-trips:
+
+- **Self-answer when confident:** If the project context (files, docs, conventions) already provides a clear answer, state your assumption inline rather than asking. Format: "Based on [evidence], I'm assuming [X]. (Let me know if this is wrong.)" — this turns a blocking question into a non-blocking assertion.
+- **Batch related questions:** When multiple questions are closely related (e.g., all about the same subsystem or decision area), present them together in one message rather than one-at-a-time. Group 2-4 related questions per turn.
+- **Use an intermediate file for complex question sets:** For topics with many interrelated questions, write them to a scratch file (e.g., `docs/superpowers/specs/.brainstorm-questions-<topic>.md`) so the user can review and answer at their own pace. This is especially useful when questions have dependencies or when the user might want to think before answering.
+- **Still ask one-at-a-time for:** genuinely independent decisions where the answer to one changes what you'd ask next, or high-stakes architectural choices that deserve focused attention.
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Confidence threshold — when to present all at once:**
+
+If the clarifying phase has already aligned understanding sufficiently (e.g., user gave detailed requirements, project context is unambiguous, or you self-answered most questions without objection), present the full design in one message and ask for approval at the end. Reserve section-by-section confirmation for cases where:
+
+- The design has genuinely uncertain areas you want early feedback on
+- Multiple sections have competing trade-offs the user should weigh independently
+- The project is large enough that a single message would be overwhelming
+
+**Design for isolation and clarity:**
+
+- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
+- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
+- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
+- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
+
+**Working in existing codebases:**
+
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**User Review Gate:**
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+**Implementation:**
+
+- Invoke the writing-plans skill to create a detailed implementation plan
+- Do NOT invoke any other skill. writing-plans is the next step.
+
+## Key Principles
+
+- **Self-answer what you can, ask what you must** - Reduce round-trips by leveraging project context to answer your own questions; only ask the user when genuinely uncertain
+- **Batch related questions** - Group related questions together; only go one-at-a-time for independent high-stakes decisions
+- **Always use `AskUserQuestion`** - Every terminal question must use this tool; it provides clickable options + built-in Other input + confirm in one interaction
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Confidence-driven presentation** - If understanding is already aligned, present the full design at once; only section-by-section when genuinely uncertain
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Visual Companion
+
+**DISABLED in this project.** All brainstorming is text/option-based. Do not offer, use, or reference the visual companion browser mode.