Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions .github/workflows/guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,18 @@ Use these rules across workshop authoring/editing workflows to keep the tutorial
- When the task is to create, edit, debug, or upgrade an agentic workflow from a CCA surface, explicitly call out the `/agentic-workflows` skill in the prompt.
- If a CCA-oriented step still requires separate terminal work (for example `gh aw init` or `gh aw compile`), clearly separate the terminal action from the Agents-tab prompt so learners know which surface to use for each action.

## Event provisioning surfaces

- Some workshop content is intentionally reused in provisioned event environments such as an org profile README and a learner-repository Codespaces launcher.
- The maintained example assets live in `workshop/examples/event-provisioning/` and represent downstream copies, not primary authored content.
- When you change workshop onboarding language that should also appear in those provisioned surfaces, update the marked source blocks in `workshop/00-welcome.md` and keep the examples in sync.
- For provisioned learner repositories, prefer a Codespaces launcher entry point that starts at Step 4 or Step 5 because org invite, repository creation, and Codespace creation are already complete.
## Golden-Ticket Workshop Surfaces

- The golden-ticket workshop is the fully preconfigured beginner path: Copilot, repository setup, and Codespaces bootstrapping are prepared ahead of time.
- Some workshop content is intentionally reused in golden-ticket workshop surfaces such as an org profile README and a learner-repository Codespaces launcher.
- The maintained golden-ticket workshop assets live on the `golden-ticket-workshop` branch under `.github/participant-template/` plus `.github/workflows/create-participants-repo.yml`. During org provisioning, that branch is copied into the provisioned org's `.github-private` repository.
- When you change workshop onboarding language that should also appear in those golden-ticket surfaces, update the marked source blocks in `workshop/00-welcome.md` and have the responsible agent check whether the `golden-ticket-workshop` branch also needs a corresponding update.
- When an agent edits onboarding, setup, Codespaces, or early navigation content on `main`, it should explicitly assess downstream impact on `golden-ticket-workshop` and either update the affected branch assets or state why no branch change is needed.
- Treat `workshop/00-welcome.md` as the source only for intentionally shared workshop framing and onboarding copy, not for page structure.
- Treat the golden-ticket participant `README.md` as a separate launcher artifact for the preconfigured beginner experience, not as a structural mirror of `workshop/00-welcome.md`.
- Keep the ending call-to-action intentionally different: `workshop/00-welcome.md` should continue learners into the next workshop step, while the golden-ticket participant `README.md` should direct them into the precreated repository and Codespaces flow.
- The participant template's `README.md`, `.devcontainer/devcontainer.json`, `.vscode/tasks.json`, `.vscode/settings.json`, and the provisioning workflow are standalone assets and must be reviewed and tested in the branch and `.github-private` context where they run.
- For golden-ticket learner repositories, prefer a Codespaces launcher entry point that starts at Step 4 or Step 5 because org invite, repository creation, and Codespace creation are already complete.

## Positioning agentic workflows as an Actions-compatible superset

Expand Down Expand Up @@ -245,7 +251,7 @@ This rule does not override clearly superior choices for all learners. It is a t

## Consistency check

Before finalizing workshop edits, quickly confirm that early steps remain UI-first, do not require `gh` before it is truly needed, do not reference Node.js as a prerequisite, and keep any event-provisioning examples synchronized with the marked workshop source content.
Before finalizing workshop edits, quickly confirm that early steps remain UI-first, do not require `gh` before it is truly needed, do not reference Node.js as a prerequisite, and ensure the responsible agent has checked whether any intended org-provisioned event changes also require updates on the `golden-ticket-workshop` branch.

## Activity numbering for a sortable adventure graph

Expand Down
20 changes: 17 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ automated tooling (author review, student simulation, order checks) under `.gith
README.md # Workshop landing page (GitHub Skills style)
AGENTS.md # This file — tips for AI agents
workshop/ # Step-by-step workshop content (00-welcome.md … 16-connect-data-source.md)
examples/event-provisioning/ # Example assets for provisioned org README and learner-repo Codespaces launchers
.github/
workflows/ # Agentic workflow definition files (*.md) and compiled lock files (*.lock.yml)
skills/ # Copilot skill definitions for agentic-workflows and agentic-workflow-designer
Expand Down Expand Up @@ -67,7 +66,13 @@ The following rules are **disabled** in `.markdownlint-cli2.yaml` — do not add

**Never configure Codespace badges or `devcontainer.json` to open from this (`gh-aw-workshop`) repository.** The workshop repository itself is not a suitable Codespace base — learners work in their own practice repositories, not a clone of this one. Any Codespace badge or devcontainer setup must point to the learner's own repository.

The checked-in examples under `workshop/examples/event-provisioning/` are exceptions for template authoring only. They exist so event provisioning systems can copy a launcher into each learner's own repository; do not treat them as launchers for this repository itself.
## Working with the Golden-Ticket Workshop

The golden-ticket workshop assets live on the `golden-ticket-workshop` branch, not on `main`. This is the fully preconfigured beginner workshop path: Copilot, repository setup, and Codespaces bootstrapping are prepared ahead of time.

During org provisioning, that branch is copied into the provisioned org's `.github-private` repository. From there, `.github/workflows/create-participants-repo.yml` and the `.github/participant-template/` files create and update participant repositories.

Do not treat those launchers as suitable for this repository itself.

## Working with workshop content

Expand All @@ -77,7 +82,16 @@ The checked-in examples under `workshop/examples/event-provisioning/` are except
- Run the markdown linter before committing any workshop step edits.
- When adding a new step, follow the existing file naming pattern and update the curriculum table in both `workshop/README.md` and `workshop/00-welcome.md`.
- When editing shared intro or onboarding copy that may be reused outside the workshop pages, preserve and update the HTML reuse markers in `workshop/00-welcome.md`.
- Treat `workshop/examples/event-provisioning/` as maintained examples. Keep the org-profile README and devcontainer launcher aligned with the corresponding marked source content in `workshop/00-welcome.md`.

Golden-ticket workshop maintenance rules:

- When a workshop change should also affect the golden-ticket workshop experience, agents should check whether the `golden-ticket-workshop` branch needs a corresponding update and carry that update through when it is in scope.
- `workshop/00-welcome.md` owns only shared workshop framing and onboarding copy that is intentionally reused.
- The golden-ticket branch README is its own launcher artifact for the preconfigured beginner experience. Do not try to keep it structurally identical to `workshop/00-welcome.md`.
- Keep the ending call-to-action intentionally different: `workshop/00-welcome.md` should continue into the next workshop step, while the golden-ticket README should direct learners into the precreated repository and Codespaces flow.
- The participant template files, Codespaces bootstrap files, and provisioning workflow are standalone branch assets.
- When an agent edits onboarding, setup, Codespaces, or early navigation content on `main`, it should explicitly assess downstream impact on `golden-ticket-workshop` and either update the affected branch assets or state why no branch change is needed.
- Validate golden-ticket changes in the branch and `.github-private` context where they run.

## Working with agentic workflow files

Expand Down