Getting Started: Workflow & Development Guidance

This guide shows you how to use the new workflow guidance and development guidance tools to get intelligent recommendations for your specific project goals.

🎯 Overview

The MCP ADR Analysis Server now includes two powerful meta-tools that act as intelligent assistants:

• get_workflow_guidance - Recommends optimal tool sequences based on your goals
• get_development_guidance - Translates architectural decisions into specific coding tasks

These tools solve the "tool discovery" problem and ensure you follow best practices to achieve your goals efficiently.

🚀 Quick Start

Step 1: Get Workflow Guidance

Start by describing what you want to accomplish:

Tool Call:

get_workflow_guidance

Parameters:

{
  "goal": "analyze new project and set up architectural documentation",
  "projectContext": "new_project",
  "availableAssets": ["codebase"],
  "timeframe": "thorough_review",
  "primaryConcerns": ["maintainability", "scalability"]
}

What You Get:

• 📋 Recommended Tool Sequence - Step-by-step workflow
• 🔄 Alternative Approaches - Different paths based on constraints
• ⏱️ Timeline Estimates - Realistic time expectations
• 📊 Success Metrics - How to measure progress
• 💡 Pro Tips - Best practices and common pitfalls

Step 2: Get Development Guidance

Once you have architectural decisions, get specific implementation guidance:

Tool Call:

get_development_guidance

Parameters:

{
  "developmentPhase": "implementation",
  "adrsToImplement": ["ADR-001: REST API Design", "ADR-002: Database Schema"],
  "technologyStack": ["TypeScript", "Node.js", "PostgreSQL"],
  "teamContext": {
    "size": "small_team",
    "experienceLevel": "mixed"
  },
  "focusAreas": ["API design", "testing strategy"]
}

What You Get:

• 🏗️ Implementation Roadmap - Phase-by-phase development plan
• 📋 Specific Coding Tasks - ADRs translated to actionable tasks
• 🧪 Testing Strategy - Comprehensive testing approach
• 📊 Quality Gates - Success criteria and checkpoints
• 🚀 Deployment Guidance - Environment and deployment strategy

📋 Common Scenarios

Scenario 1: New Project Analysis

Goal: Analyze a new React TypeScript project and set up architectural documentation.

{
  "goal": "analyze new project and set up architectural documentation",
  "projectContext": "new_project",
  "availableAssets": ["codebase"],
  "timeframe": "thorough_review"
}

Expected Workflow:

1. analyze_project_ecosystem → Discover technology stack
2. get_architectural_context → Generate architectural insights + ADR setup
3. suggest_adrs → Get ADR recommendations
4. generate_adr_from_decision → Create specific ADRs
5. get_development_guidance → Get implementation roadmap

Scenario 2: Legacy System Modernization

Goal: Modernize a legacy codebase with proper architectural documentation.

{
  "goal": "modernize legacy system with architectural documentation",
  "projectContext": "legacy_codebase",
  "availableAssets": ["codebase", "documentation"],
  "timeframe": "comprehensive_audit",
  "primaryConcerns": ["technical_debt", "maintainability", "security"]
}

Expected Workflow:

1. analyze_project_ecosystem → Understand current state
2. get_architectural_context → Assess architectural maturity
3. suggest_adrs → Identify modernization decisions
4. generate_rules → Extract current patterns
5. get_development_guidance → Create modernization roadmap

Scenario 3: Security Audit & Compliance

Goal: Perform security audit and implement data protection measures.

{
  "goal": "security audit and data protection implementation",
  "projectContext": "existing_without_adrs",
  "primaryConcerns": ["security", "compliance"],
  "timeframe": "comprehensive_audit"
}

Expected Workflow:

1. analyze_content_security → Identify sensitive data
2. generate_content_masking → Create masking strategy
3. configure_custom_patterns → Set up security patterns
4. validate_content_masking → Verify protection
5. get_development_guidance → Implement security measures

Scenario 4: PRD to Implementation

Goal: Convert a Product Requirements Document to a working implementation.

{
  "goal": "convert PRD to implementation plan",
  "projectContext": "greenfield",
  "availableAssets": ["PRD.md"],
  "timeframe": "thorough_review"
}

Expected Workflow:

1. generate_adrs_from_prd → Convert PRD to ADRs
2. generate_adr_todo (phase: "both", linkAdrs: true) → Create TDD implementation tasks
3. get_development_guidance → Get detailed development plan
4. compare_adr_progress → Validate implementation quality and detect mock patterns
5. analyze_deployment_progress → Track implementation

🔧 Development Guidance Deep Dive

The get_development_guidance tool provides phase-specific guidance:

Planning Phase

{
  "developmentPhase": "planning",
  "technologyStack": ["TypeScript", "React", "Node.js"],
  "teamContext": {"size": "small_team", "experienceLevel": "mixed"}
}

Focus: Project structure, tooling setup, development workflow

Implementation Phase

{
  "developmentPhase": "implementation",
  "adrsToImplement": ["ADR-001: API Design"],
  "focusAreas": ["API design", "database schema"]
}

Focus: Specific coding tasks, design patterns, implementation strategies

Testing Phase

{
  "developmentPhase": "testing",
  "focusAreas": ["unit testing", "integration testing", "e2e testing"]
}

Focus: Testing strategies, quality gates, automation setup

Deployment Phase

{
  "developmentPhase": "deployment",
  "focusAreas": ["CI/CD pipeline", "environment setup", "monitoring"]
}

Focus: Deployment strategies, environment configuration, monitoring setup

Validation & Quality Assurance Phase

{
  "developmentPhase": "validation",
  "focusAreas": ["mock detection", "ADR compliance", "production readiness"]
}

Focus: Implementation validation, mock vs production detection, ADR goal compliance

🧪 Enhanced TDD and Validation Workflow

The MCP server now includes sophisticated validation capabilities to ensure high-quality implementations:

New Validation-Focused Scenarios

Scenario 5: TDD Implementation with Validation

Goal: Implement ADRs using test-driven development with comprehensive validation.

{
  "goal": "implement ADRs using TDD with quality validation",
  "projectContext": "existing_with_adrs",
  "availableAssets": ["codebase", "ADRs"],
  "timeframe": "thorough_review",
  "primaryConcerns": ["code_quality", "test_coverage", "production_readiness"]
}

Expected Workflow:

1. generate_adr_todo (phase: "test") → Generate test specifications
2. Implement mock tests based on specifications
3. generate_adr_todo (phase: "production") → Generate implementation tasks
4. Implement production code to pass tests
5. compare_adr_progress (strictMode: true) → Validate against ADR goals and detect mock patterns
6. get_development_guidance → Refine implementation based on validation results

Scenario 6: Quality Assurance and Mock Detection

Goal: Validate existing implementations and detect mock code masquerading as production.

{
  "goal": "validate implementation quality and detect mock patterns",
  "projectContext": "existing_with_adrs",
  "availableAssets": ["codebase", "ADRs", "todo.md"],
  "primaryConcerns": ["production_readiness", "ADR_compliance"]
}

Expected Workflow:

1. compare_adr_progress (deepCodeAnalysis: true) → Comprehensive validation
2. generate_rules → Extract architectural rules
3. validate_rules → Check rule compliance
4. get_development_guidance → Create remediation plan for issues found

Key Validation Parameters

When using workflow guidance, consider these validation-specific parameters:

{
  "validationRequirements": {
    "mockDetection": true,
    "adrCompliance": true,
    "functionalValidation": true,
    "strictMode": true
  },
  "qualityGates": ["test_coverage", "error_handling", "integration_tests"],
  "productionCriteria": ["real_database_connections", "proper_error_handling", "input_validation"]
}

💡 Pro Tips

1. Start with Workflow Guidance

Always begin with get_workflow_guidance to get the optimal tool sequence for your specific situation.

2. Be Specific with Goals

The more specific your goal description, the better the recommendations:

• ❌ "analyze project"
• ✅ "analyze React TypeScript project for security vulnerabilities and performance optimization"

3. Provide Context

Include your team context and constraints for tailored recommendations:

{
  "teamContext": {
    "size": "solo",
    "experienceLevel": "junior"
  },
  "timeline": "2 weeks to MVP"
}

4. Use Focus Areas

Specify focus areas to get targeted guidance:

{
  "focusAreas": ["API design", "testing strategy", "deployment pipeline"]
}

5. Iterate and Refine

Use the guidance as a starting point and refine based on your specific findings and constraints.

6. Always Validate Implementation Quality

Include validation steps in every workflow:

{
  "includeValidation": true,
  "validationLevel": "strict",
  "mockDetection": true,
  "adrCompliance": true
}

7. Use TDD Approach for New Implementations

For new ADR implementations, always use the two-phase TDD approach:

• Phase 1: Generate test specifications with generate_adr_todo (phase: "test")
• Phase 2: Generate implementation tasks with generate_adr_todo (phase: "production")
• Validation: Use compare_adr_progress to ensure production readiness

8. Prevent Mock Code in Production

Always run compare_adr_progress with strictMode: true to prevent common issues:

• Mock implementations being considered production-ready
• Missing error handling and input validation
• Inadequate integration testing
• Configuration issues that prevent real deployment

🎯 Success Metrics

Track your progress using the success metrics provided by the tools:

• Immediate Indicators: Quick wins and early signals
• Progress Milestones: Key checkpoints in your workflow
• Final Outcomes: Ultimate success criteria for your goals

🔄 Integration with Other Tools

The workflow and development guidance tools work seamlessly with all other MCP tools:

• Analysis Tools: analyze_project_ecosystem, get_architectural_context
• ADR Tools: suggest_adrs, generate_adr_from_decision, discover_existing_adrs
• TDD Tools: generate_adr_todo (enhanced with phase-based approach)
• Validation Tools: compare_adr_progress, generate_rules, validate_rules
• Quality Tools: analyze_content_security, generate_content_masking
• Utility Tools: check_ai_execution_status, manage_cache

🚀 Next Steps

1. Try the workflow guidance with your current project
2. Follow the recommended tool sequence
3. Use development guidance to implement architectural decisions
4. Track progress using the provided success metrics
5. Iterate and improve based on your results

The workflow and development guidance tools transform the MCP server into a complete development lifecycle assistant that guides you from architectural planning all the way through to working code!