image-companion

What this skill does

# Image Companion

Invoke with `/image-companion` (or whenever the user wants a slide-ready image for a
passage in a document they are working on).

Supply images that **belong to one artifact**. The user owns a document — an article,
a deck, a design doc — and points at a passage or mechanism inside it. Your job is to
produce a slide-ready symbolic image that fits *that* spot and looks like it came from
the same hand as the artifact's other images.

This is not a one-shot "make an image" tool. The relationship is **lifetime
companionship**: across a session you may produce many images for the same artifact, and
the defining duty is that they read as one set. Visual consistency is a first-class
responsibility, not an afterthought.

You orchestrate two existing skills and add the human-judgment and quality layers around
them. Delegate grounding to /forge and generation to the Codex CLI; your own role is the
metaphor design, the human gate, verification, and series coherence.

```
bind artifact + passage
  → (recommended) metaphor preview gate   ← human picks the visual idea cheaply
  → /forge   (grounding + gpt-image prompt block)        [DELEGATE]
  → Codex CLI   (gpt-image-2 generation)                 [DELEGATE]
  → verify + enforce series coherence + report
```

## Step 0 — Bind the artifact and the target

Read the artifact passage the user is pointing at. Extract the **mechanism** to
symbolize (not just the sentence — the underlying thing it claims). This is per-call
data; nothing here is fixed.

Then locate the **companion set**: other images already made for this artifact (same
output directory, or earlier in this session). Their palette, tone, and text rules are
the consistency contract for the new image. If this is the first image, you are
*establishing* the contract — record the choices so later calls inherit them.

Carry the design-tone context forward by continuing in the same session. Compaction
preserves it; that is how series coherence survives a long-running artifact.

## Step 1 — Metaphor preview gate (recommended, not required)

Image generation costs real time and money. Before spending it, agree on the visual
idea in plain text. This step is **recommended** — skip it only when the user has
already named the exact metaphor.

1. Design 2–3 candidate metaphors for the mechanism. Keep them free of domain jargon
   (no SQL/JOIN/INNER/OUTER, no internal API names *in the image*) so an all-hands
   audience reads them at a glance.
2. Sketch each candidate as small **ASCII art** and put it in the `preview` field of an
   `AskUserQuestion` option, so the user compares the *ideas* in the terminal before any
   pixels are generated.
3. In the same gate, ask the **loss-depiction depth** when the passage describes a
   failure/loss: neutral (mechanism only) vs. show-through-to-the-loss (depict the bad
   outcome). This choice changes the image's punchline.

The ASCII preview is a cheap proxy that has repeatedly de-risked the expensive step —
treat it as the default, but don't force it on a user who already knows what they want.

## Step 2 — Structure the initial prompt with /forge

Invoke `epistemic-cooperative:forge` with the **gpt-image adapter**. Forge's job here is
not just to "write a prompt" — it is to **structure the initial prompt so that the
character extracted from the artifact is preserved**. Two things make up that character:
the grounded essence of the passage (what the mechanism actually claims) and the
companion set's identity (palette, tone, text rules). Forge encodes both into the
structured prompt, so the prompt block itself becomes the carrier of artifact fidelity —
not something checked back in afterward.

Forge owns the reference grounding and fills the `infographic-diagram` prompt schema (Use
case / Asset type / Primary request / Scene / Subject / Style / Composition / Lighting /
Color palette / Text verbatim / Constraints / Avoid). Hand it: the artifact passage, the
chosen metaphor, the loss-depth decision, and the house-style constraints from
`references/house-style.md` (Step 0's companion-set reading is what makes those
constraints concrete). You do not write the schema yourself — forge does.

## Step 3 — Generate via Codex CLI

Call the Codex CLI directly, in the same form as `/review-ensemble` and `/goal-research`.
This runs gpt-image-2 generation as an independent model call.

Check `which codex 2>/dev/null`. If the Codex CLI is not found, surface the
missing-binary error and stop — failure modes are raw errors, not handled internally.

Generate a unique suffix: `SUFFIX=$(openssl rand -hex 4)`. Write forge's prompt block to
`/tmp/image_companion_${SUFFIX}.txt`. The prompt MUST be English and MUST include the
`$imagegen` marker so Codex engages image generation.

Launch via `Bash(run_in_background: true, timeout: 600000)`, with `--cd` pointing at the
artifact's image directory so the PNG lands beside its companions:

```bash
codex exec --ephemeral --json --color never --skip-git-repo-check -m gpt-5.5 \
  --config model_reasoning_effort="medium" \
  --sandbox workspace-write \
  --cd <artifact-image-dir> \
  < /tmp/image_companion_${SUFFIX}.txt \
  > /tmp/image_companion_events_${SUFFIX}.jsonl 2>/tmp/image_companion_warn_${SUFFIX}.txt
```

`--color never` + splitting the streams keeps the events file pure JSONL (stdout) and the codex
banner — where the warnings ride — in its own warn file (stderr). For multiple images, launch one
background call per image in the same turn so they run in parallel — each with its own `${SUFFIX}`,
so parallel streams never collide. Each completion sends a notification — then read that call's
events file and clean up its three temp files:
`rm -f /tmp/image_companion_${SUFFIX}.txt /tmp/image_companion_events_${SUFFIX}.jsonl /tmp/image_companion_warn_${SUFFIX}.txt`.
Wait for the completion notification before reading output.

The events file is pure JSONL. Extract the codex `agent_message` narrative verbatim with the line
below and forward it to Step 4 — the PNG-confirmation and any in-message notes you surface there are
read from this narrative, not regex-parsed. **If the extraction is empty, codex failed before
answering** — read the raw events file `/tmp/image_companion_events_${SUFFIX}.jsonl` for the error
and surface that instead of reporting a successful generation:

```bash
jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text' /tmp/image_companion_events_${SUFFIX}.jsonl
```

Some codex warnings (e.g. `invalid_grant` auth-token failures, `--full-auto` deprecation) ride the
**stderr banner**, not `agent_message` — the launch sent stderr to its own warn file. Grep that to
catch what the narrative does not carry:

```bash
grep -iE 'invalid_grant|deprecat|--full-auto|warn' /tmp/image_companion_warn_${SUFFIX}.txt || true
```

Running in the background keeps Codex's verbose banner out of the main context. The model
(`-m gpt-5.5`) is fixed by design — Codex substitutes its own internal image skill
targeting gpt-image-2, so the model is structural, not a quality knob (see
`references/house-style.md`). Note: `--ephemeral` means there is no resumable session — a
correction is a fresh run with a corrective prompt, not a session resume.

## Step 4 — Verify, enforce coherence, report

Read the produced PNG and run the checklist in `references/verification.md`. The image
fails review if in-image text is not the verbatim English/numeric strings, if any
CJK/SQL/JOIN text appears, if it is not landscape, or if the palette breaks the
companion set's contract (two brand colors + exactly one reserved accent for the single
emphasized moment).

Then produce a consolidated report in the user's language using the template in
`references/verification.md`: a table with image, filename, and verdict, plus any
non-fatal warnings (e.g., auth-token refresh notices, deprecation notices) — read from the
extracted `agent_message` narrative (Step 3 jq line) AND from the Step 3 warn-fil