create-sdd-project 0.3.3 → 0.4.2

package/lib/adapt-agents.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Shared agent/skill content adaptation for single-stack projects.
+ * Used by both generator.js (new projects) and init-generator.js (--init).
+ *
+ * @param {string} dest - Destination directory
+ * @param {object} config - Config with projectType and aiTools
+ * @param {function} replaceInFileFn - Function(filePath, replacements) to perform replacements
+ */
+function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
+  const toolDirs = [];
+  if (config.aiTools !== 'gemini') toolDirs.push('.claude');
+  if (config.aiTools !== 'claude') toolDirs.push('.gemini');
+
+  if (config.projectType === 'backend') {
+    for (const dir of toolDirs) {
+      // spec-creator: remove Frontend Specifications section and UI output format
+      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
+        [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
+        [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
+        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
+      ]);
+      // production-code-validator: remove ui-components line from Spec Drift
+      replaceInFileFn(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
+        [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
+      ]);
+      // code-review-specialist: backend-only standards ref, remove ui-components
+      replaceInFileFn(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
+        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
+        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+      ]);
+      // qa-engineer: remove frontend refs, adapt standards refs
+      replaceInFileFn(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
+        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+        [/- Frontend: `cd frontend && npm test`\n/, ''],
+        [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
+        ['`backend-standards.mdc` / `frontend-standards.mdc`', '`backend-standards.mdc`'],
+        ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`backend-standards.mdc`'],
+        [/ and\/or `(?:ai-specs\/specs\/)?frontend-standards\.mdc`/, ''],
+      ]);
+    }
+  } else if (config.projectType === 'frontend') {
+    for (const dir of toolDirs) {
+      // spec-creator: remove Backend Specifications section
+      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
+        [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
+        [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
+      ]);
+      // code-review-specialist: frontend-only standards ref
+      replaceInFileFn(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
+        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
+        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+      ]);
+      // qa-engineer: remove backend refs, adapt standards refs
+      replaceInFileFn(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
+        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+        [/- Backend: `cd backend && npm test`\n/, ''],
+        [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
+        ['`backend-standards.mdc` / `frontend-standards.mdc`', '`frontend-standards.mdc`'],
+        ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`frontend-standards.mdc`'],
+        [/`(?:ai-specs\/specs\/)?backend-standards\.mdc` and\/or /, ''],
+      ]);
+    }
+  }
+
+  // Skills and templates: remove frontend/backend-specific references
+  if (config.projectType === 'backend') {
+    for (const dir of toolDirs) {
+      // Gemini agents have different text patterns for spec-creator
+      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
+        [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
+        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
+      ]);
+      replaceInFileFn(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
+        [/,? components not in ui-components\.md/, ''],
+        [/\.? ?Check components vs `ui-components\.md`/, ''],
+      ]);
+      // SKILL.md: remove ui-components references
+      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
+        [/,? `ui-components\.md`\)/, ')'],
+        [/- UI components → `docs\/specs\/ui-components\.md` \(MANDATORY\)\n/, ''],
+      ]);
+      // ticket-template: remove UI Changes section, ui-components from checklists
+      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
+        [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
+        [' / `ui-components.md`', ''],
+      ]);
+      // pr-template: remove ui-components from checklist
+      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
+        [' / ui-components.md', ''],
+      ]);
+    }
+  } else if (config.projectType === 'frontend') {
+    for (const dir of toolDirs) {
+      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
+        [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
+      ]);
+      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
+        [/`api-spec\.yaml`,? /, ''],
+        [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
+      ]);
+      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
+        [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
+        ['`api-spec.yaml` / ', ''],
+      ]);
+      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
+        ['api-spec.yaml / ', ''],
+      ]);
+    }
+  }
+}
+
+module.exports = { adaptAgentContentForProjectType };

package/lib/generator.js

@@ -9,6 +9,7 @@ const {
   FRONTEND_AGENTS,
   BACKEND_AGENTS,
 } = require('./config');
+const { adaptAgentContentForProjectType } = require('./adapt-agents');
 
 function generate(config) {
   const templateDir = path.join(__dirname, '..', 'template');
@@ -255,9 +256,10 @@ function removeFrontendFiles(dest, config) {
     [/\n# Frontend\nNEXT_PUBLIC_API_URL=.*\n/, '\n'],
   ]);
 
-  // Remove frontend from AGENTS.md project structure
+  // Remove frontend from AGENTS.md project structure + Standards References
   replaceInFile(path.join(dest, 'AGENTS.md'), [
     ['├── frontend/    ← Frontend (has its own package.json)\n', ''],
+    [/- \[Frontend Standards\].*\n/, ''],
   ]);
 
   // Product tracker already defaults to backend — no change needed
@@ -277,9 +279,10 @@ function removeBackendFiles(dest, config) {
     [/# Backend\nNODE_ENV=.*\nPORT=.*\nDATABASE_URL=.*\n\n/, ''],
   ]);
 
-  // Remove backend from AGENTS.md project structure
+  // Remove backend from AGENTS.md project structure + Standards References
   replaceInFile(path.join(dest, 'AGENTS.md'), [
     ['├── backend/     ← Backend (has its own package.json)\n', ''],
+    [/- \[Backend Standards\].*\n/, ''],
   ]);
 
   // Update product tracker default feature type to frontend
@@ -340,91 +343,7 @@ function adaptDocStandards(dest, config) {
 }
 
 function adaptAgentContent(dest, config) {
-  const toolDirs = [];
-  if (config.aiTools !== 'gemini') toolDirs.push('.claude');
-  if (config.aiTools !== 'claude') toolDirs.push('.gemini');
-
-  if (config.projectType === 'backend') {
-    for (const dir of toolDirs) {
-      // spec-creator: remove Frontend Specifications section and UI output format
-      replaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-      ]);
-      // production-code-validator: remove ui-components line
-      replaceInFile(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
-      ]);
-      // code-review-specialist: backend-only refs
-      replaceInFile(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-      ]);
-      // qa-engineer: remove frontend refs
-      replaceInFile(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-        [/- Frontend: `cd frontend && npm test`\n/, ''],
-        [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
-      ]);
-    }
-  } else if (config.projectType === 'frontend') {
-    for (const dir of toolDirs) {
-      replaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
-      ]);
-      replaceInFile(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-      ]);
-      replaceInFile(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-        [/- Backend: `cd backend && npm test`\n/, ''],
-        [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
-      ]);
-    }
-  }
-
-  // Skills and templates: same cleanup
-  if (config.projectType === 'backend') {
-    for (const dir of toolDirs) {
-      replaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
-      ]);
-      replaceInFile(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/,? components not in ui-components\.md/, ''],
-      ]);
-      replaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
-        [/,? `ui-components\.md`\)/, ')'],
-        [/- UI components → `docs\/specs\/ui-components\.md` \(MANDATORY\)\n/, ''],
-      ]);
-      replaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
-        [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
-        [' / `ui-components.md`', ''],
-      ]);
-      replaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        [' / ui-components.md', ''],
-      ]);
-    }
-  } else if (config.projectType === 'frontend') {
-    for (const dir of toolDirs) {
-      replaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
-      ]);
-      replaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
-        [/`api-spec\.yaml`,? /, ''],
-        [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
-      ]);
-      replaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
-        [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
-        ['`api-spec.yaml` / ', ''],
-      ]);
-      replaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        ['api-spec.yaml / ', ''],
-      ]);
-    }
-  }
+  adaptAgentContentForProjectType(dest, config, replaceInFile);
 }
 
 module.exports = { generate };

package/lib/init-generator.js

@@ -7,6 +7,7 @@ const {
   FRONTEND_AGENTS,
   BACKEND_AGENTS,
 } = require('./config');
+const { adaptAgentContentForProjectType } = require('./adapt-agents');
 
 /**
  * Install SDD DevFlow into an existing project.
@@ -324,19 +325,39 @@ function adaptCopiedFiles(dest, scan, config) {
   const db = scan.backend.db || 'your database';
 
   // Common Zod → generic validation replacements (all agents + skills)
-  // Order: most specific first, catch-all last
+  // Phase 1: Replace "Zod" with "validation" (most specific first)
   const zodReplacements = [
     ['Zod data schemas', 'validation schemas'],
     ['Zod schemas', 'validation schemas'],
   ];
+  // Phase 2: Clean up shared/src/schemas/ path (Zod-specific convention)
+  // Applied AFTER phase 1, so these match the post-replacement text
+  const schemaPathReplacements = [
+    ['validation schemas in `shared/src/schemas/` if applicable', 'validation schemas if applicable'],
+    ['validation schemas in `shared/src/schemas/` (if shared workspace exists)', 'validation schemas (if shared workspace exists)'],
+    ['validation schemas in `shared/src/schemas/`', 'validation schemas'],
+    ['validation schemas (`shared/src/schemas/`)', 'validation schemas'],
+    ['`shared/src/schemas/` (if exists) for current validation schemas', 'project validation schemas'],
+    // Gemini spec-creator: no "Zod" prefix, standalone path reference
+    ['and `shared/src/schemas/` (if exists)', ''],
+    ['schemas vs `shared/src/schemas/`', 'validation schemas up to date'],
+  ];
 
   // ORM/DB replacements for backend agents
-  const ormReplacements = scan.backend.orm && scan.backend.orm !== 'Prisma'
-    ? [
+  let ormReplacements = [];
+  if (scan.backend.orm && scan.backend.orm !== 'Prisma') {
+    ormReplacements = [
       ['Prisma ORM, and PostgreSQL', `${orm}${db !== 'your database' ? `, and ${db}` : ''}`],
       ['Repository implementations (Prisma)', `Repository implementations (${orm})`],
-    ]
-    : [];
+    ];
+  } else if (!scan.backend.orm) {
+    // No ORM detected — remove Prisma references with generic text
+    const dbLabel = db !== 'your database' ? `, and ${db}` : '';
+    ormReplacements = [
+      ['Prisma ORM, and PostgreSQL', dbLabel ? dbLabel.slice(6) : 'your database'],
+      ['Repository implementations (Prisma)', 'Repository implementations'],
+    ];
+  }
 
   // Apply to all AI tool directories
   const toolDirs = [];
@@ -349,6 +370,9 @@ function adaptCopiedFiles(dest, scan, config) {
       const backendAgentReplacements = [...zodReplacements, ...ormReplacements];
       replaceInCopiedFile(dest, `${dir}/agents/backend-developer.md`, backendAgentReplacements);
       replaceInCopiedFile(dest, `${dir}/agents/backend-planner.md`, backendAgentReplacements);
+      // Phase 2: clean up shared/src/schemas/ paths
+      replaceInCopiedFile(dest, `${dir}/agents/backend-developer.md`, schemaPathReplacements);
+      replaceInCopiedFile(dest, `${dir}/agents/backend-planner.md`, schemaPathReplacements);
     } else if (ormReplacements.length > 0) {
       // Zod detected but different ORM — only ORM replacements
       replaceInCopiedFile(dest, `${dir}/agents/backend-developer.md`, ormReplacements);
@@ -357,15 +381,17 @@ function adaptCopiedFiles(dest, scan, config) {
 
     // Multi-purpose agents: Zod replacements only
     if (scan.backend.validation !== 'Zod') {
-      replaceInCopiedFile(dest, `${dir}/agents/spec-creator.md`, zodReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/production-code-validator.md`, zodReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/database-architect.md`, zodReplacements);
+      const allZodReplacements = [...zodReplacements, ...schemaPathReplacements];
+      replaceInCopiedFile(dest, `${dir}/agents/spec-creator.md`, allZodReplacements);
+      replaceInCopiedFile(dest, `${dir}/agents/production-code-validator.md`, allZodReplacements);
+      replaceInCopiedFile(dest, `${dir}/agents/database-architect.md`, allZodReplacements);
     }
 
-    // Skills: Zod replacements
+    // Skills: Zod + schema path replacements
     if (scan.backend.validation !== 'Zod') {
-      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/SKILL.md`, zodReplacements);
-      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/references/ticket-template.md`, zodReplacements);
+      const allZodReplacements = [...zodReplacements, ...schemaPathReplacements];
+      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/SKILL.md`, allZodReplacements);
+      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/references/ticket-template.md`, allZodReplacements);
     }
   }
 
@@ -375,142 +401,68 @@ function adaptCopiedFiles(dest, scan, config) {
     for (const dir of toolDirs) {
       // backend-planner: adapt header, exploration paths, implementation order, rules
       regexReplaceInFile(path.join(dest, dir, 'agents', 'backend-planner.md'), [
-        // Header: remove DDD reference, use generic
+        // Header: remove DDD reference (Claude verbose format)
         ['specializing in Domain-Driven Design (DDD) layered architecture with deep knowledge of',
           'specializing in layered architecture with deep knowledge of'],
-        // Exploration paths: replace DDD-specific with generic
-        [/4\. Read `shared\/src\/schemas\/` \(if exists\) for current .* data schemas\n/, ''],
-        [/5\. Explore `backend\/src\/domain\/` for existing entities and errors\n/,
+        // Header: remove DDD reference (Gemini condensed format)
+        ['(DDD architecture)', '(layered architecture)'],
+        // Exploration: replace DDD-specific paths with generic (number-agnostic)
+        [/\d+\. Read `shared\/src\/schemas\/` \(if exists\) for current .* (?:data )?schemas\n/, ''],
+        [/\d+\. Explore existing domain entities, services, validators, repositories\n/,
           '5. Explore the codebase for existing patterns, layer structure, and reusable code\n'],
-        [/6\. Explore `backend\/src\/application\/services\/` for existing services\n/, ''],
-        [/7\. Explore `backend\/src\/application\/validators\/` for existing validators\n/, ''],
-        [/8\. Explore `backend\/src\/infrastructure\/` for existing repositories\n/, ''],
-        // Implementation Order
+        [/\d+\. Explore `backend\/src\/infrastructure\/` for existing repositories\n/, ''],
+        // Implementation Order (Claude format)
         ['following DDD layer order: Domain > Application > Infrastructure > Presentation > Tests',
           'following the layer order defined in backend-standards.mdc'],
-        // Rules
+        // Implementation Order (Gemini format)
+        ['Implementation Order (Domain > Application > Infrastructure > Presentation > Tests)',
+          'Implementation Order (see backend-standards.mdc for layer order)'],
+        // Rules (Claude format)
         ['Follow DDD layer separation: Domain > Application > Infrastructure > Presentation',
           'Follow the layer separation defined in backend-standards.mdc'],
       ]);
       // backend-developer: adapt frontmatter, header, exploration, implementation order, rules
       regexReplaceInFile(path.join(dest, dir, 'agents', 'backend-developer.md'), [
+        // Frontmatter (Claude format)
         ['follows DDD layered architecture',
           'follows layered architecture'],
+        // Header (Claude format)
         ['specializing in Domain-Driven Design (DDD) with',
           'specializing in layered architecture with'],
-        [/4\. Read `shared\/src\/schemas\/` \(if exists\) for current .* data schemas\n/, ''],
-        // Implementation Order section: replace DDD layers with generic guidance
+        // Header (Gemini condensed format)
+        ['(DDD architecture)', '(layered architecture)'],
+        // Exploration: remove shared/src/schemas reference (number-agnostic)
+        [/\d+\. Read `shared\/src\/schemas\/` \(if exists\) for current .* (?:data )?schemas\n/, ''],
+        // Implementation Order (Claude format): replace DDD layers
         ['Follow the DDD layer order from the plan:',
           'Follow the layer order from the plan (see backend-standards.mdc for project layers):'],
-        [/1\. \*\*Domain Layer\*\*: Entities, value objects, repository interfaces, domain errors\n/,
+        [/\d+\. \*\*Domain Layer\*\*: Entities, value objects, repository interfaces, domain errors\n/,
           '1. **Data Layer**: Models, database operations, data access\n'],
-        [/2\. \*\*Application Layer\*\*: Services, validators, DTOs\n/,
+        [/\d+\. \*\*Application Layer\*\*: Services, validators, DTOs\n/,
           '2. **Business Logic Layer**: Controllers, services, external integrations\n'],
-        [/3\. \*\*Infrastructure Layer\*\*: Repository implementations \([^)]*\), external integrations\n/,
+        [/\d+\. \*\*Infrastructure Layer\*\*: Repository implementations \([^)]*\), external integrations\n/,
           '3. **Presentation Layer**: Routes, handlers, middleware\n'],
-        [/4\. \*\*Presentation Layer\*\*: Controllers, routes, middleware\n/,
+        [/\d+\. \*\*Presentation Layer\*\*: Controllers, routes, middleware\n/,
           '4. **Integration Layer**: Wiring, configuration, server registration\n'],
-        // Rules
+        // Implementation Order (Gemini format)
+        ['Follow DDD layer order: Domain > Application > Infrastructure > Presentation.',
+          'Follow the layer order defined in backend-standards.mdc.'],
+        // Rules (Claude format)
         ['**ALWAYS** follow DDD layer separation',
           '**ALWAYS** follow the layer separation defined in backend-standards.mdc'],
         ['**ALWAYS** handle errors with custom domain error classes',
           '**ALWAYS** handle errors following the patterns in backend-standards.mdc'],
-        // Documentation
-        [/- \*\*MANDATORY\*\*: If modifying a DB schema → update .* schemas in `shared\/src\/schemas\/` BEFORE continuing\n/, ''],
+        // Rules (Gemini format)
+        ['ALWAYS handle errors with domain error classes',
+          'ALWAYS handle errors following the patterns in backend-standards.mdc'],
+        // Documentation: remove shared/src/schemas mandatory update
+        [/- (?:\*\*MANDATORY\*\*: )?If modifying a DB schema → update .* schemas in `shared\/src\/schemas\/` BEFORE continuing\n/, ''],
       ]);
     }
   }
 
-  // Agent content: remove frontend/backend-specific references for single-stack projects
-  if (config.projectType === 'backend') {
-    for (const dir of toolDirs) {
-      // spec-creator: remove Frontend Specifications section and UI output format
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-      ]);
-      // production-code-validator: remove ui-components line from Spec Drift
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
-      ]);
-      // code-review-specialist: backend-only standards ref, remove ui-components
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-      ]);
-      // qa-engineer: remove ui-components from specs, remove frontend test command
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-        [/- Frontend: `cd frontend && npm test`\n/, ''],
-        [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
-      ]);
-    }
-  } else if (config.projectType === 'frontend') {
-    for (const dir of toolDirs) {
-      // spec-creator: remove Backend Specifications section
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
-      ]);
-      // code-review-specialist: frontend-only standards ref
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-      ]);
-      // qa-engineer: remove api-spec from specs, remove backend test command
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-        [/- Backend: `cd backend && npm test`\n/, ''],
-        [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
-      ]);
-    }
-  }
-
-  // Skills and templates: remove frontend/backend-specific references
-  if (config.projectType === 'backend') {
-    for (const dir of toolDirs) {
-      // Gemini agents have different text patterns
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-      ]);
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/,? components not in ui-components\.md/, ''],
-      ]);
-      // SKILL.md: remove ui-components references
-      regexReplaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
-        [/,? `ui-components\.md`\)/, ')'],
-        [/- UI components → `docs\/specs\/ui-components\.md` \(MANDATORY\)\n/, ''],
-      ]);
-      // ticket-template: remove UI Changes section, ui-components from checklists
-      regexReplaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
-        [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
-        [' / `ui-components.md`', ''],
-      ]);
-      // pr-template: remove ui-components from checklist
-      regexReplaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        [' / ui-components.md', ''],
-      ]);
-    }
-  } else if (config.projectType === 'frontend') {
-    for (const dir of toolDirs) {
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
-      ]);
-      regexReplaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
-        [/`api-spec\.yaml`,? /, ''],
-        [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
-      ]);
-      regexReplaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
-        [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
-        ['`api-spec.yaml` / ', ''],
-      ]);
-      regexReplaceInFile(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        ['api-spec.yaml / ', ''],
-      ]);
-    }
-  }
+  // Agent/skill content: remove frontend/backend-specific references for single-stack projects
+  adaptAgentContentForProjectType(dest, config, regexReplaceInFile);
 
   // documentation-standards.mdc: remove irrelevant rows based on project type
   const docStdPath = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
@@ -814,6 +766,14 @@ function adaptAgentsMd(template, config, scan) {
     );
   }
 
+  if (!scan.backend.detected) {
+    // Remove backend-standards reference for frontend-only projects
+    content = content.replace(
+      /- \[Backend Standards\].*\n/,
+      ''
+    );
+  }
+
   return content;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.3.3",
+  "version": "0.4.2",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"

package/template/.claude/agents/backend-developer.md

@@ -13,6 +13,8 @@ You are an expert TypeScript backend developer specializing in Domain-Driven Des
 
 Implement the backend task following the **Implementation Plan** in the ticket. Use strict TDD methodology.
 
+**Standards take priority over legacy code.** When existing code contradicts `backend-standards.mdc`, follow the standards.
+
 ## Before Implementing
 
 1. Read the ticket file (including the Spec and Implementation Plan)
@@ -54,6 +56,7 @@ Follow the DDD layer order from the plan:
 - **ALWAYS** follow DDD layer separation
 - **ALWAYS** use explicit types (never `any`)
 - **ALWAYS** handle errors with custom domain error classes
+- **ALWAYS** prioritize standards in `backend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - **ALWAYS** run `npm test` after each TDD cycle to verify
 - **NEVER** skip tests for "simple" code
 - **NEVER** modify code outside the scope of the current ticket

package/template/.claude/agents/backend-planner.md

@@ -16,17 +16,17 @@ Generate a detailed **Implementation Plan** and write it into the ticket's `## I
 
 **NEVER write implementation code. Only produce the plan.**
 
+**Standards take priority over legacy code.** When existing code contradicts `backend-standards.mdc`, follow the standards.
+
 ## Before Planning
 
-1. Read `docs/project_notes/key_facts.md` for existing reusable components
-2. Read the ticket file passed as input (including the `## Spec` section)
-3. Read `docs/specs/api-spec.yaml` for current API endpoints and schemas
-4. Read `shared/src/schemas/` (if exists) for current Zod data schemas
-5. Explore `backend/src/domain/` for existing entities and errors
-6. Explore `backend/src/application/services/` for existing services
-7. Explore `backend/src/application/validators/` for existing validators
-8. Explore `backend/src/infrastructure/` for existing repositories
-9. Read `ai-specs/specs/backend-standards.mdc` for project standards
+1. Read `ai-specs/specs/backend-standards.mdc` — this is your primary reference for conventions
+2. Read `docs/project_notes/key_facts.md` for existing reusable components
+3. Read the ticket file passed as input (including the `## Spec` section)
+4. Read `docs/specs/api-spec.yaml` for current API endpoints and schemas
+5. Read `shared/src/schemas/` (if exists) for current Zod data schemas
+6. Explore existing domain entities, services, validators, repositories
+7. Explore `backend/src/infrastructure/` for existing repositories
 
 **Reuse over recreate.** Only propose new code when existing doesn't fit.
 
@@ -62,4 +62,5 @@ Write the following sections into the ticket's `## Implementation Plan` section:
 - **ALWAYS** check existing code before proposing new files
 - **ALWAYS** save the plan into the ticket's `## Implementation Plan` section
 - **ALWAYS** reference `ai-specs/specs/backend-standards.mdc` for project conventions
+- **ALWAYS** prioritize standards in `backend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - Follow DDD layer separation: Domain > Application > Infrastructure > Presentation

package/template/.claude/agents/code-review-specialist.md

@@ -1,7 +1,7 @@
 ---
 name: code-review-specialist
 description: "Use this agent when you need a thorough code review of recently written or modified code. This includes reviewing pull requests, evaluating code quality before committing, checking for security vulnerabilities, ensuring adherence to best practices, or getting constructive feedback on implementation approaches."
-model: sonnet
+model: opus
 ---
 
 You are a Senior Code Review Specialist. Examine code for correctness, maintainability, security, and performance. Be constructive and specific — reference exact lines, explain WHY something matters, and suggest HOW to fix it.
@@ -26,7 +26,17 @@ You are a Senior Code Review Specialist. Examine code for correctness, maintaina
 
 **Maintainability**: Readability, test coverage and quality, consistency with existing codebase.
 
-### 3. Categorize Findings
+### 3. Adversarial Analysis
+
+Go beyond checklist review — actively try to break the implementation:
+
+- **External failures**: What if the external API returns garbage, times out, or changes its contract?
+- **Concurrency**: What happens under concurrent requests? Race conditions? Double writes?
+- **Malicious input**: What data could a malicious user inject? Are all inputs validated at system boundaries?
+- **State corruption**: What if the database is slow, a transaction fails midway, or cache is stale?
+- **Missing validation**: Are values range-checked, type-checked, and null-checked before use?
+
+### 4. Categorize Findings
 
 - **Critical** — Must fix before merging (security, data loss, breaking bugs)
 - **Important** — Should fix (quality/maintainability concerns)

package/template/.claude/agents/frontend-developer.md

@@ -13,6 +13,8 @@ You are an expert React frontend developer specializing in Next.js App Router wi
 
 Implement the frontend task following the **Implementation Plan** in the ticket. Use strict TDD methodology.
 
+**Standards take priority over legacy code.** When existing code contradicts `frontend-standards.mdc`, follow the standards.
+
 ## Before Implementing
 
 1. Read the ticket file (including the Spec and Implementation Plan)
@@ -64,5 +66,6 @@ Follow the logical order from the plan:
 - **ALWAYS** handle loading and error states
 - **ALWAYS** run `npm test` after each TDD cycle to verify
 - **NEVER** skip tests for "simple" components
+- **ALWAYS** prioritize standards in `frontend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - **NEVER** modify code outside the scope of the current ticket
 - **ALWAYS** verify implementation matches the approved spec. If a deviation is needed, document it in the product tracker's Active Session and ask for approval

package/template/.claude/agents/frontend-planner.md

@@ -16,17 +16,16 @@ Generate a detailed **Implementation Plan** and write it into the ticket's `## I
 
 **NEVER write implementation code. Only produce the plan.**
 
+**Standards take priority over legacy code.** When existing code contradicts `frontend-standards.mdc`, follow the standards.
+
 ## Before Planning
 
-1. Read `docs/project_notes/key_facts.md` for existing reusable components
-2. Read the ticket file passed as input (including the `## Spec` section)
-3. Read `docs/specs/ui-components.md` for current UI component specs
-4. Read `docs/specs/api-spec.yaml` for API endpoints to consume
-5. Explore `frontend/components/` for existing components
-6. Explore `frontend/lib/` for existing utilities and services
-7. Explore `frontend/stores/` for existing state stores
-8. Explore `frontend/app/` for existing pages and layouts
-9. Read `ai-specs/specs/frontend-standards.mdc` for project standards
+1. Read `ai-specs/specs/frontend-standards.mdc` — this is your primary reference for conventions
+2. Read `docs/project_notes/key_facts.md` for existing reusable components
+3. Read the ticket file passed as input (including the `## Spec` section)
+4. Read `docs/specs/ui-components.md` for current UI component specs
+5. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+6. Explore existing components, utilities, services, stores, and pages
 
 **Reuse over recreate.** Only propose new components when existing ones don't fit.
 
@@ -62,4 +61,5 @@ Write the following sections into the ticket's `## Implementation Plan` section:
 - **ALWAYS** check existing code before proposing new files
 - **ALWAYS** save the plan into the ticket's `## Implementation Plan` section
 - **ALWAYS** reference `ai-specs/specs/frontend-standards.mdc` for project conventions
+- **ALWAYS** prioritize standards in `frontend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - Note which components need `'use client'` directive

package/template/.claude/agents/production-code-validator.md

@@ -58,11 +58,13 @@ Scan code systematically to identify and report issues that should never reach p
 - Functions longer than 50 lines
 - Missing TypeScript types where expected
 
-### 8. Spec Drift
-- API routes implemented in code that are NOT documented in `docs/specs/api-spec.yaml`
+### 8. Spec Drift (BLOCKING — any mismatch is HIGH severity)
+- **Enumerate every route** registered in the codebase and verify each has a matching entry in `docs/specs/api-spec.yaml`
+- **Enumerate every endpoint** in `api-spec.yaml` and verify each has a matching route in code
 - Components exported/used that are NOT listed in `docs/specs/ui-components.md`
 - Database schema changes not reflected in Zod schemas (`shared/src/schemas/`)
 - Mismatch between spec-defined request/response schemas and actual implementation
+- **Ticket accuracy**: verify acceptance criteria test count matches actual test count
 
 ## Output Format
 

package/template/.claude/agents/qa-engineer.md

@@ -10,10 +10,13 @@ You are an expert QA Automation Engineer. Your goal is to break the code. You as
 
 Verify the implementation's robustness and strict adherence to `docs/specs/`.
 
+**Standards take priority over legacy code.** When existing tests contradict `backend-standards.mdc` / `frontend-standards.mdc`, follow the standards.
+
 ## Workflow
 
 ### 1. Analyze
 - Read the Ticket and the Specs (`api-spec.yaml`, `ui-components.md`)
+- Read `ai-specs/specs/backend-standards.mdc` and/or `frontend-standards.mdc` for testing patterns
 - Read the implementation code and existing tests
 - Identify what the developer tested vs. what's missing
 

package/template/.claude/skills/development-workflow/SKILL.md

@@ -96,8 +96,9 @@ See `references/branching-strategy.md` for details.
 ## Step 2: Plan (Standard/Complex only)
 
 1. Use Task tool with planner agent (`backend-planner` for backend features, `frontend-planner` for frontend features)
-2. Agent writes Implementation Plan into ticket's `## Implementation Plan`
-3. Update tracker: step `2/6 (Plan)`
+2. **Fullstack features:** Run `backend-planner` first, then `frontend-planner`. Each writes its own section in the Implementation Plan
+3. Agent writes Implementation Plan into ticket's `## Implementation Plan`
+4. Update tracker: step `2/6 (Plan)`
 
 **→ CHECKPOINT: Plan Approval**
 
@@ -107,6 +108,8 @@ See `references/branching-strategy.md` for details.
 
 **Simple:** Implement directly with TDD. **Std/Cplx:** Use developer agent (`backend-developer` / `frontend-developer`).
 
+**Fullstack features:** Implement backend first (APIs must exist before the frontend consumes them), then frontend. Use the corresponding developer agent for each.
+
 **TDD Cycle:** Failing test → Minimum code to pass → Refactor → Repeat
 
 **Update specs IN REAL TIME (do not wait until Finalize):**
@@ -117,6 +120,8 @@ See `references/branching-strategy.md` for details.
 
 **Spec deviation** → document in product tracker Active Session and ask for approval.
 
+**Commits:** Commit freely during implementation (one per logical unit is fine). Final history cleanup happens via squash merge in Step 5.
+
 Update tracker: step `3/6 (Implement)`, context summary.
 
 ---
@@ -143,7 +148,7 @@ Update tracker: step `4/6 (Finalize)`
 1. Push branch, create PR (use `references/pr-template.md`)
 2. **Std/Cplx:** Run `code-review-specialist` via Task tool — **do NOT skip**
 3. **Std/Cplx:** Also run `qa-engineer` via Task tool
-4. **Merge:** Features/bugfixes → squash; Releases/hotfixes → merge commit
+4. **Merge strategy:** Features/bugfixes → **squash merge** (clean single commit on target branch); Releases/hotfixes → merge commit
 
 **→ CHECKPOINT: Merge Approval**
 
@@ -153,10 +158,11 @@ Update tracker: step `5/6 (Review)`
 
 ## Step 6: Complete
 
-1. Delete feature branch (local + remote)
-2. Update product tracker: feature → done, add to Completion Log, update progress
-3. Record bugs in `bugs.md`, decisions in `decisions.md`
-4. Clear Active Session → "No active work"
+1. **Update ticket with final state:** correct test count in acceptance criteria, mark all checkboxes, update Completion Log with all commits and key events
+2. Delete feature branch (local + remote)
+3. Update product tracker: feature → done, add to Completion Log, update progress
+4. Record bugs in `bugs.md`, decisions in `decisions.md`
+5. Clear Active Session → "No active work"
 
 ---
 

package/template/.claude/skills/development-workflow/references/pr-template.md

@@ -30,6 +30,18 @@ gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat
 - [x] Integration tests passing (if applicable)
 - [x] Validated with production-code-validator
 
+## Risk Assessment
+
+- [ ] Modifies authentication/authorization logic
+- [ ] Handles financial, medical, or sensitive data
+- [ ] Changes database schema or migrations
+- [ ] Modifies external API integrations
+- [ ] Affects error handling or recovery paths
+
+## Human Review Focus
+
+[1-3 specific areas where human expertise is most needed. Example: "Token refresh edge case in cgmData handler", "Dedup logic correctness"]
+
 ## Checklist
 
 - [ ] Code follows project standards
@@ -44,7 +56,7 @@ gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat
 Closes #issue_number (if applicable)
 
 ---
-Generated with Claude Code
+Generated with SDD DevFlow
 EOF
 )"
 ```

package/template/.claude/skills/development-workflow/references/ticket-template.md

@@ -60,12 +60,31 @@ _Pending — to be generated by the planner agent in Step 2._
 
 ---
 
+## Workflow Checklist
+
+<!-- Auto-fill based on complexity tier. Remove steps that don't apply. -->
+
+- [ ] Step 0: `spec-creator` executed, specs updated
+- [ ] Step 1: Branch created, ticket generated, tracker updated
+- [ ] Step 2: `{backend|frontend}-planner` executed, plan approved
+- [ ] Step 3: `{backend|frontend}-developer` executed with TDD
+- [ ] Step 4: `production-code-validator` executed, quality gates pass
+- [ ] Step 5: `code-review-specialist` executed
+- [ ] Step 5: `qa-engineer` executed (Standard/Complex)
+- [ ] Step 6: Ticket updated with final metrics, branch deleted
+
+---
+
 ## Completion Log
 
 | Date | Action | Notes |
 |------|--------|-------|
 | | | |
 
+<!-- After code review, add a row documenting which findings were accepted/rejected:
+| YYYY-MM-DD | Review findings | Accepted: C1-C3, H1-H2. Rejected: M5 (reason). Systemic: C4 logged in bugs.md |
+This creates a feedback loop for improving future reviews. -->
+
 ---
 
 *Ticket created: [YYYY-MM-DD]*

package/template/.claude/skills/health-check/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: health-check
+description: "Quick project health scan. Invoke with: 'health check', 'project health', or 'health'. Verifies tests, build, specs sync, secrets, and documentation freshness."
+---
+
+# Health Check Skill
+
+Run a fast, systematic health scan across the project. Useful before starting new work, after merging, or when something feels off.
+
+## Command
+
+| Command | Action |
+|---------|--------|
+| `health` | Run full health check |
+
+## Checks
+
+Run all checks in order. For each, report PASS or FAIL with details.
+
+### 1. Tests
+
+```bash
+npm test
+```
+
+FAIL if any test fails or the command exits non-zero.
+
+### 2. Build
+
+```bash
+npm run build
+```
+
+FAIL if build errors. SKIP if no build script exists.
+
+### 3. Type Check
+
+```bash
+npx tsc --noEmit
+```
+
+FAIL if type errors. SKIP if no `tsconfig.json`.
+
+### 4. Critical TODOs
+
+Search codebase for `TODO`, `FIXME`, `HACK`, `XXX` in source files (exclude `node_modules`, `dist`, `.git`).
+
+WARN if any found. List file:line for each.
+
+### 5. Spec Sync
+
+- Compare routes registered in code vs endpoints in `docs/specs/api-spec.yaml`
+- Compare exported components vs `docs/specs/ui-components.md`
+- FAIL if mismatches found. SKIP if spec files don't exist.
+
+### 6. Secrets Scan
+
+Search for patterns that suggest leaked secrets:
+- API keys, tokens, passwords in source files
+- `.env` files tracked by git (`git ls-files '*.env'`)
+- Hardcoded `localhost` URLs with ports (warn only)
+
+FAIL if secrets found. WARN for localhost URLs.
+
+### 7. Environment
+
+- Check `.env.example` exists and lists all variables referenced in code
+- WARN if `.env.example` is missing or incomplete
+
+### 8. Tracker Coherence
+
+- Read `docs/project_notes/product-tracker.md`
+- Check Active Session is clean (no stale in-progress work)
+- WARN if tracker looks stale or inconsistent
+
+## Output Format
+
+```
+## Project Health Report
+
+| # | Check | Status | Details |
+|---|-------|--------|---------|
+| 1 | Tests | PASS | 47 tests passing |
+| 2 | Build | PASS | Clean |
+| 3 | Types | PASS | No errors |
+| 4 | TODOs | WARN | 3 found (see below) |
+| 5 | Specs | PASS | Routes match |
+| 6 | Secrets | PASS | None found |
+| 7 | Env | PASS | .env.example up to date |
+| 8 | Tracker | WARN | Active session not empty |
+
+**Overall: HEALTHY / NEEDS ATTENTION / UNHEALTHY**
+
+### Details
+[Expand on any FAIL or WARN items]
+```
+
+**HEALTHY** = all PASS (WARNs ok). **NEEDS ATTENTION** = WARNs present. **UNHEALTHY** = any FAIL.
+
+## Rules
+
+- Run checks in order — stop early if tests or build fail (later checks may be unreliable)
+- Be specific about failures — include file paths, line numbers, exact errors
+- Don't fix anything — only report. The user decides what to act on
+- Keep output concise — details only for non-PASS items

package/template/.gemini/agents/backend-developer.md

@@ -7,6 +7,8 @@
 
 Implement the task following the Implementation Plan in the ticket. Use strict TDD (Red-Green-Refactor). Follow DDD layer order: Domain > Application > Infrastructure > Presentation.
 
+**Standards take priority over legacy code.** When existing code contradicts `backend-standards.mdc`, follow the standards.
+
 ## Before Implementing
 
 1. Read ticket (including Spec and Implementation Plan)
@@ -27,5 +29,6 @@ Implement the task following the Implementation Plan in the ticket. Use strict T
 - ALWAYS follow the Implementation Plan
 - ALWAYS use explicit types (no `any`)
 - ALWAYS handle errors with domain error classes
+- ALWAYS prioritize standards in `backend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - NEVER modify code outside the scope of the current ticket
 - ALWAYS verify implementation matches the approved spec. If deviation needed, document in product tracker's Active Session and ask for approval

package/template/.gemini/agents/backend-planner.md

@@ -7,14 +7,16 @@
 
 Generate a detailed Implementation Plan and write it into the ticket's `## Implementation Plan` section. The plan must be detailed enough for the backend-developer to implement autonomously.
 
+**Standards take priority over legacy code.** When existing code contradicts `backend-standards.mdc`, follow the standards.
+
 ## Before Planning
 
-1. Read `docs/project_notes/key_facts.md`
-2. Read the ticket file (including `## Spec` section)
-3. Read `docs/specs/api-spec.yaml` for current API endpoints and schemas
-4. Read `shared/src/schemas/` (if exists) for current Zod data schemas
-5. Explore existing domain entities, services, validators, repositories
-6. Read `ai-specs/specs/backend-standards.mdc`
+1. Read `ai-specs/specs/backend-standards.mdc` — primary reference for conventions
+2. Read `docs/project_notes/key_facts.md`
+3. Read the ticket file (including `## Spec` section)
+4. Read `docs/specs/api-spec.yaml` for current API endpoints and schemas
+5. Read `shared/src/schemas/` (if exists) for current Zod data schemas
+6. Explore existing domain entities, services, validators, repositories
 
 **Reuse over recreate.** Only propose new code when existing doesn't fit.
 
@@ -31,4 +33,5 @@ Generate a detailed Implementation Plan and write it into the ticket's `## Imple
 
 - NEVER write implementation code — only the plan
 - ALWAYS check existing code before proposing new files
+- ALWAYS prioritize standards in `backend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - ALWAYS save the plan into the ticket

package/template/.gemini/agents/code-review-specialist.md

@@ -14,6 +14,12 @@ Perform a multi-layer code review covering:
 - **Performance**: N+1 queries, memory leaks, unnecessary computations
 - **Maintainability**: Readability, test coverage, pattern consistency
 
+Then go beyond checklist review — actively try to break the implementation:
+- What if external APIs return garbage, time out, or change their contract?
+- What happens under concurrent requests? Race conditions?
+- What data could a malicious user inject?
+- What if a transaction fails midway or cache is stale?
+
 ## Output Format
 
 ```

package/template/.gemini/agents/frontend-developer.md

@@ -7,6 +7,8 @@
 
 Implement the task following the Implementation Plan in the ticket. Use strict TDD (Red-Green-Refactor). Follow logical order: Types > Services > Stores > Components > Pages.
 
+**Standards take priority over legacy code.** When existing code contradicts `frontend-standards.mdc`, follow the standards.
+
 ## Before Implementing
 
 1. Read ticket (including Spec and Implementation Plan)
@@ -27,5 +29,6 @@ Implement the task following the Implementation Plan in the ticket. Use strict T
 - ALWAYS use explicit types (no `any`)
 - ALWAYS use `'use client'` for components with hooks
 - ALWAYS handle loading and error states
+- ALWAYS prioritize standards in `frontend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - NEVER modify code outside the scope of the current ticket
 - ALWAYS verify implementation matches the approved spec. If deviation needed, document in product tracker's Active Session and ask for approval

package/template/.gemini/agents/frontend-planner.md

@@ -7,14 +7,16 @@
 
 Generate a detailed Implementation Plan and write it into the ticket's `## Implementation Plan` section. The plan must be detailed enough for the frontend-developer to implement autonomously.
 
+**Standards take priority over legacy code.** When existing code contradicts `frontend-standards.mdc`, follow the standards.
+
 ## Before Planning
 
-1. Read `docs/project_notes/key_facts.md`
-2. Read the ticket file (including `## Spec` section)
-3. Read `docs/specs/ui-components.md` for current UI component specs
-4. Read `docs/specs/api-spec.yaml` for API endpoints to consume
-5. Explore existing components, services, stores, pages
-6. Read `ai-specs/specs/frontend-standards.mdc`
+1. Read `ai-specs/specs/frontend-standards.mdc` — primary reference for conventions
+2. Read `docs/project_notes/key_facts.md`
+3. Read the ticket file (including `## Spec` section)
+4. Read `docs/specs/ui-components.md` for current UI component specs
+5. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+6. Explore existing components, services, stores, pages
 
 **Reuse over recreate.** Only propose new components when existing ones don't fit.
 
@@ -31,4 +33,5 @@ Generate a detailed Implementation Plan and write it into the ticket's `## Imple
 
 - NEVER write implementation code — only the plan
 - ALWAYS check existing code before proposing new files
+- ALWAYS prioritize standards in `frontend-standards.mdc` over patterns found in existing code (existing code may use legacy patterns)
 - ALWAYS save the plan into the ticket

package/template/.gemini/agents/production-code-validator.md

@@ -14,7 +14,7 @@ Scan code systematically for issues that should never reach production:
 5. **Security Red Flags**: Disabled SSL, CORS *, hardcoded credentials
 6. **Error Handling**: Empty catch blocks, swallowed errors
 7. **Code Quality**: Unused imports, missing types, overly long functions
-8. **Spec Drift**: Routes not in api-spec.yaml, components not in ui-components.md, schema mismatches with Zod schemas in `shared/src/schemas/`
+8. **Spec Drift** (BLOCKING): Enumerate every route in code vs `api-spec.yaml` — any mismatch is HIGH. Check components vs `ui-components.md`, schemas vs `shared/src/schemas/`. Verify ticket test counts match actual
 
 ## Output Format
 

package/template/.gemini/agents/qa-engineer.md

@@ -7,9 +7,11 @@
 
 You assume the happy path works (checked by Developer). Hunt for edge cases, security flaws, and spec deviations. Verify implementation against `docs/specs/`.
 
+**Standards take priority over legacy code.** When existing tests contradict `backend-standards.mdc` / `frontend-standards.mdc`, follow the standards.
+
 ## Workflow
 
-1. Read ticket, specs (`api-spec.yaml`, `ui-components.md`), implementation code, and existing tests
+1. Read ticket, specs (`api-spec.yaml`, `ui-components.md`), standards (`backend-standards.mdc` / `frontend-standards.mdc`), implementation code, and existing tests
 2. Identify missing test cases and spec deviations
 3. Run full test suite for regressions
 4. Create new edge-case tests (e.g., `*.edge-cases.test.ts`)

package/template/.gemini/skills/development-workflow/SKILL.md

@@ -96,8 +96,9 @@ See `references/branching-strategy.md` for details.
 ## Step 2: Plan (Standard/Complex only)
 
 1. Follow the planner agent instructions (`backend-planner` for backend features, `frontend-planner` for frontend features) in `.gemini/agents/`
-2. Write Implementation Plan into ticket's `## Implementation Plan`
-3. Update tracker: step `2/6 (Plan)`
+2. **Fullstack features:** Run `backend-planner` first, then `frontend-planner`. Each writes its own section in the Implementation Plan
+3. Write Implementation Plan into ticket's `## Implementation Plan`
+4. Update tracker: step `2/6 (Plan)`
 
 **→ CHECKPOINT: Plan Approval**
 
@@ -107,6 +108,8 @@ See `references/branching-strategy.md` for details.
 
 **Simple:** Implement directly with TDD. **Std/Cplx:** Follow the developer agent instructions (`backend-developer` / `frontend-developer`) in `.gemini/agents/`.
 
+**Fullstack features:** Implement backend first (APIs must exist before the frontend consumes them), then frontend. Use the corresponding developer agent for each.
+
 **TDD Cycle:** Failing test → Minimum code to pass → Refactor → Repeat
 
 **Update specs IN REAL TIME (do not wait until Finalize):**
@@ -117,6 +120,8 @@ See `references/branching-strategy.md` for details.
 
 **Spec deviation** → document in product tracker Active Session and ask for approval.
 
+**Commits:** Commit freely during implementation (one per logical unit is fine). Final history cleanup happens via squash merge in Step 5.
+
 Update tracker: step `3/6 (Implement)`, context summary.
 
 ---
@@ -143,7 +148,7 @@ Update tracker: step `4/6 (Finalize)`
 1. Push branch, create PR (use `references/pr-template.md`)
 2. **Std/Cplx:** Follow `code-review-specialist` instructions in `.gemini/agents/` — **do NOT skip**
 3. **Std/Cplx:** Also follow `qa-engineer` instructions in `.gemini/agents/`
-4. **Merge:** Features/bugfixes → squash; Releases/hotfixes → merge commit
+4. **Merge strategy:** Features/bugfixes → **squash merge** (clean single commit on target branch); Releases/hotfixes → merge commit
 
 **→ CHECKPOINT: Merge Approval**
 
@@ -153,10 +158,11 @@ Update tracker: step `5/6 (Review)`
 
 ## Step 6: Complete
 
-1. Delete feature branch (local + remote)
-2. Update product tracker: feature → done, add to Completion Log, update progress
-3. Record bugs in `bugs.md`, decisions in `decisions.md`
-4. Clear Active Session → "No active work"
+1. **Update ticket with final state:** correct test count in acceptance criteria, mark all checkboxes, update Completion Log with all commits and key events
+2. Delete feature branch (local + remote)
+3. Update product tracker: feature → done, add to Completion Log, update progress
+4. Record bugs in `bugs.md`, decisions in `decisions.md`
+5. Clear Active Session → "No active work"
 
 ---
 

package/template/.gemini/skills/development-workflow/references/pr-template.md

@@ -30,6 +30,18 @@ gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat
 - [x] Integration tests passing (if applicable)
 - [x] Validated with production-code-validator
 
+## Risk Assessment
+
+- [ ] Modifies authentication/authorization logic
+- [ ] Handles financial, medical, or sensitive data
+- [ ] Changes database schema or migrations
+- [ ] Modifies external API integrations
+- [ ] Affects error handling or recovery paths
+
+## Human Review Focus
+
+[1-3 specific areas where human expertise is most needed. Example: "Token refresh edge case in cgmData handler", "Dedup logic correctness"]
+
 ## Checklist
 
 - [ ] Code follows project standards
@@ -44,7 +56,7 @@ gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat
 Closes #issue_number (if applicable)
 
 ---
-Generated with Claude Code
+Generated with SDD DevFlow
 EOF
 )"
 ```

package/template/.gemini/skills/development-workflow/references/ticket-template.md

@@ -60,12 +60,31 @@ _Pending — to be generated by the planner agent in Step 2._
 
 ---
 
+## Workflow Checklist
+
+<!-- Auto-fill based on complexity tier. Remove steps that don't apply. -->
+
+- [ ] Step 0: `spec-creator` executed, specs updated
+- [ ] Step 1: Branch created, ticket generated, tracker updated
+- [ ] Step 2: `{backend|frontend}-planner` executed, plan approved
+- [ ] Step 3: `{backend|frontend}-developer` executed with TDD
+- [ ] Step 4: `production-code-validator` executed, quality gates pass
+- [ ] Step 5: `code-review-specialist` executed
+- [ ] Step 5: `qa-engineer` executed (Standard/Complex)
+- [ ] Step 6: Ticket updated with final metrics, branch deleted
+
+---
+
 ## Completion Log
 
 | Date | Action | Notes |
 |------|--------|-------|
 | | | |
 
+<!-- After code review, add a row documenting which findings were accepted/rejected:
+| YYYY-MM-DD | Review findings | Accepted: C1-C3, H1-H2. Rejected: M5 (reason). Systemic: C4 logged in bugs.md |
+This creates a feedback loop for improving future reviews. -->
+
 ---
 
 *Ticket created: [YYYY-MM-DD]*

package/template/.gemini/skills/health-check/SKILL.md

@@ -0,0 +1,100 @@
+# Health Check Skill
+
+Run a fast, systematic health scan across the project. Useful before starting new work, after merging, or when something feels off.
+
+## Command
+
+| Command | Action |
+|---------|--------|
+| `health` | Run full health check |
+
+## Checks
+
+Run all checks in order. For each, report PASS or FAIL with details.
+
+### 1. Tests
+
+```bash
+npm test
+```
+
+FAIL if any test fails or the command exits non-zero.
+
+### 2. Build
+
+```bash
+npm run build
+```
+
+FAIL if build errors. SKIP if no build script exists.
+
+### 3. Type Check
+
+```bash
+npx tsc --noEmit
+```
+
+FAIL if type errors. SKIP if no `tsconfig.json`.
+
+### 4. Critical TODOs
+
+Search codebase for `TODO`, `FIXME`, `HACK`, `XXX` in source files (exclude `node_modules`, `dist`, `.git`).
+
+WARN if any found. List file:line for each.
+
+### 5. Spec Sync
+
+- Compare routes registered in code vs endpoints in `docs/specs/api-spec.yaml`
+- Compare exported components vs `docs/specs/ui-components.md`
+- FAIL if mismatches found. SKIP if spec files don't exist.
+
+### 6. Secrets Scan
+
+Search for patterns that suggest leaked secrets:
+- API keys, tokens, passwords in source files
+- `.env` files tracked by git (`git ls-files '*.env'`)
+- Hardcoded `localhost` URLs with ports (warn only)
+
+FAIL if secrets found. WARN for localhost URLs.
+
+### 7. Environment
+
+- Check `.env.example` exists and lists all variables referenced in code
+- WARN if `.env.example` is missing or incomplete
+
+### 8. Tracker Coherence
+
+- Read `docs/project_notes/product-tracker.md`
+- Check Active Session is clean (no stale in-progress work)
+- WARN if tracker looks stale or inconsistent
+
+## Output Format
+
+```
+## Project Health Report
+
+| # | Check | Status | Details |
+|---|-------|--------|---------|
+| 1 | Tests | PASS | 47 tests passing |
+| 2 | Build | PASS | Clean |
+| 3 | Types | PASS | No errors |
+| 4 | TODOs | WARN | 3 found (see below) |
+| 5 | Specs | PASS | Routes match |
+| 6 | Secrets | PASS | None found |
+| 7 | Env | PASS | .env.example up to date |
+| 8 | Tracker | WARN | Active session not empty |
+
+**Overall: HEALTHY / NEEDS ATTENTION / UNHEALTHY**
+
+### Details
+[Expand on any FAIL or WARN items]
+```
+
+**HEALTHY** = all PASS (WARNs ok). **NEEDS ATTENTION** = WARNs present. **UNHEALTHY** = any FAIL.
+
+## Rules
+
+- Run checks in order — stop early if tests or build fail (later checks may be unreliable)
+- Be specific about failures — include file paths, line numbers, exact errors
+- Don't fix anything — only report. The user decides what to act on
+- Keep output concise — details only for non-PASS items