feat/general-refinement - refactor: move prompts to Markdown files with Jinja2 templating

✨ MAJOR REFACTORING: Externalized Prompts for Better Maintainability

🎯 **What Changed:**
- **Extracted all hardcoded prompts** to separate Markdown files in src/prompts/
- **Added Jinja2 templating** for dynamic variable substitution
- **Created PromptLoader utility** for loading and rendering templates
- **Comprehensive test coverage** for prompt loading functionality

📁 **New Structure:**
- src/prompts/judge_coding_plan.md - Main evaluation prompt
- src/prompts/judge_code_change.md - Code review prompt
- src/prompts/research_validation.md - Research quality validation
- src/mcp_as_a_judge/prompt_loader.py - Template loading utility
- tests/test_prompt_loader.py - Full test coverage

🚀 **Benefits:**
- **Easy editing**: Prompts now in readable Markdown format
- **Version control**: Track prompt changes separately from code
- **Maintainability**: No more giant f-strings in Python code
- **Flexibility**: Jinja2 templating for dynamic content
- **Testability**: Isolated prompt testing and validation
- **Collaboration**: Non-developers can edit prompts easily

✅ **Quality Assurance:**
- All existing tests pass (28/28)
- New comprehensive prompt loader tests
- Backward compatibility maintained
- No functional changes to evaluation logic

This refactoring makes the codebase much more maintainable and allows for easier prompt iteration and improvement! 🎉

Author: Zvi Fried

README.md

@@ -26,7 +26,7 @@
 - 🔍 **Enforcing research and best practices** before implementation
 - ⚖️ **Creating a collaborative AI-human workflow** for better software quality
 
-## 🚀 **This MCP Will Change Many Developers' Lives!**
+## 🚀 **Vibe Coding doesn't have to be frustrating**
 
 ### **What It Prevents:**
 

pyproject.toml

@@ -28,6 +28,7 @@ classifiers = [
 ]
 requires-python = ">=3.12"
 dependencies = [
+    "jinja2>=3.1.6",
     "mcp[cli]>=1.13.0",
     "pydantic>=2.0.0",
 ]

src/mcp_as_a_judge/prompt_loader.py

@@ -0,0 +1,153 @@
+"""Prompt loader utility for loading and rendering Jinja2 templates."""
+
+from pathlib import Path
+from typing import Any, Dict
+
+from jinja2 import Environment, FileSystemLoader, Template
+
+
+class PromptLoader:
+    """Loads and renders prompt templates using Jinja2."""
+
+    def __init__(self, prompts_dir: Path | None = None):
+        """Initialize the prompt loader.
+        
+        Args:
+            prompts_dir: Directory containing prompt templates. 
+                        Defaults to src/prompts relative to this file.
+        """
+        if prompts_dir is None:
+            # Default to src/prompts directory
+            current_dir = Path(__file__).parent
+            prompts_dir = current_dir.parent / "prompts"
+        
+        self.prompts_dir = prompts_dir
+        self.env = Environment(
+            loader=FileSystemLoader(str(prompts_dir)),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def load_template(self, template_name: str) -> Template:
+        """Load a Jinja2 template by name.
+        
+        Args:
+            template_name: Name of the template file (e.g., 'judge_coding_plan.md')
+            
+        Returns:
+            Jinja2 Template object
+            
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+        """
+        try:
+            return self.env.get_template(template_name)
+        except Exception as e:
+            raise FileNotFoundError(f"Template '{template_name}' not found in {self.prompts_dir}") from e
+
+    def render_prompt(self, template_name: str, **kwargs: Any) -> str:
+        """Load and render a prompt template with the given variables.
+        
+        Args:
+            template_name: Name of the template file
+            **kwargs: Variables to pass to the template
+            
+        Returns:
+            Rendered prompt string
+            
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+        """
+        template = self.load_template(template_name)
+        return template.render(**kwargs)
+
+    def render_judge_coding_plan(
+        self,
+        user_requirements: str,
+        plan: str,
+        design: str,
+        research: str,
+        context: str = "",
+        response_schema: str = "",
+    ) -> str:
+        """Render the judge coding plan prompt.
+        
+        Args:
+            user_requirements: User's requirements
+            plan: Coding plan to evaluate
+            design: System design
+            research: Research findings
+            context: Additional context
+            response_schema: JSON schema for response format
+            
+        Returns:
+            Rendered prompt string
+        """
+        return self.render_prompt(
+            "judge_coding_plan.md",
+            user_requirements=user_requirements,
+            plan=plan,
+            design=design,
+            research=research,
+            context=context,
+            response_schema=response_schema,
+        )
+
+    def render_judge_code_change(
+        self,
+        user_requirements: str,
+        code_change: str,
+        file_path: str,
+        change_description: str,
+        response_schema: str = "",
+    ) -> str:
+        """Render the judge code change prompt.
+        
+        Args:
+            user_requirements: User's requirements
+            code_change: Code content to review
+            file_path: Path to the file
+            change_description: Description of the change
+            response_schema: JSON schema for response format
+            
+        Returns:
+            Rendered prompt string
+        """
+        return self.render_prompt(
+            "judge_code_change.md",
+            user_requirements=user_requirements,
+            code_change=code_change,
+            file_path=file_path,
+            change_description=change_description,
+            response_schema=response_schema,
+        )
+
+    def render_research_validation(
+        self,
+        user_requirements: str,
+        plan: str,
+        design: str,
+        research: str,
+    ) -> str:
+        """Render the research validation prompt.
+        
+        Args:
+            user_requirements: User's requirements
+            plan: Coding plan
+            design: System design
+            research: Research to validate
+            
+        Returns:
+            Rendered prompt string
+        """
+        return self.render_prompt(
+            "research_validation.md",
+            user_requirements=user_requirements,
+            plan=plan,
+            design=design,
+            research=research,
+        )
+
+
+# Global instance for easy access
+prompt_loader = PromptLoader()