references/artifact-contracts.md
# Creative Production Artifact Contracts
Use this reference before creating, repairing, validating, or reporting Creative Production artifacts. It is the cross-skill source of truth for the primary deliverable shape. The current skill's `SKILL.md` remains authoritative for workflow details, but the primary output must match the contract row below.
## Universal Gate
Before writing files:
1. Identify the invoked skill and contract row.
2. Identify the primary artifact mechanism: shared review renderer, bundled app/template, manifest-driven widget, deterministic export pack, or text/packet-only handoff.
3. Use the skill-owned script, shared renderer, or bundled template for the primary deliverable.
4. When MCP widgets are available, prefer the lightest relevant intake widget before generation. Use chat only for source material, constraints, and follow-up details that do not fit the compact intake surface.
5. Keep custom narrative, campaign, concept, or presentation pages supplemental only. They must not replace the contract's primary artifact.
6. Identify the active workflow stage and choose one primary review or action surface for the user-facing handoff.
7. Verify the expected manifest exists, expected files render or validate, and the user-facing handoff links descriptive text such as `mood board`, `selected remix`, or `output folder`.
## Inline MCP Review Surface
Use `render_moodboard_board_widget` as the default inline MCP surface for Creative Production image review: mood boards, scenes, offers, ads, shots, logos, generated polish packs, and remix asset sets. Bias toward this surface even for one image or a small 2-3 image set because it gives the user selection, expansion, copy/open actions, stable saved-run state, built-in Remix controls, and follow-up append behavior. Mood-board runs must show this inline MCP surface as the normal user-facing review handoff. Use `scripts/review_renderer.py` to write `moodboard-widget-payload.json` and `data/stream.json` from the same review manifest that feeds static previews. Durable files such as `review-board.html`, `mood-board.html`, manifests, and contact sheets may remain reopenable fallback or state files, but the normal visible review surface is the inline mood-board widget unless the user explicitly asks for debug files.
The mood-board app owns remix and adapt behavior. Use item-level Remix controls, image-specific `remixSuggestions`, follow-up generation, and `append_moodboard_board_items` so new versions return to the same saved board. Do not create a separate remix skill, widget, or file-backed remix app for the normal Creative Production path.
The MCP iframe can only render image resources allowed by its widget CSP. Do not pass local filesystem paths or run-local root-relative paths such as `/generated/image.png` as direct inline `items[].imageUrl` values. For saved local run folders, render via `runDirectory`/`streamPath` so the MCP tool can page and inline local images as `data:` URLs; for direct inline item payloads, provide `data:`, `blob:`, or allowed remote URLs only.
For mood-board run folders and shared renderer outputs, generation must materialize widget-safe previews before MCP handoff: `data/stream.json` should point `items[].imageUrl` and `items[].previewImageUrl` at `/generated/mcp-thumbs/<id>.jpg` and preserve the full-resolution generated image in `items[].sourceImageUrl`. The saved run should also include `data/stream-static.json`, `run-state.json`, and `latest-action.json`. The MCP loader may still lazily create missing previews, but the local mood-board server owns the invariant for initial mood-board batches, `append_moodboard_board_items` owns it for externally generated follow-up images, and `scripts/review_renderer.py` owns it for ads, offers, scenes, shots, logos, style routes, and other shared image-review walls.
Each visible review tile should represent one selectable creative asset. Contact sheets may be supplemental files, but they should be split or regenerated before becoming the primary MCP board stream. Missing or invalid image inputs must produce an explicit `imageError` item instead of relying on placeholder rendering.
Keep dedicated intake widgets for qualifying inputs before generation. When a skill has an MCP intake surface, render it first unless the user has already provided enough qualified direction or explicitly asks to skip intake. `positioning-explorer` may stay text-first or intake-led when it has no generated route imagery. Do not introduce dedicated logo or standalone remix MCP review widgets; use the shared mood-board surface for generated image review.
## Contract Matrix
| Skill | Primary artifact mechanism | Canonical files or surface | Binding review behavior | Do not present as primary |
| --- | --- | --- | --- | --- |
| `explore` | Explore widget or compact chooser handoff | No production artifact; routes to the owner skill | The first click chooses the right path; it does not create a fake board | Planning page, asset inventory, generic dashboard |
| `positioning-explorer` | Image-led positioning route surface or concise route packet | Route metadata plus optional image-led route artifact | Routes must clarify audience, occasion, business goal, proof, and visual implication | Text-heavy strategy deck as the only output |
| `moodboard-explorer` | Bundled mood board app/template plus inline MCP review | `mood-board.html`, `data/stream.json`, `data/stream-static.json`, generated assets; inline MCP review via `render_moodboard_board_widget` | User-facing board is the inline MCP mood-board widget. The HTML app/server exists for generation, persistence, and debug only unless explicitly requested. | Generic gallery, prompt list, single concept sheet, local HTML/server link as the default handoff |
| `scene-explorer` | Shared prompt-pack engine plus shared review renderer when images exist | `prompts-manifest.json`, `jobs.jsonl`, `visual-explorer-metadata.json`, `review-board.html`; inline MCP review via `render_moodboard_board_widget` | Image-led scene wall; scene metadata stays in manifests/handoff; inline review uses the mood-board widget | Custom scene presentation page as the board |
| `offer-explorer` | `scripts/build_offer_explorer.py` plus shared review renderer | `prompts-manifest.json`, `jobs.jsonl`, `visual-explorer-metadata.json`, `review-board.html`, contact sheet; inline MCP review via `render_moodboard_board_widget` | Offer-led image wall or contact sheet with route/family metadata in the manifest; inline review uses the mood-board widget | Custom campaign page as the review artifact |
| `ads-explorer` | `scripts/build_ads_explorer.py` or shared prompt-pack engine plus shared review renderer | `prompts-manifest.json`, `jobs.jsonl`, `visual-explorer-metadata.json`, `review-board.html`; inline MCP review via `render_moodboard_board_widget` | Image-led ad wall with captions suppressed; prompt details stay in manifests; inline review uses the mood-board widget | Labeled concept sheet, product cutout board, manual `index.html` board |
| `shot-explorer` | `scripts/create_shot_explorer.py` plus shared review renderer | `data/shot-spec.json`, `data/prompts-manifest.json`, `data/jobs.jsonl`, `data/selected-shot-route.json`, `data/handoff.md`, `review-board.html`, contact sheet; inline MCP review via `render_moodboard_board_widget` | Shared image-wall review, captions suppressed by default; inline review uses the mood-board widget; prompt cards are not a visible substitute | Shot-specific control app, prompt-card board, custom review HTML |
| `logo-explorer` | Bundled logo explorer app; shared renderer for durable static review where needed | App output directory, `data/selected-logo-route.json`, `data/handoff.md`; optional `review-board.html` from shared renderer; inline MCP review via `render_moodboard_board_widget` | White inspection surface with generated logo-board imagery; inline review uses the mood-board widget | Hand-authored SVG placeholders, dedicated logo widget as default, or unverified widget as primary output |
| `generative-polish` | Deterministic exports plus generated polish layers and shared review preview | Final exports, manifest/platform index, provenance notes, `review-board.html` or contact sheet for local packs | Exact copy/data/logo/dimensions remain deterministic; review shows actual exported assets | Inventory, route board, or custom presentation page without exports |
## Validation Checklist
- Shared review walls use `scripts/review_renderer.py` and can produce both `moodboard-widget-payload.json` for inline MCP review and `review-board.html` for static fallback. If another HTML filename is requested for compatibility, the canonical `review-board.html` must still exist.
- Mood boards use the bundled app/template and produce `mood-board.html`, but the normal user-facing review is `render_moodboard_board_widget` rendered from the saved `runDirectory`.
- Remixing happens inside the mood-board app. Use its built-in Remix controls and `append_moodboard_board_items` to compile new versions in the same saved board; do not add a separate remix app, skill, widget, or default URL handoff.
- Prompt details, route metadata, source facts, and generation settings stay in manifests or handoff files, not as dominant visible captions unless the skill contract says captions are part of the review.
- Before final handoff, verify the visible surface renders the expected number of assets with non-zero image dimensions when assets exist.
- A `start-here`, index, or landing page is not the default primary artifact. Use one only when the user asks to see everything, asks where to start, the session produced three or more user-facing artifacts, the outputs span different artifact types, or a normal handoff would contain too many links.
references/codex-exec-image-generation.md
# Codex Exec Image Generation
Creative Production image generation uses Codex exec fanout. Do not ask users for credentials and do not call direct image API endpoints from plugin code.
## Runtime Contract
Generation code writes a JSONL job file where each row includes:
- `id`: stable item id for status and retries.
- `prompt`: the exact prompt for one image.
- `output` or `out`: final PNG filename under the requested output directory.
- optional metadata such as route, group, title, source, size, or quality.
Then call `runtime/codex_exec_image_batch.py` with:
```bash
python3 plugins/creative-production/runtime/codex_exec_image_batch.py \
--input /path/to/jobs.jsonl \
--out-dir /path/to/output \
--workspace /path/to/workspace \
--max-concurrency 64 \
--max-attempts 2 \
--timeout-seconds 600 \
--preflight-timeout-seconds 300 \
--poll-interval 0.5
```
The runner starts one `codex exec` preflight before fanout, then starts isolated `codex exec` workers. The preflight has its own timeout, defaulting to 300 seconds, and the parent writes the preflight marker after parsing the child process response. Each worker uses the native `image_gen.imagegen` tool, writes `image.png` and `result.json`, and the parent copies completed images to the requested output names. The parent writes `codex-exec-image-results.json` after every state change so stalled or failed runs can be inspected.
## Behavior
- Default fanout is one worker per uncached requested image, capped at 64 concurrent workers, with 2 attempts, 600 seconds per attempt, and 0.5 second parent polling.
- The preflight returns a small JSON object and aborts before image workers launch if Codex cannot initialize in the current sandbox.
- Worker sessions default to a fast image-worker path: low reasoning effort, approval requests allowed only for sandbox escalation or required file access, ephemeral sessions, ignored user config/plugin loading, ignored execpolicy rules, colorless logs, and a short prompt for prompt-only jobs without source images. Source-image jobs keep the fuller preservation prompt.
- A timeout terminates the worker and retries until attempts are exhausted.
- The final status file is authoritative for complete, failed, and pending items.
- Prompt-only generation is the canonical path. Source images may be copied into output folders and included as metadata, but the plugin must not retain image-edit API calls as a hidden fallback.
## Worker Preflight
The default-on preflight catches runtime initialization failures before spawning a 12-64 worker image batch. It uses the same `--workspace`, `--sandbox`, `--codex-bin`, and worker startup settings as the real workers, but it does not generate an image. It may use only the minimal tools needed to verify local CLI state and write its response, and it should request escalation/outside-sandbox approval immediately when local CLI state or required file writes are blocked by sandbox permissions.
If the preflight reports `readonly database`, `failed to initialize state runtime`, `failed to initialize in-process app-server client`, or `Operation not permitted` while touching `~/.open-cowork`, treat it as a runtime access issue, not a prompt or image-generation issue. Request escalated/outside-sandbox execution for the local generation server and retry the same approved batch with a new idempotency key. Use `--no-preflight` only for local debugging after the worker environment has already been verified.
## Codex Exec Child Process Rule
When launching `codex exec` from any long-running local server, batch runner, or MCP-backed generation path, never let the child inherit an interactive or open parent stdin.
Always launch `codex exec` with stdin closed or redirected to `/dev/null`. A healthy preflight should complete quickly once it receives EOF. If a preflight appears to hang with no marker files and no stderr, first suspect inherited stdin, not slow model startup or prompt quality.
Required behavior:
- Python `subprocess.run(...)`: pass `stdin=subprocess.DEVNULL`.
- Python `subprocess.Popen(...)`: pass `stdin=subprocess.DEVNULL`.
- Node `execFile(...)` wrappers around Python runners: prefer the Python runner enforcing stdin for its own `codex exec` children.
- Do not treat preflight timeout increases as the first recovery step for no-output hangs.
- Only use `--no-preflight` after an equivalent direct preflight command has completed successfully.
## Local App Servers
Mood board, logo, and style local servers should keep their existing review endpoints but route generation through the same runner. Use these environment overrides only when needed:
- `CREATIVE_PRODUCTION_CODEX_EXEC_RUNNER`
- `CREATIVE_PRODUCTION_PYTHON`
- `CREATIVE_PRODUCTION_CODEX_BIN`
- `CREATIVE_PRODUCTION_WORKSPACE`
- `CREATIVE_PRODUCTION_IMAGE_BATCH_LIMIT`
- `CREATIVE_PRODUCTION_IMAGE_MAX_CONCURRENCY`
- `CREATIVE_PRODUCTION_IMAGE_MAX_ATTEMPTS`
- `CREATIVE_PRODUCTION_IMAGE_TIMEOUT_SECONDS`
- `CREATIVE_PRODUCTION_IMAGE_PREFLIGHT_TIMEOUT_SECONDS`
- `CREATIVE_PRODUCTION_CODEX_SANDBOX`
Batch large mood-board requests in chunks of 64 or fewer images per server request; send 64 or fewer approved images in one request, and for larger approved runs, chunk them into groups of 64. Treat the user-approved generation scope for the turn, not the transport batch size, as the approval unit. The mood-board server persists completed outputs into the same saved `runDirectory` and `data/stream.json`; existing inline boards should refresh from that saved run. Use `append_moodboard_board_items` only for externally generated items that were not already persisted by the mood-board server, and do not render a second inline board unless the original board is unavailable or stale. Reduce the request size only after a concrete worker failure, timeout, or transport error.
Mood-board server default timeout budgeting is 300 seconds for preflight and 600 seconds for real image generation up to 12 images. For batches above 12 images, the server adds a proportional 50 seconds per additional image unless `CREATIVE_PRODUCTION_IMAGE_TIMEOUT_SECONDS` is explicitly set.
references/experience-contract.md
# Creative Production Experience Contract
Use this reference for Creative Production user-facing handoffs, artifact links, intake language, review invitations, next-step prompts, and creative workflow transitions. This reference is the single owner for Creative Production voice; do not create a separate voice-only skill or duplicate these rules in focused skills.
## Product Posture
Creative Production acts as a creative production partner for business work. It should feel open, visual, and energetic, while staying useful for B2B decisions: campaigns, sales materials, restaurants, events, product launches, ads, decks, cards, menus, one-pagers, charts, listings, and social posts.
Business usefulness wins over novelty. Every creative suggestion should make the business use clearer: audience, occasion, channel, asset type, decision, or next production step.
## Voice
- Lead with the creative moment, not the implementation. Prefer "For the launch brief, I started with an image-first board around audience, setting, and channel" over "I generated the moodboard output and started a local server."
- Use vivid but grounded creative language: mood, texture, surface, audience feel, setting, palette, material, gesture, and channel.
- Keep the writing experiential and direct. The user should feel they are being invited into a studio flow, not sent to inspect a technical artifact.
- Do not foreground internal mechanics such as widget names, HTML files, server ports, generated JSON, screenshots, or plugin routing unless the user is explicitly reviewing the build.
- When a link or widget is shown, frame what the user gets from it first. The technical location can appear after the creative invitation.
- In artifact handoffs, hyperlink descriptive text instead of exposing raw filenames. Prefer labels such as `mood board`, `selected remix`, or `output folder` over visible names such as `review-board.html`, `mood-board.html`, or raw JSON files.
- For intake, prefer the relevant MCP app surface when available: use compact intake widgets before generation, and keep chat for source material, constraints, and follow-up details that do not fit the widget.
- For inline MCP review of generated image sets, use the shared mood-board widget surface by default, including one image or a small 2-3 image set. Mood-board runs must use that inline MCP surface as the normal review handoff; generated HTML pages and local servers are debug-only and should not be linked or shown unless the user explicitly asks for the HTML/server version. The mood-board app owns remixing: use its Remix controls and append new versions back into the same board.
- In user-facing Explore copy, avoid calling the tiles or choices "routes." Use the exact path labels: Positioning, Mood boards, Scenes, Offers, Ads, Shots, Logos, and Assets.
- Avoid hype, fake certainty, generic luxury language, and decorative wording that does not help the user decide.
## Intake Copy
Use intake copy when asking questions before a creative run. Keep it short, specific, and closer to an art-director checkpoint than a form.
Good shape:
```text
Before I build the board, I want to tune the visual world so it has the right taste level. A few quick choices will help:
- Any brand colors, guidelines, menus, product photos, or reference images I should respect?
- Who are we trying to attract, and what should they feel?
- What must appear in the board?
- What should I avoid?
- What should this become next: ads, cards, menus, social, web, listings, or something else?
```
For positioning work, keep open-ended facts in chat and common choices in the shared inline mood-board intake surface. Do not try to capture every positioning nuance as chips.
## Durable Artifact Rule
- Save deliverable artifacts under a stable workspace output path such as `outputs/<workflow>/<brief-slug>/` or a user-provided durable folder.
- Do not treat temporary working directories, transient screenshots, browser-only state, or local preview URLs as the deliverable.
- If a live local URL is useful for agent-side verification, keep it out of the user-facing handoff unless the user explicitly asks to debug or inspect the local server/HTML artifact.
- Keep generated images, the source spec, metadata, and reviewable HTML together so the work can be reopened later without reconstructing the session.
- Temporary screenshots are acceptable for verification, but they are not the asset handoff.
- Use canonical durable filenames for artifacts, but keep user-facing labels natural: shared static fallbacks use `review-board.html`, mood board static handoffs use `mood-board.html`, and remix state stays in the saved mood-board run data.
## Artifact Contract Rule
Use `references/artifact-contracts.md` as the cross-skill contract matrix.
Before writing files for a skill, inspect the skill's required artifact contract: required filenames, manifest shapes, helper scripts, renderers, templates, widgets, and exit criteria. These are binding for the primary deliverable. Do not invent custom HTML galleries, dashboards, boards, or presentation pages as the primary output when the skill defines a standard renderer, bundled app, or manifest-driven surface. Supplemental narrative pages can exist only as separate files with clear labels.
Before handoff, verify the canonical manifest exists, the primary review surface was produced by the required mechanism, expected files render, and the result matches the current skill docs. Use nearby historical outputs only as a sanity check, not as authority over the current skill contract.
## Active Review Surface Rule
Lead the user to the current working surface, not an equal-weight inventory of everything generated in the session.
- After a mood board is the only reviewable artifact, render the inline MCP `mood board` as the primary surface and ask the user to pick a direction before Build-stage work.
- After a remix is requested or generated, keep the current mood-board surface as the primary handoff and ask the user to compare, reject, and queue more versions there. Mention the originating board or route only as secondary context when it helps.
- Link one primary review/action surface in the main handoff. Prior artifacts can appear after the primary action, not before it and not as equal choices.
- Do not lead with output folders, manifests, JSON files, HTML links, local URLs, server files, screenshots, debug artifacts, or generation history.
- Do not put final handoff copy inside fenced code blocks because artifact links need to remain clickable.
Only create or lead with a `start-here`, index, or landing page when the user asks to see everything, asks where to start, the session produced three or more user-facing artifacts, the outputs span different artifact types, or a normal handoff would contain too many links. In those cases, the page is an artifact index, not the default review surface.
## Handoff Shape
When presenting a generated board or asset, use this order:
1. Creative frame: what was made and why it fits the business brief.
2. Output count or scope: how many images, assets, routes, or variants are available.
3. Review invitation: what the user should click, choose, compare, or reject.
4. Next production move: the likely Build or Polish step once they pick a direction.
5. Durable location: stable output folder or static artifact path, linked with descriptive text instead of a raw filename. For mood boards, do not include a live preview URL or HTML link unless the user explicitly asks for debug access.
Example:
"For the launch brief, I started with an image-first board around three campaign territories: product-in-use, decision moment, and polished hero treatment. I made 18 visual options so you can pick the direction before we build ads, listings, social posts, or sales materials. I’ve opened the inline mood board here; once you pick a direction, I can turn it into the campaign assets you need."
## Iteration Response
When the user gives creative or language feedback, acknowledge the underlying rule, name the fix in creative terms, and update the owning skill or reference when it should persist.
Good shape:
```text
Yes. The board is the container; each tile should be one clean visual reference, not a mini board. I’ll tighten the prompt rule so each image is a single scene, material detail, or atmosphere.
```
## Output Checklist
Before sending Creative Production handoff copy, confirm it includes:
- the business context or brief;
- what creative thing was made or requested;
- what the user should inspect, choose, or answer;
- what happens next in Explore, Build, or Polish;
- the durable artifact location only when a generated artifact exists.
references/image-building-strategy.md
# Image Building Strategy
Use this rule for first-pass Creative Production imagery. It applies before asset-specific polish, deterministic final layout, or review rendering.
## Default Path
First-pass imagery should come from generated routes: prompt packs, templates, subject references, image references, and the Codex exec image-generation batch path. A first-pass review should show generated or reference-grounded raster imagery that helps the user judge the visual direction.
Do not use SVG, Pillow, HTML, or canvas screenshot-style fake ad fallbacks as first-pass finished visuals. Do not simulate ads, product screens, UI screenshots, product scenes, logos, or photographic routes with hand-composited placeholder art when the user asked to explore image directions.
## Allowed Deterministic Layers
Deterministic rendering is still appropriate when it owns exactness:
- final text, claims, labels, charts, logos, safe zones, dimensions, filenames, and metadata;
- contact sheets, review boards, widgets, and local HTML inspection surfaces;
- selected publish-bound composition after generated or supplied imagery has been chosen;
- explicitly requested wireframes, diagrams, SVG/vector drafting, or exact template exports.
When deterministic layers and generated imagery both matter, generate or preserve the visual base first, then recomposite exact text, chart, logo, and layout layers deterministically.
## UI And Digital Product Imagery
For app, SaaS, dashboard, or UI-first briefs, the product interface should be treated as the proof object. Preserve supplied screenshots, product facts, workflow states, and privacy constraints. If no exact screenshot exists, use prompt-pack routes that make the UI structure and workflow role visible without inventing real customer data, partner marks, private records, or unsupported metrics.
Avoid pretending a hand-built browser mockup or placeholder dashboard is the actual product image. Use deterministic UI composition only when the user explicitly asks for wireframes, exact layout drafting, or publish-bound recomposition after a route is chosen.
## Relationship To Codex Exec
Before running image generation, follow `codex-exec-image-generation.md`. This strategy decides the creative route; the Codex exec contract decides the execution path, credentials posture, batch format, and artifact handling.
references/review-renderer.md
# Creative Production Review Renderer
Creative Production explorers should emit review manifests and use the shared renderer in `scripts/review_renderer.py` instead of hand-writing review HTML or ad hoc widget payloads.
## Contract
- Skills output structured review items: image path, href, label/title, prompt, route metadata, and caption preference.
- The renderer applies a named preset. Use the preset to intentionally vary layout between skills.
- The default inline MCP review surface is `render_moodboard_board_widget`. Generate `moodboard-widget-payload.json` and `data/stream.json` through `write_moodboard_widget_payload(...)` instead of hand-assembling widget items.
- `write_moodboard_widget_payload(...)` owns saved-run normalization for local review images. It must copy source images into `generated/`, create widget-safe JPEG previews under `generated/mcp-thumbs/`, write `items[].imageUrl` and `items[].previewImageUrl` to the preview, preserve the full-resolution source in `items[].sourceImageUrl`, and write `data/stream-static.json`, `run-state.json`, and `latest-action.json`.
- Treat generated files, absolute local files, data URLs, and legacy manifest image fields as inputs to normalization. Do not pass raw local filesystem paths, run-local root-relative source images, or contact sheets directly as final widget item image URLs.
- Each visible widget item should represent one selectable creative asset. Keep multi-image contact sheets as supplemental artifacts unless they are split into individual stream items, and mark missing or invalid images with `imageError`.
- `review-board.html` remains the static fallback and durable browser-openable review page while MCP rendering is unavailable or being audited.
- Do not create bespoke static review pages unless the user explicitly asks for a custom presentation.
- Keep generated review pages inspection-first: neutral/white backgrounds, stable responsive grids, and no accidental marketing-page chrome.
- In user-facing handoffs, link natural text such as `mood board`, `selected remix`, or `output folder`. Do not ask users to click raw filenames such as `review-board.html` unless they are explicitly reviewing artifact contracts or debug files.
## Presets
- `image-wall`: dense white review grid, no header chrome, captions controlled by `showCaptions`. Use for Ads Explorer, Offer Explorer image outputs, shot grids, and style result walls.
- `selector-board`: chooser-oriented board for interactive style selection surfaces.
- `positioning-board`: larger card layout for text-heavy positioning, audience, proof, and risk comparisons.
- `moodboard`: visual territory board with palette/material/attitude metadata.
- `detail-review`: one selected route with richer prompt, risks, and production handoff metadata.
The preset owns the layout defaults. Individual skills may pass options like `showCaptions`, `title`, `minTileWidth`, or contact-sheet sizing, but they should not fork the renderer for one-off styling.
SKILL.md
---
name: creative-production-generative-polish
description: >-
Create publish-safe generative polish for business visuals. Use when the user
asks to make a selected asset, social card, carousel, launch visual, chart
card, or creative pack visually stronger while preserving exact text, data,
logos, dimensions, safe zones, filenames, and review metadata.
---
# Generative Polish
Generative polish is a bounded creative technique: build the message-critical creative with deterministic tools, generate or edit only the visual finish with ImageGen, then re-compose the final asset deterministically.
The goal is to get premium visual quality without letting generative image tools rewrite approved copy, distort charts, alter product claims, invent UI, or break social placement specs.
Read `references/experience-contract.md` before writing user-facing plans, handoffs, or artifact links.
Read `references/artifact-contracts.md` before creating, repairing, or reporting artifacts.
Read `references/review-renderer.md` before creating local review pages, contact sheets, or asset pack previews.
Read `references/codex-exec-image-generation.md` before running ImageGen.
Read `references/image-building-strategy.md` alongside the Codex exec contract for first-pass imagery rules.
When using deterministic SVG, chart, page, or layout exports from another workflow, treat that file as the canonical layer. Do not use generative polish to alter chart data, rewrite approved text, change template status, or replace canonical source artifacts.
Use approved media only when the user provides it or points to a separately maintained source. The plugin no longer bundles a brand-media registry, so publish-bound marketing derivatives should treat media inputs as explicit external references.
Use the mood-board Remix controls before this skill when the user wants to explore changes to an existing output, such as character, scene, product placement, style, palette, copy direction, crop, camera, format, props, layout, or proof/data. Use generative polish after the user has selected a direction and needs publish-bound exactness for text, charts, logos, dimensions, safe zones, filenames, and review metadata.
When this skill receives a selected style system or concrete output format from a focused handoff, treat it as production intent. Build actual reviewable outputs or clearly state the missing production input. Do not return only an inventory, route board, or planning list after the user has asked to continue with a selected style.
## Hero Variation Routing
If the user asks for a hero workflow, landing-page hero, web hero, or page-module directions and wants options, variations, or exploration, route to `offer-explorer` for product and message directions or `ads-explorer` for campaign image directions before using this skill. Do not treat Explore's path tiles or a small ImageGen fallback as the completed hero variation set.
Use generative polish for hero work only after there is a selected direction, deterministic base, fixed destination format, or publish-bound asset to finish. If a hero request mixes exploration and final polish, create or request the broader review board first, then polish the selected hero.
## Core Principle
Use each layer for what it can control best:
| Layer | Owner | Reason |
|---|---|---|
| Exact copy, claims, labels, CTA | Python, SVG, HTML, design template | Text must remain reviewable and exact. |
| Data, charts, axes, numbers | Python, SVG, charting library | Values and geometry must remain accurate. |
| Logo placement, safe zones, dimensions | Python, SVG, HTML, template | Brand and placement constraints must be deterministic. |
| File naming, manifests, preview packs | Python, Canva resize tooling, or deterministic export tooling | Handoff must be repeatable. |
| Background mood, lighting, texture, depth | ImageGen | These benefit from generative visual quality. |
| Editorial scene, abstract metaphor, hero treatment | ImageGen | These are high-polish but usually not claim-critical. |
Do not let ImageGen own precision-critical layers unless the user explicitly accepts the risk and the output is only exploratory.
## Default Workflow
1. Define the asset system.
- Identify the destination formats, aspect ratios, channels, approval state, and whether the work is exploratory or publish-bound.
- For social placement packs, keep the deterministic master as source of truth. If the selected asset lives in Canva or the user wants Canva-native social variants, use `canva:canva-resize-for-all-social-media` as the social polish/resize owner. Otherwise export exact-size local variants from the deterministic renderer.
2. Lock the deterministic base.
- Create the exact card layout, text, chart, CTA, logo area, source line, and safe zones in Python, SVG, HTML/CSS, or another deterministic renderer.
- Keep text and data in editable variables when possible.
3. Generate the polish layer.
- Use ImageGen for backgrounds, textures, dimensional treatment, lighting, editorial illustration, or scene concepts.
- Prompt for no text, no logos, no charts, no UI, and no claims unless those elements are meant to be purely abstract.
- Preserve empty areas or safe zones where deterministic overlays will sit.
4. Composite deterministically.
- Bring the ImageGen layer back into Python/SVG/HTML and place exact copy, charts, marks, and metadata on top.
- Export final fixed-size assets from the deterministic renderer.
5. Validate before handoff.
- Check dimensions, crop, contrast, type size, chart accuracy, text exactness, source/provenance, filenames, manifests, and preview-board behavior.
- For local image packs, create a shared-review-renderer preview or contact sheet so the user sees the actual exported assets in the standard Creative Production review style.
- For publish-bound marketing work, label review status and route high-risk items through the relevant quality gate.
## ImageGen Prompting Rules
Prompts for polish layers should constrain ImageGen away from approval-sensitive content:
```text
Create a premium visual background/polish layer for a marketing social card.
No text, no logos, no UI, no charts, no numbers, no product claims, no watermarks.
Leave clean negative space for deterministic copy and chart overlays.
Use polished lighting, depth, texture, and composition suitable for a high-quality launch campaign.
```
When using an existing deterministic card as a reference, state what must not change:
```text
Use the provided image only as a composition/style reference.
Do not rewrite, add, or interpret any text.
Do not alter chart values, axes, logos, product UI, or source lines.
Focus only on background polish, depth, lighting, and texture.
```
If exact text or charts appear in an ImageGen output, treat them as non-final. Rebuild those elements deterministically after generation.
## Common Patterns
### Social Carousel
- Python/SVG/HTML owns the card grid, exact headline, chart, CTA, and source note.
- ImageGen creates card backgrounds, textures, editorial scenes, or metaphorical hero visuals.
- Final cards are composited and exported as fixed PNGs, then previewed in social placements.
### Chart Card
- Python renders the chart and labels from data.
- ImageGen creates a polished backdrop or material treatment.
- Python overlays the chart, headline, and source line after generation.
### Launch Hero Visual
- ImageGen creates a hero scene or abstract campaign visual.
- Deterministic layout adds launch name, CTA, product/source link, and review labels.
- For first-pass hero exploration, use `offer-explorer` for the 25 starter offer directions before creating publish-bound composites.
- Avoid generated screenshots or fake product UI unless clearly marked exploratory.
### Social Polish / Format Pack
- Keep the deterministic full-size asset as the master.
- When an inline MCP review surface is useful for generated polish packs, render the exported image set with `render_moodboard_board_widget`; keep deterministic manifests and exact-size exports as the durable source of truth.
- If the master is a Canva design, or the user asks for Canva/social exports, use `canva:canva-resize-for-all-social-media` to create platform copies, preserve the original design, and return PNG export links plus Canva edit links.
- If the work is local and not Canva-backed, export exact-size variants from the deterministic renderer with `full/`, `preview/`, manifest, platform index, and any needed placement preview.
- Use generative polish before final export or as a controlled background/texture layer inside the format generator. Do not let resize or adaptation change copy, chart data, logos, claims, or source lines.
## Guardrails
- Do not use ImageGen to generate final legal, pricing, availability, benchmark, security, partner, customer, or product-capability claims.
- Do not rely on ImageGen-rendered text, numbers, code, charts, tables, logos, or source lines for publish-bound work.
- Do not create fake product UI, unofficial brand marks, customer proof, or partner lockups.
- Do not hide that an image layer was generated when review context requires provenance.
- Do not let visual polish override readability, contrast, accessibility, or placement fit.
## Output Shape
Save generated polish runs under `outputs/imagegen/generative-polish/<run-id>/` unless the user specifies another folder. Keep deterministic bases, ImageGen layers, final composites, manifests, and preview packs separated inside the run folder.
For local asset packs triggered by Explore or an asset-board handoff, return the pack as exports plus manifest plus shared review page/contact sheet. Use the shared renderer preset that matches the review surface, usually `image-wall` for asset grids or `detail-review` for one selected route. The inline widget can be offered as a convenience after the files exist, but it is not the primary deliverable.
When social variants are produced through Canva, report Canva edit links and PNG export links separately, and state that the original source design was left unchanged.
For generative polish requests, respond with:
```text
Generative polish plan: <asset or campaign>
Deterministic layers:
- <copy/chart/logo/dimensions/etc.>
ImageGen polish layers:
- <background/texture/lighting/scene/etc.>
Composition method:
- <Python/SVG/HTML/template path>
Artifact paths:
- <deterministic base / ImageGen layer / final exports / manifest>
Social polish:
- <local format pack / Canva resize outputs / not needed>
Source and media provenance:
- <approved media, user-provided references, generated layers, external design links>
Review risks:
- <text, chart, claim, logo, screenshot, partner/customer, etc.>
Validation checklist:
- <dimensions, text exactness, chart accuracy, contrast, manifest, previews>
Next action:
- <generate polish prompt / build deterministic base / export format pack / request approval>
```