agents-templated 2.2.13 → 2.2.15

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,39 @@ 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.
+
+## Orchestration-First Workflow (Current Model)
+
+The current model is orchestration-first: give one objective and let the CLI generate a deterministic multi-phase specialist handoff.
+
+- Use `agents-templated orchestrate "<objective>"` to run end-to-end routing.
+- Subagent selection is automatic and policy-driven from `CLAUDE.md`.
+- Mode-locked specialists require explicit mode handling (`qa-specialist`, `performance-specialist`).
+- Security escalation is conditionally mandatory based on trigger conditions.
+- Deprecated specialist aliases are redirected to canonical agents with explicit notices.
+- Orchestration stops on blocked/failed phases and returns structured stop conditions.
+
+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
@@ -35,6 +62,7 @@ npx agents-templated@latest wizard
 ```bash
 agents-templated workflow
 agents-templated problem-map "daily briefing assistant for founders"
+agents-templated orchestrate "build auth API and admin dashboard"
 ```
 
 ### 3. Optional preset bootstrap
@@ -95,6 +123,7 @@ Your AI assistant will auto-load the configurations and follow enterprise patter
 | **Interactive Wizard** | Guided setup with personalized recommendations |
 | **AI Agents Supported** | Cursor, GitHub Copilot, Claude, and generic agents via `AGENTS.MD` |
 | **Deterministic Commands** | Slash-command contracts with strict structured outputs |
+| **Automatic Orchestration** | Objective-to-specialist auto-routing via `orchestrate` with deterministic phase outputs |
 | **Intent-Routing Ready** | Command schema supports `slash-command-auto` mode for agent-side routing policies |
 | **Security-First** | OWASP Top 10 protection patterns built-in |
 | **Hardening Workflow** | Risk-based hardening rules plus verification/release gates |
@@ -161,10 +190,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
@@ -224,6 +251,7 @@ agents-templated list
 
 # Lifecycle workflow and specialist commands
 agents-templated workflow
+agents-templated orchestrate "build auth API and dashboard"
 ```
 
 ### Workflow Commands
@@ -244,7 +272,29 @@ These commands provide deterministic specialist guidance aligned to the sprint l
 | `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`.
+
+### Automatic Orchestration Command
+
+Use orchestration when you want the system to chain specialists automatically from one objective.
+
+```bash
+# Human-readable orchestration summary
+agents-templated orchestrate "build auth API and dashboard"
+
+# Structured output for pipelines and automation
+agents-templated orchestrate "prepare production deployment" --json
+
+# Force a specific scenario
+agents-templated orchestrate "ship release candidate" --scenario deployment --json
+```
+
+Orchestration behavior:
+
+- Uses deterministic routing and phase sequencing.
+- Enforces mode-lock constraints for `qa-specialist` and `performance-specialist`.
+- Includes deprecation notices when legacy aliases are routed.
+- Emits structured stop conditions if a phase is blocked or fails.
 
 ### Deprecated Workflow Aliases
 

package/bin/cli.js

@@ -10,6 +10,7 @@ const {
   LAYOUT,
   resolveRulesDir,
   resolveSkillsDir,
+  resolveCommandsDir,
   resolveSubagentsDir,
   hasAnyLayout,
   getLegacyMigrationPlan
@@ -146,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' }
             ],
@@ -210,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
         );
       }
@@ -291,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' }
               ],
@@ -329,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 }
           ],
@@ -395,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
         );
       }
@@ -452,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');
@@ -547,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
@@ -791,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
     );
   }
@@ -935,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) {

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

package/lib/workflow.js

@@ -542,13 +542,13 @@ function formatWorkflowOutput(workflow, objective) {
     `  Objective: ${goal}`,
     '',
     'Execution contract',
-    `  Template file: agents/commands/${workflow.contract}`,
+    `  Template file: .claude/commands/${workflow.contract}`,
     '  Mode: deterministic structured output only',
     '  Safety: destructive actions require CONFIRM-DESTRUCTIVE:<target>',
     '',
     'Recommended next actions',
     '  1. Ensure command contracts are installed: agents-templated init --commands',
-    '  2. Open agents/commands/README.md and follow the contract sections',
+    '  2. Open .claude/commands/README.md and follow the contract sections',
     '  3. Use agents-templated workflow to see the full sprint sequence',
     ''
   ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "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/README.md

@@ -16,7 +16,7 @@ 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
 
@@ -163,8 +163,7 @@ your-project/
 │   │   └── lessons-learned.md
 │   └── agents/                     # Optional subagents
 │
-├── agents/                          # Deterministic command contracts
-│   └── commands/
+│   ├── commands/                   # Deterministic command contracts
 │   │   ├── SCHEMA.md              # Global slash-command response schema
 │   │   ├── plan.md                # /plan contract
 │   │   ├── fix.md                 # /fix contract
@@ -244,7 +243,7 @@ These commands provide deterministic specialist guidance aligned to the sprint l
 | `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
 

package/templates/agents/commands/README.md

@@ -3,7 +3,7 @@
 This directory is the modular source of truth for slash-command execution contracts.
 
 - Global protocol and safety framework: `AGENTS.MD` → `Deterministic Slash Command System Standard`
-- Global response schema: `agents/commands/SCHEMA.md`
+- Global response schema: `.claude/commands/SCHEMA.md`
 - Command contracts:
   - `plan.md`
   - `task.md`
@@ -39,10 +39,11 @@ Execution requirements:
 
 ## Publish Inclusion
 
-The npm package includes command contracts from both:
+The npm package scaffolds command contracts into `.claude/commands/`.
 
-- `agents/commands/` (root mirror)
-- `templates/agents/commands/` (scaffold source)
+Template source path in this repository:
+
+- `templates/agents/commands/`
 
 ## Workflow Command Mapping