ppt-master: Instructions file for Codex

AGENTS.md

This file is the project entry point for general AI agents.

You MUST read skills/ppt-master/SKILL.md before any PPT generation task or repo modification. It owns global execution discipline and points to the route selector; after routing, the selected runtime authority owns its steps, gates, and commands.

Repository execution anchor: resolve the absolute repository root from this file's supplied path and retain the absolute skills/ppt-master root before the first command. Paths in this file are repository-relative notation only; invoke them through those absolute roots, retain the absolute project path returned by initialization, and never issue cd skills/ppt-master or cd projects/.... When parsing machine-readable stdout, keep stderr separate and never place 2>&1 upstream of a JSON or XML parser. Invoke each such command once per concrete argument set; never encode its executable or flag list in scalar shell strings, batch it through a shell loop, or add a downstream parser when the command provides a compact view.

Project Overview

PPT Master turns source material into natively editable DrawingML PPTX. Generate has two mutually exclusive runtimes: Default Strategist → Image_Generator → Executor, and self-contained Quick without separate strategy/confirmation. Beautify selects from explicit Quick intent; Image to PPTX always uses Quick.

Route selection authority: skills/ppt-master/workflows/routing.md owns the three top-level artifact routes: Generate PPTX, Create Template, and Edit Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes.

• Topic-only or fact-insufficient inputs run topic-research inside the selected Generate profile's source intake; its facts URLs are not auto-expanded. After normal image search fails, one relevant webpage may be fetched as a source package and only reviewed selections enter the runtime image pool.
• Default Generate prepares template candidates internally in Step 3, then confirms the communication contract and free-design/template choice together in Stage 1. A template never rewrites the confirmed communication contract; selected roots are installed before template-aware Stage 2. Quick skips this interaction.
• Raw PPTX template plus new material/topic routes to edit-native-pptx: a pptx_to_svg.py --roundtrip workspace where unchanged pages are referenced byte-for-byte and only planned pages are edited; it never enters Generate.
• Raw PPTX cannot be consumed as a Generate template workspace; run create-template first and return with the generated workspace root as a Stage-1 candidate. Never add Master/Layout structure directly to an existing PPTX/SVG; generate new structured SVG pages from the workspace.
• Explicit quick/fast or skip-strategy generation uses quick-generate: prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author svg_output/, pass its lockless final checker, and export.
• Recorded, self-running, or video-directed Generate work conditionally loads video-design inside the selected Default or explicit Quick runtime before page planning. It changes scene, script, and motion design—not the runtime/profile or artifact route.
• PPTX beautify is a strict 1:1 Generate profile, not a separate route. Explicit Quick intent uses the Quick runtime; otherwise it uses Default. Any split/merge/drop/reorder disables Beautify and returns to ordinary Generate in the selected runtime.
• Page-image reconstruction uses the Quick-only image-to-pptx profile on a vision host; generated layers use host reference-image editing or image_gen.py --reference-image. One normalized frame becomes one slide: native text from reviewed OCR over a text-removed base, plus identity-faithful graphics and registered scene layers (checked, padded-bbox-disjoint objects sharing a plate) for objects that must stay independent. Never use a full-slide screenshot skin.
• Finished PPTX notes / narration / timings / transitions with visible slides untouched also use edit-native-pptx; export must report rebuilt=0.
• visual-review, customize-animations, and generate-audio are supporting stages; their trigger rules remain explicit/conditional.