Codex Image Director
Behavioral Overrides
-
First, read the task scale and workflow table below to select a single workflow, then read that specific workflow document before proceeding.
- Do not write prompts, call Codex, or read deep files in
catalog/before this.
- Do not write prompts, call Codex, or read deep files in
-
After selection, reply with:
Using <workflow>[·<tier>], based on: user mentioned <original phrase>; decision mode: <ask/auto/mixed>; next read <file> -
If two or more rows in the table match, or none match, stop and ask the user instead of assuming a workflow.
-
Image generation credit consumption is significantly higher than normal conversation rounds (research note from 2026-11: approximately 3–5x). Do not batch generate images "just to try." Only change one variable per iteration.
Image Generation Pipeline
User request
│
▼
Composition design – fill unspecified dimensions / infer physics and geometry / anticipate conflicts / optimize for easy generation ← agent: director
│
▼
Prompt file (English, segmented tags) [+ fixed specification file] [+ reference images / base images]
│
▼
scripts/gen.py ──▶ codex exec (read-only sandbox) ──▶ built-in image_gen ← Codex: executor; image_gen: artist
│ Wrapper prompt must call once as-is, no rewriting, no self-checking
▼
$CODEX_HOME/generated_images/<thread_id>/ ──▶ output directory name-vNNN.<ext> (never overwrite previous versions)
│
▼
Agent reviews each image themselves, checking details at full zoom ← agent: QA
│
▼
Single-variable fix: edit / regenerate / local patch (scripts/patch_region.py)
Precision comes from the closed outer loop (design → specification → execution → self-verification → single-variable fix), not from any keyword. See README.md for the rationale (for human reading; not needed during execution).
Terminology
| Term | Meaning |
|---|---|
| Base image | The image being edited in edit mode; written as Image N is the edit target in the prompt |
| Reference image | An image from which only specified elements are borrowed, without being modified; specify what is borrowed and what is not for each |
| Lock list | Elements that must remain unchanged in the current iteration, listed individually—not just "everything else stays the same" |
| Fixed specification file | Character, art style, and physics rules shared across multiple images; appended using --spec before each image's spec |
| Edit / Regenerate | Edit: keep the base image composition, modify only a region; Regenerate: redraw entirely from the prompt, optionally with reference images |
| Local patch | Use the old image as a base, paste only the target region pixels from the new image; used as a fallback to fix drift during editing |
| Realism scale | A continuous range from flat illustration to photorealistic, with anchor terms for each tier |
| Decision point | A place in the workflow where a trade-off is needed; each workflow has a Decision Point table specifying options, auto defaults, and cases requiring mandatory consultation |
Task Scale and Workflows
Read the full table first, then select a workflow.
| Workflow | Intent signal (typical phrasing) | First step | Design depth | Expected iterations | File |
|---|---|---|---|---|---|
| Single image·fast tier | Want a new image, quick sketch, draft, "just draw something" | Directly design and generate | Only complement shot, style, lighting | 1–2 rounds | flows/single-image.md |
| Single image·premium tier | Want a new image, long description, emphasizes drama or texture, gave reference images | Fill all dimensions, infer physics geometry | Full dimensions | Multiple rounds, usually regenerate first to set the big picture, then refine | flows/single-image.md |
| Series / character project | Multiple images of the same character or universe, needs consistency, wants spec sheets or three-view drawings | First-principle questions + create project directory | Set specs first, then scenes | Multiple rounds in spec phase, 1–2 rounds per scene, then polish | flows/series-project.md |
| Variant exploration | Form not yet decided, "give me several options", wants to compare and choose | Define invariants and exploration axes | Each direction varies only one axis | Diverge → select → converge | flows/explore-variants.md |
| Refine existing image | Only change a region, "fix the hand", "everything else stays the same", "remove something" | Describe current mistake + lock list | Only describe the change | One change per round | flows/edit-refine.md |
| Redesign existing image | Change outfit, form, art style, camera angle, recomposition, while keeping face or some elements | List preserved and replaced elements | Lock preserved items, fully design replaced items | 2–4 rounds | flows/redesign.md |
| Maintenance | Maintain this skill: add experience, adjust workflows or scripts, recalibrate trigger descriptions | Determine which layer to place it | — | — | flows/maintain.md |
Common misrouting:
- "Edit this image":
- If only a region changes, use Refine.
- If composition, shot, outfit, subject, or art style changes, use Redesign. When unsure, ask the user.
- "Move the person to lower left" or "Rotate the shot": These are composition-level changes; edit mode usually can't handle them—use Redesign or Single Image Regenerate, not Refine.
- "Generate more images":
- Same character, different scenes → use Series.
- Same request, different design directions → use Variant Exploration.
Decision Modes
Where trade-offs are needed during execution, they are listed in each workflow's Decision Point table. Handle them based on the user's authorization level:
| Mode | Trigger | Behavior |
|---|---|---|
| Ask (default) | User hasn't expressed a preference | Present decision points as multiple-choice questions, with the recommended option first and a rationale; ask all questions for the same phase at once, no fragmented follow-ups |
| Auto | User says "you decide", "use your judgment", "make the call", "otherwise go with your approach" | Execute according to the "auto default" in the Decision Points table; deliver with a list of "Decisions I made for you": decision, rationale, how to override |
| Mixed | User authorizes only part—e.g., "you choose the shot, but ask me about the clothes" | Execute authorized parts as Auto, the rest as Ask |
Even in Auto mode, you must stop and ask (hard gate) in these cases:
- Overriding a setting or request the user has confirmed.
- Significantly increased credit consumption: generating more than 3 images at once, or more than 2 auto-refinement rounds on the same issue.
- Missing prerequisites: reference images from disallowed sources, Codex unavailable.
- User's request is contradictory and cannot be satisfied simultaneously.
- Items marked as "always ask" in any workflow's Decision Point table.
Auto-mode refinement:
- Structural defects (extra fingers, broken lines, counting errors, violating requirements) may be auto-refined, maximum 2 rounds per issue.
- Aesthetic trade-offs (finer vs. stronger, cooler vs. warmer) are not auto-refined; they are listed in the delivery as "Optional directions" for the user to choose.
Boundaries
- Reference images must be provided by the user or explicitly allowed. If the user requests "don't use intermediate results," previously generated images must not be used as references or base images.
- Outputs are saved with new version numbers, never overwriting existing files.
- The generating party (Codex or other agent) self-declarations about results are not considered verification; you must inspect the image yourself.
- When Codex is unavailable, not logged in, or has insufficient credits, stop and report; do not bypass or use an unauthorized generation channel.
- When canceling a generation mid-way, confirm that the Codex subprocess has ended, otherwise it will continue consuming credits.
- When drawing inspiration from others' work, borrow only the design language, not the exact shape; do not write work names, game names, or brand names in prompts—describe the rendering technique instead.