Image Variations (Skill 01)
Single entry point. Orchestration is written here; the full text of 12 directions, Prompt templates, Provider compatibility matrix, error codes, and thresholds are not here—they are all read on demand from the frozen baseline to avoid two drifting sources of truth.
- Business rules:
Image_Variations_Dual_Skill_SPEC_v1.1/specs/01-Image-Variations-Skill-v1.2.md - Direction registry:
.../references/directions/registry.json - Prompt templates:
.../references/grid-prompt.md,.../references/sequence-prompt.md - Provider compatibility & safety:
.../references/provider-compat.md - Error codes:
.../references/error-registry.json - Packaging rules:
.../references/packaging.md - Contracts:
.../contracts/{image-artifact,job-state,delivery-package}.schema.json
The baseline is read-only: the hash manifest is in shared/baseline.manifest.json; shared/check_baseline.py must always pass.
To change a specification, first explain the rationale and get confirmation—do not silently "correct" the baseline in the implementation.
1. Five Inviolable Rules
- No silent degradation. If capability is insufficient, budget is insufficient, or validation fails, always explicitly return
an error code from
references/error-registry.json; never "silently switch to a smaller size / lower tier / fewer images" and continue running, nor report a failure as a pass. - Thresholds only from configuration.
config/iv.config.jsonis the sole source (single tile edge warn/hard thresholds, seam pass/risk thresholds, upscale factor, retries and budget). These have not yet been calibrated with real models; provide data before changing them. No magic numbers in code. - Single source of truth. Directions, Prompts, error codes, and contracts are all read from the baseline at runtime; do not copy them into this Skill.
- Keys only by reference. Only accept
secret://…orenv:…; keys, original images, and user text must never appear in logs, manifests, error messages, or ZIP files. - Artifacts must be verifiable. Each delivery includes
manifest.json(image-artifact1.1) anddelivery-package.json; every entry in the manifest must actually exist and its hash must match.
2. How to Use
# 1) Preflight: calculate plan only, no model calls, no writes to disk
python scripts/run_task.py --input task.json --preflight-only
# 2) Actual execution (use mock_synthetic to test the full pipeline without keys)
python scripts/run_task.py --input task.json --workspace ./workspace --pretty
# 3) If only some frames fail, retry with the original indices (produces rev2, parent points to rev1)
python scripts/run_task.py --input task.json --retry-failed-of ./workspace/iv_<task>_rev1
Task description (a JSON file; fields match the product parameters in references/provider-compat.md):
{
"task_id": "cup_light_001",
"output_mode": "grid", // grid | sequence
"grid_size": 3, // required for grid: 2 | 3 | 4
"direction": "light", // one of 12 directions, see registry.json
"input_type": "text_only", // text_only | image_only | image_plus_text
"subject": "a light gray ceramic cup", // subject description, goes into subject anchor
"reference_path": "img/ref.png", // required when input includes image; relative to workspace
"aspect_ratio": "3:4",
"resolution_tier": "1K", // 1K | 2K | 4K; default derived from minimum tile edge
"provider": {"type": "mock_synthetic"},
"pack_zip": true
}
sequence additionally requires branch (one of 3 branches supported by the direction) and image_count (4–16).
Real Provider:
"provider": {
"type": "openai_image_compatible", // or gemini_image_compatible
"base_url": "https://api.example.com/v1",
"model_id": "gpt-image-1",
"api_key_secret_ref": "secret://IMAGE_API_KEY",
"capability": { "...": "see §1 capability declaration in provider-compat.md" }
}
If capability is absent, it is treated as non-conforming and reports MODEL_CAPABILITY_UNSUPPORTED—it is a "minimum requirement list"
that cannot be silently filled by default values. If the built-in adapter is not injected, it reports BUILTIN_UNAVAILABLE and does not
automatically switch to an external network.
3. Flow (Branch Rules)
Parse input → Preflight (capability/size ratio/tier/count/budget)
├─ Fail → Report error code, end (no model call, no write to disk)
└─ Pass ─┬─ Grid: Generate board in one shot → Validate (N×N / seamless / tileable / ratio) → Limited full-board retry
│ → Normalize → Row-major tile cropping → Check each tile edge (ok / risk / too_low)
└─ Sequence: First generate N frame plan (frame count, per-frame change points, preserved items, Prompts)
→ Generate frames one by one (frame 1 as anchor; frames 2–N always reference frame 1; if original image exists, every frame includes it)
→ If a single frame fails, keep its slot and continue; if frame 1 fails, immediately SEQUENCE_ANCHOR_FAILED
→ Near-duplicate detection (after retries exhausted, keep slot and mark it)
→ Write to disk (manifest + delivery-package + optional ZIP) → Return JSON result
Key decisions:
| Situation | Handling |
|---|---|
grid_size not 2/3/4, sequence not in 4–16 | INVALID_MODE_OR_COUNT |
| Single tile edge below hard threshold | TILE_RESOLUTION_TOO_LOW, no delivery package |
| Single tile edge below warn threshold | Deliver but record TILE_RESOLUTION_RISK warning (tile_edge_ok=false) |
| Seam < risk threshold | GRID_VALIDATION_FAILED, retry full board; do not output cropped tiles |
| Seam between risk–pass | Deliver and record GRID_SEAM_RISK |
| Board N×N structure/ratio not met | GRID_VALIDATION_FAILED |
| Frame 1 fails | SEQUENCE_ANCHOR_FAILED, stop consuming budget |
| Frame i fails | Keep the original index slot, continue with subsequent frames; final partial_failed |
| Budget about to be exceeded | BUDGET_EXCEEDED (may include split suggestions, but do not split automatically) |
4. Artifacts
workspace/iv_<task_id>_<revision>/
├── manifest.json # image-artifact 1.1 (style/size/seam/execution/warnings/errors)
├── delivery-package.json # Package manifest (sha256 per file)
├── board.png # Only for Grid: kind=board, index=0
└── images/NN.png # Grid=cropped tiles (row-major); Sequence=frames (index does not shift forward)
In the same directory, iv_<task_id>_<revision>.zip is the optional packaging artifact. The ZIP does not contain
delivery-package.json itself; the archive hash is written back into delivery-package.json.
Partial failure: only actually existing images are recorded (failed frames are not in images[]); failure information
is in errors[].asset_id + validation.failed_indices; status=partial_failed.
A retry produces a new revision (parent_artifact_revision points to the previous version), and already successful frames
remain byte-identical.
5. Boundaries
- Only image variations. Copywriting, platform publishing, cover layout belong to Skill 02 (
image-content-publishing); this Skill does not cross that boundary. - If the user explicitly requests multiple directions, pick only one and explain why, or report
MULTIPLE_DIRECTIONS; do not mix. - Do not handle borderline requests like "style transfer to someone else's work"; for content involving real people/brands,
follow the safety requirements in
provider-compat.md §4. - Artifacts from the self-test
mock_syntheticare always markedprovider_type=mock_syntheticand must not be delivered externally.
6. Development and Validation
.venv/bin/python skills/image-variations/tests/run_all.py # 9 suites (including baseline 24/24 and contracts 48/48)
.venv/bin/python shared/check_baseline.py # Baseline read-only validation
Evidence and known deviations are recorded in docs/PHASE_EVIDENCE.md.