steelmorgan/codex-image-gen

Codex Image Generation

Тонкая обёртка над Codex CLI для генерации и редактирования растровых изображений. Claude/Opus как primary agent не умеет рисовать картинки — поэтому при появлении такой задачи нужно явно делегировать её Codex'у через wrapper, описанный ниже. Это не review-сценарий: image_gen действительно создаёт файл на диске, поэтому Codex запускается в --sandbox workspace-write, в отличие от cross-provider-review.

Когда применять

| Ситуация | Действие | |----------|----------| | Нужен UI-mockup / wireframe формы 1С для обсуждения UX до реализации | Применить шаблон «UI / app mockup» из references/prompt-guide.md | | Нужна иллюстрация для спеки, ADR, статьи, презентации | Применить шаблон «Office / business illustration» или «Lifestyle scene» | | Нужна диаграмма как растр (не векторная mermaid/PlantUML) | Применить шаблон «Diagram / explainer visual» | | Нужна тестовая фикстура: иконка, аватар, плейсхолдер для реквизита Picture/AttachedFile | Применить шаблон «Icon / sticker» или «Product photo» | | Нужна правка существующего PNG (сменить цвет, убрать объект, заменить фон) | Передать оригинал через --reference-image, применить шаблон редактирования | | Пользователь спрашивает «можешь нарисовать N изображений и сравнить» | Делать N независимых вызовов wrapper'а — Codex держит стейт картинки только внутри одной сессии |

Когда НЕ применять

• Нужна векторная диаграмма (mermaid, PlantUML, dot) — пишется текстом, image_gen не нужен.
• Нужен скриншот реальной формы 1С — это web-test-1c / playwright / gui-control, не генерация.
• Нужен ASCII-арт или unicode-диаграмма в документе — пиши руками, делегировать незачем.

Анти-паттерны

• «Опиши картинку словами вместо генерации» — если пользователь явно попросил картинку, описание её не заменяет.
• Пытаться сгенерировать через cross-provider-review / codex_review.py — там жёстко прибит --sandbox read-only, файл на диске не появится. Используй именно codex_image_gen.py.
• Передавать неструктурированный промт («сделай красиво») — image_gen вернёт мусор. Брать шаблон из references/prompt-guide.md и заполнять оси.
• Складывать выход в произвольный путь — wrapper всегда пишет в tasks/<id>/assets/, чтобы артефакт жил рядом с задачей. Если задачи нет — обсудить с пользователем, нужно ли ей завестись.

Как вызывать

Wrapper лежит рядом со SKILL.md:

.claude/skills/codex-image-gen/scripts/codex_image_gen.py \
  --task-id <id> \
  --filename <name>.png \
  --prompt-file path/to/prompt.txt

или короткой строкой:

.claude/skills/codex-image-gen/scripts/codex_image_gen.py \
  --task-id <id> \
  --filename <name>.png \
  --prompt "High-fidelity UI mockup for ..."

Для редактирования существующего изображения:

.claude/skills/codex-image-gen/scripts/codex_image_gen.py \
  --task-id <id> \
  --filename <name>-v2.png \
  --reference-image tasks/<id>/assets/<name>.png \
  --prompt "Keep the original composition. Change the background to ..."

Опции wrapper'а:

| Флаг | Назначение | |------|------------| | --task-id | Обязательный. Выход пойдёт в tasks/<task-id>/assets/. Каталог создаётся автоматически. | | --filename | Обязательный. Имя итогового файла (*.png/*.jpg/*.webp). | | --prompt или --prompt-file | Содержимое промта. Один из двух обязателен. | | --reference-image | Путь к исходному изображению для режима редактирования. Можно повторять. | | --model | Модель Codex. По умолчанию gpt-5. | | --reasoning-effort | low/medium/high. По умолчанию medium. | | --timeout-sec | Таймаут одного вызова. По умолчанию 600. | | --dry-run | Покажет финальную команду codex exec без запуска. Полезно для отладки. |

Wrapper печатает в stdout JSON-блок {"status": "ok", "files": ["abs/path/...png", ...]} или {"status": "error", "reason": "..."}. Принимай результат программно по этому JSON.

Как составить промт

references/prompt-guide.md — это рабочий гайд из 8 разделов: общий принцип, оси промта (сюжет/стиль/свет/фон/ограничения), шаблон-конструктор для генерации, шаблон-конструктор для редактирования, 10 готовых шаблонов на типовые сценарии генерации, 10 шаблонов на редактирование, частые ошибки, итерационный протокол. ОБЯЗАТЕЛЬНО прочитай раздел, релевантный твоей задаче, перед составлением промта — image_gen нелинейно чувствителен к структуре.

Жёсткие требования к промту, специфичные для этого wrapper'а (а не общему image_gen):

• Промт ОБЯЗАН содержать инструкцию Save the resulting image as <filename> in the current working directory. — wrapper подставляет её автоматически в конец промта, но если ты пишешь промт-файл, ничего лишнего про сохранение писать не нужно.
• Не указывай в промте абсолютные пути, не прыгай за пределы CWD — Codex запущен с --sandbox workspace-write -C <output_dir>, любая попытка писать вне tasks/<id>/assets/ будет заблокирована kernel-sandbox.
• Если просишь несколько вариантов в одной сессии — Codex может сохранить только один файл (--filename). Для серии — несколько отдельных вызовов wrapper'а.

Как принять результат

1. Wrapper вернул status: ok + список файлов → проверь ls tasks/<id>/assets/<filename> (stat достаточно). Если файла нет — это status: error независимо от того, что сказал Codex.
2. Открой картинку (или попроси пользователя), сравни с промтом по осям: сюжет/композиция/стиль/свет/фон/ограничения. Если расхождение по 1-2 осям — итеративная правка коротким промтом «Keep everything else unchanged. <дельта>». Если расхождений много — пересобери промт целиком.
3. Если результат подошёл — упомяни путь к файлу в ответе пользователю. Если файл предназначен для документа задачи (спека, ADR, README) — добавь markdown-ссылку и оставь image inline.

Известные ограничения

• Доступность инструмента image_generation зависит от модели и настроек Codex CLI. Если wrapper падает с сообщением вида «model does not support image_generation» — сообщи пользователю и предложи переключить модель через --model (например, gpt-5/gpt-5-codex) или открыть тикет на обновление Codex CLI.
• Codex может «уйти на reasoning» и вернуть только текстовый ответ без файла. Wrapper проверяет наличие файла и сообщает status: error с подсказкой «retry, явно потребовав сохранить файл».
• Размер изображения по умолчанию определяется моделью; wrapper передаёт в промт хинт Use 1024x1024 unless the user explicitly asked for another size. — переопределяй явным указанием в собственном промте.

Почему отдельный навык, а не cross-provider-review

cross-provider-review создаёт sandbox в .review-sandboxes/, прибивает --sandbox read-only и предназначен для второго мнения по артефактам — без записи на диск и без побочных эффектов. Image generation — это, наоборот, целевой write на диск в результирующую папку проекта. Семантика и режимы безопасности разные, поэтому codex_image_gen.py — самостоятельный wrapper, а не флаг в codex_review.py.

---

depends_on:

• framework/skills/tool-usage/review/cross-provider-review/SKILL.md

---