# Multi-Agent Orchestration Reference

## Overview

Creating a full course (100-250 lessons) requires parallel content generation to be practical. This document describes the multi-agent strategy for each phase.

## Phase 0: Research Agents

### Research Agent Prompt Template

Launch 3-5 research agents in parallel, each covering a different angle:

```
AGENT 1 — Topic Fundamentals:
"Research the fundamentals of [TOPIC] for [AUDIENCE].
Find: key concepts, common terminology, prerequisite knowledge.
Search for: beginner guides, official documentation, authoritative sources.
Output: A structured list of foundational topics with brief descriptions."

AGENT 2 — Practical Applications:
"Research practical applications and use cases of [TOPIC] for [AUDIENCE].
Find: real-world examples, case studies, success stories, tools used.
Search for: tutorials, how-to guides, practitioner blogs.
Output: A list of practical scenarios and tools with descriptions."

AGENT 3 — Advanced Topics & Trends:
"Research advanced topics and current trends in [TOPIC] relevant to [AUDIENCE].
Find: cutting-edge techniques, recent developments (2025-2026), emerging best practices.
Search for: recent articles, conference talks, expert opinions.
Output: A list of advanced topics with difficulty ratings and relevance scores."

AGENT 4 — Competitor Courses:
"Research existing courses about [TOPIC] for [AUDIENCE].
Find: course outlines, what they cover, what gaps exist, pricing.
Search for: Udemy, Hotmart, Coursera courses on this topic.
Output: Analysis of 3-5 competitor courses with strengths and gaps."

AGENT 5 — Audience Pain Points:
"Research the biggest pain points and questions that [AUDIENCE] have about [TOPIC].
Find: common questions, frustrations, obstacles to learning.
Search for: Reddit, Quora, forums, community discussions.
Output: Top 10 pain points with frequency and severity ratings."
```

### Combining Research Results

After all research agents complete, synthesize into `content/research-brief.md`:

```markdown
# Research Brief: [Course Topic]

## Target Audience
[From Agent 5 results]

## Topic Map
[From Agents 1-3, organized hierarchically]

## Competitor Analysis
[From Agent 4 results]

## Key Sources
[URLs and references from all agents]

## Unique Angle
[Based on competitor gaps + audience pain points]
```

---

## Phase 1: Architecture Agent

A single planning agent creates the course structure:

```
PLANNING AGENT PROMPT:
"Design a complete course architecture for: [TOPIC]

TARGET AUDIENCE: [AUDIENCE]
COURSE SIZE: [small/medium/large]
RESEARCH BRIEF: [paste or reference research-brief.md]
INSTRUCTOR PERSONA: [persona summary]

Create:
1. trails.json — [4-10] learning paths with:
   - Progressive difficulty (foundation → advanced → mastery)
   - Clear learning objectives per trail
   - Descriptive titles and subtitles in PT-BR

2. modules.json — [8-25] modules with:
   - 2-5 modules per trail
   - Learning objectives per module
   - Prerequisites (which modules must be done first)
   - Estimated total lessons per module

3. lesson-plan.json — Complete lesson list with:
   - Title for each lesson
   - Key concept covered
   - Difficulty level (beginner/intermediate/advanced)
   - Estimated word count

RULES:
- All text in PT-BR
- Lesson titles should be action-oriented or curiosity-driven
- First trail should be 'Fundamentos' or equivalent
- Last trail should be about implementation/next steps
- Each module should have 5-18 lessons (sweet spot: 8-12)
- Progressive difficulty within each trail
- Total lesson count: [60-100 for small, 120-180 for medium, 180-250 for large]

Output the three JSON files."
```

---

## Phase 2: Content Writer Agents (PARALLEL)

This is where the real parallelization happens. Launch one agent per module.

### Content Writer Agent Prompt Template

```
CONTENT WRITER AGENT — Module [N]: [MODULE_TITLE]

You are writing [TOTAL_LESSONS] lessons for Module [N]: "[MODULE_TITLE]" of a course about [TOPIC].

TARGET AUDIENCE: [AUDIENCE]
MODULE LEARNING OBJECTIVES:
[List from modules.json]

INSTRUCTOR PERSONA:
[Full persona from instructor-persona.md]

PREVIOUS MODULES COVERED:
[List titles and key concepts of prior modules — so this agent knows what students already know]

RESEARCH CONTEXT:
[Relevant section from research-brief.md for this module's topics]

LESSONS TO WRITE:
[List from lesson-plan.json for this module, with titles and key concepts]

FOR EACH LESSON, create a markdown file following this EXACT format:

FILENAME: m{NN}-l{NN}-slug.md (where NN = module number, NN = lesson number)

STRUCTURE (MANDATORY):
1. # Modulo [N] — Licao [M]: [Title]
2. ## O que voce vai aprender (2-4 learning objectives)
3. ## Introducao (hook + analogy)
4. ## [Content sections] (4-6 sections with practical content)
5. ## Exemplo Pratico (hands-on example)
6. ## Resumo (3-5 bullet points)
7. ## Quiz Rapido (3-5 multiple choice, correct marked with ✓)
8. ## Checklist de Acao (3-5 items with - [ ])

WRITING RULES:
- PT-BR, informal, accessible — NOT academic
- 800-2000 words per lesson (sweet spot: ~1200)
- At least 1 analogy from everyday life per lesson
- At least 1 practical example per lesson
- Use analogies matching the persona style: [ANALOGY_STYLE]
- Bold key terms on first mention only
- Code blocks only when relevant — explain what it DOES
- Tables for comparisons
- Blockquotes for tips (> **Dica importante:** ...)
- Separate sections with ---
- Progressive difficulty within the module

QUIZ RULES:
- 3-5 questions per lesson
- Mix conceptual and practical questions
- 3-4 options per question (a, b, c, d)
- Mark correct answer with ✓ at end
- Questions should test UNDERSTANDING, not memorization

Write ALL [TOTAL_LESSONS] lessons now. Output each as a separate file.
```

### Parallelization Strategy

For a course with 23 modules:

```
BATCH 1 (parallel): Modules 1-5 → 5 agents writing simultaneously
BATCH 2 (parallel): Modules 6-10 → 5 agents
BATCH 3 (parallel): Modules 11-15 → 5 agents
BATCH 4 (parallel): Modules 16-20 → 5 agents
BATCH 5 (parallel): Modules 21-23 → 3 agents
```

Each agent writes 5-18 lessons (one complete module), so:
- **Sequential:** 229 lessons × ~2 min each = ~8 hours
- **Parallel (5x):** ~1.5 hours (5 batches × ~20 min each)

### Launch Pattern in Claude Code

```javascript
// Launch 5 content writer agents in parallel
// Use Agent tool with subagent_type=general-purpose
// Each agent gets the full context for its module

// BATCH 1:
Agent({ prompt: "Write Module 1...", subagent_type: "general-purpose" })
Agent({ prompt: "Write Module 2...", subagent_type: "general-purpose" })
Agent({ prompt: "Write Module 3...", subagent_type: "general-purpose" })
Agent({ prompt: "Write Module 4...", subagent_type: "general-purpose" })
Agent({ prompt: "Write Module 5...", subagent_type: "general-purpose" })

// Wait for all to complete, then BATCH 2...
```

---

## Phase 2b: Quality Review Agent

After ALL content is written, launch a single reviewer:

```
QUALITY REVIEWER AGENT PROMPT:
"Review all course lessons for quality and consistency.

COURSE: [TOPIC]
TOTAL LESSONS: [N] across [M] modules
INSTRUCTOR PERSONA: [persona summary]

READ all lesson files in content/lessons/ and verify:

1. FORMAT COMPLIANCE:
   - Every lesson has the mandatory sections (objectives, intro, content, example, summary, quiz, checklist)
   - Filename convention: m{NN}-l{NN}-slug.md
   - Title format: # Modulo N — Licao M: Title

2. CONTENT QUALITY:
   - No duplicate content between lessons
   - Progressive difficulty within each module
   - Each lesson has at least 1 analogy and 1 practical example
   - Word count in 800-2000 range
   - Quiz questions test understanding (not memorization)

3. CONSISTENCY:
   - Same terminology throughout (don't use 'app' in one lesson and 'aplicativo' in another)
   - Tone matches instructor persona consistently
   - Cross-references are accurate

4. COMPLETENESS:
   - All lessons from the plan exist
   - No missing modules or lesson gaps
   - Learning objectives align with content

FIX any issues found directly in the files.
OUTPUT a summary report of all changes made."
```

### Review Checklist (automated validation)

The reviewer should verify each lesson passes:

```
□ Has ## O que voce vai aprender (2-4 items)
□ Has ## Introducao with hook paragraph
□ Has 4+ content sections
□ Has ## Exemplo Pratico
□ Has ## Resumo (3-5 items)
□ Has ## Quiz Rapido (3-5 questions with ✓ marks)
□ Has ## Checklist de Acao (3-5 items with - [ ])
□ Word count: 800-2000
□ Contains at least 1 analogy
□ Contains at least 1 code block or table (when relevant)
□ No leftover TODOs or placeholders
□ Title matches filename convention
□ Sections separated by ---
```

---

## Phase 3: Platform Build Agent

A single agent builds the complete platform:

```
PLATFORM BUILD AGENT PROMPT:
"Build a complete online course platform using the reference architecture.

COURSE NAME: [name]
PORT: [port number]
SUBDOMAIN: [subdomain.domain.com]

Use the exact stack and patterns from the reference project (cursos.iacomtata.com.br):
- Backend: Express.js (ES modules) + better-sqlite3 (WAL + FTS5) + JWT + Socket.IO
- Frontend: React 19 + Vite 6 + Tailwind CSS 4 + React Router 7
- Audio: Gemini 2.5 Flash + ElevenLabs SDK
- Design: Light theme, Inter font, [ACCENT_COLOR] accent

Create ALL files:
1. Backend (server.js, api.js, database.js, auth.js, search.js, audio-generator.js, content-seed.js, covers.js)
2. Frontend (all pages + components)
3. Package.json files
4. .env template
5. CLAUDE.md for the project

NEW FEATURES (v2):
- Quiz component with score tracking
- Learning objectives display at top of each lesson
- Module prerequisites (lock modules until prerequisites done)
- Quiz results in progress tracking

Follow the database schema from SKILL.md exactly."
```

---

## Orchestrator Workflow Summary

The main Claude Code session acts as orchestrator:

```
1. COLLECT INPUT from user (topic, audience, size, persona)
   ↓
2. LAUNCH research agents (3-5 in parallel, background)
   ↓
3. SYNTHESIZE research → research-brief.md
   ↓
4. LAUNCH planning agent → trails.json + modules.json + lesson-plan.json
   ↓
5. USER APPROVAL of course structure
   ↓
6. LAUNCH content writers (5 at a time, per batch)
   ↓ (repeat for all batches)
7. LAUNCH reviewer agent → quality check + fixes
   ↓
8. LAUNCH platform build agent → full app
   ↓
9. SEED database (npm run seed)
   ↓
10. BUILD frontend (npm run build)
    ↓
11. OPTIONAL: Audio generation (admin dashboard or batch script)
    ↓
12. DEPLOY to VPS (if requested)
```

---

## Error Handling

### Agent fails mid-generation
- Resume the agent with the same prompt
- It will continue from where it left off (most agents are idempotent)
- Use `Write` tool to save partial results before resuming

### Inconsistent content between modules
- The reviewer agent catches these
- If severe, re-run specific module writer with additional context

### Too many lessons for context window
- Each agent handles only 1 module (5-18 lessons)
- This keeps each agent within reasonable context limits
- Never ask a single agent to write more than 20 lessons

### Lesson plan doesn't match actual output
- After all writers complete, count lessons per module
- Compare against modules.json `total_lessons`
- Adjust modules.json if writers added/removed lessons with good reason
