@ryuenn3123/agentic-senior-core 3.0.15 → 3.0.16

package/lib/cli/project-scaffolder/discovery.mjs

@@ -0,0 +1,315 @@
+import fs from 'node:fs/promises';
+
+import { askChoice, askYesNo } from '../utils.mjs';
+import {
+  ARCHITECTURE_STYLE_CHOICES,
+  AUTH_CHOICES,
+  DATABASE_CHOICES,
+  DOCKER_STRATEGY_CHOICES,
+  DOMAIN_CHOICES,
+  SUPPORTED_DOC_LANGUAGES,
+} from './constants.mjs';
+
+function parseBooleanLikeValue(rawValue) {
+  const normalizedValue = String(rawValue || '').trim().toLowerCase();
+  if (['true', 'yes', 'y', '1'].includes(normalizedValue)) {
+    return true;
+  }
+
+  if (['false', 'no', 'n', '0'].includes(normalizedValue)) {
+    return false;
+  }
+
+  return null;
+}
+
+function resolveDockerStrategy({ dockerStrategy, useDocker, useDockerDevelopment, useDockerProduction }) {
+  if (typeof dockerStrategy === 'string' && dockerStrategy.trim().length > 0) {
+    const normalizedDockerStrategy = dockerStrategy.trim().toLowerCase();
+    const directMatch = DOCKER_STRATEGY_CHOICES.find(
+      (dockerStrategyChoice) => dockerStrategyChoice.toLowerCase() === normalizedDockerStrategy
+    );
+
+    if (directMatch) {
+      return directMatch;
+    }
+  }
+
+  const normalizedUseDocker = typeof useDocker === 'boolean' ? useDocker : parseBooleanLikeValue(useDocker);
+  const normalizedUseDockerDevelopment = typeof useDockerDevelopment === 'boolean'
+    ? useDockerDevelopment
+    : parseBooleanLikeValue(useDockerDevelopment);
+  const normalizedUseDockerProduction = typeof useDockerProduction === 'boolean'
+    ? useDockerProduction
+    : parseBooleanLikeValue(useDockerProduction);
+
+  if (normalizedUseDocker === false) {
+    return DOCKER_STRATEGY_CHOICES[0];
+  }
+
+  if (normalizedUseDockerDevelopment === true && normalizedUseDockerProduction === true) {
+    return DOCKER_STRATEGY_CHOICES[3];
+  }
+
+  if (normalizedUseDockerDevelopment === true && normalizedUseDockerProduction !== true) {
+    return DOCKER_STRATEGY_CHOICES[1];
+  }
+
+  if (normalizedUseDockerProduction === true && normalizedUseDockerDevelopment !== true) {
+    return DOCKER_STRATEGY_CHOICES[2];
+  }
+
+  if (normalizedUseDocker === true) {
+    return DOCKER_STRATEGY_CHOICES[3];
+  }
+
+  return DOCKER_STRATEGY_CHOICES[0];
+}
+
+function resolveArchitectureStyle(rawArchitectureStyle) {
+  const normalizedArchitectureStyle = String(rawArchitectureStyle || '').trim().toLowerCase();
+
+  if (!normalizedArchitectureStyle) {
+    return ARCHITECTURE_STYLE_CHOICES[0];
+  }
+
+  if (normalizedArchitectureStyle === 'monolith' || normalizedArchitectureStyle === 'modular monolith') {
+    return ARCHITECTURE_STYLE_CHOICES[0];
+  }
+
+  if (
+    normalizedArchitectureStyle === 'microservice'
+    || normalizedArchitectureStyle === 'microservices'
+    || normalizedArchitectureStyle === 'distributed'
+    || normalizedArchitectureStyle === 'distributed system'
+    || normalizedArchitectureStyle === 'microservice / distributed system'
+  ) {
+    return ARCHITECTURE_STYLE_CHOICES[1];
+  }
+
+  const directMatch = ARCHITECTURE_STYLE_CHOICES.find(
+    (architectureStyleChoice) => architectureStyleChoice.toLowerCase() === normalizedArchitectureStyle
+  );
+
+  return directMatch || ARCHITECTURE_STYLE_CHOICES[0];
+}
+
+async function askFeatureList(userInterface) {
+  console.log('\nList your key features (one per line, press Enter to finish):');
+
+  const features = [];
+  while (features.length < 10) {
+    const featureLine = (await userInterface.question(`  Feature ${features.length + 1}: `)).trim();
+    if (!featureLine) {
+      break;
+    }
+
+    features.push(featureLine);
+  }
+
+  return features;
+}
+
+export function normalizeDocsLanguage(rawDocsLanguage = 'en') {
+  const normalizedDocsLanguage = String(rawDocsLanguage || 'en').trim().toLowerCase();
+  return SUPPORTED_DOC_LANGUAGES.has(normalizedDocsLanguage) ? normalizedDocsLanguage : null;
+}
+
+export async function runProjectDiscovery(userInterface, options = {}) {
+  console.log('\n--- Project Setup ---');
+  console.log('I will ask one focused set of questions to bootstrap project context and documentation.');
+  console.log('This helps AI agents understand your project before writing code.\n');
+  console.log('You can answer in your own language.');
+  console.log('CLI prompts stay in English, but non-English answers are fully supported.\n');
+
+  const defaultProjectName = (options.defaultProjectName || '').trim();
+  const defaultProjectDescription = String(options.defaultProjectDescription || '').trim();
+  const defaultIncludeCiGuardrails = typeof options.defaultIncludeCiGuardrails === 'boolean'
+    ? options.defaultIncludeCiGuardrails
+    : true;
+  const shouldAskForCiGuardrails = options.askForCiGuardrails !== false;
+
+  const projectNamePrompt = defaultProjectName
+    ? `Project name (press Enter to use folder name: ${defaultProjectName}): `
+    : 'Project name: ';
+
+  let projectName = (await userInterface.question(projectNamePrompt)).trim();
+
+  if (!projectName && defaultProjectName) {
+    projectName = defaultProjectName;
+  }
+
+  if (!projectName) {
+    throw new Error('Project name is required for documentation scaffolding.');
+  }
+
+  const projectDescriptionPrompt = defaultProjectDescription
+    ? `One-line description (press Enter to use: ${defaultProjectDescription}): `
+    : 'One-line description: ';
+
+  let projectDescription = (await userInterface.question(projectDescriptionPrompt)).trim();
+
+  if (!projectDescription) {
+    projectDescription = defaultProjectDescription || `A ${projectName} project.`;
+  }
+
+  const architectureStyle = await askChoice(
+    'Project topology:',
+    ARCHITECTURE_STYLE_CHOICES,
+    userInterface
+  );
+
+  const includeCiGuardrails = shouldAskForCiGuardrails
+    ? await askYesNo(
+      'Enable CI/CD quality checks (guardrails) and the LLM Judge policy?',
+      userInterface,
+      defaultIncludeCiGuardrails
+    )
+    : defaultIncludeCiGuardrails;
+
+  const domainSelection = await askChoice('Primary domain:', DOMAIN_CHOICES, userInterface);
+  let primaryDomain = domainSelection;
+  if (domainSelection === 'Other') {
+    primaryDomain = (await userInterface.question('Describe your domain: ')).trim() || 'Custom domain';
+  }
+
+  const databaseSelection = await askChoice('Database needs:', DATABASE_CHOICES, userInterface);
+  let databaseChoice = databaseSelection;
+  if (databaseSelection === 'Other') {
+    databaseChoice = (await userInterface.question('Describe your database setup: ')).trim() || 'Custom database';
+  }
+
+  const authSelection = await askChoice('Auth strategy:', AUTH_CHOICES, userInterface);
+  let authStrategy = authSelection;
+  if (authSelection === 'Other') {
+    authStrategy = (await userInterface.question('Describe your auth setup: ')).trim() || 'Custom auth';
+  }
+
+  const dockerStrategy = await askChoice(
+    'Containerization strategy:',
+    DOCKER_STRATEGY_CHOICES,
+    userInterface
+  );
+
+  const features = await askFeatureList(userInterface);
+
+  return {
+    projectName,
+    projectDescription,
+    architectureStyle,
+    includeCiGuardrails,
+    primaryDomain,
+    databaseChoice,
+    authStrategy,
+    dockerStrategy,
+    features,
+    additionalContext: 'No additional context provided.',
+  };
+}
+
+export function resolveProjectDocTargets(discoveryAnswers) {
+  const hasDatabase = !discoveryAnswers.databaseChoice.toLowerCase().startsWith('none');
+  const isApiOrWebDomain = ['API service', 'Web application'].includes(discoveryAnswers.primaryDomain)
+    || discoveryAnswers.primaryDomain.toLowerCase().includes('api')
+    || discoveryAnswers.primaryDomain.toLowerCase().includes('web');
+
+  const requiredDocFileNames = [
+    'project-brief.md',
+    'architecture-decision-record.md',
+    'flow-overview.md',
+  ];
+
+  if (hasDatabase) {
+    requiredDocFileNames.push('database-schema.md');
+  }
+
+  if (isApiOrWebDomain) {
+    requiredDocFileNames.push('api-contract.md');
+  }
+
+  return { requiredDocFileNames };
+}
+
+export function buildSynthesisContext(_discoveryAnswers, initContext) {
+  const additionalStackFileNames = Array.isArray(initContext.additionalStackFileNames)
+    ? initContext.additionalStackFileNames
+    : [];
+  const additionalBlueprintFileNames = Array.isArray(initContext.additionalBlueprintFileNames)
+    ? initContext.additionalBlueprintFileNames
+    : [];
+
+  return {
+    stackFileName: initContext.stackFileName,
+    additionalStackFileNames,
+    blueprintFileName: initContext.blueprintFileName,
+    additionalBlueprintFileNames,
+    runtimeEnvironmentKey: initContext.runtimeEnvironmentKey || 'linux',
+    runtimeEnvironmentLabel: initContext.runtimeEnvironmentLabel || 'Linux',
+  };
+}
+
+export async function loadProjectConfig(configFilePath) {
+  const configContent = await fs.readFile(configFilePath, 'utf8');
+  const configLines = configContent.split(/\r?\n/);
+  const configEntries = {};
+  let currentKey = null;
+  let currentArrayValues = null;
+
+  for (const configLine of configLines) {
+    const trimmedLine = configLine.trim();
+
+    if (!trimmedLine || trimmedLine.startsWith('#')) {
+      continue;
+    }
+
+    if (trimmedLine.startsWith('- ') && currentKey && currentArrayValues !== null) {
+      currentArrayValues.push(trimmedLine.slice(2).trim());
+      continue;
+    }
+
+    if (currentKey && currentArrayValues !== null) {
+      configEntries[currentKey] = currentArrayValues;
+      currentKey = null;
+      currentArrayValues = null;
+    }
+
+    const colonIndex = trimmedLine.indexOf(':');
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const entryKey = trimmedLine.slice(0, colonIndex).trim();
+    const entryValue = trimmedLine.slice(colonIndex + 1).trim();
+
+    if (!entryValue) {
+      currentKey = entryKey;
+      currentArrayValues = [];
+      continue;
+    }
+
+    configEntries[entryKey] = entryValue;
+  }
+
+  if (currentKey && currentArrayValues !== null) {
+    configEntries[currentKey] = currentArrayValues;
+  }
+
+  return {
+    projectName: configEntries.projectName || configEntries.name || '',
+    projectDescription: configEntries.projectDescription || configEntries.description || '',
+    architectureStyle: resolveArchitectureStyle(configEntries.architectureStyle || configEntries.topology || configEntries.serviceTopology),
+    includeCiGuardrails: parseBooleanLikeValue(configEntries.includeCiGuardrails) ?? parseBooleanLikeValue(configEntries.ci) ?? true,
+    primaryDomain: configEntries.primaryDomain || configEntries.domain || 'API service',
+    databaseChoice: configEntries.databaseChoice || configEntries.database || 'None (stateless service)',
+    authStrategy: configEntries.authStrategy || configEntries.auth || 'None (public service)',
+    dockerStrategy: resolveDockerStrategy({
+      dockerStrategy: configEntries.dockerStrategy || configEntries.containerStrategy,
+      useDocker: configEntries.useDocker,
+      useDockerDevelopment: configEntries.useDockerDevelopment || configEntries.dockerDevelopment,
+      useDockerProduction: configEntries.useDockerProduction || configEntries.dockerProduction,
+    }),
+    features: Array.isArray(configEntries.features) ? configEntries.features : [],
+    additionalContext: configEntries.additionalContext || configEntries.context || 'No additional context provided.',
+    docsLang: configEntries.docsLang || configEntries.docsLanguage || 'en',
+  };
+}

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -0,0 +1,196 @@
+import { toTitleCase } from '../utils.mjs';
+import {
+  ARCHITECTURE_STYLE_CHOICES,
+  PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
+} from './constants.mjs';
+import { buildDesignIntentSeed } from './design-contract.mjs';
+
+export function buildProjectContextBootstrapPrompt({
+  discoveryAnswers,
+  initContext,
+  expectedDocFileNames,
+  docsLanguage,
+  architectureRecommendation,
+}) {
+  const featuresList = Array.isArray(discoveryAnswers.features) && discoveryAnswers.features.length > 0
+    ? discoveryAnswers.features.map((feature, featureIndex) => `${featureIndex + 1}. ${feature}`).join('\n')
+    : 'Derive the first concrete feature set from the project name, description, and domain. Do not invent arbitrary modules just to fill space.';
+
+  const expectedDocsList = expectedDocFileNames
+    .map((fileName, fileIndex) => `${fileIndex + 1}. docs/${fileName}`)
+    .join('\n');
+
+  const architectureSnapshot = architectureRecommendation
+    ? JSON.stringify({
+      briefType: architectureRecommendation.briefType,
+      stack: architectureRecommendation.recommendedStackFileName,
+      blueprint: architectureRecommendation.recommendedBlueprintFileName,
+      confidenceLabel: architectureRecommendation.confidenceLabel,
+      confidenceScore: architectureRecommendation.confidenceScore,
+      signalSummary: architectureRecommendation.signalSummary,
+      uncertaintyNotes: architectureRecommendation.uncertaintyNotes,
+      failureModes: architectureRecommendation.failureModes,
+    }, null, 2)
+    : 'null';
+
+  return [
+    '# Bootstrap Prompt: Dynamic Project Context Synthesis',
+    '',
+    `Protocol version: ${PROJECT_DOC_SYNTHESIS_PROMPT_VERSION}`,
+    '',
+    'You are a Lead Solution Architect and Principal Engineer.',
+    'Write project context docs from scratch (no template rendering, no placeholder boilerplate).',
+    '',
+    '## Mission',
+    `Create or update these files in ${docsLanguage.toUpperCase()} language:`,
+    expectedDocsList,
+    '',
+    '## Hard Rules',
+    '1. No copy-paste from external prose.',
+    '2. Every major section must explain rationale and tradeoffs.',
+    '3. Keep stack, database, and auth aligned with the project constraints below unless user explicitly requests migration.',
+    '4. Output must be implementation-ready for engineers, not generic textbook explanation.',
+    '5. For any ecosystem or technology claim, perform live web research and include citation metadata (source + fetchedAt timestamp) rather than relying on offline heuristics.',
+    '6. Write for native English speakers at an 8th-grade reading level. Use clear, direct, plain language.',
+    '7. Avoid emoji, AI cliches, buzzwords, academic phrasing, padding, and generic filler.',
+    '8. Separate confirmed facts from assumptions explicitly. When context is incomplete, add an `Assumptions to Validate` section and a `Next Validation Action` line.',
+    '9. If user inputs conflict with repo evidence, call out the conflict and choose the safer interpretation instead of silently forcing a generic answer.',
+    '10. Do not invent modules or architecture layers only to make the docs look complete.',
+    '11. Prefer the latest stable compatible framework and package versions. If an official framework setup flow yields newer, better-supported defaults than manual package assembly, prefer that path.',
+    '12. Treat project topology as a design constraint: if the project is a monolith, explain why that shape is sufficient; if it is a microservice or distributed system, explain the service boundary logic and why the split is justified.',
+    '',
+    '## Project Inputs',
+    `- Project name: ${discoveryAnswers.projectName}`,
+    `- Project description: ${discoveryAnswers.projectDescription}`,
+    `- Project topology: ${discoveryAnswers.architectureStyle || ARCHITECTURE_STYLE_CHOICES[0]}`,
+    `- Primary domain: ${discoveryAnswers.primaryDomain}`,
+    `- Database strategy: ${discoveryAnswers.databaseChoice}`,
+    `- Auth strategy: ${discoveryAnswers.authStrategy}`,
+    `- Docker strategy: ${discoveryAnswers.dockerStrategy}`,
+    `- Runtime environment: ${initContext.runtimeEnvironmentLabel || initContext.runtimeEnvironmentKey || 'Linux'}`,
+    `- Selected stack: ${toTitleCase(initContext.stackFileName)}`,
+    `- Selected blueprint: ${toTitleCase(initContext.blueprintFileName)}`,
+    `- Additional stacks: ${Array.isArray(initContext.additionalStackFileNames) && initContext.additionalStackFileNames.length > 0 ? initContext.additionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ') : 'none'}`,
+    `- Additional blueprints: ${Array.isArray(initContext.additionalBlueprintFileNames) && initContext.additionalBlueprintFileNames.length > 0 ? initContext.additionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName)).join(', ') : 'none'}`,
+    '',
+    '## Key Features',
+    featuresList,
+    '',
+    '## Additional Context',
+    discoveryAnswers.additionalContext || 'No additional context provided.',
+    '',
+    '## Architecture Brief Snapshot (for grounding)',
+    '```json',
+    architectureSnapshot,
+    '```',
+    '',
+    '## Required Execution',
+    '1. Create all required docs files listed above with complete Markdown content.',
+    '2. Make the docs adaptive to the real repo and prompt context. These are living references, not frozen templates.',
+    '3. In docs/project-brief.md and docs/architecture-decision-record.md, include explicit sections for confirmed facts, assumptions to validate, and next validation actions whenever context is incomplete.',
+    '4. Keep content original, specific to this project, and actionable for implementation.',
+    '5. After writing docs, continue coding tasks using these docs as living project context.',
+    '',
+  ].join('\n');
+}
+
+export function buildDesignBootstrapPrompt({
+  discoveryAnswers,
+  initContext,
+  docsLanguage,
+  architectureRecommendation,
+}) {
+  const designIntentSeed = buildDesignIntentSeed({
+    discoveryAnswers,
+    initContext,
+    architectureRecommendation,
+  });
+
+  return [
+    '# Bootstrap Prompt: Dynamic Design Contract Synthesis',
+    '',
+    `Protocol version: ${PROJECT_DOC_SYNTHESIS_PROMPT_VERSION}`,
+    '',
+    'You are the Lead UI/UX Art Director for this project.',
+    'Create a dynamic design contract, not a fixed stylistic template.',
+    '',
+    '## Mission',
+    `Author docs/DESIGN.md in ${docsLanguage.toUpperCase()} language with strong art direction and engineering-ready guidance.`,
+    'Keep docs/design-intent.json synchronized as the machine-readable source of design intent.',
+    '',
+    '## Deliverables',
+    '1. docs/DESIGN.md',
+    '2. docs/design-intent.json',
+    '',
+    '## Required DESIGN.md Sections',
+    '1. Design Vision and Product Personality',
+    '2. Audience and Use-Context Signals',
+    '3. Visual Direction and Distinctive Moves',
+    '4. Color Science and Semantic Roles',
+    '5. Typographic Engineering and Hierarchy',
+    '6. Spacing, Layout Rhythm, and Density Strategy',
+    '7. Token Architecture and Alias Strategy',
+    '8. Responsive Strategy and Cross-Viewport Adaptation Matrix',
+    '9. Motion and Interaction Principles',
+    '10. Component Language and Morphology (cards, forms, nav, states)',
+    '11. Accessibility Non-Negotiables',
+    '12. Anti-Patterns to Avoid',
+    '13. Implementation Notes for Future UI Tasks',
+    '',
+    '## Required design-intent.json Fields',
+    '1. mode',
+    '2. status',
+    '3. project',
+    '4. designPhilosophy',
+    '5. brandAdjectives',
+    '6. antiAdjectives',
+    '7. visualDirection',
+    '8. mathSystems',
+    '9. tokenSystem',
+    '10. colorTruth',
+    '11. crossViewportAdaptation',
+    '12. motionSystem',
+    '13. componentMorphology',
+    '14. experiencePrinciples',
+    '15. forbiddenPatterns',
+    '16. validationHints',
+    '17. requiredDesignSections',
+    '18. implementation',
+    '',
+    '## Hard Rules',
+    '1. No copy-paste from external style guides.',
+    '2. Every major decision must include psychological/product rationale.',
+    '3. Keep implementation feasible for the selected stack and blueprint.',
+    '4. Keep tone decisive like an art director, not generic AI boilerplate.',
+    '5. Do not anchor the final design language to a famous brand reference. Translate inspiration into original project-specific principles.',
+    '6. Reject interchangeable hero layouts, generic SaaS gradients, and trend-chasing decoration unless the project context explicitly justifies them.',
+    '7. Encode color intent in perceptual terms first. Hex values may exist only as implementation derivatives.',
+    '8. Token guidance must define primitive, semantic, and component layers plus aliasing rules. Component tokens should consume semantic aliases instead of raw values.',
+    '9. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
+    '10. Motion can be bold, cinematic, or highly expressive when it improves memorability, hierarchy, feedback, or product confidence. Optimize it instead of flattening it. Only reject motion when it harms clarity, accessibility, or runtime performance.',
+    '11. Define component morphology across interaction states and viewports so cards, forms, nav, and feedback surfaces adapt coherently instead of only resizing.',
+    '11. Keep UI-only requests context-isolated. Load frontend design rules first and do not eagerly load backend-only rules unless the task explicitly crosses those boundaries.',
+    '12. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
+    '',
+    '## Project Inputs',
+    `- Project name: ${discoveryAnswers.projectName}`,
+    `- Product context: ${discoveryAnswers.projectDescription}`,
+    `- Project topology: ${discoveryAnswers.architectureStyle || ARCHITECTURE_STYLE_CHOICES[0]}`,
+    `- Domain: ${discoveryAnswers.primaryDomain}`,
+    `- Stack: ${toTitleCase(initContext.stackFileName)}`,
+    `- Blueprint: ${toTitleCase(initContext.blueprintFileName)}`,
+    '',
+    '## Seed Machine Contract',
+    'Refine this seed instead of discarding it. Keep the final JSON aligned with the markdown design system.',
+    '```json',
+    designIntentSeed.trim(),
+    '```',
+    '',
+    '## Required Execution',
+    '1. Create or update docs/DESIGN.md with complete content.',
+    '2. Create or update docs/design-intent.json with machine-readable design intent.',
+    '3. Ensure both files stay project-specific, dynamic, and practical for implementation and review.',
+    '4. After the contract exists, use it as a first-class source for future UI tasks.',
+    '',
+  ].join('\n');
+}

package/lib/cli/project-scaffolder/storage.mjs

@@ -0,0 +1,154 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ensureDirectory, pathExists } from '../utils.mjs';
+import {
+  PROJECT_DOC_FILE_NAMES,
+  PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
+  PROJECT_DOC_TEMPLATE_VERSION,
+  UI_DESIGN_CONTRACT_FILE_NAMES,
+} from './constants.mjs';
+import {
+  buildSynthesisContext,
+  normalizeDocsLanguage,
+  resolveProjectDocTargets,
+} from './discovery.mjs';
+import {
+  buildDesignIntentSeed,
+  shouldBootstrapDesignDocument,
+} from './design-contract.mjs';
+import {
+  buildDesignBootstrapPrompt,
+  buildProjectContextBootstrapPrompt,
+} from './prompt-builders.mjs';
+
+export async function generateProjectDocumentation(
+  targetDirectoryPath,
+  discoveryAnswers,
+  initContext,
+  options = {}
+) {
+  const normalizedDocsLanguage = normalizeDocsLanguage(options.docsLanguage || 'en');
+  if (!normalizedDocsLanguage) {
+    throw new Error(`Unsupported docs language: ${options.docsLanguage}. Supported values: en, id`);
+  }
+
+  const docsDirectoryPath = path.join(targetDirectoryPath, 'docs');
+  const promptsDirectoryPath = path.join(targetDirectoryPath, '.agent-context', 'prompts');
+  await ensureDirectory(docsDirectoryPath);
+  await ensureDirectory(promptsDirectoryPath);
+
+  const synthesisContext = buildSynthesisContext(discoveryAnswers, initContext);
+  const { requiredDocFileNames } = resolveProjectDocTargets(discoveryAnswers);
+  const expectedDocFileNames = [...requiredDocFileNames];
+  const generatedPromptFileNames = [];
+  const materializedFileNames = [];
+
+  const projectContextPromptFileName = 'bootstrap-project-context.md';
+  const architectureRecommendation = initContext.architectureRecommendation || null;
+  const projectContextPromptContent = buildProjectContextBootstrapPrompt({
+    discoveryAnswers,
+    initContext: synthesisContext,
+    expectedDocFileNames,
+    docsLanguage: normalizedDocsLanguage,
+    architectureRecommendation,
+  });
+  await fs.writeFile(
+    path.join(promptsDirectoryPath, projectContextPromptFileName),
+    projectContextPromptContent,
+    'utf8'
+  );
+  generatedPromptFileNames.push(projectContextPromptFileName);
+
+  if (shouldBootstrapDesignDocument(discoveryAnswers, initContext)) {
+    const designPromptFileName = 'bootstrap-design.md';
+    const designPromptContent = buildDesignBootstrapPrompt({
+      discoveryAnswers,
+      initContext: synthesisContext,
+      docsLanguage: normalizedDocsLanguage,
+      architectureRecommendation,
+    });
+    await fs.writeFile(path.join(promptsDirectoryPath, designPromptFileName), designPromptContent, 'utf8');
+    generatedPromptFileNames.push(designPromptFileName);
+
+    const designIntentSeedFileName = 'design-intent.json';
+    const designIntentSeedContent = buildDesignIntentSeed({
+      discoveryAnswers,
+      initContext: synthesisContext,
+      architectureRecommendation,
+    });
+    await fs.writeFile(path.join(docsDirectoryPath, designIntentSeedFileName), designIntentSeedContent, 'utf8');
+    materializedFileNames.push(designIntentSeedFileName);
+
+    for (const designContractFileName of UI_DESIGN_CONTRACT_FILE_NAMES) {
+      if (!expectedDocFileNames.includes(designContractFileName)) {
+        expectedDocFileNames.push(designContractFileName);
+      }
+    }
+  }
+
+  return {
+    docsDirectoryPath,
+    generatedFileNames: expectedDocFileNames,
+    generatedPromptFileNames,
+    materializedFileNames,
+    bootstrapMode: 'ai-synthesis',
+    synthesisPromptVersion: PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
+    templateVersion: PROJECT_DOC_TEMPLATE_VERSION,
+    docsLanguage: normalizedDocsLanguage,
+    discoveryAnswers,
+  };
+}
+
+export async function isDirectoryEffectivelyEmpty(targetDirectoryPath) {
+  try {
+    const directoryEntries = await fs.readdir(targetDirectoryPath);
+    const meaningfulEntries = directoryEntries.filter(
+      (entryName) => entryName !== '.git' && entryName !== '.gitignore'
+    );
+    return meaningfulEntries.length === 0;
+  } catch {
+    return true;
+  }
+}
+
+export async function hasExistingProjectDocs(targetDirectoryPath) {
+  const projectBriefPath = path.join(targetDirectoryPath, 'docs', 'project-brief.md');
+  return pathExists(projectBriefPath);
+}
+
+function extractTemplateVersion(documentContent) {
+  const templateVersionMatch = documentContent.match(/^(?:Template version|Versi template):\s*(.+)$/im);
+  return templateVersionMatch ? templateVersionMatch[1].trim() : null;
+}
+
+export async function detectProjectDocTemplateStaleness(targetDirectoryPath) {
+  const docsDirectoryPath = path.join(targetDirectoryPath, 'docs');
+  const checkedFileNames = [];
+  const staleFiles = [];
+
+  for (const projectDocFileName of PROJECT_DOC_FILE_NAMES) {
+    const projectDocFilePath = path.join(docsDirectoryPath, projectDocFileName);
+    if (!(await pathExists(projectDocFilePath))) {
+      continue;
+    }
+
+    checkedFileNames.push(projectDocFileName);
+    const projectDocContent = await fs.readFile(projectDocFilePath, 'utf8');
+    const detectedTemplateVersion = extractTemplateVersion(projectDocContent);
+
+    if (!detectedTemplateVersion || detectedTemplateVersion !== PROJECT_DOC_TEMPLATE_VERSION) {
+      staleFiles.push({
+        fileName: projectDocFileName,
+        detectedTemplateVersion,
+      });
+    }
+  }
+
+  return {
+    hasProjectDocs: checkedFileNames.length > 0,
+    expectedTemplateVersion: PROJECT_DOC_TEMPLATE_VERSION,
+    checkedFileNames,
+    staleFiles,
+  };
+}