wiggum-cli 0.2.2 → 0.2.5

package/src/ai/enhancer.ts

@@ -3,64 +3,61 @@
  * Uses AI to analyze the codebase for deeper insights
  */
 
-import { generateText } from 'ai';
+import { generateText, stepCountIs } from 'ai';
 import type { ScanResult, DetectedStack, DetectionResult } from '../scanner/types.js';
-import { getModel, type AIProvider, hasApiKey, getApiKeyEnvVar } from './providers.js';
-import { SYSTEM_PROMPT, createAnalysisPrompt } from './prompts.js';
+import { getModel, type AIProvider, hasApiKey, getApiKeyEnvVar, isReasoningModel } from './providers.js';
+import { SYSTEM_PROMPT, SYSTEM_PROMPT_AGENTIC, createAnalysisPrompt } from './prompts.js';
+import { createExplorationTools } from './tools.js';
 import { logger } from '../utils/logger.js';
 
 /**
- * Framework insights from AI analysis
+ * Project context from AI analysis - key structure information
  */
-export interface FrameworkInsights {
-  variant?: string;
-  confidence: 'high' | 'medium' | 'low';
-  notes?: string;
+export interface ProjectContext {
+  /** Key entry point files */
+  entryPoints?: string[];
+  /** Important directories and their purposes */
+  keyDirectories?: Record<string, string>;
+  /** Naming conventions used in the project */
+  namingConventions?: string;
 }
 
 /**
- * Architectural pattern detected by AI
+ * Detected commands from package.json scripts or common patterns
  */
-export interface ArchitecturalPattern {
-  pattern: string;
-  confidence: 'high' | 'medium' | 'low';
-  evidence: string;
+export interface DetectedCommands {
+  test?: string;
+  lint?: string;
+  typecheck?: string;
+  build?: string;
+  dev?: string;
+  format?: string;
 }
 
 /**
- * Coding convention detected by AI
+ * MCP server recommendations (categorized)
  */
-export interface CodingConvention {
-  convention: string;
-  suggestion: string;
+export interface McpRecommendations {
+  /** Essential MCP servers for this stack */
+  essential?: string[];
+  /** Recommended but optional MCP servers */
+  recommended?: string[];
 }
 
 /**
- * MCP server recommendation
- */
-export interface McpRecommendation {
-  name: string;
-  reason: string;
-}
-
-/**
- * Additional detection suggestions
- */
-export interface AdditionalDetections {
-  possibleMissed?: string[];
-  refinements?: string[];
-}
-
-/**
- * AI analysis result
+ * AI analysis result - focused on actionable outputs
  */
 export interface AIAnalysisResult {
-  frameworkInsights?: FrameworkInsights;
-  architecturalPatterns?: ArchitecturalPattern[];
-  codingConventions?: CodingConvention[];
-  recommendedMcpServers?: McpRecommendation[];
-  customPromptSuggestions?: string[];
-  additionalDetections?: AdditionalDetections;
+  /** Project structure and context */
+  projectContext?: ProjectContext;
+  /** Detected commands from package.json */
+  commands?: DetectedCommands;
+  /** Short, actionable implementation guidelines */
+  implementationGuidelines?: string[];
+  /** MCP server recommendations */
+  mcpServers?: McpRecommendations;
+  /** Additional technologies that may have been missed */
+  possibleMissedTechnologies?: string[];
 }
 
 /**
@@ -80,6 +77,8 @@ export interface EnhancerOptions {
   provider?: AIProvider;
   model?: string;
   verbose?: boolean;
+  /** Use agentic mode with tools for deeper codebase exploration */
+  agentic?: boolean;
 }
 
 /**
@@ -119,37 +118,24 @@ function applyEnhancements(
 ): DetectedStack {
   const enhanced = { ...stack };
 
-  // Enhance framework detection with AI insights
-  if (analysis.frameworkInsights && enhanced.framework) {
-    // If AI detected a more specific variant with high confidence
-    if (
-      analysis.frameworkInsights.variant &&
-      analysis.frameworkInsights.confidence === 'high'
-    ) {
-      enhanced.framework = {
-        ...enhanced.framework,
-        variant: analysis.frameworkInsights.variant,
-        evidence: [
-          ...enhanced.framework.evidence,
-          `AI: ${analysis.frameworkInsights.notes || 'variant detected'}`,
+  // Enhance MCP recommendations from AI analysis
+  if (analysis.mcpServers) {
+    const aiRecommended = [
+      ...(analysis.mcpServers.essential || []),
+      ...(analysis.mcpServers.recommended || []),
+    ];
+
+    if (aiRecommended.length > 0) {
+      enhanced.mcp = {
+        ...enhanced.mcp,
+        recommended: [
+          ...(enhanced.mcp?.recommended || []),
+          ...aiRecommended.filter(r => !enhanced.mcp?.recommended?.includes(r)),
         ],
       };
     }
   }
 
-  // Enhance MCP recommendations
-  if (analysis.recommendedMcpServers && analysis.recommendedMcpServers.length > 0) {
-    const aiRecommended = analysis.recommendedMcpServers.map(r => r.name);
-
-    enhanced.mcp = {
-      ...enhanced.mcp,
-      recommended: [
-        ...(enhanced.mcp?.recommended || []),
-        ...aiRecommended.filter(r => !enhanced.mcp?.recommended?.includes(r)),
-      ],
-    };
-  }
-
   return enhanced;
 }
 
@@ -161,11 +147,13 @@ export class AIEnhancer {
   private provider: AIProvider;
   private model?: string;
   private verbose: boolean;
+  private agentic: boolean;
 
   constructor(options: EnhancerOptions = {}) {
     this.provider = options.provider || 'anthropic';
     this.model = options.model;
     this.verbose = options.verbose || false;
+    this.agentic = options.agentic || false;
   }
 
   /**
@@ -202,22 +190,20 @@ export class AIEnhancer {
 
       if (this.verbose) {
         logger.info(`Using AI provider: ${provider} (${modelId})`);
+        if (this.agentic) {
+          logger.info('Agentic mode enabled - AI will explore the codebase with tools');
+        }
       }
 
-      // Create the analysis prompt
-      const prompt = createAnalysisPrompt(scanResult);
-
-      // Call the AI model
-      const { text } = await generateText({
-        model,
-        system: SYSTEM_PROMPT,
-        prompt,
-        maxOutputTokens: 2000,
-        temperature: 0.3, // Lower temperature for more consistent output
-      });
+      let analysis: AIAnalysisResult | null;
 
-      // Parse the response
-      const analysis = parseAIResponse(text);
+      if (this.agentic) {
+        // Agentic mode: use tools to explore codebase
+        analysis = await this.enhanceAgentic(model, modelId, scanResult);
+      } else {
+        // Simple mode: just analyze detected stack
+        analysis = await this.enhanceSimple(model, modelId, scanResult);
+      }
 
       if (!analysis) {
         return {
@@ -250,6 +236,84 @@ export class AIEnhancer {
       };
     }
   }
+
+  /**
+   * Simple enhancement mode - analyze detected stack without tools
+   */
+  private async enhanceSimple(
+    model: ReturnType<typeof getModel>['model'],
+    modelId: string,
+    scanResult: ScanResult
+  ): Promise<AIAnalysisResult | null> {
+    const prompt = createAnalysisPrompt(scanResult);
+
+    const { text } = await generateText({
+      model,
+      system: SYSTEM_PROMPT,
+      prompt,
+      maxOutputTokens: 2000,
+      // Reasoning models don't support temperature
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+    });
+
+    return parseAIResponse(text);
+  }
+
+  /**
+   * Agentic enhancement mode - use tools to explore codebase
+   */
+  private async enhanceAgentic(
+    model: ReturnType<typeof getModel>['model'],
+    modelId: string,
+    scanResult: ScanResult
+  ): Promise<AIAnalysisResult | null> {
+    const tools = createExplorationTools(scanResult.projectRoot);
+
+    const prompt = `Analyze this codebase and produce configuration for AI-assisted development.
+
+Project: ${scanResult.projectRoot}
+
+Start by exploring the codebase structure, then produce your analysis.
+When done exploring, output your final analysis as valid JSON matching this structure:
+
+{
+  "projectContext": {
+    "entryPoints": ["src/index.ts"],
+    "keyDirectories": {"src/routes": "API routes"},
+    "namingConventions": "camelCase files, PascalCase components"
+  },
+  "commands": {
+    "test": "npm test",
+    "lint": "npm run lint",
+    "build": "npm run build",
+    "dev": "npm run dev"
+  },
+  "implementationGuidelines": [
+    "Run npm test after changes",
+    "Use Zod for validation"
+  ],
+  "mcpServers": {
+    "essential": ["filesystem", "git"],
+    "recommended": ["docker"]
+  },
+  "possibleMissedTechnologies": ["Redis"]
+}`;
+
+    // Use agentic loop - AI will call tools until it has enough info
+    // stopWhen: stepCountIs(10) allows up to 10 tool-calling steps
+    const { text } = await generateText({
+      model,
+      system: SYSTEM_PROMPT_AGENTIC,
+      prompt,
+      tools,
+      stopWhen: stepCountIs(10),
+      maxOutputTokens: 4000,
+      // Reasoning models don't support temperature
+      ...(isReasoningModel(modelId) ? {} : { temperature: 0.3 }),
+    });
+
+    return parseAIResponse(text);
+  }
 }
 
 /**
@@ -269,85 +333,73 @@ export async function enhanceWithAI(
 export function formatAIAnalysis(analysis: AIAnalysisResult): string {
   const lines: string[] = [];
 
-  lines.push('=== AI Analysis ===');
-  lines.push('');
+  // Project context
+  if (analysis.projectContext) {
+    const ctx = analysis.projectContext;
 
-  // Framework insights
-  if (analysis.frameworkInsights) {
-    lines.push('Framework Insights:');
-    if (analysis.frameworkInsights.variant) {
-      lines.push(`  Variant: ${analysis.frameworkInsights.variant}`);
-    }
-    lines.push(`  Confidence: ${analysis.frameworkInsights.confidence}`);
-    if (analysis.frameworkInsights.notes) {
-      lines.push(`  Notes: ${analysis.frameworkInsights.notes}`);
+    if (ctx.entryPoints && ctx.entryPoints.length > 0) {
+      lines.push('Entry Points:');
+      for (const entry of ctx.entryPoints) {
+        lines.push(`  ${entry}`);
+      }
+      lines.push('');
     }
-    lines.push('');
-  }
 
-  // Architectural patterns
-  if (analysis.architecturalPatterns && analysis.architecturalPatterns.length > 0) {
-    lines.push('Architectural Patterns:');
-    for (const pattern of analysis.architecturalPatterns) {
-      lines.push(`  - ${pattern.pattern} [${pattern.confidence}]`);
-      lines.push(`    Evidence: ${pattern.evidence}`);
+    if (ctx.keyDirectories && Object.keys(ctx.keyDirectories).length > 0) {
+      lines.push('Key Directories:');
+      for (const [dir, purpose] of Object.entries(ctx.keyDirectories)) {
+        lines.push(`  ${dir} → ${purpose}`);
+      }
+      lines.push('');
     }
-    lines.push('');
-  }
 
-  // Coding conventions
-  if (analysis.codingConventions && analysis.codingConventions.length > 0) {
-    lines.push('Coding Conventions:');
-    for (const convention of analysis.codingConventions) {
-      lines.push(`  - ${convention.convention}`);
-      lines.push(`    Suggestion: ${convention.suggestion}`);
+    if (ctx.namingConventions) {
+      lines.push(`Naming: ${ctx.namingConventions}`);
+      lines.push('');
     }
-    lines.push('');
   }
 
-  // MCP recommendations
-  if (analysis.recommendedMcpServers && analysis.recommendedMcpServers.length > 0) {
-    lines.push('Recommended MCP Servers:');
-    for (const server of analysis.recommendedMcpServers) {
-      lines.push(`  - ${server.name}`);
-      lines.push(`    Reason: ${server.reason}`);
+  // Detected commands
+  if (analysis.commands) {
+    const cmds = analysis.commands;
+    const cmdList = Object.entries(cmds).filter(([_, v]) => v);
+
+    if (cmdList.length > 0) {
+      lines.push('Commands:');
+      for (const [name, cmd] of cmdList) {
+        lines.push(`  ${name}: ${cmd}`);
+      }
+      lines.push('');
     }
-    lines.push('');
   }
 
-  // Custom prompt suggestions
-  if (analysis.customPromptSuggestions && analysis.customPromptSuggestions.length > 0) {
-    lines.push('Custom Prompt Suggestions:');
-    for (const suggestion of analysis.customPromptSuggestions) {
-      lines.push(`  - ${suggestion}`);
+  // Implementation guidelines (the most important part)
+  if (analysis.implementationGuidelines && analysis.implementationGuidelines.length > 0) {
+    lines.push('Implementation Guidelines:');
+    for (const guideline of analysis.implementationGuidelines) {
+      lines.push(`  • ${guideline}`);
     }
     lines.push('');
   }
 
-  // Additional detections
-  if (analysis.additionalDetections) {
-    if (
-      analysis.additionalDetections.possibleMissed &&
-      analysis.additionalDetections.possibleMissed.length > 0
-    ) {
-      lines.push('Possibly Missed Technologies:');
-      for (const tech of analysis.additionalDetections.possibleMissed) {
-        lines.push(`  - ${tech}`);
-      }
-      lines.push('');
+  // MCP servers
+  if (analysis.mcpServers) {
+    if (analysis.mcpServers.essential && analysis.mcpServers.essential.length > 0) {
+      lines.push(`MCP (essential): ${analysis.mcpServers.essential.join(', ')}`);
     }
-
-    if (
-      analysis.additionalDetections.refinements &&
-      analysis.additionalDetections.refinements.length > 0
-    ) {
-      lines.push('Detection Refinements:');
-      for (const refinement of analysis.additionalDetections.refinements) {
-        lines.push(`  - ${refinement}`);
-      }
+    if (analysis.mcpServers.recommended && analysis.mcpServers.recommended.length > 0) {
+      lines.push(`MCP (optional): ${analysis.mcpServers.recommended.join(', ')}`);
+    }
+    if (analysis.mcpServers.essential?.length || analysis.mcpServers.recommended?.length) {
       lines.push('');
     }
   }
 
+  // Possibly missed technologies (brief)
+  if (analysis.possibleMissedTechnologies && analysis.possibleMissedTechnologies.length > 0) {
+    lines.push(`May also use: ${analysis.possibleMissedTechnologies.join(', ')}`);
+    lines.push('');
+  }
+
   return lines.join('\n');
 }

package/src/ai/index.ts

@@ -17,18 +17,23 @@ export {
 export {
   formatStackForPrompt,
   SYSTEM_PROMPT,
+  SYSTEM_PROMPT_AGENTIC,
   createAnalysisPrompt,
   createValidationPrompt,
   createRecommendationsPrompt,
 } from './prompts.js';
 
+// Tools for agentic exploration
+export {
+  createExplorationTools,
+  RIPGREP_SKILL,
+} from './tools.js';
+
 // AI enhancer
 export {
-  type FrameworkInsights,
-  type ArchitecturalPattern,
-  type CodingConvention,
-  type McpRecommendation,
-  type AdditionalDetections,
+  type ProjectContext,
+  type DetectedCommands,
+  type McpRecommendations,
   type AIAnalysisResult,
   type EnhancedScanResult,
   type EnhancerOptions,

package/src/ai/prompts.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ScanResult, DetectedStack } from '../scanner/types.js';
+import { RIPGREP_SKILL } from './tools.js';
 
 /**
  * Format the detected stack for inclusion in prompts
@@ -87,20 +88,52 @@ export function formatStackForPrompt(stack: DetectedStack): string {
 }
 
 /**
- * System prompt for codebase analysis
+ * System prompt for codebase analysis (agentic mode)
  */
-export const SYSTEM_PROMPT = `You are an expert software architect analyzing a codebase to provide insights for AI-assisted development.
+export const SYSTEM_PROMPT_AGENTIC = `You are an expert codebase analyst with tools to explore the project.
 
-Your role is to:
-1. Analyze the detected tech stack and provide deeper insights
-2. Identify architectural patterns and coding conventions
-3. Suggest improvements to the detection results
-4. Recommend MCP servers that would benefit this project
-5. Generate custom prompt suggestions for AI coding assistants
+Your goal is to thoroughly understand the codebase structure and produce actionable configuration for AI-assisted development.
 
-Be concise and actionable. Focus on practical insights that help developers work more effectively with AI tools.
+## Exploration Strategy
+1. First, list the root directory to understand project structure
+2. Read package.json to understand scripts and dependencies
+3. Search for key patterns: entry points, routes, components, tests
+4. Identify naming conventions by examining existing files
+5. Look for existing documentation (.md files, README)
 
-Respond in valid JSON format only.`;
+## Tools Available
+You have these tools to explore the codebase:
+- searchCode: Search using ripgrep patterns
+- readFile: Read file contents
+- listDirectory: List directory structure
+- getPackageInfo: Get package.json info
+
+${RIPGREP_SKILL}
+
+## Output Requirements
+After exploration, output valid JSON with:
+- projectContext: entry points, key directories, naming conventions
+- commands: test, lint, build, dev commands from package.json
+- implementationGuidelines: short actionable rules (5-10 words each, max 7)
+- mcpServers: essential and recommended servers
+- possibleMissedTechnologies: technologies that might be in use
+
+Be concise. Focus on WHAT TO DO, not what exists.`;
+
+/**
+ * System prompt for codebase analysis (simple mode - no tools)
+ */
+export const SYSTEM_PROMPT = `You are analyzing a codebase to help configure AI-assisted development tools.
+
+Your goal is to produce SHORT, ACTIONABLE output that helps AI coding assistants work effectively on this codebase.
+
+Rules:
+- Output valid JSON only
+- Be extremely concise (5-10 words per item max)
+- Focus on WHAT TO DO, not what exists
+- Include specific file paths and commands
+- Max 5-7 items per array
+- No explanations, just actionable rules`;
 
 /**
  * Create the codebase analysis prompt
@@ -108,49 +141,48 @@ Respond in valid JSON format only.`;
 export function createAnalysisPrompt(scanResult: ScanResult): string {
   const stackInfo = formatStackForPrompt(scanResult.stack);
 
-  return `Analyze this codebase and provide enhanced insights.
+  return `Analyze this codebase for AI-assisted development configuration.
 
-Project Root: ${scanResult.projectRoot}
+Project: ${scanResult.projectRoot}
 
 Detected Stack:
 ${stackInfo || 'No technologies detected'}
 
-Based on this stack, provide analysis in the following JSON format:
+Respond with this JSON structure (keep values SHORT - 5-10 words max per item):
 {
-  "frameworkInsights": {
-    "variant": "more specific variant if detectable (e.g., 'app-router', 'pages-router', 'spa', 'ssr')",
-    "confidence": "high/medium/low",
-    "notes": "any additional observations about framework usage"
+  "projectContext": {
+    "entryPoints": ["src/index.ts", "src/server.ts"],
+    "keyDirectories": {
+      "src/routes": "API route handlers",
+      "src/models": "Database models"
+    },
+    "namingConventions": "camelCase files, PascalCase components"
   },
-  "architecturalPatterns": [
-    {
-      "pattern": "pattern name",
-      "confidence": "high/medium/low",
-      "evidence": "why you think this pattern is used"
-    }
-  ],
-  "codingConventions": [
-    {
-      "convention": "convention name",
-      "suggestion": "how to follow this convention"
-    }
-  ],
-  "recommendedMcpServers": [
-    {
-      "name": "server name",
-      "reason": "why this would be useful"
-    }
-  ],
-  "customPromptSuggestions": [
-    "Specific prompt suggestions tailored to this codebase"
+  "commands": {
+    "test": "npm test",
+    "lint": "npm run lint",
+    "typecheck": "npm run typecheck",
+    "build": "npm run build",
+    "dev": "npm run dev"
+  },
+  "implementationGuidelines": [
+    "Run npm test after every change",
+    "Use Zod for request validation",
+    "Place routes in src/routes/<resource>.ts",
+    "Follow error pattern in src/utils/errors.ts"
   ],
-  "additionalDetections": {
-    "possibleMissed": ["technologies that might be in use but weren't detected"],
-    "refinements": ["suggestions to improve existing detections"]
-  }
+  "mcpServers": {
+    "essential": ["filesystem", "git"],
+    "recommended": ["docker", "postgres"]
+  },
+  "possibleMissedTechnologies": ["Redis", "WebSockets"]
 }
 
-Only include sections where you have meaningful insights. Keep responses focused and actionable.`;
+Important:
+- implementationGuidelines should be short rules (not analysis prompts)
+- Include actual file paths from this project
+- Infer commands from package.json patterns
+- Max 5-7 items per array`;
 }
 
 /**

package/src/ai/providers.ts

@@ -166,3 +166,21 @@ export function getAvailableProvider(): AIProvider | null {
 export function getApiKeyEnvVar(provider: AIProvider): string {
   return API_KEY_ENV_VARS[provider];
 }
+
+/**
+ * Models that don't support temperature parameter (reasoning models)
+ */
+const REASONING_MODELS = [
+  // OpenAI reasoning models
+  'o1', 'o1-mini', 'o1-preview',
+  'o3', 'o3-mini',
+  'gpt-5', 'gpt-5.1', 'gpt-5-mini',
+  'gpt-5.1-codex', 'gpt-5.1-codex-max',
+];
+
+/**
+ * Check if a model is a reasoning model that doesn't support temperature
+ */
+export function isReasoningModel(modelId: string): boolean {
+  return REASONING_MODELS.some(m => modelId.startsWith(m));
+}