Book Orchestration
This skill describes how the book agents work together to build the Agent Package Manager (APM) 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 |
|---|---|
book-architect |
Designs TOC, chapter specs, navigation, wave plan |
theory-researcher |
Produces cited concept briefs from APM docs |
apm-cli-explorer |
Installs & introspects the apm CLI; feature notes + examples |
chapter-author |
Weaves theory + CLI reference into chapter content |
code-verifier |
Runs/validates every example; 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
book-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
apm-environment-setupskill (viaapm-cli-explorer) → theapmCLI installed and introspectable, plus a sample project to inspect.
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)apm-cli-explorer→ feature notes + draft examples (content/research/<ch>-reference.md)
- Author:
chapter-author→ chapter draft, pulling both briefs together. - Verify:
code-verifier→ validate/run every example; loop with author/explorer until all PASS (or SKIPPED-needs-network with a clear marker). - Review:
chapter-reviewer→ ACCEPT or REVISE; on REVISE, route must-fixes tochapter-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-reviewerreads across chapters for cross-chapter consistency (terminology, ordering, duplicate/contradictory claims).chapter-authorapplies cross-cutting fixes;frontend-builderfinalizes nav/cross-links.
Wave ordering guidance
- Wave 0: one pilot chapter (e.g. "Why a package manager for agents?") to validate the pipeline.
- Wave 1: chapters with the most existing source material (lowest risk).
- Wave 2: the hardest chapters (governance/policy, transitive MCP, enterprise ramp).
- 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 PASS and the reviewer ACCEPTs.