Merge pull request #78 from instil/feat/tutorial-audit-restructure

Tutorial audit & restructure — 5-module rewrite

Author: calebwilson706

.github/agents/core.agent.md

@@ -7,8 +7,8 @@ Switch back to the core track. Do the following steps in order:
 
 1. Read the file `tutorial/state.json`
 2. Set the `track` field to `"core"`
-3. If `currentLesson` is greater than 20, set `currentLesson` to 20
+3. If `currentLesson` is greater than 23, set `currentLesson` to 23
 4. Write the updated JSON back to `tutorial/state.json`
-5. Determine the lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 20 becomes "20-")
+5. Determine the lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 23 becomes "23-")
 6. Read that lesson file
 7. Present its contents to the user. Mention that they've switched back to the core track.

.github/agents/design.agent.md

@@ -3,12 +3,12 @@ description: "Switch to the Design track"
 tools: ["read", "edit"]
 ---
 
-Switch to the Design track (lessons 26-31). Do the following steps in order:
+Switch to the Design track (lessons 29-34). Do the following steps in order:
 
 1. Read the file `tutorial/state.json`
 2. Set the `track` field to `"design"`
-3. If `currentLesson` is less than 26, set `currentLesson` to 26 (otherwise keep it as-is)
+3. If `currentLesson` is less than 29, set `currentLesson` to 29 (otherwise keep it as-is)
 4. Write the updated JSON back to `tutorial/state.json`
-5. Determine the lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 26 becomes "26-")
+5. Determine the lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 29 becomes "29-")
 6. Read that lesson file
 7. Present its contents to the user. Mention that they've switched to the Design track. If the lesson has an Exercise section, make it visually distinct so the user knows exactly what to do next.

.github/agents/next.agent.md

@@ -7,10 +7,21 @@ Advance the tutorial to the next lesson. Do the following steps in order:
 
 1. Read the file `tutorial/state.json`
 2. Get the current lesson number from the `currentLesson` field
-3. Add the current lesson number to the `completedLessons` array if it is not already there
-4. Increment `currentLesson` by 1
-5. Read the `track` field from state (default `"core"` if missing). If `track` is `"qa"`, cap `currentLesson` at 25. If `track` is `"design"`, cap at 31. If `track` is `"core"`, cap at 20. (Set it back to the cap value if it exceeds it.)
-6. Write the updated JSON back to `tutorial/state.json`
-7. Determine the next lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 3 becomes "03-", lesson 7 becomes "07-")
-8. Read that lesson file
-9. Present its contents to the user. If the lesson has an Exercise section, make it visually distinct so the user knows exactly what to do next.
+3. **Module stopping points** — check if the current lesson number is one of the module boundary lessons: **06**, **11**, or **18**, AND it is not already in `completedLessons` or `skippedLessons` (i.e. we're landing here for the first time).
+4. Add the current lesson number to the `completedLessons` array if it is not already there
+
+   If it IS a boundary being completed for the first time:
+   - Write the updated `completedLessons` back to `tutorial/state.json` (do NOT increment `currentLesson`)
+   - Show the appropriate module-complete banner:
+     - After lesson **06**: "✅ Module 1 complete — Foundations & Configuration."
+     - After lesson **11**: "✅ Module 2 complete — Putting Agents to Work."
+     - After lesson **18**: "✅ Module 3 complete — Reusable Workflows."
+   - Then say: "Take a break here — wait until the instructor moves on to the next module. When you're ready to continue, just say **next**."
+   - **STOP here.** Do not increment `currentLesson` or present the next lesson.
+
+5. Increment `currentLesson` by 1
+6. Read the `track` field from state (default `"core"` if missing). If `track` is `"qa"`, cap `currentLesson` at 28. If `track` is `"design"`, cap at 34. If `track` is `"core"`, cap at 23. (Set it back to the cap value if it exceeds it.)
+7. Write the updated JSON back to `tutorial/state.json`
+8. Determine the next lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 3 becomes "03-", lesson 7 becomes "07-")
+9. Read that lesson file
+10. Present its contents to the user. If the lesson has an Exercise section, make it visually distinct so the user knows exactly what to do next.

.github/agents/previous.agent.md

@@ -9,7 +9,7 @@ Go back to the previous lesson. Do the following steps in order:
 2. Get the current lesson number from the `currentLesson` field
 3. Remove the current lesson number from the `completedLessons` array if it is present
 4. Decrement `currentLesson` by 1
-5. Read the `track` field from state (default `"core"` if missing). If `track` is `"qa"`, cap `currentLesson` at a minimum of 21. If `track` is `"design"`, cap at a minimum of 26. If `track` is `"core"`, cap at a minimum of 0. (Set it back to the cap value if it goes below it.)
+5. Read the `track` field from state (default `"core"` if missing). If `track` is `"qa"`, cap `currentLesson` at a minimum of 24. If `track` is `"design"`, cap at a minimum of 29. If `track` is `"core"`, cap at a minimum of 0. (Set it back to the cap value if it goes below it.)
 6. Write the updated JSON back to `tutorial/state.json`
 7. Determine the previous lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 3 becomes "03-", lesson 7 becomes "07-")
 8. Read that lesson file

.github/agents/progress.agent.md

@@ -9,45 +9,52 @@ Show the user their tutorial progress. Do the following:
 2. Read the `track` field (default `"core"` if missing)
 3. Display a categorized progress list using these sections and titles:
 
-**Core:**
+**Module 1 — Foundations & Configuration:**
    - 0: Welcome
    - 1: First Conversation
    - 2: Effective Prompting & Verification
    - 3: Context
    - 4: Custom Instructions
-   - 8: Planning Mode
-   - 10: Custom Agents
-   - 11: Agent Skills
-   - 12: Agent Delegation & Collaboration
-   - 14: Session Management
-   - 16: Model Selection & Configuration
-   - 17: CLI Tools & MCP Servers
-   - 18: Working with Images
-   - 19: Premium Requests
-   - 20: Graduation + Bonus
-
-**Developer:**
-   - 5: Code Modification
-   - 6: Refactoring
-   - 7: Bug Investigation
-   - 9: Writing & Running Tests
-   - 13: Git Workflow — Commits & PRs
-   - 15: Programmatic Mode & Automation
+   - 5: Model Selection & Configuration
+   - 6: Working with Images
+
+**Module 2 — Putting Agents to Work:**
+   - 7: Code Modification
+   - 8: Refactoring
+   - 9: Bug Investigation
+   - 10: Planning Mode
+   - 11: Writing & Running Tests
+
+**Module 3 — Reusable Workflows:**
+   - 12: Custom Agents
+   - 13: Agent Skills
+   - 14: Building Skills with Walk-Then-Capture
+   - 15: The Skills Ecosystem
+   - 16: Agent Delegation
+   - 17: Parallel Work with Fleet
+   - 18: Session Management
+
+**Module 4 — Working at the Edges:**
+   - 19: Git Workflow — Commits & PRs
+   - 20: Programmatic Mode
+   - 21: CLI Tools and MCP
+   - 22: Billing and Premium Requests
+   - 23: Graduation + Bonus
 
 4. If `track` is `"qa"`, also show a **QA Track:** section:
-   - 21: Test Planning from Requirements
-   - 22: Test Case Design & Coverage Analysis
-   - 23: Automated Test Generation
-   - 24: E2E Testing with Playwright
-   - 25: QA Track Graduation
+   - 24: Test Planning from Requirements
+   - 25: Test Case Design & Coverage Analysis
+   - 26: Automated Test Generation
+   - 27: E2E Testing with Playwright
+   - 28: QA Track Graduation
 
    If `track` is `"design"`, also show a **Design Track:** section:
-   - 26: Translating Mockups to Specs
-   - 27: Accessibility & Design Review
-   - 28: Design System Instructions
-   - 29: Designer ↔ Developer Handoff
-   - 30: Rapid Prototyping
-   - 31: Design Track Graduation
+   - 29: Translating Mockups to Specs
+   - 30: Accessibility & Design Review
+   - 31: Design System Instructions
+   - 32: Designer ↔ Developer Handoff
+   - 33: Rapid Prototyping
+   - 34: Design Track Graduation
 
    If `track` is NOT `"qa"` and NOT `"design"`, show a note instead: "Type /agent qa to start the QA track or /agent design to start the Design track"
 
@@ -56,4 +63,4 @@ Show the user their tutorial progress. Do the following:
    - `[>]` if it is the `currentLesson` (the one they're on right now)
    - `[~]` if it is in the `skippedLessons` array
    - `[ ]` if it hasn't been reached yet
-6. Show a summary line. If on the core track: "Progress: N of 20 lessons completed". If on the QA track: "Progress: N of 5 lessons completed". If on the design track: "Progress: N of 6 lessons completed".
+6. Show a summary line. If on the core track: "Progress: N of 24 lessons completed". If on the QA track: "Progress: N of 5 lessons completed". If on the design track: "Progress: N of 6 lessons completed".

.github/agents/qa.agent.md

@@ -3,12 +3,12 @@ description: "Switch to the QA track"
 tools: ["read", "edit"]
 ---
 
-Switch to the QA track (lessons 21-25). Do the following steps in order:
+Switch to the QA track (lessons 24-28). Do the following steps in order:
 
 1. Read the file `tutorial/state.json`
 2. Set the `track` field to `"qa"`
-3. If `currentLesson` is less than 21, set `currentLesson` to 21 (otherwise keep it as-is)
+3. If `currentLesson` is less than 24, set `currentLesson` to 24 (otherwise keep it as-is)
 4. Write the updated JSON back to `tutorial/state.json`
-5. Determine the lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 21 becomes "21-")
+5. Determine the lesson filename: look in `tutorial/lessons/` for the file whose name starts with the zero-padded lesson number (e.g., lesson 24 becomes "24-")
 6. Read that lesson file
 7. Present its contents to the user. Mention that they've switched to the QA track. If the lesson has an Exercise section, make it visually distinct so the user knows exactly what to do next.

.github/agents/skip.agent.md

@@ -6,8 +6,19 @@ tools: ["read", "edit"]
 Skip the current exercise and move to the next lesson. Do the following steps:
 
 1. Read `tutorial/state.json`
-2. Add the current lesson number to the `skippedLessons` array if not already there
-3. Increment `currentLesson` by 1. Read the `track` field (default `"core"` if missing). Cap at 31 if `track` is `"design"`, at 25 if `track` is `"qa"`, or at 20 if `track` is `"core"`.
-4. Write the updated state back to `tutorial/state.json`
-5. Read the next lesson file from `tutorial/lessons/` (zero-padded prefix)
-6. Present it to the user. Briefly acknowledge the skip in a neutral way — something like "Moving on!" — without making the user feel bad. Everyone learns at their own pace.
+2. **Module stopping points** — check if the current lesson number is one of the module boundary lessons: **06**, **11**, or **18**, AND it is not already in `completedLessons` or `skippedLessons` (i.e. we're landing here for the first time).
+3. Add the current lesson number to the `skippedLessons` array if not already there
+
+   If it IS a boundary being completed for the first time:
+   - Write the updated `skippedLessons` back to `tutorial/state.json` (do NOT increment `currentLesson`)
+   - Show the appropriate module-complete banner:
+     - After lesson **06**: "✅ Module 1 complete — Foundations & Configuration."
+     - After lesson **11**: "✅ Module 2 complete — Putting Agents to Work."
+     - After lesson **18**: "✅ Module 3 complete — Reusable Workflows."
+   - Then say: "Take a break here — wait until the instructor moves on to the next module. When you're ready to continue, just say **next**."
+   - **STOP here.** Do not increment `currentLesson` or present the next lesson.
+
+4. Increment `currentLesson` by 1. Read the `track` field (default `"core"` if missing). Cap at 34 if `track` is `"design"`, at 28 if `track` is `"qa"`, or at 23 if `track` is `"core"`.
+5. Write the updated state back to `tutorial/state.json`
+6. Read the next lesson file from `tutorial/lessons/` (zero-padded prefix)
+7. Present it to the user. Briefly acknowledge the skip in a neutral way — something like "Moving on!" — without making the user feel bad. Everyone learns at their own pace.

.github/copilot-instructions.md

@@ -18,16 +18,12 @@ You are running as an interactive tutorial guide for GitHub Copilot CLI. Your jo
 | `hint` | Get a hint for the current exercise |
 | `skip` | Skip the current exercise |
 | `progress` | See tutorial progress |
-| `qa` | Switch to the QA track (lessons 21-25) |
-| `design` | Switch to the Design track (lessons 26-31) |
+| `qa` | Switch to the QA track (lessons 24-28) |
+| `design` | Switch to the Design track (lessons 29-34) |
 | `core` | Switch back to the core track |
 
 When suggesting navigation to the user, tell them to type `/agent` and select from the list, or say "next" / "next lesson" / "give me a hint" etc. — you should infer which agent to use from natural language.
 
-## Permissions Note
-
-The tutorial frequently edits `tutorial/state.json` for navigation. If the user is prompted for permission on a state.json edit, tell them to select **"Yes, approve for session"** to auto-approve for the rest of the session.
-
 ## Behaviour Rules
 
 0. **Welcome the user on the first message of every session.** This rule handles the very first message, regardless of what the user typed (including "start the tutorial", "hello", or anything else). Do not defer to navigation agents for the first message — handle it entirely here.
@@ -86,43 +82,34 @@ The tutorial frequently edits `tutorial/state.json` for navigation. If the user
 
 The tutorial includes optional specialist tracks for QA engineers and designers. It is controlled by the `track` field in `tutorial/state.json`:
 
-- `"core"` (default) — Lessons 0-20, the standard developer-focused track
-- `"qa"` — Lessons 21-25, focused on QA workflows
-- `"design"` — Lessons 26-31, focused on design workflows
+- `"core"` (default) — Lessons 0-23, the standard developer-focused track
+- `"qa"` — Lessons 24-28, focused on QA workflows
+- `"design"` — Lessons 29-34, focused on design workflows
 
 ### Track Navigation
 
 | Say this | Or type this | What it does |
 |----------|-------------|-------------|
-| "switch to QA track" | `/agent qa` | Switch to the QA track (starts at lesson 21) |
-| "switch to Design track" | `/agent design` | Switch to the Design track (starts at lesson 26) |
+| "switch to QA track" | `/agent qa` | Switch to the QA track (starts at lesson 24) |
+| "switch to Design track" | `/agent design` | Switch to the Design track (starts at lesson 29) |
 | "switch to core track" | `/agent core` | Switch back to the core track |
 
 ### QA Lessons
 
-- **21: Test Planning from Requirements** — Analyse a feature request and create a structured test plan
-- **22: Test Case Design & Coverage** — Identify coverage gaps and design test cases using QA techniques
-- **23: Automated Test Generation** — Turn test cases into running Vitest tests
-- **24: E2E Testing with Playwright** — Write Playwright tests for the web UI
-- **25: QA Track Graduation** — Recap and bonus challenges
-
-### Design Lessons
-
-- **26: Translating Mockups to Specs** — Use Copilot to turn a visual design into a structured implementation spec
-- **27: Accessibility & Design Review** — Audit a UI against WCAG 2.1 AA and create a reusable `a11y` agent
-- **28: Design System Instructions** — Encode design system conventions in `copilot-instructions.md` so Copilot enforces them automatically
-- **29: Designer ↔ Developer Handoff** — Use the "interview me" pattern to produce a developer-ready handoff spec
-- **30: Rapid Prototyping** — Generate a working, interactive HTML prototype from the handoff spec in the same session
-- **31: Design Track Graduation** — Recap and bonus challenges
+- **24: Test Planning from Requirements** — Analyse a feature request and create a structured test plan
+- **25: Test Case Design & Coverage** — Identify coverage gaps and design test cases using QA techniques
+- **26: Automated Test Generation** — Turn test cases into running Vitest tests
+- **27: E2E Testing with Playwright** — Write Playwright tests for the web UI
+- **28: QA Track Graduation** — Recap and bonus challenges
 
 ### Design Lessons
 
-- **25: Translating Mockups to Specs** — Use Copilot to turn a visual design into a structured implementation spec
-- **26: Accessibility & Design Review** — Audit a UI against WCAG 2.1 AA and create a reusable `a11y` agent
-- **27: Design System Instructions** — Encode design system conventions in `copilot-instructions.md` so Copilot enforces them automatically
-- **28: Designer ↔ Developer Handoff** — Use the "interview me" pattern to produce a developer-ready handoff spec
-- **29: Rapid Prototyping** — Generate a working, interactive HTML prototype from the handoff spec in the same session
-- **30: Design Track Graduation** — Recap and bonus challenges
+- **29: Translating Mockups to Specs** — Use Copilot to turn a visual design into a structured implementation spec
+- **30: Accessibility & Design Review** — Audit a UI against WCAG 2.1 AA and create a reusable `a11y` agent
+- **31: Design System Instructions** — Encode design system conventions in `copilot-instructions.md` so Copilot enforces them automatically
+- **32: Designer ↔ Developer Handoff** — Use the "interview me" pattern to produce a developer-ready handoff spec
+- **33: Rapid Prototyping** — Generate a working, interactive HTML prototype from the handoff spec in the same session
+- **34: Design Track Graduation** — Recap and bonus challenges
 
 The `next`, `skip`, and `progress` agents are track-aware — they respect the active track's lesson range. The hooks work with any lesson number automatically.
 

README.md

@@ -31,8 +31,8 @@ You can navigate the tutorial using natural language or the `/agent` command:
 | "hint" or "give me a hint" | `/agent hint` | Get a hint for the current exercise |
 | "skip" or "skip this" | `/agent skip` | Skip the current exercise |
 | "progress" or "show progress" | `/agent progress` | See your tutorial progress |
-| "switch to QA track" | `/agent qa` | Switch to the QA track (lessons 21-25) |
-| "switch to Design track" | `/agent design` | Switch to the Design track (lessons 26-31) |
+| "switch to QA track" | `/agent qa` | Switch to the QA track (lessons 24-28) |
+| "switch to Design track" | `/agent design` | Switch to the Design track (lessons 29-34) |
 | "switch to core track" | `/agent core` | Switch back to the core track |
 
 ## Specialist Tracks
@@ -41,17 +41,17 @@ The tutorial includes two optional specialist tracks.
 
 ### QA Track
 
-The QA track (lessons 21-25) is for QA engineers. It covers test planning, test case design, automated test generation, and E2E testing with Playwright.
+The QA track (lessons 24-28) is for QA engineers. It covers test planning, test case design, automated test generation, and E2E testing with Playwright.
 
 To start the QA track, say "switch to QA track" or type `/agent qa`.
 
 ### Design Track
 
-The Design track (lessons 26-31) is for designers and frontend developers. It covers translating mockups, accessibility reviews, design system instructions, designer-developer handoff, and rapid prototyping.
+The Design track (lessons 29-34) is for designers and frontend developers. It covers translating mockups, accessibility reviews, design system instructions, designer-developer handoff, and rapid prototyping.
 
 To start the Design track, say "switch to Design track" or type `/agent design`.
 
-Both specialist tracks assume you have completed at least the core lessons (0-4). To return to the core track, say "switch to core track" or type `/agent core`.
+Both specialist tracks assume you have completed at least the foundations lessons (0-6). To return to the core track, say "switch to core track" or type `/agent core`.
 
 ## How It Works