zhongwei/gh-laird-agents-plugins-modernize

Files

Zhongwei Li 748a979a78 Initial commit

2025-11-30 08:36:51 +08:00

23 KiB

Raw Permalink Blame History

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:

Project Inventory (4 hours)
- Map all projects/modules
- Identify dependencies
- Document current architecture
- Deliverable: Project inventory spreadsheet
Security Baseline (4 hours)
- Run vulnerability scan
- Categorize vulnerabilities
- Calculate security score
- Deliverable: Security baseline report
Test Baseline (4 hours)
- Run all existing tests
- Capture pass rates and coverage
- Document test infrastructure
- Deliverable: Test baseline report
Technology Assessment (4 hours)
- Research target framework
- Document breaking changes
- Identify obsolete APIs
- Deliverable: Technology assessment document
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:

Fix CRITICAL Vulnerabilities (XX hours)
- CVE-XXXX-XXXX: [Package] → [Action]
- CVE-YYYY-YYYY: [Package] → [Action]
- Deliverable: Zero CRITICAL CVEs
Fix HIGH Vulnerabilities (YY hours)
- CVE-ZZZZ-ZZZZ: [Package] → [Action]
- [List all HIGH CVEs with remediation plan]
- Deliverable: Zero HIGH CVEs
Update Security Dependencies (ZZ hours)
- [Package 1]: v[Old] → v[New]
- [Package 2]: v[Old] → v[New]
- Deliverable: All security patches applied
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:

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
Dependency Migration Matrix (6 hours)
- Map all dependencies to target versions
- Identify conflicts
- Define resolution strategy
- Deliverable: Dependency migration matrix
Breaking Changes Analysis (8 hours)
- Enumerate all breaking changes
- Estimate code impact %
- Create remediation guide
- Deliverable: Breaking changes guide
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)

Update framework target
Update package references
Fix compilation errors
Run tests (100% pass required)
Code review
Deliverable: Module A migrated

Module B: [Name] (YY hours) [Similar breakdown]

Module C: [Name] (ZZ hours) [Similar breakdown]

Integration (WW hours)

Merge all modules
Resolve conflicts
Full solution build
Complete test suite
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:

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
Apply Modern Patterns (YY hours)
- async/await conversion
- Pattern matching
- Record types
- Deliverable: Modern code patterns applied
Enhance Test Coverage (ZZ hours)
- Add missing unit tests
- Add integration tests
- Target ≥85% coverage
- Deliverable: 85% code coverage
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:

Baseline Benchmarks (4 hours)
- Define performance tests
- Capture baseline metrics
- Set improvement targets
- Deliverable: Baseline report
Identify Bottlenecks (8 hours)
- Run profiler
- Analyze hot paths
- Prioritize optimizations
- Deliverable: Optimization backlog
Implement Optimizations (XX hours)
- [Optimization 1]
- [Optimization 2]
- [Optimization 3]
- Deliverable: Performance improvements
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:

CHANGELOG.md (6 hours)
- Document breaking changes
- New features/improvements
- Bug fixes
- Security updates
- Deliverable: Complete CHANGELOG
MIGRATION-GUIDE.md (12 hours)
- Step-by-step upgrade guide
- Breaking changes details
- Before/after examples
- Troubleshooting
- Deliverable: Comprehensive migration guide (800+ lines)
Update Documentation (8 hours)
- Update README
- Update architecture docs
- Update API docs
- Deliverable: All docs current
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:

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
Final Security Scan (4 hours)
- Run vulnerability scan
- Verify security score ≥45
- Document any LOW/MEDIUM issues
- Deliverable: Security approval
Release Preparation (8 hours)
- Create release notes
- Tag release version
- Package artifacts
- Deployment checklist
- Deliverable: Release package
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

Use Assessment - Always run /modernize-assess first
Be Realistic - Conservative estimates prevent disappointment
Include Buffer - 30% contingency is standard
Define Gates - Clear decision points prevent drift
Plan Contingencies - Murphy's law applies
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. ✅

23 KiB Raw Permalink Blame History

Plan Command

Project Modernization Planning Protocol

Overview

Planning Process

Step 1: Load Assessment (if available)

Step 2: Define Modernization Scope (30 minutes)

2.1 Objectives

2.2 Success Criteria

Step 3: Phase Planning (60-90 minutes)

Phase 0: Discovery & Assessment

Phase 1: Security Remediation

Phase 2: Architecture & Design

Phase 3: Framework & Dependency Modernization

Phase 4: API Modernization & Code Quality

Phase 5: Performance Optimization

Phase 6: Comprehensive Documentation

Phase 7: Final Validation & Release

Step 4: Timeline & Milestones (30 minutes)

Gantt Chart

Milestones

Step 5: Resource Allocation (30 minutes)

Team Assignments

Capacity Planning

Step 6: Risk Management (45 minutes)

Risk Register

Mitigation Strategies

Step 7: Quality Gates & Decision Points (20 minutes)

Gate Criteria

Step 8: Contingency Planning (30 minutes)

What-If Scenarios

PLAN.md Output Template

Usage Examples

Example 1: With Assessment

Example 2: Without Assessment

Best Practices

Integration with /modernize-project

23 KiB

Raw Permalink Blame History