agileflow 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-02-14
+
+### Added
+- Legal audit system, native Agent Teams integration, and startup performance improvements
+
 ## [3.0.2] - 2026-02-14
 
 ### Added

package/README.md

@@ -3,8 +3,8 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-93-blue)](docs/04-architecture/commands.md)
-[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-45-orange)](docs/04-architecture/subagents.md)
+[![Commands](https://img.shields.io/badge/commands-94-blue)](docs/04-architecture/commands.md)
+[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-55-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.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.
@@ -39,9 +39,9 @@ npx agileflow@latest update
 | IDE | Status | Config Location |
 |-----|--------|-----------------|
 | Claude Code | Supported | `.claude/commands/agileflow/` |
-| Cursor | Supported | `.cursor/rules/agileflow/` |
+| Cursor | Supported | `.cursor/commands/agileflow/` |
 | Windsurf | Supported | `.windsurf/workflows/agileflow/` |
-| OpenAI Codex CLI | Supported | `.codex/skills/` |
+| OpenAI Codex CLI | Supported | `.codex/skills/` and `~/.codex/prompts/` |
 
 ---
 
@@ -65,8 +65,8 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 93 | Slash commands for agile workflows |
-| [Agents/Experts](docs/04-architecture/subagents.md) | 45 | Specialized agents with self-improving knowledge bases |
+| [Commands](docs/04-architecture/commands.md) | 94 | Slash commands for agile workflows |
+| [Agents/Experts](docs/04-architecture/subagents.md) | 55 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
 ---
@@ -76,8 +76,8 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 93 slash commands
-- [Agents/Experts](docs/04-architecture/subagents.md) - 45 specialized agents with self-improving knowledge
+- [Commands](docs/04-architecture/commands.md) - All 94 slash commands
+- [Agents/Experts](docs/04-architecture/subagents.md) - 55 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 
 ### Architecture

package/lib/feedback.js

@@ -34,7 +34,14 @@
  */
 
 const { c, BRAND_HEX } = require('./colors');
-const chalk = require('chalk');
+const { lazyRequire } = require('./lazy-require');
+
+// Lazy-load chalk: feedback.js is imported by scripts that run as hooks in
+// user projects (.agileflow/scripts/).  If chalk isn't resolvable from the
+// user's node_modules the eager require() would crash every hook that
+// imports feedback.  Deferring the require() to the single call-site that
+// actually needs chalk (brand()) avoids the crash entirely.
+const getChalk = lazyRequire('chalk');
 
 // Symbols for consistent output
 const SYMBOLS = {
@@ -182,7 +189,7 @@ class Feedback {
   brand(message) {
     if (this.quiet) return this;
     const prefix = this._indent();
-    console.log(`${prefix}${chalk.hex(BRAND_HEX)(message)}`);
+    console.log(`${prefix}${getChalk().hex(BRAND_HEX)(message)}`);
     return this;
   }
 

package/lib/lazy-require.js

@@ -0,0 +1,59 @@
+/**
+ * lazy-require.js - Reusable Lazy-Loading Utility
+ *
+ * AgileFlow scripts are copied to user projects (.agileflow/scripts/) and run
+ * as hooks. When these scripts eagerly require() npm dependencies at module
+ * load time, they crash if the dependency isn't resolvable from the user's
+ * project directory. This utility standardizes the lazy-loading pattern used
+ * ad-hoc in yaml-utils.js and dashboard-server.js.
+ *
+ * Usage:
+ *   const { lazyRequire } = require('./lazy-require');
+ *
+ *   // Returns a getter function; require() is deferred until first call
+ *   const getChalk = lazyRequire('chalk');
+ *
+ *   // With fallback resolution paths
+ *   const getYaml = lazyRequire('js-yaml',
+ *     path.join(__dirname, '..', 'node_modules', 'js-yaml')
+ *   );
+ *
+ *   // Later, when actually needed:
+ *   const chalk = getChalk();
+ */
+
+'use strict';
+
+/**
+ * Create a lazy-loading getter for an npm module.
+ *
+ * The returned function defers require() until first invocation, then caches
+ * the result. Multiple resolution paths are tried in order, so the module can
+ * be found from the user's node_modules, AgileFlow's own node_modules, or any
+ * other location.
+ *
+ * @param {string} name - Primary module name (passed to require())
+ * @param {...string} fallbackPaths - Additional paths to try if primary fails
+ * @returns {function(): any} Getter that returns the loaded module
+ */
+function lazyRequire(name, ...fallbackPaths) {
+  let cached = null;
+  return () => {
+    if (cached) return cached;
+    const paths = [name, ...fallbackPaths];
+    for (const p of paths) {
+      try {
+        cached = require(p);
+        return cached;
+      } catch (_e) {
+        // Continue to next path
+      }
+    }
+    throw new Error(
+      `${name} not found. Run: npm install ${name}\n` +
+        'Or reinstall AgileFlow: npx agileflow setup --force'
+    );
+  };
+}
+
+module.exports = { lazyRequire };

package/package.json

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

package/scripts/agileflow-configure.js

@@ -18,6 +18,7 @@
  *   --enable=<features>                 Enable specific features
  *   --disable=<features>                Disable specific features
  *   --archival-days=<N>                 Set archival threshold
+ *   --startup-mode=<MODE>              Set default startup mode (atomic)
  *   --migrate                           Fix old formats without changing features
  *   --validate                          Check for issues
  *   --detect                            Show current status
@@ -42,6 +43,7 @@ const {
   listStatuslineComponents,
   migrateSettings,
   upgradeFeatures,
+  enableStartupMode,
 } = require('./lib/configure-features');
 const { listScripts, showVersionInfo, repairScripts } = require('./lib/configure-repair');
 const { feedback } = require('../lib/feedback');
@@ -144,6 +146,7 @@ ${c.cyan}Statusline Components:${c.reset}
 
 ${c.cyan}Settings:${c.reset}
   --archival-days=N   Set archival threshold (default: 30)
+  --startup-mode=MODE Set default startup mode (skip-permissions, accept-edits, normal, no-claude)
 
 ${c.cyan}Maintenance:${c.reset}
   --migrate           Fix old/invalid formats
@@ -201,6 +204,7 @@ function main() {
   let repairFeature = null;
   let showVersion = false;
   let listScriptsMode = false;
+  let startupMode = null;
 
   args.forEach(arg => {
     if (arg.startsWith('--profile=')) profile = arg.split('=')[1];
@@ -237,6 +241,8 @@ function main() {
       repairFeature = arg.split('=')[1].trim().toLowerCase();
     } else if (arg === '--version' || arg === '-v') showVersion = true;
     else if (arg === '--list-scripts' || arg === '--scripts') listScriptsMode = true;
+    else if (arg.startsWith('--startup-mode='))
+      startupMode = arg.split('=')[1].trim().toLowerCase();
   });
 
   // Help mode
@@ -289,6 +295,12 @@ function main() {
   spinner.succeed('Configuration detected');
   const { hasIssues, hasOutdated } = printStatus(status);
 
+  // Startup mode (atomic - sets BOTH metadata AND settings.json)
+  if (startupMode) {
+    enableStartupMode(startupMode, VERSION);
+    return;
+  }
+
   // Detect only mode
   if (detect && !migrate && !upgrade && !profile && enable.length === 0 && disable.length === 0) {
     return;

package/scripts/agileflow-welcome.js

@@ -30,6 +30,20 @@ const { readJSONCached, readFileCached } = require('../lib/file-cache');
 // Session manager path (relative to script location)
 const SESSION_MANAGER_PATH = path.join(__dirname, 'session-manager.js');
 
+// PERFORMANCE OPTIMIZATION: Lazy-loaded session-manager module
+// Importing directly avoids ~50-150ms subprocess overhead per call.
+let _sessionManager;
+function getSessionManager() {
+  if (_sessionManager === undefined) {
+    try {
+      _sessionManager = require('./session-manager.js');
+    } catch (e) {
+      _sessionManager = null;
+    }
+  }
+  return _sessionManager;
+}
+
 // Hook metrics module (kept at top level - needed early for timer)
 let hookMetrics;
 try {
@@ -43,6 +57,12 @@ try {
  * Uses file-cache module for automatic caching with 15s TTL.
  * Files are cached across script invocations within TTL window.
  * Estimated savings: 60-120ms on cache hits
+ *
+ * Additional optimizations in this file (US-0356):
+ * - Git batching: 3 subprocess calls → 1 (~20-40ms savings)
+ * - Session-manager inline: subprocess → direct require() (~50-150ms savings)
+ * - Tmux cache: subprocess → session-state lookup (~10-20ms after first run)
+ * Total estimated savings: ~130-260ms
  */
 function loadProjectFiles(rootDir) {
   const paths = {
@@ -109,32 +129,57 @@ function detectPlatform() {
 
 /**
  * Check if tmux is installed
+ * PERFORMANCE OPTIMIZATION: Caches result in session-state.json (~10-20ms savings on subsequent runs)
  * Returns object with availability info and platform-specific install suggestion
  */
-function checkTmuxAvailability() {
+function checkTmuxAvailability(cache) {
+  // Check session state cache first (tmux availability doesn't change within a session)
+  if (cache?.sessionState?.tmux_available !== undefined) {
+    if (cache.sessionState.tmux_available) return { available: true };
+    return { available: false, platform: detectPlatform(), noSudoCmd: 'conda install -c conda-forge tmux' };
+  }
+
+  // Actually check (first run or no cache)
   const result = executeCommandSync('which', ['tmux'], { fallback: null });
-  if (result.data !== null) {
-    return { available: true };
+  const available = result.data !== null;
+
+  // Cache in session state for next invocation
+  try {
+    const rootDir = getProjectRoot();
+    const sessionStatePath = getSessionStatePath(rootDir);
+    if (fs.existsSync(sessionStatePath)) {
+      const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+      state.tmux_available = available;
+      fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+    }
+  } catch (e) {
+    // Cache write failed, non-critical
   }
-  const platform = detectPlatform();
-  return {
-    available: false,
-    platform,
-    noSudoCmd: 'conda install -c conda-forge tmux',
-  };
+
+  if (available) return { available: true };
+  return { available: false, platform: detectPlatform(), noSudoCmd: 'conda install -c conda-forge tmux' };
 }
 
 /**
  * PERFORMANCE OPTIMIZATION: Batch git commands into single call
- * Reduces subprocess overhead from 3 calls to 1.
- * Estimated savings: 20-40ms
+ * Uses `git log -1 --format=%D%n%h%n%s` to get branch, short hash, and subject
+ * in a single subprocess instead of 3 separate calls.
+ * Savings: ~20-40ms (eliminates 2 subprocess spawns)
  */
 function getGitInfo(rootDir) {
-  const opts = { cwd: rootDir, timeout: 5000, fallback: 'unknown' };
-  const branch = git(['branch', '--show-current'], opts).data;
-  const commit = git(['rev-parse', '--short', 'HEAD'], opts).data;
-  const lastCommit = git(['log', '-1', '--format=%s'], { ...opts, fallback: '' }).data;
-  return { branch, commit, lastCommit };
+  const opts = { cwd: rootDir, timeout: 5000, fallback: '' };
+  const result = git(['log', '-1', '--format=%D%n%h%n%s'], opts);
+  if (result.data) {
+    const lines = result.data.split('\n');
+    // %D gives decorations like "HEAD -> main, origin/main, tag: v3.0.0"
+    const branchMatch = (lines[0] || '').match(/HEAD -> ([^,\s]+)/);
+    return {
+      branch: branchMatch ? branchMatch[1] : 'detached',
+      commit: (lines[1] || 'unknown').trim(),
+      lastCommit: lines.slice(2).join('\n').trim(),
+    };
+  }
+  return { branch: 'unknown', commit: 'unknown', lastCommit: '' };
 }
 
 function getProjectInfo(rootDir, cache = null) {
@@ -403,18 +448,36 @@ function checkParallelSessions(rootDir) {
   };
 
   try {
-    // Check if session manager exists
+    // PERFORMANCE OPTIMIZATION: Import session-manager directly instead of subprocess
+    // Saves ~50-150ms by avoiding Node subprocess spawn overhead
+    const sm = getSessionManager();
+    if (sm && sm.fullStatus) {
+      result.available = true;
+      const data = sm.fullStatus();
+      result.registered = data.registered;
+      result.currentId = data.id;
+      result.otherActive = data.otherActive || 0;
+      result.cleaned = data.cleaned || 0;
+      result.cleanedSessions = data.cleanedSessions || [];
+
+      if (data.current) {
+        result.isMain = data.current.is_main === true;
+        result.nickname = data.current.nickname;
+        result.branch = data.current.branch;
+        result.sessionPath = data.current.path;
+      }
+      return result;
+    }
+
+    // Fallback: check if session manager script exists for subprocess call
     const managerPath = path.join(getAgileflowDir(rootDir), 'scripts', 'session-manager.js');
     if (!fs.existsSync(managerPath) && !fs.existsSync(SESSION_MANAGER_PATH)) {
       return result;
     }
 
     result.available = true;
-
-    // Try to use combined full-status command (saves ~200ms vs 3 separate calls)
     const scriptPath = fs.existsSync(managerPath) ? managerPath : SESSION_MANAGER_PATH;
 
-    // PERFORMANCE: Single subprocess call instead of 3 (register + count + status)
     const fullStatusResult = executeCommandSync('node', [scriptPath, 'full-status'], {
       cwd: rootDir,
       fallback: null,
@@ -435,52 +498,7 @@ function checkParallelSessions(rootDir) {
           result.branch = data.current.branch;
           result.sessionPath = data.current.path;
         }
-      } catch (e) {
-        // JSON parse failed, fall through to individual calls
-        fullStatusResult.data = null;
-      }
-    }
-
-    if (!fullStatusResult.data) {
-      // Fall back to individual calls if full-status not available (older version)
-      const registerResult = executeCommandSync('node', [scriptPath, 'register'], {
-        cwd: rootDir,
-        fallback: null,
-      });
-      if (registerResult.data) {
-        try {
-          const registerData = JSON.parse(registerResult.data);
-          result.registered = true;
-          result.currentId = registerData.id;
-        } catch (e) {}
-      }
-
-      const countResult = executeCommandSync('node', [scriptPath, 'count'], {
-        cwd: rootDir,
-        fallback: null,
-      });
-      if (countResult.data) {
-        try {
-          const countData = JSON.parse(countResult.data);
-          result.otherActive = countData.count || 0;
-        } catch (e) {}
-      }
-
-      const statusCmdResult = executeCommandSync('node', [scriptPath, 'status'], {
-        cwd: rootDir,
-        fallback: null,
-      });
-      if (statusCmdResult.data) {
-        try {
-          const statusData = JSON.parse(statusCmdResult.data);
-          if (statusData.current) {
-            result.isMain = statusData.current.is_main === true;
-            result.nickname = statusData.current.nickname;
-            result.branch = statusData.current.branch;
-            result.sessionPath = statusData.current.path;
-          }
-        } catch (e) {}
-      }
+      } catch (e) {}
     }
   } catch (e) {
     // Session system not available
@@ -1752,7 +1770,7 @@ async function main() {
   let tmuxCheck = { available: true };
   const tmuxAutoSpawnEnabled = cache?.metadata?.features?.tmuxAutoSpawn?.enabled !== false;
   if (tmuxAutoSpawnEnabled) {
-    tmuxCheck = checkTmuxAvailability();
+    tmuxCheck = checkTmuxAvailability(cache);
   }
 
   // Show session banner FIRST if in a non-main session
@@ -1897,14 +1915,12 @@ async function main() {
 
   // === SESSION HEALTH WARNINGS ===
   // Check for forgotten sessions with uncommitted changes, stale sessions, orphaned entries
+  // PERFORMANCE OPTIMIZATION: Direct function call instead of subprocess (~50-100ms savings)
   try {
-    const healthResult = executeCommandSync('node', [SESSION_MANAGER_PATH, 'health'], {
-      timeout: 10000,
-      fallback: null,
-    });
+    const sm = getSessionManager();
+    const health = sm ? sm.getSessionsHealth({ staleDays: 7 }) : null;
 
-    if (healthResult.data) {
-      const health = JSON.parse(healthResult.data);
+    if (health) {
       const hasIssues =
         health.uncommitted.length > 0 ||
         health.stale.length > 0 ||

package/scripts/claude-tmux.sh

@@ -360,7 +360,7 @@ fi
 # Silently remove sessions where all panes have exited (dead/empty shells).
 # This prevents accumulation of orphan sessions over time.
 SESSION_BASE="claude-${DIR_NAME}"
-for sid in $(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep "^${SESSION_BASE}\(\$\|-[0-9]*\$\)"); do
+for sid in $(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep -E "^${SESSION_BASE}($|-[0-9]+$)"); do
   # Count alive panes (pane_dead=0 means alive)
   ALIVE=$(tmux list-panes -t "$sid" -F '#{pane_dead}' 2>/dev/null | grep -c '^0$' || true)
   if [ "$ALIVE" = "0" ]; then
@@ -368,6 +368,36 @@ for sid in $(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep "^${SESS
   fi
 done
 
+# ── Consolidate duplicate sessions ───────────────────────────────────────
+# Kill numbered duplicates (e.g. claude-Acuide-2, -3) that were created by
+# a previous bug. If the base session exists, duplicates are unnecessary.
+# If only numbered sessions remain, promote the lowest to the base name.
+if [ "$FORCE_NEW" = false ]; then
+  HAS_BASE=false
+  NUMBERED=()
+  if tmux has-session -t "$SESSION_BASE" 2>/dev/null; then
+    HAS_BASE=true
+  fi
+  while IFS= read -r sid; do
+    [ -n "$sid" ] && NUMBERED+=("$sid")
+  done < <(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep -E "^${SESSION_BASE}-[0-9]+$" | sort -t- -k3 -n)
+
+  if [ "$HAS_BASE" = true ] && [ "${#NUMBERED[@]}" -gt 0 ]; then
+    # Base exists — kill all numbered duplicates
+    for sid in "${NUMBERED[@]}"; do
+      tmux kill-session -t "$sid" 2>/dev/null || true
+    done
+  elif [ "$HAS_BASE" = false ] && [ "${#NUMBERED[@]}" -gt 0 ]; then
+    # No base — promote lowest numbered session to base name
+    PROMOTE="${NUMBERED[0]}"
+    tmux rename-session -t "$PROMOTE" "$SESSION_BASE" 2>/dev/null || true
+    # Kill remaining duplicates
+    for sid in "${NUMBERED[@]:1}"; do
+      tmux kill-session -t "$sid" 2>/dev/null || true
+    done
+  fi
+fi
+
 # ── Auto-reattach to detached session ──────────────────────────────────────
 # When user does Alt+Q (detach) and then runs `af` again, reattach to the
 # existing session instead of creating a new one. This preserves tmux windows,
@@ -377,7 +407,7 @@ if [ "$FORCE_NEW" = false ]; then
   DETACHED=()
   while IFS= read -r sid; do
     [ -n "$sid" ] && DETACHED+=("$sid")
-  done < <(tmux list-sessions -F '#{session_name} #{session_attached}' 2>/dev/null | awk '$2 == "0" {print $1}' | grep "^${SESSION_BASE}\(\$\|-[0-9]*\$\)")
+  done < <(tmux list-sessions -F '#{session_name} #{session_attached}' 2>/dev/null | awk '$2 == "0" {print $1}' | grep -E "^${SESSION_BASE}($|-[0-9]+$)")
 
   if [ "${#DETACHED[@]}" -eq 1 ]; then
     # Single detached session — just reattach
@@ -416,7 +446,7 @@ if [ "$FORCE_NEW" = false ]; then
   EXISTING=()
   while IFS= read -r sid; do
     [ -n "$sid" ] && EXISTING+=("$sid")
-  done < <(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep "^${SESSION_BASE}\(\$\|-[0-9]*\$\)")
+  done < <(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep -E "^${SESSION_BASE}($|-[0-9]+$)")
 
   if [ "${#EXISTING[@]}" -gt 0 ]; then
     # Prefer the base session, otherwise pick the first one

package/scripts/lib/configure-features.js

@@ -1215,6 +1215,119 @@ function upgradeFeatures(status, version) {
   return upgraded > 0;
 }
 
+// ============================================================================
+// STARTUP MODE (atomic command)
+// ============================================================================
+
+/**
+ * Valid startup modes and their mappings
+ */
+const STARTUP_MODES = {
+  'skip-permissions': {
+    flags: '--dangerously-skip-permissions',
+    defaultMode: 'bypassPermissions',
+    description: 'Skip all permission prompts (trusted mode)',
+  },
+  'accept-edits': {
+    flags: '--permission-mode acceptEdits',
+    defaultMode: 'acceptEdits',
+    description: 'Auto-accept file edits, prompt for other actions',
+  },
+  normal: {
+    flags: null,
+    defaultMode: null,
+    description: 'Standard Claude with permission prompts',
+  },
+  'no-claude': {
+    flags: null,
+    defaultMode: null,
+    description: 'Create worktree only, start Claude manually',
+  },
+};
+
+/**
+ * Set startup mode atomically - updates BOTH metadata AND .claude/settings.json
+ * This replaces the fragile two-step process of updating metadata + running --enable=claudeflags
+ *
+ * @param {string} mode - One of: skip-permissions, accept-edits, normal, no-claude
+ * @param {string} version - Current version string
+ * @returns {boolean} Success
+ */
+function enableStartupMode(mode, version) {
+  const modeConfig = STARTUP_MODES[mode];
+  if (!modeConfig) {
+    error(`Unknown startup mode: ${mode}`);
+    log(`  Valid modes: ${Object.keys(STARTUP_MODES).join(', ')}`, c.dim);
+    return false;
+  }
+
+  ensureDir('.claude');
+  const settings = readJSON('.claude/settings.json') || {};
+  settings.permissions = settings.permissions || { allow: [], deny: [], ask: [] };
+
+  if (mode === 'normal' || mode === 'no-claude') {
+    // Remove defaultMode from settings
+    if (settings.permissions.defaultMode) {
+      delete settings.permissions.defaultMode;
+    }
+    writeJSON('.claude/settings.json', settings);
+
+    // Disable claudeflags + set defaultStartupMode in metadata (single write)
+    updateMetadata(
+      {
+        features: {
+          claudeFlags: {
+            enabled: false,
+            defaultFlags: '',
+            version,
+            at: new Date().toISOString(),
+          },
+        },
+      },
+      version
+    );
+  } else {
+    // Set defaultMode in settings.json
+    settings.permissions.defaultMode = modeConfig.defaultMode;
+    writeJSON('.claude/settings.json', settings);
+
+    // Enable claudeflags + set defaultStartupMode in metadata (single write)
+    updateMetadata(
+      {
+        features: {
+          claudeFlags: {
+            enabled: true,
+            defaultFlags: modeConfig.flags,
+            version,
+            at: new Date().toISOString(),
+          },
+        },
+      },
+      version
+    );
+  }
+
+  // Set defaultStartupMode in metadata (updateMetadata already created file if missing)
+  const metaPath = 'docs/00-meta/agileflow-metadata.json';
+  const meta = readJSON(metaPath) || {};
+  meta.defaultStartupMode = mode;
+  meta.updated = new Date().toISOString();
+  writeJSON(metaPath, meta);
+
+  success(`Default startup mode set to: ${mode}`);
+  if (modeConfig.defaultMode) {
+    info(`Set permissions.defaultMode = "${modeConfig.defaultMode}" in .claude/settings.json`);
+  } else {
+    info('Removed permissions.defaultMode from .claude/settings.json');
+  }
+  info(`Metadata: defaultStartupMode = "${mode}"`);
+  if (mode !== 'normal') {
+    info('Restart Claude Code for the new mode to take effect');
+  }
+
+  return true;
+}
+
 // ============================================================================
 // SHELL ALIASES
 // ============================================================================
@@ -1473,6 +1586,9 @@ module.exports = {
   // Helpers
   scriptExists,
   getScriptPath,
+  // Startup mode
+  enableStartupMode,
+  STARTUP_MODES,
   // Shell aliases
   enableShellAliases,
   disableShellAliases,