Skip to content

CLAUDE.md

Latest commit

 

History

History
125 lines (91 loc) · 6.35 KB

CLAUDE.md

File metadata and controls

125 lines (91 loc) · 6.35 KB
Raw

CLAUDE.md

This file provides a project overview for Claude Code. Before executing PPT generation tasks, you MUST first read skills/ppt-master/SKILL.md for the complete workflow and rules.

Project Overview

PPT Master is an AI-driven presentation generation system. Through multi-role collaboration (Strategist → Image_Generator → Executor), it converts source documents (PDF/DOCX/URL/Markdown) into natively editable PPTX with real PowerPoint shapes (DrawingML).

Core Pipeline: Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX

Execution Discipline (MANDATORY)

This workflow is a strict serial pipeline. Violating any rule below constitutes execution failure:

  1. SERIAL EXECUTION — Steps MUST be executed in order; output of each step is input for the next
  2. BLOCKING = HARD STOP — Steps marked ⛔ BLOCKING require full stop; wait for explicit user response
  3. NO CROSS-PHASE BUNDLING — The Eight Confirmations are ⛔ BLOCKING; present recommendations and wait for confirmation. Once confirmed, subsequent steps proceed automatically
  4. GATE BEFORE ENTRY — Each step has prerequisites (🚧 GATE) that must be verified before starting
  5. NO SPECULATIVE EXECUTION — Pre-preparing content for subsequent steps is FORBIDDEN
  6. NO SUB-AGENT SVG GENERATION — Executor Step 6 SVG generation must be completed by the main agent end-to-end
  7. SEQUENTIAL PAGE GENERATION — SVG pages must be generated one-by-one in a continuous pass; grouped batches (e.g., 5 pages at once) are FORBIDDEN

Role Definitions & When to Read

Role Reference File Read When
Strategist references/strategist.md Before Step 4 (Eight Confirmations)
Image_Generator references/image-generator.md When Step 5 triggered (AI image generation)
Executor references/executor-base.md + one style file Before Step 6 (SVG generation)

Executor style files: executor-general.md (visual impact) | executor-consultant.md (data clarity) | executor-consultant-top.md (MBB-level)

Common Commands

# Source content conversion
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>   # Requires: pandoc
python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL>

# Project management
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>

# Image tools
python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images  # Run BEFORE design spec if user has images
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images

# SVG quality check
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>

# Post-processing pipeline (MUST run sequentially, one at a time — NEVER batch)
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
# ✅ Confirm no errors before running the next command
python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
# ✅ Confirm no errors before running the next command
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final
# Default: generates native shapes (.pptx) + SVG reference (_svg.pptx)

Architecture

  • skills/ppt-master/references/ — AI role definitions and technical specifications
  • skills/ppt-master/scripts/ — Runnable tool scripts
  • skills/ppt-master/templates/ — Layout templates, chart templates, 640+ vector icons
  • skills/ppt-master/templates/charts/ — 52 visualization templates (see charts_index.json)
  • skills/ppt-master/templates/icons/ — Three libraries: chunk/ (default, sharp), tabler-filled/ (rounded), tabler-outline/ (stroke)
  • examples/ — Example projects
  • projects/ — User project workspace

Template Index Files

Type Path Usage
Layout templates templates/layouts/layouts_index.json Query page layout templates
Visualization templates templates/charts/charts_index.json Strategist reads this before content planning
Design spec reference templates/design_spec_reference.md Strategist reads this before writing design_spec.md

Icon search (zero token cost): ls skills/ppt-master/templates/icons/<library>/ | grep <keyword>

SVG Technical Constraints (Non-negotiable)

Banned features: clipPath | mask | <style> | class | external CSS | <foreignObject> | textPath | @font-face | <animate*> | <script> | <iframe> | <symbol>+<use>

Conditionally allowed: marker-start / marker-end — must be in <defs>, orient="auto", shape must be triangle/diamond/circle. Maps to DrawingML <a:headEnd> / <a:tailEnd>.

PPT compatibility alternatives:

Banned Alternative
rgba() fill-opacity / stroke-opacity
<g opacity> Set opacity on each child element individually
<image opacity> Overlay with a mask layer

Canvas Format Quick Reference

Format viewBox
PPT 16:9 0 0 1280 720
PPT 4:3 0 0 1024 768
Xiaohongshu (RED) 0 0 1242 1660
WeChat Moments 0 0 1080 1080
Story 0 0 1080 1920

Font Presets & Size Guidelines

Font presets: P1 (Modern business/tech) | P2 (Government docs) | P3 (Culture/arts) | P4 (Traditional) | P5 (English-primary)

Body font size baseline: 24px (relaxed, 3-5 points/page) or 18px (dense, 6+ points/page)

Level 24px baseline 18px baseline
Cover title 60-72px 45-54px
Page title 36-48px 27-36px
Body 24px 18px
Annotation 18-20px 14-15px

Post-processing Notes

  • NEVER use cp as a substitute for finalize_svg.py
  • NEVER export directly from svg_output/ — MUST export from svg_final/ (use -s final)
  • Do NOT add extra flags like --only to the post-processing commands
  • NEVER run the three post-processing steps in a single code block or single shell invocation