AGENTS.md

This file serves as the project entry point for general AI agents. 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 Requirements:

• Before starting a PPT task, read skills/ppt-master/SKILL.md first
• To create a template independently, read skills/ppt-master/workflows/create-template.md
• Role-specific rules and technical constraints are in skills/ppt-master/references/
• ⚠️ Strict serial execution: Every Step in the pipeline MUST be executed sequentially — bundling, batching, or parallelizing Steps is FORBIDDEN
• ⚠️ SVG generation must stay in the main agent: During Executor Step 6, SVG pages MUST be generated by the current main agent with full project context. Delegating SVG generation to sub-agents is FORBIDDEN
• ⚠️ SVG generation rhythm: In Executor Step 6, first lock the global design context, then generate SVGs sequentially page by page in one continuous pass. Generating pages in grouped batches (for example, 5 pages at a time) is FORBIDDEN

Compatibility Boundary

• This repository is a workflow/skill package, not a conventional app or service scaffold
• Do NOT assume repository-local conventions such as .worktrees/, tests/, or mandatory branch setup unless the user explicitly requests them
• If a generic coding skill conflicts with this repository's instructions, prioritize skills/ppt-master/SKILL.md and this file for work inside this repository

Common Commands

# Source content conversion
python3 skills/ppt-master/scripts/pdf_to_md.py <PDF_file>
python3 skills/ppt-master/scripts/doc_to_md.py <DOCX_or_other_file>   # Requires: pandoc (DOCX/EPUB/HTML/LaTeX/RST/etc.)
python3 skills/ppt-master/scripts/web_to_md.py <URL>
node skills/ppt-master/scripts/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
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)
# Use --only native or --only legacy to generate just one version

Core Directories

• skills/ppt-master/SKILL.md — Main entry point and complete workflow
• skills/ppt-master/workflows/create-template.md — Standalone template workflow
• skills/ppt-master/references/ — Role definitions and technical specifications
• skills/ppt-master/scripts/ — Tool scripts
• skills/ppt-master/scripts/docs/ — Topic-focused script docs (conversion, project, svg-pipeline, image, troubleshooting)
• skills/ppt-master/templates/ — Layout templates, chart templates, icon library
• examples/ — Example projects
• projects/ — User project workspace

SVG Technical Constraints

Banned features: clipPath | mask | <style> | class | external CSS | <foreignObject> | textPath | @font-face | <animate*> | <script> | marker-end | <iframe> | <symbol>+<use> (id inside <defs> is a legitimate reference and is NOT banned)

PPT compatibility alternatives:

Canvas Format Quick Reference

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