A Claude Code plugin providing production-validated protocols, specialized agents, and automation frameworks for systematic AI-assisted software modernization and development.
This plugin provides a complete modernization workflow (assess → plan → execute → improve) with 6 specialized agents and comprehensive protocol documentation. Features continuous improvement through retrospective analysis that learns from agent mistakes and user corrections. Created originally for .NET framework migrations, these tools are universally applicable to any software project requiring structured agent collaboration.
Install as Claude Code plugin:
- Use the /plugin command in claude code, and add this repo as a marketplace, then add the modernize plugin.
- Commands will be available as slash commands in Claude Code
Each command is a comprehensive protocol document (.md file) containing agent coordination, workflows, quality gates, and best practices:
-
/assess- Assessment protocol with viability evaluation (outputsASSESSMENT.md)- 8 assessment dimensions, scoring methodology, recommendation matrix
- Do this first to assess software for potential modernization
-
/plan- Planning protocol with detailed execution strategy (outputsPLAN.md)- Phase breakdown, timeline estimation, risk management, resource allocation
- Do this to propose a modernization plan
-
/modernize- Full modernization protocol with 7-phase workflow- Coordinates 6 specialist agents through Discovery → Security → Architecture → Framework → API → Performance → Documentation
- Do this to execute the plan. If there is no plan it will generate a plan and then execute it.
-
/retro- Retrospective protocol analyzing project history (outputsIMPROVEMENTS.md)- Reviews git history, user corrections, agent mistakes, protocol inefficiencies
- Do this after execution to assess how the project went and make improvement recommendations for future projects. This is optional.
-
/retro-apply- Improvement application protocol- Systematically updates commands, protocols, and automation based on retrospective findings
- Do this after
/retroif you agree with the recommendations.
Every command file includes:
- Agent coordination instructions - How 6 specialist agents work together (Migration Coordinator, Security, Architect, Coder, Tester, Documentation)
- Phase-by-phase workflows - Detailed steps with durations, deliverables, and success criteria
- Quality gates - Blocking criteria and validation checkpoints
- Examples - Real-world scenarios and usage patterns
- Anti-patterns - What NOT to do with explanations
- Troubleshooting - Common issues and solutions
- Best practices - Proven approaches and recommendations
-
Assess Viability
/assessEvaluates technical debt, risks, and ROI. Outputs
ASSESSMENT.md. -
Create Plan
/planDevelops detailed execution strategy with phases, timeline, and resources. Outputs
PLAN.md. -
Execute Modernization
/modernizeOrchestrates specialized agents through 7 phases:
- Discovery & Planning
- Security Assessment
- Architecture Decisions
- Framework Upgrade
- API Modernization
- Performance Optimization
- Documentation
-
Continuous Improvement (Optional)
/retroAfter project completion, analyzes history to identify process improvements. Reviews:
- User interruptions and corrections
- Agent behavioral issues (wrong tools, wasted effort)
- Protocol inefficiencies
- Automation opportunities
Outputs
IMPROVEMENTS.mdwith 3-5 evidence-based recommendations. -
Apply Improvements
/retro-applySystematically applies approved recommendations from
IMPROVEMENTS.md:- Updates command files with better agent behavior guidance
- Modifies protocols to prevent recurring issues
- Adds automation (scripts, hooks, CI/CD)
- Embeds lessons learned into workflow
Agents are invoked by Claude Code's Task tool when needed. They work together following established protocols:
- Architect makes technology decisions and creates ADRs
- Security scans for vulnerabilities and blocks on CRITICAL/HIGH issues
- Coder implements migrations and fixes
- Tester validates with comprehensive test suites (100% pass rate required)
- Documentation generates user-facing guides and changelogs
- Migration Coordinator orchestrates multi-stage workflows
agents/
├── commands/ # Slash commands (5 commands)
│ ├── assess.md # Assessment protocol with agent coordination
│ ├── plan.md # Planning protocol with execution strategy
│ ├── modernize.md # Full modernization protocol (7 phases, 6 agents)
│ ├── retro.md # Retrospective analysis protocol
│ └── retro-apply.md # Improvement application protocol
└── README.md
Note: Each command file IS a comprehensive protocol document containing:
- Complete phase-by-phase workflows
- Agent coordination instructions (Migration Coordinator, Security, Architect, Coder, Tester, Documentation)
- Quality gates and success criteria
- Examples, anti-patterns, and troubleshooting
- Best practices and implementation guidance
Previous versions had separate agents/, protocols/, and scripts/ directories. These have been consolidated into the command files for a streamlined structure.
- ✅ Proven results - Successfully guided 32/32 project migrations
- ✅ Universal applicability - Works with any software project, not just .NET
- ✅ Complete audit trail - HISTORY.md logging for all agent activities
- ✅ Quality gates - Automated validation at each stage
- ✅ Evidence-based evolution - Protocols continuously improved through retrospective analysis
- 🤖 6 specialized agents - Each with defined capabilities and responsibilities
- 🔄 Parallel execution - Multiple agents work independently on separate tasks
- 📊 Enforced quality - 100% test pass rate, security score ≥45/100
- 📝 Systematic workflows - 7-phase migration, 6-phase testing, 8-stage ADR lifecycle
- 🔍 Retrospective analysis - Analyzes git history, user corrections, agent mistakes
- 📈 Evidence-based recommendations - 3-5 specific improvements with quantified impact
- 🔧 Automated application - Updates commands, protocols, and automation
- 🎯 Learning from mistakes - Identifies wrong tool usage, wasted effort, requirement misunderstandings
- ♻️ Self-improving system - Each project makes the next one better
- ⏱️ Measurable impact - Recent improvements saved 27 hours per project
- 32/32 projects migrated successfully (100% success rate)
- 100% test pass rate (meets requirement)
- Security improvement from 0/100 → 45/100 (CRITICAL CVEs eliminated)
- Zero P0/P1 blocking issues in production
- 1,500+ lines of documentation auto-generated
Based on retrospective analysis of RawRabbit modernization, 5 evidence-based improvements were implemented:
-
Front-Load Test Environment Setup ⚡
- Phase 0 test setup now mandatory before any work begins
- Verified baseline metrics (build, tests, vulnerability scan) replace estimates
- Prevents "works on my machine" issues discovered too late
-
Spike-Driven ADR Process 🧪
- New Stage 2.5 for high-risk architectural decisions
- Requires empirical validation via spike branches before commitment
- 24-48hr stakeholder review period enforced
- Better decisions through evidence vs. desk research
-
Shift Security Validation Left 🔒
- New automated security scanning protocol
- Phase 0 baseline scan, continuous monitoring throughout project
- Security scores calculated from actual scans, never estimated
- Critical/High CVEs blocked earlier in workflow
-
Continuous Testing Strategy ✅
- Testing after EVERY stage, not delayed until Stage 4
- Tiered testing: Unit → Component → Integration → Performance
- Estimated 7 hours saved per project from early issue detection
- Issues found in Stage 1 vs Stage 4 dramatically cheaper to fix
-
Incremental Documentation 📝
- Status marker system:
⚠️ In Progress → ✅ Fixed (validated) → 📝 Documented - "Fixed" claims only after test validation passes
- Prevents aspirational documentation requiring corrective commits
- Accurate HISTORY.md audit trail
- Status marker system:
Combined Impact: 27 hours saved per project, earlier issue detection, verified (not estimated) security posture, empirical architectural decisions, and accurate documentation.
- Install the plugin by copying
commands/to your project - Run
/assessto evaluate modernization readiness - Run
/planto create execution strategy - Run
/modernizeto orchestrate the work - Monitor HISTORY.md for complete audit trail
- Run
/retroafter completion to identify improvements - Run
/retro-applyto embed lessons learned
- Complete a modernization project with
/modernize - Run
/retroto analyze what happened:- Reviews git history for user corrections
- Identifies agent behavioral issues
- Finds protocol inefficiencies
- Quantifies impact of improvements
- Review
IMPROVEMENTS.mdwith team - Run
/retro-applyto implement approved changes - Next project automatically benefits from improvements
- Install the plugin
- Start with
/assessto understand scope - Use
/planto create detailed execution strategy - Leverage multi-agent coordination with
/modernize - Apply continuous improvement with
/retroand/retro-apply
- Security score ≥45 before migration starts
- Build success 100% before next stage
- Test pass rate 100% before proceeding
- All P0/P1 issues resolved before release
- Framework Upgrades - .NET, Node.js, Python, Java, etc.
- Cloud Migrations - AWS, Azure, GCP platform changes
- Language Migrations - Java to Kotlin, JavaScript to TypeScript
- Database Migrations - SQL to NoSQL, version upgrades
- Legacy Modernization - Monolith to microservices, API updates
- Security Remediation - CVE scanning and vulnerability fixes
- Quality Assurance - Comprehensive testing and validation
- Documentation - Technical docs, migration guides, ADRs
| Version | Date | Changes |
|---|---|---|
| 2.6.0 | 2025-11-09 | Applied 5 evidence-based improvements from RawRabbit retrospective: front-load test setup, spike-driven ADRs, shift security left, continuous testing, incremental documentation. Impact: 27 hours saved per project |
| 2.5.0 | 2025-11-01 | Added continuous improvement workflow: /retro and /retro-apply commands for retrospective analysis and automated application of lessons learned |
| 2.4.2 | 2025-10-28 | Renamed /modernize:project to /modernize, removed agents/protocols/scripts in favor of streamlined commands |
| 2.4.1 | 2025-10-25 | Removed cost estimates, added time estimate disclaimers |
| 2.4.0 | 2025-10-25 | Added complete modernization workflow (assess → plan → execute) |
| 2.3.0 | 2025-10-25 | Added /modernize-project multi-agent orchestrator |
| 2.2.0 | 2025-10-25 | Restructured as Claude Code plugin |
| 1.0 | 2025-10-10 | Initial release with protocols and agent definitions |
- Repository: https://github.com/laird/agents
- MADR 3.0.0: https://adr.github.io/madr/ - ADR format specification
- Keep a Changelog: https://keepachangelog.com/ - CHANGELOG format
- Claude Code Docs: https://docs.claude.com/en/docs/claude-code/
MIT License - See repository for details
Status: Production-validated Applicability: Universal (all software projects) Original Context: .NET Framework Migration Maintained By: AI-assisted development community