agileflow 2.55.0 → 2.57.0

package/README.md

@@ -4,9 +4,8 @@
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
 [![Commands](https://img.shields.io/badge/commands-41-blue)](docs/04-architecture/commands.md)
-[![Subagents](https://img.shields.io/badge/subagents-26-orange)](docs/04-architecture/subagents.md)
+[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-26-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-23-purple)](docs/04-architecture/skills.md)
-[![Experts](https://img.shields.io/badge/experts-26-green)](docs/04-architecture/agent-expert-system.md)
 
 **AI-driven agile development for Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and more.** Combining Scrum, Kanban, ADRs, and docs-as-code principles into one framework-agnostic system.
 
@@ -68,9 +67,8 @@ AgileFlow combines three proven methodologies:
 | Component | Count | Description |
 |-----------|-------|-------------|
 | [Commands](docs/04-architecture/commands.md) | 41 | Slash commands for agile workflows |
-| [Subagents](docs/04-architecture/subagents.md) | 26 | Specialized agents for focused work |
+| [Agents/Experts](docs/04-architecture/subagents.md) | 26 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | 23 | Auto-activated context helpers |
-| [Experts](docs/04-architecture/agent-expert-system.md) | 26 | Self-improving knowledge bases |
 
 ---
 
@@ -80,7 +78,7 @@ Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
 - [Commands](docs/04-architecture/commands.md) - All 41 slash commands
-- [Subagents](docs/04-architecture/subagents.md) - All 26 specialized agents
+- [Agents/Experts](docs/04-architecture/subagents.md) - 26 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - 23 auto-loaded skills
 
 ### Architecture

package/package.json

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

package/scripts/agileflow-welcome.js

@@ -18,6 +18,14 @@ 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 = {
   reset: '\x1b[0m',
@@ -322,6 +330,98 @@ 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 },
@@ -394,7 +494,7 @@ function truncate(str, maxLen, suffix = '..') {
   return str.substring(0, cutIndex) + suffix;
 }
 
-function formatTable(info, archival, session, precompact, parallelSessions) {
+function formatTable(info, archival, session, precompact, parallelSessions, updateInfo = {}) {
   const W = 58; // inner width
   const R = W - 24; // right column width (34 chars)
   const lines = [];
@@ -407,25 +507,66 @@ function formatTable(info, archival, session, precompact, parallelSessions) {
     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}`;
   };
 
+  // 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)
+  // Header with version and optional update indicator
   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;
+
+  // 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, maxBranchLen - 2) + '..'
+      ? info.branch.substring(0, Math.max(5, 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}`;
+
+  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
@@ -535,7 +676,7 @@ function formatTable(info, archival, session, precompact, parallelSessions) {
 }
 
 // Main
-function main() {
+async function main() {
   const rootDir = getProjectRoot();
   const info = getProjectInfo(rootDir);
   const archival = runArchival(rootDir);
@@ -543,7 +684,29 @@ function main() {
   const precompact = checkPreCompact(rootDir);
   const parallelSessions = checkParallelSessions(rootDir);
 
-  console.log(formatTable(info, archival, session, precompact, parallelSessions));
+  // 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) {
@@ -554,4 +717,4 @@ function main() {
   }
 }
 
-main();
+main().catch(console.error);

package/scripts/check-update.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * check-update.js - Check for AgileFlow updates with caching
+ *
+ * Features:
+ * - Checks npm registry for latest version
+ * - Caches results to avoid excessive requests
+ * - Configurable check frequency (hourly, daily, weekly)
+ * - Returns structured JSON for easy parsing
+ *
+ * Usage:
+ *   node check-update.js [--force] [--json]
+ *
+ * Options:
+ *   --force  Bypass cache and check npm directly
+ *   --json   Output as JSON (default is human-readable)
+ *
+ * Environment:
+ *   DEBUG_UPDATE=1  Enable debug logging
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+// Debug mode
+const DEBUG = process.env.DEBUG_UPDATE === '1';
+
+function debugLog(message, data = null) {
+  if (DEBUG) {
+    console.error(`[check-update] ${message}`, data ? JSON.stringify(data) : '');
+  }
+}
+
+// Find project root (has .agileflow directory)
+function getProjectRoot() {
+  let dir = process.cwd();
+  while (!fs.existsSync(path.join(dir, '.agileflow')) && dir !== '/') {
+    dir = path.dirname(dir);
+  }
+  return dir !== '/' ? dir : process.cwd();
+}
+
+// Get installed AgileFlow version
+function getInstalledVersion(rootDir) {
+  // First check .agileflow/package.json (installed version)
+  const agileflowPkg = path.join(rootDir, '.agileflow', 'package.json');
+  if (fs.existsSync(agileflowPkg)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(agileflowPkg, 'utf8'));
+      if (pkg.version) return pkg.version;
+    } catch (e) {
+      debugLog('Error reading .agileflow/package.json', e.message);
+    }
+  }
+
+  // Fallback: check if this is the AgileFlow dev repo
+  const cliPkg = path.join(rootDir, 'packages/cli/package.json');
+  if (fs.existsSync(cliPkg)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(cliPkg, 'utf8'));
+      if (pkg.name === 'agileflow' && pkg.version) return pkg.version;
+    } catch (e) {}
+  }
+
+  return null;
+}
+
+// Get update configuration from metadata
+function getUpdateConfig(rootDir) {
+  const defaults = {
+    autoUpdate: false,
+    checkFrequency: 'daily', // hourly, daily, weekly, never
+    showChangelog: true,
+    lastCheck: null,
+    lastSeenVersion: null,
+    latestVersion: null,
+  };
+
+  try {
+    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      if (metadata.updates) {
+        return { ...defaults, ...metadata.updates };
+      }
+    }
+  } catch (e) {
+    debugLog('Error reading update config', e.message);
+  }
+
+  return defaults;
+}
+
+// Save update configuration
+function saveUpdateConfig(rootDir, config) {
+  try {
+    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+    let metadata = {};
+
+    if (fs.existsSync(metadataPath)) {
+      metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    }
+
+    metadata.updates = config;
+    fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n');
+    return true;
+  } catch (e) {
+    debugLog('Error saving update config', e.message);
+    return false;
+  }
+}
+
+// Check if cache is still valid
+function isCacheValid(config) {
+  if (!config.lastCheck) return false;
+
+  const now = Date.now();
+  const lastCheck = new Date(config.lastCheck).getTime();
+  const age = now - lastCheck;
+
+  // Convert frequency to milliseconds
+  const frequencies = {
+    hourly: 60 * 60 * 1000, // 1 hour
+    daily: 24 * 60 * 60 * 1000, // 24 hours
+    weekly: 7 * 24 * 60 * 60 * 1000, // 7 days
+    never: Infinity,
+  };
+
+  const maxAge = frequencies[config.checkFrequency] || frequencies.daily;
+
+  debugLog('Cache check', {
+    lastCheck: config.lastCheck,
+    ageMs: age,
+    maxAgeMs: maxAge,
+    valid: age < maxAge,
+  });
+
+  return age < maxAge;
+}
+
+// Fetch latest version from npm
+async function fetchLatestVersion() {
+  return new Promise(resolve => {
+    const options = {
+      hostname: 'registry.npmjs.org',
+      port: 443,
+      path: '/agileflow/latest',
+      method: 'GET',
+      headers: {
+        'User-Agent': 'agileflow-cli',
+      },
+    };
+
+    debugLog('Fetching from npm registry');
+
+    const req = https.request(options, res => {
+      let data = '';
+
+      res.on('data', chunk => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          debugLog('Non-200 status', { statusCode: res.statusCode });
+          return resolve(null);
+        }
+
+        try {
+          const json = JSON.parse(data);
+          debugLog('Version found', { version: json.version });
+          resolve(json.version || null);
+        } catch (err) {
+          debugLog('JSON parse error', err.message);
+          resolve(null);
+        }
+      });
+    });
+
+    req.on('error', err => {
+      debugLog('Network error', err.message);
+      resolve(null);
+    });
+
+    req.setTimeout(5000, () => {
+      debugLog('Request timeout');
+      req.destroy();
+      resolve(null);
+    });
+
+    req.end();
+  });
+}
+
+// Compare semantic versions: returns -1 if a < b, 0 if equal, 1 if a > b
+function compareVersions(a, b) {
+  if (!a || !b) return 0;
+  const partsA = a.split('.').map(Number);
+  const partsB = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const numA = partsA[i] || 0;
+    const numB = partsB[i] || 0;
+    if (numA < numB) return -1;
+    if (numA > numB) return 1;
+  }
+  return 0;
+}
+
+// Main check function
+async function checkForUpdates(options = {}) {
+  const rootDir = getProjectRoot();
+  const installedVersion = getInstalledVersion(rootDir);
+  const config = getUpdateConfig(rootDir);
+
+  const result = {
+    installed: installedVersion,
+    latest: null,
+    updateAvailable: false,
+    autoUpdate: config.autoUpdate,
+    justUpdated: false,
+    previousVersion: config.lastSeenVersion,
+    fromCache: false,
+    error: null,
+  };
+
+  // No installed version found
+  if (!installedVersion) {
+    result.error = 'Could not determine installed version';
+    return result;
+  }
+
+  // Check if we just updated (lastSeenVersion < installed)
+  if (
+    config.lastSeenVersion &&
+    compareVersions(config.lastSeenVersion, installedVersion) < 0
+  ) {
+    result.justUpdated = true;
+    result.previousVersion = config.lastSeenVersion;
+  }
+
+  // Use cache if valid and not forced
+  if (!options.force && isCacheValid(config) && config.latestVersion) {
+    result.latest = config.latestVersion;
+    result.fromCache = true;
+  } else if (config.checkFrequency !== 'never') {
+    // Fetch from npm
+    result.latest = await fetchLatestVersion();
+
+    // Update cache
+    if (result.latest) {
+      config.lastCheck = new Date().toISOString();
+      config.latestVersion = result.latest;
+      saveUpdateConfig(rootDir, config);
+    }
+  }
+
+  // Compare versions
+  if (result.latest && compareVersions(installedVersion, result.latest) < 0) {
+    result.updateAvailable = true;
+  }
+
+  return result;
+}
+
+// Mark version as seen (after update or dismissal)
+function markVersionSeen(version) {
+  const rootDir = getProjectRoot();
+  const config = getUpdateConfig(rootDir);
+  config.lastSeenVersion = version;
+  saveUpdateConfig(rootDir, config);
+}
+
+// CLI interface
+async function main() {
+  const args = process.argv.slice(2);
+  const force = args.includes('--force');
+  const jsonOutput = args.includes('--json');
+  const markSeen = args.includes('--mark-seen');
+
+  if (markSeen) {
+    const version = args[args.indexOf('--mark-seen') + 1];
+    if (version) {
+      markVersionSeen(version);
+      if (jsonOutput) {
+        console.log(JSON.stringify({ success: true, version }));
+      } else {
+        console.log(`Marked version ${version} as seen`);
+      }
+    }
+    return;
+  }
+
+  const result = await checkForUpdates({ force });
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (result.error) {
+      console.log(`Error: ${result.error}`);
+    } else if (result.justUpdated) {
+      console.log(`Updated from v${result.previousVersion} to v${result.installed}`);
+    } else if (result.updateAvailable) {
+      console.log(`Update available: v${result.installed} -> v${result.latest}`);
+      console.log(`Run: npx agileflow update`);
+    } else {
+      console.log(`AgileFlow v${result.installed} is up to date`);
+    }
+  }
+}
+
+// Export for use as module
+module.exports = {
+  checkForUpdates,
+  markVersionSeen,
+  getUpdateConfig,
+  saveUpdateConfig,
+  compareVersions,
+};
+
+// Run CLI if executed directly
+if (require.main === module) {
+  main().catch(console.error);
+}