create-universal-ai-context 2.5.0 → 2.6.0-final

package/lib/ai-orchestrator.js

@@ -1,432 +1,432 @@
-/**
- * AI Context Engineering - AI Orchestrator
- *
- * Coordinates with @context-engineer agent for full AI-powered analysis.
- * Creates initialization requests and generates agent instructions.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Context directory and file names
- */
-const AI_CONTEXT_DIR = '.ai-context';
-const AI_CONTEXT_FILE = 'AI_CONTEXT.md';
-
-/**
- * Marker file for pending initialization
- */
-const INIT_MARKER = '.init-pending';
-
-/**
- * Instruction file for agent
- */
-const INIT_REQUEST_FILE = 'INIT_REQUEST.md';
-
-/**
- * Progress tracking file
- */
-const PROGRESS_FILE = 'INIT_PROGRESS.json';
-
-/**
- * Create an initialization request marker
- * @param {string} contextDir - .ai-context directory path
- * @param {object} config - Configuration from CLI
- * @returns {object} Request object
- */
-function createInitializationRequest(contextDir, config) {
-  const request = {
-    version: '2.0.0',
-    createdAt: new Date().toISOString(),
-    projectName: config.projectName || path.basename(path.dirname(contextDir)),
-    config: {
-      techStack: config.techStack,
-      features: config.features,
-      installPlugin: config.installPlugin
-    },
-    phases: [
-      { id: 'repository-analysis', name: 'Repository Analysis', status: 'pending', progress: 0 },
-      { id: 'workflow-discovery', name: 'Workflow Discovery', status: 'pending', progress: 0 },
-      { id: 'template-population', name: 'Template Population', status: 'pending', progress: 0 },
-      { id: 'index-generation', name: 'Index Generation', status: 'pending', progress: 0 },
-      { id: 'validation', name: 'Validation', status: 'pending', progress: 0 },
-      { id: 'finalization', name: 'Finalization', status: 'pending', progress: 0 }
-    ],
-    status: 'pending',
-    completedAt: null
-  };
-
-  const markerPath = path.join(contextDir, INIT_MARKER);
-  fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
-
-  return request;
-}
-
-/**
- * Generate agent instruction file with pre-analysis results
- * @param {string} contextDir - .ai-context directory path
- * @param {object} analysis - Pre-analysis results from static analyzer
- * @param {object} config - Configuration from CLI
- */
-function generateAgentInstructions(contextDir, analysis, config) {
-  const projectName = config.projectName || path.basename(path.dirname(contextDir));
-  const pkgVersion = getPackageVersion();
-
-  const instructions = `# Context Engineering Initialization Request
-
-> **Auto-generated by \`create-ai-context\` v${pkgVersion}**
-> Generated: ${new Date().toISOString()}
-
-## Status: Awaiting AI Completion
-
-The CLI has performed static pre-analysis and prepared the template structure.
-Full AI-powered context engineering is requested to complete initialization.
-
----
-
-## Project Overview
-
-| Property | Value |
-|----------|-------|
-| **Project Name** | ${projectName} |
-| **Tech Stack** | ${analysis.techStack?.summary || 'Detected during analysis'} |
-| **Source Files** | ${analysis.sourceFiles || 'TBD'} |
-| **Lines of Code** | ${analysis.linesOfCode?.total || 'TBD'} |
-
----
-
-## Pre-Analysis Results
-
-### Entry Points Discovered (${analysis.entryPoints?.length || 0})
-
-${formatEntryPoints(analysis.entryPoints)}
-
-### Workflow Candidates (${analysis.workflows?.length || 0})
-
-${formatWorkflows(analysis.workflows)}
-
-### Architecture Layers
-
-${formatLayers(analysis.architecture?.layers)}
-
-### Dependencies (${analysis.dependencies?.length || 0})
-
-${formatDependencies(analysis.dependencies)}
-
----
-
-## Requested Actions
-
-Please complete the context engineering initialization by:
-
-### Phase 1: Verify Pre-Analysis
-- [ ] Review discovered entry points for accuracy
-- [ ] Confirm workflow candidates are valid
-- [ ] Identify any missed entry points or workflows
-
-### Phase 2: Deep Workflow Discovery
-- [ ] Trace call chains for each workflow (3 levels deep)
-- [ ] Identify database operations per workflow
-- [ ] Map external API calls per workflow
-- [ ] Document error handling patterns
-
-### Phase 3: Template Population
-- [ ] Fill ARCHITECTURE_SNAPSHOT.md with real architecture
-- [ ] Create individual workflow files (8-15 total)
-- [ ] Populate CODE_TO_WORKFLOW_MAP.md with file references
-- [ ] Update WORKFLOW_INDEX.md with all workflows
-
-### Phase 4: Index Generation
-- [ ] Generate proper category indexes
-- [ ] Create semantic anchors for key functions
-- [ ] Build reverse lookup indexes
-
-### Phase 5: Validation
-- [ ] Verify line number accuracy (target: 60%+)
-- [ ] Check all internal links
-- [ ] Confirm no placeholder values remain
-
-### Phase 6: Finalization
-- [ ] Generate summary report
-- [ ] Update AI_CONTEXT.md with project-specific info
-- [ ] Create maintenance schedule
-
----
-
-## Quick Start Command
-
-\`\`\`bash
-@context-engineer "Complete initialization for ${projectName} using the pre-analysis in INIT_REQUEST.md"
-\`\`\`
-
-Or use the dedicated command:
-
-\`\`\`bash
-/rpi-research "Complete context engineering initialization"
-\`\`\`
-
----
-
-## Files to Update
-
-| File | Action |
-|------|--------|
-| \`context/ARCHITECTURE_SNAPSHOT.md\` | Populate with real architecture |
-| \`context/WORKFLOW_INDEX.md\` | Add all discovered workflows |
-| \`context/CODE_TO_WORKFLOW_MAP.md\` | Map files to workflows |
-| \`context/workflows/*.md\` | Create individual workflow docs |
-| \`indexes/workflows/CATEGORY_INDEX.md\` | Generate category index |
-| \`../AI_CONTEXT.md\` | Finalize with project info |
-
----
-
-## Pre-Analysis Data
-
-The following JSON contains the full pre-analysis for programmatic use:
-
-\`\`\`json
-${JSON.stringify(analysis.summary || {}, null, 2)}
-\`\`\`
-
----
-
-*This file will be deleted automatically after successful initialization.*
-*Generated by create-ai-context v${pkgVersion}*
-`;
-
-  const instructionPath = path.join(contextDir, INIT_REQUEST_FILE);
-  fs.writeFileSync(instructionPath, instructions);
-
-  return instructionPath;
-}
-
-/**
- * Format entry points for markdown
- * @param {object[]} entryPoints - Entry points array
- * @returns {string}
- */
-function formatEntryPoints(entryPoints) {
-  if (!entryPoints || entryPoints.length === 0) {
-    return '*No entry points discovered during pre-analysis. AI analysis will discover them.*\n';
-  }
-
-  const limited = entryPoints.slice(0, 15);
-  let output = '| File | Line | Route | Method |\n|------|------|-------|--------|\n';
-
-  for (const ep of limited) {
-    output += `| \`${ep.file}\` | ${ep.line} | ${ep.route || '-'} | ${ep.method || '-'} |\n`;
-  }
-
-  if (entryPoints.length > 15) {
-    output += `\n*...and ${entryPoints.length - 15} more entry points*\n`;
-  }
-
-  return output;
-}
-
-/**
- * Format workflows for markdown
- * @param {object[]} workflows - Workflows array
- * @returns {string}
- */
-function formatWorkflows(workflows) {
-  if (!workflows || workflows.length === 0) {
-    return '*No workflows discovered during pre-analysis. AI analysis will discover them.*\n';
-  }
-
-  let output = '| Workflow | Category | Complexity | Files | Confidence |\n|----------|----------|------------|-------|------------|\n';
-
-  for (const wf of workflows) {
-    output += `| **${wf.name}** | ${wf.category} | ${wf.complexity} | ${wf.fileCount || wf.files?.length || 0} | ${wf.confidence || '-'}% |\n`;
-  }
-
-  return output;
-}
-
-/**
- * Format architecture layers for markdown
- * @param {object[]} layers - Layers array
- * @returns {string}
- */
-function formatLayers(layers) {
-  if (!layers || layers.length === 0) {
-    return '*Architecture layers will be determined during AI analysis.*\n';
-  }
-
-  let output = '| Layer | Directories | Purpose |\n|-------|-------------|----------|\n';
-
-  for (const layer of layers) {
-    output += `| **${layer.name}** | ${layer.directories?.join(', ') || '-'} | ${layer.purpose || '-'} |\n`;
-  }
-
-  return output;
-}
-
-/**
- * Format dependencies for markdown
- * @param {object[]} dependencies - Dependencies array
- * @returns {string}
- */
-function formatDependencies(dependencies) {
-  if (!dependencies || dependencies.length === 0) {
-    return '*No dependencies detected.*\n';
-  }
-
-  // Group by ecosystem
-  const byEcosystem = {};
-  for (const dep of dependencies) {
-    const eco = dep.ecosystem || 'unknown';
-    if (!byEcosystem[eco]) byEcosystem[eco] = [];
-    byEcosystem[eco].push(dep);
-  }
-
-  let output = '';
-  for (const [ecosystem, deps] of Object.entries(byEcosystem)) {
-    output += `\n**${ecosystem.toUpperCase()}** (${deps.length}):\n`;
-    const topDeps = deps.slice(0, 10);
-    output += topDeps.map(d => `- ${d.name}@${d.version}`).join('\n') + '\n';
-    if (deps.length > 10) {
-      output += `- *...and ${deps.length - 10} more*\n`;
-    }
-  }
-
-  return output;
-}
-
-/**
- * Get package version
- * @returns {string}
- */
-function getPackageVersion() {
-  try {
-    const pkgPath = path.join(__dirname, '..', 'package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    return pkg.version || '1.0.0';
-  } catch (error) {
-    // Silently fall back to default version
-    return '1.0.0';
-  }
-}
-
-/**
- * Check initialization status
- * @param {string} contextDir - .ai-context directory path
- * @returns {object}
- */
-function checkInitializationStatus(contextDir) {
-  const markerPath = path.join(contextDir, INIT_MARKER);
-
-  if (!fs.existsSync(markerPath)) {
-    return { status: 'not-started', request: null };
-  }
-
-  try {
-    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
-    const completedPhases = request.phases.filter(p => p.status === 'completed').length;
-    const totalPhases = request.phases.length;
-
-    return {
-      status: completedPhases === totalPhases ? 'completed' : 'in-progress',
-      progress: Math.round((completedPhases / totalPhases) * 100),
-      completedPhases,
-      totalPhases,
-      request
-    };
-  } catch {
-    return { status: 'error', request: null };
-  }
-}
-
-/**
- * Update initialization progress
- * @param {string} contextDir - .ai-context directory path
- * @param {string} phaseId - Phase ID to update
- * @param {string} status - New status ('in-progress', 'completed', 'failed')
- * @param {number} progress - Progress percentage (0-100)
- */
-function updateInitializationProgress(contextDir, phaseId, status, progress = 0) {
-  const markerPath = path.join(contextDir, INIT_MARKER);
-
-  if (!fs.existsSync(markerPath)) {
-    return false;
-  }
-
-  try {
-    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
-    const phase = request.phases.find(p => p.id === phaseId);
-
-    if (phase) {
-      phase.status = status;
-      phase.progress = progress;
-      phase.updatedAt = new Date().toISOString();
-    }
-
-    // Check if all phases are completed
-    const allCompleted = request.phases.every(p => p.status === 'completed');
-    if (allCompleted) {
-      request.status = 'completed';
-      request.completedAt = new Date().toISOString();
-    } else {
-      request.status = 'in-progress';
-    }
-
-    fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Mark initialization as complete and clean up
- * @param {string} contextDir - .ai-context directory path
- * @param {boolean} removeMarker - Whether to remove the marker file
- */
-function completeInitialization(contextDir, removeMarker = true) {
-  const markerPath = path.join(contextDir, INIT_MARKER);
-  const instructionPath = path.join(contextDir, INIT_REQUEST_FILE);
-
-  if (fs.existsSync(markerPath)) {
-    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
-    request.status = 'completed';
-    request.completedAt = new Date().toISOString();
-
-    // Archive to progress file
-    const progressPath = path.join(contextDir, PROGRESS_FILE);
-    fs.writeFileSync(progressPath, JSON.stringify(request, null, 2));
-
-    if (removeMarker) {
-      fs.unlinkSync(markerPath);
-    }
-  }
-
-  // Remove instruction file
-  if (removeMarker && fs.existsSync(instructionPath)) {
-    fs.unlinkSync(instructionPath);
-  }
-}
-
-/**
- * Check if initialization is pending
- * @param {string} contextDir - .ai-context directory path
- * @returns {boolean}
- */
-function isInitializationPending(contextDir) {
-  const markerPath = path.join(contextDir, INIT_MARKER);
-  return fs.existsSync(markerPath);
-}
-
-module.exports = {
-  createInitializationRequest,
-  generateAgentInstructions,
-  checkInitializationStatus,
-  updateInitializationProgress,
-  completeInitialization,
-  isInitializationPending,
-  INIT_MARKER,
-  INIT_REQUEST_FILE,
-  PROGRESS_FILE,
-  AI_CONTEXT_DIR,
-  AI_CONTEXT_FILE
-};
+/**
+ * AI Context Engineering - AI Orchestrator
+ *
+ * Coordinates with @context-engineer agent for full AI-powered analysis.
+ * Creates initialization requests and generates agent instructions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Context directory and file names
+ */
+const AI_CONTEXT_DIR = '.ai-context';
+const AI_CONTEXT_FILE = 'AI_CONTEXT.md';
+
+/**
+ * Marker file for pending initialization
+ */
+const INIT_MARKER = '.init-pending';
+
+/**
+ * Instruction file for agent
+ */
+const INIT_REQUEST_FILE = 'INIT_REQUEST.md';
+
+/**
+ * Progress tracking file
+ */
+const PROGRESS_FILE = 'INIT_PROGRESS.json';
+
+/**
+ * Create an initialization request marker
+ * @param {string} contextDir - .ai-context directory path
+ * @param {object} config - Configuration from CLI
+ * @returns {object} Request object
+ */
+function createInitializationRequest(contextDir, config) {
+  const request = {
+    version: '2.0.0',
+    createdAt: new Date().toISOString(),
+    projectName: config.projectName || path.basename(path.dirname(contextDir)),
+    config: {
+      techStack: config.techStack,
+      features: config.features,
+      installPlugin: config.installPlugin
+    },
+    phases: [
+      { id: 'repository-analysis', name: 'Repository Analysis', status: 'pending', progress: 0 },
+      { id: 'workflow-discovery', name: 'Workflow Discovery', status: 'pending', progress: 0 },
+      { id: 'template-population', name: 'Template Population', status: 'pending', progress: 0 },
+      { id: 'index-generation', name: 'Index Generation', status: 'pending', progress: 0 },
+      { id: 'validation', name: 'Validation', status: 'pending', progress: 0 },
+      { id: 'finalization', name: 'Finalization', status: 'pending', progress: 0 }
+    ],
+    status: 'pending',
+    completedAt: null
+  };
+
+  const markerPath = path.join(contextDir, INIT_MARKER);
+  fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
+
+  return request;
+}
+
+/**
+ * Generate agent instruction file with pre-analysis results
+ * @param {string} contextDir - .ai-context directory path
+ * @param {object} analysis - Pre-analysis results from static analyzer
+ * @param {object} config - Configuration from CLI
+ */
+function generateAgentInstructions(contextDir, analysis, config) {
+  const projectName = config.projectName || path.basename(path.dirname(contextDir));
+  const pkgVersion = getPackageVersion();
+
+  const instructions = `# Context Engineering Initialization Request
+
+> **Auto-generated by \`create-ai-context\` v${pkgVersion}**
+> Generated: ${new Date().toISOString()}
+
+## Status: Awaiting AI Completion
+
+The CLI has performed static pre-analysis and prepared the template structure.
+Full AI-powered context engineering is requested to complete initialization.
+
+---
+
+## Project Overview
+
+| Property | Value |
+|----------|-------|
+| **Project Name** | ${projectName} |
+| **Tech Stack** | ${analysis.techStack?.summary || 'Detected during analysis'} |
+| **Source Files** | ${analysis.sourceFiles || 'TBD'} |
+| **Lines of Code** | ${analysis.linesOfCode?.total || 'TBD'} |
+
+---
+
+## Pre-Analysis Results
+
+### Entry Points Discovered (${analysis.entryPoints?.length || 0})
+
+${formatEntryPoints(analysis.entryPoints)}
+
+### Workflow Candidates (${analysis.workflows?.length || 0})
+
+${formatWorkflows(analysis.workflows)}
+
+### Architecture Layers
+
+${formatLayers(analysis.architecture?.layers)}
+
+### Dependencies (${analysis.dependencies?.length || 0})
+
+${formatDependencies(analysis.dependencies)}
+
+---
+
+## Requested Actions
+
+Please complete the context engineering initialization by:
+
+### Phase 1: Verify Pre-Analysis
+- [ ] Review discovered entry points for accuracy
+- [ ] Confirm workflow candidates are valid
+- [ ] Identify any missed entry points or workflows
+
+### Phase 2: Deep Workflow Discovery
+- [ ] Trace call chains for each workflow (3 levels deep)
+- [ ] Identify database operations per workflow
+- [ ] Map external API calls per workflow
+- [ ] Document error handling patterns
+
+### Phase 3: Template Population
+- [ ] Fill ARCHITECTURE_SNAPSHOT.md with real architecture
+- [ ] Create individual workflow files (8-15 total)
+- [ ] Populate CODE_TO_WORKFLOW_MAP.md with file references
+- [ ] Update WORKFLOW_INDEX.md with all workflows
+
+### Phase 4: Index Generation
+- [ ] Generate proper category indexes
+- [ ] Create semantic anchors for key functions
+- [ ] Build reverse lookup indexes
+
+### Phase 5: Validation
+- [ ] Verify line number accuracy (target: 60%+)
+- [ ] Check all internal links
+- [ ] Confirm no placeholder values remain
+
+### Phase 6: Finalization
+- [ ] Generate summary report
+- [ ] Update AI_CONTEXT.md with project-specific info
+- [ ] Create maintenance schedule
+
+---
+
+## Quick Start Command
+
+\`\`\`bash
+@context-engineer "Complete initialization for ${projectName} using the pre-analysis in INIT_REQUEST.md"
+\`\`\`
+
+Or use the dedicated command:
+
+\`\`\`bash
+/rpi-research "Complete context engineering initialization"
+\`\`\`
+
+---
+
+## Files to Update
+
+| File | Action |
+|------|--------|
+| \`context/ARCHITECTURE_SNAPSHOT.md\` | Populate with real architecture |
+| \`context/WORKFLOW_INDEX.md\` | Add all discovered workflows |
+| \`context/CODE_TO_WORKFLOW_MAP.md\` | Map files to workflows |
+| \`context/workflows/*.md\` | Create individual workflow docs |
+| \`indexes/workflows/CATEGORY_INDEX.md\` | Generate category index |
+| \`../AI_CONTEXT.md\` | Finalize with project info |
+
+---
+
+## Pre-Analysis Data
+
+The following JSON contains the full pre-analysis for programmatic use:
+
+\`\`\`json
+${JSON.stringify(analysis.summary || {}, null, 2)}
+\`\`\`
+
+---
+
+*This file will be deleted automatically after successful initialization.*
+*Generated by create-ai-context v${pkgVersion}*
+`;
+
+  const instructionPath = path.join(contextDir, INIT_REQUEST_FILE);
+  fs.writeFileSync(instructionPath, instructions);
+
+  return instructionPath;
+}
+
+/**
+ * Format entry points for markdown
+ * @param {object[]} entryPoints - Entry points array
+ * @returns {string}
+ */
+function formatEntryPoints(entryPoints) {
+  if (!entryPoints || entryPoints.length === 0) {
+    return '*No entry points discovered during pre-analysis. AI analysis will discover them.*\n';
+  }
+
+  const limited = entryPoints.slice(0, 15);
+  let output = '| File | Line | Route | Method |\n|------|------|-------|--------|\n';
+
+  for (const ep of limited) {
+    output += `| \`${ep.file}\` | ${ep.line} | ${ep.route || '-'} | ${ep.method || '-'} |\n`;
+  }
+
+  if (entryPoints.length > 15) {
+    output += `\n*...and ${entryPoints.length - 15} more entry points*\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Format workflows for markdown
+ * @param {object[]} workflows - Workflows array
+ * @returns {string}
+ */
+function formatWorkflows(workflows) {
+  if (!workflows || workflows.length === 0) {
+    return '*No workflows discovered during pre-analysis. AI analysis will discover them.*\n';
+  }
+
+  let output = '| Workflow | Category | Complexity | Files | Confidence |\n|----------|----------|------------|-------|------------|\n';
+
+  for (const wf of workflows) {
+    output += `| **${wf.name}** | ${wf.category} | ${wf.complexity} | ${wf.fileCount || wf.files?.length || 0} | ${wf.confidence || '-'}% |\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Format architecture layers for markdown
+ * @param {object[]} layers - Layers array
+ * @returns {string}
+ */
+function formatLayers(layers) {
+  if (!layers || layers.length === 0) {
+    return '*Architecture layers will be determined during AI analysis.*\n';
+  }
+
+  let output = '| Layer | Directories | Purpose |\n|-------|-------------|----------|\n';
+
+  for (const layer of layers) {
+    output += `| **${layer.name}** | ${layer.directories?.join(', ') || '-'} | ${layer.purpose || '-'} |\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Format dependencies for markdown
+ * @param {object[]} dependencies - Dependencies array
+ * @returns {string}
+ */
+function formatDependencies(dependencies) {
+  if (!dependencies || dependencies.length === 0) {
+    return '*No dependencies detected.*\n';
+  }
+
+  // Group by ecosystem
+  const byEcosystem = {};
+  for (const dep of dependencies) {
+    const eco = dep.ecosystem || 'unknown';
+    if (!byEcosystem[eco]) byEcosystem[eco] = [];
+    byEcosystem[eco].push(dep);
+  }
+
+  let output = '';
+  for (const [ecosystem, deps] of Object.entries(byEcosystem)) {
+    output += `\n**${ecosystem.toUpperCase()}** (${deps.length}):\n`;
+    const topDeps = deps.slice(0, 10);
+    output += topDeps.map(d => `- ${d.name}@${d.version}`).join('\n') + '\n';
+    if (deps.length > 10) {
+      output += `- *...and ${deps.length - 10} more*\n`;
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Get package version
+ * @returns {string}
+ */
+function getPackageVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || '1.0.0';
+  } catch (error) {
+    // Silently fall back to default version
+    return '1.0.0';
+  }
+}
+
+/**
+ * Check initialization status
+ * @param {string} contextDir - .ai-context directory path
+ * @returns {object}
+ */
+function checkInitializationStatus(contextDir) {
+  const markerPath = path.join(contextDir, INIT_MARKER);
+
+  if (!fs.existsSync(markerPath)) {
+    return { status: 'not-started', request: null };
+  }
+
+  try {
+    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+    const completedPhases = request.phases.filter(p => p.status === 'completed').length;
+    const totalPhases = request.phases.length;
+
+    return {
+      status: completedPhases === totalPhases ? 'completed' : 'in-progress',
+      progress: Math.round((completedPhases / totalPhases) * 100),
+      completedPhases,
+      totalPhases,
+      request
+    };
+  } catch {
+    return { status: 'error', request: null };
+  }
+}
+
+/**
+ * Update initialization progress
+ * @param {string} contextDir - .ai-context directory path
+ * @param {string} phaseId - Phase ID to update
+ * @param {string} status - New status ('in-progress', 'completed', 'failed')
+ * @param {number} progress - Progress percentage (0-100)
+ */
+function updateInitializationProgress(contextDir, phaseId, status, progress = 0) {
+  const markerPath = path.join(contextDir, INIT_MARKER);
+
+  if (!fs.existsSync(markerPath)) {
+    return false;
+  }
+
+  try {
+    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+    const phase = request.phases.find(p => p.id === phaseId);
+
+    if (phase) {
+      phase.status = status;
+      phase.progress = progress;
+      phase.updatedAt = new Date().toISOString();
+    }
+
+    // Check if all phases are completed
+    const allCompleted = request.phases.every(p => p.status === 'completed');
+    if (allCompleted) {
+      request.status = 'completed';
+      request.completedAt = new Date().toISOString();
+    } else {
+      request.status = 'in-progress';
+    }
+
+    fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark initialization as complete and clean up
+ * @param {string} contextDir - .ai-context directory path
+ * @param {boolean} removeMarker - Whether to remove the marker file
+ */
+function completeInitialization(contextDir, removeMarker = true) {
+  const markerPath = path.join(contextDir, INIT_MARKER);
+  const instructionPath = path.join(contextDir, INIT_REQUEST_FILE);
+
+  if (fs.existsSync(markerPath)) {
+    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+    request.status = 'completed';
+    request.completedAt = new Date().toISOString();
+
+    // Archive to progress file
+    const progressPath = path.join(contextDir, PROGRESS_FILE);
+    fs.writeFileSync(progressPath, JSON.stringify(request, null, 2));
+
+    if (removeMarker) {
+      fs.unlinkSync(markerPath);
+    }
+  }
+
+  // Remove instruction file
+  if (removeMarker && fs.existsSync(instructionPath)) {
+    fs.unlinkSync(instructionPath);
+  }
+}
+
+/**
+ * Check if initialization is pending
+ * @param {string} contextDir - .ai-context directory path
+ * @returns {boolean}
+ */
+function isInitializationPending(contextDir) {
+  const markerPath = path.join(contextDir, INIT_MARKER);
+  return fs.existsSync(markerPath);
+}
+
+module.exports = {
+  createInitializationRequest,
+  generateAgentInstructions,
+  checkInitializationStatus,
+  updateInitializationProgress,
+  completeInitialization,
+  isInitializationPending,
+  INIT_MARKER,
+  INIT_REQUEST_FILE,
+  PROGRESS_FILE,
+  AI_CONTEXT_DIR,
+  AI_CONTEXT_FILE
+};