claude-flow-novice 1.3.6 → 1.5.0

package/.claude-flow-novice/dist/src/slash-commands/claude-soul.js

@@ -3,17 +3,21 @@
 /**
  * CLAUDE-SOUL.md Slash Command
  *
- * Generate a project soul document - the why, what, and how of the project
- * A sparse language doc limited to 500 lines focusing on project essence
+ * Interactive questionnaire to create a project soul document.
+ * Guides users through defining their project's who, what, when, where, why
+ * to provide context for AI agents when they hit roadblocks.
+ * Document size: 250-500 words focusing on project essence and decision context.
  */
 
 import fs from 'fs/promises';
 import path from 'path';
+import readline from 'readline';
 
 export class ClaudeSoulSlashCommand {
   constructor(projectPath = process.cwd()) {
     this.projectPath = projectPath;
     this.claudeSoulPath = path.join(projectPath, 'claude-soul.md');
+    this.rl = null;
   }
 
   /**
@@ -23,16 +27,40 @@ export class ClaudeSoulSlashCommand {
     const {
       backup = true,
       preview = false,
-      force = false
+      force = false,
+      interactive = true
     } = options;
 
     try {
-      console.log('🚀 Generating claude-soul.md...');
+      console.log('🚀 Creating your project soul document...');
 
-      // Step 1: Generate soul content
-      const soulContent = await this.generateSoulContent();
+      if (!preview) {
+        console.log('📝 This interactive questionnaire will help AI agents understand your project context.');
+        console.log('');
+      }
+
+      let projectData;
+
+      if (interactive && !preview) {
+        // Step 1: Run interactive questionnaire
+        projectData = await this.runQuestionnaire();
+
+        if (!projectData) {
+          return {
+            success: false,
+            action: 'cancelled',
+            message: 'Questionnaire cancelled by user'
+          };
+        }
+      } else {
+        // Fallback to auto-generation for preview mode
+        projectData = await this.autoGenerateData();
+      }
+
+      // Step 2: Generate soul content
+      const soulContent = await this.generateSoulContent(projectData);
 
-      // Step 2: Handle preview mode
+      // Step 3: Handle preview mode
       if (preview) {
         return {
           success: true,
@@ -42,10 +70,10 @@ export class ClaudeSoulSlashCommand {
         };
       }
 
-      // Step 3: Check for existing file
+      // Step 4: Check for existing file
       const existingSoulExists = await this.fileExists(this.claudeSoulPath);
 
-      // Step 4: Handle force/confirmation for existing files
+      // Step 5: Handle force/confirmation for existing files
       if (existingSoulExists && !force) {
         const shouldOverwrite = await this.confirmOverwrite();
         if (!shouldOverwrite) {
@@ -57,15 +85,18 @@ export class ClaudeSoulSlashCommand {
         }
       }
 
-      // Step 5: Create backup if requested
+      // Step 6: Create backup if requested
       if (backup && existingSoulExists) {
         await this.createBackup();
       }
 
-      // Step 6: Write the file
+      // Step 7: Write the file
       await fs.writeFile(this.claudeSoulPath, soulContent, 'utf8');
 
-      console.log('✅ claude-soul.md generated successfully');
+      console.log('');
+      console.log('✅ claude-soul.md created successfully!');
+      console.log('📊 AI agents can now reference this document for project context.');
+
       return {
         success: true,
         action: 'generated',
@@ -81,402 +112,229 @@ export class ClaudeSoulSlashCommand {
         action: 'error',
         error: error.message
       };
+    } finally {
+      if (this.rl) {
+        this.rl.close();
+      }
     }
   }
 
   /**
-   * Generate the soul content by analyzing the project
+   * Generate the soul content from questionnaire data
    */
-  async generateSoulContent() {
-    const projectAnalysis = await this.analyzeProject();
-
-    return `# ${projectAnalysis.name} - Project Soul
+  async generateSoulContent(projectData) {
+    const projectName = projectData.name || path.basename(this.projectPath);
 
-> **AI Context**: This document contains the project's essence, purpose, and philosophy. Use this context to understand project goals, make consistent decisions about code and architecture, and maintain alignment with project values throughout development.
+    return `# ${projectName} - Project Soul
 
-## WHY - The Purpose
+> **AI Context**: This document provides essential project context to help AI agents understand goals, make decisions, and maintain alignment with project values when encountering roadblocks or architectural choices.
 
-### Core Mission
-${projectAnalysis.mission}
+## WHO - The People
 
-### Problem We Solve
-${projectAnalysis.problem}
+**Project Owner**: ${projectData.owner || 'Not specified'}
+**Target Users**: ${projectData.targetUsers || 'Not specified'}
+**Team**: ${projectData.teamSize || 'Not specified'}
 
-### Vision
-${projectAnalysis.vision}
+## WHAT - The Project
 
-## WHAT - The Essence
+**Purpose**: ${projectData.purpose}
 
-### Project Identity
-- **Type**: ${projectAnalysis.type}
-- **Domain**: ${projectAnalysis.domain}
-- **Scope**: ${projectAnalysis.scope}
+**Core Problem**: ${projectData.problem}
 
-### Core Capabilities
-${projectAnalysis.capabilities.map(cap => `- ${cap}`).join('\n')}
+**Key Features**:
+${(projectData.features || []).map(feature => `- ${feature}`).join('\n') || '- Not specified'}
 
-### Key Features
-${projectAnalysis.features.map(feature => `- ${feature}`).join('\n')}
+**Success Metrics**: ${projectData.successMetrics || 'Not specified'}
 
-### Architecture Philosophy
-${projectAnalysis.architecture}
+## WHEN - The Timeline
 
-## HOW - The Approach
+**Project Stage**: ${projectData.stage || 'Not specified'}
+**Key Milestones**: ${projectData.milestones || 'Not specified'}
+**Constraints**: ${projectData.timeConstraints || 'None specified'}
 
-### Development Methodology
-${projectAnalysis.methodology}
+## WHERE - The Context
 
-### Technology Stack
-${projectAnalysis.techStack.map(tech => `- ${tech}`).join('\n')}
+**Domain**: ${projectData.domain || 'General software'}
+**Environment**: ${projectData.environment || 'Not specified'}
+**Scale**: ${projectData.scale || 'Small to medium'}
 
-### Code Principles
-${projectAnalysis.principles.map(principle => `- ${principle}`).join('\n')}
+## WHY - The Motivation
 
-### Quality Standards
-${projectAnalysis.quality}
+**Vision**: ${projectData.vision}
 
-## SOUL - The Spirit
+**Values**:
+${(projectData.values || []).map(value => `- ${value}`).join('\n') || '- Quality and maintainability'}
 
-### Values
-${projectAnalysis.values.map(value => `- ${value}`).join('\n')}
+**Impact**: ${projectData.impact || 'Positive user experience'}
 
-### Community
-${projectAnalysis.community}
+## TECHNICAL SOUL
 
-### Future Vision
-${projectAnalysis.future}
-
-### Legacy Goals
-${projectAnalysis.legacy}
+**Architecture Preference**: ${projectData.architecture || 'Clean and maintainable'}
+**Technology Stack**: ${projectData.techStack || 'Modern best practices'}
+**Quality Standards**: ${projectData.quality || 'High standards with testing'}
+**Decision Framework**: ${projectData.decisions || 'Pragmatic choices balancing speed and quality'}
 
 ---
 
-> **For AI Assistants**: Reference this document when writing code, suggesting architecture changes, or making technical decisions. Ensure all recommendations align with the project's mission, values, and technical approach outlined above.
+> **AI Assistant Guidance**: When you encounter ambiguity or need to make technical decisions, refer to this document. Prioritize solutions that align with the stated values, target users, and technical preferences. If unsure, ask for clarification within the context of these project goals.
 
-*Generated: ${new Date().toISOString().split('T')[0]} | Limit: 500 lines | Last updated: ${new Date().toLocaleDateString()}*
+*Created: ${new Date().toLocaleDateString()} | Words: ${this.countWords(projectData)} | Purpose: AI Decision Context*
 `;
   }
 
   /**
-   * Analyze the project to extract its soul
+   * Run interactive questionnaire to gather project data
    */
-  async analyzeProject() {
-    const packageInfo = await this.getPackageInfo();
-    const repoInfo = await this.getRepositoryInfo();
-    const codebaseInfo = await this.getCodebaseInfo();
+  async runQuestionnaire() {
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
 
-    // Generate project analysis
-    return {
-      name: packageInfo.name || path.basename(this.projectPath),
-      mission: this.inferMission(packageInfo, repoInfo),
-      problem: this.inferProblem(packageInfo, codebaseInfo),
-      vision: this.inferVision(packageInfo, repoInfo),
-      type: this.inferProjectType(packageInfo, codebaseInfo),
-      domain: this.inferDomain(packageInfo, codebaseInfo),
-      scope: this.inferScope(packageInfo, codebaseInfo),
-      capabilities: this.inferCapabilities(packageInfo, codebaseInfo),
-      features: this.inferFeatures(packageInfo, codebaseInfo),
-      architecture: this.inferArchitecture(codebaseInfo),
-      methodology: this.inferMethodology(codebaseInfo),
-      techStack: this.inferTechStack(packageInfo, codebaseInfo),
-      principles: this.inferPrinciples(codebaseInfo),
-      quality: this.inferQuality(packageInfo, codebaseInfo),
-      values: this.inferValues(packageInfo, repoInfo),
-      community: this.inferCommunity(packageInfo, repoInfo),
-      future: this.inferFuture(packageInfo, repoInfo),
-      legacy: this.inferLegacy(packageInfo, repoInfo)
-    };
-  }
+    console.log('📋 Let\'s define your project\'s soul! (Press Ctrl+C anytime to cancel)');
+    console.log('💡 This context helps AI agents make better decisions when they encounter roadblocks.');
+    console.log('');
 
-  /**
-   * Get package.json information
-   */
-  async getPackageInfo() {
     try {
-      const packagePath = path.join(this.projectPath, 'package.json');
-      const packageContent = await fs.readFile(packagePath, 'utf8');
-      return JSON.parse(packageContent);
-    } catch {
-      return {};
-    }
-  }
+      const projectData = {};
 
-  /**
-   * Get repository information
-   */
-  async getRepositoryInfo() {
-    const info = { hasGit: false, files: [] };
-
-    try {
-      await fs.access(path.join(this.projectPath, '.git'));
-      info.hasGit = true;
-    } catch {}
+      // WHO questions
+      console.log('\n🙋 WHO - The People Behind This Project');
+      projectData.owner = await this.ask('Who is the main owner/maintainer of this project?', 'Individual developer');
+      projectData.targetUsers = await this.ask('Who are your primary users/audience?', 'Developers');
+      projectData.teamSize = await this.ask('Team size (solo, 2-5, 6-20, 20+)?', 'Solo');
 
-    try {
-      const files = await fs.readdir(this.projectPath);
-      info.files = files;
-    } catch {}
-
-    return info;
-  }
+      // WHAT questions
+      console.log('\n📦 WHAT - The Project Essence');
+      projectData.name = await this.ask('Project name?', path.basename(this.projectPath));
+      projectData.purpose = await this.ask('What does this project do? (1-2 sentences)', 'Solves development problems');
+      projectData.problem = await this.ask('What specific problem does it solve?', 'Streamlines common tasks');
 
-  /**
-   * Get codebase structure information
-   */
-  async getCodebaseInfo() {
-    const info = {
-      directories: [],
-      languages: new Set(),
-      configFiles: [],
-      testFiles: [],
-      hasTests: false,
-      hasDocumentation: false
-    };
+      const featuresInput = await this.ask('Key features (comma-separated)?', 'Core functionality');
+      projectData.features = featuresInput.split(',').map(f => f.trim()).filter(f => f);
 
-    try {
-      const entries = await fs.readdir(this.projectPath, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          info.directories.push(entry.name);
-        } else {
-          const ext = path.extname(entry.name).toLowerCase();
-          const name = entry.name.toLowerCase();
-
-          // Track languages
-          const languageMap = {
-            '.js': 'JavaScript',
-            '.ts': 'TypeScript',
-            '.py': 'Python',
-            '.go': 'Go',
-            '.rs': 'Rust',
-            '.java': 'Java',
-            '.cpp': 'C++',
-            '.c': 'C'
-          };
+      projectData.successMetrics = await this.ask('How do you measure success?', 'User satisfaction and adoption');
 
-          if (languageMap[ext]) {
-            info.languages.add(languageMap[ext]);
-          }
-
-          // Track config files
-          if (name.includes('config') || name.includes('.json') ||
-              name.includes('.yml') || name.includes('.yaml')) {
-            info.configFiles.push(entry.name);
-          }
-
-          // Track test files
-          if (name.includes('test') || name.includes('spec')) {
-            info.testFiles.push(entry.name);
-            info.hasTests = true;
-          }
-
-          // Track documentation
-          if (ext === '.md' || name.includes('readme') || name.includes('doc')) {
-            info.hasDocumentation = true;
-          }
-        }
-      }
-    } catch {}
+      // WHEN questions
+      console.log('\n⏰ WHEN - Timeline and Stage');
+      projectData.stage = await this.ask('Current stage (concept/prototype/mvp/production/mature)?', 'Development');
+      projectData.milestones = await this.ask('Key upcoming milestones?', 'Feature completion');
+      projectData.timeConstraints = await this.ask('Any time constraints or deadlines?', 'None');
 
-    return info;
-  }
+      // WHERE questions
+      console.log('\n🌍 WHERE - Context and Environment');
+      projectData.domain = await this.ask('What domain/industry?', 'Software development');
+      projectData.environment = await this.ask('Deployment environment (local/web/mobile/enterprise)?', 'Web');
+      projectData.scale = await this.ask('Expected scale (personal/small team/enterprise)?', 'Small team');
 
-  // Inference methods
-  inferMission(pkg, repo) {
-    if (pkg.description) {
-      return pkg.description;
-    }
+      // WHY questions
+      console.log('\n💡 WHY - Motivation and Vision');
+      projectData.vision = await this.ask('What\'s your long-term vision?', 'Create valuable, maintainable software');
 
-    const name = pkg.name || path.basename(this.projectPath);
+      const valuesInput = await this.ask('Core values (comma-separated)?', 'Quality, simplicity, maintainability');
+      projectData.values = valuesInput.split(',').map(v => v.trim()).filter(v => v);
 
-    if (name.includes('flow') || name.includes('orchestrat')) {
-      return "Orchestrate and coordinate complex workflows with intelligent automation";
-    }
-    if (name.includes('api') || name.includes('server')) {
-      return "Provide robust API services and server-side functionality";
-    }
-    if (name.includes('cli') || name.includes('tool')) {
-      return "Deliver powerful command-line tools for developer productivity";
-    }
+      projectData.impact = await this.ask('What impact do you want to achieve?', 'Improve developer productivity');
 
-    return "Solve complex problems through innovative software solutions";
-  }
+      // TECHNICAL questions
+      console.log('\n⚙️ TECHNICAL - Architecture and Approach');
+      projectData.architecture = await this.ask('Preferred architecture style?', 'Clean and modular');
+      projectData.techStack = await this.ask('Technology preferences?', 'Modern, well-supported tools');
+      projectData.quality = await this.ask('Quality standards?', 'High with automated testing');
+      projectData.decisions = await this.ask('How should AI agents make decisions when unclear?', 'Ask for clarification, prefer maintainable solutions');
 
-  inferProblem(pkg, codebase) {
-    if (pkg.name?.includes('flow')) {
-      return "Complex multi-agent coordination and workflow orchestration requires simplified interfaces while maintaining advanced capabilities";
-    }
-    if (codebase.languages.has('TypeScript') && codebase.hasTests) {
-      return "Enterprise-grade development workflows need reliable, type-safe, and well-tested solutions";
-    }
-    return "Modern software development requires efficient, maintainable, and scalable solutions";
-  }
+      console.log('');
+      console.log('✅ Questionnaire complete! Generating your project soul document...');
 
-  inferVision(pkg, repo) {
-    if (pkg.name?.includes('novice')) {
-      return "Democratize advanced technology by making it accessible to users of all skill levels";
+      return projectData;
+    } catch (error) {
+      if (error.message === 'CANCELLED') {
+        console.log('\n❌ Questionnaire cancelled.');
+        return null;
+      }
+      throw error;
     }
-    return "Create software that empowers users and teams to achieve more with less complexity";
   }
 
-  inferProjectType(pkg, codebase) {
-    if (pkg.bin) return "CLI Tool";
-    if (codebase.directories.includes('src') && codebase.directories.includes('tests')) return "Library/Framework";
-    if (pkg.dependencies?.express || pkg.dependencies?.fastify) return "Web Service";
-    if (codebase.languages.has('TypeScript')) return "TypeScript Application";
-    return "Software Project";
-  }
-
-  inferDomain(pkg, codebase) {
-    const name = (pkg.name || '').toLowerCase();
-    if (name.includes('flow') || name.includes('orchestrat')) return "Workflow Orchestration";
-    if (name.includes('ai') || name.includes('ml')) return "Artificial Intelligence";
-    if (name.includes('api') || name.includes('web')) return "Web Development";
-    if (name.includes('cli') || name.includes('tool')) return "Developer Tools";
-    return "Software Development";
-  }
-
-  inferScope(pkg, codebase) {
-    const dirCount = codebase.directories.length;
-    const langCount = codebase.languages.size;
-
-    if (dirCount > 10 && langCount > 2) return "Enterprise-scale multi-language platform";
-    if (dirCount > 5) return "Medium-scale application with modular architecture";
-    return "Focused tool with clear boundaries";
-  }
-
-  inferCapabilities(pkg, codebase) {
-    const caps = [];
-
-    if (pkg.bin) caps.push("Command-line interface execution");
-    if (codebase.hasTests) caps.push("Automated testing and validation");
-    if (codebase.languages.has('TypeScript')) caps.push("Type-safe development");
-    if (pkg.dependencies?.sqlite3) caps.push("Persistent data storage");
-    if (pkg.scripts?.build) caps.push("Build and compilation");
-    if (pkg.name?.includes('flow')) caps.push("Workflow orchestration and automation");
-
-    return caps.length > 0 ? caps : ["Core functionality delivery", "Modular architecture"];
-  }
-
-  inferFeatures(pkg, codebase) {
-    const features = new Set();
-
-    if (pkg.scripts) {
-      Object.keys(pkg.scripts).forEach(script => {
-        if (script.includes('test') && !features.has("testing")) {
-          features.add("Comprehensive testing suite");
-          features.add("testing");
-        }
-        if (script.includes('build') && !features.has("build")) {
-          features.add("Automated build system");
-          features.add("build");
-        }
-        if (script.includes('dev') && !features.has("dev")) {
-          features.add("Development workflow tools");
-          features.add("dev");
+  /**
+   * Ask a question with default value
+   */
+  async ask(question, defaultValue) {
+    return new Promise((resolve, reject) => {
+      const prompt = defaultValue ?
+        `${question} [${defaultValue}]: ` :
+        `${question}: `;
+
+      this.rl.question(prompt, (answer) => {
+        if (answer.toLowerCase() === 'ctrl+c' || answer.toLowerCase() === 'cancel') {
+          reject(new Error('CANCELLED'));
+          return;
         }
+        resolve(answer.trim() || defaultValue);
       });
-    }
-
-    if (codebase.configFiles.length > 0) features.add("Flexible configuration system");
-    if (codebase.hasDocumentation) features.add("Comprehensive documentation");
-
-    // Filter out the marker keys and return as array
-    const filteredFeatures = Array.from(features).filter(f =>
-      f !== "testing" && f !== "build" && f !== "dev"
-    );
-
-    return filteredFeatures.length > 0 ? filteredFeatures : ["Modular design", "Clean architecture"];
-  }
-
-  inferArchitecture(codebase) {
-    if (codebase.directories.includes('src') && codebase.directories.includes('dist')) {
-      return "Source-to-distribution compilation with clear separation of concerns";
-    }
-    if (codebase.directories.includes('lib') || codebase.directories.includes('src')) {
-      return "Modular architecture with logical component separation";
-    }
-    return "Clean, maintainable structure following best practices";
-  }
-
-  inferMethodology(codebase) {
-    if (codebase.hasTests && codebase.directories.includes('src')) {
-      return "Test-driven development with continuous integration";
-    }
-    if (codebase.hasTests) {
-      return "Quality-first development with automated validation";
-    }
-    return "Iterative development with focus on maintainability";
+    });
   }
 
-  inferTechStack(pkg, codebase) {
-    const stack = [];
-
-    Array.from(codebase.languages).forEach(lang => stack.push(lang));
-
-    if (pkg.dependencies?.sqlite3) stack.push("SQLite Database");
-    if (pkg.dependencies?.express) stack.push("Express.js");
-    if (pkg.dependencies?.react) stack.push("React");
-    if (pkg.devDependencies?.jest) stack.push("Jest Testing");
-    if (pkg.devDependencies?.typescript) stack.push("TypeScript Compiler");
-
-    return stack.length > 0 ? stack : ["Modern JavaScript/TypeScript ecosystem"];
-  }
-
-  inferPrinciples(codebase) {
-    const principles = ["Clean, readable code"];
-
-    if (codebase.hasTests) principles.push("Test-driven development");
-    if (codebase.languages.has('TypeScript')) principles.push("Type safety and static analysis");
-    if (codebase.directories.includes('src')) principles.push("Separation of concerns");
-
-    principles.push("Progressive enhancement");
-    principles.push("Documentation-first approach");
-
-    return principles;
-  }
-
-  inferQuality(pkg, codebase) {
-    let quality = "High standards with ";
-
-    if (codebase.hasTests) quality += "comprehensive testing, ";
-    if (codebase.languages.has('TypeScript')) quality += "type safety, ";
-    if (pkg.scripts?.lint) quality += "linting, ";
-
-    quality += "and continuous improvement";
-
-    return quality;
-  }
-
-  inferValues(pkg, repo) {
-    const values = ["Simplicity without sacrificing power"];
-
-    if (pkg.name?.includes('novice')) values.push("Accessibility for all skill levels");
-    if (pkg.license === 'MIT') values.push("Open source collaboration");
-
-    values.push("Quality over quantity");
-    values.push("User-centric design");
-
-    return values;
-  }
+  /**
+   * Auto-generate data for preview mode (fallback)
+   */
+  async autoGenerateData() {
+    const packageInfo = await this.getBasicPackageInfo();
+    const projectName = packageInfo.name || path.basename(this.projectPath);
 
-  inferCommunity(pkg, repo) {
-    if (pkg.repository?.url) {
-      return `Open source project welcoming contributions. Repository: ${pkg.repository.url}`;
-    }
-    return "Collaborative development with focus on shared learning and improvement";
+    return {
+      name: projectName,
+      owner: 'Project Owner',
+      targetUsers: 'Developers and end users',
+      teamSize: 'Small team',
+      purpose: packageInfo.description || 'Software project providing valuable functionality',
+      problem: 'Solving common development challenges',
+      features: ['Core functionality', 'User interface', 'API integration'],
+      successMetrics: 'User adoption and satisfaction',
+      stage: 'Development',
+      milestones: 'Feature completion and testing',
+      timeConstraints: 'Ongoing development',
+      domain: 'Software development',
+      environment: 'Web application',
+      scale: 'Medium scale',
+      vision: 'Create maintainable, valuable software',
+      values: ['Quality', 'Maintainability', 'User focus'],
+      impact: 'Positive user experience and productivity',
+      architecture: 'Clean, modular architecture',
+      techStack: 'Modern JavaScript/TypeScript stack',
+      quality: 'High standards with automated testing',
+      decisions: 'Pragmatic choices balancing quality and delivery speed'
+    };
   }
 
-  inferFuture(pkg, repo) {
-    if (pkg.name?.includes('flow')) {
-      return "Evolve into the premier platform for accessible AI workflow orchestration";
+  /**
+   * Get basic package.json information
+   */
+  async getBasicPackageInfo() {
+    try {
+      const packagePath = path.join(this.projectPath, 'package.json');
+      const packageContent = await fs.readFile(packagePath, 'utf8');
+      return JSON.parse(packageContent);
+    } catch {
+      return {};
     }
-    return "Continuous evolution to meet emerging developer needs and technological advances";
   }
 
-  inferLegacy(pkg, repo) {
-    return "Create lasting impact by making complex technology accessible and empowering developers to build amazing things";
+  /**
+   * Count approximate words in project data
+   */
+  countWords(projectData) {
+    const textFields = [
+      projectData.owner, projectData.targetUsers, projectData.purpose,
+      projectData.problem, projectData.vision, projectData.impact,
+      projectData.architecture, projectData.techStack, projectData.quality,
+      projectData.decisions
+    ];
+
+    const arrayFields = projectData.features.concat(projectData.values);
+
+    const allText = textFields.concat(arrayFields).join(' ');
+    return allText.split(/\s+/).filter(word => word.length > 0).length;
   }
 
   /**
@@ -500,6 +358,13 @@ ${projectAnalysis.legacy}
    * Simple confirmation prompt for overwriting existing files
    */
   async confirmOverwrite() {
+    if (this.rl) {
+      return new Promise((resolve) => {
+        this.rl.question('⚠️ claude-soul.md exists. Overwrite? (y/N): ', (answer) => {
+          resolve(answer.toLowerCase().startsWith('y'));
+        });
+      });
+    }
     console.log('⚠️ claude-soul.md exists. Use --force to overwrite or --preview to see changes.');
     return false;
   }
@@ -516,12 +381,17 @@ ${projectAnalysis.legacy}
     }
   }
 
-  /**
-   * Show preview of what would be generated
-   */
-  async showPreview() {
-    const result = await this.execute({ preview: true });
+}
+
+/**
+ * CLI Interface for slash command
+ */
+export async function executeClaudeSoulCommand(args = {}) {
+  const command = new ClaudeSoulSlashCommand();
 
+  // Handle different command modes
+  if (args.preview) {
+    const result = await command.execute({ ...args, preview: true });
     if (result.success) {
       console.log('📄 claude-soul.md Preview:');
       console.log('━'.repeat(50));
@@ -530,23 +400,31 @@ ${projectAnalysis.legacy}
       console.log(`📊 Total length: ${result.content.length} characters`);
       console.log(`📏 Lines: ${result.content.split('\n').length}`);
     }
-
     return result;
   }
-}
 
-/**
- * CLI Interface for slash command
- */
-export async function executeClaudeSoulCommand(args = {}) {
-  const command = new ClaudeSoulSlashCommand();
+  if (args.help) {
+    console.log(`
+🧠 Claude Soul - Project Context Generator
 
-  // Handle different command modes
-  if (args.preview) {
-    return await command.showPreview();
+Creates a project soul document to provide AI agents with essential context
+about your project's who, what, when, where, and why.
+
+Usage:
+  /claude-soul                 # Interactive questionnaire
+  /claude-soul --preview       # Show preview without saving
+  /claude-soul --force         # Overwrite existing file
+  /claude-soul --no-interactive # Skip questionnaire, auto-generate
+
+Purpose: When AI agents hit roadblocks, they can reference this document
+to understand project goals and make decisions aligned with your vision.
+
+Document size: 250-500 words focusing on decision-making context.
+    `);
+    return { success: true, action: 'help' };
   }
 
-  // Default: generate claude-soul.md
+  // Default: run interactive questionnaire
   return await command.execute(args);
 }
 
@@ -555,8 +433,13 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   const args = {
     preview: process.argv.includes('--preview'),
     force: process.argv.includes('--force'),
-    backup: !process.argv.includes('--no-backup')
+    backup: !process.argv.includes('--no-backup'),
+    interactive: !process.argv.includes('--no-interactive'),
+    help: process.argv.includes('--help') || process.argv.includes('-h')
   };
 
-  executeClaudeSoulCommand(args);
+  executeClaudeSoulCommand(args).catch(error => {
+    console.error('Error:', error.message);
+    process.exit(1);
+  });
 }