# Plan Command **Description**: Create a detailed modernization strategy and execution plan, utilizing ASSESSMENT.md if available, with phase breakdown, timeline, and resource allocation --- # Project Modernization Planning Protocol **Version**: 1.0 **Purpose**: Create a comprehensive, actionable modernization plan **Input**: Optional `ASSESSMENT.md` from `/modernize-assess` **Output**: `PLAN.md` with detailed execution strategy **Duration**: 3-6 hours **Note**: Time estimates are based on typical human execution times and may vary significantly based on project complexity, team experience, and AI assistance capabilities. --- ## Overview This protocol creates a **detailed modernization execution plan** that serves as the blueprint for the `/modernize-project` command. The plan includes: - ✅ Detailed phase breakdown with tasks - ✅ Timeline and milestone schedule - ✅ Resource allocation and team assignments - ✅ Risk mitigation strategies - ✅ Quality gates and success criteria - ✅ Contingency plans **Core Principle**: **Proper planning prevents poor performance - plan before you execute.** --- ## Planning Process ### Step 1: Load Assessment (if available) ```bash # Check for ASSESSMENT.md if [ -f "ASSESSMENT.md" ]; then echo "✅ Found ASSESSMENT.md - using as input" # Extract: scores, risks, estimates, recommendations else echo "⚠️ No ASSESSMENT.md found - will create basic assessment" # Run abbreviated assessment inline fi ``` **If assessment exists**: - Use technical viability score - Use identified risks - Use effort estimates - Use team capacity analysis - Use dependency analysis **If no assessment**: - Create quick assessment (30 min) - Gather basic project info - Identify major risks - Rough effort estimate --- ### Step 2: Define Modernization Scope (30 minutes) #### 2.1 Objectives **Primary Objectives** (MUST achieve): - [ ] Upgrade to [Target Framework/Version] - [ ] Eliminate CRITICAL/HIGH security vulnerabilities - [ ] Achieve 100% test pass rate - [ ] [Other must-have objective] **Secondary Objectives** (SHOULD achieve): - [ ] Improve code coverage to ≥85% - [ ] Optimize performance (≥10% improvement) - [ ] Modernize APIs and patterns - [ ] [Other desirable objective] **Out of Scope** (explicitly NOT doing): - [ ] UI/UX redesign - [ ] Feature additions - [ ] Complete rewrite - [ ] [Other exclusions] #### 2.2 Success Criteria **Technical Success**: - Framework upgraded to [Version] - Security score ≥45 - Zero CRITICAL/HIGH vulnerabilities - 100% test pass rate - Code coverage ≥85% - No performance regression >10% **Business Success**: - Delivered within [X weeks] - Cost within $[Budget] ±10% - Zero production incidents caused by migration - Team trained on new framework - Documentation complete --- ### Step 3: Phase Planning (60-90 minutes) For each of the 7 phases, define: #### Phase 0: Discovery & Assessment **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Migration Coordinator + Security Agent + Architect Agent **Tasks**: 1. **Project Inventory** (4 hours) - Map all projects/modules - Identify dependencies - Document current architecture - **Deliverable**: Project inventory spreadsheet 2. **Security Baseline** (4 hours) - Run vulnerability scan - Categorize vulnerabilities - Calculate security score - **Deliverable**: Security baseline report 3. **Test Baseline** (4 hours) - Run all existing tests - Capture pass rates and coverage - Document test infrastructure - **Deliverable**: Test baseline report 4. **Technology Assessment** (4 hours) - Research target framework - Document breaking changes - Identify obsolete APIs - **Deliverable**: Technology assessment document 5. **Effort Estimation** (2 hours) - Estimate each phase duration - Identify parallel opportunities - Calculate total timeline - **Deliverable**: Detailed timeline **Exit Criteria**: - All assessments complete - Security score calculated - Timeline approved - Budget approved **Risks**: - [Risk 1]: [Mitigation] - [Risk 2]: [Mitigation] --- #### Phase 1: Security Remediation **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Security Agent (lead) + Coder Agent + Tester Agent **Tasks**: 1. **Fix CRITICAL Vulnerabilities** (XX hours) - CVE-XXXX-XXXX: [Package] → [Action] - CVE-YYYY-YYYY: [Package] → [Action] - **Deliverable**: Zero CRITICAL CVEs 2. **Fix HIGH Vulnerabilities** (YY hours) - CVE-ZZZZ-ZZZZ: [Package] → [Action] - [List all HIGH CVEs with remediation plan] - **Deliverable**: Zero HIGH CVEs 3. **Update Security Dependencies** (ZZ hours) - [Package 1]: v[Old] → v[New] - [Package 2]: v[Old] → v[New] - **Deliverable**: All security patches applied 4. **Validation Testing** (WW hours) - Re-run security scan - Run full test suite - Verify no regressions - **Deliverable**: Security score ≥45 **Exit Criteria**: - ✅ Security score ≥45 - ✅ Zero CRITICAL vulnerabilities - ✅ Zero HIGH vulnerabilities - ✅ 100% test pass rate maintained **Risks**: - [Risk 1]: Dependency conflicts → [Mitigation] - [Risk 2]: Breaking changes → [Mitigation] **Contingency**: - If unable to fix all HIGH: Document exceptions, get approval - If tests fail: Allocate +XX hours for fixes --- #### Phase 2: Architecture & Design **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Architect Agent (lead) + Migration Coordinator **Tasks**: 1. **Create Migration ADRs** (8 hours) - ADR 0001: [Target Framework Selection] - ADR 0002: [Dependency Strategy] - ADR 0003: [Migration Approach] - **Deliverable**: 3-5 ADRs in MADR format 2. **Dependency Migration Matrix** (6 hours) - Map all dependencies to target versions - Identify conflicts - Define resolution strategy - **Deliverable**: Dependency migration matrix 3. **Breaking Changes Analysis** (8 hours) - Enumerate all breaking changes - Estimate code impact % - Create remediation guide - **Deliverable**: Breaking changes guide 4. **Module Migration Order** (4 hours) - Analyze dependencies - Define migration sequence - Identify parallel opportunities - **Deliverable**: Module migration plan **Exit Criteria**: - ✅ All ADRs approved - ✅ Dependency strategy defined - ✅ Migration order established - ✅ Team aligned on approach **Risks**: - [Risk 1]: [Mitigation] - [Risk 2]: [Mitigation] --- #### Phase 3: Framework & Dependency Modernization **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Coder Agent (multiple) + Tester Agent **Parallel Execution Strategy**: ``` Module A: [Dev 1] → [X days] Module B: [Dev 2] → [Y days] Module C: [Dev 3] → [Z days] ``` **Tasks by Module**: **Module A: [Name]** (XX hours) 1. Update framework target 2. Update package references 3. Fix compilation errors 4. Run tests (100% pass required) 5. Code review 6. **Deliverable**: Module A migrated **Module B: [Name]** (YY hours) [Similar breakdown] **Module C: [Name]** (ZZ hours) [Similar breakdown] **Integration** (WW hours) 1. Merge all modules 2. Resolve conflicts 3. Full solution build 4. Complete test suite 5. **Deliverable**: All modules integrated **Exit Criteria**: - ✅ All modules migrated - ✅ Solution builds successfully - ✅ 100% test pass rate - ✅ Zero P0/P1 issues **Risks**: - [Risk 1]: Merge conflicts → Daily integration - [Risk 2]: Test failures → Dedicated tester --- #### Phase 4: API Modernization & Code Quality **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Coder Agent + Tester Agent + Architect Agent **Tasks**: 1. **Replace Obsolete APIs** (XX hours) - [Old API 1] → [New API 1] (YY instances) - [Old API 2] → [New API 2] (ZZ instances) - **Deliverable**: Zero obsolete API warnings 2. **Apply Modern Patterns** (YY hours) - async/await conversion - Pattern matching - Record types - **Deliverable**: Modern code patterns applied 3. **Enhance Test Coverage** (ZZ hours) - Add missing unit tests - Add integration tests - Target ≥85% coverage - **Deliverable**: 85% code coverage 4. **Code Quality** (WW hours) - Reduce complexity - Fix code smells - Improve naming - **Deliverable**: Quality metrics improved **Exit Criteria**: - ✅ Zero obsolete APIs - ✅ Code coverage ≥85% - ✅ 100% test pass rate - ✅ Code quality score improved **Risks**: - [Risk 1]: [Mitigation] - [Risk 2]: [Mitigation] --- #### Phase 5: Performance Optimization **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Coder Agent + Tester Agent **Tasks**: 1. **Baseline Benchmarks** (4 hours) - Define performance tests - Capture baseline metrics - Set improvement targets - **Deliverable**: Baseline report 2. **Identify Bottlenecks** (8 hours) - Run profiler - Analyze hot paths - Prioritize optimizations - **Deliverable**: Optimization backlog 3. **Implement Optimizations** (XX hours) - [Optimization 1] - [Optimization 2] - [Optimization 3] - **Deliverable**: Performance improvements 4. **Validate Performance** (6 hours) - Re-run benchmarks - Compare vs baseline - Document gains - **Deliverable**: Performance report **Exit Criteria**: - ✅ Performance ≥baseline (no regressions) - ✅ Target improvements achieved OR justified - ✅ Benchmarks documented **Risks**: - [Risk 1]: Limited improvement → Document as optimal - [Risk 2]: Regression found → Roll back and retry --- #### Phase 6: Comprehensive Documentation **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Documentation Agent (lead) **Tasks**: 1. **CHANGELOG.md** (6 hours) - Document breaking changes - New features/improvements - Bug fixes - Security updates - **Deliverable**: Complete CHANGELOG 2. **MIGRATION-GUIDE.md** (12 hours) - Step-by-step upgrade guide - Breaking changes details - Before/after examples - Troubleshooting - **Deliverable**: Comprehensive migration guide (800+ lines) 3. **Update Documentation** (8 hours) - Update README - Update architecture docs - Update API docs - **Deliverable**: All docs current 4. **ADR Summaries** (4 hours) - Compile all ADRs - Create decision log - Link to relevant docs - **Deliverable**: ADR index **Exit Criteria**: - ✅ CHANGELOG complete - ✅ Migration guide ≥800 lines - ✅ All docs updated - ✅ Documentation reviewed --- #### Phase 7: Final Validation & Release **Duration**: [X-Y days] **Team**: [Names/Roles] **Agent**: Tester Agent (lead) + Security Agent + Coordinator **Tasks**: 1. **Complete Test Execution** (12 hours) - Unit tests (100% pass) - Integration tests (100% pass) - Component tests (100% pass) - E2E tests (100% pass) - Performance tests (validation) - **Deliverable**: All tests passing 2. **Final Security Scan** (4 hours) - Run vulnerability scan - Verify security score ≥45 - Document any LOW/MEDIUM issues - **Deliverable**: Security approval 3. **Release Preparation** (8 hours) - Create release notes - Tag release version - Package artifacts - Deployment checklist - **Deliverable**: Release package 4. **GO/NO-GO Decision** (2 hours) - Review all quality gates - Production readiness assessment - Final approval - **Deliverable**: GO or NO-GO **Exit Criteria**: - ✅ 100% test pass rate (all types) - ✅ Security score ≥45 - ✅ Zero CRITICAL/HIGH vulnerabilities - ✅ All documentation complete - ✅ Release approved --- ### Step 4: Timeline & Milestones (30 minutes) #### Gantt Chart ``` Week 1-2: Phase 0 (Discovery) ████████ Week 3-4: Phase 1 (Security) ████████████ Week 5-6: Phase 2 (Arch) ████████ Week 7-10: Phase 3 (Framework) ████████████████████ Module A ████████ Module B ████████ Module C ████████ Week 11-13: Phase 4 (API Mod) ████████████ Week 14-15: Phase 5 (Perf) ████████ Week 16-17: Phase 6 (Docs) ████████ Week 18: Phase 7 (Validate) ████ ``` #### Milestones | Milestone | Date | Deliverables | Success Criteria | |-----------|------|--------------|------------------| | M1: Assessment Complete | Week 2 | Security baseline, test baseline, plan | All baselines captured | | M2: Security Remediated | Week 4 | Security score ≥45, CVEs fixed | Zero CRITICAL/HIGH | | M3: Architecture Approved | Week 6 | ADRs, migration strategy | Team aligned | | M4: Framework Migrated | Week 10 | All modules on new framework | Builds, 100% tests | | M5: Code Modernized | Week 13 | Modern APIs, ≥85% coverage | Quality improved | | M6: Performance Validated | Week 15 | Benchmarks, optimizations | No regressions | | M7: Documentation Complete | Week 17 | CHANGELOG, migration guide | All docs done | | M8: Production Ready | Week 18 | Final validation, approval | GO decision | --- ### Step 5: Resource Allocation (30 minutes) #### Team Assignments **Phase 0: Discovery** - Lead: [Name] (Architect/Coordinator) - Support: [Name] (Security) - Hours: XX total **Phase 1: Security** - Lead: [Name] (Security specialist) - Devs: [Name1, Name2] - Tester: [Name] - Hours: YY total **Phase 2: Architecture** - Lead: [Name] (Architect) - Support: [Coordinator] - Hours: ZZ total **Phase 3: Framework (PARALLEL)** - Module A: [Dev1] (WW hours) - Module B: [Dev2] (VV hours) - Module C: [Dev3] (UU hours) - Tester: [Name] (TT hours) - Hours: XX total **Phase 4-7**: [Similar breakdown] #### Capacity Planning | Week | Available Hours | Allocated Hours | Buffer | Utilization | |------|----------------|-----------------|--------|-------------| | 1-2 | 160 | 120 | 40 | 75% | | 3-4 | 160 | 140 | 20 | 88% | | ... | ... | ... | ... | ... | **Total Project**: - Available: XX hours - Allocated: YY hours - Buffer (30%): ZZ hours - **Utilization**: WW% --- ### Step 6: Risk Management (45 minutes) #### Risk Register | ID | Risk | Probability | Impact | Severity | Mitigation | Owner | |----|------|-------------|--------|----------|------------|-------| | R01 | Dependency conflicts unresolvable | Medium | High | HIGH | Upfront analysis, alternatives ready | [Name] | | R02 | Timeline overrun >30% | Medium | High | HIGH | Phased approach, weekly reviews | [Coordinator] | | R03 | Critical bug in production | Low | Critical | HIGH | Comprehensive testing, rollback plan | [Tester] | | R04 | Team member leaves | Low | Medium | MEDIUM | Knowledge sharing, documentation | [Manager] | | R05 | Breaking changes missed | Medium | High | HIGH | Thorough analysis, peer review | [Architect] | #### Mitigation Strategies **For High-Priority Risks**: **R01: Dependency Conflicts** - **Prevention**: Analyze all dependencies upfront (Phase 0) - **Detection**: Test builds daily - **Response**: Have alternative packages researched - **Contingency**: +2 weeks for rewrites if needed **R02: Timeline Overrun** - **Prevention**: 30% buffer, conservative estimates - **Detection**: Weekly status reviews, burn-down charts - **Response**: Descope secondary objectives - **Contingency**: Defer Phase 4-5 to post-launch **R03: Production Bug** - **Prevention**: 100% test pass rate, comprehensive E2E - **Detection**: Staged rollout, monitoring - **Response**: Immediate rollback procedure - **Contingency**: Rollback plan tested, backup ready --- ### Step 7: Quality Gates & Decision Points (20 minutes) #### Gate Criteria **Gate 1: Post-Assessment** (End of Phase 0) - **GO if**: Assessment score ≥60/100, budget approved - **NO-GO if**: Score <60, CRITICAL risks, no budget - **Decision Maker**: Executive sponsor **Gate 2: Post-Security** (End of Phase 1) - **GO if**: Security score ≥45, zero CRITICAL/HIGH - **NO-GO if**: Unable to remediate critical CVEs - **Decision Maker**: Security lead + Coordinator **Gate 3: Post-Architecture** (End of Phase 2) - **GO if**: All ADRs approved, team aligned - **NO-GO if**: No viable migration path - **Decision Maker**: Tech lead + Architect **Gate 4: Post-Framework** (End of Phase 3) - **GO if**: 100% tests pass, builds clean - **NO-GO if**: <100% pass rate, build issues - **Decision Maker**: Coordinator + Tester **Gate 5: Post-API Modernization** (End of Phase 4) - **GO if**: Coverage ≥85%, quality improved - **NO-GO if**: Major quality regression - **Decision Maker**: Tech lead **Gate 6: Post-Performance** (End of Phase 5) - **GO if**: No regression >10%, targets met - **NO-GO if**: Critical regression - **Decision Maker**: Tech lead + Architect **Gate 7: Post-Documentation** (End of Phase 6) - **GO if**: All docs complete and reviewed - **NO-GO if**: Major gaps in documentation - **Decision Maker**: Documentation lead **Gate 8: Final GO/NO-GO** (End of Phase 7) - **GO if**: All gates passed, production ready - **NO-GO if**: Any blocker remaining - **Decision Maker**: Executive sponsor --- ### Step 8: Contingency Planning (30 minutes) #### What-If Scenarios **Scenario 1: Critical Dependency Has No Compatible Version** - **Impact**: Cannot complete Phase 3 - **Response**: 1. Research alternative packages 2. Evaluate rewrite of dependent code 3. Consider staying on current framework with security patches - **Timeline Impact**: +2-4 weeks - **Effort Impact**: Additional development and testing required **Scenario 2: Test Pass Rate Drops Below 80%** - **Impact**: Quality gate failure - **Response**: 1. Halt further changes 2. Analyze all failures 3. Dedicate team to fixes 4. Re-run complete suite - **Timeline Impact**: +1-2 weeks - **Effort Impact**: Dedicated testing and bug fixing resources **Scenario 3: Performance Regression >20%** - **Impact**: Unacceptable for production - **Response**: 1. Roll back changes 2. Profile and identify bottleneck 3. Architect review optimization strategy 4. Implement targeted fixes - **Timeline Impact**: +2-3 weeks - **Effort Impact**: Performance analysis and optimization work **Scenario 4: Key Team Member Leaves** - **Impact**: Knowledge loss, capacity reduction - **Response**: 1. Knowledge transfer session (if notice given) 2. Redistribute work 3. Consider contractor/consultant 4. Extend timeline if needed - **Timeline Impact**: +1-3 weeks - **Effort Impact**: Onboarding and knowledge transfer overhead --- ## PLAN.md Output Template ```markdown # Project Modernization Plan **Project**: [Name] **Current Version**: [Version] **Target Version**: [Version] **Plan Created**: [Date] **Plan Owner**: [Name] **Executive Sponsor**: [Name] --- ## Executive Summary ### Objectives [Primary and secondary objectives] ### Timeline - **Start Date**: [Date] - **End Date**: [Date] - **Duration**: XX weeks (YY calendar months) - **Contingency Buffer**: 30% additional time ### Team - **Team Size**: X developers - **Key Roles**: [List] - **External Resources**: [If any] ### Success Criteria [Top 5 success criteria] --- ## Assessment Summary [If ASSESSMENT.md exists, summarize key findings] **Overall Assessment Score**: XX/100 **Recommendation**: [PROCEED/CAUTION/DEFER/DO NOT] **Key Risks**: 1. [Risk 1] 2. [Risk 2] **Mitigation Strategies**: [Summary of how risks will be addressed] --- ## Scope ### In Scope ✅ [Item 1] ✅ [Item 2] ✅ [Item 3] ### Out of Scope ❌ [Item 1] ❌ [Item 2] ### Success Criteria **Technical**: - [Criterion 1] - [Criterion 2] **Business**: - [Criterion 1] - [Criterion 2] --- ## Phase Breakdown [Include all 7 phases with tasks, durations, teams, deliverables, exit criteria] ### Phase 0: Discovery & Assessment [Detailed breakdown as created above] ### Phase 1: Security Remediation [Detailed breakdown] [... Phases 2-7 ...] --- ## Timeline & Milestones [Gantt chart and milestone table] --- ## Resource Allocation [Team assignments and capacity planning] --- ## Risk Management [Risk register and mitigation strategies] --- ## Quality Gates [All 8 quality gates with criteria] --- ## Contingency Plans [What-if scenarios and responses] --- ## Communication Plan ### Status Reporting - **Daily**: Stand-up (15 min) - **Weekly**: Status report to stakeholders - **Bi-weekly**: Executive update - **Monthly**: Board update (if applicable) ### Escalation Path 1. Team Lead 2. Tech Lead / Coordinator 3. Engineering Manager 4. CTO 5. Executive Sponsor --- ## Appendices ### A. Dependency Migration Matrix [Detailed dependency upgrade plan] ### B. Breaking Changes Guide [All breaking changes with remediation] ### C. Test Strategy [Testing approach for each phase] ### D. Deployment Strategy [How changes will be deployed] --- **Plan Version**: 1.0 **Last Updated**: [Date] **Next Review**: [Every 2 weeks during execution] ``` --- ## Usage Examples ### Example 1: With Assessment ``` User: /modernize-plan Claude: Checking for ASSESSMENT.md... ✅ Found ASSESSMENT.md (score: 78/100, PROCEED WITH CAUTION) Using assessment findings: - Technical Viability: 82/100 - Business Value: 74/100 - Risk Profile: MEDIUM (3 HIGH risks) - Estimated Effort: 22-28 days Creating detailed plan... [Generates comprehensive plan based on assessment] Phase 0: Discovery (2 days) - Already have baseline from assessment - Focus on detailed breaking changes - Estimated: 2 days vs 1-2 days typical Phase 1: Security (3-5 days) - Assessment identified 3 CRITICAL, 12 HIGH CVEs - [Detailed remediation plan] [Continues through all phases] ✅ PLAN.md created (47 pages) Summary: - Duration: 24 weeks - Team: 3 developers - Milestones: 8 quality gates - Timeline includes 30% contingency buffer ``` ### Example 2: Without Assessment ``` User: /modernize-plan Claude: No ASSESSMENT.md found. Running quick assessment first... [30-minute abbreviated assessment] Quick Assessment Results: - Project Size: Medium (~35k LOC) - Current: .NET 6 - Target: .NET 9 - Rough Estimate: 25-35 days ⚠️ Recommendation: Run full /modernize-assess for better accuracy Creating plan with conservative estimates... [Generates plan with wider ranges] ✅ PLAN.md created Note: This plan has wider time/cost ranges due to limited assessment. Consider running /modernize-assess for refined planning. ``` --- ## Best Practices 1. **Use Assessment** - Always run `/modernize-assess` first 2. **Be Realistic** - Conservative estimates prevent disappointment 3. **Include Buffer** - 30% contingency is standard 4. **Define Gates** - Clear decision points prevent drift 5. **Plan Contingencies** - Murphy's law applies 6. **Get Buy-in** - Review plan with all stakeholders before execution --- ## Integration with /modernize-project The plan created by this command is **automatically used** by `/modernize-project`: ``` User: /modernize-project Claude: Checking for existing plan... ✅ Found PLAN.md Using existing plan: - 7 phases defined - 24 weeks timeline - 3 developers allocated - 8 quality gates Proceeding with execution... [Follows plan exactly] ``` --- **Document Owner**: Migration Coordinator **Protocol Version**: 1.0 **Last Updated**: 2025-10-25 **Required Before**: Running `/modernize-project` **Remember**: **Plans are worthless, but planning is essential. Create the plan, then adapt as needed.** ✅