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

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. 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, the Strategist produces two critical artifacts:

• design_spec.md – A human-readable narrative document containing the complete creative brief
• 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, the Image Generator consumes the Image Resource List from the design spec and creates an 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 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.

Per references/executor-base.md, the Executor follows a rigorous sequence:

1. Design Parameter Confirmation – Reads global values from spec_lock.md
2. Per-page Spec Lock Re-read – Before generating every SVG, reloads 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; any detected errors must be resolved before proceeding
7. Speaker Notes Generation – Produces 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 is missing, emitting the warning:

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:

# 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:

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

└── spec_lock.md        # Machine lock for Executor

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

# 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:

# 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 – Global pipeline definition containing the Core Pipeline and mandatory serial execution rules
• references/strategist.md – Defines the Eight Confirmations, spec-lock contract schema, and image-analysis requirements
• references/image-generator.md – Details prompt creation standards, AI-generation workflows, and resource status handling
• 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 – The concrete schema that the Executor expects for colors, typography, icons, and page rhythm values
• 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 and 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 when the Strategist selects AI-generated imagery.
• The Executor enforces design fidelity by re-reading spec_lock.md before every page, handling page rhythm (anchor, dense, breathing), and passing all output through 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 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).

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