AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
refactor(visual-review): batch dispatch and tighten workflow positioning
hugohe33c8127747087
diff --git a/skills/ppt-master/references/visual-review.md b/skills/ppt-master/references/visual-review.mdindex 8891ca98..270d5b58 100644--- a/skills/ppt-master/references/visual-review.md+++ b/skills/ppt-master/references/visual-review.md@@ -19,15 +19,15 @@ If the static checker has not been run or has failed, the subagent must abort wi## §0.1 Subagent inputs-Every per-page review subagent must receive:+Each review subagent processes a **batch** of pages (see §6.1 for batch sizing). The inputs are:-1. **SVG path** — the assigned page under `<project>/svg_output/<page>.svg`-2. **PNG path** — pre-rendered 1280×720 screenshot at `<project>/.preview/<page>.png`-3. **`page_role`** — one of `cover` / `chapter` / `tldr` / `content` / `data` / `closing` / `breathing`. Parsed from `design_spec.md §IX` by the orchestrator. Subagents do **not** guess.-4. **Path to this rubric file**-5. **`<project>/design_spec.md`** (read-only) — §IX outline is the source of truth for "what should this page deliver"-6. **`<project>/spec_lock.md`** (read-only) — brand-locked values-7. **`<project>/.review/`** (writable) — where backups and findings JSON go+1. **Page batch** — a list of `(svg_path, png_path, page_role)` tuples, one per assigned page. `svg_path` resolves under `<project>/svg_output/<page>.svg`, `png_path` under `<project>/.preview/<page>.png`. `page_role` is one of `cover` / `chapter` / `tldr` / `content` / `data` / `closing` / `breathing`, parsed from `design_spec.md §IX` by the orchestrator — subagents do **not** guess.+2. **Path to this rubric file**+3. **`<project>/design_spec.md`** (read-only) — §IX outline is the source of truth for "what should this page deliver"+4. **`<project>/spec_lock.md`** (read-only) — brand-locked values+5. **`<project>/.review/`** (writable) — where backups and findings JSON go++The subagent reads inputs 2–4 **once** at the start of its turn, then iterates over the page batch sequentially (one page at a time): apply the rubric → write `<project>/.review/<page>.json` → move on. This is the core token-saving move — three fixed documents are read N/K times instead of N times.## §1 Hard rules (fix every hit)@@ -36,14 +36,13 @@ Every per-page review subagent must receive:| H1 | Out-of-bounds | element bbox falls outside `0,0,1280,720` | shrink or reposition into canvas || H2 | Text overflow | text bbox extends past its visual container | reduce font-size or line-break || H3 | Text overlap | two `<text>` elements' bboxes intersect (tspans within one text excluded) | reposition or resize |-| H4 | Readability | contrast < 4.5 (small text) / < 3.0 (font-size ≥ 24px); OR text directly atop a complex image with no scrim | **(v2)** position-only escape: add a `<rect>` scrim under the text, or raise the offending text's font-size to ≥ 24px so the 3.0 threshold applies. Full color change is brand-locked → goto §1.1 escalation. |+| H4 | Readability | contrast < 4.5 (small text) / < 3.0 (font-size ≥ 24px); OR text directly atop a complex image with no scrim | position-only escape: add a `<rect>` scrim under the text, or raise the offending text's font-size to ≥ 24px so the 3.0 threshold applies. Full color change is brand-locked → goto §1.1 escalation. |+| ~~H5~~ | Font-ramp drift | *covered by `svg_quality_checker.py` — see §0 prerequisites* | n/a (do not re-check) || H6 | Element collision | rect/circle/path bboxes overlap with z-order violating semantics | open spacing || H7 | Anchored element displaced | page number / header / footer covered, missing, or out of canvas | restore to anchor position || H8 | Image rendering broken | `<image>` empty / broken-image / severe distortion | fix `href`, adjust `preserveAspectRatio`, add `no-crop` if face/data is cropped || H9 | Missing key element | element required by `design_spec §IX` outline is absent from rendered slide | recreate from spec |-*H5 (font-ramp drift) is covered by `svg_quality_checker.py` and intentionally omitted.*-Detection order (run sequentially, do not parallelize within a single subagent):```@@ -53,7 +52,7 @@ H4 (readability)H8 → H9 (content)```-### §1.1 Brand-token contrast escalation *(new in v2)*+### §1.1 Brand-token contrast escalationIf H4 fires and the underlying color is a **brand token** (defined in `spec_lock.md`) — i.e., the violation will repeat on every page using that token — do **not** mark the page `needs_human`. Instead:@@ -94,7 +93,7 @@ If a "violation" requires reinterpreting `design_spec.md` to fix → mark `needs## §4 Iteration protocol-### §4.0 Iteration 0 — PNG sanity check *(v2 — relaxed)*+### §4.0 Iteration 0 — PNG sanity checkRun before applying any rule:@@ -102,14 +101,16 @@ Run before applying any rule:- PNG dimensions = 1280 × 720- PNG is **not** all-background (a histogram check: count of background-color pixels < 99% of total) — guards against blank/white-out renders only, **does not** filter sparse dark layouts-Any check fails → status = `render_failed`, abort without scanning rules. The earlier "non-bg pixel ratio ≥ 5%" rule is **deprecated** — it false-fires on legitimate minimalist dark decks (verified empirically in v1 plumbing test).+Any check fails → status = `render_failed`, abort without scanning rules.### §4.1 Iteration loop+The full loop is defined here but the **default budget is 1 iteration**. Multi-iteration runs require an explicit opt-in in the orchestrator prompt and roughly double render cost per added iteration.+```-iteration 1: scan all Hard + Soft → fix → re-render → re-screenshot-iteration 2: re-verify changed elements + scan for new Hard hits → fix → re-render-iteration 3: report only, no further fix+iteration 1: scan all Hard + Soft → fix → (re-render only if budget ≥ 2)+iteration 2 (opt-in): re-verify changed elements + scan for new Hard hits → fix → re-render+iteration 3 (opt-in): report only, no further fix```Per-iteration fix caps:@@ -120,8 +121,8 @@ Per-iteration fix caps:### §4.2 Termination conditions- **Rollback trigger**: any iteration's fix introduces a **new Hard hit** that did not exist before → immediately `cp` the backup back over the SVG, status = `needs_human`, finding records "rolled back fix X — created Hard Y"-- **Soft thrash trigger**: iteration 2's fix introduces a **new Soft hit** that did not exist before → stop, status = `needs_human` with note "fixes are competing"-- **Clean exit**: iteration 1 ends with zero Hard hits and ≤ 1 Soft hit remaining → status = `ok` if no fixes were applied, `fixed` if any were applied+- **Soft thrash trigger** (iteration budget ≥ 2 only): iteration 2's fix introduces a **new Soft hit** that did not exist before → stop, status = `needs_human` with note "fixes are competing"+- **Clean exit**: iteration ends with zero Hard hits and ≤ 1 Soft hit remaining → status = `ok` if no fixes were applied, `fixed` if any were applied### §4.3 Backup discipline@@ -185,20 +186,32 @@ Each subagent writes exactly one file to `<project>/.review/<page>.json`:`needs_human_items` must include a `suggested_fix_summary` for every entry — never bare problem descriptions.-## §6 Dispatch & messaging contract *(new in v2)*+## §6 Dispatch & messaging contractThis rubric is consumed by subagents spawned via the `visual-review` workflow. Mandatory dispatch invariants:-### §6.1 Orchestrator → subagent+### §6.1 Orchestrator → subagent (batched dispatch)++The orchestrator partitions the N pages into `ceil(N/K)` batches of ≤ K pages each (default **K = 5**; configurable per run via the orchestrator prompt) and spawns one subagent per batch.-- Spawn all per-page subagents in **one assistant message** (parallel `Agent` calls). Sequential dispatch breaks pipelining.-- Each subagent prompt is **self-contained** — no prior conversation context. Inline the absolute paths for §0.1 inputs 1–7 explicitly. Do not assume the subagent knows the project root.+- Spawn all batch subagents in **one assistant message** (parallel `Agent` calls). Sequential dispatch breaks pipelining.+- Each subagent prompt is **self-contained** — no prior conversation context. Inline the absolute paths for §0.1 inputs 1–5 explicitly, plus the full `(svg_path, png_path, page_role)` list for that batch. Do not assume the subagent knows the project root.- `subagent_type: general-purpose`. Tool restrictions: Read, Edit, Bash (for `cp` backups), Write (for JSON output). MCP playwright is **not** required by subagents — orchestrator pre-renders PNGs.- `name` / `team_name` parameters may be unavailable from nested teammate context. Dispatch must remain functional with anonymous subagents — do not require named addressing.+**Why batched, not per-page**: the rubric (~2.5K tokens), `design_spec.md` (~4–5K), and `spec_lock.md` (~1K) are identical inputs across all pages and do **not** share a prompt cache between sibling subagents. A 20-page deck with per-page dispatch re-reads ~150K tokens of fixed documents; batched dispatch with K=5 cuts that by ~75% while staying inside default parallel-subagent limits (~10). Batches also bound failure blast radius — one crashed subagent loses K pages, not the entire run.++**Batch size guidance**:+- `K = 5` (default) — balanced; safe for decks up to ~50 pages+- `K = 3` — high-fidelity / small decks (≤ 12 pages); slightly higher parallelism+- `K = 10` — token-sensitive / large decks (50+ pages); fewer subagents, larger blast radius per failure++Larger K is **not** always better: subagent context fills with prior pages' SVG / PNG / findings as the batch progresses, and beyond ~10 pages context auto-compression starts dropping early findings. Keep K such that `K × (avg_svg_size + image_token_cost + report_size)` stays well under the subagent context budget.+### §6.2 Subagent → orchestrator-- Subagent's **final action before going idle** must be `SendMessage(to=<lead>)` with the page's JSON path and a ≤150-word text summary of findings + actions. Going idle without messaging is a protocol violation.+- Subagent's **final action before going idle** must be `SendMessage(to=<lead>)` listing one JSON path per processed page (e.g., `<project>/.review/<page>.json`) and a ≤150-word text summary covering all pages in the batch. Going idle without messaging — or messaging with a partial batch — is a protocol violation.+- If the subagent aborts mid-batch (rule §4.2 rollback, tool error, etc.), it must still send the batch report covering both completed and aborted pages, with the aborted pages marked `needs_human` or `render_failed` as appropriate.### §6.3 Orchestrator → main agentdiff --git a/skills/ppt-master/workflows/visual-review.md b/skills/ppt-master/workflows/visual-review.mdindex 037dc9a6..1bc5f388 100644--- a/skills/ppt-master/workflows/visual-review.md+++ b/skills/ppt-master/workflows/visual-review.md@@ -10,14 +10,23 @@ description: Per-page rubric-based visual self-review via parallel subagents. Ru>> This workflow is **independent** — invokable in a fresh chat session with only `<project_path>` as input. No upstream conversation context required.+## Positioning++This is an **optional auxiliary loop**, not a default step in the main pipeline. The Executor (SKILL.md Step 6) is already single-AI / single-session / continuous-generation — visual consistency across pages is built into that path. This workflow exists to give models with weaker visual reasoning an explicit "render → re-look → optimize" loop they wouldn't otherwise have.++Trade-off to set expectations on:++- **Token cost is significant.** Each batch subagent re-reads the rubric + `design_spec.md` + `spec_lock.md` and processes K SVG+PNG pairs. For a 20-page deck with K=5, expect on the order of 100–150K additional input tokens on top of the main generation run.+- **Marginal value scales inversely with the executing model's visual ability.** Strong-visual models (e.g., Claude 4.x) rarely produce the kind of letter-spacing / vertical-rhythm / collision drift this rubric targets; running visual-review on top of them mostly catches nothing. Weaker models benefit more — the rubric becomes a structured second pass that catches what they missed.+## When to Run- Executor (SKILL.md Step 6) has finished all pages- `svg_quality_checker.py` has passed- Post-processing (`finalize_svg.py`, `svg_to_pptx.py`) has **not** yet run-- User wants to reduce manual review iterations before export+- The executing model has known visual-quality gaps that a structured re-pass is likely to catch, **or** the deck is high-stakes enough that the extra token cost is worth a safety net-Optional but recommended for any deck where layout precision matters. For decks containing data charts, run [`verify-charts`](./verify-charts.md) first — visual-review focuses on visual rhythm / collision / alignment, not chart coordinate math.+For decks containing data charts, run [`verify-charts`](./verify-charts.md) first — visual-review focuses on visual rhythm / collision / alignment, not chart coordinate math.## When NOT to Run@@ -25,6 +34,7 @@ Optional but recommended for any deck where layout precision matters. For decks- `svg_quality_checker.py` has not been run or has failed — fix static violations first- User has already applied annotations via `live-preview` workflow and is in a fixed-edit loop — describe changes directly, do not re-trigger rubric- The deck is < 3 pages and the user is reviewing manually anyway — manual review is faster+- The executing model already has strong visual reasoning — the token cost is unlikely to be recouped in fixes; skip unless there's a specific reason to double-check---@@ -67,7 +77,7 @@ If any page comes back with `"all_background": true` in the JSON summary, that p## Step 2 — Spawn the review team-Create a team and dispatch one orchestrator agent. The orchestrator spawns one per-page review subagent **in parallel** (single message, N parallel `Agent` calls), aggregates their JSON outputs, and reports back.+Create a team and dispatch one orchestrator agent. The orchestrator partitions the N pages into batches of ≤ K pages (default **K = 5**) and spawns one subagent per batch **in parallel** (single message, `ceil(N/K)` parallel `Agent` calls). Each batch subagent reads the fixed inputs (rubric + `design_spec.md` + `spec_lock.md`) **once**, then iterates over its assigned pages sequentially.```textTeamCreate(team_name="visual-review-<project>", agent_type="orchestrator")@@ -75,34 +85,21 @@ Agent(team_name="visual-review-<project>",subagent_type="general-purpose",name="orchestrator",- prompt=<orchestrator-prompt>, # see template below+ prompt=<orchestrator-prompt>,)```-### Orchestrator prompt template--The orchestrator prompt must be self-contained. Required fields (all absolute paths):+The orchestrator prompt must be self-contained and is the **single** place where dispatch shape, batch size, and forbid lists are stated — the rubric (`references/visual-review.md`) defines the contract those prompts must satisfy. Required fields (all absolute paths):- `<project_path>` — project root-- Page list with role for each page (parse `<project>/design_spec.md` §IX outline; if §IX is absent, default every page to `content` and flag this in the final report)+- Full page list with `page_role` per page (parse `<project>/design_spec.md` §IX outline; if §IX is absent, default every page to `content` and flag this in the final report)+- Batch size `K` (default 5; raise to 10 for token-sensitive runs on large decks, lower to 3 for high-fidelity short decks — see rubric §6.1)+- Iteration budget per page (default 1; 2 only for high-stakes / final-cut runs — see [Appendix: Iteration loop](#appendix-iteration-loop-opt-in))- Path to the rubric: `skills/ppt-master/references/visual-review.md`-- Instruction: **dispatch all per-page subagents in a single message**-- Instruction: after aggregation, `SendMessage(to="team-lead")` with results before going idle — orchestrator must **not** end its turn without sending the aggregate--### Per-page subagent prompt template--Composed by the orchestrator, one per page, also self-contained:--- SVG path, PNG path, `page_role`-- Path to rubric-- Path to `design_spec.md` and `spec_lock.md` (read-only)-- Output JSON path: `<project>/.review/<page>.json`-- Backup directory: `<project>/.review/backup/`-- Iteration budget: 1 by default (2 for high-stakes decks — opt in explicitly)-- Explicit forbid list: do not edit any other page, `design_spec.md`, `spec_lock.md`, `animations.json`, `image_prompts.json`, or `images/`-- Mandatory final action: `SendMessage(to=<orchestrator-name>)` with the JSON path + a ≤150-word summary before going idle+- Dispatch contract reference: rubric [§6](../references/visual-review.md#6-dispatch--messaging-contract) (batched parallel spawn, self-contained prompts, mandatory `SendMessage` on idle, anonymous-name tolerance)+- Subagent forbid list: do not edit any other page, `design_spec.md`, `spec_lock.md`, `animations.json`, `image_prompts.json`, or `images/`-See [`references/visual-review.md`](../references/visual-review.md) §6 for the full dispatch contract.+**Host compatibility**: `TeamCreate` and `SendMessage` are Claude-Code-specific multi-agent primitives. On hosts without those primitives (Cursor, VS Code + Copilot, Codebuddy, etc.) the main agent processes batches sequentially — same partitioning, same per-batch prompts, no parallel dispatch. Token savings from shared fixed inputs still apply; wall-clock time grows roughly N/K-fold.---@@ -165,13 +162,13 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path>----## Appendix: Iteration loop (v2 behavior)+## Appendix: Iteration loop (opt-in)-This v1 workflow uses single-iteration review (one scan, fix, done). The full iteration loop per [`references/visual-review.md`](../references/visual-review.md) §4.1 supports:+Default behavior is single-iteration review: one scan, fix in place, write the report. The full iteration loop in [`references/visual-review.md`](../references/visual-review.md) §4.1 supports:1. Iteration 1: scan + fix2. Re-render via `visual_review.py --pages <token>`3. Iteration 2: re-verify changed elements + scan for new Hard hits4. Rollback on any new Hard hit introduced by a fix-To enable, pass `--iteration-budget 2` in the orchestrator prompt (currently advisory; the script itself does not enforce — subagent prompt must mention it explicitly). Reserve for final-cut runs.+To enable, set iteration budget = 2 in the orchestrator prompt (this is a prompt-level instruction to subagents; neither `visual_review.py` nor the harness enforces it). Each added iteration roughly doubles render cost and triples token cost on the affected pages — reserve for final-cut runs only.