Work with GitHub Copilot modernization

This article covers how to communicate with the GitHub Copilot modernization agent, teach it your preferences, correct mistakes, review its work, and manage upgrades across multiple sessions.

GitHub Copilot modernization is an interactive collaborator that asks questions, proposes strategies, adapts to your feedback, and learns from your preferences over time. To get the best results, give the agent context. The more it knows about your goals, constraints, and preferences, the better it performs.

❌ Vague — the agent has to guess
"Upgrade my project"

✅ Specific — the agent knows exactly what you need
"Upgrade the WebAPI project to .NET 10. We need to keep backward
compatibility with our existing REST clients, and we can't change the
public API surface."

Start a conversation

1. Open Copilot Chat in VS Code, Visual Studio, or Copilot CLI.
2. Select the GitHub Copilot modernization agent for .NET from the agent picker, or type the correct agent mention for your environment: @modernize-dotnet in VS Code and Copilot CLI, or @Modernize in Visual Studio.
3. Describe what you want to accomplish in natural language.

What to say

Natural language works. Try these examples:

What happens next

When you start a conversation, the agent checks for existing upgrade work in your workspace:

• If there's no existing work, the agent starts fresh, typically beginning with an assessment of your solution.
• If there's existing work in progress, the agent picks up where you left off and shows current status, such as "3 of 8 tasks completed."

Choose a flow mode

The agent supports two flow modes that control how much the agent pauses for your input.

Automatic mode

In automatic mode, the agent works through the stages (assessment, planning, execution) without pausing for approval at each boundary. The agent still stops at genuine blockers or when it needs a decision only you can make.

Best for experienced users, straightforward upgrades, and small solutions.

Guided mode

In guided mode, the agent pauses at each stage boundary for your review:

• After assessment, before creating the plan.
• After planning, before executing any tasks.
• Before complex task breakdowns.
• At key decision points where multiple valid approaches exist.

Best for first-time users, complex solutions, and when you want to learn the process.

Switch modes mid-session

Switch freely between modes at any time:

Teach the agent

The agent learns from you. The agent saves your corrections, preferences, and instructions to scenario-instructions.md in the upgrade state folder. These preferences persist across sessions.

Correct mistakes

When the agent makes a decision you disagree with, tell the agent:

You: "Actually, don't use Newtonsoft.Json — we're standardizing on System.Text.Json."
Agent: "Got it. I'll use System.Text.Json for all serialization going forward.
        I've saved this as a preference."

The agent updates scenario-instructions.md and won't make the same choice again, even in a future session.

Set preferences

Proactively tell the agent how you like things done:

You: "Always use bottom-up strategy for this solution — upgrade leaf projects first."
Agent: "Noted. I'll use a bottom-up upgrade strategy, starting with projects that
        have no internal dependencies and working up to the top-level projects."

Give task-specific instructions

Sometimes a preference only applies to a specific task:

You: "For this task, skip the test validation — the tests are broken for a known
      reason and we'll fix them separately."
Agent: "Understood. I'll skip test validation for this task only."

What the agent saves

The scenario-instructions.md file is organized into clear sections:

Make mid-session corrections

The agent handles interruptions gracefully and doesn't lose track of where it is or what it was doing.

Pause and review

You: "Wait, stop — let me review that change first."
Agent: "Here's what I was about to do: [describes planned changes].
        Would you like me to proceed, or adjust the approach?"

Redirect

You: "Actually, let's do Project B before Project A — it has fewer dependencies."
Agent: "Good call. I'll reorder the tasks and start with Project B."

Undo

You: "That last change broke the build. Can we revert it?"
Agent: "I'll revert the last commit (abc1234: 'Migrate auth middleware').
        Reverting now."

Also revert commits yourself using standard Git commands. The agent writes clear, descriptive commit messages so you know exactly what each commit changed.

Ask questions mid-flow

Asking questions doesn't derail the workflow:

You: "Why did you choose to migrate the data layer before the API controllers?"
Agent: "The API controllers depend on the data layer interfaces. By migrating
        the data layer first, we avoid temporary compilation errors in the
        controllers and can validate each layer independently."

Review the agent's work

The agent provides multiple ways to review its work.

Source control

The agent suggests working on a separate branch and commits changes as it works. Review the agent's changes with standard Git commands:

git log --oneline -10
git diff main..<agent-branch>

Workflow files

The agent maintains several files in .github/upgrades/{scenarioId}/ that give you full visibility:

Resume interrupted work

Close the chat or shut down your IDE. The agent handles this situation seamlessly.

The agent stores all state in .github/upgrades/ inside your repository. When you start a new conversation, the agent checks the current state and immediately knows:

• Which scenario is active.
• Which tasks are completed, in progress, or pending.
• What artifacts exist (assessment, plan, task files).
• Whether any tasks appear stale (stuck in 🔄 status from a previous session).

Stale task detection

If a task is in progress from a previous session, the agent recognizes the task might be stale and offers options to continue, restart, or skip.

Work across multiple sessions

Large upgrades, such as a 20-project solution, a complex framework upgrade, or a multi-step modernization, often span multiple sessions over days or weeks. The agent handles multi-session work naturally:

• Persistent state: Everything is in .github/upgrades/. No in-memory state to lose.
• Session independence: Each chat session is independent. The agent reconstructs its context from the state files every time.
• Cross-IDE support: Start in VS Code, continue in Visual Studio or Copilot CLI. The state folder is the shared contract.

Tips for multi-session work

• Commit the state folder. Push .github/upgrades/ to your branch to back up the folder and make it visible to your team.
• Review between sessions. Read tasks.md and execution-log.md to refresh your memory on what happened in the last session.
• Update preferences as you learn. If you discover something in testing that should change the agent's approach, tell the agent at the start of the next session.

Ask for help

Not sure what the agent can do or where things stand? Ask:

Communicate effectively

The quality of your interaction directly affects the quality of the results.

Be specific about scope

"Upgrade just the Data.Access and Data.Models projects to .NET 10" gives the agent a clear focus. "Upgrade everything" works, but the agent makes more decisions on its own about ordering and priorities.

Share context

The agent doesn't know your business constraints unless you share them:

• "We're upgrading because Azure App Service is dropping .NET 8 support in November."
• "This is a high-traffic production service—zero behavioral changes in the API responses."

Express constraints

Tell the agent what it shouldn't do, not just what it should:

• "Don't change the public API surface—we have external consumers."
• "We can't upgrade Newtonsoft.Json yet—the team that owns shared contracts hasn't upgraded."
• "Don't touch the legacy reporting module—that's being rewritten separately."

Give feedback

Positive feedback helps just as much as corrections and confirms the agent is on the right track:

• "That upgrade looks great—do the same approach for the other repository project."
• "That works, but we prefer constructor injection over property injection in this codebase."

Quick reference

Related content

• What is GitHub Copilot modernization?
• Core concepts
• Best practices
• Customize GitHub Copilot modernization
• Troubleshoot GitHub Copilot modernization