agents-templated 1.2.9 → 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'));
 
@@ -195,89 +205,69 @@ program
 
 program
   .command('wizard')
-  .description('Interactive setup wizard with tech stack recommendations')
+  .description('Interactive setup wizard')
   .action(async () => {
     try {
       const templateDir = getTemplatesDir();
+      const targetDir = process.cwd();
       console.log(chalk.blue.bold('\n🧙 Agents Templated Setup Wizard\n'));
       console.log(chalk.gray('Let\'s set up your project with the right patterns and guidelines.\n'));
 
-      // Step 1: Tech stack selection
-      const stackAnswers = await inquirer.prompt([
-        {
-          type: 'list',
-          name: 'category',
-          message: 'What type of project is this?',
-          choices: [
-            { name: '🌐 Full-stack Web Application', value: 'fullstack' },
-            { name: '⚛️  Frontend Only', value: 'frontend' },
-            { name: '🔧 Backend API', value: 'backend' },
-            { name: '📦 NPM Package/Library', value: 'package' },
-            { name: '🤖 CLI Tool', value: 'cli' },
-            { name: '🎯 Custom/Other', value: 'custom' }
-          ]
-        }
-      ]);
+      const hasExistingSetup = await hasInstalledTemplates(targetDir);
+      if (hasExistingSetup) {
+        console.log(chalk.cyan('Detected an existing agents-templated setup in this project.\n'));
 
-      let techStack = {};
-      
-      if (stackAnswers.category === 'fullstack' || stackAnswers.category === 'frontend') {
-        const frontendAnswers = await inquirer.prompt([
+        const modeAnswer = await inquirer.prompt([
           {
             type: 'list',
-            name: 'framework',
-            message: 'Which frontend framework?',
+            name: 'mode',
+            message: 'How would you like to proceed?',
             choices: [
-              'React / Next.js',
-              'Vue / Nuxt',
-              'Angular',
-              'Svelte / SvelteKit',
-              'Vanilla JS / HTML',
-              'Other'
-            ]
+              { name: 'Update existing setup (recommended)', value: 'update' },
+              { name: 'Run full setup flow', value: 'setup' }
+            ],
+            default: 'update'
           }
         ]);
-        techStack.frontend = frontendAnswers.framework;
-      }
 
-      if (stackAnswers.category === 'fullstack' || stackAnswers.category === 'backend') {
-        const backendAnswers = await inquirer.prompt([
-          {
-            type: 'list',
-            name: 'framework',
-            message: 'Which backend framework?',
-            choices: [
-              'Node.js (Express/Fastify)',
-              'Python (Django/FastAPI)',
-              'Go',
-              'Rust',
-              'Java / Spring Boot',
-              'Ruby on Rails',
-              'PHP (Laravel)',
-              'Other'
-            ]
-          },
-          {
-            type: 'list',
-            name: 'database',
-            message: 'Which database?',
-            choices: [
-              'PostgreSQL',
-              'MySQL / MariaDB',
-              'MongoDB',
-              'SQLite',
-              'Supabase',
-              'Firebase',
-              'None / Not sure yet',
-              'Other'
-            ]
-          }
-        ]);
-        techStack.backend = backendAnswers.framework;
-        techStack.database = backendAnswers.database;
+        if (modeAnswer.mode === 'update') {
+          const updateAnswers = await inquirer.prompt([
+            {
+              type: 'checkbox',
+              name: 'components',
+              message: 'Select components to update:',
+              choices: [
+                { name: 'All components', value: 'all', checked: true },
+                { name: 'Documentation (agent-docs/)', value: 'docs' },
+                { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules' },
+                { name: 'Skills (reusable agent capabilities)', value: 'skills' },
+                { name: 'AI Agent instructions (Cursor, Copilot, VSCode, Gemini)', value: 'github' }
+              ],
+              validate: (answer) => {
+                if (answer.length === 0) {
+                  return 'You must choose at least one component.';
+                }
+                return true;
+              }
+            },
+            {
+              type: 'confirm',
+              name: 'overwrite',
+              message: 'Overwrite existing files while updating?',
+              default: true
+            }
+          ]);
+
+          console.log(chalk.blue('\n📦 Updating selected components...\n'));
+          await updateSelectedComponents(targetDir, templateDir, updateAnswers.components, updateAnswers.overwrite);
+
+          console.log(chalk.green.bold('\n✅ Update complete!\n'));
+          console.log(chalk.gray('Tip: run "agents-templated validate" to verify your setup.\n'));
+          return;
+        }
       }
 
-      // Step 2: Component selection
+      // Component selection
       const componentAnswers = await inquirer.prompt([
         {
           type: 'checkbox',
@@ -307,7 +297,6 @@ program
       // Step 3: Install components
       console.log(chalk.blue('\n📦 Installing components...\n'));
       
-      const targetDir = process.cwd();
       const options = {
         force: componentAnswers.overwrite,
         docs: componentAnswers.components.includes('docs'),
@@ -323,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
         );
       }
@@ -339,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
         );
       }
@@ -350,64 +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)'));
       }
 
-      // Step 4: Show recommendations
+      // Show summary and next steps
       console.log(chalk.green.bold('\n✅ Installation complete!\n'));
       
-      console.log(chalk.blue('📋 Your Project Setup:\n'));
-      if (techStack.frontend) console.log(chalk.white(`   Frontend: ${techStack.frontend}`));
-      if (techStack.backend) console.log(chalk.white(`   Backend:  ${techStack.backend}`));
-      if (techStack.database) console.log(chalk.white(`   Database: ${techStack.database}`));
-      
       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('   3. Customize agents/rules/*.mdc for your tech stack'));
-      
-      if (techStack.frontend || techStack.backend) {
-        console.log(chalk.cyan('\n📦 Recommended Packages:\n'));
-        
-        if (techStack.frontend?.includes('React')) {
-          console.log(chalk.white('   npm install react react-dom next typescript'));
-          console.log(chalk.white('   npm install -D @types/react @types/node'));
-        } else if (techStack.frontend?.includes('Vue')) {
-          console.log(chalk.white('   npm install vue nuxt typescript'));
-        } else if (techStack.frontend?.includes('Svelte')) {
-          console.log(chalk.white('   npm install svelte @sveltejs/kit typescript'));
-        }
-        
-        if (techStack.backend?.includes('Node.js')) {
-          console.log(chalk.white('   npm install express zod dotenv'));
-          console.log(chalk.white('   npm install -D @types/express'));
-        } else if (techStack.backend?.includes('Python')) {
-          console.log(chalk.white('   pip install django djangorestframework pydantic'));
-        } else if (techStack.backend?.includes('Go')) {
-          console.log(chalk.white('   go get github.com/gin-gonic/gin'));
-        }
-
-        if (techStack.database?.includes('PostgreSQL')) {
-          console.log(chalk.white('   npm install @prisma/client (or) npm install pg'));
-        } else if (techStack.database?.includes('MongoDB')) {
-          console.log(chalk.white('   npm install mongoose'));
-        } else if (techStack.database?.includes('Supabase')) {
-          console.log(chalk.white('   npm install @supabase/supabase-js'));
-        }
-      }
+      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'));
@@ -427,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');
     
@@ -454,11 +404,12 @@ program
       let warnings = [];
       let passed = [];
 
-      // Check documentation files
-      if (await fs.pathExists(path.join(targetDir, 'AGENTS.md'))) {
-        passed.push(`✓ AGENTS.md found`);
+      // 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'];
@@ -478,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'`);
@@ -639,6 +625,81 @@ async function copyDirectory(sourceDir, targetDir, force = false) {
   }
 }
 
+async function hasInstalledTemplates(targetDir) {
+  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) {
+  const components = selectedComponents.includes('all')
+    ? ['docs', 'rules', 'skills', 'github']
+    : selectedComponents;
+
+  if (components.includes('docs')) {
+    console.log(chalk.yellow('Updating documentation files...'));
+    await fs.ensureDir(path.join(targetDir, 'agent-docs'));
+    await copyDirectory(
+      path.join(templateDir, 'agent-docs'),
+      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, LAYOUT.canonical.rulesDir));
+    await copyDirectory(
+      path.join(templateDir, '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, LAYOUT.canonical.skillsDir));
+    await copyDirectory(
+      path.join(templateDir, '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', '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 });
+  }
+}
+
 program
   .command('update')
   .description('Check for and apply template updates')
@@ -657,8 +718,7 @@ program
       console.log(chalk.blue.bold('\n🔄 Checking for template updates...\n'));
 
       // Check if templates are installed
-      const hasTemplates = await fs.pathExists(path.join(targetDir, 'AGENTS.md')) ||
-                         await fs.pathExists(path.join(targetDir, 'agents'));
+      const hasTemplates = await hasInstalledTemplates(targetDir);
 
       if (!hasTemplates) {
         console.log(chalk.yellow('No templates detected in this directory.'));
@@ -666,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
@@ -678,46 +770,7 @@ program
 
         console.log(chalk.blue('📦 Updating selected components...\n'));
 
-        if (selectedComponents.includes('docs')) {
-          console.log(chalk.yellow('Updating documentation files...'));
-          await fs.ensureDir(path.join(targetDir, 'agent-docs'));
-          await copyDirectory(
-            path.join(templateDir, 'agent-docs'),
-            path.join(targetDir, 'agent-docs'),
-            true
-          );
-        }
-
-        if (selectedComponents.includes('rules')) {
-          console.log(chalk.yellow('Updating agent rules...'));
-          await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
-          await copyDirectory(
-            path.join(templateDir, 'agents', 'rules'),
-            path.join(targetDir, 'agents', 'rules'),
-            true
-          );
-        }
-
-        if (selectedComponents.includes('skills')) {
-          console.log(chalk.yellow('Updating skills...'));
-          await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
-          await copyDirectory(
-            path.join(templateDir, 'agents', 'skills'),
-            path.join(targetDir, 'agents', 'skills'),
-            true
-          );
-        }
-
-        if (selectedComponents.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',
-            'CLAUDE.md',
-            'GEMINI.md'
-          ], true);
-        }
+        await updateSelectedComponents(targetDir, templateDir, selectedComponents, true);
 
         console.log(chalk.green.bold('\n✅ Selected component updates applied successfully!\n'));
         process.exit(0);
@@ -726,27 +779,27 @@ program
       // List potential updates
       const updates = [];
       const checkFiles = [
-        { file: 'AGENTS.md', component: 'root' },
-        { file: 'agent-docs/ARCHITECTURE.md', component: 'docs' },
-        { file: 'agents/rules/security.mdc', component: 'rules' },
-        { file: 'agents/rules/testing.mdc', component: 'rules' },
-        { file: 'agents/rules/core.mdc', component: 'rules' },
-        { file: 'agents/skills/README.md', component: 'skills' },
-        { file: 'agents/skills/find-skills/SKILL.md', component: 'skills' },
-        { file: 'agents/skills/ui-ux-pro-max/SKILL.md', component: 'skills' },
-        { file: '.github/copilot-instructions.md', component: 'github' }
+        { 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: `${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 {file, component} of checkFiles) {
-        const targetPath = path.join(targetDir, file);
-        const templatePath = path.join(templateDir, file);
+      for (const {targetFile, templateFile, component} of checkFiles) {
+        const targetPath = path.join(targetDir, targetFile);
+        const templatePath = path.join(templateDir, templateFile);
         
         if (await fs.pathExists(targetPath) && await fs.pathExists(templatePath)) {
           const targetContent = await fs.readFile(targetPath, 'utf8');
           const templateContent = await fs.readFile(templatePath, 'utf8');
           
           if (targetContent !== templateContent) {
-            updates.push({ file, component });
+            updates.push({ targetFile, templateFile, component });
           }
         }
       }
@@ -757,8 +810,8 @@ program
       }
 
       console.log(chalk.yellow(`Found ${updates.length} file(s) with updates available:\n`));
-      updates.forEach(({ file }) => {
-        console.log(chalk.white(`  📄 ${file}`));
+      updates.forEach(({ targetFile }) => {
+        console.log(chalk.white(`  📄 ${targetFile}`));
       });
       console.log('');
 
@@ -785,20 +838,23 @@ program
       // Apply updates
       console.log(chalk.blue('\n📦 Applying updates...\n'));
       
-      for (const { file } of updates) {
-        const targetPath = path.join(targetDir, file);
-        const templatePath = path.join(templateDir, file);
+      for (const { targetFile, templateFile } of updates) {
+        const targetPath = path.join(targetDir, targetFile);
+        const templatePath = path.join(templateDir, templateFile);
         
         // Backup original file
         const backupPath = `${targetPath}.backup`;
         await fs.copy(targetPath, backupPath);
-        console.log(chalk.gray(`  Backed up: ${file}.backup`));
+        console.log(chalk.gray(`  Backed up: ${targetFile}.backup`));
         
         // Copy new version
         await fs.copy(templatePath, targetPath, { overwrite: true });
-        console.log(chalk.green(`  ✓ Updated: ${file}`));
+        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'));
 
@@ -886,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.9",
+  "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.
+