organic-growth 3.1.0 → 3.2.0

package/README.md

@@ -26,6 +26,9 @@ bunx organic-growth docs/my-product-spec.md
 
 # Force overwrite existing files:
 bunx organic-growth --force
+
+# Upgrade managed files (preserves CLAUDE.md, .mcp.json, etc.):
+bunx organic-growth --upgrade
 ```
 
 This installs `CLAUDE.md` at your project root and a `.claude/` directory with agents and commands. No runtime dependencies.
@@ -110,7 +113,7 @@ Properties are not test cases or user stories. A test says "when I do X, Y happe
 
 Properties **accumulate** across stages. Stage 3 must still satisfy the properties from stages 1 and 2. They are permanent commitments, not checkboxes to discard. This is what prevents regressions as the feature grows.
 
-The gardener agent handles the full property format — categories, failure analysis, dependency tracking. See the [example growth plan](docs/example-growth-plan.md) for what this looks like in practice.
+The gardener agent handles the full property format — categories, failure analysis, dependency tracking. See the [example growth plan](.organic-growth/example-growth-plan.md) for what this looks like in practice.
 
 ## After Install
 
@@ -118,7 +121,7 @@ The gardener agent handles the full property format — categories, failure anal
 2. Fill in Quality Tools section with your project's lint/test commands
 3. Start building with `/grow`
 
-See the [example growth plan](docs/example-growth-plan.md) to see properties, stages, and accumulation in action.
+See the [example growth plan](.organic-growth/example-growth-plan.md) to see properties, stages, and accumulation in action.
 
 ## Releases
 

package/bin/cli.mjs

@@ -129,6 +129,7 @@ function printHelp() {
   log('');
   log(`${CYAN}Options:${RESET}`);
   log(`  -f, --force     Overwrite existing files without prompting`);
+  log(`      --upgrade   Update managed files while preserving user customizations`);
   log(`      --migrate   Move legacy docs/growth and docs/product-dna.md to .organic-growth/`);
   log(`  -h, --help      Show this help message`);
   log(`  -v, --version   Show version number`);
@@ -141,6 +142,7 @@ function printHelp() {
   log(`  npx organic-growth                  Install Claude Code templates`);
   log(`  npx organic-growth --opencode       Install opencode templates`);
   log(`  npx organic-growth --force          Install templates (overwrite existing)`);
+  log(`  npx organic-growth --upgrade         Update managed files, keep user customizations`);
   log(`  npx organic-growth --migrate        Migrate legacy docs/ state into .organic-growth/`);
   log(`  npx organic-growth spec.md          Install templates + copy DNA document`);
   log('');
@@ -160,126 +162,218 @@ async function install() {
   }
 
   const force = args.includes('--force') || args.includes('-f');
+  const upgrade = args.includes('--upgrade');
   const migrate = args.includes('--migrate');
   const isOpencode = args.includes('--opencode');
   const dna = args.find(a => !a.startsWith('-') && a.endsWith('.md'));
 
+  // --upgrade and --force are mutually exclusive
+  if (upgrade && force) {
+    console.error('Error: --upgrade and --force are mutually exclusive. Use --upgrade to update managed files while preserving user customizations, or --force to overwrite everything.');
+    process.exit(1);
+  }
+
+  // User-customized files that --upgrade should never overwrite or create
+  const USER_FILES = new Set(['CLAUDE.md', 'AGENTS.md', '.mcp.json', 'opencode.json']);
+
+  function isUserFile(filePath) {
+    // Check if the file's basename (top-level name) is in the user files set
+    return USER_FILES.has(filePath);
+  }
+
   log('');
-  if (isOpencode) {
+  if (upgrade) {
+    log(`${GREEN}🌱 Organic Growth${RESET} — upgrading managed files`);
+  } else if (isOpencode) {
     log(`${GREEN}🌱 Organic Growth${RESET} — opencode setup for incremental development`);
   } else {
     log(`${GREEN}🌱 Organic Growth${RESET} — Claude Code setup for incremental development`);
   }
   log('');
 
-  const templatesDir = isOpencode ? TEMPLATES_OPENCODE_DIR : TEMPLATES_DIR;
-  const files = getAllFiles(templatesDir);
-  const created = [];
-  const skipped = [];
+  if (upgrade) {
+    // Read existing version for display
+    const versionFilePath = join(TARGET_DIR, '.organic-growth', '.version');
+    const fromVersion = existsSync(versionFilePath)
+      ? readFileSync(versionFilePath, 'utf8').trim()
+      : 'unknown';
+    const toVersion = readVersion();
 
-  for (const file of files) {
-    const src = join(templatesDir, file);
-    const dest = join(TARGET_DIR, file);
-    const destDir = dirname(dest);
+    const templatesDir = isOpencode ? TEMPLATES_OPENCODE_DIR : TEMPLATES_DIR;
+    const files = getAllFiles(templatesDir);
+    const updated = [];
+    const skippedUser = [];
 
-    if (!existsSync(destDir)) {
-      mkdirSync(destDir, { recursive: true });
-    }
+    for (const file of files) {
+      const src = join(templatesDir, file);
+      const dest = join(TARGET_DIR, file);
+      const destDir = dirname(dest);
 
-    if (existsSync(dest) && !force) {
-      if (!process.stdin.isTTY) {
-        skipped.push(file);
+      if (isUserFile(file)) {
+        // User-customized files: skip if they exist, don't create if missing
+        if (existsSync(dest)) {
+          skippedUser.push(file);
+        }
+        // If it doesn't exist, we intentionally do NOT create it (P8)
         continue;
       }
-      const answer = await ask(`${YELLOW}!${RESET} ${file} already exists. Overwrite? [y/N] `);
-      if (answer !== 'y' && answer !== 'yes') {
-        skipped.push(file);
-        continue;
+
+      // Managed file: overwrite (or create if new)
+      if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
       }
+      copyFileSync(src, dest);
+      updated.push(file);
     }
 
-    copyFileSync(src, dest);
-    created.push(file);
-  }
+    // Display upgrade results
+    info(`Upgrading from ${CYAN}${fromVersion}${RESET} to ${CYAN}${toVersion}${RESET}`);
+    log('');
 
-  // Create .organic-growth/growth/ directory
-  const growthDir = join(TARGET_DIR, '.organic-growth', 'growth');
-  if (!existsSync(growthDir)) {
-    mkdirSync(growthDir, { recursive: true });
-    created.push('.organic-growth/growth/');
-  }
+    if (updated.length > 0) {
+      log(`${GREEN}Updated:${RESET}`);
+      for (const f of updated) {
+        log(`  ${DIM}${f}${RESET}`);
+      }
+    }
+    if (skippedUser.length > 0) {
+      log(`${YELLOW}Skipped (user customized):${RESET}`);
+      for (const f of skippedUser) {
+        log(`  ${DIM}${f}${RESET}`);
+      }
+    }
 
-  // Handle DNA document
-  if (dna) {
-    const dnaSource = resolve(TARGET_DIR, dna);
-    if (existsSync(dnaSource)) {
-      const dnaDest = join(TARGET_DIR, '.organic-growth', 'product-dna.md');
-      mkdirSync(dirname(dnaDest), { recursive: true });
-      copyFileSync(dnaSource, dnaDest);
-      success(`Product DNA copied from ${dna}`);
-    } else {
-      warn(`DNA file not found: ${dna}`);
+    // Write version file after all managed files are updated
+    const ogDir = join(TARGET_DIR, '.organic-growth');
+    if (!existsSync(ogDir)) {
+      mkdirSync(ogDir, { recursive: true });
     }
-  }
+    writeFileSync(join(ogDir, '.version'), toVersion);
 
-  if (migrate) {
-    const migrated = migrateLegacyState(TARGET_DIR);
-    if (migrated.length > 0) {
-      log('');
-      log(`${GREEN}Migrated:${RESET}`);
-      for (const step of migrated) {
-        log(`  ${DIM}${step}${RESET}`);
+    log('');
+    log(`${GREEN}Done!${RESET} ${updated.length} updated, ${skippedUser.length} skipped.`);
+    log('');
+  } else {
+    // Normal install flow
+    const templatesDir = isOpencode ? TEMPLATES_OPENCODE_DIR : TEMPLATES_DIR;
+    const files = getAllFiles(templatesDir);
+    const created = [];
+    const skipped = [];
+
+    for (const file of files) {
+      const src = join(templatesDir, file);
+      const dest = join(TARGET_DIR, file);
+      const destDir = dirname(dest);
+
+      if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
       }
-    } else {
-      info('No legacy docs/ state found to migrate');
-    }
-  }
 
-  log('');
-  if (created.length > 0) {
-    log(`${GREEN}Installed:${RESET}`);
-    for (const f of created) {
-      log(`  ${DIM}${f}${RESET}`);
+      if (existsSync(dest) && !force) {
+        if (!process.stdin.isTTY) {
+          skipped.push(file);
+          continue;
+        }
+        const answer = await ask(`${YELLOW}!${RESET} ${file} already exists. Overwrite? [y/N] `);
+        if (answer !== 'y' && answer !== 'yes') {
+          skipped.push(file);
+          continue;
+        }
+      }
+
+      copyFileSync(src, dest);
+      created.push(file);
     }
-  }
-  if (skipped.length > 0) {
-    log(`${YELLOW}Skipped (already exist):${RESET}`);
-    for (const f of skipped) {
-      log(`  ${DIM}${f}${RESET}`);
+
+    // Create .organic-growth/growth/ directory
+    const growthDir = join(TARGET_DIR, '.organic-growth', 'growth');
+    if (!existsSync(growthDir)) {
+      mkdirSync(growthDir, { recursive: true });
+      created.push('.organic-growth/growth/');
     }
-  }
 
-  log('');
-  log(`${GREEN}Done!${RESET} Next steps:`);
-  log('');
-  if (isOpencode) {
+    // Handle DNA document
     if (dna) {
-      info(`Run ${CYAN}/seed .organic-growth/product-dna.md${RESET} to bootstrap from your DNA document`);
-    } else {
-      info(`Run ${CYAN}/seed${RESET} to bootstrap a new project (interview mode)`);
-      info(`Or: ${CYAN}/seed path/to/product-doc.md${RESET} if you have a product document`);
+      const dnaSource = resolve(TARGET_DIR, dna);
+      if (existsSync(dnaSource)) {
+        const dnaDest = join(TARGET_DIR, '.organic-growth', 'product-dna.md');
+        mkdirSync(dirname(dnaDest), { recursive: true });
+        copyFileSync(dnaSource, dnaDest);
+        success(`Product DNA copied from ${dna}`);
+      } else {
+        warn(`DNA file not found: ${dna}`);
+      }
     }
-    info(`Edit ${CYAN}AGENTS.md${RESET} to fill in your tech stack and quality tools`);
-  } else {
-    if (dna) {
-      info(`Run ${CYAN}/seed .organic-growth/product-dna.md${RESET} to bootstrap from your DNA document`);
+
+    if (migrate) {
+      const migrated = migrateLegacyState(TARGET_DIR);
+      if (migrated.length > 0) {
+        log('');
+        log(`${GREEN}Migrated:${RESET}`);
+        for (const step of migrated) {
+          log(`  ${DIM}${step}${RESET}`);
+        }
+      } else {
+        info('No legacy docs/ state found to migrate');
+      }
+    }
+
+    log('');
+    if (created.length > 0) {
+      log(`${GREEN}Installed:${RESET}`);
+      for (const f of created) {
+        log(`  ${DIM}${f}${RESET}`);
+      }
+    }
+    if (skipped.length > 0) {
+      log(`${YELLOW}Skipped (already exist):${RESET}`);
+      for (const f of skipped) {
+        log(`  ${DIM}${f}${RESET}`);
+      }
+    }
+
+    // Write version file after all templates and DNA are handled
+    const versionFilePath = join(TARGET_DIR, '.organic-growth', '.version');
+    const ogDir = dirname(versionFilePath);
+    if (!existsSync(ogDir)) {
+      mkdirSync(ogDir, { recursive: true });
+    }
+    writeFileSync(versionFilePath, readVersion());
+
+    log('');
+    log(`${GREEN}Done!${RESET} Next steps:`);
+    log('');
+    if (isOpencode) {
+      if (dna) {
+        info(`Run ${CYAN}/seed .organic-growth/product-dna.md${RESET} to bootstrap from your DNA document`);
+      } else {
+        info(`Run ${CYAN}/seed${RESET} to bootstrap a new project (interview mode)`);
+        info(`Or: ${CYAN}/seed path/to/product-doc.md${RESET} if you have a product document`);
+      }
+      info(`Edit ${CYAN}AGENTS.md${RESET} to fill in your tech stack and quality tools`);
     } else {
-      info(`Run ${CYAN}/seed${RESET} to bootstrap a new project (interview mode)`);
-      info(`Or: ${CYAN}/seed path/to/product-doc.md${RESET} if you have a product document`);
+      if (dna) {
+        info(`Run ${CYAN}/seed .organic-growth/product-dna.md${RESET} to bootstrap from your DNA document`);
+      } else {
+        info(`Run ${CYAN}/seed${RESET} to bootstrap a new project (interview mode)`);
+        info(`Or: ${CYAN}/seed path/to/product-doc.md${RESET} if you have a product document`);
+      }
+      info(`Edit ${CYAN}CLAUDE.md${RESET} to fill in your tech stack and quality tools`);
     }
-    info(`Edit ${CYAN}CLAUDE.md${RESET} to fill in your tech stack and quality tools`);
-  }
-  log('');
-  log(`${DIM}Commands available after setup:${RESET}`);
-  log(`  ${CYAN}/seed${RESET}    — bootstrap project (interview or DNA document)`);
-  log(`  ${CYAN}/grow${RESET}    — plan and start a new feature`);
-  log(`  ${CYAN}/map${RESET}     — view or adjust the system growth map`);
-  log(`  ${CYAN}/next${RESET}    — implement the next growth stage`);
-  log(`  ${CYAN}/next-automatic${RESET} — run multiple stages automatically`);
-  log(`  ${CYAN}/replan${RESET}  — re-evaluate when things change`);
-  log(`  ${CYAN}/review${RESET}  — deep quality review of recent stages`);
+    log('');
+    log(`${DIM}Commands available after setup:${RESET}`);
+    log(`  ${CYAN}/seed${RESET}    — bootstrap project (interview or DNA document)`);
+    log(`  ${CYAN}/grow${RESET}    — plan and start a new feature`);
+    log(`  ${CYAN}/map${RESET}     — view or adjust the system growth map`);
+    log(`  ${CYAN}/next${RESET}    — implement the next growth stage`);
+    log(`  ${CYAN}/next-automatic${RESET} — run multiple stages automatically`);
+    log(`  ${CYAN}/replan${RESET}  — re-evaluate when things change`);
+    log(`  ${CYAN}/review${RESET}  — deep quality review of recent stages`);
 
-  log('');
+    log('');
+    log(`${DIM}To upgrade later: npx organic-growth --upgrade${RESET}`);
+    log('');
+  }
 }
 
 install().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "organic-growth",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Claude Code and opencode setup for incremental software development — grow features in natural stages",
   "bin": {
     "organic-growth": "bin/cli.mjs"