OfficeCLI Morph-PPT Skill

This skill is a scene layer on top of officecli-pptx. Every pptx hard rule — visual delivery floor (title ≥ 36pt / body ≥ 18pt / title ≥ 2× body), 12-column grid on 33.87×19.05cm, canonical palettes, chart-choice decision table, connector canon, shell escape, resident + batch, Delivery Gate 1–5a — is inherited, not re-taught. This file adds only what Morph needs on top: cross-slide shape-name binding, Scene Actors vs content prefixing, ghost discipline, transition=morph CLI quirks, 52-style visual library lookup, and a morph-specific fresh-eyes Gate 5b extension.

When the pptx base rules cover it, the text here says → see pptx v2 §X. Read skills/officecli-pptx/SKILL.md first if you have not.

Setup

If officecli is missing:

• macOS / Linux: curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell): irm https://d.officecli.ai/install.ps1 | iex

Verify with officecli --version (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https://github.com/iOfficeAI/OfficeCLI/releases.

⚠️ Help-First Rule

This skill teaches the Morph workflow — when shape names must match, when to ghost, when the CLI auto-prefixes — not every command flag. When a prop name, enum, or preset is uncertain, consult help BEFORE guessing.

officecli help pptx slide           # authoritative for: transition, advanceTime, advanceClick, background
officecli help pptx transition      # transition / transitionDuration / transitionSpeed (Parent: slide)
officecli help pptx shape           # name, preset, x/y/width/height, fill, rotation, opacity, animation
officecli help pptx animation       # preset + trigger + duration values
officecli help pptx <element> --json  # machine-readable schema

Help reflects the installed CLI version. When skill and help disagree, help wins. Every --prop X= in this file is grep-verified against officecli help pptx <element>. Specific confirmations: transition=morph is a listed value on slide; advanceTime / advanceClick are valid. transition is a real element (officecli help pptx transition, Parent: slide, set/get) — it exposes transition, transitionDuration, and transitionSpeed. Set the transition with the high-level path set <slide> --prop transition=morph; tune speed/duration with the combined shorthand transition=morph-slow (or -fast, or transition=morph-<DUR_MS>). Speed/duration are set only via that shorthand on the transition prop, not as independent sub-props. Both round-trip on readback: transition=morph-slow/-fast reads back as transitionSpeed=slow/fast, and transition=morph-<DUR_MS> (e.g. morph-1500) reads back as transitionDuration=1500.

Mental Model & Inheritance

Inherits pptx v2. You should have read skills/officecli-pptx/SKILL.md first. This skill assumes you know how to: add slides + shapes + charts + connectors; address by @name= / @id=; quote paths; use batch heredocs; use tailEnd=triangle on flow connectors; run the Delivery Gate 1–5a; attribute [AGENT-ERROR] vs [RENDERER-BUG] vs [SKILL gap]. If any of those are unfamiliar, read pptx v2 first.

Inherited from pptx v2 (do NOT re-teach):

• Visual delivery floor — title ≥ 36pt / body ≥ 18pt / title ≥ 2× body, cover-richness, contrast floor, no \$\t\n literals, ≤ 1 animation per slide / ≤ 600ms.
• Grid math — 33.87 × 19.05cm, edge margin ≥ 1.27cm, inter-block gap ≥ 0.76cm, ≥ 20% negative space. For N-card grids: col = (33.87 − 2·margin − (N−1)·gap) / N.
• Four canonical palettes (Executive navy / Forest & moss / Warm terracotta / Charcoal minimal) — morph decks may pick a different mood from reference/styles/, but contrast rules still apply.
• Chart-choice table — column vs bar vs line vs pie vs scatter vs large-text KPI; > 3 series + > 8 categories = split.
• Connector canon — shape=straight|elbow|curve, @id= for from/to (C-P-6), tailEnd=triangle on every flow.
• Shell escape 3-layer — $ single-quoted, heredocs for batch, <a:br/> for real newlines.
• Resident mode + batch ≤ 12 ops, <<'EOF' single-quoted delimiter.
• Delivery Gate 1-5a (schema, token grep, hyperlink rPr, slide-order, dark-on-dark) — every gate prints OK before declaring done.
• Known Issues C-P-1..7 (hyperlink rPr, chart spPr warning, animation duration readback, animation remove, connector enum, connector @name=, chart color renderer normalization).
• Attribution triage — [AGENT-ERROR] vs [RENDERER-BUG] vs [SKILL gap].

Morph identity — what this skill owns (delta on top of pptx v2):

• Cross-slide shape-name binding. PowerPoint's Morph engine pairs shapes by identical name= across adjacent slides and interpolates their position / size / rotation / fill / opacity. No matching name ⇒ no animation, silent fade. This is a workflow discipline, not a CLI feature.
• Namespace prefixes: !!scene- (persistent decoration, never ghosted) / !!actor- (content that evolves then exits) / #sN-* (per-slide content, ghosted on slide N+1). Plan the names BEFORE you add.
• Ghost position x=36cm (off the right edge of the 33.87cm canvas). Never delete a !!-prefixed shape — move it off-canvas so the morph exit animation still plays.
• transition=morph auto-prefix quirk. The CLI auto-prepends !! to every shape on a morph slide (#s1-title is stored as !!#s1-title). @name= path selectors still resolve — get .../shape[@name=#s1-title] returns the shape (matching is suffix/prefix-tolerant). The name you read back is the prefixed form. See §Known Issues.
• Adjacent-slide spatial variety. Displacement ≥ 5cm or rotation ≥ 15° between pairs — otherwise morph interpolates nothing visible.
• Renderer reality. Morph renders in PowerPoint 365 / Keynote / WPS. LibreOffice and many web viewers render as plain fade (runtime feature). Not a skill defect — [RENDERER-BUG].

Reverse handoff — when to go BACK to pptx base (or sibling skills)

Stay in pptx v2 base for any deck without cross-slide motion (board reviews, sales decks, all-hands, training). Stay in officecli-pitch-deck for fundraising narrative arcs without morph. Use this skill only when the user explicitly asks for "morph" / "smooth transitions" / "continuous animation" AND ≥ 2 consecutive slides share a visual element that transforms. "Animated deck" meaning one-off entrance animations → pptx v2 §Animations, not morph.

Shell & Execution Discipline

Shell quoting, incremental execution, $FILE convention → see pptx v2 §Shell & Execution Discipline. Same rules verbatim.

Morph-specific additions:

• !! in shell values — single-quote. Bash / zsh history expansion eats unquoted !!foo. Always use --prop 'name=!!scene-ring' (single quotes). In Python subprocess.run([...]) lists, no quoting needed — pass "name=!!scene-ring" as a plain string.
• $ in prop text — single-quote (price tokens). --prop text='$9/mo' and --prop text='$199/yr' — NEVER --prop text="$9/mo" (zsh/bash eat $9 as empty var → text rendered as . / stray period). Same for ${VAR}, $USER, \n, \r, \t inside a double-quoted prop. Gate 2 morph addendum below greps for the leak signature.
• # in shell values — safe, but quote anyway. # is a comment leader only at the start of a shell word. --prop name=#s1-title works, but --prop 'name=#s1-title' is the habit that stops you guessing.
• Batch heredoc is the cleanest path for multi-shape slides. <<'EOF' | officecli batch $FILE disables all shell expansion — safe for $, !!, #, ' inside the JSON body.
• --json responses wrap the payload in .data.results[]. Both query and get return a .data.results[] array. A single node's format sits at .data.results[0].format.X; that node's children sit at .data.results[0].children[] (each child's format at .data.results[0].children[].format.X). Always go through .data.results[0] — bare .data.children[] or .data.format returns null silently.
• Variable: FILE="deck.pptx" at the top of every build script; every example below uses $FILE.
• Gate shell pattern — COUNT, then if/else. Never write grep … && echo LEAK || echo OK — when grep exits 1 (0 matches), the || branch fires with empty stdout and prints "OK" confusingly (or prints "LEAK" from prior pipes). Canonical form: COUNT=$(cmd | wc -l); if [ "$COUNT" -gt 0 ]; then echo "LEAK: …"; else echo "OK"; fi.

Two primitives this skill owns

• Scene Actors = persistent !!-named shapes (decoration or content) paired by identical name across adjacent slides so Morph can interpolate them. Every !!scene- / !!actor- shape is a scene actor.
• Choreography = the plan for how actors evolve — who moves where, who enters, who exits, on which slide pair. Written BEFORE code in the §Morph Pair Planning table.

Use this skill when the user asks for morph motion AND ≥ 2 consecutive slides share a visual element that transforms. Target-viewer caveat: morph needs PowerPoint 365 / Keynote / WPS — if the user is LibreOffice-only, warn first (see §Renderer honesty).

Speaker notes rule. Every content slide (non-cover, non-closing) MUST carry speaker notes via officecli add "$FILE" /slide[N] --type notes --prop text='…'. Missing notes = not shippable — inherits pptx v2 §Hard rules (H7). Morph decks tend to be visually minimal, so notes carry the narration.

What is Morph? (core mechanics)

PowerPoint's Morph transition creates smooth motion by interpolating shape properties between adjacent slides, matched by identical shape names.

Slide 1: shape name="!!scene-ring" x=5cm  width=8cm   fill=E94560 opacity=0.3
Slide 2: shape name="!!scene-ring" x=20cm width=12cm fill=E94560 opacity=0.6
         ↓  transition=morph on slide 2
Result:  Ring smoothly moves, grows, and fades darker over ~1 second

Morph only runs if slide N+1 carries transition=morph. Apply it via officecli add / --type slide --prop transition=morph on creation, or officecli set "/slide[N]" --prop transition=morph after the fact. Slides 2+ that omit this prop fall back to whatever the master defines (usually no transition) — motion dies silently.

Three-prefix naming system (non-negotiable):

Hard rule: !!scene- and !!actor- names must NEVER collide (e.g., !!scene-card + !!actor-card in the same deck — morph engine confuses them). Disambiguate: !!scene-card-bg vs !!actor-card-content.

Charts can be morph-paired. officecli add … --type chart accepts --prop name=!!… (the name reads back), so a chart with an identical !!-name on adjacent slides participates in shape-name morph pairing — the chart frame interpolates position / size. Note morph cannot interpolate the plotted data inside the chart frame. For bar-grow / line-grow narratives where the bars themselves must animate: (a) accept plain fade-in of the chart as-is, OR (b) build N !!actor-bar-K rectangles manually sized to the values and morph those — each rect carries the same !!actor-bar-K name across adjacent slides while width / height / fill evolves.

Ghost accumulation is silent. Once a !!-prefixed shape appears on any slide, it stays visible on every subsequent morph slide unless explicitly moved to x=36cm. final-check helper does NOT detect !! shapes lingering in the visible area — only Gate 5b screenshot audit does. Plan every actor's exit slide in the pair table BEFORE coding.

Spatial variety rule. Adjacent slides must have noticeably different compositions — displacement ≥ 5cm OR rotation ≥ 15° OR size delta ≥ 30% on at least 3 morph-paired shapes. Without this, morph interpolates nothing visible and the transition collapses to a fade (silent-fail).

Simultaneous-timing constraint. All !! shapes in one morph pair animate simultaneously. To stagger shape A before shape B, insert an intermediate keyframe slide — there is no per-shape delay knob.

Paired vs enter vs exit — three behaviors, one rule. Same mechanism (shape-name match) produces three outcomes:

Outgoing content (not incoming) is what gets !!-prefixed + ghosted. !!actor-* shapes silently "disappear" when you forget them — their name going missing on slide B reads as an unpaired exit (plain fade). Always explicit-ghost to x=36cm so the exit animation slides off the right edge visibly. One runnable example:

# Slide 2: actor is visible at x=5cm — Slide 3: same name, ghosted off-canvas → visible slide-off motion
officecli add "$FILE" "/slide[3]" --type shape --prop 'name=!!actor-metric' \
  --prop text="42%" --prop x=36cm --prop y=8cm --prop width=6cm --prop height=3cm

**Content (#sN-) is added fresh per slide.* Because text changes every slide, Morph has no meaningful pairing to do on titles / body — it cross-fades them. This is why #sN-* get different names per slide (they are intentionally unpaired) and must be ghosted on slide N+1. Scene actors (!!) carry the continuity; content (#) carries the message.

Morph Pair Planning (pre-code, REQUIRED)

Before planning morph pairs, if the deck's audience / purpose / narrative is underspecified, run the planning prompt in reference/decision-rules.md to emit a brief.md first — a morph arc without a narrative spine collapses into "slide with motion", not "story with motion".

Plan every transition in a table inside brief.md before writing any officecli add. Renaming shapes mid-build is the #1 cause of ghost accumulation bugs.

Planning rules:

1. Decide ALL !! names up front — each morph-paired shape must use the exact same name on both slides.
2. Classify every !! shape as !!scene- or !!actor-. Scene shapes persist; actors must have a planned exit slide.
3. Section-transition boundary: when moving into a new topic section, ghost ALL previous-section !!actor- on the first slide of the new section. Only !!scene- (whole-deck decoration) remains.
4. Do NOT start building until the table is complete. If the plan changes mid-build, redraw the table and re-verify affected slides.

Morph Recipes (4 patterns)

Four patterns cover ~95% of morph decks. $FILE="deck.pptx" throughout. Each block is self-contained and ≤ 20 lines.

(a) Single-element morph — size / position

Visual outcome. A hero title centered on slide 1 (size 48pt at y=8cm), then slide 2 shrinks it to 32pt and shifts it to the top-left corner (x=1.5cm, y=1cm) — letting fresh slide-2 content take center stage. One shape, clean motion, no actors.

FILE="deck.pptx"
officecli create "$FILE"; officecli open "$FILE"

# Slide 1 — hero
officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761
officecli add "$FILE" /slide[1] --type shape --prop 'name=!!actor-headline' \
  --prop text="The one idea" --prop x=4cm --prop y=8cm --prop width=26cm --prop height=3cm \
  --prop font=Georgia --prop size=48 --prop bold=true --prop color=FFFFFF --prop align=center --prop fill=none

# Slide 2 — headline shrinks + moves; new body takes stage
officecli add "$FILE" / --type slide --prop layout=blank --prop background=1E2761 --prop transition=morph
officecli add "$FILE" /slide[2] --type shape --prop 'name=!!actor-headline' \
  --prop text="The one idea" --prop x=1.5cm --prop y=1cm --prop width=12cm --prop height=1.5cm \
  --prop font=Georgia --prop size=24 --prop bold=true --prop color=FFFFFF --prop align=left --prop fill=none
officecli add "$FILE" /slide[2] --type shape --prop 'name=#s2-body' \
  --prop text="Here is the supporting evidence." --prop x=1.5cm --prop y=5cm --prop width=30cm --prop height=2cm \
  --prop font=Calibri --prop size=20 --prop color=CADCFC --prop fill=none

officecli close "$FILE"; officecli validate "$FILE"

(b) Multi-element coordinated morph — Actors / Choreography

Visual outcome. Three scene actors (!!scene-ring, !!scene-dot, !!scene-band) repositioned across 3 slides to feel like a camera pan. Fresh per-slide titles fade in / out via the #sN-* ghost pattern. Use this when the narrative has a continuous visual backdrop.

# Slide 1 — anchor composition (already built via recipe a; here we add actors)
officecli add "$FILE" /slide[1] --type shape --prop 'name=!!scene-ring' --prop preset=ellipse \
  --prop fill=E94560 --prop opacity=0.3 --prop x=5cm --prop y=3cm --prop width=8cm --prop height=8cm
officecli add "$FILE" /slide[1] --type shape --prop 'name=!!scene-dot' --prop preset=ellipse \
  --prop fill=0F3460 --prop x=28cm --prop y=15cm --prop width=1cm --prop height=1cm

# Slide 2 — morph: ring moves + grows, dot slides left (spatial variety ≥ 5cm on both)
officecli set "$FILE" "/slide[2]" --prop transition=morph
officecli add "$FILE" /slide[2] --type shape --prop 'name=!!scene-ring' --prop preset=ellipse \
  --prop fill=E94560 --prop opacity=0.6 --prop x=20cm --prop y=2cm --prop width=12cm --prop height=12cm
officecli add "$FILE" /slide[2] --type shape --prop 'name=!!scene-dot' --prop preset=ellipse \
  --prop fill=0F3460 --prop x=3cm --prop y=16cm --prop width=1.5cm --prop height=1.5cm
# Ghost slide-1 content (name path still resolves after morph — see Known Issues)
officecli set "$FILE" "/slide[2]/shape[@name=#s1-title]" --prop x=36cm 2>/dev/null || true

# Verify morph pair: identical names on slides 1 & 2
officecli get "$FILE" /slide[1] --depth 1 --json | jq -r '.data.results[0].children[]?.format.name // empty'
officecli get "$FILE" /slide[2] --depth 1 --json | jq -r '.data.results[0].children[]?.format.name // empty'
# Compare — `!!scene-ring` and `!!scene-dot` MUST appear on both, byte-identical.
# Note: morph stores names with a `!!` prefix; compare the prefixed forms.

(c) Continuous multi-slide morph (story arc) — use helpers

Visual outcome. A 5-slide arc telling one continuous story: same 2 scene actors drift across the canvas as the narrative progresses; content (#sN-*) refreshes per slide and is ghosted on the next. Building this by hand is ~60 commands — use reference/morph-helpers.py to keep the build script short and auto-verified.

#!/usr/bin/env python3
# Invoke the provided helper library for clone + ghost + verify
import subprocess, sys, os
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
HELPERS = os.path.join(SCRIPT_DIR, "reference", "morph-helpers.py")
FILE = "deck.pptx"

def helper(*args):
    subprocess.run([sys.executable, HELPERS, *[str(a) for a in args]], check=True)

# ... assume slide 1 is built with 2 scene actors (!!scene-ring, !!scene-dot) + #s1-title
# Helper builds slide 2–5 with: clone from previous + apply transition=morph + ghost previous #sN- content
# `clone` prints the cloned slide's shape list — read it to pick which shape indices carry the
# previous slide's #s(n-1)- content, then pass those explicit indices to `ghost`.
for n in range(2, 6):
    helper("clone", FILE, n - 1, n)          # clone + set transition=morph + list shapes (note the #s(n-1)- indices)
    helper("ghost", FILE, n, 1, 2)           # ghost the #s(n-1)- content shapes by index (here shapes 1 & 2)
    # …then add THIS slide's #sN- content via officecli add as normal…
helper("final-check", FILE)                   # structural pass; DOES NOT catch !! lingering in visible area

Helper signatures and source: reference/morph-helpers.py (clone, ghost, verify, final-check). The shell equivalent is reference/morph-helpers.sh — pick one per platform; do not mix.

When to use helpers vs raw officecli. For 2-3 slide decks, raw commands (recipes a, b) are clearer. For 5+ slides with repeating clone/ghost/verify cadence, helpers save ~40% of commands and provide built-in verification. Every slide is still closed by officecli validate before delivery.

(d) Morph + fade hybrid — entrance on morph slide

Visual outcome. A morph pair where !!scene-ring moves continuously while a NEW per-slide card fades in simultaneously. Used when a morph-paired backdrop carries the eye and fresh foreground content needs a softer entrance than a raw appearance.

# Slide 2 already has transition=morph and !!scene-ring. Add a new card with fade-entrance.
officecli add "$FILE" /slide[2] --type shape --prop 'name=#s2-card' --prop preset=roundRect \
  --prop fill=F5F7FA --prop line=none --prop x=2cm --prop y=12cm --prop width=10cm --prop height=5cm

# Apply simultaneous-with-morph fade entrance to the new card.
# 'fade-entrance-300-with' = fade in, 300ms, trigger=withPrevious (plays with the morph transition).
officecli set "$FILE" "/slide[2]/shape[@name=#s2-card]" --prop animation=fade-entrance-300-with
officecli get "$FILE" "/slide[2]/shape[@name=#s2-card]" --json | jq '.data.results[0].format.animation'  # readback sanity — drops the trigger suffix, reads back as "fade-entrance-300"

Why this works. Morph animates the !!scene-* shapes only (they have a pair on slide 1); the new #s2-card has no slide-1 counterpart, so morph would default-fade it — fade-entrance-300-with makes that fade explicit and timed. Keep the animation per pptx v2 floor: ≤ 600ms, no bounce / swivel / fly-from-edge (officecli help pptx animation for the canonical preset list).

Choreography — animation types + staggered timing

How morph animates multiple shapes determines what the audience sees. Pick the right mechanism for each pair: