universal-mcp-orchestration/knowledge-base/agent-guides/PHASE_2_AGENTS_GUIDE.md

🏆 UNIVERSAL AI DEVELOPMENT SYSTEM: 100% OPTIMIZED! Complete plug-and-play MCP orchestration with 20/20 agents operational, 101MB optimization, zero-error operations, and enterprise-grade reliability. Works with ANY project type at ANY scale.

# 📚 Phase 2 Agents Implementation Guide

## Overview
Phase 2 introduces 4 specialized agents focused on design, UX, and documentation. These agents complement Phase 1's development-focused agents to provide complete product development capabilities.

## 🎨 UI/UX Designer Agent

### Purpose
Creates wireframes, design systems, and ensures accessibility compliance for user interfaces.

### Configuration
```json
{
  "ui-ux-designer": {
    "command": "python3",
    "args": ["/path/to/agents/ui-ux-designer/mcp_server.py"],
    "description": "User interface and experience design specialist"
  }
}
```

### Available Tools

#### 1. `generate_wireframe`
Creates wireframe structures for features.
```python
params = {
    "feature_name": "User Dashboard",
    "description": "Dashboard showing user stats and actions",
    "screen_type": "web",  # web, mobile, tablet
    "components": ["header", "navigation", "content"]  # optional
}
```

#### 2. `create_design_system`
Builds comprehensive design systems with tokens and components.
```python
params = {
    "project_name": "MyApp",
    "brand_colors": {"primary": "#007bff", "secondary": "#6c757d"},
    "typography": {"heading": "Inter", "body": "Roboto"},
    "component_categories": ["buttons", "forms", "navigation"]
}
```

#### 3. `create_user_journey`
Maps user journeys with touchpoints and opportunities.
```python
params = {
    "persona_name": "Power User",
    "goal": "Complete purchase",
    "touchpoints": ["landing", "browse", "cart", "checkout"],
    "current_experience": "Description of current flow"
}
```

#### 4. `check_accessibility`
Audits designs for WCAG compliance.
```python
params = {
    "component_type": "form",
    "html_structure": "<form>...</form>",  # optional
    "wcag_level": "AA"  # A, AA, AAA
}
```

#### 5. `create_style_guide`
Generates UI style guide with patterns and guidelines.
```python
params = {
    "project_name": "MyApp",
    "design_principles": ["clean", "modern", "accessible"],
    "ui_patterns": ["cards", "modals", "tooltips"]
}
```

### Integration with Other Agents
- Works with **Frontend Developer** for implementation
- Coordinates with **Product Manager** for requirements
- Collaborates with **QA** for usability testing

---

## ⚛️ Frontend Developer Enhanced Agent

### Purpose
Modern web development with advanced frameworks and performance optimization.

### Configuration
```json
{
  "frontend-developer": {
    "command": "python3",
    "args": ["/path/to/agents/frontend-developer/mcp_server.py"],
    "description": "Modern web development with advanced frameworks"
  }
}
```

### Available Tools

#### 1. `create_component`
Builds framework-specific components.
```python
params = {
    "component_name": "UserProfile",
    "component_type": "functional",  # functional, class
    "framework": "react",  # react, vue, angular
    "use_typescript": True,
    "include_tests": True,
    "props": {"userId": "string", "editable": "boolean"}
}
```

#### 2. `implement_responsive_design`
Creates responsive layouts.
```python
params = {
    "component_name": "Dashboard",
    "breakpoints": {"mobile": 320, "tablet": 768, "desktop": 1024},
    "layout_type": "grid",  # grid, flexbox
    "columns": {"mobile": 1, "tablet": 2, "desktop": 3}
}
```

#### 3. `optimize_performance`
Frontend performance optimization.
```python
params = {
    "target_component": "ProductList",
    "optimization_types": ["lazy-loading", "memoization", "virtualization"],
    "bundle_analysis": True
}
```

#### 4. `create_pwa_manifest`
Progressive Web App setup.
```python
params = {
    "app_name": "MyApp",
    "theme_color": "#007bff",
    "features": ["offline", "push-notifications", "install-prompt"]
}
```

#### 5. `create_component_library`
Builds reusable component libraries.
```python
params = {
    "library_name": "MyAppUI",
    "components": ["Button", "Card", "Modal"],
    "documentation": True,
    "storybook": True
}
```

---

## 📝 Technical Writer Agent

### Purpose
Creates comprehensive documentation for all aspects of the project.

### Configuration
```json
{
  "technical-writer": {
    "command": "python3",
    "args": ["/path/to/agents/technical-writer/mcp_server.py"],
    "description": "Comprehensive documentation creation"
  }
}
```

### Available Tools

#### 1. `create_user_documentation`
End-user documentation.
```python
params = {
    "feature_name": "User Dashboard",
    "sections": ["Overview", "Getting Started", "Features", "FAQ"],
    "target_audience": "End users",
    "include_screenshots": True,
    "format": "markdown"  # markdown, html, pdf
}
```

#### 2. `generate_api_docs`
API documentation generation.
```python
params = {
    "api_name": "User API",
    "endpoints": [
        {"method": "GET", "path": "/users", "description": "List users"},
        {"method": "POST", "path": "/users", "description": "Create user"}
    ],
    "include_examples": True,
    "format": "openapi"  # openapi, markdown, postman
}
```

#### 3. `write_tutorial`
Step-by-step tutorials.
```python
params = {
    "tutorial_title": "Getting Started with MyApp",
    "steps": ["Install", "Configure", "First Steps", "Advanced Usage"],
    "difficulty": "beginner",  # beginner, intermediate, advanced
    "include_code_samples": True
}
```

#### 4. `create_troubleshooting_guide`
Problem-solving documentation.
```python
params = {
    "product_name": "MyApp",
    "common_issues": [
        {"issue": "Login fails", "solutions": ["Check credentials", "Clear cache"]},
        {"issue": "Slow performance", "solutions": ["Check network", "Update browser"]}
    ],
    "include_diagnostics": True
}
```

#### 5. `generate_readme`
Project README files.
```python
params = {
    "project_name": "MyApp",
    "sections": ["Installation", "Usage", "Contributing", "License"],
    "badges": ["build", "coverage", "license"],
    "include_demo": True
}
```

---

## 🔍 UX Researcher Agent

### Purpose
Conducts user research and analyzes usability data.

### Configuration
```json
{
  "ux-researcher": {
    "command": "python3",
    "args": ["/path/to/agents/ux-researcher/mcp_server.py"],
    "description": "User research and usability analysis"
  }
}
```

### Available Tools

#### 1. `plan_user_research`
Research planning and methodology.
```python
params = {
    "project_name": "MyApp Feature",
    "research_objectives": ["Understand user needs", "Identify pain points"],
    "target_users": {"age": "25-45", "tech_savvy": "medium"},
    "timeline_weeks": 4,
    "research_methods": ["interviews", "surveys", "usability_tests"]
}
```

#### 2. `design_survey`
Creates research surveys.
```python
params = {
    "survey_title": "User Satisfaction Survey",
    "objectives": ["Measure satisfaction", "Identify improvements"],
    "question_types": {"likert": 5, "multiple_choice": 3, "open_ended": 2},
    "target_responses": 100
}
```

#### 3. `analyze_usability_test`
Analyzes usability test results.
```python
params = {
    "test_name": "Dashboard Usability Test",
    "participants": [
        {"id": "P1", "age": 28, "tech_level": "high"},
        {"id": "P2", "age": 45, "tech_level": "medium"}
    ],
    "tasks": [
        {"name": "Find settings", "success_rate": 0.8, "avg_time": 45}
    ],
    "metrics": {"task_success": True, "time_on_task": True, "errors": True}
}
```

#### 4. `create_persona`
Develops user personas.
```python
params = {
    "persona_name": "Tech Professional Tom",
    "demographic_data": {"age": 32, "occupation": "Software Engineer"},
    "behaviors": ["Uses app daily", "Values efficiency"],
    "goals": ["Track progress", "Save time"],
    "pain_points": ["Complex interfaces", "Slow loading"],
    "research_data": {"interviews": 5, "surveys": 50}
}
```

#### 5. `analyze_ab_test`
A/B test analysis.
```python
params = {
    "test_name": "Button Color Test",
    "variant_a": {"name": "Blue", "conversions": 120, "visitors": 1000},
    "variant_b": {"name": "Green", "conversions": 150, "visitors": 1000},
    "metrics": ["conversion_rate", "statistical_significance"],
    "duration_days": 14,
    "sample_size": 2000
}
```

#### 6. `plan_user_interviews`
Interview planning and guides.
```python
params = {
    "research_topic": "Mobile App Usage",
    "target_participants": 10,
    "participant_criteria": {"uses_mobile": True, "frequency": "daily"},
    "interview_duration": 45  # minutes
}
```

---

## 🔄 Workflow Integration

### Design-First Workflow Example
```python
# 1. UX Researcher plans research
ux_researcher.plan_user_research(project_name="New Feature")

# 2. UX Researcher creates personas
ux_researcher.create_persona(persona_name="Primary User")

# 3. UI/UX Designer creates wireframes
ui_ux_designer.generate_wireframe(feature_name="Dashboard")

# 4. UI/UX Designer creates design system
ui_ux_designer.create_design_system(project_name="MyApp")

# 5. Frontend Developer implements components
frontend_developer.create_component(component_name="Dashboard")

# 6. Technical Writer documents the feature
technical_writer.create_user_documentation(feature_name="Dashboard")
```

### Multi-Agent Coordination
The Orchestration Manager automatically coordinates these agents:
1. Analyzes request to determine if design-first approach is needed
2. Sequences tasks appropriately (research → design → development → documentation)
3. Passes outputs between agents
4. Ensures consistency across deliverables

---

## 🐛 Troubleshooting

### Common Issues

#### FastMCP Compatibility
**Problem**: Agent fails to start with FastMCP error
**Solution**: Remove `description` parameter from FastMCP initialization
```python
# ❌ Wrong
mcp = FastMCP(name="agent", version="1.0", description="...")

# ✅ Correct
mcp = FastMCP(name="agent")
```

#### Bridge Registration
**Problem**: Agents not showing in UI
**Solution**: Update `real_mcp_bridge.py` MCP_AGENTS dictionary

#### Tool Name Mismatches
**Problem**: Orchestration manager can't find tool
**Solution**: Verify tool names match between agent definition and orchestration manager

---

## 📈 Best Practices

### 1. Design-First Development
- Always start with UX research for user-facing features
- Create wireframes before implementation
- Validate accessibility early

### 2. Component Reusability
- Use Frontend Developer's component library feature
- Maintain consistent design system
- Document component APIs

### 3. Documentation Throughout
- Generate docs as features are built
- Keep README files updated
- Create tutorials for complex features

### 4. User-Centered Approach
- Regular usability testing
- A/B test important changes
- Maintain updated personas

---

## 🚀 Advanced Usage

### Custom Workflows
Create specialized workflows combining Phase 2 agents:

```python
# Design System Creation Workflow
1. UX Researcher → Survey users about design preferences
2. UI/UX Designer → Create design system based on research
3. Frontend Developer → Implement component library
4. Technical Writer → Document design system usage
```

### Performance Optimization Workflow
```python
1. Frontend Developer → Analyze current performance
2. UI/UX Designer → Optimize visual assets
3. Frontend Developer → Implement optimizations
4. Technical Writer → Document performance best practices
```

---

This guide provides complete documentation for Phase 2 agents. Each agent is production-ready and integrates seamlessly with the existing Phase 1 agents through the Orchestration Manager.