agileflow 2.66.0 → 2.68.0

package/README.md

@@ -15,16 +15,15 @@
 
 ### Installation
 
-**Global (Recommended):**
 ```bash
-npm install -g agileflow
-agileflow setup
+npx agileflow@latest setup
 ```
 
-**Project-Level:**
+That's it! The `npx` command always fetches the latest version.
+
+**Updates:**
 ```bash
-npm install agileflow
-npx agileflow setup
+npx agileflow@latest update
 ```
 
 ### After Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.66.0",
+  "version": "2.68.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/agileflow-configure.js

@@ -23,7 +23,7 @@
  *   --detect                            Show current status
  *   --help                              Show help
  *
- * Features: sessionstart, precompact, stop, archival, statusline, autoupdate
+ * Features: sessionstart, precompact, archival, statusline, autoupdate
  */
 
 const fs = require('fs');
@@ -39,7 +39,7 @@ const VERSION = '2.41.0';
 const FEATURES = {
   sessionstart: { hook: 'SessionStart', script: 'agileflow-welcome.js', type: 'node' },
   precompact: { hook: 'PreCompact', script: 'precompact-context.sh', type: 'bash' },
-  stop: { hook: 'Stop', script: 'agileflow-stop.sh', type: 'bash' },
+  // Note: Stop hook removed due to Claude Code reliability issues (see GitHub issues #6974, #11544)
   archival: { script: 'archive-completed-stories.sh', requiresHook: 'sessionstart' },
   statusline: { script: 'agileflow-statusline.sh' },
   autoupdate: { metadataOnly: true }, // Stored in metadata.updates.autoUpdate
@@ -60,24 +60,24 @@ const STATUSLINE_COMPONENTS = [
 const PROFILES = {
   full: {
     description: 'All features enabled',
-    enable: ['sessionstart', 'precompact', 'stop', 'archival', 'statusline'],
+    enable: ['sessionstart', 'precompact', 'archival', 'statusline'],
     archivalDays: 7,
   },
   basic: {
     description: 'Essential hooks + archival (SessionStart + PreCompact + Archival)',
     enable: ['sessionstart', 'precompact', 'archival'],
-    disable: ['stop', 'statusline'],
+    disable: ['statusline'],
     archivalDays: 7,
   },
   minimal: {
     description: 'SessionStart + archival only',
     enable: ['sessionstart', 'archival'],
-    disable: ['precompact', 'stop', 'statusline'],
+    disable: ['precompact', 'statusline'],
     archivalDays: 7,
   },
   none: {
     description: 'Disable all AgileFlow features',
-    disable: ['sessionstart', 'precompact', 'stop', 'archival', 'statusline'],
+    disable: ['sessionstart', 'precompact', 'archival', 'statusline'],
   },
 };
 
@@ -154,7 +154,6 @@ function detectConfig() {
     features: {
       sessionstart: { enabled: false, valid: true, issues: [] },
       precompact: { enabled: false, valid: true, issues: [] },
-      stop: { enabled: false, valid: true, issues: [] },
       archival: { enabled: false, threshold: null },
       statusline: { enabled: false, valid: true, issues: [] },
     },
@@ -221,23 +220,7 @@ function detectConfig() {
           }
         }
 
-        // Stop
-        if (settings.hooks.Stop) {
-          if (Array.isArray(settings.hooks.Stop) && settings.hooks.Stop.length > 0) {
-            const hook = settings.hooks.Stop[0];
-            if (hook.matcher !== undefined && hook.hooks) {
-              status.features.stop.enabled = true;
-            } else {
-              status.features.stop.enabled = true;
-              status.features.stop.valid = false;
-              status.features.stop.issues.push('Old format - needs migration');
-            }
-          } else if (typeof settings.hooks.Stop === 'string') {
-            status.features.stop.enabled = true;
-            status.features.stop.valid = false;
-            status.features.stop.issues.push('String format - needs migration');
-          }
-        }
+        // Note: Stop hook removed due to reliability issues
       }
 
       // StatusLine
@@ -313,7 +296,6 @@ function printStatus(status) {
 
   printFeature('sessionstart', 'SessionStart Hook');
   printFeature('precompact', 'PreCompact Hook');
-  printFeature('stop', 'Stop Hook');
 
   const arch = status.features.archival;
   log(
@@ -357,9 +339,9 @@ function migrateSettings() {
 
   let migrated = false;
 
-  // Migrate hooks
+  // Migrate hooks (Stop hook removed due to reliability issues)
   if (settings.hooks) {
-    ['SessionStart', 'PreCompact', 'Stop', 'UserPromptSubmit'].forEach(hookName => {
+    ['SessionStart', 'PreCompact', 'UserPromptSubmit'].forEach(hookName => {
       const hook = settings.hooks[hookName];
       if (!hook) return;
 
@@ -472,15 +454,6 @@ function enableFeature(feature, options = {}) {
         );
       } else if (feature === 'precompact') {
         fs.writeFileSync(scriptPath, '#!/bin/bash\necho "PreCompact: preserving context"\n');
-      } else if (feature === 'stop') {
-        fs.writeFileSync(
-          scriptPath,
-          `#!/bin/bash
-git rev-parse --git-dir > /dev/null 2>&1 || exit 0
-CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-[ "$CHANGES" -gt 0 ] && echo -e "\\n\\033[33m$CHANGES uncommitted change(s)\\033[0m"
-`
-        );
       }
       try {
         fs.chmodSync(scriptPath, '755');
@@ -862,7 +835,7 @@ ${c.cyan}Feature Control:${c.reset}
   --enable=<list>     Enable features (comma-separated)
   --disable=<list>    Disable features (comma-separated)
 
-  Features: sessionstart, precompact, stop, archival, statusline
+  Features: sessionstart, precompact, archival, statusline
 
 ${c.cyan}Statusline Components:${c.reset}
   --show=<list>       Show statusline components (comma-separated)
@@ -884,7 +857,7 @@ ${c.cyan}Examples:${c.reset}
   node scripts/agileflow-configure.js --profile=full
 
   # Enable specific features
-  node scripts/agileflow-configure.js --enable=sessionstart,precompact,stop
+  node scripts/agileflow-configure.js --enable=sessionstart,precompact,archival
 
   # Disable a feature
   node scripts/agileflow-configure.js --disable=statusline

package/scripts/agileflow-welcome.js

@@ -86,15 +86,26 @@ function getProjectInfo(rootDir) {
     currentStory: null,
   };
 
-  // Get package info
+  // Get AgileFlow version (check multiple sources in priority order)
+  // 1. AgileFlow metadata (installed user projects)
+  // 2. packages/cli/package.json (AgileFlow dev project)
+  // 3. .agileflow/package.json (fallback)
   try {
-    const pkg = JSON.parse(
-      fs.readFileSync(path.join(rootDir, 'packages/cli/package.json'), 'utf8')
-    );
-    info.version = pkg.version || info.version;
+    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      info.version = metadata.version || info.version;
+    } else {
+      // Dev project: check packages/cli/package.json
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(rootDir, 'packages/cli/package.json'), 'utf8')
+      );
+      info.version = pkg.version || info.version;
+    }
   } catch (e) {
+    // Fallback: check .agileflow/package.json
     try {
-      const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
+      const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, '.agileflow/package.json'), 'utf8'));
       info.version = pkg.version || info.version;
     } catch (e2) {}
   }

package/src/core/templates/agileflow-configure.js

@@ -11,7 +11,7 @@
  *   - RECONFIGURE: Change settings (archival days, etc.)
  *
  * Usage:
- *   node .agileflow/scripts/agileflow-configure.js [options]
+ *   node scripts/agileflow-configure.js [options]
  *
  * Options:
  *   --profile=full|basic|minimal|none   Apply a preset
@@ -23,7 +23,7 @@
  *   --detect                            Show current status
  *   --help                              Show help
  *
- * Features: sessionstart, precompact, stop, archival, statusline
+ * Features: sessionstart, precompact, archival, statusline, autoupdate
  */
 
 const fs = require('fs');
@@ -39,36 +39,46 @@ const VERSION = '2.41.0';
 const FEATURES = {
   sessionstart: { hook: 'SessionStart', script: 'agileflow-welcome.js', type: 'node' },
   precompact: { hook: 'PreCompact', script: 'precompact-context.sh', type: 'bash' },
-  stop: { hook: 'Stop', script: 'agileflow-stop.sh', type: 'bash' },
+  // Note: Stop hook removed due to Claude Code reliability issues (see GitHub issues #6974, #11544)
   archival: { script: 'archive-completed-stories.sh', requiresHook: 'sessionstart' },
-  statusline: { script: 'agileflow-statusline.sh' }
+  statusline: { script: 'agileflow-statusline.sh' },
+  autoupdate: { metadataOnly: true }, // Stored in metadata.updates.autoUpdate
 };
 
 // Statusline component names
-const STATUSLINE_COMPONENTS = ['agileflow', 'model', 'story', 'epic', 'wip', 'context', 'cost', 'git'];
+const STATUSLINE_COMPONENTS = [
+  'agileflow',
+  'model',
+  'story',
+  'epic',
+  'wip',
+  'context',
+  'cost',
+  'git',
+];
 
 const PROFILES = {
   full: {
     description: 'All features enabled',
-    enable: ['sessionstart', 'precompact', 'stop', 'archival', 'statusline'],
-    archivalDays: 7
+    enable: ['sessionstart', 'precompact', 'archival', 'statusline'],
+    archivalDays: 7,
   },
   basic: {
     description: 'Essential hooks + archival (SessionStart + PreCompact + Archival)',
     enable: ['sessionstart', 'precompact', 'archival'],
-    disable: ['stop', 'statusline'],
-    archivalDays: 7
+    disable: ['statusline'],
+    archivalDays: 7,
   },
   minimal: {
     description: 'SessionStart + archival only',
     enable: ['sessionstart', 'archival'],
-    disable: ['precompact', 'stop', 'statusline'],
-    archivalDays: 7
+    disable: ['precompact', 'statusline'],
+    archivalDays: 7,
   },
   none: {
     description: 'Disable all AgileFlow features',
-    disable: ['sessionstart', 'precompact', 'stop', 'archival', 'statusline']
-  }
+    disable: ['sessionstart', 'precompact', 'archival', 'statusline'],
+  },
 };
 
 // ============================================================================
@@ -76,8 +86,13 @@ const PROFILES = {
 // ============================================================================
 
 const c = {
-  reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
-  green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m'
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
 };
 
 const log = (msg, color = '') => console.log(`${color}${msg}${c.reset}`);
@@ -91,11 +106,16 @@ const header = msg => log(`\n${msg}`, c.bold + c.cyan);
 // FILE UTILITIES
 // ============================================================================
 
-const ensureDir = dir => { if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); };
+const ensureDir = dir => {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+};
 
 const readJSON = filePath => {
-  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
-  catch { return null; }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
 };
 
 const writeJSON = (filePath, data) => {
@@ -107,12 +127,14 @@ const copyTemplate = (templateName, destPath) => {
   const sources = [
     path.join(process.cwd(), '.agileflow', 'templates', templateName),
     path.join(__dirname, templateName),
-    path.join(__dirname, '..', 'templates', templateName)
+    path.join(__dirname, '..', 'templates', templateName),
   ];
   for (const src of sources) {
     if (fs.existsSync(src)) {
       fs.copyFileSync(src, destPath);
-      try { fs.chmodSync(destPath, '755'); } catch {}
+      try {
+        fs.chmodSync(destPath, '755');
+      } catch {}
       return true;
     }
   }
@@ -132,18 +154,19 @@ function detectConfig() {
     features: {
       sessionstart: { enabled: false, valid: true, issues: [] },
       precompact: { enabled: false, valid: true, issues: [] },
-      stop: { enabled: false, valid: true, issues: [] },
       archival: { enabled: false, threshold: null },
-      statusline: { enabled: false, valid: true, issues: [] }
+      statusline: { enabled: false, valid: true, issues: [] },
     },
-    metadata: { exists: false, version: null }
+    metadata: { exists: false, version: null },
   };
 
   // Git
   if (fs.existsSync('.git')) {
     status.git.initialized = true;
     try {
-      status.git.remote = execSync('git remote get-url origin 2>/dev/null', { encoding: 'utf8' }).trim();
+      status.git.remote = execSync('git remote get-url origin 2>/dev/null', {
+        encoding: 'utf8',
+      }).trim();
     } catch {}
   }
 
@@ -160,7 +183,10 @@ function detectConfig() {
       if (settings.hooks) {
         // SessionStart
         if (settings.hooks.SessionStart) {
-          if (Array.isArray(settings.hooks.SessionStart) && settings.hooks.SessionStart.length > 0) {
+          if (
+            Array.isArray(settings.hooks.SessionStart) &&
+            settings.hooks.SessionStart.length > 0
+          ) {
             const hook = settings.hooks.SessionStart[0];
             if (hook.matcher !== undefined && hook.hooks) {
               status.features.sessionstart.enabled = true;
@@ -194,23 +220,7 @@ function detectConfig() {
           }
         }
 
-        // Stop
-        if (settings.hooks.Stop) {
-          if (Array.isArray(settings.hooks.Stop) && settings.hooks.Stop.length > 0) {
-            const hook = settings.hooks.Stop[0];
-            if (hook.matcher !== undefined && hook.hooks) {
-              status.features.stop.enabled = true;
-            } else {
-              status.features.stop.enabled = true;
-              status.features.stop.valid = false;
-              status.features.stop.issues.push('Old format - needs migration');
-            }
-          } else if (typeof settings.hooks.Stop === 'string') {
-            status.features.stop.enabled = true;
-            status.features.stop.valid = false;
-            status.features.stop.issues.push('String format - needs migration');
-          }
-        }
+        // Note: Stop hook removed due to reliability issues
       }
 
       // StatusLine
@@ -248,8 +258,10 @@ function printStatus(status) {
   header('📊 Current Configuration');
 
   // Git
-  log(`Git: ${status.git.initialized ? '✅' : '❌'} ${status.git.initialized ? 'initialized' : 'not initialized'}${status.git.remote ? ` (${status.git.remote})` : ''}`,
-    status.git.initialized ? c.green : c.dim);
+  log(
+    `Git: ${status.git.initialized ? '✅' : '❌'} ${status.git.initialized ? 'initialized' : 'not initialized'}${status.git.remote ? ` (${status.git.remote})` : ''}`,
+    status.git.initialized ? c.green : c.dim
+  );
 
   // Settings
   if (!status.settingsExists) {
@@ -284,11 +296,12 @@ function printStatus(status) {
 
   printFeature('sessionstart', 'SessionStart Hook');
   printFeature('precompact', 'PreCompact Hook');
-  printFeature('stop', 'Stop Hook');
 
   const arch = status.features.archival;
-  log(`  ${arch.enabled ? '✅' : '❌'} Archival: ${arch.enabled ? `${arch.threshold} days` : 'disabled'}`,
-    arch.enabled ? c.green : c.dim);
+  log(
+    `  ${arch.enabled ? '✅' : '❌'} Archival: ${arch.enabled ? `${arch.threshold} days` : 'disabled'}`,
+    arch.enabled ? c.green : c.dim
+  );
 
   printFeature('statusline', 'Status Line');
 
@@ -326,19 +339,21 @@ function migrateSettings() {
 
   let migrated = false;
 
-  // Migrate hooks
+  // Migrate hooks (Stop hook removed due to reliability issues)
   if (settings.hooks) {
-    ['SessionStart', 'PreCompact', 'Stop', 'UserPromptSubmit'].forEach(hookName => {
+    ['SessionStart', 'PreCompact', 'UserPromptSubmit'].forEach(hookName => {
       const hook = settings.hooks[hookName];
       if (!hook) return;
 
       // String format → array format
       if (typeof hook === 'string') {
         const isNode = hook.includes('node ') || hook.endsWith('.js');
-        settings.hooks[hookName] = [{
-          matcher: '',
-          hooks: [{ type: 'command', command: isNode ? hook : `bash ${hook}` }]
-        }];
+        settings.hooks[hookName] = [
+          {
+            matcher: '',
+            hooks: [{ type: 'command', command: isNode ? hook : `bash ${hook}` }],
+          },
+        ];
         success(`Migrated ${hookName} from string format`);
         migrated = true;
       }
@@ -348,19 +363,23 @@ function migrateSettings() {
         if (first.enabled !== undefined || first.command !== undefined) {
           // Old format with enabled/command
           if (first.command) {
-            settings.hooks[hookName] = [{
-              matcher: '',
-              hooks: [{ type: 'command', command: first.command }]
-            }];
+            settings.hooks[hookName] = [
+              {
+                matcher: '',
+                hooks: [{ type: 'command', command: first.command }],
+              },
+            ];
             success(`Migrated ${hookName} from old object format`);
             migrated = true;
           }
         } else if (first.matcher === undefined) {
           // Missing matcher
-          settings.hooks[hookName] = [{
-            matcher: '',
-            hooks: first.hooks || [{ type: 'command', command: 'echo "hook"' }]
-          }];
+          settings.hooks[hookName] = [
+            {
+              matcher: '',
+              hooks: first.hooks || [{ type: 'command', command: 'echo "hook"' }],
+            },
+          ];
           success(`Migrated ${hookName} - added matcher`);
           migrated = true;
         }
@@ -374,7 +393,7 @@ function migrateSettings() {
       settings.statusLine = {
         type: 'command',
         command: settings.statusLine,
-        padding: 0
+        padding: 0,
       };
       success('Migrated statusLine from string format');
       migrated = true;
@@ -417,7 +436,7 @@ function enableFeature(feature, options = {}) {
   ensureDir('.claude');
   ensureDir('scripts');
 
-  let settings = readJSON('.claude/settings.json') || {};
+  const settings = readJSON('.claude/settings.json') || {};
   settings.hooks = settings.hooks || {};
   settings.permissions = settings.permissions || { allow: [], deny: [], ask: [] };
 
@@ -429,31 +448,30 @@ function enableFeature(feature, options = {}) {
     if (!copyTemplate(config.script, scriptPath)) {
       // Create minimal version
       if (feature === 'sessionstart') {
-        fs.writeFileSync(scriptPath, `#!/usr/bin/env node\nconsole.log('AgileFlow v${VERSION} loaded');\n`);
+        fs.writeFileSync(
+          scriptPath,
+          `#!/usr/bin/env node\nconsole.log('AgileFlow v${VERSION} loaded');\n`
+        );
       } else if (feature === 'precompact') {
         fs.writeFileSync(scriptPath, '#!/bin/bash\necho "PreCompact: preserving context"\n');
-      } else if (feature === 'stop') {
-        fs.writeFileSync(scriptPath, `#!/bin/bash
-git rev-parse --git-dir > /dev/null 2>&1 || exit 0
-CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-[ "$CHANGES" -gt 0 ] && echo -e "\\n\\033[33m$CHANGES uncommitted change(s)\\033[0m"
-`);
       }
-      try { fs.chmodSync(scriptPath, '755'); } catch {}
+      try {
+        fs.chmodSync(scriptPath, '755');
+      } catch {}
       warn(`Created minimal ${config.script}`);
     } else {
       success(`Deployed ${config.script}`);
     }
 
     // Configure hook
-    const command = config.type === 'node'
-      ? `node ${scriptPath}`
-      : `bash ${scriptPath}`;
-
-    settings.hooks[config.hook] = [{
-      matcher: '',
-      hooks: [{ type: 'command', command }]
-    }];
+    const command = config.type === 'node' ? `node ${scriptPath}` : `bash ${scriptPath}`;
+
+    settings.hooks[config.hook] = [
+      {
+        matcher: '',
+        hooks: [{ type: 'command', command }],
+      },
+    ];
     success(`${config.hook} hook enabled`);
   }
 
@@ -470,13 +488,13 @@ CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
 
     // Add to SessionStart hook
     if (settings.hooks.SessionStart?.[0]?.hooks) {
-      const hasArchival = settings.hooks.SessionStart[0].hooks.some(
-        h => h.command?.includes('archive-completed-stories')
+      const hasArchival = settings.hooks.SessionStart[0].hooks.some(h =>
+        h.command?.includes('archive-completed-stories')
       );
       if (!hasArchival) {
         settings.hooks.SessionStart[0].hooks.push({
           type: 'command',
-          command: 'bash .agileflow/scripts/archive-completed-stories.sh --quiet'
+          command: 'bash scripts/archive-completed-stories.sh --quiet',
         });
       }
     }
@@ -491,12 +509,17 @@ CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
     const scriptPath = 'scripts/agileflow-statusline.sh';
 
     if (!copyTemplate('agileflow-statusline.sh', scriptPath)) {
-      fs.writeFileSync(scriptPath, `#!/bin/bash
+      fs.writeFileSync(
+        scriptPath,
+        `#!/bin/bash
 input=$(cat)
 MODEL=$(echo "$input" | jq -r '.model.display_name // "Claude"')
 echo "[$MODEL] AgileFlow"
-`);
-      try { fs.chmodSync(scriptPath, '755'); } catch {}
+`
+      );
+      try {
+        fs.chmodSync(scriptPath, '755');
+      } catch {}
       warn('Created minimal statusline script');
     } else {
       success('Deployed agileflow-statusline.sh');
@@ -504,14 +527,31 @@ echo "[$MODEL] AgileFlow"
 
     settings.statusLine = {
       type: 'command',
-      command: 'bash .agileflow/scripts/agileflow-statusline.sh',
-      padding: 0
+      command: 'bash scripts/agileflow-statusline.sh',
+      padding: 0,
     };
     success('Status line enabled');
   }
 
+  // Handle autoupdate (metadata only, no hooks needed)
+  if (feature === 'autoupdate') {
+    const frequency = options.checkFrequency || 'daily';
+    updateMetadata({
+      updates: {
+        autoUpdate: true,
+        checkFrequency: frequency,
+        showChangelog: true,
+      },
+    });
+    success(`Auto-update enabled (check frequency: ${frequency})`);
+    info('AgileFlow will automatically update on session start');
+    return true; // Skip settings.json write for this feature
+  }
+
   writeJSON('.claude/settings.json', settings);
-  updateMetadata({ features: { [feature]: { enabled: true, version: VERSION, at: new Date().toISOString() } } });
+  updateMetadata({
+    features: { [feature]: { enabled: true, version: VERSION, at: new Date().toISOString() } },
+  });
   updateGitignore();
 
   return true;
@@ -556,8 +596,21 @@ function disableFeature(feature) {
     success('Status line disabled');
   }
 
+  // Disable autoupdate
+  if (feature === 'autoupdate') {
+    updateMetadata({
+      updates: {
+        autoUpdate: false,
+      },
+    });
+    success('Auto-update disabled');
+    return true; // Skip settings.json write for this feature
+  }
+
   writeJSON('.claude/settings.json', settings);
-  updateMetadata({ features: { [feature]: { enabled: false, version: VERSION, at: new Date().toISOString() } } });
+  updateMetadata({
+    features: { [feature]: { enabled: false, version: VERSION, at: new Date().toISOString() } },
+  });
 
   return true;
 }
@@ -586,6 +639,9 @@ function updateMetadata(updates) {
       meta.features[key] = { ...meta.features[key], ...value };
     });
   }
+  if (updates.updates) {
+    meta.updates = { ...meta.updates, ...updates.updates };
+  }
 
   meta.version = VERSION;
   meta.updated = new Date().toISOString();
@@ -600,7 +656,7 @@ function updateGitignore() {
     '.claude/context.log',
     '.claude/hook.log',
     '.claude/prompt-log.txt',
-    '.claude/session.log'
+    '.claude/session.log',
   ];
 
   let content = fs.existsSync('.gitignore') ? fs.readFileSync('.gitignore', 'utf8') : '';
@@ -718,7 +774,9 @@ function applyProfile(profileName, options = {}) {
 
   // Enable features
   if (profile.enable) {
-    profile.enable.forEach(f => enableFeature(f, { archivalDays: profile.archivalDays || options.archivalDays }));
+    profile.enable.forEach(f =>
+      enableFeature(f, { archivalDays: profile.archivalDays || options.archivalDays })
+    );
   }
 
   // Disable features
@@ -765,7 +823,7 @@ function printHelp() {
 ${c.bold}AgileFlow Configure${c.reset} - Manage AgileFlow features
 
 ${c.cyan}Usage:${c.reset}
-  node .agileflow/scripts/agileflow-configure.js [options]
+  node scripts/agileflow-configure.js [options]
 
 ${c.cyan}Profiles:${c.reset}
   --profile=full      All features (hooks, archival, statusline)
@@ -777,7 +835,7 @@ ${c.cyan}Feature Control:${c.reset}
   --enable=<list>     Enable features (comma-separated)
   --disable=<list>    Disable features (comma-separated)
 
-  Features: sessionstart, precompact, stop, archival, statusline
+  Features: sessionstart, precompact, archival, statusline
 
 ${c.cyan}Statusline Components:${c.reset}
   --show=<list>       Show statusline components (comma-separated)
@@ -796,28 +854,28 @@ ${c.cyan}Maintenance:${c.reset}
 
 ${c.cyan}Examples:${c.reset}
   # Quick setup with all features
-  node .agileflow/scripts/agileflow-configure.js --profile=full
+  node scripts/agileflow-configure.js --profile=full
 
   # Enable specific features
-  node .agileflow/scripts/agileflow-configure.js --enable=sessionstart,precompact,stop
+  node scripts/agileflow-configure.js --enable=sessionstart,precompact,archival
 
   # Disable a feature
-  node .agileflow/scripts/agileflow-configure.js --disable=statusline
+  node scripts/agileflow-configure.js --disable=statusline
 
   # Show only agileflow branding and context in statusline
-  node .agileflow/scripts/agileflow-configure.js --hide=model,story,epic,wip,cost,git
+  node scripts/agileflow-configure.js --hide=model,story,epic,wip,cost,git
 
   # Re-enable git branch in statusline
-  node .agileflow/scripts/agileflow-configure.js --show=git
+  node scripts/agileflow-configure.js --show=git
 
   # List component status
-  node .agileflow/scripts/agileflow-configure.js --components
+  node scripts/agileflow-configure.js --components
 
   # Fix format issues
-  node .agileflow/scripts/agileflow-configure.js --migrate
+  node scripts/agileflow-configure.js --migrate
 
   # Check current status
-  node .agileflow/scripts/agileflow-configure.js --detect
+  node scripts/agileflow-configure.js --detect
 `);
 }
 
@@ -842,10 +900,26 @@ function main() {
 
   args.forEach(arg => {
     if (arg.startsWith('--profile=')) profile = arg.split('=')[1];
-    else if (arg.startsWith('--enable=')) enable = arg.split('=')[1].split(',').map(s => s.trim().toLowerCase());
-    else if (arg.startsWith('--disable=')) disable = arg.split('=')[1].split(',').map(s => s.trim().toLowerCase());
-    else if (arg.startsWith('--show=')) show = arg.split('=')[1].split(',').map(s => s.trim().toLowerCase());
-    else if (arg.startsWith('--hide=')) hide = arg.split('=')[1].split(',').map(s => s.trim().toLowerCase());
+    else if (arg.startsWith('--enable='))
+      enable = arg
+        .split('=')[1]
+        .split(',')
+        .map(s => s.trim().toLowerCase());
+    else if (arg.startsWith('--disable='))
+      disable = arg
+        .split('=')[1]
+        .split(',')
+        .map(s => s.trim().toLowerCase());
+    else if (arg.startsWith('--show='))
+      show = arg
+        .split('=')[1]
+        .split(',')
+        .map(s => s.trim().toLowerCase());
+    else if (arg.startsWith('--hide='))
+      hide = arg
+        .split('=')[1]
+        .split(',')
+        .map(s => s.trim().toLowerCase());
     else if (arg.startsWith('--archival-days=')) archivalDays = parseInt(arg.split('=')[1]) || 7;
     else if (arg === '--migrate') migrate = true;
     else if (arg === '--detect' || arg === '--validate') detect = true;

package/src/core/templates/agileflow-welcome.js

@@ -13,7 +13,18 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
+
+// Session manager path (relative to script location)
+const SESSION_MANAGER_PATH = path.join(__dirname, 'session-manager.js');
+
+// Update checker module
+let updateChecker;
+try {
+  updateChecker = require('./check-update.js');
+} catch (e) {
+  // Update checker not available
+}
 
 // ANSI color codes
 const c = {
@@ -39,9 +50,16 @@ const c = {
 
 // Box drawing characters
 const box = {
-  tl: '╭', tr: '╮', bl: '╰', br: '╯',
-  h: '─', v: '│',
-  lT: '├', rT: '┤', tT: '┬', bT: '┴',
+  tl: '╭',
+  tr: '╮',
+  bl: '╰',
+  br: '╯',
+  h: '─',
+  v: '│',
+  lT: '├',
+  rT: '┤',
+  tT: '┬',
+  bT: '┴',
   cross: '┼',
 };
 
@@ -68,13 +86,26 @@ function getProjectInfo(rootDir) {
     currentStory: null,
   };
 
-  // Get package info
+  // Get AgileFlow version (check multiple sources in priority order)
+  // 1. AgileFlow metadata (installed user projects)
+  // 2. packages/cli/package.json (AgileFlow dev project)
+  // 3. .agileflow/package.json (fallback)
   try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'packages/cli/package.json'), 'utf8'));
-    info.version = pkg.version || info.version;
+    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      info.version = metadata.version || info.version;
+    } else {
+      // Dev project: check packages/cli/package.json
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(rootDir, 'packages/cli/package.json'), 'utf8')
+      );
+      info.version = pkg.version || info.version;
+    }
   } catch (e) {
+    // Fallback: check .agileflow/package.json
     try {
-      const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
+      const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, '.agileflow/package.json'), 'utf8'));
       info.version = pkg.version || info.version;
     } catch (e2) {}
   }
@@ -83,7 +114,10 @@ function getProjectInfo(rootDir) {
   try {
     info.branch = execSync('git branch --show-current', { cwd: rootDir, encoding: 'utf8' }).trim();
     info.commit = execSync('git rev-parse --short HEAD', { cwd: rootDir, encoding: 'utf8' }).trim();
-    info.lastCommit = execSync('git log -1 --format="%s"', { cwd: rootDir, encoding: 'utf8' }).trim();
+    info.lastCommit = execSync('git log -1 --format="%s"', {
+      cwd: rootDir,
+      encoding: 'utf8',
+    }).trim();
   } catch (e) {}
 
   // Get status info
@@ -152,10 +186,10 @@ function runArchival(rootDir) {
     if (toArchiveCount > 0) {
       // Run archival
       try {
-        execSync('bash .agileflow/scripts/archive-completed-stories.sh', {
+        execSync('bash scripts/archive-completed-stories.sh', {
           cwd: rootDir,
           encoding: 'utf8',
-          stdio: 'pipe'
+          stdio: 'pipe',
         });
         result.archived = toArchiveCount;
         result.remaining -= toArchiveCount;
@@ -201,6 +235,60 @@ function clearActiveCommands(rootDir) {
   return result;
 }
 
+function checkParallelSessions(rootDir) {
+  const result = {
+    available: false,
+    registered: false,
+    otherActive: 0,
+    currentId: null,
+    cleaned: 0,
+  };
+
+  try {
+    // Check if session manager exists
+    const managerPath = path.join(rootDir, '.agileflow', 'scripts', 'session-manager.js');
+    if (!fs.existsSync(managerPath) && !fs.existsSync(SESSION_MANAGER_PATH)) {
+      return result;
+    }
+
+    result.available = true;
+
+    // Try to register current session and get status
+    const scriptPath = fs.existsSync(managerPath) ? managerPath : SESSION_MANAGER_PATH;
+
+    // Register this session
+    try {
+      const registerOutput = execSync(`node "${scriptPath}" register`, {
+        cwd: rootDir,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const registerData = JSON.parse(registerOutput);
+      result.registered = true;
+      result.currentId = registerData.id;
+    } catch (e) {
+      // Registration failed, continue anyway
+    }
+
+    // Get count of other active sessions
+    try {
+      const countOutput = execSync(`node "${scriptPath}" count`, {
+        cwd: rootDir,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const countData = JSON.parse(countOutput);
+      result.otherActive = countData.count || 0;
+    } catch (e) {
+      // Count failed
+    }
+  } catch (e) {
+    // Session system not available
+  }
+
+  return result;
+}
+
 function checkPreCompact(rootDir) {
   const result = { configured: false, scriptExists: false, version: null, outdated: false };
 
@@ -253,12 +341,104 @@ function compareVersions(a, b) {
   return 0;
 }
 
+// Check for updates (async but we'll use sync approach for welcome)
+async function checkUpdates() {
+  const result = {
+    available: false,
+    installed: null,
+    latest: null,
+    justUpdated: false,
+    previousVersion: null,
+    autoUpdate: false,
+    changelog: [],
+  };
+
+  if (!updateChecker) return result;
+
+  try {
+    const updateInfo = await updateChecker.checkForUpdates();
+    result.installed = updateInfo.installed;
+    result.latest = updateInfo.latest;
+    result.available = updateInfo.updateAvailable;
+    result.justUpdated = updateInfo.justUpdated;
+    result.previousVersion = updateInfo.previousVersion;
+    result.autoUpdate = updateInfo.autoUpdate;
+
+    // If just updated, try to get changelog entries
+    if (result.justUpdated && result.installed) {
+      result.changelog = getChangelogEntries(result.installed);
+    }
+  } catch (e) {
+    // Silently fail - update check is non-critical
+  }
+
+  return result;
+}
+
+// Parse CHANGELOG.md for entries of a specific version
+function getChangelogEntries(version) {
+  const entries = [];
+
+  try {
+    // Look for CHANGELOG.md in .agileflow or package location
+    const possiblePaths = [
+      path.join(__dirname, '..', 'CHANGELOG.md'),
+      path.join(__dirname, 'CHANGELOG.md'),
+    ];
+
+    let changelogContent = null;
+    for (const p of possiblePaths) {
+      if (fs.existsSync(p)) {
+        changelogContent = fs.readFileSync(p, 'utf8');
+        break;
+      }
+    }
+
+    if (!changelogContent) return entries;
+
+    // Find the section for this version
+    const versionPattern = new RegExp(`## \\[${version}\\].*?\\n([\\s\\S]*?)(?=## \\[|$)`);
+    const match = changelogContent.match(versionPattern);
+
+    if (match) {
+      // Extract bullet points from Added/Changed/Fixed sections
+      const lines = match[1].split('\n');
+      for (const line of lines) {
+        const bulletMatch = line.match(/^- (.+)$/);
+        if (bulletMatch && entries.length < 3) {
+          entries.push(bulletMatch[1]);
+        }
+      }
+    }
+  } catch (e) {
+    // Silently fail
+  }
+
+  return entries;
+}
+
+// Run auto-update if enabled
+async function runAutoUpdate(rootDir) {
+  try {
+    console.log(`${c.cyan}Updating AgileFlow...${c.reset}`);
+    execSync('npx agileflow update', {
+      cwd: rootDir,
+      encoding: 'utf8',
+      stdio: 'inherit',
+    });
+    return true;
+  } catch (e) {
+    console.log(`${c.yellow}Auto-update failed. Run manually: npx agileflow update${c.reset}`);
+    return false;
+  }
+}
+
 function getFeatureVersions(rootDir) {
   const result = {
     hooks: { version: null, outdated: false },
     archival: { version: null, outdated: false },
     statusline: { version: null, outdated: false },
-    precompact: { version: null, outdated: false }
+    precompact: { version: null, outdated: false },
   };
 
   // Minimum compatible versions for each feature
@@ -266,7 +446,7 @@ function getFeatureVersions(rootDir) {
     hooks: '2.35.0',
     archival: '2.35.0',
     statusline: '2.35.0',
-    precompact: '2.40.0'  // Multi-command support
+    precompact: '2.40.0', // Multi-command support
   };
 
   try {
@@ -277,7 +457,8 @@ function getFeatureVersions(rootDir) {
       for (const feature of Object.keys(result)) {
         if (metadata.features?.[feature]?.configured_version) {
           result[feature].version = metadata.features[feature].configured_version;
-          result[feature].outdated = compareVersions(result[feature].version, minVersions[feature]) < 0;
+          result[feature].outdated =
+            compareVersions(result[feature].version, minVersions[feature]) < 0;
         }
       }
     }
@@ -291,7 +472,8 @@ function pad(str, len, align = 'left') {
   const diff = len - stripped.length;
   if (diff <= 0) return str;
   if (align === 'right') return ' '.repeat(diff) + str;
-  if (align === 'center') return ' '.repeat(Math.floor(diff/2)) + str + ' '.repeat(Math.ceil(diff/2));
+  if (align === 'center')
+    return ' '.repeat(Math.floor(diff / 2)) + str + ' '.repeat(Math.ceil(diff / 2));
   return str + ' '.repeat(diff);
 }
 
@@ -323,7 +505,7 @@ function truncate(str, maxLen, suffix = '..') {
   return str.substring(0, cutIndex) + suffix;
 }
 
-function formatTable(info, archival, session, precompact) {
+function formatTable(info, archival, session, precompact, parallelSessions, updateInfo = {}) {
   const W = 58; // inner width
   const R = W - 24; // right column width (34 chars)
   const lines = [];
@@ -336,29 +518,101 @@ function formatTable(info, archival, session, precompact) {
     return `${c.dim}${box.v}${c.reset} ${pad(leftStr, 20)} ${c.dim}${box.v}${c.reset} ${pad(rightStr, R)} ${c.dim}${box.v}${c.reset}`;
   };
 
-  const divider = () => `${c.dim}${box.lT}${box.h.repeat(22)}${box.cross}${box.h.repeat(W - 22)}${box.rT}${c.reset}`;
+  // Helper for full-width row (spans both columns)
+  const fullRow = (content, color = '') => {
+    const contentStr = `${color}${content}${color ? c.reset : ''}`;
+    return `${c.dim}${box.v}${c.reset} ${pad(contentStr, W - 1)} ${c.dim}${box.v}${c.reset}`;
+  };
+
+  const divider = () =>
+    `${c.dim}${box.lT}${box.h.repeat(22)}${box.cross}${box.h.repeat(W - 22)}${box.rT}${c.reset}`;
+  const fullDivider = () =>
+    `${c.dim}${box.lT}${box.h.repeat(W)}${box.rT}${c.reset}`;
   const topBorder = `${c.dim}${box.tl}${box.h.repeat(22)}${box.tT}${box.h.repeat(W - 22)}${box.tr}${c.reset}`;
   const bottomBorder = `${c.dim}${box.bl}${box.h.repeat(22)}${box.bT}${box.h.repeat(W - 22)}${box.br}${c.reset}`;
 
-  // Header (truncate branch name if too long)
-  const branchColor = info.branch === 'main' ? c.green : info.branch.startsWith('fix') ? c.red : c.cyan;
-  // Fixed parts: "agileflow " (10) + "v" (1) + version + "  " (2) + " (" (2) + commit (7) + ")" (1) = 23 + version.length
-  const maxBranchLen = (W - 1) - 23 - info.version.length;
-  const branchDisplay = info.branch.length > maxBranchLen
-    ? info.branch.substring(0, maxBranchLen - 2) + '..'
-    : info.branch;
-  const header = `${c.brand}${c.bold}agileflow${c.reset} ${c.dim}v${info.version}${c.reset}  ${branchColor}${branchDisplay}${c.reset} ${c.dim}(${info.commit})${c.reset}`;
+  // Header with version and optional update indicator
+  const branchColor =
+    info.branch === 'main' ? c.green : info.branch.startsWith('fix') ? c.red : c.cyan;
+
+  // Build version string with update status
+  let versionStr = `v${info.version}`;
+  if (updateInfo.justUpdated && updateInfo.previousVersion) {
+    versionStr = `v${info.version} ${c.green}✓${c.reset}${c.dim} (was v${updateInfo.previousVersion})`;
+  } else if (updateInfo.available && updateInfo.latest) {
+    versionStr = `v${info.version} ${c.yellow}↑${updateInfo.latest}${c.reset}`;
+  }
+
+  // Calculate remaining space for branch
+  const versionVisibleLen = updateInfo.justUpdated
+    ? info.version.length + 20 + (updateInfo.previousVersion?.length || 0)
+    : updateInfo.available
+      ? info.version.length + 3 + (updateInfo.latest?.length || 0)
+      : info.version.length;
+  const maxBranchLen = W - 1 - 15 - versionVisibleLen;
+  const branchDisplay =
+    info.branch.length > maxBranchLen
+      ? info.branch.substring(0, Math.max(5, maxBranchLen - 2)) + '..'
+      : info.branch;
+
+  const header = `${c.brand}${c.bold}agileflow${c.reset} ${c.dim}${versionStr}${c.reset}  ${branchColor}${branchDisplay}${c.reset} ${c.dim}(${info.commit})${c.reset}`;
   const headerLine = `${c.dim}${box.v}${c.reset} ${pad(header, W - 1)} ${c.dim}${box.v}${c.reset}`;
 
   lines.push(topBorder);
   lines.push(headerLine);
+
+  // Show update available notification
+  if (updateInfo.available && updateInfo.latest && !updateInfo.justUpdated) {
+    lines.push(fullDivider());
+    lines.push(fullRow(`↑ Update available: v${updateInfo.latest}`, c.yellow));
+    lines.push(fullRow(`  Run: npx agileflow update`, c.dim));
+  }
+
+  // Show "just updated" changelog
+  if (updateInfo.justUpdated && updateInfo.changelog && updateInfo.changelog.length > 0) {
+    lines.push(fullDivider());
+    lines.push(fullRow(`What's new in v${info.version}:`, c.green));
+    for (const entry of updateInfo.changelog.slice(0, 2)) {
+      lines.push(fullRow(`• ${truncate(entry, W - 4)}`, c.dim));
+    }
+    lines.push(fullRow(`Run /agileflow:whats-new for full changelog`, c.dim));
+  }
+
   lines.push(divider());
 
   // Stories section
-  lines.push(row('In Progress', info.wipCount > 0 ? `${info.wipCount}` : '0', c.dim, info.wipCount > 0 ? c.yellow : c.dim));
-  lines.push(row('Blocked', info.blockedCount > 0 ? `${info.blockedCount}` : '0', c.dim, info.blockedCount > 0 ? c.red : c.dim));
-  lines.push(row('Ready', info.readyCount > 0 ? `${info.readyCount}` : '0', c.dim, info.readyCount > 0 ? c.cyan : c.dim));
-  lines.push(row('Completed', info.completedCount > 0 ? `${info.completedCount}` : '0', c.dim, info.completedCount > 0 ? c.green : c.dim));
+  lines.push(
+    row(
+      'In Progress',
+      info.wipCount > 0 ? `${info.wipCount}` : '0',
+      c.dim,
+      info.wipCount > 0 ? c.yellow : c.dim
+    )
+  );
+  lines.push(
+    row(
+      'Blocked',
+      info.blockedCount > 0 ? `${info.blockedCount}` : '0',
+      c.dim,
+      info.blockedCount > 0 ? c.red : c.dim
+    )
+  );
+  lines.push(
+    row(
+      'Ready',
+      info.readyCount > 0 ? `${info.readyCount}` : '0',
+      c.dim,
+      info.readyCount > 0 ? c.cyan : c.dim
+    )
+  );
+  lines.push(
+    row(
+      'Completed',
+      info.completedCount > 0 ? `${info.completedCount}` : '0',
+      c.dim,
+      info.completedCount > 0 ? c.green : c.dim
+    )
+  );
 
   lines.push(divider());
 
@@ -366,16 +620,15 @@ function formatTable(info, archival, session, precompact) {
   if (archival.disabled) {
     lines.push(row('Auto-archival', 'disabled', c.dim, c.dim));
   } else {
-    const archivalStatus = archival.archived > 0
-      ? `archived ${archival.archived} stories`
-      : `nothing to archive`;
-    lines.push(row('Auto-archival', archivalStatus, c.dim, archival.archived > 0 ? c.green : c.dim));
+    const archivalStatus =
+      archival.archived > 0 ? `archived ${archival.archived} stories` : `nothing to archive`;
+    lines.push(
+      row('Auto-archival', archivalStatus, c.dim, archival.archived > 0 ? c.green : c.dim)
+    );
   }
 
   // Session cleanup
-  const sessionStatus = session.cleared > 0
-    ? `cleared ${session.cleared} command(s)`
-    : `clean`;
+  const sessionStatus = session.cleared > 0 ? `cleared ${session.cleared} command(s)` : `clean`;
   lines.push(row('Session state', sessionStatus, c.dim, session.cleared > 0 ? c.green : c.dim));
 
   // PreCompact status with version check
@@ -396,11 +649,31 @@ function formatTable(info, archival, session, precompact) {
     lines.push(row('Context preserve', 'not configured', c.dim, c.dim));
   }
 
+  // Parallel sessions status
+  if (parallelSessions && parallelSessions.available) {
+    if (parallelSessions.otherActive > 0) {
+      const sessionStr = `⚠️ ${parallelSessions.otherActive} other active`;
+      lines.push(row('Sessions', sessionStr, c.dim, c.yellow));
+    } else {
+      const sessionStr = parallelSessions.currentId
+        ? `✓ Session ${parallelSessions.currentId} (only)`
+        : '✓ Only session';
+      lines.push(row('Sessions', sessionStr, c.dim, c.green));
+    }
+  }
+
   lines.push(divider());
 
   // Current story (if any) - row() auto-truncates
   if (info.currentStory) {
-    lines.push(row('Current', `${c.blue}${info.currentStory.id}${c.reset}: ${info.currentStory.title}`, c.dim, ''));
+    lines.push(
+      row(
+        'Current',
+        `${c.blue}${info.currentStory.id}${c.reset}: ${info.currentStory.title}`,
+        c.dim,
+        ''
+      )
+    );
   } else {
     lines.push(row('Current', 'No active story', c.dim, c.dim));
   }
@@ -414,14 +687,45 @@ function formatTable(info, archival, session, precompact) {
 }
 
 // Main
-function main() {
+async function main() {
   const rootDir = getProjectRoot();
   const info = getProjectInfo(rootDir);
   const archival = runArchival(rootDir);
   const session = clearActiveCommands(rootDir);
   const precompact = checkPreCompact(rootDir);
+  const parallelSessions = checkParallelSessions(rootDir);
 
-  console.log(formatTable(info, archival, session, precompact));
+  // Check for updates (async, cached)
+  let updateInfo = {};
+  try {
+    updateInfo = await checkUpdates();
+
+    // If auto-update is enabled and update available, run it
+    if (updateInfo.available && updateInfo.autoUpdate) {
+      const updated = await runAutoUpdate(rootDir);
+      if (updated) {
+        // Re-run welcome after update (the new version will show changelog)
+        return;
+      }
+    }
+
+    // Mark current version as seen to track for next update
+    if (updateInfo.justUpdated && updateChecker) {
+      updateChecker.markVersionSeen(info.version);
+    }
+  } catch (e) {
+    // Update check failed - continue without it
+  }
+
+  console.log(formatTable(info, archival, session, precompact, parallelSessions, updateInfo));
+
+  // Show warning and tip if other sessions are active
+  if (parallelSessions.otherActive > 0) {
+    console.log('');
+    console.log(`${c.yellow}⚠️  Other Claude session(s) active in this repo.${c.reset}`);
+    console.log(`${c.dim}   Run /agileflow:session:status to see all sessions.${c.reset}`);
+    console.log(`${c.dim}   Run /agileflow:session:new to create isolated workspace.${c.reset}`);
+  }
 }
 
-main();
+main().catch(console.error);

package/tools/cli/commands/update.js

@@ -105,15 +105,20 @@ module.exports = {
       // Check if CLI itself is still outdated (only if self-update was disabled)
       if (npmLatestVersion && semver.lt(localCliVersion, npmLatestVersion) && !shouldSelfUpdate) {
         console.log();
-        warning('Your CLI is outdated!');
-        console.log(chalk.dim(`  To update your installation, run:\n`));
-        console.log(chalk.cyan(`  npx agileflow@latest update\n`));
+        warning('Your global CLI is outdated!');
+        console.log(
+          chalk.dim(`  You have a global installation at v${localCliVersion}, but v${npmLatestVersion} is available.\n`)
+        );
+        console.log(chalk.dim(`  Options:`));
+        console.log(chalk.dim(`  1. Cancel and run: `) + chalk.cyan(`npx agileflow@latest update`));
+        console.log(chalk.dim(`  2. Remove global:  `) + chalk.cyan(`npm uninstall -g agileflow`) + chalk.dim(` (recommended)`));
+        console.log(chalk.dim(`  3. Update global:  `) + chalk.cyan(`npm install -g agileflow@latest\n`));
 
         const useOutdated = options.force
           ? true
           : await confirm('Continue with outdated CLI anyway?');
         if (!useOutdated) {
-          console.log(chalk.dim('\nUpdate cancelled\n'));
+          console.log(chalk.dim('\nUpdate cancelled. Run: npx agileflow@latest update\n'));
           process.exit(0);
         }
       }
@@ -209,6 +214,19 @@ module.exports = {
 
       console.log(chalk.green(`\n✨ Update complete! (${status.version} → ${latestVersion})\n`));
 
+      // If running from outdated global installation, remind user to update it
+      if (
+        npmLatestVersion &&
+        semver.lt(localCliVersion, npmLatestVersion) &&
+        !options.selfUpdated
+      ) {
+        console.log(chalk.yellow('💡 Tip: Your global AgileFlow CLI is outdated.'));
+        console.log(chalk.dim('   To avoid this message, either:'));
+        console.log(chalk.dim('   • Remove global: npm uninstall -g agileflow (recommended)'));
+        console.log(chalk.dim('   • Use npx:       npx agileflow@latest update'));
+        console.log(chalk.dim('   • Update global: npm install -g agileflow@latest\n'));
+      }
+
       process.exit(0);
     } catch (err) {
       console.error(chalk.red('Update failed:'), err.message);

package/scripts/agileflow-stop.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-# agileflow-stop.sh - Session wrap-up hook
-
-# Only run if we're in a git repo
-git rev-parse --git-dir > /dev/null 2>&1 || exit 0
-
-# Check for uncommitted changes
-CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-
-if [ "$CHANGES" -gt 0 ]; then
-  echo ""
-  echo -e "\033[0;33m$CHANGES uncommitted change(s)\033[0m"
-fi

package/src/core/templates/agileflow-stop.sh

@@ -1,13 +0,0 @@
-#!/bin/bash
-# agileflow-stop.sh - Session wrap-up hook
-
-# Only run if we're in a git repo
-git rev-parse --git-dir > /dev/null 2>&1 || exit 0
-
-# Check for uncommitted changes
-CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
-
-if [ "$CHANGES" -gt 0 ]; then
-  echo ""
-  echo -e "\033[0;33m$CHANGES uncommitted change(s)\033[0m"
-fi