claude-code-skills-reference/ppt-creator/references/ORCHESTRATION_PPTX.md

ORCHESTRATION_PPTX.md

Purpose: Comprehensive specifications for Stage 8d (Dual-Path PPTX Creation) and Stage 8e (Chart Insertion) in orchestration mode.

Navigation: ← Back to Overview | ← Data & Charts

Note: This is a comprehensive reference (650 lines) covering both Marp CLI and document-skills:pptx paths with complete implementation details, quality gates, error handling, and examples.

---

Stage 8d: Dual-Path PPTX Creation (Parallel Execution)

Strategy: Launch TWO parallel sub-agents to generate PPTX files using different technologies. This preserves existing Marp capabilities while adding document-skills:pptx support.

Why Dual-Path?

Problem: ppt-creator internally uses Marp-formatted Markdown (with Marp-specific YAML frontmatter and directives), but document-skills:pptx uses reveal.js/HTML and cannot properly parse Marp syntax.

Solution: Support BOTH paths simultaneously:

• Path A (Marp CLI): Native Marp export → preserves Marp themes, directives, and styling
• Path B (document-skills:pptx): Strip Marp directives → convert to PowerPoint → reveal.js-style output

Both paths run in parallel (single message with two Task calls), delivering whichever succeeds (or both for user choice).

---

Path A: Marp CLI Export

Purpose: Export slides.md to PPTX using official Marp CLI, preserving native Marp styling

Task Invocation:

Tool: Task
subagent_type: general-purpose
description: Marp CLI PPTX generation
prompt: |
  Generate PPTX from Marp-formatted slides using Marp CLI.

  CRITICAL: This path preserves Marp-specific features (themes, directives, styling).

  Steps:
  1. Check Marp CLI installation:
     which marp || npm list -g @marp-team/marp-cli

  2. If Marp CLI not found, install it:
     npm install -g @marp-team/marp-cli

     If npm fails:
     - Try: brew install marp-cli (macOS)
     - Document error and skip to fallback

  3. Export slides.md to PPTX:
     cd output
     marp slides.md -o presentation_marp.pptx --allow-local-files --html

     Options explained:
     - --allow-local-files: Enable chart image embedding
     - --html: Preserve HTML directives (speaker notes)

  4. Quality checks:
     - File exists: /output/presentation_marp.pptx
     - File size: 200-500KB (12-15 slides with embedded fonts)
     - No "ERROR" in marp output

  5. If successful, report:
     "✓ Path A complete: presentation_marp.pptx (Marp-styled, [FILE_SIZE]KB)"

  Fallback: If any step fails, document error in /output/README.md and exit gracefully

Expected Output:

• File: /output/presentation_marp.pptx (~200-500KB)
• Styling: Marp theme from YAML frontmatter (e.g., theme: default, custom CSS)
• Charts: Text placeholders initially (will be replaced in Stage 8e-A)
• Notes: Speaker notes from <!-- NOTES: ... --> comments
• Font embedding: Marp auto-embeds fonts

Marp Installation Verification:

# Check if Marp CLI is available
which marp
# OR
npm list -g @marp-team/marp-cli

# Expected output:
/usr/local/bin/marp
# OR
@marp-team/marp-cli@3.x.x

Installation Methods (if not found):

# Method 1: npm (preferred)
npm install -g @marp-team/marp-cli

# Method 2: Homebrew (macOS)
brew install marp-cli

# Method 3: Docker (fallback)
docker run --rm -v ${PWD}:/workspace marpteam/marp-cli slides.md -o presentation_marp.pptx

Common Marp Errors & Fixes:

Error	Cause	Fix
marp: command not found	Marp CLI not installed	Run npm install -g @marp-team/marp-cli
EACCES permission error	npm global directory not writable	Use sudo or fix npm permissions
Cannot find module	Incomplete installation	Reinstall: npm uninstall -g @marp-team/marp-cli && npm install -g @marp-team/marp-cli
Image embedding fails	Missing --allow-local-files	Add flag: marp slides.md -o out.pptx --allow-local-files

Fallback: If Marp CLI unavailable after installation attempts:

• Skip Path A
• Document in /output/README.md: "Marp CLI unavailable, delivered document-skills:pptx version only"
• Proceed with Path B only

---

Path B: document-skills:pptx Export

Purpose: Convert Markdown to PPTX using Anthropic's official PowerPoint skill (reveal.js-based)

Pre-Processing Required: Since slides.md contains Marp-specific syntax, we must strip it before passing to document-skills:pptx:

Marp Syntax to Remove:

---
marp: true
theme: default
paginate: true
---

<!-- _class: lead -->
<!-- _backgroundColor: #f4f4f4 -->

Task Invocation:

Tool: Task
subagent_type: general-purpose (with document-skills:pptx access)
description: document-skills:pptx PPTX generation
prompt: |
  Use document-skills:pptx skill to create PowerPoint from slides.md content.

  CRITICAL: Pre-process slides.md to remove Marp-specific syntax.

  Steps:
  1. Read /output/slides.md content

  2. Pre-process content (remove Marp syntax):
     - Remove YAML frontmatter block (--- ... ---)
     - Remove HTML comments with Marp directives: <!-- _class: ... -->, <!-- _backgroundColor: ... -->
     - Keep speaker notes: <!-- NOTES: ... --> (convert to PowerPoint notes)
     - Keep standard Markdown: #, ##, bullets, bold, italics

  3. Convert to document-skills:pptx compatible format:
     - # → Title slide
     - ## → Content slide heading (large, bold)
     - ### → Subheading (if used)
     - Bullet points → PowerPoint bullet lists
     - **[占位图表]**: description → Text box placeholder "[CHART: description]"

  4. Create PPTX using document-skills:pptx:
     - File: /output/presentation_pptx.pptx
     - Layout: 16:9 (default)
     - Theme: document-skills default (reveal.js-based)
     - Embed speaker notes from <!-- NOTES: ... -->

  5. Quality checks:
     - File exists: /output/presentation_pptx.pptx
     - Slide count matches slides.md (±1 acceptable)
     - No Markdown artifacts visible (no "---", no "<!-- -->")
     - Headings rendered correctly

  6. If successful, report:
     "✓ Path B complete: presentation_pptx.pptx (document-skills styled, [FILE_SIZE]KB)"

  Fallback: If document-skills:pptx unavailable, document in README.md and exit gracefully

Expected Output:

• File: /output/presentation_pptx.pptx (~200-300KB)
• Styling: document-skills:pptx default theme (reveal.js-based, clean/modern)
• Charts: Text placeholders initially (will be replaced in Stage 8e-B)
• Notes: Speaker notes embedded in PowerPoint notes section
• Font: System defaults (Calibri/Arial)

Fallback: If document-skills:pptx unavailable:

• Skip Path B
• Document in /output/README.md: "document-skills:pptx unavailable, delivered Marp version only"
• Proceed with Path A only

---

Parallel Execution Pattern

Implementation: Use a single message with TWO Task tool calls to execute both paths simultaneously.

Pseudo-code:

# In ppt-creator's response, invoke BOTH agents at once:

1. Call Task tool with Path A prompt (Marp CLI)
2. Call Task tool with Path B prompt (document-skills:pptx)

Both agents run in parallel (non-blocking).

Wait for both to complete, then:
- If both succeed → deliver both PPTX files
- If one succeeds → deliver that one + document other's failure
- If both fail → fallback to Markdown + conversion instructions

User Communication:

🎯 Launching dual-path PPTX generation in parallel...

Path A: Marp CLI → presentation_marp.pptx (native Marp styling)
Path B: document-skills:pptx → presentation_pptx.pptx (reveal.js styling)

Estimated time: 2-3 minutes (parallel execution)

---

Quality Checks for Stage 8d

After both paths complete, verify:

Path A (Marp) Success Criteria:

• ✓ File exists: /output/presentation_marp.pptx
• ✓ File size: 200-500KB (fonts embedded, reasonable size)
• ✓ Slide count: 12-15 slides (matches slides.md)
• ✓ No error logs from Marp CLI

Path B (document-skills:pptx) Success Criteria:

• ✓ File exists: /output/presentation_pptx.pptx
• ✓ File size: 200-300KB
• ✓ Slide count: matches slides.md (±1 slide acceptable)
• ✓ No Markdown artifacts visible

Delivery Matrix:

Path A	Path B	Delivery
✓ Success	✓ Success	Both PPTX files (user chooses preferred styling)
✓ Success	✗ Fail	presentation_marp.pptx + README note about Path B failure
✗ Fail	✓ Success	presentation_pptx.pptx + README note about Path A failure
✗ Fail	✗ Fail	Markdown only + pandoc conversion command in README

---

Stage 8e: Dual-Path Chart Insertion (Parallel Execution)

Strategy: Insert generated PNG charts into BOTH PPTX files (if both exist) using path-specific methods.

Chart-to-Slide Mapping

Common Mapping Strategy (applies to both paths):

1. Parse slides.md to identify chart placeholders:
   • Pattern: **[占位图表]**: or **[Chart]**:
2. Extract chart filename from placeholder description
3. Map to slide number (skip title/TOC, typically start from slide 3)

Example Mapping:

chart_mapping = [
    {"slide": 3, "chart": "assets/cost_trend.png", "title_contains": "成本"},
    {"slide": 4, "chart": "assets/capacity_growth.png", "title_contains": "装机容量"},
    {"slide": 5, "chart": "assets/employment.png", "title_contains": "就业"},
    # ... (8 charts total)
]

Positioning Guidelines:

• Standard layout: Right column at (5.5", 2.0") from top-left corner
• Width: 4.0" (leaves 0.5" right margin on 10" slide width)
• Height: Auto (maintain aspect ratio from 10×6 inch source)
• Alternative: Full-width charts at (1.0", 2.5"), width 8.0"

---

Path A: Marp PPTX Chart Insertion

Method: Use python-pptx library to directly manipulate presentation_marp.pptx

Task Invocation:

Tool: Task
subagent_type: general-purpose
description: Insert charts into Marp PPTX
prompt: |
  Insert PNG charts into presentation_marp.pptx using python-pptx library.

  Steps:
  1. Check python-pptx availability:
     python3 -c "import pptx; print(pptx.__version__)"

     If not found: uv pip install python-pptx

  2. Create insertion script (insert_charts_marp.py):
     ```python
     from pptx import Presentation
     from pptx.util import Inches

     prs = Presentation('output/presentation_marp.pptx')

     chart_mapping = [
         (2, 'output/assets/cost_trend.png'),      # Slide 3 (0-indexed: 2)
         (3, 'output/assets/capacity_growth.png'),
         (4, 'output/assets/employment.png'),
         # ... (all 8 charts)
     ]

     for slide_idx, chart_path in chart_mapping:
         slide = prs.slides[slide_idx]
         # Position: right column, 5.5" from left, 2.0" from top, 4.0" wide
         slide.shapes.add_picture(
             chart_path,
             Inches(5.5),
             Inches(2.0),
             width=Inches(4.0)
         )
         print(f"✓ Inserted {chart_path} into slide {slide_idx + 1}")

     prs.save('output/presentation_marp_with_charts.pptx')
     print("✅ Final Marp PPTX: presentation_marp_with_charts.pptx")
     ```

  3. Execute script:
     cd .
     python3 output/insert_charts_marp.py

  4. Quality checks:
     - File exists: /output/presentation_marp_with_charts.pptx
     - File size increase: +300-600KB (charts embedded)
     - All 8 charts inserted without errors

  5. Report:
     "✓ Path A charts inserted: presentation_marp_with_charts.pptx ([FINAL_SIZE]KB)"

  Fallback: If python-pptx fails, deliver presentation_marp.pptx + manual insertion instructions

Expected Output:

• File: /output/presentation_marp_with_charts.pptx (500-900KB)
• Charts: All 8 PNG images embedded at correct positions
• Styling: Marp theme preserved
• Quality: Charts readable, no overlapping text

---

Path B: document-skills:pptx Chart Insertion

Method: Use document-skills:pptx editing capabilities via Task tool

Task Invocation:

Tool: Task
subagent_type: general-purpose (with document-skills:pptx access)
description: Insert charts into document-skills PPTX
prompt: |
  Use document-skills:pptx to insert chart images into presentation_pptx.pptx.

  Chart mapping (insert in order):
  1. Slide 3: Insert /output/assets/cost_trend.png at position (5.5", 2.0"), width 4.0"
  2. Slide 4: Insert /output/assets/capacity_growth.png at position (5.5", 2.0"), width 4.0"
  3. Slide 5: Insert /output/assets/employment.png at position (5.5", 2.0"), width 4.0"
  4. Slide 6: Insert /output/assets/solar_roi.png at position (5.5", 2.0"), width 4.0"
  5. Slide 7: Insert /output/assets/health_impact.png at position (5.5", 2.0"), width 4.0"
  6. Slide 8: Insert /output/assets/emissions_reduction.png at position (5.5", 2.0"), width 4.0"
  7. Slide 9: Insert /output/assets/cost_parity.png at position (5.5", 2.0"), width 4.0"
  8. Slide 10: Insert /output/assets/future_projection.png at position (5.5", 2.0"), width 4.0"

  Actions for each chart:
  - Open: /output/presentation_pptx.pptx
  - Navigate to slide N
  - Delete placeholder text box (if exists with "[CHART:" text)
  - Insert chart image at specified position (5.5" left, 2.0" top, 4.0" width)
  - Maintain aspect ratio (auto-height)

  Save as: /output/presentation_pptx_with_charts.pptx

  Quality checks:
  - All 8 charts inserted successfully
  - No overlapping content (check visually)
  - File size increase: 300-600KB (charts embedded)

  Report:
  "✓ Path B charts inserted: presentation_pptx_with_charts.pptx ([FINAL_SIZE]KB)"

  Fallback: If document-skills:pptx unavailable, use python-pptx fallback (same as Path A method)

Expected Output:

• File: /output/presentation_pptx_with_charts.pptx (500-800KB)
• Charts: All 8 PNG images embedded
• Styling: document-skills theme preserved
• Quality: Charts readable, professional layout

---

Parallel Execution Pattern for Chart Insertion

Implementation: Launch both chart insertion tasks in parallel (if both PPTX files exist from Stage 8d).

Decision Logic:

If presentation_marp.pptx exists:
  → Launch Path A chart insertion task

If presentation_pptx.pptx exists:
  → Launch Path B chart insertion task

If both exist:
  → Launch BOTH tasks in parallel (single message with two Task calls)

If neither exist:
  → Skip Stage 8e, deliver Markdown + charts + assembly instructions

---

Quality Checks for Stage 8e

Path A (Marp) Final Checks:

• ✓ File exists: /output/presentation_marp_with_charts.pptx
• ✓ File size: 500-900KB (base PPTX + charts)
• ✓ All 8 charts visible when opening in PowerPoint/Keynote
• ✓ No overlapping text or broken layouts
• ✓ Charts maintain aspect ratio and readability

Path B (document-skills:pptx) Final Checks:

• ✓ File exists: /output/presentation_pptx_with_charts.pptx
• ✓ File size: 500-800KB
• ✓ All 8 charts visible and positioned correctly
• ✓ Theme styling preserved
• ✓ Speaker notes still present

Final Delivery Matrix:

Path A 8e	Path B 8e	Final Deliverables
✓ Success	✓ Success	Both complete PPTX (presentation_marp_with_charts.pptx + presentation_pptx_with_charts.pptx)
✓ Success	✗ Fail	presentation_marp_with_charts.pptx + presentation_pptx.pptx (no charts) + manual instructions
✗ Fail	✓ Success	presentation_pptx_with_charts.pptx + presentation_marp.pptx (no charts) + manual instructions
✗ Fail	✗ Fail	Both base PPTX + charts folder + manual insertion guide in README

---

User Communication After Stage 8e

Success (Both Paths):

✅ Dual-path orchestration complete!

📦 Deliverables:
  - presentation_marp_with_charts.pptx (557KB, Marp-styled)
  - presentation_pptx_with_charts.pptx (543KB, document-skills styled)

Both files contain:
  ✓ 14 slides with complete content
  ✓ 8 real data-driven charts (180 DPI)
  ✓ Speaker notes for each slide
  ✓ Professional styling and layout

Choose your preferred version or compare both!

Partial Success (One Path):

✅ Orchestration complete (partial success)

📦 Deliverables:
  - presentation_[PATH]_with_charts.pptx (557KB, complete)
  - presentation_[OTHER_PATH].pptx (210KB, charts missing)
  - assets/*.png (8 chart files for manual insertion)
  - README.md (manual insertion instructions for second path)

Reason for partial: [Brief explanation of why one path failed]

Failure (Both Paths):

⚠️ Orchestration failed at Stage 8e (chart insertion)

📦 Deliverables:
  - presentation_marp.pptx (210KB, text placeholders)
  - presentation_pptx.pptx (200KB, text placeholders)
  - assets/*.png (8 chart files)
  - README.md (manual insertion instructions)

Manual steps:
1. Open preferred PPTX in PowerPoint
2. Navigate to slides 3-10
3. Insert → Pictures → Select corresponding chart from assets/
4. Resize to 4" width, position at right column

Quality Gates

After Each Stage

8b: Data Synthesis

• ✓ All required CSV files exist in /output/data/
• ✓ CSV columns match refs.md specifications
• ✓ Data trends match source calibration (e.g., -87% for solar cost)
• ✓ No missing values or malformed rows

8c: Chart Generation

• ✓ All PNG files exist in /output/assets/
• ✓ Image dimensions: ~10×6 inches, 180 DPI
• ✓ File sizes: 40-150KB per chart (optimized)
• ✓ Visual inspection: labels readable, colors distinct, no clipping

8d: PPTX Creation

• ✓ File exists: /output/presentation.pptx
• ✓ Slide count matches slides.md (±1 slide acceptable)
• ✓ Headings converted correctly (no Markdown artifacts)
• ✓ Speaker notes embedded

8e: Chart Insertion

• ✓ File exists: /output/presentation_with_charts.pptx
• ✓ File size increase: 300-600KB (charts added)
• ✓ Visual check: Open PPTX, verify all charts visible and positioned correctly
• ✓ No overlapping text or images

Final Deliverable Checklist

Before marking orchestration complete:

• /output/presentation_with_charts.pptx exists
• File size: 500KB - 2MB (reasonable range)
• All placeholder charts replaced with real visualizations
• Speaker notes preserved
• Visual inspection: open file, scroll through all slides
• Backup files retained: slides.md, assets/*.png (for future edits)

---

Error Handling

Common Failures and Responses

1. Data Synthesis Fails (pandas unavailable)

Fallback: Skip Stage 8b, proceed with user-provided data only
Message: "⚠️ pandas unavailable - skipping synthetic data generation. Using provided data files only."

2. Chart Generation Fails (matplotlib issues)

Fallback: Deliver PPTX with text placeholders + standalone Python script
Message: "⚠️ Chart generation failed. Delivering:
  - presentation.pptx (with placeholders)
  - generate_charts.py (run manually: python generate_charts.py)
  - Installation: uv pip install pandas matplotlib"

3. document-skills:pptx Unavailable

Fallback: Deliver Markdown + manual conversion instructions
Message: "⚠️ document-skills:pptx unavailable. Delivering:
  - slides.md (complete content)
  - assets/*.png (charts ready)
  - Conversion: Use Marp/Reveal.js or pandoc to convert to PPTX
  Command: pandoc slides.md -o presentation.pptx"

4. Chart Insertion Fails (positioning issues)

Fallback: Deliver PPTX + manual insertion instructions
Message: "⚠️ Automatic chart insertion failed. Delivering:
  - presentation.pptx (content ready)
  - assets/*.png (charts ready)
  - Manual: Open PPTX → Insert → Pictures → Select chart → Resize to 4\" width"

Partial Success Strategy

Always deliver maximum value:

• If 6 out of 8 charts succeed → deliver partial PPTX + fix instructions for remaining 2
• If PPTX creation fails → deliver Markdown + charts + conversion command
• Document all failures in /output/README.md "Known Issues" section

---

Examples

Example A: Minimal User Input → Full Orchestration

User Request:

"Create a presentation about renewable energy, ready for tomorrow's board meeting."

Detection:

• Trigger: "ready for tomorrow's meeting" (implicit final deliverable request)
• Mode: Orchestration ✓

Pipeline Execution:

Stage 0-7: Content creation → slides.md (14 slides, score 87/100)
Stage 8a: Package Markdown → notes.md, refs.md
Stage 8b: Data synthesis → 8 CSV files generated (refs.md specs)
Stage 8c: Chart generation → 8 PNG charts (579KB total)
Stage 8d: PPTX creation → presentation.pptx (210KB)
Stage 8e: Chart insertion → presentation_with_charts.pptx (557KB) ✓

Delivered:

• /output/presentation_with_charts.pptx (557KB, 14 slides, 8 real charts)
• Backup: slides.md, assets/.png, data/.csv, notes.md

---

Example B: User Provides Data → Skip Synthesis

User Request:

"Generate complete PPTX from these Q3 sales data files [uploads 3 CSVs]"

Detection:

• Trigger: "complete PPTX" (explicit orchestration request)
• User data: ✓ (3 CSV files uploaded)
• Mode: Orchestration, skip Stage 8b ✓

Pipeline Execution:

Stage 0-7: Content creation → slides.md (12 slides)
Stage 8a: Package Markdown
Stage 8b: SKIPPED (user data provided)
Stage 8c: Chart generation → use user CSVs → 5 PNG charts
Stage 8d: PPTX creation → presentation.pptx
Stage 8e: Chart insertion → presentation_with_charts.pptx ✓

---

Example C: Markdown-Only Request → No Orchestration

User Request:

"Create slides.md for renewable energy topic, I'll handle the PPTX conversion myself."

Detection:

• Trigger: "slides.md" + "I'll handle conversion" (explicit manual mode)
• Mode: Manual, no orchestration

Pipeline Execution:

Stage 0-7: Content creation → slides.md
Stage 8a: Package Markdown → notes.md, refs.md
Stage 8b-e: SKIPPED

Delivered:

• /output/slides.md with placeholder charts
• /output/notes.md, /output/refs.md
• Instructions: "Convert to PPTX using Marp or pandoc"

---

Version History

• v1.0.0 (2024-01): Initial orchestration capability