polish-with-images

/polish-with-images — Plan a coherent image system for an existing page

Purpose

Find the exact places where illustrations or images would materially improve an existing webpage, define one professional art direction, and produce a generation-ready specification with few, medium, and many-image options.

This command plans only. It does not generate images or change production code before the user chooses a tier and approves the spec.

Invocation

/polish-with-images <route/page and desired outcome>

Examples:

/polish-with-images / Make the landing page feel more credible and memorable
/polish-with-images /features Explain the workflow visually without making it busy
/polish-with-images /about Add a coherent editorial illustration system

Accepted input

An existing route/page, screenshots or references, desired mood or medium, brand constraints, audience, product claims, and optional asset-count or performance limits.

Prerequisites

A HarnessKit workspace and an existing webpage. A runnable preview is strongly preferred. Static source or screenshots may be used with lower-confidence findings.

Procedure

1. Apply context-discovery. Resolve the exact page, audience, primary task, intended outcome, preview command, stable content/data, supported themes, relevant viewports, existing assets, and asset-delivery conventions.
2. Inspect repository and page evidence before asking questions. Ask one grouped batch of at most three decision-changing questions only when necessary:
   • illustration, photography, diagram, product capture, or mixed medium;
   • immutable brand/reference constraints;
   • acceptable performance/licensing/generation-provider constraints. Propose evidence-backed defaults for unanswered preferences.
3. Have visual-qa-tester capture the current page at representative narrow, medium, and wide viewports. Record hierarchy, long text runs, abstract claims, trust gaps, empty states, page rhythm, existing imagery, LCP candidates, themes, and responsive behavior.
4. Have visual-assets-director apply image-art-direction, visual-craft, and design-system-integration. Produce a candidate-slot inventory. For every possible location record:
   • exact route, section/landmark, component, and surrounding copy;
   • the user or communication problem;
   • proposed image role and why image is better than copy/layout alone;
   • expected value, confidence, accessibility/performance risk, and rejection reason if omitted.
5. Define one page-wide style lock grounded in existing brand evidence: medium, perspective, composition, palette, lighting, texture, geometry, line/edge treatment, depth, detail, background, whitespace, representation, crop behavior, and forbidden motifs. Include an exact shared prompt prefix and suffix. Every asset prompt must repeat them verbatim so independent generation calls remain stylistically consistent.
6. Build three cumulative tiers:
   • Tier 1 — Few / essential: normally 1–3 highest-value assets.
   • Tier 2 — Medium / balanced: normally 4–7 total assets and includes Tier 1.
   • Tier 3 — Many / editorial: normally 8–12 total assets and includes Tier 2, but may use fewer when additional images would become filler. For each tier state the outcome, included asset IDs, page-weight budget, implementation effort, strengths, risks, and why it is meaningfully better than the tier below.
7. Create a complete asset registry. Every asset must specify:
   • stable ID and tiers containing it;
   • exact placement and visual purpose;
   • asset type, unique subject/action, composition, mood, and focal point;
   • one self-contained generation prompt containing the exact shared style lock;
   • negative constraints and prohibited content;
   • aspect ratio and slot-specific source resolution(s);
   • rendered dimensions by breakpoint, safe crop, responsive srcset/art direction, and optional theme variants;
   • alt text or explicit decorative rationale, caption if required;
   • format, compression target, loading priority, LCP implications, dimensions, fallback, and maximum file size;
   • content/licensing dependencies and visual acceptance criteria. Resolutions should differ when placements differ; do not normalize a hero, portrait, card, and inline diagram to one canvas size.
8. Have visual-craft-specialist review the three tiers and prompts for product specificity, stylistic consistency, hierarchy, visual repetition, generic AI motifs, content integrity, and over-decoration. Resolve findings before persisting the spec.
9. Write .agent/specs/<kebab-case-name>.md using the required frontmatter below. Include findings, candidate/rejected slots, style lock, all three tiers, asset registry, implementation tasks, asset-generation/selection QA, integration plan, accessibility, performance budgets, browser scenarios, risks, non-goals, and open decisions.
10. Present a concise comparison table and recommend one tier based on user value and cost. Then provide a /sum-spec-style summary and stop for the user to choose a tier and explicitly approve the spec.