universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/src/flows/init-flow.js

@@ -11,7 +11,8 @@ import {
   promptContentMode,
   promptMethodology,
   promptCommandsInstallation,
-  handleAgentsMdSharing
+  handleAgentsMdSharing,
+  promptAgentsMd
 } from '../prompts/init.js';
 import {
   promptIntegrationConfig
@@ -84,6 +85,15 @@ export async function runInitFlow(options, detected, projectPath) {
   // === STEP 3: Handle AGENTS.md sharing ===
   aiTools = handleAgentsMdSharing(aiTools);
 
+  // === STEP 3.5: AGENTS.md universal output ===
+  let generateAgentsMd = false;
+  if (!options.agentsMd && options.agentsMd !== false) {
+    // No explicit flag — prompt user (only if codex/opencode not selected)
+    generateAgentsMd = await promptAgentsMd(aiTools);
+  } else {
+    generateAgentsMd = !!options.agentsMd;
+  }
+
   const skillsSupportedTools = aiTools.filter(tool => {
     const config = getAgentConfig(tool);
     return config?.supportsSkills && config?.skills;
@@ -159,12 +169,17 @@ export async function runInitFlow(options, detected, projectPath) {
   }
 
   // === STEP 6: Standards Format ===
+  // Default to 'ai'; only prompt when --experimental flag is used
   if (!format) {
-    format = await promptFormat();
+    if (options.experimental) {
+      format = await promptFormat();
+    } else {
+      format = 'ai';
+    }
   }
 
   // === STEP 7: Standard Options ===
-  standardOptions = await promptStandardOptions(3, displayLanguage);
+  standardOptions = await promptStandardOptions(3, displayLanguage, { experimental: options.experimental });
 
   // === STEP 8: Language Extensions ===
   if (!languages) {
@@ -203,8 +218,9 @@ export async function runInitFlow(options, detected, projectPath) {
   skillsConfig.integrationConfigs = integrationConfigs;
 
   // === STEP 11: Content Mode ===
-  let contentMode = 'minimal';
-  if (aiTools.length > 0) {
+  // Default to 'index'; only prompt when --experimental flag is used
+  let contentMode = 'index';
+  if (aiTools.length > 0 && options.experimental) {
     contentMode = await promptContentMode();
   }
   skillsConfig.contentMode = contentMode;
@@ -226,6 +242,7 @@ export async function runInitFlow(options, detected, projectPath) {
     skillsConfig,
     aiTools,
     integrations,
-    contentMode
+    contentMode,
+    generateAgentsMd
   };
 }

package/src/i18n/messages.js

@@ -338,6 +338,14 @@ export const messages = {
       }
     },
 
+    // AGENTS.md Universal Output
+    agentsMdPrompt: {
+      title: 'AGENTS.md (Universal Standard)',
+      description: 'AGENTS.md is an open standard (AAIF) supported by 60K+ open source projects.',
+      description2: 'Generating it allows Copilot, Jules, Codex, and other tools to auto-read your project standards.',
+      question: 'Generate AGENTS.md as a universal standards summary?'
+    },
+
     // AI Tools Selection
     aiTools: {
       title: 'AI Development Tools',
@@ -961,6 +969,9 @@ export const messages = {
         generatingClaudeMd: 'Generating CLAUDE.md...',
         generatedClaudeMd: 'Generated CLAUDE.md',
         couldNotGenerateClaudeMd: 'Could not generate CLAUDE.md',
+        generatingAgentsMd: 'Generating AGENTS.md (universal summary)...',
+        generatedAgentsMd: 'Generated AGENTS.md (universal summary)',
+        couldNotGenerateAgentsMd: 'Could not generate AGENTS.md',
         installingSkills: 'Installing Claude Code Skills...',
         installedSkills: 'Installed {count} Skills to {locations}',
         installedSkillsWithErrors: 'Installed {count} Skills with {errors} errors',
@@ -1103,7 +1114,12 @@ export const messages = {
         duplicatesFound: 'Found duplicate installations:',
         duplicatesCleaned: 'Cleaned {count} duplicate installation(s)',
         legacyCleaned: 'Cleaned {count} legacy command file(s)',
-        noDuplicatesFound: 'No duplicate installations found'
+        noDuplicatesFound: 'No duplicate installations found',
+        // Post-update integrity check
+        missingAfterUpdate: '⚠ {count} file(s) still missing after update',
+        restoreMissingPrompt: 'Restore {count} missing file(s)?',
+        restoringMissing: 'Restoring missing files...',
+        restoredCount: 'Restored {restored}/{total} file(s)'
       },
 
       // configure command
@@ -1552,6 +1568,14 @@ export const messages = {
       }
     },
 
+    // AGENTS.md 通用輸出
+    agentsMdPrompt: {
+      title: 'AGENTS.md（通用標準）',
+      description: 'AGENTS.md 是 AAIF 管理的開放標準，60K+ 開源專案採用。',
+      description2: '生成後，Copilot、Jules、Codex 等工具可自動讀取您的專案標準。',
+      question: '是否生成 AGENTS.md 作為通用標準摘要？'
+    },
+
     // AI Tools Selection
     aiTools: {
       title: 'AI 開發工具',
@@ -2175,6 +2199,9 @@ export const messages = {
         generatingClaudeMd: '產生 CLAUDE.md 中...',
         generatedClaudeMd: '已產生 CLAUDE.md',
         couldNotGenerateClaudeMd: '無法產生 CLAUDE.md',
+        generatingAgentsMd: '產生 AGENTS.md（通用摘要）中...',
+        generatedAgentsMd: '已產生 AGENTS.md（通用摘要）',
+        couldNotGenerateAgentsMd: '無法產生 AGENTS.md',
         installingSkills: '安裝 Claude Code Skills 中...',
         installedSkills: '已安裝 {count} 個 Skills 到 {locations}',
         installedSkillsWithErrors: '已安裝 {count} 個 Skills，有 {errors} 個錯誤',
@@ -2317,7 +2344,12 @@ export const messages = {
         duplicatesFound: '發現重複安裝：',
         duplicatesCleaned: '已清理 {count} 個重複安裝',
         legacyCleaned: '已清理 {count} 個舊版命令檔案',
-        noDuplicatesFound: '未發現重複安裝'
+        noDuplicatesFound: '未發現重複安裝',
+        // Post-update integrity check
+        missingAfterUpdate: '⚠ 更新後仍有 {count} 個檔案缺失',
+        restoreMissingPrompt: '是否批次還原 {count} 個缺失的檔案？',
+        restoringMissing: '正在還原缺失的檔案...',
+        restoredCount: '已還原 {restored}/{total} 個檔案'
       },
 
       // configure command
@@ -2766,6 +2798,14 @@ export const messages = {
       }
     },
 
+    // AGENTS.md 通用输出
+    agentsMdPrompt: {
+      title: 'AGENTS.md（通用标准）',
+      description: 'AGENTS.md 是 AAIF 管理的开放标准，60K+ 开源项目采用。',
+      description2: '生成后，Copilot、Jules、Codex 等工具可自动读取您的项目标准。',
+      question: '是否生成 AGENTS.md 作为通用标准摘要？'
+    },
+
     // AI Tools Selection
     aiTools: {
       title: 'AI 开发工具',
@@ -3135,6 +3175,9 @@ export const messages = {
         generatingClaudeMd: '正在生成 CLAUDE.md...',
         generatedClaudeMd: '已生成 CLAUDE.md',
         couldNotGenerateClaudeMd: '无法生成 CLAUDE.md',
+        generatingAgentsMd: '正在生成 AGENTS.md（通用摘要）...',
+        generatedAgentsMd: '已生成 AGENTS.md（通用摘要）',
+        couldNotGenerateAgentsMd: '无法生成 AGENTS.md',
         installingSkills: '正在安装 Claude Code Skills...',
         installedSkills: '已安装 {count} 个 Skills 到 {locations}',
         installedSkillsWithErrors: '已安装 {count} 个 Skills，有 {errors} 个错误',
@@ -3460,7 +3503,12 @@ export const messages = {
         duplicatesFound: '发现重复安装：',
         duplicatesCleaned: '已清理 {count} 个重复安装',
         legacyCleaned: '已清理 {count} 个旧版命令文件',
-        noDuplicatesFound: '未发现重复安装'
+        noDuplicatesFound: '未发现重复安装',
+        // Post-update integrity check
+        missingAfterUpdate: '⚠ 更新后仍有 {count} 个文件缺失',
+        restoreMissingPrompt: '是否批量还原 {count} 个缺失的文件？',
+        restoringMissing: '正在还原缺失的文件...',
+        restoredCount: '已还原 {restored}/{total} 个文件'
       },
 
       // configure command

package/src/installers/integration-installer.js

@@ -3,7 +3,8 @@ import { copyIntegration } from '../utils/copier.js';
 import {
   writeIntegrationFile,
   integrationFileExists,
-  getToolFilePath
+  getToolFilePath,
+  writeAgentsMdSummary
 } from '../utils/integration-generator.js';
 import { calculateCategoriesFromStandards } from '../utils/reference-sync.js';
 import { t } from '../i18n/messages.js';
@@ -83,7 +84,8 @@ export async function installIntegrations(config, projectPath) {
   const results = {
     integrations: [],
     errors: [],
-    integrationBlockHashes: {}
+    integrationBlockHashes: {},
+    manifestIntegrationConfigs: {}
   };
 
   // Early return if no integrations to install
@@ -136,6 +138,17 @@ export async function installIntegrations(config, projectPath) {
           installedAt: new Date().toISOString()
         };
       }
+
+      // Collect integration config for manifest (enables sync-refs regeneration)
+      results.manifestIntegrationConfigs[result.path] = {
+        tool: enhancedConfig.tool,
+        categories: enhancedConfig.categories,
+        language: enhancedConfig.language,
+        installedStandards: [...enhancedConfig.installedStandards],
+        contentMode: enhancedConfig.contentMode,
+        level: enhancedConfig.level,
+        commitLanguage: enhancedConfig.commitLanguage,
+      };
     } else {
       // Fall back to legacy static file copy
       const mapping = INTEGRATION_MAPPINGS[tool];
@@ -235,3 +248,55 @@ export async function generateClaudeMd(config, projectPath) {
     return { path: null, error: result.error };
   }
 }
+
+/**
+ * Generate universal AGENTS.md summary if requested and not already generated
+ *
+ * @param {Object} config - Installation configuration
+ * @param {boolean} config.generateAgentsMd - Whether to generate AGENTS.md
+ * @param {string[]} config.aiTools - Selected AI tools
+ * @param {string[]} config.installedStandards - Installed standard file names
+ * @param {Object} config.standardOptions - Standard options
+ * @param {string} config.displayLanguage - Display language
+ * @param {Object} integrationResults - Results from installIntegrations
+ * @param {string[]} integrationResults.integrations - List of generated integration files
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Result with path and blockHashInfo
+ */
+export async function generateUniversalAgentsMd(config, integrationResults, projectPath) {
+  // Skip if not requested
+  if (!config.generateAgentsMd) {
+    return { path: null, error: null };
+  }
+
+  // Skip if AGENTS.md was already generated by codex/opencode integration
+  const alreadyGenerated = (integrationResults.integrations || []).includes('AGENTS.md');
+  if (alreadyGenerated) {
+    return { path: null, error: null };
+  }
+
+  const msg = t().commands.init;
+  const spinner = ora(msg.generatingAgentsMd || 'Generating AGENTS.md...').start();
+
+  const commitLanguage = config.commitLanguage ||
+    config.standardOptions?.commit_language ||
+    config.skillsConfig?.commitLanguage ||
+    'english';
+
+  const summaryConfig = {
+    installedStandards: config.installedStandards || [],
+    language: config.displayLanguage || config.commonLanguage || 'en',
+    commitLanguage,
+    standardOptions: config.standardOptions || {}
+  };
+
+  const result = writeAgentsMdSummary(summaryConfig, projectPath);
+
+  if (result.success) {
+    spinner.succeed(msg.generatedAgentsMd || 'Generated AGENTS.md (universal summary)');
+    return { path: result.path, error: null, blockHashInfo: result.blockHashInfo };
+  } else {
+    spinner.warn(msg.couldNotGenerateAgentsMd || 'Could not generate AGENTS.md');
+    return { path: null, error: result.error };
+  }
+}

package/src/installers/manifest-installer.js

@@ -37,6 +37,7 @@ export function writeFinalManifest(config, results, projectPath) {
       commit_language: config.standardOptions?.commit_language || null,
       test_levels: config.standardOptions?.test_levels || []
     },
+    generateAgentsMd: config.generateAgentsMd || false,
     aiTools: config.aiTools || [],
     skills: {
       installed: config.skillsConfig?.installed || false,

package/src/installers/standards-installer.js

@@ -161,10 +161,11 @@ export async function installStandards(config, projectPath) {
 
   // Helper to compute and store hash
   const addFileHash = (relativePath) => {
-    const fullPath = join(projectPath, relativePath);
+    const normalizedPath = relativePath.replace(/\\/g, '/');
+    const fullPath = join(projectPath, normalizedPath);
     const hashInfo = computeFileHash(fullPath);
     if (hashInfo) {
-      results.fileHashes[relativePath] = {
+      results.fileHashes[normalizedPath] = {
         ...hashInfo,
         installedAt: now
       };

package/src/prompts/init.js

@@ -822,13 +822,18 @@ export async function promptTestLevels() {
  * @param {string} displayLanguage - Display language for bilingual commit option filtering
  * @returns {Promise<Object>} Selected options
  */
-export async function promptStandardOptions(level, displayLanguage = 'en') {
+export async function promptStandardOptions(level, displayLanguage = 'en', opts = {}) {
   const options = {};
 
   // Git workflow options (level 2+)
   if (level >= 2) {
     options.workflow = await promptGitWorkflow();
-    options.merge_strategy = await promptMergeStrategy();
+    // Merge strategy: default to 'squash'; only prompt with --experimental
+    if (opts.experimental) {
+      options.merge_strategy = await promptMergeStrategy();
+    } else {
+      options.merge_strategy = 'squash';
+    }
   }
 
   // Commit message options (level 1+)
@@ -836,8 +841,13 @@ export async function promptStandardOptions(level, displayLanguage = 'en') {
   options.commit_language = await promptCommitLanguage(displayLanguage);
 
   // Testing options (level 2+)
+  // Default to all 4 levels; only prompt with --experimental
   if (level >= 2) {
-    options.test_levels = await promptTestLevels();
+    if (opts.experimental) {
+      options.test_levels = await promptTestLevels();
+    } else {
+      options.test_levels = ['unit-testing', 'integration-testing', 'system-testing', 'e2e-testing'];
+    }
   }
 
   return options;
@@ -1137,6 +1147,43 @@ export async function promptContentMode() {
   return mode;
 }
 
+/**
+ * Prompt for universal AGENTS.md generation
+ * Shown when user has NOT selected codex/opencode (which already generate AGENTS.md)
+ *
+ * @param {string[]} selectedTools - Selected AI tools
+ * @returns {Promise<boolean>} True if user wants AGENTS.md generated
+ */
+export async function promptAgentsMd(selectedTools) {
+  const hasCodex = selectedTools.includes('codex');
+  const hasOpencode = selectedTools.includes('opencode');
+
+  // Skip if codex/opencode already selected (they generate AGENTS.md)
+  if (hasCodex || hasOpencode) {
+    return false;
+  }
+
+  const msg = t().agentsMdPrompt || {};
+
+  console.log();
+  console.log(chalk.cyan(msg.title || 'AGENTS.md (Universal Standard)'));
+  console.log(chalk.gray(`  ${msg.description || 'AGENTS.md is an open standard supported by 60K+ projects.'}`));
+  console.log(chalk.gray(`  ${msg.description2 || 'Generating it allows Copilot, Jules, Codex, and other tools to read your project standards.'}`));
+  console.log();
+
+  const { generate } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'generate',
+      message: msg.question || 'Generate AGENTS.md as a universal standards summary?',
+      suffix: ' ',
+      default: true
+    }
+  ]);
+
+  return generate;
+}
+
 /**
  * Handle AGENTS.md sharing notification
  * When both Codex and OpenCode are selected, inform user they share the same file

package/src/reconciler/manifest-migrator.js

@@ -101,9 +101,9 @@ export function backfillFileHashes(projectPath, manifest) {
 
   // Backfill standard file hashes
   for (const standardPath of (updated.standards || [])) {
-    const relativePath = standardPath.startsWith('.standards/')
+    const relativePath = (standardPath.startsWith('.standards/')
       ? standardPath
-      : `.standards/${standardPath}`;
+      : `.standards/${standardPath}`).replace(/\\/g, '/');
     const absPath = join(projectPath, relativePath);
 
     if (!updated.fileHashes[relativePath] && existsSync(absPath)) {

package/src/reconciler/plan-executor.js

@@ -402,6 +402,17 @@ async function executeCommandBatch(projectPath, commandActions, manifest) {
         );
 
         if (installResult.allFileHashes) {
+          // Clean up stale entries for agents being updated before merging
+          const updatedPrefixes = new Set(
+            Object.keys(installResult.allFileHashes).map(k => k.split('/')[0])
+          );
+          for (const prefix of updatedPrefixes) {
+            for (const key of Object.keys(manifest.commandHashes)) {
+              if (key.startsWith(prefix + '/')) {
+                delete manifest.commandHashes[key];
+              }
+            }
+          }
           Object.assign(manifest.commandHashes, installResult.allFileHashes);
         }