The OpenMAIC Generation Process: 5 Stages to Build Interactive Classrooms

TLDR: The OpenMAIC generation process consists of five sequential stages—Outline (Stage-Design), Scene Generation, Text-to-Speech (TTS) Generation, Media Generation, and Consolidation—that transform a lesson outline into a runnable classroom using the agent-runtime skill set.

The THU-MAIC/OpenMAIC repository implements a structured pipeline for creating interactive learning environments. Understanding the OpenMAIC generation process reveals how high-level lesson plans become fully materialized classrooms with synchronized audio, visuals, and interactive elements.

The Five Stages of the OpenMAIC Generation Process

The pipeline converts a pedagogical outline into a runnable classroom through distinct, ordered stages. Each stage corresponds to a specific skill or module within the agent-runtime architecture.

Stage 1: Outline (Stage-Design) — Planning

The Outline stage determines the macro-structure of the lesson, defining milestones, titles, descriptions, and completion criteria. This blueprint drives every subsequent generation step.

According to the source code, this planning logic resides in skills/agent-runtime/stage-design/SKILL.md. The "stage-design" skill first plans and builds one stage by establishing the pedagogical framework before any visual or audio assets are created.

Stage 2: Scene Generation

For each milestone defined in the outline, the Scene Generation stage creates slide-like visual containers. This process generates layouts, text elements, shapes, and interactive widgets, persisting each scene as a JSON document under the stage.

The implementation bootstraps from lib/workbench/course-chat-bootstrap.ts, which initializes the classroom and initiates generate_scene calls. The generate_scene tool is invoked directly from the "stage-design" skill to materialize individual slides.

Stage 3: Text-to-Speech (TTS) Generation

The TTS Generation stage synthesizes narration audio for each scene, linking spoken scripts to their corresponding visual slides. This ensures synchronized audio coverage for the entire learning experience.

The lib/workbench/tts-stage-sync.ts module orchestrates this process, synchronizing TTS jobs for a stage and updating the stage's media store with the resulting audio files.

Stage 4: Media Generation (Images and Video)

Supplemental visual assets—illustrations, diagrams, and short video clips—are created during Media Generation. These assets are uploaded, versioned, and linked to specific scenes as required by the slide content.

The lib/workbench/media-lifecycle.ts module manages this lifecycle, handling upload scheduling and policy enforcement for all generated media assets.

Stage 5: Consolidation and Publication

Once all scenes and media are ready, the Consolidation stage marks the stage as generationComplete, making the classroom runnable. Final stage data persists in the IndexedDB DocumentStore and becomes available to the front-end.

The lib/workbench/stage-freshness.ts module tracks stage freshness and flips the generationComplete flag. The test suite in lib/store/stage-generation-complete.test.ts confirms this behavior, ensuring the classroom only launches when all artifacts are present.

How the Stages Orchestrate Together

The OpenMAIC generation process follows a strict sequence: Outline → Scene Generation → TTS → Media → Consolidation.

The agent-runtime skill set orchestrates this flow. The stage-design skill first plans the outline, then drives a sequence of generate_scene calls. After each slide materializes, tts-stage-sync runs TTS jobs while media-lifecycle handles visual assets. Finally, stage-freshness validates completion and marks the stage runnable.

Implementation Examples

Below are practical TypeScript snippets demonstrating how to trigger each stage using the OpenMAIC SDK. These correspond to the source files implementing each phase.

// 1. Outline – create a new stage (outline only)
await createStage({
  title: "Python Basics – 7-Day Course",
  milestones: [
    { 
      title: "Day 1 — Variables", 
      description: "Introduce variables.", 
      completionCriteria: "Learner writes a variable." 
    },
    // …more milestones
  ],
});

// 2. Scene generation – generate a scene for a given milestone
await generateScene({
  stageId,
  milestoneIndex: 0,
  brief: "Explain Python variables with a simple example.",
});

// 3. TTS generation – synthesize narration for the scene
await generateTTS({
  stageId,
  sceneId,
  script: "In Python, a variable stores data …",
});

// 4. Media generation – add an image to the scene
await generateImage({
  stageId,
  sceneId,
  prompt: "A colorful illustration of a Python variable bag.",
});

// 5. Consolidation – mark the stage as generation-complete
await finalizeStage({ stageId });

Summary

• The OpenMAIC generation process transforms lesson outlines into interactive classrooms through five distinct stages.
• Stage-design (skills/agent-runtime/stage-design/SKILL.md) handles macro-planning and milestone definition.
• Scene generation (lib/workbench/course-chat-bootstrap.ts) creates visual slide structures as JSON documents.
• TTS generation (lib/workbench/tts-stage-sync.ts) synthesizes and synchronizes narration audio for each scene.
• Media generation (lib/workbench/media-lifecycle.ts) produces and manages supplemental images and video.
• Consolidation (lib/workbench/stage-freshness.ts) validates completion and sets the generationComplete flag, persisting data to DocumentStore.

Frequently Asked Questions

What triggers the OpenMAIC generation process?

The process initiates when the stage-design skill receives a request to build a new classroom. This skill, defined in skills/agent-runtime/stage-design/SKILL.md, first creates the pedagogical outline, then automatically triggers the downstream scene generation, TTS, and media stages through the agent-runtime orchestrator.

How does the system ensure all stages complete before publication?

The stage-freshness.ts module tracks the state of each artifact in the pipeline. It monitors the media store for pending uploads and verifies that all scenes have associated TTS and media assets. Only when every dependency is satisfied does it flip the generationComplete flag, as validated by the test suite in stage-generation-complete.test.ts.

Can individual stages be regenerated without rebuilding the entire classroom?

Yes. Each stage operates on distinct resources with specific IDs. You can target generateScene for specific milestones, rerun generateTTS for individual scenes, or invoke generateImage to update media assets. The stage-freshness module detects these changes and updates the completion status accordingly without requiring a full pipeline restart.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}