asset-pipeline

Files (1)

• SKILL.md

SKILL.md (first lines)

# Asset Pipeline (Codex Image)

A higher-order orchestration of `/codex-image:style-gen`: given a locked style reference and a project context, plan the project's asset list, confirm with the user, then generate each asset in the same visual style.

## Sprite-sheet gate (CONDITIONAL — only for animation/sprite-sheet items)

For each generated item whose kind is a **sprite sheet / animation sheet** (a uniform
grid of animation frames), you MUST run the strict `sheetfit` gate after generating it:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-image.mjs" sheetfit "<sheet.png>" --grid <CxR>
```
On `status: "rework"`, regenerate that sheet (label-free, transparent gutters, strict
even grid, same scale per cell) and re-run until `"fixed"`/`"pass"`. See
`/codex-image:sheetfit`. **Items of any other kind (single illustration, background,
icon, mockup, tileset, etc.) MUST NOT be passed through sheetfit** — the gate is only
for multi-frame sprite/animation sheets.

## Arguments

- **First whitespace-separated token**: the **reference image path** (the locked style; quote if the path contains spaces).
- **Rest**: the **project context description**, free-form. Examples:
  - `"RPG mobile game with 5 enemies, 10 items, 4 backgrounds, UI buttons"`
  - `"SaaS landing page: hero, 4 section illustrations, OG image, favicon"`
  - `"casual puzzle app: app icon, splash, 6 tile sprites, particle textures"`

## Workflow

This skill is **orchestrated by the Claude Code agent** (you), not by a single bash one-liner — that lets the user review the plan before tokens are burned. Bash is only used for the underlying dispatcher primitives.

### 1. Parse and validate arguments

**Important — resolve attached-image placeholders first.** If `$ARGUMENTS` begins with a `[Image #N]` token (Claude Code's placeholder for an image the user attached via the chat UI, not a typed path), Claude Code provides the actual file path nearby in the message as image metadata of the form `[Image: source: <absolute-path>]`. In that case:

1. Replace the `[Image #N]` token with the resolved absolute path from the image metadata.
2. Treat everything after the original placeholder as the context string.
3. Pass the resolved path + context to `parse-args` as two arguments.

Otherwise (the user typed a path directly), pass `$ARGUMENTS` through as-is.

```bash
# Typed-path case:
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-image.mjs" parse-args "$ARGUMENTS"

# Attached-image case (after substituting the placeholder with the metadata path):
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-image.mjs" parse-args "<resolved-abs-path>" "<rest of arguments>"
```

On success, stdout contains two lines:
```
REF: <absolute path>
CONTEXT: <rest of arguments>
```

On failure (missing args, missing reference file), exit code is non-zero and stderr explains. **Stop and report the error to the user.**

### 2. Plan the asset list

Based on the CONTEXT string, propose a concrete asset list **yourself** (do not call Codex for this — Codex turns are for image generation only, planning is text-only reasoning).

#### CRITICAL: Screen-flow + element-size planning FIRST, asset list SECOND

Do not jump straight to "list of PNGs to generate." Real apps/games need a SCREEN-LEVEL design pass first, because the same visual element (a button, an orb, an icon) has a SPECIFIC PIXEL SIZE per screen, and that pixel size determines the asset's source resolution, atlas cell size, and whether it can be shared with another screen.

**Step 0 — Confirm the target viewport BEFORE doing anything else.**

Before planning screens or assets, the agent MUST ask the user which viewport the project targets, because every downstream size calculation depends on it. Use `AskUserQuestion` with the following options (or a subset that fits the context — drop irrelevant ones for the obvious cases, e.g. don't offer "Desktop" when the context string says "iOS app"):

> Question: "What viewport(s) does this project target? Asset sizes (cells,
> backdrops, icons) depend on this — wrong viewport = wrong asset sizes."
>
> Options (header "Viewport"):
> - Mobile portrait (430×932, iPhone 14 Pro baseline) — RECOMMENDED for most mobile games/apps
> - Mobile portrait small (390×844 / 360×800 Android baseline)
> - Mobile landscape (932×430)
> - Tablet portrait (820×1180)
> - Desktop web (1440×900)
> - Mobile + Desktop responsive (need both viewports planned)

Wait for the answer. The answer becomes the **target viewport** used in Step B element sizing. For responsive web, plan TWO sets of element sizes (mobile and desktop) and pick the largest pixel size each shared asset needs across both.

Only after the user answers do you proceed:

**Step A — Enumerate every screen in the flow.**

Use the inference rules below (game / mobile app / web / SaaS / etc.) to list EVERY screen the project needs, not just the one in the reference. Include overlay screens (level-up, pause, confirmation dialogs), error/empty states, transition screens (loading), and meta screens (settings, bestiary, achievements) implied by the product type.

**Step B — Size every element on every screen.**

For each screen, lay out the actual UI elements with PIXEL DIMENSIONS at the target viewport. State the viewport up front:
- Mobile portrait game/app: 430 × 932 (iPhone-ish baseline; use 360×800 for Android baseline if specified)
- Mobile landscape: 932 × 430
- Tablet portrait: 820 × 1180
- Web desktop: 1440 × 900 (or 1280 × 720)
- Web mobile responsive: still plan two viewports — mobile 390×844 and desktop 1440×900

Write the layout as a table per screen:

| Y range | Element | Size | Notes |
|---|---|---|---|
| 0–50 | back button (top-left) | 36×36 | iconRound variant |
| 60–110 | section header label | 240×40 | text-label PNG, no frame |
| 115–375 | map landscape backdrop | 430×260 | full-bleed, 1.65:1 ratio |
| ... | ... | ... | ... |

Do this for EVERY screen. Each element is a pixel rectangle on the viewport. Position (x, y, w, h) + display purpose. This step alone takes more thinking than the asset list — and that's the point. Without it, the asset list is guessing.

**Step C — Consolidate: identify shared elements across screens.**

This is the SINGLE MOST IMPORTANT planning step. Most assets in a real product are SHARED across many screens (back arrow on every sub-screen, primary button on every CTA, modal frame on every dialog, HP icon in HUD and results screen, etc.). If you draft assets per-screen without consolidating, you end up generating the same button 7 times — wasting tokens and creating visual drift.

Procedure:
1. Take every element from every screen's Step B table.
2. Group identical/near-identical elements by visual purpose. Examples:
   - All `back-arrow` instances across screens → ONE shared icon
   - All `primary-button` instances → ONE shared button atlas (with all states)
   - All `header-banner` instances → ONE shared banner asset
   - All `modal-frame` instances → ONE shared frame
   - All `HP-icon` / `coin-icon` / `gem-icon` instances → ONE shared HUD-icons atlas

From gmlxo76/codex-image-in-cc, Apache-2.0.

More from gmlxo76/codex-image-in-cc