agents-templated 2.2.12 → 2.2.14

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/rickandrew2/agents-templated?style=social)](https://github.com/rickandrew2/agents-templated)
 
-> **Agents Templated** is a CLI tool and npm package that instantly scaffolds production-ready project structures with enterprise-grade development patterns, security guidelines, and AI assistant configurations. Designed for developers who want to start projects the right way—with proven OWASP security practices, comprehensive testing strategies (80/15/5 coverage targets), and agent-based architecture patterns—without being locked into specific frameworks. It generates unified configuration files that work seamlessly with Cursor, GitHub Copilot, Claude, and Google Gemini, allowing AI assistants to automatically follow best practices from day one. Whether you're building a Next.js app, Django API, Go microservice, or any custom stack, Agents Templated provides the guardrails and patterns you need while giving you complete freedom to choose your technology.
+> **Agents Templated** is a technology-agnostic CLI that scaffolds the AI development operating layer around your app: policy rules, deterministic command contracts, reusable skills, and compatibility files for Cursor, GitHub Copilot, Claude, and generic agent hosts. It does not scaffold your product framework. It scaffolds how your team and agents plan, build, test, review, and release.
 
 ---
 
@@ -16,12 +16,28 @@ Most starter templates only create files. This package creates operating rules f
 You get:
 
 - Multi-agent configuration for Cursor, Copilot, Claude, and generic hosts
-- Deterministic command contracts in `agents/commands/`
+- Deterministic command contracts in `.claude/commands/`
 - Security-first and testing-first rule baselines
 - Reusable skills and optional subagents
 
 Important: this package does not install your framework. It installs the operating layer around your framework.
 
+## What Agents Templated Actually Is
+
+Agents Templated is a project governance and agent-orchestration scaffold.
+
+- It installs a canonical AI policy source (`CLAUDE.md`) and compatibility shims (`AGENTS.MD`, `.github/copilot-instructions.md`, `.cursorrules`).
+- It installs deterministic command contracts in `.claude/commands/` for repeatable specialist workflows.
+- It installs reusable skills in `.github/skills/` and optional subagents in `.claude/agents/`.
+- It installs rule modules in `.claude/rules/` for security, testing, planning, workflows, and guardrails.
+- It includes `validate`, `doctor`, `update`, and `workflow` commands to keep scaffolds healthy over time.
+
+What it is not:
+
+- Not a framework generator.
+- Not a dependency installer for your app stack.
+- Not a replacement for your application architecture.
+
 ## 30-Second Start
 
 ### 1. Install setup
@@ -161,10 +177,8 @@ your-project/
 │   │   ├── system-workflow.md
 │   │   ├── hardening.md
 │   │   └── lessons-learned.md
-│   └── agents/                     # Optional subagents
-│
-├── agents/                          # Deterministic command contracts
-│   └── commands/
+│   ├── agents/                     # Optional subagents
+│   └── commands/                   # Deterministic command contracts
 │   │   ├── SCHEMA.md              # Global slash-command response schema
 │   │   ├── plan.md                # /plan contract
 │   │   ├── fix.md                 # /fix contract
@@ -237,13 +251,31 @@ These commands provide deterministic specialist guidance aligned to the sprint l
 | `arch-check` | Architecture Reviewer | Lock architecture and edge-case coverage |
 | `ux-bar` | Design Quality Lead | Raise UX quality before implementation |
 | `debug-track` | Root-Cause Investigator | Reproduce and isolate root cause |
+| `test-data` | Test Data Builder | Prepare deterministic fixtures/seeds for downstream validation |
 | `risk-review` | Release Risk Reviewer | Surface production-risk issues before merge |
 | `perf` | Performance Analyst | Optimize performance and guard against regressions |
 | `release-ready` | Release Coordinator | Prepare release artifacts and final checks |
 | `docs` | Documentation Engineer | Sync docs with shipped behavior |
 | `learn-loop` | Iteration Lead | Capture lessons and next-cycle actions |
 
-Each command maps to deterministic contract files in `agents/commands/` and uses the schema in `agents/commands/SCHEMA.md`.
+Each command maps to deterministic contract files in `.claude/commands/` and uses the schema in `.claude/commands/SCHEMA.md`.
+
+### Deprecated Workflow Aliases
+
+The CLI keeps selected legacy names as non-breaking redirects with deterministic notices.
+
+| Deprecated | Canonical |
+|------------|-----------|
+| `quality-gate` | `risk-review` |
+| `perf-scan` | `perf` |
+| `docs-sync` | `docs` |
+
+Migration guidance:
+
+- Existing scripts continue to work.
+- Alias invocations print a deprecation warning and redirect deterministically.
+- New automation should use canonical names only.
+- Sunset guidance: deprecated aliases remain supported through v2.x and are scheduled for removal in v3.0.
 
 
 ---
@@ -361,11 +393,20 @@ Your AI will follow the enterprise patterns automatically!
 
 | Agent | Responsibility |
 |-------|---------------|
-| **FrontendAgent** | UI/UX, components, design system, accessibility |
-| **BackendAgent** | API, business logic, authentication, middleware |
-| **DatabaseAgent** | Schema design, migrations, query optimization |
-| **TestAgent** | Unit, integration, E2E, accessibility testing |
-| **SecurityAgent** | Input validation, authentication, OWASP compliance |
+| **backend-specialist** | API, business logic, auth middleware, persistence changes |
+| **frontend-specialist** | UI/UX implementation, accessibility, interaction behavior |
+| **qa-specialist** | Design-mode test planning and validation-mode regression gates |
+| **performance-specialist** | Mode-locked performance profiling and load threshold validation |
+| **test-data-builder** | Deterministic fixtures, seeds, and downstream handoff contracts |
+| **security-reviewer** | Conditional security invocation based on trigger thresholds |
+| **dependency-auditor** | CVE/dependency risk auditing and upgrade hygiene |
+| **deployment-specialist** | Ordered deployment phase contract and rollback readiness |
+
+#### Separation-Preservation Sequence Contracts
+
+- Backend implementation lane: `backend-specialist -> build-error-resolver -> compatibility-checker`
+- Review/governance lane: `code-reviewer -> dependency-auditor -> doc-updater`
+- Test-data handoff lane: `qa-specialist(mode=design) -> test-data-builder -> qa-specialist(mode=validation) -> e2e-runner -> performance-specialist(mode=load)`
 
 **Reference**: [AGENTS.MD](AGENTS.MD)
 

package/bin/cli.js

@@ -10,6 +10,7 @@ const {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveCommandsDir,
   resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan
@@ -27,9 +28,14 @@ const {
   WORKFLOW_COMMANDS,
   CONTRACT_FILES,
   SPECIALIST_CONTRACT_FILES,
+  DEPRECATED_COMMAND_ALIASES,
   formatWorkflowOutput,
   validateWorkflowDefinitions
 } = require('../lib/workflow');
+const {
+  WorkflowOrchestrator,
+  formatOrchestrationOutput
+} = require('../lib/orchestrator');
 
 // Resolve the templates directory - works in both dev and installed contexts
 const getTemplatesDir = () => {
@@ -141,7 +147,7 @@ program
               { name: 'Documentation files (agent-docs/)', value: 'docs' },
               { name: 'Agent rules (.claude/rules/*.md)', value: 'rules' },
               { name: 'Skills (.github/skills/*)', value: 'skills' },
-              { name: 'Command contracts (agents/commands/*.md)', value: 'commands' },
+              { name: 'Command contracts (.claude/commands/*.md)', value: 'commands' },
               { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
               { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
             ],
@@ -205,10 +211,10 @@ program
       // Install deterministic command contracts
       if (installAll || choices.includes('commands')) {
         console.log(chalk.yellow('Installing command contracts...'));
-        await fs.ensureDir(path.join(targetDir, 'agents', 'commands'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.commandsDir));
         await copyDirectory(
           path.join(templateDir, 'agents', 'commands'),
-          path.join(targetDir, 'agents', 'commands'),
+          path.join(targetDir, LAYOUT.canonical.commandsDir),
           options.force
         );
       }
@@ -286,7 +292,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: 'Command contracts (agents/commands/*.md)', value: 'commands' },
+                { name: 'Command contracts (.claude/commands/*.md)', value: 'commands' },
                 { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
                 { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
               ],
@@ -324,7 +330,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: 'Command contracts (agents/commands/*.md)', value: 'commands', checked: true },
+            { name: 'Command contracts (.claude/commands/*.md)', value: 'commands', checked: true },
             { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true },
             { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents', checked: true }
           ],
@@ -390,10 +396,10 @@ program
       // Install deterministic command contracts
       if (options.commands) {
         console.log(chalk.yellow('Installing command contracts...'));
-        await fs.ensureDir(path.join(targetDir, 'agents', 'commands'));
+        await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.commandsDir));
         await copyDirectory(
           path.join(templateDir, 'agents', 'commands'),
-          path.join(targetDir, 'agents', 'commands'),
+          path.join(targetDir, LAYOUT.canonical.commandsDir),
           options.force
         );
       }
@@ -447,7 +453,7 @@ program
     console.log(chalk.yellow('docs') + '    - Documentation files (agent-docs/ directory)');
     console.log(chalk.yellow('rules') + '   - Agent rules (.claude/rules/*.md)');
     console.log(chalk.yellow('skills') + '  - Agent skills (.github/skills/*)');
-    console.log(chalk.yellow('commands') + ' - Deterministic command contracts (agents/commands/*.md)');
+    console.log(chalk.yellow('commands') + ' - Deterministic command contracts (.claude/commands/*.md)');
     console.log(chalk.yellow('github') + '  - AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)');
     console.log(chalk.yellow('subagents') + ' - Agent subagents (.claude/agents/*.md)');
     console.log(chalk.yellow('all') + '     - All components');
@@ -542,27 +548,35 @@ program
         warnings.push(`⚠ ${LAYOUT.canonical.skillsDir} directory missing - run 'agents-templated init --skills'`);
       }
 
-      const commandsDir = path.join(targetDir, 'agents', 'commands');
+      const canonicalCommandsDir = path.join(targetDir, LAYOUT.canonical.commandsDir);
+      const legacyCommandsDir = path.join(targetDir, LAYOUT.legacy.commandsDirs[0]);
+      const commandsDir = path.join(targetDir, resolveCommandsDir(targetDir));
+
+      if (!(await fs.pathExists(canonicalCommandsDir)) && await fs.pathExists(legacyCommandsDir)) {
+        issues.push(`✗ Legacy command contract layout detected at ${LAYOUT.legacy.commandsDirs[0]} - run 'agents-templated update --all' to migrate`);
+      }
+
       if (await fs.pathExists(commandsDir)) {
+        const relativeCommandsDir = path.relative(targetDir, commandsDir) || LAYOUT.canonical.commandsDir;
         for (const contractFile of CONTRACT_FILES) {
           const contractPath = path.join(commandsDir, contractFile);
           if (await fs.pathExists(contractPath)) {
-            passed.push(`✓ agents/commands/${contractFile} found`);
+            passed.push(`✓ ${relativeCommandsDir}/${contractFile} found`);
           } else {
-            warnings.push(`⚠ agents/commands/${contractFile} missing`);
+            warnings.push(`⚠ ${relativeCommandsDir}/${contractFile} missing`);
           }
         }
 
         for (const contractFile of SPECIALIST_CONTRACT_FILES) {
           const contractPath = path.join(commandsDir, contractFile);
           if (await fs.pathExists(contractPath)) {
-            passed.push(`✓ agents/commands/${contractFile} found`);
+            passed.push(`✓ ${relativeCommandsDir}/${contractFile} found`);
           } else {
-            warnings.push(`⚠ agents/commands/${contractFile} missing`);
+            warnings.push(`⚠ ${relativeCommandsDir}/${contractFile} missing`);
           }
         }
       } else {
-        warnings.push(`⚠ agents/commands directory missing - run 'agents-templated init --commands'`);
+        warnings.push(`⚠ ${LAYOUT.canonical.commandsDir} directory missing - run 'agents-templated init --commands'`);
       }
 
       // Check subagents
@@ -786,10 +800,10 @@ async function updateSelectedComponents(targetDir, templateDir, selectedComponen
 
   if (components.includes('commands')) {
     console.log(chalk.yellow('Updating command contracts...'));
-    await fs.ensureDir(path.join(targetDir, 'agents', 'commands'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.commandsDir));
     await copyDirectory(
       path.join(templateDir, 'agents', 'commands'),
-      path.join(targetDir, 'agents', 'commands'),
+      path.join(targetDir, LAYOUT.canonical.commandsDir),
       overwrite
     );
   }
@@ -930,8 +944,8 @@ program
         { targetFile: `${LAYOUT.canonical.skillsDir}/error-patterns/SKILL.md`, templateFile: 'agents/skills/error-patterns/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: `${LAYOUT.canonical.skillsDir}/shadcn-ui/SKILL.md`, templateFile: 'agents/skills/shadcn-ui/SKILL.md', component: 'skills' },
-        { targetFile: 'agents/commands/SCHEMA.md', templateFile: 'agents/commands/SCHEMA.md', component: 'commands' },
-        { targetFile: 'agents/commands/README.md', templateFile: 'agents/commands/README.md', component: 'commands' }
+        { targetFile: `${LAYOUT.canonical.commandsDir}/SCHEMA.md`, templateFile: 'agents/commands/SCHEMA.md', component: 'commands' },
+        { targetFile: `${LAYOUT.canonical.commandsDir}/README.md`, templateFile: 'agents/commands/README.md', component: 'commands' }
       ];
 
       for (const {targetFile, templateFile, component} of checkFiles) {
@@ -1109,6 +1123,32 @@ program
     console.log(chalk.white('  agents-templated problem-map "daily briefing app for founders"\n'));
   });
 
+program
+  .command('orchestrate [objective...]')
+  .description('Automatically route a high-level objective across specialist subagents')
+  .option('--scenario <id>', 'Force a specific scenario id (feature-delivery, backend-api, frontend-feature, bug-fix, deployment)')
+  .option('--mode <mode>', 'slash-command or slash-command-auto', 'slash-command-auto')
+  .option('--retry-cycle <n>', 'Current retry cycle for refactor-cleaner/build-error-resolver loop control', '0')
+  .option('--json', 'Emit structured JSON only')
+  .action((objective, options) => {
+    const objectiveText = Array.isArray(objective) ? objective.join(' ') : '';
+    const retryCycle = Number.parseInt(options.retryCycle, 10);
+    const orchestrator = new WorkflowOrchestrator();
+    const result = orchestrator.orchestrate({
+      objective: objectiveText,
+      scenarioId: options.scenario,
+      mode: options.mode,
+      retryCycle: Number.isNaN(retryCycle) ? 0 : retryCycle
+    });
+
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return;
+    }
+
+    process.stdout.write(formatOrchestrationOutput(result));
+  });
+
 for (const workflow of WORKFLOW_COMMANDS) {
   program
     .command(`${workflow.cli} [objective...]`)
@@ -1119,6 +1159,24 @@ for (const workflow of WORKFLOW_COMMANDS) {
     });
 }
 
+for (const deprecatedAlias of DEPRECATED_COMMAND_ALIASES) {
+  program
+    .command(`${deprecatedAlias.from} [objective...]`)
+    .description(`Deprecated alias for ${deprecatedAlias.to}`)
+    .action((objective) => {
+      const objectiveText = Array.isArray(objective) ? objective.join(' ') : '';
+      const redirectedWorkflow = WORKFLOW_COMMANDS.find((workflow) => workflow.cli === deprecatedAlias.to);
+
+      if (!redirectedWorkflow) {
+        console.error(chalk.red(`Deprecated alias target not found: ${deprecatedAlias.to}`));
+        process.exit(1);
+      }
+
+      console.log(chalk.yellow(`[deprecated] ${deprecatedAlias.notice}`));
+      process.stdout.write(formatWorkflowOutput(redirectedWorkflow, objectiveText));
+    });
+}
+
 program
   .command('new-skill <name>')
   .description('Scaffold a new skill in .github/skills/<name>/SKILL.md')

package/index.js

@@ -72,10 +72,10 @@ async function install(targetDir, options = {}) {
 
   // Deterministic command contracts
   if (installAll || options.commands) {
-    await fs.ensureDir(path.join(targetDir, 'agents', 'commands'));
+    await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.commandsDir));
     await copyDirectory(
       path.join(templateDir, 'agents', 'commands'),
-      path.join(targetDir, 'agents', 'commands'),
+      path.join(targetDir, LAYOUT.canonical.commandsDir),
       options.force
     );
   }

package/lib/layout.js

@@ -6,11 +6,13 @@ const LAYOUT = {
     docsDir: 'agent-docs',
     rulesDir: '.claude/rules',
     skillsDir: '.github/skills',
-    subagentsDir: '.claude/agents'
+    subagentsDir: '.claude/agents',
+    commandsDir: '.claude/commands'
   },
   legacy: {
     rulesDirs: ['agents/rules'],
-    skillsDirs: ['agents/skills']
+    skillsDirs: ['agents/skills'],
+    commandsDirs: ['agents/commands']
   },
   compatible: {
     rulesDirs: [],
@@ -45,16 +47,26 @@ function resolveSubagentsDir(baseDir) {
   return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.subagentsDir;
 }
 
+function resolveCommandsDir(baseDir) {
+  const candidates = [
+    LAYOUT.canonical.commandsDir,
+    ...LAYOUT.legacy.commandsDirs
+  ];
+  return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.commandsDir;
+}
+
 async function hasAnyLayout(baseDir) {
   const checks = [
     path.join(baseDir, LAYOUT.canonical.rulesDir),
     path.join(baseDir, LAYOUT.canonical.skillsDir),
     path.join(baseDir, LAYOUT.canonical.subagentsDir),
+    path.join(baseDir, LAYOUT.canonical.commandsDir),
     path.join(baseDir, 'agents', 'subagents'),
     ...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))
+    ...LAYOUT.legacy.skillsDirs.map((relPath) => path.join(baseDir, relPath)),
+    ...LAYOUT.legacy.commandsDirs.map((relPath) => path.join(baseDir, relPath))
   ];
 
   for (const checkPath of checks) {
@@ -91,6 +103,17 @@ async function getLegacyMigrationPlan(baseDir) {
     }
   }
 
+  for (const relPath of LAYOUT.legacy.commandsDirs) {
+    const from = path.join(baseDir, relPath);
+    if (await fs.pathExists(from)) {
+      plan.push({
+        type: 'directory',
+        source: relPath,
+        target: LAYOUT.canonical.commandsDir
+      });
+    }
+  }
+
   return plan;
 }
 
@@ -98,6 +121,7 @@ module.exports = {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveCommandsDir,
   resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan