Oma Image

Image Agent - Multi-Vendor Image Router

Scheduling

Goal

Generate images and visual assets through authenticated multi-vendor routing while preserving prompt clarity, reference-image handling, cost controls, and reproducible output manifests.

Intent signature

• User asks to generate images, visual assets, illustrations, product photos, concept art, mockups, or AI art.
• Another skill needs shared image-generation infrastructure.
• User provides reference images or asks for vendor comparison.

When to use

• Generating images, visual assets, illustrations, product photos, concept art
• Comparing output between multiple image models for the same prompt
• Producing images from prompts within editor workflows (Claude Code, Codex, Gemini CLI)
• Other skills needing image generation infrastructure (shared invocation)

When NOT to use

• Editing an existing image or photo manipulation -> out of scope
• Generating videos or audio -> out of scope
• Inline vector art / SVG composition from structured data -> use a templating skill
• Simple asset resizing or format conversion -> use a dedicated image library

Expected inputs

• Image prompt or creative brief
• Optional vendor, size, quality, count, output directory, and reference images
• Authentication/environment state for Codex, Pollinations, or Gemini

Expected outputs

• Generated image files under .agents/results/images/ or requested output directory
• manifest.json with prompt, vendor, model, and reproducibility metadata
• Vendor comparison outputs when --vendor all is used

Dependencies

• oma image generate CLI and vendor authentication
• Codex image generation, Pollinations API, or Gemini API/CLI strategy
• resources/vendor-matrix.md, resources/prompt-tips.md, and config/image-config.yaml

Control-flow features

• Branches by prompt ambiguity, vendor auth, cost threshold, reference-image support, path safety, and safety/timeout exit codes
• Calls external vendor APIs/CLIs
• Reads reference images and writes generated images plus manifests

Structural Flow

Entry

1. Validate that the request contains enough subject, setting, style, usage, and aspect-ratio signal.
2. Detect attached/reference images and vendor support.
3. Check authentication, cost guardrails, output path, and count limits.

Scenes

1. PREPARE: Clarify or amplify prompt and choose vendor strategy.
2. ACQUIRE: Validate auth, references, output path, and provider availability.
3. ACT: Invoke oma image generate with selected vendor(s), prompt, references, and options.
4. VERIFY: Check manifest, output files, exit code, and provider result.
5. FINALIZE: Return output paths and relevant warnings.

Transitions

• If prompt lacks required signal, clarify or show amplified prompt before generation.
• If --vendor all is requested, require every requested vendor to be available.
• If reference path is supported by selected vendor, pass it automatically.
• If estimated cost exceeds guardrail, require confirmation unless bypassed.

Failure and recovery

• If auth is missing, report vendor-specific authentication requirement.
• If reference support is unavailable for the selected vendor, reject with actionable guidance.
• If local CLI is outdated, ask user to run oma update.
• If generation times out or is blocked, surface exit code and provider status.

Exit

• Success: images and manifest exist in the output directory.
• Partial success: some vendors fail in comparison mode and failures are reported.
• Failure: no image is produced and the route/cost/auth/safety blocker is explicit.

Logical Operations

Actions

Tools and instruments

• oma image generate, oma image doctor, oma image list-vendors
• Codex, Pollinations, and Gemini provider paths
• Prompt tips, vendor matrix, and image config

Canonical command path

oma image doctor
oma image generate "<prompt>" --vendor auto --size auto --quality auto --format json

With reference images:

oma image generate --reference "<absolute-path>" --vendor codex "<prompt>"

Resource scope

Preconditions

• Prompt is sufficiently specified or user approves amplification.
• Required vendor auth and output permissions exist.
• Reference paths are accessible when used.

Effects and side effects

• Creates image files and manifests.
• May call paid or rate-limited provider APIs.
• May read attached/reference images.

Guardrails

1. Clarify before invoking — if the user's request is ambiguous about subject, style, composition, or usage context, ask the user first or amplify the prompt explicitly (showing the user the expanded version for approval). Do NOT silently generate from a vague prompt. See Clarification Protocol below.
2. Authentication-aware dispatch — detect which vendor CLIs are authenticated and run only those; with --vendor all, every requested vendor must be available (strict).
3. Cost guardrail — confirm before executing runs whose estimated cost is ≥ $0.20 (configurable). --yes / OMA_IMAGE_YES=1 bypass. Default vendor pollinations (flux/zimage) is free, so auto-triggering on keywords is safe.
4. Path safety — output paths outside $PWD require --allow-external-out.
5. Cancellable — SIGINT/SIGTERM aborts in-flight provider calls and the orchestrator.
6. Deterministic outputs — every run writes manifest.json next to the images for reproducibility.
7. Max n = 5 — wall-time bound.
8. Exit codes align with oma search fetch (0, 1, 2=safety, 3=not-found, 4=invalid-input, 5=auth-required, 6=timeout).

Clarification Protocol

Before invoking oma image generate, the calling agent runs this checklist against the user's request. If any answer is "no / unknown", clarify with the user first.

Required signal (must be present or inferable):

• Subject — what is the primary thing in the image? (object, person, scene)
• Setting / backdrop — where is it? (context, environment)

Strongly recommended (ask if absent AND not inferable from context):

• Style — photorealistic, illustration, 3D render, oil painting, concept art, flat vector, …?
• Mood / lighting — bright vs moody, warm vs cool, dramatic vs minimal
• Usage context — hero image, icon, thumbnail, product shot, poster? (dictates aspect ratio + composition)
• Aspect ratio — square (1024x1024), portrait (1024x1536), landscape (1536x1024)?

Amplification shortcut. For brief prompts (e.g. "a red apple"), do not pop clarifying questions if the request is genuinely that simple — instead amplify inline and show the user the expanded version before invoking:

User: "a red apple" Agent: "I'll generate this as: a single glossy red apple centered on a clean white background, soft studio lighting, photorealistic, shallow depth of field, 1024×1024. Shall I proceed, or would you like a different style/composition?"

Skip both clarification and amplification when the user has clearly authored a full creative brief (≥ 2 of: subject + style + lighting + composition). Respect their prompt verbatim.

Category-specific briefs (app mockup, poster, thumbnail, infographic, comic panel, avatar): consult resources/prompt-tips.md → External Prompt Libraries.

Output language. Generation prompts are sent to the provider in English (image models are trained predominantly on English captions). Translate the user's request if they wrote in another language, and show them the translated version during amplification so they can correct misreadings.