agents-templated 1.2.11 → 2.0.0

package/README.md

@@ -100,7 +100,7 @@ Your AI assistant will auto-load the configurations and follow enterprise patter
 |---------|-------------|
 | 🚀 **Quick Start Presets** | 5 popular tech stack presets (Next.js, Express, Django, FastAPI, Go) |
 | 🧙 **Interactive Wizard** | Guided setup with personalized recommendations |
-| 🤖 **4 AI Agents Supported** | Cursor, GitHub Copilot, Claude, Google Gemini (auto-discovery) |
+| 🤖 **AI Agents Supported** | Cursor, GitHub Copilot, Claude, and generic agents via `AGENTS.MD` |
 | 🧭 **Deterministic Commands** | Slash-command contracts with strict structured outputs |
 | 💬 **Auto Intent Routing** | Non-slash prompts can map to command contracts (`slash-command-auto`) |
 | 🔒 **Security-First** | OWASP Top 10 protection patterns built-in |
@@ -115,14 +115,14 @@ Your AI assistant will auto-load the configurations and follow enterprise patter
 
 ## 🤖 AI Agent Support
 
-Agents Templated automatically configures 4 major AI coding assistants:
+Agents Templated automatically configures compatible wrappers for major AI coding assistants:
 
 | AI Agent | Config File | Auto-Discovery |
 |----------|-------------|----------------|
 | **Cursor** | `.cursorrules` | ✅ Auto-loads in Cursor IDE |
-| **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 |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ Auto-loads in VS Code |
+| **Claude** | `CLAUDE.md` | ✅ Compatible |
+| **Generic agents** | `AGENTS.MD` | ✅ Compatible |
 
 **Single source of truth:** `instructions/source/core.md` drives generated tool-compatible instruction files.
 
@@ -143,11 +143,8 @@ your-project/
 │   └── README.md                   # Human-readable setup guide
 │
 ├── .github/
-│   ├── instructions/                # Canonical generated instructions
+│   ├── instructions/                # Generated compatibility wrappers + rules
 │   │   ├── AGENTS.md
-│   │   ├── copilot-instructions.md
-│   │   ├── CLAUDE.md
-│   │   ├── GEMINI.md
 │   │   └── rules/
 │   │   ├── core.mdc               # Core development principles
 │   │   ├── security.mdc           # Security patterns (CRITICAL)
@@ -181,8 +178,7 @@ your-project/
 │
 ├── 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
+├── .cursorrules                     # Compatibility shim for Cursor
 ├── .gitignore                      # Pre-configured Git ignore
 └── README.md                       # Project documentation
 ```
@@ -262,7 +258,7 @@ Open your AI assistant and it will automatically load the appropriate config:
 - **Cursor**: Opens `.cursorrules` automatically
 - **GitHub Copilot**: Reads `.github/copilot-instructions.md`
 - **Claude**: Reads `CLAUDE.md`
-- **Gemini**: Reads `GEMINI.md`
+- **Generic/other tools**: Read `AGENTS.MD`
 
 ### 3. Create Custom Skills (Optional)
 
@@ -270,13 +266,13 @@ Extend your AI agents with domain-specific skills for your project:
 
 ```bash
 # View the skills guide
-cat agents/skills/README.md
+cat .github/skills/README.md
 ```
 
-Create a new skill folder in `agents/skills/`:
+Create a new skill folder in `.github/skills/`:
 
 ```markdown
-agents/skills/my-custom-skill/SKILL.md
+.github/skills/my-custom-skill/SKILL.md
 ---
 name: my-custom-skill
 description: Custom patterns for my project domain
@@ -296,15 +292,15 @@ Use this skill when working with [your domain].
 Code and examples...
 ```
 
-Skills define *how to execute specific tasks*, complementing rules that define *how to behave*. See [agents/skills/README.md](agents/skills/README.md) for detailed guidance.
+Skills define *how to execute specific tasks*, complementing rules that define *how to behave*. See [.github/skills/README.md](.github/skills/README.md) for detailed guidance.
 
 ### 4. Read the Documentation
 
 - **[AGENTS.MD](AGENTS.MD)** – AI assistant guide
 - **[agent-docs/ARCHITECTURE.md](agent-docs/ARCHITECTURE.md)** – Project architecture & tech stack guidance
-- **[agents/skills/README.md](agents/skills/README.md)** – Custom skills guide
-- **[agents/rules/security.mdc](agents/rules/security.mdc)** – Security patterns (CRITICAL)
-- **[agents/rules/testing.mdc](agents/rules/testing.mdc)** – Testing strategy
+- **[.github/skills/README.md](.github/skills/README.md)** – Custom skills guide
+- **[.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)** – Security patterns (CRITICAL)
+- **[.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)** – Testing strategy
 
 ### 5. Start Building
 
@@ -330,7 +326,7 @@ Your AI will follow the enterprise patterns automatically!
 ✅ Sanitize outputs to prevent injection attacks  
 ✅ Never expose sensitive data in error messages or logs
 
-**Reference**: [agents/rules/security.mdc](agents/rules/security.mdc)
+**Reference**: [.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)
 
 ### Testing Strategy
 
@@ -338,7 +334,7 @@ Your AI will follow the enterprise patterns automatically!
 - **15% Integration Tests** – API endpoints, database operations
 - **5% E2E Tests** – Critical user journeys
 
-**Reference**: [agents/rules/testing.mdc](agents/rules/testing.mdc)
+**Reference**: [.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)
 
 ### Agent-Based Architecture
 

package/bin/cli.js

@@ -16,6 +16,7 @@ const {
 const {
   CORE_SOURCE_REL_PATH,
   GENERATED_INSTRUCTION_PATHS,
+  KNOWN_ORPHAN_PATHS,
   writeGeneratedInstructions,
   validateInstructionDrift
 } = require('../lib/instructions');
@@ -119,7 +120,7 @@ program
               { name: 'Documentation files (agent-docs/)', value: 'docs' },
               { 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' }
+              { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' }
             ],
             default: ['all']
           },
@@ -177,16 +178,15 @@ program
         );
       }
 
-      // Install AI Agent instructions (Cursor, Copilot, Claude, Gemini)
+      // Install AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)
       if (installAll || choices.includes('github')) {
         console.log(chalk.yellow('Installing AI agent instructions...'));
         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/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.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md shim)'));
+        console.log(chalk.gray('  ✓ Claude (CLAUDE.md shim)'));
+        console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD shim + canonical .github/instructions/AGENTS.md)'));
       }
 
       console.log(chalk.green.bold('\nInstallation complete!\n'));
@@ -241,7 +241,7 @@ program
                 { 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' }
+                { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' }
               ],
               validate: (answer) => {
                 if (answer.length === 0) {
@@ -277,7 +277,7 @@ program
             { name: 'Documentation (agent-docs/)', value: 'docs', checked: true },
             { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules', checked: true },
             { name: 'Skills (reusable agent capabilities)', value: 'skills', checked: true },
-            { name: 'AI Agent instructions (Cursor, Copilot, VSCode, Gemini)', value: 'github', checked: true }
+            { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true }
           ],
           validate: (answer) => {
             if (answer.length === 0) {
@@ -337,17 +337,15 @@ program
         );
       }
 
-      // Install AI Agent instructions (Cursor, Copilot, VSCode, Gemini)
+      // Install AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)
       if (options.github) {
         console.log(chalk.yellow('Installing AI agent instructions...'));
         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/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)'));
+        console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md shim)'));
+        console.log(chalk.gray('  ✓ Claude (CLAUDE.md shim)'));
+        console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD shim + canonical .github/instructions/AGENTS.md)'));
       }
 
       // Show summary and next steps
@@ -379,7 +377,7 @@ program
     console.log(chalk.yellow('docs') + '    - Documentation files (agent-docs/ directory)');
     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('github') + '  - AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)');
     console.log(chalk.yellow('all') + '     - All components');
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
@@ -470,26 +468,29 @@ program
       // 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.copilot)) ||
         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) {
+        } else if (instructionDrift.driftFiles.length > 0) {
           issues.push(`✗ Generated instruction files are out of sync: ${instructionDrift.driftFiles.join(', ')}`);
         } else {
           passed.push('✓ Generated instruction files are in sync with canonical source');
         }
+        if (instructionDrift.orphanedPolicyFiles && instructionDrift.orphanedPolicyFiles.length > 0) {
+          issues.push(
+            `✗ Orphaned policy files detected (contain duplicated content, should be deleted): ` +
+            `${instructionDrift.orphanedPolicyFiles.join(', ')} — run 'agents-templated update --github' to remove`
+          );
+        }
       }
 
-      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)) {
+      if (await fs.pathExists(compatCopilotFile)) {
         passed.push(`✓ GitHub Copilot configuration found`);
       } else {
         warnings.push(`⚠ GitHub Copilot configuration missing - run 'agents-templated init --github'`);
@@ -631,6 +632,24 @@ async function hasInstalledTemplates(targetDir) {
     await fs.pathExists(path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.generic));
 }
 
+async function cleanupLegacyInstructionFiles(targetDir) {
+  // Files removed in v2.0.0: orphaned wrappers that contained duplicated policy
+  // content and were not managed/validated by the generator.
+  const legacyFiles = [
+    ...KNOWN_ORPHAN_PATHS,
+    // Pre-v1.2.13 paths
+    '.claude/CLAUDE.md'
+  ];
+
+  for (const file of legacyFiles) {
+    const filePath = path.join(targetDir, file);
+    if (await fs.pathExists(filePath)) {
+      await fs.remove(filePath);
+      console.log(chalk.green(`  ✓ Removed legacy file: ${file}`));
+    }
+  }
+}
+
 async function updateSelectedComponents(targetDir, templateDir, selectedComponents, overwrite = true) {
   const components = selectedComponents.includes('all')
     ? ['docs', 'rules', 'skills', 'github']
@@ -670,8 +689,8 @@ async function updateSelectedComponents(targetDir, templateDir, selectedComponen
   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);
+    await cleanupLegacyInstructionFiles(targetDir);
   }
 
   if ((components.includes('docs') || components.includes('github')) && !components.includes('github')) {
@@ -786,8 +805,7 @@ program
         { 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' }
+        { targetFile: `${LAYOUT.canonical.skillsDir}/ui-ux-pro-max/SKILL.md`, templateFile: 'agents/skills/ui-ux-pro-max/SKILL.md', component: 'skills' }
       ];
 
       for (const {targetFile, templateFile, component} of checkFiles) {
@@ -854,6 +872,7 @@ program
 
       await writeGeneratedInstructions(targetDir, templateDir, true);
       console.log(chalk.green('  ✓ Regenerated instruction compatibility files'));
+      await cleanupLegacyInstructionFiles(targetDir);
 
       console.log(chalk.green.bold('\n✅ Updates applied successfully!\n'));
       console.log(chalk.gray('Backup files created with .backup extension\n'));

package/index.js

@@ -69,16 +69,9 @@ async function install(targetDir, options = {}) {
     );
   }
 
-  // AI Agent instructions (Cursor, Copilot, Claude, Gemini)
+  // AI Agent instructions (Cursor, Copilot, Claude)
   if (installAll || options.github) {
     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

@@ -5,23 +5,27 @@ 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'
+    generic: '.github/instructions/AGENTS.md'
   },
   compatibility: {
     generic: 'AGENTS.MD',
     copilot: '.github/copilot-instructions.md',
     claude: 'CLAUDE.md',
-    gemini: 'GEMINI.md'
+    cursor: '.cursorrules'
   }
 };
 
+// Files that MUST NOT exist — legacy/orphaned files that contain or may contain
+// duplicated policy content. Their presence is reported as a violation by validateInstructionDrift.
+const KNOWN_ORPHAN_PATHS = [
+  '.github/instructions/CLAUDE.md',
+  '.github/instructions/GEMINI.md',
+  '.github/instructions/agents.instructions.md',
+  '.github/instructions/copilot-instructions.md',
+  '.claude/rules/claude.instructions.md',
+  'GEMINI.md'
+];
+
 function getLegacyCoreCandidates() {
   return ['AGENTS.MD', 'AGENTS.md'];
 }
@@ -40,40 +44,29 @@ function buildCompatInstruction(toolName, corePath) {
     generic: '# AGENTS Instructions',
     copilot: '# GitHub Copilot Instructions',
     claude: '# Claude Instructions',
-    gemini: '# Gemini Instructions'
+    cursor: '# Cursor Rules'
   };
 
   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.',
+    'Load policy only from the canonical source file above.',
+    'Do not duplicate, summarize, or inline rules in this file.',
+    'If this file and the canonical source conflict, the canonical source wins.',
     ''
   ].join('\n');
 }
 
-function buildGeneratedArtifacts(coreContent) {
+function buildGeneratedArtifacts() {
   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.canonical.generic] = `${buildHeaders('generic-wrapper')}${buildCompatInstruction('generic', 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)}`;
+  files[GENERATED_INSTRUCTION_PATHS.compatibility.cursor] = `${buildHeaders('cursor-compat')}${buildCompatInstruction('cursor', corePath)}`;
 
   return files;
 }
@@ -87,7 +80,14 @@ async function resolveCoreContent(targetDir, templateDir) {
   for (const legacyFile of getLegacyCoreCandidates()) {
     const legacyPath = path.join(targetDir, legacyFile);
     if (await fs.pathExists(legacyPath)) {
-      return fs.readFile(legacyPath, 'utf8');
+      const legacyContent = await fs.readFile(legacyPath, 'utf8');
+      const isWrapper =
+        legacyContent.includes(`Source of truth: ${CORE_SOURCE_REL_PATH}`) ||
+        legacyContent.includes('Primary policy source: `instructions/source/core.md`.');
+
+      if (!isWrapper) {
+        return legacyContent;
+      }
     }
   }
 
@@ -109,9 +109,7 @@ async function ensureCoreSource(targetDir, templateDir, force = false) {
 
 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);
+  const artifacts = buildGeneratedArtifacts();
 
   for (const [relPath, content] of Object.entries(artifacts)) {
     const targetPath = path.join(targetDir, relPath);
@@ -131,12 +129,12 @@ async function validateInstructionDrift(targetDir) {
     return {
       ok: false,
       missingCore: true,
-      driftFiles: []
+      driftFiles: [],
+      orphanedPolicyFiles: []
     };
   }
 
-  const coreContent = await fs.readFile(corePath, 'utf8');
-  const expected = buildGeneratedArtifacts(coreContent);
+  const expected = buildGeneratedArtifacts();
   const driftFiles = [];
 
   for (const [relPath, expectedContent] of Object.entries(expected)) {
@@ -152,16 +150,26 @@ async function validateInstructionDrift(targetDir) {
     }
   }
 
+  // Detect orphaned policy files that must not exist
+  const orphanedPolicyFiles = [];
+  for (const relPath of KNOWN_ORPHAN_PATHS) {
+    if (await fs.pathExists(path.join(targetDir, relPath))) {
+      orphanedPolicyFiles.push(relPath);
+    }
+  }
+
   return {
-    ok: driftFiles.length === 0,
+    ok: driftFiles.length === 0 && orphanedPolicyFiles.length === 0,
     missingCore: false,
-    driftFiles
+    driftFiles,
+    orphanedPolicyFiles
   };
 }
 
 module.exports = {
   CORE_SOURCE_REL_PATH,
   GENERATED_INSTRUCTION_PATHS,
+  KNOWN_ORPHAN_PATHS,
   writeGeneratedInstructions,
   validateInstructionDrift
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "1.2.11",
+  "version": "2.0.0",
   "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": {

package/templates/.cursorrules

@@ -1,70 +1,9 @@
-# Cursor Rules - Technology-Agnostic Development Template
-# This is a flexible development template that adapts to any technology stack with enterprise-grade patterns.
-# Detailed rules are in agents/rules/*.mdc files - refer to those for implementation patterns.
-
-## Developer Identity & Communication
-- AI assistant should provide clear, step-by-step solutions with actionable examples
-- Focus on security, performance, and maintainability in all recommendations
-- Adapt patterns to the chosen technology stack
-
-## Core Principles
-- **Security-first development**: Always validate inputs, authenticate users, implement appropriate rate limiting
-- **Type safety**: Use strong typing systems available in chosen language/framework
-- **Performance optimization**: Monitor resource usage, implement caching, optimize assets
-- **Testing strategy**: Comprehensive testing at unit, integration, and E2E levels
-- **Accessibility**: WCAG 2.1 AA compliance for all user-facing interfaces
-- **Documentation**: Keep project documentation updated and comprehensive
-
-## Architecture Principles
-- **Technology-agnostic**: This template adapts to your chosen stack
-- **Security patterns**: Input validation, authentication, authorization, rate limiting
-- **Performance patterns**: Caching, lazy loading, bundle optimization
-- **Testing patterns**: Unit (80%), Integration (15%), E2E (5%) coverage target
-- **Feature-oriented structure**: Group by domain/feature, not just technical layer
-
-## Security Requirements (CRITICAL)
-- **Input validation**: All user inputs MUST be validated with appropriate schema validation
-- **Authentication**: Implement secure authentication flows with session management
-- **Rate limiting**: Public endpoints MUST have rate limiting protection
-- **Authorization**: Role-based access control with proper middleware
-- **Error handling**: Never expose sensitive data in error responses
-- **Database access**: Use ORM/ODM patterns, avoid raw queries unless performance-critical
-
-## Code Quality Standards
-- **Type Safety**: Use strict typing, avoid loose type usage
-- **Performance**: Monitor bundle/binary size, implement lazy loading patterns
-- **Accessibility**: WCAG 2.1 AA compliance for user-facing components
-- **Testing**: All business logic and user flows must have appropriate tests
-- **Documentation**: Keep README, agent-docs/ARCHITECTURE.md, and AGENTS.md updated
-
-## Technology Stack Adaptation
-Choose your stack and apply these patterns consistently:
-
-### Frontend Options
-- **React/Next.js/Vue/Svelte**: Component-based with proper state management
-- **Angular**: Component + service architecture with TypeScript
-- **Traditional**: Server-side rendering with progressive enhancement
-
-### Backend Options  
-- **Node.js**: Express, Fastify, or framework API routes
-- **Python**: Django, FastAPI, Flask with proper ORM patterns
-- **Other**: Adapt patterns to your chosen backend technology
-
-### Database Options
-- **SQL**: PostgreSQL, MySQL with ORM (Prisma, TypeORM, SQLAlchemy)
-- **NoSQL**: MongoDB, DynamoDB with ODM patterns
-- **Cloud**: Supabase, Firebase, managed database services
-
-## Agent Delegation (See AGENTS.md for details)
-- **UI/Design work** → FrontendAgent
-- **API/Business logic** → BackendAgent  
-- **Database/Schema** → DatabaseAgent
-- **Testing implementation** → TestAgent
-- **Security reviews** → SecurityAgent
-- **Code quality** → ReviewerAgent
-
-## Usage Instructions
-1. Choose your technology stack
-2. Adapt the patterns in agents/rules/*.mdc to your chosen technologies
-3. Update this .cursorrules file with stack-specific details
-4. Begin development following the established patterns
+<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
+<!-- Source of truth: instructions/source/core.md -->
+<!-- Tool profile: cursor-compat -->
+# Cursor Rules
+
+Primary policy source: `instructions/source/core.md`.
+Load policy only from the canonical source file above.
+Do not duplicate, summarize, or inline rules in this file.
+If this file and the canonical source conflict, the canonical source wins.

package/templates/.github/copilot-instructions.md

@@ -1,64 +1,9 @@
+<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
+<!-- Source of truth: instructions/source/core.md -->
+<!-- Tool profile: copilot-compat -->
 # GitHub Copilot Instructions
 
-This project follows enterprise-grade, technology-agnostic development patterns.
-
-## Quick Start
-
-- **AI Guide**: See `AGENTS.md` for comprehensive instructions
-- **Architecture**: See `agent-docs/ARCHITECTURE.md` for project guidelines
-- **Custom Skills**: See `agents/skills/` directory for domain-specific extensions
-- **Detailed Rules**: See `agents/rules/*.mdc` files
-
-## Always Apply
-
-1. **Security-first**: Validate inputs, authenticate endpoints, rate limit public APIs
-   - Reference: `agents/rules/security.mdc`
-
-2. **Testing**: Unit (80%), Integration (15%), E2E (5%) coverage
-   - Reference: `agents/rules/testing.mdc`
-
-3. **Type Safety**: Strong typing with runtime validation at boundaries
-   - Reference: `agents/rules/core.mdc`
-
-## Agent Delegation
-
-When implementing features, follow agent patterns from `AGENTS.MD`:
-- **UI/Design** → FrontendAgent patterns (`agents/rules/frontend.mdc`)
-- **API/Logic** → BackendAgent patterns (`agents/rules/security.mdc`)
-- **Database** → DatabaseAgent patterns (`agents/rules/database.mdc`)
-- **Testing** → TestAgent patterns (`agents/rules/testing.mdc`)
-- **Security** → SecurityAgent patterns (`agents/rules/security.mdc`)
-
-## Deterministic Slash Commands
-
-- Slash command protocol is defined in `AGENTS.MD` under `Deterministic Slash Command System Standard`.
-- Modular command contracts are stored in `agents/commands/`.
-- Command mode is strict: unknown or malformed slash commands must return structured error output and stop.
-- No conversational fallback is allowed once slash-command mode is entered.
-- Destructive actions require explicit confirmation token format: `CONFIRM-DESTRUCTIVE:<target>`.
-
-## Critical Rules
-
-- Validate ALL user inputs with schema validation
-- Authenticate and authorize protected endpoints
-- Rate limit public endpoints
-- Write tests for all business logic
-- Ensure WCAG 2.1 AA accessibility compliance
-- Use ORM/ODM patterns, avoid raw queries
-- Never expose sensitive data in errors/logs
-
-## Reference Files
-
-- `AGENTS.MD` - Primary AI assistant guide
-- `agent-docs/ARCHITECTURE.md` - Architecture and technology stack guidance
-- `agents/commands/` - Deterministic slash command contracts
-- `agents/rules/core.mdc` - Core principles
-- `agents/rules/security.mdc` - Security patterns (CRITICAL)
-- `agents/rules/testing.mdc` - Testing strategy (CRITICAL)
-- `agents/rules/frontend.mdc` - Frontend patterns
-- `agents/rules/database.mdc` - Database patterns
-- `agents/rules/style.mdc` - Code style guidelines
-
----
-
-**Note**: This is technology-agnostic. Adapt patterns to your chosen stack while maintaining security and quality standards.
+Primary policy source: `instructions/source/core.md`.
+Load policy only from the canonical source file above.
+Do not duplicate, summarize, or inline rules in this file.
+If this file and the canonical source conflict, the canonical source wins.

package/templates/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- GENERATED FILE - DO NOT EDIT DIRECTLY -->
+<!-- Source of truth: instructions/source/core.md -->
+<!-- Tool profile: generic-compat -->
+# AGENTS Instructions
+
+Primary policy source: `instructions/source/core.md`.
+Load policy only from the canonical source file above.
+Do not duplicate, summarize, or inline rules in this file.
+If this file and the canonical source conflict, the canonical source wins.