agileflow 2.95.2 → 2.96.0

package/tools/cli/commands/serve.js

@@ -0,0 +1,456 @@
+/**
+ * AgileFlow CLI - Serve Command
+ *
+ * Starts a WebSocket server for the AgileFlow Dashboard to connect to.
+ * Enables real-time communication between the dashboard and Claude Code.
+ */
+
+const chalk = require('chalk');
+const path = require('node:path');
+const { displayLogo, displaySection, success, warning, info } = require('../lib/ui');
+
+module.exports = {
+  name: 'serve',
+  description: 'Start WebSocket server for AgileFlow Dashboard',
+  options: [
+    ['-p, --port <number>', 'Port to listen on (default: 8765)'],
+    ['-H, --host <host>', 'Host to bind to (default: 0.0.0.0)'],
+    ['-k, --api-key <key>', 'API key for authentication'],
+    ['--require-auth', 'Require API key for connections'],
+    ['--no-tunnel', 'Disable automatic tunnel (local only)'],
+    ['--tunnel-provider <provider>', 'Tunnel provider: cloudflared (default) or ngrok'],
+  ],
+  action: async options => {
+    try {
+      // Import server modules
+      const {
+        createDashboardServer,
+        startDashboardServer,
+        stopDashboardServer,
+      } = require('../../../lib/dashboard-server');
+      const {
+        createNotification,
+        createTextDelta,
+        createToolStart,
+        createToolResult,
+      } = require('../../../lib/dashboard-protocol');
+      const { execSync } = require('child_process');
+      const readline = require('readline');
+
+      let port = parseInt(options.port, 10) || 8765;
+      const host = options.host || '0.0.0.0';
+
+      // Check if port is in use and handle it
+      port = await handlePortConflict(port, readline);
+
+      const serverOptions = {
+        port,
+        host,
+        apiKey: options.apiKey || null,
+        requireAuth: options.requireAuth || !!options.apiKey,
+      };
+
+      // Display banner
+      printBanner();
+      console.log('Starting server...\n');
+
+      // Create server
+      const server = createDashboardServer(serverOptions);
+
+      // Set up event handlers
+      setupEventHandlers(server, { createTextDelta, createToolStart, createToolResult });
+
+      // Start server
+      const { wsUrl } = await startDashboardServer(server);
+
+      // Start tunnel automatically (unless --no-tunnel)
+      let tunnelUrl = null;
+      if (options.tunnel !== false) {
+        const provider = options.tunnelProvider || 'cloudflared';
+        console.log(chalk.dim(`  Starting ${provider} tunnel...`));
+        tunnelUrl = await startTunnel(serverOptions.port, provider);
+      }
+
+      console.log('─────────────────────────────────────────────────────────────');
+      console.log('');
+      if (tunnelUrl) {
+        console.log(chalk.green('  Ready!') + ' Connect your dashboard to:');
+        console.log('');
+        console.log(chalk.cyan.bold(`  ${tunnelUrl}`));
+        console.log('');
+        console.log(chalk.dim(`  Dashboard: https://dashboard.agileflow.projectquestorg.com`));
+        console.log(chalk.dim(`  Paste the URL above into the WebSocket URL field.`));
+      } else {
+        console.log(chalk.green('  Ready!') + ' Local connection:');
+        console.log(chalk.cyan(`  ${wsUrl}`));
+        console.log('');
+        console.log(chalk.yellow('  ⚠️  For cloud dashboard, run with tunnel:'));
+        console.log(chalk.dim('     npx agileflow serve'));
+        console.log(chalk.dim('     (tunnels are enabled by default)'));
+      }
+      console.log('');
+      if (serverOptions.apiKey) {
+        console.log(chalk.dim(`  API Key: ${serverOptions.apiKey.slice(0, 8)}...`));
+        console.log('');
+      }
+      console.log(chalk.dim('  Press Ctrl+C to stop.'));
+      console.log('');
+      console.log('─────────────────────────────────────────────────────────────');
+      console.log('');
+
+      // Handle shutdown
+      const shutdown = async () => {
+        console.log('\nShutting down...');
+        await stopDashboardServer(server);
+        process.exit(0);
+      };
+
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+    } catch (err) {
+      console.error(chalk.red('Error:'), err.message);
+      if (process.env.DEBUG) {
+        console.error(err.stack);
+      }
+      process.exit(1);
+    }
+  },
+};
+
+function printBanner() {
+  console.log(`
+${chalk.hex('#e8683a')('╔═══════════════════════════════════════════════════════════╗')}
+${chalk.hex('#e8683a')('║')}                                                           ${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}   ${chalk.bold.hex('#e8683a')('█████╗  ██████╗ ██╗██╗     ███████╗███████╗██╗      ')}${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}   ${chalk.bold.hex('#e8683a')('██╔══██╗██╔════╝ ██║██║     ██╔════╝██╔════╝██║      ')}${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}   ${chalk.bold.hex('#e8683a')('███████║██║  ███╗██║██║     █████╗  █████╗  ██║      ')}${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}   ${chalk.bold.hex('#e8683a')('██╔══██║██║   ██║██║██║     ██╔══╝  ██╔══╝  ██║      ')}${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}   ${chalk.bold.hex('#e8683a')('██║  ██║╚██████╔╝██║███████╗███████╗██║     ███████╗ ')}${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}   ${chalk.bold.hex('#e8683a')('╚═╝  ╚═╝ ╚═════╝ ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝ ')}${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}                                                           ${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}              ${chalk.white('Dashboard WebSocket Server')}                   ${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('║')}                                                           ${chalk.hex('#e8683a')('║')}
+${chalk.hex('#e8683a')('╚═══════════════════════════════════════════════════════════╝')}
+`);
+}
+
+function setupEventHandlers(server, protocol) {
+  const { createTextDelta, createToolStart, createToolResult } = protocol;
+
+  // Session events
+  server.on('session:connected', (sessionId, session) => {
+    console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Session connected: ${chalk.cyan(sessionId)}`);
+  });
+
+  server.on('session:disconnected', sessionId => {
+    console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Session disconnected: ${chalk.yellow(sessionId)}`);
+  });
+
+  // User message handler - uses real Claude CLI
+  server.on('user:message', async (session, content) => {
+    console.log(
+      chalk.dim(`[${new Date().toISOString()}]`) +
+        ` Message from ${chalk.cyan(session.id)}: ${chalk.white(content.slice(0, 50))}...`
+    );
+
+    // Use real Claude CLI
+    await handleClaudeMessage(session, content, { createTextDelta, createToolStart, createToolResult });
+  });
+
+  // Cancel handler
+  server.on('user:cancel', session => {
+    console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Cancel from ${chalk.yellow(session.id)}`);
+    // Note: To properly cancel, we'd need to track the bridge per session
+    // For now, this just logs the cancel request
+    session.setState('idle');
+  });
+
+  // Refresh handlers
+  server.on('refresh:tasks', session => {
+    console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Task refresh for ${chalk.cyan(session.id)}`);
+  });
+
+  server.on('refresh:status', session => {
+    console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Status refresh for ${chalk.cyan(session.id)}`);
+  });
+}
+
+async function handleClaudeMessage(session, content, protocol) {
+  const { createTextDelta, createToolStart, createToolResult } = protocol;
+  const { createClaudeBridge } = require('../../../lib/claude-cli-bridge');
+
+  // Set session state to thinking
+  session.setState('thinking');
+
+  try {
+    const bridge = createClaudeBridge({
+      cwd: process.cwd(),
+
+      onText: (text, done) => {
+        // Always send text deltas (even empty ones with done=true to signal completion)
+        if (text) {
+          console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Text: ${chalk.green(text.slice(0, 50))}${text.length > 50 ? '...' : ''}`);
+        }
+        session.send(createTextDelta(text || '', done));
+        if (done) {
+          console.log(chalk.dim(`[${new Date().toISOString()}]`) + chalk.green(' Response complete'));
+          session.setState('idle');
+        }
+      },
+
+      onToolStart: (id, name, input) => {
+        console.log(chalk.dim(`[${new Date().toISOString()}]`) + ` Tool: ${chalk.yellow(name)}`);
+        session.send(createToolStart(id, name, input));
+      },
+
+      onToolResult: (id, output, isError, toolName) => {
+        session.send(createToolResult(id, output, isError ? output : null));
+      },
+
+      onError: (error) => {
+        console.error(chalk.red(`[${new Date().toISOString()}]`) + ` Error: ${error}`);
+        session.send(createTextDelta(`\n\nError: ${error}`, true));
+        session.setState('error');
+      },
+
+      onComplete: (fullResponse) => {
+        session.addMessage('assistant', fullResponse);
+        session.setState('idle');
+      }
+    });
+
+    // Send the message to Claude
+    await bridge.sendMessage(content);
+
+  } catch (err) {
+    console.error(chalk.red('Claude error:'), err.message);
+    session.send(createTextDelta(`Error: ${err.message}`, true));
+    session.setState('error');
+  }
+}
+
+async function startTunnel(port, provider = 'cloudflared') {
+  const { spawn, exec } = require('child_process');
+
+  // Try cloudflared first (free, no signup needed)
+  if (provider === 'cloudflared') {
+    const url = await startCloudflaredTunnel(port, spawn, exec);
+    if (url) return url;
+    // Fall back to ngrok if cloudflared fails
+    console.log(chalk.dim('  Trying ngrok as fallback...'));
+  }
+
+  // Try ngrok
+  return startNgrokTunnel(port, exec);
+}
+
+async function startCloudflaredTunnel(port, spawn, exec) {
+  return new Promise((resolve) => {
+    // Check if cloudflared is installed
+    exec('which cloudflared', (error) => {
+      if (error) {
+        console.log(chalk.yellow('  cloudflared not found.'));
+        console.log(chalk.dim('  Install: brew install cloudflared (mac) or sudo apt install cloudflared (linux)'));
+        console.log(chalk.dim('  Or download from: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/'));
+        resolve(null);
+        return;
+      }
+
+      // Start cloudflared tunnel (quick tunnel, no account needed)
+      const tunnel = spawn('cloudflared', ['tunnel', '--url', `http://localhost:${port}`], {
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+
+      let resolved = false;
+
+      const handleOutput = (data) => {
+        const output = data.toString();
+        // Look for the tunnel URL in output
+        const urlMatch = output.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
+        if (urlMatch && !resolved) {
+          resolved = true;
+          const httpsUrl = urlMatch[0];
+          const wssUrl = httpsUrl.replace('https://', 'wss://');
+          console.log(chalk.green('  ✓ Tunnel ready'));
+          resolve(wssUrl);
+        }
+      };
+
+      tunnel.stdout.on('data', handleOutput);
+      tunnel.stderr.on('data', handleOutput);
+
+      tunnel.on('error', (err) => {
+        if (!resolved) {
+          console.log(chalk.yellow(`  cloudflared error: ${err.message}`));
+          resolve(null);
+        }
+      });
+
+      // Timeout after 15 seconds
+      setTimeout(() => {
+        if (!resolved) {
+          console.log(chalk.yellow('  cloudflared tunnel timeout'));
+          resolve(null);
+        }
+      }, 15000);
+    });
+  });
+}
+
+async function startNgrokTunnel(port, exec) {
+  return new Promise((resolve) => {
+    exec('which ngrok', (error) => {
+      if (error) {
+        console.log(chalk.yellow('  ngrok not found either.'));
+        console.log('');
+        console.log(chalk.yellow('  To enable cloud dashboard access, install a tunnel:'));
+        console.log(chalk.dim('    brew install cloudflared   # Recommended (free, no signup)'));
+        console.log(chalk.dim('    npm install -g ngrok       # Alternative (requires signup)'));
+        resolve(null);
+        return;
+      }
+
+      const ngrok = exec(`ngrok http ${port} --log stdout`, { encoding: 'utf8' });
+
+      let resolved = false;
+
+      ngrok.stdout.on('data', data => {
+        const urlMatch = data.match(/url=(https?:\/\/[^\s]+)/);
+        if (urlMatch && !resolved) {
+          resolved = true;
+          const tunnelUrl = urlMatch[1].replace('https://', 'wss://').replace('http://', 'ws://');
+          console.log(chalk.green('  ✓ ngrok tunnel ready'));
+          resolve(tunnelUrl);
+        }
+      });
+
+      ngrok.stderr.on('data', data => {
+        if (!resolved && data.includes('error')) {
+          console.error(chalk.red('  ngrok error:'), data);
+        }
+      });
+
+      setTimeout(() => {
+        if (!resolved) {
+          console.log(chalk.yellow('  ngrok tunnel timeout'));
+          resolve(null);
+        }
+      }, 10000);
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if port is in use and handle conflict
+ */
+async function handlePortConflict(port, readline) {
+  const { execSync } = require('child_process');
+  const net = require('net');
+
+  // Check if port is in use
+  const isPortInUse = await new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(true);
+      } else {
+        resolve(false);
+      }
+    });
+    server.once('listening', () => {
+      server.close();
+      resolve(false);
+    });
+    server.listen(port);
+  });
+
+  if (!isPortInUse) {
+    return port;
+  }
+
+  // Port is in use - find out what's using it
+  let processInfo = '';
+  try {
+    processInfo = execSync(`lsof -i :${port} -t 2>/dev/null`, { encoding: 'utf-8' }).trim();
+  } catch (e) {
+    // lsof might not be available or port check failed
+  }
+
+  console.log(chalk.yellow(`\n  Port ${port} is already in use.`));
+
+  if (processInfo) {
+    console.log(chalk.dim(`  Process ID: ${processInfo}`));
+  }
+
+  // Ask user what to do
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    console.log('');
+    console.log('  Options:');
+    console.log(chalk.cyan('    [k]') + ' Kill existing process and use this port');
+    console.log(chalk.cyan('    [n]') + ' Use next available port');
+    console.log(chalk.cyan('    [q]') + ' Quit');
+    console.log('');
+
+    rl.question('  Your choice (k/n/q): ', async (answer) => {
+      rl.close();
+      const choice = answer.toLowerCase().trim();
+
+      if (choice === 'k' && processInfo) {
+        // Kill the process
+        try {
+          execSync(`kill ${processInfo}`, { encoding: 'utf-8' });
+          console.log(chalk.green(`  Killed process ${processInfo}`));
+          await sleep(500); // Give it a moment to release the port
+          resolve(port);
+        } catch (e) {
+          console.log(chalk.red(`  Failed to kill process: ${e.message}`));
+          console.log(chalk.dim('  Trying next available port instead...'));
+          resolve(await findNextAvailablePort(port));
+        }
+      } else if (choice === 'n') {
+        const newPort = await findNextAvailablePort(port);
+        console.log(chalk.green(`  Using port ${newPort}`));
+        resolve(newPort);
+      } else {
+        console.log(chalk.dim('  Exiting.'));
+        process.exit(0);
+      }
+    });
+  });
+}
+
+/**
+ * Find next available port starting from given port
+ */
+async function findNextAvailablePort(startPort) {
+  const net = require('net');
+  let port = startPort + 1;
+
+  while (port < startPort + 100) {
+    const available = await new Promise((resolve) => {
+      const server = net.createServer();
+      server.once('error', () => resolve(false));
+      server.once('listening', () => {
+        server.close();
+        resolve(true);
+      });
+      server.listen(port);
+    });
+
+    if (available) {
+      return port;
+    }
+    port++;
+  }
+
+  throw new Error('Could not find an available port');
+}

package/tools/cli/installers/core/installer.js

@@ -139,6 +139,7 @@ class Installer {
           fileOps,
           force: effectiveForce,
           timestamp,
+          docsFolder: docsFolder || 'docs',
         });
       } else {
         // Fallback: copy from old structure (commands, agents, skills at root)
@@ -149,6 +150,7 @@ class Installer {
           fileOps,
           force: effectiveForce,
           timestamp,
+          docsFolder: docsFolder || 'docs',
         });
       }
 
@@ -295,8 +297,9 @@ class Installer {
    * @param {string} source - Source file path
    * @param {string} dest - Destination file path
    * @param {string} agileflowFolder - AgileFlow folder name
+   * @param {string} docsFolder - Docs folder name (default: 'docs')
    */
-  async copyFileWithReplacements(source, dest, agileflowFolder) {
+  async copyFileWithReplacements(source, dest, agileflowFolder, docsFolder = 'docs') {
     const ext = path.extname(source).toLowerCase();
 
     if (TEXT_EXTENSIONS.has(ext)) {
@@ -306,6 +309,7 @@ class Installer {
       content = injectContent(content, {
         coreDir: this.coreDir,
         agileflowFolder,
+        docsFolder,
         version: this.version,
       });
 
@@ -326,7 +330,7 @@ class Installer {
    * @param {Object} policy - Copy policy
    */
   async copyFileWithPolicy(source, dest, agileflowFolder, policy) {
-    const { agileflowDir, cfgDir, fileIndex, fileOps, force, timestamp } = policy;
+    const { agileflowDir, cfgDir, fileIndex, fileOps, force, timestamp, docsFolder = 'docs' } = policy;
 
     const relativePath = toPosixPath(path.relative(agileflowDir, dest));
     const maybeRecord = fileIndex.files[relativePath];
@@ -342,6 +346,7 @@ class Installer {
       content = injectContent(content, {
         coreDir: this.coreDir,
         agileflowFolder,
+        docsFolder,
         version: this.version,
       });
       newContent = content;

package/tools/cli/installers/ide/claude-code.js

@@ -56,6 +56,9 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     // Claude Code specific: Setup damage control hooks
     await this.setupDamageControl(projectDir, agileflowDir, ideDir, options);
 
+    // Claude Code specific: Setup SessionStart hooks (welcome, archive, context-loader)
+    await this.setupSessionStartHooks(projectDir, agileflowDir, ideDir, options);
+
     return result;
   }
 
@@ -93,6 +96,14 @@ class ClaudeCodeSetup extends BaseIdeSetup {
       }
     }
 
+    // Copy lib/damage-control-utils.js (required by hook scripts via ../lib/damage-control-utils)
+    const libSource = path.join(agileflowDir, 'scripts', 'lib', 'damage-control-utils.js');
+    const libTarget = path.join(claudeDir, 'hooks', 'lib', 'damage-control-utils.js');
+    if (fs.existsSync(libSource)) {
+      await this.ensureDir(path.dirname(libTarget));
+      await fs.copy(libSource, libTarget);
+    }
+
     // Copy patterns.yaml (preserve existing)
     const patternsSource = path.join(damageControlSource, 'patterns.yaml');
     const patternsTarget = path.join(damageControlTarget, 'patterns.yaml');
@@ -195,6 +206,80 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     // Write settings
     await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
   }
+
+  /**
+   * Setup SessionStart hooks (welcome, archive, context-loader)
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} claudeDir - .claude directory path
+   * @param {Object} options - Setup options
+   */
+  async setupSessionStartHooks(projectDir, agileflowDir, claudeDir, options = {}) {
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    let settings = {};
+
+    // Load existing settings
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      } catch (e) {
+        settings = {};
+      }
+    }
+
+    // Initialize hooks structure
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+    // Define SessionStart hooks
+    const sessionStartHooks = [
+      {
+        type: 'command',
+        command: 'node $CLAUDE_PROJECT_DIR/.agileflow/scripts/agileflow-welcome.js 2>/dev/null || true',
+        timeout: 10000,
+      },
+      {
+        type: 'command',
+        command:
+          'bash $CLAUDE_PROJECT_DIR/.agileflow/scripts/archive-completed-stories.sh --quiet 2>/dev/null || true',
+        timeout: 10000,
+      },
+      {
+        type: 'command',
+        command: 'node $CLAUDE_PROJECT_DIR/.agileflow/scripts/context-loader.js 2>/dev/null || true',
+        timeout: 5000,
+      },
+    ];
+
+    // Check if SessionStart hooks already exist
+    const existingEntry = settings.hooks.SessionStart.find(
+      h => h.matcher === '' || h.matcher === undefined
+    );
+
+    if (existingEntry) {
+      // Merge hooks - add any missing
+      if (!existingEntry.hooks) existingEntry.hooks = [];
+
+      for (const newHook of sessionStartHooks) {
+        const alreadyExists = existingEntry.hooks.some(
+          h => h.command && h.command.includes(newHook.command.split('/').pop().split(' ')[0])
+        );
+        if (!alreadyExists) {
+          existingEntry.hooks.push(newHook);
+        }
+      }
+    } else {
+      // Add new entry
+      settings.hooks.SessionStart.push({
+        matcher: '',
+        hooks: sessionStartHooks,
+      });
+    }
+
+    // Write settings
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    console.log(chalk.dim(`    - SessionStart hooks: welcome, archive, context-loader`));
+  }
 }
 
 module.exports = { ClaudeCodeSetup };

package/tools/cli/lib/content-injector.js

@@ -23,7 +23,12 @@
  *
  * FOLDER REFERENCES:
  *   {agileflow_folder} - Name of the agileflow folder (e.g., .agileflow)
+ *   {docs_folder}      - Name of the docs folder (e.g., docs, agileflow-docs)
  *   {project-root}     - Project root reference
+ *
+ * PATH INJECTION:
+ *   When docsFolder is not 'docs', all path references like `docs/` are replaced
+ *   with the actual folder name (e.g., `agileflow-docs/`).
  */
 
 const fs = require('fs');
@@ -473,11 +478,12 @@ function clearPreserveRulesCache() {
  * @param {Object} context - Context for replacements
  * @param {string} context.coreDir - Path to core directory (commands/, agents/, skills/)
  * @param {string} context.agileflowFolder - AgileFlow folder name
+ * @param {string} context.docsFolder - Docs folder name (default: 'docs')
  * @param {string} context.version - AgileFlow version
  * @returns {string} Content with all placeholders replaced
  */
 function injectContent(content, context = {}) {
-  const { coreDir, agileflowFolder = '.agileflow', version = 'unknown' } = context;
+  const { coreDir, agileflowFolder = '.agileflow', docsFolder = 'docs', version = 'unknown' } = context;
 
   let result = content;
 
@@ -502,6 +508,10 @@ function injectContent(content, context = {}) {
     'agileflow_folder',
     agileflowFolder
   ).sanitized;
+  const safeDocsFolder = validatePlaceholderValue(
+    'docs_folder',
+    docsFolder
+  ).sanitized;
 
   // Replace count placeholders (both formats: {{X}} and <!-- {{X}} -->)
   result = result.replace(/\{\{COMMAND_COUNT\}\}/g, String(safeCommandCount));
@@ -593,8 +603,22 @@ function injectContent(content, context = {}) {
 
   // Replace folder placeholders with sanitized values
   result = result.replace(/\{agileflow_folder\}/g, safeAgileflowFolder);
+  result = result.replace(/\{docs_folder\}/g, safeDocsFolder);
   result = result.replace(/\{project-root\}/g, '{project-root}'); // Keep as-is for runtime
 
+  // Replace docs/ path references with actual folder if different from default
+  // This ensures all path references point to the correct folder
+  // Pattern matches: `docs/`, "docs/", 'docs/' but NOT word boundaries like "documents/"
+  if (safeDocsFolder !== 'docs') {
+    // Replace in code/path contexts: `docs/xxx`, "docs/xxx", 'docs/xxx'
+    result = result.replace(/`docs\//g, `\`${safeDocsFolder}/`);
+    result = result.replace(/"docs\//g, `"${safeDocsFolder}/`);
+    result = result.replace(/'docs\//g, `'${safeDocsFolder}/`);
+    // Replace standalone path references like: docs/00-meta, docs/09-agents
+    // Must be followed by a path component (letter, number, or dash)
+    result = result.replace(/\bdocs\/([0-9a-zA-Z_-])/g, `${safeDocsFolder}/$1`);
+  }
+
   return result;
 }
 
@@ -690,6 +714,7 @@ function hasPlaceholders(content) {
     /\{\{QUALITY_GATE_PRIORITIES\}\}/,
     /\{\{RULES:\w+\}\}/,
     /\{agileflow_folder\}/,
+    /\{docs_folder\}/,
   ];
 
   return patterns.some(pattern => pattern.test(content));
@@ -735,6 +760,7 @@ function getPlaceholderDocs() {
     },
     folders: {
       '{agileflow_folder}': 'Name of the AgileFlow folder',
+      '{docs_folder}': 'Name of the docs folder (docs/ paths auto-replaced when different)',
       '{project-root}': 'Project root reference (kept as-is)',
     },
   };