From 96c6565cae433eef549297145aaa13b66b77ad94 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Wed, 22 Apr 2026 15:57:18 -0700 Subject: [PATCH] Improve image-guided shape and craft flows --- .agents/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .agents/skills/impeccable/reference/live.md | 3 +- .agents/skills/impeccable/reference/shape.md | 40 ++++++++++- .claude/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .claude/skills/impeccable/reference/live.md | 3 +- .claude/skills/impeccable/reference/shape.md | 40 ++++++++++- .cursor/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .cursor/skills/impeccable/reference/live.md | 3 +- .cursor/skills/impeccable/reference/shape.md | 40 ++++++++++- .gemini/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .gemini/skills/impeccable/reference/live.md | 3 +- .gemini/skills/impeccable/reference/shape.md | 40 ++++++++++- .github/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .github/skills/impeccable/reference/live.md | 3 +- .github/skills/impeccable/reference/shape.md | 40 ++++++++++- .kiro/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .kiro/skills/impeccable/reference/live.md | 3 +- .kiro/skills/impeccable/reference/shape.md | 40 ++++++++++- .../skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .opencode/skills/impeccable/reference/live.md | 3 +- .../skills/impeccable/reference/shape.md | 40 ++++++++++- .pi/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .pi/skills/impeccable/reference/live.md | 3 +- .pi/skills/impeccable/reference/shape.md | 40 ++++++++++- .rovodev/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .rovodev/skills/impeccable/reference/live.md | 3 +- .rovodev/skills/impeccable/reference/shape.md | 40 ++++++++++- .trae-cn/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .trae-cn/skills/impeccable/reference/live.md | 3 +- .trae-cn/skills/impeccable/reference/shape.md | 40 ++++++++++- .trae/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- .trae/skills/impeccable/reference/live.md | 3 +- .trae/skills/impeccable/reference/shape.md | 40 ++++++++++- source/skills/impeccable/reference/craft.md | 66 +++++++++++++++++-- source/skills/impeccable/reference/live.md | 3 +- source/skills/impeccable/reference/shape.md | 40 ++++++++++- 36 files changed, 1224 insertions(+), 84 deletions(-) diff --git a/.agents/skills/impeccable/reference/craft.md b/.agents/skills/impeccable/reference/craft.md index 3b95aac83..45249f46c 100644 --- a/.agents/skills/impeccable/reference/craft.md +++ b/.agents/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.agents/skills/impeccable/reference/live.md b/.agents/skills/impeccable/reference/live.md index 0cf0ab53a..afbcff18b 100644 --- a/.agents/skills/impeccable/reference/live.md +++ b/.agents/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.agents/skills/impeccable/reference/shape.md b/.agents/skills/impeccable/reference/shape.md index 66f106b4f..ea4e3f765 100644 --- a/.agents/skills/impeccable/reference/shape.md +++ b/.agents/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to $impeccable craft, or directly to $impeccable for freeform implementation. +**Output**: A design brief that can be handed off to $impeccable craft, or directly to $impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.claude/skills/impeccable/reference/craft.md b/.claude/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.claude/skills/impeccable/reference/craft.md +++ b/.claude/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.claude/skills/impeccable/reference/live.md b/.claude/skills/impeccable/reference/live.md index e0de59d27..8dbaee2f4 100644 --- a/.claude/skills/impeccable/reference/live.md +++ b/.claude/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.claude/skills/impeccable/reference/shape.md b/.claude/skills/impeccable/reference/shape.md index a83ca85fd..609e6a83a 100644 --- a/.claude/skills/impeccable/reference/shape.md +++ b/.claude/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.cursor/skills/impeccable/reference/craft.md b/.cursor/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.cursor/skills/impeccable/reference/craft.md +++ b/.cursor/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.cursor/skills/impeccable/reference/live.md b/.cursor/skills/impeccable/reference/live.md index c9ed2bacc..64822bfe8 100644 --- a/.cursor/skills/impeccable/reference/live.md +++ b/.cursor/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.cursor/skills/impeccable/reference/shape.md b/.cursor/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.cursor/skills/impeccable/reference/shape.md +++ b/.cursor/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.gemini/skills/impeccable/reference/craft.md b/.gemini/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.gemini/skills/impeccable/reference/craft.md +++ b/.gemini/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.gemini/skills/impeccable/reference/live.md b/.gemini/skills/impeccable/reference/live.md index 7fdaac105..162ede687 100644 --- a/.gemini/skills/impeccable/reference/live.md +++ b/.gemini/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.gemini/skills/impeccable/reference/shape.md b/.gemini/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.gemini/skills/impeccable/reference/shape.md +++ b/.gemini/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.github/skills/impeccable/reference/craft.md b/.github/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.github/skills/impeccable/reference/craft.md +++ b/.github/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.github/skills/impeccable/reference/live.md b/.github/skills/impeccable/reference/live.md index b7e4f968a..59e191cf3 100644 --- a/.github/skills/impeccable/reference/live.md +++ b/.github/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.github/skills/impeccable/reference/shape.md b/.github/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.github/skills/impeccable/reference/shape.md +++ b/.github/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.kiro/skills/impeccable/reference/craft.md b/.kiro/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.kiro/skills/impeccable/reference/craft.md +++ b/.kiro/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.kiro/skills/impeccable/reference/live.md b/.kiro/skills/impeccable/reference/live.md index 55db8aa14..65c5475b6 100644 --- a/.kiro/skills/impeccable/reference/live.md +++ b/.kiro/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.kiro/skills/impeccable/reference/shape.md b/.kiro/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.kiro/skills/impeccable/reference/shape.md +++ b/.kiro/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.opencode/skills/impeccable/reference/craft.md b/.opencode/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.opencode/skills/impeccable/reference/craft.md +++ b/.opencode/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.opencode/skills/impeccable/reference/live.md b/.opencode/skills/impeccable/reference/live.md index 0ad537c2d..7fdcb0bb7 100644 --- a/.opencode/skills/impeccable/reference/live.md +++ b/.opencode/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.opencode/skills/impeccable/reference/shape.md b/.opencode/skills/impeccable/reference/shape.md index bb36d314c..6c74df043 100644 --- a/.opencode/skills/impeccable/reference/shape.md +++ b/.opencode/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.pi/skills/impeccable/reference/craft.md b/.pi/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.pi/skills/impeccable/reference/craft.md +++ b/.pi/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.pi/skills/impeccable/reference/live.md b/.pi/skills/impeccable/reference/live.md index 9a5d417db..64570f56a 100644 --- a/.pi/skills/impeccable/reference/live.md +++ b/.pi/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.pi/skills/impeccable/reference/shape.md b/.pi/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.pi/skills/impeccable/reference/shape.md +++ b/.pi/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.rovodev/skills/impeccable/reference/craft.md b/.rovodev/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.rovodev/skills/impeccable/reference/craft.md +++ b/.rovodev/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.rovodev/skills/impeccable/reference/live.md b/.rovodev/skills/impeccable/reference/live.md index b77547437..b1187a25d 100644 --- a/.rovodev/skills/impeccable/reference/live.md +++ b/.rovodev/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.rovodev/skills/impeccable/reference/shape.md b/.rovodev/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.rovodev/skills/impeccable/reference/shape.md +++ b/.rovodev/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.trae-cn/skills/impeccable/reference/craft.md b/.trae-cn/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.trae-cn/skills/impeccable/reference/craft.md +++ b/.trae-cn/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.trae-cn/skills/impeccable/reference/live.md b/.trae-cn/skills/impeccable/reference/live.md index 0f2c3ec8a..87a6acc2b 100644 --- a/.trae-cn/skills/impeccable/reference/live.md +++ b/.trae-cn/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.trae-cn/skills/impeccable/reference/shape.md b/.trae-cn/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.trae-cn/skills/impeccable/reference/shape.md +++ b/.trae-cn/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/.trae/skills/impeccable/reference/craft.md b/.trae/skills/impeccable/reference/craft.md index b038cf96d..163ca78f9 100644 --- a/.trae/skills/impeccable/reference/craft.md +++ b/.trae/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/.trae/skills/impeccable/reference/live.md b/.trae/skills/impeccable/reference/live.md index ef359d84b..15ccead5c 100644 --- a/.trae/skills/impeccable/reference/live.md +++ b/.trae/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/.trae/skills/impeccable/reference/shape.md b/.trae/skills/impeccable/reference/shape.md index 7419e792d..7e5d40eac 100644 --- a/.trae/skills/impeccable/reference/shape.md +++ b/.trae/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. +**Output**: A design brief that can be handed off to /impeccable craft, or directly to /impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief. diff --git a/source/skills/impeccable/reference/craft.md b/source/skills/impeccable/reference/craft.md index 4374144f4..57e2f9882 100644 --- a/source/skills/impeccable/reference/craft.md +++ b/source/skills/impeccable/reference/craft.md @@ -24,7 +24,61 @@ Then add references based on the brief's needs: - Responsive requirements? Consult [responsive-design.md](responsive-design.md) - Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md) -## Step 3: Build +## Step 3: North Star Mock (Capability-Gated) + +Before implementation, generate a small set of high-fidelity visual comps when all of these are true: + +- The work is **net-new** or visually open-ended enough that composition exploration will improve the build. +- The brief's scope is **mid-fi, high-fi, or production-ready**. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default for **both brand and product work**. + +### Purpose + +Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone. + +### What to generate + +Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. + +- For brand work, push visual identity, composition, and mood aggressively. +- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states. + +The comps must be genuinely different in primary visual direction, not just color variants. + +### After generation + +Choose a direction with the user, or if the user delegated the decision, pick the strongest one and explain why. + +Before moving to implementation, summarize: + +- What to carry into code +- What **not** to literalize from the mock + +Treat the mock as a **north star**, not a screenshot to trace. Do **not** let it override the confirmed brief. + +## Step 4: Asset Extraction (Optional) + +If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. + +Good candidates: + +- stickers +- badges +- seals +- tickets +- graphic labels +- textures +- abstract objects +- decorative marks +- non-semantic scene elements + +Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code. + +Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. + +## Step 5: Build Implement the feature following the design brief. Work in this order: @@ -40,9 +94,11 @@ Implement the feature following the design brief. Work in this order: - Test with real (or realistic) data at every step, not placeholder text - Check each state as you build it, not all at the end - If you discover a design question, stop and ask rather than guessing -- Every visual choice should trace back to something in the design brief +- Every visual choice should trace back to something in the design brief or the chosen north-star direction +- Keep text semantic, layout real, and interactions accessible. Do not turn the mock into a pile of rasterized UI +- If assets were extracted, use them intentionally. They support the build; they do not replace interface structure -## Step 4: Visual Iteration +## Step 6: Visual Iteration **This step is critical.** Do not stop after the first implementation pass. @@ -59,12 +115,12 @@ Iterate through these checks visually: After each round of fixes, visually verify again. **Repeat until you would be proud to show this to the user.** The bar is not "it works"; the bar is "this delights." -## Step 5: Present +## Step 7: Present Present the result to the user: - Show the feature in its primary state - Walk through the key states (empty, error, responsive) -- Explain design decisions that connect back to the design brief +- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock - Ask: "What's working? What isn't?" Iterate based on feedback. Good design is rarely right on the first pass. diff --git a/source/skills/impeccable/reference/live.md b/source/skills/impeccable/reference/live.md index 1f4438679..95ef8094f 100644 --- a/source/skills/impeccable/reference/live.md +++ b/source/skills/impeccable/reference/live.md @@ -9,7 +9,7 @@ A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR Execute in order. No step skipped, no step reordered. 1. `live.mjs` — boot. -2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). **If the session has browser automation (e.g. Claude Code / Cursor with Chrome MCP), open the tab yourself before the first poll.** Otherwise, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. +2. Navigate to the URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). If you can't infer it confidently, tell the user once to open their dev/preview URL. Never use `serverPort` as that URL — it's the helper, not the app. 3. Poll loop with the default long timeout (600000 ms). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`. 4. On `generate` — read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again. 5. On `accept` / `discard` — the poll script already cleaned up; just poll again. @@ -18,6 +18,7 @@ Execute in order. No step skipped, no step reordered. Harness policy: - **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free. Do not block the shell. - **Cursor**: run the poll in the **foreground** (blocking shell — not a background terminal, not a subagent). Cursor background terminals and subagents do not reliably resume the chat with poll stdout. +- **Codex**: run the poll in the **foreground** (blocking shell — not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode. - **Other harnesses**: foreground unless you know stdout reliably returns to this session. Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences. diff --git a/source/skills/impeccable/reference/shape.md b/source/skills/impeccable/reference/shape.md index 9577f202c..34e15c21a 100644 --- a/source/skills/impeccable/reference/shape.md +++ b/source/skills/impeccable/reference/shape.md @@ -2,7 +2,7 @@ Shape the UX and UI for a feature before any code is written. This command produ **Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good. -**Output**: A design brief that can be handed off to {{command_prefix}}impeccable craft, or directly to {{command_prefix}}impeccable for freeform implementation. +**Output**: A design brief that can be handed off to {{command_prefix}}impeccable craft, or directly to {{command_prefix}}impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output. ## Philosophy @@ -55,6 +55,42 @@ Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — c - What should this NOT be? What would be a wrong direction? - What's the biggest risk of getting this wrong? +## Phase 1.5: Visual Direction Probe (Capability-Gated) + +After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true: + +- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief. +- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning. +- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this. + +When those conditions are met, this step is the default. Use it to explore visual lanes, not to replace the brief. + +### What to generate + +Generate **2 to 4** distinct direction probes based on the discovery answers, especially: + +- Color strategy +- Theme scene sentence +- Named anchor references +- Scope and fidelity + +The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks. + +### How to use the probes + +- Treat them as **direction tests**, not final designs. +- Use them to pressure-test whether the brief is pointing at the right lane. +- Ask the user which direction feels closest, what feels off, and what should carry forward. +- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief. + +### Important limits + +- Do **not** skip discovery because image generation is available. +- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior. +- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice. + +If image generation is unavailable, or the task doesn't benefit from it, skip this phase and proceed directly to the design brief. + ## Phase 2: Design Brief After the interview, synthesize everything into a structured design brief. Present it to the user for confirmation before considering this command complete. @@ -70,6 +106,8 @@ The single most important thing a user should do or understand here. **3. Design Direction** Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides. +If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it. + **4. Scope** Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief.