agents-templated 2.2.10 → 2.2.12

package/agents/commands/test.md

@@ -0,0 +1,58 @@
+# /test
+
+## A. Intent
+Run deterministic validation and gate release readiness based on test evidence.
+
+## B. When to Use
+- Use when validating behavior after implementation or before merge/release.
+- This command now includes quality-gate behavior; do not use /quality-gate.
+
+## C. Context Assumptions
+- Test targets are defined.
+- Required environments are available.
+- Pass/fail criteria are explicit.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `test_scope` | string | "api regression" |
+| `test_suites` | string[] | ["unit", "integration", "critical-flow"] |
+| `evidence_artifact` | artifact | test report path or CI run URL |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] test scope is non-empty
+- [ ] critical test suites are executable
+- [ ] pass criteria are declared
+
+## F. Execution Flow
+1. Collect test targets and runtime config.
+2. Execute suites in deterministic order.
+3. Aggregate results and failures.
+4. Decision point ->
+   - condition A -> critical failures present -> gate = blocked
+   - condition B ->  no critical failures -> gate = pass.
+5. Build validation evidence and remediation list.
+6. Emit test and gate report.
+
+## G. Output Schema
+
+```json
+{
+  "test_run_id": "string",
+  "results": ["array","of","strings"],
+  "gate_status": "low | medium | high",
+  "blocker": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- critical test suite cannot run
+- result schema cannot be produced
+
+## J. Safety Constraints
+- Hard block: hard block when critical flow tests fail
+- Warn only: warn when flaky tests are excluded with justification

package/agents/commands/ux-bar.md

@@ -0,0 +1,58 @@
+# /ux-bar
+
+## A. Intent
+Assess UX quality bar and guarantee core interaction states are defined before build.
+
+## B. When to Use
+- Use when UX quality and accessibility need pre-implementation validation.
+- Do not use as a replacement for visual design exploration.
+
+## C. Context Assumptions
+- Scope and architecture are available.
+- Primary user flows are identified.
+- Design references exist.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `ux_goal` | string | "reduce checkout friction" |
+| `flows` | string[] | ["cart", "payment", "confirmation"] |
+| `design_artifact` | artifact | wireframes, Figma link, screenshots |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] critical flows are enumerated
+- [ ] interaction states include loading/error/empty
+- [ ] accessibility checks are defined
+
+## F. Execution Flow
+1. Review flows and interaction states.
+2. Evaluate accessibility and usability risks.
+3. Score UX gaps by severity.
+4. Decision point ->
+   - condition A -> critical UX gap -> block readiness
+   - condition B ->  manageable gaps -> continue.
+5. Build prioritized improvement list.
+6. Emit UX quality package.
+
+## G. Output Schema
+
+```json
+{
+  "ux_review_id": "string",
+  "ux_gaps": ["array","of","strings"],
+  "severity": "low | medium | high",
+  "blocker": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- critical flow lacks defined interaction states
+- accessibility baseline is not addressed
+
+## J. Safety Constraints
+- Hard block: hard block on unaddressed critical accessibility failures
+- Warn only: warn when medium UX issues are deferred

package/agents/rules/planning.mdc

@@ -0,0 +1,69 @@
+---
+title: "Planning Discipline"
+description: "Every feature discussion or implementation must produce a reusable prompt plan file in .github/prompts/"
+version: "1.0.0"
+tags: ["planning", "workflow", "documentation", "prompts"]
+alwaysApply: true
+---
+
+## Purpose
+
+Ensure every feature discussion, design decision, or implementation produces a reusable prompt plan stored in `.github/prompts/`. Plans persist across sessions and serve as living context for future work — they are never discarded.
+
+## When to Apply
+
+This rule is always active. Trigger when:
+
+- User asks to implement a new feature
+- A design or architecture decision is being made
+- A significant refactor is planned
+- A bug fix requires non-trivial investigation or systemic changes
+- A discussion produces decisions that affect future work
+
+## Plan File Convention
+
+**Location:** `.github/prompts/`
+**Filename:** `YYYY-MM-DD-{feature-slug}.prompt.md`
+**Format:** VS Code reusable prompt (`.prompt.md` — usable as an `@workspace` prompt in Copilot Chat)
+
+## Required Sections
+
+Each plan file must contain:
+
+```
+---
+agent: agent
+description: One-line summary of what this plan covers.
+---
+
+## Context
+Brief background — what problem are we solving and why now.
+
+## Decision
+What we decided to do and the reasoning behind it (not just what, but why).
+
+## Steps
+Numbered implementation steps in dependency order.
+
+## Acceptance Criteria
+Concrete, testable outcomes that define "done".
+
+## Status
+- [ ] Not started  /  [ ] In progress  /  [x] Complete
+Blockers (if any):
+```
+
+## Workflow
+
+1. At the start of any feature discussion or implementation, create the plan file immediately.
+2. Use the filename convention: `YYYY-MM-DD-{feature-slug}.prompt.md`.
+3. Fill out **Context**, **Decision**, and **Steps** before starting implementation.
+4. Update **Status** and **Acceptance Criteria** incrementally as work progresses.
+5. Mark the plan complete when implementation is verified and accepted.
+
+## Guardrails
+
+- Do not skip plan creation for "small" features — small decisions accumulate into undocumented technical debt.
+- Plans are never deleted — they form a historical record of architectural decisions.
+- Plan files must not contain secrets, credentials, or PII.
+- If a plan changes significantly mid-implementation, update it in place rather than creating a new one.

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,177 @@
+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: 'perf',
+    slash: '/perf',
+    purpose: 'performance-optimization-and-regression-check',
+    specialist: 'Performance Analyst',
+    contract: 'perf.md',
+    description: 'Optimize performance and validate baseline-vs-candidate regression safety.'
+  },
+  {
+    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',
+    slash: '/docs',
+    purpose: 'documentation-update-and-synchronization',
+    specialist: 'Documentation Engineer',
+    contract: 'docs.md',
+    description: 'Update and synchronize 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',
+  'fix.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',
+  'release-ready.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.12",
   "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",