forge-workflow 1.4.7 → 1.4.9

package/bin/forge.js

@@ -32,10 +32,10 @@
  *   bunx forge setup --quick
  */
 
-const fs = require('fs');
-const path = require('path');
-const readline = require('readline');
-const { execSync } = require('child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+const { execSync } = require('node:child_process');
 
 // Get version from package.json (single source of truth)
 const packageDir = path.dirname(__dirname);
@@ -188,6 +188,8 @@ function safeExec(cmd) {
   try {
     return execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
   } catch (e) {
+    // Command execution failure is expected when tool is not installed or fails
+    // Returning null allows caller to handle missing tools gracefully
     return null;
   }
 }
@@ -212,7 +214,7 @@ function checkPrerequisites() {
   // Check GitHub CLI
   const ghVersion = safeExec('gh --version');
   if (ghVersion) {
-    console.log(`  ✓ ${ghVersion.split('\\n')[0]}`);
+    console.log(`  ✓ ${ghVersion.split(String.raw`\n`)[0]}`);
     // Check if authenticated
     const authStatus = safeExec('gh auth status');
     if (!authStatus) {
@@ -223,7 +225,7 @@ function checkPrerequisites() {
   }
 
   // Check Node.js version
-  const nodeVersion = parseInt(process.version.slice(1).split('.')[0]);
+  const nodeVersion = Number.parseInt(process.version.slice(1).split('.')[0]);
   if (nodeVersion >= 20) {
     console.log(`  ✓ node ${process.version}`);
   } else {
@@ -434,10 +436,8 @@ function copyFile(src, dest) {
       }
       fs.copyFileSync(src, destPath);
       return true;
-    } else {
-      if (process.env.DEBUG) {
-        console.warn(`  ⚠ Source file not found: ${src}`);
-      }
+    } else if (process.env.DEBUG) {
+      console.warn(`  ⚠ Source file not found: ${src}`);
     }
   } catch (err) {
     console.error(`  ✗ Failed to copy ${src} -> ${dest}: ${err.message}`);
@@ -472,7 +472,9 @@ function createSymlinkOrCopy(source, target) {
       const relPath = path.relative(targetDir, fullSource);
       fs.symlinkSync(relPath, fullTarget);
       return 'linked';
-    } catch (symlinkErr) {
+    } catch (error_) {
+      // Symlink creation may fail due to permissions or OS limitations (e.g., Windows without admin)
+      // Fall back to copying the file instead to ensure operation succeeds
       fs.copyFileSync(fullSource, fullTarget);
       return 'copied';
     }
@@ -494,7 +496,10 @@ function readEnvFile() {
     if (fs.existsSync(envPath)) {
       return fs.readFileSync(envPath, 'utf8');
     }
-  } catch (err) {}
+  } catch (err) {
+    // File read failure is acceptable - file may not exist or have permission issues
+    // Return empty string to allow caller to proceed with defaults
+  }
   return '';
 }
 
@@ -535,7 +540,7 @@ function writeEnvTokens(tokens, preserveExisting = true) {
 
   // Add/update tokens - PRESERVE existing values if preserveExisting is true
   Object.entries(tokens).forEach(([key, value]) => {
-    if (value && value.trim()) {
+    if (value?.trim()) {
       if (preserveExisting && existingKeys.has(key)) {
         // Keep existing value, don't overwrite
         preserved.push(key);
@@ -552,12 +557,14 @@ function writeEnvTokens(tokens, preserveExisting = true) {
 
   // Add header if new file
   if (!content.includes('# External Service API Keys')) {
-    outputLines.push('# External Service API Keys for Forge Workflow');
-    outputLines.push('# Get your keys from:');
-    outputLines.push('#   Parallel AI: https://platform.parallel.ai');
-    outputLines.push('#   Greptile: https://app.greptile.com/api');
-    outputLines.push('#   SonarCloud: https://sonarcloud.io/account/security');
-    outputLines.push('');
+    outputLines.push(
+      '# External Service API Keys for Forge Workflow',
+      '# Get your keys from:',
+      '#   Parallel AI: https://platform.parallel.ai',
+      '#   Greptile: https://app.greptile.com/api',
+      '#   SonarCloud: https://sonarcloud.io/account/security',
+      ''
+    );
   }
 
   // Add existing content (preserve order and comments)
@@ -591,7 +598,10 @@ function writeEnvTokens(tokens, preserveExisting = true) {
     if (!gitignore.includes('.env.local')) {
       fs.appendFileSync(gitignorePath, '\n# Local environment variables\n.env.local\n');
     }
-  } catch (err) {}
+  } catch (err) {
+    // Gitignore update is optional - failure doesn't prevent .env.local creation
+    // User can manually add .env.local to .gitignore if needed
+  }
 
   return { added, preserved };
 }
@@ -648,7 +658,7 @@ async function askYesNo(question, prompt, defaultNo = true) {
     const normalized = answer.trim().toLowerCase();
 
     // Handle empty input (use default)
-    if (normalized === '') return defaultNo ? false : true;
+    if (normalized === '') return !defaultNo;
 
     // Accept yes variations
     if (normalized === 'y' || normalized === 'yes') return true;
@@ -709,6 +719,238 @@ function detectProjectStatus() {
   return status;
 }
 
+// Helper: Detect test framework from dependencies
+function detectTestFramework(deps) {
+  if (deps.jest) return 'jest';
+  if (deps.vitest) return 'vitest';
+  if (deps.mocha) return 'mocha';
+  if (deps['@playwright/test']) return 'playwright';
+  if (deps.cypress) return 'cypress';
+  if (deps.karma) return 'karma';
+  return null;
+}
+
+// Helper: Detect language features (TypeScript, monorepo, Docker, CI/CD)
+function detectLanguageFeatures(pkg) {
+  const features = {
+    typescript: false,
+    monorepo: false,
+    docker: false,
+    cicd: false
+  };
+
+  // Detect TypeScript
+  if (pkg.devDependencies?.typescript || pkg.dependencies?.typescript) {
+    features.typescript = true;
+  }
+
+  // Detect monorepo
+  if (pkg.workspaces ||
+      fs.existsSync(path.join(projectRoot, 'pnpm-workspace.yaml')) ||
+      fs.existsSync(path.join(projectRoot, 'lerna.json'))) {
+    features.monorepo = true;
+  }
+
+  // Detect Docker
+  if (fs.existsSync(path.join(projectRoot, 'Dockerfile')) ||
+      fs.existsSync(path.join(projectRoot, 'docker-compose.yml'))) {
+    features.docker = true;
+  }
+
+  // Detect CI/CD
+  if (fs.existsSync(path.join(projectRoot, '.github/workflows')) ||
+      fs.existsSync(path.join(projectRoot, '.gitlab-ci.yml')) ||
+      fs.existsSync(path.join(projectRoot, 'azure-pipelines.yml')) ||
+      fs.existsSync(path.join(projectRoot, '.circleci/config.yml'))) {
+    features.cicd = true;
+  }
+
+  return features;
+}
+
+// Helper: Detect Next.js framework
+function detectNextJs(deps) {
+  if (!deps.next) return null;
+
+  return {
+    framework: 'Next.js',
+    frameworkConfidence: 100,
+    projectType: 'fullstack',
+    buildTool: 'next',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect NestJS framework
+function detectNestJs(deps) {
+  if (!deps['@nestjs/core'] && !deps['@nestjs/common']) return null;
+
+  return {
+    framework: 'NestJS',
+    frameworkConfidence: 100,
+    projectType: 'backend',
+    buildTool: 'nest',
+    testFramework: 'jest'
+  };
+}
+
+// Helper: Detect Angular framework
+function detectAngular(deps) {
+  if (!deps['@angular/core'] && !deps['@angular/cli']) return null;
+
+  return {
+    framework: 'Angular',
+    frameworkConfidence: 100,
+    projectType: 'frontend',
+    buildTool: 'ng',
+    testFramework: 'karma'
+  };
+}
+
+// Helper: Detect Vue.js framework
+function detectVue(deps) {
+  if (!deps.vue) return null;
+
+  if (deps.nuxt) {
+    return {
+      framework: 'Nuxt',
+      frameworkConfidence: 100,
+      projectType: 'fullstack',
+      buildTool: 'nuxt',
+      testFramework: detectTestFramework(deps)
+    };
+  }
+
+  const hasVite = deps.vite;
+  const hasWebpack = deps.webpack;
+
+  return {
+    framework: 'Vue.js',
+    frameworkConfidence: deps['@vue/cli'] ? 100 : 90,
+    projectType: 'frontend',
+    buildTool: hasVite ? 'vite' : (hasWebpack ? 'webpack' : 'vue-cli'),
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect React framework
+function detectReact(deps) {
+  if (!deps.react) return null;
+
+  const hasVite = deps.vite;
+  const hasReactScripts = deps['react-scripts'];
+
+  return {
+    framework: 'React',
+    frameworkConfidence: 95,
+    projectType: 'frontend',
+    buildTool: hasVite ? 'vite' : (hasReactScripts ? 'create-react-app' : 'webpack'),
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect Express framework
+function detectExpress(deps, features) {
+  if (!deps.express) return null;
+
+  return {
+    framework: 'Express',
+    frameworkConfidence: 90,
+    projectType: 'backend',
+    buildTool: features.typescript ? 'tsc' : 'node',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect Fastify framework
+function detectFastify(deps, features) {
+  if (!deps.fastify) return null;
+
+  return {
+    framework: 'Fastify',
+    frameworkConfidence: 95,
+    projectType: 'backend',
+    buildTool: features.typescript ? 'tsc' : 'node',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect Svelte framework
+function detectSvelte(deps) {
+  if (!deps.svelte) return null;
+
+  if (deps['@sveltejs/kit']) {
+    return {
+      framework: 'SvelteKit',
+      frameworkConfidence: 100,
+      projectType: 'fullstack',
+      buildTool: 'vite',
+      testFramework: detectTestFramework(deps)
+    };
+  }
+
+  return {
+    framework: 'Svelte',
+    frameworkConfidence: 95,
+    projectType: 'frontend',
+    buildTool: 'vite',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect Remix framework
+function detectRemix(deps) {
+  if (!deps['@remix-run/react']) return null;
+
+  return {
+    framework: 'Remix',
+    frameworkConfidence: 100,
+    projectType: 'fullstack',
+    buildTool: 'remix',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect Astro framework
+function detectAstro(deps) {
+  if (!deps.astro) return null;
+
+  return {
+    framework: 'Astro',
+    frameworkConfidence: 100,
+    projectType: 'frontend',
+    buildTool: 'astro',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect generic Node.js project
+function detectGenericNodeJs(pkg, deps, features) {
+  if (!pkg.main && !pkg.scripts?.start) return null;
+
+  return {
+    framework: 'Node.js',
+    frameworkConfidence: 70,
+    projectType: 'backend',
+    buildTool: features.typescript ? 'tsc' : 'node',
+    testFramework: detectTestFramework(deps)
+  };
+}
+
+// Helper: Detect generic JavaScript/TypeScript project (fallback)
+function detectGenericProject(deps, features) {
+  const hasVite = deps.vite;
+  const hasWebpack = deps.webpack;
+
+  return {
+    framework: features.typescript ? 'TypeScript' : 'JavaScript',
+    frameworkConfidence: 60,
+    projectType: 'library',
+    buildTool: hasVite ? 'vite' : (hasWebpack ? 'webpack' : 'npm'),
+    testFramework: detectTestFramework(deps)
+  };
+}
+
 // Detect project type from package.json
 function detectProjectType() {
   const detection = {
@@ -733,174 +975,34 @@ function detectProjectType() {
 
   detection.hasPackageJson = true;
 
-  // Detect TypeScript
-  if (pkg.devDependencies?.typescript || pkg.dependencies?.typescript) {
-    detection.features.typescript = true;
+  // Detect language features
+  detection.features = detectLanguageFeatures(pkg);
+  if (detection.features.typescript) {
     detection.language = 'typescript';
   }
 
-  // Detect monorepo
-  if (pkg.workspaces || fs.existsSync(path.join(projectRoot, 'pnpm-workspace.yaml')) || fs.existsSync(path.join(projectRoot, 'lerna.json'))) {
-    detection.features.monorepo = true;
-  }
-
-  // Detect Docker
-  if (fs.existsSync(path.join(projectRoot, 'Dockerfile')) || fs.existsSync(path.join(projectRoot, 'docker-compose.yml'))) {
-    detection.features.docker = true;
-  }
-
-  // Detect CI/CD
-  if (fs.existsSync(path.join(projectRoot, '.github/workflows')) ||
-      fs.existsSync(path.join(projectRoot, '.gitlab-ci.yml')) ||
-      fs.existsSync(path.join(projectRoot, 'azure-pipelines.yml')) ||
-      fs.existsSync(path.join(projectRoot, '.circleci/config.yml'))) {
-    detection.features.cicd = true;
-  }
-
   // Framework detection with confidence scoring
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
 
-  // Helper function for test framework detection
-  const detectTestFramework = (deps) => {
-    if (deps.jest) return 'jest';
-    if (deps.vitest) return 'vitest';
-    if (deps.mocha) return 'mocha';
-    if (deps['@playwright/test']) return 'playwright';
-    if (deps.cypress) return 'cypress';
-    if (deps.karma) return 'karma';
-    return null;
-  };
-
-  // Next.js (highest priority for React projects)
-  if (deps.next) {
-    detection.framework = 'Next.js';
-    detection.frameworkConfidence = 100;
-    detection.projectType = 'fullstack';
-    detection.buildTool = 'next';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // NestJS (backend framework)
-  if (deps['@nestjs/core'] || deps['@nestjs/common']) {
-    detection.framework = 'NestJS';
-    detection.frameworkConfidence = 100;
-    detection.projectType = 'backend';
-    detection.buildTool = 'nest';
-    detection.testFramework = 'jest';
-    return detection;
-  }
-
-  // Angular
-  if (deps['@angular/core'] || deps['@angular/cli']) {
-    detection.framework = 'Angular';
-    detection.frameworkConfidence = 100;
-    detection.projectType = 'frontend';
-    detection.buildTool = 'ng';
-    detection.testFramework = 'karma';
-    return detection;
-  }
-
-  // Vue.js
-  if (deps.vue) {
-    if (deps.nuxt) {
-      detection.framework = 'Nuxt';
-      detection.frameworkConfidence = 100;
-      detection.projectType = 'fullstack';
-      detection.buildTool = 'nuxt';
-    } else {
-      detection.framework = 'Vue.js';
-      detection.frameworkConfidence = deps['@vue/cli'] ? 100 : 90;
-      detection.projectType = 'frontend';
-      detection.buildTool = deps.vite ? 'vite' : deps.webpack ? 'webpack' : 'vue-cli';
-    }
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // React (without Next.js)
-  if (deps.react) {
-    detection.framework = 'React';
-    detection.frameworkConfidence = 95;
-    detection.projectType = 'frontend';
-    detection.buildTool = deps.vite ? 'vite' : deps['react-scripts'] ? 'create-react-app' : 'webpack';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Express (backend)
-  if (deps.express) {
-    detection.framework = 'Express';
-    detection.frameworkConfidence = 90;
-    detection.projectType = 'backend';
-    detection.buildTool = detection.features.typescript ? 'tsc' : 'node';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Fastify (backend)
-  if (deps.fastify) {
-    detection.framework = 'Fastify';
-    detection.frameworkConfidence = 95;
-    detection.projectType = 'backend';
-    detection.buildTool = detection.features.typescript ? 'tsc' : 'node';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Svelte
-  if (deps.svelte) {
-    if (deps['@sveltejs/kit']) {
-      detection.framework = 'SvelteKit';
-      detection.frameworkConfidence = 100;
-      detection.projectType = 'fullstack';
-      detection.buildTool = 'vite';
-    } else {
-      detection.framework = 'Svelte';
-      detection.frameworkConfidence = 95;
-      detection.projectType = 'frontend';
-      detection.buildTool = 'vite';
-    }
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Remix
-  if (deps['@remix-run/react']) {
-    detection.framework = 'Remix';
-    detection.frameworkConfidence = 100;
-    detection.projectType = 'fullstack';
-    detection.buildTool = 'remix';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Astro
-  if (deps.astro) {
-    detection.framework = 'Astro';
-    detection.frameworkConfidence = 100;
-    detection.projectType = 'frontend';
-    detection.buildTool = 'astro';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Generic Node.js project
-  if (pkg.main || pkg.scripts?.start) {
-    detection.framework = 'Node.js';
-    detection.frameworkConfidence = 70;
-    detection.projectType = 'backend';
-    detection.buildTool = detection.features.typescript ? 'tsc' : 'node';
-    detection.testFramework = detectTestFramework(deps);
-    return detection;
-  }
-
-  // Fallback: generic JavaScript/TypeScript project
-  detection.framework = detection.features.typescript ? 'TypeScript' : 'JavaScript';
-  detection.frameworkConfidence = 60;
-  detection.projectType = 'library';
-  detection.buildTool = deps.vite ? 'vite' : deps.webpack ? 'webpack' : 'npm';
-  detection.testFramework = detectTestFramework(deps);
+  // Try framework detectors in priority order
+  const frameworkResult =
+    detectNextJs(deps) ||
+    detectNestJs(deps) ||
+    detectAngular(deps) ||
+    detectVue(deps) ||
+    detectReact(deps) ||
+    detectExpress(deps, detection.features) ||
+    detectFastify(deps, detection.features) ||
+    detectSvelte(deps) ||
+    detectRemix(deps) ||
+    detectAstro(deps) ||
+    detectGenericNodeJs(pkg, deps, detection.features) ||
+    detectGenericProject(deps, detection.features);
+
+  // Merge framework detection results
+  if (frameworkResult) {
+    Object.assign(detection, frameworkResult);
+  }
 
   return detection;
 }
@@ -1045,9 +1147,7 @@ function updateAgentsMdWithProjectType(detection) {
   // Add framework-specific tips
   const tips = generateFrameworkTips(detection);
   if (tips.length > 0) {
-    metadata.push('');
-    metadata.push('**Framework conventions**:');
-    metadata.push(...tips);
+    metadata.push('', '**Framework conventions**:', ...tips);
   }
 
   // Insert metadata
@@ -1056,142 +1156,149 @@ function updateAgentsMdWithProjectType(detection) {
   fs.writeFileSync(agentsPath, lines.join('\n'), 'utf-8');
 }
 
-// Smart file selection with context warnings
-async function handleInstructionFiles(rl, question, selectedAgents, projectStatus) {
-  const hasClaude = selectedAgents.some(a => a.key === 'claude');
-  const hasOtherAgents = selectedAgents.some(a => a.key !== 'claude');
-
-  // Calculate estimated tokens (rough: ~4 chars per token)
-  const estimateTokens = (bytes) => Math.ceil(bytes / 4);
+// Helper: Calculate estimated tokens (rough: ~4 chars per token)
+function estimateTokens(bytes) {
+  return Math.ceil(bytes / 4);
+}
 
-  const result = {
-    createAgentsMd: false,
-    createClaudeMd: false,
-    skipAgentsMd: false,
-    skipClaudeMd: false
+// Helper: Create instruction files result object
+function createInstructionFilesResult(createAgentsMd = false, createClaudeMd = false, skipAgentsMd = false, skipClaudeMd = false) {
+  return {
+    createAgentsMd,
+    createClaudeMd,
+    skipAgentsMd,
+    skipClaudeMd
   };
+}
 
-  // Scenario 1: Both files exist (potential context bloat)
-  if (projectStatus.hasAgentsMd && projectStatus.hasClaudeMd) {
-    const totalLines = projectStatus.agentsMdLines + projectStatus.claudeMdLines;
-    const totalTokens = estimateTokens(projectStatus.agentsMdSize + projectStatus.claudeMdSize);
+// Helper: Handle scenario where both AGENTS.md and CLAUDE.md exist
+async function handleBothFilesExist(question, projectStatus) {
+  const totalLines = projectStatus.agentsMdLines + projectStatus.claudeMdLines;
+  const totalTokens = estimateTokens(projectStatus.agentsMdSize + projectStatus.claudeMdSize);
 
-    console.log('');
-    console.log('⚠️  WARNING: Multiple Instruction Files Detected');
-    console.log('='.repeat(60));
-    console.log(`  AGENTS.md:  ${projectStatus.agentsMdLines} lines (~${estimateTokens(projectStatus.agentsMdSize)} tokens)`);
-    console.log(`  CLAUDE.md:  ${projectStatus.claudeMdLines} lines (~${estimateTokens(projectStatus.claudeMdSize)} tokens)`);
-    console.log(`  Total:      ${totalLines} lines (~${totalTokens} tokens)`);
-    console.log('');
-    console.log('  ⚠️  Claude Code reads BOTH files on every request');
-    console.log('  ⚠️  This increases context usage and costs');
-    console.log('');
-    console.log('  Options:');
-    console.log('  1) Keep CLAUDE.md only (recommended for Claude Code only)');
-    console.log('  2) Keep AGENTS.md only (recommended for multi-agent users)');
-    console.log('  3) Keep both (higher context usage)');
-    console.log('');
+  console.log('');
+  console.log('⚠️  WARNING: Multiple Instruction Files Detected');
+  console.log('='.repeat(60));
+  console.log(`  AGENTS.md:  ${projectStatus.agentsMdLines} lines (~${estimateTokens(projectStatus.agentsMdSize)} tokens)`);
+  console.log(`  CLAUDE.md:  ${projectStatus.claudeMdLines} lines (~${estimateTokens(projectStatus.claudeMdSize)} tokens)`);
+  console.log(`  Total:      ${totalLines} lines (~${totalTokens} tokens)`);
+  console.log('');
+  console.log('  ⚠️  Claude Code reads BOTH files on every request');
+  console.log('  ⚠️  This increases context usage and costs');
+  console.log('');
+  console.log('  Options:');
+  console.log('  1) Keep CLAUDE.md only (recommended for Claude Code only)');
+  console.log('  2) Keep AGENTS.md only (recommended for multi-agent users)');
+  console.log('  3) Keep both (higher context usage)');
+  console.log('');
 
-    while (true) {
-      const choice = await question('Your choice (1/2/3) [2]: ');
-      const normalized = choice.trim() || '2';
-
-      if (normalized === '1') {
-        result.skipAgentsMd = true;
-        result.createClaudeMd = false; // Keep existing
-        console.log('  ✓ Will keep CLAUDE.md, remove AGENTS.md');
-        break;
-      } else if (normalized === '2') {
-        result.skipClaudeMd = true;
-        result.createAgentsMd = false; // Keep existing
-        console.log('  ✓ Will keep AGENTS.md, remove CLAUDE.md');
-        break;
-      } else if (normalized === '3') {
-        result.createAgentsMd = false; // Keep existing
-        result.createClaudeMd = false; // Keep existing
-        console.log('  ✓ Will keep both files (context: ~' + totalTokens + ' tokens)');
-        break;
-      } else {
-        console.log('  Please enter 1, 2, or 3');
-      }
+  while (true) {
+    const choice = await question('Your choice (1/2/3) [2]: ');
+    const normalized = choice.trim() || '2';
+
+    if (normalized === '1') {
+      console.log('  ✓ Will keep CLAUDE.md, remove AGENTS.md');
+      return createInstructionFilesResult(false, false, true, false);
+    } else if (normalized === '2') {
+      console.log('  ✓ Will keep AGENTS.md, remove CLAUDE.md');
+      return createInstructionFilesResult(false, false, false, true);
+    } else if (normalized === '3') {
+      console.log('  ✓ Will keep both files (context: ~' + totalTokens + ' tokens)');
+      return createInstructionFilesResult(false, false, false, false);
+    } else {
+      console.log('  Please enter 1, 2, or 3');
     }
-
-    return result;
   }
+}
 
-  // Scenario 2: Only CLAUDE.md exists
-  if (projectStatus.hasClaudeMd && !projectStatus.hasAgentsMd) {
-    if (hasOtherAgents) {
-      console.log('');
-      console.log('📋 Found existing CLAUDE.md (' + projectStatus.claudeMdLines + ' lines)');
-      console.log('   You selected multiple agents. Recommendation:');
-      console.log('   → Migrate to AGENTS.md (works with all agents)');
-      console.log('');
+// Helper: Handle scenario where only CLAUDE.md exists
+async function handleOnlyClaudeMdExists(question, projectStatus, hasOtherAgents) {
+  if (hasOtherAgents) {
+    console.log('');
+    console.log('📋 Found existing CLAUDE.md (' + projectStatus.claudeMdLines + ' lines)');
+    console.log('   You selected multiple agents. Recommendation:');
+    console.log('   → Migrate to AGENTS.md (works with all agents)');
+    console.log('');
 
-      const migrate = await askYesNo(question, 'Migrate CLAUDE.md to AGENTS.md?', false);
-      if (migrate) {
-        result.createAgentsMd = true;
-        result.skipClaudeMd = true;
-        console.log('  ✓ Will migrate content to AGENTS.md');
-      } else {
-        result.createAgentsMd = true;
-        result.createClaudeMd = false; // Keep existing
-        console.log('  ✓ Will keep CLAUDE.md and create AGENTS.md');
-      }
+    const migrate = await askYesNo(question, 'Migrate CLAUDE.md to AGENTS.md?', false);
+    if (migrate) {
+      console.log('  ✓ Will migrate content to AGENTS.md');
+      return createInstructionFilesResult(true, false, false, true);
     } else {
-      // Claude Code only - keep CLAUDE.md
-      result.createClaudeMd = false; // Keep existing
-      console.log('  ✓ Keeping existing CLAUDE.md');
+      console.log('  ✓ Will keep CLAUDE.md and create AGENTS.md');
+      return createInstructionFilesResult(true, false, false, false);
     }
-
-    return result;
+  } else {
+    // Claude Code only - keep CLAUDE.md
+    console.log('  ✓ Keeping existing CLAUDE.md');
+    return createInstructionFilesResult(false, false, false, false);
   }
+}
 
-  // Scenario 3: Only AGENTS.md exists
-  if (projectStatus.hasAgentsMd && !projectStatus.hasClaudeMd) {
-    if (hasClaude && !hasOtherAgents) {
-      console.log('');
-      console.log('📋 Found existing AGENTS.md (' + projectStatus.agentsMdLines + ' lines)');
-      console.log('   You selected Claude Code only. Options:');
-      console.log('   1) Keep AGENTS.md (works fine)');
-      console.log('   2) Rename to CLAUDE.md (Claude-specific naming)');
-      console.log('');
+// Helper: Handle scenario where only AGENTS.md exists
+async function handleOnlyAgentsMdExists(question, projectStatus, hasClaude, hasOtherAgents) {
+  if (hasClaude && !hasOtherAgents) {
+    console.log('');
+    console.log('📋 Found existing AGENTS.md (' + projectStatus.agentsMdLines + ' lines)');
+    console.log('   You selected Claude Code only. Options:');
+    console.log('   1) Keep AGENTS.md (works fine)');
+    console.log('   2) Rename to CLAUDE.md (Claude-specific naming)');
+    console.log('');
 
-      const rename = await askYesNo(question, 'Rename to CLAUDE.md?', true);
-      if (rename) {
-        result.createClaudeMd = true;
-        result.skipAgentsMd = true;
-        console.log('  ✓ Will rename to CLAUDE.md');
-      } else {
-        result.createAgentsMd = false; // Keep existing
-        console.log('  ✓ Keeping AGENTS.md');
-      }
+    const rename = await askYesNo(question, 'Rename to CLAUDE.md?', true);
+    if (rename) {
+      console.log('  ✓ Will rename to CLAUDE.md');
+      return createInstructionFilesResult(false, true, true, false);
     } else {
-      // Multi-agent or other agents - keep AGENTS.md
-      result.createAgentsMd = false; // Keep existing
-      console.log('  ✓ Keeping existing AGENTS.md');
+      console.log('  ✓ Keeping AGENTS.md');
+      return createInstructionFilesResult(false, false, false, false);
     }
-
-    return result;
+  } else {
+    // Multi-agent or other agents - keep AGENTS.md
+    console.log('  ✓ Keeping existing AGENTS.md');
+    return createInstructionFilesResult(false, false, false, false);
   }
+}
 
-  // Scenario 4: Neither file exists (fresh install)
+// Helper: Handle scenario where no instruction files exist (fresh install)
+function handleNoFilesExist(hasClaude, hasOtherAgents) {
   if (hasClaude && !hasOtherAgents) {
     // Claude Code only → create CLAUDE.md
-    result.createClaudeMd = true;
     console.log('  ✓ Will create CLAUDE.md (Claude Code specific)');
+    return createInstructionFilesResult(false, true, false, false);
   } else if (!hasClaude && hasOtherAgents) {
     // Other agents only → create AGENTS.md
-    result.createAgentsMd = true;
     console.log('  ✓ Will create AGENTS.md (universal)');
+    return createInstructionFilesResult(true, false, false, false);
   } else {
     // Multiple agents including Claude → create AGENTS.md + reference CLAUDE.md
-    result.createAgentsMd = true;
-    result.createClaudeMd = true; // Will be minimal reference
     console.log('  ✓ Will create AGENTS.md (main) + CLAUDE.md (reference)');
+    return createInstructionFilesResult(true, true, false, false);
+  }
+}
+
+// Smart file selection with context warnings
+async function handleInstructionFiles(rl, question, selectedAgents, projectStatus) {
+  const hasClaude = selectedAgents.some(a => a.key === 'claude');
+  const hasOtherAgents = selectedAgents.some(a => a.key !== 'claude');
+
+  // Scenario 1: Both files exist (potential context bloat)
+  if (projectStatus.hasAgentsMd && projectStatus.hasClaudeMd) {
+    return await handleBothFilesExist(question, projectStatus);
   }
 
-  return result;
+  // Scenario 2: Only CLAUDE.md exists
+  if (projectStatus.hasClaudeMd && !projectStatus.hasAgentsMd) {
+    return await handleOnlyClaudeMdExists(question, projectStatus, hasOtherAgents);
+  }
+
+  // Scenario 3: Only AGENTS.md exists
+  if (projectStatus.hasAgentsMd && !projectStatus.hasClaudeMd) {
+    return await handleOnlyAgentsMdExists(question, projectStatus, hasClaude, hasOtherAgents);
+  }
+
+  // Scenario 4: Neither file exists (fresh install)
+  return handleNoFilesExist(hasClaude, hasOtherAgents);
 }
 
 // Create minimal CLAUDE.md that references AGENTS.md
@@ -1284,18 +1391,20 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
   const codeReviewChoice = await question('Select [1]: ') || '1';
 
   switch (codeReviewChoice) {
-    case '1':
+    case '1': {
       tokens['CODE_REVIEW_TOOL'] = 'github-code-quality';
       console.log('  ✓ Using GitHub Code Quality (FREE)');
       break;
-    case '2':
+    }
+    case '2': {
       tokens['CODE_REVIEW_TOOL'] = 'coderabbit';
       console.log('  ✓ Using CodeRabbit - Install the GitHub App to activate');
       console.log('     https://coderabbit.ai');
       break;
-    case '3':
+    }
+    case '3': {
       const greptileKey = await question('  Enter Greptile API key: ');
-      if (greptileKey && greptileKey.trim()) {
+      if (greptileKey?.trim()) {
         tokens['CODE_REVIEW_TOOL'] = 'greptile';
         tokens['GREPTILE_API_KEY'] = greptileKey.trim();
         console.log('  ✓ Greptile configured');
@@ -1304,9 +1413,11 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
         console.log('  Skipped - No API key provided');
       }
       break;
-    default:
+    }
+    default: {
       tokens['CODE_REVIEW_TOOL'] = 'none';
       console.log('  Skipped code review integration');
+    }
   }
 
   // ============================================
@@ -1332,15 +1443,16 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
   const codeQualityChoice = await question('Select [1]: ') || '1';
 
   switch (codeQualityChoice) {
-    case '1':
+    case '1': {
       tokens['CODE_QUALITY_TOOL'] = 'eslint';
       console.log('  ✓ Using ESLint (built-in)');
       break;
-    case '2':
+    }
+    case '2': {
       const sonarToken = await question('  Enter SonarCloud token: ');
       const sonarOrg = await question('  Enter SonarCloud organization: ');
       const sonarProject = await question('  Enter SonarCloud project key: ');
-      if (sonarToken && sonarToken.trim()) {
+      if (sonarToken?.trim()) {
         tokens['CODE_QUALITY_TOOL'] = 'sonarcloud';
         tokens['SONAR_TOKEN'] = sonarToken.trim();
         if (sonarOrg) tokens['SONAR_ORGANIZATION'] = sonarOrg.trim();
@@ -1351,7 +1463,8 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
         console.log('  Falling back to ESLint');
       }
       break;
-    case '3':
+    }
+    case '3': {
       console.log('');
       console.log('  SonarQube Self-Hosted Setup:');
       console.log('  docker run -d --name sonarqube -p 9000:9000 sonarqube:community');
@@ -1361,14 +1474,16 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
       const sqToken = await question('  Enter SonarQube token (optional): ');
       tokens['CODE_QUALITY_TOOL'] = 'sonarqube';
       tokens['SONARQUBE_URL'] = sqUrl;
-      if (sqToken && sqToken.trim()) {
+      if (sqToken?.trim()) {
         tokens['SONARQUBE_TOKEN'] = sqToken.trim();
       }
       console.log('  ✓ SonarQube self-hosted configured');
       break;
-    default:
+    }
+    default: {
       tokens['CODE_QUALITY_TOOL'] = 'none';
       console.log('  Skipped code quality integration');
+    }
   }
 
   // ============================================
@@ -1390,7 +1505,7 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
 
   if (researchChoice === '2') {
     const parallelKey = await question('  Enter Parallel AI API key: ');
-    if (parallelKey && parallelKey.trim()) {
+    if (parallelKey?.trim()) {
       tokens['PARALLEL_API_KEY'] = parallelKey.trim();
       console.log('  ✓ Parallel AI configured');
     } else {
@@ -1564,137 +1679,150 @@ function minimalInstall() {
   console.log('');
 }
 
-// Setup specific agent
-function setupAgent(agentKey, claudeCommands, skipFiles = {}) {
-  const agent = AGENTS[agentKey];
-  if (!agent) return;
-
-  console.log(`\nSetting up ${agent.name}...`);
-
-  // Create directories
-  agent.dirs.forEach(dir => ensureDir(dir));
+// Helper: Setup Claude agent
+function setupClaudeAgent(skipFiles = {}) {
+  // Copy commands from package (unless skipped)
+  if (skipFiles.claudeCommands) {
+    console.log('  Skipped: .claude/commands/ (keeping existing)');
+  } else {
+    COMMANDS.forEach(cmd => {
+      const src = path.join(packageDir, `.claude/commands/${cmd}.md`);
+      copyFile(src, `.claude/commands/${cmd}.md`);
+    });
+    console.log('  Copied: 9 workflow commands');
+  }
 
-  // Handle Claude Code specifically (downloads commands)
-  if (agentKey === 'claude') {
-    // Copy commands from package (unless skipped)
-    if (skipFiles.claudeCommands) {
-      console.log('  Skipped: .claude/commands/ (keeping existing)');
-    } else {
-      COMMANDS.forEach(cmd => {
-        const src = path.join(packageDir, `.claude/commands/${cmd}.md`);
-        copyFile(src, `.claude/commands/${cmd}.md`);
-      });
-      console.log('  Copied: 9 workflow commands');
-    }
+  // Copy rules
+  const rulesSrc = path.join(packageDir, '.claude/rules/workflow.md');
+  copyFile(rulesSrc, '.claude/rules/workflow.md');
 
-    // Copy rules
-    const rulesSrc = path.join(packageDir, '.claude/rules/workflow.md');
-    copyFile(rulesSrc, '.claude/rules/workflow.md');
+  // Copy scripts
+  const scriptSrc = path.join(packageDir, '.claude/scripts/load-env.sh');
+  copyFile(scriptSrc, '.claude/scripts/load-env.sh');
+}
 
-    // Copy scripts
-    const scriptSrc = path.join(packageDir, '.claude/scripts/load-env.sh');
-    copyFile(scriptSrc, '.claude/scripts/load-env.sh');
-  }
+// Helper: Setup Cursor agent
+function setupCursorAgent() {
+  writeFile('.cursor/rules/forge-workflow.mdc', CURSOR_RULE);
+  console.log('  Created: .cursor/rules/forge-workflow.mdc');
+}
 
-  // Custom setups
-  if (agent.customSetup === 'cursor') {
-    writeFile('.cursor/rules/forge-workflow.mdc', CURSOR_RULE);
-    console.log('  Created: .cursor/rules/forge-workflow.mdc');
+// Helper: Setup Aider agent
+function setupAiderAgent() {
+  const aiderPath = path.join(projectRoot, '.aider.conf.yml');
+  if (fs.existsSync(aiderPath)) {
+    console.log('  Skipped: .aider.conf.yml already exists');
+    return true; // Signal early return
   }
 
-  if (agent.customSetup === 'aider') {
-    const aiderPath = path.join(projectRoot, '.aider.conf.yml');
-    if (!fs.existsSync(aiderPath)) {
-      writeFile('.aider.conf.yml', `# Aider configuration
+  writeFile('.aider.conf.yml', `# Aider configuration
 # Read AGENTS.md for workflow instructions
 read:
   - AGENTS.md
   - docs/WORKFLOW.md
 `);
-      console.log('  Created: .aider.conf.yml');
-    } else {
-      console.log('  Skipped: .aider.conf.yml already exists');
-    }
-    return;
-  }
+  console.log('  Created: .aider.conf.yml');
+  return true; // Signal early return
+}
 
-  // Convert/copy commands
-  if (claudeCommands && (agent.needsConversion || agent.copyCommands || agent.promptFormat || agent.continueFormat)) {
-    Object.entries(claudeCommands).forEach(([cmd, content]) => {
-      let targetContent = content;
-      let targetFile = cmd;
+// Helper: Convert command to agent-specific format
+function convertCommandToAgentFormat(cmd, content, agent) {
+  let targetContent = content;
+  let targetFile = cmd;
 
-      if (agent.needsConversion) {
-        targetContent = stripFrontmatter(content);
-      }
+  if (agent.needsConversion) {
+    targetContent = stripFrontmatter(content);
+  }
 
-      if (agent.promptFormat) {
-        targetFile = cmd.replace('.md', '.prompt.md');
-        targetContent = stripFrontmatter(content);
-      }
+  if (agent.promptFormat) {
+    targetFile = cmd.replace('.md', '.prompt.md');
+    targetContent = stripFrontmatter(content);
+  }
 
-      if (agent.continueFormat) {
-        const baseName = cmd.replace('.md', '');
-        targetFile = `${baseName}.prompt`;
-        targetContent = `---
+  if (agent.continueFormat) {
+    const baseName = cmd.replace('.md', '');
+    targetFile = `${baseName}.prompt`;
+    targetContent = `---
 name: ${baseName}
 description: Forge workflow command - ${baseName}
 invokable: true
 ---
 
 ${stripFrontmatter(content)}`;
-      }
+  }
 
-      const targetDir = agent.dirs[0]; // First dir is commands/workflows
-      writeFile(`${targetDir}/${targetFile}`, targetContent);
-    });
-    console.log('  Converted: 9 workflow commands');
+  return { targetFile, targetContent };
+}
+
+// Helper: Copy commands for agent
+function copyAgentCommands(agent, claudeCommands) {
+  if (!claudeCommands) return;
+  if (!agent.needsConversion && !agent.copyCommands && !agent.promptFormat && !agent.continueFormat) return;
+
+  Object.entries(claudeCommands).forEach(([cmd, content]) => {
+    const { targetFile, targetContent } = convertCommandToAgentFormat(cmd, content, agent);
+    const targetDir = agent.dirs[0]; // First dir is commands/workflows
+    writeFile(`${targetDir}/${targetFile}`, targetContent);
+  });
+  console.log('  Converted: 9 workflow commands');
+}
+
+// Helper: Copy rules for agent
+function copyAgentRules(agent) {
+  if (!agent.needsConversion) return;
+
+  const workflowMdPath = path.join(projectRoot, '.claude/rules/workflow.md');
+  if (!fs.existsSync(workflowMdPath)) return;
+
+  const rulesDir = agent.dirs.find(d => d.includes('/rules'));
+  if (!rulesDir) return;
+
+  const ruleContent = readFile(workflowMdPath);
+  if (ruleContent) {
+    writeFile(`${rulesDir}/workflow.md`, ruleContent);
   }
+}
 
-  // Copy rules if needed
-  if (agent.needsConversion && fs.existsSync(path.join(projectRoot, '.claude/rules/workflow.md'))) {
-    const rulesDir = agent.dirs.find(d => d.includes('/rules'));
-    if (rulesDir) {
-      const ruleContent = readFile(path.join(projectRoot, '.claude/rules/workflow.md'));
-      if (ruleContent) {
-        writeFile(`${rulesDir}/workflow.md`, ruleContent);
-      }
-    }
+// Helper: Create skill file for agent
+function createAgentSkill(agent) {
+  if (!agent.hasSkill) return;
+
+  const skillDir = agent.dirs.find(d => d.includes('/skills/'));
+  if (skillDir) {
+    writeFile(`${skillDir}/SKILL.md`, SKILL_CONTENT);
+    console.log('  Created: forge-workflow skill');
   }
+}
 
-  // Create SKILL.md
-  if (agent.hasSkill) {
-    const skillDir = agent.dirs.find(d => d.includes('/skills/'));
-    if (skillDir) {
-      writeFile(`${skillDir}/SKILL.md`, SKILL_CONTENT);
-      console.log('  Created: forge-workflow skill');
-    }
+// Helper: Setup MCP config for Claude
+function setupClaudeMcpConfig() {
+  const mcpPath = path.join(projectRoot, '.mcp.json');
+  if (fs.existsSync(mcpPath)) {
+    console.log('  Skipped: .mcp.json already exists');
+    return;
   }
 
-  // Create .mcp.json with Context7 MCP (Claude Code only)
-  if (agentKey === 'claude') {
-    const mcpPath = path.join(projectRoot, '.mcp.json');
-    if (!fs.existsSync(mcpPath)) {
-      const mcpConfig = {
-        mcpServers: {
-          context7: {
-            command: 'npx',
-            args: ['-y', '@upstash/context7-mcp@latest']
-          }
-        }
-      };
-      writeFile('.mcp.json', JSON.stringify(mcpConfig, null, 2));
-      console.log('  Created: .mcp.json with Context7 MCP');
-    } else {
-      console.log('  Skipped: .mcp.json already exists');
+  const mcpConfig = {
+    mcpServers: {
+      context7: {
+        command: 'npx',
+        args: ['-y', '@upstash/context7-mcp@latest']
+      }
     }
+  };
+  writeFile('.mcp.json', JSON.stringify(mcpConfig, null, 2));
+  console.log('  Created: .mcp.json with Context7 MCP');
+}
+
+// Helper: Setup MCP config for Continue
+function setupContinueMcpConfig() {
+  const configPath = path.join(projectRoot, '.continue/config.yaml');
+  if (fs.existsSync(configPath)) {
+    console.log('  Skipped: config.yaml already exists');
+    return;
   }
 
-  // Create config.yaml with Context7 MCP (Continue only)
-  if (agentKey === 'continue') {
-    const configPath = path.join(projectRoot, '.continue/config.yaml');
-    if (!fs.existsSync(configPath)) {
-      const continueConfig = `# Continue Configuration
+  const continueConfig = `# Continue Configuration
 # https://docs.continue.dev/customize/deep-dives/configuration
 
 name: Forge Workflow
@@ -1710,117 +1838,122 @@ mcpServers:
 
 # Rules loaded from .continuerules
 `;
-      writeFile('.continue/config.yaml', continueConfig);
-      console.log('  Created: config.yaml with Context7 MCP');
-    } else {
-      console.log('  Skipped: config.yaml already exists');
-    }
-  }
+  writeFile('.continue/config.yaml', continueConfig);
+  console.log('  Created: config.yaml with Context7 MCP');
+}
 
-  // Create link file
-  if (agent.linkFile) {
-    const result = createSymlinkOrCopy('AGENTS.md', agent.linkFile);
-    if (result) {
-      console.log(`  ${result === 'linked' ? 'Linked' : 'Copied'}: ${agent.linkFile}`);
-    }
+// Helper: Create agent link file
+function createAgentLinkFile(agent) {
+  if (!agent.linkFile) return;
+
+  const result = createSymlinkOrCopy('AGENTS.md', agent.linkFile);
+  if (result) {
+    console.log(`  ${result === 'linked' ? 'Linked' : 'Copied'}: ${agent.linkFile}`);
   }
 }
 
-// Interactive setup
-async function interactiveSetup() {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
+// Setup specific agent
+function setupAgent(agentKey, claudeCommands, skipFiles = {}) {
+  const agent = AGENTS[agentKey];
+  if (!agent) return;
 
-  let setupCompleted = false;
-
-  // Handle Ctrl+C gracefully
-  rl.on('close', () => {
-    if (!setupCompleted) {
-      console.log('\n\nSetup cancelled.');
-      process.exit(0);
-    }
-  });
+  console.log(`\nSetting up ${agent.name}...`);
 
-  // Handle input errors
-  rl.on('error', (err) => {
-    console.error('Input error:', err.message);
-    process.exit(1);
-  });
+  // Create directories
+  agent.dirs.forEach(dir => ensureDir(dir));
 
-  const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
+  // Handle agent-specific setup
+  if (agentKey === 'claude') {
+    setupClaudeAgent(skipFiles);
+  }
 
-  showBanner('Agent Configuration');
+  if (agent.customSetup === 'cursor') {
+    setupCursorAgent();
+  }
 
-  // Show target directory
-  console.log(`  Target directory: ${process.cwd()}`);
-  console.log('  (Use --path <dir> to change target directory)');
-  console.log('');
+  if (agent.customSetup === 'aider') {
+    const shouldReturn = setupAiderAgent();
+    if (shouldReturn) return;
+  }
 
-  // Check prerequisites first
-  checkPrerequisites();
-  console.log('');
+  // Convert/copy commands
+  copyAgentCommands(agent, claudeCommands);
 
-  // =============================================
-  // PROJECT DETECTION
-  // =============================================
-  const projectStatus = detectProjectStatus();
+  // Copy rules if needed
+  copyAgentRules(agent);
 
-  if (projectStatus.type !== 'fresh') {
-    console.log('==============================================');
-    console.log('  Existing Installation Detected');
-    console.log('==============================================');
-    console.log('');
+  // Create SKILL.md
+  createAgentSkill(agent);
 
-    if (projectStatus.type === 'upgrade') {
-      console.log('Found existing Forge installation:');
-    } else {
-      console.log('Found partial installation:');
-    }
+  // Setup MCP configs
+  if (agentKey === 'claude') {
+    setupClaudeMcpConfig();
+  }
 
-    if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
-    if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
-    if (projectStatus.hasEnvLocal) console.log('  - .env.local');
-    if (projectStatus.hasDocsWorkflow) console.log('  - docs/WORKFLOW.md');
-    console.log('');
+  if (agentKey === 'continue') {
+    setupContinueMcpConfig();
   }
 
-  // Track which files to skip based on user choices
-  const skipFiles = {
-    agentsMd: false,
-    claudeCommands: false
-  };
+  // Create link file
+  createAgentLinkFile(agent);
+}
 
-  // Ask about overwriting AGENTS.md if it exists
-  if (projectStatus.hasAgentsMd) {
-    const overwriteAgents = await askYesNo(question, 'Found existing AGENTS.md. Overwrite?', true);
-    if (!overwriteAgents) {
-      skipFiles.agentsMd = true;
-      console.log('  Keeping existing AGENTS.md');
-    } else {
-      console.log('  Will overwrite AGENTS.md');
-    }
-  }
 
-  // Ask about overwriting .claude/commands/ if it exists
-  if (projectStatus.hasClaudeCommands) {
-    const overwriteCommands = await askYesNo(question, 'Found existing .claude/commands/. Overwrite?', true);
-    if (!overwriteCommands) {
-      skipFiles.claudeCommands = true;
-      console.log('  Keeping existing .claude/commands/');
-    } else {
-      console.log('  Will overwrite .claude/commands/');
-    }
+// =============================================
+// Helper Functions for Interactive Setup
+// =============================================
+
+/**
+ * Display existing installation status
+ */
+function displayInstallationStatus(projectStatus) {
+  if (projectStatus.type === 'fresh') return;
+
+  console.log('==============================================');
+  console.log('  Existing Installation Detected');
+  console.log('==============================================');
+  console.log('');
+
+  if (projectStatus.type === 'upgrade') {
+    console.log('Found existing Forge installation:');
+  } else {
+    console.log('Found partial installation:');
   }
 
-  if (projectStatus.type !== 'fresh') {
-    console.log('');
+  if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
+  if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
+  if (projectStatus.hasEnvLocal) console.log('  - .env.local');
+  if (projectStatus.hasDocsWorkflow) console.log('  - docs/WORKFLOW.md');
+  console.log('');
+}
+
+/**
+ * Prompt for file overwrite and update skipFiles
+ */
+async function promptForFileOverwrite(question, fileType, exists, skipFiles) {
+  if (!exists) return;
+
+  const fileLabels = {
+    agentsMd: { prompt: 'Found existing AGENTS.md. Overwrite?', message: 'AGENTS.md', key: 'agentsMd' },
+    claudeCommands: { prompt: 'Found existing .claude/commands/. Overwrite?', message: '.claude/commands/', key: 'claudeCommands' }
+  };
+
+  const config = fileLabels[fileType];
+  if (!config) return;
+
+  const overwrite = await askYesNo(question, config.prompt, true);
+  if (overwrite) {
+    console.log(`  Will overwrite ${config.message}`);
+  } else {
+    skipFiles[config.key] = true;
+    console.log(`  Keeping existing ${config.message}`);
   }
+}
 
-  // =============================================
-  // STEP 1: Agent Selection
-  // =============================================
+/**
+ * Display agent selection options
+ */
+function displayAgentOptions(agentKeys) {
   console.log('STEP 1: Select AI Coding Agents');
   console.log('================================');
   console.log('');
@@ -1828,7 +1961,6 @@ async function interactiveSetup() {
   console.log('(Enter numbers separated by spaces, or "all")');
   console.log('');
 
-  const agentKeys = Object.keys(AGENTS);
   agentKeys.forEach((key, index) => {
     const agent = AGENTS[key];
     console.log(`  ${(index + 1).toString().padStart(2)}) ${agent.name.padEnd(20)} - ${agent.description}`);
@@ -1836,105 +1968,133 @@ async function interactiveSetup() {
   console.log('');
   console.log('  all) Install for all agents');
   console.log('');
+}
 
-  let selectedAgents = [];
+/**
+ * Validate and parse agent selection input
+ */
+function validateAgentSelection(input, agentKeys) {
+  // Handle empty input
+  if (!input || !input.trim()) {
+    return { valid: false, agents: [], message: 'Please enter at least one agent number or "all".' };
+  }
 
-  // Loop until valid input is provided
-  while (selectedAgents.length === 0) {
-    const answer = await question('Your selection: ');
+  // Handle "all" selection
+  if (input.toLowerCase() === 'all') {
+    return { valid: true, agents: agentKeys, message: null };
+  }
 
-    // Handle empty input - reprompt
-    if (!answer || !answer.trim()) {
-      console.log('  Please enter at least one agent number or "all".');
-      continue;
-    }
+  // Parse numbers
+  const nums = input.split(/[\s,]+/).map(n => Number.parseInt(n.trim())).filter(n => !Number.isNaN(n));
 
-    if (answer.toLowerCase() === 'all') {
-      selectedAgents = agentKeys;
-    } else {
-      const nums = answer.split(/[\s,]+/).map(n => parseInt(n.trim())).filter(n => !isNaN(n));
+  // Validate numbers are in range
+  const validNums = nums.filter(n => n >= 1 && n <= agentKeys.length);
+  const invalidNums = nums.filter(n => n < 1 || n > agentKeys.length);
 
-      // Validate numbers are in range
-      const validNums = nums.filter(n => n >= 1 && n <= agentKeys.length);
-      const invalidNums = nums.filter(n => n < 1 || n > agentKeys.length);
+  if (invalidNums.length > 0) {
+    console.log(`  ⚠ Invalid numbers ignored: ${invalidNums.join(', ')} (valid: 1-${agentKeys.length})`);
+  }
 
-      if (invalidNums.length > 0) {
-        console.log(`  ⚠ Invalid numbers ignored: ${invalidNums.join(', ')} (valid: 1-${agentKeys.length})`);
-      }
+  // Deduplicate selected agents using Set
+  const selectedAgents = [...new Set(validNums.map(n => agentKeys[n - 1]))].filter(Boolean);
 
-      // Deduplicate selected agents using Set
-      selectedAgents = [...new Set(validNums.map(n => agentKeys[n - 1]))].filter(Boolean);
-    }
+  if (selectedAgents.length === 0) {
+    return { valid: false, agents: [], message: 'No valid agents selected. Please try again.' };
+  }
 
-    if (selectedAgents.length === 0) {
-      console.log('  No valid agents selected. Please try again.');
+  return { valid: true, agents: selectedAgents, message: null };
+}
+
+/**
+ * Prompt for agent selection with validation loop
+ */
+async function promptForAgentSelection(question, agentKeys) {
+  displayAgentOptions(agentKeys);
+
+  let selectedAgents = [];
+
+  // Loop until valid input is provided
+  while (selectedAgents.length === 0) {
+    const answer = await question('Your selection: ');
+    const result = validateAgentSelection(answer, agentKeys);
+
+    if (result.valid) {
+      selectedAgents = result.agents;
+    } else if (result.message) {
+      console.log(`  ${result.message}`);
     }
   }
 
-  console.log('');
-  console.log('Installing Forge workflow...');
+  return selectedAgents;
+}
 
-  // Copy AGENTS.md unless skipped
+/**
+ * Handle AGENTS.md installation
+ */
+async function installAgentsMd(skipFiles) {
   if (skipFiles.agentsMd) {
     console.log('  Skipped: AGENTS.md (keeping existing)');
-  } else {
-    const agentsSrc = path.join(packageDir, 'AGENTS.md');
-    const agentsDest = path.join(projectRoot, 'AGENTS.md');
+    return;
+  }
 
-    // Try smart merge if file exists
-    if (fs.existsSync(agentsDest)) {
-      const existingContent = fs.readFileSync(agentsDest, 'utf8');
-      const newContent = fs.readFileSync(agentsSrc, 'utf8');
-      const merged = smartMergeAgentsMd(existingContent, newContent);
+  const agentsSrc = path.join(packageDir, 'AGENTS.md');
+  const agentsDest = path.join(projectRoot, 'AGENTS.md');
+
+  // Try smart merge if file exists
+  if (fs.existsSync(agentsDest)) {
+    const existingContent = fs.readFileSync(agentsDest, 'utf8');
+    const newContent = fs.readFileSync(agentsSrc, 'utf8');
+    const merged = smartMergeAgentsMd(existingContent, newContent);
+
+    if (merged) {
+      fs.writeFileSync(agentsDest, merged, 'utf8');
+      console.log('  Updated: AGENTS.md (preserved USER sections)');
+    } else if (copyFile(agentsSrc, 'AGENTS.md')) {
+      // No markers, do normal copy (user already approved overwrite)
+      console.log('  Updated: AGENTS.md (universal standard)');
+    }
+  } else if (copyFile(agentsSrc, 'AGENTS.md')) {
+    // New file
+    console.log('  Created: AGENTS.md (universal standard)');
 
-      if (merged) {
-        fs.writeFileSync(agentsDest, merged, 'utf8');
-        console.log('  Updated: AGENTS.md (preserved USER sections)');
-      } else {
-        // No markers, do normal copy (user already approved overwrite)
-        if (copyFile(agentsSrc, 'AGENTS.md')) {
-          console.log('  Updated: AGENTS.md (universal standard)');
-        }
-      }
-    } else {
-      // New file
-      if (copyFile(agentsSrc, 'AGENTS.md')) {
-        console.log('  Created: AGENTS.md (universal standard)');
-
-        // Detect project type and update AGENTS.md
-        const detection = detectProjectType();
-        if (detection.hasPackageJson) {
-          updateAgentsMdWithProjectType(detection);
-          displayProjectType(detection);
-        }
-      }
+    // Detect project type and update AGENTS.md
+    const detection = detectProjectType();
+    if (detection.hasPackageJson) {
+      updateAgentsMdWithProjectType(detection);
+      displayProjectType(detection);
     }
   }
-  console.log('');
+}
 
-  // Setup core documentation
-  setupCoreDocs();
-  console.log('');
+/**
+ * Load Claude commands for conversion
+ */
+function loadClaudeCommands(selectedAgents) {
+  const claudeCommands = {};
+  const needsClaudeCommands = selectedAgents.includes('claude') ||
+    selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands);
 
-  // Load Claude commands if needed
-  let claudeCommands = {};
-  if (selectedAgents.includes('claude') || selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands)) {
-    // First ensure Claude is set up
-    if (selectedAgents.includes('claude')) {
-      setupAgent('claude', null, skipFiles);
-    }
-    // Then load the commands (from existing or newly created)
-    COMMANDS.forEach(cmd => {
-      const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
-      const content = readFile(cmdPath);
-      if (content) {
-        claudeCommands[`${cmd}.md`] = content;
-      }
-    });
+  if (!needsClaudeCommands) {
+    return claudeCommands;
   }
 
-  // Setup each selected agent with progress indication
+  COMMANDS.forEach(cmd => {
+    const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
+    const content = readFile(cmdPath);
+    if (content) {
+      claudeCommands[`${cmd}.md`] = content;
+    }
+  });
+
+  return claudeCommands;
+}
+
+/**
+ * Setup agents with progress indication
+ */
+function setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles) {
   const totalAgents = selectedAgents.length;
+
   selectedAgents.forEach((agentKey, index) => {
     const agent = AGENTS[agentKey];
     console.log(`\n[${index + 1}/${totalAgents}] Setting up ${agent.name}...`);
@@ -1952,22 +2112,12 @@ async function interactiveSetup() {
     const agent = AGENTS[key];
     console.log(`  * ${agent.name}`);
   });
+}
 
-  // =============================================
-  // STEP 2: External Services Configuration
-  // =============================================
-  console.log('');
-  console.log('STEP 2: External Services (Optional)');
-  console.log('=====================================');
-
-  await configureExternalServices(rl, question, selectedAgents, projectStatus);
-
-  setupCompleted = true;
-  rl.close();
-
-  // =============================================
-  // Final Summary
-  // =============================================
+/**
+ * Display final setup summary
+ */
+function displaySetupSummary(selectedAgents) {
   console.log('');
   console.log('==============================================');
   console.log(`  Forge v${VERSION} Setup Complete!`);
@@ -1978,6 +2128,7 @@ async function interactiveSetup() {
   console.log('  - docs/WORKFLOW.md (full workflow guide)');
   console.log('  - docs/research/TEMPLATE.md (research template)');
   console.log('  - docs/planning/PROGRESS.md (progress tracking)');
+
   selectedAgents.forEach(key => {
     const agent = AGENTS[key];
     if (agent.linkFile) {
@@ -1993,6 +2144,7 @@ async function interactiveSetup() {
       }
     }
   });
+
   console.log('');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('📋  NEXT STEP - Complete AGENTS.md');
@@ -2024,6 +2176,112 @@ async function interactiveSetup() {
   console.log('');
 }
 
+
+// Interactive setup
+async function interactiveSetup() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  let setupCompleted = false;
+
+  // Handle Ctrl+C gracefully
+  rl.on('close', () => {
+    if (!setupCompleted) {
+      console.log('\n\nSetup cancelled.');
+      process.exit(0);
+    }
+  });
+
+  // Handle input errors
+  rl.on('error', (err) => {
+    console.error('Input error:', err.message);
+    process.exit(1);
+  });
+
+  const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
+
+  showBanner('Agent Configuration');
+
+  // Show target directory
+  console.log(`  Target directory: ${process.cwd()}`);
+  console.log('  (Use --path <dir> to change target directory)');
+  console.log('');
+
+  // Check prerequisites first
+  checkPrerequisites();
+  console.log('');
+
+  // =============================================
+  // PROJECT DETECTION
+  // =============================================
+  const projectStatus = detectProjectStatus();
+  displayInstallationStatus(projectStatus);
+
+  // Track which files to skip based on user choices
+  const skipFiles = {
+    agentsMd: false,
+    claudeCommands: false
+  };
+
+  // Ask about overwriting existing files
+  await promptForFileOverwrite(question, 'agentsMd', projectStatus.hasAgentsMd, skipFiles);
+  await promptForFileOverwrite(question, 'claudeCommands', projectStatus.hasClaudeCommands, skipFiles);
+
+  if (projectStatus.type !== 'fresh') {
+    console.log('');
+  }
+
+  // =============================================
+  // STEP 1: Agent Selection
+  // =============================================
+  const agentKeys = Object.keys(AGENTS);
+  const selectedAgents = await promptForAgentSelection(question, agentKeys);
+
+  console.log('');
+  console.log('Installing Forge workflow...');
+
+  // Install AGENTS.md
+  await installAgentsMd(skipFiles);
+  console.log('');
+
+  // Setup core documentation
+  setupCoreDocs();
+  console.log('');
+
+  // Load Claude commands if needed
+  let claudeCommands = {};
+  if (selectedAgents.includes('claude') || selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands)) {
+    // First ensure Claude is set up
+    if (selectedAgents.includes('claude')) {
+      setupAgent('claude', null, skipFiles);
+    }
+    // Then load the commands
+    claudeCommands = loadClaudeCommands(selectedAgents);
+  }
+
+  // Setup each selected agent with progress indication
+  setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles);
+
+  // =============================================
+  // STEP 2: External Services Configuration
+  // =============================================
+  console.log('');
+  console.log('STEP 2: External Services (Optional)');
+  console.log('=====================================');
+
+  await configureExternalServices(rl, question, selectedAgents, projectStatus);
+
+  setupCompleted = true;
+  rl.close();
+
+  // =============================================
+  // Final Summary
+  // =============================================
+  displaySetupSummary(selectedAgents);
+}
+
 // Parse CLI flags
 function parseFlags() {
   const flags = {
@@ -2035,39 +2293,51 @@ function parseFlags() {
     path: null
   };
 
-  for (let i = 0; i < args.length; i++) {
+  for (let i = 0; i < args.length; ) {
     const arg = args[i];
 
     if (arg === '--quick' || arg === '-q') {
       flags.quick = true;
+      i++;
     } else if (arg === '--skip-external' || arg === '--skip-services') {
       flags.skipExternal = true;
+      i++;
     } else if (arg === '--all') {
       flags.all = true;
+      i++;
     } else if (arg === '--help' || arg === '-h') {
       flags.help = true;
+      i++;
     } else if (arg === '--path' || arg === '-p') {
       // --path <directory> or -p <directory>
       if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
         flags.path = args[i + 1];
-        i++; // Skip next arg
+        i += 2; // Skip current and next arg
+      } else {
+        i++;
       }
     } else if (arg.startsWith('--path=')) {
       // --path=/some/dir format
       flags.path = arg.replace('--path=', '');
+      i++;
     } else if (arg === '--agents') {
       // --agents claude cursor format
       const agentList = [];
-      for (let j = i + 1; j < args.length; j++) {
-        if (args[j].startsWith('-')) break;
+      let j = i + 1;
+      while (j < args.length && !args[j].startsWith('-')) {
         agentList.push(args[j]);
+        j++;
       }
       if (agentList.length > 0) {
         flags.agents = agentList.join(',');
       }
+      i = j; // Skip all consumed arguments
     } else if (arg.startsWith('--agents=')) {
       // --agents=claude,cursor format
       flags.agents = arg.replace('--agents=', '');
+      i++;
+    } else {
+      i++;
     }
   }
 
@@ -2188,7 +2458,10 @@ async function quickSetup(selectedAgents, skipExternal) {
   });
 
   // Configure external services with defaults (unless skipped)
-  if (!skipExternal) {
+  if (skipExternal) {
+    console.log('');
+    console.log('Skipping external services configuration...');
+  } else {
     console.log('');
     console.log('Configuring default services...');
     console.log('');
@@ -2205,9 +2478,6 @@ async function quickSetup(selectedAgents, skipExternal) {
     console.log('  * Code Quality: ESLint (built-in)');
     console.log('');
     console.log('Configuration saved to .env.local');
-  } else {
-    console.log('');
-    console.log('Skipping external services configuration...');
   }
 
   // Final summary
@@ -2293,22 +2563,22 @@ async function interactiveSetupWithFlags(flags) {
   // Ask about overwriting AGENTS.md if it exists
   if (projectStatus.hasAgentsMd) {
     const overwriteAgents = await askYesNo(question, 'Found existing AGENTS.md. Overwrite?', true);
-    if (!overwriteAgents) {
+    if (overwriteAgents) {
+      console.log('  Will overwrite AGENTS.md');
+    } else {
       skipFiles.agentsMd = true;
       console.log('  Keeping existing AGENTS.md');
-    } else {
-      console.log('  Will overwrite AGENTS.md');
     }
   }
 
   // Ask about overwriting .claude/commands/ if it exists
   if (projectStatus.hasClaudeCommands) {
     const overwriteCommands = await askYesNo(question, 'Found existing .claude/commands/. Overwrite?', true);
-    if (!overwriteCommands) {
+    if (overwriteCommands) {
+      console.log('  Will overwrite .claude/commands/');
+    } else {
       skipFiles.claudeCommands = true;
       console.log('  Keeping existing .claude/commands/');
-    } else {
-      console.log('  Will overwrite .claude/commands/');
     }
   }
 
@@ -2350,7 +2620,7 @@ async function interactiveSetupWithFlags(flags) {
     if (answer.toLowerCase() === 'all') {
       selectedAgents = agentKeys;
     } else {
-      const nums = answer.split(/[\s,]+/).map(n => parseInt(n.trim())).filter(n => !isNaN(n));
+      const nums = answer.split(/[\s,]+/).map(n => Number.parseInt(n.trim())).filter(n => !Number.isNaN(n));
 
       // Validate numbers are in range
       const validNums = nums.filter(n => n >= 1 && n <= agentKeys.length);
@@ -2388,23 +2658,19 @@ async function interactiveSetupWithFlags(flags) {
       if (merged) {
         fs.writeFileSync(agentsDest, merged, 'utf8');
         console.log('  Updated: AGENTS.md (preserved USER sections)');
-      } else {
+      } else if (copyFile(agentsSrc, 'AGENTS.md')) {
         // No markers, do normal copy (user already approved overwrite)
-        if (copyFile(agentsSrc, 'AGENTS.md')) {
-          console.log('  Updated: AGENTS.md (universal standard)');
-        }
+        console.log('  Updated: AGENTS.md (universal standard)');
       }
-    } else {
+    } else if (copyFile(agentsSrc, 'AGENTS.md')) {
       // New file
-      if (copyFile(agentsSrc, 'AGENTS.md')) {
-        console.log('  Created: AGENTS.md (universal standard)');
-
-        // Detect project type and update AGENTS.md
-        const detection = detectProjectType();
-        if (detection.hasPackageJson) {
-          updateAgentsMdWithProjectType(detection);
-          displayProjectType(detection);
-        }
+      console.log('  Created: AGENTS.md (universal standard)');
+
+      // Detect project type and update AGENTS.md
+      const detection = detectProjectType();
+      if (detection.hasPackageJson) {
+        updateAgentsMdWithProjectType(detection);
+        displayProjectType(detection);
       }
     }
   }
@@ -2454,15 +2720,15 @@ async function interactiveSetupWithFlags(flags) {
   // =============================================
   // STEP 2: External Services Configuration
   // =============================================
-  if (!flags.skipExternal) {
+  if (flags.skipExternal) {
+    console.log('');
+    console.log('Skipping external services configuration...');
+  } else {
     console.log('');
     console.log('STEP 2: External Services (Optional)');
     console.log('=====================================');
 
     await configureExternalServices(rl, question, selectedAgents, projectStatus);
-  } else {
-    console.log('');
-    console.log('Skipping external services configuration...');
   }
 
   setupCompleted = true;
@@ -2528,6 +2794,124 @@ async function interactiveSetupWithFlags(flags) {
 }
 
 // Main
+// Helper: Handle --path setup
+function handlePathSetup(targetPath) {
+  const resolvedPath = path.resolve(targetPath);
+
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(resolvedPath)) {
+    try {
+      fs.mkdirSync(resolvedPath, { recursive: true });
+      console.log(`Created directory: ${resolvedPath}`);
+    } catch (err) {
+      console.error(`Error creating directory: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Verify it's a directory
+  if (!fs.statSync(resolvedPath).isDirectory()) {
+    console.error(`Error: ${resolvedPath} is not a directory`);
+    process.exit(1);
+  }
+
+  // Change to target directory
+  try {
+    process.chdir(resolvedPath);
+    console.log(`Working directory: ${resolvedPath}`);
+    console.log('');
+  } catch (err) {
+    console.error(`Error changing to directory: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// Helper: Determine selected agents from flags
+function determineSelectedAgents(flags) {
+  if (flags.all) {
+    return Object.keys(AGENTS);
+  }
+
+  if (flags.agents) {
+    const selectedAgents = validateAgents(flags.agents);
+    if (selectedAgents.length === 0) {
+      console.log('No valid agents specified.');
+      console.log('Available agents:', Object.keys(AGENTS).join(', '));
+      process.exit(1);
+    }
+    return selectedAgents;
+  }
+
+  return [];
+}
+
+// Helper: Handle setup command in non-quick mode
+async function handleSetupCommand(selectedAgents, flags) {
+  showBanner('Installing for specified agents...');
+  console.log('');
+
+  // Check prerequisites
+  checkPrerequisites();
+  console.log('');
+
+  // Copy AGENTS.md
+  const agentsSrc = path.join(packageDir, 'AGENTS.md');
+  if (copyFile(agentsSrc, 'AGENTS.md')) {
+    console.log('  Created: AGENTS.md (universal standard)');
+  }
+  console.log('');
+
+  // Setup core documentation
+  setupCoreDocs();
+  console.log('');
+
+  // Load Claude commands if needed
+  const claudeCommands = loadClaudeCommands(selectedAgents);
+
+  // Setup agents
+  selectedAgents.forEach(agentKey => {
+    if (agentKey !== 'claude') {
+      setupAgent(agentKey, claudeCommands);
+    }
+  });
+
+  console.log('');
+  console.log('Agent configuration complete!');
+
+  // External services (unless skipped)
+  await handleExternalServices(flags.skipExternal, selectedAgents);
+
+  console.log('');
+  console.log('Done! Get started with: /status');
+}
+
+// Helper: Handle external services configuration
+async function handleExternalServices(skipExternal, selectedAgents) {
+  if (skipExternal) {
+    console.log('');
+    console.log('Skipping external services configuration...');
+    return;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  let setupCompleted = false;
+  rl.on('close', () => {
+    if (!setupCompleted) {
+      console.log('\n\nSetup cancelled.');
+      process.exit(0);
+    }
+  });
+
+  const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
+  await configureExternalServices(rl, question, selectedAgents);
+  setupCompleted = true;
+  rl.close();
+}
+
 async function main() {
   const command = args[0];
   const flags = parseFlags();
@@ -2540,50 +2924,12 @@ async function main() {
 
   // Handle --path option: change to target directory
   if (flags.path) {
-    const targetPath = path.resolve(flags.path);
-
-    // Create directory if it doesn't exist
-    if (!fs.existsSync(targetPath)) {
-      try {
-        fs.mkdirSync(targetPath, { recursive: true });
-        console.log(`Created directory: ${targetPath}`);
-      } catch (err) {
-        console.error(`Error creating directory: ${err.message}`);
-        process.exit(1);
-      }
-    }
-
-    // Verify it's a directory
-    if (!fs.statSync(targetPath).isDirectory()) {
-      console.error(`Error: ${targetPath} is not a directory`);
-      process.exit(1);
-    }
-
-    // Change to target directory
-    try {
-      process.chdir(targetPath);
-      console.log(`Working directory: ${targetPath}`);
-      console.log('');
-    } catch (err) {
-      console.error(`Error changing to directory: ${err.message}`);
-      process.exit(1);
-    }
+    handlePathSetup(flags.path);
   }
 
   if (command === 'setup') {
     // Determine agents to install
-    let selectedAgents = [];
-
-    if (flags.all) {
-      selectedAgents = Object.keys(AGENTS);
-    } else if (flags.agents) {
-      selectedAgents = validateAgents(flags.agents);
-      if (selectedAgents.length === 0) {
-        console.log('No valid agents specified.');
-        console.log('Available agents:', Object.keys(AGENTS).join(', '));
-        process.exit(1);
-      }
-    }
+    let selectedAgents = determineSelectedAgents(flags);
 
     // Quick mode
     if (flags.quick) {
@@ -2597,74 +2943,7 @@ async function main() {
 
     // Agents specified via flag (non-quick mode)
     if (selectedAgents.length > 0) {
-      showBanner('Installing for specified agents...');
-      console.log('');
-
-      // Check prerequisites
-      checkPrerequisites();
-      console.log('');
-
-      // Copy AGENTS.md
-      const agentsSrc = path.join(packageDir, 'AGENTS.md');
-      if (copyFile(agentsSrc, 'AGENTS.md')) {
-        console.log('  Created: AGENTS.md (universal standard)');
-      }
-      console.log('');
-
-      // Setup core documentation
-      setupCoreDocs();
-      console.log('');
-
-      // Load Claude commands if needed
-      let claudeCommands = {};
-      if (selectedAgents.includes('claude')) {
-        setupAgent('claude', null);
-      }
-
-      if (selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands)) {
-        COMMANDS.forEach(cmd => {
-          const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
-          const content = readFile(cmdPath);
-          if (content) {
-            claudeCommands[`${cmd}.md`] = content;
-          }
-        });
-      }
-
-      // Setup agents
-      selectedAgents.forEach(agentKey => {
-        if (agentKey !== 'claude') {
-          setupAgent(agentKey, claudeCommands);
-        }
-      });
-
-      console.log('');
-      console.log('Agent configuration complete!');
-
-      // External services (unless skipped)
-      if (!flags.skipExternal) {
-        const rl = readline.createInterface({
-          input: process.stdin,
-          output: process.stdout
-        });
-        let setupCompleted = false;
-        rl.on('close', () => {
-          if (!setupCompleted) {
-            console.log('\n\nSetup cancelled.');
-            process.exit(0);
-          }
-        });
-        const question = (prompt) => new Promise(resolve => rl.question(prompt, resolve));
-        await configureExternalServices(rl, question, selectedAgents);
-        setupCompleted = true;
-        rl.close();
-      } else {
-        console.log('');
-        console.log('Skipping external services configuration...');
-      }
-
-      console.log('');
-      console.log('Done! Get started with: /status');
+      await handleSetupCommand(selectedAgents, flags);
       return;
     }
 
@@ -2738,13 +3017,9 @@ function validateRollbackInput(method, target) {
 }
 
 // Extract USER sections before rollback
-function extractUserSections(filePath) {
-  if (!fs.existsSync(filePath)) return {};
-
-  const content = fs.readFileSync(filePath, 'utf-8');
+// Helper: Extract USER:START/END marker sections from content
+function extractUserMarkerSections(content) {
   const sections = {};
-
-  // Extract USER sections
   const userRegex = /<!-- USER:START -->([\s\S]*?)<!-- USER:END -->/g;
   let match;
   let index = 0;
@@ -2754,15 +3029,35 @@ function extractUserSections(filePath) {
     index++;
   }
 
-  // Extract custom commands
+  return sections;
+}
+
+// Helper: Extract custom commands from directory
+function extractCustomCommands(filePath) {
   const customCommandsDir = path.join(path.dirname(filePath), '.claude', 'commands', 'custom');
-  if (fs.existsSync(customCommandsDir)) {
-    sections.customCommands = fs.readdirSync(customCommandsDir)
-      .filter(f => f.endsWith('.md'))
-      .map(f => ({
-        name: f,
-        content: fs.readFileSync(path.join(customCommandsDir, f), 'utf-8')
-      }));
+
+  if (!fs.existsSync(customCommandsDir)) {
+    return null;
+  }
+
+  return fs.readdirSync(customCommandsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => ({
+      name: f,
+      content: fs.readFileSync(path.join(customCommandsDir, f), 'utf-8')
+    }));
+}
+
+function extractUserSections(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const sections = extractUserMarkerSections(content);
+
+  // Extract custom commands
+  const customCommands = extractCustomCommands(filePath);
+  if (customCommands) {
+    sections.customCommands = customCommands;
   }
 
   return sections;
@@ -2778,7 +3073,7 @@ function preserveUserSections(filePath, savedSections) {
 
   // Restore USER sections
   let index = 0;
-  content = content.replace(
+  content = content.replaceAll(
     /<!-- USER:START -->[\s\S]*?<!-- USER:END -->/g,
     () => {
       const section = savedSections[`user_${index}`];
@@ -2807,6 +3102,110 @@ function preserveUserSections(filePath, savedSections) {
 }
 
 // Perform rollback operation
+// Helper: Check git working directory is clean
+function checkGitWorkingDirectory() {
+  try {
+    const { execSync } = require('node:child_process');
+    const status = execSync('git status --porcelain', { encoding: 'utf-8' });
+    if (status.trim() !== '') {
+      console.log(chalk.red('  ❌ Working directory has uncommitted changes'));
+      console.log('     Commit or stash changes before rollback');
+      return false;
+    }
+    return true;
+  } catch (err) {
+    console.log(chalk.red('  ❌ Git error:'), err.message);
+    return false;
+  }
+}
+
+// Helper: Update Beads issue after PR rollback
+function updateBeadsIssue(commitMessage) {
+  const issueMatch = commitMessage.match(/#(\d+)/);
+  if (!issueMatch) return;
+
+  try {
+    const { execSync } = require('node:child_process');
+    execSync(`bd update ${issueMatch[1]} --status reverted --comment "PR reverted"`, { stdio: 'inherit' });
+    console.log(`     Updated Beads issue #${issueMatch[1]} to 'reverted'`);
+  } catch {
+    // Beads not installed - silently continue
+  }
+}
+
+// Helper: Handle commit rollback
+function handleCommitRollback(target, dryRun, execSync) {
+  if (dryRun) {
+    console.log(`     Would revert: ${target}`);
+    const files = execSync(`git diff-tree --no-commit-id --name-only -r ${target}`, { encoding: 'utf-8' });
+    console.log('     Affected files:');
+    files.trim().split('\n').forEach(f => console.log(`       - ${f}`));
+  } else {
+    execSync(`git revert --no-edit ${target}`, { stdio: 'inherit' });
+  }
+}
+
+// Helper: Handle PR rollback
+function handlePrRollback(target, dryRun, execSync) {
+  if (dryRun) {
+    console.log(`     Would revert merge: ${target}`);
+    const files = execSync(`git diff-tree --no-commit-id --name-only -r ${target}`, { encoding: 'utf-8' });
+    console.log('     Affected files:');
+    files.trim().split('\n').forEach(f => console.log(`       - ${f}`));
+  } else {
+    execSync(`git revert -m 1 --no-edit ${target}`, { stdio: 'inherit' });
+
+    // Update Beads issue if linked
+    const commitMsg = execSync(`git log -1 --format=%B ${target}`, { encoding: 'utf-8' });
+    updateBeadsIssue(commitMsg);
+  }
+}
+
+// Helper: Handle partial file rollback
+function handlePartialRollback(target, dryRun, execSync) {
+  const files = target.split(',').map(f => f.trim());
+  if (dryRun) {
+    console.log('     Would restore files:');
+    files.forEach(f => console.log(`       - ${f}`));
+  } else {
+    files.forEach(f => {
+      execSync(`git checkout HEAD~1 -- "${f}"`, { stdio: 'inherit' });
+    });
+    execSync(`git commit -m "chore: rollback ${files.join(', ')}"`, { stdio: 'inherit' });
+  }
+}
+
+// Helper: Handle branch range rollback
+function handleBranchRollback(target, dryRun, execSync) {
+  const [startCommit, endCommit] = target.split('..');
+  if (dryRun) {
+    console.log(`     Would revert range: ${startCommit}..${endCommit}`);
+    const commits = execSync(`git log --oneline ${startCommit}..${endCommit}`, { encoding: 'utf-8' });
+    console.log('     Commits to revert:');
+    commits.trim().split('\n').forEach(c => console.log(`       ${c}`));
+  } else {
+    execSync(`git revert --no-edit ${startCommit}..${endCommit}`, { stdio: 'inherit' });
+  }
+}
+
+// Helper: Finalize rollback by restoring user sections
+function finalizeRollback(agentsPath, savedSections) {
+  const { execSync } = require('node:child_process');
+
+  console.log('  📦 Restoring user content...');
+  preserveUserSections(agentsPath, savedSections);
+
+  // Amend commit to include restored USER sections
+  if (fs.existsSync(agentsPath)) {
+    execSync('git add AGENTS.md', { stdio: 'inherit' });
+    execSync('git commit --amend --no-edit', { stdio: 'inherit' });
+  }
+
+  console.log('');
+  console.log(chalk.green('  ✅ Rollback complete'));
+  console.log('     User content preserved');
+}
+
 async function performRollback(method, target, dryRun = false) {
   console.log('');
   console.log(chalk.cyan(`  🔄 Rollback: ${method}`));
@@ -2824,16 +3223,7 @@ async function performRollback(method, target, dryRun = false) {
   }
 
   // Check for clean working directory
-  try {
-    const { execSync } = require('child_process');
-    const status = execSync('git status --porcelain', { encoding: 'utf-8' });
-    if (status.trim() !== '') {
-      console.log(chalk.red('  ❌ Working directory has uncommitted changes'));
-      console.log('     Commit or stash changes before rollback');
-      return false;
-    }
-  } catch (err) {
-    console.log(chalk.red('  ❌ Git error:'), err.message);
+  if (!checkGitWorkingDirectory()) {
     return false;
   }
 
@@ -2846,74 +3236,20 @@ async function performRollback(method, target, dryRun = false) {
   }
 
   try {
-    const { execSync } = require('child_process');
+    const { execSync } = require('node:child_process');
 
     if (method === 'commit') {
-      if (dryRun) {
-        console.log(`     Would revert: ${target}`);
-        const files = execSync(`git diff-tree --no-commit-id --name-only -r ${target}`, { encoding: 'utf-8' });
-        console.log('     Affected files:');
-        files.trim().split('\n').forEach(f => console.log(`       - ${f}`));
-      } else {
-        execSync(`git revert --no-edit ${target}`, { stdio: 'inherit' });
-      }
+      handleCommitRollback(target, dryRun, execSync);
     } else if (method === 'pr') {
-      if (dryRun) {
-        console.log(`     Would revert merge: ${target}`);
-        const files = execSync(`git diff-tree --no-commit-id --name-only -r ${target}`, { encoding: 'utf-8' });
-        console.log('     Affected files:');
-        files.trim().split('\n').forEach(f => console.log(`       - ${f}`));
-      } else {
-        execSync(`git revert -m 1 --no-edit ${target}`, { stdio: 'inherit' });
-
-        // Update Beads issue if linked
-        const commitMsg = execSync(`git log -1 --format=%B ${target}`, { encoding: 'utf-8' });
-        const issueMatch = commitMsg.match(/#(\d+)/);
-        if (issueMatch) {
-          try {
-            execSync(`bd update ${issueMatch[1]} --status reverted --comment "PR reverted"`, { stdio: 'inherit' });
-            console.log(`     Updated Beads issue #${issueMatch[1]} to 'reverted'`);
-          } catch {
-            // Beads not installed - silently continue
-          }
-        }
-      }
+      handlePrRollback(target, dryRun, execSync);
     } else if (method === 'partial') {
-      const files = target.split(',').map(f => f.trim());
-      if (dryRun) {
-        console.log('     Would restore files:');
-        files.forEach(f => console.log(`       - ${f}`));
-      } else {
-        files.forEach(f => {
-          execSync(`git checkout HEAD~1 -- "${f}"`, { stdio: 'inherit' });
-        });
-        execSync(`git commit -m "chore: rollback ${files.join(', ')}"`, { stdio: 'inherit' });
-      }
+      handlePartialRollback(target, dryRun, execSync);
     } else if (method === 'branch') {
-      const [startCommit, endCommit] = target.split('..');
-      if (dryRun) {
-        console.log(`     Would revert range: ${startCommit}..${endCommit}`);
-        const commits = execSync(`git log --oneline ${startCommit}..${endCommit}`, { encoding: 'utf-8' });
-        console.log('     Commits to revert:');
-        commits.trim().split('\n').forEach(c => console.log(`       ${c}`));
-      } else {
-        execSync(`git revert --no-edit ${startCommit}..${endCommit}`, { stdio: 'inherit' });
-      }
+      handleBranchRollback(target, dryRun, execSync);
     }
 
     if (!dryRun) {
-      console.log('  📦 Restoring user content...');
-      preserveUserSections(agentsPath, savedSections);
-
-      // Amend commit to include restored USER sections
-      if (fs.existsSync(agentsPath)) {
-        execSync('git add AGENTS.md', { stdio: 'inherit' });
-        execSync('git commit --amend --no-edit', { stdio: 'inherit' });
-      }
-
-      console.log('');
-      console.log(chalk.green('  ✅ Rollback complete'));
-      console.log('     User content preserved');
+      finalizeRollback(agentsPath, savedSections);
     }
 
     return true;
@@ -2952,33 +3288,33 @@ async function showRollbackMenu() {
   let method, target, dryRun = false;
 
   switch (choice.trim()) {
-    case '1':
+    case '1': {
       method = 'commit';
       target = 'HEAD';
       break;
-
-    case '2':
+    }
+    case '2': {
       target = await new Promise(resolve => {
         rl.question('  Enter commit hash: ', resolve);
       });
       method = 'commit';
       break;
-
-    case '3':
+    }
+    case '3': {
       target = await new Promise(resolve => {
         rl.question('  Enter merge commit hash: ', resolve);
       });
       method = 'pr';
       break;
-
-    case '4':
+    }
+    case '4': {
       target = await new Promise(resolve => {
         rl.question('  Enter file paths (comma-separated): ', resolve);
       });
       method = 'partial';
       break;
-
-    case '5':
+    }
+    case '5': {
       const start = await new Promise(resolve => {
         rl.question('  Enter start commit: ', resolve);
       });
@@ -2988,8 +3324,8 @@ async function showRollbackMenu() {
       target = `${start.trim()}..${end.trim()}`;
       method = 'branch';
       break;
-
-    case '6':
+    }
+    case '6': {
       dryRun = true;
       const dryMethod = await new Promise(resolve => {
         rl.question('  Preview method (commit/pr/partial/branch): ', resolve);
@@ -2999,11 +3335,12 @@ async function showRollbackMenu() {
         rl.question('  Enter target (commit/files/range): ', resolve);
       });
       break;
-
-    default:
+    }
+    default: {
       console.log(chalk.red('  Invalid choice'));
       rl.close();
       return;
+    }
   }
 
   rl.close();