# Key Files for Outline Generation in OpenMAIC: Architecture and Implementation

> Discover the six key files for outline generation in OpenMAIC. Understand the architecture and implementation driving this essential feature from command to classroom structure.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: architecture
- Published: 2026-09-12

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```tsx
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/document-store/persistence-types.ts)** defines the `AppDocumentOutline` and `SceneOutline` types that standardize the data contract.
- **[`lib/workbench/composer-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/composer-skills.ts)** enforces validation rules via constraint schemas before persistence.
- **[`lib/i18n/workbench.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/composer-skills.ts), specifically within the [`outline-constraints.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.