design-engine

Design Engine

A post graphic has one job: stop the scroll before the copy is read. Generate multiple candidates against a locked visual style, score them, pick one, and record why. Never post a candidate that fails the style gate, and never fall back to text-only silently.

Inputs

Confirm before generating: the hook (first-line idea of the post), the thesis (the lesson or take behind it), the asset type (post graphic, quote card, newsletter header, meme), and the aspect ratio (default 4:5 for feed posts, wide for newsletter headers). Providers and models come from configuration (<IMAGE_PROVIDER_PRIMARY>, <IMAGE_PROVIDER_FALLBACK>, <IMAGE_MODEL_DEFAULT>), never hardcode them, model catalogs churn.

Workflow

1. Derive the metaphor. Turn the hook and thesis into 3-5 distinct visual metaphors, one clear metaphor per candidate. The image must visually explain the hook, not decorate it.
2. Write the prompts. Apply the locked scene language and hard rules. Read references/visual-style.md before writing prompts: it holds the scene language, palette, and rejection rules. Non-negotiables: no text overlay, no logos, one metaphor per image.
3. Generate candidates. 3-5 images through the primary provider; on provider failure, retry through the fallback. Vertical output on some endpoints requires an explicit image size parameter, not just an aspect-ratio field; verify dimensions on the first return.
4. Score every candidate on the rubric: reference match (feels like the locked style, not generic AI art), metaphor clarity, scroll-stop strength, composition (clear subject, strong depth), brand fit, cleanliness (no text artifacts, broken anatomy, or model noise).
5. Select or reject. Pick one winner. If all candidates fail the reference-match gate, regenerate with a different model or provider. If they still fail, log the failure and stop. Do not let a text-only post ship as a silent fallback, and do not ship "close enough".
6. Record the run. Save under design-engine/<channel>/<date>/: all candidates, selection.md (scores, winner, reason), selection.json (selectedPath, reason, scores, for automation), and a provider run log (provider, model, request id, latency, status, errors).
7. Hand off the selected path to the posting workflow. While the style is still being locked with the owner, require owner approval on the next few selections before autonomous use.

Verification

Open the selected image at full size. Expect: no rendered text or logo fragments, no broken hands or faces, a subject readable at thumbnail size, and dimensions matching the requested ratio. Then check selection.json parses and its selectedPath exists on disk. If any check fails, the selection record is invalid: rescore or regenerate before handoff.

Good vs Bad

Judgment call: hook is "Agent drift will embarrass a lot of teams."

Bad prompt: "Futuristic AI dashboard with glowing neural network, robot hand, cyberpunk city, dramatic lighting." Generic AI wallpaper, zero metaphor, instant rejection.

Good prompt: "A vast coastal highway veering imperceptibly off its painted lane toward a cliff edge, cinematic matte-painting style, cobalt sky, hot coral accents, extreme scale, one tiny maintenance figure looking away." One metaphor (drift), locked palette, expensive and strange.

Footguns

• Prompting the topic instead of a metaphor. "AI agents working" produces stock-photo mush. Fix: force one concrete visual metaphor per candidate before prompting.
• Trusting the aspect-ratio field. Some endpoints ignore it and return landscape. Fix: pass explicit dimensions and check the first output's size.
• Style drift across a week of posts. Each session re-invents the look and the feed turns incoherent. Fix: prompts pull scene language only from references/visual-style.md; propose style changes there, not inline.
• Silent text-only fallback. A failed generation quietly becomes a plain post and nobody notices the pipeline broke. Fix: failure is logged and surfaced, the posting workflow decides, not this skill.

Completion Checklist

• [ ] Hook, thesis, type, and ratio confirmed
• [ ] 3-5 candidates generated, one metaphor each
• [ ] Every candidate scored on the full rubric
• [ ] Winner passes the reference-match gate, or failure logged and surfaced
• [ ] selection.md, selection.json, and provider run log saved
• [ ] Verification checks passed on the winner

Any box unchecked: not done. Fix or say so.