agents-templated 2.2.10 → 2.2.11

package/bin/cli.js

@@ -23,6 +23,13 @@ const {
   scaffoldRule,
   scaffoldSubagent
 } = require('../lib/instructions');
+const {
+  WORKFLOW_COMMANDS,
+  CONTRACT_FILES,
+  SPECIALIST_CONTRACT_FILES,
+  formatWorkflowOutput,
+  validateWorkflowDefinitions
+} = require('../lib/workflow');
 
 // Resolve the templates directory - works in both dev and installed contexts
 const getTemplatesDir = () => {
@@ -40,6 +47,15 @@ const getTemplatesDir = () => {
 };
 
 const program = new Command();
+const workflowValidationIssues = validateWorkflowDefinitions();
+
+if (workflowValidationIssues.length > 0) {
+  console.error(chalk.red('Invalid workflow command definitions detected:'));
+  workflowValidationIssues.forEach((issue) => {
+    console.error(chalk.red(`  - ${issue}`));
+  });
+  process.exit(1);
+}
 
 program
   .name('agents-templated')
@@ -53,6 +69,7 @@ program
   .option('-d, --docs', 'Install documentation files only')
   .option('-r, --rules', 'Install agent rules only')
   .option('-s, --skills', 'Install skills only')
+  .option('-C, --commands', 'Install deterministic command contracts 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)')
@@ -113,7 +130,7 @@ program
       let choices = [];
       
       // If no specific options provided, prompt user
-      if (!options.all && !options.docs && !options.rules && !options.skills && !options.github) {
+      if (!options.all && !options.docs && !options.rules && !options.skills && !options.commands && !options.github) {
         const answers = await inquirer.prompt([
           {
             type: 'checkbox',
@@ -124,6 +141,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: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
               { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
             ],
@@ -146,6 +164,7 @@ program
         if (options.docs) choices.push('docs');
         if (options.rules) choices.push('rules');
         if (options.skills) choices.push('skills');
+        if (options.commands) choices.push('commands');
         if (options.github) choices.push('github');
         if (options.subagents) choices.push('subagents');
       }
@@ -183,6 +202,17 @@ 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 copyDirectory(
+          path.join(templateDir, 'agents', 'commands'),
+          path.join(targetDir, 'agents', 'commands'),
+          options.force
+        );
+      }
+
       // Install AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)
       if (installAll || choices.includes('github')) {
         console.log(chalk.yellow('Installing AI agent instructions...'));
@@ -256,6 +286,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: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
                 { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
               ],
@@ -293,6 +324,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: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true },
             { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents', checked: true }
           ],
@@ -319,6 +351,7 @@ program
         docs: componentAnswers.components.includes('docs'),
         rules: componentAnswers.components.includes('rules'),
         skills: componentAnswers.components.includes('skills'),
+        commands: componentAnswers.components.includes('commands'),
         github: componentAnswers.components.includes('github'),
         subagents: componentAnswers.components.includes('subagents')
       };
@@ -354,6 +387,17 @@ program
         );
       }
 
+      // Install deterministic command contracts
+      if (options.commands) {
+        console.log(chalk.yellow('Installing command contracts...'));
+        await fs.ensureDir(path.join(targetDir, 'agents', 'commands'));
+        await copyDirectory(
+          path.join(templateDir, 'agents', 'commands'),
+          path.join(targetDir, 'agents', 'commands'),
+          options.force
+        );
+      }
+
       // Install AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)
       if (options.github) {
         console.log(chalk.yellow('Installing AI agent instructions...'));
@@ -403,9 +447,15 @@ 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('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');
+
+    console.log(chalk.blue.bold('\n\nWorkflow Commands:\n'));
+    WORKFLOW_COMMANDS.forEach(({ cli, specialist, description }) => {
+      console.log(chalk.cyan(cli) + ` - ${specialist}: ${description}`);
+    });
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
     console.log(chalk.cyan('nextjs') + '       - Next.js with TypeScript, React, and Tailwind CSS');
@@ -492,6 +542,29 @@ program
         warnings.push(`⚠ ${LAYOUT.canonical.skillsDir} directory missing - run 'agents-templated init --skills'`);
       }
 
+      const commandsDir = path.join(targetDir, 'agents', 'commands');
+      if (await fs.pathExists(commandsDir)) {
+        for (const contractFile of CONTRACT_FILES) {
+          const contractPath = path.join(commandsDir, contractFile);
+          if (await fs.pathExists(contractPath)) {
+            passed.push(`✓ agents/commands/${contractFile} found`);
+          } else {
+            warnings.push(`⚠ agents/commands/${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`);
+          } else {
+            warnings.push(`⚠ agents/commands/${contractFile} missing`);
+          }
+        }
+      } else {
+        warnings.push(`⚠ agents/commands directory missing - run 'agents-templated init --commands'`);
+      }
+
       // Check subagents
       const subagentsDir = path.join(targetDir, LAYOUT.canonical.subagentsDir);
       if (await fs.pathExists(subagentsDir)) {
@@ -678,7 +751,7 @@ async function cleanupLegacyInstructionFiles(targetDir) {
 
 async function updateSelectedComponents(targetDir, templateDir, selectedComponents, overwrite = true) {
   const components = selectedComponents.includes('all')
-    ? ['docs', 'rules', 'skills', 'github', 'subagents']
+    ? ['docs', 'rules', 'skills', 'commands', 'github', 'subagents']
     : selectedComponents;
 
   if (components.includes('docs')) {
@@ -711,6 +784,16 @@ 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 copyDirectory(
+      path.join(templateDir, 'agents', 'commands'),
+      path.join(targetDir, 'agents', 'commands'),
+      overwrite
+    );
+  }
+
   if (components.includes('github')) {
     console.log(chalk.yellow('Updating AI agent instructions...'));
     await writeGeneratedInstructions(targetDir, templateDir, overwrite);
@@ -760,6 +843,7 @@ program
   .option('-d, --docs', 'Update documentation files only')
   .option('-r, --rules', 'Update agent rules only')
   .option('-s, --skills', 'Update skills only')
+  .option('-C, --commands', 'Update deterministic command contracts 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')
@@ -812,7 +896,7 @@ program
         console.log(chalk.green('✓ Legacy layout migration completed.\n'));
       }
 
-      const hasComponentSelection = options.all || options.docs || options.rules || options.skills || options.github;
+      const hasComponentSelection = options.all || options.docs || options.rules || options.skills || options.commands || options.github || options.subagents;
 
       // Component refresh mode: update selected parts directly without stack/wizard prompts
       if (hasComponentSelection) {
@@ -820,6 +904,7 @@ program
         if (options.all || options.docs) selectedComponents.push('docs');
         if (options.all || options.rules) selectedComponents.push('rules');
         if (options.all || options.skills) selectedComponents.push('skills');
+        if (options.all || options.commands) selectedComponents.push('commands');
         if (options.all || options.github) selectedComponents.push('github');
         if (options.all || options.subagents) selectedComponents.push('subagents');
 
@@ -844,7 +929,9 @@ program
         { targetFile: `${LAYOUT.canonical.skillsDir}/find-skills/SKILL.md`, templateFile: 'agents/skills/find-skills/SKILL.md', component: 'skills' },
         { 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: `${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' }
       ];
 
       for (const {targetFile, templateFile, component} of checkFiles) {
@@ -1007,6 +1094,31 @@ program
     }
   });
 
+program
+  .command('workflow')
+  .description('Show the lifecycle workflow and specialist commands')
+  .alias('sprint')
+  .action(() => {
+    console.log(chalk.blue.bold('\nWorkflow Lifecycle\n'));
+    console.log(chalk.white('Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect\n'));
+    WORKFLOW_COMMANDS.forEach(({ cli, specialist, slash, description }) => {
+      console.log(chalk.cyan(cli) + ` (${slash})`);
+      console.log(chalk.gray(`  ${specialist} - ${description}`));
+    });
+    console.log(chalk.gray('\nRun any workflow command with an objective, for example:'));
+    console.log(chalk.white('  agents-templated problem-map "daily briefing app for founders"\n'));
+  });
+
+for (const workflow of WORKFLOW_COMMANDS) {
+  program
+    .command(`${workflow.cli} [objective...]`)
+    .description(`${workflow.specialist}: ${workflow.description}`)
+    .action((objective) => {
+      const objectiveText = Array.isArray(objective) ? objective.join(' ') : '';
+      process.stdout.write(formatWorkflowOutput(workflow, objectiveText));
+    });
+}
+
 program
   .command('new-skill <name>')
   .description('Scaffold a new skill in .github/skills/<name>/SKILL.md')

package/index.js

@@ -15,6 +15,7 @@ const { CANONICAL_INSTRUCTION_FILE, writeGeneratedInstructions } = require('./li
  * @param {boolean} options.docs - Install documentation files
  * @param {boolean} options.rules - Install agent rules
  * @param {boolean} options.skills - Install skills
+ * @param {boolean} options.commands - Install deterministic command contracts
  * @param {boolean} options.github - Install GitHub Copilot instructions
  * @param {boolean} options.subagents - Install agent subagents
  * @param {boolean} options.force - Overwrite existing files
@@ -22,7 +23,7 @@ const { CANONICAL_INSTRUCTION_FILE, writeGeneratedInstructions } = require('./li
  */
 async function install(targetDir, options = {}) {
   const templateDir = path.join(__dirname, 'templates');
-  const installAll = !options.docs && !options.rules && !options.skills && !options.github && !options.subagents;
+  const installAll = !options.docs && !options.rules && !options.skills && !options.commands && !options.github && !options.subagents;
 
   const files = [];
 
@@ -69,6 +70,16 @@ async function install(targetDir, options = {}) {
     );
   }
 
+  // Deterministic command contracts
+  if (installAll || options.commands) {
+    await fs.ensureDir(path.join(targetDir, 'agents', 'commands'));
+    await copyDirectory(
+      path.join(templateDir, 'agents', 'commands'),
+      path.join(targetDir, 'agents', 'commands'),
+      options.force
+    );
+  }
+
   // AI Agent instructions (Cursor, Copilot, Claude)
   if (installAll || options.github) {
     await writeGeneratedInstructions(targetDir, templateDir, options.force);

package/lib/workflow.js

@@ -0,0 +1,190 @@
+const WORKFLOW_COMMANDS = [
+  {
+    cli: 'problem-map',
+    slash: '/problem-map',
+    purpose: 'problem-framing',
+    specialist: 'Problem Strategist',
+    contract: 'plan.md',
+    description: 'Clarify user pain and define the real problem before implementation.'
+  },
+  {
+    cli: 'scope-shape',
+    slash: '/scope-shape',
+    purpose: 'scope-decision',
+    specialist: 'Scope Director',
+    contract: 'plan.md',
+    description: 'Challenge scope and lock the highest-leverage direction.'
+  },
+  {
+    cli: 'arch-check',
+    slash: '/arch-check',
+    purpose: 'architecture-readiness',
+    specialist: 'Architecture Reviewer',
+    contract: 'plan.md',
+    description: 'Lock architecture, edge cases, and test strategy before build.'
+  },
+  {
+    cli: 'ux-bar',
+    slash: '/ux-bar',
+    purpose: 'ux-quality-readiness',
+    specialist: 'Design Quality Lead',
+    contract: 'plan.md',
+    description: 'Assess UX quality and close design gaps before implementation.'
+  },
+  {
+    cli: 'debug-track',
+    slash: '/debug-track',
+    purpose: 'root-cause-investigation',
+    specialist: 'Root-Cause Investigator',
+    contract: 'fix.md',
+    description: 'Reproduce issues and isolate root cause before applying fixes.'
+  },
+  {
+    cli: 'risk-review',
+    slash: '/risk-review',
+    purpose: 'release-risk-assessment',
+    specialist: 'Release Risk Reviewer',
+    contract: 'audit.md',
+    description: 'Run a production-risk review on active changes.'
+  },
+  {
+    cli: 'quality-gate',
+    slash: '/quality-gate',
+    purpose: 'quality-gating',
+    specialist: 'Quality Gatekeeper',
+    contract: 'test.md',
+    description: 'Validate behavior, capture regressions, and enforce quality gates.'
+  },
+  {
+    cli: 'perf-scan',
+    slash: '/perf-scan',
+    purpose: 'performance-regression-check',
+    specialist: 'Performance Analyst',
+    contract: 'perf.md',
+    description: 'Record baseline performance and compare before/after changes.'
+  },
+  {
+    cli: 'release-ready',
+    slash: '/release-ready',
+    purpose: 'release-readiness',
+    specialist: 'Release Coordinator',
+    contract: 'release.md',
+    description: 'Prepare release branch, tests, and release checklist artifacts.'
+  },
+  {
+    cli: 'docs-sync',
+    slash: '/docs-sync',
+    purpose: 'documentation-synchronization',
+    specialist: 'Documentation Engineer',
+    contract: 'docs.md',
+    description: 'Update README and architecture docs to match shipped behavior.'
+  },
+  {
+    cli: 'learn-loop',
+    slash: '/learn-loop',
+    purpose: 'retrospective-action-loop',
+    specialist: 'Iteration Lead',
+    contract: 'task.md',
+    description: 'Capture wins, misses, and next-cycle improvements.'
+  }
+];
+
+const CONTRACT_FILES = [
+  'SCHEMA.md',
+  'README.md',
+  'plan.md',
+  'task.md',
+  'scaffold.md',
+  'fix.md',
+  'refactor.md',
+  'audit.md',
+  'perf.md',
+  'test.md',
+  'pr.md',
+  'release.md',
+  'docs.md'
+];
+
+const SPECIALIST_CONTRACT_FILES = [
+  'problem-map.md',
+  'scope-shape.md',
+  'arch-check.md',
+  'ux-bar.md',
+  'debug-track.md',
+  'risk-review.md',
+  'quality-gate.md',
+  'perf-scan.md',
+  'release-ready.md',
+  'docs-sync.md',
+  'learn-loop.md'
+];
+
+const DEPRECATED_COMMAND_ALIASES = [];
+
+function formatWorkflowOutput(workflow, objective) {
+  const trimmedObjective = (objective || '').trim();
+  const goal = trimmedObjective.length > 0 ? trimmedObjective : 'No explicit objective provided';
+
+  return [
+    '',
+    'Workflow command',
+    `  Command: ${workflow.cli}`,
+    `  Slash contract: ${workflow.slash}`,
+    `  Specialist: ${workflow.specialist}`,
+    `  Objective: ${goal}`,
+    '',
+    'Execution contract',
+    `  Template file: agents/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',
+    '  3. Use agents-templated workflow to see the full sprint sequence',
+    ''
+  ].join('\n');
+}
+
+function validateWorkflowDefinitions() {
+  const seenCli = new Set();
+  const seenSlash = new Set();
+  const seenPurpose = new Set();
+  const issues = [];
+
+  for (const workflow of WORKFLOW_COMMANDS) {
+    if (seenCli.has(workflow.cli)) {
+      issues.push(`Duplicate cli command: ${workflow.cli}`);
+    }
+    seenCli.add(workflow.cli);
+
+    if (seenSlash.has(workflow.slash)) {
+      issues.push(`Duplicate slash command: ${workflow.slash}`);
+    }
+    seenSlash.add(workflow.slash);
+
+    if (!workflow.purpose) {
+      issues.push(`Missing purpose for command: ${workflow.cli}`);
+    } else if (seenPurpose.has(workflow.purpose)) {
+      issues.push(`Duplicate command purpose: ${workflow.purpose}`);
+    }
+    seenPurpose.add(workflow.purpose);
+  }
+
+  for (const alias of DEPRECATED_COMMAND_ALIASES) {
+    if (seenCli.has(alias.from)) {
+      issues.push(`Alias conflicts with active command name: ${alias.from}`);
+    }
+  }
+
+  return issues;
+}
+
+module.exports = {
+  WORKFLOW_COMMANDS,
+  CONTRACT_FILES,
+  SPECIALIST_CONTRACT_FILES,
+  DEPRECATED_COMMAND_ALIASES,
+  formatWorkflowOutput,
+  validateWorkflowDefinitions
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.2.10",
+  "version": "2.2.11",
   "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": {
@@ -37,6 +37,7 @@
   "files": [
     "bin",
     "lib",
+    "agents",
     "templates",
     "templates/presets",
     "index.js",

package/templates/CLAUDE.md

@@ -36,6 +36,8 @@ All policy, routing, and skill governance lives here — edit this file directly
 | feature-delivery | `.github/skills/feature-delivery/SKILL.md` | Build/add/implement feature work |
 | find-skills | `.github/skills/find-skills/SKILL.md` | User asks to discover a skill |
 | ui-ux-pro-max | `.github/skills/ui-ux-pro-max/SKILL.md` | UI, layout, design, visual work |
+| emilkowalski-skill | `.github/skills/emilkowalski-skill/SKILL.md` | Frontend polish, animation quality, interaction refinement |
+| raphaelsalaja-userinterface-wiki | `.github/skills/raphaelsalaja-userinterface-wiki/SKILL.md` | UI hierarchy, readability, and interface best-practice audits |
 | api-design | `.github/skills/api-design/SKILL.md` | REST/GraphQL API design, OpenAPI specs, versioning |
 | llm-integration | `.github/skills/llm-integration/SKILL.md` | LLM integrations, RAG, prompt engineering, evaluation |