ai-development-framework 0.1.0 → 0.1.1

package/cli/init.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const readline = require('readline');
+const { PROTECTED_FILES, PROTECTED_DIRS, CUSTOMIZABLE_FILES, toProjectRelative } = require('./protected-files');
 
 const REPO = 'cristian-robert/AIDevelopmentFramework';
 const BRANCH = 'main';
@@ -18,66 +19,193 @@ function ask(question) {
   });
 }
 
-function copyDirRecursive(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-  var entries = fs.readdirSync(src, { withFileTypes: true });
-  for (var i = 0; i < entries.length; i++) {
-    var entry = entries[i];
-    var srcPath = path.join(src, entry.name);
-    var destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDirRecursive(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
+function copyFileSimple(srcPath, destPath) {
+  var destDir = path.dirname(destPath);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
   }
+  fs.copyFileSync(srcPath, destPath);
 }
 
-function downloadFramework(targetDir) {
-  var tmpDir = path.join(require('os').tmpdir(), 'ai-framework-' + Date.now());
-  fs.mkdirSync(tmpDir, { recursive: true });
-
+function downloadAndExtract(tmpDir) {
   console.log('Downloading latest framework from GitHub...');
-
   try {
-    // Download and extract tarball
     execFileSync('curl', ['-sL', TARBALL_URL, '-o', path.join(tmpDir, 'framework.tar.gz')]);
     execFileSync('tar', ['-xzf', path.join(tmpDir, 'framework.tar.gz'), '-C', tmpDir, '--strip-components=1']);
+    return true;
+  } catch (err) {
+    console.error('Download failed: ' + err.message);
+    return false;
+  }
+}
 
-    // Copy .claude/ folder
-    var sourceClaudeDir = path.join(tmpDir, '.claude');
-    var targetClaudeDir = path.join(targetDir, '.claude');
+function getLocalFallbackDir() {
+  var frameworkDir = path.join(__dirname, '..');
+  if (fs.existsSync(path.join(frameworkDir, '.claude'))) {
+    return frameworkDir;
+  }
+  return null;
+}
 
-    if (fs.existsSync(sourceClaudeDir)) {
-      console.log('Installing .claude/ framework structure...');
-      copyDirRecursive(sourceClaudeDir, targetClaudeDir);
+function isTemplateContent(filePath) {
+  try {
+    var content = fs.readFileSync(filePath, 'utf-8');
+    if (content.includes('> Populated by /create-rules')) return true;
+    if (content.includes('> Populated when /create-rules')) return true;
+    if (content.includes('> No decisions recorded yet')) return true;
+    if (content.includes('Run `/create-rules` to populate')) return true;
+    if (content.includes('> This section is populated as the project grows')) return true;
+    return false;
+  } catch (e) {
+    return false;
+  }
+}
+
+function cleanupTmpDir(tmpDir) {
+  try {
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  } catch (e) {
+    // Best-effort cleanup
+  }
+}
+
+// Collect all files from source, compute project-root-relative paths, classify them
+function collectSourceFiles(sourceDir, projectRoot) {
+  var files = [];
+
+  function walk(dir) {
+    var entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (var i = 0; i < entries.length; i++) {
+      var entry = entries[i];
+      var srcPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(srcPath);
+      } else {
+        // Compute the project-root-relative path this file WOULD have
+        var relFromSource = path.relative(sourceDir, srcPath).split(path.sep).join('/');
+        files.push({ srcPath: srcPath, relPath: relFromSource });
+      }
     }
+  }
 
-    // Copy docs/ folder
-    var sourceDocsDir = path.join(tmpDir, 'docs');
-    var targetDocsDir = path.join(targetDir, 'docs');
+  walk(sourceDir);
+  return files;
+}
+
+function detectConflicts(sourceDir, targetDir, projectRoot) {
+  var conflicts = { protected: [], customized: [], safe: [] };
+  var files = collectSourceFiles(sourceDir, projectRoot);
+
+  for (var i = 0; i < files.length; i++) {
+    var relPath = files[i].relPath;
+    var srcPath = files[i].srcPath;
+    var destPath = path.join(targetDir, relPath);
 
-    if (fs.existsSync(sourceDocsDir)) {
-      console.log('Installing docs/...');
-      copyDirRecursive(sourceDocsDir, targetDocsDir);
+    // Compute project-root-relative path for matching against protection lists
+    var projectRelPath = toProjectRelative(destPath, projectRoot);
+
+    if (!fs.existsSync(destPath)) {
+      conflicts.safe.push(relPath);
+    } else if (PROTECTED_FILES.indexOf(projectRelPath) !== -1) {
+      if (!isTemplateContent(destPath)) {
+        conflicts.protected.push(relPath);
+      } else {
+        conflicts.safe.push(relPath);
+      }
+    } else if (CUSTOMIZABLE_FILES.indexOf(projectRelPath) !== -1) {
+      var srcContent = fs.readFileSync(srcPath, 'utf-8');
+      var destContent = fs.readFileSync(destPath, 'utf-8');
+      if (srcContent !== destContent) {
+        conflicts.customized.push(relPath);
+      } else {
+        conflicts.safe.push(relPath);
+      }
+    } else {
+      conflicts.safe.push(relPath);
     }
+  }
 
-    return true;
-  } catch (err) {
-    console.error('Download failed: ' + err.message);
-    console.log('');
-    console.log('Falling back to local copy...');
-    return false;
-  } finally {
-    // Cleanup tmp
-    try {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    } catch (e) {
-      // ignore cleanup errors
+  return conflicts;
+}
+
+function smartCopy(sourceDir, targetDir, projectRoot, strategy, customizedAction) {
+  var stats = { created: 0, updated: 0, skipped: 0, backedUp: 0 };
+
+  function copy(src, dest) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    var entries = fs.readdirSync(src, { withFileTypes: true });
+    for (var i = 0; i < entries.length; i++) {
+      var entry = entries[i];
+      var srcPath = path.join(src, entry.name);
+      var destPath = path.join(dest, entry.name);
+      var projectRelPath = toProjectRelative(destPath, projectRoot);
+
+      if (entry.isDirectory()) {
+        if (strategy === 'smart') {
+          var isProtectedDir = PROTECTED_DIRS.some(function (d) {
+            return projectRelPath === d || projectRelPath.startsWith(d + '/');
+          });
+          if (isProtectedDir && fs.existsSync(destPath)) {
+            // Count actual files in the directory for accurate reporting
+            try {
+              var dirFiles = fs.readdirSync(destPath, { recursive: true });
+              stats.skipped += dirFiles.length || 1;
+            } catch (e) {
+              stats.skipped++;
+            }
+            continue;
+          }
+        }
+        copy(srcPath, destPath);
+      } else {
+        var destExists = fs.existsSync(destPath);
+
+        if (strategy === 'smart' && destExists) {
+          // Protected file with real content — never overwrite
+          if (PROTECTED_FILES.indexOf(projectRelPath) !== -1 && !isTemplateContent(destPath)) {
+            stats.skipped++;
+            continue;
+          }
+
+          // Customized file — apply user's chosen action
+          if (CUSTOMIZABLE_FILES.indexOf(projectRelPath) !== -1) {
+            var srcContent = fs.readFileSync(srcPath, 'utf-8');
+            var destContent = fs.readFileSync(destPath, 'utf-8');
+            if (srcContent !== destContent) {
+              if (customizedAction === 'keep') {
+                stats.skipped++;
+                continue;
+              } else if (customizedAction === 'backup') {
+                // Use timestamped backup name to avoid overwriting previous backups
+                var timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+                var backupPath = destPath + '.' + timestamp + '.backup';
+                fs.copyFileSync(destPath, backupPath);
+                fs.copyFileSync(srcPath, destPath);
+                stats.backedUp++;
+                stats.updated++;
+                continue;
+              }
+              // 'overwrite' falls through to normal copy
+            }
+          }
+        }
+
+        fs.copyFileSync(srcPath, destPath);
+        if (destExists) {
+          stats.updated++;
+        } else {
+          stats.created++;
+        }
+      }
     }
   }
+
+  copy(sourceDir, targetDir);
+  return stats;
 }
 
 function detectTechStack() {
@@ -115,7 +243,7 @@ function detectTechStack() {
       if (reqContent.includes('django')) detected.push('Django');
       if (reqContent.includes('flask')) detected.push('Flask');
     } catch (e) {
-      // ignore read errors
+      // ignore
     }
   }
   if (fs.existsSync('go.mod')) detected.push('Go');
@@ -133,45 +261,143 @@ async function main() {
   var targetDir = process.cwd();
   var hasGit = fs.existsSync('.git');
   var hasClaudeDir = fs.existsSync('.claude');
-
-  // Check if .claude/ already exists
-  if (hasClaudeDir) {
-    var overwrite = await ask('.claude/ already exists. Overwrite? (yes/no): ');
-    if (overwrite.toLowerCase() !== 'yes' && overwrite.toLowerCase() !== 'y') {
-      console.log('Aborted. Use "npx ai-framework update" to update existing installation.');
-      rl.close();
-      return;
-    }
-  }
+  var hasCLAUDEmd = fs.existsSync('CLAUDE.md');
 
   // Detect tech stack
   var stack = detectTechStack();
   if (stack.length > 0) {
-    console.log('Detected tech stack: ' + stack.join(', '));
+    console.log('  Detected tech stack: ' + stack.join(', '));
+    console.log('');
   }
 
-  // Download from GitHub (latest version)
-  var downloaded = downloadFramework(targetDir);
-
-  // Fall back to local copy if download fails (when installed via npm)
-  if (!downloaded) {
-    var frameworkDir = path.join(__dirname, '..');
-    var localClaudeDir = path.join(frameworkDir, '.claude');
-    if (fs.existsSync(localClaudeDir)) {
-      console.log('Copying from local package...');
-      copyDirRecursive(localClaudeDir, path.join(targetDir, '.claude'));
+  // Download framework to temp dir
+  var tmpDir = path.join(require('os').tmpdir(), 'ai-framework-' + Date.now());
+  fs.mkdirSync(tmpDir, { recursive: true });
 
-      var localDocsDir = path.join(frameworkDir, 'docs');
-      if (fs.existsSync(localDocsDir)) {
-        copyDirRecursive(localDocsDir, path.join(targetDir, 'docs'));
-      }
+  var sourceDir = null;
+  var downloaded = downloadAndExtract(tmpDir);
+  if (downloaded) {
+    sourceDir = tmpDir;
+  } else {
+    var fallback = getLocalFallbackDir();
+    if (fallback) {
+      console.log('Using local package as fallback...');
+      sourceDir = fallback;
     } else {
-      console.error('No local framework files found. Please check your installation.');
+      console.error('No framework source available. Check your internet connection.');
+      cleanupTmpDir(tmpDir);
       rl.close();
       process.exit(1);
     }
   }
 
+  var strategy = 'fresh';
+  var customizedAction = 'overwrite';
+
+  if (hasClaudeDir || hasCLAUDEmd) {
+    console.log('Existing configuration detected. Scanning for conflicts...');
+    console.log('');
+
+    // Scan .claude/ directory for conflicts
+    var claudeConflicts = { protected: [], customized: [], safe: [] };
+    var sourceClaudeDir = path.join(sourceDir, '.claude');
+    if (fs.existsSync(sourceClaudeDir)) {
+      claudeConflicts = detectConflicts(sourceClaudeDir, path.join(targetDir, '.claude'), targetDir);
+    }
+
+    // Check CLAUDE.md separately
+    if (hasCLAUDEmd && !isTemplateContent(path.join(targetDir, 'CLAUDE.md'))) {
+      claudeConflicts.protected.push('CLAUDE.md');
+    }
+
+    if (claudeConflicts.protected.length > 0) {
+      console.log('  Project-specific files (will be preserved):');
+      for (var i = 0; i < claudeConflicts.protected.length; i++) {
+        console.log('    ' + claudeConflicts.protected[i]);
+      }
+      console.log('');
+    }
+
+    if (claudeConflicts.customized.length > 0) {
+      console.log('  Modified files (differ from framework defaults):');
+      for (var j = 0; j < claudeConflicts.customized.length; j++) {
+        console.log('    ' + claudeConflicts.customized[j]);
+      }
+      console.log('');
+
+      var choice = await ask(
+        '  How should modified files be handled?\n' +
+        '    1. Keep mine     — preserve your customizations, skip framework updates\n' +
+        '    2. Use framework — overwrite with latest framework versions\n' +
+        '    3. Backup + update — save yours as .backup, install framework versions\n' +
+        '  Choice (1/2/3): '
+      );
+
+      if (choice === '1') customizedAction = 'keep';
+      else if (choice === '2') customizedAction = 'overwrite';
+      else if (choice === '3') customizedAction = 'backup';
+      else customizedAction = 'keep'; // default to safe option
+
+      console.log('');
+    }
+
+    if (claudeConflicts.safe.length > 0) {
+      console.log('  New/unchanged files: ' + claudeConflicts.safe.length + ' (will be installed)');
+      console.log('');
+    }
+
+    strategy = 'smart';
+  }
+
+  // Install .claude/
+  console.log('Installing framework...');
+  var stats = smartCopy(
+    path.join(sourceDir, '.claude'),
+    path.join(targetDir, '.claude'),
+    targetDir,
+    strategy,
+    customizedAction
+  );
+
+  // Install CLAUDE.md from framework source (if not protected)
+  var claudeMdSource = path.join(sourceDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdSource)) {
+    var claudeMdDest = path.join(targetDir, 'CLAUDE.md');
+    if (!fs.existsSync(claudeMdDest)) {
+      copyFileSimple(claudeMdSource, claudeMdDest);
+      stats.created++;
+    } else if (strategy === 'fresh') {
+      copyFileSimple(claudeMdSource, claudeMdDest);
+      stats.updated++;
+    }
+    // In 'smart' mode, CLAUDE.md is handled by the protection logic above
+  }
+
+  // Install docs/ (methodology guides only, not project-specific plans)
+  var docsSource = path.join(sourceDir, 'docs');
+  if (fs.existsSync(docsSource)) {
+    var docsTarget = path.join(targetDir, 'docs');
+    if (!fs.existsSync(docsTarget)) {
+      fs.mkdirSync(docsTarget, { recursive: true });
+    }
+    var docsEntries = fs.readdirSync(docsSource, { withFileTypes: true });
+    for (var k = 0; k < docsEntries.length; k++) {
+      var entry = docsEntries[k];
+      if (entry.isFile()) {
+        var srcPath = path.join(docsSource, entry.name);
+        var destPath = path.join(docsTarget, entry.name);
+        var existed = fs.existsSync(destPath);
+        fs.copyFileSync(srcPath, destPath);
+        if (existed) {
+          stats.updated++;
+        } else {
+          stats.created++;
+        }
+      }
+      // Skip docs/plans/ and docs/superpowers/ — project-specific
+    }
+  }
+
   // Create docs/plans directory
   var plansDir = path.join(targetDir, 'docs', 'plans');
   if (!fs.existsSync(plansDir)) {
@@ -180,6 +406,7 @@ async function main() {
 
   // Init git if needed
   if (!hasGit) {
+    console.log('');
     var initGit = await ask('No git repo found. Initialize one? (yes/no): ');
     if (initGit.toLowerCase() === 'yes' || initGit.toLowerCase() === 'y') {
       try {
@@ -192,10 +419,17 @@ async function main() {
     }
   }
 
+  // Summary
   console.log('');
   console.log('Setup complete!');
   console.log('');
-  console.log('Installed:');
+  console.log('  Created:  ' + stats.created + ' files');
+  console.log('  Updated:  ' + stats.updated + ' files');
+  console.log('  Skipped:  ' + stats.skipped + ' files (preserved your customizations)');
+  if (stats.backedUp > 0) {
+    console.log('  Backed up: ' + stats.backedUp + ' files (saved as .backup)');
+  }
+  console.log('');
   console.log('  .claude/commands/    10 pipeline commands');
   console.log('  .claude/agents/      4 specialist agents + template');
   console.log('  .claude/skills/      2 framework skills');
@@ -210,6 +444,7 @@ async function main() {
   console.log('  3. Run /start to begin');
   console.log('');
 
+  cleanupTmpDir(tmpDir);
   rl.close();
 }
 

package/cli/protected-files.js

@@ -0,0 +1,65 @@
+// Files that contain project-specific content and should never be blindly overwritten.
+// All paths are relative to the PROJECT ROOT (not .claude/).
+var PROTECTED_FILES = [
+  // Project CLAUDE.md (user may have their own)
+  'CLAUDE.md',
+
+  // Agent knowledge bases (populated per-project by /evolve and architect-agent RECORD)
+  '.claude/agents/architect-agent/index.md',
+  '.claude/agents/architect-agent/shared/patterns.md',
+  '.claude/agents/architect-agent/decisions/log.md',
+
+  // Tester agent project-specific config
+  '.claude/agents/tester-agent/test-patterns.md',
+  '.claude/agents/tester-agent/auth-state.md',
+
+  // Mobile tester project-specific config
+  '.claude/agents/mobile-tester-agent/screen-patterns.md',
+
+  // Project-specific code patterns (generated by /create-rules)
+  '.claude/references/code-patterns.md',
+
+  // Project-specific settings and permissions
+  '.claude/settings.local.json',
+];
+
+// Directories with project-specific content (architect-agent module knowledge).
+// All paths are relative to the PROJECT ROOT.
+var PROTECTED_DIRS = [
+  '.claude/agents/architect-agent/modules',
+  '.claude/agents/architect-agent/frontend',
+];
+
+// Files that users commonly customize (rules, hooks).
+// These get special "merge" treatment — ask user what to do.
+// All paths are relative to the PROJECT ROOT.
+var CUSTOMIZABLE_FILES = [
+  '.claude/rules/_global.md',
+  '.claude/rules/backend.md',
+  '.claude/rules/frontend.md',
+  '.claude/rules/mobile.md',
+  '.claude/rules/database.md',
+  '.claude/rules/testing.md',
+  '.claude/hooks/branch-guard.sh',
+  '.claude/hooks/plan-required.sh',
+  '.claude/hooks/architect-sync.sh',
+  '.claude/hooks/evolve-reminder.sh',
+  '.claude/hooks/session-primer.sh',
+];
+
+// Helper: normalize a path to project-root-relative format.
+// Call sites that compare against these lists MUST use this function
+// to ensure the path prefix matches (e.g., '.claude/rules/backend.md').
+function toProjectRelative(filePath, rootDir) {
+  var path = require('path');
+  var abs = path.resolve(filePath);
+  var root = path.resolve(rootDir);
+  return path.relative(root, abs).split(path.sep).join('/');
+}
+
+module.exports = {
+  PROTECTED_FILES: PROTECTED_FILES,
+  PROTECTED_DIRS: PROTECTED_DIRS,
+  CUSTOMIZABLE_FILES: CUSTOMIZABLE_FILES,
+  toProjectRelative: toProjectRelative,
+};

package/cli/update.js

@@ -1,58 +1,123 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const readline = require('readline');
+const { PROTECTED_FILES, PROTECTED_DIRS, CUSTOMIZABLE_FILES, toProjectRelative } = require('./protected-files');
 
 const REPO = 'cristian-robert/AIDevelopmentFramework';
 const BRANCH = 'main';
 const TARBALL_URL = 'https://github.com/' + REPO + '/archive/refs/heads/' + BRANCH + '.tar.gz';
 
-// Files that are project-specific and should NOT be overwritten
-var PROTECTED_FILES = [
-  '.claude/agents/architect-agent/index.md',
-  '.claude/agents/architect-agent/shared/patterns.md',
-  '.claude/agents/architect-agent/decisions/log.md',
-  '.claude/agents/tester-agent/test-patterns.md',
-  '.claude/agents/tester-agent/auth-state.md',
-  '.claude/agents/mobile-tester-agent/screen-patterns.md',
-  '.claude/references/code-patterns.md',
-  '.claude/settings.local.json',
-];
-
-// Directories with project-specific content that should NOT be overwritten
-var PROTECTED_DIRS = [
-  '.claude/agents/architect-agent/modules',
-  '.claude/agents/architect-agent/frontend',
-];
-
-function copyDirRecursive(src, dest, protectedFiles, protectedDirs) {
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(question) {
+  return new Promise(function (resolve) {
+    rl.question(question, resolve);
+  });
+}
+
+function isTemplateContent(filePath) {
+  try {
+    var content = fs.readFileSync(filePath, 'utf-8');
+    if (content.includes('> Populated by /create-rules')) return true;
+    if (content.includes('> Populated when /create-rules')) return true;
+    if (content.includes('> No decisions recorded yet')) return true;
+    if (content.includes('Run `/create-rules` to populate')) return true;
+    if (content.includes('> This section is populated as the project grows')) return true;
+    return false;
+  } catch (e) {
+    return false;
+  }
+}
+
+function copyDirWithProtection(src, dest, projectRoot, customizedAction) {
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
   }
   var entries = fs.readdirSync(src, { withFileTypes: true });
+  var stats = { updated: 0, skipped: 0, backedUp: 0 };
   for (var i = 0; i < entries.length; i++) {
     var entry = entries[i];
     var srcPath = path.join(src, entry.name);
     var destPath = path.join(dest, entry.name);
-    var relativePath = path.relative(process.cwd(), destPath);
+    var projectRelPath = toProjectRelative(destPath, projectRoot);
 
     if (entry.isDirectory()) {
-      // Skip protected directories entirely
-      if (protectedDirs.some(function (d) { return relativePath.startsWith(d); })) {
+      var isProtectedDir = PROTECTED_DIRS.some(function (d) {
+        return projectRelPath === d || projectRelPath.startsWith(d + '/');
+      });
+      if (isProtectedDir && fs.existsSync(destPath)) {
+        console.log('  Skipped (project-specific): ' + projectRelPath + '/');
+        try {
+          var dirFiles = fs.readdirSync(destPath, { recursive: true });
+          stats.skipped += dirFiles.length || 1;
+        } catch (e) {
+          stats.skipped++;
+        }
         continue;
       }
-      copyDirRecursive(srcPath, destPath, protectedFiles, protectedDirs);
+      var sub = copyDirWithProtection(srcPath, destPath, projectRoot, customizedAction);
+      stats.updated += sub.updated;
+      stats.skipped += sub.skipped;
+      stats.backedUp += sub.backedUp;
     } else {
-      // Skip protected files
-      if (protectedFiles.indexOf(relativePath) !== -1) {
-        console.log('  Skipped (project-specific): ' + relativePath);
+      if (!fs.existsSync(destPath)) {
+        // New file — always install
+        var destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir)) {
+          fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(srcPath, destPath);
+        stats.updated++;
         continue;
       }
+
+      // Protected file — skip if it has real content, update if still template
+      if (PROTECTED_FILES.indexOf(projectRelPath) !== -1) {
+        if (!isTemplateContent(destPath)) {
+          console.log('  Skipped (project-specific): ' + projectRelPath);
+          stats.skipped++;
+        } else {
+          fs.copyFileSync(srcPath, destPath);
+          stats.updated++;
+        }
+        continue;
+      }
+
+      // Customizable file — apply chosen action
+      if (CUSTOMIZABLE_FILES.indexOf(projectRelPath) !== -1) {
+        var srcContent = fs.readFileSync(srcPath, 'utf-8');
+        var destContent = fs.readFileSync(destPath, 'utf-8');
+        if (srcContent !== destContent) {
+          if (customizedAction === 'keep') {
+            console.log('  Skipped (customized): ' + projectRelPath);
+            stats.skipped++;
+            continue;
+          } else if (customizedAction === 'backup') {
+            var timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            var backupPath = destPath + '.' + timestamp + '.backup';
+            fs.copyFileSync(destPath, backupPath);
+            console.log('  Backed up: ' + projectRelPath);
+            fs.copyFileSync(srcPath, destPath);
+            stats.backedUp++;
+            stats.updated++;
+            continue;
+          }
+          // 'overwrite' falls through
+        }
+      }
+
       fs.copyFileSync(srcPath, destPath);
+      stats.updated++;
     }
   }
+  return stats;
 }
 
-function main() {
+async function main() {
   console.log('');
   console.log('  AIDevelopmentFramework — Update');
   console.log('');
@@ -62,6 +127,7 @@ function main() {
     process.exit(1);
   }
 
+  var projectRoot = process.cwd();
   var tmpDir = path.join(require('os').tmpdir(), 'ai-framework-update-' + Date.now());
   fs.mkdirSync(tmpDir, { recursive: true });
 
@@ -71,40 +137,63 @@ function main() {
     execFileSync('curl', ['-sL', TARBALL_URL, '-o', path.join(tmpDir, 'framework.tar.gz')]);
     execFileSync('tar', ['-xzf', path.join(tmpDir, 'framework.tar.gz'), '-C', tmpDir, '--strip-components=1']);
 
+    // Ask about customized files
+    var customizedAction = 'keep';
+    console.log('');
+    var choice = await ask(
+      '  How should customized rules/hooks be handled?\n' +
+      '    1. Keep mine     — preserve your customizations (default)\n' +
+      '    2. Use framework — overwrite with latest framework versions\n' +
+      '    3. Backup + update — save yours as .backup, install new versions\n' +
+      '  Choice (1/2/3): '
+    );
+
+    if (choice === '2') customizedAction = 'overwrite';
+    else if (choice === '3') customizedAction = 'backup';
+
     var sourceClaudeDir = path.join(tmpDir, '.claude');
-    var targetClaudeDir = path.join(process.cwd(), '.claude');
+    var targetClaudeDir = path.join(projectRoot, '.claude');
 
     if (fs.existsSync(sourceClaudeDir)) {
-      console.log('Updating .claude/ (preserving project-specific files)...');
-      copyDirRecursive(sourceClaudeDir, targetClaudeDir, PROTECTED_FILES, PROTECTED_DIRS);
-    }
+      console.log('');
+      console.log('Updating .claude/ ...');
+      console.log('');
+      var stats = copyDirWithProtection(sourceClaudeDir, targetClaudeDir, projectRoot, customizedAction);
 
-    // Update docs (but not docs/plans/ which contains project plans)
-    var sourceDocsDir = path.join(tmpDir, 'docs');
-    var targetDocsDir = path.join(process.cwd(), 'docs');
-    if (fs.existsSync(sourceDocsDir)) {
-      console.log('Updating docs/...');
-      var docEntries = fs.readdirSync(sourceDocsDir, { withFileTypes: true });
-      for (var i = 0; i < docEntries.length; i++) {
-        var entry = docEntries[i];
-        if (entry.isFile()) {
-          fs.copyFileSync(
-            path.join(sourceDocsDir, entry.name),
-            path.join(targetDocsDir, entry.name)
-          );
+      // Update docs (but not docs/plans/ or docs/superpowers/)
+      var sourceDocsDir = path.join(tmpDir, 'docs');
+      var targetDocsDir = path.join(projectRoot, 'docs');
+      if (fs.existsSync(sourceDocsDir)) {
+        console.log('');
+        console.log('Updating docs/...');
+        if (!fs.existsSync(targetDocsDir)) {
+          fs.mkdirSync(targetDocsDir, { recursive: true });
+        }
+        var docEntries = fs.readdirSync(sourceDocsDir, { withFileTypes: true });
+        for (var i = 0; i < docEntries.length; i++) {
+          var entry = docEntries[i];
+          if (entry.isFile()) {
+            fs.copyFileSync(
+              path.join(sourceDocsDir, entry.name),
+              path.join(targetDocsDir, entry.name)
+            );
+            stats.updated++;
+          }
         }
-        // Skip docs/plans/ and docs/superpowers/ — project-specific
       }
-    }
 
-    console.log('');
-    console.log('Update complete!');
-    console.log('');
-    console.log('Updated: commands, agent protocols, rules templates, hooks, skills, docs');
-    console.log('Preserved: agent knowledge bases, test patterns, auth state, code patterns, settings, plans');
-    console.log('');
-    console.log('Run /setup to check if new plugins are required.');
-    console.log('');
+      console.log('');
+      console.log('Update complete!');
+      console.log('');
+      console.log('  Updated:   ' + stats.updated + ' files');
+      console.log('  Skipped:   ' + stats.skipped + ' files (preserved your customizations)');
+      if (stats.backedUp > 0) {
+        console.log('  Backed up: ' + stats.backedUp + ' files (saved as .backup)');
+      }
+      console.log('');
+      console.log('Run /setup to check if new plugins are required.');
+      console.log('');
+    }
   } catch (err) {
     console.error('Update failed: ' + err.message);
     process.exit(1);
@@ -112,8 +201,9 @@ function main() {
     try {
       fs.rmSync(tmpDir, { recursive: true, force: true });
     } catch (e) {
-      // ignore cleanup errors
+      // ignore
     }
+    rl.close();
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-development-framework",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The system around the AI that makes the AI reliable. Structured AI-assisted development with the PIV+E loop.",
   "bin": {
     "ai-framework": "cli/index.js"