create-sdd-project 0.4.2 → 0.5.0

package/README.md

@@ -1,6 +1,7 @@
 # SDD DevFlow
 
 [![npm version](https://img.shields.io/npm/v/create-sdd-project)](https://www.npmjs.com/package/create-sdd-project)
+[![npm downloads](https://img.shields.io/npm/dm/create-sdd-project)](https://www.npmjs.com/package/create-sdd-project)
 [![license](https://img.shields.io/npm/l/create-sdd-project)](LICENSE)
 [![node](https://img.shields.io/node/v/create-sdd-project)](package.json)
 
@@ -16,7 +17,34 @@ A complete development methodology for Claude Code and Gemini that combines spec
 npx create-sdd-project my-app
 ```
 
-The interactive wizard asks about your stack, AI tools, and autonomy level. For defaults (fullstack Express+Next.js):
+The interactive wizard asks about your stack, AI tools, and autonomy level:
+
+```
+🚀 Create SDD DevFlow Project
+
+── Step 1: Project Basics ──────────────────────
+  Project name: my-app
+  Brief project description: Task management API
+
+── Step 3: Project Type & Tech Stack ──────────
+  1) Backend + Frontend (monorepo)  ← default
+  2) Backend only
+  3) Frontend only
+
+── Step 4: AI Tools ────────────────────────────
+  1) Claude Code + Gemini  ← default
+  2) Claude Code only
+  3) Gemini only
+
+── Step 5: Workflow Configuration ──────────────
+  Autonomy level:
+  1) L1 Full Control — Human approves every checkpoint
+  2) L2 Trusted — Human reviews plans + merges only  ← default
+  3) L3 Autopilot — Human only approves merges
+  4) L4 Full Auto — No human checkpoints, CI/CD gates only
+```
+
+For defaults (fullstack Express+Next.js, L2 autonomy):
 
 ```bash
 npx create-sdd-project my-app --yes
@@ -29,18 +57,108 @@ cd your-existing-project
 npx create-sdd-project --init
 ```
 
-Scans your project, detects your stack and architecture, and installs SDD files adapted to your project. Never modifies existing code or overwrites existing files.
+The scanner detects your stack and installs adapted SDD files:
+
+```
+🔍 Scanning project...
+
+    Project:       my-api
+    Language:      TypeScript
+    Backend:       Express + Mongoose + MongoDB
+    Frontend:      Not detected
+    Architecture:  Layered (controllers + handlers + managers)
+    Tests:         Jest (3 test files)
+    Monorepo:      No
+
+Adding SDD DevFlow to my-api...
+
+  ✓ Installing Claude Code config (agents, skills, commands, hooks)
+  ✓ Installing Gemini config (agents, skills, commands)
+  ✓ Creating ai-specs/specs/ (4 standards files)
+  ✓ Creating docs/project_notes/ (product tracker, memory)
+  ✓ Creating AGENTS.md
+  ✓ Setting autonomy level: L2 (Trusted)
+
+Done! Next steps:
+  git add -A && git commit -m "chore: add SDD DevFlow to existing project"
+  # Open in your AI coding tool and run: add feature "your first feature"
+```
+
+Never modifies existing code or overwrites existing files.
+
+### Upgrade
+
+When a new version of SDD DevFlow is released, upgrade your project's template files:
+
+```bash
+cd your-existing-project
+npx create-sdd-project@latest --upgrade
+```
+
+```
+🔄 SDD DevFlow Upgrade
+
+  Current version:  0.4.2
+  New version:      0.5.0
+  AI tools:         Claude Code + Gemini
+  Project type:     backend
+
+  Will replace:
+    ✓ .claude/ (agents, skills, hooks)
+    ✓ .gemini/ (agents, skills, commands)
+    ✓ AGENTS.md, CLAUDE.md / GEMINI.md
+    ✓ .env.example
+
+  Will preserve:
+    ⊘ .claude/settings.local.json (personal settings)
+    ⊘ docs/project_notes/* (project memory)
+    ⊘ docs/specs/* (your specs)
+    ⊘ docs/tickets/* (your tickets)
+    ⊘ .gitignore
+
+  Standards:
+    ✓ ai-specs/specs/base-standards.mdc — unchanged, will update
+    ⚠ ai-specs/specs/backend-standards.mdc — modified by you, preserved
+
+  Proceed? (y/N)
+```
+
+**What gets upgraded:**
+- Agent definitions, skills, hooks, and commands
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.env.example`
+- Standards files (`.mdc`) — only if you haven't customized them
+
+**What is always preserved:**
+- Your project documentation (`docs/project_notes/`, `docs/specs/`, `docs/tickets/`)
+- Custom agents you added to `.claude/agents/` or `.gemini/agents/`
+- Custom commands in `.claude/commands/`
+- Personal settings (`.claude/settings.local.json`)
+- Your `.gitignore`
+- Autonomy level setting
+
+For non-interactive upgrades (CI/scripts): `npx create-sdd-project@latest --upgrade --yes`
 
 ### After Setup
 
-Open in your AI coding tool and run:
+Open your project in Claude Code or Gemini and start building:
+
+**Claude Code:**
+```
+/add-feature "user authentication with JWT"
+/start-task F001
+/show-progress
+/next-task
+```
 
+**Gemini:**
 ```
-add feature "your first feature"
-start task F001
+/add-feature "user authentication with JWT"
+/start-task F001
+/show-progress
+/next-task
 ```
 
-The workflow skill guides you through each step with checkpoints based on your autonomy level.
+The workflow skill guides you through each step — from spec writing to implementation to code review — with checkpoints based on your autonomy level.
 
 ---
 
@@ -149,7 +267,7 @@ When running `--init` on an existing project, the scanner automatically detects:
 | **Component libraries** | Radix UI, Headless UI, Material UI, Chakra UI, Ant Design |
 | **State management** | Zustand, Redux, Jotai, TanStack Query, Recoil, Pinia, MobX |
 | **Testing** | Jest, Vitest, Mocha (unit) + Playwright, Cypress (e2e) |
-| **Architecture** | MVC, DDD, feature-based, handler-based, flat |
+| **Architecture** | MVC, DDD, feature-based, handler-based, layered, flat |
 | **Project type** | Monorepo (workspaces, Lerna, Turbo, pnpm) or single-package |
 
 Standards files are adapted to match your actual architecture — not generic defaults.
@@ -203,7 +321,7 @@ Configurable via the wizard or `<!-- CONFIG -->` comments in template files:
 
 - **Backend**: Node.js + Express + Prisma + PostgreSQL
 - **Frontend**: Next.js (App Router) + Tailwind CSS + Radix UI + Zustand
-- **Shared Types**: Zod schemas with `z.infer<>` for TypeScript types
+- **Shared Types**: Validation schemas with TypeScript type inference
 - **Testing**: Jest (unit) + Playwright (e2e)
 - **Methodology**: TDD + DDD + Spec-Driven Development
 
@@ -214,7 +332,7 @@ These 6 principles apply to ALL tasks, ALL agents, ALL complexity levels:
 1. **Spec First** — No implementation without an approved specification
 2. **Small Tasks** — Work in baby steps, one at a time
 3. **Test-Driven Development** — Write tests before implementation
-4. **Type Safety** — Strict TypeScript, no `any`, runtime validation with Zod
+4. **Type Safety** — Strict TypeScript, no `any`, runtime validation at boundaries
 5. **English Only** — All code, comments, docs, commits, and tickets in English
 6. **Reuse Over Recreate** — Always check existing code before proposing new files
 
@@ -224,21 +342,25 @@ These 6 principles apply to ALL tasks, ALL agents, ALL complexity levels:
 - Node.js 18+
 - `jq` (for quick-scan hook): `brew install jq` (macOS) or `apt install jq` (Linux)
 
-## Manual Setup (Alternative)
+## Manual Setup
 
-If you prefer manual configuration over the CLI wizard:
+If you prefer manual configuration over the CLI wizard, copy the template directory and look for `<!-- CONFIG: ... -->` comments in the files to customize:
 
 ```bash
-cp -r template/ /path/to/your-project/
+cp -r node_modules/create-sdd-project/template/ /path/to/your-project/
 ```
 
-Then look for `<!-- CONFIG: ... -->` comments in the files to customize.
-
 ## Roadmap
 
-- **Agent Teams**: Parallel execution of independent tasks (waiting for Claude Code Agent Teams to stabilize)
-- **PM Agent + L5 Autonomous**: AI-driven feature orchestration with human review at milestone boundaries
+- **Monorepo improvements**: Better support for pnpm workspaces and Turbo
+- **SDD Upgrade/Migration**: Version bumps for projects already using SDD
 - **Retrofit Testing**: Automated test generation for existing projects with low coverage
+- **Agent Teams**: Parallel execution of independent tasks
+- **PM Agent + L5 Autonomous**: AI-driven feature orchestration with human review at milestone boundaries
+
+## Contributing
+
+Found a bug or have a suggestion? [Open an issue on GitHub](https://github.com/pbojeda/sdd-devflow/issues).
 
 ## License
 

package/bin/cli.js

@@ -8,8 +8,13 @@ const args = process.argv.slice(2);
 const projectName = args.find((a) => !a.startsWith('-'));
 const useDefaults = args.includes('--yes') || args.includes('-y');
 const isInit = args.includes('--init');
+const isUpgrade = args.includes('--upgrade');
+const isForce = args.includes('--force');
 
 async function main() {
+  if (isUpgrade) {
+    return runUpgrade();
+  }
   if (isInit) {
     return runInit();
   }
@@ -90,6 +95,106 @@ async function runInit() {
   generateInit(config);
 }
 
+async function runUpgrade() {
+  const { scan } = require('../lib/scanner');
+  const { buildInitDefaultConfig } = require('../lib/init-wizard');
+  const readline = require('readline');
+  const {
+    generateUpgrade,
+    readInstalledVersion,
+    getPackageVersion,
+    detectAiTools,
+    detectProjectType,
+    readAutonomyLevel,
+    collectCustomAgents,
+    collectCustomCommands,
+    buildSummary,
+  } = require('../lib/upgrade-generator');
+
+  const cwd = process.cwd();
+
+  // Validate: must be in an existing project
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    console.error('Error: No package.json found in current directory.');
+    console.error('The --upgrade flag must be run from inside an existing project.');
+    process.exit(1);
+  }
+
+  // Validate: SDD must be installed
+  if (!fs.existsSync(path.join(cwd, 'ai-specs'))) {
+    console.error('Error: ai-specs/ directory not found.');
+    console.error('SDD DevFlow does not appear to be installed. Use --init first.');
+    process.exit(1);
+  }
+
+  // Validate: no project name with --upgrade
+  if (projectName) {
+    console.error('Error: Cannot specify a project name with --upgrade.');
+    console.error('Usage: create-sdd-project --upgrade');
+    process.exit(1);
+  }
+
+  // Read current state
+  const installedVersion = readInstalledVersion(cwd);
+  const packageVersion = getPackageVersion();
+
+  // Same version check
+  if (installedVersion === packageVersion && !isForce) {
+    console.log(`\nSDD DevFlow is already at version ${packageVersion}.`);
+    console.log('Use --force to re-install the same version.\n');
+    return;
+  }
+
+  // Scan project
+  const scanResult = scan(cwd);
+
+  // Detect current config from installed files
+  const aiTools = detectAiTools(cwd);
+  const projectType = detectProjectType(cwd);
+  const autonomy = readAutonomyLevel(cwd);
+  const customAgents = collectCustomAgents(cwd);
+  const customCommands = collectCustomCommands(cwd);
+  const settingsLocal = fs.existsSync(path.join(cwd, '.claude', 'settings.local.json'));
+
+  // Build config (reuse init defaults as base)
+  const config = buildInitDefaultConfig(scanResult);
+  config.aiTools = aiTools;
+  config.projectType = projectType;
+  config.autonomyLevel = autonomy.level;
+  config.autonomyName = autonomy.name;
+  config.installedVersion = installedVersion;
+
+  // Build and show summary
+  const state = {
+    installedVersion,
+    packageVersion,
+    aiTools,
+    projectType,
+    customAgents,
+    customCommands,
+    settingsLocal,
+    standardsStatus: [], // computed during generation
+  };
+
+  if (!useDefaults) {
+    console.log('\n' + buildSummary(state));
+    console.log('');
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question('  Proceed? (y/N) ', resolve);
+    });
+    rl.close();
+
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      console.log('\nUpgrade cancelled.\n');
+      return;
+    }
+  }
+
+  generateUpgrade(config);
+}
+
 main().catch((err) => {
   console.error('\nError:', err.message);
   process.exit(1);

package/lib/config.js

@@ -93,6 +93,16 @@ const BRANCHING_STRATEGIES = [
 const FRONTEND_AGENTS = ['frontend-developer.md', 'frontend-planner.md'];
 const BACKEND_AGENTS = ['backend-developer.md', 'backend-planner.md', 'database-architect.md'];
 
+// All template-provided agent files (for upgrade: detect custom agents)
+const TEMPLATE_AGENTS = [
+  ...FRONTEND_AGENTS,
+  ...BACKEND_AGENTS,
+  'spec-creator.md',
+  'code-review-specialist.md',
+  'production-code-validator.md',
+  'qa-engineer.md',
+];
+
 module.exports = {
   DEFAULTS,
   PROJECT_TYPES,
@@ -103,4 +113,5 @@ module.exports = {
   BRANCHING_STRATEGIES,
   FRONTEND_AGENTS,
   BACKEND_AGENTS,
+  TEMPLATE_AGENTS,
 };

package/lib/generator.js

@@ -77,6 +77,10 @@ function generate(config) {
     safeDelete(path.join(dest, 'CLAUDE.md'));
   }
 
+  // Write version marker
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  fs.writeFileSync(path.join(dest, '.sdd-version'), pkg.version + '\n', 'utf8');
+
   // Show notes
   const notes = collectNotes(config);
   if (notes.length > 0) {

package/lib/init-generator.js

@@ -230,6 +230,10 @@ function generateInit(config) {
     console.log('     Referenced in docs/project_notes/key_facts.md');
   }
 
+  // Write version marker
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  fs.writeFileSync(path.join(dest, '.sdd-version'), pkg.version + '\n', 'utf8');
+
   // Done
   console.log(`\nDone! Next steps:`);
   console.log(`  git add -A && git commit -m "chore: add SDD DevFlow to existing project"`);
@@ -996,4 +1000,14 @@ function appendGitignore(dest, skipped) {
   }
 }
 
-module.exports = { generateInit };
+module.exports = {
+  generateInit,
+  adaptBaseStandards,
+  adaptBackendStandards,
+  adaptFrontendStandards,
+  adaptAgentsMd,
+  adaptCopiedFiles,
+  adaptEnvExample,
+  updateAutonomy,
+  regexReplaceInFile,
+};

package/lib/upgrade-generator.js

@@ -0,0 +1,504 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  AUTONOMY_LEVELS,
+  FRONTEND_AGENTS,
+  BACKEND_AGENTS,
+  TEMPLATE_AGENTS,
+} = require('./config');
+const { adaptAgentContentForProjectType } = require('./adapt-agents');
+const {
+  adaptBaseStandards,
+  adaptBackendStandards,
+  adaptFrontendStandards,
+  adaptAgentsMd,
+  adaptCopiedFiles,
+  adaptEnvExample,
+  updateAutonomy,
+  regexReplaceInFile,
+} = require('./init-generator');
+
+/**
+ * Read the installed SDD version from .sdd-version file.
+ */
+function readInstalledVersion(dest) {
+  const versionFile = path.join(dest, '.sdd-version');
+  if (fs.existsSync(versionFile)) {
+    return fs.readFileSync(versionFile, 'utf8').trim();
+  }
+  return 'unknown';
+}
+
+/**
+ * Read the current package version.
+ */
+function getPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+/**
+ * Detect which AI tools are installed by checking existing directories.
+ */
+function detectAiTools(dest) {
+  const hasClaude = fs.existsSync(path.join(dest, '.claude'));
+  const hasGemini = fs.existsSync(path.join(dest, '.gemini'));
+  if (hasClaude && hasGemini) return 'both';
+  if (hasClaude) return 'claude';
+  if (hasGemini) return 'gemini';
+  return 'both'; // fallback: install both
+}
+
+/**
+ * Detect project type from existing agent files.
+ */
+function detectProjectType(dest) {
+  const toolDir = fs.existsSync(path.join(dest, '.claude')) ? '.claude' : '.gemini';
+  const agentsDir = path.join(dest, toolDir, 'agents');
+  if (!fs.existsSync(agentsDir)) return 'fullstack';
+
+  const agents = fs.readdirSync(agentsDir);
+  const hasFrontend = agents.some((a) => FRONTEND_AGENTS.includes(a));
+  const hasBackend = agents.some((a) => BACKEND_AGENTS.includes(a));
+
+  if (hasFrontend && hasBackend) return 'fullstack';
+  if (hasBackend) return 'backend';
+  if (hasFrontend) return 'frontend';
+  return 'fullstack';
+}
+
+/**
+ * Read autonomy level from CLAUDE.md or GEMINI.md.
+ */
+function readAutonomyLevel(dest) {
+  for (const file of ['CLAUDE.md', 'GEMINI.md']) {
+    const filePath = path.join(dest, file);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const match = content.match(/\*\*Autonomy Level: (\d+) \(([^)]+)\)\*\*/);
+      if (match) {
+        return { level: parseInt(match[1], 10), name: match[2] };
+      }
+    }
+  }
+  return { level: 2, name: 'Trusted' }; // default
+}
+
+/**
+ * Find custom agent files (not in template list).
+ * Returns array of { name, content } objects.
+ */
+function collectCustomAgents(dest) {
+  const customs = [];
+  for (const toolDir of ['.claude', '.gemini']) {
+    const agentsDir = path.join(dest, toolDir, 'agents');
+    if (!fs.existsSync(agentsDir)) continue;
+    const files = fs.readdirSync(agentsDir);
+    for (const file of files) {
+      if (!TEMPLATE_AGENTS.includes(file) && file.endsWith('.md')) {
+        customs.push({
+          relativePath: path.join(toolDir, 'agents', file),
+          content: fs.readFileSync(path.join(agentsDir, file), 'utf8'),
+        });
+      }
+    }
+  }
+  return customs;
+}
+
+/**
+ * Find custom command files (not .gitkeep).
+ * Returns array of { relativePath, content } objects.
+ */
+function collectCustomCommands(dest) {
+  const customs = [];
+  const commandsDir = path.join(dest, '.claude', 'commands');
+  if (!fs.existsSync(commandsDir)) return customs;
+  const files = fs.readdirSync(commandsDir);
+  for (const file of files) {
+    if (file === '.gitkeep') continue;
+    customs.push({
+      relativePath: path.join('.claude', 'commands', file),
+      content: fs.readFileSync(path.join(commandsDir, file), 'utf8'),
+    });
+  }
+  return customs;
+}
+
+/**
+ * Check if a standard file has been modified by the user.
+ * Compares existing file against freshly generated version.
+ */
+function isStandardModified(existingContent, freshContent) {
+  return existingContent.trim() !== freshContent.trim();
+}
+
+/**
+ * Build the upgrade summary for display.
+ */
+function buildSummary(state) {
+  const lines = [];
+  lines.push('🔄 SDD DevFlow Upgrade\n');
+  lines.push(`  Current version:  ${state.installedVersion}`);
+  lines.push(`  New version:      ${state.packageVersion}`);
+  lines.push(`  AI tools:         ${state.aiTools === 'both' ? 'Claude Code + Gemini' : state.aiTools === 'claude' ? 'Claude Code' : 'Gemini'}`);
+  lines.push(`  Project type:     ${state.projectType}\n`);
+
+  lines.push('  Will replace:');
+  if (state.aiTools !== 'gemini') {
+    const customNote = state.customAgents.filter((a) => a.relativePath.startsWith('.claude')).length > 0
+      ? ` — custom agents preserved` : '';
+    lines.push(`    ✓ .claude/ (agents, skills, hooks)${customNote}`);
+  }
+  if (state.aiTools !== 'claude') {
+    lines.push(`    ✓ .gemini/ (agents, skills, commands)`);
+  }
+  lines.push('    ✓ AGENTS.md, CLAUDE.md / GEMINI.md');
+  lines.push('    ✓ .env.example\n');
+
+  lines.push('  Will preserve:');
+  if (state.settingsLocal) lines.push('    ⊘ .claude/settings.local.json (personal settings)');
+  lines.push('    ⊘ .claude/settings.json permissions (if any)');
+  for (const c of state.customCommands) lines.push(`    ⊘ ${c.relativePath} (custom command)`);
+  for (const a of state.customAgents) lines.push(`    ⊘ ${a.relativePath} (custom agent)`);
+  lines.push('    ⊘ docs/project_notes/* (project memory)');
+  lines.push('    ⊘ docs/specs/* (your specs)');
+  lines.push('    ⊘ docs/tickets/* (your tickets)');
+  lines.push('    ⊘ .gitignore\n');
+
+  if (state.standardsStatus.length > 0) {
+    lines.push('  Standards:');
+    for (const s of state.standardsStatus) {
+      if (s.modified) {
+        lines.push(`    ⚠ ${s.name} — modified by you, will be preserved`);
+      } else {
+        lines.push(`    ✓ ${s.name} — unchanged, will update`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Main upgrade function.
+ */
+function generateUpgrade(config) {
+  const templateDir = path.join(__dirname, '..', 'template');
+  const dest = config.projectDir;
+  const scan = config.scanResult;
+  const aiTools = config.aiTools;
+  const projectType = config.projectType;
+
+  console.log(`\nUpgrading SDD DevFlow in ${config.projectName}...\n`);
+
+  // --- a) Preserve user items ---
+  const autonomy = readAutonomyLevel(dest);
+  const customAgents = collectCustomAgents(dest);
+  const customCommands = collectCustomCommands(dest);
+
+  // Preserve settings.local.json
+  let settingsLocal = null;
+  const settingsLocalPath = path.join(dest, '.claude', 'settings.local.json');
+  if (fs.existsSync(settingsLocalPath)) {
+    settingsLocal = fs.readFileSync(settingsLocalPath, 'utf8');
+  }
+
+  let replaced = 0;
+  let preserved = 0;
+
+  // --- b) Replace SDD-owned directories ---
+  const toolDirs = [];
+  if (aiTools !== 'gemini') toolDirs.push('.claude');
+  if (aiTools !== 'claude') toolDirs.push('.gemini');
+
+  for (const dir of toolDirs) {
+    const base = path.join(dest, dir);
+    // Delete specific SDD-owned subdirectories (NOT commands for .claude)
+    for (const sub of ['agents', 'skills', 'hooks', 'styles']) {
+      const subDir = path.join(base, sub);
+      if (fs.existsSync(subDir)) {
+        fs.rmSync(subDir, { recursive: true, force: true });
+      }
+    }
+    // For .gemini, also remove commands (SDD-owned — Gemini TOML commands)
+    if (dir === '.gemini') {
+      const cmdDir = path.join(base, 'commands');
+      if (fs.existsSync(cmdDir)) {
+        fs.rmSync(cmdDir, { recursive: true, force: true });
+      }
+    }
+
+    // Copy fresh from template
+    const templateToolDir = path.join(templateDir, dir);
+    if (fs.existsSync(templateToolDir)) {
+      for (const sub of ['agents', 'skills', 'hooks', 'styles', 'commands']) {
+        const srcSub = path.join(templateToolDir, sub);
+        const destSub = path.join(base, sub);
+        if (fs.existsSync(srcSub)) {
+          // For .claude/commands, merge (don't overwrite user's custom commands)
+          if (dir === '.claude' && sub === 'commands') {
+            // Just ensure directory exists — template only has .gitkeep
+            fs.mkdirSync(destSub, { recursive: true });
+          } else {
+            fs.cpSync(srcSub, destSub, { recursive: true });
+          }
+          replaced++;
+        }
+      }
+
+      // Merge settings.json — update hooks from template, preserve user's permissions/additionalDirectories
+      const settingsSrc = path.join(templateToolDir, 'settings.json');
+      const settingsDest = path.join(base, 'settings.json');
+      if (fs.existsSync(settingsSrc)) {
+        const templateSettings = JSON.parse(fs.readFileSync(settingsSrc, 'utf8'));
+        if (fs.existsSync(settingsDest)) {
+          const userSettings = JSON.parse(fs.readFileSync(settingsDest, 'utf8'));
+          // Keep user's permissions and additionalDirectories, take template's hooks
+          const merged = { ...templateSettings };
+          if (userSettings.permissions) merged.permissions = userSettings.permissions;
+          if (userSettings.additionalDirectories) merged.additionalDirectories = userSettings.additionalDirectories;
+          fs.writeFileSync(settingsDest, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+        } else {
+          fs.copyFileSync(settingsSrc, settingsDest);
+        }
+      }
+    }
+  }
+  step('Replaced agents, skills, hooks, and settings');
+
+  // --- c) Restore preserved items ---
+  for (const agent of customAgents) {
+    const agentPath = path.join(dest, agent.relativePath);
+    fs.mkdirSync(path.dirname(agentPath), { recursive: true });
+    fs.writeFileSync(agentPath, agent.content, 'utf8');
+    preserved++;
+  }
+  if (customAgents.length > 0) {
+    step(`Restored ${customAgents.length} custom agent(s)`);
+  }
+
+  // Restore settings.local.json
+  if (settingsLocal) {
+    fs.writeFileSync(settingsLocalPath, settingsLocal, 'utf8');
+    preserved++;
+  }
+
+  // --- d) Handle standards (smart diff) ---
+  const standardsResults = [];
+
+  // base-standards.mdc
+  const baseStdPath = path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc');
+  if (fs.existsSync(baseStdPath)) {
+    const existing = fs.readFileSync(baseStdPath, 'utf8');
+    const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'base-standards.mdc'), 'utf8');
+    const fresh = adaptBaseStandards(template, scan, config);
+    if (isStandardModified(existing, fresh)) {
+      standardsResults.push({ name: 'ai-specs/specs/base-standards.mdc', modified: true });
+      preserved++;
+    } else {
+      fs.writeFileSync(baseStdPath, fresh, 'utf8');
+      standardsResults.push({ name: 'ai-specs/specs/base-standards.mdc', modified: false });
+      replaced++;
+    }
+  }
+
+  // backend-standards.mdc
+  if (projectType !== 'frontend') {
+    const backendStdPath = path.join(dest, 'ai-specs', 'specs', 'backend-standards.mdc');
+    if (fs.existsSync(backendStdPath)) {
+      const existing = fs.readFileSync(backendStdPath, 'utf8');
+      const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'backend-standards.mdc'), 'utf8');
+      const fresh = adaptBackendStandards(template, scan);
+      if (isStandardModified(existing, fresh)) {
+        standardsResults.push({ name: 'ai-specs/specs/backend-standards.mdc', modified: true });
+        preserved++;
+      } else {
+        fs.writeFileSync(backendStdPath, fresh, 'utf8');
+        standardsResults.push({ name: 'ai-specs/specs/backend-standards.mdc', modified: false });
+        replaced++;
+      }
+    }
+  }
+
+  // frontend-standards.mdc
+  if (projectType !== 'backend') {
+    const frontendStdPath = path.join(dest, 'ai-specs', 'specs', 'frontend-standards.mdc');
+    if (fs.existsSync(frontendStdPath)) {
+      const existing = fs.readFileSync(frontendStdPath, 'utf8');
+      const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'frontend-standards.mdc'), 'utf8');
+      const fresh = adaptFrontendStandards(template, scan);
+      if (isStandardModified(existing, fresh)) {
+        standardsResults.push({ name: 'ai-specs/specs/frontend-standards.mdc', modified: true });
+        preserved++;
+      } else {
+        fs.writeFileSync(frontendStdPath, fresh, 'utf8');
+        standardsResults.push({ name: 'ai-specs/specs/frontend-standards.mdc', modified: false });
+        replaced++;
+      }
+    }
+  }
+
+  // documentation-standards.mdc — always replace (unlikely customized, no adaptation)
+  const docStdSrc = path.join(templateDir, 'ai-specs', 'specs', 'documentation-standards.mdc');
+  const docStdDest = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
+  if (fs.existsSync(docStdSrc)) {
+    fs.copyFileSync(docStdSrc, docStdDest);
+    replaced++;
+  }
+
+  step('Updated standards files');
+  const modifiedStandards = standardsResults.filter((s) => s.modified);
+  if (modifiedStandards.length > 0) {
+    for (const s of modifiedStandards) {
+      console.log(`    ⚠ ${s.name} — customized, preserved`);
+    }
+  }
+
+  // --- e) Replace top-level configs ---
+  // AGENTS.md
+  const agentsMdTemplate = fs.readFileSync(path.join(templateDir, 'AGENTS.md'), 'utf8');
+  const adaptedAgentsMd = adaptAgentsMd(agentsMdTemplate, config, scan);
+  fs.writeFileSync(path.join(dest, 'AGENTS.md'), adaptedAgentsMd, 'utf8');
+  replaced++;
+
+  // CLAUDE.md / GEMINI.md
+  if (aiTools !== 'gemini') {
+    fs.copyFileSync(path.join(templateDir, 'CLAUDE.md'), path.join(dest, 'CLAUDE.md'));
+    replaced++;
+  }
+  if (aiTools !== 'claude') {
+    fs.copyFileSync(path.join(templateDir, 'GEMINI.md'), path.join(dest, 'GEMINI.md'));
+    replaced++;
+  }
+
+  // Restore autonomy level
+  const autonomyConfig = {
+    autonomyLevel: autonomy.level,
+    autonomyName: autonomy.name,
+  };
+  // Ensure autonomy name matches expected values
+  const levelInfo = AUTONOMY_LEVELS.find((l) => l.level === autonomy.level);
+  if (levelInfo) {
+    autonomyConfig.autonomyName = levelInfo.name;
+  }
+  updateAutonomy(dest, autonomyConfig);
+  step(`Restored autonomy level: L${autonomy.level} (${autonomyConfig.autonomyName})`);
+
+  // .env.example — generate fresh, then append any custom lines from existing
+  let envContent = fs.readFileSync(path.join(templateDir, '.env.example'), 'utf8');
+  envContent = adaptEnvExample(envContent, config, scan);
+  const envPath = path.join(dest, '.env.example');
+  if (fs.existsSync(envPath)) {
+    const existingEnv = fs.readFileSync(envPath, 'utf8');
+    const freshLines = new Set(envContent.split('\n').map((l) => l.trim()));
+    const customLines = existingEnv.split('\n').filter((line) => {
+      const trimmed = line.trim();
+      // Keep lines that are not in the fresh version and are not empty
+      return trimmed.length > 0 && !freshLines.has(trimmed);
+    });
+    if (customLines.length > 0) {
+      envContent = envContent.trimEnd() + '\n\n# Project-specific variables (preserved from previous version)\n' + customLines.join('\n') + '\n';
+    }
+  }
+  fs.writeFileSync(envPath, envContent, 'utf8');
+  replaced++;
+
+  step('Replaced AGENTS.md, CLAUDE.md/GEMINI.md, .env.example');
+
+  // --- f) Adapt for project type ---
+  // Remove agents for single-stack projects
+  if (projectType === 'backend') {
+    for (const agent of FRONTEND_AGENTS) {
+      for (const dir of toolDirs) {
+        const agentPath = path.join(dest, dir, 'agents', agent);
+        try { fs.unlinkSync(agentPath); } catch { /* ignore */ }
+      }
+    }
+    // Remove frontend spec doc if it doesn't exist as user-owned
+    // (don't touch docs/specs/ — user-owned)
+  } else if (projectType === 'frontend') {
+    for (const agent of BACKEND_AGENTS) {
+      for (const dir of toolDirs) {
+        const agentPath = path.join(dest, dir, 'agents', agent);
+        try { fs.unlinkSync(agentPath); } catch { /* ignore */ }
+      }
+    }
+  }
+
+  // Adapt agent/skill content for project type
+  if (projectType !== 'fullstack') {
+    adaptAgentContentForProjectType(dest, config, regexReplaceInFile);
+  }
+
+  // Adapt copied files for detected stack (Zod, Prisma, DDD, etc.)
+  adaptCopiedFiles(dest, scan, config);
+
+  // Adapt documentation-standards for project type
+  const docStdPath2 = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
+  if (fs.existsSync(docStdPath2)) {
+    if (projectType === 'backend') {
+      regexReplaceInFile(docStdPath2, [
+        [/\| `ai-specs\/specs\/frontend-standards\.mdc` \|[^\n]*\n/, ''],
+        [/\| `docs\/specs\/ui-components\.md` \|[^\n]*\n/, ''],
+        [/   - UI component changes → `docs\/specs\/ui-components\.md`\n/, ''],
+      ]);
+    } else if (projectType === 'frontend') {
+      regexReplaceInFile(docStdPath2, [
+        [/\| `ai-specs\/specs\/backend-standards\.mdc` \|[^\n]*\n/, ''],
+        [/\| `docs\/specs\/api-spec\.yaml` \|[^\n]*\n/, ''],
+      ]);
+    }
+  }
+
+  step('Adapted files for project type and stack');
+
+  // --- g) Write version marker ---
+  const newVersion = getPackageVersion();
+  fs.writeFileSync(path.join(dest, '.sdd-version'), newVersion + '\n', 'utf8');
+  step(`Updated .sdd-version to ${newVersion}`);
+
+  // --- Show result ---
+  const updatedCount = standardsResults.filter((s) => !s.modified).length;
+  const preservedCount = modifiedStandards.length;
+
+  console.log(`\n✅ Upgraded SDD DevFlow: ${config.installedVersion} → ${newVersion}\n`);
+  console.log(`  Replaced: agents, skills, hooks, configs`);
+  if (customAgents.length > 0 || customCommands.length > 0 || settingsLocal) {
+    const items = [];
+    if (customAgents.length > 0) items.push(`${customAgents.length} custom agent(s)`);
+    if (customCommands.length > 0) items.push(`${customCommands.length} custom command(s)`);
+    if (settingsLocal) items.push('personal settings');
+    console.log(`  Preserved: ${items.join(', ')}`);
+  }
+  if (standardsResults.length > 0) {
+    console.log(`  Standards: ${updatedCount} updated, ${preservedCount} preserved (customized)`);
+  }
+
+  if (modifiedStandards.length > 0) {
+    console.log(`\n  ⚠ Review preserved standards for compatibility:`);
+    for (const s of modifiedStandards) {
+      console.log(`    - ${s.name} (customized — not updated)`);
+    }
+  }
+
+  console.log(`\nNext: git add -A && git commit -m "chore: upgrade SDD DevFlow to ${newVersion}"\n`);
+}
+
+function step(msg) {
+  console.log(`  ✓ ${msg}`);
+}
+
+module.exports = {
+  generateUpgrade,
+  readInstalledVersion,
+  getPackageVersion,
+  detectAiTools,
+  detectProjectType,
+  readAutonomyLevel,
+  collectCustomAgents,
+  collectCustomCommands,
+  buildSummary,
+};

package/package.json

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