Set up your App workspace

Open your own shop

You need JDK 21+, Git and a supported Copilot App account. No Docker or Node installation is needed.

This workshop’s GitHub repository is also the shopping-cart template. Open it and choose Use this template → Create a new repository. Choose your account as owner and a name such as cart-workshop; private or public both work. Leave Include all branches unchecked so your repository contains only the starting code, without the solutions.

Open it in Copilot App

In the App sidebar, click + next to Sessions, then choose Add GitHub repository. Select your new cart-workshop repository; the App clones it for you. Do not select the template owner’s repository.

If a private repository is not available in the picker, use the App’s Clone repository option with its Git URL and your configured credentials. Do not paste credentials into prompts. See the App’s repository connection guide.

Prepare a session in this repository. Choose This computer, New worktree and Interactive. This creates a separate branch starting from main; you are not editing main directly.

In the model picker below the prompt box, select Fusion Standard, which automatically chooses a model for each task. If unavailable, choose Claude Sonnet 5.5 or GPT-6.1 Sol and turn Copilot Fusion off if the switch is shown. Available models depend on your plan and organization settings. See how Fusion works.

Send this first prompt to start the session:

Analyze this project's tech stack from its source and configuration files.
Briefly explain the backend, frontend, database and test tooling.
Do not edit files, install dependencies, start the application or call MCP tools.

Once the session has started, name the session Cart: quantity bug. Use the Open in… menu at the top right to open the session’s working directory in your editor. There, review AGENTS.md, the skill instructions under .github/skills/ and .github/mcp.json before approving repository configuration or using its skills and MCP tools. The three Java skills are already installed; no installation is needed. Their chapter covers usage.

If a file read is denied, stop and review the App’s repository-trust or file-access request. MCP approval does not grant filesystem access.

Your own repository should be ready for GitHub Actions, PRs and Agent Merge with the default settings. If you run into an access or approval issue later, ask the facilitator.

Understand AGENTS.md

AGENTS.md is a Markdown file containing project instructions for coding agents. Copilot loads applicable instructions automatically, so you don’t need to repeat the project’s commands and conventions in every prompt. It guides Copilot; it does not run commands or grant tool permissions.

Open the root AGENTS.md in your editor. Find the commands to start the shop, run the four baseline tests and run the full suite as you add tests. Notice the project boundaries too: keep the existing stack, preserve acceptance tests and let the human manage the running shop.

For your own projects, a useful AGENTS.md should:

• Give exact, working build, run and test commands, including required versions and any setup steps. Prefer the project’s wrapper, such as ./mvnw.
• Explain non-obvious conventions and constraints, such as HTTP tests using random ports and isolated databases.
• Stay short and current. Link to detailed documentation instead of copying it, and update commands when the workflow changes.

App tip: let tools handle style. Keep formatting commands in AGENTS.md so agents can normalize their changes before handing them back. A shared formatter reduces style-only differences between sessions; it does not replace tests or prevent conflicting changes to behavior.

In this template, run ./mvnw spotless:apply (Windows: .\mvnw.cmd spotless:apply) to format Java with the pinned Eclipse JDT formatter and shared four-space profile in .mvn/eclipse-formatter.xml. It also trims trailing whitespace and adds final newlines to the configured project files. Use ./mvnw spotless:check to verify without editing files. Neither command runs automatically during normal builds or tests. No IDE plugin is required.

The template already provides these instructions; you don’t need to edit them. Next, use its baseline-test and startup commands.

Check the starter

Let Copilot check the checkout and preserve your starting point:

Confirm this session uses my own cart-workshop repository.
Check the source directory, branch, remote and uncommitted changes.
Before any edits, create an annotated tag workshop-start at the current commit.
Never replace an existing tag; if this is not a clean new starter, ask me first.
Report the source directory, branch and saved starting point. Do not edit files.

The tag saves your starting point for the final review; Copilot handles the Git bookkeeping. If Git asks for a name and email, ask Copilot to help configure your own identity.

In this session’s working directory, run the baseline check, or ask Copilot to run it:

java -version
./mvnw -Dtest=BaselineTest test

Expect 4 tests, 0 failures, 0 errors, 0 skipped. Maven downloads missing dependencies. These tests do not yet cover adding the same product twice.

Start the application

Click the terminal icon at the top right to open a terminal in the current session’s worktree, then run:

./mvnw spring-boot:run

Keep that terminal open. Open the shop. Ctrl+C in that terminal stops the app. A restart resets data.

Keep it running while you work in this worktree. Spring Boot DevTools automatically restarts the app when the compiled classpath changes, not merely when Java source is saved. The workshop’s Maven test commands compile Java and copy resources. Wait for the app to finish restarting before using the browser; recreate sample cart data after a restart.

For UI-only edits without a test run, ask Copilot to copy the changed resources from this same worktree:

./mvnw compile

Then reload the browser, or have Copilot reload the existing Browser canvas. The Canvas exercise includes this refresh in the editing prompt. Static HTML, CSS and JavaScript changes do not normally restart the app or reset the cart.

Tests have random ports and isolated H2 databases. Never run two persistent servers on port 18765 or stop processes by name.

Work in the right session

Find the composer, mode/model controls and Changes view. Your worktree is a separate copy: run and preview the code from this session, not the repository’s original checkout.

Use one named session and one reviewed PR for each task:

Create each new session in the App from the latest merged main, using New worktree. Send its first prompt before naming it. Keep completed sessions for their history; do not reuse their branches for the next task. The Parallel sessions chapter then runs two independent tasks at the same time.

Move the running shop

The shop belongs to a particular terminal and source copy. DevTools does not switch worktrees. When a new task moves the running shop to another worktree, use Ctrl+C in the terminal that owns the shop, then start the new session’s copy using the startup command above. Run Maven and preview the shop from that session’s directory, with only one persistent shop running. A manual restart is also a recovery option if compiled changes are not picked up or the server has stopped. If you cannot identify the owner, ask the facilitator; never stop an unknown process to free port 18765.

Ready check

The shop opens, baseline tests pass, you can reproduce the two-click bug, and you know the active project/session. MCP setup comes later, in Investigate runtime with MCP.