/ppt

description: "PPT slide generation workflow: init -> requirement research -> material collection -> outline planning -> planning draft -> design draft + Gemini review -> delivery"
argument-hint: "[--style=<style>] [--brand-colors=<path>] [--pages=10-15] [--run-id=<id>] <topic>"
allowed-tools:
  - Task
  - AskUserQuestion
  - Read
  - Write
  - Bash

/ppt-agent:ppt

Purpose

Generate professional PPT slides as SVG files (1280x720) through a structured multi-phase workflow with Bento Grid layouts, Claude draft generation, and Gemini quality review.

Agent Types

• `ppt-agent:research-core`
• `ppt-agent:content-core`
• `ppt-agent:slide-core`
• `ppt-agent:review-core`

Required Artifacts

• `${RUN_DIR}/input.md`
• `${RUN_DIR}/proposal.md`
• `${RUN_DIR}/tasks.md`
• `${RUN_DIR}/research-context.md`
• `${RUN_DIR}/requirements.md`
• `${RUN_DIR}/materials.md`
• `${RUN_DIR}/outline.json`
• `${RUN_DIR}/outline-preview.md`
• `${RUN_DIR}/drafts/slide-{nn}.svg`
• `${RUN_DIR}/draft-manifest.json`
• `${RUN_DIR}/slides/slide-{nn}.svg`
• `${RUN_DIR}/slide-status.json`
• `${RUN_DIR}/reviews/review-{nn}.md`
• `${RUN_DIR}/reviews/review-holistic.md`
• `${RUN_DIR}/review-manifest.json`
• `${RUN_DIR}/output/`
• `${RUN_DIR}/output/index.html`
• `${RUN_DIR}/output/speaker-notes.md`

Phase 1: Init

1. Parse flags: `--style` (optional), `--pages` (default: `10-15`), `--run-id`. Available styles are discovered from `skills/_shared/index.json` (filter resources where `domain == "style"`). Do NOT hardcode style names — read the registry.

**Style selection** (if `--style` not provided, two-step flow):

**Step 1 — Choose style group** via `AskUserQuestion` (4 options): | Group | Styles | Description | |-------|--------|-------------| | Professional | business, minimal, notion, scientific, editorial-infographic | 商务、学术、数据驱动场景 | | Creative | creative, bold-editorial, vector-illustration, sketch-notes, watercolor | 设计、营销、艺术场景 | | Tech / Dark | tech, blueprint, intuition-machine, pixel-art | 技术演示、产品发布、暗色系 | | Thematic | chalkboard, fantasy-animation, vintage | 教育、故事、复古主题 |

**Step 2 — Choose specific style** via `AskUserQuestion` (2-4 options from the selected group): Read each candidate style's YAML, present with `preview` field showing:

   {name}
   Mood: {mood first sentence}
   Colors: ██ {primary} ██ {accent} ██ {card_bg}
   Font: {heading_font first entry}

If the group has >4 styles, split into two questions or show the top 4 most relevant to the topic.

If `--style` is explicitly provided, skip both steps. 2. Parse `--brand-colors` flag (optional). If provided, read the brand YAML file which should contain:

   brand:
     primary: "#FF6900"     # Main brand color
     secondary: "#000000"   # Secondary brand color
     logo_text: "Mi"        # Short brand mark (2-3 chars)

Merge brand colors with the selected style: brand `primary` overrides style `accent`, brand `secondary` overrides style `primary`. The plugin derives remaining tokens (card_bg, text contrast) automatically. Write merged style to `${RUN_DIR}/brand-style.yaml` for downstream agents to reference. 3. Extract `<topic>` from remaining arguments. 4. Resolve run id:

   # If --run-id provided, resume existing run
   # Otherwise derive CHANGE_ID: kebab-case from topic
   # Examples: "ppt-ai-industry-trends", "ppt-quarterly-report"
   # Fallback: "ppt-$(date +%Y%m%d-%H%M%S)"
   if [[ -n "${RUN_ID_ARG}" ]]; then
     CHANGE_ID="${RUN_ID_ARG}"
   else
     CHANGE_ID="ppt-${slug_from_topic}"
   fi
   RUN_DIR="openspec/changes/${CHANGE_ID}"
   mkdir -p "${RUN_DIR}"

**Resume detection** (when `--run-id` is provided): Check existing artifacts to determine the resume point:

• Before checking resume artifacts, delete any orphaned `${RUN_DIR}/slide-status.tmp.json`. This temp file is never authoritative and may be left behind by an interrupted atomic write.
• If `${RUN_DIR}/slide-status.json` exists, validate it with `python3` before trusting it. If validation fails, stop and surface the error instead of guessing resume state.
• Valid `slide-status.json` exists → read it, skip slides already marked `passed` or `accepted_with_warning`, and resume Phase 6 from the first incomplete slide
• `draft-manifest.json` exists but no valid `slide-status.json` → resume at Phase 6 start
• `outline.json` exists with `"approved": true` but no `draft-manifest.json` → resume at Phase 5
• `outline.json` exists with `"approved": false` or missing → resume at Phase 4 (re-enter Hard Stop for user approval)
• `materials.md` exists but no `outline.json` → resume at Phase 4
• `requirements.md` exists but no `materials.md` → resume at Phase 3
• `research-context.md` exists but no `requirements.md` → resume at Phase 2 (user confirmation)
• Nothing exists → start from Phase 1

5. **Write OpenSpec scaffold** to `${RUN_DIR}/`:

• `proposal.md`: `# Change:` title, `## Why` (presentation purpose), `## What Changes` (slide deliverables), `## Impact`
• `tasks.md`: one numbered section per phase (Init, Research, Collection, Outline, Draft, Design, Delivery) with `- [ ]` items
• Mark items `[x]` as each phase completes.

6. Write `${RUN_DIR}/input.md` with topic, style, page range, and flags.

Phase 2: Requirement Research (Hard Stop)

1. Run background research:

   Task(subagent_type="ppt-agent:research-core", prompt="run_dir=${RUN_DIR} mode=research topic=${TOPIC}")

Agent uses `agent-reach` skill for web search and outputs `${RUN_DIR}/research-context.md`.

2. **MANDATORY**: MUST call `AskUserQuestion` to present research findings and ask:

• Target audience (who will see this presentation?)
• Presentation purpose (inform / persuade / teach / report?)
• Key messages (3-5 core points to convey)
• Tone preference (formal / casual / inspirational / data-driven?)
• Any specific content requirements or constrai