Key Files for Outline Generation in OpenMAIC: Architecture and Implementation

The outline generation pipeline in OpenMAIC relies on six core files across the server runtime, document store, and workbench client to transform a generate_outline command into a persisted classroom structure.

OpenMAIC implements classroom outline generation through a coordinated multi-stage pipeline defined in the THU-MAIC/OpenMAIC repository. The system translates user requests into structured scene hierarchies using server-side tool orchestration and client-side state persistence. Understanding these key files reveals how the application bridges AI planning with durable storage and reactive UI updates.

The Three-Stage Outline Generation Pipeline

Stage 1: Planning and Tool Mapping in course-tools.ts

When a user initiates outline generation, the agent runtime intercepts the legacy generate_outline command and translates it into a modern conversation plan. This logic resides in lib/server/agent-runtime/course-tools.ts, which maps the tool name to a workflow that creates a stage and generates one scene per page.

The file defines the DSL_TOOLS_PROMPT constant that instructs the LLM how to handle the command:

// Server-side: How generate_outline is mapped (excerpt from course-tools.ts)
export const DSL_TOOLS_PROMPT = [
  // …snip…
  'generate_outline → (plan in conversation, then create_stage + one generate_scene per page with an explicit brief);',
].join(' ');

This mapping ensures the agent first plans the conversation context, then executes create_stage followed by multiple generate_scene calls—one for each intended page in the classroom outline.

Stage 2: Merging and Persistence in curriculum-tools.ts

Once the agent generates individual scene outlines, the system must merge them with any existing outline data and persist the result. The lib/server/agent-runtime/curriculum-tools.ts file contains the mergeStageOutline function that handles this operation.

The function performs ownership checks, resolves conflicts between new and existing SceneOutline arrays, and writes the final envelope to the persistence layer:

// Merging a new outline with any existing data (excerpt from curriculum-tools.ts)
export async function mergeStageOutline(
  stageId: string,
  newOutlines: SceneOutline[],
  deps: CurriculumToolDeps,
) {
  const existing = await deps.store.getOutline(stageId);
  const merged = [...(existing?.outlines ?? []), ...newOutlines];
  await deps.store.saveOutline(stageId, { outlines: merged, generationComplete: true });
}

This approach allows incremental updates to classroom structures without overwriting previously generated content.

Stage 3: Client-Side Consumption via use-workbench-session.ts

The front-end workbench accesses the persisted outline through the useWorkBenchSession hook located in lib/workbench/use-workbench-session.ts. This React hook loads the outline data into the session store and drives UI components including the outline rail, page list, and checkpoint handlers.

Client components dispatch actions to trigger server-side generation:

// Example: Trigger outline generation from the workbench UI
import { useWorkBenchSession } from '@/lib/workbench/use-workbench-session';

function GenerateOutlineButton() {
  const { dispatch } = useWorkBenchSession();

  const startOutline = async () => {
    // Calls the server-side tool which creates a stage + scenes
    await dispatch({ tool: 'generate_outline', params: {} });
  };

  return <button onClick={startOutline}>Plan Classroom</button>;
}

The hook maintains synchronization between the server-side state and the reactive UI, ensuring the outline rail updates immediately when generationComplete is set to true.

Data Structures and Validation

Persistence Types in persistence-types.ts

The lib/document-store/persistence-types.ts file defines the AppDocumentOutline interface, which specifies the JSON shape used for durable storage. This type comprises an array of SceneOutline objects plus metadata fields including generation status and timestamps.

This contract ensures type safety across the boundary between the agent runtime and the document store.

Outline Constraints in composer-skills.ts

Before committing outlines to storage, OpenMAIC validates them against a schema defined in lib/workbench/composer-skills.ts. This module contains outline-constraints.json, which enforces structural rules such as required fields per scene, maximum outline depth, and valid page type enumerations.

These constraints prevent malformed outlines from entering the persistence layer and ensure consistency across different generation sessions.

Localization in i18n/workbench.ts

Human-readable labels, button text, and error messages for the outline generation interface are centralized in lib/i18n/workbench.ts. This separation allows the system to render localized strings for success confirmations (e.g., "Outline generated successfully") and failure states (e.g., "Failed to merge stage outline") without modifying the core logic.

Summary

• lib/server/agent-runtime/course-tools.ts maps the generate_outline command to a modern planning workflow involving stage creation and scene generation.
• lib/server/agent-runtime/curriculum-tools.ts handles outline merging through mergeStageOutline, performing ownership checks and atomic updates to the document store.
• lib/workbench/use-workbench-session.ts provides the client-side hook that triggers generation, receives updates, and hydrates the UI with outline data.
• lib/document-store/persistence-types.ts defines the AppDocumentOutline and SceneOutline types that standardize the data contract.
• lib/workbench/composer-skills.ts enforces validation rules via constraint schemas before persistence.
• lib/i18n/workbench.ts supplies localized strings for all user-facing outline generation messages.

Frequently Asked Questions

What triggers outline generation in OpenMAIC?

Outline generation begins when a client component dispatches the generate_outline tool action through the useWorkBenchSession hook. This dispatch sends a request to the server-side agent runtime, which interprets the command according to the mapping defined in course-tools.ts and initiates the planning workflow.

How does OpenMAIC handle existing outlines when generating new content?

The system uses the mergeStageOutline function in curriculum-tools.ts to combine newly generated scene arrays with existing outline data. The function retrieves the current outline via deps.store.getOutline, spreads the existing and new arrays together, and saves the merged result, preserving previous work while appending new pages.

What data structure stores the generated outline?

The outline persists as an AppDocumentOutline object defined in persistence-types.ts. This structure contains an outlines array of SceneOutline objects, each with properties for order, title, and type, along with metadata flags like generationComplete that signal the UI to update.

Where are outline validation rules defined in OpenMAIC?

Validation constraints reside in lib/workbench/composer-skills.ts, specifically within the outline-constraints.json schema. This file validates generated outlines before they reach the persistence layer, ensuring all required fields are present and page hierarchies meet structural requirements.

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