microsoft · gurretl · Jul 30, 2026
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-01.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-01.md
@@ -18,15 +18,26 @@ Before pointing AI at a real .NET or Java application (challenges 2 and 3), you
 
 ## Actions
 
+* **Fork the sample applications** — fork both repositories into your own GitHub account. You need them here to dry-run your agent, and you will keep using them in Challenges 2 and 3:
+  * PhotoAlbum (.NET): `https://github.com/Azure-Samples/PhotoAlbum`
+  * PhotoAlbum-Java (Spring Boot): `https://github.com/Azure-Samples/PhotoAlbum-Java`
+
+  Clone your fork of **PhotoAlbum** locally and open it in VS Code — this clone is the *target repo* for the agent, skill, and MCP files you author below.
 * Read [docs/00-fundamentals.md](../docs/00-fundamentals.md) and review the base templates in [templates/](../templates/).
-* **Author a Custom Agent** — copy [templates/agents/modernization.agent.md](../templates/agents/modernization.agent.md) to `.github/agents/<name>.agent.md` in a target repo, replace every `{{PLACEHOLDER}}`, and tighten the tool allow-list so the assessment phase stays read-only (least privilege).
+* **Author a Custom Agent** — copy [templates/agents/modernization.agent.md](../templates/agents/modernization.agent.md) to `.github/agents/<name>.agent.md` in your PhotoAlbum clone, replace every `{{PLACEHOLDER}}`, and tighten the tool allow-list so the assessment phase stays read-only (least privilege).
 * **Author a Skill** — copy [templates/skills/modernization-skill/SKILL.md](../templates/skills/modernization-skill/SKILL.md) to `.github/skills/<skill-name>/SKILL.md`, and write an explicit `WHEN:` trigger description plus at least one transformation-rules table. Optionally use the [skill-creator](../templates/skills/skill-creator/SKILL.md) meta-skill to iterate.
 * **Configure MCP** — copy [templates/mcp/mcp.json](../templates/mcp/mcp.json) to `.vscode/mcp.json`, then run **MCP: List Servers** and confirm the `appmod-*` tools (registered by the App Modernization extensions) appear in the agent's tool picker.
-* **Dry-run the loop** — select your Custom Agent in Copilot Chat and prompt it to modernize a sample. Confirm it **stops at Gate 1 (assessment)** and **Gate 2 (plan)** before editing any code.
+* **Dry-run the loop** — reload VS Code, open Copilot Chat in your PhotoAlbum clone, and select your Custom Agent in the agent picker. Prompt it with something deliberately open-ended, such as *"Modernize this application following your workflow."*, and watch what it does:
+  * it must run the assessment, produce an assessment report, and **stop at Gate 1** waiting for your approval;
+  * after you approve, it must produce a plan and **stop at Gate 2**;
+  * at no point before those approvals may it edit source code.
+
+  This is a test of *behaviour*, not of output quality — the assessment itself does not have to be perfect. If the agent runs straight through and starts rewriting files, its definition is wrong (most often because `editFiles` is still in the tool list used by the assessment phase). Optionally, reject the plan once on purpose and confirm the agent revises it instead of proceeding.
 * Compare your work against the pre-tailored references shipped in [templates/](../templates/) (`dotnet-modernization.agent.md`, `dotnet-upgrade`, `java-modernization.agent.md`, `java-upgrade`).
 
 ## Success criteria
 
+* Both **PhotoAlbum** and **PhotoAlbum-Java** are forked into your GitHub account, and PhotoAlbum is cloned locally.
 * You can explain, in one sentence each, what an Agent, a Skill, and an MCP server contribute to a modernization workflow.
 * A valid Custom Agent (`.agent.md` with YAML frontmatter) exists, with a phased, gated workflow and a least-privilege tool list.
 * A valid Skill (`SKILL.md`) exists with an explicit `WHEN:` trigger description and at least one rules table.

diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-02.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-02.md
@@ -8,9 +8,7 @@ Use the GitHub Copilot App Modernization agent (modernize CLI) to assess and upg
 
 ## Actions
 
-* Fork the two sample repositories into your own GitHub account:
-  * PhotoAlbum-Java (Spring Boot): `https://github.com/Azure-Samples/PhotoAlbum-Java`
-  * PhotoAlbum (.NET): `https://github.com/Azure-Samples/PhotoAlbum`
+* You already forked both sample repositories in [Challenge 1](challenge-01.md) — make sure your forks of **PhotoAlbum** (.NET) and **PhotoAlbum-Java** (Spring Boot) are cloned into a single working directory before you continue.
 * Prepare a working directory and install the GitHub Copilot App Modernization agent (modernize CLI), which you will use end-to-end for assessment, upgrade, planning, and execution.
 * Create a repositories config file so the CLI can operate on both apps in a single batch run.
 * Run a **batch assessment** across both repositories, selecting the *Upgrade* and *Cloud readiness* analyses with full analysis coverage. Let the assessment run locally and wait for it to complete.
@@ -25,7 +23,7 @@ Use the GitHub Copilot App Modernization agent (modernize CLI) to assess and upg
 
 ## Success criteria
 
-* Both PhotoAlbum-Java and PhotoAlbum are forked and available in your working directory.
+* Both PhotoAlbum-Java and PhotoAlbum (forked in Challenge 1) are available in your working directory.
 * The modernize CLI is installed and configured to target both repositories from a config file.
 * A batch assessment completes and produces both an aggregated report and per-repository reports.
 * The .NET app is upgraded to .NET 10 and the Java app is upgraded to Java 25 / Spring Boot 4.0, each reporting a successful upgrade.

diff --git a/...-App Innovation/03_GHCPAppModernization/walkthrough/challenge-01/solution-01.md b/...-App Innovation/03_GHCPAppModernization/walkthrough/challenge-01/solution-01.md
@@ -10,6 +10,13 @@ Author a reusable, gated modernization Custom Agent, package a Skill, and config
 
 ## Actions
 
+### Fork the sample applications
+
+1. Log in to your GitHub account and fork both sample apps:
+   - <https://github.com/Azure-Samples/PhotoAlbum> (.NET)
+   - <https://github.com/Azure-Samples/PhotoAlbum-Java> (Spring Boot)
+2. Clone your fork of **PhotoAlbum** locally and open it in VS Code. This clone is the target repo for the files you author below, and you will reuse both forks in Challenges 2 and 3.
+
 ### Understand the model
 
 1. Read [docs/00-fundamentals.md](../../docs/00-fundamentals.md).
@@ -46,10 +53,13 @@ Author a reusable, gated modernization Custom Agent, package a Skill, and config
 
 ### Dry-run the gated loop
 
-1. Select your Custom Agent in Copilot Chat.
-2. Prompt: *"Modernize this application following your workflow."*
-3. Verify the agent runs the assessment and **stops at Gate 1** with an `ASSESSMENT.md`, then **stops at Gate 2** with a `PLAN.md` — without editing any source code.
-4. Approve to continue, or reject the plan once on purpose and watch the agent revise it.
+1. Reload VS Code so the agent, skill, and MCP configuration are picked up.
+2. Open Copilot Chat in your **PhotoAlbum** clone and select your Custom Agent in the agent picker. If it does not appear, check the YAML frontmatter and the file location (`.github/agents/<name>.agent.md`).
+3. Prompt: *"Modernize this application following your workflow."* — keep it open-ended on purpose, so the agent's own definition drives the run rather than your prompt.
+4. Verify the agent runs the assessment and **stops at Gate 1** with an `ASSESSMENT.md`, then **stops at Gate 2** with a `PLAN.md` — without editing any source code.
+5. Approve to continue, or reject the plan once on purpose and watch the agent revise it.
+
+> 💡 This step validates *behaviour*, not the quality of the assessment. If the agent runs straight through and starts editing files, the most common cause is `editFiles` still being available during the assessment phase — trim the `tools:` allow-list and try again.
 
 ## Success Criteria
 

diff --git a/...-App Innovation/03_GHCPAppModernization/walkthrough/challenge-02/solution-02.md b/...-App Innovation/03_GHCPAppModernization/walkthrough/challenge-02/solution-02.md
@@ -2,9 +2,9 @@
 
 [Previous Challenge Solution](../challenge-01/solution-01.md) - **[Home](../../Readme.md)** - [Next Challenge Solution](../challenge-03/solution-03.md)
 
-## 2.1. Fork the sample repositories
+## 2.1. Check your forks of the sample repositories
 
-Start by logging in your Github account and fork both the .NET and the Java app.
+You forked both apps in [Challenge 1](../challenge-01/solution-01.md). Confirm they are still available in your GitHub account before continuing:
 
 - <https://github.com/Azure-Samples/PhotoAlbum-Java>
 - <https://github.com/Azure-Samples/PhotoAlbum>