diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6967f376..dfef81ed 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,18 +2,17 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an Astro + Starlight site at . The demo application learners build during the workshop lives in a separate repository: . -**This is a content-only repo.** Do not add Python, Flask, Svelte, Tailwind, or other application code here. Application changes belong in `tailspin-toys`. +**This is a content-only repo.** Do not add the demo app's application code (Astro SSR endpoints, the Drizzle data layer, UI components, Tailwind styles, or tests) here. Application changes belong in `tailspin-toys`. ## Repository structure - `docs/` — Astro + Starlight site that publishes the workshop to GitHub Pages. - `src/content/docs/` — **Source MDX for all lessons. Edit here.** - `index.mdx` — Workshop landing page. - - `prereqs.mdx` — Shared setup lesson (Exercise 0). - - `cli/`, `vscode/`, `cloud/` — Per-path lessons (Copilot CLI / VS Code / Cloud agent). + - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each harness opens with its own `0-prerequisites.mdx` setup lesson; the CLI and VS Code harnesses set up a codespace, while the app and cloud harnesses cover the setup their flow needs (for the app, installing Node.js locally and creating the project from the template). - `_shared/` — Reusable MDX fragments imported via the `@shared/*` alias (see partials conventions below). Underscore-prefixed dirs are excluded from routing. - `_images/` — Screenshots and diagrams. - - `astro.config.mjs` — Site config including the manually maintained sidebar and a redirect from the legacy `/shared/0-prereqs/` URL to `/prereqs/`. + - `astro.config.mjs` — Site config including the manually maintained sidebar. The legacy `/shared/0-prereqs/` → home (`/`) redirect is a full-HTML redirect page at `src/pages/shared/0-prereqs.astro` (not an `astro.config.mjs` `redirects` entry, which would emit a stub with no `` element that Pagefind can't index). Prerequisites are now per-harness (`//0-prerequisites/`), so the old shared-prereqs URL forwards to the home page. - `scripts/` — Author tooling for the partials system (`lint_partials.py`, `sync_partial_metadata.py`, `_partials_lib.py`). - `AUTHORING.md` — Author entry point (recipes for adding lessons, partials, images). - `CONTRIBUTING.md` — Short pointer to AUTHORING.md + PR/CI rules. @@ -48,7 +47,7 @@ Don't extract a partial unless it's used in 2+ places (or the same place across ### Reusing a lesson across paths -When the same prose applies to multiple paths (CLI, VS Code, cloud), pull the body into a `section-…` partial under `_shared/` and `import` it from each per-path lesson. The host page owns frontmatter, H2s, and prev/next nav; the partial owns the reusable prose. +When the same prose applies to multiple harnesses (CLI, VS Code, cloud), pull the body into a `section-…` partial under `_shared/` and `import` it from each per-harness lesson. The host page owns frontmatter, H2s, and prev/next nav; the partial owns the reusable prose. ### Linking @@ -76,7 +75,7 @@ Before opening or updating a PR, also make the **PR-time consistency pass** docu ## Things NOT to do here -- Don't add Python, Flask, SQLAlchemy, Svelte, Astro components, Tailwind classes, or any other application code. That belongs in `github-samples/tailspin-toys`. -- Don't author against `client/` or `server/` paths — they were removed when the app was extracted. +- Don't add the demo app's application code — Astro SSR endpoints, the Drizzle data layer, `.astro` UI components, Tailwind classes, or Vitest/Playwright tests. That belongs in `github-samples/tailspin-toys`. +- Don't author against application source paths — the demo app is a single Astro project that lives in `tailspin-toys`, not here. - Don't generate summary markdown files at the end of a task. - Don't add `mkdocs.yml` or other parallel docs tooling — Astro + Starlight is the site. diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md index 5f57c60f..bedd1025 100644 --- a/.github/instructions/astro.instructions.md +++ b/.github/instructions/astro.instructions.md @@ -16,7 +16,7 @@ applyTo: 'docs/**/*.{astro,mjs,ts,js}' ## Don't add app-style components -This is a docs wrapper. Don't add interactive Svelte islands, Tailwind utility-class styling layers, custom routing, or other application-style code. Anything beyond Starlight defaults should be justified. +This is a docs wrapper. Don't add interactive framework islands (Svelte, React, etc.), Tailwind utility-class styling layers, custom routing, or other application-style code. Anything beyond Starlight defaults should be justified. ## Building and verifying diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md index 515bff82..f5193b60 100644 --- a/.github/instructions/markdown.instructions.md +++ b/.github/instructions/markdown.instructions.md @@ -149,11 +149,11 @@ Use Markdown image syntax with paths relative to the MDX file: ![Alt text describing the image](../_images/some-screenshot.png) ``` -For an image referenced from a `_shared/` partial, use the same `../_images/...` relative path — `_shared/` sits one level under `docs/src/content/docs/`, just like `cli/`, `vscode/`, and `cloud/`, so the path resolves identically for the partial and its consumer pages. +For an image referenced from a `_shared/` partial, use the same `../_images/...` relative path — `_shared/` sits one level under `docs/src/content/docs/`, just like `cli/`, `vscode/`, `cloud/`, and `app/`, so the path resolves identically for the partial and its consumer pages. ### Path conventions -- Per-path lessons: `cli/`, `vscode/`, `cloud/`. Files numbered by lesson order: `1-installing.mdx`, `2-custom-instructions.mdx`, etc. +- Per-path lessons: `cli/`, `vscode/`, `cloud/`, `app/`. Files numbered by lesson order: `1-installing.mdx`, `2-custom-instructions.mdx`, etc. - Shared content: reusable fragments live in `_shared/` (e.g. `section-mcp-overview.mdx`) and are imported into lesson pages via the `@shared/` alias. They are body-only partials inlined at build time, not standalone routed pages — see [`partials.instructions.md`](./partials.instructions.md). ### Cross-repo links diff --git a/.github/skills/build-and-verify-docs/SKILL.md b/.github/skills/build-and-verify-docs/SKILL.md index 707db55a..1da8fe7f 100644 --- a/.github/skills/build-and-verify-docs/SKILL.md +++ b/.github/skills/build-and-verify-docs/SKILL.md @@ -45,7 +45,7 @@ cd docs && rm -rf dist && npm run build ### 2. Page-count invariant -The built page count should equal the number of routable `.mdx` files — everything under `docs/src/content/docs/` **except** `_shared/` — plus the one legacy redirect (`/shared/0-prereqs/`). You never hard-code the number; you confirm the relationship: +The built page count should equal the number of routable `.mdx` files — everything under `docs/src/content/docs/` **except** `_shared/` — plus the one legacy redirect (`/shared/0-prereqs/`, authored as a full-HTML redirect page at `docs/src/pages/shared/0-prereqs.astro`). You never hard-code the number; you confirm the relationship: ```bash # routable .mdx (expected pages, minus the redirect) diff --git a/.github/skills/validate-site-playwright/SKILL.md b/.github/skills/validate-site-playwright/SKILL.md index e04c3be2..b901add7 100644 --- a/.github/skills/validate-site-playwright/SKILL.md +++ b/.github/skills/validate-site-playwright/SKILL.md @@ -39,7 +39,7 @@ Don't hard-code URLs. The built `dist/` is the source of truth for what routes e find docs/dist -name index.html | grep -v 404 | sed 's#docs/dist#/agents-in-sdlc#; s#/index.html#/#' ``` -Validate a **representative sample** that covers every layout and path: the landing page (`/agents-in-sdlc/`), `prereqs/`, and at least one lesson from each of `cli/`, `vscode/`, and `cloud/`. For a release pass or a change that touches shared layout/components, validate **all** routes. +Validate a **representative sample** that covers every layout and harness: the landing page (`/agents-in-sdlc/`), a per-harness prerequisites page (e.g. `cli/0-prerequisites/`), and at least one lesson from each of `cli/`, `vscode/`, `cloud/`, and `app/`. For a release pass or a change that touches shared layout/components, validate **all** routes. ## 3. Validate each route @@ -49,7 +49,7 @@ For each chosen route, use the Playwright MCP tools: 2. **Confirm it rendered** — `browser_snapshot` and check the page has its heading/title and real content (not an error page or raw, unrendered MDX). 3. **Check the console** — `browser_console_messages` with `level: "error"`. There should be **zero** errors. Hydration warnings and 404s for assets surface here. - *Known benign exception:* the legacy redirect route `/agents-in-sdlc/shared/0-prereqs/` is a bare meta-refresh stub (it immediately forwards to `/prereqs/`) and declares no favicon, so the browser auto-requests `/favicon.ico` and logs a single `404 (Not Found)`. That one favicon 404 **on the redirect stub only** is expected. Validate that route by confirming it lands on `/prereqs/`, not by console cleanliness. A favicon 404 on any *real* page is a genuine finding (real pages link `favicon.svg`). + *Known benign exception:* the legacy redirect route `/agents-in-sdlc/shared/0-prereqs/` is a minimal full-HTML redirect page (it immediately forwards to the home page `/agents-in-sdlc/` via a meta refresh) and declares no favicon, so the browser auto-requests `/favicon.ico` and logs a single `404 (Not Found)`. That one favicon 404 **on the redirect page only** is expected. Validate that route by confirming it lands on the home page, not by console cleanliness. A favicon 404 on any *real* page is a genuine finding (real pages link `favicon.svg`). 4. **Find broken images** — `browser_evaluate` with an async function that **force-loads lazy images first**, then flags only the ones that truly fail. Starlight/Astro mark below-the-fold images `loading="lazy"`, so a naive `naturalWidth === 0` check reports false positives for images that simply haven't scrolled into view yet: ```js diff --git a/AUTHORING.md b/AUTHORING.md index 1a0a65ae..3774be30 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -13,10 +13,10 @@ agents-in-sdlc/ ├── docs/ │ └── src/content/docs/ ← MDX source. EDIT HERE. │ ├── index.mdx ← Workshop landing page -│ ├── prereqs.mdx ← Shared setup (Exercise 0) -│ ├── cli/ ← Copilot CLI lessons -│ ├── vscode/ ← VS Code lessons -│ ├── cloud/ ← Cloud agent lessons +│ ├── cli/ ← Copilot CLI lessons (0-prerequisites.mdx + numbered exercises) +│ ├── vscode/ ← VS Code lessons (0-prerequisites.mdx + numbered exercises) +│ ├── cloud/ ← Cloud agent lessons (0-prerequisites.mdx + numbered exercises) +│ ├── app/ ← GitHub Copilot app lessons (setup folded into Exercise 1) │ ├── _shared/ ← Reusable MDX fragments (callout-/section-/exercise-) │ └── _images/ ← Screenshots and diagrams └── .github/ @@ -29,7 +29,7 @@ agents-in-sdlc/ ### Add a new lesson -1. **Pick a path and number.** Lessons live under `docs/src/content/docs/{cli,vscode,cloud}/N-name.mdx`. `N` is the next available integer in that path; the number drives the URL slug (`/cli/4-generating-code/`). +1. **Pick a path and number.** Lessons live under `docs/src/content/docs/{cli,vscode,app,cloud}/N-name.mdx`. `N` is the next available integer in that path; the number drives the URL slug (`/cli/3-generating-code/`). 2. **Create the file** with frontmatter: ```mdx --- @@ -44,8 +44,8 @@ agents-in-sdlc/ 3. **Write the body.** Use Markdown plus optional MDX `