Initial commit
This commit is contained in:
Zhongwei Li
867
commands/modernize.md
Normal file
867
commands/modernize.md
Normal file
@@ -0,0 +1,867 @@
|
||||
# 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** ✅
|
||||
Reference in New Issue
Block a user