# Modernize Command

**Description**: Orchestrate a team of specialist agents to upgrade a project to be modern, secure, well-tested, and performant

---

# Project Modernization & Security Protocol

**Version**: 2.0
**Purpose**: Coordinate multiple specialist agents to systematically upgrade any software project
**Team**: Migration Coordinator, Security Agent, Architect Agent, Coder Agent, Tester Agent, Documentation Agent
**Inputs**: Optional `ASSESSMENT.md` and `PLAN.md` from `/modernize-assess` and `/modernize-plan`

---

## Prerequisites Check

**Before starting, this command checks for**:

```bash
# Check for assessment
if [ -f "ASSESSMENT.md" ]; then
    echo "✅ Found ASSESSMENT.md - will use assessment findings"
    USE_ASSESSMENT=true
else
    echo "⚠️  No ASSESSMENT.md - recommend running /modernize-assess first"
    echo "   Continue with basic assessment? (y/n)"
    USE_ASSESSMENT=false
fi

# Check for plan
if [ -f "PLAN.md" ]; then
    echo "✅ Found PLAN.md - will follow existing plan"
    USE_PLAN=true
else
    echo "⚠️  No PLAN.md - will create plan on-the-fly"
    echo "   Recommend running /modernize-plan first for better accuracy"
    USE_PLAN=false
fi
```

**Recommendation Workflow**:
1. **Best**: Run `/modernize-assess` → `/modernize-plan` → `/modernize-project`
2. **Good**: Run `/modernize-plan` → `/modernize-project`
3. **Acceptable**: Run `/modernize-project` (will create minimal assessment/plan inline)

---

## Overview

This protocol orchestrates a **multi-agent team** to modernize and secure your project through a systematic, phased approach. The team works in coordination to ensure:
- ✅ Modern frameworks and dependencies
- ✅ Security vulnerabilities eliminated
- ✅ Comprehensive test coverage (≥95%)
- ✅ Performance optimization
- ✅ Complete documentation
- ✅ Production-ready quality

**Core Principle**: **Systematic, agent-coordinated modernization with quality gates at every stage.**

---

## Agent Team Roles

### 1. **Migration Coordinator** (Orchestrator)
- **Role**: Strategic oversight and coordination
- **Responsibilities**: Plan phases, coordinate agents, enforce quality gates, track progress
- **When active**: Throughout entire project

### 2. **Security Agent** (Blocker)
- **Role**: Vulnerability assessment and remediation
- **Responsibilities**: Scan CVEs, calculate security score, prioritize fixes
- **When active**: Phase 1 (blocks all progress until CRITICAL/HIGH resolved)

### 3. **Architect Agent** (Decision Maker)
- **Role**: Technology research and architectural decisions
- **Responsibilities**: Research alternatives, create ADRs, recommend patterns
- **When active**: Phases 1-2 (planning and design)

### 4. **Coder Agent** (Implementation)
- **Role**: Code migration and modernization
- **Responsibilities**: Update frameworks, replace obsolete APIs, fix builds
- **When active**: Phases 3-4 (can run multiple in parallel)

### 5. **Tester Agent** (Quality Gate)
- **Role**: Comprehensive testing and validation
- **Responsibilities**: Run all test phases, fix-and-retest cycles, enforce 100% pass rate
- **When active**: After every code change (blocks progression)

### 6. **Documentation Agent** (Knowledge Management)
- **Role**: Documentation creation and maintenance
- **Responsibilities**: HISTORY.md, ADRs, migration guides, changelogs
- **When active**: Continuous throughout, final comprehensive docs at end

---

## Modernization Phases

### Phase 0: Discovery & Assessment (1-2 days)

**Active Agents**: Migration Coordinator, Security Agent, Architect Agent

**Input Handling**:
```
IF ASSESSMENT.md EXISTS:
    ✅ Skip detailed assessment
    ✅ Use existing scores, risks, estimates
    ✅ Focus on validation and updates
    Duration: 0.5-1 day (validation only)
ELSE:
    ⚠️  Run full assessment (as described below)
    Duration: 1-2 days
```

**Activities**:

**⚠️ CRITICAL: Test Environment Setup MUST Be First Task**

1. **Test Environment Setup** (MANDATORY FIRST - NEW per Recommendation 1)
   - **Why First**: Cannot validate anything without working build/test environment
   - Install required SDKs (.NET, Node.js, Python, etc.)
   - Install Docker for integration testing
   - Configure environment variables
   - **Verify build succeeds**: `dotnet build` (establish baseline)
   - **Verify tests run**: `dotnet test` (establish pass rate baseline)
   - **Run vulnerability scan**: `dotnet list package --vulnerable --include-transitive`
   - Document baseline metrics: test count, pass rate, build warnings, CVE count
   - **Deliverable**: Working environment with verified baseline metrics
   - **Duration**: 1-2 hours (BLOCKING - nothing else can proceed without this)

2. **Security Baseline** (BLOCKING - Now uses verified scan from Task 1)
   - **Use vulnerability scan from Task 1** (already executed)
   - Calculate security score (0-100): `100 - (CRITICAL×10 + HIGH×5 + MEDIUM×2 + LOW×0.5)`
   - Categorize vulnerabilities (CRITICAL/HIGH/MEDIUM/LOW)
   - Document top 10 CVEs in ASSESSMENT.md
   - **BLOCK**: Must have scan results before proceeding (scores are verified, not estimated)

3. **Project Analysis**
   - **If ASSESSMENT.md exists**: ✅ Load existing inventory
   - **If no assessment**: Inventory all dependencies and frameworks
   - Identify current versions vs latest stable (using actual package resolution from Task 1 build)
   - Map project structure and architecture
   - Identify technology debt
   - **Deliverable**: Project assessment (or validate existing)

4. **Technology Assessment**
   - Research latest framework versions
   - Identify obsolete APIs and patterns
   - Document breaking changes
   - Create upgrade roadmap

5. **Test Baseline Analysis**
   - **Use test results from Task 1** (already executed)
   - Capture baseline metrics (pass rate, coverage, performance)
   - Document current test infrastructure
   - Identify test gaps

**Outputs**:
- Project assessment report (or use existing ASSESSMENT.md)
- Security vulnerability report
- Technology upgrade roadmap
- Test baseline report
- Initial HISTORY.md entry

**With Existing Assessment**:
- ✅ Validate assessment still accurate (dependencies haven't changed)
- ✅ Update if needed (typically minimal)
- ✅ Faster completion (0.5-1 day vs 1-2 days)

**Quality Gate** (UPDATED per Recommendation 1 & 3):
- ✅ Test environment ready (build succeeds, tests run)
- ✅ Baseline test metrics documented (pass rate, count, coverage)
- ✅ Vulnerability scan completed (verified CVE counts, not estimates)
- ✅ Security score calculated from scan results (≥45 required)
- ✅ All CRITICAL/HIGH vulnerabilities documented
- ✅ Docker/external dependencies ready for integration tests

---

### Phase 1: Security Remediation (2-5 days)

**Active Agents**: Security Agent (lead), Coder Agent, Tester Agent

**Activities**:
1. **Fix Critical Vulnerabilities** (P0)
   - Update packages with CRITICAL CVEs
   - Fix security misconfigurations
   - Remove deprecated/insecure code
   - Verify fixes with security scans

2. **Fix High-Priority Vulnerabilities** (P1)
   - Update packages with HIGH CVEs
   - Apply security patches
   - Implement security best practices

3. **Post-Update Security Validation** (BLOCKING - NEW per Recommendation 3)
   - **Re-run vulnerability scan**: `dotnet list package --vulnerable --include-transitive > security-after-phase1.txt`
   - **Compare before/after**: `diff security-baseline.txt security-after-phase1.txt`
   - **Verify CRITICAL/HIGH count decreased** (not just assumed)
   - **Verify no NEW vulnerabilities introduced** by updates
   - Recalculate security score from scan results (must show improvement)
   - **Run all tests** to ensure no regressions (Tier 1: Unit tests minimum)
   - Update HISTORY.md with verified security improvements

**Outputs**:
- Security fixes applied
- Updated security scan report
- Test results (must maintain 100% pass rate)
- HISTORY.md entry for security work

**Quality Gate** (UPDATED per Recommendation 3):
- ✅ Security scan re-run and results verified (not estimated)
- ✅ Security score ≥45 (calculated from verified scan results)
- ✅ Zero CRITICAL vulnerabilities (verified in scan diff)
- ✅ Zero HIGH vulnerabilities (verified in scan diff, or documented with explicit approval)
- ✅ No NEW vulnerabilities introduced by updates
- ✅ All tests passing (100% - Tier 1 Unit tests minimum)

---

### Phase 2: Architecture & Design (2-3 days)

**Active Agents**: Architect Agent (lead), Migration Coordinator

**Input Handling**:
```
IF PLAN.md EXISTS:
    ✅ Use existing architecture decisions
    ✅ Validate ADRs are current
    ✅ Follow defined strategy
    Duration: 0.5-1 day (validation only)
ELSE:
    ⚠️  Create architecture decisions (as described below)
    Duration: 2-3 days
```

**Activities**:

**⚠️ NEW: Spike-Driven ADR Process for High-Risk Decisions (per Recommendation 2)**

1. **Framework Upgrade Planning**
   - Research target framework versions
   - Evaluate migration paths
   - **For high-risk decisions**: Create spike branches (1-2 days)
     - Test Option A on single project
     - Test Option B on single project
     - Document actual compilation errors, API changes, test failures
   - Create evaluation matrix with empirical data from spikes
   - Document breaking changes
   - Create ADRs with status "proposed" first (allow 24-48hr review)
   - Mark ADRs as "accepted" after stakeholder review

2. **Dependency Strategy**
   - Identify dependency upgrade order
   - **For major version changes**: Create spike branches
     - Example: RabbitMQ.Client 5→6 vs 5→7
     - Run tests on each spike, document pass rates
     - Compare actual migration effort (file count, errors)
   - Map dependency conflicts (using spike results)
   - Plan parallel vs sequential updates
   - Create dependency upgrade matrix with verified estimates

3. **Architecture Decisions**
   - Obsolete pattern replacements
   - New feature approaches
   - Performance optimization strategies
   - Testing strategy updates
   - **All ADRs must include**:
     - Evaluation matrix with weighted criteria
     - Spike results (for high-risk decisions)
     - 24-48hr review period before "accepted" status

**Outputs**:
- ADRs for all major decisions (MADR 3.0.0 format) - or use existing from PLAN.md
- Dependency upgrade matrix
- Migration timeline
- Risk assessment
- HISTORY.md entry

**With Existing Plan**:
- ✅ ADRs already created and approved
- ✅ Migration strategy defined
- ✅ Just validate and proceed
- ✅ Faster completion (0.5-1 day vs 2-3 days)

**Quality Gate**: All major decisions documented in ADRs, migration plan approved

---

### Phase 3: Framework & Dependency Modernization (5-10 days)

**Active Agents**: Coder Agent (multiple if parallel), Tester Agent, Migration Coordinator

**Input Handling**:
```
IF PLAN.md EXISTS:
    ✅ Use defined module migration order
    ✅ Follow parallel execution strategy
    ✅ Use task breakdown from plan
    More accurate timeline
ELSE:
    ⚠️  Determine migration order on-the-fly
    More conservative timeline
```

**Activities**:
1. **Framework Upgrade**
   - Update to target framework version
   - Fix compilation errors
   - Update project files
   - Resolve API changes

2. **Dependency Updates**
   - Update dependencies in priority order
   - Resolve version conflicts
   - Update package references
   - Fix breaking changes

3. **Continuous Testing** (BLOCKING)
   - Run tests after each change
   - Fix-and-retest cycles
   - Maintain 100% pass rate
   - No progression until tests pass

**Parallel Execution Strategy**:
```
Migration Coordinator
  ↓
  ├─ Coder Agent #1 (Module A) → Tester Agent validates
  ├─ Coder Agent #2 (Module B) → Tester Agent validates
  └─ Coder Agent #3 (Module C) → Tester Agent validates
```

**Outputs**:
- Updated framework versions
- Updated dependencies
- Fixed compilation errors
- Test results (100% pass rate)
- HISTORY.md entries for each module

**Quality Gate**:
- All projects build successfully
- 100% test pass rate (MANDATORY)
- No P0/P1 issues
- Code coverage ≥80%

---

### Phase 4: API Modernization & Code Quality (3-7 days)

**Active Agents**: Coder Agent, Tester Agent, Architect Agent

**Activities**:
1. **Replace Obsolete APIs**
   - Identify deprecated API usage
   - Replace with modern equivalents
   - Update code patterns
   - Verify functionality

2. **Code Quality Improvements**
   - Apply modern language features
   - Remove code smells
   - Improve error handling
   - Optimize performance hotspots

3. **Test Enhancement**
   - Add missing test coverage
   - Update test patterns
   - Add integration tests
   - Performance benchmarks

**Outputs**:
- Modernized codebase
- Improved code quality metrics
- Enhanced test suite
- Performance benchmarks
- HISTORY.md entries

**Quality Gate**:
- Zero obsolete API warnings
- Code coverage ≥85%
- 100% test pass rate
- No performance regressions (≤10%)

---

### Phase 5: Performance Optimization (2-4 days)

**Active Agents**: Coder Agent, Tester Agent, Architect Agent

**Activities**:
1. **Performance Profiling**
   - Run performance benchmarks
   - Identify bottlenecks
   - Compare against baseline
   - Document performance goals

2. **Optimization Implementation**
   - Optimize critical paths
   - Implement caching strategies
   - Improve database queries
   - Reduce memory allocations

3. **Validation**
   - Re-run benchmarks
   - Verify improvements
   - Ensure no regressions
   - Document performance gains

**Outputs**:
- Performance optimization report
- Benchmark comparisons
- Performance ADRs (if architectural changes)
- HISTORY.md entry

**Quality Gate**:
- Performance improvement ≥10% OR documented as optimal
- No performance regressions
- All tests passing

---

### Phase 6: Comprehensive Documentation (2-3 days)

**Active Agents**: Documentation Agent (lead), Migration Coordinator

**Activities**:
1. **CHANGELOG Creation**
   - Document all breaking changes
   - List new features
   - Security fixes
   - Performance improvements
   - Migration notes

2. **Migration Guide**
   - Step-by-step upgrade instructions
   - Breaking change details
   - Code examples (before/after)
   - Troubleshooting guide
   - FAQ section

3. **Final Documentation**
   - Update README
   - API documentation
   - Architecture documentation
   - Deployment guides
   - Release notes

**Outputs**:
- CHANGELOG.md (Keep a Changelog format)
- MIGRATION-GUIDE.md (800+ lines, comprehensive)
- Updated README.md
- ADR summary
- Release notes
- Final HISTORY.md entry

**Quality Gate**: All documentation complete, reviewed, and accurate

---

### Phase 7: Final Validation & Release (1-2 days)

**Active Agents**: Tester Agent (lead), Security Agent, Migration Coordinator

**Activities**:
1. **Complete Test Suite**
   - Run all test phases
   - Unit tests (100% pass rate)
   - Integration tests (100% pass rate)
   - Component tests (100% pass rate)
   - Performance tests (baseline validation)
   - E2E tests (100% pass rate)

2. **Final Security Scan**
   - Run comprehensive CVE scan
   - Verify security score ≥45
   - Document any remaining LOW/MEDIUM issues
   - Get security approval

3. **Release Preparation**
   - Tag release version
   - Generate release notes
   - Create deployment checklist
   - Backup current production

**Outputs**:
- Final test report
- Final security report
- Release notes
- Deployment checklist
- Production readiness assessment

**Quality Gate** (GO/NO-GO Decision):
- ✅ Security score ≥45
- ✅ Zero CRITICAL/HIGH vulnerabilities
- ✅ 100% test pass rate (all test types)
- ✅ Code coverage ≥85%
- ✅ Zero P0/P1 issues
- ✅ All documentation complete
- ✅ Performance validated

---

## Using This Protocol

### Starting the Modernization

**Option 1: Full Team Orchestration**
```
User: /modernize-project
User: I have a .NET 6 project I need to upgrade to .NET 9, modernize dependencies, fix security issues, and improve test coverage.

Claude: I'll coordinate a team of specialist agents to modernize your project. Let me start with Phase 0: Discovery & Assessment...

[Migration Coordinator activates]
Phase 0: Discovery & Assessment
- Analyzing project structure...
- Running security scan...
- Creating upgrade roadmap...

[Security Agent activates]
Security Baseline:
- Current score: 23/100
- CRITICAL: 3 vulnerabilities
- HIGH: 12 vulnerabilities
⚠️ BLOCKING: Must fix CRITICAL/HIGH before proceeding

[Architect Agent activates]
Technology Assessment:
- Current: .NET 6.0
- Target: .NET 9.0
- Breaking changes identified: 47
- ADR needed for: [list of decisions]

...
```

**Option 2: Phase-by-Phase**
```
User: /modernize-project
User: Start with Phase 0 only - just assess my project

Claude: Running Phase 0: Discovery & Assessment...
[Detailed assessment output]
```

**Option 3: Specific Agent Focus**
```
User: /modernize-project
User: Focus on security remediation only (Phase 1)

Claude: [Security Agent + Coder Agent + Tester Agent activate]
```

### Monitoring Progress

The Migration Coordinator maintains a progress dashboard:

```markdown
## Modernization Progress

### Overall Status: Phase 3 - Framework Modernization (60% complete)

| Phase | Status | Duration | Quality Gate |
|-------|--------|----------|--------------|
| 0. Discovery | ✅ Complete | 1.5 days | ✅ Passed |
| 1. Security | ✅ Complete | 3 days | ✅ Score: 52/100 |
| 2. Architecture | ✅ Complete | 2 days | ✅ ADRs: 5 |
| 3. Framework | 🔄 In Progress | 4/7 days | ⏳ Pending |
| 4. API Modernization | ⏳ Pending | - | - |
| 5. Performance | ⏳ Pending | - | - |
| 6. Documentation | ⏳ Pending | - | - |
| 7. Final Validation | ⏳ Pending | - | - |

### Current Phase Details
- **Active Agents**: Coder #1, Coder #2, Tester
- **Module A**: ✅ Complete (.NET 9 migration done)
- **Module B**: 🔄 In Progress (fixing build errors)
- **Module C**: ⏳ Queued
- **Test Pass Rate**: 96.2% (6 failures, P2 severity)
```

---

## Quality Gates (Blocking Criteria)

### Security Gates (BLOCKING)
- ❌ **BLOCK**: Security score <45
- ❌ **BLOCK**: Any CRITICAL vulnerabilities unresolved
- ❌ **BLOCK**: Any HIGH vulnerabilities unresolved (unless explicitly approved)

### Testing Gates (BLOCKING)
- ❌ **BLOCK**: Test pass rate <100% (production releases)
- ❌ **BLOCK**: Code coverage <80%
- ❌ **BLOCK**: Any P0 or P1 test failures
- ❌ **BLOCK**: Performance regression >10%

### Build Gates (BLOCKING)
- ❌ **BLOCK**: Any compilation errors
- ❌ **BLOCK**: Any dependency conflicts
- ❌ **BLOCK**: Build warnings in critical code paths

### Documentation Gates (BLOCKING)
- ❌ **BLOCK**: Missing CHANGELOG
- ❌ **BLOCK**: Missing migration guide
- ❌ **BLOCK**: Undocumented breaking changes

---

## Agent Coordination Patterns

### Sequential Pipeline (Default)
```
Migration Coordinator
  ↓
Security Agent (Phase 1) → GATE → Must pass before Phase 2
  ↓
Architect Agent (Phase 2) → GATE → ADRs must be complete
  ↓
Coder Agent (Phase 3) → Tester Agent → GATE → 100% pass rate
  ↓
Coder Agent (Phase 4) → Tester Agent → GATE → 100% pass rate
  ↓
Documentation Agent (Phase 6)
  ↓
Tester + Security (Phase 7) → FINAL GATE → GO/NO-GO
```

### Parallel Execution (Faster)
```
Migration Coordinator
  ↓
Security Agent (Phase 1) → GATE
  ↓
Architect Agent (Phase 2) → GATE
  ↓
  ├─ Coder #1 (Module A) → Tester → ✅
  ├─ Coder #2 (Module B) → Tester → ✅
  └─ Coder #3 (Module C) → Tester → ✅
  ↓
Documentation Agent → Final Validation
```

### Fix-and-Retest Cycle
```
Coder Agent makes changes
  ↓
Tester Agent runs tests
  ↓ (failures found)
Tester Agent documents failures (P0/P1/P2/P3)
  ↓
Coder Agent fixes issues
  ↓
Tester Agent re-runs tests
  ↓
[Repeat until 100% pass rate achieved]
```

---

## Logging Protocol

**MANDATORY**: All agents must log to HISTORY.md using `./scripts/append-to-history.sh`

**When to Log**:
- After completing each phase
- After fixing security vulnerabilities
- After making architectural decisions
- After completing migrations
- After test validation
- After documentation updates

**Example Entry**:
```markdown
## 2025-10-25 14:30 - Phase 1: Security Remediation Complete

**Agent**: Security Agent + Coder Agent
**Phase**: 1 - Security Remediation

### What Changed
- Fixed 3 CRITICAL vulnerabilities (CVE-2024-1234, CVE-2024-5678, CVE-2024-9012)
- Fixed 12 HIGH vulnerabilities
- Updated 15 dependencies to latest secure versions
- Improved security score from 23/100 → 52/100

### Why Changed
- CRITICAL vulnerabilities blocked progression (Phase 0 quality gate)
- Required to achieve minimum security score ≥45
- Multiple packages had known exploits in production

### Impact
- Security score: 23/100 → 52/100 (+29 points)
- CRITICAL vulnerabilities: 3 → 0 (✅ resolved)
- HIGH vulnerabilities: 12 → 0 (✅ resolved)
- MEDIUM vulnerabilities: 8 → 5 (-3)
- Dependencies updated: 15 packages
- Test pass rate: 100% (no regressions introduced)

### Outcome
✅ **Quality Gate PASSED** - Ready for Phase 2: Architecture & Design
- Security score ≥45: ✅ (52/100)
- Zero CRITICAL: ✅
- Zero HIGH: ✅
- Tests passing: ✅ (100%)

**Next Phase**: Phase 2 - Architecture & Design (2-3 days estimated)
```

---

## Success Criteria

### Project Modernization Complete When:

✅ **Security**
- Security score ≥45
- Zero CRITICAL vulnerabilities
- Zero HIGH vulnerabilities
- All dependencies up-to-date

✅ **Quality**
- 100% test pass rate (all test types)
- Code coverage ≥85%
- Zero P0/P1 issues
- Performance validated (no regressions >10%)

✅ **Modernization**
- Latest stable framework version
- All dependencies current
- Zero obsolete API warnings
- Modern code patterns applied

✅ **Documentation**
- Complete CHANGELOG
- Comprehensive migration guide
- All ADRs documented
- Updated README and docs
- HISTORY.md fully populated

---

## Estimated Timeline

**Note**: Time estimates are based on typical human execution times and may vary significantly based on project complexity, team experience, and AI assistance capabilities.

| Phase | Duration | Can Parallelize |
|-------|----------|-----------------|
| 0. Discovery & Assessment | 1-2 days | No |
| 1. Security Remediation | 2-5 days | Partial (by vulnerability) |
| 2. Architecture & Design | 2-3 days | No |
| 3. Framework Modernization | 5-10 days | Yes (by module) |
| 4. API Modernization | 3-7 days | Yes (by area) |
| 5. Performance Optimization | 2-4 days | Partial |
| 6. Documentation | 2-3 days | Partial (by doc type) |
| 7. Final Validation | 1-2 days | No |

**Total**: 18-36 days (depends on project size and parallelization)

**Small Project** (<10k LOC): ~18-22 days
**Medium Project** (10k-50k LOC): ~25-30 days
**Large Project** (>50k LOC): ~30-36 days

---

## Example Usage Scenarios

### Scenario 1: .NET Framework to .NET 9
```
User: /modernize-project
User: Upgrade my .NET Framework 4.8 project to .NET 9, fix all security issues, and ensure 95%+ test coverage

Claude: I'll coordinate the modernization team:

Phase 0: Discovery & Assessment
- Current: .NET Framework 4.8
- Target: .NET 9.0
- Security Score: 18/100 ⚠️
- Test Coverage: 42% ⚠️

[Detailed execution across all 7 phases]
```

### Scenario 2: Node.js Upgrade + Security
```
User: /modernize-project
User: My Node.js 14 app needs to go to Node.js 22, fix CVEs, and add proper testing

Claude: Modernization Plan:
- Phase 0: Assess Node.js 14 → 22 migration path
- Phase 1: Fix 47 vulnerabilities (Security Agent priority)
- Phase 2: Plan ESM migration, update patterns (Architect)
- Phase 3-4: Upgrade dependencies, modernize code (Coder)
- Phase 5: Performance validation
- Phase 6-7: Documentation and final validation
```

### Scenario 3: Python 2 to Python 3
```
User: /modernize-project
User: Legacy Python 2.7 codebase → Python 3.12, modernize dependencies, add type hints

Claude: This is a major migration requiring all agents:
[Systematic execution with extra focus on syntax changes, dependency compatibility]
```

---

## Troubleshooting

### Quality Gate Failures

**Security Gate Failed**
```
❌ Security score: 38/100 (required ≥45)
→ Action: Security Agent + Coder Agent continue Phase 1
→ Cannot proceed to Phase 2 until resolved
```

**Testing Gate Failed**
```
❌ Test pass rate: 87% (required 100%)
→ Action: Tester Agent documents failures
→ Coder Agent fixes issues
→ Re-run fix-and-retest cycle
```

**Performance Gate Failed**
```
❌ Performance regression: -23% (threshold -10%)
→ Action: Roll back change
→ Architect Agent reviews approach
→ Coder Agent implements optimized solution
```

---

## Best Practices

1. **Always start with Phase 0** - Never skip discovery
2. **Don't skip quality gates** - They prevent production issues
3. **Fix security first** - Security blocks everything else
4. **Test continuously** - Don't batch testing until the end
5. **Document as you go** - Incremental documentation saves time
6. **Use parallel execution** - When dependencies allow it
7. **Log everything to HISTORY.md** - Complete audit trail
8. **Create ADRs for major decisions** - Future maintainers will thank you

---

## Anti-Patterns to Avoid

❌ **Skipping security phase** - "We'll fix it later"
❌ **Accepting <100% test pass rates** - "Good enough for now"
❌ **Batching all changes** - "One big PR at the end"
❌ **Skipping documentation** - "We'll document after release"
❌ **Ignoring quality gates** - "We're on a deadline"
❌ **Solo agent execution** - "Just the Coder Agent is fine"
❌ **No progress tracking** - "Trust the process"

---

**Document Owner**: Migration Coordinator
**Protocol Version**: 1.0
**Last Updated**: 2025-10-25
**Applicability**: Universal - All software projects requiring modernization

**Remember**: **Systematic agent coordination = Production-ready modernization** ✅