create-sdd-project 0.6.1 → 0.8.0

package/README.md

@@ -168,6 +168,66 @@ npx create-sdd-project --doctor
 
 Exit code 1 if errors found — useful for CI pipelines.
 
+### Eject (Uninstall SDD)
+
+Cleanly remove all SDD DevFlow files from your project:
+
+```bash
+cd your-project
+npx create-sdd-project --eject
+```
+
+```
+🗑️  SDD DevFlow Eject
+
+  Installed version:  0.7.0
+  AI tools:           Claude Code + Gemini
+  Project type:       backend
+
+  Will remove:
+    ✗ .claude/agents/           template agents
+    ✗ .claude/skills/
+    ✗ .claude/hooks/
+    ✗ .claude/settings.json
+    ✗ .gemini/                  entire directory
+    ✗ ai-specs/                 standards
+    ✗ AGENTS.md
+    ✗ CLAUDE.md / GEMINI.md
+    ✗ .env.example
+    ✗ .sdd-version
+    ✗ .github/workflows/ci.yml  (SDD-generated)
+
+  Will preserve:
+    ⊘ .claude/agents/my-agent.md   (custom agent)
+    ⊘ .claude/settings.local.json  (personal settings)
+    ⊘ docs/                        (project notes, specs, tickets)
+
+  Proceed? (y/N)
+```
+
+**What gets removed:** All SDD-generated files (agents, skills, hooks, standards, configs, CI workflow).
+
+**What is always preserved:** Custom agents, custom commands, personal settings, project documentation (`docs/`), customized CI workflows (without SDD marker).
+
+For non-interactive eject: `npx create-sdd-project --eject --yes`
+
+Preview what would be removed: `npx create-sdd-project --eject --diff`
+
+To re-install later: `npx create-sdd-project --init`
+
+### Preview Changes (--diff)
+
+See what `--init`, `--upgrade`, or `--eject` would do without modifying anything:
+
+```bash
+cd your-existing-project
+npx create-sdd-project --init --diff      # Preview init
+npx create-sdd-project --upgrade --diff   # Preview upgrade
+npx create-sdd-project --eject --diff    # Preview eject
+```
+
+Shows detected stack, files that would be created/replaced/preserved, and standards status — zero filesystem writes.
+
 ### CI/CD (Auto-Generated)
 
 Every project gets a GitHub Actions CI workflow at `.github/workflows/ci.yml`, adapted to your stack:

package/bin/cli.js

@@ -11,11 +11,19 @@ const isInit = args.includes('--init');
 const isUpgrade = args.includes('--upgrade');
 const isDoctor = args.includes('--doctor');
 const isForce = args.includes('--force');
+const isEject = args.includes('--eject');
+const isDiff = args.includes('--diff');
 
 async function main() {
+  if (isDiff) {
+    return runDiff();
+  }
   if (isDoctor) {
     return runDoctorCmd();
   }
+  if (isEject) {
+    return runEject();
+  }
   if (isUpgrade) {
     return runUpgrade();
   }
@@ -216,6 +224,169 @@ async function runUpgrade() {
   generateUpgrade(config);
 }
 
+async function runEject() {
+  const readline = require('readline');
+  const {
+    collectEjectInventory,
+    buildEjectSummary,
+    generateEject,
+  } = require('../lib/eject-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 --eject 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. Nothing to eject.');
+    process.exit(1);
+  }
+
+  // Validate: no project name with --eject
+  if (projectName) {
+    console.error('Error: Cannot specify a project name with --eject.');
+    console.error('Usage: create-sdd-project --eject');
+    process.exit(1);
+  }
+
+  const state = collectEjectInventory(cwd);
+
+  if (!useDefaults) {
+    console.log('\n' + buildEjectSummary(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('\nEject cancelled.\n');
+      return;
+    }
+  }
+
+  generateEject(cwd);
+}
+
+async function runDiff() {
+  if (!isInit && !isUpgrade && !isEject) {
+    console.error('Error: --diff must be combined with --init, --upgrade, or --eject.');
+    console.error('Usage: create-sdd-project --init --diff');
+    console.error('       create-sdd-project --upgrade --diff');
+    console.error('       create-sdd-project --eject --diff');
+    process.exit(1);
+  }
+
+  if (projectName) {
+    console.error('Error: Cannot specify a project name with --diff.');
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+
+  if (!fs.existsSync(path.join(cwd, 'package.json'))) {
+    console.error('Error: No package.json found in current directory.');
+    process.exit(1);
+  }
+
+  if (isEject) {
+    // Same validation as --eject
+    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. Nothing to eject.');
+      process.exit(1);
+    }
+
+    const { runEjectDiffReport } = require('../lib/diff-generator');
+    const { collectEjectInventory } = require('../lib/eject-generator');
+
+    const state = collectEjectInventory(cwd);
+    runEjectDiffReport(state);
+    return;
+  }
+
+  const { scan } = require('../lib/scanner');
+  const { buildInitDefaultConfig } = require('../lib/init-wizard');
+  const { runInitDiffReport, runUpgradeDiffReport } = require('../lib/diff-generator');
+
+  if (isInit) {
+    // Same validation as --init
+    if (fs.existsSync(path.join(cwd, 'ai-specs'))) {
+      console.error('Error: ai-specs/ directory already exists.');
+      console.error('SDD DevFlow appears to already be installed. Use --upgrade --diff instead.');
+      process.exit(1);
+    }
+
+    const scanResult = scan(cwd);
+    const config = buildInitDefaultConfig(scanResult);
+    runInitDiffReport(config);
+    return;
+  }
+
+  if (isUpgrade) {
+    // Same validation as --upgrade
+    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 --diff instead.');
+      process.exit(1);
+    }
+
+    const {
+      readInstalledVersion,
+      getPackageVersion,
+      detectAiTools,
+      detectProjectType,
+      readAutonomyLevel,
+      collectCustomAgents,
+      collectCustomCommands,
+    } = require('../lib/upgrade-generator');
+
+    const installedVersion = readInstalledVersion(cwd);
+    const packageVersion = getPackageVersion();
+
+    if (installedVersion === packageVersion && !isForce) {
+      console.log(`\nSDD DevFlow is already at version ${packageVersion}.`);
+      console.log('Use --force --diff to preview a re-install.\n');
+      return;
+    }
+
+    const scanResult = scan(cwd);
+    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'));
+
+    const config = buildInitDefaultConfig(scanResult);
+    config.aiTools = aiTools;
+    config.projectType = projectType;
+    config.autonomyLevel = autonomy.level;
+    config.autonomyName = autonomy.name;
+    config.installedVersion = installedVersion;
+
+    const state = {
+      installedVersion,
+      packageVersion,
+      aiTools,
+      projectType,
+      customAgents,
+      customCommands,
+      settingsLocal,
+    };
+
+    runUpgradeDiffReport(config, state);
+  }
+}
+
 main().catch((err) => {
   console.error('\nError:', err.message);
   process.exit(1);

package/lib/diff-generator.js

@@ -0,0 +1,287 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  FRONTEND_AGENTS,
+  BACKEND_AGENTS,
+  TEMPLATE_AGENTS,
+} = require('./config');
+const {
+  adaptBaseStandards,
+  adaptBackendStandards,
+  adaptFrontendStandards,
+} = require('./init-generator');
+const {
+  isStandardModified,
+  getPackageVersion,
+} = require('./upgrade-generator');
+const { formatScanSummary } = require('./init-wizard');
+
+const templateDir = path.join(__dirname, '..', 'template');
+
+/**
+ * Count files recursively in a directory.
+ */
+function countFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Compute how many agents would be kept after project-type filtering.
+ */
+function countAgents(projectType) {
+  const all = TEMPLATE_AGENTS.length; // 9
+  if (projectType === 'backend') return all - FRONTEND_AGENTS.length;
+  if (projectType === 'frontend') return all - BACKEND_AGENTS.length;
+  return all;
+}
+
+/**
+ * Compute how many standards would be created for a project type.
+ * base + documentation + backend (if not frontend) + frontend (if not backend)
+ */
+function countStandards(projectType) {
+  let count = 2; // base + documentation
+  if (projectType !== 'frontend') count++; // backend
+  if (projectType !== 'backend') count++; // frontend
+  return count;
+}
+
+// ── Init Diff ────────────────────────────────────────────────
+
+function runInitDiffReport(config) {
+  const dest = config.projectDir;
+  const scan = config.scanResult;
+  const projectType = config.projectType;
+  const aiTools = config.aiTools;
+
+  const lines = [];
+  lines.push('\n🔍 SDD DevFlow — Preview (--init)\n');
+
+  // Detected stack
+  lines.push('  Detected stack:');
+  lines.push(formatScanSummary(scan));
+  lines.push('');
+
+  // Compute what would be created
+  const wouldCreate = [];
+
+  // AI tool directories
+  const agentCount = countAgents(projectType);
+  const removedAgents = TEMPLATE_AGENTS.length - agentCount;
+
+  if (aiTools !== 'gemini') {
+    const claudeSkills = countFiles(path.join(templateDir, '.claude', 'skills'));
+    wouldCreate.push(`  .claude/agents/             ${agentCount} agents${removedAgents > 0 ? ` (${removedAgents} removed: ${projectType}-only)` : ''}`);
+    wouldCreate.push(`  .claude/skills/             ${claudeSkills} files (4 skills)`);
+    wouldCreate.push('  .claude/hooks/              quick-scan.sh');
+    wouldCreate.push('  .claude/settings.json');
+    wouldCreate.push('  .claude/commands/           .gitkeep');
+  }
+
+  if (aiTools !== 'claude') {
+    const geminiSkills = countFiles(path.join(templateDir, '.gemini', 'skills'));
+    const geminiCmds = countFiles(path.join(templateDir, '.gemini', 'commands'));
+    wouldCreate.push(`  .gemini/agents/             ${agentCount} agents${removedAgents > 0 ? ` (${removedAgents} removed: ${projectType}-only)` : ''}`);
+    wouldCreate.push(`  .gemini/skills/             ${geminiSkills} files (4 skills)`);
+    wouldCreate.push(`  .gemini/commands/           ${geminiCmds} commands`);
+    wouldCreate.push('  .gemini/styles/             default.md');
+    wouldCreate.push('  .gemini/settings.json');
+  }
+
+  // Standards
+  const stdCount = countStandards(projectType);
+  const stdDetails = ['base-standards'];
+  if (projectType !== 'frontend') stdDetails.push('backend-standards');
+  if (projectType !== 'backend') stdDetails.push('frontend-standards');
+  stdDetails.push('documentation-standards');
+  wouldCreate.push(`  ai-specs/specs/             ${stdCount} standards (${stdDetails.join(', ')})`);
+
+  // Docs
+  wouldCreate.push('  docs/project_notes/         4 files (bugs, decisions, key_facts, product-tracker)');
+  const specFiles = [];
+  if (projectType !== 'frontend') specFiles.push('api-spec.yaml');
+  if (projectType !== 'backend') specFiles.push('ui-components.md');
+  if (specFiles.length > 0) {
+    wouldCreate.push(`  docs/specs/                 ${specFiles.join(', ')}`);
+  }
+  wouldCreate.push('  docs/tickets/               .gitkeep');
+
+  // Top-level files
+  wouldCreate.push('  AGENTS.md');
+  if (aiTools !== 'gemini') wouldCreate.push('  CLAUDE.md');
+  if (aiTools !== 'claude') wouldCreate.push('  GEMINI.md');
+  wouldCreate.push('  .env.example');
+  wouldCreate.push('  .github/workflows/ci.yml');
+  wouldCreate.push('  .sdd-version');
+
+  lines.push(`  Would create (${wouldCreate.length} items):`);
+  for (const item of wouldCreate) {
+    lines.push(`    + ${item.trim()}`);
+  }
+
+  // .gitignore handling
+  const gitignorePath = path.join(dest, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    lines.push('\n  Would modify:');
+    lines.push('    ~ .gitignore                append SDD entries');
+  } else {
+    lines.push('\n  Would create:');
+    lines.push('    + .gitignore                with SDD entries');
+  }
+
+  lines.push('\n  No files deleted. Run without --diff to apply.\n');
+
+  console.log(lines.join('\n'));
+}
+
+// ── Upgrade Diff ─────────────────────────────────────────────
+
+function runUpgradeDiffReport(config, state) {
+  const dest = config.projectDir;
+  const scan = config.scanResult;
+  const projectType = config.projectType;
+  const aiTools = config.aiTools;
+
+  const lines = [];
+  lines.push('\n🔍 SDD DevFlow — Preview (--upgrade)\n');
+  lines.push(`  ${state.installedVersion} → ${state.packageVersion}\n`);
+
+  // Would replace
+  const replaceItems = [];
+
+  if (aiTools !== 'gemini') {
+    const agentCount = countAgents(projectType);
+    replaceItems.push(`.claude/agents/             ${agentCount} agents`);
+    replaceItems.push('.claude/skills/             4 skills');
+    replaceItems.push('.claude/hooks/              quick-scan.sh');
+    replaceItems.push('.claude/settings.json       hooks updated, permissions preserved');
+  }
+  if (aiTools !== 'claude') {
+    const agentCount = countAgents(projectType);
+    replaceItems.push(`.gemini/agents/             ${agentCount} agents`);
+    replaceItems.push('.gemini/skills/             4 skills');
+    replaceItems.push('.gemini/commands/           TOML commands');
+    replaceItems.push('.gemini/styles/             default.md');
+    replaceItems.push('.gemini/settings.json');
+  }
+  replaceItems.push('AGENTS.md');
+  if (aiTools !== 'gemini') replaceItems.push('CLAUDE.md');
+  if (aiTools !== 'claude') replaceItems.push('GEMINI.md');
+  replaceItems.push('.env.example                custom vars preserved');
+  replaceItems.push('.sdd-version');
+
+  lines.push(`  Would replace (${replaceItems.length} items):`);
+  for (const item of replaceItems) {
+    lines.push(`    ✓ ${item}`);
+  }
+
+  // Would preserve
+  const preserveItems = [];
+  if (state.settingsLocal) preserveItems.push('.claude/settings.local.json   personal settings');
+  for (const c of state.customCommands) preserveItems.push(`${c.relativePath}   custom command`);
+  for (const a of state.customAgents) preserveItems.push(`${a.relativePath}   custom agent`);
+  preserveItems.push('docs/project_notes/*          project memory');
+  preserveItems.push('docs/specs/*                  your specs');
+  preserveItems.push('docs/tickets/*                your tickets');
+  preserveItems.push('.gitignore');
+
+  lines.push(`\n  Would preserve (${preserveItems.length} items):`);
+  for (const item of preserveItems) {
+    lines.push(`    ⊘ ${item}`);
+  }
+
+  // Standards diff
+  const standardsStatus = [];
+
+  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);
+    standardsStatus.push({
+      name: 'base-standards.mdc',
+      modified: isStandardModified(existing, fresh),
+    });
+  }
+
+  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);
+      standardsStatus.push({
+        name: 'backend-standards.mdc',
+        modified: isStandardModified(existing, fresh),
+      });
+    }
+  }
+
+  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);
+      standardsStatus.push({
+        name: 'frontend-standards.mdc',
+        modified: isStandardModified(existing, fresh),
+      });
+    }
+  }
+
+  standardsStatus.push({ name: 'documentation-standards.mdc', modified: false });
+
+  lines.push('\n  Standards:');
+  for (const s of standardsStatus) {
+    if (s.modified) {
+      lines.push(`    ⚠ ${s.name}  customized → preserve`);
+    } else {
+      lines.push(`    ✓ ${s.name}  unchanged → update`);
+    }
+  }
+
+  // Would add (new files)
+  const addItems = [];
+  const ciPath = path.join(dest, '.github', 'workflows', 'ci.yml');
+  if (!fs.existsSync(ciPath)) {
+    addItems.push('.github/workflows/ci.yml');
+  }
+
+  if (addItems.length > 0) {
+    lines.push(`\n  Would add (${addItems.length} new):`);
+    for (const item of addItems) {
+      lines.push(`    + ${item}`);
+    }
+  }
+
+  lines.push('\n  Run without --diff to apply.\n');
+
+  console.log(lines.join('\n'));
+}
+
+// ── Eject Diff ──────────────────────────────────────────────
+
+function runEjectDiffReport(state) {
+  const { buildEjectSummary } = require('./eject-generator');
+
+  const lines = [];
+  lines.push('\n🔍 SDD DevFlow — Preview (--eject)\n');
+  lines.push(buildEjectSummary(state).split('\n').slice(1).join('\n')); // skip the emoji header (already have our own)
+  lines.push('\n  No files removed. Run without --diff to apply.\n');
+
+  console.log(lines.join('\n'));
+}
+
+module.exports = { runInitDiffReport, runUpgradeDiffReport, runEjectDiffReport };

package/lib/eject-generator.js

@@ -0,0 +1,352 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { TEMPLATE_AGENTS } = require('./config');
+const {
+  readInstalledVersion,
+  detectAiTools,
+  detectProjectType,
+  collectCustomAgents,
+  collectCustomCommands,
+} = require('./upgrade-generator');
+
+/**
+ * Collect inventory of what eject would remove vs preserve.
+ */
+function collectEjectInventory(cwd) {
+  const installedVersion = readInstalledVersion(cwd);
+  const aiTools = detectAiTools(cwd);
+  const projectType = detectProjectType(cwd);
+  const customAgents = collectCustomAgents(cwd);
+  const customCommands = collectCustomCommands(cwd);
+
+  const hasSettingsLocal = fs.existsSync(path.join(cwd, '.claude', 'settings.local.json'));
+  const hasDocsDir = fs.existsSync(path.join(cwd, 'docs'));
+
+  // Detect SDD-generated CI workflow
+  let ciIsSddGenerated = false;
+  const ciPath = path.join(cwd, '.github', 'workflows', 'ci.yml');
+  if (fs.existsSync(ciPath)) {
+    const ciContent = fs.readFileSync(ciPath, 'utf8');
+    ciIsSddGenerated = ciContent.includes('Generated by SDD DevFlow');
+  }
+
+  // Detect SDD entries in .gitignore
+  let gitignoreHasSddEntries = false;
+  const gitignorePath = path.join(cwd, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    gitignoreHasSddEntries = content.includes('# SDD DevFlow');
+  }
+
+  return {
+    installedVersion,
+    aiTools,
+    projectType,
+    customAgents,
+    customCommands,
+    hasSettingsLocal,
+    hasDocsDir,
+    ciPath: fs.existsSync(ciPath) ? ciPath : null,
+    ciIsSddGenerated,
+    gitignoreHasSddEntries,
+  };
+}
+
+/**
+ * Build the eject summary for display.
+ */
+function buildEjectSummary(state) {
+  const lines = [];
+  lines.push('🗑️  SDD DevFlow Eject\n');
+  lines.push(`  Installed version:  ${state.installedVersion}`);
+  lines.push(`  AI tools:           ${state.aiTools === 'both' ? 'Claude Code + Gemini' : state.aiTools === 'claude' ? 'Claude Code' : 'Gemini'}`);
+  lines.push(`  Project type:       ${state.projectType}\n`);
+
+  // Will remove
+  lines.push('  Will remove:');
+  if (state.aiTools !== 'gemini') {
+    lines.push('    ✗ .claude/agents/           template agents');
+    lines.push('    ✗ .claude/skills/');
+    lines.push('    ✗ .claude/hooks/');
+    lines.push('    ✗ .claude/settings.json');
+  }
+  if (state.aiTools !== 'claude') {
+    lines.push('    ✗ .gemini/                  entire directory');
+  }
+  lines.push('    ✗ ai-specs/                 standards');
+  lines.push('    ✗ AGENTS.md');
+  if (state.aiTools !== 'gemini') lines.push('    ✗ CLAUDE.md');
+  if (state.aiTools !== 'claude') lines.push('    ✗ GEMINI.md');
+  lines.push('    ✗ .env.example');
+  lines.push('    ✗ .sdd-version');
+  if (state.ciIsSddGenerated) {
+    lines.push('    ✗ .github/workflows/ci.yml  (SDD-generated)');
+  }
+
+  // Will preserve
+  const preserveItems = [];
+  if (state.customAgents.length > 0) {
+    for (const a of state.customAgents) {
+      preserveItems.push(`${a.relativePath}  (custom agent)`);
+    }
+  }
+  if (state.customCommands.length > 0) {
+    for (const c of state.customCommands) {
+      preserveItems.push(`${c.relativePath}  (custom command)`);
+    }
+  }
+  if (state.hasSettingsLocal) {
+    preserveItems.push('.claude/settings.local.json  (personal settings)');
+  }
+  if (state.hasDocsDir) {
+    preserveItems.push('docs/                        (project notes, specs, tickets)');
+  }
+  if (state.ciPath && !state.ciIsSddGenerated) {
+    preserveItems.push('.github/workflows/ci.yml     (customized — not SDD-generated)');
+  }
+
+  if (preserveItems.length > 0) {
+    lines.push('\n  Will preserve:');
+    for (const item of preserveItems) {
+      lines.push(`    ⊘ ${item}`);
+    }
+  }
+
+  // Will modify
+  if (state.gitignoreHasSddEntries) {
+    lines.push('\n  Will modify:');
+    lines.push('    ~ .gitignore                remove SDD DevFlow section');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Execute the eject: remove all SDD-owned files, preserve user work.
+ */
+function generateEject(cwd) {
+  const state = collectEjectInventory(cwd);
+  let removed = 0;
+  let preserved = 0;
+
+  console.log(`\nEjecting SDD DevFlow from ${path.basename(cwd)}...\n`);
+
+  // --- 1. Remove template agents (preserve custom) ---
+  for (const toolDir of ['.claude', '.gemini']) {
+    const agentsDir = path.join(cwd, toolDir, 'agents');
+    if (!fs.existsSync(agentsDir)) continue;
+
+    const files = fs.readdirSync(agentsDir);
+    for (const file of files) {
+      if (TEMPLATE_AGENTS.includes(file)) {
+        fs.unlinkSync(path.join(agentsDir, file));
+        removed++;
+      }
+    }
+
+    // Remove agents dir if empty
+    if (fs.existsSync(agentsDir) && fs.readdirSync(agentsDir).length === 0) {
+      fs.rmSync(agentsDir, { recursive: true });
+    }
+  }
+  step('Removed template agents');
+
+  // --- 2. Remove skills ---
+  for (const toolDir of ['.claude', '.gemini']) {
+    const skillsDir = path.join(cwd, toolDir, 'skills');
+    if (fs.existsSync(skillsDir)) {
+      removed += countFilesRecursive(skillsDir);
+      fs.rmSync(skillsDir, { recursive: true });
+    }
+  }
+  step('Removed skills');
+
+  // --- 3. Remove hooks ---
+  const hooksDir = path.join(cwd, '.claude', 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    removed += countFilesRecursive(hooksDir);
+    fs.rmSync(hooksDir, { recursive: true });
+  }
+  step('Removed hooks');
+
+  // --- 4. Handle commands ---
+  // .claude/commands: only remove .gitkeep, keep custom commands
+  const claudeCommandsDir = path.join(cwd, '.claude', 'commands');
+  if (fs.existsSync(claudeCommandsDir)) {
+    const gitkeepPath = path.join(claudeCommandsDir, '.gitkeep');
+    if (fs.existsSync(gitkeepPath)) {
+      fs.unlinkSync(gitkeepPath);
+      removed++;
+    }
+    // Remove dir if empty
+    if (fs.readdirSync(claudeCommandsDir).length === 0) {
+      fs.rmSync(claudeCommandsDir, { recursive: true });
+    }
+  }
+
+  // .gemini/commands: remove entirely (SDD-owned TOML commands)
+  const geminiCommandsDir = path.join(cwd, '.gemini', 'commands');
+  if (fs.existsSync(geminiCommandsDir)) {
+    removed += countFilesRecursive(geminiCommandsDir);
+    fs.rmSync(geminiCommandsDir, { recursive: true });
+  }
+
+  // --- 5. Handle .claude/settings.json ---
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      delete settings.hooks;
+
+      // If nothing meaningful remains, delete the file
+      const remainingKeys = Object.keys(settings);
+      if (remainingKeys.length === 0) {
+        fs.unlinkSync(settingsPath);
+        removed++;
+      } else {
+        // Keep permissions and other user settings
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+        preserved++;
+      }
+    } catch {
+      // Corrupted JSON — remove it
+      fs.unlinkSync(settingsPath);
+      removed++;
+    }
+  }
+  step('Handled settings.json');
+
+  // --- 6. Remove .gemini/ entirely (styles, settings) ---
+  // styles
+  const geminiStylesDir = path.join(cwd, '.gemini', 'styles');
+  if (fs.existsSync(geminiStylesDir)) {
+    removed += countFilesRecursive(geminiStylesDir);
+    fs.rmSync(geminiStylesDir, { recursive: true });
+  }
+  // settings.json
+  const geminiSettingsPath = path.join(cwd, '.gemini', 'settings.json');
+  if (fs.existsSync(geminiSettingsPath)) {
+    fs.unlinkSync(geminiSettingsPath);
+    removed++;
+  }
+
+  // --- 7. Remove ai-specs/ entirely ---
+  const aiSpecsDir = path.join(cwd, 'ai-specs');
+  if (fs.existsSync(aiSpecsDir)) {
+    removed += countFilesRecursive(aiSpecsDir);
+    fs.rmSync(aiSpecsDir, { recursive: true });
+  }
+  step('Removed ai-specs/');
+
+  // --- 8. Remove top-level SDD files ---
+  const topLevelFiles = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.env.example', '.sdd-version'];
+  for (const file of topLevelFiles) {
+    const filePath = path.join(cwd, file);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      removed++;
+    }
+  }
+  step('Removed AGENTS.md, CLAUDE.md, GEMINI.md, .env.example, .sdd-version');
+
+  // --- 9. Handle CI workflow ---
+  if (state.ciIsSddGenerated) {
+    fs.unlinkSync(state.ciPath);
+    removed++;
+    step('Removed .github/workflows/ci.yml (SDD-generated)');
+
+    // Clean empty dirs
+    const workflowsDir = path.join(cwd, '.github', 'workflows');
+    if (fs.existsSync(workflowsDir) && fs.readdirSync(workflowsDir).length === 0) {
+      fs.rmSync(workflowsDir, { recursive: true });
+    }
+    const githubDir = path.join(cwd, '.github');
+    if (fs.existsSync(githubDir) && fs.readdirSync(githubDir).length === 0) {
+      fs.rmSync(githubDir, { recursive: true });
+    }
+  } else if (state.ciPath) {
+    preserved++;
+    step('Preserved .github/workflows/ci.yml (customized)');
+  }
+
+  // --- 10. Clean .gitignore ---
+  if (state.gitignoreHasSddEntries) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    let content = fs.readFileSync(gitignorePath, 'utf8');
+    // Remove the SDD DevFlow section (tolerant of leading/trailing newlines)
+    content = content.replace(/\n?# SDD DevFlow\ndocs\/tickets\/\*\.md\n!docs\/tickets\/\.gitkeep\n?/, '');
+    fs.writeFileSync(gitignorePath, content, 'utf8');
+    step('Cleaned .gitignore');
+  }
+
+  // --- 11. Clean empty parent directories ---
+  for (const dir of ['.claude', '.gemini']) {
+    const dirPath = path.join(cwd, dir);
+    if (fs.existsSync(dirPath)) {
+      cleanEmptyDirs(dirPath);
+    }
+  }
+
+  // Count preserved items
+  preserved += state.customAgents.length + state.customCommands.length;
+  if (state.hasSettingsLocal) preserved++;
+  if (state.hasDocsDir) preserved++;
+
+  // --- Show result ---
+  console.log(`\n✅ SDD DevFlow ejected (was v${state.installedVersion})\n`);
+  console.log(`  Removed: ${removed} SDD files`);
+  if (preserved > 0) {
+    const items = [];
+    if (state.customAgents.length > 0) items.push(`${state.customAgents.length} custom agent(s)`);
+    if (state.customCommands.length > 0) items.push(`${state.customCommands.length} custom command(s)`);
+    if (state.hasSettingsLocal) items.push('personal settings');
+    if (state.hasDocsDir) items.push('docs/');
+    if (state.ciPath && !state.ciIsSddGenerated) items.push('CI workflow (customized)');
+    console.log(`  Preserved: ${items.join(', ')}`);
+  }
+  console.log('\n  To re-install later: npx create-sdd-project --init\n');
+}
+
+function step(msg) {
+  console.log(`  ✓ ${msg}`);
+}
+
+function countFilesRecursive(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFilesRecursive(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Remove a directory if empty, then check parent recursively.
+ */
+function cleanEmptyDirs(dirPath) {
+  if (!fs.existsSync(dirPath)) return;
+
+  // First clean subdirectories
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      cleanEmptyDirs(path.join(dirPath, entry.name));
+    }
+  }
+
+  // Then remove if empty
+  if (fs.existsSync(dirPath) && fs.readdirSync(dirPath).length === 0) {
+    fs.rmSync(dirPath, { recursive: true });
+  }
+}
+
+module.exports = {
+  collectEjectInventory,
+  buildEjectSummary,
+  generateEject,
+};

package/lib/init-wizard.js

@@ -283,4 +283,4 @@ function buildInitDefaultConfig(scanResult) {
   return config;
 }
 
-module.exports = { runInitWizard, buildInitDefaultConfig };
+module.exports = { runInitWizard, buildInitDefaultConfig, formatScanSummary };

package/lib/upgrade-generator.js

@@ -512,5 +512,6 @@ module.exports = {
   readAutonomyLevel,
   collectCustomAgents,
   collectCustomCommands,
+  isStandardModified,
   buildSummary,
 };

package/package.json

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