AutoDocs MCP Server

# Workflow Planning Assistant: Revised Implementation Plan ## Executive Summary ### Vision Statement (Revised) Transform the AutoDocs MCP ecosystem from individual specialized agents into an intelligent **Workflow Planning Assistant** that analyzes user requests, suggests optimal task sequences, and provides guided execution support while respecting Claude Agents/hooks platform limitations. ### Critical Constraint Acknowledgment Based on expert consultation feedback, a full TASK_GRAPH_SYSTEM as originally specified is **NOT technically feasible** with Claude Agents/hooks only. This revised plan implements a **Workflow Planning Assistant** approach that works within platform constraints while delivering meaningful user value. ### Revised Strategic Objectives 1. **Intelligent Task Analysis**: Analyze complex user requests and suggest optimal task breakdown 2. **Guided Workflow Assistance**: Provide step-by-step guidance rather than automatic orchestration 3. **Context Continuity**: Maintain workflow context across sequential agent interactions 4. **Pattern Recognition**: Learn from successful workflows to improve future recommendations 5. **Backward Compatibility**: Enhance existing agent capabilities without disruption ### Realistic Success Criteria - **30% reduction** in multi-step task completion time through better planning - **80% user satisfaction** with workflow guidance and recommendations - **Zero regression** in individual agent performance - **100% reliability** in workflow state management using file-based persistence - **3-5 sequential tasks** maximum per workflow (platform constraint) ## Technical Constraints & Realistic Scope ### Claude Agents/hooks Platform Limitations #### Critical Technical Constraints 1. **No True Multi-Agent Orchestration**: Claude Agents/hooks cannot support real concurrent multi-agent execution 2. **File-Based State Only**: Limited to JSON file persistence with no transactional guarantees 3. **Single Session Limitation**: Workflows cannot persist across Claude Code sessions 4. **No Background Processing**: All operations must complete within request-response cycles 5. **Memory Constraints**: Context must fit within single agent token limits #### Maximum Realistic Scope - **Sequential Tasks**: 3-5 tasks maximum per workflow - **Single Concurrent Workflow**: Only one active workflow per session - **Session-Bound State**: All state lost when session ends - **File-Based Coordination**: Using proven AutoDocs file management patterns - **Guidance Over Automation**: Suggest and guide rather than fully automate ### Architecture Shift: Workflow Planning Assistant Instead of a full orchestration system, we implement: 1. **Workflow Analyzer**: Analyzes requests and suggests task breakdown 2. **Planning Assistant**: Creates structured workflow plans with clear steps 3. **Context Manager**: Maintains workflow state using file-based storage 4. **Progress Tracker**: Tracks completed steps and suggests next actions 5. **Pattern Learner**: Captures successful workflows for future reference ## Revised 3-Phase Implementation Roadmap ### Phase Overview | Phase | Duration | Focus | Risk Level | Realistic Scope | |-------|----------|-------|------------|-----------------| | **Phase 1: Planning Foundation** | 4 weeks | Basic workflow analysis & planning | Low | File-based workflow state | | **Phase 2: Guided Execution** | 6 weeks | Step-by-step workflow guidance | Medium | Context continuity patterns | | **Phase 3: Pattern Learning** | 4 weeks | Workflow optimization & learning | Low | Success pattern recognition | **Total Timeline: 14 weeks (3.5 months)** - 50% reduction from original plan ## Phase 1: Planning Foundation (4 weeks) **Objective**: Build basic workflow analysis and planning capabilities using file-based state management ### Key Deliverables 1. **Workflow Analyzer Tool**: MCP tool that analyzes complex requests 2. **Planning State Manager**: File-based workflow state persistence 3. **Basic Task Breakdown**: Simple task decomposition algorithms 4. **Integration with Existing Agents**: Non-breaking extensions to current agents ### Success Criteria - Workflow analyzer successfully processes requests and suggests 3-5 task breakdown - File-based state management stores and retrieves workflow plans reliably - All existing AutoDocs functionality remains unaffected - Basic workflow patterns identified and catalogued ### Implementation Tasks #### Task 1.1: Workflow Analysis MCP Tool **Duration**: 1.5 weeks **Priority**: Critical ```python @mcp.tool async def analyze_workflow_request( request_description: str, request_type: str = "general", complexity_hint: int = 5 ) -> dict: """ Analyze a complex request and suggest workflow breakdown. Args: request_description: Natural language description of what user wants request_type: Type of request (feature_development, documentation, analysis) complexity_hint: User's estimate of complexity (1-10) Returns: Structured workflow plan with suggested task sequence """ ``` **Leverages Existing Patterns**: - Uses `error_formatter.py` patterns for structured output - Follows `security.py` input validation approach - Adopts `cache_manager.py` file handling patterns #### Task 1.2: File-Based Workflow State Manager **Duration**: 2 weeks **Priority**: Critical ```python # src/autodocs_mcp/workflow/state_manager.py class WorkflowStateManager: """File-based workflow state management using proven AutoDocs patterns.""" def __init__(self, workflow_dir: Path): self.workflow_dir = Path(workflow_dir) / "workflows" self.current_workflow_file = self.workflow_dir / "current_workflow.json" async def create_workflow(self, workflow_plan: dict) -> str: """Create new workflow with unique ID.""" async def get_current_workflow(self) -> dict | None: """Get active workflow state.""" async def update_workflow_progress(self, task_id: str, status: str, result: dict) -> None: """Update task completion status.""" async def complete_workflow(self, final_result: dict) -> None: """Mark workflow as completed.""" ``` **Implementation Approach**: - Follow `cache_manager.py` file patterns exactly - Use `security.sanitize_cache_key()` for filename safety - Implement atomic file operations with temp files - Add comprehensive error handling using `error_formatter.py` #### Task 1.3: Task Breakdown Engine **Duration**: 1.5 weeks **Priority**: High ```python class TaskBreakdownEngine: """Simple rule-based task decomposition.""" def __init__(self): self.task_patterns = self._load_task_patterns() async def analyze_request(self, request: str, request_type: str) -> list[dict]: """Break down request into sequential tasks.""" # Simple pattern matching approach if request_type == "feature_development": return self._break_down_feature_request(request) elif request_type == "documentation_update": return self._break_down_documentation_request(request) else: return self._break_down_general_request(request) def _break_down_feature_request(self, request: str) -> list[dict]: """Feature development task breakdown.""" return [ {"id": "analyze", "description": "Analyze requirements", "agent": "core-services"}, {"id": "implement", "description": "Implement feature", "agent": "core-services"}, {"id": "test", "description": "Add tests", "agent": "testing-specialist"}, {"id": "document", "description": "Update documentation", "agent": "technical-writer"} ] ``` ## Phase 2: Guided Execution (6 weeks) **Objective**: Implement guided workflow execution with context continuity between tasks ### Key Deliverables 1. **Workflow Execution MCP Tools**: Tools to execute workflow steps 2. **Context Continuity System**: Maintain context between sequential tasks 3. **Progress Tracking**: Track and report workflow progress 4. **Agent Integration Enhancements**: Optional workflow awareness for existing agents ### Success Criteria - Users can execute workflows step-by-step with guidance - Context maintained between sequential tasks within same session - Progress clearly communicated to users - Existing agent functionality enhanced but not broken ### Implementation Tasks #### Task 2.1: Workflow Execution Tools **Duration**: 2 weeks ```python @mcp.tool async def execute_workflow_step( workflow_id: str, step_id: str, user_inputs: dict = None ) -> dict: """ Execute the next step in a workflow. Returns: Step execution result with next step guidance """ @mcp.tool async def get_workflow_progress(workflow_id: str) -> dict: """ Get current workflow status and next recommended actions. Returns: Current progress, completed tasks, and next steps """ @mcp.tool async def skip_workflow_step( workflow_id: str, step_id: str, reason: str ) -> dict: """ Skip a workflow step with reason (for flexibility). """ ``` #### Task 2.2: Context Continuity Manager **Duration**: 2.5 weeks ```python class WorkflowContextManager: """Manage workflow context using file-based storage.""" def __init__(self, context_dir: Path): self.context_dir = Path(context_dir) / "workflow_contexts" async def store_step_context( self, workflow_id: str, step_id: str, context: dict ) -> None: """Store context from completed step for next step.""" async def load_workflow_context(self, workflow_id: str) -> dict: """Load accumulated context for current workflow.""" async def merge_step_result( self, workflow_id: str, step_result: dict ) -> dict: """Merge step result into workflow context.""" ``` **File Structure**: ``` ~/.cache/autodocs-mcp/workflows/ ├── current_workflow.json ├── completed_workflows/ │ └── {workflow_id}.json └── contexts/ └── {workflow_id}_context.json ``` #### Task 2.3: Enhanced Agent Integration **Duration**: 2.5 weeks Add optional workflow awareness to existing agents without breaking changes: ```python # Optional enhancement to existing agents class WorkflowAwareAgent: """Mixin for workflow context awareness.""" async def load_workflow_context(self, workflow_id: str) -> dict: """Load relevant workflow context if available.""" async def contribute_to_workflow( self, workflow_id: str, step_result: dict ) -> None: """Contribute results to workflow context.""" ``` **Integration Strategy**: - Add workflow context as optional parameter to existing tools - Existing functionality works identically without workflow context - When workflow context provided, agents can access previous step results - Follow existing AutoDocs patterns for backward compatibility ## Phase 3: Pattern Learning (4 weeks) **Objective**: Implement workflow pattern recognition and optimization ### Key Deliverables 1. **Workflow Pattern Database**: Store successful workflow patterns 2. **Pattern Recognition Engine**: Identify similar requests and suggest proven workflows 3. **Success Metrics Collection**: Track workflow completion and user satisfaction 4. **Workflow Optimization**: Suggest improvements based on historical data ### Success Criteria - System recognizes similar requests and suggests proven workflows - Workflow completion rates improve over time - User satisfaction with suggestions increases - Pattern database grows with successful workflows ### Implementation Tasks #### Task 3.1: Pattern Database and Recognition **Duration**: 2 weeks ```python class WorkflowPatternManager: """Manage workflow patterns using file-based storage.""" def __init__(self, patterns_dir: Path): self.patterns_dir = Path(patterns_dir) / "workflow_patterns" async def store_successful_workflow( self, workflow: dict, success_metrics: dict ) -> None: """Store completed workflow as pattern.""" async def find_similar_workflows( self, request_description: str, request_type: str ) -> list[dict]: """Find similar successful workflows.""" async def suggest_workflow_from_pattern( self, pattern_id: str, current_request: str ) -> dict: """Adapt existing pattern to current request.""" ``` #### Task 3.2: Success Metrics and Optimization **Duration**: 2 weeks ```python @mcp.tool async def record_workflow_feedback( workflow_id: str, success_rating: int, time_saved: int = None, user_comments: str = None ) -> dict: """Record user feedback on workflow completion.""" @mcp.tool async def get_workflow_suggestions( request_description: str, request_type: str = "general" ) -> dict: """Get workflow suggestions based on successful patterns.""" ``` ## File-Based Architecture Implementation ### Leveraging AutoDocs Patterns #### Cache Manager Pattern Adaptation ```python # Workflow state follows cache_manager.py patterns class WorkflowFileManager: """File management using proven AutoDocs patterns.""" def __init__(self, base_dir: Path): self.base_dir = Path(base_dir) self.error_formatter = ErrorFormatter() async def store_workflow_state(self, workflow_id: str, state: dict) -> None: """Store workflow state atomically.""" workflow_file = self.base_dir / f"{sanitize_cache_key(workflow_id)}.json" temp_file = workflow_file.with_suffix('.tmp') try: # Atomic write pattern from cache_manager.py with temp_file.open('w') as f: json.dump(state, f, indent=2) temp_file.rename(workflow_file) except Exception as e: self._cleanup_temp_file(temp_file) raise CacheError(f"Failed to store workflow state: {str(e)}") ``` #### Error Handling Pattern ```python # Error handling follows error_formatter.py patterns class WorkflowError(Exception): """Workflow-specific error with structured formatting.""" pass class WorkflowErrorFormatter: """Format workflow errors using AutoDocs patterns.""" def format_workflow_error( self, error: Exception, workflow_id: str, context: dict ) -> FormattedError: """Format workflow errors consistently.""" return FormattedError( severity=ErrorSeverity.ERROR, message=f"Workflow {workflow_id} failed: {str(error)}", details=context, recovery_suggestions=self._get_recovery_suggestions(error) ) ``` ### File Structure Organization ``` ~/.cache/autodocs-mcp/ ├── packages/ # Existing AutoDocs cache └── workflows/ # New workflow system ├── current_workflow.json # Active workflow state ├── completed/ # Completed workflow history │ └── {workflow_id}.json ├── contexts/ # Workflow contexts │ └── {workflow_id}_context.json └── patterns/ # Successful workflow patterns ├── feature_development/ ├── documentation/ └── analysis/ ``` ## Integration Strategy ### Non-Breaking Enhancement Approach #### Existing MCP Tools Enhancement ```python # Example: Enhance existing scan_dependencies tool @mcp.tool async def scan_dependencies( project_path: str = None, workflow_id: str = None # Optional workflow integration ) -> dict: """ Existing functionality unchanged. Optional workflow integration when workflow_id provided. """ # Existing logic unchanged result = await existing_scan_dependencies_logic(project_path) # Optional workflow integration if workflow_id: await contribute_to_workflow(workflow_id, "dependency_analysis", result) return result ``` #### New MCP Tools for Workflow System ```python # New tools added to main.py app.add_tools([ analyze_workflow_request, # Analyze and plan workflows execute_workflow_step, # Execute workflow steps get_workflow_progress, # Check workflow status skip_workflow_step, # Skip steps when needed record_workflow_feedback, # Collect user feedback get_workflow_suggestions # Get pattern-based suggestions ]) ``` ## Risk Management & Constraints ### Technical Risk Mitigation #### File System Limitations - **Risk**: Race conditions with concurrent file access - **Mitigation**: Single workflow per session constraint, atomic file operations - **Monitoring**: File lock detection and cleanup procedures #### Context Size Limitations - **Risk**: Workflow context exceeds token limits - **Mitigation**: Context pruning and summarization - **Implementation**: Follow `context_formatter.py` patterns for context management #### Session Boundary Limitations - **Risk**: Workflows lost when session ends - **Mitigation**: Clear user communication about session limits - **Enhancement**: Store completed workflows for pattern learning ### User Experience Risk Mitigation #### Expectation Management - **Clear Communication**: Document system limitations upfront - **Progressive Enhancement**: Start with simple workflows, add complexity gradually - **Fallback Strategy**: Always allow manual task execution #### Learning Curve - **Simple Start**: Begin with common workflow patterns - **Guided Experience**: Provide step-by-step guidance - **Documentation**: Clear examples and common patterns ## Success Metrics & Validation ### Quantitative Metrics 1. **Workflow Completion Rate**: % of started workflows completed successfully 2. **Time Efficiency**: Average time reduction for multi-step tasks 3. **Pattern Recognition Accuracy**: % of relevant patterns suggested 4. **User Adoption Rate**: % of users who try workflow features ### Qualitative Metrics 1. **User Satisfaction**: Feedback ratings on workflow guidance 2. **Workflow Usefulness**: User assessment of suggested task breakdowns 3. **System Reliability**: Consistency of workflow state management 4. **Integration Quality**: Impact on existing AutoDocs functionality ### Phase-Specific Success Criteria #### Phase 1 Success Validation - [ ] Workflow analyzer processes 100% of test requests without errors - [ ] File-based state persists through session for 3-5 sequential tasks - [ ] All existing AutoDocs MCP tools function identically - [ ] Basic workflow patterns catalogued (5+ common patterns) #### Phase 2 Success Validation - [ ] Users complete 3-task workflows with guided assistance - [ ] Context continuity maintained between workflow steps - [ ] Progress tracking provides clear status and next steps - [ ] Enhanced agent integration provides value without breaking changes #### Phase 3 Success Validation - [ ] Pattern recognition suggests relevant workflows 70%+ accuracy - [ ] Workflow completion time improves 20%+ over manual approach - [ ] Success metrics show positive user experience trends - [ ] Pattern database contains 20+ validated successful workflows ## Resource Requirements ### Development Team (Reduced Scope) - **Core Services Engineer**: 12 weeks focused engagement - **Testing Specialist**: 8 weeks focused engagement - **Technical Writer**: 4 weeks documentation - **Product Manager**: 2 weeks requirements validation ### Infrastructure Requirements (Minimal) - **File Storage**: Standard filesystem operations - **No Additional Dependencies**: Uses existing AutoDocs infrastructure - **No External Services**: Self-contained within current system - **Development Environment**: Standard AutoDocs development setup ## Implementation Timeline ### Month 1: Planning Foundation - Week 1-2: Workflow analysis MCP tool and basic task breakdown - Week 3-4: File-based state management and integration testing ### Month 2: Guided Execution - Week 5-7: Workflow execution tools and context continuity - Week 8-10: Agent integration and progress tracking ### Month 3: Pattern Learning - Week 11-12: Pattern recognition and success metrics - Week 13-14: Optimization and comprehensive testing ### Month 4: Polish & Documentation - Week 15-16: Documentation, examples, and production readiness ## Conclusion This revised implementation plan acknowledges the Claude Agents/hooks platform constraints while delivering meaningful workflow assistance value. By focusing on **planning and guidance** rather than full orchestration, we can: ### Realistic Deliverables 1. **Intelligent Workflow Analysis**: Break down complex requests into manageable steps 2. **Guided Task Execution**: Provide step-by-step assistance with context continuity 3. **Pattern-Based Learning**: Improve suggestions based on successful workflows 4. **Seamless Integration**: Enhance existing AutoDocs without breaking changes ### Strategic Value Within Constraints - **Immediate Value**: Users get intelligent task breakdown and guidance - **Manageable Complexity**: File-based system within platform capabilities - **Growth Path**: Foundation for future enhancements when platform evolves - **Risk Management**: Conservative approach with high probability of success ### Success Probability: High This approach has **high probability of success** because it: - Works within confirmed platform constraints - Leverages proven AutoDocs patterns - Provides incremental value without radical changes - Has realistic timeline and resource requirements The Workflow Planning Assistant will transform how users approach complex tasks in the AutoDocs ecosystem, providing intelligent guidance while respecting technical limitations and maintaining the reliability users expect.