An open-source, AI-assisted methodology for modernizing legacy applications — built for AI IDEs like Kiro, GitHub Copilot (VS Code), Claude Code, and Codex. Drop this into your workspace alongside your legacy codebase and let the structured process guide you from assessment to actionable plan.

Designed for multi-application landscapes. Assess each application individually, then analyze them as a whole — shared databases, overlapping business logic, hidden coupling, and consolidation opportunities only become visible when you look at the full picture.

Created by Burly Mingo LLC.

A workspace template that packages a complete modernization methodology with native support for Kiro (steering/specs/hooks), GitHub Copilot (custom instructions/prompt files), Claude Code (CLAUDE.md/slash commands), and Codex (system instructions/runbooks). It guides an AI assistant (and the human domain expert working with it) through a structured process that produces real engineering deliverables:

• Per-application architecture assessments with 7 R's classification
• Consolidated cross-application analysis (shared data sources, hidden coupling, consolidation opportunities)
• Prioritized pain point analysis
• Target architecture design with buy vs. build decisions
• Phased modernization plan with timelines and costs
• Business case, DR plan, staffing recommendation, and security remediation plan

Works for a single application, but the methodology is at its best with multiple interconnected applications — that's where the consolidated analysis reveals insights no per-app assessment can surface.

• A magic prompt that produces a plan without human input
• A 1:1 code translation tool
• A replacement for domain expertise or professional implementation services
• Tied to any specific source or target technology stack

• Organizations considering modernization who want a detailed, honest assessment before committing budget. The plan this produces gives you the information to make an informed go/no-go decision.
• Internal teams planning a modernization who want a structured process instead of ad-hoc discovery.
• Organizations hiring a consulting firm who want to walk into that engagement with a real blueprint — specific enough to hold vendors accountable to scope, timeline, and cost. A detailed plan is leverage at the negotiating table.
• Consulting firms themselves who want a repeatable methodology for the assessment and planning phase of modernization engagements.

The methodology has 6 phases, each producing a specific deliverable with a human review checkpoint:

Important: The .kiro/ folder must be at the root of the directory you open in Kiro. Kiro looks for .kiro/steering/, .kiro/specs/, and .kiro/hooks/ at the workspace root — if .kiro/ is nested inside a subfolder, Kiro won't see it. All three setup paths below place .kiro/ at the root of the workspace you'll open.

Add to an existing project (recommended):

These commands work on macOS and Linux. On Windows, use Git Bash, WSL, or equivalent.

# From your project's root directory (where your legacy code lives)
git clone https://github.com/Burly-Mingo/modernization-kit.git /tmp/mod-kit
cp -r /tmp/mod-kit/.kiro .
cp -r /tmp/mod-kit/.codex .
cp -r /tmp/mod-kit/.claude .
cp -r /tmp/mod-kit/.github .
cp /tmp/mod-kit/CLAUDE.md .
cp /tmp/mod-kit/MODERNIZATION_METHODOLOGY.md .
rm -rf /tmp/mod-kit

Then open the workspace in your AI IDE. For Kiro, the steering files activate automatically and specs appear in the spec panel. For VS Code with Copilot, the custom instructions load automatically. For Claude Code, CLAUDE.md loads automatically and slash commands are available via /phase-*. For Codex, load the system instructions manually.

Multi-application workspace (optimal):

# Create a workspace that contains all related applications
mkdir my-modernization && cd my-modernization
git clone https://github.com/Burly-Mingo/modernization-kit.git /tmp/mod-kit
cp -r /tmp/mod-kit/.kiro .
cp -r /tmp/mod-kit/.codex .
cp -r /tmp/mod-kit/.claude .
cp -r /tmp/mod-kit/.github .
cp /tmp/mod-kit/CLAUDE.md .
cp /tmp/mod-kit/MODERNIZATION_METHODOLOGY.md .
rm -rf /tmp/mod-kit

# Add your applications (copy, symlink, or git submodule)
# e.g.:
# cp -r /path/to/app-one ./app-one
# cp -r /path/to/app-two ./app-two
# git submodule add https://repo/app-three ./app-three
# Open my-modernization/ in Kiro (not a parent folder)

Having all applications in one workspace lets the AI see shared databases, overlapping stored procedures, cross-app API calls, and data coupling that's invisible when assessing apps in isolation. The consolidated assessment step in Phase 1 depends on this.

Start fresh (single app):

git clone https://github.com/Burly-Mingo/modernization-kit.git my-modernization
cd my-modernization
# Add your legacy codebase to this workspace (copy, symlink, or git submodule)
# Open my-modernization/ in Kiro

Don't clone this repo as a subfolder inside another workspace (e.g., my-project/modernization-kit/). The .kiro/ folder would be nested and Kiro won't detect it. Always copy the .kiro/, .codex/, .claude/, and .github/ folders (plus CLAUDE.md) to the root of whatever directory you open in your IDE.

What happens when you open in Kiro:

1. The 4 steering files in .kiro/steering/ activate automatically — they guide the AI's behavior for the entire engagement (core principles, regulatory awareness, buy vs. build framework, anti-patterns)
2. The 6 specs in .kiro/specs/ appear in the Kiro spec panel — each one is a phase of the methodology with requirements, design approach, and tasks
3. The 3 hooks in .kiro/hooks/ provide guardrails — human review reminders, open question tracking, and compliance consistency checks
4. Start a conversation and open the Phase 0 spec. The AI will begin the Discovery Interview.

What happens when you open in VS Code (Copilot):

1. .github/copilot-instructions.md loads automatically as custom instructions — core principles and methodology overview
2. Reference the phase prompt files in .github/prompts/ from Copilot Chat to work through each phase
3. Quality gates are manual — use the checklist in the instructions file before moving phases

What happens when you run Claude Code:

1. CLAUDE.md loads automatically — core principles and methodology overview
2. Type /phase-0-discovery (or any /phase-* command) to start that phase
3. Quality gates are manual — use the checklist in CLAUDE.md before moving phases

.kiro/                                     # Kiro IDE — full native support
├── steering/                              # Always-active AI guidance
│   ├── 00-modernization-principles.md     # Core principles and interaction style
│   ├── 01-regulatory-reference.md         # Compliance framework quick reference
│   ├── 02-buy-vs-build.md                 # Decision framework for component selection
│   └── 03-anti-patterns.md                # What not to do (learned from real projects)
│
├── specs/                                 # Phased workflow with requirements, design, and tasks
│   ├── phase-0-discovery/                 # Organization, industry, regulations, infrastructure, goals
│   ├── phase-1-codebase-analysis/         # Read the code, produce factual assessments
│   ├── phase-2-pain-points/               # Interview users, prioritize what hurts
│   ├── phase-3-target-architecture/       # Design the future state
│   ├── phase-4-modernization-plan/        # Phased implementation plan
│   └── phase-5-supporting-docs/           # Business case, DR, staffing, security
│
└── hooks/                                 # Automated guardrails
    ├── checkpoint-reminder.json           # Pause for human review after each deliverable
    ├── open-questions-tracker.json        # Flag unknowns in deliverables
    └── compliance-check.json              # Validate compliance consistency across documents

.github/                                   # GitHub Copilot (VS Code) — native support
├── copilot-instructions.md                # Always-on custom instructions (principles + methodology)
└── prompts/                               # Per-phase prompt files for Copilot Chat
    ├── phase-0-discovery.prompt.md
    ├── phase-1-codebase-analysis.prompt.md
    ├── phase-2-pain-points.prompt.md
    ├── phase-3-target-architecture.prompt.md
    ├── phase-4-modernization-plan.prompt.md
    └── phase-5-supporting-docs.prompt.md

CLAUDE.md                                  # Claude Code — always-on instructions (auto-loaded)
.claude/                                   # Claude Code — slash commands
└── commands/                              # Per-phase slash commands (/phase-0-discovery, etc.)
    ├── phase-0-discovery.md
    ├── phase-1-codebase-analysis.md
    ├── phase-2-pain-points.md
    ├── phase-3-target-architecture.md
    ├── phase-4-modernization-plan.md
    └── phase-5-supporting-docs.md

.codex/                                    # Codex — native support
├── README.md                              # Quick start for Codex users
├── context/system-instructions.md         # Always-on system instructions
├── runbooks/phase-workflow.md             # Phase-by-phase runbook
└── checklists/quality-gates.md            # Manual quality gates

• Modernize, don't translate. Rethink the architecture, don't just change the language.
• Containers by default, not by dogma. Cloud-agnostic is the recommendation, but respect organizational preferences.
• Buy vs. build at every decision point. Know the audience — some orgs need vendor support, others embrace open source.
• AI-assisted, spec-driven development. Experienced dev + Kiro specs = significantly faster. Not vibe coding.
• New tech stacks are not the barrier they once were. AI IDEs let teams adopt the right technology, not just the familiar one.
• Comprehensive automated testing is a baseline. AI makes generating unit, integration, and API tests fast enough to be non-negotiable.
• Honest about unknowns. "I don't know" is always better than a confident guess.
• Security is Phase 0. Fix critical vulnerabilities before modernization begins.
• The human is always right about their domain. The AI reads code. The human understands the business.

• An AI IDE — this kit ships with native support for Kiro (steering/specs/hooks), GitHub Copilot in VS Code (custom instructions/prompt files), Claude Code (CLAUDE.md/slash commands), and Codex (system instructions/runbook). Kiro's spec-driven workflow provides the richest experience (structured requirements → design → tasks with automated hooks), but the methodology works in any AI IDE.
• A capable model — Claude Opus 4.6+ (Kiro), GPT-4o/o1+ (Copilot), or equivalent. The codebase analysis, architecture design, and plan generation require a model that can hold large context and reason about complex systems. Lesser models will produce lesser plans.
• Codebase access — the AI needs to read the actual source code
• A domain expert — someone who understands the business processes. Reviews every deliverable. This is the irreplaceable ingredient.
• Time for iteration — each phase involves analysis → review → correction → revision

These Model Context Protocol servers significantly improve the methodology experience in Kiro. None are strictly required, but each one solves a real problem.

Memory (@modelcontextprotocol/server-memory) — A modernization engagement spans multiple sessions over days or weeks. The Memory MCP maintains a persistent knowledge graph across sessions — discovery findings, regulatory frameworks, architecture decisions, open questions, and cross-application dependencies survive between conversations instead of evaporating. This is the single most impactful MCP for this methodology.

"memory": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-memory"],
  "disabled": false,
  "autoApprove": ["create_entities", "add_observations", "search_nodes"]
}

Sequential Thinking (@modelcontextprotocol/server-sequential-thinking) — Architecture decisions in Phase 3 and plan sequencing in Phase 4 involve complex trade-offs with multiple interacting constraints (compliance, team size, budget, existing infrastructure, cross-app dependencies). Sequential thinking helps the AI reason through these systematically rather than jumping to conclusions.

"sequential-thinking": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
  "disabled": false,
  "autoApprove": ["sequentialthinking"]
}

Context7 (@upstash/context7-mcp) — When the AI recommends specific technologies (Keycloak, K3s, PostgreSQL, etc.), Context7 lets it pull current documentation rather than relying on training data that may be outdated. Useful during Phase 3 architecture design and Phase 4 when estimating implementation effort.

"context7": {
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"],
  "disabled": false,
  "autoApprove": ["resolve-library-id", "query-docs"]
}

Add these to .kiro/settings/mcp.json (workspace-level) or ~/.kiro/settings/mcp.json (user-level). Requires npx (Node.js). See MCP documentation for setup details.

This kit ships with native support for four AI IDEs. The methodology is the same — only the delivery mechanism differs:

For other AI IDEs: steering files → system prompts, specs → task lists, hooks → manual checkpoints.

This kit includes a .github/ compatibility layer for GitHub Copilot in VS Code.

• Copilot reads .github/copilot-instructions.md automatically as custom instructions
• Per-phase prompt files in .github/prompts/ are invokable in Copilot Chat
• Same deliverables, same methodology, same quality gates

Quick start:

1. Open this workspace in VS Code with GitHub Copilot enabled
2. The custom instructions load automatically — they contain the core principles and methodology overview
3. In Copilot Chat, reference a phase prompt file to start that phase (e.g., type @workspace and reference /prompts/phase-0-discovery.prompt.md)
4. Work through phases 0-5 in order, with human review at each checkpoint

What's different from Kiro: Copilot doesn't have hooks (automated guardrails), so quality gates are manual — use the checklist in copilot-instructions.md before moving to the next phase. Copilot also doesn't have Kiro's spec panel, so the prompt files serve as the phase-by-phase workflow guide.

.github/
├── copilot-instructions.md              # Always-on custom instructions (principles + methodology)
└── prompts/                             # Per-phase prompt files for Copilot Chat
    ├── phase-0-discovery.prompt.md
    ├── phase-1-codebase-analysis.prompt.md
    ├── phase-2-pain-points.prompt.md
    ├── phase-3-target-architecture.prompt.md
    ├── phase-4-modernization-plan.prompt.md
    └── phase-5-supporting-docs.prompt.md

This kit includes a CLAUDE.md + .claude/ compatibility layer for Claude Code (Anthropic's CLI agent).

• CLAUDE.md at the project root loads automatically every session — core principles and methodology overview
• Per-phase slash commands in .claude/commands/ are invokable as /phase-0-discovery through /phase-5-supporting-docs
• Same deliverables, same methodology, same quality gates

Quick start:

1. Open this workspace directory in Claude Code (claude from the terminal)
2. CLAUDE.md loads automatically
3. Type /phase-0-discovery to start the Discovery Interview
4. Work through phases 0-5 in order, with human review at each checkpoint

CLAUDE.md                                # Always-on instructions (auto-loaded every session)
.claude/
└── commands/                            # Per-phase slash commands
    ├── phase-0-discovery.md             # /phase-0-discovery
    ├── phase-1-codebase-analysis.md     # /phase-1-codebase-analysis
    ├── phase-2-pain-points.md           # /phase-2-pain-points
    ├── phase-3-target-architecture.md   # /phase-3-target-architecture
    ├── phase-4-modernization-plan.md    # /phase-4-modernization-plan
    └── phase-5-supporting-docs.md       # /phase-5-supporting-docs

This kit includes a .codex/ compatibility layer so you can run the same methodology in Codex without forking the repo.

• Kiro uses .kiro/ (steering/specs/hooks)
• Copilot uses .github/ (custom instructions/prompt files)
• Claude Code uses CLAUDE.md + .claude/ (instructions/slash commands)
• Codex uses .codex/ (system instructions/runbook/quality gates)
• All four produce the same deliverables in the workspace root

Start with .codex/README.md, then load .codex/context/system-instructions.md and follow .codex/runbooks/phase-workflow.md.

This methodology was developed by Burly Mingo LLC during a real modernization engagement — three legacy ASP.NET WebForms applications (VB.NET + C#, .NET 4.5-4.7, 9 SQL Server databases) being modernized to a unified platform (ASP.NET Core 9, React/Next.js, PostgreSQL, Redis, K3s). The entire process was conducted in Kiro IDE with Claude Opus 4.6, producing a 1,600-line modernization plan, business case, DR plan, staffing recommendation, and security assessments over 12+ collaborative sessions.

The key insight: the plan's quality came from iteration and domain expertise, not from a clever prompt. Every time the human corrected the AI ("Not Blazor — React." "EF Core alone won't cut it." "You need Redis for this workflow."), the plan got dramatically better. Kiro's spec-driven workflow made this iteration structured and productive rather than chaotic.

A second insight emerged from having all three applications in one workspace: assessing them individually produced useful findings, but assessing them together revealed shared databases, overlapping stored procedures, cross-app data dependencies, and consolidation opportunities that no single-app assessment could surface. The multi-app consolidated analysis fundamentally changed the migration strategy, timeline, and data architecture. This kit packages both insights — the iterative human-in-the-loop process and the multi-app holistic analysis — so others can follow them.

MIT. Use it, fork it, improve it, sell consulting services around it. Just don't pretend a prompt alone produces a good modernization plan — the human in the loop is what makes it work.

Built with Kiro + Claude Opus 4.6, with native support for GitHub Copilot, Claude Code, and Codex. If you're modernizing legacy systems without AI-assisted development, you're working too hard.

A Burly Mingo LLC open source project.