diff --git a/content/00-prerequisites.md b/content/00-prerequisites.md index 3312b9b..07f5320 100644 --- a/content/00-prerequisites.md +++ b/content/00-prerequisites.md @@ -30,16 +30,17 @@ In this lesson, you will: When doing standard development, the first step is often to fork or clone the repository you'll be contributing to. For our course, since you'll be working through the exercises on your own, you'll grab a separate copy of the project. You'll do this by creating a new instance of the repository by using a [template repository][github-template-docs] on your own personal GitHub account. -1. In your browser, navigate to [https://github.com/github-samples/contoso-inventory](https://github.com/github-samples/contoso-inventory). +1. In your browser, navigate to the [contoso-inventory repository][contoso-inventory]. 2. Select **Use this template**. 3. Select **Create a new repository**. 4. Under **Owner**, select your personal GitHub account. 5. For **Repository name**, enter `AssetTrack`. -6. Leave the remaining options at their defaults. -7. Select **Create repository**. -8. Once the new repository has been created, select the **Code** button. -9. Switch to the **Codespaces** tab. -10. Select **Create codespace on main**. +6. Select **Include all branches** so the module catch-up branches (`start-of-module-02` through `start-of-module-07`) are copied to your repository. +7. Leave the remaining options at their defaults. +8. Select **Create repository**. +9. Once the new repository has been created, select the **Code** button. +10. Switch to the **Codespaces** tab. +11. Select **Create codespace on main**. > [!NOTE] > The first launch of the codespace will take a few minutes. AssetTrack uses a custom devcontainer that includes the runtimes for all four stacks (Java, Node/Astro, .NET, Python/FastAPI), and the container image needs to be built the first time the codespace starts. Subsequent launches will be much faster. diff --git a/content/01-working-with-copilot-cli.md b/content/01-working-with-copilot-cli.md index b76eab8..e9cad83 100644 --- a/content/01-working-with-copilot-cli.md +++ b/content/01-working-with-copilot-cli.md @@ -196,6 +196,9 @@ As you likely expected, there's quite a bit going on behind the scenes with Copi Selecting **Yes** will allow for the first call only, and the next two will require separate approvals. **Yes, and don't ask again for `gh issue` in this repo (*path*)** will allow Copilot CLI to always call the `gh issue` CLI tool for this repository. +> [!NOTE] +> "Don't ask again" choices are saved per folder in `~/.copilot/permissions-config.json`, so they carry across sessions in that repository. You can also pre-approve tools when you launch with `--allow-tool` — for example, `copilot --allow-tool write --allow-tool 'shell(git:*)'` — which skips the prompt for exactly those tools while still asking about anything else. The codespace for this course ships with a set of local tools already approved this way, so later modules start Copilot without stopping for permission on routine local work. + > [!IMPORTANT] > Ensure you always consider the implications of granting Copilot or any AI tool permissions to perform actions on your behalf. diff --git a/content/02-building-ai-infrastructure.md b/content/02-building-ai-infrastructure.md index 9956c21..1a71190 100644 --- a/content/02-building-ai-infrastructure.md +++ b/content/02-building-ai-infrastructure.md @@ -179,7 +179,7 @@ Now let's add a reusable `Accessibility Expert` custom agent and use it against 1. Ask Copilot to work with the Accessibility Expert agent to produce an accessibility report for the Astro frontend with recommendations ```text - Work with the the accessibility expert to review the Astro frontend code and produce an accessibility report with specific recommendations for improvements based on WCAG 2.2 AA standards. + Work with the accessibility expert to review the Astro frontend code and produce an accessibility report with specific recommendations for improvements based on WCAG 2.2 AA standards. ``` Notice that the main agent passes the task to the Accessibility Expert agent, which then finds the custom instructions for Astro/React you created earlier, tracks the relevant files and produces a report with specific, actionable recommendations that reference WCAG success criteria and specific selectors in the code. @@ -192,7 +192,7 @@ Now let's add a reusable `Accessibility Expert` custom agent and use it against ## Agent skills -Custom agents introduce *specialized personas*. **Agent skills** change what Copilot *knows* to do. A skill is a packaged capability, could include an instruction set, optional scripts and resources - that the agent can invoke **at runtime** when the task matches its trigger. Skills live in `.copilot/skills/` (for repo-scoped) or `~/.copilot/skills/` (for user-scoped) and in Copilot CLI, you use `/skills` to view and manage them. +Custom agents introduce *specialized personas*. **Agent skills** change what Copilot *knows* to do. A skill is a packaged capability, could include an instruction set, optional scripts and resources - that the agent can invoke **at runtime** when the task matches its trigger. Skills live in `.github/skills/` (for repo-scoped) or `~/.copilot/skills/` (for user-scoped) and in Copilot CLI, you use `/skills` to view and manage them. The new AI infrastructure for Contoso is coming together nicely, but there's one more piece to add. Now that you have a baseline for how copilot should approach making updates locally, we want to bootstrap the contribution standards that should be followed to land these updates through channels that integrate with the team's existing workflows for enhanced collaboration, human-in-the-loop review and auditability. diff --git a/content/04-lifecycle-hooks.md b/content/04-lifecycle-hooks.md index 5e6f476..97bd76a 100644 --- a/content/04-lifecycle-hooks.md +++ b/content/04-lifecycle-hooks.md @@ -67,7 +67,7 @@ The harness emits named events across the session lifecycle and your hook config For the test-and-lint feedback loop in this module, the events that matter most are: - `postToolUse` - to run checks after each file edit and feed results back to the agent loop -- `agentStop` - to optionally block the agent from finishing a turn if checks are red). +- `agentStop` - to optionally block the agent from finishing a turn if checks are red. ### Reading hook input and writing hook output @@ -192,8 +192,8 @@ AssetTrack's checks span four different stacks - .NET, Java, Python, TypeScript, 3. Download `.github/hooks/scripts/test-router.sh`, which reads the edited file path from the `postToolUse` payload, runs the right test runner for that stack and emits the result as `additionalContext`. The same script also handles `agentStop` by looking at changed files and blocking only when the relevant stack's tests fail: ```bash - curl -o .github/hooks/scripts/test-router.sh \ - https://raw.githubusercontent.com/github-samples/advanced-copilot-cli/main/assets/04/.github/hooks/scripts/test-router.sh + curl --fail -o .github/hooks/scripts/test-router.sh \ + https://raw.githubusercontent.com/github-samples/advanced-copilot-cli/1af928893a2e180dc3b2a469b22712a78b1f74a7/assets/04/.github/hooks/scripts/test-router.sh ``` 4. Make the script executable: diff --git a/content/05-add-feature-barcode.md b/content/05-add-feature-barcode.md index 38e68c7..13ffb97 100644 --- a/content/05-add-feature-barcode.md +++ b/content/05-add-feature-barcode.md @@ -62,15 +62,15 @@ Two of those need help from outside the agent's own reasoning. Exploring the run Let's start by registering the Playwright MCP server for the quality assurance agent to be able to use later. > [!NOTE] -> You'll start Copilot CLI with `--yolo`, which auto-approves every edit, command, and tool call so the work doesn't stop for permission on each step — useful once the `/fleet` build is running. That's appropriate here because a codespace is the kind of sandboxed, disposable container that [Module 1][m01] called out as the right home for YOLO mode. Treat it as the exception: on your own machine, or anywhere near real credentials or unreviewed code, start Copilot with plain `copilot` and approve actions deliberately. +> This codespace comes with a collection of approved local tools for Copilot to use, like creating files, running builds, and other local operations. It's scoped to just the codespace, and not any external services. When it comes time to use other services, Copilot will ask for approval, or you'll use a command to add it to its list of approved tools. Here you'll register the Playwright MCP server, so you'll start Copilot with `--allow-tool playwright` to add it to that approved list up front — the `/fleet` build can then drive the browser without stopping for permission mid-run. 1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. 2. Open a terminal window by selecting Ctrl + `. 3. Create and switch to a feature branch with `git switch -c feat/barcode-support`. -4. Start Copilot CLI in YOLO mode from the repository root: +4. Start Copilot CLI from the repository root, adding the Playwright server you'll register next to its list of approved tools: ```bash - copilot --yolo + copilot --allow-tool playwright ``` 5. In Copilot CLI, run the command `/mcp add` to open the MCP registration panel. @@ -265,7 +265,6 @@ The throughline is the loop itself: research and planning make the parallel buil [previous-lesson]: ./04-lifecycle-hooks.md [next-lesson]: ./06-modernize-apps.md -[m01]: ./01-working-with-copilot-cli.md [m02]: ./02-building-ai-infrastructure.md [m04]: ./04-lifecycle-hooks.md [copilot-plan]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli diff --git a/content/06-modernize-apps.md b/content/06-modernize-apps.md index 8d32843..d752295 100644 --- a/content/06-modernize-apps.md +++ b/content/06-modernize-apps.md @@ -64,7 +64,7 @@ GitHub Copilot provides access to numerous models of various levels, including t As you work through the application modernization flow, you'll move back and forth between higher-end tasks, like planning and research, to lower-end tasks, like writing code and generating tests. With `/model` you can switch to an appropriate model depending on the needs of the current ask, both saving time and reducing the credit usage necessary to complete the operation. For example, you might choose Claude Opus 4.8 to build the plan, then assign an agent using MAI-Flash-1 to implement the code as defined in the plan. > [!NOTE] -> During our exploration here we're going to use `auto` as our model choice, which allows Copilot to choose the model it thinks is most appropriate for the task. This is both to streamline the lesson and to allow for completion of the course with reduced credit usage. When it comes time to being complex operations on your production codebase, you can deploy various strategies to choose the right model at the right time. +> During our exploration here we're going to use `auto` as our model choice, which allows Copilot to choose the model it thinks is most appropriate for the task. This is both to streamline the lesson and to allow for completion of the course with reduced credit usage. When it comes time to perform complex operations on your production codebase, you can deploy various strategies to choose the right model at the right time. ## Giving Copilot better signal: LSP and documentation MCP @@ -86,8 +86,10 @@ You'll give Copilot structured intelligence for AssetTrack's Java code and a fir Start with the code signal: install the Eclipse JDT language server through the `lsp-setup` skill and commit its configuration so the whole team shares the same view of the code. +This codespace comes with a collection of approved local tools for Copilot to use, like creating files, running builds, and other local operations. It's scoped to just the codespace, and not any external services. When it comes time to use other services — like the documentation MCP server you'll add later in this module — Copilot will ask for approval, or you'll use a command to add it to its list of approved tools. + 1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. -2. Open a terminal by selecting Ctrl + \`, then start Copilot CLI from the repository root by running `copilot --yolo`. +2. Open a terminal by selecting Ctrl + \`, then start Copilot CLI from the repository root by running `copilot`. 3. If prompted, trust the project folder by selecting **Yes, and remember this folder for future sessions**. 4. Run `/models`, select **Auto** from the list, and select Enter. 5. Ask Copilot to install the skill directly from the [Awesome GitHub Copilot][awesome-copilot] collection by entering the prompt: @@ -126,7 +128,7 @@ Start with the code signal: install the Eclipse JDT language server through the > [!NOTE] > The committed `.github/lsp.json` tells Copilot how to launch `jdtls`, but each environment still needs the server installed — that's what the `lsp-setup` skill does. A teammate who clones the repo runs the same skill once to install `jdtls` locally. It runs on the Java 21 JDK the AssetTrack devcontainer provides, which both builds `audit-svc` and `auth-svc` — they target Java 17 — and analyzes their source without trouble. -9. To complete the installation, exit Copilot CLI by using the command `/exit`, then `/exit` again, then re-open Copilot by running `copilot --yolo`. +9. To complete the installation, exit Copilot CLI by using the command `/exit`, then `/exit` again, then re-open Copilot by running `copilot`. With `.github/lsp.json` committed and `jdtls` installed, every contributor now gets the same compiler-backed view of AssetTrack's Java code. @@ -259,7 +261,7 @@ As highlighted previously, app modernization follows a cycle of research, coding 1. Turn what you just learned into a short playbook so the next service reuses the recipe. Ask Copilot to write it from the actual work, not from theory, by sending the following prompt: ```text - Using the the learnings and process we just followed, let's create an updated migration-playbook.md file that will supersede the original. Bring over anything applicable generalized from the original research, and any lessons from the upgrade you just performed. + Using the learnings and process we just followed, let's create an updated migration-playbook.md file that will supersede the original. Bring over anything applicable generalized from the original research, and any lessons from the upgrade you just performed. ``` 2. Ask Copilot to update the agent with any learnings it has that might improve the process by using the following prompt: @@ -293,7 +295,7 @@ Modernizing the first service was the expensive part. The second one is where bu Modernize services/auth-svc following the guidelines provided in the agent, and give me a final status report at the end. The baseline test suite from the previous exercise is already in place, so confirm it passes and start from the toolchain phase. ``` - The agent performs the upgrade, following the steps lessons from your research and the first migration process. + The agent performs the upgrade, following the steps and lessons from your research and the first migration process. 5. Once the work is complete, ask Copilot to create a PR with your new agent, playbook, and newly upgraded services by using the following prompt: diff --git a/content/07-manage-infrastructure.md b/content/07-manage-infrastructure.md index 226da89..3b45c3f 100644 --- a/content/07-manage-infrastructure.md +++ b/content/07-manage-infrastructure.md @@ -3,7 +3,7 @@ | [← Previous: Modernizing apps with Copilot CLI][previous-lesson] | [Next: Wrap-up →][next-lesson] | |:--|--:| -Everything so far has been scoped to a single repository, or to you as the individual developer. The instructions, custom agents, agent skills, and lifecycle hooks you committed to AssetTrack do travel to anyone who clones it — but they stop at that repo's boundary. The MCP configuration was saved to your user settings. In practice, though, there are always rules, agents, skills, and shared resources that shouldn't belong to single repository; they encode how the whole organization works, and every developer at Contoso should get them automatically. This module moves that setup to the enterprise level: a custom MCP server that exposes a shared resource, a plugin that bundles your AI infrastructure into a single installable unit, and enterprise standards that push it to every developer without anyone cloning a repo or copying a file. +Everything so far has been scoped to a single repository, or to you as the individual developer. The instructions, custom agents, agent skills, and lifecycle hooks you committed to AssetTrack do travel to anyone who clones it — but they stop at that repo's boundary. The MCP configuration was saved to your user settings. In practice, though, there are always rules, agents, skills, and shared resources that shouldn't belong to a single repository; they encode how the whole organization works, and every developer at Contoso should get them automatically. This module moves that setup to the enterprise level: a custom MCP server that exposes a shared resource, a plugin that bundles your AI infrastructure into a single installable unit, and enterprise standards that push it to every developer without anyone cloning a repo or copying a file. ## What you will learn @@ -27,7 +27,7 @@ Closing that gap means lifting the setup out of AssetTrack and up to where the w > git checkout start-of-module-07 > ``` > -> The plugin and MCP work in this module targets your fork only, but the patterns are written for org-wide rollout. +> The plugin and MCP work in this module target your fork only, but the patterns are written for org-wide rollout. ## Custom MCP servers as shared infrastructure @@ -60,9 +60,11 @@ You'll scaffold an MCP server that introspects AssetTrack's service databases an ### Start the databases and scaffold the server +This codespace comes with a collection of approved local tools for Copilot to use, like creating files, running builds, and other local operations. It's scoped to just the codespace, and not any external services. When it comes time to use other services, Copilot will ask for approval, or you'll use a command to add it to its list of approved tools. + 1. Return to your codespace. If you closed it, navigate to your repository on GitHub.com, select **Code** > **Codespaces**, then reopen your existing codespace. 2. Open a terminal by selecting Ctrl + \`, then start AssetTrack once so each service creates and seeds its database. Run `npm run dev` and leave it running. Each service's `dev:*` script creates its SQLite file under `services//data/`. -3. Open a second terminal by selecting Ctrl + Shift + \`, then start Copilot CLI from the repository root by running `copilot --yolo`. +3. Open a second terminal by selecting Ctrl + Shift + \`, then start Copilot CLI from the repository root by running `copilot`. 4. If prompted, trust the project folder by selecting **Yes, and remember this folder for future sessions**. 5. Run `/models`, select **Auto** from the list, and select Enter. 6. Ask Copilot to scaffold the catalog server, keeping it read-only and pointed at the dev databases: @@ -106,7 +108,7 @@ You'll scaffold an MCP server that introspects AssetTrack's service databases an 3. Select Ctrl + S to save the configuration. 4. Select Esc to exit the configuration screen. 5. Confirm the server loaded by running `/mcp` and checking that `assettrack-catalog` appears with its three tools. -6. Start a new session by using the command `/new` and selecting Enter.: +6. Start a new session by using the command `/new` and selecting Enter. 7. Test the new MCP server by using the following prompt: ```text @@ -122,13 +124,13 @@ With the catalog registered, "where does this data live?" is now a first-class t With our new MCP server created, let's create a pull request (PR) so it becomes part of our project! 1. Use the `/new` prompt in Copilot to create a new session. -2. Use the following prompt to tell Copilot to create a new branch, a commit and a PR, and to merge the PR when done: +2. Use the following prompt to tell Copilot to create a new branch, a commit, and a PR: - ``` - We just defined a new MCP server. Can you please create a new branch called add-mcp-server, generate a short commit message, then create the PR. Once the CI completes for the PR, go ahead and merge it. + ```text + We just defined a new MCP server. Can you please create a new branch called add-mcp-server, generate a short commit message, then create the PR. ``` -Copilot will get to work on creating the PR and merging it. This will take just a couple of minutes to complete. +Copilot creates the branch, commit, and PR, then stops. Because this MCP server reaches the service databases and will be distributed as shared infrastructure, treat the PR as a human review gate: read the diff yourself, let CI finish, and merge it only once you're satisfied it's correct. Building that review habit for code that runs organization-wide matters more than shaving off a few minutes. ## Plugins: bundling AI infrastructure @@ -221,9 +223,9 @@ The AssetTrack AI infrastructure is now a single unit. Everything you built piec Installing from your own marketplace solves the problem for you; solving it for everyone is a distribution problem. This can be tackled in three steps: -1. host the marketplace where the whole organization can reach it, -2. make the plugin install automatically through enterprise-managed plugin standards, -3. and govern org-wide personas through enterprise custom agents.| +1. Host the marketplace where the whole organization can reach it. +2. Make the plugin install automatically through enterprise-managed plugin standards. +3. Govern org-wide personas through enterprise custom agents. These are driven from the enterprise's `.github-private` repository, so their rules are version-controlled and reviewed like any other change.