agents-templated 1.2.10 → 1.2.11

package/README.md

@@ -120,11 +120,11 @@ Agents Templated automatically configures 4 major AI coding assistants:
 | AI Agent | Config File | Auto-Discovery |
 |----------|-------------|----------------|
 | **Cursor** | `.cursorrules` | ✅ Auto-loads in Cursor IDE |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ Auto-loads in VS Code |
-| **Claude** | `CLAUDE.md` | ✅ Auto-loads in Claude IDE/API |
-| **Gemini** | `GEMINI.md` | ✅ Auto-loads in Gemini IDE/API |
+| **GitHub Copilot** | `.github/instructions/copilot-instructions.md` (+ shim `.github/copilot-instructions.md`) | ✅ Auto-loads in VS Code |
+| **Claude** | `.github/instructions/CLAUDE.md` (+ shim `CLAUDE.md`) | ✅ Compatible |
+| **Gemini** | `.github/instructions/GEMINI.md` (+ shim `GEMINI.md`) | ✅ Compatible |
 
-**All agents follow the same standards:** `agents/rules/` contains behavior rules, and `agents/commands/` contains deterministic slash-command contracts.
+**Single source of truth:** `instructions/source/core.md` drives generated tool-compatible instruction files.
 
 ---
 
@@ -134,13 +134,21 @@ When you run `agents-templated init`, you get:
 
 ```
 your-project/
+├── instructions/
+│   └── source/
+│       └── core.md               # Canonical instruction source of truth
+│
 ├── agent-docs/                      # 📚 Comprehensive documentation
-│   ├── AGENTS.MD                   # AI assistant guide
 │   ├── ARCHITECTURE.md             # Project architecture & tech stack
 │   └── README.md                   # Human-readable setup guide
 │
-├── agents/                          # 🤖 AI Agent rules and skills
-│   ├── rules/
+├── .github/
+│   ├── instructions/                # Canonical generated instructions
+│   │   ├── AGENTS.md
+│   │   ├── copilot-instructions.md
+│   │   ├── CLAUDE.md
+│   │   ├── GEMINI.md
+│   │   └── rules/
 │   │   ├── core.mdc               # Core development principles
 │   │   ├── security.mdc           # Security patterns (CRITICAL)
 │   │   ├── testing.mdc            # Testing strategy
@@ -151,7 +159,18 @@ your-project/
 │   │   ├── intent-routing.mdc     # Intent-to-command routing policy
 │   │   ├── system-workflow.mdc    # End-to-end delivery lifecycle gates
 │   │   └── hardening.mdc          # Hardening and obfuscation guidance
-│   ├── commands/
+│   ├── skills/
+│   │   ├── find-skills/           # Skill discovery helper
+│   │   ├── feature-delivery/      # Scoped feature delivery workflow
+│   │   ├── bug-triage/            # Reproduction-first defect workflow
+│   │   ├── app-hardening/         # Hardening and release-evidence workflow
+│   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
+│   │   ├── README.md              # Guide for creating custom skills
+│   │   └── [your-custom-skills]/  # Your project-specific skills
+│   └── copilot-instructions.md    # Compatibility shim for Copilot
+│
+├── agents/                          # 🤖 Deterministic command contracts
+│   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
 │   │   ├── plan.md                # /plan contract
 │   │   ├── fix.md                 # /fix contract
@@ -159,20 +178,10 @@ your-project/
 │   │   ├── release.md             # /release contract
 │   │   ├── ...                    # Other command contracts
 │   │   └── README.md              # Commands directory guide
-│   └── skills/
-│       ├── find-skills/           # Skill discovery helper
-│       ├── feature-delivery/      # Scoped feature delivery workflow
-│       ├── bug-triage/            # Reproduction-first defect workflow
-│       ├── app-hardening/         # Hardening and release-evidence workflow
-│       ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
-│       ├── README.md              # Guide for creating custom skills
-│       └── [your-custom-skills]/  # Your project-specific skills
-│
-├── .github/
-│   └── copilot-instructions.md    # GitHub Copilot config
 │
-├── CLAUDE.md                       # Claude AI config
-├── GEMINI.md                       # Gemini AI config
+├── AGENTS.MD                        # Compatibility shim for generic agents
+├── CLAUDE.md                        # Compatibility shim for Claude tooling
+├── GEMINI.md                        # Compatibility shim for Gemini tooling
 ├── .cursorrules                    # Cursor IDE config
 ├── .gitignore                      # Pre-configured Git ignore
 └── README.md                       # Project documentation

package/bin/cli.js

@@ -6,6 +6,19 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 const { version } = require('../package.json');
+const {
+  LAYOUT,
+  resolveRulesDir,
+  resolveSkillsDir,
+  hasAnyLayout,
+  getLegacyMigrationPlan
+} = require('../lib/layout');
+const {
+  CORE_SOURCE_REL_PATH,
+  GENERATED_INSTRUCTION_PATHS,
+  writeGeneratedInstructions,
+  validateInstructionDrift
+} = require('../lib/instructions');
 
 // Resolve the templates directory - works in both dev and installed contexts
 const getTemplatesDir = () => {
@@ -104,8 +117,8 @@ program
             choices: [
               { name: 'All components', value: 'all' },
               { name: 'Documentation files (agent-docs/)', value: 'docs' },
-              { name: 'Agent rules (agents/rules/*.mdc)', value: 'rules' },
-              { name: 'Skills (agents/skills/*)', value: 'skills' },
+              { name: 'Agent rules (.github/instructions/rules/*.mdc)', value: 'rules' },
+              { name: 'Skills (.github/skills/*)', value: 'skills' },
               { name: 'AI Agent instructions (Cursor, Copilot, VSCode, Gemini)', value: 'github' }
             ],
             default: ['all']
@@ -136,18 +149,19 @@ program
       if (installAll || choices.includes('docs')) {
         console.log(chalk.yellow('Installing documentation files...'));
         const sourceDir = path.join(templateDir, 'agent-docs');
-        const targetDir = path.join(targetDir, 'agent-docs');
-        await fs.ensureDir(targetDir);
-        await copyDirectory(sourceDir, targetDir, options.force);
+        const targetDocsDir = path.join(targetDir, 'agent-docs');
+        await fs.ensureDir(targetDocsDir);
+        await copyDirectory(sourceDir, targetDocsDir, options.force);
+        await copyFiles(templateDir, targetDir, [CORE_SOURCE_REL_PATH], options.force);
       }
 
       // Install agent rules
       if (installAll || choices.includes('rules')) {
         console.log(chalk.yellow('Installing agent rules...'));
-        await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.rulesDir));
         await copyDirectory(
           path.join(templateDir, 'agents', 'rules'),
-          path.join(targetDir, 'agents', 'rules'),
+          path.join(targetDir, LAYOUT.canonical.rulesDir),
           options.force
         );
       }
@@ -155,10 +169,10 @@ program
       // Install skills
       if (installAll || choices.includes('skills')) {
         console.log(chalk.yellow('Installing skills...'));
-        await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.skillsDir));
         await copyDirectory(
           path.join(templateDir, 'agents', 'skills'),
-          path.join(targetDir, 'agents', 'skills'),
+          path.join(targetDir, LAYOUT.canonical.skillsDir),
           options.force
         );
       }
@@ -166,24 +180,20 @@ program
       // Install AI Agent instructions (Cursor, Copilot, Claude, Gemini)
       if (installAll || choices.includes('github')) {
         console.log(chalk.yellow('Installing AI agent instructions...'));
-        await fs.ensureDir(path.join(targetDir, '.github'));
-        await copyFiles(templateDir, targetDir, [
-          '.cursorrules',
-          '.github/copilot-instructions.md',
-          'CLAUDE.md',
-          'GEMINI.md'
-        ], options.force);
+        await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
+        await copyFiles(templateDir, targetDir, ['.cursorrules'], options.force);
+        await writeGeneratedInstructions(targetDir, templateDir, options.force);
         console.log(chalk.gray('  ✓ Cursor (.cursorrules)'));
-        console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md)'));
-        console.log(chalk.gray('  ✓ Claude (CLAUDE.md)'));
-        console.log(chalk.gray('  ✓ Google Gemini (GEMINI.md)'));
+        console.log(chalk.gray('  ✓ GitHub Copilot (.github/instructions/copilot-instructions.md + compat shim)'));
+        console.log(chalk.gray('  ✓ Claude (.github/instructions/CLAUDE.md + compat shim)'));
+        console.log(chalk.gray('  ✓ Google Gemini (.github/instructions/GEMINI.md + compat shim)'));
       }
 
       console.log(chalk.green.bold('\nInstallation complete!\n'));
       console.log(chalk.cyan('Next steps:'));
-      console.log(chalk.white('  1. Review AGENTS.MD for generic AI assistant guide'));
+      console.log(chalk.white('  1. Review instructions/source/core.md (canonical AI guide)'));
       console.log(chalk.white('  2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
-      console.log(chalk.white('  3. Review AGENTS.MD for AI assistant guide'));
+      console.log(chalk.white('  3. Review .github/instructions/ for generated tool-compatible files'));
       console.log(chalk.white('  4. Configure your AI assistant (Cursor, Copilot, etc.)'));
       console.log(chalk.white('  5. Adapt the rules to your technology stack\n'));
 
@@ -302,15 +312,16 @@ program
         const targetDocsDir = path.join(targetDir, 'agent-docs');
         await fs.ensureDir(targetDocsDir);
         await copyDirectory(sourceDocsDir, targetDocsDir, options.force);
+        await copyFiles(templateDir, targetDir, [CORE_SOURCE_REL_PATH], options.force);
       }
 
       // Install agent rules
       if (options.rules) {
         console.log(chalk.yellow('Installing agent rules...'));
-        await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.rulesDir));
         await copyDirectory(
           path.join(templateDir, 'agents', 'rules'),
-          path.join(targetDir, 'agents', 'rules'),
+          path.join(targetDir, LAYOUT.canonical.rulesDir),
           options.force
         );
       }
@@ -318,10 +329,10 @@ program
       // Install skills
       if (options.skills) {
         console.log(chalk.yellow('Installing skills...'));
-        await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.skillsDir));
         await copyDirectory(
           path.join(templateDir, 'agents', 'skills'),
-          path.join(targetDir, 'agents', 'skills'),
+          path.join(targetDir, LAYOUT.canonical.skillsDir),
           options.force
         );
       }
@@ -329,29 +340,24 @@ program
       // Install AI Agent instructions (Cursor, Copilot, VSCode, Gemini)
       if (options.github) {
         console.log(chalk.yellow('Installing AI agent instructions...'));
-        await fs.ensureDir(path.join(targetDir, '.github'));
-        await copyFiles(templateDir, targetDir, [
-          '.cursorrules',
-          '.github/copilot-instructions.md',
-          'AGENTS.MD',
-          'CLAUDE.md',
-          'GEMINI.md'
-        ], options.force);
+        await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
+        await copyFiles(templateDir, targetDir, ['.cursorrules'], options.force);
+        await writeGeneratedInstructions(targetDir, templateDir, options.force);
         console.log(chalk.gray('  ✓ Cursor (.cursorrules)'));
-        console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md)'));
-        console.log(chalk.gray('  ✓ Generic AI (AGENTS.MD)'));
-        console.log(chalk.gray('  ✓ Claude (CLAUDE.md)'));
-        console.log(chalk.gray('  ✓ Google Gemini (GEMINI.md)'));
+        console.log(chalk.gray('  ✓ GitHub Copilot (.github/instructions/copilot-instructions.md + compat shim)'));
+        console.log(chalk.gray('  ✓ Generic AI (.github/instructions/AGENTS.md + compat shim)'));
+        console.log(chalk.gray('  ✓ Claude (.github/instructions/CLAUDE.md + compat shim)'));
+        console.log(chalk.gray('  ✓ Google Gemini (.github/instructions/GEMINI.md + compat shim)'));
       }
 
       // Show summary and next steps
       console.log(chalk.green.bold('\n✅ Installation complete!\n'));
       
       console.log(chalk.cyan('\n📚 Next Steps:\n'));
-      console.log(chalk.white('   1. Review AGENTS.MD for AI assistant guide'));
+      console.log(chalk.white('   1. Review instructions/source/core.md (canonical AI guide)'));
       console.log(chalk.white('   2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
-      console.log(chalk.white('   3. Review AGENTS.MD for AI assistant guide'));
-      console.log(chalk.white('   4. Customize agents/rules/*.mdc for your tech stack'));
+      console.log(chalk.white('   3. Review .github/instructions/ for generated tool-compatible files'));
+      console.log(chalk.white('   4. Customize .github/instructions/rules/*.mdc for your tech stack'));
       
       console.log(chalk.cyan('\n🔒 Security Reminder:\n'));
       console.log(chalk.white('   • Review agents/rules/security.mdc'));
@@ -371,8 +377,8 @@ program
   .action(() => {
     console.log(chalk.blue.bold('\nAvailable Components:\n'));
     console.log(chalk.yellow('docs') + '    - Documentation files (agent-docs/ directory)');
-    console.log(chalk.yellow('rules') + '   - Agent rules (core, database, frontend, security, testing, style)');
-    console.log(chalk.yellow('skills') + '  - Agent skills (find-skills, ui-ux-pro-max)');
+    console.log(chalk.yellow('rules') + '   - Agent rules (.github/instructions/rules/*.mdc)');
+    console.log(chalk.yellow('skills') + '  - Agent skills (.github/skills/*)');
     console.log(chalk.yellow('github') + '  - AI Agent instructions (Cursor, Copilot, VSCode, Gemini)');
     console.log(chalk.yellow('all') + '     - All components');
     
@@ -398,13 +404,12 @@ program
       let warnings = [];
       let passed = [];
 
-      // Check documentation files
-      if (await fs.pathExists(path.join(targetDir, 'AGENTS.MD'))) {
-        passed.push(`✓ AGENTS.MD found`);
-      } else if (await fs.pathExists(path.join(targetDir, 'AGENTS.md'))) {
-        passed.push(`✓ AGENTS.md found (legacy filename)`);
+      // Check canonical source file
+      const coreSourcePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
+      if (await fs.pathExists(coreSourcePath)) {
+        passed.push(`✓ ${CORE_SOURCE_REL_PATH} found`);
       } else {
-        warnings.push(`⚠ AGENTS.MD missing - run 'agents-templated init --docs'`);
+        warnings.push(`⚠ ${CORE_SOURCE_REL_PATH} missing - run 'agents-templated init --docs'`);
       }
 
       const docFiles = ['ARCHITECTURE.md'];
@@ -424,32 +429,67 @@ program
 
       // Check agent rules
       const ruleFiles = ['core.mdc', 'security.mdc', 'testing.mdc', 'frontend.mdc', 'database.mdc', 'style.mdc'];
-      const rulesDir = path.join(targetDir, 'agents', 'rules');
-      
+      const canonicalRulesDir = path.join(targetDir, LAYOUT.canonical.rulesDir);
+      const legacyRulesDir = path.join(targetDir, LAYOUT.legacy.rulesDirs[0]);
+      const rulesDir = path.join(targetDir, resolveRulesDir(targetDir));
+
+      if (!(await fs.pathExists(canonicalRulesDir)) && await fs.pathExists(legacyRulesDir)) {
+        issues.push(`✗ Legacy rules layout detected at ${LAYOUT.legacy.rulesDirs[0]} - run 'agents-templated update --all' to migrate`);
+      }
+
       if (await fs.pathExists(rulesDir)) {
+        const relativeRulesDir = path.relative(targetDir, rulesDir) || LAYOUT.canonical.rulesDir;
         for (const file of ruleFiles) {
           if (await fs.pathExists(path.join(rulesDir, file))) {
-            passed.push(`✓ agents/rules/${file} found`);
+            passed.push(`✓ ${relativeRulesDir}/${file} found`);
           } else {
-            warnings.push(`⚠ agents/rules/${file} missing`);
+            warnings.push(`⚠ ${relativeRulesDir}/${file} missing`);
           }
         }
       } else {
-        warnings.push(`⚠ agents/rules directory missing - run 'agents-templated init --rules'`);
+        warnings.push(`⚠ ${LAYOUT.canonical.rulesDir} directory missing - run 'agents-templated init --rules'`);
       }
 
       // Check skills
-      const skillsDir = path.join(targetDir, 'agents', 'skills');
+      const canonicalSkillsDir = path.join(targetDir, LAYOUT.canonical.skillsDir);
+      const legacySkillsDir = path.join(targetDir, LAYOUT.legacy.skillsDirs[0]);
+      const skillsDir = path.join(targetDir, resolveSkillsDir(targetDir));
+
+      if (!(await fs.pathExists(canonicalSkillsDir)) && await fs.pathExists(legacySkillsDir)) {
+        issues.push(`✗ Legacy skills layout detected at ${LAYOUT.legacy.skillsDirs[0]} - run 'agents-templated update --all' to migrate`);
+      }
+
       if (await fs.pathExists(skillsDir)) {
         const skills = await fs.readdir(skillsDir);
-        passed.push(`✓ ${skills.length} skills installed`);
+        const relativeSkillsDir = path.relative(targetDir, skillsDir) || LAYOUT.canonical.skillsDir;
+        passed.push(`✓ ${skills.length} skills installed in ${relativeSkillsDir}`);
       } else {
-        warnings.push(`⚠ agents/skills directory missing - run 'agents-templated init --skills'`);
+        warnings.push(`⚠ ${LAYOUT.canonical.skillsDir} directory missing - run 'agents-templated init --skills'`);
+      }
+
+      // Check generated instruction files and drift
+      const hasInstructionFootprint =
+        await fs.pathExists(path.join(targetDir, '.github', 'instructions')) ||
+        await fs.pathExists(path.join(targetDir, '.claude', 'rules')) ||
+        await fs.pathExists(path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.copilot)) ||
+        await fs.pathExists(path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.claude)) ||
+        await fs.pathExists(path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.gemini)) ||
+        await fs.pathExists(path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.generic));
+
+      if (hasInstructionFootprint) {
+        const instructionDrift = await validateInstructionDrift(targetDir);
+        if (instructionDrift.missingCore) {
+          issues.push(`✗ Canonical instruction source missing - run 'agents-templated init --docs --github'`);
+        } else if (!instructionDrift.ok) {
+          issues.push(`✗ Generated instruction files are out of sync: ${instructionDrift.driftFiles.join(', ')}`);
+        } else {
+          passed.push('✓ Generated instruction files are in sync with canonical source');
+        }
       }
 
-      // Check GitHub Copilot config
-      const copilotFile = path.join(targetDir, '.github', 'copilot-instructions.md');
-      if (await fs.pathExists(copilotFile)) {
+      const canonicalCopilotFile = path.join(targetDir, GENERATED_INSTRUCTION_PATHS.canonical.copilot);
+      const compatCopilotFile = path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.copilot);
+      if (await fs.pathExists(canonicalCopilotFile) || await fs.pathExists(compatCopilotFile)) {
         passed.push(`✓ GitHub Copilot configuration found`);
       } else {
         warnings.push(`⚠ GitHub Copilot configuration missing - run 'agents-templated init --github'`);
@@ -586,9 +626,9 @@ async function copyDirectory(sourceDir, targetDir, force = false) {
 }
 
 async function hasInstalledTemplates(targetDir) {
-  return await fs.pathExists(path.join(targetDir, 'AGENTS.MD')) ||
-    await fs.pathExists(path.join(targetDir, 'AGENTS.md')) ||
-    await fs.pathExists(path.join(targetDir, 'agents'));
+  return await hasAnyLayout(targetDir) ||
+    await fs.pathExists(path.join(targetDir, CORE_SOURCE_REL_PATH)) ||
+    await fs.pathExists(path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.generic));
 }
 
 async function updateSelectedComponents(targetDir, templateDir, selectedComponents, overwrite = true) {
@@ -604,38 +644,59 @@ async function updateSelectedComponents(targetDir, templateDir, selectedComponen
       path.join(targetDir, 'agent-docs'),
       overwrite
     );
+    await copyFiles(templateDir, targetDir, [CORE_SOURCE_REL_PATH], overwrite);
   }
 
   if (components.includes('rules')) {
     console.log(chalk.yellow('Updating agent rules...'));
-    await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.rulesDir));
     await copyDirectory(
       path.join(templateDir, 'agents', 'rules'),
-      path.join(targetDir, 'agents', 'rules'),
+      path.join(targetDir, LAYOUT.canonical.rulesDir),
       overwrite
     );
   }
 
   if (components.includes('skills')) {
     console.log(chalk.yellow('Updating skills...'));
-    await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.skillsDir));
     await copyDirectory(
       path.join(templateDir, 'agents', 'skills'),
-      path.join(targetDir, 'agents', 'skills'),
+      path.join(targetDir, LAYOUT.canonical.skillsDir),
       overwrite
     );
   }
 
   if (components.includes('github')) {
     console.log(chalk.yellow('Updating AI agent instructions...'));
-    await fs.ensureDir(path.join(targetDir, '.github'));
-    await copyFiles(templateDir, targetDir, [
-      '.cursorrules',
-      '.github/copilot-instructions.md',
-      'AGENTS.MD',
-      'CLAUDE.md',
-      'GEMINI.md'
-    ], overwrite);
+    await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
+    await copyFiles(templateDir, targetDir, ['.cursorrules'], overwrite);
+    await writeGeneratedInstructions(targetDir, templateDir, overwrite);
+  }
+
+  if ((components.includes('docs') || components.includes('github')) && !components.includes('github')) {
+    await writeGeneratedInstructions(targetDir, templateDir, overwrite);
+  }
+}
+
+async function applyLegacyMigrationPlan(targetDir, migrationPlan, overwrite = true) {
+  for (const move of migrationPlan) {
+    const sourcePath = path.join(targetDir, move.source);
+    const targetPath = path.join(targetDir, move.target);
+
+    if (!(await fs.pathExists(sourcePath))) {
+      continue;
+    }
+
+    await fs.ensureDir(path.dirname(targetPath));
+
+    if (await fs.pathExists(targetPath)) {
+      await copyDirectory(sourcePath, targetPath, overwrite);
+      await fs.remove(sourcePath);
+      continue;
+    }
+
+    await fs.move(sourcePath, targetPath, { overwrite });
   }
 }
 
@@ -665,6 +726,38 @@ program
         process.exit(0);
       }
 
+      const migrationPlan = await getLegacyMigrationPlan(targetDir);
+      if (migrationPlan.length > 0) {
+        console.log(chalk.yellow('Legacy layout detected. Migration to canonical Copilot-style paths is required.\n'));
+        migrationPlan.forEach(({ source, target }) => {
+          console.log(chalk.white(`  ${source}  ->  ${target}`));
+        });
+        console.log('');
+
+        if (options.checkOnly) {
+          console.log(chalk.red('Migration required before validation can pass.'));
+          console.log(chalk.gray('Run "agents-templated update" and confirm migration.\n'));
+          process.exit(1);
+        }
+
+        const migrationAnswer = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'proceed',
+            message: 'Migrate legacy directories now?',
+            default: true
+          }
+        ]);
+
+        if (!migrationAnswer.proceed) {
+          console.log(chalk.red('\nMigration skipped. Setup remains non-canonical.\n'));
+          process.exit(1);
+        }
+
+        await applyLegacyMigrationPlan(targetDir, migrationPlan, true);
+        console.log(chalk.green('✓ Legacy layout migration completed.\n'));
+      }
+
       const hasComponentSelection = options.all || options.docs || options.rules || options.skills || options.github;
 
       // Component refresh mode: update selected parts directly without stack/wizard prompts
@@ -685,20 +778,16 @@ program
 
       // List potential updates
       const updates = [];
-      const rootAgentsTargetFile = (await fs.pathExists(path.join(targetDir, 'AGENTS.MD')))
-        ? 'AGENTS.MD'
-        : ((await fs.pathExists(path.join(targetDir, 'AGENTS.md'))) ? 'AGENTS.md' : 'AGENTS.MD');
-
       const checkFiles = [
-        { targetFile: rootAgentsTargetFile, templateFile: 'AGENTS.MD', component: 'root' },
+        { targetFile: CORE_SOURCE_REL_PATH, templateFile: CORE_SOURCE_REL_PATH, component: 'root' },
         { targetFile: 'agent-docs/ARCHITECTURE.md', templateFile: 'agent-docs/ARCHITECTURE.md', component: 'docs' },
-        { targetFile: 'agents/rules/security.mdc', templateFile: 'agents/rules/security.mdc', component: 'rules' },
-        { targetFile: 'agents/rules/testing.mdc', templateFile: 'agents/rules/testing.mdc', component: 'rules' },
-        { targetFile: 'agents/rules/core.mdc', templateFile: 'agents/rules/core.mdc', component: 'rules' },
-        { targetFile: 'agents/skills/README.md', templateFile: 'agents/skills/README.md', component: 'skills' },
-        { targetFile: 'agents/skills/find-skills/SKILL.md', templateFile: 'agents/skills/find-skills/SKILL.md', component: 'skills' },
-        { targetFile: 'agents/skills/ui-ux-pro-max/SKILL.md', templateFile: 'agents/skills/ui-ux-pro-max/SKILL.md', component: 'skills' },
-        { targetFile: '.github/copilot-instructions.md', templateFile: '.github/copilot-instructions.md', component: 'github' }
+        { targetFile: `${LAYOUT.canonical.rulesDir}/security.mdc`, templateFile: 'agents/rules/security.mdc', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/testing.mdc`, templateFile: 'agents/rules/testing.mdc', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/core.mdc`, templateFile: 'agents/rules/core.mdc', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.skillsDir}/README.md`, templateFile: 'agents/skills/README.md', component: 'skills' },
+        { targetFile: `${LAYOUT.canonical.skillsDir}/find-skills/SKILL.md`, templateFile: 'agents/skills/find-skills/SKILL.md', component: 'skills' },
+        { targetFile: `${LAYOUT.canonical.skillsDir}/ui-ux-pro-max/SKILL.md`, templateFile: 'agents/skills/ui-ux-pro-max/SKILL.md', component: 'skills' },
+        { targetFile: '.cursorrules', templateFile: '.cursorrules', component: 'github' }
       ];
 
       for (const {targetFile, templateFile, component} of checkFiles) {
@@ -763,6 +852,9 @@ program
         console.log(chalk.green(`  ✓ Updated: ${targetFile}`));
       }
 
+      await writeGeneratedInstructions(targetDir, templateDir, true);
+      console.log(chalk.green('  ✓ Regenerated instruction compatibility files'));
+
       console.log(chalk.green.bold('\n✅ Updates applied successfully!\n'));
       console.log(chalk.gray('Backup files created with .backup extension\n'));
 
@@ -850,7 +942,7 @@ program
       console.log(chalk.blue('\n📚 Quick Tips:\n'));
       console.log(chalk.white('  • Run "agents-templated validate" to check setup'));
       console.log(chalk.white('  • Run "agents-templated wizard" for guided setup'));
-      console.log(chalk.white('  • Review agents/rules/security.mdc for security patterns\n'));
+      console.log(chalk.white('  • Review .github/instructions/rules/security.mdc for security patterns\n'));
 
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);

package/index.js

@@ -1,5 +1,7 @@
 const fs = require('fs-extra');
 const path = require('path');
+const { LAYOUT } = require('./lib/layout');
+const { CORE_SOURCE_REL_PATH, writeGeneratedInstructions } = require('./lib/instructions');
 
 /**
  * Programmatic API for agents-templated
@@ -26,9 +28,9 @@ async function install(targetDir, options = {}) {
   // Documentation files
   if (installAll || options.docs) {
     files.push(
-      'AGENTS.md',
       'agent-docs/ARCHITECTURE.md',
-      'agent-docs/README.md'
+      'agent-docs/README.md',
+      CORE_SOURCE_REL_PATH
     );
   }
 
@@ -49,51 +51,35 @@ async function install(targetDir, options = {}) {
 
   // Agent rules
   if (installAll || options.rules) {
-    await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.rulesDir));
     await copyDirectory(
       path.join(templateDir, 'agents', 'rules'),
-      path.join(targetDir, 'agents', 'rules'),
+      path.join(targetDir, LAYOUT.canonical.rulesDir),
       options.force
     );
   }
 
   // Skills
   if (installAll || options.skills) {
-    await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.skillsDir));
     await copyDirectory(
       path.join(templateDir, 'agents', 'skills'),
-      path.join(targetDir, 'agents', 'skills'),
+      path.join(targetDir, LAYOUT.canonical.skillsDir),
       options.force
     );
   }
 
   // AI Agent instructions (Cursor, Copilot, Claude, Gemini)
   if (installAll || options.github) {
-    await fs.ensureDir(path.join(targetDir, '.github'));
-    
-    // Copy all AI agent config files
-    const agentConfigs = [
-      '.cursorrules',
-      'CLAUDE.md',
-      'GEMINI.md'
-    ];
-    
-    for (const config of agentConfigs) {
-      const sourcePath = path.join(templateDir, config);
-      const targetPath = path.join(targetDir, config);
-      
-      if (await fs.pathExists(sourcePath)) {
-        await fs.copy(sourcePath, targetPath, { overwrite: options.force });
-      }
-    }
-    
-    // Copy GitHub Copilot instructions
-    const sourceGithubPath = path.join(templateDir, '.github', 'copilot-instructions.md');
-    const targetGithubPath = path.join(targetDir, '.github', 'copilot-instructions.md');
-    
-    if (await fs.pathExists(sourceGithubPath)) {
-      await fs.copy(sourceGithubPath, targetGithubPath, { overwrite: options.force });
+    await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
+
+    const cursorSource = path.join(templateDir, '.cursorrules');
+    const cursorTarget = path.join(targetDir, '.cursorrules');
+    if (await fs.pathExists(cursorSource)) {
+      await fs.copy(cursorSource, cursorTarget, { overwrite: options.force });
     }
+
+    await writeGeneratedInstructions(targetDir, templateDir, options.force);
   }
 }
 

package/lib/instructions.js

@@ -0,0 +1,167 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const CORE_SOURCE_REL_PATH = 'instructions/source/core.md';
+
+const GENERATED_INSTRUCTION_PATHS = {
+  canonical: {
+    generic: '.github/instructions/AGENTS.md',
+    copilot: '.github/instructions/copilot-instructions.md',
+    claude: '.github/instructions/CLAUDE.md',
+    gemini: '.github/instructions/GEMINI.md'
+  },
+  styleCompat: {
+    githubInstructions: '.github/instructions/agents.instructions.md',
+    claudeRules: '.claude/rules/claude.instructions.md'
+  },
+  compatibility: {
+    generic: 'AGENTS.MD',
+    copilot: '.github/copilot-instructions.md',
+    claude: 'CLAUDE.md',
+    gemini: 'GEMINI.md'
+  }
+};
+
+function getLegacyCoreCandidates() {
+  return ['AGENTS.MD', 'AGENTS.md'];
+}
+
+function buildHeaders(toolName) {
+  return [
+    '<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->',
+    `<!-- Source of truth: ${CORE_SOURCE_REL_PATH} -->`,
+    `<!-- Tool profile: ${toolName} -->`,
+    ''
+  ].join('\n');
+}
+
+function buildCompatInstruction(toolName, corePath) {
+  const titles = {
+    generic: '# AGENTS Instructions',
+    copilot: '# GitHub Copilot Instructions',
+    claude: '# Claude Instructions',
+    gemini: '# Gemini Instructions'
+  };
+
+  return [
+    `${titles[toolName]}`,
+    '',
+    `Primary policy source: \`${corePath}\`.`,
+    '',
+    'Always apply these mandatory rules:',
+    '- Security-first implementation (validate inputs, authz/authn, rate limiting).',
+    '- Testing-first delivery with unit + integration coverage for changed logic.',
+    '- Strong typing and runtime boundary validation.',
+    '- Do not expose secrets or sensitive data in logs/errors.',
+    '',
+    'Use the canonical source for full policy and architecture guidance.',
+    ''
+  ].join('\n');
+}
+
+function buildGeneratedArtifacts(coreContent) {
+  const corePath = CORE_SOURCE_REL_PATH;
+  const files = {};
+
+  files[GENERATED_INSTRUCTION_PATHS.canonical.generic] = `${buildHeaders('generic')}${coreContent.trim()}\n`;
+  files[GENERATED_INSTRUCTION_PATHS.canonical.copilot] = `${buildHeaders('copilot')}${buildCompatInstruction('copilot', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.canonical.claude] = `${buildHeaders('claude')}${buildCompatInstruction('claude', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.canonical.gemini] = `${buildHeaders('gemini')}${buildCompatInstruction('gemini', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.styleCompat.githubInstructions] = `${buildHeaders('github-instructions-style')}${buildCompatInstruction('generic', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.styleCompat.claudeRules] = `${buildHeaders('claude-rules-style')}${buildCompatInstruction('claude', corePath)}`;
+
+  files[GENERATED_INSTRUCTION_PATHS.compatibility.generic] = `${buildHeaders('generic-compat')}${buildCompatInstruction('generic', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.compatibility.copilot] = `${buildHeaders('copilot-compat')}${buildCompatInstruction('copilot', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.compatibility.claude] = `${buildHeaders('claude-compat')}${buildCompatInstruction('claude', corePath)}`;
+  files[GENERATED_INSTRUCTION_PATHS.compatibility.gemini] = `${buildHeaders('gemini-compat')}${buildCompatInstruction('gemini', corePath)}`;
+
+  return files;
+}
+
+async function resolveCoreContent(targetDir, templateDir) {
+  const canonicalPath = path.join(targetDir, CORE_SOURCE_REL_PATH);
+  if (await fs.pathExists(canonicalPath)) {
+    return fs.readFile(canonicalPath, 'utf8');
+  }
+
+  for (const legacyFile of getLegacyCoreCandidates()) {
+    const legacyPath = path.join(targetDir, legacyFile);
+    if (await fs.pathExists(legacyPath)) {
+      return fs.readFile(legacyPath, 'utf8');
+    }
+  }
+
+  const templateCorePath = path.join(templateDir, CORE_SOURCE_REL_PATH);
+  return fs.readFile(templateCorePath, 'utf8');
+}
+
+async function ensureCoreSource(targetDir, templateDir, force = false) {
+  const targetCorePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
+
+  if (await fs.pathExists(targetCorePath) && !force) {
+    return;
+  }
+
+  const coreContent = await resolveCoreContent(targetDir, templateDir);
+  await fs.ensureDir(path.dirname(targetCorePath));
+  await fs.writeFile(targetCorePath, coreContent, 'utf8');
+}
+
+async function writeGeneratedInstructions(targetDir, templateDir, force = false) {
+  await ensureCoreSource(targetDir, templateDir, force);
+  const corePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
+  const coreContent = await fs.readFile(corePath, 'utf8');
+  const artifacts = buildGeneratedArtifacts(coreContent);
+
+  for (const [relPath, content] of Object.entries(artifacts)) {
+    const targetPath = path.join(targetDir, relPath);
+
+    if (await fs.pathExists(targetPath) && !force) {
+      continue;
+    }
+
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, content, 'utf8');
+  }
+}
+
+async function validateInstructionDrift(targetDir) {
+  const corePath = path.join(targetDir, CORE_SOURCE_REL_PATH);
+  if (!(await fs.pathExists(corePath))) {
+    return {
+      ok: false,
+      missingCore: true,
+      driftFiles: []
+    };
+  }
+
+  const coreContent = await fs.readFile(corePath, 'utf8');
+  const expected = buildGeneratedArtifacts(coreContent);
+  const driftFiles = [];
+
+  for (const [relPath, expectedContent] of Object.entries(expected)) {
+    const filePath = path.join(targetDir, relPath);
+    if (!(await fs.pathExists(filePath))) {
+      driftFiles.push(relPath);
+      continue;
+    }
+
+    const actual = await fs.readFile(filePath, 'utf8');
+    if (actual !== expectedContent) {
+      driftFiles.push(relPath);
+    }
+  }
+
+  return {
+    ok: driftFiles.length === 0,
+    missingCore: false,
+    driftFiles
+  };
+}
+
+module.exports = {
+  CORE_SOURCE_REL_PATH,
+  GENERATED_INSTRUCTION_PATHS,
+  writeGeneratedInstructions,
+  validateInstructionDrift
+};

package/lib/layout.js

@@ -0,0 +1,95 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const LAYOUT = {
+  canonical: {
+    docsDir: 'agent-docs',
+    rulesDir: '.github/instructions/rules',
+    skillsDir: '.github/skills'
+  },
+  legacy: {
+    rulesDirs: ['agents/rules'],
+    skillsDirs: ['agents/skills']
+  },
+  compatible: {
+    rulesDirs: ['.claude/rules', '.github/instructions'],
+    skillsDirs: ['.claude/skills', '.agents/skills']
+  }
+};
+
+function firstExistingPath(baseDir, relativePaths) {
+  return relativePaths.find((relPath) => fs.existsSync(path.join(baseDir, relPath))) || null;
+}
+
+function resolveRulesDir(baseDir) {
+  const candidates = [
+    LAYOUT.canonical.rulesDir,
+    ...LAYOUT.compatible.rulesDirs,
+    ...LAYOUT.legacy.rulesDirs
+  ];
+  return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.rulesDir;
+}
+
+function resolveSkillsDir(baseDir) {
+  const candidates = [
+    LAYOUT.canonical.skillsDir,
+    ...LAYOUT.compatible.skillsDirs,
+    ...LAYOUT.legacy.skillsDirs
+  ];
+  return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.skillsDir;
+}
+
+async function hasAnyLayout(baseDir) {
+  const checks = [
+    path.join(baseDir, LAYOUT.canonical.rulesDir),
+    path.join(baseDir, LAYOUT.canonical.skillsDir),
+    ...LAYOUT.compatible.rulesDirs.map((relPath) => path.join(baseDir, relPath)),
+    ...LAYOUT.compatible.skillsDirs.map((relPath) => path.join(baseDir, relPath)),
+    ...LAYOUT.legacy.rulesDirs.map((relPath) => path.join(baseDir, relPath)),
+    ...LAYOUT.legacy.skillsDirs.map((relPath) => path.join(baseDir, relPath))
+  ];
+
+  for (const checkPath of checks) {
+    if (await fs.pathExists(checkPath)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function getLegacyMigrationPlan(baseDir) {
+  const plan = [];
+
+  for (const relPath of LAYOUT.legacy.rulesDirs) {
+    const from = path.join(baseDir, relPath);
+    if (await fs.pathExists(from)) {
+      plan.push({
+        type: 'directory',
+        source: relPath,
+        target: LAYOUT.canonical.rulesDir
+      });
+    }
+  }
+
+  for (const relPath of LAYOUT.legacy.skillsDirs) {
+    const from = path.join(baseDir, relPath);
+    if (await fs.pathExists(from)) {
+      plan.push({
+        type: 'directory',
+        source: relPath,
+        target: LAYOUT.canonical.skillsDir
+      });
+    }
+  }
+
+  return plan;
+}
+
+module.exports = {
+  LAYOUT,
+  resolveRulesDir,
+  resolveSkillsDir,
+  hasAnyLayout,
+  getLegacyMigrationPlan
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "1.2.10",
+  "version": "1.2.11",
   "description": "Technology-agnostic development template with multi-AI agent support (Cursor, Copilot, VSCode, Gemini), security-first patterns, and comprehensive testing guidelines",
   "main": "index.js",
   "bin": {
@@ -36,6 +36,7 @@
   },
   "files": [
     "bin",
+    "lib",
     "templates",
     "templates/presets",
     "index.js",

package/templates/README.md

@@ -101,11 +101,11 @@ Agents Templated automatically configures 4 major AI coding assistants:
 | AI Agent | Config File | Auto-Discovery |
 |----------|-------------|----------------|
 | **Cursor** | `.cursorrules` | ✅ Auto-loads in Cursor IDE |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ Auto-loads in VS Code |
-| **Claude** | `CLAUDE.md` | ✅ Auto-loads in Claude IDE/API |
-| **Gemini** | `GEMINI.md` | ✅ Auto-loads in Gemini IDE/API |
+| **GitHub Copilot** | `.github/instructions/copilot-instructions.md` (+ shim `.github/copilot-instructions.md`) | ✅ Auto-loads in VS Code |
+| **Claude** | `.github/instructions/CLAUDE.md` (+ shim `CLAUDE.md`) | ✅ Compatible |
+| **Gemini** | `.github/instructions/GEMINI.md` (+ shim `GEMINI.md`) | ✅ Compatible |
 
-**All agents follow the same standards:** `agents/rules/` contains behavior rules, and `agents/commands/` contains deterministic slash-command contracts.
+**Single source of truth:** `instructions/source/core.md` drives generated tool-compatible instruction files.
 
 ---
 
@@ -115,20 +115,36 @@ When you run `agents-templated init`, you get:
 
 ```
 your-project/
+├── instructions/
+│   └── source/
+│       └── core.md               # Canonical instruction source of truth
+│
 ├── agent-docs/                      # 📚 Comprehensive documentation
-│   ├── AGENTS.MD                   # AI assistant guide
 │   ├── ARCHITECTURE.md             # Project architecture & tech stack
 │   └── README.md                   # Human-readable setup guide
 │
-├── agents/                          # 🤖 AI Agent rules and skills
-│   ├── rules/
+├── .github/
+│   ├── instructions/                # Canonical generated instructions
+│   │   ├── AGENTS.md
+│   │   ├── copilot-instructions.md
+│   │   ├── CLAUDE.md
+│   │   ├── GEMINI.md
+│   │   └── rules/
 │   │   ├── core.mdc               # Core development principles
 │   │   ├── security.mdc           # Security patterns (CRITICAL)
 │   │   ├── testing.mdc            # Testing strategy
 │   │   ├── frontend.mdc           # Frontend patterns
 │   │   ├── database.mdc           # Database patterns
 │   │   └── style.mdc              # Code style guidelines
-│   ├── commands/
+│   ├── skills/
+│   │   ├── find-skills/           # Skill discovery helper
+│   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
+│   │   ├── README.md              # Guide for creating custom skills
+│   │   └── [your-custom-skills]/  # Your project-specific skills
+│   └── copilot-instructions.md    # Compatibility shim for Copilot
+│
+├── agents/                          # 🤖 Deterministic command contracts
+│   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
 │   │   ├── plan.md                # /plan contract
 │   │   ├── fix.md                 # /fix contract
@@ -136,17 +152,10 @@ your-project/
 │   │   ├── release.md             # /release contract
 │   │   ├── ...                    # Other command contracts
 │   │   └── README.md              # Commands directory guide
-│   └── skills/
-│       ├── find-skills/           # Skill discovery helper
-│       ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
-│       ├── README.md              # Guide for creating custom skills
-│       └── [your-custom-skills]/  # Your project-specific skills
-│
-├── .github/
-│   └── copilot-instructions.md    # GitHub Copilot config
 │
-├── CLAUDE.md                       # Claude AI config
-├── GEMINI.md                       # Gemini AI config
+├── AGENTS.MD                        # Compatibility shim for generic agents
+├── CLAUDE.md                        # Compatibility shim for Claude tooling
+├── GEMINI.md                        # Compatibility shim for Gemini tooling
 ├── .cursorrules                    # Cursor IDE config
 ├── .gitignore                      # Pre-configured Git ignore
 └── README.md                       # Project documentation

package/templates/instructions/source/core.md

@@ -0,0 +1,36 @@
+# Canonical AI Instructions
+
+This file is the single source of truth for project AI guidance.
+
+## Always Apply
+
+1. Security-first implementation:
+   - Validate all external inputs at boundaries.
+   - Enforce authentication and authorization on protected operations.
+   - Rate limit public endpoints.
+   - Never expose sensitive values in logs, errors, or responses.
+
+2. Testing discipline:
+   - Add tests for changed business logic.
+   - Prefer focused unit tests first, then integration tests for boundaries.
+   - Keep critical workflows covered before release.
+
+3. Type safety and reliability:
+   - Use strong typing where available.
+   - Add runtime validation at trust boundaries.
+   - Keep changes minimal, deterministic, and scoped to the requested task.
+
+## Project References
+
+- `agent-docs/ARCHITECTURE.md`
+- `agents/rules/security.mdc`
+- `agents/rules/testing.mdc`
+- `agents/rules/core.mdc`
+
+## Operational Rules
+
+- Prefer smallest safe change set.
+- Preserve existing APIs unless the task requires breaking changes.
+- Do not commit secrets or credentials.
+- Do not disable security controls to make tests pass.
+