create-sdd-project 0.3.0 → 0.4.1

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');
@@ -50,7 +51,22 @@ function generate(config) {
     removeBackendFiles(dest, config);
   }
 
-  // 7. Remove AI tool config if single tool selected
+  // 7. Adapt agent/skill content for non-default backend stacks
+  if (config.projectType !== 'frontend') {
+    const bp = config.backendPreset || BACKEND_STACKS[0];
+    if (bp.orm && bp.orm !== 'Prisma') {
+      step(`Adapting agents for ${bp.orm}`);
+      adaptAgentsForStack(dest, bp, config);
+    }
+  }
+
+  // 7b. Clean documentation-standards and agent content based on project type
+  adaptDocStandards(dest, config);
+  if (config.projectType !== 'fullstack') {
+    adaptAgentContent(dest, config);
+  }
+
+  // 8. Remove AI tool config if single tool selected
   if (config.aiTools === 'claude') {
     step('Removing Gemini config (Claude only)');
     fs.rmSync(path.join(dest, '.gemini'), { recursive: true, force: true });
@@ -289,4 +305,43 @@ function collectNotes(config) {
   return notes;
 }
 
+function adaptAgentsForStack(dest, bPreset, config) {
+  const ormReplacements = [
+    ['Prisma ORM, and PostgreSQL', `${bPreset.orm}${bPreset.db ? `, and ${bPreset.db}` : ''}`],
+    ['Repository implementations (Prisma)', `Repository implementations (${bPreset.orm})`],
+  ];
+
+  const toolDirs = [];
+  if (config.aiTools !== 'gemini') toolDirs.push('.claude');
+  if (config.aiTools !== 'claude') toolDirs.push('.gemini');
+
+  for (const dir of toolDirs) {
+    replaceInFile(path.join(dest, dir, 'agents', 'backend-developer.md'), ormReplacements);
+    replaceInFile(path.join(dest, dir, 'agents', 'backend-planner.md'), ormReplacements);
+  }
+}
+
+function adaptDocStandards(dest, config) {
+  const docStdPath = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
+  if (!fs.existsSync(docStdPath)) return;
+
+  const replacements = [];
+  if (config.projectType === 'backend') {
+    replacements.push([/\| `ai-specs\/specs\/frontend-standards\.mdc` \|[^\n]*\n/, '']);
+    replacements.push([/\| `docs\/specs\/ui-components\.md` \|[^\n]*\n/, '']);
+    replacements.push([/   - UI component changes → `docs\/specs\/ui-components\.md`\n/, '']);
+  } else if (config.projectType === 'frontend') {
+    replacements.push([/\| `ai-specs\/specs\/backend-standards\.mdc` \|[^\n]*\n/, '']);
+    replacements.push([/\| `docs\/specs\/api-spec\.yaml` \|[^\n]*\n/, '']);
+  }
+
+  if (replacements.length > 0) {
+    replaceInFile(docStdPath, replacements);
+  }
+}
+
+function adaptAgentContent(dest, config) {
+  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.
@@ -35,12 +36,15 @@ function generateInit(config) {
   step('Creating ai-specs/specs/ (4 standards files)');
   ensureDir(path.join(dest, 'ai-specs', 'specs'));
 
-  // base-standards and documentation-standards: copy as-is
-  copyFileIfNotExists(
-    path.join(templateDir, 'ai-specs', 'specs', 'base-standards.mdc'),
-    path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc'),
-    skipped
-  );
+  // base-standards: adapt validation references based on detected stack
+  const baseStdPath = path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc');
+  if (!fs.existsSync(baseStdPath)) {
+    const baseTemplate = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'base-standards.mdc'), 'utf8');
+    const adaptedBase = adaptBaseStandards(baseTemplate, scan, config);
+    fs.writeFileSync(baseStdPath, adaptedBase, 'utf8');
+  } else {
+    skipped.push('ai-specs/specs/base-standards.mdc');
+  }
   copyFileIfNotExists(
     path.join(templateDir, 'ai-specs', 'specs', 'documentation-standards.mdc'),
     path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc'),
@@ -174,6 +178,9 @@ function generateInit(config) {
     removeAgentFiles(dest, BACKEND_AGENTS, config);
   }
 
+  // 7b. Adapt agent/skill content to match detected stack
+  adaptCopiedFiles(dest, scan, config);
+
   // 8. Append to .gitignore
   appendGitignore(dest, skipped);
 
@@ -288,8 +295,239 @@ function safeDelete(filePath) {
   try { fs.unlinkSync(filePath); } catch { /* ignore */ }
 }
 
+// --- Adapt Copied Agent/Skill Files ---
+
+function replaceInCopiedFile(dest, relativePath, replacements) {
+  const filePath = path.join(dest, relativePath);
+  if (!fs.existsSync(filePath)) return;
+  let content = fs.readFileSync(filePath, 'utf8');
+  for (const [from, to] of replacements) {
+    content = content.replaceAll(from, to);
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function regexReplaceInFile(filePath, replacements) {
+  if (!fs.existsSync(filePath)) return;
+  let content = fs.readFileSync(filePath, 'utf8');
+  for (const [from, to] of replacements) {
+    if (from instanceof RegExp) {
+      content = content.replace(from, to);
+    } else {
+      content = content.replaceAll(from, to);
+    }
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function adaptCopiedFiles(dest, scan, config) {
+  const orm = scan.backend.orm || 'your ORM';
+  const db = scan.backend.db || 'your database';
+
+  // Common Zod → generic validation replacements (all agents + skills)
+  // 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
+  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 = [];
+  if (config.aiTools !== 'gemini') toolDirs.push('.claude');
+  if (config.aiTools !== 'claude') toolDirs.push('.gemini');
+
+  for (const dir of toolDirs) {
+    // Backend agents: Zod + ORM replacements
+    if (scan.backend.validation !== 'Zod') {
+      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);
+      replaceInCopiedFile(dest, `${dir}/agents/backend-planner.md`, ormReplacements);
+    }
+
+    // Multi-purpose agents: Zod replacements only
+    if (scan.backend.validation !== 'Zod') {
+      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 + schema path replacements
+    if (scan.backend.validation !== 'Zod') {
+      const allZodReplacements = [...zodReplacements, ...schemaPathReplacements];
+      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/SKILL.md`, allZodReplacements);
+      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/references/ticket-template.md`, allZodReplacements);
+    }
+  }
+
+  // Architecture adaptation: DDD-specific content in backend agents
+  const arch = scan.srcStructure ? scan.srcStructure.pattern : 'ddd';
+  if (arch !== 'ddd') {
+    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 (Claude verbose format)
+        ['specializing in Domain-Driven Design (DDD) layered architecture with deep knowledge of',
+          'specializing in layered architecture with deep knowledge of'],
+        // 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'],
+        [/\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'],
+        // 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'],
+        // 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):'],
+        [/\d+\. \*\*Domain Layer\*\*: Entities, value objects, repository interfaces, domain errors\n/,
+          '1. **Data Layer**: Models, database operations, data access\n'],
+        [/\d+\. \*\*Application Layer\*\*: Services, validators, DTOs\n/,
+          '2. **Business Logic Layer**: Controllers, services, external integrations\n'],
+        [/\d+\. \*\*Infrastructure Layer\*\*: Repository implementations \([^)]*\), external integrations\n/,
+          '3. **Presentation Layer**: Routes, handlers, middleware\n'],
+        [/\d+\. \*\*Presentation Layer\*\*: Controllers, routes, middleware\n/,
+          '4. **Integration Layer**: Wiring, configuration, server registration\n'],
+        // 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'],
+        // 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/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');
+  if (fs.existsSync(docStdPath)) {
+    let content = fs.readFileSync(docStdPath, 'utf8');
+    if (config.projectType === 'backend') {
+      content = content.replace(/\| `ai-specs\/specs\/frontend-standards\.mdc` \|[^\n]*\n/, '');
+      content = content.replace(/\| `docs\/specs\/ui-components\.md` \|[^\n]*\n/, '');
+      content = content.replace(/   - UI component changes → `docs\/specs\/ui-components\.md`\n/, '');
+    } else if (config.projectType === 'frontend') {
+      content = content.replace(/\| `ai-specs\/specs\/backend-standards\.mdc` \|[^\n]*\n/, '');
+      content = content.replace(/\| `docs\/specs\/api-spec\.yaml` \|[^\n]*\n/, '');
+    }
+    fs.writeFileSync(docStdPath, content, 'utf8');
+  }
+}
+
 // --- Standards Adaptation ---
 
+function adaptBaseStandards(template, scan, config) {
+  let content = template;
+
+  // Adapt validation recommendation based on detected library
+  const val = scan.backend.validation;
+  if (val && val !== 'Zod') {
+    content = content.replace(
+      'Use runtime validation (Zod recommended).',
+      `Use runtime validation (${val}).`
+    );
+  } else if (!val) {
+    content = content.replace(
+      'Use runtime validation (Zod recommended).',
+      'Use runtime validation at system boundaries.'
+    );
+  }
+
+  // Adapt Shared Types Strategy section based on project structure
+  const hasSharedTypes = scan.frontend.detected && scan.backend.detected;
+  if (!hasSharedTypes) {
+    // Backend-only or frontend-only: remove entire Shared Types section
+    content = content.replace(
+      /## 5\. Shared Types Strategy\n\n<!-- CONFIG:.*?-->\n\n[\s\S]*?(?=\n## 6\.)/,
+      '## 5. Shared Types Strategy\n\n_Not applicable — single-stack project._\n\n'
+    );
+  } else if (val !== 'Zod') {
+    // Fullstack but not using Zod (or no validation detected): generalize the section
+    content = content.replace(
+      /## 5\. Shared Types Strategy\n\n<!-- CONFIG:.*?-->\n\nFor projects with backend \+ frontend, use a shared workspace for Zod schemas:\n\n```\n[\s\S]*?```\n\n\*\*Rules:\*\*\n[\s\S]*?(?=\n## 6\.)/,
+      `## 5. Shared Types Strategy\n\n<!-- CONFIG: Remove this section if your project has no shared types -->\n\nFor projects with backend + frontend, use a shared workspace for types:\n\n\`\`\`\nproject/\n├── shared/              ← @project/shared (npm workspace)\n│   └── src/types/       ← Shared TypeScript types\n├── backend/             ← imports @project/shared\n└── frontend/            ← imports @project/shared\n\`\`\`\n\n**Rules:**\n- Define shared types in the shared workspace\n- Both apps import from shared — never duplicate type definitions\n- Update shared types FIRST — both apps get changes automatically\n- Wire with npm workspaces + \`tsconfig.json\` paths\n\n`
+    );
+  }
+  // If Zod detected + fullstack: keep as-is (template default is correct)
+
+  // Remove frontend/backend references for single-stack projects
+  if (config.projectType === 'backend') {
+    content = content.replace(/  - \*\*Frontend\*\*: Update `docs\/specs\/ui-components\.md` first\.\n/, '');
+    content = content.replace('`backend-standards.mdc` / `frontend-standards.mdc`', '`backend-standards.mdc`');
+  } else if (config.projectType === 'frontend') {
+    content = content.replace(/  - \*\*Backend\*\*: Update `docs\/specs\/api-spec\.yaml` first\.\n/, '');
+    content = content.replace('`backend-standards.mdc` / `frontend-standards.mdc`', '`frontend-standards.mdc`');
+  }
+
+  return content;
+}
+
 function adaptBackendStandards(template, scan) {
   let content = template;
 
@@ -367,6 +605,11 @@ function adaptBackendStandards(template, scan) {
       /## Database Patterns\n\n[\s\S]*?(?=\n## )/,
       `## Database Patterns\n\n<!-- TODO: Add database access patterns for your project. -->\n`
     );
+  } else if (scan.backend.orm === 'Mongoose') {
+    content = content.replace(
+      /## Database Patterns\n\n[\s\S]*?(?=\n## )/,
+      `## Database Patterns\n\n### Mongoose Best Practices\n- Define schemas in dedicated model files\n- Use TypeScript interfaces alongside Mongoose schemas for type safety\n- Use \`.lean()\` for read-only queries (returns plain objects, better performance)\n- Use \`.select()\` to limit returned fields on large documents\n- Add indexes for frequently queried fields (\`{ index: true }\` or compound \`schema.index()\`)\n- Use \`.populate()\` sparingly — avoid deep nesting, prefer manual joins for complex queries\n- Use middleware (pre/post hooks) for cross-cutting concerns (timestamps, audit logs)\n- Use transactions (\`session\`) for multi-document operations that must be atomic\n- Always handle \`CastError\` (invalid ObjectId) at the controller/middleware level\n\n### Schema Pattern\n\`\`\`typescript\nimport mongoose, { Schema, Document } from 'mongoose';\n\nexport interface IUser extends Document {\n  email: string;\n  name: string;\n  role: 'user' | 'admin';\n}\n\nconst UserSchema = new Schema<IUser>({\n  email: { type: String, required: true, unique: true, index: true },\n  name: { type: String, required: true },\n  role: { type: String, enum: ['user', 'admin'], default: 'user' },\n}, { timestamps: true });\n\nexport const User = mongoose.model<IUser>('User', UserSchema);\n\`\`\`\n\n`
+    );
   } else if (scan.backend.orm !== 'Prisma') {
     content = content.replace(
       /## Database Patterns\n\n[\s\S]*?(?=\n## )/,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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

package/template/AGENTS.md

@@ -11,7 +11,7 @@
 project/
 ├── backend/     ← Backend (has its own package.json)
 ├── frontend/    ← Frontend (has its own package.json)
-├── shared/      ← Shared Zod schemas (optional — see base-standards.mdc § Shared Types)
+├── shared/      ← Shared type schemas (optional — see base-standards.mdc § Shared Types)
 └── docs/        ← Documentation (no package.json)
 ```