codex-image-gen

name	codex-image-gen
description	Use when Steve asks to create final-quality images, especially Threads/carousel visuals, and the output must be generated through Codex native image generation rather than local placeholder renderers.
version	1.0.1
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["codex","image-generation","threads","carousel","visual-qa"],"related_skills":["codex","monca-threads-visual-style"]}}

Codex Image Gen

Overview

Use this skill when Steve asks for final-quality images and expects Codex native image generation. This is not the same as asking Codex to write a Python/PIL/Swift/AppKit/HTML/CSS renderer.

The required behavior is:

Codex native image generation first
→ save actual raster PNG/JPG outputs
→ copy/move them into the requested workspace paths
→ normalize size only if needed
→ vision QA for text, clipping, overlap, malformed shapes
→ deliver images or upload to Notion if requested

Steve explicitly corrected a failed carousel where a local renderer produced broken visuals. For Steve image work, do not substitute quick scripts, AppKit, PIL, matplotlib, SVG, HTML/CSS, or screenshots unless Steve explicitly approves a fallback.

When to Use

• Steve says “이미지 만들어”, “이미지 뽑아줘”, “캐러셀 만들어”, “visual 만들어”.
• Steve asks for Codex image gen, codex-image-gen, or “codex로 이미지”.
• Final-quality Threads/@monca.dev carousel images are requested.
• A previous local-rendered visual was rejected for being placeholder-like, malformed, or ugly.
• You need image generation with Korean text and must preserve Steve’s preference for Codex-generated image outputs.

Do not use for:

• Simple deterministic diagrams explicitly requested as SVG/Excalidraw/HTML.
• Code-native assets where the repo already owns the vector/CSS source.
• Rough internal layout sketches unless Steve explicitly says a non-Codex fallback is OK.

Hard Rules

1. No fake Codex image gen. If Codex wrote a renderer, script, SVG, HTML, or CSS, say that clearly. Do not call it image generation.
2. No silent fallback. If Codex native image generation is blocked, write/report the blocker and stop. Ask before using Hermes image_generate, PIL, AppKit, Playwright, or any other path.
3. Actual raster files required. Final outputs should be PNG/JPG/WebP files generated by Codex’s image generation path.
4. Korean text QA is mandatory. Generated images often distort text; inspect with vision before delivery. If QA finds a Korean typo, first reduce/shorten the exact copy and regenerate natively. Do not accept Codex's attempt to repair generated text with local text overlays, Swift/AppKit/PIL, HTML/CSS, or other renderer-like patches unless Steve explicitly approves a fallback.
5. Shape QA is mandatory. Check arrows, clocks, diagrams, connectors, icons, and badges for malformed geometry or overlap.
6. Resize is allowed; redraw is not. Using sips/ImageMagick to normalize canvas size is acceptable. Rebuilding the image with code is not.

Known Codex Behavior

In this environment, codex exec can load its built-in image generation skill from:

~/.codex/skills/.system/imagegen/SKILL.md

The Codex CLI may not expose a top-level codex image command. That is OK. The successful path is to ask Codex directly, inside codex exec, to generate actual raster images using native image generation.

Generated files may appear under:

~/.codex/generated_images/<codex-session-id>/*.png

Codex should then copy/move selected outputs into the workspace paths requested by the prompt.

Standard Workflow

1. Create a clean Codex image workspace

Prefer a fresh unique temp directory instead of deleting/reusing a fixed path. This avoids Hermes dangerous-command approval prompts from rm -rf and reduces the chance of accidentally deleting prior work.

WORKDIR="$(mktemp -d /tmp/<short-topic>-codex-imagegen.XXXXXX)"
mkdir -p "$WORKDIR/out" "$WORKDIR/notes"
printf '%s\n' "$WORKDIR" > "$WORKDIR/notes/WORKDIR.txt"
cd "$WORKDIR"
git init
pwd

Use a git repo because Codex works best inside one. Do not begin image jobs with rm -rf "$WORKDIR" unless Steve explicitly asks for cleanup or you have a strong reason; in Slack/gateway sessions it triggers a recursive delete approval prompt and interrupts the image-generation flow. Keep this unique workdir around after delivery so Steve can later inspect IMAGE_PROMPT.md, out/, and notes/; cleanup can be handled later in a separate batch.

2. Write IMAGE_PROMPT.md

The prompt must explicitly ban local renderers and placeholders. Treat IMAGE_PROMPT.md as the durable request record for the job: save the user's original request, final interpreted brief, output filenames, dimensions, style constraints, and any correction/regeneration instructions in this file so the workdir remains useful for later reference.

You are Codex with image generation capability. Generate actual raster image files, not code, not SVG, not HTML, not CSS, not a Python/Swift/AppKit/PIL renderer.

Task: <what to create>

Output requirements:
- Create exactly these files:
  - out/01-....png
  - out/02-....png
- Each image: 1080x1350 px, vertical 4:5.  # or the requested size
- Clean premium Korean PPT-style visual, mobile-legible.
- Do not draw decorative elements that overlap text.
- No broken arrows, malformed icons, fake clock hands over text, or text obstruction.
- Korean text must be large, clean, and readable.

Slide/card specs:
<exact copy and visual direction per image>

Important:
- If native image generation is unavailable in this Codex environment, do not create any fallback renderer or placeholder. Instead, write notes/IMAGE_GEN_BLOCKED.md explaining the blocker.

3. Run Codex with image-gen intent

Use PTY mode through Hermes terminal.

codex exec --sandbox workspace-write \
  "Read IMAGE_PROMPT.md and follow it exactly. Generate the requested actual PNG images using native image generation. Do not write a renderer or placeholder. If native image generation is unavailable, create notes/IMAGE_GEN_BLOCKED.md only."

Hermes tool call pattern. Replace workdir with the actual unique directory printed by pwd/saved in notes/WORKDIR.txt; do not use the literal template path.

{
  "command": "codex exec --sandbox workspace-write \"Read IMAGE_PROMPT.md and follow it exactly. Generate the requested actual PNG images using native image generation. Do not write a renderer or placeholder. If native image generation is unavailable, create notes/IMAGE_GEN_BLOCKED.md only.\"",
  "workdir": "/tmp/<short-topic>-codex-imagegen.A1b2C3",
  "pty": true,
  "timeout": 600
}

4. Verify files and dimensions

Use tools; do not assume success from Codex’s summary.

find out -maxdepth 1 -type f -print | sort
sips -g pixelWidth -g pixelHeight out/*.png

If Codex saved native outputs under ~/.codex/generated_images/... but failed to copy them, copy by creation order into the requested filenames, then resize if needed:

ls -tr "$HOME/.codex/generated_images/<session-id>"/*.png > generated-list.txt
sed -n '1p' generated-list.txt | xargs -I{} cp {} out/01-....png
sed -n '2p' generated-list.txt | xargs -I{} cp {} out/02-....png
sips -z 1350 1080 out/01-....png
sips -z 1350 1080 out/02-....png

Resizing native outputs is acceptable; creating a renderer is not.

5. Vision QA before delivery

Run vision_analyze on every final image. Ask specifically about:

• Korean text readability
• misspellings, broken Hangul, weird glyphs
• clipping/cropping
• text overlap/obstruction
• malformed arrows/connectors/icons/clocks
• whether the visual communicates the intended idea

Example QA prompt:

이 1080x1350 한국어 Threads 카드의 텍스트 가독성, 글자 오류/깨짐, 겹침/가림, 장식 요소가 글자를 가리는지, 전체 품질을 아주 엄격하게 검수해줘.

If QA finds a material issue, regenerate with a narrower correction prompt through Codex image generation. Do not patch with local drawing code unless Steve approves.

6. Deliver

In Slack/Telegram, send images as native media:

MEDIA:/absolute/path/out/01-....png
MEDIA:/absolute/path/out/02-....png

Mention succinctly:

• “Codex native image generation으로 생성”
• final paths
• retained workdir path, especially IMAGE_PROMPT.md, so Steve can refer back later
• QA result if relevant

Carousel Prompt Pattern for Steve

For @monca.dev carousel visuals, use this structure:

Task: Create a polished <N>-card Korean Threads carousel for @monca.dev.

Style:
- Clean premium Korean PPT-style mobile carousel.
- 1080x1350 px, vertical 4:5.
- Strong title hierarchy.
- One central visual metaphor per card.
- Minimal decoration; no generic robot/brain imagery unless requested.
- Warm off-white or clean navy background, sparse blue/orange accents.
- Korean text large enough for mobile.

Avoid:
- broken arrows or malformed diagrams
- clocks/hands/icons overlapping text
- tiny text
- hallucinated Korean text
- random extra slogans
- busy gradients

Output files:
- out/01-<slug>.png
- out/02-<slug>.png
- out/03-<slug>.png

Card 1:
Exact text:
...
Visual:
...

Card 2:
Exact text:
...
Visual:
...

Blocker Handling

If Codex cannot use native image generation, create/report:

notes/IMAGE_GEN_BLOCKED.md

Include:

• codex --version
• codex login status result, without secrets
• whether ~/.codex/skills/.system/imagegen/SKILL.md exists
• exact Codex error message
• what was preserved in the workdir

Then stop and tell Steve the blocker. Do not generate a substitute image.

Common Pitfalls

1. Asking Codex to “build a generator.” That produces code-rendered placeholders, not Codex image generation.
2. Trusting Codex’s final summary. Always verify files and dimensions yourself.
3. Skipping QA because the image “looks OK.” Korean text and arrows must be inspected explicitly.
4. Letting generated text drift. Put exact copy in IMAGE_PROMPT.md; if text fidelity is critical, ask for fewer words and larger type.
5. Overusing diagrams. For social cards, one clean metaphor beats a dense architecture diagram.
6. Fixing generated image errors with local scripts. Regenerate through Codex image gen unless Steve approves fallback.
7. Missing the requested contrast story. If Steve asks to show “글보다 시각화가 더 이해가 좋다,” make the composition explicitly comparative (e.g. left = dense Markdown/prose, right = structured visual document/diagram) instead of only showing generic API/architecture diagrams.
8. Fixing only the complained-about slide. For carousel work, a corrected first card can make later cards feel off-tone. When Steve says other pages “톤이 달라” or similar, treat the approved/revised card as the style guide and regenerate the remaining pages to match: same background, title/chip treatment, card grammar, bottom message/page-number system, and visual density. QA the whole set for consistency, not just each image in isolation.
9. Native output dimension mismatch. Codex native image generation may return a non-requested aspect/size (e.g. 997×1577 or 1122×1402). If the composition is otherwise good, it is acceptable to mechanically resize/crop/pad the raster with sips/ImageMagick to the requested canvas without redrawing; verify dimensions afterward.
10. Codex trying to patch text locally. Codex may propose local text correction after repeated Korean typos. For Steve's final image work, this violates the native-image-first rule unless he explicitly approved fallback. Stop that path, simplify the copy/prompt, regenerate natively, and run vision QA again.
11. Generated footer/separator hallucinations. Codex may add extra punctuation or separators in card footers (e.g. 03 | / ...) even when copy is specified. During QA, inspect small footer text explicitly. If separators are wrong, regenerate natively with a narrower prompt that says the footer is plain text only and bans slashes/pipes/extra punctuation.
12. Stopping before Notion read-back. When generated carousel images are uploaded to Notion Carousel Images, download or read back the uploaded assets and re-check dimensions/legibility. A local pass is not enough when the final handoff is the Notion file property.
13. Approval prompt churn from cleanup commands. In Hermes Slack/gateway sessions, rm -rf "$WORKDIR" and similar cleanup commands trigger dangerous-command approvals (recursive delete). Prefer mktemp -d fresh workdirs for image jobs. If a cleanup approval is unavoidable during a single image session, ask Steve to use Allow Session or /approve session; avoid recommending broad Always Allow for recursive delete because it permanently allowlists a wide pattern, not a single temp path.

Verification Checklist

• IMAGE_PROMPT.md explicitly requested actual raster images and banned renderers/placeholders.
• IMAGE_PROMPT.md includes the user's original request, interpreted brief, output filenames, dimensions, and any correction prompts for later reference.
• codex exec was used with pty=true from a git workdir.
• Final files exist under out/ with the requested names.
• Dimensions match requested size, usually 1080x1350.
• No notes/IMAGE_GEN_BLOCKED.md unless generation truly failed.
• Vision QA passed for Korean text, clipping, overlap, and malformed shapes.
• Final response includes MEDIA:/absolute/path attachments or a verified upload link.