agents-templated 1.2.12 → 2.1.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

@@ -14,10 +14,12 @@ const {
   getLegacyMigrationPlan
 } = require('../lib/layout');
 const {
-  CORE_SOURCE_REL_PATH,
-  GENERATED_INSTRUCTION_PATHS,
+  CANONICAL_INSTRUCTION_FILE,
+  POINTER_FILES,
   writeGeneratedInstructions,
-  validateInstructionDrift
+  validateInstructionDrift,
+  scaffoldSkill,
+  scaffoldRule
 } = require('../lib/instructions');
 
 // Resolve the templates directory - works in both dev and installed contexts
@@ -152,7 +154,6 @@ program
         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
@@ -181,20 +182,18 @@ program
       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/copilot-instructions.md shim)'));
-        console.log(chalk.gray('  ✓ Claude (.claude/CLAUDE.md shim)'));
-        console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD shim + canonical .github/instructions/AGENTS.md)'));
+        console.log(chalk.gray('  ✓ Claude (CLAUDE.md — canonical source)'));
+        console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md pointer)'));
+        console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD pointer)'));
       }
 
       console.log(chalk.green.bold('\nInstallation complete!\n'));
       console.log(chalk.cyan('Next steps:'));
-      console.log(chalk.white('  1. Review instructions/source/core.md (canonical AI guide)'));
+      console.log(chalk.white('  1. Review CLAUDE.md (canonical AI policy — edit this directly)'));
       console.log(chalk.white('  2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
-      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('  3. AGENTS.MD and .github/copilot-instructions.md are thin compatibility pointers'));
+      console.log(chalk.white('  4. Configure your AI assistant (Copilot, Claude, etc.)'));
       console.log(chalk.white('  5. Adapt the rules to your technology stack\n'));
 
     } catch (error) {
@@ -312,7 +311,6 @@ 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
@@ -341,22 +339,20 @@ program
       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/copilot-instructions.md shim)'));
-        console.log(chalk.gray('  ✓ Claude (.claude/CLAUDE.md shim)'));
-        console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD shim + canonical .github/instructions/AGENTS.md)'));
+        console.log(chalk.gray('  ✓ Claude (CLAUDE.md — canonical source)'));
+        console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md pointer)'));
+        console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD pointer)'));
       }
 
       // 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 instructions/source/core.md (canonical AI guide)'));
+      console.log(chalk.white('   1. Review CLAUDE.md (canonical AI policy — edit this directly)'));
       console.log(chalk.white('   2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
-      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.white('   3. AGENTS.MD and .github/copilot-instructions.md are thin pointers to CLAUDE.md'));
+      console.log(chalk.white('   4. Customize agents/rules/*.mdc for your tech stack'));
       
       console.log(chalk.cyan('\n🔒 Security Reminder:\n'));
       console.log(chalk.white('   • Review agents/rules/security.mdc'));
@@ -403,12 +399,12 @@ program
       let warnings = [];
       let passed = [];
 
-      // 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`);
+      // Check canonical instruction file
+      const claudePath = path.join(targetDir, CANONICAL_INSTRUCTION_FILE);
+      if (await fs.pathExists(claudePath)) {
+        passed.push(`✓ ${CANONICAL_INSTRUCTION_FILE} found (canonical policy source)`);
       } else {
-        warnings.push(`⚠ ${CORE_SOURCE_REL_PATH} missing - run 'agents-templated init --docs'`);
+        warnings.push(`⚠ ${CANONICAL_INSTRUCTION_FILE} missing - run 'agents-templated init --github'`);
       }
 
       const docFiles = ['ARCHITECTURE.md'];
@@ -466,37 +462,23 @@ program
         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, GENERATED_INSTRUCTION_PATHS.compatibility.claude)) ||
-        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) {
-          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 instruction pointer files and drift
+      const instructionDrift = await validateInstructionDrift(targetDir);
+      if (instructionDrift.missingCanonical) {
+        issues.push(`✗ CLAUDE.md missing - run 'agents-templated init --github'`);
+      } else if (instructionDrift.driftFiles.length > 0) {
+        warnings.push(`⚠ Pointer files out of sync: ${instructionDrift.driftFiles.join(', ')} — run 'agents-templated update --github'`);
+      } else {
+        passed.push('✓ AGENTS.MD and .github/copilot-instructions.md are in sync');
       }
 
-      const compatCopilotFile = path.join(targetDir, GENERATED_INSTRUCTION_PATHS.compatibility.copilot);
+      const compatCopilotFile = path.join(targetDir, POINTER_FILES.copilot);
       if (await fs.pathExists(compatCopilotFile)) {
         passed.push(`✓ GitHub Copilot configuration found`);
       } else {
         warnings.push(`⚠ GitHub Copilot configuration missing - run 'agents-templated init --github'`);
       }
 
-      // Check for .cursorrules (if using Cursor)
-      const cursorrules = path.join(targetDir, '.cursorrules');
-      if (await fs.pathExists(cursorrules)) {
-        passed.push(`✓ .cursorrules file found (Cursor IDE)`);
-      }
-
       // Check for .gitignore
       const gitignore = path.join(targetDir, '.gitignore');
       if (await fs.pathExists(gitignore)) {
@@ -623,12 +605,19 @@ 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));
+    await fs.pathExists(path.join(targetDir, CANONICAL_INSTRUCTION_FILE)) ||
+    await fs.pathExists(path.join(targetDir, POINTER_FILES.agents));
 }
 
 async function cleanupLegacyInstructionFiles(targetDir) {
-  const legacyFiles = ['CLAUDE.md', 'GEMINI.md'];
+  // Files removed in v2.0.0: orphaned wrappers that contained duplicated policy
+  // content and were not managed/validated by the generator.
+  const legacyFiles = [
+    '.cursorrules',
+    '.github/instructions/AGENTS.md',
+    // Pre-v1.2.13 paths
+    '.claude/CLAUDE.md'
+  ];
 
   for (const file of legacyFiles) {
     const filePath = path.join(targetDir, file);
@@ -652,7 +641,6 @@ 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')) {
@@ -678,7 +666,6 @@ 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);
   }
@@ -788,15 +775,14 @@ program
       // List potential updates
       const updates = [];
       const checkFiles = [
-        { targetFile: CORE_SOURCE_REL_PATH, templateFile: CORE_SOURCE_REL_PATH, component: 'root' },
+        { targetFile: CANONICAL_INSTRUCTION_FILE, templateFile: CANONICAL_INSTRUCTION_FILE, 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' }
+        { 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) {
@@ -926,7 +912,6 @@ program
 
       // Check AI assistant configs
       const configs = [
-        { file: '.cursorrules', name: 'Cursor IDE' },
         { file: '.github/copilot-instructions.md', name: 'GitHub Copilot' }
       ];
 
@@ -952,8 +937,40 @@ 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 .github/instructions/rules/security.mdc for security patterns\n'));
+      console.log(chalk.white('  • Review agents/rules/security.mdc for security patterns\n'));
+
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
 
+program
+  .command('new-skill <name>')
+  .description('Scaffold a new skill in agents/skills/<name>/SKILL.md')
+  .action(async (name) => {
+    try {
+      const targetDir = process.cwd();
+      const relPath = await scaffoldSkill(targetDir, name);
+      console.log(chalk.green(`\n+ ${relPath}\n`));
+      console.log(chalk.gray('Fill in Trigger Conditions, Workflow, and Output Contract.'));
+      console.log(chalk.gray('Then add it to the Reference Index in CLAUDE.md.\n'));
+    } catch (error) {
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('new-rule <name>')
+  .description('Scaffold a new rule in agents/rules/<name>.mdc')
+  .action(async (name) => {
+    try {
+      const targetDir = process.cwd();
+      const relPath = await scaffoldRule(targetDir, name);
+      console.log(chalk.green(`\n+ ${relPath}\n`));
+      console.log(chalk.gray('Fill in Purpose and Requirements sections.'));
+      console.log(chalk.gray('Then add it to the Reference Index in CLAUDE.md.\n'));
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
       process.exit(1);

package/index.js

@@ -1,7 +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');
+const { CANONICAL_INSTRUCTION_FILE, writeGeneratedInstructions } = require('./lib/instructions');
 
 /**
  * Programmatic API for agents-templated
@@ -29,8 +29,7 @@ async function install(targetDir, options = {}) {
   if (installAll || options.docs) {
     files.push(
       'agent-docs/ARCHITECTURE.md',
-      'agent-docs/README.md',
-      CORE_SOURCE_REL_PATH
+      'agent-docs/README.md'
     );
   }
 
@@ -72,13 +71,6 @@ async function install(targetDir, options = {}) {
   // 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);
   }
 }