5-phase-workflow 1.9.0 → 1.9.1

package/bin/install.js

@@ -38,13 +38,17 @@ function compareVersions(v1, v2) {
 }
 
 // Get installed version from .5/version.json
+// Reads per-runtime version when available (runtimes[activeRuntime].packageVersion),
+// falling back to top-level packageVersion for backward compatibility.
 function getInstalledVersion(isGlobal) {
   const versionFile = path.join(getDataPath(isGlobal), 'version.json');
   if (!fs.existsSync(versionFile)) return null;
 
   try {
     const data = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
-    return data.packageVersion;
+    return (data.runtimes && data.runtimes[activeRuntime] && data.runtimes[activeRuntime].packageVersion)
+      || data.packageVersion
+      || null;
   } catch (e) {
     return null; // Corrupted file, treat as missing
   }
@@ -624,7 +628,10 @@ function cleanupOrphanedFiles(targetPath, dataDir) {
   if (fs.existsSync(versionFile)) {
     try {
       const data = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
-      oldManifest = data.manifest || null;
+      // Prefer per-runtime manifest to avoid cross-runtime orphan cleanup
+      oldManifest = (data.runtimes && data.runtimes[activeRuntime] && data.runtimes[activeRuntime].manifest)
+        || data.manifest
+        || null;
     } catch (e) {
       // Corrupted file, treat as no manifest
     }
@@ -677,27 +684,73 @@ function ensureDotFiveGitignore(dataDir) {
   }
 }
 
-// Initialize version.json after successful install
-function initializeVersionJson(isGlobal) {
-  const dataDir = getDataPath(isGlobal);
+// Write (or update) version.json, preserving per-runtime state for other runtimes.
+// - Reads existing file to preserve the other runtime's runtimes[] entry.
+// - Writes runtimes[activeRuntime] with current version + manifest.
+// - Top-level packageVersion = minimum across all runtime versions (so hooks
+//   detect an update if ANY runtime is behind).
+function writeVersionJson(dataDir, isGlobal, version) {
   const versionFile = path.join(dataDir, 'version.json');
+  const now = new Date().toISOString();
 
-  if (!fs.existsSync(dataDir)) {
-    fs.mkdirSync(dataDir, { recursive: true });
+  let existing = {};
+  if (fs.existsSync(versionFile)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
+    } catch (e) {
+      existing = {};
+    }
   }
 
-  const version = getPackageVersion();
-  const now = new Date().toISOString();
-
-  const versionData = {
+  const runtimes = existing.runtimes || {};
+  runtimes[activeRuntime] = {
     packageVersion: version,
-    installedAt: now,
     lastUpdated: now,
-    installationType: isGlobal ? 'global' : 'local',
     manifest: getFileManifest()
   };
 
+  // Top-level packageVersion = min across all runtime versions
+  const runtimeVersions = Object.values(runtimes).map(r => r.packageVersion).filter(Boolean);
+  const minVersion = runtimeVersions.reduce((min, v) => compareVersions(v, min) < 0 ? v : min, version);
+
+  const versionData = {
+    packageVersion: minVersion,
+    installedAt: existing.installedAt || now,
+    lastUpdated: now,
+    installationType: existing.installationType || (isGlobal ? 'global' : 'local'),
+    manifest: runtimes[activeRuntime].manifest,
+    runtimes
+  };
+
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
+  }
   fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
+}
+
+// Detect which runtimes are actually installed by probing marker files.
+function getInstalledRuntimes(isGlobal) {
+  const installed = [];
+  const saved = activeRuntime;
+  for (const rt of ['claude', 'codex']) {
+    activeRuntime = rt;
+    const tp = getTargetPath(isGlobal);
+    if (checkExistingInstallation(tp)) installed.push(rt);
+  }
+  activeRuntime = saved;
+  return installed;
+}
+
+// Initialize version.json after successful install
+function initializeVersionJson(isGlobal) {
+  const dataDir = getDataPath(isGlobal);
+
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
+  }
+
+  const version = getPackageVersion();
+  writeVersionJson(dataDir, isGlobal, version);
   ensureDotFiveGitignore(dataDir);
   log.success('Initialized version tracking');
 }
@@ -868,25 +921,8 @@ function performUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   // Merge settings (deep merge preserves user customizations)
   mergeSettings(targetPath, sourcePath);
 
-  // Update version.json
-  const versionFile = path.join(dataDir, 'version.json');
-  const now = new Date().toISOString();
-
-  const existing = fs.existsSync(versionFile)
-    ? JSON.parse(fs.readFileSync(versionFile, 'utf8'))
-    : {};
-  const versionData = {
-    packageVersion: versionInfo.available,
-    installedAt: existing.installedAt || now,
-    lastUpdated: now,
-    installationType: existing.installationType || (isGlobal ? 'global' : 'local'),
-    manifest: getFileManifest()
-  };
-
-  if (!fs.existsSync(dataDir)) {
-    fs.mkdirSync(dataDir, { recursive: true });
-  }
-  fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
+  // Update version.json (per-runtime, preserving other runtime's state)
+  writeVersionJson(dataDir, isGlobal, versionInfo.available);
   ensureDotFiveGitignore(dataDir);
 
   // Create features directory if it doesn't exist
@@ -1092,24 +1128,8 @@ function performCodexUpdate(targetPath, sourcePath, isGlobal, versionInfo) {
   const dataDir = getDataPath(isGlobal);
   cleanupOrphanedFiles(targetPath, dataDir);
 
-  // Update version.json
-  const versionFile = path.join(dataDir, 'version.json');
-  const now = new Date().toISOString();
-  const existing = fs.existsSync(versionFile)
-    ? JSON.parse(fs.readFileSync(versionFile, 'utf8'))
-    : {};
-  const versionData = {
-    packageVersion: versionInfo.available,
-    installedAt: existing.installedAt || now,
-    lastUpdated: now,
-    installationType: existing.installationType || (isGlobal ? 'global' : 'local'),
-    manifest: getFileManifest()
-  };
-
-  if (!fs.existsSync(dataDir)) {
-    fs.mkdirSync(dataDir, { recursive: true });
-  }
-  fs.writeFileSync(versionFile, JSON.stringify(versionData, null, 2));
+  // Update version.json (per-runtime, preserving other runtime's state)
+  writeVersionJson(dataDir, isGlobal, versionInfo.available);
   ensureDotFiveGitignore(dataDir);
 
   const featuresDir = path.join(dataDir, 'features');
@@ -1216,6 +1236,7 @@ function install(isGlobal, forceUpgrade = false) {
       log.warn('Detected legacy installation (no version tracking)');
       log.info(`Upgrading from legacy install to ${versionInfo.available}`);
       update(targetPath, sourcePath, isGlobal, versionInfo);
+      updateOtherRuntime(isGlobal);
       return;
     } else if (versionInfo.needsUpdate) {
       log.info(`Installed: ${versionInfo.installed}`);
@@ -1235,11 +1256,13 @@ function install(isGlobal, forceUpgrade = false) {
             return;
           }
           update(targetPath, sourcePath, isGlobal, versionInfo);
+          updateOtherRuntime(isGlobal);
         });
         return; // Wait for user input
       }
       // Force upgrade, no prompt
       update(targetPath, sourcePath, isGlobal, versionInfo);
+      updateOtherRuntime(isGlobal);
       return;
     } else {
       // Same version
@@ -1252,6 +1275,31 @@ function install(isGlobal, forceUpgrade = false) {
   freshInstall(targetPath, sourcePath, isGlobal);
 }
 
+// After updating the active runtime, check if the other runtime is also installed
+// and needs an update. Updates it silently if so.
+function updateOtherRuntime(isGlobal) {
+  const primaryRuntime = activeRuntime;
+  const installed = getInstalledRuntimes(isGlobal);
+
+  for (const rt of installed) {
+    if (rt === primaryRuntime) continue;
+
+    activeRuntime = rt;
+    const tp = getTargetPath(isGlobal);
+    const sp = getSourcePath();
+    const vi = getVersionInfo(tp, isGlobal);
+
+    if (vi.exists && (vi.needsUpdate || vi.legacy)) {
+      const updateFn = rt === 'codex' ? performCodexUpdate : performUpdate;
+      updateFn(tp, sp, isGlobal, vi);
+    } else if (vi.exists) {
+      log.success(`${rt}: already at version ${vi.installed}`);
+    }
+  }
+
+  activeRuntime = primaryRuntime;
+}
+
 // Perform uninstallation
 function uninstall() {
   if (activeRuntime === 'codex') {
@@ -1369,25 +1417,48 @@ function main() {
   }
 
   if (options.check) {
-    const targetPath = getTargetPath(options.global);
     migrateDataDir(options.global);
-    const versionInfo = getVersionInfo(targetPath, options.global);
 
-    if (!versionInfo.exists) {
-      log.info(`Not installed (${activeRuntime})`);
+    // When --codex is explicitly passed, check only Codex. Otherwise check all installed runtimes.
+    const runtimesToCheck = options.runtime === 'codex'
+      ? ['codex']
+      : getInstalledRuntimes(options.global);
+
+    if (runtimesToCheck.length === 0) {
+      log.info('Not installed');
       return;
     }
 
-    log.info(`Runtime: ${activeRuntime}`);
-    log.info(`Installed: ${versionInfo.installed || 'legacy (no version)'}`);
-    log.info(`Available: ${versionInfo.available}`);
+    const primaryRuntime = activeRuntime;
+    let anyUpdateAvailable = false;
 
-    if (versionInfo.needsUpdate) {
-      log.warn('Update available');
-      log.info(`Run: npx 5-phase-workflow${activeRuntime === 'codex' ? ' --codex' : ''} --upgrade`);
-    } else {
-      log.success('Up to date');
+    for (const rt of runtimesToCheck) {
+      activeRuntime = rt;
+      const tp = getTargetPath(options.global);
+      const vi = getVersionInfo(tp, options.global);
+
+      if (!vi.exists) {
+        log.info(`${rt}: not installed`);
+        continue;
+      }
+
+      log.info(`Runtime: ${rt}`);
+      log.info(`Installed: ${vi.installed || 'legacy (no version)'}`);
+      log.info(`Available: ${vi.available}`);
+
+      if (vi.needsUpdate) {
+        log.warn(`${rt}: update available`);
+        anyUpdateAvailable = true;
+      } else {
+        log.success(`${rt}: up to date`);
+      }
     }
+
+    if (anyUpdateAvailable) {
+      log.info('Run: npx 5-phase-workflow --upgrade');
+    }
+
+    activeRuntime = primaryRuntime;
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/commands/5/discuss-feature.md

@@ -117,6 +117,8 @@ Use `multiSelect: false` to get single focus area initially.
 
 Based on the user's focus area, explore the codebase if needed:
 
+**Index shortcut:** Before spawning Explore agents or running Glob/Grep, check if `.5/index/` exists. If it does, read `.5/index/README.md` first for the generation timestamp — if fresh (under 1 day old), read the relevant index files (e.g., modules.md for scope changes, routes.md for API discussions, models.md for data model questions) to quickly gather context and skip broad scanning. If outdated, inform the user they can run `.5/index/rebuild-index.sh` to refresh it. If `.5/index/` does not exist, inform the user they can run `/5:reconfigure` to generate it. In both missing/outdated cases, fall back to Glob/Grep or Explore agents for exploration.
+
 **For technical constraint discussions:**
 - Search for similar implementations
 - Check existing patterns

package/src/commands/5/implement-feature.md

@@ -207,6 +207,9 @@ Task tool call:
     {If Depends On is not "—": "This component depends on {dep-name} ({dep-file}). Read that file first to understand the exports/types you need to use."}
     {If Depends On is "—": omit this section entirely}
 
+    ## Codebase Context (optional)
+    If you need to understand how this component relates to other modules (imports, service boundaries, data flow), check `.5/index/` for quick reference — especially modules.md and libraries.md. Only if these files exist.
+
     ## Verify
     {Verify command(s) from plan table — executor runs these after implementation}
 

package/src/commands/5/plan-feature.md

@@ -129,12 +129,13 @@ Analyze the codebase for a feature specification session.
 **Feature Description:** {paste the user's feature description}
 
 **Your Task:**
-1. Explore project structure to identify modules/components
-2. Find existing implementations similar to this feature
-3. Identify coding patterns and conventions
-4. Find reusable components or patterns
-5. Identify affected files/modules
-6. Run `git branch --show-current` to get the current branch name
+1. Check if `.5/index/` exists. If it does, read `.5/index/README.md` first — it includes a generation timestamp. If the index is fresh (under 1 day old), read the relevant index files (e.g., modules.md, routes.md, models.md) as your structural overview and skip broad Glob scans for information already covered. If the index is outdated (over 1 day old), note in your report that the user should run `.5/index/rebuild-index.sh` to refresh it, then use it anyway (stale is better than nothing). If `.5/index/` does not exist at all, note in your report that the user can run `/5:reconfigure` to generate it, then proceed with Glob/Grep exploration as below.
+2. Explore project structure to identify modules/components
+3. Find existing implementations similar to this feature
+4. Identify coding patterns and conventions
+5. Find reusable components or patterns
+6. Identify affected files/modules
+7. Run `git branch --show-current` to get the current branch name
 
 **Report Format:**
 - Current git branch name

package/src/commands/5/plan-implementation.md

@@ -160,13 +160,14 @@ Quick codebase scan for implementation planning.
 Focus scan on {projectType}-relevant directories and patterns.
 
 **Your Task:**
-1. Find source directories and understand project structure
-2. Identify where similar components live (models, services, controllers, tests)
-3. Note naming conventions from existing files
-4. Find example files that can serve as patterns for new components
-5. Identify the project's test framework, test file conventions, and test directory structure (e.g., __tests__/, tests/, *.test.ts, *.spec.ts, test_*.py)
-6. Detect e2e test framework and config (Cypress, Playwright, Selenium, Supertest, etc.) — look for config files like playwright.config.ts, cypress.config.js, e2e/ directories
-7. Detect integration test patterns (test containers, in-memory DBs, API test helpers, fixtures) — look for setup files, docker-compose.test.yml, test utilities
+1. Check if `.5/index/` exists. If it does, read `.5/index/README.md` first — it includes a generation timestamp. If the index is fresh (under 1 day old), read the relevant index files (modules.md, models.md, libraries.md, etc.) for project structure and component locations, then focus Glob/Grep on naming conventions, pattern files, and test framework details not covered by the index. If the index is outdated (over 1 day old), note in your report that the user should run `.5/index/rebuild-index.sh` to refresh it, then use it anyway. If `.5/index/` does not exist at all, note in your report that the user can run `/5:reconfigure` to generate it, then scan from scratch as below.
+2. Find source directories and understand project structure
+3. Identify where similar components live (models, services, controllers, tests)
+4. Note naming conventions from existing files
+5. Find example files that can serve as patterns for new components
+6. Identify the project's test framework, test file conventions, and test directory structure (e.g., __tests__/, tests/, *.test.ts, *.spec.ts, test_*.py)
+7. Detect e2e test framework and config (Cypress, Playwright, Selenium, Supertest, etc.) — look for config files like playwright.config.ts, cypress.config.js, e2e/ directories
+8. Detect integration test patterns (test containers, in-memory DBs, API test helpers, fixtures) — look for setup files, docker-compose.test.yml, test utilities
 
 **Report Format:**
 - Project structure (key directories)

package/src/commands/5/quick-implement.md

@@ -91,7 +91,7 @@ Check if `.5/features/${feature_name}/state.json` already exists:
 
 ### Step 4: Analyze and Scope Check
 
-1. **Identify affected files** using Glob and Grep
+1. **Identify affected files:** If `.5/index/` exists, read `.5/index/README.md` first for the generation timestamp — if fresh (under 1 day old), read the relevant index files (modules.md, routes.md, models.md) to quickly locate affected areas, then confirm with targeted Glob/Grep. If the index is outdated, note that the user can run `.5/index/rebuild-index.sh` to refresh it. If no index exists, note that the user can run `/5:reconfigure` to generate it. In both cases, fall back to Glob and Grep directly.
 2. **Determine skills needed** based on task type
 3. **List components** (max 5 for quick mode)
 
@@ -261,6 +261,7 @@ Task tool call:
     For each component:
 
     **If creating a new file:**
+    0. If `.5/index/` exists, check modules.md or libraries.md to find where similar components live — this narrows your Glob search.
     1. Find a similar file using Glob (e.g., *Service.ts for services)
     2. Read it to understand the pattern (imports, structure, exports)
     3. Create the new file following that pattern