PPTwise deck generation playbook

PPTwise turns semantic JSON into native DrawingML .pptx files. Text and shapes stay editable in PowerPoint. Authors describe what each page is doing and which typed components it contains. The theme and engine own the page face, geometry, color, type, and decoration.

Use this one-way chain. Do not skip backward or decide two layers at once.

clarify -> gather materials -> outline and theme -> make -> check -> deliver

Run the CLI

Run every command through the launcher bundled beside this file. Replace <skill-dir> with this skill directory.

bash <skill-dir>/scripts/run.sh <args>                                       # macOS / Linux
powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>  # Windows

The launcher tries a compatible pptwise on PATH, then npx, then bunx. It forwards arguments and exit codes unchanged. Exit 78 means no JavaScript runtime was found. Relay the nextSteps from stderr instead of retrying.

If scripts are unavailable, use the first available route:

1. pptwise <args> when the installed version is compatible with the pin: on a 0.x pin, the same major and minor and a patch at or above it. On 1.0 and later, the same major and at or above the pin.
2. npx --yes --package @liustack/pptwise@0.49.0 pptwise <args>.
3. bunx --bun @liustack/pptwise@0.49.0 <args>.
4. Otherwise ask the user to install Node 22.19+ or Bun.

Run pptwise doctor after installation and whenever a failure is not explained by its own error. Relay the result instead of guessing. Content packs are installed at setup, not per deck. When the user has a license, pptwise login <key> is the installation step: it checks the key with the pack server, saves it, and installs the packs. Relay its answer. A key whose purchase is still being reviewed is saved, and pptwise sync installs the packs once the review clears. pptwise sync runs again only when the user asks to update packs, a review clears, the license changes, or pptwise doctor reports packs that can be updated. These are the only commands that write the PPTwise home folder (~/.pptwise), with pptwise logout and config set. Making a deck writes nothing there, so it works in a sandbox whose home folder is read-only. Never run login, sync, or logout as part of a deck task.

Read live truth first

Never write IR or a spec from memory. Run these at the start of each deck task:

pptwise schema --spec
pptwise narratives --json
pptwise themes --json

themes --json lists installed content pack themes with "source": "pack". Each theme row carries its menu: the keys of menu.content are the content kinds it offers. The IR component contract is read per page while making, never whole. See step 4.

Scan the workspace before asking questions, .pptwise/decks/ included: a file search that honours .gitignore skips it. An existing deck.spec.json already records the narrative, bound theme, page order, headings, and content kinds: a change to that deck starts at step 4. A deck-local theme.json, a workspace themes/ file, a named theme, or a supplied .thmx, .potx, or branded .pptx is a theme signal.

Where the user decides

Write every message to the user in the language they wrote in, from the first status line to the final answer. The user decides in two places only: the one round of questions in step 1, and the outline and theme in step 3. Everything else runs without stopping. When the user has said to go ahead without asking ("just do it", "you decide"), skip the questions in step 1, and in step 3 still show the outline and the theme, then keep going in the same reply.

Workflow

1. Clarify the request

Settle four facts: audience, desired outcome, whether the deck will be presented or circulated, and available time. With them, settle the narrative: argument strategy, pacing (how dense the pages are), and audience (the tone). Use a named preset from pptwise narratives --json when it matches. Derive what the request and workspace already say, and ask what is still missing in one round, with ask_user_question when that tool exists. Never ask twice. When the user said to go ahead, infer the rest. Narrative never chooses a page face. See references/spec.md.

2. Gather materials, quietly

Ask the user nothing here. Create the deck folder: .pptwise/decks/<name>/ under the project folder (the folder holding pptwise.config.json, else the working directory), <name> a few lowercase English words joined by hyphens, such as q3-review. Put it elsewhere only when the user names a place. Edit a deck that already exists where it is, and never move it. Run commands from the project folder: deck-dir/ below is the deck's path from there. Then gather two kinds of material:

• Content. Do desk research by default: search the web for the figures, dates, and examples the deck needs, each with its source. When the user's material already holds the content, only add its sources. Never invent a figure.
• Visual. Run pptwise brand scan --json for the project's logo, pictures, brand colors and fonts, and Office templates (see references/branding.md), and plan the picture each page should have (see references/images.md).

Write both into deck-dir/materials.md, in the shape references/materials.md gives. Every later step reads it instead of memory, so the same materials make the same deck. When something changes, change the file first.

3. Outline and theme, settled at once

Write deck-dir/deck.spec.json from the materials. The spec locks narrative, theme, branding posture, footer marks, page order, page type, heading, and the kind of every content page. Bind the theme you would pick for now. A theme file, pack theme, or brand file in the workspace comes first. Otherwise take the factory theme whose occasions and identity in themes --json fit best. Theme names resolve in this order:

1. The deck directory.
2. A workspace themes/ directory while walking upward from the deck.
3. Installed content packs (pptwise packs list).
4. The 24 factory presets.

A deck prints no page number, organization, date, or confidentiality line unless the spec's footer asks for it, see references/branding.md.

• cover, chapter, and ending are page types and do not use kind.
• Every content page requires exactly one explicit kind. Authors write only a semantic kind, never a page face or geometry choice. focus and summary are optional writing hints.
• Unless the user said not to show pictures, at least one content page is a photo page, more when the material has places, products, people, or work to show. Every factory theme draws its picture: pick the theme for the occasion, never for pictures.
• When the user names a page count, the spec has exactly that many pages, the cover and the ending included. Never add or drop pages to get past a check.

Run pptwise spec validate deck-dir/deck.spec.json until it prints OK. A kind the bound menu lacks is a note, not an error: the page is drawn as the nearest offered kind. Keep the kind that tells the truth about the page. Then put three things to the user in one message, with ask_user_question when that tool exists:

1. Outline: one line per page with its number, page type or kind, heading, and what it says. Call pptwise_outline on the deck directory too where it exists.
2. Theme: a wall drawn with the deck's own cover title. Call pptwise_themes with the title, subtitle, and occasion. When the scan found the brand's colors, also pass brand set to its next.brandFlag: the wall then ends with one more option, the first theme repainted in the brand's colors. Offer one option per theme, labelled with its number. Without the tool, draw the same wall and show its SVGs or contact-sheet.html:

pptwise theme try --title "<cover title>" --subtitle "<subtitle>" --occasion <words> --json

Add --brand '<next.brandFlag>' for the brand option. When the user named a theme, show it instead of a wall.

3. Pictures: the direction from the materials, in one line: what the pictures show, and where they come from.

Bind what the user chose. For the brand option, run the theme fork line the wall printed, writing deck-dir/theme.json under the deck's own id, and bind that id. Validate again. The spec is now locked: the theme does not change while the deck is made. Creating and forking themes are in references/spec.md.

4. Make the deck

Write pages/<id>.json in batches of at most four. A page file may contain components, background, image_side, footnote, fields, stamp, tag, ballot, years, stage, and notes. Never repeat type, kind, or heading, because the spec owns them. Choose components that serve the page's kind. quote is a page kind. The quotation component is blockquote. See references/components.md and references/density.md.

Read one page's contract before writing it. inspect prints what the spec locked, the fields the page file may carry, the components the bound theme's face draws there, the counts validate holds the page to, and validate's current findings on it. Expand a component before writing it. When a page runs long, --fit draws it and says whether render would drop anything. Icon fields take a name from pptwise icons. inspect also lists the theme's signature layouts for the page, each with how it looks and a recipe (write: the components, item counts and fields it takes). A page written to a recipe gets that drawing. On a cover, chapter or ending whose face draws over a photograph, the recipe is a background photograph. Write to one when the content you have holds it.

pptwise inspect deck-dir/ --page <id>
pptwise inspect deck-dir/ --page <id> --component <type>
pptwise inspect deck-dir/ --page <id> --fit
pptwise icons

Give the deck pictures, following the picture plan, unless the user said not to: every photo page, the cover and chapter pages where their inspect lists a photograph recipe, and other pages where the picture is the point, never to fill space. Take them in this order: the user's and the project's own, then stock search, then the web, then a local generator when one is enabled. Once a batch is written and before building it, run pptwise asset-brief deck-dir/ for every frame's shape, crop and palette, search with pptwise images search "<two to four English words>" --orientation <shape> --sheet, look at the numbered contact sheet, and pin the number that fits with pptwise images fetch <id> --deck deck-dir/ --as <asset_id>. Where a pptwise_images tool exists, search with it. Pin a project file or a web picture with pptwise images add, which takes a web picture only with the license its own page states. The rules are in references/images.md.

After each batch, build. Use the pptwise_build tool when it exists. Otherwise run:

pptwise build deck-dir/ --json

Each entry in errors names its page, the file and field to edit, and the check's own fix. Fix every error and build again until status is ok. Pages not written yet are reported as such until the last batch. Restructure content instead of deleting what a check caught. The report also gives each page drawn plain the nearest signature recipe: rewrite a plain page to its recipe where its content already holds it. Never invent facts, figures or pictures to fill a recipe.

5. Check what the deck looks like

The build report is the first check: status is ok and no warning is left that you could fix. The second is your own eyes. Build with the sheet, every page drawn small in one numbered picture, and look at it: pptwise build deck-dir/ --json --sheet prints its path as preview.sheet, and pptwise_build with sheet: true shows it to you. Look for three things:

• Pictures: each one shows what its page says, is not a generic stock cliché, keeps its subject inside the crop, and leaves the words over it readable.
• Holes: an empty frame, a page that is mostly blank, a picture the plan wanted and the deck lacks.
• Rhythm: three pages in a row that look the same, text page after text page, chapters that do not match.

Fix what you find in step 4 and look again. Stop after two rounds, and tell the user what you left as it is. references/validate.md has the details.

6. Deliver

pptx in the build report is the deck's one final file, under .pptwise/<deck>/. Deliver exactly that file. Do not run render again, copy, rename, or export another .pptx. On DSH, hand it over with present. Elsewhere, give its absolute path, start pptwise serve deck-dir/ --no-open in the background, and give the address it prints for a live review. Name the pictures that need a credit, from pptwise images list.

The user's changes go back to step 4. When the user asks for another theme, build once with --alternatives (alternatives: true on pptwise_build): it draws the deck's cover and a page or two in three other themes, numbered. The latest build's result lists them with the numbers the card shows: read the number off it, not off files. To switch, change only theme in deck.spec.json and build again. Pages keep their kinds and files: the build lists pages drawn as another kind under drawnAs and warns about what the new faces leave off. When the user asks for other colors without naming one, fork two or three fitting colors, draw them with theme try, and let the user choose before binding.

Add pptwise audit deck-dir/ --pixels when text sits over photo backgrounds. Use render --draft or --allow-dropped-content only when the user explicitly requests that compromise.

Fast component routing

Page intent	kind	Typical component
Ordered reasoning	points	bullets, numbered_cards, paragraph, concept_equation
Reorderable inventory	list	row_cards, icon_cards, people_cards, word_cloud
Side-by-side differences	comparison	comparison, from_to, image_compare, matrix, swot, harvey_balls, venn, positioning_map, pros_cons
Directed steps or time	process	steps, chevron_process, staircase, swimlane, journey_map, flowchart, timeline, roadmap, gantt, cycle, value_chain
Numeric structure	data	chart, data_table, kpi_cards, progress_donuts, scorecard, pictogram, heatmap, sankey
Image as the message	photo	image, image_grid, device_mockup
Author's own proposition	statement	verdict_banner, callout, or no component
Another speaker's words	quote	blockquote
One number as the message	fact	one-item kpi_cards, pictogram, or no component
Claim plus one exhibit	evidence	image, chart, data_table, code, device_mockup, sketch
Containment or levels	hierarchy	architecture, bmc, five_forces, rings, hub_spoke, decision_tree, org_tree, issue_tree, pyramid, iceberg, pillar_model, fishbone, segmented_wheel

Rules

• Never edit or post-process the generated .pptx.
• Never add coordinates, SVG, page face names, or geometry controls to authored content.
• Talk to the user in their language throughout, including progress notes and questions, and keep public deck copy in it too. Keep schema keys and enum values in English.
• Never claim that chart or data_table values are native PowerPoint data objects. They export as editable grouped shapes and text. Change figures in the source and rerender.
• Write the value itself. Never stand in for content with a leftover count or an ellipsis. validate rejects it.
• Never put a picture in a deck whose source does not say it may be used, and never copy one from a page that states no license.
• Preview is read-only. Revisions go back into deck.spec.json, pages/*.json, assets, or the bound theme file.
• When an image generator fails because a sandbox will not let it write its own home folder, run images generate outside the sandbox or ask the user to allow it. Never copy, move, or redirect any login or credential file to get around it.

Read when

• references/spec.md: intent, narrative, theme creation, binding, rebinding, spec, and menu errors.
• references/materials.md: the materials file, desk research, and the picture plan.
• references/layouts.md: choosing among the 11 kind words.
• references/components.md: component ownership, fields, and lookalike choices.
• references/density.md: pacing, capacity, full-page components, and local decoration.
• references/branding.md: brand scan, footer marks (page numbers, organization, confidentiality), deck branding posture, frameless pages, logos, and brand extraction.
• references/images.md: which pages get pictures, where they come from, image assets, stock search and its contact sheet, web pictures and their licenses, source setup, generation, and photo versus evidence.
• references/validate.md: build, the deck sheet and what to look for, assemble, validate, audit, preview, serve, render, and revision loops.