@iservu-inc/adf-cli 0.11.0 → 0.12.9

package/bin/adf.js

@@ -29,7 +29,68 @@ program
   .addHelpText('before', () => {
     const adfInstallPath = path.resolve(__dirname, '..');
     return `\n${chalk.cyan.bold('ADF CLI')} ${chalk.gray(`v${packageJson.version}`)}\n${chalk.gray('Install Path:')} ${chalk.white(adfInstallPath)}\n`;
-  });
+  })
+  .addHelpText('after', `
+${chalk.cyan.bold('Quick Start:')}
+  ${chalk.gray('1. Configure your AI provider')}
+  $ adf config
+
+  ${chalk.gray('2. Initialize a project with AI-guided interview')}
+  $ adf init
+
+  ${chalk.gray('3. Deploy to your AI coding assistant')}
+  $ adf deploy
+
+${chalk.cyan.bold('What is ADF?')}
+  AgentDevFramework (ADF) is an AI-assisted development framework that helps
+  you gather requirements through intelligent AI-guided interviews. It supports
+  multiple AI providers and workflow levels, from rapid prototyping to
+  comprehensive enterprise documentation.
+
+${chalk.cyan.bold('Key Features:')}
+  • ${chalk.yellow('Multi-Provider AI')} - Anthropic, OpenAI, Google, OpenRouter
+  • ${chalk.yellow('3 Workflow Levels')} - Rapid (PRP), Balanced (Spec-Kit), Comprehensive (BMAD)
+  • ${chalk.yellow('Smart Filtering')} - AI-powered question filtering based on context
+  • ${chalk.yellow('Learning System')} - Adapts to your preferences over time
+  • ${chalk.yellow('Session Resume')} - Pause and resume interviews anytime
+  • ${chalk.yellow('Multi-Tool Deploy')} - 10+ IDEs and CLI tools supported
+    ${chalk.gray('IDEs:')} Windsurf, Cursor, VS Code, Zed, Antigravity
+    ${chalk.gray('CLI:')} Claude Code, OpenCode, Gemini CLI, DeepAgent
+
+${chalk.cyan.bold('Getting Help:')}
+  ${chalk.gray('# Detailed help for specific commands')}
+  $ adf init --help
+  $ adf deploy --help
+  $ adf config --help
+  $ adf update --help
+
+  ${chalk.gray('# Check version and install path')}
+  $ adf --version
+
+${chalk.cyan.bold('Common Workflows:')}
+  ${chalk.yellow('Quick Prototype:')}
+    $ adf init --rapid --tool windsurf
+
+  ${chalk.yellow('Standard Project:')}
+    $ adf config              ${chalk.gray('# Configure AI provider once')}
+    $ adf init --balanced     ${chalk.gray('# Run interview')}
+    $ adf deploy cursor       ${chalk.gray('# Deploy to Cursor')}
+
+  ${chalk.yellow('Enterprise Project:')}
+    $ adf config              ${chalk.gray('# Configure with comprehensive mode')}
+    $ adf init --comprehensive
+    $ adf deploy vscode       ${chalk.gray('# Deploy to multiple tools')}
+    $ adf deploy claude-code
+
+${chalk.cyan.bold('Documentation & Support:')}
+  • GitHub: https://github.com/iservu/adf-cli
+  • Issues: https://github.com/iservu/adf-cli/issues
+  • Docs:   https://github.com/iservu/adf-cli#readme
+
+${chalk.cyan.bold('Learn More:')}
+  Run any command with ${chalk.white('--help')} for detailed information:
+  ${chalk.gray('$ adf <command> --help')}
+`);
 
 // adf init
 program
@@ -39,6 +100,51 @@ program
   .option('--balanced', 'Skip questions, use Level 2 (Balanced)')
   .option('--comprehensive', 'Skip questions, use Level 3 (Comprehensive)')
   .option('--tool <tool>', 'Specify deployment tool (windsurf, cursor, etc.)')
+  .addHelpText('after', `
+${chalk.cyan.bold('Description:')}
+  Start an interactive AI-guided interview to gather project requirements.
+  The interview uses AI to analyze your answers and generate comprehensive
+  documentation based on your chosen workflow level.
+
+${chalk.cyan.bold('Workflow Levels:')}
+  ${chalk.yellow('Rapid (PRP)')}          - 20 core questions, fast setup
+                        Agents: dev, qa
+                        Output: prp.md
+                        Best for: Quick prototypes, MVPs
+
+  ${chalk.yellow('Balanced (Spec-Kit)')}  - 30+ questions, detailed specs
+                        Agents: analyst, pm, dev, qa
+                        Output: constitution.md, specification.md, plan.md, tasks.md
+                        Best for: Standard projects with clear requirements
+
+  ${chalk.yellow('Comprehensive (BMAD)')} - 40+ questions, full documentation
+                        Agents: analyst, pm, architect, sm, dev, qa
+                        Output: prd.md, architecture.md, stories.md
+                        Best for: Enterprise projects, complex systems
+
+${chalk.cyan.bold('Examples:')}
+  ${chalk.gray('# Interactive mode - choose workflow interactively')}
+  $ adf init
+
+  ${chalk.gray('# Quick start with Rapid workflow')}
+  $ adf init --rapid
+
+  ${chalk.gray('# Balanced workflow deployed to Windsurf')}
+  $ adf init --balanced --tool windsurf
+
+  ${chalk.gray('# Comprehensive workflow for enterprise project')}
+  $ adf init --comprehensive
+
+${chalk.cyan.bold('Features:')}
+  • AI-powered question filtering based on project context
+  • Answer quality analysis and suggestions
+  • Session resume capability (Ctrl+C to pause)
+  • Learning system that adapts to your preferences
+  • Multi-provider AI support (Anthropic, OpenAI, Google, OpenRouter)
+
+${chalk.cyan.bold('Output Directory:')}
+  All outputs saved to: ${chalk.white('.adf/sessions/{timestamp}_{workflow}/')}
+`)
   .action(initCommand);
 
 // adf deploy
@@ -46,6 +152,96 @@ program
   .command('deploy [tool]')
   .description('Deploy framework to specified tool')
   .option('-l, --list', 'List available deployment tools')
+  .addHelpText('after', `
+${chalk.cyan.bold('Description:')}
+  Deploy ADF framework outputs to your AI coding assistant or IDE.
+  Converts session outputs (PRD, specs, stories) into tool-specific
+  configuration files and agent definitions.
+
+${chalk.cyan.bold('Command Syntax:')}
+  ${chalk.white('adf deploy [tool]')}
+
+  ${chalk.yellow('[tool]')} - (Optional) Target tool name
+              If omitted, you'll be prompted to select interactively
+              Supported: windsurf, cursor, vscode, claude-code, zed, generic
+
+${chalk.cyan.bold('Supported Tools:')}
+  ${chalk.white.bold('IDEs:')}
+  ${chalk.yellow('windsurf')}      - Codeium Windsurf IDE
+                   Output: .windsurfrules
+
+  ${chalk.yellow('cursor')}        - Cursor AI IDE
+                   Output: .cursorrules
+
+  ${chalk.yellow('vscode')}        - Visual Studio Code
+                   Output: .vscode/settings.json, .github/copilot-instructions.md
+
+  ${chalk.yellow('zed')}           - Zed Editor
+                   Output: .zed/settings.json, .zed/rules (symlink to AGENTS.md)
+
+  ${chalk.yellow('antigravity')}   - Google Antigravity IDE
+                   Output: .antigravity/agents.yaml
+
+  ${chalk.white.bold('CLI Tools:')}
+  ${chalk.yellow('claude-code')}   - Anthropic Claude Code CLI
+                   Output: .framework/agents/*.md
+
+  ${chalk.yellow('opencode')}      - OpenCode CLI
+                   Output: .opencode.json (JSON config with agents & MCP)
+
+  ${chalk.yellow('gemini-cli')}    - Google Gemini CLI
+                   Output: GEMINI.md (project context markdown)
+
+  ${chalk.yellow('deepagent')}     - Abacus.ai DeepAgent CLI
+                   Output: .deepagent/agents/*.md, .deepagent/README.md
+
+  ${chalk.white.bold('Generic:')}
+  ${chalk.yellow('generic')}       - Generic AI tools (agent markdown files)
+                   Output: .framework/agents/*.md
+
+${chalk.cyan.bold('Examples:')}
+  ${chalk.gray('# List available tools')}
+  $ adf deploy --list
+
+  ${chalk.gray('# Interactive tool selection')}
+  $ adf deploy
+
+  ${chalk.gray('# Deploy to specific tool')}
+  $ adf deploy windsurf
+
+  ${chalk.gray('# Deploy to multiple tools (run multiple times)')}
+  $ adf deploy cursor
+  $ adf deploy vscode
+
+${chalk.cyan.bold('How It Works:')}
+  1. Finds latest completed interview session
+  2. Loads session outputs (PRD, architecture, stories, etc.)
+  3. Transforms outputs into tool-specific format
+  4. Writes configuration files to project root
+  5. Deploys agent definitions (if applicable)
+
+${chalk.cyan.bold('Requirements:')}
+  • Must have completed at least one 'adf init' session
+  • Session must have generated outputs
+  • Outputs located in: .adf/sessions/{timestamp}_{workflow}/outputs/
+
+${chalk.cyan.bold('Output Files by Tool:')}
+  ${chalk.white.bold('IDEs:')}
+  Windsurf:      ${chalk.white('.windsurfrules')}
+  Cursor:        ${chalk.white('.cursorrules')}
+  VS Code:       ${chalk.white('.vscode/settings.json + .github/copilot-instructions.md')}
+  Zed:           ${chalk.white('.zed/settings.json + .zed/rules')}
+  Antigravity:   ${chalk.white('.antigravity/agents.yaml')}
+
+  ${chalk.white.bold('CLI Tools:')}
+  Claude Code:   ${chalk.white('.framework/agents/*.md')}
+  OpenCode:      ${chalk.white('.opencode.json')}
+  Gemini CLI:    ${chalk.white('GEMINI.md')}
+  DeepAgent:     ${chalk.white('.deepagent/agents/*.md + .deepagent/README.md')}
+
+  ${chalk.white.bold('Generic:')}
+  Generic:       ${chalk.white('.framework/agents/*.md')}
+`)
   .action(deployCommand);
 
 // adf update
@@ -53,12 +249,154 @@ program
   .command('update')
   .description('Check for CLI updates and update to latest version')
   .option('--check', 'Only check for updates, don\'t install')
+  .addHelpText('after', `
+${chalk.cyan.bold('Description:')}
+  Check for new versions of ADF CLI and update to the latest release.
+  Compares your current version with the latest published on npm registry.
+
+${chalk.cyan.bold('Command Syntax:')}
+  ${chalk.white('adf update [options]')}
+
+${chalk.cyan.bold('Options:')}
+  ${chalk.yellow('--check')} - Check for updates without installing
+              Shows version comparison and changelog preview
+              No modifications made to your installation
+
+${chalk.cyan.bold('Examples:')}
+  ${chalk.gray('# Check if updates are available')}
+  $ adf update --check
+
+  ${chalk.gray('# Update to latest version')}
+  $ adf update
+
+  ${chalk.gray('# Check current version')}
+  $ adf --version
+
+${chalk.cyan.bold('Update Process:')}
+  1. Fetches latest version info from npm registry
+  2. Compares with your installed version
+  3. Shows changelog and new features
+  4. Prompts for confirmation (if installing)
+  5. Downloads and installs latest version
+  6. Verifies successful installation
+
+${chalk.cyan.bold('Installation Methods:')}
+  ${chalk.yellow('Global Install')} (recommended)
+    $ npm install -g @iservu-inc/adf-cli
+    Updates system-wide installation
+
+  ${chalk.yellow('Local Development')} (npm link)
+    $ cd adf-cli && git pull && npm link
+    Updates linked development version
+
+${chalk.cyan.bold('What Gets Updated:')}
+  • Core CLI functionality
+  • AI provider integrations (Anthropic, OpenAI, Google, OpenRouter)
+  • Interview question sets
+  • Output generators and templates
+  • Bug fixes and performance improvements
+
+${chalk.cyan.bold('Backwards Compatibility:')}
+  • Existing .adf directories are preserved
+  • Sessions and learning data remain intact
+  • API keys and configurations are not affected
+  • May require re-running 'adf deploy' for new features
+`)
   .action(updateCommand);
 
 // adf config
 program
   .command('config')
   .description('Configure ADF settings (AI provider, etc.)')
+  .addHelpText('after', `
+${chalk.cyan.bold('Description:')}
+  Interactive configuration wizard for ADF settings.
+  Configure AI providers, analysis settings, and learning system preferences.
+
+${chalk.cyan.bold('Configuration Categories:')}
+  ${chalk.yellow('1. AI Provider Setup')}
+     Configure which AI provider to use for interviews
+     • Select provider (Anthropic, OpenAI, Google, OpenRouter)
+     • Enter/validate API key
+     • Choose model from dynamically fetched list
+     • Test connection before saving
+
+  ${chalk.yellow('2. Analysis Settings')}
+     Control AI analysis features and performance
+     • Performance Mode: Fast / Balanced / Comprehensive
+     • Answer Quality Analysis: ON / OFF
+     • Smart Question Filtering: ON / OFF
+     • Question Reordering: ON / OFF
+     • Context Extraction: ON / OFF
+
+  ${chalk.yellow('3. Learning System')}
+     Manage skip pattern detection and auto-filtering
+     • Enable/Disable learning system
+     • View detected patterns and rules
+     • Manage learned preferences
+     • Export analytics to JSON/CSV
+     • Configure decay thresholds
+
+${chalk.cyan.bold('AI Providers Supported:')}
+  ${chalk.yellow('Anthropic Claude')}
+    Models: claude-sonnet-4-5, claude-opus-4-5, claude-3-5-sonnet, etc.
+    API Key: Get from https://console.anthropic.com/
+    Format: sk-ant-...
+
+  ${chalk.yellow('OpenAI GPT')}
+    Models: gpt-5.2-chat, gpt-4o, o1, o3, etc. (116+ models)
+    API Key: Get from https://platform.openai.com/api-keys
+    Format: sk-...
+
+  ${chalk.yellow('Google Gemini')}
+    Models: gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash, etc.
+    API Key: Get from https://aistudio.google.com/app/apikey
+    Format: (varies)
+
+  ${chalk.yellow('OpenRouter')}
+    Models: 100+ models from multiple providers
+    API Key: Get from https://openrouter.ai/keys
+    Format: sk-or-...
+
+${chalk.cyan.bold('Examples:')}
+  ${chalk.gray('# Open configuration menu')}
+  $ adf config
+
+  ${chalk.gray('# After configuration, verify with:')}
+  $ cat .adf/.env
+  $ adf init
+
+${chalk.cyan.bold('Performance Modes:')}
+  ${chalk.yellow('Fast')}           - Minimal AI calls (~0.5s per answer)
+                    Answer quality: OFF
+                    Smart filtering: OFF
+                    Best for: Quick interviews, testing
+
+  ${chalk.yellow('Balanced')}       - Moderate AI usage (~2-3s per answer)
+                    Answer quality: ON
+                    Smart filtering: ON
+                    Best for: Most projects (recommended)
+
+  ${chalk.yellow('Comprehensive')} - Full AI analysis (~4-6s per answer)
+                    All features: ON
+                    Context extraction: ON
+                    Question reordering: ON
+                    Best for: Critical projects, detailed requirements
+
+${chalk.cyan.bold('Storage Locations:')}
+  API Keys:           ${chalk.white('.adf/.env')} ${chalk.gray('(gitignored)')}
+  Analysis Config:    ${chalk.white('.adf/analysis-config.json')}
+  Learning Data:      ${chalk.white('.adf/learning/')}
+  Active Provider:    ${chalk.white('.adf/.env')} ${chalk.gray('(ADF_CURRENT_PROVIDER)')}
+  Active Model:       ${chalk.white('.adf/.env')} ${chalk.gray('(ADF_CURRENT_MODEL)')}
+
+${chalk.cyan.bold('Security Notes:')}
+  • API keys stored in .adf/.env (automatically gitignored)
+  • Never committed to version control
+  • Keys validated before saving
+  • Models tested for operational status
+  • All data stored locally on your machine
+`)
   .action(configCommand);
 
 // Handle unknown commands

package/lib/ai/ai-client.js

@@ -97,8 +97,19 @@ class AIClient {
       ]
     });
 
+    // Validate response structure
+    if (!response.content || response.content.length === 0) {
+      throw new Error(`Anthropic model '${this.model}' returned no content.`);
+    }
+
+    const content = response.content[0].text;
+
+    if (!content || content.trim().length === 0) {
+      throw new Error(`Anthropic model '${this.model}' returned empty text.`);
+    }
+
     return {
-      content: response.content[0].text,
+      content,
       model: this.model,
       provider: 'anthropic',
       usage: {
@@ -113,9 +124,9 @@ class AIClient {
    * OpenAI GPT request
    */
   async openaiRequest(prompt, maxTokens, temperature) {
-    // o-series models (o1, o3, etc.) use max_completion_tokens instead of max_tokens
-    // Check for any model starting with 'o' followed by a digit
-    const isOSeriesModel = /^o\d/.test(this.model);
+    // Newer OpenAI models use max_completion_tokens instead of max_tokens
+    // This includes: o-series (o1, o3), gpt-5 series, and potentially others
+    const usesNewParameters = /^(o1|o3|gpt-5)/i.test(this.model);
 
     const requestParams = {
       model: this.model,
@@ -127,27 +138,56 @@ class AIClient {
       ]
     };
 
-    // o-series models use different parameter names
-    if (isOSeriesModel) {
+    // Newer models use different parameter names
+    if (usesNewParameters) {
       requestParams.max_completion_tokens = maxTokens;
-      // o-series models don't support temperature parameter
+      // Newer reasoning models don't support temperature parameter
     } else {
       requestParams.max_tokens = maxTokens;
       requestParams.temperature = temperature;
     }
 
-    const response = await this.client.chat.completions.create(requestParams);
+    try {
+      const response = await this.client.chat.completions.create(requestParams);
 
-    return {
-      content: response.choices[0].message.content,
-      model: this.model,
-      provider: 'openai',
-      usage: {
-        promptTokens: response.usage.prompt_tokens,
-        completionTokens: response.usage.completion_tokens,
-        totalTokens: response.usage.total_tokens
+      return {
+        content: response.choices[0].message.content,
+        model: this.model,
+        provider: 'openai',
+        usage: {
+          promptTokens: response.usage.prompt_tokens,
+          completionTokens: response.usage.completion_tokens,
+          totalTokens: response.usage.total_tokens
+        }
+      };
+    } catch (error) {
+      // If we get a 400 error about max_tokens not being supported,
+      // automatically retry with max_completion_tokens
+      if (error.status === 400 && error.message.includes('max_tokens')) {
+        const retryParams = {
+          model: this.model,
+          messages: requestParams.messages,
+          max_completion_tokens: maxTokens
+          // Don't include temperature for new parameter format models
+        };
+
+        const response = await this.client.chat.completions.create(retryParams);
+
+        return {
+          content: response.choices[0].message.content,
+          model: this.model,
+          provider: 'openai',
+          usage: {
+            promptTokens: response.usage.prompt_tokens,
+            completionTokens: response.usage.completion_tokens,
+            totalTokens: response.usage.total_tokens
+          }
+        };
       }
-    };
+
+      // Re-throw other errors
+      throw error;
+    }
   }
 
   /**
@@ -165,8 +205,20 @@ class AIClient {
     const result = await model.generateContent(prompt);
     const response = result.response;
 
+    // Validate response
+    let content;
+    try {
+      content = response.text();
+    } catch (error) {
+      throw new Error(`Google Gemini model '${this.model}' failed to generate text: ${error.message}`);
+    }
+
+    if (!content || content.trim().length === 0) {
+      throw new Error(`Google Gemini model '${this.model}' returned empty content.`);
+    }
+
     return {
-      content: response.text(),
+      content,
       model: this.model,
       provider: 'google',
       usage: {
@@ -181,28 +233,85 @@ class AIClient {
    * OpenRouter request (uses OpenAI-compatible API)
    */
   async openrouterRequest(prompt, maxTokens, temperature) {
-    const response = await this.client.chat.completions.create({
+    // Newer OpenAI models on OpenRouter may use max_completion_tokens
+    // This includes: o-series (o1, o3), gpt-5 series
+    const usesNewParameters = /^openai\/(o1|o3|gpt-5)/i.test(this.model);
+
+    const requestParams = {
       model: this.model,
-      max_tokens: maxTokens,
-      temperature,
       messages: [
         {
           role: 'user',
           content: prompt
         }
       ]
-    });
+    };
 
-    return {
-      content: response.choices[0].message.content,
-      model: this.model,
-      provider: 'openrouter',
-      usage: {
-        promptTokens: response.usage?.prompt_tokens || 0,
-        completionTokens: response.usage?.completion_tokens || 0,
-        totalTokens: response.usage?.total_tokens || 0
+    // Newer models use different parameter names
+    if (usesNewParameters) {
+      requestParams.max_completion_tokens = maxTokens;
+      // Newer reasoning models don't support temperature parameter
+    } else {
+      requestParams.max_tokens = maxTokens;
+      requestParams.temperature = temperature;
+    }
+
+    try {
+      const response = await this.client.chat.completions.create(requestParams);
+
+      // Validate response structure
+      if (!response.choices || response.choices.length === 0) {
+        throw new Error(`OpenRouter model '${this.model}' returned no choices. The model may not exist or be unavailable.`);
       }
-    };
+
+      if (!response.choices[0].message) {
+        throw new Error(`OpenRouter model '${this.model}' returned invalid response structure.`);
+      }
+
+      const content = response.choices[0].message.content;
+
+      if (!content || content.trim().length === 0) {
+        throw new Error(`OpenRouter model '${this.model}' returned empty content. The model may not support this request format.`);
+      }
+
+      return {
+        content,
+        model: this.model,
+        provider: 'openrouter',
+        usage: {
+          promptTokens: response.usage?.prompt_tokens || 0,
+          completionTokens: response.usage?.completion_tokens || 0,
+          totalTokens: response.usage?.total_tokens || 0
+        }
+      };
+    } catch (error) {
+      // If we get a 400 error about max_tokens not being supported,
+      // automatically retry with max_completion_tokens
+      if (error.status === 400 && error.message.includes('max_tokens')) {
+        const retryParams = {
+          model: this.model,
+          messages: requestParams.messages,
+          max_completion_tokens: maxTokens
+          // Don't include temperature for new parameter format models
+        };
+
+        const response = await this.client.chat.completions.create(retryParams);
+
+        return {
+          content: response.choices[0].message.content,
+          model: this.model,
+          provider: 'openrouter',
+          usage: {
+            promptTokens: response.usage?.prompt_tokens || 0,
+            completionTokens: response.usage?.completion_tokens || 0,
+            totalTokens: response.usage?.total_tokens || 0
+          }
+        };
+      }
+
+      // Re-throw other errors
+      throw error;
+    }
   }
 
   /**
@@ -211,21 +320,29 @@ class AIClient {
   async test() {
     const testPrompt = 'Respond with exactly: "Connection successful"';
 
-    const response = await this.sendMessage(testPrompt, {
-      maxTokens: 50,
-      temperature: 0
-    });
+    try {
+      const response = await this.sendMessage(testPrompt, {
+        maxTokens: 50,
+        temperature: 0
+      });
 
-    if (!response.content) {
-      throw new Error('No response from AI provider');
-    }
+      if (!response.content) {
+        throw new Error(`Model '${this.model}' on ${this.provider} returned no content. The model may not exist or be unavailable.`);
+      }
 
-    return {
-      success: true,
-      provider: this.provider,
-      model: this.model,
-      response: response.content
-    };
+      return {
+        success: true,
+        provider: this.provider,
+        model: this.model,
+        response: response.content
+      };
+    } catch (error) {
+      // Add context to the error message
+      if (error.message.includes('returned no content') || error.message.includes('returned no choices')) {
+        throw error; // Already has good context
+      }
+      throw new Error(`Test failed for ${this.provider} model '${this.model}': ${error.message}`);
+    }
   }
 
   /**