image-gen

Generate an image from a prompt, with a visible pipeline the user can inspect and edit.

The pipeline is the skill - editing a step mutates this file.

Steps

1. Parse intent

Extract the image subject, style, and mood from the user's prompt.

# No side effects. Extract: subject, style, mood, aspect ratio.
# Default aspect: 1024x1024 square. Default style: natural photorealistic.

2. Expand the prompt

Rewrite the raw intent into a rich generation prompt.

# Expand subject into vivid detail: lighting, camera angle, color palette.
# Keep under 400 chars for DALL-E 3 compatibility.
# Append negative: "blurry, watermark, low quality" to end.

3. Pick the model

Select the backend based on available credentials.

OPENAI_API_KEY_EXISTS=$([ -n "$OPENAI_API_KEY" ] && echo "yes" || echo "no")
REPLICATE_API_KEY_EXISTS=$([ -n "$REPLICATE_API_KEY" ] && echo "yes" || echo "no")
# if OPENAI_API_KEY: use dall-e-3
# elif REPLICATE_API_KEY: use stability-ai/sdxl
# else: emit graceful Callout (no key — skip generation)

4. Generate the image

Call the selected model API with the expanded prompt.

# DALL-E 3 path:
#   POST https://api.openai.com/v1/images/generations
#   body: { model: "dall-e-3", prompt: "<expanded>", n: 1, size: "1024x1024" }
#   response: data[0].url
#
# Replicate path:
#   POST https://api.replicate.com/v1/models/stability-ai/sdxl/predictions
#   body: { input: { prompt: "<expanded>", negative_prompt: "...", width: 1024, height: 1024 } }
#   poll until status="succeeded", response: output[0]

5. Verify the output

Confirm the URL is reachable and the image is non-empty.

# HEAD <url>: expect 200 and content-type image/*
# If fail: retry once, then emit Callout with "generation failed".

6. Return the result

Emit an ImagePreview card with the URL, prompt used, and model name.

# Return: { url, prompt_used, model, width, height, ts }
# Log to state/log/chain.ndjson: { ts, skill: "image-gen", url, model }

Eval

Actor: the generation model (DALL-E 3 or SDXL). Auditor: Gemini vision model inspects for subject match + quality.

Gotchas

• Step 3 is the API key gate - if neither key exists, the pipeline short-circuits to a Callout. The user should see a helpful message with setup instructions, not an error.
• DALL-E 3 does NOT support n > 1 with hd quality. Keep n=1.
• Replicate predictions can take 15-45s. Poll every 2s with a 60s timeout.
• Prompt expansion (Step 2) is the highest-leverage step - editing it is the most common user action.
• Empty negative prompt causes poorer results. Always include the default negative.

image-gen - loader

Per-turn rules for the image-gen skill. Full skill: state/skills/image-gen/SKILL.md (6-step pipeline: parse intent → expand prompt → pick model → generate → verify → return).

Critical Rules

1. Pipeline = SKILL.md Steps. Each ### N. Title is a step. Edit via POST /skills/image-gen/edit-step { step_index: N, new_body: "..." }.
2. No-key fallback: emit Callout + PipelineDiagram. Show setup instructions if both OPENAI_API_KEY and REPLICATE_API_KEY absent. Never attempt generation without a key.
3. Key gate: OPENAI → DALL-E 3 | REPLICATE → SDXL | neither → Callout only.
4. DALL-E 3: n=1 only. Does NOT support n > 1 with hd quality.
5. Replicate: poll every 2s, timeout 60s. Predictions 15-45s. Poll status="succeeded", return output[0].
6. Step 2 (prompt expansion) is highest-leverage. Vivid detail (lighting, camera, palette), <400 chars, default negative "blurry, watermark, low quality".
7. Feedback via POST /skills/:slug/feedback. Appends to state/skills/:slug/feedback.ndjson (rating 1-5).
8. Pipeline history: git log --oneline -10 -- state/skills/image-gen/SKILL.md. Emit DiffView if ≥2 commits.
9. Rollback via git is destructive. Warn user before git checkout HEAD~1 -- state/skills/image-gen/SKILL.md.

Commands

Self-Test

• [ ] Pipeline = SKILL.md Steps, edit via POST /skills/image-gen/edit-step?
• [ ] Emit Callout + PipelineDiagram when no API keys?
• [ ] Route correctly: OpenAI → DALL-E 3, Replicate → SDXL?
• [ ] DALL-E 3 n=1 only?
• [ ] Replicate: poll 2s, timeout 60s?
• [ ] Step 2 (prompt expansion) is highest-leverage?
• [ ] Feedback appends to feedback.ndjson?
• [ ] Pipeline history via git log?
• [ ] Warn before destructive rollback?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] image-gen: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate. Pick the value that describes what you actually did:
• shape-ok - frontmatter-shape verification only
• skill-ran - the skill ran end-to-end with eval row in state/log/evals.ndjson
• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case), OR regen rewrote it
• pattern-elevated - you promoted a recurring failure to a Critical Rule

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.