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-guided regeneration, 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 for a new generated variation 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)
• Regenerating a new image that follows a supplied reference's subject, style, lighting, or composition

When NOT to use

• Pixel-level editing, masking, inpainting, object removal, compositing, cropping, resizing, or format conversion -> out of scope; use an image editor or a tool that explicitly supports that operation.
• 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 the image: section of .agents/oma-config.yaml

Control-flow features

• Branches by prompt ambiguity, vendor auth, cost threshold, reference-guided regeneration 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. Classify a supplied image as a reference for a newly generated variation, or as a request for unsupported pixel/mask editing.
3. Check authentication, cost guardrails, output path, and count limits.

Transitions

• If the subject or intended result cannot be inferred, clarify that missing input; otherwise proceed with reasonable defaults.
• If --vendor all is requested, require every requested vendor to be available.
• If the request is reference-guided regeneration and the selected vendor supports references, pass it automatically.
• If the request requires pixel, mask, crop, resize, or format editing, stop before generation and name the unsupported operation and an appropriate editor route.
• 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

Tools and instruments

• oma image generate, oma image doctor, oma image vendor list
• 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 --output json

With reference images:

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

Resource scope

Scope	Resource target
LOCAL_FS	Reference images, generated images, manifests
PROCESS	Provider CLIs and image router commands
NETWORK	Pollinations/Gemini or provider APIs
CREDENTIALS	Provider auth and API keys

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. Resolve the brief: use supplied details and reasonable creative defaults. Ask only when a missing choice materially changes the requested result. Do not require approval of an expanded prompt when generation is already authorized.
2. Authentication-aware dispatch: detect which vendor CLIs are available and run only those; with --vendor all, every requested vendor must be available (strict). Caveat: the antigravity health check verifies installation only (agy --version) — a signed-out agy passes health and fails at generate time with agy's own error.
3. Cost guardrail: confirm before executing runs whose estimated cost is ≥ $0.20 (configurable). --yes / OMA_IMAGE_YES=1 bypass. Choose generation from the requested outcome, not keyword presence. Non-interactive contexts (agents, CI — no TTY on stdin): the CLI cannot prompt, so a run at/over the threshold exits 1 with a message naming --yes. Use --dry-run to estimate cost. Reuse an existing budget authorization; otherwise confirm the additional spend before re-running with -y.
4. Path safety: output paths outside $PWD require --allow-external-output.
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).

Creative brief

Use the requested subject and constraints. Infer setting, style, lighting, and aspect ratio when unspecified; preserve explicit text and reference intent. Ask only for a material unresolved choice. Read resources/prompt-tips.md for an unfamiliar image category.

References

• Provider invocation, references, and output layout: resources/invocation.md (selected vendor or reference-image operation only).

Configuration

Project-specific settings: the image: section of .agents/oma-config.yaml, which oma update preserves. Shipped defaults live in the CLI (DEFAULTS in cli/commands/image/config.ts) — write only the keys you change. The legacy config/image-config.yaml is no longer read by the CLI; migration 022 moves anything you had changed there into oma-config (and deletes the file when it was never edited). Env vars: OMA_IMAGE_DEFAULT_VENDOR, OMA_IMAGE_DEFAULT_OUT, OMA_IMAGE_YES, POLLINATIONS_API_KEY.

• Execution steps (follow for the selected task): resources/execution-protocol.md
• Vendor matrix: resources/vendor-matrix.md
• Prompt tips: resources/prompt-tips.md
• Checklist (run before handoff): resources/checklist.md
• Context loading: ../_shared/core/context-loading.md