@ryuenn3123/agentic-senior-core 3.0.5 → 3.0.7

package/lib/cli/project-scaffolder.mjs

@@ -6,7 +6,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { ensureDirectory, askChoice, askYesNo, toTitleCase, pathExists } from './utils.mjs';
+import { ensureDirectory, askChoice, toTitleCase, pathExists } from './utils.mjs';
 
 const SUPPORTED_DOC_LANGUAGES = new Set(['en', 'id']);
 const PROJECT_DOC_FILE_NAMES = [
@@ -16,6 +16,7 @@ const PROJECT_DOC_FILE_NAMES = [
   'api-contract.md',
   'flow-overview.md',
 ];
+const UI_DESIGN_CONTRACT_FILE_NAMES = ['DESIGN.md', 'design-intent.json'];
 
 // Legacy project docs may still carry this version header; keep for upgrade staleness checks.
 export const PROJECT_DOC_TEMPLATE_VERSION = '1.2.0';
@@ -54,57 +55,6 @@ const DOCKER_STRATEGY_CHOICES = [
   'Docker for both development and production',
 ];
 
-const DISCOVERY_MODE_CHOICES = [
-  'Quick mode (mostly choices, fastest)',
-  'Detailed mode (type your own answers)',
-];
-
-const DESCRIPTION_TEMPLATE_CHOICES = [
-  'Marketplace / commerce platform',
-  'Internal operations dashboard',
-  'SaaS workflow product',
-  'Developer platform / API product',
-  'Content and community platform',
-  'Other',
-];
-
-const FEATURE_PRESET_CHOICES = [
-  'MVP foundation (auth, core CRUD, role-based access)',
-  'Commerce flow (catalog, cart, checkout)',
-  'Operations flow (dashboard, approvals, reporting)',
-  'API platform flow (keys, rate-limit, webhooks)',
-  'Content flow (publish, moderation, search)',
-  'Other',
-];
-
-const FEATURE_PRESET_MAP = {
-  'MVP foundation (auth, core CRUD, role-based access)': [
-    'Authentication and user profiles',
-    'Core CRUD workflow for primary resources',
-    'Role-based access control',
-  ],
-  'Commerce flow (catalog, cart, checkout)': [
-    'Product catalog and filtering',
-    'Shopping cart and wishlist',
-    'Checkout and payment processing flow',
-  ],
-  'Operations flow (dashboard, approvals, reporting)': [
-    'Operational dashboard with KPIs',
-    'Approval workflow and audit trail',
-    'Reporting and export functionality',
-  ],
-  'API platform flow (keys, rate-limit, webhooks)': [
-    'API key management',
-    'Rate limiting and usage quotas',
-    'Webhook delivery and retry handling',
-  ],
-  'Content flow (publish, moderation, search)': [
-    'Draft and publish workflow',
-    'Moderation queue and policy checks',
-    'Search and discovery experience',
-  ],
-};
-
 function parseBooleanLikeValue(rawValue) {
   const normalizedValue = String(rawValue || '').trim().toLowerCase();
   if (['true', 'yes', 'y', '1'].includes(normalizedValue)) {
@@ -161,44 +111,6 @@ function resolveDockerStrategy({ dockerStrategy, useDocker, useDockerDevelopment
   return DOCKER_STRATEGY_CHOICES[0];
 }
 
-function parseDockerStrategy(dockerStrategy) {
-  const normalizedDockerStrategy = String(dockerStrategy || '').toLowerCase();
-
-  if (normalizedDockerStrategy.includes('both development and production')) {
-    return {
-      dockerStrategy: DOCKER_STRATEGY_CHOICES[3],
-      hasDocker: true,
-      useDockerDevelopment: true,
-      useDockerProduction: true,
-    };
-  }
-
-  if (normalizedDockerStrategy.includes('development only')) {
-    return {
-      dockerStrategy: DOCKER_STRATEGY_CHOICES[1],
-      hasDocker: true,
-      useDockerDevelopment: true,
-      useDockerProduction: false,
-    };
-  }
-
-  if (normalizedDockerStrategy.includes('production only')) {
-    return {
-      dockerStrategy: DOCKER_STRATEGY_CHOICES[2],
-      hasDocker: true,
-      useDockerDevelopment: false,
-      useDockerProduction: true,
-    };
-  }
-
-  return {
-    dockerStrategy: DOCKER_STRATEGY_CHOICES[0],
-    hasDocker: false,
-    useDockerDevelopment: false,
-    useDockerProduction: false,
-  };
-}
-
 async function askFeatureList(userInterface) {
   console.log('\nList your key features (one per line, press Enter to finish):');
 
@@ -231,67 +143,32 @@ export async function runProjectDiscovery(userInterface, options = {}) {
   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 selectedDiscoveryMode = await askChoice(
-    'How do you want to answer project questions?',
-    DISCOVERY_MODE_CHOICES,
-    userInterface
-  );
-
-  const isQuickMode = selectedDiscoveryMode === DISCOVERY_MODE_CHOICES[0];
-
   const defaultProjectName = (options.defaultProjectName || '').trim();
+  const defaultProjectDescription = String(options.defaultProjectDescription || '').trim();
   let projectName = '';
 
-  if (isQuickMode && defaultProjectName) {
-    const projectNameSource = await askChoice(
-      'Project name source:',
-      [
-        `Use folder name (${defaultProjectName})`,
-        'Type custom project name',
-      ],
-      userInterface
-    );
+  const projectNamePrompt = defaultProjectName
+    ? `Project name (press Enter to use folder name: ${defaultProjectName}): `
+    : 'Project name: ';
 
-    if (projectNameSource.startsWith('Use folder name')) {
-      projectName = defaultProjectName;
-    }
-  }
-
-  if (!projectName) {
-    const projectNamePrompt = defaultProjectName
-      ? `Project name (press Enter to use folder name: ${defaultProjectName}): `
-      : 'Project name: ';
+  projectName = (await userInterface.question(projectNamePrompt)).trim();
 
-    projectName = (await userInterface.question(projectNamePrompt)).trim();
-
-    if (!projectName && defaultProjectName) {
-      projectName = defaultProjectName;
-    }
+  if (!projectName && defaultProjectName) {
+    projectName = defaultProjectName;
   }
 
   if (!projectName) {
     throw new Error('Project name is required for documentation scaffolding.');
   }
 
-  let projectDescription = '';
-  if (isQuickMode) {
-    const selectedDescriptionTemplate = await askChoice(
-      'Project description template:',
-      DESCRIPTION_TEMPLATE_CHOICES,
-      userInterface
-    );
+  const projectDescriptionPrompt = defaultProjectDescription
+    ? `One-line description (press Enter to use: ${defaultProjectDescription}): `
+    : 'One-line description: ';
 
-    if (selectedDescriptionTemplate === 'Other') {
-      projectDescription = (await userInterface.question('One-line description: ')).trim();
-    } else {
-      projectDescription = `${selectedDescriptionTemplate} for ${projectName}.`;
-    }
-  } else {
-    projectDescription = (await userInterface.question('One-line description: ')).trim();
-  }
+  let projectDescription = (await userInterface.question(projectDescriptionPrompt)).trim();
 
   if (!projectDescription) {
-    projectDescription = `A ${projectName} project.`;
+    projectDescription = defaultProjectDescription || `A ${projectName} project.`;
   }
 
   const domainSelection = await askChoice(
@@ -327,79 +204,20 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     authStrategy = (await userInterface.question('Describe your auth setup: ')).trim() || 'Custom auth';
   }
 
-  let dockerStrategy = DOCKER_STRATEGY_CHOICES[0];
-  if (isQuickMode) {
-    dockerStrategy = await askChoice(
-      'Containerization strategy:',
-      DOCKER_STRATEGY_CHOICES,
-      userInterface
-    );
-  } else {
-    const useDocker = await askYesNo(
-      'Use Docker for this project (development and/or production)?',
-      userInterface,
-      false
-    );
-
-    if (useDocker) {
-      const useDockerDevelopment = await askYesNo(
-        'Use Docker for development workflow?',
-        userInterface,
-        true
-      );
-      const useDockerProduction = await askYesNo(
-        'Use Docker for production runtime/build?',
-        userInterface,
-        true
-      );
-
-      dockerStrategy = resolveDockerStrategy({
-        useDocker,
-        useDockerDevelopment,
-        useDockerProduction,
-      });
-    }
-  }
-
-  const parsedDockerStrategy = parseDockerStrategy(dockerStrategy);
-
-  let features = [];
-  if (isQuickMode) {
-    const selectedFeaturePreset = await askChoice(
-      'Feature set:',
-      FEATURE_PRESET_CHOICES,
-      userInterface
-    );
+  const dockerStrategy = await askChoice(
+    'Containerization strategy:',
+    DOCKER_STRATEGY_CHOICES,
+    userInterface
+  );
 
-    if (selectedFeaturePreset === 'Other') {
-      features = await askFeatureList(userInterface);
-    } else {
-      features = FEATURE_PRESET_MAP[selectedFeaturePreset] || [];
-    }
-  } else {
-    features = await askFeatureList(userInterface);
-  }
+  let features = await askFeatureList(userInterface);
 
   if (features.length === 0) {
     features.push('Core functionality (define during development)');
   }
 
-  let additionalContext = 'No additional context provided.';
-  if (isQuickMode) {
-    const wantsAdditionalContext = await askYesNo(
-      'Add additional context now?',
-      userInterface,
-      false
-    );
-
-    if (wantsAdditionalContext) {
-      additionalContext = (await userInterface.question('Additional context: ')).trim()
-        || 'No additional context provided.';
-    }
-  } else {
-    additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
-      || 'No additional context provided.';
-  }
+  const additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
+    || 'No additional context provided.';
 
   return {
     projectName,
@@ -407,9 +225,7 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     primaryDomain,
     databaseChoice,
     authStrategy,
-    dockerStrategy: parsedDockerStrategy.dockerStrategy,
-    useDockerDevelopment: parsedDockerStrategy.useDockerDevelopment,
-    useDockerProduction: parsedDockerStrategy.useDockerProduction,
+    dockerStrategy,
     features,
     additionalContext,
   };
@@ -490,6 +306,134 @@ function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
   return false;
 }
 
+function inferDesignKeywords(discoveryAnswers) {
+  const normalizedDescription = String(discoveryAnswers.projectDescription || '').toLowerCase();
+  const normalizedDomain = String(discoveryAnswers.primaryDomain || '').toLowerCase();
+  const normalizedFeatures = Array.isArray(discoveryAnswers.features)
+    ? discoveryAnswers.features.map((featureValue) => String(featureValue).toLowerCase()).join(' ')
+    : '';
+  const aggregateText = `${normalizedDescription} ${normalizedDomain} ${normalizedFeatures}`;
+
+  if (aggregateText.includes('commerce') || aggregateText.includes('catalog') || aggregateText.includes('checkout')) {
+    return {
+      brandAdjectives: ['clear', 'desirable', 'confident'],
+      antiAdjectives: ['cluttered', 'hesitant', 'coupon-noisy'],
+      distinctiveMoves: [
+        'Use product hierarchy and buying cues without turning the interface into a discount template.',
+        'Keep decision-critical information prominent while secondary merchandising stays quiet.',
+        'Let imagery and spacing create premium perception before decorative effects do.',
+      ],
+    };
+  }
+
+  if (aggregateText.includes('dashboard') || aggregateText.includes('operations') || aggregateText.includes('report')) {
+    return {
+      brandAdjectives: ['calm', 'precise', 'trustworthy'],
+      antiAdjectives: ['chaotic', 'gimmicky', 'visually exhausting'],
+      distinctiveMoves: [
+        'Prioritize scanning clarity and status recognition over decorative density.',
+        'Use visual weight to separate signal from operational noise.',
+        'Reserve strong accents for alerts, decisions, and state transitions only.',
+      ],
+    };
+  }
+
+  if (aggregateText.includes('developer') || aggregateText.includes('api') || aggregateText.includes('platform')) {
+    return {
+      brandAdjectives: ['precise', 'technical', 'transparent'],
+      antiAdjectives: ['vague', 'marketing-heavy', 'template-polished'],
+      distinctiveMoves: [
+        'Make structure and feedback feel exact without becoming sterile.',
+        'Use code-adjacent rhythm and hierarchy to build trust with technical users.',
+        'Keep complexity legible through spacing, grouping, and explicit interaction states.',
+      ],
+    };
+  }
+
+  if (aggregateText.includes('content') || aggregateText.includes('community') || aggregateText.includes('publish')) {
+    return {
+      brandAdjectives: ['editorial', 'warm', 'expressive'],
+      antiAdjectives: ['flat', 'anonymous', 'feed-generic'],
+      distinctiveMoves: [
+        'Build a strong reading rhythm so content feels curated rather than dumped into cards.',
+        'Use contrast and spacing to guide attention between creation, moderation, and discovery.',
+        'Give key interaction moments personality without sacrificing clarity.',
+      ],
+    };
+  }
+
+  return {
+    brandAdjectives: ['clear', 'human', 'distinct'],
+    antiAdjectives: ['generic', 'template-like', 'trend-chasing'],
+    distinctiveMoves: [
+      'Create a visual direction with one memorable tension instead of stacking fashionable effects.',
+      'Use rhythm, hierarchy, and motion intentionally so the interface feels authored.',
+      'Keep the system flexible enough to evolve with product scope without losing identity.',
+    ],
+  };
+}
+
+function buildDesignIntentSeed({
+  discoveryAnswers,
+  initContext,
+  architectureRecommendation,
+}) {
+  const inferredKeywords = inferDesignKeywords(discoveryAnswers);
+  const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
+
+  return `${JSON.stringify({
+    mode: 'dynamic',
+    status: 'seed-needs-design-synthesis',
+    project: {
+      name: discoveryAnswers.projectName,
+      context: discoveryAnswers.projectDescription,
+      domain: discoveryAnswers.primaryDomain,
+      stack: toTitleCase(initContext.stackFileName),
+      blueprint: toTitleCase(initContext.blueprintFileName),
+    },
+    brandAdjectives: inferredKeywords.brandAdjectives,
+    antiAdjectives: inferredKeywords.antiAdjectives,
+    visualDirection: {
+      trendStance: 'trend-aware-not-trend-chasing',
+      distinctiveMoves: inferredKeywords.distinctiveMoves,
+      copiedReferenceAllowed: false,
+    },
+    experiencePrinciples: [
+      'Design must feel project-specific, not interchangeable with generic SaaS templates.',
+      'Major interface decisions must be explainable in product and user terms.',
+      'Accessibility, responsiveness, and implementation realism are non-negotiable.',
+    ],
+    forbiddenPatterns: [
+      'generic-saas-hero',
+      'copycat-brand-system',
+      'unjustified-default-gradients',
+      'placeholder-design-language',
+    ],
+    requiredDesignSections: [
+      'Design Intent and Product Personality',
+      'Audience and Use-Context Signals',
+      'Visual Direction and Distinctive Moves',
+      'Color System and Semantic Roles',
+      'Typography System and Hierarchy',
+      'Spacing, Layout Rhythm, and Density Strategy',
+      'Interaction, Motion, and Feedback Rules',
+      'Component Language and Shared Patterns',
+      'Accessibility Non-Negotiables',
+      'Responsive Strategy',
+      'Anti-Patterns to Avoid',
+      'Implementation Notes for Future UI Tasks',
+    ],
+    implementation: {
+      requiredDeliverables: ['docs/DESIGN.md', 'docs/design-intent.json'],
+      requireDesignRationale: true,
+      requireDistinctVisualDirection: true,
+      requireMachineReadableContract: true,
+      bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
+    },
+    architectSignals: designSignals,
+  }, null, 2)}\n`;
+}
+
 function buildProjectContextBootstrapPrompt({
   discoveryAnswers,
   initContext,
@@ -576,35 +520,61 @@ function buildDesignBootstrapPrompt({
 }) {
   const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
   const designSignalsJson = JSON.stringify(designSignals, null, 2);
+  const designIntentSeed = buildDesignIntentSeed({
+    discoveryAnswers,
+    initContext,
+    architectureRecommendation,
+  });
 
   return [
-    '# Bootstrap Prompt: Dynamic DESIGN.md Synthesis',
+    '# Bootstrap Prompt: Dynamic Design Contract Synthesis',
     '',
     `Protocol version: ${PROJECT_DOC_SYNTHESIS_PROMPT_VERSION}`,
     '',
     'You are the Lead UI/UX Art Director for this project.',
-    'Write docs/DESIGN.md from zero. Do not use generic template prose.',
+    '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 Sections',
+    '## Required DESIGN.md Sections',
     '1. Design Vision and Product Personality',
-    '2. Theme and Atmosphere Direction',
-    '3. Color System (tokens, semantic roles, accessibility rationale)',
-    '4. Typography System (pairing, scale, usage rules)',
-    '5. Spacing and Layout Rhythm',
-    '6. Motion and Interaction Principles',
-    '7. Component Language (cards, forms, nav, states)',
-    '8. Do and Don\'t Rules',
+    '2. Audience and Use-Context Signals',
+    '3. Visual Direction and Distinctive Moves',
+    '4. Color System (tokens, semantic roles, accessibility rationale)',
+    '5. Typography System (pairing, scale, usage rules)',
+    '6. Spacing, Layout Rhythm, and Density Strategy',
+    '7. Motion and Interaction Principles',
+    '8. Component Language (cards, forms, nav, states)',
     '9. Accessibility Non-Negotiables',
-    '10. Redesign Protocol (how to evolve without breaking design identity)',
+    '10. Responsive Strategy',
+    '11. Anti-Patterns to Avoid',
+    '12. Implementation Notes for Future UI Tasks',
+    '',
+    '## Required design-intent.json Fields',
+    '1. mode',
+    '2. status',
+    '3. project',
+    '4. brandAdjectives',
+    '5. antiAdjectives',
+    '6. visualDirection',
+    '7. experiencePrinciples',
+    '8. forbiddenPatterns',
+    '9. requiredDesignSections',
+    '10. 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.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -619,10 +589,17 @@ function buildDesignBootstrapPrompt({
     designSignalsJson || 'null',
     '```',
     '',
+    '## 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 docs/DESIGN.md with complete content.',
-    '2. Ensure rules are practical for implementation and review.',
-    '3. After DESIGN.md exists, use it as first-class source for future UI tasks.',
+    '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');
 }
@@ -643,12 +620,14 @@ export async function generateProjectDocumentation(
 
   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;
@@ -677,8 +656,19 @@ export async function generateProjectDocumentation(
     await fs.writeFile(path.join(promptsDirectoryPath, designPromptFileName), designPromptContent, 'utf8');
     generatedPromptFileNames.push(designPromptFileName);
 
-    if (!expectedDocFileNames.includes('DESIGN.md')) {
-      expectedDocFileNames.push('DESIGN.md');
+    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);
+      }
     }
   }
 
@@ -686,6 +676,7 @@ export async function generateProjectDocumentation(
     docsDirectoryPath,
     generatedFileNames: expectedDocFileNames,
     generatedPromptFileNames,
+    materializedFileNames,
     bootstrapMode: 'ai-synthesis',
     synthesisPromptVersion: PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
     templateVersion: PROJECT_DOC_TEMPLATE_VERSION,