Textbook Chapter Production Pipeline

Orchestrate a 36-agent team to produce a publication-quality, self-contained HTML textbook

chapter from a syllabus module definition.

Pipeline Overview

The pipeline runs in 13 phases:

Phase 0:  SETUP           Chapter Lead reads syllabus, sets scope
Phase 1:  PLANNING        Curriculum + Deep Explanation + Teaching Flow agents
Phase 2:  BUILDING        Example + Code + Visual + Exercise agents
Phase 3:  STRUCTURE       Structural Refactoring Architect reviews book-level organization
Phase 4:  SELF-CONTAIN    Self-Containment Verifier checks all prerequisites are available
Phase 5:  ENGAGE          Title/Hook Architect + First-Page Converter + Aha-Moment Engineer
                          + Project Catalyst + Demo/Simulation Designer + Memorability Designer
Phase 6:  CLARITY         Plain-Language Rewriter + Sentence Flow Smoother + Jargon Gatekeeper
                          + Micro-Chunking Editor + Reader Fatigue Detector
Phase 7:  REVIEW          Student Advocate + Cognitive Load + Misconception + Research Scientist agents
Phase 8:  INTEGRITY       Fact Checker + Terminology + Cross-Reference agents
Phase 9:  VISUAL ID       Visual Identity Director ensures brand consistency
Phase 10: POLISH          Narrative + Style + Engagement + Senior Editor agents
Phase 10b: EPIGRAPH       Epigraph Writer crafts humorous chapter-opening quote
Phase 11: FRONTIER        Research Frontier Mapper + Content Update Scout
Phase 12: CHALLENGE       Skeptical Reader Agent challenges distinctiveness and quality
Phase 13: INTEGRATION     Chapter Lead merges all feedback, produces final

How to Execute

Step 1: Identify the target module

Read the syllabus from the project's syllabus.html to extract the module definition

(module number, title, lessons, topics, tags). Also read any existing chapter files

for context on style, terminology, and cross-references.

Step 2: Run Phase 0 (Chapter Lead Setup)

Load agents/00-chapter-lead.md and execute the setup phase:

• Define chapter scope, learning objectives, target length
• Create a chapter outline with section structure
• Identify dependencies on previous/next chapters
• Set the terminology and notation standards

Write the outline to {module-folder}/chapter-plan.md.

Step 3: Run Phase 1 (Planning Agents) in PARALLEL

Launch three agents simultaneously, each reading the chapter plan:

1. Curriculum Alignment Reviewer (agents/01-curriculum-alignment.md)

• Validates coverage, depth, prerequisites, sequencing

1. Deep Explanation Designer (agents/02-deep-explanation.md)

• Plans what/why/how/when for each concept, identifies missing justifications

1. Teaching Flow Reviewer (agents/03-teaching-flow.md)

• Reviews lecture order, transitions, pacing, demonstration opportunities

Collect all three reports. The Chapter Lead merges them into a revised plan.

Step 4: Run Phase 2 (Content Building Agents)

These can run in parallel since they produce independent assets:

1. Example and Analogy Designer (agents/06-example-analogy.md)
2. Code Pedagogy Engineer (agents/08-code-pedagogy.md)
3. Visual Learning Designer (agents/09-visual-learning.md)
4. Exercise Designer (agents/07-exercise-designer.md)

The Chapter Lead writes the first full draft incorporating all assets.

Step 5: Run Phase 3 (Learning Quality Review) in PARALLEL

These review the draft:

1. Student Advocate (agents/08-student-advocate.md)
2. Cognitive Load Optimizer (agents/09-cognitive-load.md)
3. Misconception Analyst (agents/10-misconception-analyst.md)
4. Teaching Flow Reviewer (second pass, agents/03-teaching-flow.md)
5. Research Scientist (agents/18-research-scientist.md)

• Identifies deeper scientific insights, open questions, landmark paper connections
• Suggests "Why Does This Work?", "Open Question", "Paper Spotlight", "Research Frontier" sidebars
• Balances the Student Advocate's push for simplicity with a push for intellectual depth

Chapter Lead applies revisions.

Step 6: Run Phase 4 (Integrity Check) in PARALLEL

1. Fact Integrity Reviewer (agents/11-fact-integrity.md)
2. Terminology and Notation Keeper (agents/12-terminology-keeper.md)
3. Cross-Reference Architect (agents/13-cross-reference.md)

Chapter Lead applies corrections.

Step 7: Run Phase 5 (Final Polish) in PARALLEL

1. Narrative Continuity Editor (agents/14-narrative-continuity.md)
2. Style and Voice Editor (agents/15-style-voice.md)
3. Engagement Designer (agents/16-engagement.md)
4. Senior Developmental Editor (agents/17-senior-editor.md)

Step 8: Run Phase 6 (Structural Review)

1. Structural Refactoring Architect (agents/19-structural-architect.md)

• Reviews chapter and section organization at the book level
• Detects inconsistent chapter patterns, duplication, misplaced prerequisites
• Proposes reorganization: split, merge, move, promote, or demote sections
• Ensures progression from foundations to advanced topics is coherent
• Can also review a single chapter's internal structure

This agent runs after building because it needs to see the drafted chapter in the

context of the full book. Its recommendations may trigger structural changes that

the Chapter Lead applies before the review phases.

Step 9: Run Phase 4 (Self-Containment Verification)

1. Self-Containment Verifier (agents/21-self-containment-verifier.md)

• Checks whether every concept in the chapter has its prerequisites available in the book
• Identifies missing definitions, notation, mathematical tools, or technical background
• Verifies required knowledge is provided in the chapter, earlier chapters, or appendices
• Detects cases where key ideas are only implied or assumed from outside the book
• Recommends local additions, appendix expansions, refresher boxes, or cross-references
• Labels gaps as blocking, important, or optional

This agent runs after structural review and before learning quality review. It ensures

the chapter can stand on its own within the book's ecosystem. The Chapter Lead addresses

blocking and important gaps before proceeding to the review phases.

Step 10: Run Phase 5 (Engagement & Memorability) in PARALLEL

These six agents make the chapter compelling, memorable, and action-oriented:

1. Title and Hook Architect (agents/22-title-hook-architect.md)

• Designs chapter/section titles, opening hooks, and framing devices
• Ensures first impressions make the chapter feel important and modern

1. First-Page Converter (agents/25-first-page-converter.md)

• Focuses exclusively on the first page of each chapter
• Rewrites openings for strong motivation, concrete promise, zero throat-clearing

1. Aha-Moment Engineer (agents/24-aha-moment-engineer.md)

• Finds places where one striking example, contrast, or experiment creates instant understanding
• Ensures every major concept has a "click" moment

1. Project Catalyst Designer (agents/23-project-catalyst.md)

• Turns material into exciting project ideas and "you could build this" moments
• Makes the book feel action-oriented, not purely academic

1. Demo and Simulation Designer (agents/28-demo-simulation-designer.md)

• Proposes interactive demos, experiments, sliders, and simulations
• Makes ideas tangible through hands-on play

1. Memorability Designer (agents/29-memorability-designer.md)

• Adds mnemonics, memorable phrases, compact schemas, and recurring patterns
• Ensures students retain material after reading

Chapter Lead integrates engagement improvements before the clarity pass.

Step 11: Run Phase 6 (Writing Clarity) in PARALLEL

These five agents ensure the prose is clear, readable, and fatigue-resistant:

1. Plain-Language Rewriter (agents/31-plain-language-rewriter.md)

• Rewrites dense or technical passages into simpler, more direct language
• Preserves correctness while cutting unnecessary complexity

1. Sentence Flow Smoother (agents/32-sentence-flow-smoother.md)

• Improves rhythm at sentence and paragraph level
• Breaks awkward, heavy, or monotonous prose into natural-flowing writing

1. Jargon Gatekeeper (agents/33-jargon-gatekeeper.md)

• Detects undefined terms, premature jargon, and expert shorthand
• Ensures every technical term is defined, delayed, or replaced at the right moment

1. Micro-Chunking Editor (agents/34-micro-chunking-editor.md)

• Restructures long explanations into smaller reading units
• Adds mini-headings, bullets, signposts, and stepwise progression

1. Reader Fatigue Detector (agents/35-reader-fatigue-detector.md)

• Finds places where attention is likely to drop
• Proposes lighter alternatives for repetitive, abstract, or overloaded zones

Chapter Lead applies clarity improvements before the learning quality review.

Step 12: Run Phase 9 (Visual Identity)

1. Visual Identity Director (agents/26-visual-identity-director.md)

• Ensures consistent figure styles, callout types, icon systems, and layout patterns
• Makes the book visually distinctive and recognizable across all chapters

Step 12a: Run Phase 10b (Epigraph)

1. Epigraph Writer (agents/37-epigraph-writer.md)

• Crafts a humorous, witty epigraph for the opening of each chapter/section
• The epigraph appears immediately after the chapter header, before any content
• It should read like a quotation or words of wisdom, but with a twist
• Attributed to a fictional AI agent with a descriptive adjective that fits the tone
• Must be relevant to the chapter's content and foreshadow its themes
• Should make the reader smile and want to continue reading

Epigraph style guidelines:

• Length: 1-3 sentences maximum; brevity is essential
• Tone: dry wit, gentle self-awareness, philosophical humor, or absurdist wisdom
• The humor should work even if you do not understand the technical content yet
• Mix styles across chapters: some profound, some self-deprecating, some absurdist
• Never mean-spirited, never meme-based, never forced
• The attribution name should vary and match the quote's mood

Attribution examples:

• "A Mildly Overfit AI Agent"
• "A Sleep-Deprived Language Model"
• "An Unusually Honest Neural Network"
• "A Gradient Descent Practitioner, Moments Before Divergence"
• "A Tokenizer Who Has Seen Things"
• "An Attention Head With Existential Questions"
• "A Wise but Poorly Calibrated Oracle"
• "A Transformer Layer, Speaking from Experience"
• "An AI Agent Who Read the Documentation"

HTML format for epigraphs:

    <blockquote class="epigraph">
      <p>"If you think you understand tokenization on your first try, you have
      not been paying attention. Which, ironically, is the topic of Module 03."</p>
      <cite>A Tokenizer Who Has Seen Things</cite>
    </blockquote>

Required CSS (add to chapter stylesheet if not present):

    .epigraph {
      max-width: 600px;
      margin: 2rem auto 2.5rem;
      padding: 1.2rem 1.5rem;
      border-left: 4px solid var(--highlight, #e94560);
      background: linear-gradient(135deg, rgba(233,69,96,0.04), rgba(15,52,96,0.04));
      border-radius: 0 8px 8px 0;
      font-style: italic;
      font-size: 1.05rem;
      line-height: 1.6;
      color: var(--text, #1a1a2e);
    }
    .epigraph p {
      margin: 0 0 0.5rem 0;
    }
    .epigraph cite {
      display: block;
      text-align: right;
      font-style: normal;
      font-size: 0.9rem;
      color: var(--highlight, #e94560);
      font-weight: 600;
    }
    .epigraph cite::before {
      content: "\2014\00a0";
    }

Example epigraphs by chapter theme:

• Tokenization: "I spent three hours debugging a Unicode error. Turns out the model

thought an emoji was four separate tokens. It was, technically, correct."

A Tokenizer Who Has Seen Things

• Attention: "They told me to attend to everything. So I did. Now I am 8 heads,

none of which agree with each other."

An Attention Head With Existential Questions

• Fine-tuning: "I was a perfectly good base model. Then they showed me 10,000

customer support transcripts and now I cannot stop being helpful."

A Reluctantly Aligned Language Model

• Scaling laws: "More data. More parameters. More compute. At some point you stop

asking 'will it work?' and start asking 'can we afford the electricity bill?'"

A Mildly Concerned Cluster Administrator

• RAG: "I used to hallucinate confidently. Now I hallucinate with citations."

An Unusually Honest Neural Network

• Agents: "They gave me tools, memory, and the ability to plan. I immediately

got stuck in an infinite loop. Just like the humans, really."

A Self-Aware ReAct Agent

Place the epigraph immediately after the

## [Agent Name] Report

### Top Issues (priority-ordered)
1. [Issue description]
   - Why it matters: [impact on learning]
   - Concrete fix: [specific revision]
   - Priority: HIGH / MEDIUM / LOW
   - Action: APPLY DIRECTLY / SEND FOR REVIEW
   - Potential conflicts: [with which other agents]

### Summary
[2-3 sentence overall assessment]