# How the PPT Master Multi-Role Workflow Converts Documents to PowerPoint

> Discover the PPT Master multi-role workflow: Strategist, Image Generator, and Executor. Learn how it converts documents to PowerPoint and prevents design drift.

- Repository: [HugoHe/ppt-master](https://github.com/hugohe3/ppt-master)
- Tags: how-to-guide
- Published: 2026-04-24

---

**PPT Master uses a strict, three-stage multi-role workflow where the Strategist creates immutable design specifications, the optional Image Generator produces AI visual assets, and the Executor renders final SVG slides while continuously re-reading the spec lock to prevent design drift.**

The open-source tool `hugohe3/ppt-master` automates presentation creation through a collaborative AI pipeline defined in [`skills/ppt-master/SKILL.md`](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/SKILL.md). This multi-role workflow divides the transformation process into specialized stages—Strategist, Image Generator, and Executor—ensuring that every slide adheres to pre-confirmed design parameters before visual production begins.

## The Three-Phase Multi-Role Pipeline

### Phase 1: Strategist – Blueprint and Contract Creation

The **Strategist** role serves as the architectural foundation of the multi-role workflow. It ingests raw source material—whether PDF, DOCX, URL, or Markdown—and executes the **Eight Confirmations** ritual covering canvas format, page count, audience profile, visual style, color system, icon library, typography, and image usage strategy.

According to [`references/strategist.md`](https://github.com/hugohe3/ppt-master/blob/main/references/strategist.md), the Strategist produces two critical artifacts:

- **[`design_spec.md`](https://github.com/hugohe3/ppt-master/blob/main/design_spec.md)** – A human-readable narrative document containing the complete creative brief
- **[`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md)** – A machine-readable contract that functions as an immutable execution lock

If the image-usage confirmation selects *AI generation*, the Strategist additionally runs the image-analysis script to populate the **Image Resource List**, flagging which visual assets require AI creation versus manual sourcing.

### Phase 2: Image Generator – Conditional Asset Production

The **Image Generator** role activates only when the Strategist’s Eight Confirmations specify *AI-generated* image usage. This phase bridges the gap between design specification and visual assets before the Executor begins rendering.

As defined in [`references/image-generator.md`](https://github.com/hugohe3/ppt-master/blob/main/references/image-generator.md), the Image Generator consumes the Image Resource List from the design spec and creates an **[`image_prompts.md`](https://github.com/hugohe3/ppt-master/blob/main/image_prompts.md)** document. This file contains structured generation parameters for each image, including positive prompts, negative prompts, and alt-text descriptions.

The role then orchestrates asset creation through [`scripts/image_gen.py`](https://github.com/hugohe3/ppt-master/blob/main/scripts/image_gen.py) or a host-native generator, materializing each image into `project/images/`. It updates the resource list status to either `Generated` or `Needs-Manual`, ensuring the Executor knows which assets are ready for inclusion.

### Phase 3: Executor – Visual Construction and Quality Enforcement

The **Executor** functions as the final production stage, transforming the design specification into concrete SVG pages. This role enforces strict adherence to the Strategist’s original decisions through continuous validation against [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md).

Per [`references/executor-base.md`](https://github.com/hugohe3/ppt-master/blob/main/references/executor-base.md), the Executor follows a rigorous sequence:

1. **Design Parameter Confirmation** – Reads global values from [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md)
2. **Per-page Spec Lock Re-read** – Before generating every SVG, reloads [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md) to guarantee color, font, icon, and image consistency, preventing drift on long decks
3. **Page Rhythm Application** – Interprets the `page_rhythm` tag (`anchor`, `dense`, or `breathing`) to determine layout density
4. **Template Integration** – Reads chart templates from `templates/charts/` and icons from the selected library, adapting them to the project’s locked palette
5. **Sequential SVG Generation** – Writes each page to `svg_output/` individually, avoiding batch grouping that could introduce errors
6. **Quality Gate** – Runs [`scripts/svg_quality_checker.py`](https://github.com/hugohe3/ppt-master/blob/main/scripts/svg_quality_checker.py); any detected errors must be resolved before proceeding
7. **Speaker Notes Generation** – Produces [`notes/total.md`](https://github.com/hugohe3/ppt-master/blob/main/notes/total.md) and splits it into per-page files after all SVGs pass inspection

## Strict Sequential Execution and Blocking Mechanisms

The multi-role workflow operates as a **strictly serial pipeline**—advancement to the next phase requires satisfaction of the current phase’s mandatory checkpoints. The reference files in `skills/ppt-master/references/` contain "BLOCKING" annotations that prevent premature progression.

The Executor enforces this dependency strictly: it will refuse to start if [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md) is missing, emitting the warning:

```text
warning: spec_lock.md missing — generating without execution lock

```

This blocking design ensures the Strategist’s Eight Confirmations and the Image Generator’s assets are finalized before visual construction consumes computational resources.

## Practical Implementation: Running the Pipeline

The multi-role workflow executes through specific CLI invocations from the repository root. Below are the typical commands that orchestrate the three roles.

Initialize the project and import sources:

```bash

# Create project structure

python3 skills/ppt-master/scripts/project_manager.py init my_deck --format ppt169

# Import converted markdown

python3 skills/ppt-master/scripts/project_manager.py import-sources projects/my_deck_... my_source.md --move

```

After the Strategist phase completes automatically, the project directory contains:

```text
projects/my_deck_.../
├── design_spec.md      # Human-readable spec

└── spec_lock.md        # Machine lock for Executor

```

For AI-generated images (Strategist selected option C):

```bash

# Generate image prompts and assets

python3 skills/ppt-master/scripts/analyze_images.py projects/my_deck_.../images
python3 skills/ppt-master/scripts/image_gen.py "abstract tech background, deep navy gradient" \
    --aspect_ratio 16:9 --image_size 1K \
    -o projects/my_deck_.../images --filename cover_bg

```

Execute the final construction phase:

```bash

# Quality check and SVG generation

python3 skills/ppt-master/scripts/svg_quality_checker.py projects/my_deck_...

# Finalize and convert to PowerPoint

python3 skills/ppt-master/scripts/total_md_split.py projects/my_deck_...
python3 skills/ppt-master/scripts/finalize_svg.py projects/my_deck_...
python3 skills/ppt-master/scripts/svg_to_pptx.py projects/my_deck_... -s final

```

## Key Files Controlling the Multi-Role Workflow

Several configuration files encode the collaboration logic between roles:

- **[`skills/ppt-master/SKILL.md`](https://github.com/hugohe3/ppt-master/blob/main/skills/ppt-master/SKILL.md)** – Global pipeline definition containing the Core Pipeline and mandatory serial execution rules
- **[`references/strategist.md`](https://github.com/hugohe3/ppt-master/blob/main/references/strategist.md)** – Defines the Eight Confirmations, spec-lock contract schema, and image-analysis requirements
- **[`references/image-generator.md`](https://github.com/hugohe3/ppt-master/blob/main/references/image-generator.md)** – Details prompt creation standards, AI-generation workflows, and resource status handling
- **[`references/executor-base.md`](https://github.com/hugohe3/ppt-master/blob/main/references/executor-base.md)** – Specifies per-page spec lock re-reads, page-rhythm interpretation, template mapping, and quality-gate procedures
- **[`templates/spec_lock_reference.md`](https://github.com/hugohe3/ppt-master/blob/main/templates/spec_lock_reference.md)** – The concrete schema that the Executor expects for colors, typography, icons, and page rhythm values
- **[`templates/design_spec_reference.md`](https://github.com/hugohe3/ppt-master/blob/main/templates/design_spec_reference.md)** – Guarantees Strategist output follows a known structure (sections I–XI)

## Summary

- The **multi-role workflow** divides PPT Master’s operation into three strictly sequential phases: Strategist, Image Generator, and Executor.
- The **Strategist** creates [`design_spec.md`](https://github.com/hugohe3/ppt-master/blob/main/design_spec.md) and [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md) after performing the Eight Confirmations, establishing an immutable design contract.
- The **Image Generator** runs conditionally to produce AI assets and [`image_prompts.md`](https://github.com/hugohe3/ppt-master/blob/main/image_prompts.md) when the Strategist selects AI-generated imagery.
- The **Executor** enforces design fidelity by re-reading [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md) before every page, handling page rhythm (`anchor`, `dense`, `breathing`), and passing all output through [`scripts/svg_quality_checker.py`](https://github.com/hugohe3/ppt-master/blob/main/scripts/svg_quality_checker.py).
- The pipeline uses **blocking checkpoints** to prevent phase advancement until mandatory artifacts are present.

## Frequently Asked Questions

### What happens if the Executor cannot find spec_lock.md?

The Executor emits a warning—`spec_spec.md missing — generating without execution lock`—and halts processing. The Strategist must be re-run to generate the missing lock file before visual construction can begin.

### Is the Image Generator role always required in the multi-role workflow?

No. The Image Generator activates only when the Strategist’s Eight Confirmations specify "C) AI-generated" for image usage. If the design uses manual images or stock assets, the workflow proceeds directly from Strategist to Executor.

### How does the Executor prevent design drift across long presentations?

The Executor re-reads [`spec_lock.md`](https://github.com/hugohe3/ppt-master/blob/main/spec_lock.md) before generating every individual SVG page. This per-page reload guarantees that color values, fonts, icon libraries, and image references remain consistent throughout the deck, regardless of processing duration.

### What are the Eight Confirmations performed by the Strategist?

The Strategist validates eight design parameters before producing the lock file: canvas format, page count, audience profile, visual style, color system, icon library, typography choices, and image usage strategy (manual vs. AI-generated).