Playbook Orchestration
This skill describes how the book's agents work together to build the GitHub Agentic Workflows
(gh-aw) interactive book. It is the orchestration layer: who is dispatched, in what order, with
what hand-offs and checkpoints. (This is a starting scaffold — refine as the project evolves.)
The team
| Agent |
Role |
playbook-architect |
Designs TOC, chapter specs, navigation, wave plan |
theory-researcher |
Produces cited concept briefs from the gh-aw docs |
gh-aw-explorer |
Installs & explores the gh aw CLI + schema; feature notes + examples |
chapter-author |
Weaves theory + capability into chapter content |
code-verifier |
Compiles every example workflow; reports pass/fail |
chapter-reviewer |
Reviews chapters; ACCEPT/REVISE + ranked findings |
frontend-builder |
Builds the interactive HTML shell and wires content in |
Pipeline (per the case-study methodology: draft → review → revise, in waves)
Phase 0 — Architecture
- Dispatch
playbook-architect → TOC, chapter table, section breakdowns, wave plan.
- Dispatch
frontend-builder → scaffold the site shell + nav driven by the TOC.
- Checkpoint: commit TOC + shell.
Phase 1 — Environment
- Run the
gh-aw-environment-setup skill (via gh-aw-explorer) → the gh aw CLI installed and
explorable (gh aw version).
Waves (repeat per wave; start with ONE pilot chapter, then widen)
For each chapter in the wave, run research in parallel, then author, verify, review:
5. Research (parallel):
theory-researcher → concept brief (content/research/<ch>-theory.md)gh-aw-explorer → feature notes + draft example workflows (content/research/<ch>-features.md)
- Author:
chapter-author → chapter draft, pulling both briefs together.
- Verify:
code-verifier → compile every example workflow; loop with author/explorer until all
PASS (or SKIPPED-needs-secret with a clear marker).
- Review:
chapter-reviewer → ACCEPT or REVISE; on REVISE, route must-fixes to chapter-author.
- Integrate:
frontend-builder → wire the accepted chapter into the site nav.
- Checkpoint: commit the chapter (draft + examples + review verdict).
Integration pass (after all waves)
chapter-reviewer reads across chapters for cross-chapter consistency (terminology, ordering,
duplicate/contradictory claims).chapter-author applies cross-cutting fixes; frontend-builder finalizes nav/cross-links.
Wave ordering guidance
- Wave 0: one pilot chapter (e.g. "What is an agentic workflow?") to validate the whole pipeline.
- Wave 1: chapters with the most existing source material (lowest risk).
- Wave 2: the hardest chapters (security model, safe-outputs, MCP, multi-workflow composition).
- Wave 3: integration chapters needing cross-references to earlier ones.
Orchestration principles
- One chapter, one author per wave — keep scope inside an agent's context budget; split if too big.
- Checkpoint discipline — draft → review → revise → commit at each chapter.
- Batch reviews in later waves (one reviewer over several chapters) to cut dispatch overhead.
- Fix the primitives, not the symptom — when a recurring gap appears, update the relevant agent
definition / instructions rather than hand-patching each chapter.
- Verify before ship — no chapter is "done" until its examples compile (PASS) and the reviewer ACCEPTs.
1---2name: playbook-orchestration3description: The wave-based workflow that coordinates the book's agent team (architect, theory-researcher, gh-aw-explorer, chapter-author, code-verifier, chapter-reviewer, frontend-builder) to produce the GitHub Agentic Workflows interactive book end to end. Use to plan and run the production pipeline for one or more chapters.4---56# Playbook Orchestration78This skill describes **how the book's agents work together** to build the GitHub Agentic Workflows9(gh-aw) interactive book. It is the orchestration layer: who is dispatched, in what order, with10what hand-offs and checkpoints. (This is a starting scaffold — refine as the project evolves.)1112## The team13| Agent | Role |14|-------|------|15| `playbook-architect` | Designs TOC, chapter specs, navigation, wave plan |16| `theory-researcher` | Produces cited concept briefs from the gh-aw docs |17| `gh-aw-explorer` | Installs & explores the `gh aw` CLI + schema; feature notes + examples |18| `chapter-author` | Weaves theory + capability into chapter content |19| `code-verifier` | Compiles every example workflow; reports pass/fail |20| `chapter-reviewer` | Reviews chapters; ACCEPT/REVISE + ranked findings |21| `frontend-builder` | Builds the interactive HTML shell and wires content in |2223## Pipeline (per the case-study methodology: draft → review → revise, in waves)2425### Phase 0 — Architecture261. Dispatch `playbook-architect` → TOC, chapter table, section breakdowns, wave plan.272. Dispatch `frontend-builder` → scaffold the site shell + nav driven by the TOC.283. Checkpoint: commit TOC + shell.2930### Phase 1 — Environment314. Run the `gh-aw-environment-setup` skill (via `gh-aw-explorer`) → the `gh aw` CLI installed and32 explorable (`gh aw version`).3334### Waves (repeat per wave; start with ONE pilot chapter, then widen)35For each chapter in the wave, run **research in parallel**, then author, verify, review:365. **Research (parallel):**37 - `theory-researcher` → concept brief (`content/research/<ch>-theory.md`)38 - `gh-aw-explorer` → feature notes + draft example workflows (`content/research/<ch>-features.md`)396. **Author:** `chapter-author` → chapter draft, pulling both briefs together.407. **Verify:** `code-verifier` → compile every example workflow; loop with author/explorer until all41 PASS (or SKIPPED-needs-secret with a clear marker).428. **Review:** `chapter-reviewer` → ACCEPT or REVISE; on REVISE, route must-fixes to `chapter-author`.439. **Integrate:** `frontend-builder` → wire the accepted chapter into the site nav.4410. Checkpoint: commit the chapter (draft + examples + review verdict).4546### Integration pass (after all waves)4711. `chapter-reviewer` reads across chapters for cross-chapter consistency (terminology, ordering,48 duplicate/contradictory claims).4912. `chapter-author` applies cross-cutting fixes; `frontend-builder` finalizes nav/cross-links.5051## Wave ordering guidance52- **Wave 0:** one pilot chapter (e.g. "What is an agentic workflow?") to validate the whole pipeline.53- **Wave 1:** chapters with the most existing source material (lowest risk).54- **Wave 2:** the hardest chapters (security model, safe-outputs, MCP, multi-workflow composition).55- **Wave 3:** integration chapters needing cross-references to earlier ones.5657## Orchestration principles58- **One chapter, one author per wave** — keep scope inside an agent's context budget; split if too big.59- **Checkpoint discipline** — draft → review → revise → commit at each chapter.60- **Batch reviews** in later waves (one reviewer over several chapters) to cut dispatch overhead.61- **Fix the primitives, not the symptom** — when a recurring gap appears, update the relevant agent62 definition / instructions rather than hand-patching each chapter.63- **Verify before ship** — no chapter is "done" until its examples compile (PASS) and the reviewer ACCEPTs.
webmaxru