| 1 | # AGENTS.md |
| 2 | |
| 3 | This file is the project entry point for general AI agents. |
| 4 | |
| 5 | **You MUST read [`skills/ppt-master/SKILL.md`](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. |
| 6 | |
| 7 | **Repository execution anchor**: resolve the absolute repository root from this |
| 8 | file's supplied path and retain the absolute `skills/ppt-master` root before the |
| 9 | first command. Paths in this file are repository-relative notation only; invoke |
| 10 | them through those absolute roots, retain the absolute project path returned by |
| 11 | initialization, and never issue `cd skills/ppt-master` or `cd projects/...`. |
| 12 | When parsing machine-readable stdout, keep stderr separate and never place |
| 13 | `2>&1` upstream of a JSON or XML parser. Invoke each such command once per |
| 14 | concrete argument set; never encode its executable or flag list in scalar shell |
| 15 | strings, batch it through a shell loop, or add a downstream parser when the |
| 16 | command provides a compact view. |
| 17 | |
| 18 | ## Project Overview |
| 19 | |
| 20 | 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. |
| 21 | |
| 22 | **Route selection authority**: [`skills/ppt-master/workflows/routing.md`](skills/ppt-master/workflows/routing.md) owns the four top-level artifact routes: Generate PPTX, Create Template, Fill Native PPTX, and Enhance Native PPTX. Child workflows, profiles, stages, and governance documents refine one selected route; they are not competing top-level routes. |
| 23 | |
| 24 | - Topic-only or fact-insufficient inputs run [`topic-research`](skills/ppt-master/workflows/stages/topic-research.md) 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. |
| 25 | - Default Generate prepares template candidates internally in Step 3, then confirms the communication contract and free-design/template choice together in Stage 1. Template content stays unread until that confirmation; selected roots are installed before template-aware Stage 2. Quick skips this interaction. |
| 26 | - Raw PPTX template plus new material/topic routes to [`template-fill-pptx`](skills/ppt-master/workflows/template-fill-pptx.md), not the SVG pipeline. |
| 27 | - Raw PPTX cannot be consumed as a Generate template workspace; run [`create-template`](skills/ppt-master/workflows/create-template.md) 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. |
| 28 | - Explicit quick/fast or skip-strategy generation uses [`quick-generate`](skills/ppt-master/workflows/profiles/quick-generate.md): prepare sources/resources as needed, decide without interaction, omit Strategist/confirmation/spec/lock, hand-author `svg_output/`, pass its lockless final checker, and export. |
| 29 | - Recorded, self-running, or video-directed Generate work conditionally loads [`video-design`](skills/ppt-master/references/video-design.md) 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. |
| 30 | - PPTX beautify is a strict 1:1 Generate [`profile`](skills/ppt-master/workflows/profiles/beautify-pptx.md), 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. |
| 31 | - Page-image reconstruction uses the Codex-supported, Quick-only [`image-to-pptx`](skills/ppt-master/workflows/profiles/image-to-pptx.md) profile. Normalize input page frames; one frame becomes one slide. Restore text natively, reconstruct low-resolution graphics without changing identity, and derive registered clean-base/scene layers. Padded-bbox-disjoint objects may share a generated plate and become independent crops. Never use a full-slide screenshot skin. Other hosts are unsupported. |
| 32 | - Finished PPTX native enhancement uses [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) and must not enter SVG regeneration. |
| 33 | - [`visual-review`](skills/ppt-master/workflows/stages/visual-review.md), [`customize-animations`](skills/ppt-master/workflows/stages/customize-animations.md), and [`generate-audio`](skills/ppt-master/workflows/stages/generate-audio.md) are supporting stages; their trigger rules remain explicit/conditional. |
| 34 | |
| 35 | ## Execution Requirements |
| 36 | |
| 37 | - For any `brand`, `style`, `layout`, or `deck` workspace creation from PPTX/SVG, images/PDFs, documents/websites, brand assets, direct text, or mixed references, enter [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md); it keeps the fixed Create Template name and dispatches exactly one of [`create-brand`](skills/ppt-master/workflows/create-template/create-brand.md), [`create-style`](skills/ppt-master/workflows/create-template/create-style.md), [`create-layout`](skills/ppt-master/workflows/create-template/create-layout.md), or [`create-deck`](skills/ppt-master/workflows/create-template/create-deck.md). |
| 38 | - Always-on SVG constraints and shared visual-quality defaults live in [`skills/ppt-master/references/shared-standards-core.md`](skills/ppt-master/references/shared-standards-core.md). Default and Quick Generate always load [`svg-effects.md`](skills/ppt-master/references/svg-effects.md); other routes load it, [`native-data-interface.md`](skills/ppt-master/references/native-data-interface.md), and [`pptx-structure-interface.md`](skills/ppt-master/references/pptx-structure-interface.md) only when their documented execution triggers apply. |
| 39 | - Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md). |
| 40 | - Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md). |
| 41 | |
| 42 | ## Required Conventions |
| 43 | |
| 44 | - **Repo-wide style rules** — when editing prompt files under [`skills/ppt-master/references/`](skills/ppt-master/references/), Python under [`skills/ppt-master/scripts/`](skills/ppt-master/scripts/), or any other code/prose in the repo, follow the matching style rule in [`docs/rules/`](docs/rules/). |
| 45 | - **Prompt decision ownership** — follow [`docs/rules/prompt-style.md`](docs/rules/prompt-style.md) §4.1. Default Strategist prepares project-local resources and Executor realizes them; Quick's current agent decides and prepares before SVG authoring. This is not downstream acquisition. Every project icon is prepared material; `icons.inventory` indexes the default plan's curated bundled pool, not page usage or an execution whitelist. Sounds follow [`animations.md`](skills/ppt-master/references/animations.md) §2.2. |
| 46 | - **Markdown language consistency** — follow [`docs/rules/language.md`](docs/rules/language.md): one language per file, mirroring the siblings in that directory; a non-English string may appear in an English file only as quoted content (user trigger text, sample values, rendered labels, proper nouns), never as the wording of a rule; never hard-code which language the model replies in. Chat replies are unaffected. |
| 47 | |
| 48 | ## Compatibility Boundary |
| 49 | |
| 50 | - This repository is a workflow/skill package, not an app or service scaffold. |
| 51 | - Do NOT assume generic-project conventions like `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them. |
| 52 | - On conflict with a generic coding skill, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) inside this repository. |
| 53 | |
| 54 | ## Command Quick Reference |
| 55 | |
| 56 | Convenience summary only — route selection starts in [`SKILL.md`](skills/ppt-master/SKILL.md). Image to PPTX always uses [`quick-generate.md`](skills/ppt-master/workflows/profiles/quick-generate.md); Beautify uses it only when Quick is explicit, otherwise [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md). |
| 57 | |
| 58 | ```bash |
| 59 | # Source content conversion |
| 60 | python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...] |
| 61 | |
| 62 | # Project management |
| 63 | python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169 |
| 64 | python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...> |
| 65 | python3 skills/ppt-master/scripts/project_manager.py scaffold-spec <project_path> # optional manual helper |
| 66 | python3 skills/ppt-master/scripts/project_manager.py scaffold-lock <project_path> # optional manual helper |
| 67 | python3 skills/ppt-master/scripts/project_manager.py validate <project_path> |
| 68 | |
| 69 | # Icon selection — copy chosen library icons into <project>/icons/ (missing names reported + non-zero = re-pick) |
| 70 | python3 skills/ppt-master/scripts/icon_sync.py <project_path> <lib/name> [<lib/name>...] |
| 71 | |
| 72 | # Sounds — after a concrete cue job, read the complete vocabulary: |
| 73 | # skills/ppt-master/templates/sounds/sound-vocabulary.md |
| 74 | # list is optional exact filtering |
| 75 | python3 skills/ppt-master/scripts/sound_sync.py list [--query term] |
| 76 | python3 skills/ppt-master/scripts/sound_sync.py <project_path> <namespace>/<id>... |
| 77 | |
| 78 | python3 skills/ppt-master/scripts/confirm_ui/server.py <project_path> --daemon |
| 79 | python3 skills/ppt-master/scripts/confirm_ui/server.py <project_path> --wait-only --wait-stage stage1 |
| 80 | |
| 81 | # Image tools and SVG quality check |
| 82 | python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images |
| 83 | # In-pipeline AI image generation — manifest mode (required, even for 1 image): |
| 84 | python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json |
| 85 | python3 skills/ppt-master/scripts/image_gen.py --render-md <project_path>/images/image_prompts.json |
| 86 | # Out-of-pipeline one-off / debug / single-image fixup only (no manifest, no sidecar): |
| 87 | python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images |
| 88 | # Spot illustrations — slice one AI grid sheet into individual elements (see image-generator.md §4.3): |
| 89 | python3 skills/ppt-master/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names a,b,c --trim --alpha --bg KEY_HEX_FROM_PROMPT --strict-alpha |
| 90 | python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemon |
| 91 | python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path> |
| 92 | # Shared create-template coordinate compaction before template validation |
| 93 | python3 skills/ppt-master/scripts/compact_svg_coordinates.py "<template_workspace>/templates" --inplace --keep-native-frames |
| 94 | # Explicit create-template normalization: selected complex <g> -> one SVG picture asset / <image> |
| 95 | python3 skills/ppt-master/scripts/extract_svg_pictures.py "<svg_file>" --select "<group_id>" --resource-root "<workspace>" --images-dir "<workspace>/picture-assets" --inplace |
| 96 | # Type A create-template mirror: validated authoring IR -> deterministic structured template workspace |
| 97 | python3 skills/ppt-master/scripts/mirror_template_materialize.py "<import_workspace>" "<empty_template_workspace>" |
| 98 | # create-template review deck (workspace root may be global or project-scoped) |
| 99 | python3 skills/ppt-master/scripts/template_preview_pptx.py <template_workspace> |
| 100 | python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animation |
| 101 | python3 skills/ppt-master/scripts/animation_config.py validate <project_path> # optional, before re-export |
| 102 | |
| 103 | # Existing PPTX native enhancement workflow — direct OOXML patch, no SVG conversion |
| 104 | python3 skills/ppt-master/scripts/native_enhance_pptx.py init <PPTX_file> --name <project_slug> |
| 105 | python3 skills/ppt-master/scripts/native_enhance_pptx.py validate <project_path> |
| 106 | python3 skills/ppt-master/scripts/native_enhance_pptx.py apply <project_path> |
| 107 | ``` |
| 108 | |
| 109 | For serial post-processing and export, follow [`generate-pptx.md`](skills/ppt-master/workflows/generate-pptx.md) Step 7 exactly. See [`svg-pipeline.md`](skills/ppt-master/scripts/docs/svg-pipeline.md) for tool flags and behavior. |
| 110 | |
| 111 | ## Core Directories |
| 112 | |
| 113 | - `skills/ppt-master/SKILL.md` — global discipline and route-entry authority. |
| 114 | - `skills/ppt-master/workflows/generate-pptx.md` — Generate PPTX Step 1–7 authority. |
| 115 | - `skills/ppt-master/references/` — role cores plus conditionally loaded role and technical modules. |
| 116 | - `skills/ppt-master/scripts/` — runnable tool scripts. |
| 117 | - `skills/ppt-master/scripts/docs/` — topic-focused script docs. |
| 118 | - `skills/ppt-master/templates/` — layout templates, chart templates, icon library, brand presets. |
| 119 | - `skills/ppt-master/workflows/` — top-level route authorities plus supporting child workflows, profiles, stages, and governance runbooks. |
| 120 | - `docs/` — user-facing documentation (FAQ, installation, technical design, templates guide, audio narration). |
| 121 | - `docs/rules/` — repo-wide style rules. |
| 122 | - `examples/` — example projects. |
| 123 | - `projects/` — user project workspace. |
| 124 |