diff --git a/.github/ISSUE_TEMPLATE/demo-task.md b/.github/ISSUE_TEMPLATE/practice-task.md similarity index 79% rename from .github/ISSUE_TEMPLATE/demo-task.md rename to .github/ISSUE_TEMPLATE/practice-task.md index bd2d0fb..1c0c107 100644 --- a/.github/ISSUE_TEMPLATE/demo-task.md +++ b/.github/ISSUE_TEMPLATE/practice-task.md @@ -1,8 +1,8 @@ --- -name: Demo task -about: A scoped task for driving a GitHub Copilot app session during the Lunch & Learn +name: Practice task +about: A scoped task for driving a GitHub Copilot app session while following the walkthrough title: "" -labels: demo +labels: practice --- ## Goal diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b57b20..7079761 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ Thanks for helping make this a better resource for learning the GitHub Copilot app! 🎉 This repo is a community **learning resource**, not an official GitHub product. The goal is a -workshop that's accurate, easy to run, and friendly to newcomers. +self‑guided walkthrough that's accurate, easy to follow, and friendly to newcomers. ## Ways to contribute @@ -11,15 +11,15 @@ workshop that's accurate, easy to run, and friendly to newcomers. change. - **Improve the sample app or exercises** in [`sample-app/`](sample-app/) and [`exercises/`](exercises/). -- **Add a new exercise** that demonstrates an app feature not yet covered. +- **Add a new exercise** that exercises an app feature not yet covered. - **Report issues** — out‑of‑date steps, broken links, confusing instructions. ## Ground rules - Keep the sample app **small, dependency‑light, and beginner‑friendly**. Resist scope creep. - Keep `main` **green**: every change should keep `npm test` and `npm run build` passing. -- The four intentional gaps in the sample app are **load‑bearing** for the demos — don't fix them - in `main`; they each have an exercise. +- The four intentional gaps in the sample app are **load‑bearing** for the exercises — don't fix + them in `main`; they each have an exercise. - Cross‑check product claims against the [official docs](https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started) and link to them rather than restating volatile details. diff --git a/README.md b/README.md index d5057e0..f62afae 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Learn the GitHub Copilot app -A hands‑on, copy‑paste‑able workshop for walking technical developers through the +A hands‑on, self‑paced walkthrough for getting real experience with the **[GitHub Copilot app](https://github.com/features/ai/github-app)** — the agent‑driven desktop app for macOS, Windows, and Linux that [went GA on June 17, 2026](https://github.blog/changelog/2026-06-17-github-copilot-app-generally-available/). @@ -10,41 +10,42 @@ desktop app for macOS, Windows, and Linux that > and worktree; review the diff, validate in the integrated terminal and browser, and open a > pull request that uses your team's existing checks — all without context‑switching. -This repo gives a facilitator everything needed to run the session and gives attendees a real, -runnable codebase to drive the agent against. +Clone this repo, open it in the app, and work through the modules at your own pace. You get a +real, runnable codebase to drive the agent against and a step‑by‑step path from your first quick +chat to shipping a reviewed pull request. --- ## Who this is for -- **Audience:** technical developers (comfortable with Git, a terminal, and a typical web stack). -- **Format:** ~45 minutes, demo‑led, with optional hands‑on exercises. -- **Outcome:** attendees can install the app, run sessions in the three modes, review and ship a - PR, run sessions in parallel, and know where the advanced features (canvases, automations, +- **You:** a developer comfortable with Git, a terminal, and a typical web stack. +- **Time:** about an hour end to end, or pick individual modules. +- **What you'll be able to do:** install the app, run sessions in the three modes, review and ship + a PR, run sessions in parallel, and know where the advanced features (canvases, automations, MCP/BYOK, sandboxes) live. ## What's in here | Path | What it is | | --- | --- | -| [`docs/facilitator-guide.md`](docs/facilitator-guide.md) | Minute‑by‑minute run sheet for the 45‑minute session | -| [`docs/00-prerequisites.md`](docs/00-prerequisites.md) | Install + sign‑in checklist to send attendees beforehand | +| [`docs/walkthrough.md`](docs/walkthrough.md) | Start here — the suggested path through the modules | +| [`docs/00-prerequisites.md`](docs/00-prerequisites.md) | Install + sign‑in checklist to do first | | [`docs/01-quick-chat.md`](docs/01-quick-chat.md) | Module 1 — Quick chats | | [`docs/02-first-session.md`](docs/02-first-session.md) | Module 2 — Your first agent session (modes) | | [`docs/03-review-and-pr.md`](docs/03-review-and-pr.md) | Module 3 — Review the diff, verify, open a PR | | [`docs/04-parallel-sessions.md`](docs/04-parallel-sessions.md) | Module 4 — Parallel sessions & worktrees | | [`docs/05-modes-and-models.md`](docs/05-modes-and-models.md) | Module 5 — Modes, models & reasoning effort | | [`docs/06-advanced.md`](docs/06-advanced.md) | Module 6 — Canvases, automations, MCP/BYOK, sandboxes, `/chronicle` | -| [`docs/cheatsheet.md`](docs/cheatsheet.md) | One‑page reference to project on screen | -| [`exercises/`](exercises/) | Ready‑made demo tasks + seed issues + solutions | +| [`docs/cheatsheet.md`](docs/cheatsheet.md) | One‑page reference to keep open while you work | +| [`exercises/`](exercises/) | Ready‑made tasks + seed issues + solutions | | [`sample-app/`](sample-app/) | A tiny Express + TypeScript Task API to drive the agent against | ## The sample app [`sample-app/`](sample-app/) is a tiny **Express + TypeScript Task API** with a passing [Vitest](https://vitest.dev) + [Supertest](https://github.com/ladjs/supertest) suite. It is -deliberately small and has a few **intentional gaps** so the agent has real work to do during -the demo: +deliberately small and has a few **intentional gaps** so the agent has real work to do as you +follow along: 1. `POST /tasks` has **no input validation**. 2. There is **no `DELETE /tasks/:id`** endpoint (and `TaskStore.remove()` is missing). @@ -61,14 +62,14 @@ npm test # 8 passing tests npm run dev # http://localhost:3000 (GET /health, /tasks) ``` -## Run the Lunch & Learn +## How to follow along -1. **Before the session:** send attendees [`docs/00-prerequisites.md`](docs/00-prerequisites.md) - so they arrive with the app installed and signed in. -2. **Fork or use this repo** so you (and attendees) have issues and PRs to work with. Optionally - create the demo issues in one shot — see [`exercises/seed-issues.md`](exercises/seed-issues.md). -3. **Follow** [`docs/facilitator-guide.md`](docs/facilitator-guide.md) start to finish. -4. **Project** [`docs/cheatsheet.md`](docs/cheatsheet.md) when you want attendees to follow along. +1. **Set up first:** work through [`docs/00-prerequisites.md`](docs/00-prerequisites.md) so the app + is installed, signed in, and this repo is connected. +2. **Fork or clone this repo** so you have your own issues and PRs to work with. Optionally + create the practice issues in one shot — see [`exercises/seed-issues.md`](exercises/seed-issues.md). +3. **Work through** [`docs/walkthrough.md`](docs/walkthrough.md) module by module. +4. **Keep** [`docs/cheatsheet.md`](docs/cheatsheet.md) open as a quick reference while you work. ## License & contributing diff --git a/docs/00-prerequisites.md b/docs/00-prerequisites.md index c3d027a..5ffdbf6 100644 --- a/docs/00-prerequisites.md +++ b/docs/00-prerequisites.md @@ -1,7 +1,6 @@ -# 00 · Prerequisites & setup (send this before the session) +# 00 · Prerequisites & setup -Send this page to attendees a day ahead so everyone arrives ready. Setup eats demo time — -front‑load it. +Get this out of the way first so the rest of the walkthrough goes smoothly. None of it takes long. ## What you need @@ -47,12 +46,12 @@ The **sidebar** is your map: - **Search** — search across your repositories. - **Sessions** — active agent sessions grouped by repository, plus **Quick chats**. -## Facilitator pre‑flight +## Quick checklist - [ ] Signed in, this repo connected. -- [ ] Demo issues created (see [`../exercises/seed-issues.md`](../exercises/seed-issues.md)). +- [ ] Practice issues created (see [`../exercises/seed-issues.md`](../exercises/seed-issues.md)). - [ ] `npm install` already run in `sample-app/`. -- [ ] Decide which **model** you'll demo and confirm it's available to you. -- [ ] Screen share set so the **right side panel** (where canvases/diffs open) is visible. +- [ ] Picked a **model** you want to try and confirmed it's available to you. +- [ ] Noted the **right side panel** — that's where canvases and diffs open. ➡️ Next: [01 · Quick chat](01-quick-chat.md) diff --git a/docs/01-quick-chat.md b/docs/01-quick-chat.md index 8b74416..e5407f1 100644 --- a/docs/01-quick-chat.md +++ b/docs/01-quick-chat.md @@ -1,14 +1,14 @@ # 01 · Quick chat — explore without a branch -**Time:** ~5 min · **Goal:** show the lowest‑friction entry point. Quick chats let you ask -questions and brainstorm **without creating a branch or worktree**. +**Goal:** see the lowest‑friction entry point. Quick chats let you ask questions and brainstorm +**without creating a branch or worktree**. ## Why start here Not every question needs an agent session. Quick chats are perfect for orientation, scoping, and "how does this work?" moments — and they cost less than spinning up a full session. -## Do it live +## Try it 1. In the sidebar, click **+** next to **Quick chats**. 2. Ask something grounded in this repo: @@ -16,11 +16,11 @@ Not every question needs an agent session. Quick chats are perfect for orientati > Give me an overview of the `sample-app` Task API: its routes, where state lives, and any gaps > or TODOs you can find. -3. Follow up to show it's a real conversation: +3. Follow up to see it's a real conversation: > Which endpoint is missing input validation, and what would you add? -## Talking points +## What's happening - **No side effects.** Nothing is branched or written — it's a conversation. - **Repo‑aware.** It can read the connected repo to ground its answers. @@ -28,8 +28,8 @@ Not every question needs an agent session. Quick chats are perfect for orientati the work. This is the recommended way to keep AI usage efficient. - **History is saved.** Chats are listed by name so you can come back to them. -## Land the transition +## Before you move on -> "Great — Copilot understands the gap. Now let's give it a branch and have it actually fix one." +Copilot now understands the gap. Next, give it a branch and have it actually fix one. ➡️ Next: [02 · Your first session](02-first-session.md) diff --git a/docs/02-first-session.md b/docs/02-first-session.md index 23f044a..016f1a0 100644 --- a/docs/02-first-session.md +++ b/docs/02-first-session.md @@ -1,9 +1,9 @@ # 02 · Your first agent session — the centerpiece -**Time:** ~12 min · **Goal:** start a session from an issue, use **Plan** mode to agree on an -approach, then **Interactive** mode to steer the agent to a real, tested change. +**Goal:** start a session from an issue, use **Plan** mode to agree on an approach, then +**Interactive** mode to steer the agent to a real, tested change. -This is the most important module. Slow down and narrate what you're doing and why. +This is the most important module. Take your time and pay attention to what you're doing and why. ## The change we'll make @@ -16,8 +16,8 @@ behind it. 1. In the sidebar, open **My work** and find the issue **"Add input validation to POST /tasks"** (create it first with [`seed-issues.md`](../exercises/seed-issues.md) if needed). 2. Click the issue, then **New session**. The issue context loads automatically. -3. Below the prompt, choose where the session runs: a **new working tree** (recommended for the - demo — it keeps your main checkout clean), your local repo, or a **cloud sandbox**. +3. Below the prompt, choose where the session runs: a **new working tree** (recommended — it keeps + your main checkout clean), your local repo, or a **cloud sandbox**. 4. Pick a **session mode**, **model**, and **reasoning effort** (more on these in [05](05-modes-and-models.md)). @@ -32,11 +32,11 @@ Select **Plan** mode and prompt: > `title` should return `400` with a clear JSON error and must not create a task. Add tests > covering the happy path and the invalid cases. -The agent proposes a plan. **Read it aloud.** Approve it, or steer it: +The agent proposes a plan. **Read it carefully.** Approve it, or steer it: > Keep it dependency‑free — validate in the route handler, don't add a validation library. -**Point to make:** Plan mode front‑loads the disagreements. You catch a wrong approach before any +**Why it matters:** Plan mode front‑loads the disagreements. You catch a wrong approach before any code is written. ## Step 2 — Interactive mode (steer the work) @@ -47,7 +47,7 @@ Switch to **Interactive** mode and let it implement. As it works: - Nudge it if needed: > Also return `400` when `title` is only whitespace, and add a test for that. -**Point to make:** you're collaborating turn by turn — the agent suggests, you approve or redirect. +**Why it matters:** you're collaborating turn by turn — the agent suggests, you approve or redirect. ## Step 3 — Confidence check with rubber duck (optional) diff --git a/docs/03-review-and-pr.md b/docs/03-review-and-pr.md index d152597..dc106a6 100644 --- a/docs/03-review-and-pr.md +++ b/docs/03-review-and-pr.md @@ -1,7 +1,7 @@ # 03 · Review the diff, verify, and open a PR -**Time:** ~7 min · **Goal:** treat agent output like any teammate's — read the diff, verify it -runs, then ship it through your normal GitHub flow. +**Goal:** treat agent output like any teammate's — read the diff, verify it runs, then ship it +through your normal GitHub flow. ## Step 1 — Read the diff @@ -11,7 +11,7 @@ Open the session's **diff** view and walk the changes: - Is the validation logic correct and the error shape sensible? - Are the new tests meaningful, not just present? -**Point to make:** the diff is the contract. You review the change, not the chat transcript. +**Why it matters:** the diff is the contract. You review the change, not the chat transcript. ## Step 2 — Verify in the integrated terminal @@ -29,7 +29,7 @@ npm run dev # in another terminal tab: curl -s -X POST http://localhost:3000/tasks -H "content-type: application/json" -d "{}" # expect HTTP 400 with a JSON error -curl -s -X POST http://localhost:3000/tasks -H "content-type: application/json" -d "{\"title\":\"Demo\"}" +curl -s -X POST http://localhost:3000/tasks -H "content-type: application/json" -d "{\"title\":\"Write docs\"}" # expect HTTP 201 with the created task ``` @@ -40,7 +40,7 @@ Open the integrated **browser** canvas and hit: - `http://localhost:3000/health` → `{ "status": "ok" }` - `http://localhost:3000/tasks` → the tasks you created -**Point to make:** terminal + browser are *inside* the app, so reviewing and validating doesn't +**Why it matters:** terminal + browser are *inside* the app, so reviewing and validating doesn't mean alt‑tabbing across three windows. ## Step 4 — Open the pull request @@ -50,9 +50,9 @@ From the session, **create a pull request**. Then: - Show the PR uses your repo's **existing checks and merge requirements** — the CI in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) runs on the same change. - Show that you can **review the PR and view CI status** from **My work** without leaving the app. -- Merge it (or leave it open for Q&A). +- Merge it, or leave it open to revisit later. -## The loop to name out loud +## The loop, end to end > *issue → session (mode + model) → review the diff → verify → open PR → check CI → merge.* diff --git a/docs/04-parallel-sessions.md b/docs/04-parallel-sessions.md index f7a417d..992df4f 100644 --- a/docs/04-parallel-sessions.md +++ b/docs/04-parallel-sessions.md @@ -1,7 +1,7 @@ # 04 · Parallel sessions & worktrees -**Time:** ~7 min · **Goal:** show the app's signature move — multiple agent sessions running at -once, each isolated on its own branch and git worktree. +**Goal:** see the app's signature move — multiple agent sessions running at once, each isolated on +its own branch and git worktree. ## Why this matters @@ -9,7 +9,7 @@ Most "AI in the editor" tools are single‑threaded: one conversation, one worki app runs **many sessions in parallel**, each in a **dedicated worktree and branch**, so progress on one task never clobbers another. You shift from *doing the work* to *directing several streams of it.* -## Do it live +## Try it While the PR from Module 3 is building, start two more sessions from issues: @@ -18,7 +18,7 @@ While the PR from Module 3 is building, start two more sessions from issues: 3. Session B — **"Fix: completing a task doesn't update updatedAt"** ([exercise 3](../exercises/README.md)). 4. Give each a one‑line prompt and let them run. -Now switch between **all three** sessions in the sidebar (grouped by repository). Call out: +Now switch between **all three** sessions in the sidebar (grouped by repository). Notice: - Each session has its **own branch and worktree** — open two diffs side by side to prove the isolation. @@ -26,14 +26,14 @@ Now switch between **all three** sessions in the sidebar (grouped by repository) DELETE endpoint; Interactive for the subtler bug). - Nothing blocks: Session A doesn't wait for Session B. -## A good narration +## The mental model -> "I'm not waiting on any one agent. The DELETE endpoint is well‑scoped, so I'll let it run on -> Autopilot. The `updatedAt` bug is subtler, so I'll keep that one Interactive and steer it. Both -> live in their own worktree, so neither can step on the other — or on the validation PR that's -> already in review." +Think of it this way: you're not waiting on any one agent. The DELETE endpoint is well‑scoped, so +you can let it run on Autopilot. The `updatedAt` bug is subtler, so keep that one Interactive and +steer it. Both live in their own worktree, so neither can step on the other — or on the validation +PR that's already in review. -## Cloud sessions (mention) +## Cloud sessions (good to know) Sessions can also run in **cloud sandboxes** (public preview) — fully isolated Linux environments hosted by GitHub. Great for offloading compute or picking work up from another device. More in diff --git a/docs/05-modes-and-models.md b/docs/05-modes-and-models.md index 00435c2..9672d7a 100644 --- a/docs/05-modes-and-models.md +++ b/docs/05-modes-and-models.md @@ -1,7 +1,6 @@ # 05 · Modes, models & reasoning effort -**Time:** ~2 min on screen · **Goal:** give attendees a mental model for the knobs they'll reach -for in every session. This is a recap slide more than a demo. +**Goal:** build a mental model for the knobs you'll reach for in every session. ## Session modes — how much autonomy diff --git a/docs/06-advanced.md b/docs/06-advanced.md index 2ceaf5a..a033296 100644 --- a/docs/06-advanced.md +++ b/docs/06-advanced.md @@ -1,8 +1,7 @@ # 06 · Advanced features — a guided tour -**Time:** ~3 min · **Goal:** show attendees the ceiling. Don't deep‑dive; point at each feature, -say what it's for, and move on. Pick **one** to demo live if time allows (canvases is the crowd -pleaser). +**Goal:** see the ceiling. Don't try to master each feature now — learn what each one is for, then +try **one** that interests you (canvases is a good first pick). ## Canvases — shared, interactive surfaces @@ -67,4 +66,4 @@ concrete feedback, running on a **different model** than your main session. Invo - **Agent skills** (`/`‑commands) to package repeatable workflows. - **Voice dictation** to speak prompts instead of typing them. -➡️ Back to the [facilitator guide](facilitator-guide.md) · or the [cheat sheet](cheatsheet.md) +➡️ Back to the [walkthrough](walkthrough.md) · or the [cheat sheet](cheatsheet.md) diff --git a/docs/cheatsheet.md b/docs/cheatsheet.md index d5d5579..a417627 100644 --- a/docs/cheatsheet.md +++ b/docs/cheatsheet.md @@ -1,6 +1,6 @@ # Cheat sheet — GitHub Copilot app -Project this during the session. One screen, the essentials. +Keep this open while you work. One screen, the essentials. ## The core loop diff --git a/docs/facilitator-guide.md b/docs/facilitator-guide.md deleted file mode 100644 index 3f0c9d0..0000000 --- a/docs/facilitator-guide.md +++ /dev/null @@ -1,106 +0,0 @@ -# Facilitator guide — 45‑minute run sheet - -This is the script for delivering the Lunch & Learn. Times are a guide; the demo is the star, -so keep slides to a minimum and stay in the app. - -**Goal:** by the end, attendees understand how the GitHub Copilot app turns agent‑driven -development into a reviewable, parallel, GitHub‑native workflow — and can do it themselves. - -## Before you start (facilitator prep) - -- [ ] Install + sign in to the GitHub Copilot app (see [`00-prerequisites.md`](00-prerequisites.md)). -- [ ] Fork this repo (or have your own copy) and connect it in the app. -- [ ] Create the demo issues so you can "start from an issue": - see [`../exercises/seed-issues.md`](../exercises/seed-issues.md). -- [ ] `cd sample-app && npm install` once so live `npm test` runs are fast. -- [ ] Have [`cheatsheet.md`](cheatsheet.md) open to project. -- [ ] Pick the model you'll demo with and confirm it's available on your plan. - -## Timeline at a glance - -| Time | Module | What you show | -| --- | --- | --- | -| 0:00–0:03 | Intro | What the app is and why it's different | -| 0:03–0:07 | [00](00-prerequisites.md) / setup | App tour: sidebar, My work, Sessions, Quick chats | -| 0:07–0:12 | [01](01-quick-chat.md) | Quick chat — explore the repo, no branch | -| 0:12–0:24 | [02](02-first-session.md) | First session — Plan → Interactive, fix a real gap | -| 0:24–0:31 | [03](03-review-and-pr.md) | Review diff, verify in terminal/browser, open a PR | -| 0:31–0:38 | [04](04-parallel-sessions.md) | Parallel sessions on separate worktrees | -| 0:38–0:40 | [05](05-modes-and-models.md) | Modes, models & reasoning effort (recap on screen) | -| 0:40–0:43 | [06](06-advanced.md) | Advanced: canvases, automations, MCP/BYOK, sandboxes | -| 0:43–0:45 | Wrap | Recap, resources, Q&A | - ---- - -## 0:00–0:03 — Intro - -Say it in three sentences: - -1. "The GitHub Copilot app is a **desktop app** for agent‑driven development — you direct agents - instead of doing every keystroke yourself." -2. "It's built on GitHub Copilot CLI and is **native to GitHub**: issues, branches, PRs, and CI - work out of the box." -3. "The superpower is **parallelism with review** — many agents, each in its own branch/worktree, - and you stay in control through diffs, modes, and checks." - -> Avoid a long slide intro. The product sells itself once it's on screen. - -## 0:03–0:07 — Setup & app tour - -Walk the **sidebar**: **My work** (issues/PRs/CI), **Automations**, **Search**, **Sessions** -(with **Quick chats**). Confirm this repo is connected (`+` next to Sessions → repo). -Talking points live in [`00-prerequisites.md`](00-prerequisites.md). - -## 0:07–0:12 — Module 1: Quick chat - -Follow [`01-quick-chat.md`](01-quick-chat.md). Ask: *"Give me an overview of the sample-app and -how the Task API is structured."* Land the point: **no branch, no worktree — just answers.** - -## 0:12–0:24 — Module 2: Your first session (the centerpiece) - -Follow [`02-first-session.md`](02-first-session.md). Start from the **"Add input validation"** -issue. Show **Plan mode** (agent proposes, you approve), then switch to **Interactive** to steer. -Let it implement validation for `POST /tasks` and add a test. This is where you spend your time. - -## 0:24–0:31 — Module 3: Review & ship - -Follow [`03-review-and-pr.md`](03-review-and-pr.md). Read the **diff**, run `npm test` in the -**integrated terminal**, hit `/health` in the **browser**, then **open a PR** from the app and -point at CI running on the same change. - -## 0:31–0:38 — Module 4: Parallel sessions - -Follow [`04-parallel-sessions.md`](04-parallel-sessions.md). While the first PR's CI runs, start -**two more** sessions (e.g. "Add DELETE endpoint" and "Fix the updatedAt bug"), each on its own -worktree/branch. Switch between them in the sidebar — emphasize **isolation** (no clobbering). - -## 0:38–0:40 — Module 5: Modes & models - -Recap on screen with [`05-modes-and-models.md`](05-modes-and-models.md): Interactive vs Plan vs -Autopilot, model picker, reasoning effort, and how to match them to task complexity. - -## 0:40–0:43 — Module 6: Advanced - -Tour, don't deep‑dive, [`06-advanced.md`](06-advanced.md): **canvases** (`/create-canvas`), -**automations** (scheduled agent work), **MCP servers & BYOK**, **cloud/local sandboxes**, -`/chronicle` for session history, and the **rubber‑duck** agent. - -## 0:43–0:45 — Wrap - -- Recap the loop: *issue → session (mode + model) → review → verify → PR → repeat in parallel.* -- Point to resources in [`cheatsheet.md`](cheatsheet.md) and the official docs. -- Invite everyone to fork this repo and try the [`../exercises`](../exercises). - ---- - -## If you're short on time - -Drop **Module 4** (parallel) to a 60‑second mention and trim **Module 6** to a single canvas -demo. The non‑negotiables are **Module 2** (a real session) and **Module 3** (review + PR) — -that loop is the whole story. - -## If you have extra time - -- Do a live **Autopilot** run on a well‑scoped exercise and review the result. -- Build a small **canvas** live with `/create-canvas` (e.g. a triage board). -- Show **`/chronicle standup`** to summarize what you just did in the session. diff --git a/docs/walkthrough.md b/docs/walkthrough.md new file mode 100644 index 0000000..265f222 --- /dev/null +++ b/docs/walkthrough.md @@ -0,0 +1,95 @@ +# Walkthrough — start here + +This is the suggested path through the modules. Work through them in order the first time, or jump +straight to a topic once you know your way around. The app itself is the star, so spend most of your +time in it rather than reading. + +**What you'll come away with:** a feel for how the GitHub Copilot app turns agent‑driven development +into a reviewable, parallel, GitHub‑native workflow — and the confidence to do it on your own repos. + +## Before you start + +- [ ] Install and sign in to the GitHub Copilot app (see [`00-prerequisites.md`](00-prerequisites.md)). +- [ ] Fork or clone this repo and connect it in the app. +- [ ] Create the practice issues so you can "start from an issue": + see [`../exercises/seed-issues.md`](../exercises/seed-issues.md). +- [ ] `cd sample-app && npm install` once so live `npm test` runs are fast. +- [ ] Keep [`cheatsheet.md`](cheatsheet.md) open as a quick reference. +- [ ] Pick a model you want to try and confirm it's available on your plan. + +## The modules + +| Module | What you'll do | +| --- | --- | +| [00 · Prerequisites](00-prerequisites.md) | Install, sign in, connect this repo, tour the sidebar | +| [01 · Quick chat](01-quick-chat.md) | Ask questions and explore the repo — no branch | +| [02 · First session](02-first-session.md) | Start from an issue; Plan → Interactive; fix a real gap | +| [03 · Review & PR](03-review-and-pr.md) | Read the diff, verify in terminal/browser, open a PR | +| [04 · Parallel sessions](04-parallel-sessions.md) | Run sessions in parallel on separate worktrees | +| [05 · Modes & models](05-modes-and-models.md) | Match modes, models & reasoning effort to the task | +| [06 · Advanced](06-advanced.md) | Canvases, automations, MCP/BYOK, sandboxes, `/chronicle` | + +--- + +## 1 — Get oriented + +Start in [`00-prerequisites.md`](00-prerequisites.md) to install the app and connect this repo. Then +take a minute with the **sidebar**: **My work** (issues/PRs/CI), **Automations**, **Search**, and +**Sessions** (with **Quick chats**). This is your map for everything that follows. + +The short version of what the app is: it's a **desktop app** for agent‑driven development. You direct +agents instead of doing every keystroke yourself, it's **native to GitHub** (issues, branches, PRs, +and CI work out of the box), and its superpower is **parallelism with review** — many agents, each in +its own branch/worktree, with you in control through diffs, modes, and checks. + +## 2 — Quick chat (Module 1) + +Work through [`01-quick-chat.md`](01-quick-chat.md). Ask: *"Give me an overview of the sample-app and +how the Task API is structured."* The takeaway: **no branch, no worktree — just answers.** + +## 3 — Your first session (Module 2, the centerpiece) + +Work through [`02-first-session.md`](02-first-session.md). Start from the **"Add input validation"** +issue. Use **Plan mode** (the agent proposes, you approve), then switch to **Interactive** to steer. +Let it implement validation for `POST /tasks` and add a test. This is the part worth slowing down for. + +## 4 — Review & ship (Module 3) + +Work through [`03-review-and-pr.md`](03-review-and-pr.md). Read the **diff**, run `npm test` in the +**integrated terminal**, hit `/health` in the **browser**, then **open a PR** from the app and watch +CI run on the same change. + +## 5 — Parallel sessions (Module 4) + +Work through [`04-parallel-sessions.md`](04-parallel-sessions.md). While the first PR's CI runs, start +**two more** sessions (e.g. "Add DELETE endpoint" and "Fix the updatedAt bug"), each on its own +worktree/branch. Switch between them in the sidebar and notice the **isolation** — no clobbering. + +## 6 — Modes & models (Module 5) + +Read [`05-modes-and-models.md`](05-modes-and-models.md): Interactive vs Plan vs Autopilot, the model +picker, reasoning effort, and how to match them to task complexity. + +## 7 — Advanced (Module 6) + +Skim [`06-advanced.md`](06-advanced.md): **canvases** (`/create-canvas`), **automations** (scheduled +agent work), **MCP servers & BYOK**, **cloud/local sandboxes**, `/chronicle` for session history, and +the **rubber‑duck** agent. Try one that interests you. + +## 8 — Recap + +Name the loop to yourself: *issue → session (mode + model) → review → verify → PR → repeat in +parallel.* Then point your new skills at your own repos and the [`../exercises`](../exercises). + +--- + +## Short on time? + +Skip **Module 4** (parallel) on a first pass and skim **Module 6**. The two you don't want to miss are +**Module 2** (a real session) and **Module 3** (review + PR) — that loop is the whole story. + +## Want to go deeper? + +- Do a full **Autopilot** run on a well‑scoped exercise and review the result. +- Build a small **canvas** with `/create-canvas` (e.g. a triage board). +- Run **`/chronicle standup`** to summarize what you just did in the session. diff --git a/exercises/README.md b/exercises/README.md index 2d265f1..b9ac3da 100644 --- a/exercises/README.md +++ b/exercises/README.md @@ -1,7 +1,7 @@ # Exercises -Four self‑contained tasks built on real gaps in [`../sample-app`](../sample-app). Each one is the -basis for a demo in the facilitator guide and maps to a ready‑made GitHub issue in +Four self‑contained tasks built on real gaps in [`../sample-app`](../sample-app). Each one drives a +module in the [walkthrough](../docs/walkthrough.md) and maps to a ready‑made GitHub issue in [`seed-issues.md`](seed-issues.md). Reference solutions are in [`solutions.md`](solutions.md) — don't peek until you've let the agent try. @@ -10,10 +10,10 @@ tests that prove it. | # | Title | What's missing | Difficulty | Good for | | --- | --- | --- | --- | --- | -| 1 | Validate `POST /tasks` | No input validation — accepts a missing/blank `title` | ⭐ | Plan → Interactive demo | -| 2 | Add `DELETE /tasks/:id` | No delete route and no `TaskStore.remove()` | ⭐ | Autopilot demo | -| 3 | Fix the `updatedAt` bug | `setCompleted` never refreshes `updatedAt` | ⭐⭐ | Subtle‑bug / Interactive demo | -| 4 | Filter `GET /tasks?completed=` | No query‑param filtering | ⭐⭐ | Hands‑on attendee exercise | +| 1 | Validate `POST /tasks` | No input validation — accepts a missing/blank `title` | ⭐ | Plan → Interactive | +| 2 | Add `DELETE /tasks/:id` | No delete route and no `TaskStore.remove()` | ⭐ | Autopilot | +| 3 | Fix the `updatedAt` bug | `setCompleted` never refreshes `updatedAt` | ⭐⭐ | Subtle bug / Interactive | +| 4 | Filter `GET /tasks?completed=` | No query‑param filtering | ⭐⭐ | On your own | ## Exercise 1 — Validate `POST /tasks` diff --git a/exercises/seed-issues.md b/exercises/seed-issues.md index e8fbe1a..b56d8d1 100644 --- a/exercises/seed-issues.md +++ b/exercises/seed-issues.md @@ -1,33 +1,33 @@ # Seed issues -Create the four demo issues so you can "start a session from an issue" during the talk. Run these -from the repo root with the [GitHub CLI](https://cli.github.com/) (`gh auth login` first). They +Create the four practice issues so you can "start a session from an issue" as you follow along. Run +these from the repo root with the [GitHub CLI](https://cli.github.com/) (`gh auth login` first). They target whatever repo your current directory is in — run them from your fork. ```bash gh issue create \ --title "Add input validation to POST /tasks" \ - --label "good first issue,demo" \ + --label "good first issue,practice" \ --body "POST /tasks currently creates a task even when 'title' is missing or blank. Validate the request: reject a missing, non-string, or whitespace-only 'title' with HTTP 400 and a clear JSON error, and do not create the task. Add tests for the happy path and the invalid cases. See exercises/README.md (Exercise 1)." gh issue create \ --title "Add a DELETE /tasks/:id endpoint" \ - --label "demo" \ + --label "practice" \ --body "There is no way to delete a task. Add TaskStore.remove(id) and a DELETE /tasks/:id route that returns 204 on success and 404 when the task does not exist. Add tests. See exercises/README.md (Exercise 2)." gh issue create \ --title "Fix: completing a task does not update updatedAt" \ - --label "bug,demo" \ + --label "bug,practice" \ --body "TaskStore.setCompleted flips 'completed' but never refreshes 'updatedAt', so a completed task looks untouched. Refresh updatedAt when a task changes and add a test asserting it updates. See exercises/README.md (Exercise 3)." gh issue create \ --title "Support filtering GET /tasks by completed status" \ - --label "enhancement,demo" \ + --label "enhancement,practice" \ --body "GET /tasks always returns every task. Support ?completed=true and ?completed=false to filter, return all tasks when the param is absent, and 400 on an invalid value. Add tests. See exercises/README.md (Exercise 4)." ``` -> Tip: the `demo` label makes it easy to find these in **My work**. Create it first if it doesn't -> exist: `gh label create demo --color FBCA04 --description "Lunch & learn demo task"`. +> Tip: the `practice` label makes it easy to find these in **My work**. Create it first if it +> doesn't exist: `gh label create practice --color FBCA04 --description "Copilot app walkthrough task"`. If you'd rather create issues by hand, copy each title/body into **New issue** on GitHub, or use -the [`demo-task` issue template](../.github/ISSUE_TEMPLATE/demo-task.md) that ships with this repo. +the [`practice-task` issue template](../.github/ISSUE_TEMPLATE/practice-task.md) that ships with this repo. diff --git a/exercises/solutions.md b/exercises/solutions.md index 858c096..f0aa29c 100644 --- a/exercises/solutions.md +++ b/exercises/solutions.md @@ -1,11 +1,11 @@ # Reference solutions -Use these to sanity‑check what the agent produced, or to reset after a demo. They're intentionally -dependency‑free and match the style of the existing code. There's more than one correct answer — -the agent's version may differ and still be right. +Use these to sanity‑check what the agent produced, or to reset after working through an exercise. +They're intentionally dependency‑free and match the style of the existing code. There's more than one +correct answer — the agent's version may differ and still be right. -> Don't paste these in during the talk. The point is to let the agent write them and review the -> result together. +> Don't read these until you've let the agent try. The point is to let the agent write them and then +> review the result. ## Exercise 1 — Validate `POST /tasks` diff --git a/sample-app/README.md b/sample-app/README.md index dc5e7a7..1d5a4fe 100644 --- a/sample-app/README.md +++ b/sample-app/README.md @@ -1,8 +1,8 @@ # Sample app — Task API -A deliberately tiny **Express + TypeScript** REST API used for the -[GitHub Copilot app Lunch & Learn](../README.md). It exists to give the agent real, reviewable -work during the session — not to be a production service. +A deliberately tiny **Express + TypeScript** REST API used by the +[Learn the GitHub Copilot app walkthrough](../README.md). It exists to give the agent real, +reviewable work as you follow along — not to be a production service. ## Run it @@ -27,7 +27,7 @@ npm start # run the compiled server | `GET` | `/tasks/:id` | Get one task (404 if missing) | | `PATCH` | `/tasks/:id` | Set `{ "completed": true \| false }` | -State is held **in memory**, so it resets on restart — perfect for repeatable demos. +State is held **in memory**, so it resets on restart — easy to run an exercise repeatably. ## Intentional gaps (this is on purpose)