feat: bind workflow guidance to plan system prompt with structured field specs

[OtherVibes]

🎯 Overview

This PR enhances the workflow guidance system to expose comprehensive structured guidance to the plan system prompt, enabling AI coding assistants to receive detailed field specifications, conditional requirements, and preparation instructions.

🚀 Key Changes

Enhanced Workflow Guidance Extraction

• **Modified **: Now returns the full structured guidance object instead of just text
• Added comprehensive formatting logic: Converts structured guidance into detailed system prompt content
• Improved error handling: Graceful handling of malformed or missing guidance data

Plan System Prompt Improvements

• Enhanced evaluation protocol: Updated to use structured guidance information more effectively
• Field-specific validation: Added focus on required plan fields, conditional requirements, and preparation alignment
• Scope adherence: Strengthened instructions to only evaluate based on guidance requirements

Structured Guidance Exposure

The plan system prompt now receives:

• Next Tool: What tool should be called next
• Reasoning: Why this tool is recommended
• Preparation Required: Specific preparation steps needed
• Required Plan Fields: Detailed field specifications with types, requirements, and conditions
• Detailed Guidance: Comprehensive guidance text

Example Enhanced Guidance Format

**Next Tool:** judge_coding_plan
**Reasoning:** Plan needs validation before implementation can begin
**Preparation Required:**
- Prepare comprehensive design document with architecture details
- Define library selection map with purpose, selection, source, and justification
**Required Plan Fields:**
- **plan** (string) [REQUIRED]: Detailed implementation plan
- **design** (string) [REQUIRED]: Architecture and component design
- **library_plan** (list[dict]) [REQUIRED]: Library selection map
- **design_patterns** (list[dict]) [REQUIRED] [Conditional on: design_patterns_enforcement]: Design patterns to apply
**Detailed Guidance:** Create comprehensive plan addressing all required fields

🧪 Testing

• Added comprehensive test suite ()
• 6 new test cases covering guidance extraction, formatting, and integration
• All 173 existing tests pass + 6 new tests
• Edge case handling for malformed data, missing guidance, and various guidance structures

�� Documentation

• Created comprehensive documentation ()
• Detailed examples of how the enhanced system works
• Integration guides for AI coding assistants
• Benefits and usage patterns explained

🎁 Benefits

For AI Coding Assistants

• Precise field requirements: No guessing about what fields are needed
• Type information: Proper data structure guidance (string, list[dict], etc.)
• Conditional logic: Clear understanding of when optional fields become required
• Preparation steps: Specific actions to take before calling judge_coding_plan

For the System

• Reduced validation failures: Clear requirements eliminate ambiguity
• Better success rates: Plans are prepared correctly on first attempt
• Consistent workflow: Guidance ensures proper preparation for next steps
• Maintainable code: Structured approach improves code organization

🔒 Security Considerations

The plan system prompt already includes comprehensive security aspects:

• Security & Robustness section: Validates security vulnerabilities and best practices
• Risk Assessment section: Covers OAuth, CSRF, XSS, secret management, and more
• Built-in security risk generation: Automatic security risk detection and mitigation

📋 Files Changed

• src/mcp_as_a_judge/server.py: Enhanced guidance extraction and formatting
• src/mcp_as_a_judge/prompts/system/judge_coding_plan.md: Improved evaluation protocol
• tests/test_workflow_guidance_exposure.py: Comprehensive test coverage
• examples/workflow_guidance_exposure_demo.md: Documentation and examples

✅ Quality Assurance

• Backward compatibility: No breaking changes to existing functionality
• Type safety: Proper type annotations throughout
• Error handling: Graceful degradation for edge cases
• Performance: Minimal overhead for guidance processing

🔄 Migration Notes

This is a non-breaking enhancement. Existing workflows will continue to function normally, with the added benefit of more detailed guidance when available.

🎯 Related Issues

Addresses the need for better AI coding assistant preparation by exposing structured workflow guidance to the plan system prompt, significantly improving plan validation success rates.