🤖 AI-Powered Workflow Orchestration Guide

This guide covers the advanced AI-powered features of the MCP ADR Analysis Server, including intelligent tool orchestration, human override capabilities, and systematic troubleshooting workflows.

🧠 Overview of AI-Powered Features

The MCP ADR Analysis Server includes several AI-powered tools that leverage OpenRouter.ai and advanced prompt engineering to provide intelligent workflow automation:

Core AI Tools

• Tool Chain Orchestrator - Dynamic tool sequencing based on user intent
• Troubleshooting Workflow - Systematic failure analysis with test plan generation
• Smart Project Scoring - Cross-tool health assessment with AI optimization

Key Benefits

• Hallucination Prevention - Reality checks and structured planning prevent AI confusion
• Dynamic Workflow Generation - AI analyzes context to generate optimal tool sequences
• Intelligent Fallbacks - Template-based approaches when AI services are unavailable
• Cross-Tool Coordination - Tools work together for comprehensive project insights

🔗 Tool Chain Orchestrator

The Tool Chain Orchestrator is the central AI-powered planning system that generates intelligent tool execution sequences.

Core Operations

Generate Execution Plan

{
  "operation": "generate_plan",
  "userRequest": "Complete architectural analysis and generate implementation roadmap",
  "includeContext": true,
  "optimizeFor": "comprehensive"
}

What it does:

• Analyzes user intent using OpenRouter.ai
• Generates structured tool execution sequences
• Provides dependency analysis and execution order
• Includes confidence scoring and alternative approaches

Analyze User Intent

{
  "operation": "analyze_intent",
  "userRequest": "Help me understand why my deployment is failing",
  "extractGoals": true
}

Use Cases:

• Understanding complex user requests
• Goal extraction from natural language
• Intent classification for workflow selection

Suggest Relevant Tools

{
  "operation": "suggest_tools",
  "userRequest": "I need to improve my project's architectural documentation",
  "maxSuggestions": 5
}

Common Workflow Patterns

When LLMs get confused or for systematic workflows, use these proven tool sequences:

Complete Project Analysis

Tools: analyze_project_ecosystem → discover_existing_adrs → suggest_adrs → smart_score

Generate Documentation

Tools: generate_adr_todo → generate_deployment_guidance → generate_rules

Security Audit and Fix

Tools: analyze_content_security → suggest_adrs → generate_rules → validate_rules

Deployment Readiness

Tools: compare_adr_progress → smart_score → generate_deployment_guidance → smart_git_push

Systematic Troubleshooting

Tools: troubleshoot_guided_workflow → smart_score → compare_adr_progress

Complete TODO Management

Tools: generate_adr_todo → manage_todo → compare_adr_progress → smart_score

Advanced Features

Reality Check for Hallucination Detection

{
  "operation": "reality_check",
  "sessionContext": "Previous conversation context",
  "detectConfusion": true
}

Hallucination Indicators:

• Repetitive tool suggestions
• Circular reasoning patterns
• Requests for non-existent tools
• Inconsistent parameter suggestions

Session Guidance for Long Conversations

{
  "operation": "session_guidance",
  "conversationLength": "long",
  "provideSummary": true
}

Provides:

• Conversation summary and progress
• Suggested next steps
• Warning about potential confusion
• Reset recommendations

🚨 Human Override System

The Human Override system forces AI-powered planning when LLMs get confused or stuck in loops.

When to Use Human Override

Indicators you need human override:

• LLM asking repetitive questions
• Circular conversation patterns
• LLM claiming tools don't exist
• Inconsistent or contradictory suggestions
• LLM seems "stuck" or confused

Core Operations

Force AI Planning

{
  "taskDescription": "Set up complete ADR infrastructure with deployment pipeline",
  "forceExecution": true,
  "includeContext": true
}

What it does:

• Bypasses current LLM confusion
• Forces fresh AI analysis through OpenRouter.ai
• Generates structured execution plans
• Provides clear command schemas for LLM consumption

Extract Goals from Natural Language

{
  "taskDescription": "The build is broken and tests are failing, need to fix everything",
  "forceExecution": true,
  "extractGoals": true
}

Goal Extraction Example:

• Input: "The build is broken and tests are failing, need to fix everything"
• Extracted Goals: ["Fix build issues", "Resolve test failures", "Validate system stability"]

Integration with Knowledge Graph

The Human Override system integrates with the Knowledge Graph to:

• Track human intervention patterns
• Record forced execution contexts
• Analyze effectiveness of override strategies
• Provide analytics on LLM confusion patterns

🔧 Troubleshooting Guided Workflow

Systematic problem-solving with ADR/TODO alignment and AI-powered test plan generation.

Supported Failure Types

• test_failure - Unit/integration test failures
• deployment_failure - Production deployment issues
• build_failure - Compilation or build process failures
• runtime_error - Application runtime exceptions
• performance_issue - Performance degradation problems
• security_issue - Security vulnerabilities or breaches

Core Operations

Analyze Failure

{
  "operation": "analyze_failure",
  "failureType": "deployment_failure",
  "description": "Kubernetes deployment failing with connection timeouts",
  "severity": "high",
  "context": {
    "environment": "production",
    "lastWorkingVersion": "v2.1.0",
    "errorDetails": "Connection timeout after 30s"
  }
}

Generate AI-Powered Test Plan

{
  "operation": "generate_test_plan",
  "failureType": "build_failure",
  "description": "TypeScript compilation failing after dependency update",
  "severity": "medium"
}

AI-Generated Output:

{
  "testPlan": {
    "diagnosticCommands": [
      "npx tsc --noEmit --listFiles",
      "npm ls typescript",
      "npx tsc --showConfig"
    ],
    "validationSteps": [
      "Verify TypeScript version compatibility",
      "Check for conflicting type definitions",
      "Validate tsconfig.json configuration"
    ],
    "expectedOutcomes": [
      "TypeScript version should be compatible with dependencies",
      "No duplicate type definitions should exist",
      "Configuration should match project requirements"
    ]
  }
}

Full Workflow Integration

{
  "operation": "full_workflow",
  "failureType": "security_issue",
  "description": "Potential sensitive data exposure in logs",
  "severity": "critical"
}

Full Workflow Steps:

1. Analyze failure with AI-powered assessment
2. Generate specific test plan with commands
3. Execute analyze_content_security for sensitive data detection
4. Run suggest_adrs for security-related architectural decisions
5. Use generate_rules to create security compliance rules
6. Execute smart_score to assess security posture improvement

📊 Smart Project Scoring System

Cross-tool coordination for comprehensive project health assessment.

Core Operations

Recalculate All Scores

{
  "operation": "recalculate_scores",
  "updateSources": true,
  "includeOptimization": true
}

Synchronize Cross-Tool Scores

{
  "operation": "sync_scores",
  "rebalanceWeights": true,
  "focusAreas": ["todo", "architecture", "security", "deployment"]
}

Comprehensive Health Diagnostics

{
  "operation": "diagnose_scores",
  "includeRecommendations": true,
  "dataFreshness": true
}

AI-Driven Weight Optimization

{
  "operation": "optimize_weights",
  "projectType": "web-application",
  "optimizationGoal": "deployment_readiness"
}

Score Components

Default Scoring Weights:

• TODO Completion: 30%
• Architecture Compliance: 25%
• Security Posture: 20%
• Deployment Readiness: 15%
• Code Quality: 10%

Project-Specific Optimization:

• Startup Projects: Higher weight on TODO completion and deployment readiness
• Enterprise Applications: Higher weight on security and architecture compliance
• Open Source: Higher weight on code quality and documentation

🔄 Best Practices for AI-Powered Workflows

1. Start with Tool Orchestration

For complex tasks, always begin with:

{
  "operation": "generate_plan",
  "userRequest": "Your specific goal",
  "includeContext": true
}

2. Use Human Override When Stuck

If conversation becomes circular:

{
  "taskDescription": "Clear description of what you want to achieve",
  "forceExecution": true
}

3. Leverage Troubleshooting for Problems

For any failure or issue:

{
  "operation": "full_workflow",
  "failureType": "appropriate_type",
  "description": "Specific problem description"
}

4. Monitor Health Continuously

Regular health checks:

{
  "operation": "diagnose_scores",
  "includeRecommendations": true
}

5. Validate with Reality Checks

Prevent AI confusion:

{
  "operation": "reality_check",
  "detectConfusion": true
}

🚀 Advanced Integration Patterns

Workflow Chaining

Combine AI-powered tools for comprehensive workflows:

1. Initial Planning: tool_chain_orchestrator generates plan
2. Execution: Follow generated tool sequence
3. Validation: smart_score assesses results
4. Troubleshooting: troubleshoot_guided_workflow if issues arise
5. Restart: Start fresh session if confusion occurs

Context Preservation

Maintain context across tool executions:

• Include conversation history in orchestration requests
• Use knowledge graph to track intent progressions
• Leverage smart scoring for continuous assessment

Fallback Strategies

Always have fallbacks when AI is unavailable:

• Predefined task patterns in orchestrator
• Template-based test plans in troubleshooting
• Manual workflow guides for common scenarios

🎯 Common Scenarios and Solutions

Scenario 1: LLM Keeps Asking Same Questions

Solution: Use Human Override

{
  "taskDescription": "Complete architectural analysis for microservices project",
  "forceExecution": true
}

Scenario 2: Complex Multi-Step Task

Solution: Use Tool Orchestration

{
  "operation": "generate_plan",
  "userRequest": "Migrate monolith to microservices with full documentation",
  "optimizeFor": "comprehensive"
}

Scenario 3: Deployment Keeps Failing

Solution: Use Troubleshooting Workflow

{
  "operation": "full_workflow",
  "failureType": "deployment_failure",
  "description": "Specific deployment error details"
}

Scenario 4: Project Health Declining

Solution: Use Smart Scoring Diagnostics

{
  "operation": "diagnose_scores",
  "includeRecommendations": true,
  "focusAreas": ["todo", "architecture", "deployment"]
}

🔮 Future Enhancements

Planned AI Improvements

1. Enhanced Hallucination Detection - More sophisticated confusion pattern recognition
2. Learning from Patterns - AI learns from successful workflow patterns
3. Cross-Project Insights - Share knowledge across different projects
4. Advanced Context Understanding - Better long-term conversation context
5. Predictive Troubleshooting - Anticipate issues before they occur

Integration Roadmap

• CI/CD Integration - Automated workflow orchestration in pipelines
• IDE Extensions - Real-time AI guidance during development
• Team Collaboration - Shared AI insights and workflow patterns
• Advanced Analytics - Project health prediction and optimization

---

Need Help?

• Check the main README for basic setup
• Review specific tool guides for detailed parameters
• Open an issue on GitHub for AI-related problems