# 📋 Getting Started: New Projects with PRD.md

This guide helps you bootstrap architectural decisions for new projects using a Product Requirements Document (PRD.md). You'll learn how to automatically generate ADRs from requirements and create a solid architectural foundation.

## 📋 Prerequisites

### Required Software

- **Node.js** ≥18.0.0
- **MCP Client** (Claude Desktop, Cline, Cursor, or Windsurf)
- **PRD.md file** with your project requirements

### MCP Server Installation

```bash
# Global installation (recommended)
npm install -g mcp-adr-analysis-server

# Verify installation
mcp-adr-analysis-server --version
```

## ⚙️ Configuration

### Environment Setup

```bash
export PROJECT_PATH="/path/to/your/new/project"
export ADR_DIRECTORY="./adrs"
export LOG_LEVEL="INFO"
export CACHE_ENABLED="true"
```

### MCP Client Configuration

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/new/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

## 📝 PRD.md Requirements

Your PRD.md should include these sections for optimal ADR generation:

```markdown
# Product Requirements Document

## Technical Requirements

- Performance requirements
- Scalability needs
- Security requirements
- Integration requirements

## Architecture Constraints

- Technology preferences
- Platform requirements
- Compliance needs
- Budget constraints

## Non-Functional Requirements

- Availability requirements
- Maintainability needs
- Monitoring requirements
```

## 🚀 Step-by-Step Workflow

### Step 1: Generate ADRs from PRD

Transform your requirements into architectural decisions:

**Tool Call:**

```
generate_adrs_from_prd
```

**Parameters:**

```json
{
  "prdPath": "PRD.md",
  "outputDirectory": "./adrs"
}
```

**What this does:**

- Analyzes your PRD.md file
- Identifies architectural decision points
- Generates appropriate ADRs for each decision
- Creates properly formatted ADR files

**Expected Output:**

- Multiple ADR files in `././adrs/` directory
- Each ADR addresses a specific architectural decision
- ADRs follow standard format (Context, Decision, Consequences)
- Numbered sequence (001-xxx.md, 002-xxx.md, etc.)

### Step 2: Validate Generated Decisions

Ensure the generated ADRs make sense for your project:

**Tool Call:**

```
analyze_project_ecosystem
```

**Parameters:**

```json
{}
```

**What this does:**

- Analyzes your project structure (if any exists)
- Validates ADR decisions against project context
- Identifies potential conflicts or gaps
- Suggests refinements

**Expected Output:**

- Validation report for generated ADRs
- Recommendations for adjustments
- Technology stack compatibility analysis

### Step 3: Create Enhanced TDD Implementation Roadmap

Generate actionable tasks using the new two-phase TDD approach:

**Tool Call:**

```
generate_adr_todo
```

**Parameters:**

```json
{
  "scope": "pending",
  "phase": "both",
  "linkAdrs": true,
  "includeRules": true
}
```

**What this does:**

- Extracts implementation tasks from ADRs with TDD approach
- Links all ADRs to create system-wide test coverage
- Integrates architectural rules validation
- Creates both test specifications and implementation tasks
- Generates comprehensive development roadmap with validation checkpoints

**Expected Output:**

- `todo.md` file with TDD-focused implementation tasks
- Test specifications linking all ADRs for comprehensive coverage
- Implementation tasks with architectural rule compliance checks
- Prioritized list of architectural work with production readiness criteria
- Dependencies and sequencing information with validation gates

### Step 4: AI-Powered Development Planning

Let AI orchestrate your implementation workflow based on PRD requirements:

**Tool Call:**

```
tool_chain_orchestrator
```

**Parameters:**

```json
{
  "operation": "generate_plan",
  "userRequest": "Implement PRD requirements with full ADR coverage and deployment readiness",
  "includeContext": true,
  "optimizeFor": "prd_implementation"
}
```

**What this does:**

- AI analyzes PRD-generated ADRs to create optimal implementation sequence
- Generates comprehensive tool execution plan with dependencies
- Provides structured workflow preventing implementation gaps
- Includes confidence scoring and alternative approaches

### Step 5: Advanced Deployment Guidance

Generate comprehensive deployment guidance from your ADRs:

**Tool Call:**

```
generate_deployment_guidance
```

**Parameters:**

```json
{
  "adrDirectory": "./adrs",
  "environmentType": "production",
  "includeInfrastructure": true,
  "includeSecurityChecklist": true,
  "technologyFilter": ["web", "database", "api"]
}
```

**What this does:**

- Extracts deployment requirements from ADR technology decisions
- Generates environment-specific deployment procedures
- Creates comprehensive infrastructure setup guides
- Provides actionable deployment instructions with commands
- Includes security checklists and validation procedures

### Step 6: Smart Project Health Monitoring

Track implementation progress against PRD goals:

**Tool Call:**

```
smart_score
```

**Parameters:**

```json
{
  "operation": "sync_scores",
  "includeWeightOptimization": true,
  "focusAreas": ["todo", "architecture", "deployment", "prd_compliance"]
}
```

### Step 7: Establish Quality Validation Framework

Set up validation to ensure implementations meet ADR goals from the start:

**Tool Call:**

```
compare_adr_progress
```

**Parameters:**

```json
{
  "todoPath": "todo.md",
  "adrDirectory": "./adrs",
  "deepCodeAnalysis": true,
  "functionalValidation": true,
  "strictMode": true,
  "includeTestCoverage": true,
  "validateDependencies": true,
  "prdValidation": true
}
```

**What this does:**

- Establishes quality gates for new implementations
- Sets up mock vs production code detection patterns
- Creates validation criteria for each ADR goal
- Provides reality-check mechanisms for implementation progress
- Validates cross-ADR dependencies and system consistency
- Ensures implementations meet original PRD requirements

**Expected Output:**

- Quality validation framework configuration
- Implementation standards and patterns
- Validation checkpoints for each development phase
- Clear criteria for production readiness assessment
- PRD compliance validation reports

### Step 8: Research Critical Decisions

For complex decisions, generate research questions:

**Tool Call:**

```
generate_research_questions
```

**Parameters:**

```json
{
  "context": "Database selection for high-traffic application",
  "scope": "data_architecture",
  "researchAreas": ["performance", "scalability", "cost"]
}
```

**What this does:**

- Identifies areas needing additional research
- Generates specific research questions
- Creates research tracking templates
- Suggests validation approaches

## 🔄 Iterative Refinement

### Refining Generated ADRs

**1. Review and Enhance**

```
Tool: suggest_adrs
Parameters: {
  "analysisType": "comprehensive",
  "existingAdrs": ["Generated ADR titles"]
}
```

**2. Add Missing Decisions**

```
Tool: generate_adr_from_decision
Parameters: {
  "decisionData": {
    "title": "Additional Decision Title",
    "context": "Context from PRD analysis",
    "decision": "Specific architectural choice",
    "consequences": "Expected outcomes"
  }
}
```

### Incorporating Research Findings

**Tool Call:**

```
incorporate_research
```

**Parameters:**

```json
{
  "researchFindings": "Research results and conclusions",
  "targetAdr": "001-database-selection.md",
  "updateType": "enhance"
}
```

## 🎯 Common PRD Scenarios

### Scenario 1: Web Application

**PRD Focus:** User interface, API design, data management

**Expected ADRs:**

- Frontend framework selection
- API architecture (REST/GraphQL)
- Database choice
- Authentication strategy
- Deployment architecture

**Key Tools:**

1. `generate_adrs_from_prd` - Initial generation
2. `suggest_adrs` - Fill gaps (caching, monitoring, etc.)
3. `generate_research_questions` - For complex choices

### Scenario 2: Microservices Platform

**PRD Focus:** Scalability, service boundaries, data consistency

**Expected ADRs:**

- Service decomposition strategy
- Inter-service communication
- Data management approach
- Service discovery mechanism
- Monitoring and observability

**Key Tools:**

1. `generate_adrs_from_prd` - Core architecture
2. `analyze_environment` - Platform constraints
3. `generate_rules` - Service design principles

### Scenario 3: Mobile Application

**PRD Focus:** Platform support, offline capabilities, performance

**Expected ADRs:**

- Platform strategy (native/cross-platform)
- State management approach
- Offline data strategy
- Push notification system
- App store deployment

## 🧪 TDD Workflow for PRD-Based Projects

When starting from a PRD, the TDD workflow ensures your implementation matches the requirements:

### Phase 1: Generate Test Specifications from PRD-Generated ADRs

**Create comprehensive test specifications:**

```
Tool: generate_adr_todo
Parameters: {
  "phase": "test",
  "linkAdrs": true,
  "includeRules": true,
  "outputPath": "todo-tests.md"
}
```

**Benefits for PRD-based projects:**

- Validates that all PRD requirements are testable
- Creates system-wide test coverage based on architectural decisions
- Establishes clear acceptance criteria for each requirement
- Links business requirements to technical implementation through ADRs

### Phase 2: Generate Production Implementation from Tests

**Create implementation roadmap:**

```
Tool: generate_adr_todo
Parameters: {
  "phase": "production",
  "linkAdrs": true,
  "includeRules": true,
  "outputPath": "todo-implementation.md"
}
```

**Benefits for PRD-based projects:**

- Ensures implementation directly addresses PRD requirements
- Maintains traceability from PRD to ADRs to implementation
- Includes architectural rule compliance for all PRD-driven decisions
- Provides clear production readiness criteria

### Validation Against PRD Requirements

**Ensure implementations meet original PRD goals:**

```
Tool: compare_adr_progress
Parameters: {
  "todoPath": "todo.md",
  "adrDirectory": "./adrs",
  "projectPath": "/path/to/project",
  "deepCodeAnalysis": true,
  "functionalValidation": true,
  "strictMode": true,
  "prdValidation": true
}
```

**PRD-specific validation patterns:**

- Verifies functional requirements are actually implemented
- Checks non-functional requirements (performance, security) are met
- Validates business logic matches PRD specifications
- Ensures user experience requirements are addressed
- Confirms compliance requirements are satisfied

### Common PRD Implementation Pitfalls to Avoid

The validation system helps prevent:

**Requirements Drift:**

- Mock implementations that don't meet actual PRD requirements
- Features that work in isolation but don't integrate properly
- Performance implementations that don't meet PRD criteria
- Security implementations that don't address PRD compliance needs

**Traceability Loss:**

- Code that implements features not described in the PRD
- Missing implementations for critical PRD requirements
- ADRs that don't align with actual PRD priorities
- Tests that don't validate real PRD acceptance criteria

## 📊 Advanced Features and AI-Powered Workflows

### AI-Powered Troubleshooting

When implementing PRD requirements runs into issues:

**Tool Call:**

```
troubleshoot_guided_workflow
```

**Parameters:**

```json
{
  "operation": "full_workflow",
  "failureType": "deployment_failure",
  "description": "PRD implementation deployment failing in production environment",
  "severity": "high"
}
```

**What this does:**

- Systematic analysis of implementation vs PRD requirements
- AI-generated test plans with specific diagnostic commands
- Integration with other MCP tools for comprehensive troubleshooting
- Fallback templates when AI services are unavailable

### Human Override for Complex PRD Tasks

When LLMs get confused during complex PRD implementation:

**Tool Call:**

```
troubleshoot_guided_workflow
```

**Parameters:**

```json
{
  "taskDescription": "Implement complex microservices architecture from PRD requirements with full deployment pipeline",
  "forceExecution": true,
  "includeContext": true
}
```

**What this does:**

- Forces AI-powered planning through OpenRouter.ai
- Cuts through LLM confusion with structured execution plans
- Provides clear command schemas for complex PRD implementation
- Includes confidence scoring and detailed execution notes

### Deployment Readiness for PRD Projects

Validate your PRD implementation is ready for production:

**Tool Call:**

```
deployment_readiness
```

**Parameters:**

```json
{
  "operation": "full_audit",
  "targetEnvironment": "production",
  "maxTestFailures": 0,
  "requireTestCoverage": 80,
  "blockOnFailingTests": true,
  "deploymentSuccessThreshold": 80,
  "integrateTodoTasks": true,
  "requireAdrCompliance": true,
  "strictMode": true
}
```

**PRD-specific validation:**

- Validates all PRD requirements have passing tests
- Ensures test coverage meets requirements
- Checks deployment history for stability
- Validates ADR compliance with PRD goals
- Creates blocking tasks for any gaps

**Expected Output:**

- Deployment readiness score with PRD alignment
- Test validation covering all PRD requirements
- Critical blockers linked to specific PRD sections
- Clear resolution steps for each issue

### Smart Git Operations for PRD Projects

Deploy with confidence using deployment-aware git push:

**Tool Call:**

```
smart_git_push
```

**Parameters:**

```json
{
  "message": "Implement core PRD requirements with ADR compliance",
  "branch": "main",
  "checkDeploymentReadiness": true,
  "enforceDeploymentReadiness": true,
  "targetEnvironment": "production",
  "strictDeploymentMode": true
}
```

**What this does:**

- Runs deployment readiness checks before push
- Validates PRD implementation completeness
- Blocks push if critical PRD requirements are missing
- Ensures all tests are passing
- Provides detailed failure reports with PRD traceability

### Environment Analysis

Understand deployment and operational context:

**Tool Call:**

```
analyze_environment
```

**Parameters:**

```json
{
  "environmentType": "cloud",
  "constraints": ["budget", "compliance", "performance"]
}
```

### Rule Generation

Create architectural guidelines from your ADRs:

**Tool Call:**

```
generate_rules
```

**Parameters:**

```json
{
  "adrDirectory": "./adrs",
  "includeCompliance": true,
  "outputFormat": "json"
}
```

### Action Confirmation

For critical implementation steps:

**Tool Call:**

```
request_action_confirmation
```

**Parameters:**

```json
{
  "proposedAction": "Implement database migration strategy",
  "impactAssessment": "High - affects all data operations",
  "alternatives": ["Alternative approaches"]
}
```

## 🔧 Troubleshooting

### Common Issues

**PRD Not Parsed Correctly**

- Ensure PRD.md follows standard markdown format
- Include clear section headers
- Provide specific technical requirements

**Generated ADRs Too Generic**

- Add more technical details to PRD
- Include specific constraints and preferences
- Use `suggest_adrs` to add missing specifics

**Missing Critical Decisions**

- Review generated ADRs for gaps
- Use `analyze_project_ecosystem` for validation
- Manually create ADRs for missed decisions

## 📈 Best Practices

1. **Detailed PRD**: Include technical constraints and preferences
2. **Iterative Approach**: Generate, review, refine ADRs
3. **Research Integration**: Use research tools for complex decisions
4. **Validation**: Check ADRs against project constraints
5. **Implementation Planning**: Use todo generation for roadmap

## 🔄 Next Steps After ADR Generation

### 1. Team Review

- Share generated ADRs with team
- Gather feedback and refinements
- Update ADRs based on team input

### 2. Implementation Planning

- Use `generate_adr_todo` for detailed tasks
- Prioritize implementation order
- Identify dependencies and risks

### 3. Ongoing Maintenance

- Set up regular ADR reviews
- Use `suggest_adrs` for new decisions
- Validate implementation against ADRs

## 🔗 Related Documentation

- **[API Reference](../reference/api-reference.md)** - Complete tool reference
- **[Working with Existing ADRs](./work-with-existing-adrs.md)** - Managing existing decisions
- **[First Steps Tutorial](../tutorials/01-first-steps.md)** - Starting from scratch

---

**Need Help?** Open an issue on [GitHub](https://github.com/tosin2013/mcp-adr-analysis-server/issues)
