| 1 | # Codex: Visual Direction & Asset Production |
| 2 | |
| 3 | This file is loaded by `$impeccable craft` when the harness has native image generation (currently Codex via `image_gen`). Other harnesses skip it. It covers the two craft steps that depend on real image generation: landing the visual direction, and producing the raster assets the implementation will compose. |
| 4 | |
| 5 | Read this *before* generating any images. The order matters, and the per-step user pauses are what keep generated imagery from drifting away from the brief. |
| 6 | |
| 7 | ### Four stop points before code |
| 8 | |
| 9 | Steps A through D each end with the user. Do not advance past any of them on your own read of the situation. |
| 10 | |
| 11 | 1. **STOP after Step A questions.** Wait for answers. |
| 12 | 2. **STOP after Step B palette generation.** Wait for "confirm palette." |
| 13 | 3. **STOP after Step C mocks.** Wait for direction approval or delegation. |
| 14 | 4. **Only after Step D approves a direction** do you return to craft.md Step 4 and write code. |
| 15 | |
| 16 | Prior shape approval does **not** satisfy any of these. Shape's "confirm or override" advances you into Step A; it is not a substitute for it. |
| 17 | |
| 18 | ## Step A: Explore Directions with the User |
| 19 | |
| 20 | Before generating anything, run a brief direction conversation grounded in the shape brief. |
| 21 | |
| 22 | **Step A is required even when shape just produced a confirmed brief.** The shape questions and Step A questions cover different ground: shape pins purpose, content, scope; Step A pins palette, atmosphere, and named visual references for the comps you're about to generate. The only time you can skip Step A is when the user has already answered these exact palette/atmosphere/reference questions in the same session. |
| 23 | |
| 24 | Ask **2-3 targeted questions** about visual lane, color strategy, atmosphere, and named anchor references. Don't enumerate generic menus; tie each question to the shape brief's answers. Example shape-grounded questions: |
| 25 | |
| 26 | - "Brief says 'specimen-page restraint.' Are we closer to a quiet typographic page or a wider editorial spread with hero imagery?" |
| 27 | - "Palette strategy from shape was 'Committed.' Which one color carries the surface (a brand-driven pick rather than a default warm-or-cool framing)? (And no, the answer isn't a cream/sand body bg; that's the saturated AI default.)" |
| 28 | |
| 29 | **STOP and wait for answers.** These pin the palette before any pixel gets generated. Do not proceed to Step B until the user has responded. |
| 30 | |
| 31 | ## Step B: Generate the Brand Palette First |
| 32 | |
| 33 | Generate **one** palette artifact before any mocks. This is a small, focused image: typography pairing on the chosen background, primary + accent color swatches, one signature ornament or motif. Single image, single pass. |
| 34 | |
| 35 | Why palette first: mocks generated against a vague color sense produce noise that drowns out the structural decisions. A confirmed palette is the first concrete contract for everything downstream. |
| 36 | |
| 37 | Show the palette to the user. Ask one question: "This is the palette I'm locking in for the mocks. Confirm, or call out what to shift?" |
| 38 | |
| 39 | **STOP and wait for confirmation.** Do not generate mocks against an unconfirmed palette. "Probably good enough" is the wrong call here; the palette is the contract for everything downstream. |
| 40 | |
| 41 | ## Step C: Generate 1-3 Visual Mocks Against the Palette |
| 42 | |
| 43 | Once the palette is confirmed, generate **1 to 3** high-fidelity north-star comps. Each mock must use the confirmed palette and typography. Mocks differ in *structural* direction (hierarchy, topology, density, composition), not in color or motif. |
| 44 | |
| 45 | - Brand work: push visual identity, composition, mood, and signature motifs. |
| 46 | - Product work: push hierarchy, topology, density, tone, grounded in realistic product structure. |
| 47 | - Landing pages and long-form brand surfaces: show enough of the second fold to establish the system beyond the hero. |
| 48 | |
| 49 | Use the `image_gen` tool directly (or via the imagegen skill when available). Don't ask the user to install anything. |
| 50 | |
| 51 | ## Step D: Approval Loop |
| 52 | |
| 53 | Show the comps. Ask what carries forward. Iterate until **one direction is approved** or the user explicitly delegates. |
| 54 | |
| 55 | **STOP and wait for the approval or the delegation.** Do not begin Step E or return to craft.md Step 4 until a single direction is named. If the user delegates, pick the strongest direction and explain it from the brief, not personal taste. |
| 56 | |
| 57 | Before moving to assets, summarize what to carry into code and what *not* to literalize from the mock. This is the handoff between visual exploration and semantic implementation. |
| 58 | |
| 59 | ## Step E: Mock Fidelity Inventory |
| 60 | |
| 61 | Inventory the approved mock's major visible ingredients. For each, decide implementation: semantic HTML/CSS/SVG, generated raster, sourced raster, icon library, canvas/WebGL, or accepted omission. |
| 62 | |
| 63 | Common ingredients to inventory: |
| 64 | |
| 65 | - Hero silhouette and dominant composition |
| 66 | - Signature motifs (planets, devices, portraits, charts, route lines, insets, badges, etc.) |
| 67 | - Nav and primary CTA treatment |
| 68 | - Section sequence, especially the second fold |
| 69 | - Image-native content the concept depends on |
| 70 | - Typography, density, color/material treatment, motion cues |
| 71 | |
| 72 | Treat the mock as a north star, not a screenshot to trace. Don't rasterize core UI text. But if the live result lacks the mock's major ingredients, the implementation is wrong. |
| 73 | |
| 74 | If a photographic, architectural, product, or place-led mock becomes generic CSS scenery, decorative diagrams, bullets, or copy, stop and fix it. That's a broken implementation, not a harmless interpretation. |
| 75 | |
| 76 | Don't substitute a different hero composition or visual driver post-approval without user sign-off. |
| 77 | |
| 78 | ## Step F: Asset Slicing via the Asset Producer |
| 79 | |
| 80 | Raster ingredients identified in Step E need clean production assets. Use the bundled `impeccable_asset_producer` subagent rather than producing inline. |
| 81 | |
| 82 | Spawn it as a scoped subagent. If you do not have explicit permission to use agents, stop and ask: |
| 83 | |
| 84 | ```text |
| 85 | Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? |
| 86 | ``` |
| 87 | |
| 88 | Pass to the agent: |
| 89 | |
| 90 | - Approved mock path or screenshot reference |
| 91 | - Crop paths or a contact sheet with crop ids |
| 92 | - Output directory |
| 93 | - Required dimensions, format, transparency needs |
| 94 | - Avoid list |
| 95 | - Notes on what should remain semantic HTML/CSS/SVG instead of raster |
| 96 | |
| 97 | Attach image generation capability to the spawned agent when the harness supports it. Do **not** load image-generation reference material into the parent thread. |
| 98 | |
| 99 | Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. |
| 100 | |
| 101 | Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; reach for real, generated, or stock imagery when the mock or subject matter calls for actual visual content. |
| 102 | |
| 103 | ## After This File |
| 104 | |
| 105 | Once Steps A through F are complete, return to `craft.md` Step 5 (Build to Production Quality). The implementation builds against the confirmed palette, approved mock, and the assets the producer wrote. |
| 106 |