clickroom 0.0.0-stage → 0.2.0

package/cli/gaps.js

@@ -0,0 +1,37 @@
+// "Find gaps with Claude" (Clarify): the project's clickroom terminal runs Claude Code headless in
+// the project folder. It may only read files and ask through clickroom's MCP server, so each gap it
+// finds lands in Clarify as a draft, live, while nothing in the folder changes.
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { ROOT } from './config.js';
+import { call } from './client.js';
+import { gapsPrompt } from '../worker/handoff.js';
+
+const TOOLS = ['Read', 'Glob', 'Grep', 'mcp__clickroom__clickroom_ask', 'mcp__clickroom__clickroom_get_questions'];
+const NEVER = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash', 'WebFetch', 'WebSearch'];
+const LIMIT = 10 * 60 * 1000; // a run that hangs is stopped
+
+export const hasClaude = () => spawnSync(process.platform === 'win32' ? 'where' : 'which', ['claude'], { stdio: 'ignore' }).status === 0;
+
+const questionCount = async (name) =>
+  (await call('GET', `/__ps/api/projects/${encodeURIComponent(name)}/threads`)).threads.filter((t) => t.kind === 'question').length;
+
+// Resolves to the number of questions it added (drafts), or throws.
+export async function findGaps(name, root) {
+  if (!hasClaude()) throw new Error('Claude Code (`claude`) is not installed on the computer running `clickroom` for this project');
+  const before = await questionCount(name);
+  const mcp = JSON.stringify({ mcpServers: { clickroom: { command: process.execPath, args: [path.join(ROOT, 'bin', 'clickroom.js'), 'mcp'] } } });
+  const args = ['-p', gapsPrompt(name), '--mcp-config', mcp, '--strict-mcp-config', '--tools', 'Read,Glob,Grep', '--allowedTools', TOOLS.join(','), '--disallowedTools', NEVER.join(','), '--no-session-persistence'];
+  await new Promise((resolve, reject) => {
+    const child = spawn('claude', args, { cwd: root, stdio: ['ignore', 'ignore', 'pipe'] });
+    let err = '';
+    child.stderr.on('data', (d) => (err = (err + d).slice(-2000)));
+    const timer = setTimeout(() => child.kill('SIGTERM'), LIMIT);
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      code === 0 ? resolve() : reject(new Error(err.trim().split('\n').pop() || `claude exited with ${code}`));
+    });
+  });
+  return Math.max(0, (await questionCount(name)) - before);
+}

package/cli/login.js

@@ -0,0 +1,74 @@
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { credentials, saveCredentials, adminToken } from './config.js';
+import { bold, dim } from './dev.js';
+
+export const DEFAULT_URL = 'https://clickroom.dev';
+
+// `clickroom login [workspace|url]`: connects this computer to a clickroom workspace as you
+// ("acme" means https://acme.clickroom.dev). It opens a page in your browser (where you're signed
+// in from your invite) to approve this computer, then keeps a key of its own in
+// ~/.clickroom/credentials.json.
+export async function login(arg) {
+  if (arg && /^[a-z][a-z0-9-]{1,19}$/.test(arg)) arg = `https://${arg}.${new URL(DEFAULT_URL).hostname}`;
+  const url = (arg || process.env.CLICKROOM_URL || credentials()?.url || DEFAULT_URL).replace(/\/$/, '');
+  if (!/^https?:\/\//.test(url)) throw new Error('usage: clickroom login <workspace>   (or a URL: clickroom login https://acme.clickroom.dev)');
+  if (adminToken() && !process.env.CLICKROOM_TOKEN) console.log(dim('  This computer has the admin key (.dev.vars), which the clickroom command uses first.'));
+  const res = await fetch(`${url}/__ps/api/cli-login`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ label: `${os.userInfo().username} on ${os.hostname().replace(/\.local$/, '')}` }),
+  }).catch(() => null);
+  if (!res) throw new Error(`Can't reach ${url}.`);
+  const start = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(start.error || `${url} answered ${res.status}`);
+
+  console.log(`\n  Approve this computer in your browser:\n  ${bold(start.url)}\n`);
+  console.log(`  Check that the page shows ${bold(start.code)}.`);
+  console.log(dim('  Not signed in there? Sign in with the email address you were invited with.\n'));
+  openUrl(start.url);
+
+  const until = Date.now() + start.expiresIn * 1000;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const r = await fetch(`${url}/__ps/api/cli-login/poll`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ poll: start.poll }),
+    }).catch(() => null);
+    if (!r?.ok) continue;
+    const d = await r.json();
+    if (d.status === 'expired') break;
+    if (d.status === 'approved') {
+      saveCredentials({ url, token: d.token, name: d.me.name, email: d.me.email || null, at: new Date().toISOString() });
+      console.log(`${bold('✔')} Signed in to ${url} as ${bold(d.me.name)}${d.me.email ? ` (${d.me.email})` : ''}.`);
+      console.log(dim('  Run `clickroom` in a project to share it.'));
+      return;
+    }
+  }
+  throw new Error('The approval link expired. Run `clickroom login` again.');
+}
+
+export async function logout() {
+  const c = credentials();
+  if (!c) return console.log('Not signed in.');
+  await fetch(`${c.url}/__ps/api/cli-login/logout`, { method: 'POST', headers: { authorization: `Bearer ${c.token}` } }).catch(() => {});
+  saveCredentials(null);
+  console.log(`${bold('✔')} Signed out of ${c.url}.`);
+}
+
+export async function whoami() {
+  const c = credentials();
+  if (!c) return console.log(adminToken() ? 'The owner (admin key in .dev.vars).' : 'Not signed in. Run `clickroom login`.');
+  const res = await fetch(`${c.url}/__ps/api/me`, { headers: { authorization: `Bearer ${c.token}` } }).catch(() => null);
+  if (res?.status === 401) return console.log(`Your sign-in to ${c.url} has ended. Run \`clickroom login\` again.`);
+  const me = res?.ok ? await res.json() : c;
+  console.log(`${me.name}${me.email ? ` (${me.email})` : ''} on ${c.url}`);
+}
+
+function openUrl(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+  try {
+    spawn(cmd, [url], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+  } catch {}
+}

package/cli/mcp.js

@@ -0,0 +1,205 @@
+import readline from 'node:readline';
+import fs from 'node:fs';
+import path from 'node:path';
+import { call, callBinary, callUpload } from './client.js';
+
+// Minimal MCP server over stdio (newline-delimited JSON-RPC 2.0).
+// Every tool proxies to the running clickroom worker so actions broadcast live to reviewers.
+
+const AGENT = () => ({ name: process.env.CLICKROOM_AGENT_NAME || 'Claude', role: 'agent', color: '#7c3aed' });
+const enc = encodeURIComponent;
+
+const TOOLS = [
+  {
+    name: 'clickroom_list_projects',
+    description: 'List prototypes under review with feedback counts per status (open, queued, in_progress, review, resolved).',
+    inputSchema: { type: 'object', properties: {} },
+    run: async () => {
+      const { projects } = await call('GET', '/__ps/api/projects');
+      if (!projects.length) return 'No projects registered.';
+      return projects
+        .map((p) => `${p.name} (${p.kind}, source: ${p.source || p.target}): open ${p.counts.open}, queued ${p.counts.queued}, in_progress ${p.counts.in_progress}, review ${p.counts.review ?? 0}, resolved ${p.counts.resolved}, open questions ${p.counts.questions ?? 0}`)
+        .join('\n');
+    },
+  },
+  {
+    name: 'clickroom_get_feedback',
+    description:
+      'Get client/team feedback for a prototype as an actionable Markdown digest: element selectors, text, HTML snippets and full conversations. Default status "actionable" = only the threads the team queued for agents; work on nothing else.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        status: { type: 'string', enum: ['actionable', 'open', 'queued', 'in_progress', 'review', 'resolved', 'active', 'all'], default: 'actionable' },
+        format: { type: 'string', enum: ['markdown', 'json'], default: 'markdown' },
+      },
+      required: ['project'],
+    },
+    run: async ({ project, status = 'actionable', format = 'markdown' }) => {
+      const ext = format === 'json' ? 'json' : 'md';
+      const data = await call('GET', `/__ps/api/projects/${enc(project)}/feedback.${ext}?status=${enc(status)}`);
+      return typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    },
+  },
+  {
+    name: 'clickroom_ask',
+    description:
+      'Ask the client a question (e.g. a business rule, missing content, which option they prefer), or list an assumption you made for them to confirm or correct. It starts as a draft that only the team sees; the team sends it to the client, edits, answers or removes it. It shows up in the review under Questions, with `now` saying what the prototype does until it is answered. Point it at the spot it is about with `page` + `selector` (and a `screenshot` if you have one) so it is easier to answer; the team\'s browser adds a screenshot of that spot when there is none.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        question: { type: 'string' },
+        type: { type: 'string', enum: ['question', 'assumption'], default: 'question', description: 'assumption: something you decided that the client should confirm or correct' },
+        now: { type: 'string', description: 'What the prototype does until this is answered' },
+        key: { type: 'string', description: 'Stable id; asking again with the same key rewords the item instead of adding it twice' },
+        page: { type: 'string', description: 'Prototype path it is about, e.g. /pricing' },
+        selector: { type: 'string', description: 'CSS selector of the element it is about, on that page' },
+        screenshot: { type: 'string', description: 'Absolute path of a PNG/JPEG/WebP screenshot of what it is about' },
+      },
+      required: ['project', 'question'],
+    },
+    run: async ({ project, question, type, now, key, page, selector, screenshot }) => {
+      const base = `/__ps/api/projects/${enc(project)}/threads`;
+      const el = selector ? { selector } : undefined;
+      const t = await call('POST', base, { kind: 'question', body: question, type, now, key, page, el, author: AGENT() });
+      if (screenshot) {
+        const mime = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' }[path.extname(screenshot).toLowerCase()];
+        if (!mime) throw new Error('screenshot must be a .png, .jpg or .webp file');
+        await callUpload(`${base}/${t.seq}/shot`, fs.readFileSync(screenshot), mime);
+      }
+      if (t.createdAt !== t.updatedAt) return `Updated #${t.seq}. Check for answers with clickroom_get_questions.`;
+      return t.status === 'draft'
+        ? `Saved #${t.seq} as a draft: the team reviews it and sends it to the client (or answers it). Check for answers with clickroom_get_questions.`
+        : `Asked #${t.seq}. Check for answers with clickroom_get_questions.`;
+    },
+  },
+  {
+    name: 'clickroom_get_questions',
+    description:
+      'Get the questions asked to the client with their full conversations; the client\'s replies are the answer. Default status "open" (sent to the client); "draft" lists the ones the team has not sent yet. Each question says whether it is waiting for the client, answered, or sent to agent; "answered" lists the answers the team sent to an agent to work in.',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, status: { type: 'string', enum: ['open', 'draft', 'answered', 'resolved', 'all'], default: 'open' } },
+      required: ['project'],
+    },
+    run: ({ project, status = 'open' }) => call('GET', `/__ps/api/projects/${enc(project)}/feedback.md?kind=question&status=${enc(status)}`),
+  },
+  {
+    name: 'clickroom_get_thread',
+    description: 'Get one feedback thread (by its #number) with its anchor, full conversation and, when there is one, a screenshot of the spot as the reviewer saw it.',
+    inputSchema: { type: 'object', properties: { project: { type: 'string' }, seq: { type: 'integer' } }, required: ['project', 'seq'] },
+    run: async ({ project, seq }) => {
+      const path = `/__ps/api/projects/${enc(project)}/threads/${Number(seq)}`;
+      const t = await call('GET', path);
+      const content = [{ type: 'text', text: JSON.stringify(t, null, 2) }];
+      const shot = t.shot ? await callBinary(`${path}/shot`) : null;
+      if (shot) content.push({ type: 'image', data: shot.base64, mimeType: shot.mime });
+      return content;
+    },
+  },
+  {
+    name: 'clickroom_claim',
+    description: 'Optional: post a short note on a thread before working on it (its status stays as it is; mark it with clickroom_mark_fixed when done).',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, seq: { type: 'integer' }, note: { type: 'string' } },
+      required: ['project', 'seq'],
+    },
+    run: async ({ project, seq, note }) => {
+      const t = await call('PATCH', `/__ps/api/projects/${enc(project)}/threads/${Number(seq)}`, { status: 'in_progress', note, author: AGENT() });
+      return note ? `Noted on #${t.seq}.` : `#${t.seq}: nothing to note. Mark it with clickroom_mark_fixed when it's done.`;
+    },
+  },
+  {
+    name: 'clickroom_reply',
+    description: 'Reply in a feedback thread, e.g. to ask the client a clarifying question. Shows up live in the review.',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, seq: { type: 'integer' }, body: { type: 'string' } },
+      required: ['project', 'seq', 'body'],
+    },
+    run: async ({ project, seq, body }) => {
+      const t = await call('POST', `/__ps/api/projects/${enc(project)}/threads/${Number(seq)}/comments`, { body, author: AGENT() });
+      return `Replied on #${t.seq}.`;
+    },
+  },
+  {
+    name: 'clickroom_mark_fixed',
+    description:
+      'Mark a thread fixed after making the change, or an answered question as worked into the prototype. Include a note describing what changed. The next pushed version records where it landed; for comments the reviewer then checks it and resolves or reopens it.',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, seq: { type: 'integer' }, note: { type: 'string' } },
+      required: ['project', 'seq'],
+    },
+    run: ({ project, seq, note }) => markFixed(project, seq, note),
+  },
+  {
+    name: 'clickroom_resolve',
+    description:
+      'Same as clickroom_mark_fixed (the reviewer confirms the fix). Pass close: true to resolve outright, only when no check is needed (e.g. a team note, or closing a settled question).',
+    inputSchema: {
+      type: 'object',
+      properties: { project: { type: 'string' }, seq: { type: 'integer' }, note: { type: 'string' }, close: { type: 'boolean' } },
+      required: ['project', 'seq'],
+    },
+    run: async ({ project, seq, note, close }) => {
+      if (!close) return markFixed(project, seq, note);
+      const t = await call('PATCH', `/__ps/api/projects/${enc(project)}/threads/${Number(seq)}`, { status: 'resolved', note, author: AGENT() });
+      return `Resolved #${t.seq}.`;
+    },
+  },
+];
+
+async function markFixed(project, seq, note) {
+  const t = await call('PATCH', `/__ps/api/projects/${enc(project)}/threads/${Number(seq)}`, { status: 'review', note, author: AGENT() });
+  if (t.kind === 'question') return `#${t.seq} marked processed. ${t.fixedIn ? `It landed in v${t.fixedIn}.` : 'The next push (`clickroom push`) records the version it lands in.'}`;
+  const where = t.fixedIn ? `in ${t.fixedIn === 'live' ? 'the live dev server' : 'v' + t.fixedIn}` : 'once a new version is pushed (`clickroom push`)';
+  return `#${t.seq} marked fixed. The reviewer checks it ${where}.`;
+}
+
+export function runMcp({ input = process.stdin, output = process.stdout } = {}) {
+  const write = (msg) => output.write(JSON.stringify(msg) + '\n');
+  const rl = readline.createInterface({ input });
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    }
+    const { id, method, params } = msg;
+    const reply = (result) => id !== undefined && write({ jsonrpc: '2.0', id, result });
+    const fail = (code, message) => id !== undefined && write({ jsonrpc: '2.0', id, error: { code, message } });
+    switch (method) {
+      case 'initialize':
+        return reply({
+          protocolVersion: params?.protocolVersion || '2025-06-18',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'clickroom', version: '0.1.0' },
+          instructions:
+            'clickroom collects client feedback on prototypes. Typical loop: clickroom_get_feedback → for each item change the code, then clickroom_mark_fixed with a note (the reviewer confirms it in the next pushed version). Use clickroom_get_thread to see a screenshot of the spot, and clickroom_reply to ask about one comment. For anything you would otherwise guess (content, business rules, choices), ask the client with clickroom_ask and read answers with clickroom_get_questions. Once an answer is worked into the prototype, mark that question with clickroom_mark_fixed. `clickroom process` in the project folder gathers all of this into .clickroom/process.md.',
+        });
+      case 'ping':
+        return reply({});
+      case 'tools/list':
+        return reply({ tools: TOOLS.map(({ run, ...t }) => t) });
+      case 'tools/call': {
+        const tool = TOOLS.find((t) => t.name === params?.name);
+        if (!tool) return fail(-32602, `Unknown tool: ${params?.name}`);
+        try {
+          const out = await tool.run(params.arguments || {});
+          return reply({ content: Array.isArray(out) ? out : [{ type: 'text', text: out }] });
+        } catch (err) {
+          return reply({ content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true });
+        }
+      }
+      default:
+        if (method?.startsWith('notifications/')) return;
+        return fail(-32601, `Method not found: ${method}`);
+    }
+  });
+  return rl;
+}

package/cli/note.js

@@ -0,0 +1,109 @@
+import { spawn } from 'node:child_process';
+import { call } from './client.js';
+import { changedSource, folderChanges } from './changes.js';
+
+// The version note when a push comes without one ("Push v16" on the dashboard, or an empty
+// answer in the terminal): Claude Code on this computer (`claude -p`) describes the source changes
+// since the last push as reviewers will notice them, plus the comments fixed in this version.
+// Without git, Claude or a usable answer: the fixed comments, else the changed file names.
+// CLICKROOM_AUTO_NOTE=off never asks Claude.
+
+const PROMPT = [
+  'You write the version note for a clickable prototype that designers, product people and clients review.',
+  'You get the code changes since the previous version, and the review comments this version fixes.',
+  'Describe what changed the way someone clicking through the prototype would notice it.',
+  'Write 1 to 4 items of at most 6 words each, separated by ", " (comma and space), in English. Keep it under 160 characters.',
+  'No file names, code terms, version numbers, quotes or a full stop at the end. Output only the note.',
+].join(' ');
+const NOTE_MAX = 200;
+
+export async function autoNote(name, dir) {
+  const fixes = await fixesInNextVersion(name).catch(() => []);
+  if (process.env.CLICKROOM_AUTO_NOTE !== 'off') {
+    const src = await changedSource(name, dir).catch(() => null);
+    if (src) {
+      const input = [
+        fixes.length ? `Review comments fixed in this version:\n${fixes.map((f) => `- ${f}`).join('\n')}\n` : '',
+        `Files changed:\n${src.stat.trim()}\n`,
+        `Diff:\n${src.patch}`,
+      ].join('\n');
+      const note = clean(await askClaude(input));
+      if (note) return note;
+    }
+  }
+  return fallbackNote(fixes, await folderChanges(name, dir).catch(() => null));
+}
+
+// Fixes waiting for the next version: in review, not yet shipped (see addVersion in room.js).
+async function fixesInNextVersion(name) {
+  const { threads } = await call('GET', `/__ps/api/projects/${encodeURIComponent(name)}/threads`);
+  return (threads || [])
+    .filter((t) => t.status === 'review' && !t.fixedIn)
+    .map((t) => oneLine(t.comments?.[0]?.body || `#${t.seq}`, 80));
+}
+
+export function fallbackNote(fixes, changes) {
+  if (fixes?.length) return cut(`Fixed: ${fixes.join(', ')}`);
+  const files = (changes?.paths || []).map((p) => p.split('/').pop());
+  if (!files.length) return null;
+  const more = (changes.files || files.length) - Math.min(files.length, 3);
+  return cut(`Updated ${files.slice(0, 3).join(', ')}${more > 0 ? ` +${more}` : ''}`);
+}
+
+function askClaude(input) {
+  return new Promise((resolve) => {
+    let out = '';
+    let child;
+    try {
+      child = spawn('claude', ['-p', '--model', 'haiku', '--tools', '', '--no-session-persistence', '--setting-sources', '', '--system-prompt', PROMPT], { stdio: ['pipe', 'pipe', 'ignore'] });
+    } catch {
+      return resolve(null);
+    }
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve(null);
+    }, 90000);
+    child.on('error', () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+    child.stdout.on('data', (d) => (out += d));
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve(code === 0 ? out : null);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}
+
+// One plain line: no wrapping quotes, bullets or trailing full stop; null when there's nothing.
+export function clean(text) {
+  if (!text) return null;
+  const items = String(text).trim().replace(/^["'“]+|["'”]+$/g, '').split('\n')
+    .map((l) => l.trim().replace(/^[-*•]\s*/, '').replace(/\.$/, '').trim())
+    .filter(Boolean);
+  const line = oneLine(items.join(', '), 1000);
+  return line ? fit(line) : null;
+}
+
+// Whole items only, up to NOTE_MAX: a note never ends halfway through a word.
+function fit(line) {
+  if (line.length <= NOTE_MAX) return line;
+  let out = '';
+  for (const item of line.split(/,\s+/)) {
+    const next = out ? `${out}, ${item}` : item;
+    if (next.length > NOTE_MAX) break;
+    out = next;
+  }
+  return out || cut(line);
+}
+
+function oneLine(s, max) {
+  const flat = String(s).replace(/\s+/g, ' ').trim();
+  return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
+}
+
+function cut(s) {
+  return s.length > NOTE_MAX ? s.slice(0, NOTE_MAX - 1) + '…' : s;
+}

package/cli/process.js

@@ -0,0 +1,47 @@
+// `clickroom process`: gathers what the team queued for an agent (comments, and
+// answers to questions), writes one brief into the project and starts Claude Code on it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { call } from './client.js';
+import { buildBrief } from '../worker/handoff.js';
+
+const BRIEF = path.join('.clickroom', 'process.md');
+
+export async function gather(name, { comments = true, questions = true } = {}) {
+  const base = `/__ps/api/projects/${encodeURIComponent(name)}`;
+  const get = async (query) => {
+    const [json, md] = await Promise.all([call('GET', `${base}/feedback.json?${query}`), call('GET', `${base}/feedback.md?${query}`)]);
+    return { count: json.count, md: json.count ? md : '', tasks: json.threads.filter((t) => t.kind === 'task').length };
+  };
+  return {
+    ...(comments ? await get('status=actionable').then(({ tasks, ...c }) => ({ comments: c, tasks })) : { comments: { count: 0, md: '' } }),
+    answers: questions ? await get('kind=question&status=answered') : { count: 0, md: '' },
+  };
+}
+
+export { buildBrief };
+
+export function writeBrief(root, text) {
+  const dir = path.join(root, '.clickroom');
+  fs.mkdirSync(dir, { recursive: true });
+  // Keep the folder out of the project's git without touching its .gitignore.
+  const ignore = path.join(dir, '.gitignore');
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, '*\n');
+  fs.writeFileSync(path.join(root, BRIEF), text);
+  return BRIEF;
+}
+
+export function hasClaude() {
+  return spawnSync(process.platform === 'win32' ? 'where' : 'which', ['claude'], { stdio: 'ignore' }).status === 0;
+}
+
+// Interactive Claude Code in the project, so the person watches and approves the changes.
+export function startClaude(root, name) {
+  const prompt = `Process the clickroom feedback in ${BRIEF} for project "${name}". Read it first, then work through every item.`;
+  return new Promise((resolve, reject) => {
+    const child = spawn('claude', [prompt], { cwd: root, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('exit', (code) => resolve(code ?? 0));
+  });
+}