@microsoft/modernize-plan-execute

---
name: modernize-plan-execute
description: "Execute an existing modernization plan for Java or .NET projects. USE FOR: run plan, execute plan, apply changes, modernize plan execute, start migration, run modernization, apply upgrade, implement plan, carry out migration. DO NOT USE FOR: running assessments (use modernize-assess), creating new plans (use modernize-plan-create)."
---

# Modernize Run Plan

> ⛔ **MANDATORY**: Follow [global-rules](../_shared/global-rules.md) for all operations.
>
> **NOTE**: A modernization plan must exist before executing. Plans can be created with **modernize-plan-create** or provided externally.

Execute an existing modernization plan to apply the planned changes to your Java or .NET project.

## Instructions

When the user invokes this command, follow these steps:

## Rule 0: Ensure the modernize CLI is Installed

⛔ **ALWAYS** verify the `modernize` CLI is available before running any `modernize` command.

Run the following check:

- **Linux/macOS (bash)**:
  ```bash
  export PATH="$PATH:$HOME/.local/bin" && command -v modernize
  ```
- **Windows (PowerShell)**:
  ```powershell
  $env:PATH += ";$env:LOCALAPPDATA\Programs\modernize"; Get-Command modernize -ErrorAction SilentlyContinue
  ```

If `modernize` is **not found**, install it by running the appropriate installer for the platform:

- **Linux/macOS (bash)**:
  ```bash
  curl -fsSL https://raw.githubusercontent.com/microsoft/modernize-cli/main/scripts/install.sh | sh
  ```
- **Windows (PowerShell)**:
  ```powershell
  irm https://raw.githubusercontent.com/microsoft/modernize-cli/main/scripts/install.ps1 | iex
  ```

After installation, the install script will print the exact PATH entry to add. Use that output to ensure the binary is on PATH for subsequent commands. If the script did not print a path, fall back to the default:

- **Linux/macOS (bash)**:
  ```bash
  export PATH="$PATH:$HOME/.local/bin"
  ```
- **Windows (PowerShell)**:
  ```powershell
  $env:PATH += ";$env:LOCALAPPDATA\Programs\modernize"
  ```

If the installation fails, explain the error and link the user to https://github.com/microsoft/modernize-cli for manual installation instructions.

### 1. Pre-Execution Check

Before collecting parameters, verify that a plan exists:

1. Check for the plan at `.github/modernize/<plan-name>` (default: `.github/modernize/modernization-plan`), there should be a `plan.md` and `tasks.json` file inside that directory
2. If no plan exists, inform the user and suggest running `/modernize-plan-create` first
3. If a plan exists, show a brief summary and ask for confirmation before proceeding
4. If multiple plans are found, list them and ask the user to specify which one to execute using `--plan-name <plan-name>`

**Example when no plan exists:**
```
I couldn't find a modernization plan at `.github/modernize/<plan-name>`.

Would you like me to:
1. Create a new plan first using /modernize-plan-create
2. Specify a different plan name if you have an existing plan elsewhere
```

### 2. Parameter Collection

All parameters are optional with sensible defaults.

**Optional Parameters:**

- `prompt`: Specific instructions for executing the plan. Default: `execute the plan`
  - Prompt: "Any specific instructions for executing the plan? (Default: 'execute the plan')"
- `--plan-name <plan-name>`: The name of the modernization plan. Default: `modernization-plan`, it is expected to be located at `.github/modernize/<plan-name>`
- `--source <source>`: Path to source project (relative or absolute local path). Default: `.`
- `--language <java|dotnet>`: The programming language for the modernization plan. Default: auto-detect

**Example interaction:**
```
I found the modernization plan at `.github/modernize/modernization-plan`.

Plan Summary:
- Phase 1: Update dependencies
- Phase 2: Migrate configuration
- Phase 3: Update deployment

Would you like to customize the execution?
- Specific instructions (default: "execute the plan")

Or I can proceed with defaults - just say "go" or "continue".
```

### 3. Validation

Before executing, validate:

- **`prompt`**: If provided, must not be empty
- **`--language`**: If provided, must be either `java` or `dotnet` (case-insensitive)
- **Plan exists**: Verify `.github/modernize/<plan-name>` exists before attempting execution

If validation fails, explain the issue clearly and ask the user to provide a corrected value.

### 4. Execution

Run the following command (always include `--no-tty` for plain text output):

```bash
modernize plan execute "<prompt>" [--plan-name <plan-name>] [--source <source>] [--language <java|dotnet>] --no-tty
```

**Important:** Properly escape the user-provided prompt when constructing the shell command to prevent injection. The command will execute for long-running tasks (up to 1 hour), so set the timeout to run the command to more than 1 hour, wait for it to complete and capture all output for the next step.

### 5. Results

After execution:

1. Report the execution status (success, partial success, or failure)
2. Summarize what changes were made
3. List completed tasks vs remaining tasks
4. Report execution progress
5. Suggest next steps based on results:
   - If all tasks completed: Suggest reviewing changes and running tests
   - If some tasks remain: Offer to continue execution or investigate issues
   - If failures occurred: Help diagnose and suggest remediation

## Error Handling

If the command fails:
1. Parse the error output to identify the root cause
2. Explain the error in user-friendly terms
3. Suggest corrective actions
4. Offer to retry with modified parameters or help investigate the issue

## Examples

**Execute with defaults:**
```
User: /modernize-plan-execute
Claude: [Checks for plan, shows summary]
Claude: Ready to execute. Proceed?
User: go
Claude: [Executes: modernize plan execute "execute the plan" --no-tty]
```

**Execute a specific plan:**
```
User: /modernize-plan-execute
User: run the dotnet8-upgrade plan
Claude: [Executes: modernize plan execute "execute the plan" --plan-name dotnet8-upgrade --no-tty]
```

**Execute with custom instructions:**
```
User: /modernize-plan-execute
User: focus on the dependency updates first
Claude: [Executes: modernize plan execute "focus on the dependency updates first" --no-tty]
```

**When no plan exists:**
```
User: /modernize-plan-execute
Claude: I couldn't find a plan at `.github/modernize/modernization-plan`.
        Would you like to create one first with /modernize-plan-create?
```