agents-templated 2.2.11 → 2.2.13

package/lib/workflow.js

@@ -3,6 +3,7 @@ const WORKFLOW_COMMANDS = [
     cli: 'problem-map',
     slash: '/problem-map',
     purpose: 'problem-framing',
+    track: 'planning',
     specialist: 'Problem Strategist',
     contract: 'plan.md',
     description: 'Clarify user pain and define the real problem before implementation.'
@@ -11,6 +12,7 @@ const WORKFLOW_COMMANDS = [
     cli: 'scope-shape',
     slash: '/scope-shape',
     purpose: 'scope-decision',
+    track: 'planning',
     specialist: 'Scope Director',
     contract: 'plan.md',
     description: 'Challenge scope and lock the highest-leverage direction.'
@@ -19,6 +21,7 @@ const WORKFLOW_COMMANDS = [
     cli: 'arch-check',
     slash: '/arch-check',
     purpose: 'architecture-readiness',
+    track: 'backend',
     specialist: 'Architecture Reviewer',
     contract: 'plan.md',
     description: 'Lock architecture, edge cases, and test strategy before build.'
@@ -27,6 +30,7 @@ const WORKFLOW_COMMANDS = [
     cli: 'ux-bar',
     slash: '/ux-bar',
     purpose: 'ux-quality-readiness',
+    track: 'frontend',
     specialist: 'Design Quality Lead',
     contract: 'plan.md',
     description: 'Assess UX quality and close design gaps before implementation.'
@@ -35,6 +39,7 @@ const WORKFLOW_COMMANDS = [
     cli: 'debug-track',
     slash: '/debug-track',
     purpose: 'root-cause-investigation',
+    track: 'qa',
     specialist: 'Root-Cause Investigator',
     contract: 'fix.md',
     description: 'Reproduce issues and isolate root cause before applying fixes.'
@@ -43,60 +48,332 @@ const WORKFLOW_COMMANDS = [
     cli: 'risk-review',
     slash: '/risk-review',
     purpose: 'release-risk-assessment',
+    track: 'release-ops',
     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',
+    cli: 'perf',
+    slash: '/perf',
+    purpose: 'performance-optimization-and-regression-check',
+    track: 'performance',
     specialist: 'Performance Analyst',
     contract: 'perf.md',
-    description: 'Record baseline performance and compare before/after changes.'
+    description: 'Optimize performance and validate baseline-vs-candidate regression safety.'
+  },
+  {
+    cli: 'test-data',
+    slash: '/test-data',
+    purpose: 'test-data-asset-preparation',
+    track: 'test-data',
+    specialist: 'Test Data Builder',
+    contract: 'test.md',
+    description: 'Prepare deterministic fixtures, seeds, and synthetic datasets for downstream validation.'
   },
   {
     cli: 'release-ready',
     slash: '/release-ready',
     purpose: 'release-readiness',
+    track: 'deployment',
     specialist: 'Release Coordinator',
     contract: 'release.md',
     description: 'Prepare release branch, tests, and release checklist artifacts.'
   },
   {
-    cli: 'docs-sync',
-    slash: '/docs-sync',
-    purpose: 'documentation-synchronization',
+    cli: 'docs',
+    slash: '/docs',
+    purpose: 'documentation-update-and-synchronization',
+    track: 'release-ops',
     specialist: 'Documentation Engineer',
     contract: 'docs.md',
-    description: 'Update README and architecture docs to match shipped behavior.'
+    description: 'Update and synchronize README and architecture docs to match shipped behavior.'
   },
   {
     cli: 'learn-loop',
     slash: '/learn-loop',
     purpose: 'retrospective-action-loop',
+    track: 'release-ops',
     specialist: 'Iteration Lead',
     contract: 'task.md',
     description: 'Capture wins, misses, and next-cycle improvements.'
   }
 ];
 
+const ORCHESTRATION_TRACKS = {
+  planning: {
+    subagent: 'planner',
+    skills: ['feature-delivery', 'feature-forge'],
+    goal: 'Clarify objective and lock scope before implementation.'
+  },
+  backend: {
+    subagent: 'backend-specialist',
+    skills: ['secure-code-guardian', 'feature-delivery', 'bug-triage'],
+    goal: 'Design and implement API/data/server-side logic.'
+  },
+  frontend: {
+    subagent: 'frontend-specialist',
+    skills: ['ui-ux-pro-max', 'emilkowalski-skill', 'raphaelsalaja-userinterface-wiki'],
+    goal: 'Design and implement UI, accessibility, and interactions.'
+  },
+  qa: {
+    subagent: 'qa-specialist',
+    skills: ['debug-skill', 'bug-triage'],
+    goal: 'Verify quality gates, regression checks, and issue triage.'
+  },
+  'qa-design': {
+    subagent: 'qa-specialist',
+    skills: ['debug-skill', 'bug-triage'],
+    goal: 'Design test strategy before implementation starts.'
+  },
+  performance: {
+    subagent: 'performance-specialist',
+    skills: ['debug-skill', 'bug-triage'],
+    goal: 'Diagnose bottlenecks and validate load thresholds.'
+  },
+  'test-data': {
+    subagent: 'test-data-builder',
+    skills: ['bug-triage', 'feature-delivery'],
+    goal: 'Build deterministic data assets for downstream validation and load checks.'
+  },
+  'release-ops': {
+    subagent: 'release-ops-specialist',
+    skills: ['app-hardening', 'secure-code-guardian'],
+    goal: 'Harden release, validate risk posture, and synchronize docs.'
+  },
+  deployment: {
+    subagent: 'deployment-specialist',
+    skills: ['app-hardening', 'secure-code-guardian'],
+    goal: 'Prepare and validate deployment execution plans.'
+  }
+};
+
+const ORCHESTRATION_SCENARIOS = [
+  {
+    id: 'feature-delivery',
+    description: 'End-to-end feature lifecycle from framing to release.',
+    keywords: ['feature', 'build', 'implement', 'add', 'create'],
+    phases: [
+      { command: 'problem-map', track: 'planning' },
+      { command: 'scope-shape', track: 'planning' },
+      { command: 'scope-shape', track: 'qa-design' },
+      { command: 'test-data', track: 'test-data' },
+      { command: 'arch-check', track: 'backend' },
+      { command: 'ux-bar', track: 'frontend' },
+      { command: 'debug-track', track: 'qa' },
+      { command: 'perf', track: 'performance' },
+      { command: 'risk-review', track: 'release-ops' },
+      { command: 'release-ready', track: 'deployment' },
+      { command: 'docs', track: 'release-ops' }
+    ]
+  },
+  {
+    id: 'backend-api',
+    description: 'API and backend-focused changes with risk checks.',
+    keywords: ['api', 'backend', 'service', 'database', 'endpoint'],
+    phases: [
+      { command: 'problem-map', track: 'planning' },
+      { command: 'problem-map', track: 'qa-design' },
+      { command: 'arch-check', track: 'backend' },
+      { command: 'test-data', track: 'test-data' },
+      { command: 'debug-track', track: 'qa' },
+      { command: 'perf', track: 'performance' },
+      { command: 'risk-review', track: 'release-ops' },
+      { command: 'release-ready', track: 'deployment' }
+    ]
+  },
+  {
+    id: 'frontend-feature',
+    description: 'UI-focused delivery with quality and release gates.',
+    keywords: ['frontend', 'ui', 'ux', 'design', 'component'],
+    phases: [
+      { command: 'problem-map', track: 'planning' },
+      { command: 'scope-shape', track: 'planning' },
+      { command: 'scope-shape', track: 'qa-design' },
+      { command: 'test-data', track: 'test-data' },
+      { command: 'ux-bar', track: 'frontend' },
+      { command: 'debug-track', track: 'qa' },
+      { command: 'perf', track: 'performance' },
+      { command: 'risk-review', track: 'release-ops' },
+      { command: 'release-ready', track: 'deployment' }
+    ]
+  },
+  {
+    id: 'bug-fix',
+    description: 'Defect-focused sequence with regression protection.',
+    keywords: ['bug', 'fix', 'issue', 'error', 'regression'],
+    phases: [
+      { command: 'debug-track', track: 'qa' },
+      { command: 'perf', track: 'performance' },
+      { command: 'arch-check', track: 'backend' },
+      { command: 'risk-review', track: 'release-ops' },
+      { command: 'release-ready', track: 'deployment' }
+    ]
+  },
+  {
+    id: 'deployment',
+    description: 'Deployment-focused path with risk and release checks.',
+    keywords: ['deploy', 'deployment', 'ship', 'release', 'production'],
+    phases: [
+      { command: 'risk-review', track: 'release-ops' },
+      { command: 'perf', track: 'performance' },
+      { command: 'release-ready', track: 'deployment' },
+      { command: 'docs', track: 'release-ops' },
+      { command: 'learn-loop', track: 'release-ops' }
+    ]
+  }
+];
+
+const OPTIONAL_SUBAGENT_RULES = [
+  {
+    subagent: 'architect',
+    required: false,
+    reason: 'Deep architecture trade-off analysis support.',
+    when: {
+      commands: ['arch-check'],
+      keywords: ['architecture', 'design', 'scalability', 'adr']
+    }
+  },
+  {
+    subagent: 'tdd-guide',
+    required: false,
+    reason: 'Test-first guidance when explicit test strategy is requested.',
+    deprecatedAliasFor: 'qa-specialist',
+    mode: 'design',
+    when: {
+      tracks: ['backend', 'frontend', 'qa'],
+      keywords: ['test', 'tdd', 'coverage', 'unit test']
+    }
+  },
+  {
+    subagent: 'test-data-builder',
+    required: false,
+    reason: 'Prepare deterministic fixtures and seed data for downstream validation phases.',
+    when: {
+      tracks: ['qa-design', 'backend', 'test-data'],
+      keywords: ['test data', 'fixture', 'seed', 'mock', 'dataset', 'migration', 'database']
+    }
+  },
+  {
+    subagent: 'code-reviewer',
+    required: false,
+    reason: 'Static quality review before release risk checkpoints.',
+    when: {
+      commands: ['risk-review'],
+      scenarios: ['feature-delivery', 'bug-fix', 'deployment']
+    }
+  },
+  {
+    subagent: 'security-reviewer',
+    required: false,
+    reason: 'Security audit for auth, secrets, and sensitive data paths.',
+    when: {
+      tracks: ['backend', 'release-ops', 'deployment'],
+      keywords: ['auth', 'token', 'secret', 'security', 'permission', 'pii']
+    }
+  },
+  {
+    subagent: 'build-error-resolver',
+    required: false,
+    reason: 'Targeted build/type/lint failure remediation.',
+    when: {
+      scenarios: ['bug-fix'],
+      keywords: ['build', 'type', 'compile', 'lint', 'error']
+    }
+  },
+  {
+    subagent: 'e2e-runner',
+    required: false,
+    reason: 'E2E execution for journey-level validation after test data handoff.',
+    dependsOnSubagents: ['test-data-builder'],
+    when: {
+      tracks: ['qa', 'frontend'],
+      keywords: ['e2e', 'playwright', 'journey', 'end-to-end', 'validation']
+    }
+  },
+  {
+    subagent: 'refactor-cleaner',
+    required: false,
+    reason: 'Safe dead-code cleanup and refactor hygiene pass.',
+    when: {
+      keywords: ['refactor', 'cleanup', 'dead code', 'unused']
+    }
+  },
+  {
+    subagent: 'doc-updater',
+    required: false,
+    reason: 'Documentation synchronization for release and handoff.',
+    when: {
+      commands: ['docs']
+    }
+  },
+  {
+    subagent: 'performance-specialist',
+    required: false,
+    reason: 'Performance bottleneck profiling for latency/resource risks.',
+    mode: 'profile',
+    when: {
+      tracks: ['performance'],
+      keywords: ['performance', 'latency', 'memory', 'cpu', 'slow', 'profile']
+    }
+  },
+  {
+    subagent: 'dependency-auditor',
+    required: false,
+    reason: 'Dependency and CVE hygiene audit.',
+    when: {
+      tracks: ['backend', 'release-ops', 'deployment'],
+      keywords: ['dependency', 'package', 'cve', 'vulnerability', 'upgrade']
+    }
+  },
+  {
+    subagent: 'configuration-validator',
+    required: false,
+    reason: 'Configuration and environment safety validation.',
+    deprecatedAliasFor: 'deployment-specialist',
+    mode: 'config-validation',
+    when: {
+      scenarios: ['deployment'],
+      keywords: ['config', 'environment', 'env', 'settings']
+    }
+  },
+  {
+    subagent: 'database-migrator',
+    required: false,
+    reason: 'Schema/data migration planning and rollback checks.',
+    when: {
+      tracks: ['backend'],
+      keywords: ['database', 'schema', 'migration', 'sql']
+    }
+  },
+  {
+    subagent: 'performance-specialist',
+    required: false,
+    reason: 'Load and stress validation near release/deployment phases after test data handoff.',
+    mode: 'load',
+    dependsOnSubagents: ['test-data-builder'],
+    when: {
+      tracks: ['performance', 'deployment'],
+      keywords: ['load', 'throughput', 'stress', 'traffic']
+    }
+  },
+  {
+    subagent: 'compatibility-checker',
+    required: false,
+    reason: 'Contract and version compatibility checks for API changes.',
+    when: {
+      tracks: ['backend', 'release-ops'],
+      keywords: ['compatibility', 'breaking', 'contract', 'api version']
+    }
+  }
+];
+
 const CONTRACT_FILES = [
   'SCHEMA.md',
   'README.md',
   'plan.md',
   'task.md',
-  'scaffold.md',
   'fix.md',
-  'refactor.md',
   'audit.md',
   'perf.md',
   'test.md',
@@ -111,15 +388,146 @@ const SPECIALIST_CONTRACT_FILES = [
   'arch-check.md',
   'ux-bar.md',
   'debug-track.md',
+  'test-data.md',
   'risk-review.md',
-  'quality-gate.md',
-  'perf-scan.md',
   'release-ready.md',
-  'docs-sync.md',
   'learn-loop.md'
 ];
 
-const DEPRECATED_COMMAND_ALIASES = [];
+const DEPRECATED_COMMAND_ALIASES = [
+  {
+    from: 'quality-gate',
+    to: 'risk-review',
+    status: 'deprecated',
+    notice: 'quality-gate is deprecated; redirecting to risk-review.'
+  },
+  {
+    from: 'perf-scan',
+    to: 'perf',
+    status: 'deprecated',
+    notice: 'perf-scan is deprecated; redirecting to perf.'
+  },
+  {
+    from: 'docs-sync',
+    to: 'docs',
+    status: 'deprecated',
+    notice: 'docs-sync is deprecated; redirecting to docs.'
+  }
+];
+
+const DEPRECATED_SUBAGENT_ALIASES = {
+  'tdd-guide': {
+    to: 'qa-specialist',
+    mode: 'design',
+    notice: 'tdd-guide is deprecated; redirecting to qa-specialist(mode=design).'
+  },
+  'performance-profiler': {
+    to: 'performance-specialist',
+    mode: 'profile',
+    notice: 'performance-profiler is deprecated; redirecting to performance-specialist(mode=profile).'
+  },
+  'load-tester': {
+    to: 'performance-specialist',
+    mode: 'load',
+    notice: 'load-tester is deprecated; redirecting to performance-specialist(mode=load).'
+  },
+  'configuration-validator': {
+    to: 'deployment-specialist',
+    mode: 'config-validation',
+    notice: 'configuration-validator is deprecated; redirecting to deployment-specialist(mode=config-validation).'
+  }
+};
+
+const NON_OVERLAP_ROUTE_BOUNDARIES = {
+  backendResolutionSubagents: ['build-error-resolver', 'compatibility-checker', 'database-migrator'],
+  reviewSequence: ['code-reviewer', 'dependency-auditor', 'doc-updater'],
+  commandAllowlist: {
+    'arch-check': [
+      'architect',
+      'security-reviewer',
+      'build-error-resolver',
+      'compatibility-checker',
+      'database-migrator',
+      'test-data-builder'
+    ],
+    'risk-review': ['code-reviewer', 'dependency-auditor', 'security-reviewer', 'compatibility-checker'],
+    docs: ['doc-updater', 'security-reviewer']
+  }
+};
+
+const MODE_LOCKED_SPECIALISTS = {
+  'qa-specialist': ['design', 'validation'],
+  'performance-specialist': ['profile', 'load']
+};
+
+const SECURITY_REVIEW_POLICY = {
+  mandatoryKeywords: [
+    'auth',
+    'authorization',
+    'session',
+    'token',
+    'permission',
+    'public endpoint',
+    'parser',
+    'secret',
+    'credential',
+    'cve',
+    'vulnerability',
+    'breaking',
+    'api contract',
+    'production',
+    'threat surface',
+    'pii'
+  ],
+  mediumKeywords: [
+    'input',
+    'transform',
+    'middleware',
+    'integration',
+    'upload',
+    'request',
+    'external'
+  ],
+  mediumThreshold: 3
+};
+
+const REFACTOR_BUILD_RETRY_CAP = 2;
+const REFACTOR_BUILD_HALT_AFTER = REFACTOR_BUILD_RETRY_CAP + 1;
+
+function findScenarioById(id) {
+  if (!id) {
+    return null;
+  }
+
+  return ORCHESTRATION_SCENARIOS.find((scenario) => scenario.id === id) || null;
+}
+
+function resolveScenarioFromObjective(objective) {
+  const normalizedObjective = (objective || '').toLowerCase();
+  let bestScenario = ORCHESTRATION_SCENARIOS[0];
+  let bestScore = -1;
+
+  for (const scenario of ORCHESTRATION_SCENARIOS) {
+    let score = 0;
+    for (const keyword of scenario.keywords) {
+      if (normalizedObjective.includes(keyword)) {
+        score += 1;
+      }
+    }
+
+    if (score > bestScore) {
+      bestScenario = scenario;
+      bestScore = score;
+    }
+  }
+
+  return {
+    scenario: bestScenario,
+    reason: bestScore > 0
+      ? `matched ${bestScore} scenario keyword(s)`
+      : 'defaulted to feature-delivery because no scenario keywords matched'
+  };
+}
 
 function formatWorkflowOutput(workflow, objective) {
   const trimmedObjective = (objective || '').trim();
@@ -150,6 +558,8 @@ function validateWorkflowDefinitions() {
   const seenCli = new Set();
   const seenSlash = new Set();
   const seenPurpose = new Set();
+  const seenScenarioIds = new Set();
+  const seenOptionalSubagentRule = new Set();
   const issues = [];
 
   for (const workflow of WORKFLOW_COMMANDS) {
@@ -177,14 +587,60 @@ function validateWorkflowDefinitions() {
     }
   }
 
+  for (const scenario of ORCHESTRATION_SCENARIOS) {
+    if (seenScenarioIds.has(scenario.id)) {
+      issues.push(`Duplicate orchestration scenario id: ${scenario.id}`);
+    }
+    seenScenarioIds.add(scenario.id);
+
+    for (const phase of scenario.phases) {
+      if (!seenCli.has(phase.command)) {
+        issues.push(`Scenario ${scenario.id} references unknown command: ${phase.command}`);
+      }
+
+      if (!ORCHESTRATION_TRACKS[phase.track]) {
+        issues.push(`Scenario ${scenario.id} references unknown track: ${phase.track}`);
+      }
+    }
+  }
+
+  for (const rule of OPTIONAL_SUBAGENT_RULES) {
+    const key = JSON.stringify({
+      subagent: rule.subagent,
+      when: rule.when || {},
+      mode: rule.mode || null,
+      deprecatedAliasFor: rule.deprecatedAliasFor || null,
+      dependsOnSubagents: rule.dependsOnSubagents || []
+    });
+    if (seenOptionalSubagentRule.has(key)) {
+      issues.push(`Duplicate optional subagent rule: ${rule.subagent}`);
+    }
+    seenOptionalSubagentRule.add(key);
+
+    if (rule.required !== false) {
+      issues.push(`Optional subagent rule must remain non-required: ${rule.subagent}`);
+    }
+  }
+
   return issues;
 }
 
 module.exports = {
   WORKFLOW_COMMANDS,
+  ORCHESTRATION_TRACKS,
+  ORCHESTRATION_SCENARIOS,
+  OPTIONAL_SUBAGENT_RULES,
+  DEPRECATED_SUBAGENT_ALIASES,
+  NON_OVERLAP_ROUTE_BOUNDARIES,
+  MODE_LOCKED_SPECIALISTS,
+  SECURITY_REVIEW_POLICY,
+  REFACTOR_BUILD_RETRY_CAP,
+  REFACTOR_BUILD_HALT_AFTER,
   CONTRACT_FILES,
   SPECIALIST_CONTRACT_FILES,
   DEPRECATED_COMMAND_ALIASES,
+  findScenarioById,
+  resolveScenarioFromObjective,
   formatWorkflowOutput,
   validateWorkflowDefinitions
 };

package/package.json

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

@@ -23,11 +23,18 @@ Subagents are bounded agent processes that your orchestrator (main AI) can deleg
 | `refactor-cleaner` | sonnet | Remove dead code, unused deps, orphaned exports |
 | `doc-updater` | haiku | Sync README, API docs, and codemaps after code changes |
 | `performance-profiler` | sonnet | Diagnose latency and resource bottlenecks with measurable optimization plans |
+| `performance-specialist` | sonnet | Execute explicit profile/load performance phases with mode-locked invocation |
+| `test-data-builder` | sonnet | Build deterministic fixtures/seeds and handoff data for validation/e2e/load |
 | `dependency-auditor` | sonnet | Audit dependency risk, CVEs, and upgrade hygiene |
 | `configuration-validator` | sonnet | Validate environment config, safety defaults, and deploy readiness |
 | `database-migrator` | sonnet | Plan and review schema/data migrations with rollback and validation gates |
 | `load-tester` | sonnet | Define load scenarios, thresholds, and release-quality performance gates |
 | `compatibility-checker` | sonnet | Detect contract-breaking API changes and enforce versioning discipline |
+| `backend-specialist` | sonnet | Execute backend-oriented implementation phases in orchestrated runs |
+| `frontend-specialist` | sonnet | Execute frontend-oriented implementation phases in orchestrated runs |
+| `qa-specialist` | sonnet | Run validation and regression-focused orchestration phases |
+| `release-ops-specialist` | sonnet | Perform release hardening, risk checks, and operational readiness steps |
+| `deployment-specialist` | sonnet | Prepare deployment rollout plans and rollback-safe execution guidance |
 
 ## Model Selection Guide
 
@@ -64,11 +71,18 @@ Reference the subagent file directly in your prompt or instruct your AI to follo
 ├── refactor-cleaner.md
 ├── doc-updater.md
 ├── performance-profiler.md
+├── performance-specialist.md
+├── test-data-builder.md
 ├── dependency-auditor.md
 ├── configuration-validator.md
 ├── database-migrator.md
 ├── load-tester.md
-└── compatibility-checker.md
+├── compatibility-checker.md
+├── backend-specialist.md
+├── frontend-specialist.md
+├── qa-specialist.md
+├── release-ops-specialist.md
+└── deployment-specialist.md
 ```
 
 ## Adding a New Subagent