zengwenliang416/ppt-agent/gemini-cli

Gemini CLI - PPT Slide Layout & Aesthetic Optimizer

SVG slide layout and aesthetic optimizer via scripts/invoke-gemini-ppt.ts. Gemini's role is to optimize layout and improve visual aesthetics — not just check compliance. It evaluates layout balance, visual hierarchy, color harmony, typography, and readability, then proposes concrete improvements. The script automatically tries fallback models if the primary model is unavailable.

Script Entry

npx tsx scripts/invoke-gemini-ppt.ts \
  --role "<role>" \
  --prompt "<prompt>" \
  [--image "<path>"] \
  [--model "<model>"] \
  [--output "<path>"]

Resource Usage

• Role prompts: references/roles/{role}.md
• Execution script: scripts/invoke-gemini-ppt.ts

Roles

Workflow

Step 1: Read the SVG source and style tokens

Before calling Gemini, read the SVG file content and the relevant style YAML so you can include them in the prompt. The reviewer needs the actual SVG source code to inspect element attributes (font-size, fill, opacity, coordinates).

Step 2: Build the optimization prompt

Construct a prompt that includes:

• The full SVG source code (or relevant excerpts for very large files)
• The style token values (colors, fonts, border-radius, gap)
• The slide context (index, topic, presentation style name)

Step 3: Call Gemini

npx tsx scripts/invoke-gemini-ppt.ts \
  --role reviewer \
  --prompt "$REVIEW_PROMPT" \
  --output "${RUN_DIR}/reviews/gemini-raw-${SLIDE_INDEX}.md"

The script tries models in order: default → gemini-2.5-pro → gemini-2.5-flash. If all fail, it exits with code 2.

Step 4: Handle the result

• Exit code 0: Gemini responded. The raw output is already persisted at ${RUN_DIR}/reviews/gemini-raw-{nn}.md — do not delete it. Read and extract the structured optimization suggestions.
• Exit code 2: All Gemini models unavailable. Fall back to Claude self-optimization using the same quality standards from references/roles/reviewer.md. This is the expected degradation path — optimization must still happen, just without the cross-model perspective.
• Exit code 1: Script error (bad args, missing file). Fix and retry.

Step 5: Write the final optimization report

Whether from Gemini or Claude fallback, write the structured report to ${run_dir}/reviews/review-{nn}.md using the output format defined in references/roles/reviewer.md. The Gemini raw output (gemini-raw-{nn}.md) is preserved as an intermediate artifact for traceability.

Prompt Templates

Role: reviewer — SVG Layout & Aesthetic Optimization

npx tsx scripts/invoke-gemini-ppt.ts \
  --role reviewer \
  --output "${RUN_DIR}/reviews/gemini-raw-${N}.md" \
  --prompt "
## Task
Optimize the SVG presentation slide's layout and visual aesthetics. Your primary output is **typed optimization suggestions** — concrete, actionable design improvements. Scoring is a secondary quality gate.
 
## Slide Content
${SVG_CONTENT}
 
## Style Reference
${STYLE_NAME} style with tokens: ${STYLE_TOKENS}
 
## Optimization Criteria
1. Layout Balance: card arrangement, visual weight distribution, whitespace usage
2. Color Harmony: palette consistency, contrast ratios, accent usage
3. Typography: hierarchy clarity, font size appropriateness, line spacing
4. Readability: text legibility at presentation resolution, information flow
5. Information Density: content-to-whitespace ratio, cognitive load
 
## Output Format
Follow the exact structure from references/roles/reviewer.md:
1. **Optimization Suggestions** (primary): typed suggestions using the 5-type taxonomy (attribute_change, layout_restructure, full_rethink, content_reduction, deck_coordination). Each with type, priority (1-3), description, and type-specific details.
2. **Suggestions JSON**: parseable JSON array of all suggestions for downstream automation.
3. **Quality Gate** (secondary): overall_score (1-10), pass (true/false), per-criterion weighted scores, hard rule violations.
"

Fallback Strategy — Technical Validation Only

The dual-model approach provides value through independent aesthetic perspective. Aesthetic optimization requires cross-model review — Claude cannot meaningfully optimize its own visual design choices (production data: 12 slides all scored 8.2-8.8 with identical notes during self-review).

When Gemini is unavailable (exit code 2), review-core performs technical validation only:

1. Run hard-rule checks from references/roles/reviewer.md Quality Standards table:

• XML validity (xmllint)
• ViewBox present (1280x720)
• Font-size floor (>= 14px body, >= 12px labels)
• Safe area margins (>= 60px)
• WCAG AA contrast ratios
• Style token compliance (colors from declared YAML)

1. Report violations as pass/fail — no aesthetic scores, no optimization suggestions.
2. Mark output header as: **Reviewer**: Claude technical validation (Gemini unavailable) — aesthetic optimization not performed
3. The fix loop does not trigger for technical-only reviews (there are no typed suggestions to apply). Only hard-rule violations that are Critical or Major are reported as blocking issues.

This is an honest tradeoff: without Gemini, slides have technical correctness but no cross-model aesthetic refinement. This is better than rubber-stamp scores that give false confidence.

Intermediate Artifact Preservation

Gemini's raw output (gemini-raw-{nn}.md) MUST be preserved in ${RUN_DIR}/reviews/. These files serve as:

• Traceability: what Gemini actually suggested vs what was applied
• Debugging: if a fix round makes things worse, the original suggestion is available
• Learning: patterns in Gemini's suggestions can inform future style token tuning

Constraints

Collaboration

1. review-core agent invokes this skill via Skill(skill="ppt-agent:gemini-cli") at runtime. The Skill tool loads SKILL.md into the agent's context, then the agent uses Bash to call invoke-gemini-ppt.ts. Both Skill and Bash must be in the agent's tools list.
2. Review output feeds back to slide-core for fix iterations