popeye-cli 1.5.0 → 1.6.0

package/src/workflow/auto-fix-bundler.ts

@@ -0,0 +1,392 @@
+/**
+ * Bundler error parser and fixer for non-TypeScript build errors.
+ * Handles CSS/PostCSS/Tailwind, webpack module resolution, and generic bundler errors.
+ * Used as a fallback when parseTypeScriptErrors() returns empty but the build failed.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { executePrompt } from '../adapters/claude.js';
+import type { AutoFixResult, BuildError } from './auto-fix.js';
+
+/** Bundler-specific error with type classification */
+export interface BundlerError extends BuildError {
+  type: 'css' | 'module-not-found' | 'syntax' | 'generic';
+}
+
+/** Config files that often need modification to fix CSS/bundler errors */
+const RELATED_CONFIG_FILES = [
+  'tailwind.config.ts',
+  'tailwind.config.js',
+  'postcss.config.js',
+  'postcss.config.mjs',
+  'next.config.js',
+  'next.config.mjs',
+  'next.config.ts',
+  'vite.config.ts',
+  'vite.config.js',
+  'tsconfig.json',
+  'package.json',
+];
+
+/**
+ * Parse non-TypeScript build errors from bundler output.
+ * Catches CSS/PostCSS/Tailwind errors, module-not-found, and generic syntax errors.
+ */
+export function parseBundlerErrors(output: string): BundlerError[] {
+  const errors: BundlerError[] = [];
+  const clean = output.replace(/\x1b\[[0-9;]*m/g, '');
+  const seen = new Set<string>();
+
+  // Pattern 1: CSS/PostCSS/Tailwind class not found
+  // "Syntax error: /abs/path/file.css The `className` class does not exist..."
+  const cssClassPattern = /Syntax error:\s*(\S+\.css)\s+(The [`'][\w-]+['`] class does not exist[^]*?)(?=\n\n|\n>|\nat\s|$)/gm;
+  let match;
+  while ((match = cssClassPattern.exec(clean)) !== null) {
+    const key = `css:${match[1]}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      errors.push({
+        file: match[1],
+        message: match[2].trim().split('\n')[0],
+        type: 'css',
+      });
+    }
+  }
+
+  // Pattern 2: File reference with line:col (bundler-style, non-TS)
+  // "./src/app/globals.css:1:1" followed by "Syntax error:" on next lines
+  const fileLinePattern = /^\.\/([\w/.@-]+\.(?:css|scss|less|json|mjs|cjs)):(\d+):(\d+)\s*$/gm;
+  while ((match = fileLinePattern.exec(clean)) !== null) {
+    const filePath = `./${match[1]}`;
+    const line = parseInt(match[2], 10);
+    const col = parseInt(match[3], 10);
+    // Grab up to 500 chars after match for context
+    const afterMatch = clean.slice(match.index + match[0].length, match.index + match[0].length + 500);
+    const errorLine = afterMatch.split('\n').find(l => l.trim().length > 10);
+    const key = `ref:${filePath}:${line}:${col}`;
+    if (!seen.has(key) && errorLine) {
+      seen.add(key);
+      errors.push({
+        file: filePath,
+        line,
+        column: col,
+        message: errorLine.trim(),
+        type: 'syntax',
+      });
+    }
+  }
+
+  // Pattern 3: Module not found
+  // "Module not found: Can't resolve 'package' in '/path'"
+  const modulePattern = /Module not found:\s*(?:Error:\s*)?Can't resolve '([^']+)'\s+in\s+'([^']+)'/gm;
+  while ((match = modulePattern.exec(clean)) !== null) {
+    const key = `module:${match[1]}:${match[2]}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      errors.push({
+        file: match[2],
+        message: `Cannot resolve module '${match[1]}'`,
+        type: 'module-not-found',
+      });
+    }
+  }
+
+  // Pattern 4: Generic "Build failed because of webpack errors" — extract file references
+  if (errors.length === 0 && /Build failed because of webpack errors/i.test(clean)) {
+    // Try to find Import trace lines: "./src/path/file.ext"
+    const importTracePattern = /^\.\/([\w/.@-]+\.\w+)\s*$/gm;
+    while ((match = importTracePattern.exec(clean)) !== null) {
+      const filePath = `./${match[1]}`;
+      const key = `trace:${filePath}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        errors.push({
+          file: filePath,
+          message: 'Referenced in build error import trace',
+          type: 'generic',
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Resolve the app directory from an error file path.
+ * E.g., "apps/website/src/foo.css" -> "<projectDir>/apps/website"
+ */
+function resolveAppDir(projectDir: string, errorFile: string): string {
+  const appsMatch = errorFile.match(/apps\/([^/]+)\//);
+  if (appsMatch) {
+    return path.join(projectDir, 'apps', appsMatch[1]);
+  }
+  return projectDir;
+}
+
+/**
+ * Find config files related to the error (tailwind.config, postcss.config, etc.)
+ * Searches both the app directory and project root.
+ */
+export async function findRelatedConfigs(
+  projectDir: string,
+  errorFile: string,
+): Promise<Array<{ path: string; content: string }>> {
+  const configs: Array<{ path: string; content: string }> = [];
+  const appDir = resolveAppDir(projectDir, errorFile);
+
+  // Search in both app dir and project root (deduped)
+  const searchDirs = [...new Set([appDir, projectDir])];
+
+  for (const dir of searchDirs) {
+    for (const configFile of RELATED_CONFIG_FILES) {
+      const configPath = path.join(dir, configFile);
+      try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        // Cap config file size to avoid token bloat
+        configs.push({ path: configPath, content: content.slice(0, 4000) });
+      } catch { /* not found */ }
+    }
+  }
+
+  return configs;
+}
+
+/**
+ * Resolve the absolute path of a bundler error file.
+ * Tries multiple locations: absolute, relative to app dir, relative to project root.
+ */
+async function resolveErrorFile(
+  projectDir: string,
+  errorFile: string,
+): Promise<{ resolvedPath: string; content: string } | null> {
+  const appDir = resolveAppDir(projectDir, errorFile);
+  const candidates = [
+    path.isAbsolute(errorFile) ? errorFile : null,
+    path.join(appDir, errorFile.replace(/^\.\//, '')),
+    path.join(projectDir, errorFile.replace(/^\.\//, '')),
+  ].filter(Boolean) as string[];
+
+  for (const p of candidates) {
+    try {
+      const content = await fs.readFile(p, 'utf-8');
+      return { resolvedPath: p, content };
+    } catch { /* continue */ }
+  }
+
+  return null;
+}
+
+/**
+ * Generate a fix prompt for bundler/CSS errors.
+ * Includes the error file, related config files, and instructions for multi-file fixes.
+ */
+function generateBundlerFixPrompt(
+  errorFile: string,
+  fileContent: string,
+  errors: BundlerError[],
+  configs: Array<{ path: string; content: string }>,
+  rawOutput: string,
+): string {
+  const errorList = errors.map(e => `- ${e.type}: ${e.message}`).join('\n');
+
+  const configSection = configs.length > 0
+    ? '\n\n## Related Configuration Files:\n' +
+      configs.map(c => `### ${c.path}\n\`\`\`\n${c.content}\n\`\`\``).join('\n\n')
+    : '';
+
+  // Include raw output snippet for full context (last 1500 chars)
+  const outputSnippet = rawOutput.slice(-1500);
+
+  return `Fix the following build error. This is a CSS/bundler/config error, NOT a TypeScript error.
+
+## Error File: ${errorFile}
+
+## Errors:
+${errorList}
+
+## Raw Build Output (last 1500 chars):
+\`\`\`
+${outputSnippet}
+\`\`\`
+
+## Error file content:
+\`\`\`
+${fileContent}
+\`\`\`${configSection}
+
+## Instructions:
+1. Analyze the error carefully — it may be a CSS, Tailwind, PostCSS, or webpack bundler error
+2. The fix might be in the error file OR in a configuration file (e.g., tailwind.config.ts)
+3. For Tailwind "class does not exist" errors: the fix is usually adding the class definition to tailwind.config.ts theme.extend.colors (e.g., background: 'hsl(var(--background))')
+4. For module-not-found: the fix is usually a missing dependency or wrong import path
+5. Return your response using this exact format for EACH file that needs changes:
+
+FILE: <absolute path to file>
+\`\`\`
+<complete fixed file content>
+\`\`\`
+
+If multiple files need changes, repeat the FILE: pattern for each.
+Return ONLY the files that need changes.`.trim();
+}
+
+/**
+ * Parse Claude's multi-file response format.
+ * Extracts "FILE: <path>\n```\n<content>\n```" blocks.
+ */
+export function parseMultiFileResponse(
+  response: string,
+): Array<{ targetPath: string; content: string }> {
+  const results: Array<{ targetPath: string; content: string }> = [];
+  const filePattern = /FILE:\s*(.+)\n```(?:\w*)\n([\s\S]*?)\n```/g;
+  let match;
+  while ((match = filePattern.exec(response)) !== null) {
+    const content = match[2].trim();
+    if (content.length > 20) {
+      results.push({ targetPath: match[1].trim(), content });
+    }
+  }
+  return results;
+}
+
+/**
+ * Resolve a target path from Claude's response to an actual writable file.
+ */
+async function resolveTargetPath(
+  targetPath: string,
+  projectDir: string,
+  appDir: string,
+  configs: Array<{ path: string; content: string }>,
+): Promise<string | null> {
+  const candidates = [
+    path.isAbsolute(targetPath) ? targetPath : null,
+    path.join(appDir, targetPath.replace(/^\.\//, '')),
+    path.join(projectDir, targetPath.replace(/^\.\//, '')),
+    // Match against known config paths by basename
+    ...configs.map(c => c.path).filter(p => p.endsWith(path.basename(targetPath))),
+  ].filter(Boolean) as string[];
+
+  for (const p of candidates) {
+    try {
+      await fs.access(p);
+      return p;
+    } catch { /* continue */ }
+  }
+  return null;
+}
+
+/**
+ * Fix bundler errors by sending them to Claude with full context.
+ * Handles CSS/Tailwind/PostCSS/webpack errors that parseTypeScriptErrors() can't parse.
+ */
+export async function fixBundlerErrors(
+  projectDir: string,
+  buildOutput: string,
+  errors: BundlerError[],
+  _language: string,
+  onProgress?: (message: string) => void,
+): Promise<AutoFixResult> {
+  const fixes: Array<{ file: string; description: string }> = [];
+
+  // Group errors by file
+  const errorsByFile = new Map<string, BundlerError[]>();
+  for (const error of errors) {
+    const existing = errorsByFile.get(error.file) || [];
+    existing.push(error);
+    errorsByFile.set(error.file, existing);
+  }
+
+  for (const [errorFile, fileErrors] of errorsByFile) {
+    onProgress?.(`Fixing ${fileErrors.length} bundler error(s) in ${path.basename(errorFile)}...`);
+
+    // Read the error file
+    const resolved = await resolveErrorFile(projectDir, errorFile);
+    if (!resolved) {
+      onProgress?.(`Cannot find ${errorFile}, skipping`);
+      continue;
+    }
+
+    // Find related config files
+    const configs = await findRelatedConfigs(projectDir, errorFile);
+
+    // Generate fix prompt
+    const prompt = generateBundlerFixPrompt(
+      errorFile, resolved.content, fileErrors, configs, buildOutput,
+    );
+
+    // Ask Claude to fix
+    const result = await executePrompt(prompt, {
+      allowedTools: [],
+      permissionMode: 'default',
+    });
+
+    if (!result.success || !result.response) {
+      onProgress?.(`Failed to get fix for ${path.basename(errorFile)}: ${result.error}`);
+      continue;
+    }
+
+    // Parse multi-file response
+    const fileChanges = parseMultiFileResponse(result.response);
+    const appDir = resolveAppDir(projectDir, errorFile);
+
+    for (const change of fileChanges) {
+      const resolvedTarget = await resolveTargetPath(
+        change.targetPath, projectDir, appDir, configs,
+      );
+
+      if (!resolvedTarget) {
+        onProgress?.(`Cannot resolve target path: ${change.targetPath}`);
+        continue;
+      }
+
+      await fs.writeFile(resolvedTarget, change.content, 'utf-8');
+      fixes.push({
+        file: resolvedTarget,
+        description: `Fixed bundler error: ${fileErrors[0].message.slice(0, 80)}`,
+      });
+      onProgress?.(`Fixed ${path.basename(resolvedTarget)}`);
+    }
+
+    // Fallback: if no FILE: pattern found, try single code-block extraction
+    if (fileChanges.length === 0) {
+      const singleBlock = result.response.match(/```(?:\w*)\n([\s\S]*?)\n```/);
+      if (singleBlock && singleBlock[1].length > 20) {
+        const content = singleBlock[1];
+        // Determine if this is a config fix or a direct file fix
+        let targetFile = resolved.resolvedPath;
+        if (
+          (content.includes('export default') || content.includes('module.exports')) &&
+          !resolved.resolvedPath.endsWith('.css')
+        ) {
+          const configMatch = configs.find(c =>
+            (content.includes('tailwind') && c.path.includes('tailwind')) ||
+            (content.includes('postcss') && c.path.includes('postcss')) ||
+            (content.includes('next') && c.path.includes('next.config')),
+          );
+          if (configMatch) targetFile = configMatch.path;
+        }
+
+        await fs.writeFile(targetFile, content, 'utf-8');
+        fixes.push({
+          file: targetFile,
+          description: `Fixed bundler error: ${fileErrors[0].message.slice(0, 80)}`,
+        });
+        onProgress?.(`Fixed ${path.basename(targetFile)}`);
+      }
+    }
+  }
+
+  return {
+    success: fixes.length > 0,
+    fixedErrors: fixes.length,
+    remainingErrors: 0,
+    attempts: 1,
+    fixes,
+    missingFileCount: 0,
+    totalErrorFiles: errorsByFile.size,
+    isStructuralIssue: false,
+    missingFiles: [],
+  };
+}

package/src/workflow/auto-fix.ts

@@ -7,6 +7,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { executePrompt } from '../adapters/claude.js';
 import { isWorkspace, type OutputLanguage } from '../types/project.js';
+import { parseBundlerErrors, fixBundlerErrors } from './auto-fix-bundler.js';
 
 /** Standard workspace subdirectories to search when a file isn't at the root */
 const WORKSPACE_SUBDIRS = ['apps/frontend', 'apps/backend', 'apps/website', 'packages/frontend', 'packages/backend'];
@@ -250,10 +251,17 @@ export async function autoFixTypeScriptErrors(
 
     if (errors.length === 0) {
       // First attempt with zero parsed errors and no prior fixes: the build failed
-      // but we can't parse the error format. This is NOT success.
+      // but we can't parse the error format. Try bundler error parser as fallback.
       const noParsedOnFirstAttempt = attempts === 1 && fixes.length === 0;
       if (noParsedOnFirstAttempt) {
-        onProgress?.('No parseable TypeScript errors in build output (may be bundler/non-TS errors)');
+        // Fallback: try parsing CSS/PostCSS/Tailwind/webpack bundler errors
+        const bundlerErrors = parseBundlerErrors(currentOutput);
+        if (bundlerErrors.length > 0) {
+          onProgress?.(`Found ${bundlerErrors.length} bundler/CSS error(s), attempting fix...`);
+          return fixBundlerErrors(projectDir, currentOutput, bundlerErrors, language, onProgress);
+        }
+
+        onProgress?.('No parseable errors in build output (not TS or bundler format)');
         return {
           success: false,
           fixedErrors: 0,
@@ -264,7 +272,7 @@ export async function autoFixTypeScriptErrors(
           totalErrorFiles: 0,
           isStructuralIssue: false,
           missingFiles: [],
-          error: 'Build failed but no parseable TypeScript errors found in output',
+          error: 'Build failed but no parseable errors found in output',
         };
       }
 

package/src/workflow/index.ts

@@ -41,6 +41,7 @@ export * from './ui-designer.js';
 export * from './ui-verification.js';
 export * from './project-verification.js';
 export * from './auto-fix.js';
+export * from './auto-fix-bundler.js';
 export * from './project-structure.js';
 // Note: plan-parser.js exports are accessible but have naming conflicts with plan-mode.js
 // Import directly from './plan-parser.js' if you need the extended TaskAppTag type (includes 'WEB')
@@ -269,6 +270,17 @@ export async function resumeWorkflow(
       }
 
       case 'execution': {
+        // Update website content before resuming execution
+        if (state.language === 'website' || state.language === 'all' || state.language === 'fullstack') {
+          try {
+            onProgress?.('website-update', 'Updating website with project context before execution resume...');
+            const { updateWebsiteContent } = await import('./website-updater.js');
+            await updateWebsiteContent(projectDir, state, state.language, (msg) => onProgress?.('website-update', msg));
+          } catch {
+            // Non-blocking: website content update failure should not stop workflow
+          }
+        }
+
         onProgress?.('workflow', 'Resuming Execution Mode...');
 
         const executionResult = await resumeExecutionMode({

package/src/workflow/overview.ts

@@ -279,6 +279,12 @@ function analyzeProject(
       'Project includes a website but was completed without any user documentation. Website likely has placeholder content.',
       'Run /overview fix to discover docs and update website template files');
   }
+  // Show strategy error if present
+  if (state.strategyError) {
+    push('error', 'strategy',
+      `Website strategy generation failed: ${state.strategyError}`,
+      'Ensure OpenAI API key is set and product docs are available, then re-run planning');
+  }
   return issues;
 }
 

package/src/workflow/plan-mode.ts

@@ -19,6 +19,7 @@ import {
   storeSpecification,
   storeUserDocs,
   storeBrandContext,
+  storeSourceDocPaths,
   storeWebsiteStrategyPath,
   addMilestones,
 } from '../state/index.js';
@@ -265,7 +266,7 @@ function isActionableTask(name: string): boolean {
 /**
  * Task app tag for fullstack projects
  */
-export type TaskAppTag = 'FE' | 'BE' | 'INT';
+export type TaskAppTag = 'FE' | 'BE' | 'INT' | 'WEB';
 
 /**
  * Task with app targeting information for fullstack projects
@@ -274,7 +275,7 @@ export interface ParsedFullstackTask {
   name: string;
   description: string;
   appTag?: TaskAppTag;
-  appTarget?: 'frontend' | 'backend' | 'unified';
+  appTarget?: 'frontend' | 'backend' | 'unified' | 'website';
   files?: string[];
   dependencies?: string[];
   acceptanceCriteria?: string[];
@@ -289,7 +290,7 @@ export interface ParsedFullstackTask {
  * @returns The parsed app tag or undefined
  */
 export function parseTaskTag(taskName: string): TaskAppTag | undefined {
-  const tagMatch = taskName.match(/\[(FE|BE|INT)\]/i);
+  const tagMatch = taskName.match(/\[(FE|BE|INT|WEB)\]/i);
   if (tagMatch) {
     return tagMatch[1].toUpperCase() as TaskAppTag;
   }
@@ -302,10 +303,11 @@ export function parseTaskTag(taskName: string): TaskAppTag | undefined {
  * @param tag - The task tag
  * @returns The app target
  */
-export function tagToAppTarget(tag: TaskAppTag): 'frontend' | 'backend' | 'unified' {
+export function tagToAppTarget(tag: TaskAppTag): 'frontend' | 'backend' | 'unified' | 'website' {
   switch (tag) {
     case 'FE': return 'frontend';
     case 'BE': return 'backend';
+    case 'WEB': return 'website';
     case 'INT': return 'unified';
   }
 }
@@ -377,6 +379,7 @@ export function validateFullstackPlan(plan: string): {
     feTasks: number;
     beTasks: number;
     intTasks: number;
+    webTasks: number;
     untaggedTasks: number;
   };
 } {
@@ -385,6 +388,7 @@ export function validateFullstackPlan(plan: string): {
   let feTasks = 0;
   let beTasks = 0;
   let intTasks = 0;
+  let webTasks = 0;
   let untaggedTasks = 0;
 
   // Find all task headers
@@ -401,6 +405,7 @@ export function validateFullstackPlan(plan: string): {
         case 'FE': feTasks++; break;
         case 'BE': beTasks++; break;
         case 'INT': intTasks++; break;
+        case 'WEB': webTasks++; break;
       }
     } else {
       untaggedTasks++;
@@ -435,6 +440,7 @@ export function validateFullstackPlan(plan: string): {
       feTasks,
       beTasks,
       intTasks,
+      webTasks,
       untaggedTasks,
     },
   };
@@ -599,6 +605,7 @@ export function parsePlanMilestones(plan: string): Omit<Milestone, 'id'>[] {
   while ((taskMatch = explicitTaskPattern.exec(plan)) !== null) {
     const name = taskMatch[1].trim()
       .replace(/^\*\*(.+)\*\*$/, '$1')  // Remove bold
+      .replace(/^\[(?:FE|BE|INT|WEB|API|DB)\]\s*:?\s*/i, '')  // Strip app tags before verb check
       .replace(/^:/, '')                 // Remove leading colon
       .trim();
 
@@ -917,10 +924,16 @@ export async function runPlanMode(
         userDocs = await readProjectDocs(docPaths);
         onProgress?.('doc-discovery', `Found ${docPaths.length} project doc(s)`);
         state = await storeUserDocs(projectDir, userDocs);
+        // Store source doc paths for later re-reading
+        state = await storeSourceDocPaths(projectDir, docPaths);
         await logger.info('init', 'docs_found', `Found ${docPaths.length} project docs`, {
           docCount: docPaths.length,
           docPaths: docPaths.map((p) => path.basename(p)),
         });
+
+        // Generate PROJECT_BRIEF.md in .popeye/ for persistent reference
+        await generateProjectBrief(projectDir, spec.name || state.name, userDocs, docPaths);
+        onProgress?.('doc-discovery', 'Generated PROJECT_BRIEF.md');
       }
       const brandAssets = await findBrandAssets(parentDir);
       if (brandAssets.logoPath) {
@@ -1013,12 +1026,13 @@ export async function runPlanMode(
         });
       } catch (strategyError) {
         // Non-blocking: strategy generation failure should not stop the workflow
+        const errorMsg = strategyError instanceof Error ? strategyError.message : 'Unknown error';
         onProgress?.(
           'get-context',
-          `Website strategy skipped: ${strategyError instanceof Error ? strategyError.message : 'Unknown error'}`
+          `WARNING: Website strategy failed: ${errorMsg}`
         );
-        await logger.warn('website-strategy', 'strategy_skipped', 'Website strategy was skipped', {
-          error: strategyError instanceof Error ? strategyError.message : 'Unknown error',
+        await logger.error('website-strategy', 'strategy_failed', 'Website strategy generation failed', {
+          error: errorMsg,
         });
       }
     }
@@ -1373,3 +1387,63 @@ export async function resumePlanMode(
     }
   );
 }
+
+/**
+ * Generate a PROJECT_BRIEF.md file in .popeye/ that summarizes
+ * key project details extracted from user documentation.
+ *
+ * This brief is loaded at every workflow stage for consistent context.
+ *
+ * @param projectDir - The project root directory
+ * @param projectName - The project/product name
+ * @param userDocs - Combined user documentation content
+ * @param docPaths - Absolute paths to source doc files
+ */
+async function generateProjectBrief(
+  projectDir: string,
+  projectName: string,
+  userDocs: string,
+  docPaths: string[]
+): Promise<void> {
+  const briefDir = path.join(projectDir, '.popeye');
+  const briefPath = path.join(briefDir, 'PROJECT_BRIEF.md');
+
+  // Extract key details from docs
+  const productName = extractBriefField(userDocs, /^#\s+(.+)/m) || projectName;
+  const tagline = extractBriefField(userDocs, /(?:tagline|subtitle|description)[:\s]+["']?(.+?)["']?\s*$/im) || '';
+  const primaryColor = extractBriefField(userDocs, /#([0-9a-fA-F]{6})\b/) || '';
+
+  const briefContent = [
+    `# Project Brief: ${productName}`,
+    '',
+    `**Product Name:** ${productName}`,
+    tagline ? `**Tagline:** ${tagline}` : '',
+    primaryColor ? `**Primary Color:** #${primaryColor}` : '',
+    '',
+    '## Source Documents',
+    ...docPaths.map(p => `- ${path.basename(p)}`),
+    '',
+    '---',
+    '*Auto-generated by Popeye. Re-read source docs for full context.*',
+    '',
+  ].filter(line => line !== undefined).join('\n');
+
+  try {
+    await fs.mkdir(briefDir, { recursive: true });
+    await fs.writeFile(briefPath, briefContent, 'utf-8');
+  } catch {
+    // Non-critical: brief generation failure shouldn't stop workflow
+  }
+}
+
+/**
+ * Extract a field value from documentation using a regex pattern.
+ *
+ * @param content - Documentation content to search
+ * @param pattern - Regex with a capture group for the value
+ * @returns The captured value, or null if not found
+ */
+function extractBriefField(content: string, pattern: RegExp): string | null {
+  const match = content.match(pattern);
+  return match?.[1]?.trim() || null;
+}