knowzcode 0.5.2 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official KnowzCode plugin marketplace - Platform-agnostic AI development methodology",
-    "version": "0.5.2"
+    "version": "0.6.0"
   },
   "plugins": [
     {
       "name": "kc",
       "source": "./",
       "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-      "version": "0.5.2",
+      "version": "0.6.0",
       "author": {
         "name": "Alex Headscarf"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kc",
   "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "author": {
     "name": "Alex Headscarf"
   }

package/README.md

@@ -6,7 +6,7 @@
 
 [![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT_+_Commons_Clause-yellow.svg)](LICENSE)
 [![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowzcode)
-[![Version](https://img.shields.io/badge/version-0.5.2-blue)](https://github.com/knowz-io/knowzcode/releases)
+[![Version](https://img.shields.io/badge/version-0.6.0-blue)](https://github.com/knowz-io/knowzcode/releases)
 
 [Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)
 

package/bin/knowzcode.mjs

@@ -82,6 +82,7 @@ function parseArgs(argv) {
     target: process.cwd(),
     platforms: [],
     force: false,
+    clean: false,
     global: false,
     verbose: false,
     agentTeams: false,
@@ -96,6 +97,8 @@ function parseArgs(argv) {
       opts.platforms = args[++i].split(',').map((p) => p.trim().toLowerCase());
     } else if (arg === '--force') {
       opts.force = true;
+    } else if (arg === '--clean') {
+      opts.clean = true;
     } else if (arg === '--global') {
       opts.global = true;
     } else if (arg === '--agent-teams') {
@@ -619,151 +622,184 @@ function enableAgentTeams(claudeDir, isGlobal) {
   log.ok(`Agent Teams enabled in ${settingsFile}`);
 }
 
-// ─── Commands ────────────────────────────────────────────────────────────────
-
-// DETECT
-function cmdDetect(opts) {
-  const dir = opts.target;
-  console.log('');
-  console.log(`${c.bold}KnowzCode Platform Detection${c.reset}`);
-  console.log(`${c.dim}Scanning: ${dir}${c.reset}`);
-  console.log('');
-
-  const detected = detectPlatforms(dir);
-  const hasKnowzcode = existsSync(join(dir, 'knowzcode'));
-
-  console.log(`  KnowzCode framework: ${hasKnowzcode ? `${c.green}installed${c.reset}` : `${c.dim}not found${c.reset}`}`);
+// ─── Installation Scanner ────────────────────────────────────────────────────
+
+function scanExistingInstallation(kcDir, dir) {
+  const result = {
+    version: null,
+    specs: [],
+    trackerEntries: 0,
+    logEntries: 0,
+    hasArchitecture: false,
+    hasProject: false,
+    hasPreferences: false,
+    hasOrchestration: false,
+    workgroups: [],
+    installedPlatforms: [],
+    customizedFiles: [],
+  };
 
-  if (hasKnowzcode) {
-    const versionFile = join(dir, 'knowzcode', '.knowzcode-version');
-    if (existsSync(versionFile)) {
-      const ver = readFileSync(versionFile, 'utf8').trim();
-      console.log(`  Installed version:   ${c.cyan}${ver}${c.reset}`);
-    }
+  // Version
+  const versionFile = join(kcDir, '.knowzcode-version');
+  if (existsSync(versionFile)) {
+    result.version = readFileSync(versionFile, 'utf8').trim();
   }
 
-  console.log('');
-  console.log(`  ${c.bold}Platforms:${c.reset}`);
-
-  for (const [id, platform] of Object.entries(PLATFORMS)) {
-    const found = detected.includes(id);
-    const indicator = found ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
-    console.log(`    ${platform.name.padEnd(18)} ${indicator}`);
+  // Specs
+  const specsDir = join(kcDir, 'specs');
+  if (existsSync(specsDir)) {
+    result.specs = readdirSync(specsDir).filter(f => f.endsWith('.md') && f !== 'Readme.md');
   }
 
-  console.log('');
-  if (detected.length === 0) {
-    console.log(`  No platforms detected. Run ${c.cyan}npx knowzcode install${c.reset} to set up.`);
-  } else {
-    console.log(`  ${detected.length} platform(s) detected.`);
+  // Tracker entries (look for non-empty table rows — rows starting with |)
+  const trackerFile = join(kcDir, 'knowzcode_tracker.md');
+  if (existsSync(trackerFile)) {
+    const content = readFileSync(trackerFile, 'utf8');
+    const rows = content.split('\n').filter(line => /^\|[^:|\-]/.test(line) && !/^\| Status/.test(line) && line.trim() !== '| | | | | | | | | |');
+    result.trackerEntries = rows.length;
   }
-  console.log('');
-}
 
-// INSTALL
-async function cmdInstall(opts) {
-  const dir = opts.target;
-  const kcDir = join(dir, 'knowzcode');
-
-  console.log('');
-  console.log(`${c.bold}KnowzCode Install${c.reset}`);
-  console.log(`${c.dim}Target: ${dir}${c.reset}`);
-  console.log('');
-
-  // Check for existing installation
-  if (existsSync(kcDir) && !opts.force) {
-    log.warn('KnowzCode already installed at ' + kcDir);
-    log.warn('Use --force to overwrite.');
-    process.exit(1);
+  // Log entries (count --- delimited entries beyond SystemInitialization)
+  const logFile = join(kcDir, 'knowzcode_log.md');
+  if (existsSync(logFile)) {
+    const content = readFileSync(logFile, 'utf8');
+    const typeMatches = content.match(/\*\*Type:\*\*/g);
+    result.logEntries = typeMatches ? Math.max(0, typeMatches.length - 1) : 0; // -1 for SystemInitialization
   }
 
-  if (!existsSync(dir)) {
-    log.err('Target directory does not exist: ' + dir);
-    process.exit(1);
+  // Architecture — check if edited (compare size to source template)
+  const archFile = join(kcDir, 'knowzcode_architecture.md');
+  const srcArch = join(PKG_ROOT, 'knowzcode', 'knowzcode_architecture.md');
+  if (existsSync(archFile)) {
+    const installedSize = statSync(archFile).size;
+    const templateSize = existsSync(srcArch) ? statSync(srcArch).size : 0;
+    result.hasArchitecture = installedSize !== templateSize;
   }
 
-  // 1. Copy knowzcode/ template directory
-  log.info('Installing core framework...');
-  const srcKc = join(PKG_ROOT, 'knowzcode');
-  ensureDir(kcDir);
-  ensureDir(join(kcDir, 'specs'));
-  ensureDir(join(kcDir, 'workgroups'));
-  ensureDir(join(kcDir, 'prompts'));
+  // Project config
+  const projectFile = join(kcDir, 'knowzcode_project.md');
+  const srcProject = join(PKG_ROOT, 'knowzcode', 'knowzcode_project.md');
+  if (existsSync(projectFile)) {
+    const installedSize = statSync(projectFile).size;
+    const templateSize = existsSync(srcProject) ? statSync(srcProject).size : 0;
+    result.hasProject = installedSize !== templateSize;
+  }
 
-  // Create workgroups/README.md (workgroups/ is gitignored and excluded from npm)
-  writeFileSync(join(kcDir, 'workgroups', 'README.md'), '# WorkGroups\n\nSession-specific WorkGroup files are stored here.\nThis directory is gitignored — contents are local to each checkout.\n');
+  // Preferences
+  result.hasPreferences = existsSync(join(kcDir, 'user_preferences.md'));
 
-  // Copy .md files (skip tracker and log — generate fresh)
-  for (const entry of readdirSync(srcKc)) {
-    const srcPath = join(srcKc, entry);
-    const stat = statSync(srcPath);
-    if (stat.isFile() && entry.endsWith('.md') && entry !== 'knowzcode_tracker.md' && entry !== 'knowzcode_log.md') {
-      writeFileSync(join(kcDir, entry), readFileSync(srcPath));
-    } else if (stat.isFile() && !entry.endsWith('.md')) {
-      // Copy non-md files, handling gitignore.template → .gitignore rename
-      if (entry === 'gitignore.template') {
-        writeFileSync(join(kcDir, '.gitignore'), readFileSync(srcPath));
-      } else {
-        writeFileSync(join(kcDir, entry), readFileSync(srcPath));
-      }
-    }
+  // Orchestration
+  const orchFile = join(kcDir, 'knowzcode_orchestration.md');
+  const srcOrch = join(PKG_ROOT, 'knowzcode', 'knowzcode_orchestration.md');
+  if (existsSync(orchFile)) {
+    const installedSize = statSync(orchFile).size;
+    const templateSize = existsSync(srcOrch) ? statSync(srcOrch).size : 0;
+    result.hasOrchestration = installedSize !== templateSize;
   }
 
-  // Copy prompts/
-  if (existsSync(join(srcKc, 'prompts'))) {
-    copyDirContents(join(srcKc, 'prompts'), join(kcDir, 'prompts'));
+  // Workgroups
+  const wgDir = join(kcDir, 'workgroups');
+  if (existsSync(wgDir)) {
+    result.workgroups = readdirSync(wgDir).filter(f => f !== 'README.md');
   }
 
-  // Copy specs readme
-  if (existsSync(join(srcKc, 'specs', 'Readme.md'))) {
-    writeFileSync(join(kcDir, 'specs', 'Readme.md'), readFileSync(join(srcKc, 'specs', 'Readme.md')));
+  // Installed platforms
+  const adapterChecks = {
+    claude: () => existsSync(join(dir, '.claude', 'commands')) || existsSync(join(dir, '.claude', 'agents')),
+    codex: () => existsSync(join(dir, 'AGENTS.md')),
+    gemini: () => existsSync(join(dir, 'GEMINI.md')),
+    cursor: () => existsSync(join(dir, '.cursor', 'rules', 'knowzcode.mdc')),
+    copilot: () => existsSync(join(dir, '.github', 'copilot-instructions.md')),
+    windsurf: () => existsSync(join(dir, '.windsurf', 'rules', 'knowzcode.md')),
+  };
+  for (const [id, check] of Object.entries(adapterChecks)) {
+    if (check()) result.installedPlatforms.push(id);
   }
 
-  // Copy enterprise/ if exists
-  if (existsSync(join(srcKc, 'enterprise'))) {
-    copyDirContents(join(srcKc, 'enterprise'), join(kcDir, 'enterprise'));
+  // Customized files — compare framework .md files against source templates
+  const srcKc = join(PKG_ROOT, 'knowzcode');
+  const userEditable = ['knowzcode_architecture.md', 'knowzcode_project.md', 'environment_context.md', 'user_preferences.md', 'knowzcode_orchestration.md'];
+  for (const entry of userEditable) {
+    const installed = join(kcDir, entry);
+    const source = join(srcKc, entry);
+    if (existsSync(installed) && existsSync(source)) {
+      if (statSync(installed).size !== statSync(source).size) {
+        result.customizedFiles.push(entry);
+      }
+    }
   }
 
-  // Initialize fresh tracker and log
-  initTracker(join(kcDir, 'knowzcode_tracker.md'));
-  initLog(join(kcDir, 'knowzcode_log.md'));
-
-  // Write version marker
-  writeFileSync(join(kcDir, '.knowzcode-version'), VERSION + '\n');
+  return result;
+}
 
-  log.ok('Core framework installed');
+function displayInstallationSummary(scan, dir) {
+  console.log(`  ${c.bold}KnowzCode v${scan.version || 'unknown'} detected${c.reset}`);
+  console.log('');
 
-  // 2. Platform detection + selection
-  const detected = detectPlatforms(dir);
-  let selectedPlatforms;
+  // User data
+  const hasData = scan.specs.length > 0 || scan.trackerEntries > 0 || scan.logEntries > 0 ||
+    scan.hasArchitecture || scan.hasProject || scan.hasPreferences || scan.workgroups.length > 0;
 
-  if (opts.platforms.length > 0) {
-    if (opts.platforms.includes('all')) {
-      selectedPlatforms = Object.keys(PLATFORMS);
-    } else {
-      selectedPlatforms = opts.platforms.filter((p) => p in PLATFORMS);
+  if (hasData) {
+    console.log('  Your data:');
+    if (scan.specs.length > 0) {
+      const specNames = scan.specs.slice(0, 5).map(s => s.replace('.md', '')).join(', ');
+      const more = scan.specs.length > 5 ? `, +${scan.specs.length - 5} more` : '';
+      console.log(`    ${String(scan.specs.length).padStart(2)} spec(s)         (${specNames}${more})`);
     }
-  } else if (opts.force) {
-    // Non-interactive mode with --force: install for detected platforms only
-    selectedPlatforms = detected;
+    if (scan.trackerEntries > 0) console.log(`    ${String(scan.trackerEntries).padStart(2)} tracker entries`);
+    if (scan.logEntries > 0) console.log(`    ${String(scan.logEntries).padStart(2)} log entries`);
+    if (scan.hasArchitecture) console.log('    Architecture     customized');
+    if (scan.hasProject) console.log('    Project config   customized');
+    if (scan.hasPreferences) console.log('    Preferences      configured');
+    if (scan.hasOrchestration) console.log('    Orchestration    customized');
+    if (scan.workgroups.length > 0) console.log(`    ${String(scan.workgroups.length).padStart(2)} active workgroup(s)`);
   } else {
-    selectedPlatforms = await promptPlatforms(detected);
+    console.log('  Your data:      (no customizations detected)');
+  }
+
+  // Platforms
+  const detected = detectPlatforms(dir);
+  console.log('');
+  console.log('  Platforms:');
+  for (const [id, platform] of Object.entries(PLATFORMS)) {
+    const installed = scan.installedPlatforms.includes(id);
+    const det = detected.includes(id);
+    let status;
+    if (installed) status = `${c.green}installed${c.reset}`;
+    else if (det) status = `${c.yellow}detected (not installed)${c.reset}`;
+    else status = `${c.dim}not installed${c.reset}`;
+    console.log(`    ${platform.name.padEnd(18)} ${status}`);
   }
+}
+
+function isAdapterInstalled(platformId, dir) {
+  const checks = {
+    claude: () => existsSync(join(dir, '.claude', 'commands')) || existsSync(join(dir, '.claude', 'agents')),
+    codex: () => existsSync(join(dir, 'AGENTS.md')),
+    gemini: () => existsSync(join(dir, 'GEMINI.md')),
+    cursor: () => existsSync(join(dir, '.cursor', 'rules', 'knowzcode.mdc')),
+    copilot: () => existsSync(join(dir, '.github', 'copilot-instructions.md')),
+    windsurf: () => existsSync(join(dir, '.windsurf', 'rules', 'knowzcode.md')),
+  };
+  return checks[platformId] ? checks[platformId]() : false;
+}
 
-  // 3. Generate adapters
+// ─── Adapter Generation (shared helper) ──────────────────────────────────────
+
+async function generateAdapters(dir, selectedPlatforms, opts) {
   const templates = parseAdapterTemplates();
   const adapterFiles = [];
+  let agentTeamsEnabled = false;
 
   for (const platformId of selectedPlatforms) {
     const platform = PLATFORMS[platformId];
 
     if (platformId === 'claude') {
-      // Claude Code: copy agents, commands, skills
       const claudeDir = opts.global ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude') : join(dir, '.claude');
 
       log.info(`Installing Claude Code components to ${claudeDir}/`);
 
-      // Remove stale files before copying on --force
       if (opts.force) {
         removeStaleFiles(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
         removeStaleFiles(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
@@ -773,27 +809,21 @@ async function cmdInstall(opts) {
       copyDirContents(join(PKG_ROOT, 'commands'), join(claudeDir, 'commands'));
       copyDirContents(join(PKG_ROOT, 'agents'), join(claudeDir, 'agents'));
       copyDirContents(join(PKG_ROOT, 'skills'), join(claudeDir, 'skills'));
-
-      // Pre-register marketplace in settings.json
       setMarketplaceConfig(claudeDir);
-
       adapterFiles.push(claudeDir + '/commands/', claudeDir + '/agents/', claudeDir + '/skills/');
     } else {
-      // Other platforms: extract template and write adapter + additional files
       const templateSet = templates.get(platformId);
       if (!templateSet) {
         log.warn(`No adapter template found for ${platform.name} — skipping`);
         continue;
       }
 
-      // Write primary adapter file
       const adapterFile = platform.adapterPath(dir);
       ensureDir(dirname(adapterFile));
       writeFileSync(adapterFile, injectVersion(templateSet.primary));
       adapterFiles.push(adapterFile);
       log.ok(`${platform.name} adapter: ${adapterFile}`);
 
-      // Write additional files (prompts, TOMLs, skills, subagents)
       for (const [relativePath, { content }] of templateSet.files) {
         let filePath;
         if (platformId === 'codex' && opts.global && relativePath.startsWith('.agents/skills/')) {
@@ -813,7 +843,6 @@ async function cmdInstall(opts) {
         log.ok(`  + ${templateSet.files.size} additional file(s)`);
       }
 
-      // Clean up legacy .codex/skills/kc/ if present (migrated to .agents/skills/)
       if (platformId === 'codex') {
         const legacySkillDir = join(dir, '.codex', 'skills', 'kc');
         if (existsSync(legacySkillDir)) {
@@ -832,7 +861,7 @@ async function cmdInstall(opts) {
     }
   }
 
-  // 3.5. Gemini MCP config offer (when Gemini is selected and not --force)
+  // Gemini MCP config offer
   if (selectedPlatforms.includes('gemini') && !opts.global && !opts.force) {
     console.log('');
     console.log(`${c.bold}Gemini MCP Configuration${c.reset}`);
@@ -852,16 +881,14 @@ async function cmdInstall(opts) {
     }
   }
 
-  // 4. Agent Teams enablement
+  // Agent Teams
   const agentTeamsClaudeDir = opts.global
     ? join(process.env.HOME || process.env.USERPROFILE || '~', '.claude')
     : join(dir, '.claude');
-  let agentTeamsEnabled = false;
   if (opts.agentTeams) {
     enableAgentTeams(agentTeamsClaudeDir, opts.global);
     agentTeamsEnabled = true;
   } else if (selectedPlatforms.includes('claude') && !opts.force) {
-    // Interactive prompt for Claude Code users
     console.log('');
     console.log(`${c.bold}Agent Teams${c.reset} enables multi-agent coordination where specialized`);
     console.log(`teammates handle each workflow phase. ${c.dim}(experimental)${c.reset}`);
@@ -872,7 +899,193 @@ async function cmdInstall(opts) {
     }
   }
 
-  // 5. Summary
+  return { adapterFiles, agentTeamsEnabled };
+}
+
+// ─── Commands ────────────────────────────────────────────────────────────────
+
+// DETECT
+function cmdDetect(opts) {
+  const dir = opts.target;
+  console.log('');
+  console.log(`${c.bold}KnowzCode Platform Detection${c.reset}`);
+  console.log(`${c.dim}Scanning: ${dir}${c.reset}`);
+  console.log('');
+
+  const detected = detectPlatforms(dir);
+  const hasKnowzcode = existsSync(join(dir, 'knowzcode'));
+
+  console.log(`  KnowzCode framework: ${hasKnowzcode ? `${c.green}installed${c.reset}` : `${c.dim}not found${c.reset}`}`);
+
+  if (hasKnowzcode) {
+    const versionFile = join(dir, 'knowzcode', '.knowzcode-version');
+    if (existsSync(versionFile)) {
+      const ver = readFileSync(versionFile, 'utf8').trim();
+      console.log(`  Installed version:   ${c.cyan}${ver}${c.reset}`);
+    }
+  }
+
+  console.log('');
+  console.log(`  ${c.bold}Platforms:${c.reset}`);
+
+  for (const [id, platform] of Object.entries(PLATFORMS)) {
+    const found = detected.includes(id);
+    const indicator = found ? `${c.green}detected${c.reset}` : `${c.dim}not detected${c.reset}`;
+    console.log(`    ${platform.name.padEnd(18)} ${indicator}`);
+  }
+
+  console.log('');
+  if (detected.length === 0) {
+    console.log(`  No platforms detected. Run ${c.cyan}npx knowzcode install${c.reset} to set up.`);
+  } else {
+    console.log(`  ${detected.length} platform(s) detected.`);
+  }
+  console.log('');
+}
+
+// INSTALL
+async function cmdInstall(opts) {
+  const dir = opts.target;
+  const kcDir = join(dir, 'knowzcode');
+
+  console.log('');
+  console.log(`${c.bold}KnowzCode Install${c.reset}`);
+  console.log(`${c.dim}Target: ${dir}${c.reset}`);
+  console.log('');
+
+  // Check for existing installation — guided flow instead of hard exit
+  if (existsSync(kcDir) && !opts.force) {
+    const scan = scanExistingInstallation(kcDir, dir);
+    displayInstallationSummary(scan, dir);
+    console.log('');
+    console.log('  Options:');
+    console.log('  [1] Add/change platform adapters only');
+    console.log('  [2] Reinstall framework (preserves your data)');
+    console.log('  [3] Cancel');
+    console.log('');
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question('Select: ');
+    rl.close();
+
+    const choice = answer.trim();
+    if (choice === '1') return cmdAddPlatforms(opts);
+    if (choice === '2') { opts.force = true; /* fall through to install */ }
+    else return;
+  }
+
+  if (!existsSync(dir)) {
+    log.err('Target directory does not exist: ' + dir);
+    process.exit(1);
+  }
+
+  // Detect reinstall — preserve user data unless --clean
+  const isReinstall = existsSync(join(kcDir, '.knowzcode-version'));
+  const preserveFiles = isReinstall && !opts.clean ? new Set([
+    'knowzcode_tracker.md', 'knowzcode_log.md',
+    'knowzcode_architecture.md', 'knowzcode_project.md',
+    'environment_context.md', 'user_preferences.md',
+    'knowzcode_orchestration.md',
+  ]) : new Set();
+
+  // 1. Copy knowzcode/ template directory
+  log.info(isReinstall ? 'Reinstalling core framework...' : 'Installing core framework...');
+  const srcKc = join(PKG_ROOT, 'knowzcode');
+  ensureDir(kcDir);
+  ensureDir(join(kcDir, 'specs'));
+  ensureDir(join(kcDir, 'workgroups'));
+  ensureDir(join(kcDir, 'prompts'));
+
+  // Create workgroups/README.md (workgroups/ is gitignored and excluded from npm)
+  writeFileSync(join(kcDir, 'workgroups', 'README.md'), '# WorkGroups\n\nSession-specific WorkGroup files are stored here.\nThis directory is gitignored — contents are local to each checkout.\n');
+
+  // Copy .md files (skip tracker and log — generate fresh; skip preserved files on reinstall)
+  for (const entry of readdirSync(srcKc)) {
+    const srcPath = join(srcKc, entry);
+    const stat = statSync(srcPath);
+    if (stat.isFile() && entry.endsWith('.md') && entry !== 'knowzcode_tracker.md' && entry !== 'knowzcode_log.md') {
+      if (preserveFiles.has(entry) && existsSync(join(kcDir, entry))) {
+        if (opts.verbose) log.info(`Preserved: ${entry}`);
+        continue;
+      }
+      writeFileSync(join(kcDir, entry), readFileSync(srcPath));
+    } else if (stat.isFile() && !entry.endsWith('.md')) {
+      // Copy non-md files, handling gitignore.template → .gitignore rename
+      if (entry === 'gitignore.template') {
+        writeFileSync(join(kcDir, '.gitignore'), readFileSync(srcPath));
+      } else {
+        writeFileSync(join(kcDir, entry), readFileSync(srcPath));
+      }
+    }
+  }
+
+  // Copy prompts/
+  if (existsSync(join(srcKc, 'prompts'))) {
+    copyDirContents(join(srcKc, 'prompts'), join(kcDir, 'prompts'));
+  }
+
+  // Copy specs readme — don't overwrite if specs/ already has user content
+  const specsDir = join(kcDir, 'specs');
+  const userSpecs = existsSync(specsDir) ? readdirSync(specsDir).filter(f => f.endsWith('.md') && f !== 'Readme.md') : [];
+  if (userSpecs.length === 0 && existsSync(join(srcKc, 'specs', 'Readme.md'))) {
+    writeFileSync(join(kcDir, 'specs', 'Readme.md'), readFileSync(join(srcKc, 'specs', 'Readme.md')));
+  }
+
+  // Copy enterprise/ if exists
+  if (existsSync(join(srcKc, 'enterprise'))) {
+    copyDirContents(join(srcKc, 'enterprise'), join(kcDir, 'enterprise'));
+  }
+
+  // Initialize tracker and log — only create fresh if not preserving
+  if (!preserveFiles.has('knowzcode_tracker.md') || !existsSync(join(kcDir, 'knowzcode_tracker.md'))) {
+    initTracker(join(kcDir, 'knowzcode_tracker.md'));
+  }
+  if (!preserveFiles.has('knowzcode_log.md') || !existsSync(join(kcDir, 'knowzcode_log.md'))) {
+    initLog(join(kcDir, 'knowzcode_log.md'));
+  }
+
+  // Write version marker
+  writeFileSync(join(kcDir, '.knowzcode-version'), VERSION + '\n');
+
+  if (isReinstall && preserveFiles.size > 0) {
+    const preserved = [];
+    if (preserveFiles.has('knowzcode_tracker.md') && existsSync(join(kcDir, 'knowzcode_tracker.md'))) preserved.push('tracker');
+    if (preserveFiles.has('knowzcode_log.md') && existsSync(join(kcDir, 'knowzcode_log.md'))) preserved.push('log');
+    if (preserveFiles.has('knowzcode_architecture.md') && existsSync(join(kcDir, 'knowzcode_architecture.md'))) preserved.push('architecture');
+    if (preserveFiles.has('knowzcode_project.md') && existsSync(join(kcDir, 'knowzcode_project.md'))) preserved.push('project config');
+    if (preserveFiles.has('environment_context.md') && existsSync(join(kcDir, 'environment_context.md'))) preserved.push('environment');
+    if (preserveFiles.has('user_preferences.md') && existsSync(join(kcDir, 'user_preferences.md'))) preserved.push('preferences');
+    if (preserveFiles.has('knowzcode_orchestration.md') && existsSync(join(kcDir, 'knowzcode_orchestration.md'))) preserved.push('orchestration');
+    log.ok(`Core framework reinstalled (preserved: ${preserved.join(', ')})`);
+  } else {
+    log.ok('Core framework installed');
+  }
+
+  // 2. Platform detection + selection
+  const detected = detectPlatforms(dir);
+  let selectedPlatforms;
+
+  if (opts.platforms.length > 0) {
+    if (opts.platforms.includes('all')) {
+      selectedPlatforms = Object.keys(PLATFORMS);
+    } else {
+      selectedPlatforms = opts.platforms.filter((p) => p in PLATFORMS);
+    }
+  } else if (opts.force && opts.platforms.length === 0 && !isReinstall) {
+    // Non-interactive mode with --force on fresh install: install for detected platforms only
+    selectedPlatforms = detected;
+  } else if (opts.force && opts.platforms.length === 0 && isReinstall) {
+    // Reinstall: re-generate for already-installed platforms
+    const scan = scanExistingInstallation(kcDir, dir);
+    selectedPlatforms = scan.installedPlatforms.length > 0 ? scan.installedPlatforms : detected;
+  } else {
+    selectedPlatforms = await promptPlatforms(detected);
+  }
+
+  // 3. Generate adapters (using shared helper)
+  const { adapterFiles, agentTeamsEnabled } = await generateAdapters(dir, selectedPlatforms, opts);
+
+  // 4. Summary
   console.log('');
   console.log(`${c.green}${c.bold}Installation complete!${c.reset}`);
   console.log('');
@@ -888,21 +1101,116 @@ async function cmdInstall(opts) {
   }
   console.log('');
   console.log(`${c.bold}Next steps:${c.reset}`);
-  console.log('  1. Edit knowzcode/knowzcode_project.md — set project name, stack, standards');
-  console.log('  2. Edit knowzcode/environment_context.md — configure build/test commands');
+  if (!isReinstall) {
+    console.log('  1. Edit knowzcode/knowzcode_project.md — set project name, stack, standards');
+    console.log('  2. Edit knowzcode/environment_context.md — configure build/test commands');
+  }
   if (selectedPlatforms.includes('claude')) {
-    console.log('  3. Install the KnowzCode plugin (recommended):');
+    const step = isReinstall ? 1 : 3;
+    console.log(`  ${step}. Install the KnowzCode plugin (recommended):`);
     console.log('     /plugin install kc@knowzcode');
-    console.log('  4. Start building:');
+    console.log(`  ${step + 1}. Start building:`);
     console.log('     /kc:work "Your first feature"');
     console.log('');
     console.log('  Note: Commands also work without plugin as /work, /plan, /fix, etc.');
-  } else {
+  } else if (!isReinstall) {
     console.log('  3. Start building: use knowzcode/prompts/[LOOP_1A]__Propose_Change_Set.md');
   }
   console.log('');
 }
 
+// ADD-PLATFORMS
+async function cmdAddPlatforms(opts) {
+  const dir = opts.target;
+  const kcDir = join(dir, 'knowzcode');
+
+  console.log('');
+  console.log(`${c.bold}KnowzCode — Add/Change Platforms${c.reset}`);
+  console.log(`${c.dim}Target: ${dir}${c.reset}`);
+  console.log('');
+
+  if (!existsSync(kcDir)) {
+    log.err('No KnowzCode installation found. Run `npx knowzcode install` first.');
+    process.exit(1);
+  }
+
+  const scan = scanExistingInstallation(kcDir, dir);
+  const detected = detectPlatforms(dir);
+  const ids = Object.keys(PLATFORMS);
+
+  // Show platform status
+  console.log(`${c.bold}Platform status:${c.reset}`);
+  console.log('');
+  ids.forEach((id, i) => {
+    const p = PLATFORMS[id];
+    const installed = scan.installedPlatforms.includes(id);
+    const det = detected.includes(id);
+    let tag = '';
+    if (installed) tag = ` ${c.green}(installed)${c.reset}`;
+    else if (det) tag = ` ${c.yellow}(detected)${c.reset}`;
+    console.log(`  [${i + 1}] ${p.name}${tag}`);
+  });
+  console.log(`  [A] All platforms`);
+  console.log(`  [S] Cancel`);
+  console.log('');
+
+  let selectedPlatforms;
+  if (opts.platforms.length > 0) {
+    if (opts.platforms.includes('all')) {
+      selectedPlatforms = ids;
+    } else {
+      selectedPlatforms = opts.platforms.filter((p) => p in PLATFORMS);
+    }
+  } else {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question('Select platforms (comma-separated, e.g. 1,2): ');
+    rl.close();
+
+    const trimmed = answer.trim().toUpperCase();
+    if (trimmed === 'S' || trimmed === '') return;
+    if (trimmed === 'A') {
+      selectedPlatforms = ids;
+    } else {
+      selectedPlatforms = [];
+      for (const part of trimmed.split(',')) {
+        const num = parseInt(part.trim(), 10);
+        if (num >= 1 && num <= ids.length) selectedPlatforms.push(ids[num - 1]);
+      }
+      selectedPlatforms = [...new Set(selectedPlatforms)];
+    }
+  }
+
+  if (selectedPlatforms.length === 0) return;
+
+  // Confirm regeneration for already-installed platforms
+  const toRegenerate = selectedPlatforms.filter(id => scan.installedPlatforms.includes(id));
+  const toAdd = selectedPlatforms.filter(id => !scan.installedPlatforms.includes(id));
+
+  if (toRegenerate.length > 0 && !opts.force) {
+    const names = toRegenerate.map(id => PLATFORMS[id].name).join(', ');
+    const confirmed = await promptConfirm(`${names} already installed. Regenerate adapter(s)?`);
+    if (!confirmed) {
+      // Only generate the new ones
+      selectedPlatforms = toAdd;
+      if (selectedPlatforms.length === 0) return;
+    }
+  }
+
+  const { adapterFiles, agentTeamsEnabled } = await generateAdapters(dir, selectedPlatforms, opts);
+
+  console.log('');
+  log.ok('Platform adapters updated');
+  if (adapterFiles.length > 0) {
+    for (const f of adapterFiles) {
+      console.log('    ' + f);
+    }
+  }
+  if (agentTeamsEnabled) {
+    console.log('  Agent Teams: enabled');
+  }
+  console.log('');
+}
+
 // UNINSTALL
 async function cmdUninstall(opts) {
   const dir = opts.target;
@@ -1329,6 +1637,18 @@ async function cmdUpgrade(opts) {
     log.info('Preserved: Gemini MCP config (.gemini/settings.json)');
   }
 
+  // Offer to add detected-but-uninstalled platforms
+  const uninstalled = detected.filter(id => !isAdapterInstalled(id, dir));
+  if (uninstalled.length > 0 && !opts.force) {
+    const names = uninstalled.map(id => PLATFORMS[id].name).join(', ');
+    log.info(`New platforms detected: ${names}`);
+    const addNew = await promptConfirm('Generate adapters for these platforms?');
+    if (addNew) {
+      await generateAdapters(dir, uninstalled, opts);
+      regenerated.push(...uninstalled.map(id => PLATFORMS[id].name + ' (new)'));
+    }
+  }
+
   // Write new version
   writeFileSync(versionFile, VERSION + '\n');
 
@@ -1351,7 +1671,8 @@ Platform-agnostic AI development methodology
 
 ${c.bold}Usage:${c.reset}
   npx knowzcode                          Interactive mode
-  npx knowzcode install [options]        Install to current/target directory
+  npx knowzcode install [options]        Install (preserves data on reinstall)
+  npx knowzcode add-platforms [options]  Add/change platform adapters only
   npx knowzcode uninstall [options]      Remove KnowzCode
   npx knowzcode upgrade [options]        Upgrade preserving user data
   npx knowzcode detect                   Show detected platforms (dry run)
@@ -1360,6 +1681,7 @@ ${c.bold}Options:${c.reset}
   --target <path>      Target directory (default: current directory)
   --platforms <list>   Comma-separated: claude,codex,gemini,cursor,copilot,windsurf,all
   --force              Skip confirmation prompts
+  --clean              Full reset on reinstall (disables data preservation)
   --global             Install Claude Code to ~/.claude/, Codex skills to ~/.agents/skills/, Gemini skills to ~/.gemini/skills/
   --agent-teams        Enable Agent Teams in .claude/settings.local.json
   --verbose            Show detailed output
@@ -1369,6 +1691,7 @@ ${c.bold}Options:${c.reset}
 ${c.bold}Examples:${c.reset}
   npx knowzcode install --platforms claude,cursor
   npx knowzcode install --platforms all --force
+  npx knowzcode add-platforms --platforms cursor
   npx knowzcode upgrade --target ./my-project
   npx knowzcode uninstall --force
   npx knowzcode detect
@@ -1393,31 +1716,50 @@ async function cmdInteractive(opts) {
   }
 
   if (existsSync(kcDir)) {
+    // Always scan and display existing installation
+    const scan = scanExistingInstallation(kcDir, dir);
+    displayInstallationSummary(scan, dir);
+    console.log('');
+
     const versionFile = join(kcDir, '.knowzcode-version');
     const currentVersion = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : 'unknown';
 
     if (currentVersion !== VERSION) {
-      log.info(`Installed version: ${currentVersion}, available: ${VERSION}`);
-      const doUpgrade = await promptConfirm('Upgrade to latest version?');
-      if (doUpgrade) {
-        return cmdUpgrade(opts);
-      }
+      // Version mismatch — upgrade is the primary action
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      console.log(`  ${c.yellow}Update available: ${currentVersion} → ${VERSION}${c.reset}`);
+      console.log('');
+      console.log('  [1] Upgrade to v' + VERSION + ' (preserves all your data)');
+      console.log('  [2] Add/change platform adapters');
+      console.log('  [3] Reinstall framework (preserves your data)');
+      console.log('  [4] Uninstall');
+      console.log('  [5] Exit');
+      console.log('');
+      const answer = await rl.question('Select action: ');
+      rl.close();
+
+      const choice = answer.trim();
+      if (choice === '1') return cmdUpgrade(opts);
+      if (choice === '2') return cmdAddPlatforms(opts);
+      if (choice === '3') return cmdInstall({ ...opts, force: true });
+      if (choice === '4') return cmdUninstall(opts);
+      return;
     } else {
-      log.info(`KnowzCode ${currentVersion} already installed.`);
+      // Same version — add platforms is the primary action
       const rl = createInterface({ input: process.stdin, output: process.stdout });
       console.log('');
-      console.log('  [1] Reinstall (overwrite)');
-      console.log('  [2] Uninstall');
-      console.log('  [3] Detect platforms');
+      console.log('  [1] Add/change platform adapters');
+      console.log('  [2] Reinstall framework (preserves your data)');
+      console.log('  [3] Uninstall');
       console.log('  [4] Exit');
       console.log('');
       const answer = await rl.question('Select action: ');
       rl.close();
 
       const choice = answer.trim();
-      if (choice === '1') return cmdInstall({ ...opts, force: true });
-      if (choice === '2') return cmdUninstall(opts);
-      if (choice === '3') return cmdDetect(opts);
+      if (choice === '1') return cmdAddPlatforms(opts);
+      if (choice === '2') return cmdInstall({ ...opts, force: true });
+      if (choice === '3') return cmdUninstall(opts);
       return;
     }
   } else {
@@ -1435,6 +1777,8 @@ async function main() {
   switch (opts.command) {
     case 'install':
       return cmdInstall(opts);
+    case 'add-platforms':
+      return cmdAddPlatforms(opts);
     case 'uninstall':
       return cmdUninstall(opts);
     case 'upgrade':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowzcode",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
   "type": "module",
   "bin": {

package/skills/alias-resolver.json

@@ -1,6 +1,6 @@
 {
   "name": "alias-resolver",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Resolves friendly natural-language aliases to KnowzCode canonical values (phase, audit, plan, workgroup_type).",
   "parameters": [
     {"name": "domain", "type": "string", "required": true},

package/skills/architecture-diff.json

@@ -1,6 +1,6 @@
 {
   "name": "architecture-diff",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Highlights differences between specs and the Mermaid flowchart in knowzcode_architecture.md.",
   "parameters": [],
   "actions": [

package/skills/check-installation-status.json

@@ -1,6 +1,6 @@
 {
   "name": "check-installation-status",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Checks if KnowzCode is initialized in the current project and reports current status",
 
   "parameters": [],

package/skills/environment-guard.json

@@ -1,6 +1,6 @@
 {
   "name": "environment-guard",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Verifies that knowzcode/environment_context.md no longer contains placeholder brackets.",
   "parameters": [],
   "actions": [

package/skills/generate-workgroup-id.json

@@ -1,6 +1,6 @@
 {
   "name": "generate-workgroup-id",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Generates a WorkGroupID following the KnowzCode convention [type]-[slug]-YYYYMMDD-HHMMSS. The slug is a 2-4 word descriptor extracted from the goal.",
   "parameters": [
     {

package/skills/install-knowzcode.json

@@ -1,6 +1,6 @@
 {
   "name": "install-knowzcode",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Initializes KnowzCode directory structure and required files in the current project",
 
   "parameters": [

package/skills/load-core-context.json

@@ -1,6 +1,6 @@
 {
   "name": "load-core-context",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Loads the KnowzCode project overview, architecture, tracker, log header, and automation manifest for downstream steps.",
   "parameters": [],
   "actions": [

package/skills/log-entry-builder.json

@@ -1,6 +1,6 @@
 {
   "name": "log-entry-builder",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Appends structured entries to knowzcode/knowzcode_log.md with KnowzCode formatting.",
   "parameters": [
     {"name": "entry_type", "type": "string", "required": true},

package/skills/spec-quality-check.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-quality-check",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Validates KnowzCode spec files for mandatory sections. Supports new 4-section format and legacy numbered format.",
   "parameters": [
     {"name": "node_id", "type": "string", "required": true}

package/skills/spec-template.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-template",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Seeds or repairs KnowzCode spec files with the lean 4-section template.",
   "parameters": [
     {"name": "node_id", "type": "string", "required": true},

package/skills/spec-validator.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-validator",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Validates NodeID specification completeness and quality. Supports new 4-section format (preferred) and legacy numbered sections (deprecated).",
   "parameters": [
     {

package/skills/tracker-scan.json

@@ -1,6 +1,6 @@
 {
   "name": "tracker-scan",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Extracts NodeID statuses and WorkGroup assignments from the KnowzCode tracker.",
   "parameters": [],
   "actions": [

package/skills/tracker-update.json

@@ -1,6 +1,6 @@
 {
   "name": "tracker-update",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Applies validated updates to knowzcode/knowzcode_tracker.md while preserving table structure.",
   "parameters": [
     {

package/skills/validate-installation.json

@@ -1,6 +1,6 @@
 {
   "name": "validate-installation",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Validates that KnowzCode installation completed successfully with required directories and files",
 
   "parameters": [],