Image to Editable PPT

Overview

.pptx

.pptx

Hard Constraints

• Every source page must be reconstructed by a page subagent, including single-image inputs.
• The main agent does not perform page reconstruction, only orchestration.
• Do not design a parent agent to execute alone, perform sequential degradation, or use low-fidelity degradation mode. Stop if no available page subagent is present, do not proceed to page reconstruction.
• All image generation, image modification, background repair, transparent bitmap assets, and asset sheets must use the

  $imagegen

  skill.
• The default path for

  $imagegen

  is the built-in

  image_gen

  . Do not directly call Image APIs in this skill.
• If a page requires

  $imagegen

  but

  $imagegen

  or the built-in

  image_gen

  is unavailable, stop processing this page and report the blocker, do not forge assets.
• Overlaying editable text on the original full-page

  source.png

  is a failure mode, not a fallback.
• Only basic primitives and simple structural objects can use native PPT shapes. For non-text visual objects with uncertainty, default to using

  $imagegen

  to redraw them into independent assets.
• Page workers must first calibrate the checklist of text font sizes, visual objects, background strategies, and shape corners before writing the manifest; cannot rely on aesthetic guesses for default font sizes or default rounded corners.
• Key states can only be advanced by scripts. Agents cannot manually write JSON to mark pages, imagegen jobs, or runs as completed.

Visible Progress Plan

1. Prepare input and task directories.
2. Dispatch page reconstruction tasks.
3. Reconstruct page objects.
4. Inspect and repair pages.
5. Assemble and validate PPTX.

• Prepare input and task directories

  :

  deck_manifest.json

  ,

  page_jobs.json

  ,

  pages/page_NNN/source.png

  ,

  notes_manifest.json

  exist.

• Dispatch page reconstruction tasks

  : The main agent spawns page subagents in batches according to

  max_concurrent_pages

  ; each spawned page is recorded as dispatched by

  record_page_dispatch.py

  . If subagents cannot be spawned continuously, stop here and report the blocker.

• Reconstruct page objects

  : Each page produces

  manifest.json

  ,

  page.pptx

  ,

  preview.png

  ,

  split_assets_contact.png

  ,

  validation.json

  ,

  page_result.json

  by the page worker.

• Inspect and repair pages

  : All pages are recorded by

  record_page_result.py

  , and the repair queue is cleared; report blockers if repairs are not possible.

• Assemble and validate PPTX

  :

  final/<origin>_edited.pptx

  and

  final/validation.json

  exist.

Default Workflow

1. Run

   prepare_deck_run.py

   to create the run directory, normalize inputs, and generate deck/page manifests and page requests.
2. Run

   page_job_status.py

   to view pending dispatch pages, active dispatches, and available dispatch slots.
3. The main agent spawns regular Codex worker subagents in batches according to

   max_concurrent_pages

   ; do not spawn more than the runtime concurrency limit at once.
4. Immediately run

   record_page_dispatch.py

   to record the dispatch after spawning.
5. Each page worker only works within its own page directory, completing page-level build, preview, contact sheet, and validation.
6. After the page worker returns, the main agent runs

   record_page_result.py

   to check files, paths, and hashes, and advance the page state.
7. Run

   page_job_status.py

   again; if there are pending/repair_needed pages, continue dispatching the next batch.
8. If there are page issues, run

   queue_page_repairs.py

   to generate repair items, then dispatch repair workers in batches.
9. After all pages are accepted, run

   finalize_deck_run.py

   to assemble the final PPTX, copy notes, and run deck validation and QA summary.

prepare_deck_run.py

Generation Delegation

$imagegen

${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md

$imagegen

$imagegen

• Text, icons, or foreground objects on complex backgrounds, requiring source-preserving foreground removal + localized background restoration.
• Icons, pictograms, badges, stickers, hand-drawn marks, stylized arrows, decorative symbols, etc., that need to be treated as independent assets.
• Need to generate chroma-key asset sheets, then perform local background removal, segmentation, and transparency processing.
• Need targeted repair of a clean base or a foreground asset.

imagegen-jobs.json

$CODEX_HOME/generated_images/...

$imagegen

background_strategy

Subagent Dispatch

• Absolute paths of run dir, page id, page dir, and source image.
• Allowed write scope: Only the current page dir can be written to.
• Prohibited write scope: Deck manifest, notes manifest, final deck, other pages.
• Required references:

  page-decision-tree.md

  ,

  imagegen-integration.md

  ,

  manifest-schema.md

  ,

  qa-rubric.md

  .
• Required reading of

  $imagegen/SKILL.md

  .
• Required outputs and return format.

prompts/page-worker.md

Rules

• Text: All readable text should become visible native PPT text boxes. Hidden, transparent, 1 pt, off-canvas, or metadata-only text does not count as editable text.
• Font size: First estimate based on source glyph height, container height, and peer density, then compare with preview for scaling; when uncertain, use a smaller size rather than a larger one. The manifest must record

  quality_checks.font_size_calibrated=true

  .
• Structure: Only basic primitives can use native PPT shapes, such as lines, rectangles, circles, table lines, axes, simple bar blocks, and basic containers. Rectangular containers default to using

  rect

  ; only use

  roundRect

  if the source clearly has rounded corners, and record

  source_corner_radius_px

  or

  corner_reason

  .
• Foreground: Icons, pictograms, logo-like marks, hand-drawn marks, stickers, badges, complex arrows, and decorative elements default to being redrawn into independent assets using

  $imagegen

  . If small visual objects in the source image require high consistency, have no readable text, and redrawing would change their identity, they can be cropped as independent source-derived raster assets and their source areas recorded; this is not a full-page screenshot fallback.
• Background: Solid colors, simple gradients, regular grids, and ordinary cards can be reconstructed natively or via scripts; when complex photos, textures, or illustrations are occluded by foreground objects, use

  $imagegen

  for inpainting/restoration.
• Asset sheet: Default to using sparse chroma-key asset sheets to reduce the number of image generation times. Prioritize element spacing; cannot be crowded, stuck together, or have overlapping projections.
• Provenance: Each final raster asset must have a source record. Do not treat original source crops as default visual assets.
• QA: Deterministic validation is necessary but not sufficient. Must check

  preview.png

  and

  split_assets_contact.png

  .
• Repair: Repair the minimum failed scope. Do not reconstruct the entire page for a single text box or icon.
• State: Key states in

  page_jobs.json

  and

  imagegen-jobs.json

  must be advanced by scripts.

Acceptance Criteria

• The output is a valid

  .pptx

  file.
• Single image input outputs 1 page; multiple images output 1 page per image; page N of PDF corresponds to page N of output; page N of PPT/PPTX corresponds to page N of output.
• PPT/PPTX speaker notes are copied as-is per page, without translation, summarization, or rewriting by page workers.
• Each page has

  manifest.json

  ,

  page.pptx

  ,

  preview.png

  ,

  split_assets_contact.png

  ,

  validation.json

  ,

  page_result.json

  .
• Each page has records of source image size, text inventory, object decisions, asset provenance, and known limits.
• Each page is recorded as dispatched by

  record_page_dispatch.py

  and the result is recorded by

  record_page_result.py

  .
• The final deck has

  final/<origin>_edited.pptx

  and

  final/validation.json

  .
• If a blocker occurs, the final response must explain the blocker stage, evidence path, and reason for incompletion; cannot be called a normal completion.

Reference Map

• references/architecture.md

  : Responsibility boundaries, run/page directory structure, owner principles.

• references/state-machine.md

  : Run/page/imagegen state machine and script advancement rules.

• references/subagent-contract.md

  : Prompt contracts and return formats for page workers and repair workers.

• references/imagegen-integration.md

  : How to combine

  $imagegen

  , including clean base, asset sheet, transparency processing, and recording.

• references/page-decision-tree.md

  : Page analysis, background strategies, foreground/structural object boundaries.

• references/manifest-schema.md

  : First version of deck/page/imagegen JSON schema.

• references/qa-rubric.md

  : Structural, text, asset, background, and visual QA standards.

• references/repair-policy.md

  : Repair queue, minimum rework scope, and blocker determination.

• references/script-contracts.md

  : Script responsibilities, inputs/outputs, and allowed callers.

• prompts/page-worker.md

  : Prompt for regular page reconstruction workers.

• prompts/page-repair-worker.md

  : Prompt for page repair workers.

• prompts/imagegen-clean-base.md

  : Prompt for clean base generation/editing.

• prompts/imagegen-asset-sheet.md

  : Prompt for sparse asset sheet generation.

• prompts/imagegen-repair.md

  : Prompt for targeted imagegen repair.