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)

# 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:

---

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:

---

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:

---

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

# 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. ✅