[side-quest] Add side quest: Understanding Workflow Orchestration and dispatch-workflow

workshop/28-orchestrate-workflows.md

@@ -28,27 +28,27 @@ You'll build an orchestrator workflow that reads repository state, decides which
 
 ## Understand workflow orchestration
 
-When a repository needs different kinds of AI work — status reports, PR reviews, cost audits — you can keep each concern in its own focused workflow. An orchestrator connects them: it reads signals from the repository and dispatches the right specialist.
-
-The key primitive is `dispatch-workflow` in [`safe-outputs`](https://github.github.com/gh-aw/reference/safe-outputs/). It lets your orchestrator trigger another workflow in the same repository and optionally pass inputs to it.
+When a repository needs different kinds of AI work — status reports, PR reviews, cost audits — you can keep each concern in its own focused workflow. An orchestrator connects them: it reads signals from the repository and dispatches the right specialist using the [`dispatch-workflow`](https://github.github.com/gh-aw/reference/safe-outputs/) safe-output, which lets one workflow trigger another in the same repository.
 
 <picture>
    <source media="(prefers-color-scheme: dark)" srcset="images/28-orchestrator-routing-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="images/28-orchestrator-routing-light.svg">
    <img alt="Diagram: an orchestrator workflow reads repository signals and dispatches exactly one specialist workflow, or logs a summary and exits when no condition matches." src="images/28-orchestrator-routing-light.svg">
 </picture>
 
-> :thinking: **Predict:** Look at your existing workflows. Which one handles the broadest task? Which handles the narrowest? The broadest is a natural orchestration candidate; the narrowest is a natural specialist.
+> [!TIP]
+> <details>
+> <summary><b>Optional Side Quest:</b> Want the full explanation of why orchestration matters, how `dispatch-workflow` and its `workflows`/`max` fields work, and help choosing good signals before you design your own?</summary>
+>
+> Work through [Side Quest: Understanding Workflow Orchestration and `dispatch-workflow`](side-quest-28-01-orchestration-concepts.md), then come back here.
+>
+> </details>
 
 ## Steps
 
 ### Design your orchestrator
 
-Before writing code, decide:
-
-- What signals will the orchestrator read? (open issues count, PR age, recent commit activity, or a combination)
-- Which specialist workflows will it activate? (at most one per run keeps behavior predictable)
-- What condition routes to each specialist?
+Before writing code, decide what signals your orchestrator will read (for example, open issues count, PR age, or recent commit activity), which specialist workflows it will activate (at most one per run keeps behavior predictable), and what condition routes to each specialist.
 
 A simple decision table helps:
 

workshop/README.md

@@ -107,6 +107,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [Project Future AI Credit Costs with `gh aw forecast`](side-quest-26-01-forecast-costs.md) — full walkthrough of `gh aw forecast`: reading P10/P50/P90 output, using `--period week` and `--days 7`, forecasting all workflows, and deriving a `max-daily-ai-credits` value from the P90 figure; branches from [Step 26](26-manage-costs-and-budgets.md).
 - [Skill Injection Strategies — Hint, Fusion, and Inline](side-quest-29-01-skill-injection-strategies.md) — decision table, code examples, and a practice exercise for the hint, fusion, and inline strategies for wiring a `SKILL.md` into a workflow prompt; branches from [Step 29](29-skills-and-domain-knowledge.md).
 - [Recognizing Common Agentic Workflow Failure Modes](side-quest-22-01-failure-modes.md) — worked examples of empty data, tool error, timeout, and prompt drift failures with a match-the-fix practice exercise; branches from [Step 22](22-error-handling-and-resilience.md).
+- [Understanding Workflow Orchestration and `dispatch-workflow`](side-quest-28-01-orchestration-concepts.md) — explains why orchestration matters, how the `dispatch-workflow` safe-output and its `workflows`/`max` fields work, and how to choose good signals before designing an orchestrator; branches from [Step 28](28-orchestrate-workflows.md).
 - [How the `agentic-workflows` Skill Dispatcher Works](side-quest-10-03-skill-dispatcher.md) — full task-type table with trigger phrases, plus practice scenarios for matching a request to the Edit, Debug, or Optimize path; branches from [Step 9](09-agentic-editing.md).
 
 ## Getting Started

workshop/side-quest-28-01-orchestration-concepts.md

@@ -0,0 +1,71 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+# Side Quest: Understanding Workflow Orchestration and `dispatch-workflow`
+
+> _Optional: work through this before designing your orchestrator if you want the full mental model for how `dispatch-workflow` composes specialist workflows into a pipeline._
+
+## :dart: What You'll Do
+
+You'll learn why orchestration exists, how the `dispatch-workflow` [safe-output](https://github.github.com/gh-aw/reference/safe-outputs/) works, and how to pick good signals and candidate workflows before you design your own orchestrator.
+
+## :clipboard: Before You Start
+
+- You've read [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md) up to **Design your orchestrator**.
+
+## Why orchestrate instead of building one big workflow?
+
+When a repository needs different kinds of AI work — status reports, PR reviews, cost audits — you can keep each concern in its own focused workflow. An orchestrator connects them: it reads signals from the repository and dispatches the right specialist, instead of one workflow trying to do everything.
+
+<picture>
+   <source media="(prefers-color-scheme: dark)" srcset="images/28-orchestrator-routing-dark.svg">
+   <source media="(prefers-color-scheme: light)" srcset="images/28-orchestrator-routing-light.svg">
+   <img alt="Diagram: an orchestrator workflow reads repository signals and dispatches exactly one specialist workflow, or logs a summary and exits when no condition matches." src="images/28-orchestrator-routing-light.svg">
+</picture>
+
+> :thinking: **Predict:** Look at your existing workflows. Which one handles the broadest task? Which handles the narrowest? The broadest is a natural orchestration candidate; the narrowest is a natural specialist.
+
+## How `dispatch-workflow` works
+
+The key primitive is `dispatch-workflow` in [`safe-outputs`](https://github.github.com/gh-aw/reference/safe-outputs/). It lets your orchestrator trigger another workflow in the same repository and optionally pass inputs to it.
+
+```markdown .github/workflows/repo-orchestrator.md
+---
+safe-outputs:
+  dispatch-workflow:
+    workflows:
+      - daily-status
+      - pr-reviewer
+    max: 1
+---
+```
+
+The `workflows` list is an allowlist — your orchestrator can only dispatch workflows named here. The `max: 1` cap prevents one run from triggering many specialists at once.
+
+> [!NOTE]
+> `dispatch-workflow` triggers the named workflow with a `workflow_dispatch` event. The specialist runs asynchronously in its own Actions job. Your orchestrator does not wait for it to complete.
+
+## Choose signals and candidates
+
+Before writing any orchestrator brief, decide:
+
+- **What signals will the orchestrator read?** (open issues count, PR age, recent commit activity, or a combination)
+- **Which specialist workflows will it activate?** (at most one per run keeps behavior predictable)
+- **What condition routes to each specialist?**
+
+A simple decision table helps turn these questions into something you can hand to your agent:
+
+| Signal | Action |
+|--------|--------|
+| Stale open PRs exist | Dispatch the PR reviewer |
+| No status issue created today | Dispatch the daily-status reporter |
+| Neither condition | Log a summary and exit |
+
+Keep the table narrow at first — one or two signals and two specialists is enough to prove the pattern. You can add more rows once the first version is working reliably.
+
+## :white_check_mark: Checkpoint
+
+- [ ] You can explain, in one sentence, why an orchestrator is useful once you have more than one workflow
+- [ ] You can describe what `workflows:` and `max:` do inside a `dispatch-workflow` safe-output block
+- [ ] You wrote your own signal-to-action decision table with at least two rows
+
+**Return to the main adventure:** [Orchestrate Multiple Agentic Workflows](28-orchestrate-workflows.md)