agents-templated 2.0.0 → 2.2.0

package/bin/cli.js

@@ -10,15 +10,18 @@ const {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan
 } = require('../lib/layout');
 const {
-  CORE_SOURCE_REL_PATH,
-  GENERATED_INSTRUCTION_PATHS,
-  KNOWN_ORPHAN_PATHS,
+  CANONICAL_INSTRUCTION_FILE,
+  POINTER_FILES,
   writeGeneratedInstructions,
-  validateInstructionDrift
+  validateInstructionDrift,
+  scaffoldSkill,
+  scaffoldRule,
+  scaffoldSubagent
 } = require('../lib/instructions');
 
 // Resolve the templates directory - works in both dev and installed contexts
@@ -51,6 +54,7 @@ program
   .option('-r, --rules', 'Install agent rules only')
   .option('-s, --skills', 'Install skills only')
   .option('-g, --github', 'Install GitHub Copilot instructions')
+  .option('-S, --subagents', 'Install agent subagents only')
   .option('-p, --preset <name>', 'Use a preset configuration (nextjs, django-react, express-api, fastapi, go-api)')
   .option('-f, --force', 'Overwrite existing files')
   .action(async (options) => {
@@ -120,7 +124,8 @@ 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, Claude, Generic AGENTS)', value: 'github' }
+              { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
+              { name: 'Agent subagents (agents/subagents/*.md)', value: 'subagents' }
             ],
             default: ['all']
           },
@@ -142,6 +147,7 @@ program
         if (options.rules) choices.push('rules');
         if (options.skills) choices.push('skills');
         if (options.github) choices.push('github');
+        if (options.subagents) choices.push('subagents');
       }
 
       const installAll = choices.includes('all');
@@ -153,7 +159,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
@@ -183,18 +188,28 @@ program
         console.log(chalk.yellow('Installing AI agent instructions...'));
         await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
         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.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)'));
+      }
+
+      // Install agent subagents
+      if (installAll || choices.includes('subagents')) {
+        console.log(chalk.yellow('Installing agent subagents...'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
+        await copyDirectory(
+          path.join(templateDir, 'agents', 'subagents'),
+          path.join(targetDir, LAYOUT.canonical.subagentsDir),
+          options.force
+        );
       }
 
       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) {
@@ -241,7 +256,8 @@ 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, Claude, Generic AGENTS)', value: 'github' }
+                { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
+                { name: 'Agent subagents (agents/subagents/*.md)', value: 'subagents' }
               ],
               validate: (answer) => {
                 if (answer.length === 0) {
@@ -277,7 +293,8 @@ 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, Claude, Generic AGENTS)', value: 'github', checked: true }
+            { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true },
+            { name: 'Agent subagents (agents/subagents/*.md)', value: 'subagents', checked: true }
           ],
           validate: (answer) => {
             if (answer.length === 0) {
@@ -302,7 +319,8 @@ program
         docs: componentAnswers.components.includes('docs'),
         rules: componentAnswers.components.includes('rules'),
         skills: componentAnswers.components.includes('skills'),
-        github: componentAnswers.components.includes('github')
+        github: componentAnswers.components.includes('github'),
+        subagents: componentAnswers.components.includes('subagents')
       };
 
       // Install documentation files
@@ -312,7 +330,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
@@ -342,20 +359,30 @@ program
         console.log(chalk.yellow('Installing AI agent instructions...'));
         await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
         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.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)'));
+      }
+
+      // Install agent subagents
+      if (options.subagents) {
+        console.log(chalk.yellow('Installing agent subagents...'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
+        await copyDirectory(
+          path.join(templateDir, 'agents', 'subagents'),
+          path.join(targetDir, LAYOUT.canonical.subagentsDir),
+          options.force
+        );
       }
 
       // 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'));
@@ -378,6 +405,7 @@ program
     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, Claude, Generic AGENTS)');
+    console.log(chalk.yellow('subagents') + ' - Agent subagents (agents/subagents/*.md)');
     console.log(chalk.yellow('all') + '     - All components');
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
@@ -402,12 +430,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'];
@@ -465,43 +493,32 @@ 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));
+      // Check subagents
+      const subagentsDir = path.join(targetDir, LAYOUT.canonical.subagentsDir);
+      if (await fs.pathExists(subagentsDir)) {
+        const subagents = (await fs.readdir(subagentsDir)).filter(f => f.endsWith('.md') && f !== 'README.md');
+        passed.push(`✓ ${subagents.length} subagents installed in ${LAYOUT.canonical.subagentsDir}`);
+      } else {
+        warnings.push(`⚠ ${LAYOUT.canonical.subagentsDir} directory missing - run 'agents-templated init --subagents'`);
+      }
 
-      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.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`
-          );
-        }
+      // 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)) {
@@ -628,15 +645,16 @@ 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) {
   // 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,
+    '.cursorrules',
+    '.github/instructions/AGENTS.md',
     // Pre-v1.2.13 paths
     '.claude/CLAUDE.md'
   ];
@@ -652,7 +670,7 @@ async function cleanupLegacyInstructionFiles(targetDir) {
 
 async function updateSelectedComponents(targetDir, templateDir, selectedComponents, overwrite = true) {
   const components = selectedComponents.includes('all')
-    ? ['docs', 'rules', 'skills', 'github']
+    ? ['docs', 'rules', 'skills', 'github', 'subagents']
     : selectedComponents;
 
   if (components.includes('docs')) {
@@ -663,7 +681,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')) {
@@ -693,6 +710,16 @@ async function updateSelectedComponents(targetDir, templateDir, selectedComponen
     await cleanupLegacyInstructionFiles(targetDir);
   }
 
+  if (components.includes('subagents')) {
+    console.log(chalk.yellow('Updating agent subagents...'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
+    await copyDirectory(
+      path.join(templateDir, 'agents', 'subagents'),
+      path.join(targetDir, LAYOUT.canonical.subagentsDir),
+      overwrite
+    );
+  }
+
   if ((components.includes('docs') || components.includes('github')) && !components.includes('github')) {
     await writeGeneratedInstructions(targetDir, templateDir, overwrite);
   }
@@ -727,6 +754,7 @@ program
   .option('-r, --rules', 'Update agent rules only')
   .option('-s, --skills', 'Update skills only')
   .option('-g, --github', 'Update AI agent instruction files only')
+  .option('-S, --subagents', 'Update agent subagents only')
   .option('-c, --check-only', 'Only check for updates, don\'t install')
   .option('-f, --force', 'Force overwrite files during update')
   .action(async (options) => {
@@ -786,6 +814,7 @@ program
         if (options.all || options.rules) selectedComponents.push('rules');
         if (options.all || options.skills) selectedComponents.push('skills');
         if (options.all || options.github) selectedComponents.push('github');
+        if (options.all || options.subagents) selectedComponents.push('subagents');
 
         console.log(chalk.blue('📦 Updating selected components...\n'));
 
@@ -798,7 +827,7 @@ 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' },
@@ -935,7 +964,6 @@ program
 
       // Check AI assistant configs
       const configs = [
-        { file: '.cursorrules', name: 'Cursor IDE' },
         { file: '.github/copilot-instructions.md', name: 'GitHub Copilot' }
       ];
 
@@ -961,8 +989,56 @@ 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);
+    }
+  });
+
+program
+  .command('new-subagent <name>')
+  .description('Scaffold a new subagent in agents/subagents/<name>.md')
+  .action(async (name) => {
+    try {
+      const targetDir = process.cwd();
+      const relPath = await scaffoldSubagent(targetDir, name);
+      console.log(chalk.green(`\n+ ${relPath}\n`));
+      console.log(chalk.gray('Fill in Activation Conditions, Workflow, and Output Format.'));
+      console.log(chalk.gray('Then add it to the Subagent modules table 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'
     );
   }