Replace overrides model with CI-injected steps for scenario exercises

[Copilot]

✨ Enhancement

The old overrides/ model required duplicating entire 200+ line exercise files when only a few lines differed per scenario. Core exercises also had Tailspin Toys content hardcoded, making it impossible to add a non-Tailspin scenario without full rewrites.

What does this improve?

• Core exercises are now generic templates; scenario-specific content is injected at CI time
• Adding a new scenario only requires writing the ## sections that differ — not copying whole files
• The injection mechanism is explicit and composable: sections absent from a steps file are taken from the core unchanged

Implementation approach:

Injection model

scenarios/<id>/overrides/ (full file copies) → scenarios/<id>/steps/ (section-only files)

A steps file contains only the ## headings that need to differ:

## Scenario

As the list of games grows, Tailspin Toys wants to allow users to filter by publisher and category...

## Running the application

The website is a crowdfunding platform... backend written in Python using Flask...

scripts/render-scenario.py (new) walks each core exercise, replaces any ## section that has a matching entry in the scenario's steps file, and writes rendered output to rendered/<scenario-id>/. A new .github/workflows/render-exercises.yml runs this on push and uploads the rendered exercises as a CI artifact.

Core exercises generified

• 2-custom-instructions.md — removed Flask/C# specific examples; fixed missing [repository-custom-instructions] link ref
• 3-copilot-agent-mode-vscode.md — ## Running the Tailspin Toys website → ## Running the application; removed Flask/Python specifics
• 4-copilot-coding-agent.md — ## Scenarios → ## Scenario; removed YAML setup block and games-specific issue text; ## Create new endpoints to modify games → ## Create new API endpoints
• 6-managing-agents.md — fixed pre-existing duplicate [next-lesson] reference
• 7-iterating-copilot-work.md — "Flask API" → "API"

Scenario steps files created

Both tailspin-toys and tailspin-toys-dotnet now have steps/ files for exercises 2–6, each containing only the sections that differ (Tailspin branding, tech-stack startup output, YAML setup blocks, language-specific doc comment examples, etc.).

Tooling updated

• scripts/new-scenario.py — scaffolds steps/README.md explaining section-injection; updated next-steps messaging
• scripts/validate-scenario.py — _check_overrides() → _check_steps(); validates against steps/ directory
• scenarios/README.md and docs/authoring/new-scenario-guide.md — Step 5 rewritten to document steps-file authoring with minimal and multi-section examples

Original prompt

Let's create an implementation that takes everything into account we talked about for allowing new scenarios to be added to the workshop. The real keys are: 1. Ensuring we have a structure that makes it easy for an author to do so. 2. Contains scripts to create scaffolding for new scenarios. 3. Has guidelines on what the scenario should contain, and maybe an agent or prompt that could be used to help either create or update a sample app for this purpose. 4. Allows for skipping of certain modules in case there are some that aren't appropriate for the scenario in question. Don't create a PR. Just work on a new branch and I'll come back to this later to see where we want to go from here.

Chronological Review: 1. User asked to copy tailspin-toys app source from agents-in-sdlc repo to github.com/github-samples/tailspin-toys with NO CHANGES to source repo 2. I confirmed scope via ask_user (app_core only, fresh history), staged files in /tmp, pushed to target repo successfully 3. User asked how hard it would be to create CI workflow generating markdown from MDX/Astro setup 4. I analyzed and gave 3 approaches (regex strip, HTML→MD via Turndown, MDX AST walker) 5. User clarified goal: emit standard MD that renders on GitHub 6. I confirmed yes, recommended MDX AST walker approach 7. User asked about supporting scenario swap (e.g., Java app instead of Tailspin) 8. I refreshed repo state - found new structure: workshop/, workshop-content/_partials/, scripts/render-markdown.py, .github/instructions/ - and gave detailed scenario-pack architecture suggestions 9. User asked for walkthrough of adding new scenario - I gave 11-step walkthrough 10. User asked about scripts to streamline - I gave 4-tier script proposal 11. User asked for current branch name - I answered from memory: `chore/workshop-review-pass` 12. User said "check again :D" 13. I ran `git branch --show-current` → result: `refactor/relocate-content-and-author-docs` 14. I responded acknowledging the branch had changed

Intent Mapping:

• Copy tailspin app to new repo (DONE)
• Discuss CI for MDX→MD conversion (DISCUSSION)
• Discuss scenario-swap architecture (DISCUSSION)
• Discuss authoring scripts (DISCUSSION)
• Confirm current branch (ANSWERED)

Technical Inventory:

• Source repo: /Users/geektrainer/repos/agents-in-sdlc
• Target repo: github.com/github-samples/tailspin-toys (was empty, now populated)
• Stack: Astro + Starlight (docs/), Svelte (client/), Python/Flask (server/ - now in workshop/)
• MDX content in workshop-content/ with _partials/ system
• scripts/render-markdown.py exists for MDX→MD conversion
• workshop/ contains generated .md files
• Branch changed during session from chore/workshop-review-pass to refactor/relocate-content-and-author-docs

Code Archaeology:

• No code changes made (user repeatedly said NO CHANGES)
• Only git/file reads and one push to external repo

Progress Assessment:

• Tailspin copy: COMPLETE
• All other items: discussion only, no code changes

Recent Commands:

• git branch --show-current → returned refactor/relocate-content-and-author-docs
• Responded to user with corrected branch name plus quip about switching branches

1. Conversation Overview: - Primary Objectives: - "take the source code that makes up the tailspin toys app...and create a new copy of that on github.com/github-samples/tailspin-toys" (DONE) - "how hard would it be to create a new CI workflow that generates markdown files from the MDX/Astro setup?" (discussion) - "I want to be able to have a CI where i could take the MDX/modular structure we have and be able to emit standard Markdown that would render properly on GItHub. Is that possible?" (discussion) - Scenario-swap support: "instead of using tailspin-toys as their example they wanted to use a Java app. what updates would we need" (discussion) - "walk me through the steps someone would need to complete to bring in a new scenario" (discussion) - "could we create scripts that would help streamline this process?" (discussion) - "what's the branch name you have?" (just answered) - Session Context: One concrete action (repo copy) followed by four discussion threads about MDX-to-MD conversion, scenario-pack architecture, authoring workflow, and supporting scripts. User repeatedly emphasized "DO NOT MAKE ANY CHANGES" / "NO UPDATES". - User Intent Evolution: Started with concrete task, then shifted to architectural brainstorming for workshop scalability.

2. Technical Foundation:
   • Source repo: /Users/geektrainer/repos/agents-in-sdlc (branch changed mid-session from chore/workshop-review-pass to refactor/relocate-content-and-author-docs)
   • Target repo: github.com/github-samples/tailspin-toys (internal visibility, was empty, now populated with single fresh-history commit on main)
   • Frontend: Astro (server output, node adapter) + Svelte + Tailwind in client/
   • Docs site: Astro + Starlight in docs/, builds workshop-con...

Created from Copilot CLI via the copilot delegate command.