brain-dev 0.1.0

package/bin/lib/commands/new-project.cjs

@@ -0,0 +1,885 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+const { writeRoadmap, parseRoadmap } = require('../roadmap.cjs');
+const { detectProject } = require('../detect.cjs');
+const { output, error, success } = require('../core.cjs');
+
+/**
+ * 6 research focus areas for new-project research phase.
+ */
+const RESEARCH_AREAS = [
+  { name: 'stack-researcher', file: 'stack.md', area: 'Technology Stack & Ecosystem', description: 'technology stack, frameworks, libraries, and ecosystem tools' },
+  { name: 'architecture-researcher', file: 'architecture.md', area: 'Architecture Patterns', description: 'architecture patterns, project structure, and design decisions' },
+  { name: 'pitfalls-researcher', file: 'pitfalls.md', area: 'Pitfalls & Anti-patterns', description: 'common pitfalls, anti-patterns, and mistakes to avoid' },
+  { name: 'security-researcher', file: 'security.md', area: 'Security & Compliance', description: 'security requirements, compliance needs, and vulnerability prevention' },
+  { name: 'competitive-researcher', file: 'competitive.md', area: 'Competitive Analysis', description: 'competitive landscape, similar products, and differentiation opportunities' },
+  { name: 'testing-researcher', file: 'testing.md', area: 'Testing Strategy', description: 'testing approach, coverage targets, and quality assurance strategy' }
+];
+
+/**
+ * Core vision-first questions for greenfield (new) projects.
+ * Each question includes AskUserQuestion-compatible options as guidance templates.
+ */
+const CORE_QUESTIONS = [
+  {
+    id: 'vision',
+    text: 'What are you building? Describe the core idea in 1-2 sentences.',
+    header: 'Project Type',
+    options: [
+      { label: 'Web Application', description: 'Full-stack web app with frontend and backend' },
+      { label: 'API / Backend Service', description: 'REST/GraphQL API or microservice' },
+      { label: 'CLI Tool', description: 'Command-line tool or developer utility' },
+      { label: 'Mobile App', description: 'iOS/Android or cross-platform mobile application' }
+    ]
+  },
+  {
+    id: 'users',
+    text: 'Who is it for? Who are the primary users?',
+    header: 'Target Users',
+    options: [
+      { label: 'Developers', description: 'Software engineers and technical users' },
+      { label: 'End Users', description: 'Non-technical consumers or business users' },
+      { label: 'Internal Team', description: 'Internal tools for your organization' },
+      { label: 'B2B Customers', description: 'Business clients and enterprise users' }
+    ]
+  },
+  {
+    id: 'features',
+    text: 'What must it do? List the 3-5 most critical features.',
+    header: 'Core Features',
+    multiSelect: true,
+    options: [
+      { label: 'Auth & Users', description: 'User registration, login, roles, permissions' },
+      { label: 'CRUD & Data', description: 'Create, read, update, delete operations with database' },
+      { label: 'Real-time', description: 'WebSocket, live updates, notifications' },
+      { label: 'Integrations', description: 'Third-party APIs, payment, email, etc.' }
+    ]
+  },
+  {
+    id: 'constraints',
+    text: 'Any constraints? (tech stack preferences, timeline, budget, existing codebase)',
+    header: 'Constraints',
+    options: [
+      { label: 'Existing Codebase', description: 'Adding to or extending an existing project' },
+      { label: 'Specific Stack', description: 'Must use a particular language/framework' },
+      { label: 'Tight Timeline', description: 'MVP or deadline-driven development' },
+      { label: 'No Constraints', description: 'Flexible on technology and timeline' }
+    ]
+  }
+];
+
+/**
+ * Build brownfield (existing project) questions dynamically from detection results.
+ * @param {object} detection - Detection result from detectProject()
+ * @returns {Array} AskUserQuestion-compatible question specs
+ */
+function buildBrownfieldQuestions(detection) {
+  const { stack, features, summary, workspace } = detection;
+
+  // Question 1: Vision/Goal - context-aware with workspace
+  let visionText = `I detected a ${summary}. What do you want to do?`;
+  if (workspace && workspace.siblings.length > 0) {
+    const sibNames = workspace.siblings.map(s => `${s.name} (${s.stack.framework || s.stack.language})`).join(', ');
+    visionText = `I detected a ${summary}. I also found ${workspace.siblings.length} related project(s): ${sibNames}. What do you want to do?`;
+  }
+
+  const visionQuestion = {
+    id: 'vision',
+    text: visionText,
+    header: 'Goal',
+    options: [
+      { label: 'Add New Feature', description: 'Build something new on top of the existing codebase' },
+      { label: 'Refactor / Improve', description: 'Improve architecture, performance, or code quality' },
+      { label: 'Fix & Stabilize', description: 'Fix bugs, add tests, improve reliability' },
+      { label: 'Scale & Optimize', description: 'Performance optimization, scaling, infrastructure' }
+    ]
+  };
+
+  // Question 2: Users - same as greenfield but context-aware text
+  const usersQuestion = {
+    id: 'users',
+    text: 'Who are the current or target users of this project?',
+    header: 'Target Users',
+    options: [
+      { label: 'Developers', description: 'Software engineers and technical users' },
+      { label: 'End Users', description: 'Non-technical consumers or business users' },
+      { label: 'Internal Team', description: 'Internal tools for your organization' },
+      { label: 'B2B Customers', description: 'Business clients and enterprise users' }
+    ]
+  };
+
+  // Question 3: Features/Priorities - dynamically built from detection
+  const featureOptions = [];
+  // Add detected features as "extend" options (max 2)
+  for (const feat of features.slice(0, 2)) {
+    featureOptions.push({ label: `Extend ${feat}`, description: `Build on existing ${feat} capability` });
+  }
+  // Fill remaining slots with generic options (total max 4)
+  const genericFeatureOpts = [
+    { label: 'New Feature', description: 'Something not yet in the codebase' },
+    { label: 'Testing & Quality', description: 'Improve test coverage and code quality' },
+    { label: 'Performance', description: 'Optimize speed, memory, or resource usage' },
+    { label: 'Documentation', description: 'Improve docs, README, API documentation' }
+  ];
+  for (const opt of genericFeatureOpts) {
+    if (featureOptions.length >= 4) break;
+    featureOptions.push(opt);
+  }
+
+  const featuresText = features.length > 0
+    ? `I found these capabilities: ${features.join(', ')}. What's the next priority?`
+    : 'What are the most important features or improvements?';
+
+  const featuresQuestion = {
+    id: 'features',
+    text: featuresText,
+    header: 'Priorities',
+    multiSelect: true,
+    options: featureOptions
+  };
+
+  // Question 4: Constraints - stack-aware (use primary stack)
+  const primary = stack.primary || stack;
+  const stackLabel = primary.framework || (primary.language ? primary.language.charAt(0).toUpperCase() + primary.language.slice(1) : 'current stack');
+  const constraintsText = primary.framework
+    ? `The project uses ${primary.framework}${primary.language ? ` (${primary.language})` : ''}. Any additional constraints?`
+    : 'Any constraints? (timeline, budget, compatibility)';
+
+  const constraintsQuestion = {
+    id: 'constraints',
+    text: constraintsText,
+    header: 'Constraints',
+    options: [
+      { label: `Keep ${stackLabel}`, description: 'Stay within the existing technology choices' },
+      { label: 'Allow Migration', description: 'Open to changing frameworks or libraries' },
+      { label: 'Tight Timeline', description: 'MVP or deadline-driven development' },
+      { label: 'No Constraints', description: 'Flexible on approach' }
+    ]
+  };
+
+  return [visionQuestion, usersQuestion, featuresQuestion, constraintsQuestion];
+}
+
+/**
+ * Run the new-project command.
+ * Multi-step flow driven by flags:
+ *   (no flags)         -> Step 1: Detect project + output questions
+ *   --answers <json>   -> Step 2: Parse answers, spawn researchers (+ mappers for brownfield)
+ *   --synthesize       -> Step 3: Spawn synthesis agent
+ *   --generate-roadmap -> Step 4: Generate REQUIREMENTS.md + ROADMAP.md
+ *   --finalize         -> Step 5: Finalize, update state
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir override for testing, rootDir for testing)
+ * @returns {object} Structured result for Claude to act on
+ */
+function run(args = [], opts = {}) {
+  const brainDir = (opts && opts.brainDir) || path.join(process.cwd(), '.brain');
+  const rootDir = (opts && opts.rootDir) || process.cwd();
+
+  // Parse flags
+  const answersIdx = args.indexOf('--answers');
+  const hasSynthesize = args.includes('--synthesize');
+  const hasGenerateRoadmap = args.includes('--generate-roadmap');
+  const hasFinalize = args.includes('--finalize');
+
+  if (hasFinalize) {
+    return stepFinalize(args, brainDir);
+  }
+  if (hasGenerateRoadmap) {
+    return stepGenerateRoadmap(brainDir);
+  }
+  if (hasSynthesize) {
+    return stepSynthesize(brainDir);
+  }
+  if (answersIdx >= 0) {
+    const answersJson = args[answersIdx + 1];
+    if (!answersJson) {
+      error('--answers requires a JSON argument. Usage: brain-dev new-project --answers \'{"vision":"..."}\'');
+      return { action: 'error', error: 'missing-argument' };
+    }
+    return stepResearch(answersJson, brainDir);
+  }
+
+  // Default: Step 1 - Detect + Questions
+  return stepQuestions(brainDir, rootDir);
+}
+
+/**
+ * Step 1: Detect project type, output appropriate questions.
+ * Greenfield: generic vision-first questions.
+ * Brownfield: codebase-aware context questions.
+ */
+function stepQuestions(brainDir, rootDir) {
+  // Check project not already initialized
+  const state = readState(brainDir);
+  if (state && state.project && state.project.initialized === true) {
+    return {
+      action: 'error',
+      message: 'Project already initialized. Use /brain:discuss to refine.'
+    };
+  }
+
+  // Detect project type
+  const detection = detectProject(rootDir);
+
+  // Persist detection for later steps
+  fs.mkdirSync(brainDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(brainDir, 'detection.json'),
+    JSON.stringify(detection, null, 2),
+    'utf8'
+  );
+
+  // Build questions based on detection
+  const isBrownfield = detection.type === 'brownfield';
+  const questions = isBrownfield
+    ? buildBrownfieldQuestions(detection)
+    : CORE_QUESTIONS;
+
+  // Build AskUserQuestion-compatible question specs
+  const askQuestions = questions.map(q => ({
+    question: q.text,
+    header: q.header,
+    multiSelect: q.multiSelect || false,
+    options: q.options
+  }));
+
+  const detectionLine = isBrownfield
+    ? `[brain] Detected existing project: ${detection.summary}`
+    : '[brain] No existing code detected — starting fresh';
+
+  const humanText = [
+    '[brain] New project setup - Step 1: Gathering your vision',
+    detectionLine,
+    '',
+    'IMPORTANT: Use the AskUserQuestion tool to ask these questions.',
+    'Do NOT ask as freetext. Use the structured questions below.',
+    'The user can select predefined options OR type custom answers via "Other".',
+    '',
+    'Ask ALL 4 questions in a SINGLE AskUserQuestion call (it supports 1-4 questions):',
+    ''
+  ];
+
+  for (const q of questions) {
+    humanText.push(`  ${q.id} [${q.header}]: ${q.text}`);
+  }
+
+  humanText.push('');
+  humanText.push('After collecting answers, run:');
+  humanText.push('brain-dev new-project --answers \'{"vision":"...","users":"...","features":"...","constraints":"..."}\'');
+
+  const result = {
+    action: 'ask-questions',
+    projectType: detection.type,
+    detection,
+    questions: askQuestions,
+    tool: 'AskUserQuestion',
+    instruction: 'Use AskUserQuestion tool with the questions array above. Do NOT ask as freetext.'
+  };
+
+  output(result, humanText.join('\n'));
+  return result;
+}
+
+/**
+ * Step 2: Parse user answers, create PROJECT.md draft, output researcher spawn instructions.
+ * For brownfield projects, also spawns mapper agents and injects codebase context.
+ */
+function stepResearch(answersJson, brainDir) {
+  let answers;
+  try {
+    answers = JSON.parse(answersJson);
+  } catch (e) {
+    return { action: 'error', message: 'Invalid JSON for --answers: ' + e.message };
+  }
+  if (!answers || typeof answers !== 'object') {
+    return { action: 'error', message: '--answers requires a JSON object, not null/primitive' };
+  }
+
+  // Read detection results
+  const detection = readDetection(brainDir);
+  const isBrownfield = detection && detection.type === 'brownfield';
+
+  // Create research directory
+  const researchDir = path.join(brainDir, 'research');
+  fs.mkdirSync(researchDir, { recursive: true });
+
+  // Write PROJECT.md draft
+  const projectMd = isBrownfield
+    ? generateProjectMd(answers, detection)
+    : generateProjectMd(answers);
+  fs.writeFileSync(path.join(brainDir, 'PROJECT.md'), projectMd, 'utf8');
+
+  // Build codebase context for brownfield researcher prompts
+  const codebaseContext = isBrownfield
+    ? buildCodebaseContext(detection)
+    : '';
+
+  // Generate researcher prompts
+  const researcherTemplate = loadTemplate('researcher');
+  const agents = RESEARCH_AREAS.map(area => {
+    const prompt = interpolate(researcherTemplate, {
+      focus_area: area.area,
+      project_description: answers.vision || 'TBD',
+      target_users: answers.users || 'TBD',
+      key_features: answers.features || 'TBD',
+      constraints: answers.constraints || 'None',
+      focus_area_description: area.description,
+      output_path: path.join(researchDir, area.file),
+      codebase_context: codebaseContext
+    });
+
+    return {
+      name: area.name,
+      file: area.file,
+      outputPath: path.join(researchDir, area.file),
+      prompt
+    };
+  });
+
+  // Build mapper agents for brownfield
+  let mapperAgents = [];
+  if (isBrownfield) {
+    const codebaseDir = path.join(brainDir, 'codebase');
+    fs.mkdirSync(codebaseDir, { recursive: true });
+
+    try {
+      const mapperTemplate = loadTemplate('mapper');
+      const mapperFoci = ['tech', 'arch'];
+
+      mapperAgents = mapperFoci.map(focus => {
+        const prompt = interpolate(mapperTemplate, {
+          focus,
+          codebase_root: path.dirname(brainDir),
+          output_dir: codebaseDir
+        });
+        return { focus, prompt, output_dir: codebaseDir };
+      });
+    } catch {
+      // Mapper template may not exist; continue without mappers
+    }
+  }
+
+  // Build output
+  const humanText = [
+    '[brain] New project setup - Step 2: Research',
+    ''
+  ];
+
+  if (isBrownfield && mapperAgents.length > 0) {
+    humanText.push(`[brain] Brownfield project detected. Spawning ${mapperAgents.length} mapper agents + ${agents.length} research agents in parallel.`);
+    humanText.push('');
+    humanText.push('Mapper agents (subagent_type: "brain-mapper"):');
+    for (const ma of mapperAgents) {
+      humanText.push(`  - mapper-${ma.focus} -> .brain/codebase/`);
+    }
+    humanText.push('');
+  }
+
+  humanText.push('PROJECT.md draft created. Now spawn research agents in parallel.');
+  humanText.push('IMPORTANT: Use the Agent tool to spawn each agent. Do NOT do the research yourself.');
+  humanText.push('');
+  for (const agent of agents) {
+    humanText.push(`  - ${agent.name} -> ${agent.file}`);
+  }
+  humanText.push('');
+  humanText.push('Use the Agent tool (subagent_type: "brain-researcher") to spawn all 6 in parallel.');
+  if (isBrownfield && mapperAgents.length > 0) {
+    humanText.push('Use the Agent tool (subagent_type: "brain-mapper") to spawn mapper agents in parallel alongside researchers.');
+  }
+  humanText.push('IMPORTANT: Use subagent_type "brain-researcher" for research agents, "brain-mapper" for mapper agents.');
+  humanText.push('After all complete, run: npx brain-dev new-project --synthesize');
+
+  const action = isBrownfield && mapperAgents.length > 0
+    ? 'spawn-mapper-and-researchers'
+    : 'spawn-researchers';
+
+  const result = { action, agents };
+  if (mapperAgents.length > 0) {
+    result.mapperAgents = mapperAgents;
+  }
+
+  output(result, humanText.join('\n'));
+  return result;
+}
+
+/**
+ * Step 3: Output synthesis agent spawn instructions.
+ * For brownfield projects, includes codebase analysis in synthesis prompt.
+ */
+function stepSynthesize(brainDir) {
+  const researchDir = path.join(brainDir, 'research');
+  const outputPath = path.join(researchDir, 'SUMMARY.md');
+
+  const synthesisTemplate = loadTemplate('synthesis');
+
+  // Check for brownfield codebase analysis
+  const detection = readDetection(brainDir);
+  const isBrownfield = detection && detection.type === 'brownfield';
+  const codebaseDir = path.join(brainDir, 'codebase');
+  const hasCodebaseAnalysis = isBrownfield && fs.existsSync(codebaseDir);
+
+  let codebaseInstructions = '';
+  if (hasCodebaseAnalysis) {
+    codebaseInstructions = [
+      '',
+      'Also read codebase analysis from ' + codebaseDir + '/:',
+      '- STACK.md (detected technology stack)',
+      '- ARCHITECTURE.md (detected architecture patterns)',
+      '',
+      'Incorporate existing codebase context into your synthesis.',
+      'Focus recommendations on what to ADD or CHANGE, not what to build from scratch.'
+    ].join('\n');
+  }
+
+  const prompt = interpolate(synthesisTemplate, {
+    research_dir: researchDir,
+    output_path: outputPath
+  }) + codebaseInstructions;
+
+  const humanText = [
+    '[brain] New project setup - Step 3: Synthesis',
+    '',
+    'IMPORTANT: Use the Agent tool to spawn a synthesis agent. Do NOT synthesize manually.',
+    'Use subagent_type: "brain-synthesizer" with the prompt below.',
+    '',
+    'After the agent completes, run: npx brain-dev new-project --generate-roadmap',
+    hasCodebaseAnalysis ? '[brain] Codebase analysis from .brain/codebase/ will be included in synthesis.' : ''
+  ].filter(Boolean);
+
+  output({
+    action: 'spawn-synthesis',
+    prompt,
+    outputPath
+  }, humanText.join('\n'));
+
+  return {
+    action: 'spawn-synthesis',
+    prompt,
+    outputPath
+  };
+}
+
+/**
+ * Step 4: Generate REQUIREMENTS.md with hierarchical IDs and proposed ROADMAP.md.
+ */
+function stepGenerateRoadmap(brainDir) {
+  // Read PROJECT.md and research SUMMARY.md
+  const projectMdPath = path.join(brainDir, 'PROJECT.md');
+  const summaryPath = path.join(brainDir, 'research', 'SUMMARY.md');
+
+  let projectContent = '';
+  let summaryContent = '';
+
+  if (fs.existsSync(projectMdPath)) {
+    projectContent = fs.readFileSync(projectMdPath, 'utf8');
+  }
+  if (fs.existsSync(summaryPath)) {
+    summaryContent = fs.readFileSync(summaryPath, 'utf8');
+  }
+
+  // Extract features from PROJECT.md
+  const features = extractFeatures(projectContent);
+  const constraints = extractSection(projectContent, 'Constraints');
+
+  // Generate REQUIREMENTS.md with hierarchical IDs
+  const { requirementsMd, categories } = generateRequirementsMd(features, summaryContent);
+  fs.writeFileSync(path.join(brainDir, 'REQUIREMENTS.md'), requirementsMd, 'utf8');
+
+  // Generate proposed roadmap phases from requirement categories
+  const phases = categories.map((cat, i) => ({
+    number: i + 1,
+    name: cat.name,
+    goal: cat.goal,
+    dependsOn: i === 0 ? [] : [i],
+    requirements: cat.reqIds,
+    plans: '',
+    status: 'Pending'
+  }));
+
+  // Write proposed ROADMAP.md
+  const roadmapData = {
+    overview: extractSection(projectContent, 'Vision') || 'Project roadmap',
+    phases
+  };
+  writeRoadmap(brainDir, roadmapData);
+
+  const humanText = [
+    '[brain] New project setup - Step 4: Roadmap proposal',
+    '',
+    'REQUIREMENTS.md and ROADMAP.md created.',
+    '',
+    "Here's the proposed roadmap. Present it to the user and ask:",
+    '"Modify or confirm this roadmap?"',
+    '',
+    'After confirmed, run: brain-dev new-project --finalize --project-name "ProjectName"'
+  ];
+
+  output({
+    action: 'confirm-roadmap',
+    phases,
+    requirementsPath: path.join(brainDir, 'REQUIREMENTS.md'),
+    roadmapPath: path.join(brainDir, 'ROADMAP.md')
+  }, humanText.join('\n'));
+
+  return {
+    action: 'confirm-roadmap',
+    phases,
+    requirementsPath: path.join(brainDir, 'REQUIREMENTS.md'),
+    roadmapPath: path.join(brainDir, 'ROADMAP.md')
+  };
+}
+
+/**
+ * Step 5: Finalize - write final artifacts, update brain.json, commit.
+ */
+function stepFinalize(args, brainDir) {
+  // Get project name
+  const nameIdx = args.indexOf('--project-name');
+  const projectName = (nameIdx >= 0 && args[nameIdx + 1]) ? args[nameIdx + 1] : 'Untitled Project';
+
+  // Read current state
+  const state = readState(brainDir);
+  if (!state) {
+    return { action: 'error', message: 'No brain.json found. Run brain-dev init first.' };
+  }
+
+  // Read roadmap to get phase info
+  let phaseCount = 0;
+  let phaseData = [];
+  try {
+    const roadmap = parseRoadmap(brainDir);
+    phaseCount = roadmap.phases.length;
+    phaseData = roadmap.phases.map(p => ({
+      id: p.number,
+      number: p.number,
+      name: p.name,
+      status: p.status || 'Pending',
+      goal: p.goal || ''
+    }));
+  } catch {
+    // Roadmap may not exist yet; that's okay
+  }
+
+  // Read detection for projectType
+  const detection = readDetection(brainDir);
+
+  // Update state
+  state.project.name = projectName;
+  state.project.initialized = true;
+  state.project.description = extractProjectDescription(brainDir);
+  state.project.projectType = detection ? detection.type : 'greenfield';
+  state.phase.current = phaseCount > 0 ? 1 : 0;
+  state.phase.status = phaseCount > 0 ? 'pending' : 'initialized';
+  state.phase.total = phaseCount;
+  state.phase.phases = phaseData;
+  state.milestone.current = 'v1.0';
+
+  // Write updated state
+  writeState(brainDir, state);
+
+  const humanText = [
+    '[brain] New project setup - Complete!',
+    '',
+    `Project "${projectName}" initialized with ${phaseCount} phases.`,
+    detection ? `Project type: ${detection.type}` : '',
+    '',
+    'Created:',
+    '  - PROJECT.md (project vision and context)',
+    '  - REQUIREMENTS.md (hierarchical requirements)',
+    '  - ROADMAP.md (development phases)',
+    '  - brain.json (updated state)',
+    '',
+    'Run /brain:discuss to refine the first phase, or /brain:plan to start planning.'
+  ].filter(Boolean);
+
+  output({
+    action: 'finalized',
+    projectName,
+    phases: phaseCount,
+    projectType: detection ? detection.type : 'greenfield',
+    files: ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'brain.json'],
+    nextAction: '/brain:discuss'
+  }, humanText.join('\n'));
+
+  return {
+    action: 'finalized',
+    projectName,
+    phases: phaseCount,
+    projectType: detection ? detection.type : 'greenfield',
+    files: ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'brain.json'],
+    nextAction: '/brain:discuss'
+  };
+}
+
+// ---- Helper functions ----
+
+/**
+ * Read detection.json from .brain/ directory.
+ * @param {string} brainDir
+ * @returns {object|null}
+ */
+function readDetection(brainDir) {
+  try {
+    const detPath = path.join(brainDir, 'detection.json');
+    if (!fs.statSync(detPath).isFile()) return null;
+    const content = fs.readFileSync(detPath, 'utf8');
+    const data = JSON.parse(content);
+    if (!data || typeof data !== 'object' || !data.type) return null;
+    // Ensure stack.primary exists for safe access
+    if (data.stack && !data.stack.primary) {
+      data.stack.primary = { language: data.stack.language || null, framework: data.stack.framework || null, runtime: data.stack.runtime || null, dependencies: data.stack.dependencies || [] };
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build codebase context string for brownfield researcher prompts.
+ * @param {object} detection
+ * @returns {string}
+ */
+function buildCodebaseContext(detection) {
+  const { stack, features, signals, workspace } = detection;
+  const primary = stack.primary || stack;
+  const lines = [
+    '',
+    '## Existing Codebase Context',
+    '',
+    'This is NOT a greenfield project. An existing codebase was detected:',
+  ];
+
+  if (primary.framework) {
+    lines.push(`- **Primary Stack:** ${primary.framework}${primary.language ? ` (${primary.language})` : ''}`);
+  } else if (primary.language) {
+    lines.push(`- **Language:** ${primary.language}`);
+  }
+
+  // Frontend stack (when separate from primary, e.g., Laravel + Vue.js)
+  if (stack.frontend) {
+    const feParts = [stack.frontend.framework, stack.frontend.bundler, stack.frontend.css].filter(Boolean).join(' + ');
+    if (feParts) {
+      lines.push(`- **Frontend:** ${feParts}`);
+    }
+  }
+
+  if (features.length > 0) {
+    lines.push(`- **Existing features:** ${features.join(', ')}`);
+  }
+
+  if (signals.codeFiles > 0) {
+    lines.push(`- **Size:** ${signals.codeFiles} source files`);
+  }
+
+  if (signals.commitCount > 0) {
+    lines.push(`- **History:** ${signals.commitCount} commits`);
+  }
+
+  const deps = primary.dependencies || [];
+  if (deps.length > 0) {
+    lines.push(`- **Key dependencies:** ${deps.slice(0, 5).join(', ')}`);
+  }
+
+  // Workspace siblings
+  if (workspace && workspace.siblings.length > 0) {
+    lines.push('');
+    lines.push('### Related Projects in Workspace');
+    for (const sib of workspace.siblings) {
+      lines.push(`- **${sib.name}:** ${sib.stack.framework || sib.stack.language}`);
+    }
+    lines.push('');
+    lines.push('Consider how this project integrates with sibling projects.');
+  }
+
+  lines.push('');
+  lines.push('**IMPORTANT:** Research should focus on EXTENDING/IMPROVING this existing codebase, not starting from scratch.');
+  lines.push('Consider compatibility with the existing stack and patterns.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate PROJECT.md from user answers, marking unknowns as TBD.
+ * Optionally includes existing codebase section for brownfield projects.
+ * @param {object} answers
+ * @param {object} [detection] - Detection result for brownfield projects
+ */
+function generateProjectMd(answers, detection) {
+  const tbd = (val) => {
+    if (!val) return 'TBD';
+    if (Array.isArray(val)) return val.join(', ') || 'TBD';
+    if (typeof val !== 'string') return String(val);
+    const lower = val.toLowerCase().trim();
+    if (lower === "i don't know yet" || lower === 'idk' || lower === 'not sure' || lower === 'tbd') {
+      return 'TBD';
+    }
+    return val;
+  };
+
+  const lines = [
+    '# Project',
+    '',
+    '## Vision',
+    tbd(answers.vision),
+    '',
+    '## Users',
+    tbd(answers.users),
+    '',
+    '## Features',
+    tbd(answers.features),
+    '',
+    '## Constraints',
+    tbd(answers.constraints),
+    ''
+  ];
+
+  // Add existing codebase section for brownfield projects
+  if (detection && detection.type === 'brownfield') {
+    const primary = detection.stack.primary || detection.stack;
+    lines.push('## Existing Codebase');
+    if (primary.framework) {
+      lines.push(`- **Stack:** ${primary.framework}${primary.language ? ` (${primary.language})` : ''}`);
+    } else if (primary.language) {
+      lines.push(`- **Language:** ${primary.language}`);
+    }
+    if (detection.stack.frontend) {
+      const feParts = [detection.stack.frontend.framework, detection.stack.frontend.bundler, detection.stack.frontend.css].filter(Boolean).join(' + ');
+      if (feParts) lines.push(`- **Frontend:** ${feParts}`);
+    }
+    if (detection.features.length > 0) {
+      lines.push(`- **Features:** ${detection.features.join(', ')}`);
+    }
+    if (detection.signals.codeFiles > 0) {
+      lines.push(`- **Size:** ${detection.signals.codeFiles} source files`);
+    }
+    if (detection.signals.commitCount > 0) {
+      lines.push(`- **Commits:** ${detection.signals.commitCount}`);
+    }
+    lines.push(`- **Status:** Active development`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Extract features list from PROJECT.md content.
+ */
+function extractFeatures(content) {
+  const featSection = extractSection(content, 'Features');
+  if (!featSection) return [];
+
+  // Split by lines starting with - or numbered items
+  return featSection
+    .split('\n')
+    .map(l => l.replace(/^[-*\d.)\s]+/, '').trim())
+    .filter(l => l.length > 0);
+}
+
+/**
+ * Extract a markdown section's content by heading name.
+ */
+function extractSection(content, heading) {
+  const regex = new RegExp(`## ${heading}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const match = content.match(regex);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Generate REQUIREMENTS.md with hierarchical IDs grouped by category.
+ */
+function generateRequirementsMd(features, summaryContent) {
+  // Create categories from features and summary
+  const categories = [];
+
+  // Category 1: Core features (from user's feature list)
+  if (features.length > 0) {
+    const reqIds = features.map((_, i) => `1.${i + 1}`);
+    categories.push({
+      name: 'Core Features',
+      goal: 'Implement the primary functionality',
+      reqIds,
+      items: features.map((f, i) => ({ id: `1.${i + 1}`, text: f }))
+    });
+  }
+
+  // Category 2: Infrastructure (from research summary)
+  const infraItems = [];
+  if (summaryContent.includes('Stack') || summaryContent.includes('stack')) {
+    infraItems.push({ id: '2.1', text: 'Setup recommended technology stack' });
+  }
+  if (summaryContent.includes('Architecture') || summaryContent.includes('architecture')) {
+    infraItems.push({ id: '2.2', text: 'Implement recommended architecture patterns' });
+  }
+  if (infraItems.length > 0) {
+    categories.push({
+      name: 'Infrastructure',
+      goal: 'Setup project infrastructure and architecture',
+      reqIds: infraItems.map(i => i.id),
+      items: infraItems
+    });
+  }
+
+  // Category 3: Quality (testing + security from summary)
+  const qualityItems = [];
+  if (summaryContent.includes('Testing') || summaryContent.includes('testing')) {
+    qualityItems.push({ id: '3.1', text: 'Implement testing strategy' });
+  }
+  if (summaryContent.includes('Security') || summaryContent.includes('security')) {
+    qualityItems.push({ id: '3.2', text: 'Implement security requirements' });
+  }
+  if (qualityItems.length > 0) {
+    categories.push({
+      name: 'Quality & Security',
+      goal: 'Ensure quality and security standards',
+      reqIds: qualityItems.map(i => i.id),
+      items: qualityItems
+    });
+  }
+
+  // Fallback: if no categories created, make a default one
+  if (categories.length === 0) {
+    categories.push({
+      name: 'Setup',
+      goal: 'Initialize the project',
+      reqIds: ['1.1'],
+      items: [{ id: '1.1', text: 'Project initialization' }]
+    });
+  }
+
+  // Generate markdown
+  const lines = ['# Requirements', ''];
+
+  for (const cat of categories) {
+    lines.push(`## ${cat.name}`);
+    lines.push('');
+    for (const item of cat.items) {
+      lines.push(`- **${item.id}** ${item.text}`);
+    }
+    lines.push('');
+  }
+
+  return { requirementsMd: lines.join('\n'), categories };
+}
+
+/**
+ * Extract a short project description from PROJECT.md.
+ */
+function extractProjectDescription(brainDir) {
+  try {
+    const content = fs.readFileSync(path.join(brainDir, 'PROJECT.md'), 'utf8');
+    return extractSection(content, 'Vision') || '';
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { run, buildBrownfieldQuestions };