agileflow 2.94.1 → 2.95.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.95.0] - 2026-01-30
+
+### Added
+- Global session management commands (status, history, cleanup)
+- `/agileflow:install` and `/agileflow:maintain` commands for quick setup
+- Multi-expert Implementation Ideation in `/research:import` and `/research:analyze`
+- Plan file context preservation with experimental profile
+- Tmux freeze recovery keybinds and `--rescue` flag
+- Shellcheck CI job for shell script linting
+
+### Fixed
+- Prevent worktree sessions from being marked as main
+- Prevent duplicate agents during install/update
+- Inline uncommitted changes handling for `/session:end`
+
 ## [2.94.1] - 2026-01-24
 
 ### Added

package/lib/colors.generated.js

@@ -0,0 +1,117 @@
+/**
+ * colors.generated.js - Auto-generated from config/colors.yaml
+ *
+ * DO NOT EDIT THIS FILE DIRECTLY.
+ * Run: node scripts/generate-colors.js
+ *
+ * Generated: 2026-01-29T08:28:33.726Z
+ */
+
+'use strict';
+
+// Brand color
+const BRAND_HEX = '#e8683a';
+
+// Modifiers
+const modifiers = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+};
+
+// Standard ANSI colors
+const standard = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  black: '\x1b[30m',
+};
+
+// Bright ANSI colors
+const bright = {
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+  brightBlack: '\x1b[90m',
+};
+
+// 256-color palette
+const palette256 = {
+  mintGreen: '\x1b[38;5;158m', // Healthy/success states
+  peach: '\x1b[38;5;215m', // Warning states
+  coral: '\x1b[38;5;203m', // Critical/error states
+  lightGreen: '\x1b[38;5;194m', // Session healthy
+  lightYellow: '\x1b[38;5;228m', // Session warning
+  lightPink: '\x1b[38;5;210m', // Session critical
+  skyBlue: '\x1b[38;5;117m', // Directories/paths, ready states
+  lavender: '\x1b[38;5;147m', // Model info, story IDs
+  softGold: '\x1b[38;5;222m', // Cost/money
+  teal: '\x1b[38;5;80m', // Pending states
+  slate: '\x1b[38;5;103m', // Secondary info
+  rose: '\x1b[38;5;211m', // Blocked/critical accent
+  amber: '\x1b[38;5;214m', // WIP/in-progress accent
+  powder: '\x1b[38;5;153m', // Labels/headers
+};
+
+// Background colors
+const backgrounds = {
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+};
+
+// Brand color ANSI
+const brand = '\x1b[38;2;232;104;58m';
+
+// High-contrast mode colors (WCAG AAA)
+const highContrast = {
+  red: '\x1b[91m',
+  green: '\x1b[92m',
+  yellow: '\x1b[93m',
+  blue: '\x1b[94m',
+  magenta: '\x1b[95m',
+  cyan: '\x1b[96m',
+  white: '\x1b[97m',
+  dim: '\x1b[0m',
+  brightBlack: '\x1b[37m',
+  brand: '\x1b[38;2;255;165;0m',
+};
+
+// Combined standard color palette
+const cStandard = {
+  ...modifiers,
+  ...standard,
+  ...bright,
+  ...palette256,
+  ...backgrounds,
+  brand,
+  orange: brand, // Alias
+  // Semantic aliases
+  success: standard.green,
+  error: standard.red,
+  warning: standard.yellow,
+  info: standard.cyan,
+};
+
+module.exports = {
+  BRAND_HEX,
+  modifiers,
+  standard,
+  bright,
+  palette256,
+  backgrounds,
+  brand,
+  highContrast,
+  cStandard,
+};

package/lib/colors.js

@@ -4,6 +4,9 @@
  * Centralized ANSI color codes and formatting helpers.
  * Uses 256-color palette for modern terminal support.
  *
+ * Color definitions are generated from config/colors.yaml.
+ * Run: node scripts/generate-colors.js
+ *
  * WCAG AA Contrast Ratios (verified against #1a1a1a dark terminal background):
  * - Green (#32CD32):     4.5:1 ✓ (meets AA for normal text)
  * - Red (#FF6B6B):       5.0:1 ✓ (meets AA for normal text)
@@ -22,6 +25,9 @@
  * are for typical dark terminal configurations.
  */
 
+// Import generated color definitions from YAML source of truth
+const generated = require('./colors.generated');
+
 // High-contrast mode detection
 let _highContrastMode = null;
 
@@ -57,135 +63,79 @@ function resetHighContrast() {
  * Brand color hex value for chalk compatibility.
  * Use with chalk.hex(BRAND_HEX) in files that use chalk.
  */
-const BRAND_HEX = '#e8683a';
+const { BRAND_HEX } = generated;
 
 /**
  * WCAG AAA high-contrast color palette (7:1+ contrast ratio).
  * Used when AGILEFLOW_HIGH_CONTRAST=1 or --high-contrast flag.
+ * Built from generated highContrast values plus additional mappings.
  */
 const hc = {
-  // Reset and modifiers
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[0m', // No dimming in high-contrast (use regular text)
-  italic: '\x1b[3m',
-  underline: '\x1b[4m',
-
-  // High-contrast standard colors (bright variants for max visibility)
-  red: '\x1b[91m', // Bright red
-  green: '\x1b[92m', // Bright green
-  yellow: '\x1b[93m', // Bright yellow
-  blue: '\x1b[94m', // Bright blue
-  magenta: '\x1b[95m', // Bright magenta
-  cyan: '\x1b[96m', // Bright cyan
-  white: '\x1b[97m', // Bright white
+  // Reset and modifiers from generated
+  reset: generated.modifiers.reset,
+  bold: generated.modifiers.bold,
+  dim: generated.highContrast.dim, // No dimming in high-contrast
+  italic: generated.modifiers.italic,
+  underline: generated.modifiers.underline,
+
+  // High-contrast standard colors (from generated)
+  red: generated.highContrast.red,
+  green: generated.highContrast.green,
+  yellow: generated.highContrast.yellow,
+  blue: generated.highContrast.blue,
+  magenta: generated.highContrast.magenta,
+  cyan: generated.highContrast.cyan,
+  white: generated.highContrast.white,
 
   // Bright variants (same in high-contrast mode)
-  brightBlack: '\x1b[37m', // Use white instead of gray
-  brightRed: '\x1b[91m',
-  brightGreen: '\x1b[92m',
-  brightYellow: '\x1b[93m',
-  brightBlue: '\x1b[94m',
-  brightMagenta: '\x1b[95m',
-  brightCyan: '\x1b[96m',
-  brightWhite: '\x1b[97m',
+  brightBlack: generated.highContrast.brightBlack, // Use white instead of gray
+  brightRed: generated.highContrast.red,
+  brightGreen: generated.highContrast.green,
+  brightYellow: generated.highContrast.yellow,
+  brightBlue: generated.highContrast.blue,
+  brightMagenta: generated.highContrast.magenta,
+  brightCyan: generated.highContrast.cyan,
+  brightWhite: generated.highContrast.white,
 
   // 256-color high-contrast alternatives (all 7:1+ ratio)
-  mintGreen: '\x1b[92m', // Bright green
-  peach: '\x1b[93m', // Bright yellow
-  coral: '\x1b[91m', // Bright red
-  lightGreen: '\x1b[92m', // Bright green
-  lightYellow: '\x1b[93m', // Bright yellow
-  lightPink: '\x1b[91m', // Bright red
-  skyBlue: '\x1b[96m', // Bright cyan
-  lavender: '\x1b[95m', // Bright magenta
-  softGold: '\x1b[93m', // Bright yellow
-  teal: '\x1b[96m', // Bright cyan
-  slate: '\x1b[97m', // White (instead of gray)
-  rose: '\x1b[91m', // Bright red
-  amber: '\x1b[93m', // Bright yellow
-  powder: '\x1b[96m', // Bright cyan
-
-  // Brand color - use bright orange/yellow for visibility
-  brand: '\x1b[38;2;255;165;0m', // Bright orange (#FFA500 - 8.0:1 ratio)
-  orange: '\x1b[38;2;255;165;0m',
+  mintGreen: generated.highContrast.green,
+  peach: generated.highContrast.yellow,
+  coral: generated.highContrast.red,
+  lightGreen: generated.highContrast.green,
+  lightYellow: generated.highContrast.yellow,
+  lightPink: generated.highContrast.red,
+  skyBlue: generated.highContrast.cyan,
+  lavender: generated.highContrast.magenta,
+  softGold: generated.highContrast.yellow,
+  teal: generated.highContrast.cyan,
+  slate: generated.highContrast.white, // White instead of gray
+  rose: generated.highContrast.red,
+  amber: generated.highContrast.yellow,
+  powder: generated.highContrast.cyan,
+
+  // Brand color - from generated high-contrast brand
+  brand: generated.highContrast.brand,
+  orange: generated.highContrast.brand,
 
   // Background colors (same as standard)
-  bgRed: '\x1b[41m',
-  bgGreen: '\x1b[42m',
-  bgYellow: '\x1b[43m',
-  bgBlue: '\x1b[44m',
+  bgRed: generated.backgrounds.bgRed,
+  bgGreen: generated.backgrounds.bgGreen,
+  bgYellow: generated.backgrounds.bgYellow,
+  bgBlue: generated.backgrounds.bgBlue,
 
   // Semantic aliases
-  success: '\x1b[92m',
-  error: '\x1b[91m',
-  warning: '\x1b[93m',
-  info: '\x1b[96m',
+  success: generated.highContrast.green,
+  error: generated.highContrast.red,
+  warning: generated.highContrast.yellow,
+  info: generated.highContrast.cyan,
 };
 
 /**
  * ANSI color codes for terminal output.
  * Includes standard colors, 256-color palette, and brand colors.
+ * Values imported from generated colors (config/colors.yaml source of truth).
  */
-const cStandard = {
-  // Reset and modifiers
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  italic: '\x1b[3m',
-  underline: '\x1b[4m',
-
-  // Standard ANSI colors (8 colors)
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  magenta: '\x1b[35m',
-  cyan: '\x1b[36m',
-  white: '\x1b[37m',
-
-  // Bright variants
-  brightBlack: '\x1b[90m',
-  brightRed: '\x1b[91m',
-  brightGreen: '\x1b[92m',
-  brightYellow: '\x1b[93m',
-  brightBlue: '\x1b[94m',
-  brightMagenta: '\x1b[95m',
-  brightCyan: '\x1b[96m',
-  brightWhite: '\x1b[97m',
-
-  // 256-color palette (vibrant, modern look)
-  mintGreen: '\x1b[38;5;158m', // Healthy/success states
-  peach: '\x1b[38;5;215m', // Warning states
-  coral: '\x1b[38;5;203m', // Critical/error states
-  lightGreen: '\x1b[38;5;194m', // Session healthy
-  lightYellow: '\x1b[38;5;228m', // Session warning
-  lightPink: '\x1b[38;5;210m', // Session critical
-  skyBlue: '\x1b[38;5;117m', // Directories/paths, ready states
-  lavender: '\x1b[38;5;147m', // Model info, story IDs
-  softGold: '\x1b[38;5;222m', // Cost/money
-  teal: '\x1b[38;5;80m', // Pending states
-  slate: '\x1b[38;5;103m', // Secondary info
-  rose: '\x1b[38;5;211m', // Blocked/critical accent
-  amber: '\x1b[38;5;214m', // WIP/in-progress accent
-  powder: '\x1b[38;5;153m', // Labels/headers
-
-  // Brand color (#e8683a - burnt orange/terracotta)
-  brand: '\x1b[38;2;232;104;58m',
-  orange: '\x1b[38;2;232;104;58m', // Alias for brand color
-
-  // Background colors
-  bgRed: '\x1b[41m',
-  bgGreen: '\x1b[42m',
-  bgYellow: '\x1b[43m',
-  bgBlue: '\x1b[44m',
-
-  // Semantic aliases (for consistent meaning across codebase)
-  success: '\x1b[32m', // Same as green
-  error: '\x1b[31m', // Same as red
-  warning: '\x1b[33m', // Same as yellow
-  info: '\x1b[36m', // Same as cyan
-};
+const cStandard = generated.cStandard;
 
 /**
  * Get the active color palette based on high-contrast mode.

package/lib/generator-factory.js

@@ -0,0 +1,333 @@
+/**
+ * GeneratorFactory - Dependency Injection for Content Generators
+ *
+ * Provides a centralized factory for creating content generators with:
+ * - Shared PlaceholderRegistry built once
+ * - Dependency injection for testability
+ * - Generator registration pattern
+ *
+ * Usage:
+ *   const factory = new GeneratorFactory();
+ *   factory.registerGenerator('help', HelpGenerator);
+ *   factory.registerGenerator('readme', ReadmeGenerator);
+ *
+ *   // Build registry once, pass to all generators
+ *   const context = await factory.buildContext();
+ *   await factory.runAll(context);
+ */
+
+'use strict';
+
+const { PlaceholderRegistry, createDefaultRegistry } = require('./placeholder-registry');
+const { createContainer, createScannerFactory } = require('./registry-di');
+
+/**
+ * Generator interface
+ * @typedef {Object} IGenerator
+ * @property {string} name - Generator name
+ * @property {Function} register - Register placeholders: (registry) => void
+ * @property {Function} generate - Generate content: (context) => Promise<void>
+ */
+
+/**
+ * GeneratorFactory - Factory for creating and running generators
+ */
+class GeneratorFactory {
+  /**
+   * Create a new GeneratorFactory
+   * @param {Object} options - Factory options
+   * @param {Object} [options.container] - DI container (from registry-di.js)
+   * @param {PlaceholderRegistry} [options.registry] - Pre-built registry
+   * @param {Object} [options.paths] - Path configuration
+   */
+  constructor(options = {}) {
+    this._generators = new Map();
+    this._container = options.container || createContainer();
+    this._registry = options.registry || null;
+    this._paths = options.paths || {};
+    this._built = false;
+    this._context = null;
+  }
+
+  /**
+   * Register a generator with the factory
+   * @param {string} name - Generator name
+   * @param {IGenerator|Function} generator - Generator instance or class
+   * @returns {GeneratorFactory} this for chaining
+   */
+  registerGenerator(name, generator) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Generator name must be a non-empty string');
+    }
+
+    // Support both instances and classes
+    const instance = typeof generator === 'function' ? new generator() : generator;
+
+    if (!instance.register || typeof instance.register !== 'function') {
+      throw new Error(`Generator "${name}" must have a register(registry) method`);
+    }
+
+    if (!instance.generate || typeof instance.generate !== 'function') {
+      throw new Error(`Generator "${name}" must have a generate(context) method`);
+    }
+
+    this._generators.set(name, instance);
+
+    // Reset built state when new generator is added
+    this._built = false;
+    this._context = null;
+
+    return this;
+  }
+
+  /**
+   * Unregister a generator
+   * @param {string} name - Generator name
+   * @returns {boolean} True if removed
+   */
+  unregisterGenerator(name) {
+    const result = this._generators.delete(name);
+    if (result) {
+      this._built = false;
+      this._context = null;
+    }
+    return result;
+  }
+
+  /**
+   * Get list of registered generator names
+   * @returns {string[]}
+   */
+  getGeneratorNames() {
+    return Array.from(this._generators.keys());
+  }
+
+  /**
+   * Check if a generator is registered
+   * @param {string} name - Generator name
+   * @returns {boolean}
+   */
+  hasGenerator(name) {
+    return this._generators.has(name);
+  }
+
+  /**
+   * Get the shared registry instance
+   * @returns {PlaceholderRegistry}
+   */
+  getRegistry() {
+    if (!this._registry) {
+      this._registry = createDefaultRegistry();
+    }
+    return this._registry;
+  }
+
+  /**
+   * Build context by registering all generator placeholders
+   * Registry is built once and shared across all generators
+   * @param {Object} [baseContext={}] - Base context to merge
+   * @returns {Object} Built context
+   */
+  buildContext(baseContext = {}) {
+    if (this._built && this._context) {
+      return { ...this._context, ...baseContext };
+    }
+
+    const registry = this.getRegistry();
+
+    // Let each generator register its placeholders
+    for (const [name, generator] of this._generators) {
+      try {
+        generator.register(registry);
+      } catch (error) {
+        console.error(`Failed to register placeholders for "${name}":`, error.message);
+      }
+    }
+
+    // Build context with resolved values
+    this._context = {
+      registry,
+      container: this._container,
+      paths: this._paths,
+      scanner: createScannerFactory(this._container),
+      ...baseContext,
+    };
+
+    this._built = true;
+
+    return this._context;
+  }
+
+  /**
+   * Run a specific generator
+   * @param {string} name - Generator name
+   * @param {Object} [context] - Context override
+   * @returns {Promise<{success: boolean, error?: Error}>}
+   */
+  async runGenerator(name, context) {
+    const generator = this._generators.get(name);
+
+    if (!generator) {
+      return { success: false, error: new Error(`Generator not found: ${name}`) };
+    }
+
+    const ctx = context || this.buildContext();
+
+    try {
+      await generator.generate(ctx);
+      return { success: true };
+    } catch (error) {
+      return { success: false, error };
+    }
+  }
+
+  /**
+   * Run all registered generators
+   * @param {Object} [context] - Context override
+   * @returns {Promise<Map<string, {success: boolean, error?: Error}>>}
+   */
+  async runAll(context) {
+    const ctx = context || this.buildContext();
+    const results = new Map();
+
+    for (const name of this._generators.keys()) {
+      results.set(name, await this.runGenerator(name, ctx));
+    }
+
+    return results;
+  }
+
+  /**
+   * Run generators in parallel
+   * @param {Object} [context] - Context override
+   * @returns {Promise<Map<string, {success: boolean, error?: Error}>>}
+   */
+  async runParallel(context) {
+    const ctx = context || this.buildContext();
+    const results = new Map();
+
+    const promises = Array.from(this._generators.keys()).map(async name => {
+      const result = await this.runGenerator(name, ctx);
+      return { name, result };
+    });
+
+    const settled = await Promise.allSettled(promises);
+
+    for (const item of settled) {
+      if (item.status === 'fulfilled') {
+        results.set(item.value.name, item.value.result);
+      } else {
+        // Shouldn't happen since runGenerator catches errors
+        const name = 'unknown';
+        results.set(name, { success: false, error: item.reason });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Reset the factory state
+   */
+  reset() {
+    this._built = false;
+    this._context = null;
+    this._registry = null;
+  }
+
+  /**
+   * Get container (for testing)
+   * @returns {Object}
+   */
+  getContainer() {
+    return this._container;
+  }
+}
+
+/**
+ * Base generator class with common utilities
+ */
+class BaseGenerator {
+  constructor(options = {}) {
+    this.name = options.name || this.constructor.name;
+    this.placeholders = [];
+  }
+
+  /**
+   * Register placeholders - override in subclass
+   * @param {PlaceholderRegistry} registry
+   */
+  register(registry) {
+    // Subclasses should override this method
+    for (const placeholder of this.placeholders) {
+      registry.register(placeholder.name, placeholder.resolver, placeholder.config);
+    }
+  }
+
+  /**
+   * Generate content - override in subclass
+   * @param {Object} context
+   * @returns {Promise<void>}
+   */
+  async generate(context) {
+    throw new Error('Subclass must implement generate(context)');
+  }
+
+  /**
+   * Helper to add a placeholder definition
+   * @param {string} name - Placeholder name
+   * @param {Function} resolver - Resolver function
+   * @param {Object} [config] - Configuration
+   */
+  addPlaceholder(name, resolver, config = {}) {
+    this.placeholders.push({ name, resolver, config });
+  }
+}
+
+/**
+ * Create a factory with standard generators
+ * @param {Object} options - Factory options
+ * @returns {GeneratorFactory}
+ */
+function createGeneratorFactory(options = {}) {
+  const factory = new GeneratorFactory(options);
+
+  // Register standard generators if provided
+  if (options.generators) {
+    for (const [name, generator] of Object.entries(options.generators)) {
+      factory.registerGenerator(name, generator);
+    }
+  }
+
+  return factory;
+}
+
+// Singleton instance
+let _factoryInstance = null;
+
+/**
+ * Get singleton factory instance
+ * @param {Object} [options] - Factory options
+ * @returns {GeneratorFactory}
+ */
+function getGeneratorFactory(options = {}) {
+  if (!_factoryInstance || options.forceNew) {
+    _factoryInstance = createGeneratorFactory(options);
+  }
+  return _factoryInstance;
+}
+
+/**
+ * Reset singleton (for testing)
+ */
+function resetGeneratorFactory() {
+  _factoryInstance = null;
+}
+
+module.exports = {
+  GeneratorFactory,
+  BaseGenerator,
+  createGeneratorFactory,
+  getGeneratorFactory,
+  resetGeneratorFactory,
+};