create-agent-room 1.2.1

package/lib/lint-sessions.js

@@ -0,0 +1,278 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { green, yellow, red, cyan, bold } = require('./color');
+
+const REQUIRED_SECTIONS = [
+  'Goal',
+  'Files touched',
+  'Actions taken',
+  'Tests run',
+  'Decisions made',
+  'Outcome'
+];
+
+// These are inline fields, not section headers
+const REQUIRED_FIELDS = ['Date', 'Agent', 'Classification'];
+
+const VALID_CLASSIFICATIONS = ['Bug', 'Enhancement', 'Feature', 'Product'];
+const VALID_OUTCOMES = ['Completed', 'Handed Off', 'In Progress', 'Blocked'];
+
+function validateMarkdownSession(filePath, fileName) {
+  const errors = [];
+  const warnings = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Check if file is empty or too short
+    if (!content.trim()) {
+      errors.push(`${fileName}: File is empty`);
+      return { errors, warnings };
+    }
+
+    // Check for session log title
+    if (!content.match(/^#\s+Session Log:/m)) {
+      errors.push(`${fileName}: Missing "# Session Log:" header`);
+    }
+
+    // Check for required inline fields (Date, Agent, Classification)
+    for (const field of REQUIRED_FIELDS) {
+      const fieldRegex = new RegExp(`\\*\\*${field}:\\*\\*\\s*(.+?)(?:\\n|\\r|$)`, 'i');
+      if (!content.match(fieldRegex)) {
+        errors.push(`${fileName}: Missing required field "**${field}:**"`);
+      }
+    }
+
+    // Check for each required section header
+    for (const section of REQUIRED_SECTIONS) {
+      const sectionRegex = new RegExp(`^##\\s+${section}`, 'm');
+      if (!content.match(sectionRegex)) {
+        errors.push(`${fileName}: Missing required section "## ${section}"`);
+      }
+    }
+
+    // Validate Date format
+    const dateMatch = content.match(/\*\*Date:\*\*\s*(.+?)(?:\n|\r)/);
+    if (!dateMatch || !dateMatch[1].trim()) {
+      errors.push(`${fileName}: Date field is empty or malformed`);
+    } else {
+      const dateStr = dateMatch[1].trim();
+      if (!/^\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}/.test(dateStr)) {
+        warnings.push(`${fileName}: Date format should be "YYYY-MM-DD HH:MM", got "${dateStr}"`);
+      }
+    }
+
+    // Validate Agent field
+    const agentMatch = content.match(/\*\*Agent:\*\*\s*(.+?)(?:\n|\r)/);
+    if (!agentMatch || !agentMatch[1].trim()) {
+      errors.push(`${fileName}: Agent field is empty`);
+    }
+
+    // Validate Classification
+    const classMatch = content.match(/\*\*Classification:\*\*\s*(.+?)(?:\n|\r)/);
+    if (!classMatch || !classMatch[1].trim()) {
+      errors.push(`${fileName}: Classification field is empty`);
+    } else {
+      const classification = classMatch[1].trim();
+      if (!VALID_CLASSIFICATIONS.includes(classification)) {
+        errors.push(`${fileName}: Invalid Classification "${classification}". Must be one of: ${VALID_CLASSIFICATIONS.join(', ')}`);
+      }
+    }
+
+    // Validate Goal (one sentence, not empty)
+    const goalMatch = content.match(/##\s+Goal\r?\n+([\s\S]*?)(?=##|$)/);
+    if (!goalMatch || !goalMatch[1].trim()) {
+      errors.push(`${fileName}: Goal section is empty`);
+    } else {
+      const goalText = goalMatch[1].trim();
+      if (goalText.split('\n').length > 1) {
+        warnings.push(`${fileName}: Goal should be one sentence, found multiple lines`);
+      }
+      if (goalText.length > 200) {
+        warnings.push(`${fileName}: Goal is very long (${goalText.length} chars), consider shorter wording`);
+      }
+    }
+
+    // Validate Files touched (should list something)
+    const filesMatch = content.match(/##\s+Files touched\r?\n+([\s\S]*?)(?=##|$)/);
+    if (!filesMatch || !filesMatch[1].trim()) {
+      warnings.push(`${fileName}: Files touched section is empty (should list Read/Created/Modified)`);
+    } else {
+      const filesText = filesMatch[1].trim();
+      if (!filesText.match(/-(Read|Created|Modified):/i)) {
+        warnings.push(`${fileName}: Files touched should use format "- Read: file.js" / "- Created: file.js" / "- Modified: file.js"`);
+      }
+    }
+
+    // Validate Actions taken (should have at least one action)
+    const actionsMatch = content.match(/##\s+Actions taken\r?\n+([\s\S]*?)(?=##|$)/);
+    if (!actionsMatch || !actionsMatch[1].trim()) {
+      errors.push(`${fileName}: Actions taken section is empty`);
+    } else {
+      const actionsText = actionsMatch[1].trim();
+      if (!actionsText.match(/^\s*\d+\./m)) {
+        warnings.push(`${fileName}: Actions should be numbered list (1., 2., etc.)`);
+      }
+      const actionCount = (actionsText.match(/^\s*\d+\./gm) || []).length;
+      if (actionCount === 0) {
+        errors.push(`${fileName}: Actions taken should contain numbered steps (found 0)`);
+      }
+    }
+
+    // Validate Tests run
+    const testsMatch = content.match(/##\s+Tests run\r?\n+([\s\S]*?)(?=##|$)/);
+    if (!testsMatch || !testsMatch[1].trim()) {
+      warnings.push(`${fileName}: Tests run section is empty`);
+    }
+
+    // Validate Outcome Status
+    const outcomeMatch = content.match(/##\s+Outcome[^#]*\*\*Status:\*\*\s*(.+?)(?:\n|\r)/);
+    if (!outcomeMatch || !outcomeMatch[1].trim()) {
+      warnings.push(`${fileName}: Outcome Status field is empty or malformed`);
+    } else {
+      const outcome = outcomeMatch[1].trim();
+      if (!VALID_OUTCOMES.includes(outcome)) {
+        warnings.push(`${fileName}: Outcome Status should be one of: ${VALID_OUTCOMES.join(', ')}, got "${outcome}"`);
+      }
+    }
+
+    return { errors, warnings };
+  } catch (err) {
+    return {
+      errors: [`${fileName}: Failed to read or parse: ${err.message}`],
+      warnings: []
+    };
+  }
+}
+
+function validateJSONSession(filePath, fileName) {
+  const errors = [];
+  const warnings = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = JSON.parse(content);
+
+    // Check required fields
+    const requiredFields = ['date', 'agent', 'classification', 'goal', 'outcome'];
+    for (const field of requiredFields) {
+      if (!data[field]) {
+        errors.push(`${fileName}: Missing required field "${field}"`);
+      } else if (typeof data[field] === 'string' && !data[field].trim()) {
+        errors.push(`${fileName}: Required field "${field}" is empty`);
+      }
+    }
+
+    // Validate classification
+    if (data.classification && !VALID_CLASSIFICATIONS.includes(data.classification)) {
+      errors.push(`${fileName}: Invalid classification "${data.classification}". Must be one of: ${VALID_CLASSIFICATIONS.join(', ')}`);
+    }
+
+    // Validate outcome
+    if (data.outcome && !VALID_OUTCOMES.includes(data.outcome)) {
+      warnings.push(`${fileName}: Outcome should be one of: ${VALID_OUTCOMES.join(', ')}, got "${data.outcome}"`);
+    }
+
+    // Check actions
+    if (!data.actions || (Array.isArray(data.actions) && data.actions.length === 0)) {
+      errors.push(`${fileName}: Actions should be a non-empty array`);
+    }
+
+    return { errors, warnings };
+  } catch (err) {
+    return {
+      errors: [`${fileName}: Failed to parse JSON: ${err.message}`],
+      warnings: []
+    };
+  }
+}
+
+function runLintSessions(target) {
+  console.log(bold(`Linting session logs in: ${cyan(target)}\n`));
+
+  const sessionsDir = path.join(target, '.agent-room', 'sessions');
+
+  if (!fs.existsSync(sessionsDir)) {
+    console.log(yellow(`⚠️  No sessions directory found at ${sessionsDir}`));
+    return;
+  }
+
+  const files = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.md') || f.endsWith('.json'));
+
+  if (files.length === 0) {
+    console.log(yellow(`⚠️  No session logs found in ${sessionsDir}`));
+    return;
+  }
+
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  const results = [];
+
+  for (const file of files) {
+    const filePath = path.join(sessionsDir, file);
+    let result;
+
+    if (file.endsWith('.md')) {
+      result = validateMarkdownSession(filePath, file);
+    } else if (file.endsWith('.json')) {
+      result = validateJSONSession(filePath, file);
+    } else {
+      continue;
+    }
+
+    totalErrors += result.errors.length;
+    totalWarnings += result.warnings.length;
+
+    results.push({ file, ...result });
+  }
+
+  // Output results
+  let hasFailed = false;
+
+  for (const result of results) {
+    if (result.errors.length > 0 || result.warnings.length > 0) {
+      console.log(`${bold(result.file)}`);
+
+      if (result.errors.length > 0) {
+        hasFailed = true;
+        for (const err of result.errors) {
+          console.log(red(`  ❌ ${err}`));
+        }
+      }
+
+      if (result.warnings.length > 0) {
+        for (const warn of result.warnings) {
+          console.log(yellow(`  ⚠️  ${warn}`));
+        }
+      }
+
+      console.log('');
+    }
+  }
+
+  // Summary
+  console.log(bold('Summary:'));
+  console.log(`  Files scanned: ${files.length}`);
+  console.log(`  Errors: ${totalErrors}`);
+  console.log(`  Warnings: ${totalWarnings}`);
+
+  if (hasFailed) {
+    console.log('');
+    console.log(red('Linting FAILED: Some session logs have validation errors.'));
+    process.exitCode = 1;
+  } else if (totalWarnings > 0) {
+    console.log('');
+    console.log(bold(yellow('Linting PASSED with warnings.')));
+  } else {
+    console.log('');
+    console.log(bold(green('Linting PASSED! All session logs are valid.')));
+  }
+}
+
+module.exports = {
+  runLintSessions,
+  validateMarkdownSession,
+  validateJSONSession
+};

package/lib/metrics.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { green, yellow, red, cyan, bold } = require('./color');
+
+function countFiles(str) {
+  if (!str) return 0;
+  const clean = str.trim().replace(/\[|\]/g, '');
+  if (/^(none|blank|n\/a|list of.*|placeholder)$/i.test(clean)) return 0;
+  const items = clean.split(',').map((s) => s.trim()).filter(Boolean);
+  return items.length;
+}
+
+function parseFileList(val) {
+  if (Array.isArray(val)) return val.length;
+  if (typeof val === 'number') return val;
+  if (typeof val === 'string') return countFiles(val);
+  return 0;
+}
+
+function parseMarkdownSession(filePath, stats) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  stats.total++;
+
+  // Regex matches
+  const agentMatch = content.match(/\*\*Agent:\*\*\s*(.+)/i);
+  const classMatch = content.match(/\*\*Classification:\*\*\s*(.+)/i);
+
+  // Parse Outcome
+  let outcome = 'Handed Off';
+  const outcomeHeaderMatch = content.match(/## Outcome\s*\n+([^\n#\s]+[^\n#]*)/i);
+  if (outcomeHeaderMatch) {
+    const parsed = outcomeHeaderMatch[1].trim();
+    if (/completed/i.test(parsed)) outcome = 'Completed';
+    else if (/blocked/i.test(parsed)) outcome = 'Blocked';
+    else if (/handed/i.test(parsed)) outcome = 'Handed Off';
+  }
+  stats.outcomes[outcome]++;
+
+  if (classMatch) {
+    const val = classMatch[1].trim();
+    let matchedClass = null;
+    if (/bug/i.test(val)) matchedClass = 'Bug';
+    else if (/enhancement/i.test(val)) matchedClass = 'Enhancement';
+    else if (/feature/i.test(val)) matchedClass = 'Feature';
+    else if (/product/i.test(val)) matchedClass = 'Product';
+
+    if (matchedClass) {
+      stats.classifications[matchedClass]++;
+    }
+  }
+
+  if (agentMatch) {
+    const agent = agentMatch[1].trim().replace(/\[|\]/g, '');
+    stats.agents[agent] = (stats.agents[agent] || 0) + 1;
+  }
+
+  // Parse Files touched
+  const readMatch = content.match(/-\s*Read:\s*(.+)/i);
+  const createdMatch = content.match(/-\s*Created:\s*(.+)/i);
+  const modifiedMatch = content.match(/-\s*Modified:\s*(.+)/i);
+
+  if (readMatch) stats.filesRead += countFiles(readMatch[1]);
+  if (createdMatch) stats.filesCreated += countFiles(createdMatch[1]);
+  if (modifiedMatch) stats.filesModified += countFiles(modifiedMatch[1]);
+}
+
+function parseJSONSession(filePath, stats) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const data = JSON.parse(content);
+  stats.total++;
+
+  if (data.classification) {
+    const val = data.classification;
+    if (stats.classifications[val] !== undefined) {
+      stats.classifications[val]++;
+    }
+  }
+  if (data.outcome) {
+    let outcome = 'Handed Off';
+    if (/completed/i.test(data.outcome)) outcome = 'Completed';
+    else if (/blocked/i.test(data.outcome)) outcome = 'Blocked';
+    stats.outcomes[outcome]++;
+  } else {
+    stats.outcomes['Handed Off']++;
+  }
+  if (data.agent) {
+    stats.agents[data.agent] = (stats.agents[data.agent] || 0) + 1;
+  }
+  if (data.filesTouched) {
+    if (data.filesTouched.read) stats.filesRead += parseFileList(data.filesTouched.read);
+    if (data.filesTouched.created) stats.filesCreated += parseFileList(data.filesTouched.created);
+    if (data.filesTouched.modified) stats.filesModified += parseFileList(data.filesTouched.modified);
+  }
+}
+
+function printDashboard(stats) {
+  const t = stats.total;
+  const pct = (val) => (t > 0 ? ((val / t) * 100).toFixed(1) : '0.0');
+
+  const bar = (val) => {
+    if (t === 0) return '[                    ]';
+    const fillCount = Math.round((val / t) * 20);
+    const fill = '='.repeat(Math.max(0, fillCount - 1)) + (fillCount > 0 ? '>' : '');
+    const empty = ' '.repeat(20 - fillCount);
+    return `[${fill}${empty}]`;
+  };
+
+  console.log(bold('======================================================'));
+  console.log(bold('              Agent Session Dashboard'));
+  console.log(bold('======================================================'));
+  console.log(`Total Sessions Logged: ${cyan(t)}\n`);
+
+  console.log(bold('--- Outcomes Success Rate ---'));
+  console.log(`Completed:  ${green(bar(stats.outcomes.Completed))} ${pct(stats.outcomes.Completed)}% (${stats.outcomes.Completed})`);
+  console.log(`Blocked:    ${red(bar(stats.outcomes.Blocked))} ${pct(stats.outcomes.Blocked)}% (${stats.outcomes.Blocked})`);
+  console.log(`Handed Off: ${yellow(bar(stats.outcomes['Handed Off']))} ${pct(stats.outcomes['Handed Off'])}% (${stats.outcomes['Handed Off']})\n`);
+
+  console.log(bold('--- Classification Distribution ---'));
+  console.log(`Bug:         ${stats.classifications.Bug} (${pct(stats.classifications.Bug)}%)`);
+  console.log(`Enhancement: ${stats.classifications.Enhancement} (${pct(stats.classifications.Enhancement)}%)`);
+  console.log(`Feature:     ${stats.classifications.Feature} (${pct(stats.classifications.Feature)}%)`);
+  console.log(`Product:     ${stats.classifications.Product} (${pct(stats.classifications.Product)}%)\n`);
+
+  console.log(bold('--- Agent Breakdown ---'));
+  const agentsSorted = Object.entries(stats.agents).sort((a, b) => b[1] - a[1]);
+  if (agentsSorted.length === 0) {
+    console.log('No agent information logged.');
+  } else {
+    for (const [agent, count] of agentsSorted) {
+      console.log(`- ${agent}: ${count} session(s)`);
+    }
+  }
+  console.log('');
+
+  console.log(bold('--- File Volumes ---'));
+  console.log(`Files Read:     ${stats.filesRead}`);
+  console.log(`Files Created:  ${stats.filesCreated}`);
+  console.log(`Files Modified: ${stats.filesModified}`);
+  console.log(bold('======================================================'));
+}
+
+function runMetrics(target) {
+  const sessionsDir = path.join(target, '.agent-room', 'sessions');
+  if (!fs.existsSync(sessionsDir) || !fs.statSync(sessionsDir).isDirectory()) {
+    console.log(yellow(`No sessions directory found at ${path.relative(process.cwd(), sessionsDir)}`));
+    console.log('Ensure agents have logged sessions under .agent-room/sessions/ first.');
+    return;
+  }
+
+  const files = fs.readdirSync(sessionsDir).filter(
+    (f) => (f.endsWith('.md') || f.endsWith('.json')) && f !== '.gitkeep'
+  );
+  if (files.length === 0) {
+    console.log(yellow('No session logs found.'));
+    return;
+  }
+
+  const stats = {
+    total: 0,
+    classifications: { Bug: 0, Enhancement: 0, Feature: 0, Product: 0 },
+    outcomes: { Completed: 0, Blocked: 0, 'Handed Off': 0 },
+    agents: {},
+    filesRead: 0,
+    filesCreated: 0,
+    filesModified: 0
+  };
+
+  for (const file of files) {
+    const fullPath = path.join(sessionsDir, file);
+    try {
+      if (file.endsWith('.json')) {
+        parseJSONSession(fullPath, stats);
+      } else {
+        parseMarkdownSession(fullPath, stats);
+      }
+    } catch (err) {
+      console.warn(yellow(`Warning: Failed to parse session log ${file}: ${err.message}`));
+    }
+  }
+
+  printDashboard(stats);
+}
+
+module.exports = {
+  runMetrics,
+  parseMarkdownSession,
+  parseJSONSession
+};

package/lib/pr.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { green, red } = require('./color');
+
+function getSection(content, headerName) {
+  const escapedHeader = headerName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+  const regex = new RegExp(`##\\s*${escapedHeader}\\s*\\r?\\n([\\s\\S]*?)(?:\\r?\\n##|$)`, 'i');
+  const match = content.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+function parseMarkdownSession(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+
+  const dateMatch = content.match(/\*\*Date:\*\*\s*(.+)/i);
+  const agentMatch = content.match(/\*\*Agent:\*\*\s*(.+)/i);
+  const classMatch = content.match(/\*\*Classification:\*\*\s*(.+)/i);
+
+  const goal = getSection(content, 'Goal');
+  const filesTouched = getSection(content, 'Files touched');
+  const actions = getSection(content, 'Actions taken');
+  const tests = getSection(content, 'Tests run');
+  const decisions = getSection(content, 'Decisions made');
+  const outcomeRaw = getSection(content, 'Outcome');
+
+  // Parse Handoff note specifically
+  const handoffRegex = /\*\*Handoff note[^:]*:\*\*\r?\n?([\s\S]*)/i;
+  const handoffMatch = content.match(handoffRegex);
+  const handoffNote = handoffMatch ? handoffMatch[1].trim() : '';
+
+  // Clean outcome of handoff note text
+  let outcome = outcomeRaw;
+  const handoffHeaderMatch = outcomeRaw.match(/\*\*Handoff note/i);
+  if (handoffHeaderMatch) {
+    outcome = outcomeRaw.slice(0, handoffHeaderMatch.index).trim();
+  }
+
+  return {
+    date: dateMatch ? dateMatch[1].trim() : 'N/A',
+    agent: agentMatch ? agentMatch[1].trim().replace(/\[|\]/g, '') : 'N/A',
+    classification: classMatch ? classMatch[1].trim() : 'N/A',
+    goal,
+    filesTouched,
+    actions,
+    tests,
+    decisions,
+    outcome: outcome || 'Completed',
+    handoffNote
+  };
+}
+
+function parseJSONSession(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const data = JSON.parse(content);
+
+  const formatFileList = (files) => {
+    if (Array.isArray(files)) return files.map((f) => `- ${f}`).join('\n');
+    if (typeof files === 'object' && files !== null) {
+      const parts = [];
+      if (files.read) parts.push(`- Read: ${Array.isArray(files.read) ? files.read.join(', ') : files.read}`);
+      if (files.created) parts.push(`- Created: ${Array.isArray(files.created) ? files.created.join(', ') : files.created}`);
+      if (files.modified) parts.push(`- Modified: ${Array.isArray(files.modified) ? files.modified.join(', ') : files.modified}`);
+      return parts.join('\n');
+    }
+    return String(files || '');
+  };
+
+  const formatActions = (actions) => {
+    if (Array.isArray(actions)) return actions.map((a, i) => `${i + 1}. ${a}`).join('\n');
+    return String(actions || '');
+  };
+
+  return {
+    date: data.date || 'N/A',
+    agent: data.agent || 'N/A',
+    classification: data.classification || 'N/A',
+    goal: data.goal || '',
+    filesTouched: formatFileList(data.filesTouched),
+    actions: formatActions(data.actions),
+    tests: data.testsRun ? `Command: ${data.testsRun.command || ''}\nResult: ${data.testsRun.result || ''}` : '',
+    decisions: Array.isArray(data.decisions) ? data.decisions.map((d) => `- ${d}`).join('\n') : String(data.decisions || ''),
+    outcome: data.outcome || 'Completed',
+    handoffNote: data.handoffNote || ''
+  };
+}
+
+function runPrDesc(target, args) {
+  const sessionsDir = path.join(target, '.agent-room', 'sessions');
+  if (!fs.existsSync(sessionsDir) || !fs.statSync(sessionsDir).isDirectory()) {
+    console.error(red(`Error: Sessions directory not found at ${sessionsDir}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const files = fs.readdirSync(sessionsDir).filter(
+    (f) => (f.endsWith('.md') || f.endsWith('.json')) && f !== '.gitkeep'
+  );
+  if (files.length === 0) {
+    console.error(red('Error: No session logs found.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Sort alphabetically to find the latest session log
+  files.sort();
+  const latestFile = files[files.length - 1];
+  const fullPath = path.join(sessionsDir, latestFile);
+
+  let session = null;
+  try {
+    if (latestFile.endsWith('.json')) {
+      session = parseJSONSession(fullPath);
+    } else {
+      session = parseMarkdownSession(fullPath);
+    }
+  } catch (err) {
+    console.error(red(`Error: Failed to parse session log ${latestFile}: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Generate PR Description Markdown
+  let prDesc = `# Pull Request Description
+
+## Overview
+* **Session Log Reference:** [${latestFile}](.agent-room/sessions/${latestFile})
+* **Date:** ${session.date}
+* **Agent:** ${session.agent}
+* **Classification:** ${session.classification}
+
+## Goal
+${session.goal || 'No goal documented.'}
+
+## Changes Implemented
+${session.filesTouched || 'No files touched documented.'}
+
+## Actions Taken
+${session.actions || 'No actions documented.'}
+
+## Verification & Testing
+${session.tests || 'No verification tests documented.'}
+
+## Decisions & Architecture Changes
+${session.decisions || 'No decisions documented.'}
+
+## Outcome & Next Steps
+* **Status:** ${session.outcome}
+`;
+
+  if (session.handoffNote) {
+    prDesc += `\n### Handoff Details\n${session.handoffNote}\n`;
+  }
+
+  // Print to stdout
+  console.log(prDesc);
+
+  // Optionally write to .agent-room/pr-description.md
+  if (args.write) {
+    const outputPath = path.join(target, '.agent-room', 'pr-description.md');
+    try {
+      fs.writeFileSync(outputPath, prDesc);
+      console.log(green(`\nSuccess: PR description written to ${outputPath}`));
+    } catch (err) {
+      console.error(red(`Error: Failed to write PR description to ${outputPath}: ${err.message}`));
+      process.exitCode = 1;
+    }
+  }
+}
+
+module.exports = {
+  runPrDesc,
+  parseMarkdownSession,
+  parseJSONSession
+};

package/lib/prompt.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const readline = require('readline');
+
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.on('SIGINT', () => {
+      rl.close();
+      console.log('\nScaffolding cancelled. Goodbye!');
+      process.exit(0);
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+module.exports = { ask };