/legacy-modernize

description: "Orchestrate legacy system modernization using the strangler fig pattern with gradual component replacement"
argument-hint: "<legacy codebase path or description> [--strategy parallel-systems|big-bang|by-feature|database-first|api-first]"

Legacy Code Modernization Workflow

CRITICAL BEHAVIORAL RULES

You MUST follow these rules exactly. Violating any of them is a failure.

1. **Execute steps in order.** Do NOT skip ahead, reorder, or merge steps. 2. **Write output files.** Each step MUST produce its output file in `.legacy-modernize/` before the next step begins. Read from prior step files — do NOT rely on context window memory. 3. **Stop at checkpoints.** When you reach a `PHASE CHECKPOINT`, you MUST stop and wait for explicit user approval before continuing. Use the AskUserQuestion tool with clear options. 4. **Halt on failure.** If any step fails (agent error, test failure, missing dependency), STOP immediately. Present the error and ask the user how to proceed. Do NOT silently continue. 5. **Use only local agents.** All `subagent_type` references use agents bundled with this plugin or `general-purpose`. No cross-plugin dependencies. 6. **Never enter plan mode autonomously.** Do NOT use EnterPlanMode. This command IS the plan — execute it.

Pre-flight Checks

Before starting, perform these checks:

1. Check for existing session

Check if `.legacy-modernize/state.json` exists:

• If it exists and `status` is `"in_progress"`: Read it, display the current step, and ask the user:

  Found an in-progress legacy modernization session:
  Target: [target from state]
  Current step: [step from state]

  1. Resume from where we left off
  2. Start fresh (archives existing session)

• If it exists and `status` is `"complete"`: Ask whether to archive and start fresh.

2. Initialize state

Create `.legacy-modernize/` directory and `state.json`:

{
  "target": "$ARGUMENTS",
  "status": "in_progress",
  "strategy": "parallel-systems",
  "current_step": 1,
  "current_phase": 1,
  "completed_steps": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}

Parse `$ARGUMENTS` for `--strategy` flag. Use `parallel-systems` as default if not specified.

3. Parse target description

Extract the target description from `$ARGUMENTS` (everything before the flags). This is referenced as `$TARGET` in prompts below.

---

Phase 1: Legacy Assessment and Risk Analysis (Steps 1–3)

Step 1: Comprehensive Legacy System Analysis

Use the Task tool with subagent_type="framework-migration-legacy-modernizer":

Task:
  subagent_type: "framework-migration-legacy-modernizer"
  description: "Analyze legacy codebase for modernization readiness"
  prompt: |
    Analyze the legacy codebase at $TARGET. Document a technical debt inventory including:
    - Outdated dependencies and deprecated APIs
    - Security vulnerabilities and performance bottlenecks
    - Architectural anti-patterns

    Generate a modernization readiness report with:
    - Component complexity scores (1-10)
    - Dependency mapping between modules
    - Database coupling analysis
    - Quick wins vs complex refactoring targets

    Write your complete assessment as a single markdown document.

Save the agent's output to `.legacy-modernize/01-legacy-assessment.md`.

Update `state.json`: set `current_step` to 2, add `"01-legacy-assessment.md"` to `files_created`, add step 1 to `completed_steps`.

Step 2: Dependency and Integration Mapping

Read `.legacy-modernize/01-legacy-assessment.md` to load assessment context.

Use the Task tool with subagent_type="framework-migration-architect-review":

Task:
  subagent_type: "framework-migration-architect-review"
  description: "Create dependency graph and integration point catalog"
  prompt: |
    Based on the legacy assessment report below, create a comprehensive dependency graph.

    ## Legacy Assessment
    [Insert full contents of .legacy-modernize/01-legacy-assessment.md]

    ## Deliverables
    1. Internal module dependencies
    2. External service integrations
    3. Shared database schemas and cross-system data flows
    4. Integration points requiring facade patterns or adapter layers during migration
    5. Circular dependencies and tight coupling that need resolution

    Write your complete dependency analysis as a single markdown document.

Save the agent's output to `.legacy-modernize/02-dependency-map.md`.

Update `state.json`: set `current_step` to 3, add step 2 to `completed_steps`.

Step 3: Business Impact and Risk Assessment

Read `.legacy-modernize/01-legacy-assessment.md` and `.legacy-modernize/02-dependency-map.md`.

Use the Task tool with subagent_type="general-purpose":

Task:
  subagent_type: "general-purpose"
  description: "Evaluate business impact and create migration roadmap"
  prompt: |
    You are a business analyst specializing in technology transformation and risk assessment.

    Evaluate the business impact of modernizing each component identified in the assessment and dependency analysis below.

    ## Legacy Assessment
    [Insert contents of .legacy-modernize/01-legacy-assessment.md]

    ## Dependency Map
    [Insert contents of .legacy-modernize/02-dependency-map.md]

    ## Deliverables
    1. Risk assessment matrix considering: business criticality (revenue impact), user traffic patterns, data sensitivity, regulatory requirements, and fallback complexity
    2. Prioritized components using weighted scoring: (Business Value x 0.4) + (Technical Risk x 0.3) + (Quick Win Potential x 0.3)
    3. Rollback strategies for each component
    4. Recommended migration order

    Write your complete business impact analysis as a single markdown document.

Save the agent's output to `.legacy-modernize/03-business-impact.md`.

Update `state.json`: set `current_step` to "checkpoint-1", add step 3 to `completed_steps`.

---

PHASE CHECKPOINT 1 —