mcp-adr-analysis-server 1.1.0 → 2.0.2

package/dist/src/index.js

@@ -23,7 +23,7 @@ const SERVER_INFO = {
 /**
  * Main server class
  */
-class McpAdrAnalysisServer {
+export class McpAdrAnalysisServer {
     server;
     maskingConfig;
     config;
@@ -75,7 +75,7 @@ class McpAdrAnalysisServer {
                 tools: [
                     {
                         name: 'analyze_project_ecosystem',
-                        description: 'Analyze the project ecosystem including technology stack, patterns, and architecture',
+                        description: 'Comprehensive recursive project ecosystem analysis with advanced prompting techniques (Knowledge Generation + Reflexion)',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -87,6 +87,48 @@ class McpAdrAnalysisServer {
                                     type: 'array',
                                     items: { type: 'string' },
                                     description: 'File patterns to include in analysis'
+                                },
+                                enhancedMode: {
+                                    type: 'boolean',
+                                    description: 'Enable advanced prompting features (Knowledge Generation + Reflexion)',
+                                    default: true
+                                },
+                                knowledgeEnhancement: {
+                                    type: 'boolean',
+                                    description: 'Enable Knowledge Generation for technology-specific insights',
+                                    default: true
+                                },
+                                learningEnabled: {
+                                    type: 'boolean',
+                                    description: 'Enable Reflexion learning from past analysis outcomes',
+                                    default: true
+                                },
+                                technologyFocus: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Specific technologies to focus analysis on (auto-detected if not provided)'
+                                },
+                                analysisDepth: {
+                                    type: 'string',
+                                    enum: ['basic', 'detailed', 'comprehensive'],
+                                    description: 'Depth of ecosystem analysis',
+                                    default: 'comprehensive'
+                                },
+                                includeEnvironment: {
+                                    type: 'boolean',
+                                    description: 'Automatically include comprehensive environment analysis (default: true)',
+                                    default: true
+                                },
+                                recursiveDepth: {
+                                    type: 'string',
+                                    description: 'Depth of recursive project analysis',
+                                    enum: ['shallow', 'moderate', 'deep', 'comprehensive'],
+                                    default: 'comprehensive'
+                                },
+                                analysisScope: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Specific analysis areas to focus on (e.g., ["security", "performance", "architecture", "dependencies"])'
                                 }
                             },
                             required: []
@@ -94,7 +136,7 @@ class McpAdrAnalysisServer {
                     },
                     {
                         name: 'get_architectural_context',
-                        description: 'Get detailed architectural context for specific files or the entire project',
+                        description: 'Get detailed architectural context for specific files or the entire project, automatically sets up ADR infrastructure if missing, and provides outcome-focused workflow for project success',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -112,7 +154,7 @@ class McpAdrAnalysisServer {
                     },
                     {
                         name: 'generate_adrs_from_prd',
-                        description: 'Generate Architectural Decision Records from a Product Requirements Document',
+                        description: 'Generate Architectural Decision Records from a Product Requirements Document with advanced prompting techniques (APE + Knowledge Generation)',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -123,6 +165,27 @@ class McpAdrAnalysisServer {
                                 outputDirectory: {
                                     type: 'string',
                                     description: 'Directory to output generated ADRs (optional, uses configured ADR_DIRECTORY if not provided)'
+                                },
+                                enhancedMode: {
+                                    type: 'boolean',
+                                    description: 'Enable advanced prompting features (APE + Knowledge Generation)',
+                                    default: true
+                                },
+                                promptOptimization: {
+                                    type: 'boolean',
+                                    description: 'Enable Automatic Prompt Engineering for optimized ADR generation',
+                                    default: true
+                                },
+                                knowledgeEnhancement: {
+                                    type: 'boolean',
+                                    description: 'Enable Knowledge Generation for domain-specific insights',
+                                    default: true
+                                },
+                                prdType: {
+                                    type: 'string',
+                                    enum: ['web-application', 'mobile-app', 'microservices', 'data-platform', 'api-service', 'general'],
+                                    description: 'Type of PRD for optimized knowledge generation',
+                                    default: 'general'
                                 }
                             },
                             required: ['prdPath']
@@ -130,7 +193,7 @@ class McpAdrAnalysisServer {
                     },
                     {
                         name: 'generate_adr_todo',
-                        description: 'Generate or update todo.md from existing ADRs',
+                        description: 'Generate TDD-focused todo.md from existing ADRs with two-phase approach: test generation and production code',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -143,6 +206,83 @@ class McpAdrAnalysisServer {
                                     enum: ['all', 'pending', 'in_progress'],
                                     description: 'Scope of tasks to include',
                                     default: 'all'
+                                },
+                                phase: {
+                                    type: 'string',
+                                    enum: ['both', 'test', 'production'],
+                                    description: 'TDD phase: both (default), test (mock test generation), production (implementation after tests)',
+                                    default: 'both'
+                                },
+                                linkAdrs: {
+                                    type: 'boolean',
+                                    description: 'Link all ADRs to create comprehensive system test coverage',
+                                    default: true
+                                },
+                                includeRules: {
+                                    type: 'boolean',
+                                    description: 'Include architectural rules validation in TDD tasks',
+                                    default: true
+                                },
+                                ruleSource: {
+                                    type: 'string',
+                                    enum: ['adrs', 'patterns', 'both'],
+                                    description: 'Source for architectural rules (only used if includeRules is true)',
+                                    default: 'both'
+                                }
+                            }
+                        }
+                    },
+                    {
+                        name: 'compare_adr_progress',
+                        description: 'Compare TODO.md progress against ADRs and current environment to validate implementation status',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                todoPath: {
+                                    type: 'string',
+                                    description: 'Path to TODO.md file to analyze',
+                                    default: 'TODO.md'
+                                },
+                                adrDirectory: {
+                                    type: 'string',
+                                    description: 'Directory containing ADR files',
+                                    default: 'docs/adrs'
+                                },
+                                projectPath: {
+                                    type: 'string',
+                                    description: 'Path to project root for environment analysis',
+                                    default: '.'
+                                },
+                                validationType: {
+                                    type: 'string',
+                                    enum: ['full', 'todo-only', 'adr-only', 'environment-only'],
+                                    description: 'Type of validation to perform',
+                                    default: 'full'
+                                },
+                                includeFileChecks: {
+                                    type: 'boolean',
+                                    description: 'Include file existence and implementation checks',
+                                    default: true
+                                },
+                                includeRuleValidation: {
+                                    type: 'boolean',
+                                    description: 'Include architectural rule compliance validation',
+                                    default: true
+                                },
+                                deepCodeAnalysis: {
+                                    type: 'boolean',
+                                    description: 'Perform deep code analysis to distinguish mock from production implementations',
+                                    default: true
+                                },
+                                functionalValidation: {
+                                    type: 'boolean',
+                                    description: 'Validate that code actually functions according to ADR goals, not just exists',
+                                    default: true
+                                },
+                                strictMode: {
+                                    type: 'boolean',
+                                    description: 'Enable strict validation mode with reality-check mechanisms against overconfident assessments',
+                                    default: true
                                 }
                             }
                         }
@@ -313,7 +453,7 @@ class McpAdrAnalysisServer {
                     },
                     {
                         name: 'suggest_adrs',
-                        description: 'Suggest ADRs based on project analysis and implicit decisions',
+                        description: 'Suggest architectural decisions with advanced prompting techniques (Knowledge Generation + Reflexion)',
                         inputSchema: {
                             type: 'object',
                             properties: {
@@ -349,6 +489,21 @@ class McpAdrAnalysisServer {
                                     type: 'array',
                                     items: { type: 'string' },
                                     description: 'List of existing ADR titles to avoid duplication'
+                                },
+                                enhancedMode: {
+                                    type: 'boolean',
+                                    description: 'Enable advanced prompting features (Knowledge Generation + Reflexion)',
+                                    default: true
+                                },
+                                learningEnabled: {
+                                    type: 'boolean',
+                                    description: 'Enable Reflexion learning from past experiences',
+                                    default: true
+                                },
+                                knowledgeEnhancement: {
+                                    type: 'boolean',
+                                    description: 'Enable Knowledge Generation for domain-specific insights',
+                                    default: true
                                 }
                             }
                         }
@@ -889,6 +1044,100 @@ class McpAdrAnalysisServer {
                                 }
                             }
                         }
+                    },
+                    {
+                        name: 'check_ai_execution_status',
+                        description: 'Check AI execution configuration and status for debugging prompt-only mode issues',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {},
+                            required: []
+                        }
+                    },
+                    {
+                        name: 'get_workflow_guidance',
+                        description: 'Get intelligent workflow guidance and tool recommendations based on your goals and project context to achieve expected outcomes efficiently',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                goal: {
+                                    type: 'string',
+                                    description: 'What you want to accomplish (e.g., "analyze new project", "document existing decisions", "security audit", "modernize legacy system")'
+                                },
+                                projectContext: {
+                                    type: 'string',
+                                    description: 'Current state of your project (e.g., "new project", "existing project with ADRs", "legacy codebase", "greenfield development")',
+                                    enum: ['new_project', 'existing_with_adrs', 'existing_without_adrs', 'legacy_codebase', 'greenfield', 'maintenance_mode', 'unknown']
+                                },
+                                availableAssets: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'What assets you already have (e.g., ["PRD.md", "existing ADRs", "codebase", "documentation", "test suite"])'
+                                },
+                                timeframe: {
+                                    type: 'string',
+                                    description: 'Available time/effort level',
+                                    enum: ['quick_analysis', 'thorough_review', 'comprehensive_audit', 'ongoing_process']
+                                },
+                                primaryConcerns: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Main areas of concern (e.g., ["security", "performance", "maintainability", "scalability", "compliance"])'
+                                }
+                            },
+                            required: ['goal', 'projectContext']
+                        }
+                    },
+                    {
+                        name: 'get_development_guidance',
+                        description: 'Get comprehensive development guidance that translates architectural decisions and workflow recommendations into specific coding tasks, implementation patterns, and development roadmap',
+                        inputSchema: {
+                            type: 'object',
+                            properties: {
+                                developmentPhase: {
+                                    type: 'string',
+                                    description: 'Current development phase',
+                                    enum: ['planning', 'setup', 'implementation', 'testing', 'deployment', 'maintenance', 'refactoring']
+                                },
+                                adrsToImplement: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'List of ADR titles or file paths that need to be implemented in code'
+                                },
+                                technologyStack: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Current technology stack (e.g., ["TypeScript", "React", "Node.js", "PostgreSQL", "Docker"])'
+                                },
+                                currentProgress: {
+                                    type: 'string',
+                                    description: 'What has already been implemented or current state of development'
+                                },
+                                teamContext: {
+                                    type: 'object',
+                                    properties: {
+                                        size: {
+                                            type: 'string',
+                                            enum: ['solo', 'small_team', 'medium_team', 'large_team']
+                                        },
+                                        experienceLevel: {
+                                            type: 'string',
+                                            enum: ['junior', 'mixed', 'senior', 'expert']
+                                        }
+                                    }
+                                },
+                                timeline: {
+                                    type: 'string',
+                                    description: 'Development timeline or deadline constraints'
+                                },
+                                focusAreas: {
+                                    type: 'array',
+                                    items: { type: 'string' },
+                                    description: 'Specific areas to focus on (e.g., ["API design", "database schema", "testing strategy", "deployment pipeline"])'
+                                }
+                            },
+                            required: ['developmentPhase']
+                        }
                     }
                 ]
             };
@@ -911,6 +1160,9 @@ class McpAdrAnalysisServer {
                     case 'generate_adr_todo':
                         response = await this.generateAdrTodo(args);
                         break;
+                    case 'compare_adr_progress':
+                        response = await this.compareAdrProgress(args);
+                        break;
                     case 'analyze_content_security':
                         response = await this.analyzeContentSecurity(args);
                         break;
@@ -968,6 +1220,15 @@ class McpAdrAnalysisServer {
                     case 'analyze_deployment_progress':
                         response = await this.analyzeDeploymentProgress(args);
                         break;
+                    case 'check_ai_execution_status':
+                        response = await this.checkAIExecutionStatus(args);
+                        break;
+                    case 'get_workflow_guidance':
+                        response = await this.getWorkflowGuidance(args);
+                        break;
+                    case 'get_development_guidance':
+                        response = await this.getDevelopmentGuidance(args);
+                        break;
                     default:
                         throw new McpAdrError(`Unknown tool: ${name}`, 'UNKNOWN_TOOL');
                 }
@@ -1073,226 +1334,1983 @@ class McpAdrAnalysisServer {
     /**
      * Tool implementations
      */
-    async analyzeProjectEcosystem(args) {
-        // Use configured project path if not provided in args
-        const projectPath = args.projectPath || this.config.projectPath;
-        this.logger.info(`Analyzing project ecosystem at: ${projectPath}`);
+    async checkAIExecutionStatus(_args) {
         try {
-            // Import utilities dynamically to avoid circular dependencies
-            const { analyzeProjectStructure, readFileContent } = await import('./utils/file-system.js');
-            const { generateAnalysisContext, generateComprehensiveAnalysisPrompt } = await import('./prompts/analysis-prompts.js');
-            // Analyze project structure
-            const projectStructure = await analyzeProjectStructure(projectPath);
-            // Read key files for context
-            let packageJsonContent;
-            try {
-                packageJsonContent = await readFileContent(`${projectPath}/package.json`);
-            }
-            catch {
-                // package.json might not exist
-            }
-            // Generate analysis context
-            const analysisContext = generateAnalysisContext(projectStructure);
-            // Generate comprehensive analysis prompt
-            const analysisPrompt = generateComprehensiveAnalysisPrompt(analysisContext, packageJsonContent);
+            const { getAIExecutionStatus } = await import('./utils/prompt-execution.js');
+            const status = getAIExecutionStatus();
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Project ecosystem analysis for: ${projectPath}\n\nPlease analyze this project using the following prompt:\n\n${analysisPrompt}`
+                        text: `# AI Execution Status Diagnostic
+
+## Current Configuration
+- **AI Execution Enabled**: ${status.isEnabled ? '✅ YES' : '❌ NO'}
+- **Has API Key**: ${status.hasApiKey ? '✅ YES' : '❌ NO'}
+- **Execution Mode**: ${status.executionMode}
+- **AI Model**: ${status.model}
+
+${status.reason ? `## ⚠️ Issue Detected
+**Problem**: ${status.reason}
+
+## Solution
+${!status.hasApiKey ? `
+1. Get an OpenRouter API key from https://openrouter.ai/keys
+2. Add it to your MCP configuration:
+   \`\`\`json
+   {
+     "mcpServers": {
+       "adr-analysis": {
+         "command": "mcp-adr-analysis-server",
+         "env": {
+           "OPENROUTER_API_KEY": "your_api_key_here",
+           "EXECUTION_MODE": "full",
+           "AI_MODEL": "anthropic/claude-3-sonnet"
+         }
+       }
+     }
+   }
+   \`\`\`
+3. Restart your MCP client (Claude Desktop, etc.)
+` : status.executionMode !== 'full' ? `
+1. Update your MCP configuration to set EXECUTION_MODE to "full":
+   \`\`\`json
+   {
+     "mcpServers": {
+       "adr-analysis": {
+         "env": {
+           "EXECUTION_MODE": "full"
+         }
+       }
+     }
+   }
+   \`\`\`
+2. Restart your MCP client
+` : ''}` : `## ✅ Configuration Looks Good!
+
+AI execution is properly configured. Tools should return actual results instead of prompts.
+
+If you're still seeing prompts instead of results, try:
+1. Restart your MCP client
+2. Check your OpenRouter API key has sufficient credits
+3. Verify network connectivity to OpenRouter.ai`}
+
+## Environment Variables Expected
+- **OPENROUTER_API_KEY**: Your OpenRouter API key
+- **EXECUTION_MODE**: Set to "full" for AI execution
+- **AI_MODEL**: AI model to use (optional, defaults to claude-3-sonnet)
+
+## Testing
+After fixing the configuration, try calling \`suggest_adrs\` - it should return actual ADR suggestions instead of prompts.
+`
                     }
                 ]
             };
         }
         catch (error) {
-            throw new McpAdrError(`Failed to analyze project ecosystem: ${error instanceof Error ? error.message : String(error)}`, 'ANALYSIS_ERROR');
-        }
-    }
-    async getArchitecturalContext(args) {
-        const { filePath } = args;
-        try {
-            const { analyzeProjectStructure } = await import('./utils/file-system.js');
-            const { generateAnalysisContext, generatePatternDetectionPrompt } = await import('./prompts/analysis-prompts.js');
-            // Determine project path
-            const projectPath = filePath ? filePath.split('/').slice(0, -1).join('/') : process.cwd();
-            // Analyze project structure
-            const projectStructure = await analyzeProjectStructure(projectPath);
-            const analysisContext = generateAnalysisContext(projectStructure);
-            // Generate pattern detection prompt
-            const patternPrompt = generatePatternDetectionPrompt(analysisContext);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Architectural context analysis${filePath ? ` for: ${filePath}` : ''}\n\nPlease analyze architectural patterns using the following prompt:\n\n${patternPrompt}`
+                        text: `# AI Execution Status Check Failed
+
+**Error**: ${error instanceof Error ? error.message : String(error)}
+
+This diagnostic tool helps identify why tools return prompts instead of actual results.
+
+## Manual Check
+Verify these environment variables are set in your MCP configuration:
+- OPENROUTER_API_KEY
+- EXECUTION_MODE=full
+- AI_MODEL (optional)
+`
                     }
                 ]
             };
         }
-        catch (error) {
-            throw new McpAdrError(`Failed to get architectural context: ${error instanceof Error ? error.message : String(error)}`, 'ANALYSIS_ERROR');
-        }
     }
-    async generateAdrsFromPrd(args) {
-        const { prdPath } = args;
-        const outputDirectory = args.outputDirectory || this.config.adrDirectory;
-        this.logger.info(`Generating ADRs from PRD: ${prdPath} to ${outputDirectory}`);
+    async getWorkflowGuidance(args) {
+        const { goal, projectContext, availableAssets = [], timeframe = 'thorough_review', primaryConcerns = [] } = args;
         try {
-            const { readFileContent, fileExists } = await import('./utils/file-system.js');
-            // Check if PRD file exists
-            if (!(await fileExists(prdPath))) {
-                throw new McpAdrError(`PRD file not found: ${prdPath}`, 'FILE_NOT_FOUND');
-            }
-            // Read PRD content
-            const prdContent = await readFileContent(prdPath);
-            // Generate ADR creation prompt
-            const adrPrompt = `
-# ADR Generation from PRD Request
+            const workflowPrompt = `
+# Workflow Guidance & Tool Recommendation System
 
-Please analyze the following Product Requirements Document and generate Architectural Decision Records (ADRs).
+## User Context Analysis
+- **Goal**: ${goal}
+- **Project Context**: ${projectContext}
+- **Available Assets**: ${availableAssets.length > 0 ? availableAssets.join(', ') : 'None specified'}
+- **Timeframe**: ${timeframe}
+- **Primary Concerns**: ${primaryConcerns.length > 0 ? primaryConcerns.join(', ') : 'General analysis'}
 
-## PRD Content
-\`\`\`markdown
-${prdContent}
-\`\`\`
+## Available MCP Tools (24 Total)
 
-## Requirements
+### 🎯 **Core Analysis Tools** (AI-Powered ✅)
+1. **analyze_project_ecosystem** - Comprehensive technology and pattern detection
+2. **get_architectural_context** - Generate intelligent architectural insights + ADR setup
+3. **generate_adrs_from_prd** - Convert requirements to structured ADRs
+4. **analyze_content_security** - Detect sensitive information patterns
 
-1. **Extract Key Decisions**: Identify all architectural decisions implied or stated in the PRD
-2. **Generate ADRs**: Create individual ADR files for each significant decision
-3. **Follow ADR Format**: Use standard ADR template (title, status, context, decision, consequences)
-4. **Number Sequentially**: Use format 001-decision-title.md, 002-next-decision.md, etc.
-5. **Output Directory**: Place ADRs in ${outputDirectory}/
+### 📋 **ADR Management Tools** (AI-Powered ✅)
+5. **suggest_adrs** - Auto-suggest ADRs from implicit decisions
+6. **generate_adr_from_decision** - Create ADRs from specific decisions
+7. **discover_existing_adrs** - Intelligent ADR discovery and analysis
+8. **generate_adr_todo** - Create actionable task lists from ADRs
 
-## ADR Template Format
+### 🔍 **Research & Documentation Tools** (AI-Powered ✅)
+9. **generate_research_questions** - Create context-aware research questions
+10. **incorporate_research** - Integrate research findings into decisions
+11. **create_research_template** - Generate research documentation templates
 
-\`\`\`markdown
-# [Number]. [Title]
+### 🛡️ **Security & Compliance Tools** (AI-Powered ✅)
+12. **generate_content_masking** - Intelligent content masking and protection
+13. **configure_custom_patterns** - Customize security and masking settings
+14. **apply_basic_content_masking** - Basic content masking (fallback)
+15. **validate_content_masking** - Validate masking effectiveness
 
-**Status**: [Proposed/Accepted/Deprecated/Superseded]
-**Date**: [YYYY-MM-DD]
+### 🏗️ **Rule & Governance Tools** (AI-Powered ✅)
+16. **generate_rules** - Extract architectural rules from ADRs
+17. **validate_rules** - Validate code against architectural rules
+18. **create_rule_set** - Create comprehensive rule management systems
 
-## Context
-[Describe the context and problem statement]
+### 🚀 **Deployment & Environment Tools** (AI-Powered ✅)
+19. **analyze_environment** - Environment analysis and optimization
+20. **analyze_deployment_progress** - Deployment tracking and verification
 
-## Decision
-[Describe the architectural decision]
+### ⚙️ **Utility & Management Tools**
+21. **manage_cache** - Cache management and optimization
+22. **configure_output_masking** - Configure global output masking
+23. **request_action_confirmation** - Interactive user confirmation workflows
+24. **get_workflow_guidance** - This tool - intelligent workflow advisor
 
-## Consequences
-[Describe the positive and negative consequences]
+## Workflow Recommendation Instructions
 
-## Implementation Plan
-[Optional: Steps to implement this decision]
-\`\`\`
+Based on the user's goal, project context, available assets, timeframe, and concerns, provide:
 
-Please provide:
-1. List of identified architectural decisions
-2. Generated ADR content for each decision
-3. Recommended file names and structure
-4. Implementation priority order
+### 1. **Recommended Tool Sequence**
+Provide a step-by-step workflow with:
+- **Tool Name**: Exact tool to call
+- **Purpose**: Why this tool is needed
+- **Expected Outcome**: What it will deliver
+- **Parameters**: Suggested parameters for the tool call
+- **Success Criteria**: How to know it worked
+
+### 2. **Alternative Workflows**
+Provide 2-3 alternative approaches based on:
+- Different time constraints
+- Different priorities
+- Different starting points
+
+### 3. **Expected Timeline & Effort**
+For each recommended workflow:
+- **Estimated Time**: How long each step takes
+- **Effort Level**: Low/Medium/High effort required
+- **Dependencies**: Which steps must be completed first
+
+### 4. **Success Metrics**
+Define how to measure success:
+- **Immediate Indicators**: Quick wins and early signals
+- **Progress Milestones**: Key checkpoints
+- **Final Outcomes**: Ultimate success criteria
+
+### 5. **Common Pitfalls & Tips**
+- **What to Avoid**: Common mistakes in this workflow
+- **Pro Tips**: Best practices for maximum effectiveness
+- **Troubleshooting**: What to do if steps fail
+
+## Common Workflow Patterns
+
+### **New Project Setup**
+1. analyze_project_ecosystem → 2. get_architectural_context → 3. suggest_adrs → 4. generate_adr_from_decision
+
+### **Existing Project Analysis**
+1. discover_existing_adrs → 2. get_architectural_context → 3. generate_adr_todo → 4. validate_rules
+
+### **Security Audit**
+1. analyze_content_security → 2. generate_content_masking → 3. configure_custom_patterns → 4. validate_content_masking
+
+### **PRD to Implementation**
+1. generate_adrs_from_prd → 2. generate_adr_todo → 3. analyze_deployment_progress
+
+### **Legacy Modernization**
+1. analyze_project_ecosystem → 2. get_architectural_context → 3. suggest_adrs → 4. generate_rules → 5. validate_rules
+
+## Output Format
+
+Provide a comprehensive workflow guide that includes:
+
+1. **🎯 Recommended Primary Workflow** (step-by-step with tool calls)
+2. **🔄 Alternative Approaches** (2-3 different paths)
+3. **⏱️ Timeline & Effort Estimates** (realistic expectations)
+4. **📊 Success Metrics** (how to measure progress)
+5. **💡 Pro Tips & Best Practices** (maximize effectiveness)
+6. **⚠️ Common Pitfalls** (what to avoid)
+
+Make the guidance **actionable, specific, and outcome-focused** so the user can immediately start executing the recommended workflow.
 `;
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `ADR generation from PRD: ${prdPath}\n\nPlease generate ADRs using the following prompt:\n\n${adrPrompt}`
-                    }
-                ]
-            };
+            // Execute the workflow guidance with AI if enabled
+            const { executePromptWithFallback, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executePromptWithFallback(workflowPrompt, 'Analyze the user context and provide intelligent workflow guidance with specific tool recommendations.', {
+                temperature: 0.1,
+                maxTokens: 6000,
+                systemPrompt: `You are an expert workflow advisor for the MCP ADR Analysis Server.
+Your role is to analyze user goals and project context, then recommend the optimal sequence of tools to achieve their objectives efficiently.
+Provide specific, actionable guidance with clear tool sequences, expected outcomes, and success criteria.
+Focus on practical workflows that deliver measurable results.`
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful - return actual workflow guidance
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# Workflow Guidance & Tool Recommendations
+
+## Your Context
+- **Goal**: ${goal}
+- **Project Context**: ${projectContext}
+- **Available Assets**: ${availableAssets.length > 0 ? availableAssets.join(', ') : 'None specified'}
+- **Timeframe**: ${timeframe}
+- **Primary Concerns**: ${primaryConcerns.length > 0 ? primaryConcerns.join(', ') : 'General analysis'}
+
+## AI-Generated Workflow Guidance
+
+${executionResult.content}
+
+## Quick Reference: Available Tools
+
+**Core Analysis**: analyze_project_ecosystem, get_architectural_context, generate_adrs_from_prd, analyze_content_security
+**ADR Management**: suggest_adrs, generate_adr_from_decision, discover_existing_adrs, generate_adr_todo
+**Security**: generate_content_masking, configure_custom_patterns, validate_content_masking
+**Governance**: generate_rules, validate_rules, create_rule_set
+**Environment**: analyze_environment, analyze_deployment_progress
+**Utilities**: manage_cache, configure_output_masking, check_ai_execution_status
+
+## Next Steps
+
+1. **Start with the recommended primary workflow** above
+2. **Call the first tool** with the suggested parameters
+3. **Review the results** and proceed to the next step
+4. **Track progress** using the success metrics provided
+5. **Adjust as needed** based on your specific findings
+
+This guidance is tailored to your specific context and goals for maximum effectiveness!
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: workflowPrompt
+                        }
+                    ]
+                };
+            }
         }
         catch (error) {
-            throw new McpAdrError(`Failed to generate ADRs from PRD: ${error instanceof Error ? error.message : String(error)}`, 'GENERATION_ERROR');
+            throw new McpAdrError(`Failed to generate workflow guidance: ${error instanceof Error ? error.message : String(error)}`, 'WORKFLOW_ERROR');
         }
     }
-    async generateAdrTodo(args) {
-        const { scope = 'all' } = args;
-        const adrDirectory = args.adrDirectory || this.config.adrDirectory;
-        this.logger.info(`Generating todo from ADRs in: ${adrDirectory}`);
+    async getDevelopmentGuidance(args) {
+        const { developmentPhase, adrsToImplement = [], technologyStack = [], currentProgress = '', teamContext = { size: 'small_team', experienceLevel: 'mixed' }, timeline = '', focusAreas = [] } = args;
         try {
+            // Generate prompts for ADR discovery if ADRs are specified
             const { findFiles } = await import('./utils/file-system.js');
-            // Find all ADR files
-            const adrFiles = await findFiles(process.cwd(), [`${adrDirectory}/**/*.md`], { includeContent: true });
-            if (adrFiles.length === 0) {
-                throw new McpAdrError(`No ADR files found in ${adrDirectory}`, 'NO_ADRS_FOUND');
+            let adrAnalysisPrompt = '';
+            if (adrsToImplement.length > 0) {
+                const { getAdrDirectoryPath } = await import('./utils/config.js');
+                const absoluteAdrPath = getAdrDirectoryPath(this.config);
+                const adrFileDiscovery = await findFiles(this.config.projectPath, [`${absoluteAdrPath}/**/*.md`], {
+                    includeContent: true,
+                });
+                adrAnalysisPrompt = `
+## ADR Analysis for Implementation
+
+${adrFileDiscovery.prompt}
+
+**ADRs to Implement**: ${adrsToImplement.join(', ')}
+**ADR Directory**: ${absoluteAdrPath}
+`;
             }
-            // Prepare ADR content for analysis
-            const adrContent = adrFiles.map(file => ({
-                filename: file.name,
-                path: file.path,
-                content: file.content || ''
-            }));
-            // Generate todo creation prompt
-            const todoPrompt = `
-# ADR Todo Generation Request
+            const developmentPrompt = `
+# Development Guidance & Implementation Roadmap
 
-Please analyze the following Architectural Decision Records and generate a comprehensive todo.md file.
+## Development Context
+- **Development Phase**: ${developmentPhase}
+- **Technology Stack**: ${technologyStack.length > 0 ? technologyStack.join(', ') : 'Not specified'}
+- **Current Progress**: ${currentProgress || 'Starting fresh'}
+- **Team Size**: ${teamContext.size}
+- **Team Experience**: ${teamContext.experienceLevel}
+- **Timeline**: ${timeline || 'Not specified'}
+- **Focus Areas**: ${focusAreas.length > 0 ? focusAreas.join(', ') : 'General development'}
 
-## ADR Files
-${adrContent.map(adr => `
-### ${adr.filename}
-\`\`\`markdown
-${adr.content.slice(0, 1500)}${adr.content.length > 1500 ? '\n... (truncated)' : ''}
-\`\`\`
-`).join('')}
+${adrAnalysisPrompt}
 
-## Requirements
+## Development Guidance Instructions
 
-1. **Extract Tasks**: Identify all implementation tasks from ADRs
-2. **Categorize**: Group tasks by ADR and priority
-3. **Status Detection**: Determine task completion status based on:
-   - File existence checks
-   - Code analysis hints
-   - Implementation evidence
-4. **Progress Tracking**: Calculate overall progress
-5. **Scope Filter**: ${scope === 'all' ? 'Include all tasks' : `Focus on ${scope} tasks only`}
+Based on the development context, ADRs to implement, and technology stack, provide comprehensive development guidance including:
 
-## Todo.md Format
+### 1. **Implementation Roadmap**
+Create a detailed development plan with:
+- **Phase-by-Phase Breakdown**: Logical development phases
+- **Task Prioritization**: Order tasks by dependencies and impact
+- **Milestone Definition**: Clear checkpoints and deliverables
+- **Risk Assessment**: Potential blockers and mitigation strategies
 
-\`\`\`markdown
-# ADR Implementation Progress
+### 2. **Code Structure & Architecture**
+Provide specific guidance on:
+- **Project Structure**: How to organize code files and directories
+- **Module Architecture**: How to structure components/modules
+- **Design Patterns**: Which patterns to use and where
+- **Code Organization**: Separation of concerns and layering
 
-**Last Updated**: [Date]
-**Overall Progress**: [X]% Complete
+### 3. **Implementation Patterns & Best Practices**
+For each technology in the stack, provide:
+- **Framework-Specific Patterns**: Best practices for the chosen frameworks
+- **API Design**: How to structure APIs and endpoints
+- **Data Layer**: Database schema and data access patterns
+- **State Management**: How to handle application state
+- **Error Handling**: Consistent error handling strategies
 
-## Summary
-- Total ADRs: [count]
-- Total Tasks: [count]
-- Completed: [count]
-- In Progress: [count]
-- Pending: [count]
+### 4. **ADR-to-Code Translation**
+For each ADR to implement:
+- **Implementation Tasks**: Specific coding tasks derived from the ADR
+- **Code Examples**: Pseudo-code or pattern examples
+- **Integration Points**: How this ADR affects other parts of the system
+- **Validation Criteria**: How to verify the ADR is properly implemented
 
-## Tasks by ADR
+### 5. **Testing Strategy**
+Comprehensive testing approach:
+- **Unit Testing**: What to test and how
+- **Integration Testing**: API and component integration tests
+- **End-to-End Testing**: User workflow testing
+- **Performance Testing**: Load and performance validation
+- **Security Testing**: Security validation approaches
 
-### ADR-001: [Title]
-- [ ] Task 1 description
-- [x] Task 2 description (completed)
-- [/] Task 3 description (in progress)
+### 6. **Development Workflow**
+Team-specific guidance:
+- **Git Workflow**: Branching strategy and code review process
+- **CI/CD Pipeline**: Automated testing and deployment
+- **Code Quality**: Linting, formatting, and quality gates
+- **Documentation**: What to document and how
+
+### 7. **Quality Gates & Checkpoints**
+Define success criteria:
+- **Code Quality Metrics**: Coverage, complexity, maintainability
+- **Performance Benchmarks**: Response times, throughput targets
+- **Security Checkpoints**: Security validation at each phase
+- **Architectural Compliance**: Adherence to ADR decisions
+
+### 8. **Technology-Specific Implementation**
+For each technology in the stack, provide:
+- **Setup Instructions**: Environment and tooling setup
+- **Configuration**: Framework and tool configuration
+- **Optimization**: Performance and build optimization
+- **Deployment**: Technology-specific deployment considerations
+
+## Expected Output Format
+
+Provide a comprehensive development guide that includes:
+
+### 📋 **1. Development Roadmap**
+- **Phase 1-N**: Logical development phases with tasks
+- **Dependencies**: Task dependencies and critical path
+- **Timeline**: Estimated effort and duration
+- **Milestones**: Key deliverables and checkpoints
+
+### 🏗️ **2. Implementation Guide**
+- **Code Structure**: Detailed project organization
+- **Design Patterns**: Specific patterns to implement
+- **API Design**: Endpoint structure and conventions
+- **Data Architecture**: Database and data flow design
+
+### 🧪 **3. Testing & Quality Strategy**
+- **Test Types**: Unit, integration, e2e testing approach
+- **Quality Gates**: Code quality and performance criteria
+- **Automation**: CI/CD and automated testing setup
+
+### 🚀 **4. Deployment & Operations**
+- **Environment Setup**: Development, staging, production
+- **Deployment Pipeline**: Automated deployment process
+- **Monitoring**: Logging, metrics, and alerting
+- **Maintenance**: Ongoing maintenance and updates
+
+### 📊 **5. Progress Tracking**
+- **Success Metrics**: How to measure development progress
+- **Quality Indicators**: Code quality and performance metrics
+- **Milestone Validation**: How to verify milestone completion
+- **Risk Monitoring**: Early warning signs and mitigation
+
+### 💡 **6. Team-Specific Recommendations**
+Based on team size (${teamContext.size}) and experience (${teamContext.experienceLevel}):
+- **Workflow Adaptations**: Process adjustments for team context
+- **Skill Development**: Areas for team skill building
+- **Tool Recommendations**: Development tools and practices
+- **Communication**: Coordination and documentation practices
+
+## Integration with Architectural Decisions
+
+Ensure all development guidance:
+- **Aligns with ADRs**: Every recommendation supports architectural decisions
+- **Maintains Consistency**: Consistent patterns across the codebase
+- **Enables Evolution**: Flexible design for future changes
+- **Supports Quality**: Built-in quality and maintainability
+
+Make the guidance **actionable, specific, and immediately implementable** so developers can start coding with confidence and architectural alignment.
+`;
+            // Execute the development guidance with AI if enabled
+            const { executePromptWithFallback, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executePromptWithFallback(developmentPrompt, 'Analyze the development context and provide comprehensive implementation guidance that translates architectural decisions into specific coding tasks and development roadmap.', {
+                temperature: 0.1,
+                maxTokens: 8000,
+                systemPrompt: `You are an expert software development advisor specializing in translating architectural decisions into practical implementation guidance.
+Your role is to bridge the gap between architectural planning and actual code development.
+Provide specific, actionable development guidance with clear implementation steps, code patterns, and quality criteria.
+Focus on practical guidance that ensures architectural decisions are properly implemented in code.
+Consider team context, technology stack, and development phase to provide tailored recommendations.`
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful - return actual development guidance
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# Development Guidance & Implementation Roadmap
+
+## Your Development Context
+- **Development Phase**: ${developmentPhase}
+- **Technology Stack**: ${technologyStack.length > 0 ? technologyStack.join(', ') : 'Not specified'}
+- **Current Progress**: ${currentProgress || 'Starting fresh'}
+- **Team Context**: ${teamContext.size} team with ${teamContext.experienceLevel} experience
+- **Timeline**: ${timeline || 'Not specified'}
+- **Focus Areas**: ${focusAreas.length > 0 ? focusAreas.join(', ') : 'General development'}
+- **ADRs to Implement**: ${adrsToImplement.length > 0 ? adrsToImplement.join(', ') : 'None specified'}
+
+## AI-Generated Development Guidance
+
+${executionResult.content}
+
+## Integration with Workflow Tools
+
+This development guidance works seamlessly with other MCP tools:
+
+### **Workflow Integration**
+1. **get_workflow_guidance** → Recommends architectural process
+2. **get_development_guidance** → Guides implementation (this tool)
+3. **validate_rules** → Ensures code follows architectural decisions
+4. **analyze_deployment_progress** → Tracks implementation progress
+
+### **Quality Assurance Tools**
+- **generate_rules** → Extract coding standards from ADRs
+- **validate_rules** → Validate code against architectural rules
+- **analyze_content_security** → Security validation during development
+
+### **Documentation Tools**
+- **generate_adr_todo** → Create implementation task lists
+- **discover_existing_adrs** → Reference existing architectural decisions
+
+## Next Steps: From Architecture to Code
+
+1. **📋 Review the Development Roadmap** above
+2. **🏗️ Set Up Project Structure** as recommended
+3. **🧪 Implement Testing Strategy** early in development
+4. **📊 Track Progress** using the success metrics provided
+5. **🔄 Iterate and Refine** based on implementation learnings
+
+This guidance ensures your development work is **architecturally aligned**, **quality-focused**, and **efficiently executed**!
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: developmentPrompt
+                        }
+                    ]
+                };
+            }
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to generate development guidance: ${error instanceof Error ? error.message : String(error)}`, 'DEVELOPMENT_ERROR');
+        }
+    }
+    async analyzeProjectEcosystem(args) {
+        // Use configured project path if not provided in args
+        const projectPath = args.projectPath || this.config.projectPath;
+        const { includePatterns, enhancedMode = true, knowledgeEnhancement = true, learningEnabled = true, technologyFocus = [], analysisDepth = 'comprehensive', includeEnvironment = true, recursiveDepth = 'comprehensive', analysisScope = [] } = args;
+        this.logger.info(`Generating comprehensive ecosystem analysis for project at: ${projectPath}`);
+        this.logger.info(`Analysis configuration - Depth: ${analysisDepth}, Recursive: ${recursiveDepth}, Environment: ${includeEnvironment}`);
+        this.logger.info(`Enhancement features - Knowledge: ${knowledgeEnhancement}, Learning: ${learningEnabled}`);
+        this.logger.info(`Analysis scope: ${analysisScope.length > 0 ? analysisScope.join(', ') : 'Full ecosystem analysis'}`);
+        try {
+            // Import utilities dynamically to avoid circular dependencies
+            const { analyzeProjectStructure } = await import('./utils/file-system.js');
+            // Import advanced prompting utilities if enhanced mode is enabled
+            let generateArchitecturalKnowledge = null;
+            let executeWithReflexion = null;
+            let retrieveRelevantMemories = null;
+            let createToolReflexionConfig = null;
+            if (enhancedMode) {
+                if (knowledgeEnhancement) {
+                    const knowledgeModule = await import('./utils/knowledge-generation.js');
+                    generateArchitecturalKnowledge = knowledgeModule.generateArchitecturalKnowledge;
+                }
+                if (learningEnabled) {
+                    const reflexionModule = await import('./utils/reflexion.js');
+                    executeWithReflexion = reflexionModule.executeWithReflexion;
+                    retrieveRelevantMemories = reflexionModule.retrieveRelevantMemories;
+                    createToolReflexionConfig = reflexionModule.createToolReflexionConfig;
+                }
+            }
+            // Step 1: Generate technology-specific knowledge if enabled
+            let knowledgeContext = '';
+            if (enhancedMode && knowledgeEnhancement && generateArchitecturalKnowledge) {
+                try {
+                    const knowledgeResult = await generateArchitecturalKnowledge({
+                        projectPath,
+                        technologies: technologyFocus,
+                        patterns: [],
+                        projectType: 'ecosystem-analysis',
+                        existingAdrs: []
+                    }, {
+                        domains: this.getEcosystemAnalysisDomains(technologyFocus),
+                        depth: analysisDepth === 'basic' ? 'basic' : 'intermediate',
+                        cacheEnabled: true
+                    });
+                    knowledgeContext = `
+## Technology-Specific Knowledge Enhancement
+
+The following architectural knowledge has been generated to enhance ecosystem analysis:
+
+${knowledgeResult.prompt}
+
+---
+`;
+                }
+                catch (error) {
+                    this.logger.warn('Knowledge generation failed:', error);
+                    knowledgeContext = '<!-- Knowledge generation unavailable -->\n';
+                }
+            }
+            // Step 2: Retrieve relevant memories if learning is enabled
+            let reflexionContext = '';
+            if (enhancedMode && learningEnabled && retrieveRelevantMemories) {
+                try {
+                    const memoryResult = await retrieveRelevantMemories('ecosystem-analysis', { projectPath, analysisDepth, technologyFocus }, { maxResults: 5, relevanceThreshold: 0.6 });
+                    reflexionContext = `
+## Learning from Past Analyses
+
+The following insights from past ecosystem analysis tasks will inform this analysis:
+
+${memoryResult.prompt}
+
+---
+`;
+                }
+                catch (error) {
+                    this.logger.warn('Reflexion memory retrieval failed:', error);
+                    reflexionContext = '<!-- Learning context unavailable -->\n';
+                }
+            }
+            // Step 3: Generate base project analysis prompt with recursive depth
+            const baseProjectAnalysisPrompt = await analyzeProjectStructure(projectPath);
+            // Step 4: Generate environment analysis if enabled
+            let environmentAnalysisContext = '';
+            if (includeEnvironment) {
+                try {
+                    this.logger.info('Including comprehensive environment analysis in ecosystem analysis');
+                    const { analyzeEnvironment } = await import('./tools/environment-analysis-tool.js');
+                    // Call environment analysis with comprehensive scope
+                    const environmentResult = await analyzeEnvironment({
+                        projectPath,
+                        adrDirectory: this.config.adrDirectory,
+                        analysisType: 'comprehensive'
+                    });
+                    // Extract environment analysis content
+                    if (environmentResult.content && environmentResult.content[0]) {
+                        environmentAnalysisContext = `
+## Integrated Environment Analysis
+
+${environmentResult.content[0].text}
+
+---
+`;
+                    }
+                }
+                catch (error) {
+                    this.logger.warn('Environment analysis integration failed:', error);
+                    environmentAnalysisContext = `
+## Environment Analysis
+<!-- Environment analysis unavailable: ${error instanceof Error ? error.message : 'Unknown error'} -->
+
+---
+`;
+                }
+            }
+            // Step 5: Apply Reflexion execution if learning is enabled
+            let enhancedAnalysisPrompt = baseProjectAnalysisPrompt.prompt + environmentAnalysisContext;
+            if (enhancedMode && learningEnabled && executeWithReflexion && createToolReflexionConfig) {
+                try {
+                    const reflexionConfig = createToolReflexionConfig('analyze_project_ecosystem', {
+                        reflectionDepth: analysisDepth === 'basic' ? 'basic' : 'detailed',
+                        evaluationCriteria: ['task-success', 'accuracy', 'completeness'],
+                        learningRate: 0.7
+                    });
+                    const reflexionResult = await executeWithReflexion({
+                        prompt: baseProjectAnalysisPrompt.prompt + knowledgeContext + environmentAnalysisContext,
+                        instructions: baseProjectAnalysisPrompt.instructions,
+                        context: {
+                            projectPath,
+                            analysisDepth,
+                            recursiveDepth,
+                            technologyFocus,
+                            includePatterns,
+                            includeEnvironment,
+                            analysisScope,
+                            knowledgeEnhanced: knowledgeEnhancement,
+                            learningEnabled: true
+                        }
+                    }, reflexionConfig);
+                    enhancedAnalysisPrompt = reflexionResult.prompt;
+                }
+                catch (error) {
+                    this.logger.warn('Reflexion execution failed:', error);
+                    enhancedAnalysisPrompt = baseProjectAnalysisPrompt.prompt + knowledgeContext + environmentAnalysisContext;
+                }
+            }
+            else {
+                enhancedAnalysisPrompt = baseProjectAnalysisPrompt.prompt + knowledgeContext + environmentAnalysisContext;
+            }
+            // Execute the analysis with AI if enabled, otherwise return prompt
+            const { executeEcosystemAnalysisPrompt, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executeEcosystemAnalysisPrompt(enhancedAnalysisPrompt, baseProjectAnalysisPrompt.instructions, {
+                temperature: 0.1,
+                maxTokens: 6000,
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful - return actual analysis results
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# Comprehensive Project Ecosystem Analysis Results
+
+## Analysis Configuration
+- **Project Path**: ${projectPath}
+- **Analysis Depth**: ${analysisDepth}
+- **Recursive Depth**: ${recursiveDepth}
+- **Environment Analysis**: ${includeEnvironment ? '✅ Included' : '❌ Excluded'}
+- **Analysis Scope**: ${analysisScope.length > 0 ? analysisScope.join(', ') : 'Full ecosystem analysis'}
+
+## Enhancement Features
+- **Knowledge Generation**: ${enhancedMode && knowledgeEnhancement ? '✅ Enabled' : '❌ Disabled'}
+- **Reflexion Learning**: ${enhancedMode && learningEnabled ? '✅ Enabled' : '❌ Disabled'}
+- **Enhanced Mode**: ${enhancedMode ? '✅ Enabled' : '❌ Disabled'}
+- **Technology Focus**: ${technologyFocus.length > 0 ? technologyFocus.join(', ') : 'Auto-detect'}
+
+${knowledgeContext}
+
+${reflexionContext}
+
+## Comprehensive Ecosystem Analysis Results
+
+${executionResult.content}
+
+${includeEnvironment ? `
+
+## Environment Integration Summary
+
+The analysis above includes comprehensive environment analysis covering:
+- **Infrastructure Specifications**: Deployment and runtime environment details
+- **Containerization**: Docker, Kubernetes, and container orchestration analysis
+- **Environment Requirements**: Configuration and dependency requirements
+- **Compliance Assessment**: Security and regulatory compliance evaluation
+
+This integrated approach provides complete understanding of both codebase patterns AND operational environment.
+` : ''}
+
+## Next Steps: Complete Ecosystem Understanding
+
+Based on the comprehensive analysis above:
+
+### **Immediate Actions**
+1. **Review Ecosystem Overview**: Examine the complete technology stack and environment context
+2. **Assess Integration Points**: Understand how code patterns relate to operational environment
+3. **Identify Critical Dependencies**: Focus on key dependencies between code and infrastructure
+
+### **Strategic Planning**
+4. **Address Architectural Issues**: Prioritize improvements based on both code and environment analysis
+5. **Plan Environment Optimization**: Optimize deployment and operational configurations
+6. **Update Documentation**: Document both architectural decisions and environment specifications
+
+### **Implementation Roadmap**
+7. **Implement Code Improvements**: Execute code-level architectural enhancements
+8. **Optimize Environment**: Improve infrastructure and deployment configurations
+9. **Monitor Integration**: Ensure code and environment changes work together effectively
+
+This comprehensive ecosystem analysis provides the foundation for informed architectural and operational decisions.
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Comprehensive Project Ecosystem Analysis
+
+This comprehensive analysis provides deep recursive project understanding with integrated environment analysis.
+
+## Analysis Configuration
+- **Project Path**: ${projectPath}
+- **Analysis Depth**: ${analysisDepth}
+- **Recursive Depth**: ${recursiveDepth}
+- **Environment Analysis**: ${includeEnvironment ? '✅ Included' : '❌ Excluded'}
+- **Analysis Scope**: ${analysisScope.length > 0 ? analysisScope.join(', ') : 'Full ecosystem analysis'}
+
+## Enhancement Features
+- **Knowledge Generation**: ${enhancedMode && knowledgeEnhancement ? '✅ Enabled' : '❌ Disabled'}
+- **Reflexion Learning**: ${enhancedMode && learningEnabled ? '✅ Enabled' : '❌ Disabled'}
+- **Enhanced Mode**: ${enhancedMode ? '✅ Enabled' : '❌ Disabled'}
+- **Technology Focus**: ${technologyFocus.length > 0 ? technologyFocus.join(', ') : 'Auto-detect'}
+- **Include Patterns**: ${includePatterns?.length ? includePatterns.join(', ') : 'Default patterns'}
+
+${knowledgeContext}
+
+${reflexionContext}
+
+## Enhanced Analysis Prompt
+
+${enhancedAnalysisPrompt}
+
+## Enhanced Implementation Instructions
+
+${baseProjectAnalysisPrompt.instructions}
+
+### Enhancement-Specific Instructions
+
+${enhancedMode && knowledgeEnhancement ? `
+#### Knowledge Enhancement
+- Apply technology-specific knowledge to ecosystem analysis
+- Use domain expertise to identify patterns and anti-patterns
+- Leverage architectural best practices for technology stack evaluation
+` : ''}
+
+${enhancedMode && learningEnabled ? `
+#### Learning Integration
+- Apply lessons learned from past ecosystem analyses
+- Use memory insights to improve pattern recognition accuracy
+- Incorporate feedback from previous analysis outcomes
+` : ''}
+
+## Expected Enhanced Output
+
+The enhanced analysis should provide:
+1. **Technology Stack Analysis** with domain knowledge context
+2. **Architectural Pattern Detection** informed by past experiences
+3. **Ecosystem Health Assessment** using learned evaluation criteria
+4. **Improvement Recommendations** based on domain best practices
+5. **Learning Insights** for future analysis improvement
+
+## Quality Assurance
+
+- Ensure analysis leverages all available enhancement features
+- Verify technology-specific knowledge is properly applied
+- Confirm learning insights improve analysis accuracy
+- Validate recommendations align with domain best practices`
+                        }
+                    ]
+                };
+            }
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to analyze project ecosystem: ${error instanceof Error ? error.message : String(error)}`, 'ANALYSIS_ERROR');
+        }
+    }
+    async getArchitecturalContext(args) {
+        const { filePath, includeCompliance = true } = args;
+        try {
+            const { analyzeProjectStructure, fileExists, ensureDirectory } = await import('./utils/file-system.js');
+            const path = await import('path');
+            // Determine project path
+            const projectPath = filePath ? filePath.split('/').slice(0, -1).join('/') : this.config.projectPath;
+            const adrDirectory = path.join(projectPath, this.config.adrDirectory);
+            // Generate prompts for ADR directory setup
+            const adrDirectoryCheckPrompt = await fileExists(adrDirectory);
+            const adrDirectorySetupPrompt = await ensureDirectory(adrDirectory);
+            // Generate architectural analysis prompt
+            const projectAnalysisPrompt = await analyzeProjectStructure(projectPath);
+            const architecturalPrompt = `
+# Architectural Context Analysis & Project Setup
+
+## Project Overview
+**Project Path**: ${projectPath}
+**Analysis Scope**: ${filePath ? `Specific file: ${filePath}` : 'Entire project'}
+**ADR Directory**: ${this.config.adrDirectory}
+**Include Compliance**: ${includeCompliance ? 'Yes' : 'No'}
+
+## 🚀 ADR Infrastructure Setup
+
+This analysis will include setting up ADR infrastructure if needed:
+
+### ADR Directory Check
+${adrDirectoryCheckPrompt.prompt}
+
+### ADR Directory Setup (if needed)
+${adrDirectorySetupPrompt.prompt}
+
+## Comprehensive Project Analysis
+
+${projectAnalysisPrompt.prompt}
+
+## Enhanced Architectural Focus
+
+Please provide a **comprehensive, outcome-focused analysis** including:
+
+### 1. Technology Stack & Infrastructure Analysis
+- **Core Technologies**: Programming languages, frameworks, runtime environments
+- **Dependencies**: Package managers, third-party libraries, version constraints
+- **Build & Deployment**: CI/CD pipelines, build tools, deployment strategies
+- **Data Layer**: Databases, caching, data storage and retrieval patterns
+
+### 2. Architectural Pattern & Design Analysis
+- **System Architecture**: Monolith, microservices, serverless, hybrid patterns
+- **Code Organization**: Module structure, separation of concerns, layering
+- **API Design**: REST, GraphQL, RPC patterns and conventions
+- **Data Flow**: Request/response cycles, event handling, state management
+${filePath ? `- **File-specific Context**: How ${filePath} fits into the overall architecture` : ''}
+
+### 3. Quality, Security & Performance Assessment
+- **Code Quality**: Structure, naming, documentation, testing strategies
+- **Security Implementation**: Authentication, authorization, data protection
+- **Performance Patterns**: Caching, optimization, scalability considerations
+- **Monitoring & Observability**: Logging, metrics, error tracking
+
+### 4. Architectural Decision Discovery & Documentation
+- **Explicit Decisions**: Find existing documentation and decision records
+- **Implicit Decisions**: Identify significant undocumented architectural choices
+- **Technology Rationale**: Understand selection criteria and trade-offs
+- **Evolution Path**: How the architecture has changed over time
+
+${includeCompliance ? `### 5. Compliance & Standards Assessment
+- **Industry Standards**: Adherence to relevant industry standards and best practices
+- **Security Compliance**: Security standards compliance (OWASP, SOC2, etc.)
+- **Code Standards**: Coding standards and style guide compliance
+- **Architectural Compliance**: Adherence to established architectural principles
+- **Regulatory Requirements**: Any regulatory compliance requirements (GDPR, HIPAA, etc.)` : ''}
+
+## Expected Output: Outcome-Focused Architectural Context
+
+Provide a **comprehensive architectural context** with **clear project outcomes**:
+
+### 📋 **1. Executive Summary & Project Outcomes**
+- **Current State**: What the project is and what it does
+- **Architectural Maturity**: Assessment of current architectural practices
+- **Key Strengths**: What's working well architecturally
+- **Critical Gaps**: What needs immediate attention
+- **Success Metrics**: How to measure architectural improvements
+
+### 🔧 **2. Technology & Infrastructure Inventory**
+- **Technology Stack**: Complete inventory with versions and purposes
+- **Infrastructure Components**: Deployment, monitoring, data storage
+- **Dependencies**: Critical dependencies and potential risks
+- **Tool Chain**: Development, testing, and deployment tools
+
+### 🏗️ **3. Architectural Patterns & Design Decisions**
+- **System Design**: Overall architectural approach and patterns
+- **Component Architecture**: How major components interact
+- **Data Architecture**: How data flows and is managed
+- **Integration Patterns**: How external systems are integrated
+
+### 📊 **4. Quality & Compliance Assessment**
+- **Code Quality Score**: Assessment of current code quality
+- **Security Posture**: Security implementation and gaps
+- **Performance Profile**: Current performance characteristics
+- **Maintainability Index**: How easy the system is to maintain and evolve
+
+### 🎯 **5. Outcome-Focused Action Plan**
+Based on the analysis, provide a **clear workflow** with **projected outcomes**:
+
+#### **Immediate Actions (Next 1-2 weeks)**
+- **Priority 1**: Most critical architectural issues to address
+- **Quick Wins**: Low-effort, high-impact improvements
+- **Documentation**: Essential decisions that need immediate documentation
+
+#### **Short-term Goals (Next 1-3 months)**
+- **Architectural Improvements**: Planned enhancements with expected outcomes
+- **Technical Debt**: Priority technical debt to address
+- **Process Improvements**: Development workflow enhancements
+
+#### **Long-term Vision (3-12 months)**
+- **Strategic Architecture**: Long-term architectural evolution
+- **Scalability Roadmap**: How to scale the system effectively
+- **Innovation Opportunities**: Areas for architectural innovation
+
+### 📈 **6. Success Metrics & Outcomes**
+Define **measurable outcomes** for architectural improvements:
+
+- **Performance Metrics**: Response times, throughput, resource utilization
+- **Quality Metrics**: Code coverage, bug rates, maintainability scores
+- **Developer Experience**: Build times, deployment frequency, developer satisfaction
+- **Business Impact**: Feature delivery speed, system reliability, cost efficiency
+
+### 🏗️ **7. ADR Infrastructure & Documentation Plan**
+
+If ADR directory doesn't exist, also provide:
+
+1. **Create Directory Structure**:
+   \`\`\`
+   ${this.config.adrDirectory}/
+   ├── 0001-record-architecture-decisions.md (template)
+   ├── README.md (ADR process guide)
+   └── template.md (ADR template)
+   \`\`\`
+
+2. **Generate Initial ADRs** for discovered architectural decisions
+3. **Create ADR Process Guide** for the team
+4. **Establish ADR Workflow** for future decisions
+
+### 🔄 **8. Continuous Improvement Workflow**
+Establish ongoing architectural governance:
+
+- **Regular Reviews**: Monthly architectural health checks
+- **Decision Documentation**: Process for documenting new architectural decisions
+- **Compliance Monitoring**: Ongoing adherence to architectural standards
+- **Evolution Planning**: Quarterly architectural roadmap updates
+
+## Next Steps: Grounded Project Workflow
+
+After this analysis, follow this **outcome-focused workflow**:
+
+1. **📋 Review Analysis**: Examine the architectural context and recommendations
+2. **🎯 Set Priorities**: Choose 3-5 most impactful improvements based on outcomes
+3. **📝 Document Decisions**: Create ADRs for significant architectural choices
+4. **🔧 Implement Changes**: Execute improvements in priority order
+5. **📊 Measure Progress**: Track success metrics and outcomes
+6. **🔄 Iterate**: Regular reviews and continuous improvement
+
+This approach ensures that architectural work is **grounded in measurable outcomes** and **aligned with project success**.
+`;
+            // Execute the analysis with AI if enabled, otherwise return prompt
+            const { executeEcosystemAnalysisPrompt, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executeEcosystemAnalysisPrompt(architecturalPrompt, projectAnalysisPrompt.instructions, {
+                temperature: 0.1,
+                maxTokens: 5000,
+                systemPrompt: `You are a senior software architect specializing in architectural context analysis.
+Analyze the provided project to understand its architectural patterns, design decisions, and structural organization.
+Focus on providing actionable insights about the architecture that can guide development decisions.`
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful - return actual analysis results
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# Architectural Context Analysis Results
+
+${filePath ? `## Target File: ${filePath}` : '## Project-wide Analysis'}
+
+## Project Information
+- **Project Path**: ${projectPath}
+- **Analysis Scope**: ${filePath ? 'File-specific' : 'Project-wide'}
+- **ADR Directory**: ${this.config.adrDirectory}
+
+## ADR Infrastructure Setup
+
+The analysis includes automatic ADR infrastructure setup:
+
+${adrDirectoryCheckPrompt.instructions}
+
+${adrDirectorySetupPrompt.instructions}
+
+## AI Analysis Results
+
+${executionResult.content}
+
+## Outcome-Focused Next Steps
+
+Based on the architectural analysis, follow this **grounded workflow**:
+
+### **Immediate Actions (This Week)**
+1. **Review Analysis**: Examine the architectural context and recommendations above
+2. **Set Up ADRs**: Ensure ADR directory structure is created and ready
+3. **Identify Quick Wins**: Focus on low-effort, high-impact improvements
+
+### **Short-term Goals (Next Month)**
+4. **Document Key Decisions**: Create ADRs for the most significant architectural choices
+5. **Address Critical Issues**: Tackle the highest-priority architectural concerns
+6. **Establish Metrics**: Set up measurement for the success metrics identified
+
+### **Long-term Vision (Next Quarter)**
+7. **Implement Roadmap**: Execute the architectural improvement plan
+8. **Monitor Progress**: Track success metrics and adjust approach as needed
+9. **Continuous Improvement**: Establish regular architectural reviews
+
+This **outcome-focused approach** ensures architectural work delivers **measurable value** and keeps the project **grounded in clear objectives**.
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: architecturalPrompt
+                        }
+                    ]
+                };
+            }
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to get architectural context: ${error instanceof Error ? error.message : String(error)}`, 'ANALYSIS_ERROR');
+        }
+    }
+    async generateAdrsFromPrd(args) {
+        const { prdPath, enhancedMode = true, promptOptimization = true, knowledgeEnhancement = true, prdType = 'general' } = args;
+        const outputDirectory = args.outputDirectory || this.config.adrDirectory;
+        this.logger.info(`Generating enhanced ADRs from PRD: ${prdPath} to ${outputDirectory}`);
+        this.logger.info(`Enhancement features - APE: ${promptOptimization}, Knowledge: ${knowledgeEnhancement}, Type: ${prdType}`);
+        try {
+            const { readFileContent, fileExists } = await import('./utils/file-system.js');
+            // Import advanced prompting utilities if enhanced mode is enabled
+            let generateArchitecturalKnowledge = null;
+            let optimizePromptWithAPE = null;
+            let createToolAPEConfig = null;
+            if (enhancedMode) {
+                if (knowledgeEnhancement) {
+                    const knowledgeModule = await import('./utils/knowledge-generation.js');
+                    generateArchitecturalKnowledge = knowledgeModule.generateArchitecturalKnowledge;
+                }
+                if (promptOptimization) {
+                    const apeModule = await import('./utils/automatic-prompt-engineering.js');
+                    optimizePromptWithAPE = apeModule.optimizePromptWithAPE;
+                    createToolAPEConfig = apeModule.createToolAPEConfig;
+                }
+            }
+            // Generate file existence check prompt
+            const fileExistsPrompt = await fileExists(prdPath);
+            // Generate file content reading prompt
+            const fileContentPrompt = await readFileContent(prdPath);
+            // Step 1: Generate domain-specific knowledge if enabled
+            let knowledgeContext = '';
+            if (enhancedMode && knowledgeEnhancement && generateArchitecturalKnowledge) {
+                try {
+                    const knowledgeResult = await generateArchitecturalKnowledge({
+                        projectPath: outputDirectory,
+                        technologies: [],
+                        patterns: [],
+                        projectType: prdType,
+                        existingAdrs: []
+                    }, {
+                        domains: this.getPrdTypeDomains(prdType),
+                        depth: 'intermediate',
+                        cacheEnabled: true
+                    });
+                    knowledgeContext = `
+## Domain-Specific Knowledge Enhancement
+
+The following architectural knowledge has been generated to enhance PRD analysis and ADR creation:
+
+${knowledgeResult.prompt}
+
+---
+`;
+                }
+                catch (error) {
+                    this.logger.warn('Knowledge generation failed:', error);
+                    knowledgeContext = '<!-- Knowledge generation unavailable -->\n';
+                }
+            }
+            // Step 2: Create base ADR generation prompt
+            const baseAdrPrompt = this.createBaseAdrPrompt(prdPath, outputDirectory, knowledgeContext);
+            // Step 3: Apply APE optimization if enabled
+            let finalAdrPrompt = baseAdrPrompt;
+            if (enhancedMode && promptOptimization && optimizePromptWithAPE && createToolAPEConfig) {
+                try {
+                    const apeConfig = createToolAPEConfig('generate_adrs_from_prd', {
+                        candidateCount: 5,
+                        evaluationCriteria: ['task-completion', 'clarity', 'specificity'],
+                        optimizationRounds: 2,
+                        qualityThreshold: 0.75
+                    });
+                    const apeResult = await optimizePromptWithAPE({
+                        prompt: baseAdrPrompt,
+                        instructions: 'Generate comprehensive ADRs from PRD analysis',
+                        context: { prdPath, outputDirectory, prdType, knowledgeEnhanced: knowledgeEnhancement }
+                    }, apeConfig);
+                    finalAdrPrompt = apeResult.prompt;
+                }
+                catch (error) {
+                    this.logger.warn('APE optimization failed:', error);
+                    finalAdrPrompt = baseAdrPrompt;
+                }
+            }
+            // Generate comprehensive ADR creation prompt that includes file operations
+            const adrPrompt = `
+# Enhanced ADR Generation from PRD Request
+
+This is a comprehensive prompt-driven ADR generation process enhanced with advanced prompting techniques.
+
+## Enhancement Status
+- **APE Optimization**: ${enhancedMode && promptOptimization ? '✅ Enabled' : '❌ Disabled'}
+- **Knowledge Generation**: ${enhancedMode && knowledgeEnhancement ? '✅ Enabled' : '❌ Disabled'}
+- **PRD Type**: ${prdType}
+- **Enhanced Mode**: ${enhancedMode ? '✅ Enabled' : '❌ Disabled'}
+
+## Step 1: File Validation
+${fileExistsPrompt.prompt}
+
+**Instructions**: First, execute the file existence check above. If the file does not exist, stop the process and report the error. Only proceed to Step 2 if the file exists.
+
+## Step 2: PRD Content Reading
+${fileContentPrompt.prompt}
+
+**Instructions**: Execute the file reading operation above to obtain the PRD content. Use the content from this step for the enhanced ADR generation in Step 3.
+
+## Step 3: Enhanced ADR Generation
+
+${enhancedMode && promptOptimization ? `
+### APE-Optimized Analysis
+This prompt has been optimized using Automatic Prompt Engineering for superior ADR generation quality.
+The optimization focused on task completion, clarity, and specificity for PRD analysis.
+
+` : ''}
+
+${finalAdrPrompt}
+
+### File Creation Instructions
+
+For each generated ADR, create a file creation prompt using the following pattern:
+- **File Path**: ${outputDirectory}/[number]-[decision-title].md
+- **Content**: The complete enhanced ADR markdown content
+- **Action Confirmation**: Require user confirmation before creating files
+- **Security Validation**: Ensure output directory is safe and authorized
+
+### Enhanced Quality Assurance
+
+- Ensure each ADR leverages domain knowledge when available
+- Verify decisions align with PRD type best practices
+- Check that enhancement features are properly utilized
+- Validate that ADR content exceeds baseline quality expectations
+- Confirm all decisions are traceable back to PRD requirements with domain context
+`;
+            // Execute the ADR generation with AI if enabled, otherwise return prompt
+            const { executeADRGenerationPrompt, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executeADRGenerationPrompt(adrPrompt, 'Generate comprehensive ADRs from PRD analysis with enhanced domain knowledge and optimization', {
+                temperature: 0.1,
+                maxTokens: 8000,
+                systemPrompt: `You are an expert software architect who creates comprehensive Architectural Decision Records (ADRs) from Product Requirements Documents (PRDs).
+Generate well-structured ADRs that follow best practices and include all necessary sections.
+Focus on extracting architectural decisions from the PRD and creating actionable ADRs with clear reasoning.`
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful - return actual ADR generation results
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# ADR Generation from PRD Results
+
+## Enhancement Features
+- **APE Optimization**: ${enhancedMode && promptOptimization ? '✅ Enabled' : '❌ Disabled'}
+- **Knowledge Generation**: ${enhancedMode && knowledgeEnhancement ? '✅ Enabled' : '❌ Disabled'}
+- **PRD Type Optimization**: ${prdType}
+- **Enhanced Mode**: ${enhancedMode ? '✅ Enabled' : '❌ Disabled'}
+
+## Source Information
+- **PRD Path**: ${prdPath}
+- **Output Directory**: ${outputDirectory}
+
+## Generated ADRs
+
+${executionResult.content}
+
+## Next Steps
+
+1. **Review Generated ADRs**: Examine each ADR for completeness and accuracy
+2. **Save ADR Files**: Create individual .md files for each ADR in ${outputDirectory}
+3. **Update ADR Index**: Add new ADRs to your project's ADR catalog
+4. **Stakeholder Review**: Share ADRs with team for feedback and approval
+5. **Implementation Planning**: Create tasks for implementing the architectural decisions
+
+## File Creation Commands
+
+To save the generated ADRs, create individual files in ${outputDirectory}:
+
+\`\`\`bash
+# Create ADR directory if it doesn't exist
+mkdir -p ${outputDirectory}
+
+# Save each ADR as a separate file (example)
+# Replace [NUMBER] and [TITLE] with actual values from generated ADRs
+# cat > "${outputDirectory}/001-example-decision.md" << 'EOF'
+# [ADR content here]
+# EOF
+\`\`\`
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Enhanced ADR Generation from PRD: ${prdPath}
+
+## Advanced Prompt-Driven ADR Generation Process
+
+This tool uses a 100% prompt-driven architecture enhanced with advanced prompting techniques:
+
+### Enhancement Features
+- **APE Optimization**: ${enhancedMode && promptOptimization ? '✅ Enabled - Prompts optimized for superior quality' : '❌ Disabled'}
+- **Knowledge Generation**: ${enhancedMode && knowledgeEnhancement ? '✅ Enabled - Domain knowledge enhanced analysis' : '❌ Disabled'}
+- **PRD Type Optimization**: ${prdType} - Tailored for specific domain requirements
+- **Enhanced Mode**: ${enhancedMode ? '✅ Enabled - All advanced features active' : '❌ Disabled - Basic mode'}
+
+### Enhanced AI Agent Workflow
+
+1. **Validate PRD file existence** using secure file system operations
+2. **Read PRD content** safely with proper security validation
+3. **Apply domain knowledge** to enhance understanding (if enabled)
+4. **Generate optimized ADRs** using APE-enhanced prompts (if enabled)
+5. **Create enhanced ADR files** in the specified output directory: ${outputDirectory}
+
+## Execution Instructions
+
+Please execute the following enhanced comprehensive prompt:
+
+${adrPrompt}
+
+## Advanced Features
+
+${enhancedMode && knowledgeEnhancement ? `
+### Knowledge Enhancement
+- Domain-specific architectural knowledge has been generated
+- PRD analysis is enhanced with ${prdType} domain expertise
+- ADR decisions leverage domain best practices and patterns
+` : ''}
+
+${enhancedMode && promptOptimization ? `
+### APE Optimization
+- Prompts have been automatically optimized for quality
+- Enhanced evaluation criteria ensure superior ADR generation
+- Optimization focused on task completion, clarity, and specificity
+` : ''}
+
+## Security and Validation
+
+- All file operations include security validation
+- Path traversal protection is enabled
+- System directory access is prevented
+- User confirmation is required for file creation
+- Content validation ensures safe enhanced ADR generation
+
+## Expected Enhanced Workflow
+
+1. Execute file existence check for: ${prdPath}
+2. If file exists, read PRD content securely
+3. Apply domain knowledge to enhance PRD understanding
+4. Analyze PRD content using optimized prompts
+5. Generate domain-enhanced individual ADRs for each decision
+6. Create file creation prompts for each enhanced ADR
+7. Confirm with user before writing files to: ${outputDirectory}
+
+The enhanced process maintains full traceability from PRD requirements to generated ADRs while providing superior quality through advanced prompting techniques and ensuring security and user control over file operations.`
+                        }
+                    ]
+                };
+            }
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to generate ADR prompts from PRD: ${error instanceof Error ? error.message : String(error)}`, 'PROMPT_GENERATION_ERROR');
+        }
+    }
+    async generateAdrTodo(args) {
+        const { scope = 'all', phase = 'both', linkAdrs = true, includeRules = true, ruleSource = 'both' } = args;
+        const { getAdrDirectoryPath } = await import('./utils/config.js');
+        const path = await import('path');
+        // Use absolute ADR path relative to project
+        const absoluteAdrPath = args.adrDirectory ?
+            path.resolve(this.config.projectPath, args.adrDirectory) :
+            getAdrDirectoryPath(this.config);
+        // Keep relative path for display purposes
+        const adrDirectory = args.adrDirectory || this.config.adrDirectory;
+        this.logger.info(`Generating TDD-focused todo for ADRs in: ${absoluteAdrPath} (phase: ${phase})`);
+        try {
+            const { findFiles } = await import('./utils/file-system.js');
+            // Generate file discovery prompt for ADR files using project path as base
+            const adrFilesPrompt = await findFiles(this.config.projectPath, [`${absoluteAdrPath}/**/*.md`], { includeContent: true });
+            // For ADR linking, also discover all project structure
+            let projectStructurePrompt = '';
+            if (linkAdrs) {
+                const projectFiles = await findFiles(this.config.projectPath, [
+                    '**/*.{ts,js,py,java,cs,go,rb,php,swift,kt,rs,cpp,c,h}',
+                    '!node_modules/**',
+                    '!dist/**',
+                    '!build/**',
+                    '!.git/**'
+                ], {
+                    includeContent: false
+                });
+                projectStructurePrompt = `
+## Project Structure (for ADR linking)
+${projectFiles.prompt}
+`;
+            }
+            // For rules integration, extract architectural rules from ADRs
+            let rulesPrompt = '';
+            if (includeRules) {
+                try {
+                    const rulesResult = await this.generateRules({
+                        source: ruleSource,
+                        adrDirectory: adrDirectory,
+                        projectPath: this.config.projectPath,
+                        outputFormat: 'json'
+                    });
+                    if (rulesResult.content) {
+                        rulesPrompt = `
+## Architectural Rules (for compliance validation)
+The following architectural rules have been extracted from ADRs and should be validated in tests:
+
+${Array.isArray(rulesResult.content) ? rulesResult.content.map((c) => c.text || c).join('\n') : rulesResult.content}
+`;
+                    }
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to extract rules: ${error instanceof Error ? error.message : String(error)}`);
+                    rulesPrompt = `
+## Architectural Rules (failed to extract)
+Note: Could not extract architectural rules automatically. Manual rule validation may be needed.
+`;
+                }
+            }
+            // Generate TDD-focused todo creation prompt
+            const todoPrompt = `
+# TDD-Focused ADR Todo Generation Request
+
+## Step 1: File Discovery
+${adrFilesPrompt.prompt}
+${projectStructurePrompt}
+${rulesPrompt}
+
+## Step 2: TDD Todo Generation Analysis
+
+Once you have discovered and read the ADR files, please analyze them and generate a comprehensive TDD-focused todo.md file.
+
+## TDD Phase: ${phase}
+${phase === 'test' ? '**Focus on Phase 1: Mock Test Generation Only**' : ''}
+${phase === 'production' ? '**Focus on Phase 2: Production Code Implementation (assumes tests exist)**' : ''}
+${phase === 'both' ? '**Generate both Phase 1 (Tests) and Phase 2 (Production) tasks**' : ''}
+
+## Requirements
+
+1. **Extract Tasks**: Identify all implementation tasks from ADRs
+2. **TDD Approach**: For each task, create:
+   - Phase 1: Mock test specifications
+   - Phase 2: Production implementation tasks
+3. **ADR Linking**: ${linkAdrs ? 'Link related ADRs to create comprehensive system tests' : 'Focus on individual ADR tasks'}
+4. **Rules Integration**: ${includeRules ? `Include architectural rules validation in tests (source: ${ruleSource})` : 'Skip architectural rules validation'}
+5. **Categorize**: Group tasks by ADR and testing phase
+6. **Status Detection**: Determine task completion status
+7. **Progress Tracking**: Calculate overall progress for both test and implementation phases
+8. **Scope Filter**: ${scope === 'all' ? 'Include all tasks' : `Focus on ${scope} tasks only`}
+
+## TDD Todo.md Format
+
+\`\`\`markdown
+# TDD-Focused ADR Implementation Progress
+
+**Last Updated**: [Date]
+**Overall Progress**: [X]% Complete
+**Test Coverage**: [X]% Complete
+**Implementation Coverage**: [X]% Complete
+
+## Summary
+- Total ADRs: [count]
+- Total Tasks: [count] (Tests: [count], Implementation: [count])
+- Completed: [count]
+- In Progress: [count]
+- Pending: [count]
+
+## System Architecture Overview (from linked ADRs)
+[Brief summary of how all ADRs connect to form the complete system]
+
+## Phase 1: Test Generation Tasks
+
+### ADR-001: [Title]
+#### Test Specifications
+- [ ] TEST: Unit test for [component/function]
+  - Mock: [what to mock]
+  - Expected: [expected behavior]
+  - Coverage: [what this tests]
+- [ ] TEST: Integration test for [feature]
+  - Setup: [test environment]
+  - Scenario: [test scenario]
+  - Assertions: [what to verify]
+${includeRules ? `- [ ] RULE: Architectural rule validation test for [rule name]
+  - Validation: [what rule to check]
+  - Pattern: [validation pattern/regex]
+  - Expected: [compliant behavior]` : ''}
+
+### ADR-002: [Title]
+#### Test Specifications
+- [ ] TEST: [test description]
+${includeRules ? '- [ ] RULE: [rule validation test]' : ''}
+...
+
+## Phase 2: Production Implementation Tasks
+
+### ADR-001: [Title]
+#### Implementation Tasks (after tests pass)
+- [ ] IMPL: Implement [component/function]
+  - Precondition: Unit test for [component] exists
+  - Definition: [what to implement]
+  - Acceptance: All related tests pass
+${includeRules ? `  - Compliance: Must pass architectural rule validation` : ''}
+- [ ] IMPL: [implementation task]
 
 ### ADR-002: [Title]
-- [ ] Task 1 description
+#### Implementation Tasks
+- [ ] IMPL: [implementation description]
+${includeRules ? '  - Compliance: [specific rule requirements]' : ''}
 ...
+
+## ADR Dependencies and Links
+- ADR-001 → ADR-002: [relationship description]
+- ADR-002 → ADR-003: [relationship description]
+
+## Test-First Development Workflow
+1. Complete all Phase 1 tests for a component
+${includeRules ? '2. Complete architectural rule validation tests' : ''}
+${includeRules ? '3' : '2'}. Run tests (they should fail)
+${includeRules ? '4' : '3'}. Implement Phase 2 production code
+${includeRules ? '5' : '4'}. Run tests (they should pass)
+${includeRules ? '6. Validate architectural rule compliance' : ''}
+${includeRules ? '7' : '5'}. Refactor if needed while maintaining rule compliance
 \`\`\`
 
 Please provide:
 1. Comprehensive task extraction from all ADRs
-2. Status assessment for each task
-3. Progress calculation
-4. Prioritized task list
-5. Implementation recommendations
+2. Test specifications for each implementation task
+${includeRules ? '3. Architectural rule validation tests and compliance checks' : ''}
+${includeRules ? '4' : '3'}. Clear separation of test and implementation phases
+${includeRules ? '5' : '4'}. ADR relationship mapping for system-wide test coverage
+${includeRules ? '6' : '5'}. TDD workflow recommendations with rule compliance integration
 `;
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `ADR todo generation for: ${adrDirectory}\n\nPlease generate todo.md using the following prompt:\n\n${todoPrompt}`
-                    }
-                ]
-            };
+            // Execute the todo generation with AI if enabled, otherwise return prompt
+            const { executePromptWithFallback, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executePromptWithFallback(todoPrompt, 'Generate TDD-focused todo.md file from ADR analysis with test-first approach and system-wide coverage', {
+                temperature: 0.1,
+                maxTokens: 8000,
+                systemPrompt: `You are an expert in Test-Driven Development (TDD) and architectural implementation.
+Analyze the provided ADRs to extract actionable tasks following a strict TDD approach.
+
+Key responsibilities:
+1. For each implementation task, FIRST define the test specifications
+2. Create mock test descriptions that verify the expected behavior
+3. Link related ADRs to ensure comprehensive system test coverage
+4. Separate test generation (Phase 1) from production code (Phase 2)
+5. Ensure every production task has corresponding test coverage
+6. Map ADR dependencies to identify integration test requirements
+${includeRules ? '7. Include architectural rule validation in test specifications' : ''}
+${includeRules ? '8. Create compliance checks for extracted architectural rules' : ''}
+${includeRules ? '9. Ensure implementation tasks include rule compliance verification' : ''}
+
+Follow the TDD red-green-refactor cycle:
+- Red: Write failing tests first (Phase 1)${includeRules ? ' including rule validation tests' : ''}
+- Green: Implement minimal code to pass tests (Phase 2)
+- Refactor: Improve code while keeping tests green${includeRules ? ' and maintaining rule compliance' : ''}
+
+${includeRules ? 'The architectural rules provide constraints and patterns that must be validated in tests and followed in implementation.' : ''}
+
+The todo.md should serve as the glue connecting all ADRs into a cohesive, testable${includeRules ? ', rule-compliant' : ''} system.`,
+                responseFormat: 'text'
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful - return actual todo generation results
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# TDD-Focused ADR Todo Generation Results
+
+## Analysis Information
+- **ADR Directory**: ${adrDirectory}
+- **Scope**: ${scope}
+- **TDD Phase**: ${phase}
+- **ADR Linking**: ${linkAdrs ? 'Enabled' : 'Disabled'}
+- **Rules Integration**: ${includeRules ? `Enabled (${ruleSource})` : 'Disabled'}
+
+## AI-Generated TDD Todo Results
+
+${executionResult.content}
+
+## TDD Implementation Workflow
+
+### Phase 1: Test Generation (Red Phase)
+1. **Review Test Specifications**: Examine each test task for completeness
+2. **Create Mock Tests**: Implement test files with proper mocking
+3. **Define Assertions**: Ensure tests verify expected behavior
+4. **Run Tests**: Confirm all tests fail (red phase)
+
+### Phase 2: Production Implementation (Green Phase)
+1. **Implement Minimal Code**: Write just enough code to pass tests
+2. **Run Tests Again**: Verify tests now pass (green phase)
+3. **Check Coverage**: Ensure all ADR requirements are tested
+4. **Integration Testing**: Verify ADR interactions work correctly
+
+### Phase 3: Refactoring (Refactor Phase)
+1. **Improve Code Quality**: Refactor while keeping tests green
+2. **Update Documentation**: Keep ADRs and tests in sync
+3. **Performance Optimization**: Optimize without breaking tests
+
+## ADR System Integration
+
+The todo.md serves as the glue connecting all ADRs by:
+- **Mapping Dependencies**: Shows how ADRs relate to each other
+- **System-wide Coverage**: Ensures no gaps in test coverage
+- **Progress Tracking**: Monitors both test and implementation completion
+- **Working Environment**: Defines the expected system outcome
+
+## Integration Commands
+
+### Generate Test Phase Only:
+\`\`\`json
+{
+  "tool": "generate_adr_todo",
+  "args": {
+    "adrDirectory": "${adrDirectory}",
+    "phase": "test",
+    "linkAdrs": true,
+    "includeRules": true,
+    "ruleSource": "both"
+  }
+}
+\`\`\`
+
+### Generate Production Phase Only:
+\`\`\`json
+{
+  "tool": "generate_adr_todo",
+  "args": {
+    "adrDirectory": "${adrDirectory}",
+    "phase": "production",
+    "scope": "pending",
+    "includeRules": true
+  }
+}
+\`\`\`
+
+### Update Full TDD Todo with Rules:
+\`\`\`json
+{
+  "tool": "generate_adr_todo",
+  "args": {
+    "adrDirectory": "${adrDirectory}",
+    "phase": "both",
+    "linkAdrs": true,
+    "includeRules": true,
+    "ruleSource": "both"
+  }
+}
+\`\`\`
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `TDD-focused ADR todo generation for: ${adrDirectory}\n\nPhase: ${phase}\nADR Linking: ${linkAdrs ? 'Enabled' : 'Disabled'}\nRules Integration: ${includeRules ? `Enabled (${ruleSource})` : 'Disabled'}\nScope: ${scope}\n\nPlease generate a TDD-focused todo.md using the following prompt:\n\n${todoPrompt}`
+                        }
+                    ]
+                };
+            }
         }
         catch (error) {
             throw new McpAdrError(`Failed to generate ADR todo: ${error instanceof Error ? error.message : String(error)}`, 'GENERATION_ERROR');
         }
     }
+    async compareAdrProgress(args) {
+        const { todoPath = 'TODO.md', adrDirectory = this.config.adrDirectory, projectPath = this.config.projectPath, validationType = 'full', includeFileChecks = true, includeRuleValidation = true, deepCodeAnalysis = true, functionalValidation = true, strictMode = true } = args;
+        const { getAdrDirectoryPath } = await import('./utils/config.js');
+        const path = await import('path');
+        // Resolve paths
+        const absoluteTodoPath = path.resolve(projectPath, todoPath);
+        const absoluteAdrPath = adrDirectory ?
+            path.resolve(projectPath, adrDirectory) :
+            getAdrDirectoryPath(this.config);
+        this.logger.info(`Comparing ADR progress: TODO(${absoluteTodoPath}) vs ADRs(${absoluteAdrPath}) vs Environment(${projectPath})`);
+        try {
+            const { findFiles } = await import('./utils/file-system.js');
+            // Step 1: Discover TODO.md file
+            let todoPrompt = '';
+            if (validationType === 'full' || validationType === 'todo-only') {
+                try {
+                    const todoContent = await findFiles(projectPath, [todoPath], { includeContent: true });
+                    todoPrompt = `
+## TODO.md Analysis
+${todoContent.prompt}
+`;
+                }
+                catch (error) {
+                    todoPrompt = `
+## TODO.md Analysis
+Error: Could not read TODO.md file at ${absoluteTodoPath}
+`;
+                }
+            }
+            // Step 2: Discover ADR files
+            let adrPrompt = '';
+            if (validationType === 'full' || validationType === 'adr-only') {
+                const adrFiles = await findFiles(projectPath, [`${absoluteAdrPath}/**/*.md`], { includeContent: true });
+                adrPrompt = `
+## ADR Files Analysis
+${adrFiles.prompt}
+`;
+            }
+            // Step 3: Discover project environment
+            let environmentPrompt = '';
+            if (validationType === 'full' || validationType === 'environment-only') {
+                const includeContent = deepCodeAnalysis || functionalValidation;
+                const projectFiles = await findFiles(projectPath, [
+                    '**/*.{ts,js,py,java,cs,go,rb,php,swift,kt,rs,cpp,c,h,json,yaml,yml,md}',
+                    '!node_modules/**',
+                    '!dist/**',
+                    '!build/**',
+                    '!.git/**',
+                    '!coverage/**',
+                    '!.mcp-adr-cache/**'
+                ], { includeContent });
+                environmentPrompt = `
+## Project Environment Analysis
+${projectFiles.prompt}
+`;
+            }
+            // Step 4: Include architectural rules if requested
+            let rulesPrompt = '';
+            if (includeRuleValidation) {
+                try {
+                    const rulesResult = await this.generateRules({
+                        source: 'both',
+                        adrDirectory: adrDirectory,
+                        projectPath: projectPath,
+                        outputFormat: 'json'
+                    });
+                    if (rulesResult.content) {
+                        rulesPrompt = `
+## Architectural Rules Validation
+${Array.isArray(rulesResult.content) ? rulesResult.content.map((c) => c.text || c).join('\n') : rulesResult.content}
+`;
+                    }
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to extract rules for validation: ${error instanceof Error ? error.message : String(error)}`);
+                    rulesPrompt = `
+## Architectural Rules Validation
+Note: Could not extract architectural rules for validation.
+`;
+                }
+            }
+            // Generate comparison prompt
+            const comparisonPrompt = `
+# ADR Progress Validation Request
+
+## Validation Type: ${validationType}
+${todoPrompt}
+${adrPrompt}
+${environmentPrompt}
+${rulesPrompt}
+
+## Validation Requirements
+
+Please perform a comprehensive comparison and validation between the TODO.md, ADRs, and current project environment:
+
+### 1. TODO vs ADR Alignment
+- Verify that all tasks in TODO.md correspond to actual ADR requirements
+- Identify missing tasks that should be in TODO.md based on ADRs
+- Check for obsolete tasks that no longer align with current ADRs
+- Validate that task descriptions match ADR specifications
+
+### 2. Implementation Status Verification
+${includeFileChecks ? `- Check file existence for tasks marked as completed
+- Verify that implemented code matches task specifications
+- Identify discrepancies between TODO status and actual implementation
+- Validate that file structures align with ADR requirements` : '- File existence checks disabled'}
+
+${deepCodeAnalysis ? `### 2.1. Deep Code Analysis (Mock vs Production Detection)
+- **Mock Detection**: Identify placeholder functions, TODO comments, and stub implementations
+- **Production Readiness**: Verify code has actual business logic, not just interfaces
+- **Implementation Depth**: Check for proper error handling, edge cases, and real functionality
+- **Completeness Validation**: Ensure functions do more than return mock data or throw NotImplementedException` : ''}
+
+${functionalValidation ? `### 2.2. Functional Validation Against ADR Goals
+- **Goal Alignment**: Verify implementations actually achieve the architectural goals stated in ADRs
+- **Environment Testing**: Check if code can run in the intended environment described by ADRs
+- **Integration Verification**: Validate that components work together as architected
+- **Performance Requirements**: Verify non-functional requirements from ADRs are met` : ''}
+
+### 3. Environment vs ADR Compliance
+- Compare current project structure with ADR decisions
+- Identify technology choices that deviate from ADRs
+- Verify that architectural patterns are implemented as specified
+- Check for missing components or files required by ADRs
+
+${includeRuleValidation ? `### 4. Architectural Rule Compliance
+- Validate current code against extracted architectural rules
+- Identify rule violations in the existing codebase
+- Check if TODO tasks include necessary rule compliance steps
+- Verify that completed tasks maintain rule compliance` : ''}
+
+## Expected Output Format
+
+\`\`\`markdown
+# ADR Progress Validation Report
+
+**Validation Date**: [Date]
+**Validation Type**: ${validationType}
+**Project Path**: ${projectPath}
+
+## Summary
+- **Total ADRs**: [count]
+- **Total TODO Tasks**: [count] 
+- **Completed Tasks**: [count]
+- **Alignment Score**: [percentage]%
+- **Compliance Score**: [percentage]%
+
+## Alignment Analysis
+
+### ✅ Properly Aligned Tasks
+- [Task name]: Correctly implements [ADR reference]
+- [Task name]: Status verified, implementation complete
+
+### ⚠️ Misaligned Tasks  
+- [Task name]: Description doesn't match [ADR reference]
+- [Task name]: Status marked complete but implementation missing
+
+### ❌ Missing Tasks
+- [Missing task]: Required by [ADR reference] but not in TODO
+- [Missing task]: Implementation needed for [specific requirement]
+
+### 🗑️ Obsolete Tasks
+- [Task name]: No longer needed due to [ADR change/superseded]
+
+## Implementation Status
+
+### File Existence Validation
+${includeFileChecks ? `- ✅ [filename]: Exists and matches expectations
+- ❌ [filename]: Missing but marked as implemented
+- ⚠️ [filename]: Exists but doesn't match specifications` : '- File checks disabled'}
+
+${deepCodeAnalysis ? `### Mock vs Production Code Analysis
+- ✅ **Production Ready**: [component] - Full implementation with business logic
+- ⚠️ **Partial Implementation**: [component] - Some functionality missing or incomplete
+- ❌ **Mock/Stub Only**: [component] - Contains only placeholders, interfaces, or TODO comments
+- 🔍 **Requires Verification**: [component] - Implementation exists but needs deeper inspection
+
+#### Mock Detection Indicators Found:
+- TODO comments: [count] instances
+- Placeholder functions: [count] instances  
+- NotImplementedException: [count] instances
+- Mock return values: [count] instances
+- Empty function bodies: [count] instances` : ''}
+
+${functionalValidation ? `### Functional Validation Results
+- ✅ **ADR Goal Achieved**: [goal] - Implementation fully meets architectural objective
+- ⚠️ **Partial Goal Achievement**: [goal] - Implementation partially meets requirements
+- ❌ **Goal Not Met**: [goal] - Implementation doesn't achieve stated ADR objective
+- 🚫 **Environment Incompatible**: [component] - Code won't run in target environment
+
+#### Environment Readiness Assessment:
+- **Dependency Management**: [status] - All required dependencies available
+- **Configuration**: [status] - Environment-specific config properly handled
+- **Integration Points**: [status] - External system connections functional
+- **Performance Criteria**: [status] - Meets ADR performance requirements` : ''}
+
+### Code Implementation Review
+- [Component]: Implementation status and quality assessment
+- [Feature]: Comparison with ADR requirements
+
+## Environment Compliance
+
+### Architecture Alignment
+- ✅ [Decision]: Correctly implemented
+- ❌ [Decision]: Not implemented or incorrectly implemented
+- ⚠️ [Decision]: Partially implemented
+
+### Technology Stack Validation
+- [Technology]: Usage aligns with [ADR reference]
+- [Technology]: Deviation from [ADR decision]
+
+${includeRuleValidation ? `## Rule Compliance Analysis
+
+### Rule Violations
+- [Rule name]: [violation description and location]
+- [Rule name]: [compliance status]
+
+### Compliance Recommendations
+- [Recommendation]: Steps to achieve compliance
+- [Fix]: Specific changes needed` : ''}
+
+## Recommendations
+
+### High Priority Actions
+1. [Action]: [Reason and expected outcome]
+2. [Action]: [Priority justification]
+
+### Medium Priority Actions
+1. [Action]: [Impact and timeline]
+
+### Low Priority Actions
+1. [Action]: [Optional improvements]
+
+## Next Steps
+1. Address high-priority alignment issues
+2. Update TODO.md with missing tasks
+3. Verify implementation of completed tasks
+4. Resolve rule compliance violations
+\`\`\`
+
+Please provide a comprehensive validation report that helps ensure the TODO.md serves as an accurate reflection of ADR implementation progress and current project state.
+`;
+            // Execute the comparison with AI if enabled, otherwise return prompt
+            const { executePromptWithFallback, formatMCPResponse } = await import('./utils/prompt-execution.js');
+            const executionResult = await executePromptWithFallback(comparisonPrompt, 'Compare TODO.md progress against ADRs and project environment for validation and alignment', {
+                temperature: 0.1,
+                maxTokens: 10000,
+                systemPrompt: `You are an expert project auditor specializing in ADR implementation validation.
+Your role is to ensure that TODO lists accurately reflect ADR requirements and implementation reality.
+
+Key responsibilities:
+1. Cross-reference TODO tasks with ADR specifications
+2. Verify implementation status against actual project state
+3. Identify gaps, misalignments, and obsolete items
+4. Validate architectural rule compliance
+5. Provide actionable recommendations for improvement
+
+${strictMode ? `## STRICT VALIDATION MODE ENABLED
+
+**CRITICAL**: Apply maximum scrutiny to distinguish between mock and production code:
+
+### Mock Detection (Mark as ❌ or ⚠️):
+- Functions that only return hardcoded values or throw NotImplementedException
+- Classes with empty method bodies or only getter/setter stubs  
+- TODO comments indicating incomplete work
+- Interface definitions without concrete implementations
+- Test data or placeholder responses instead of real business logic
+- Comments like "// TODO: implement this" or "// placeholder"
+
+### Production Verification (Only mark ✅ if ALL criteria met):
+- Complete business logic implementation with proper error handling
+- Real data processing, not just mock responses
+- Proper integration with external systems/databases as specified in ADRs
+- Environment-specific configuration and dependency management
+- Performance and security requirements from ADRs actually implemented
+
+### ADR Goal Achievement (Be highly critical):
+- Implementation MUST actually solve the architectural problem stated in the ADR
+- Code MUST run successfully in the intended environment described by ADRs
+- Non-functional requirements (performance, security, scalability) MUST be demonstrably met
+- Integration points MUST be functional, not just stubbed
+
+**DO NOT** be lenient about completion status. If there's ANY doubt about production readiness, mark as incomplete.` : ''}
+
+Focus on accuracy, completeness, and practical next steps.
+Be thorough but concise in your analysis.
+Prioritize findings by impact and urgency.
+${strictMode ? 'Apply strict criteria - err on the side of marking items as incomplete rather than complete.' : ''}`,
+                responseFormat: 'text'
+            });
+            if (executionResult.isAIGenerated) {
+                // AI execution successful
+                return formatMCPResponse({
+                    ...executionResult,
+                    content: `# ADR Progress Validation Results
+
+## Validation Information
+- **TODO Path**: ${todoPath}
+- **ADR Directory**: ${adrDirectory}
+- **Project Path**: ${projectPath}
+- **Validation Type**: ${validationType}
+- **File Checks**: ${includeFileChecks ? 'Enabled' : 'Disabled'}
+- **Rule Validation**: ${includeRuleValidation ? 'Enabled' : 'Disabled'}
+- **Deep Code Analysis**: ${deepCodeAnalysis ? 'Enabled' : 'Disabled'}
+- **Functional Validation**: ${functionalValidation ? 'Enabled' : 'Disabled'}
+- **Strict Mode**: ${strictMode ? 'Enabled - High scrutiny for mock vs production' : 'Disabled'}
+
+## AI-Generated Validation Report
+
+${executionResult.content}
+
+## Integration Commands
+
+### Regenerate TODO after fixes:
+\`\`\`json
+{
+  "tool": "generate_adr_todo",
+  "args": {
+    "adrDirectory": "${adrDirectory}",
+    "phase": "both",
+    "linkAdrs": true,
+    "includeRules": ${includeRuleValidation}
+  }
+}
+\`\`\`
+
+### Validate architectural rules:
+\`\`\`json
+{
+  "tool": "validate_rules",
+  "args": {
+    "projectPath": "${projectPath}",
+    "adrDirectory": "${adrDirectory}"
+  }
+}
+\`\`\`
+
+### Re-run strict validation after updates:
+\`\`\`json
+{
+  "tool": "compare_adr_progress",
+  "args": {
+    "todoPath": "${todoPath}",
+    "adrDirectory": "${adrDirectory}",
+    "validationType": "full",
+    "deepCodeAnalysis": true,
+    "functionalValidation": true,
+    "strictMode": true
+  }
+}
+\`\`\`
+
+### Quick validation (environment only):
+\`\`\`json
+{
+  "tool": "compare_adr_progress",
+  "args": {
+    "validationType": "environment-only",
+    "functionalValidation": true,
+    "strictMode": false
+  }
+}
+\`\`\`
+`,
+                });
+            }
+            else {
+                // Fallback to prompt-only mode
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `ADR progress comparison for: ${todoPath}\n\nValidation Type: ${validationType}\nFile Checks: ${includeFileChecks ? 'Enabled' : 'Disabled'}\nRule Validation: ${includeRuleValidation ? 'Enabled' : 'Disabled'}\nDeep Code Analysis: ${deepCodeAnalysis ? 'Enabled' : 'Disabled'}\nFunctional Validation: ${functionalValidation ? 'Enabled' : 'Disabled'}\nStrict Mode: ${strictMode ? 'Enabled' : 'Disabled'}\n\nPlease perform ADR progress validation using the following prompt:\n\n${comparisonPrompt}`
+                        }
+                    ]
+                };
+            }
+        }
+        catch (error) {
+            throw new McpAdrError(`Failed to compare ADR progress: ${error instanceof Error ? error.message : String(error)}`, 'VALIDATION_ERROR');
+        }
+    }
     /**
      * Content masking tool implementations
      */
@@ -1322,29 +3340,55 @@ Please provide:
             const { clearCache, getCacheStats, cleanupCache, invalidateCache } = await import('./utils/cache.js');
             switch (action) {
                 case 'clear': {
-                    await clearCache();
+                    const clearPrompt = await clearCache();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: '✅ Cache cleared successfully. All cached resources have been removed.'
+                                text: `# Cache Clear Operation
+
+## AI Delegation Required
+
+Please execute the following cache clearing operation:
+
+${clearPrompt.prompt}
+
+## Implementation Instructions
+
+${clearPrompt.instructions}
+
+## Expected Result
+
+After successful execution, all cache entries will be removed while preserving the cache directory structure and metadata.json file.`
                             }
                         ]
                     };
                 }
                 case 'stats': {
-                    const stats = await getCacheStats();
+                    const statsPrompt = await getCacheStats();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `# Cache Statistics
+                                text: `# Cache Statistics Collection
 
-## Overview
-- **Total Entries**: ${stats.totalEntries}
-- **Total Size**: ${(stats.totalSize / 1024).toFixed(2)} KB
-- **Oldest Entry**: ${stats.oldestEntry || 'None'}
-- **Newest Entry**: ${stats.newestEntry || 'None'}
+## AI Delegation Required
+
+Please execute the following cache statistics collection operation:
+
+${statsPrompt.prompt}
+
+## Implementation Instructions
+
+${statsPrompt.instructions}
+
+## Expected Information
+
+The AI agent will provide:
+- **Total Entries**: Number of cache files
+- **Total Size**: Combined size of all cache files
+- **Oldest Entry**: Cache key of the oldest entry
+- **Newest Entry**: Cache key of the newest entry
 
 ## Cache Directory
 \`.mcp-adr-cache/\`
@@ -1358,19 +3402,32 @@ Please provide:
 Use \`manage_cache\` tool with different actions:
 - \`clear\`: Remove all cache entries
 - \`cleanup\`: Remove expired entries only
-- \`invalidate\`: Remove specific cache entry
-`
+- \`invalidate\`: Remove specific cache entry`
                             }
                         ]
                     };
                 }
                 case 'cleanup': {
-                    const cleanedCount = await cleanupCache();
+                    const cleanupPrompt = await cleanupCache();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `✅ Cache cleanup completed. Removed ${cleanedCount} expired entries.`
+                                text: `# Cache Cleanup Operation
+
+## AI Delegation Required
+
+Please execute the following cache cleanup operation:
+
+${cleanupPrompt.prompt}
+
+## Implementation Instructions
+
+${cleanupPrompt.instructions}
+
+## Expected Result
+
+The AI agent will remove expired cache entries and provide a count of cleaned files.`
                             }
                         ]
                     };
@@ -1379,12 +3436,28 @@ Use \`manage_cache\` tool with different actions:
                     if (!key) {
                         throw new McpAdrError('Cache key is required for invalidate action', 'INVALID_INPUT');
                     }
-                    await invalidateCache(key);
+                    const invalidatePrompt = await invalidateCache(key);
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `✅ Cache entry invalidated: ${key}`
+                                text: `# Cache Invalidation Operation
+
+## AI Delegation Required
+
+Please execute the following cache invalidation operation:
+
+${invalidatePrompt.prompt}
+
+## Implementation Instructions
+
+${invalidatePrompt.instructions}
+
+## Target Cache Entry
+
+**Cache Key**: ${key}
+
+The AI agent will safely remove the specified cache entry.`
                             }
                         ]
                     };
@@ -1497,6 +3570,165 @@ ${newConfig.enabled ?
             throw new McpAdrError(`Output masking configuration failed: ${error instanceof Error ? error.message : String(error)}`, 'CONFIG_ERROR');
         }
     }
+    /**
+     * Helper method to get domains based on PRD type
+     */
+    getPrdTypeDomains(prdType) {
+        const domainMap = {
+            'web-application': ['api-design', 'frontend-architecture', 'database-design', 'security'],
+            'mobile-app': ['mobile-architecture', 'api-design', 'performance-optimization', 'security'],
+            'microservices': ['microservices', 'api-design', 'distributed-systems', 'database-design'],
+            'data-platform': ['database-design', 'data-architecture', 'performance-optimization', 'scalability'],
+            'api-service': ['api-design', 'microservices', 'security', 'performance-optimization'],
+            'general': ['api-design', 'database-design', 'security']
+        };
+        return domainMap[prdType] || domainMap['general'] || ['api-design', 'database-design', 'security'];
+    }
+    /**
+     * Helper method to get domains for ecosystem analysis based on technology focus
+     */
+    getEcosystemAnalysisDomains(technologyFocus) {
+        // Base domains for ecosystem analysis
+        const baseDomains = ['api-design', 'database-design', 'security', 'performance-optimization'];
+        // Technology-specific domain mapping
+        const technologyDomainMap = {
+            'react': ['frontend-architecture', 'web-applications'],
+            'vue': ['frontend-architecture', 'web-applications'],
+            'angular': ['frontend-architecture', 'web-applications'],
+            'node': ['api-design', 'microservices'],
+            'express': ['api-design', 'web-applications'],
+            'fastify': ['api-design', 'performance-optimization'],
+            'nestjs': ['api-design', 'microservices'],
+            'spring': ['api-design', 'microservices'],
+            'django': ['api-design', 'web-applications'],
+            'flask': ['api-design', 'web-applications'],
+            'rails': ['api-design', 'web-applications'],
+            'laravel': ['api-design', 'web-applications'],
+            'docker': ['containerization', 'microservices'],
+            'kubernetes': ['containerization', 'distributed-systems'],
+            'mongodb': ['database-design', 'data-architecture'],
+            'postgresql': ['database-design', 'data-architecture'],
+            'mysql': ['database-design', 'data-architecture'],
+            'redis': ['database-design', 'performance-optimization'],
+            'elasticsearch': ['database-design', 'data-architecture'],
+            'kafka': ['distributed-systems', 'data-architecture'],
+            'rabbitmq': ['distributed-systems', 'microservices'],
+            'aws': ['cloud-architecture', 'scalability'],
+            'azure': ['cloud-architecture', 'scalability'],
+            'gcp': ['cloud-architecture', 'scalability'],
+            'terraform': ['infrastructure-as-code', 'cloud-architecture'],
+            'ansible': ['infrastructure-as-code', 'automation'],
+            'jenkins': ['ci-cd', 'automation'],
+            'github-actions': ['ci-cd', 'automation'],
+            'gitlab-ci': ['ci-cd', 'automation']
+        };
+        // Collect domains based on technology focus
+        const technologyDomains = new Set();
+        for (const tech of technologyFocus) {
+            const techLower = tech.toLowerCase();
+            const domains = technologyDomainMap[techLower];
+            if (domains) {
+                domains.forEach(domain => technologyDomains.add(domain));
+            }
+        }
+        // Combine base domains with technology-specific domains
+        const allDomains = [...baseDomains, ...Array.from(technologyDomains)];
+        // Remove duplicates and limit to reasonable number
+        const uniqueDomains = [...new Set(allDomains)];
+        // Return up to 6 most relevant domains
+        return uniqueDomains.slice(0, 6);
+    }
+    /**
+     * Helper method to create base ADR generation prompt
+     */
+    createBaseAdrPrompt(prdPath, outputDirectory, knowledgeContext) {
+        return `
+# Enhanced ADR Generation from PRD Request
+
+This is a comprehensive prompt-driven ADR generation process enhanced with domain knowledge and optimized prompting.
+
+${knowledgeContext}
+
+## Step 1: File Validation
+Please verify that the PRD file exists at: ${prdPath}
+
+## Step 2: PRD Content Reading
+Read and analyze the PRD content from: ${prdPath}
+
+## Step 3: Enhanced ADR Generation and Creation
+
+Once you have successfully read the PRD content, analyze it using the domain knowledge above and generate Architectural Decision Records (ADRs).
+
+### Enhanced Analysis Requirements
+
+1. **Extract Key Decisions**: Identify all architectural decisions implied or stated in the PRD
+2. **Apply Domain Knowledge**: Use the generated domain knowledge to enhance decision analysis
+3. **Decision Categorization**: Group decisions by:
+   - Technology stack choices (informed by domain best practices)
+   - Architectural patterns (leveraging domain-specific patterns)
+   - Infrastructure decisions (considering domain requirements)
+   - Security considerations (applying domain security knowledge)
+   - Performance requirements (using domain performance insights)
+   - Integration approaches (following domain integration patterns)
+
+### Enhanced ADR Generation Requirements
+
+1. **Follow ADR Format**: Use standard ADR template with domain-enhanced content
+2. **Number Sequentially**: Use format 001-decision-title.md, 002-next-decision.md, etc.
+3. **Output Directory**: Place ADRs in ${outputDirectory}/
+4. **Domain Context**: Include relevant domain knowledge in each ADR
+5. **File Creation**: Generate file creation prompts for each ADR
+
+### Enhanced ADR Template Format
+
+\`\`\`markdown
+# [Number]. [Title]
+
+**Status**: [Proposed/Accepted/Deprecated/Superseded]
+**Date**: [YYYY-MM-DD]
+**Domain**: [Relevant domain from knowledge enhancement]
+
+## Context
+[Describe the context and problem statement from PRD, enhanced with domain knowledge]
+
+## Decision
+[Describe the architectural decision, informed by domain best practices]
+
+## Consequences
+[Describe positive and negative consequences, considering domain-specific implications]
+
+## Domain Considerations
+[Specific considerations from the domain knowledge that influenced this decision]
+
+## Implementation Plan
+[Steps to implement this decision, leveraging domain expertise]
+
+## Related PRD Sections
+[Reference specific sections from the PRD that led to this decision]
+
+## Domain References
+[References to domain knowledge that informed this decision]
+\`\`\`
+
+### Expected Enhanced Output
+
+Please provide:
+1. **File Validation Results**: Confirmation that PRD file exists and is readable
+2. **PRD Content Summary**: Brief summary enhanced with domain context
+3. **Domain Analysis**: How domain knowledge applies to this PRD
+4. **Identified Decisions**: List of all architectural decisions with domain context
+5. **Generated ADRs**: Complete enhanced ADR content for each decision
+6. **File Creation Plan**: File names, directory structure, and creation order
+7. **Implementation Priority**: Recommended order considering domain best practices
+
+### Quality Assurance with Domain Enhancement
+
+- Ensure each ADR leverages relevant domain knowledge
+- Verify decisions align with domain best practices
+- Check that domain considerations are properly documented
+- Validate that ADR content is enhanced beyond basic analysis
+`;
+    }
     /**
      * ADR suggestion tool implementations
      */
@@ -1572,16 +3804,16 @@ ${newConfig.enabled ?
         }
         catch (error) {
             // If masking fails, log warning and return original response
-            console.warn('Output masking failed:', error);
+            // Log to stderr to avoid corrupting MCP protocol
+            console.error('[WARN] Output masking failed:', error);
             return response;
         }
     }
     /**
-     * Read MCP resource with caching
+     * Read MCP resource with prompt-driven caching
      */
     async readResource(uri) {
         try {
-            const { getCachedOrGenerate } = await import('./utils/cache.js');
             // Parse URI to determine resource type and parameters
             const url = new globalThis.URL(uri);
             const resourceType = url.pathname.replace('/', '');
@@ -1590,7 +3822,8 @@ ${newConfig.enabled ?
                 case 'architectural_knowledge_graph': {
                     const { generateArchitecturalKnowledgeGraph } = await import('./resources/index.js');
                     const projectPath = params['projectPath'] || process.cwd();
-                    const result = await getCachedOrGenerate(`knowledge-graph:${projectPath}`, () => generateArchitecturalKnowledgeGraph(projectPath), { ttl: 3600 });
+                    // Generate resource directly (caching is now handled through AI delegation)
+                    const result = await generateArchitecturalKnowledgeGraph(projectPath);
                     return {
                         contents: [
                             {
@@ -1605,7 +3838,8 @@ ${newConfig.enabled ?
                     const { generateAnalysisReport } = await import('./resources/index.js');
                     const projectPath = params['projectPath'] || process.cwd();
                     const focusAreas = params['focusAreas'] ? params['focusAreas'].split(',') : undefined;
-                    const result = await getCachedOrGenerate(`analysis-report:${projectPath}:${focusAreas?.join(',') || ''}`, () => generateAnalysisReport(projectPath, focusAreas), { ttl: 1800 });
+                    // Generate resource directly (caching is now handled through AI delegation)
+                    const result = await generateAnalysisReport(projectPath, focusAreas);
                     return {
                         contents: [
                             {
@@ -1618,8 +3852,14 @@ ${newConfig.enabled ?
                 }
                 case 'adr_list': {
                     const { generateAdrList } = await import('./resources/index.js');
-                    const adrDirectory = params['adrDirectory'] || 'docs/adrs';
-                    const result = await getCachedOrGenerate(`adr-list:${adrDirectory}`, () => generateAdrList(adrDirectory), { ttl: 900 });
+                    const { getAdrDirectoryPath } = await import('./utils/config.js');
+                    const path = await import('path');
+                    // Use absolute ADR path relative to project
+                    const absoluteAdrPath = params['adrDirectory'] ?
+                        path.resolve(this.config.projectPath, params['adrDirectory']) :
+                        getAdrDirectoryPath(this.config);
+                    // Generate resource directly (caching is now handled through AI delegation)
+                    const result = await generateAdrList(absoluteAdrPath, this.config.projectPath);
                     return {
                         contents: [
                             {
@@ -1713,7 +3953,11 @@ Examples:
     }
 }
 // Start the server if this file is run directly
-if (import.meta.url === `file://${process.argv[1]}`) {
+// Jest-compatible check: avoid import.meta.url which Jest cannot handle
+// Handle both direct execution and npm global package symlinks
+if (process.argv[1] && (process.argv[1].endsWith('index.js') ||
+    process.argv[1].endsWith('index.ts') ||
+    process.argv[1].endsWith('mcp-adr-analysis-server'))) {
     main().catch((error) => {
         console.error('Unhandled error:', error);
         process.exit(1);