/compose-creative

name: compose-creative
description: "Compose just the creative (image or video) for a calendar post, in four modes. \"make the visual for this post\""
argument-hint: "[--post <id>] [--all] [--variant b]"
effort: max
user-invocable: true

/socialforge:compose-creative — Creative Production Engine

> **Script location.** If your host does not set `${CLAUDE_PLUGIN_ROOT}`, the scripts are in this plugin's `scripts/` folder, next to `skills/`. Run them with Python 3.10 or newer: `python`, or `python3` where `python` is not found (macOS, many Linux systems).

The core production skill. Takes asset matching results and produces visual and video assets for each post according to its assigned creative mode, using a staged human-in-the-loop approval flow.

Context efficiency

Asset-heavy skill. **Grep before Read** the asset catalog (`${CLAUDE_PLUGIN_DATA}/socialforge/brands/<brand>/asset-index.json`) — never list the asset directory. Reference generated images / videos by path, not by loading metadata. Brand profile loads once per session.

The 4 Creative Modes

MODE 1: ANCHOR_COMPOSE

Brand asset is the untouchable center. AI generates scene around it. 1. Remove background from brand asset (rembg) 2. Generate surrounding scene via AI using brand style references 3. Composite asset onto generated scene (Pillow) 4. Add shadow/reflection for natural placement 5. Add text overlay + logo 6. Resize per platform

MODE 2: ENHANCE_EXTEND

Brand asset is the foundation. AI modifies periphery only. 1. Feed real image to AI edit endpoint 2. AI extends/enhances while preserving core subject 3. Verify core subject preservation 4. Add overlay + resize

MODE 3: STYLE_REFERENCED

No brand asset composited. Style reference photos guide AI generation. 1. Load 2-8 brand style reference images 2. Construct 5-layer prompt (brand identity, post context, creative direction, image rules, technical) 3. Feed references + prompt to AI generation 4. Quality review — does output match brand DNA? 5. Add overlay + resize

MODE 4: PURE_CREATIVE

Full AI generation with only text prompt + brand colors/mood. 1. Construct prompt from brief + brand-config visual style 2. Generate (text-only, no reference images) 3. Quality review 4. Add overlay + resize

Reference images and keyframes — what the scripts actually do

Read from `scripts/generate_image.py`, `scripts/edit_image.py` and `scripts/generate_video.py`. This skill promises only what those scripts implement.

| Input | How to pass it | What is true today | |---|---|---| | Style references for a new image (STYLE_REFERENCED) | `generate_image.py --references <path> [<path> ...]` — the first 14 are read | Sent to the **primary** image provider only. The fallback providers receive the prompt and aspect ratio, **not** the references: when the result carries `fallback_from` and references were supplied, it also carries `references_used: 0`, `references_dropped: <n>` and a `references_note` — the image is **not** style-referenced. Tell the user, and fix the primary provider's credentials rather than accepting a reference-less image as a style-referenced one. | | References alongside an image being edited (ENHANCE_EXTEND) | `edit_image.py --image <src> --instruction "..." --references <path> ...` — first 14 | Supported. There is no fallback chain for edits. (`generate_image.py --edit` takes no references.) | | First frame for video | `generate_video.py --image <path>` | Supported by every video provider in the chain; one of them requires it. See `/socialforge:generate-video`. | | Last frame for video | `generate_video.py --last-image <path>` (with `--generate-video`) | Sent to the `kling` rung as the clip's end image; no other rung takes one. The result's `video.last_frame_used` says whether it was sent — `false` (with a `last_frame_note`) means the clip was not steered to the approved last frame. See `/socialforge:generate-video`. | | Reference images for video | none | **Not wired** through `generate_video.py` — no flag exists. See `/socialforge:generate-video`. |

Two caveats from the code: file type is set from the extension (`.jpg`/`.jpeg` as JPEG, everything else as PNG), so pass JPEG or PNG and convert WebP first; and `references_used` is the number of files actually read and sent, not the number of paths passed. When it is lower than what you passed, the result says why: `references_missing` lists the paths that do not exist (they are not sent, and there is no error), `references_over_limit` counts the paths past the 14-file limit, and `references_dropped` plus `references_note` mean a fallback provider made the image. Read those fields before treating an image as style-referenced.

Prerequisites

• `asset-matches.json` must exist (generated by `/socialforge:match-assets` -> match_assets.py)
• `calendar-data.json` must exist (generated by `/socialforge:parse-calendar`)
• `brand-config.json` must exist for active brand
• `cost-log.json` initialized (via status_manager.py --action init-month)
• Valid credentials for the image provider (Vertex AI or a Gemini API key, alias `latest-image-balanced-google`) and the video provider (WaveSpeed, alias `latest-video-wavespeed`; or Vertex AI for Veo) via credential_manager.py. Which model each alias resolves to today: `python "${CLAUDE_PLUGIN_ROOT}/scripts/generate_video.py" --list-models`.

If any prerequisite is missing: "Run `/socialforge:match-assets` first — creative production needs asset matching results."

Quote, then go (before any paid call)

Generation spends provider credits, so the first paid call waits for a quote and an explicit go. This skill states no price and the model registry stores none: `price_book.py` is the only source, and it refuses rather than guesses.

1. List what is about to be generated: for each paid call, the registry alias (`resolve_model.py --alias <alias>` gives the current model id), the provider, and the units (images, or seconds of video, plus any option that ch