From ea2e372564dd9d4e09a92b92fbb442eeffd176cb Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Wed, 6 May 2026 16:14:07 -0700 Subject: [PATCH] skill: strip gate ceremony; require shape pause; allow compact briefs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The setup gate table and IMPECCABLE_PREFLIGHT banner pushed every craft run through ritual restatement (PRODUCT.md → original prompt → round 1 → round 2 → 70-line "confirmed brief" → critique → summary, all saying the same thing). Replaced with imperative prose that still demands the same work but skips the user-facing telemetry. Specifically: SKILL.md - Drop the Setup gate table and IMPECCABLE_PREFLIGHT banner. - Keep the imperative steps explicitly: load context, identify register and load brand.md or product.md, AND load the matching command reference (craft.md / shape.md / etc.) when a sub-command is invoked. The command-reference step is non-negotiable; without craft.md loaded the agent skips the shape-and-confirm pause. craft.md - Drop the Build Gate / Craft Contract formal sections; replace with one paragraph stating prerequisites. - Step 1 explicitly requires ending the response after presenting the shape output; the user must confirm before any code lands. Allows a compact 3-5 bullet brief when the prompt + PRODUCT.md already pin direction (full 10-section structure reserved for genuinely ambiguous tasks). - Step 3 image gate skips silently when image generation isn't natively available; no user-facing announcement. - Step 6 explicitly legitimizes "first pass clean, shipping" as a valid endpoint and bans inventing fake defects to demonstrate iteration. shape.md - Cap discovery at 1 round by default; second round only when first leaves material gaps. - Adds an "assert-then-confirm, not menu-with-escape" rule: when PRODUCT.md and the prompt make one option obvious, name it and ask for confirm or override instead of enumerating "Restrained / Committed / Or something else?" as a real choice. - Phase 2 brief has two forms now: compact (default for clear briefs) and full structured (genuinely ambiguous). Open Questions can't double as leading-with-Recommend; if you'd write "Recommend: X", decide X. - Image gate same as craft.md. Validated end-to-end with a Haiku skill-on observability run: agent loads craft.md plus the brief's recommended implementation refs, pauses for one productive question (accent color, trace fidelity, CTA), and ships an artifact with zero side-tab violations vs. the original v1 baseline. Cost trades up modestly for that quality. Co-Authored-By: Claude Opus 4.7 (1M context) --- .agents/skills/impeccable/SKILL.md | 25 ++---- .agents/skills/impeccable/reference/craft.md | 77 ++++++------------- .agents/skills/impeccable/reference/shape.md | 33 +++++--- .claude/skills/impeccable/SKILL.md | 25 ++---- .claude/skills/impeccable/reference/craft.md | 77 ++++++------------- .claude/skills/impeccable/reference/shape.md | 33 +++++--- .cursor/skills/impeccable/SKILL.md | 25 ++---- .cursor/skills/impeccable/reference/craft.md | 77 ++++++------------- .cursor/skills/impeccable/reference/shape.md | 33 +++++--- .gemini/skills/impeccable/SKILL.md | 25 ++---- .gemini/skills/impeccable/reference/craft.md | 77 ++++++------------- .gemini/skills/impeccable/reference/shape.md | 33 +++++--- .github/skills/impeccable/SKILL.md | 25 ++---- .github/skills/impeccable/reference/craft.md | 77 ++++++------------- .github/skills/impeccable/reference/shape.md | 33 +++++--- .kiro/skills/impeccable/SKILL.md | 25 ++---- .kiro/skills/impeccable/reference/craft.md | 77 ++++++------------- .kiro/skills/impeccable/reference/shape.md | 33 +++++--- .opencode/skills/impeccable/SKILL.md | 25 ++---- .../skills/impeccable/reference/craft.md | 77 ++++++------------- .../skills/impeccable/reference/shape.md | 33 +++++--- .pi/skills/impeccable/SKILL.md | 25 ++---- .pi/skills/impeccable/reference/craft.md | 77 ++++++------------- .pi/skills/impeccable/reference/shape.md | 33 +++++--- .qoder/skills/impeccable/SKILL.md | 25 ++---- .qoder/skills/impeccable/reference/craft.md | 77 ++++++------------- .qoder/skills/impeccable/reference/shape.md | 33 +++++--- .rovodev/skills/impeccable/SKILL.md | 25 ++---- .rovodev/skills/impeccable/reference/craft.md | 77 ++++++------------- .rovodev/skills/impeccable/reference/shape.md | 33 +++++--- .trae-cn/skills/impeccable/SKILL.md | 25 ++---- .trae-cn/skills/impeccable/reference/craft.md | 77 ++++++------------- .trae-cn/skills/impeccable/reference/shape.md | 33 +++++--- .trae/skills/impeccable/SKILL.md | 25 ++---- .trae/skills/impeccable/reference/craft.md | 77 ++++++------------- .trae/skills/impeccable/reference/shape.md | 33 +++++--- plugin/skills/impeccable/SKILL.md | 25 ++---- plugin/skills/impeccable/reference/craft.md | 77 ++++++------------- plugin/skills/impeccable/reference/shape.md | 33 +++++--- skill/SKILL.md | 25 ++---- skill/reference/craft.md | 77 ++++++------------- skill/reference/shape.md | 33 +++++--- 42 files changed, 742 insertions(+), 1148 deletions(-) diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index 25044b37a..8af38df3d 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -5,28 +5,15 @@ description: Use when the user wants to design, redesign, shape, critique, audit Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .agents/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `$impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `$impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `$impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `$impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.agents/skills/impeccable/reference/craft.md b/.agents/skills/impeccable/reference/craft.md index ed40a688c..e014f1f22 100644 --- a/.agents/skills/impeccable/reference/craft.md +++ b/.agents/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run $impeccable shape, passing along whatever feature description the user provided. +Run $impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run $impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.agents/skills/impeccable/reference/shape.md b/.agents/skills/impeccable/reference/shape.md index 834b7d15b..320b9397e 100644 --- a/.agents/skills/impeccable/reference/shape.md +++ b/.agents/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to $impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use $impeccable craft instead, which runs this command internally.) diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md index 5e926ac04..56dd99820 100644 --- a/.claude/skills/impeccable/SKILL.md +++ b/.claude/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .claude/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.claude/skills/impeccable/reference/craft.md b/.claude/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.claude/skills/impeccable/reference/craft.md +++ b/.claude/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.claude/skills/impeccable/reference/shape.md b/.claude/skills/impeccable/reference/shape.md index b31b75646..60348d482 100644 --- a/.claude/skills/impeccable/reference/shape.md +++ b/.claude/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and call the AskUserQuestion tool to clarify. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and call the AskUserQuestion tool to clarify. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.cursor/skills/impeccable/SKILL.md b/.cursor/skills/impeccable/SKILL.md index df15564ab..39f9c9709 100644 --- a/.cursor/skills/impeccable/SKILL.md +++ b/.cursor/skills/impeccable/SKILL.md @@ -7,28 +7,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .cursor/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.cursor/skills/impeccable/reference/craft.md b/.cursor/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.cursor/skills/impeccable/reference/craft.md +++ b/.cursor/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.cursor/skills/impeccable/reference/shape.md b/.cursor/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.cursor/skills/impeccable/reference/shape.md +++ b/.cursor/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.gemini/skills/impeccable/SKILL.md b/.gemini/skills/impeccable/SKILL.md index fe6ba645e..cca0ecd71 100644 --- a/.gemini/skills/impeccable/SKILL.md +++ b/.gemini/skills/impeccable/SKILL.md @@ -6,28 +6,15 @@ version: 3.0.7 Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .gemini/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.gemini/skills/impeccable/reference/craft.md b/.gemini/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.gemini/skills/impeccable/reference/craft.md +++ b/.gemini/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.gemini/skills/impeccable/reference/shape.md b/.gemini/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.gemini/skills/impeccable/reference/shape.md +++ b/.gemini/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.github/skills/impeccable/SKILL.md b/.github/skills/impeccable/SKILL.md index 011a492ac..c5fa7be37 100644 --- a/.github/skills/impeccable/SKILL.md +++ b/.github/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .github/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.github/skills/impeccable/reference/craft.md b/.github/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.github/skills/impeccable/reference/craft.md +++ b/.github/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.github/skills/impeccable/reference/shape.md b/.github/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.github/skills/impeccable/reference/shape.md +++ b/.github/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.kiro/skills/impeccable/SKILL.md b/.kiro/skills/impeccable/SKILL.md index 3d69b6358..482250f18 100644 --- a/.kiro/skills/impeccable/SKILL.md +++ b/.kiro/skills/impeccable/SKILL.md @@ -7,28 +7,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .kiro/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.kiro/skills/impeccable/reference/craft.md b/.kiro/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.kiro/skills/impeccable/reference/craft.md +++ b/.kiro/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.kiro/skills/impeccable/reference/shape.md b/.kiro/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.kiro/skills/impeccable/reference/shape.md +++ b/.kiro/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.opencode/skills/impeccable/SKILL.md b/.opencode/skills/impeccable/SKILL.md index 2ea593923..2ecc77f1c 100644 --- a/.opencode/skills/impeccable/SKILL.md +++ b/.opencode/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .opencode/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.opencode/skills/impeccable/reference/craft.md b/.opencode/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.opencode/skills/impeccable/reference/craft.md +++ b/.opencode/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.opencode/skills/impeccable/reference/shape.md b/.opencode/skills/impeccable/reference/shape.md index b9eac54c0..0b1ec2fa5 100644 --- a/.opencode/skills/impeccable/reference/shape.md +++ b/.opencode/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and call the `question` tool to clarify. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and call the `question` tool to clarify. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.pi/skills/impeccable/SKILL.md b/.pi/skills/impeccable/SKILL.md index bb9125629..bdf333388 100644 --- a/.pi/skills/impeccable/SKILL.md +++ b/.pi/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .pi/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.pi/skills/impeccable/reference/craft.md b/.pi/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.pi/skills/impeccable/reference/craft.md +++ b/.pi/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.pi/skills/impeccable/reference/shape.md b/.pi/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.pi/skills/impeccable/reference/shape.md +++ b/.pi/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.qoder/skills/impeccable/SKILL.md b/.qoder/skills/impeccable/SKILL.md index 951a0dfb4..58bf42f8e 100644 --- a/.qoder/skills/impeccable/SKILL.md +++ b/.qoder/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .qoder/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.qoder/skills/impeccable/reference/craft.md b/.qoder/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.qoder/skills/impeccable/reference/craft.md +++ b/.qoder/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.qoder/skills/impeccable/reference/shape.md b/.qoder/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.qoder/skills/impeccable/reference/shape.md +++ b/.qoder/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.rovodev/skills/impeccable/SKILL.md b/.rovodev/skills/impeccable/SKILL.md index 24ded37d7..125b66ec4 100644 --- a/.rovodev/skills/impeccable/SKILL.md +++ b/.rovodev/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .rovodev/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.rovodev/skills/impeccable/reference/craft.md b/.rovodev/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.rovodev/skills/impeccable/reference/craft.md +++ b/.rovodev/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.rovodev/skills/impeccable/reference/shape.md b/.rovodev/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.rovodev/skills/impeccable/reference/shape.md +++ b/.rovodev/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.trae-cn/skills/impeccable/SKILL.md b/.trae-cn/skills/impeccable/SKILL.md index 5ae9750d6..7f906895e 100644 --- a/.trae-cn/skills/impeccable/SKILL.md +++ b/.trae-cn/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .trae-cn/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.trae-cn/skills/impeccable/reference/craft.md b/.trae-cn/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.trae-cn/skills/impeccable/reference/craft.md +++ b/.trae-cn/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.trae-cn/skills/impeccable/reference/shape.md b/.trae-cn/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.trae-cn/skills/impeccable/reference/shape.md +++ b/.trae-cn/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/.trae/skills/impeccable/SKILL.md b/.trae/skills/impeccable/SKILL.md index a819ddb38..5099ab5d5 100644 --- a/.trae/skills/impeccable/SKILL.md +++ b/.trae/skills/impeccable/SKILL.md @@ -9,28 +9,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .trae/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/.trae/skills/impeccable/reference/craft.md b/.trae/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/.trae/skills/impeccable/reference/craft.md +++ b/.trae/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/.trae/skills/impeccable/reference/shape.md b/.trae/skills/impeccable/reference/shape.md index cba058e60..d1c983ff4 100644 --- a/.trae/skills/impeccable/reference/shape.md +++ b/.trae/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -ask the user directly to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +ask the user directly to clarify what you cannot infer. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/plugin/skills/impeccable/SKILL.md b/plugin/skills/impeccable/SKILL.md index 5e926ac04..56dd99820 100644 --- a/plugin/skills/impeccable/SKILL.md +++ b/plugin/skills/impeccable/SKILL.md @@ -11,28 +11,15 @@ allowed-tools: Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .claude/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `/impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `/impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/plugin/skills/impeccable/reference/craft.md b/plugin/skills/impeccable/reference/craft.md index ce958b98f..e6c56ddb6 100644 --- a/plugin/skills/impeccable/reference/craft.md +++ b/plugin/skills/impeccable/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run /impeccable shape, passing along whatever feature description the user provided. +Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/plugin/skills/impeccable/reference/shape.md b/plugin/skills/impeccable/reference/shape.md index b31b75646..60348d482 100644 --- a/plugin/skills/impeccable/reference/shape.md +++ b/plugin/skills/impeccable/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -STOP and call the AskUserQuestion tool to clarify. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +STOP and call the AskUserQuestion tool to clarify. + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this command internally.) diff --git a/skill/SKILL.md b/skill/SKILL.md index 13b119bf2..1d611efc5 100644 --- a/skill/SKILL.md +++ b/skill/SKILL.md @@ -10,28 +10,15 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft. -## Setup (non-optional) +## Setup -Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project. +Before any design work or file edits: -| Gate | Required check | If fail | -|---|---|---| -| Context | The PRODUCT.md / DESIGN.md loader result is known from `node {{scripts_path}}/load-context.mjs`. | Run the loader before continuing. | -| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `{{command_prefix}}impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. | -| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. | -| Craft | `{{command_prefix}}impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `{{command_prefix}}impeccable shape` and wait for explicit brief confirmation. | -| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. | -| Mutation | All active gates above pass. | Do not edit project files yet. | +1. Load context (PRODUCT.md / DESIGN.md) via the loader script. +2. Identify the register and load the matching register reference (brand.md or product.md). +3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects. -Codex-style agents must state this before editing files: - -```text -IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped: mutation=open -``` - -For `{{command_prefix}}impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself. - -Other harnesses should follow the same checklist when they can expose this state. +Skipping these produces generic output that ignores the project. ### 1. Context gathering diff --git a/skill/reference/craft.md b/skill/reference/craft.md index 93abfc6ed..e64a8f9a6 100644 --- a/skill/reference/craft.md +++ b/skill/reference/craft.md @@ -1,43 +1,20 @@ # Craft Flow -Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar. +Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar. -## Build Gate +Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief. -Craft cannot build until all of these are true: - -1. PRODUCT context is valid and current. -2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief. -3. Implementation references from the brief are loaded. -4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved. -5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable. - -PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user. - -Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets. - -## Craft Contract - -Craft is not a first pass. It is a loop with these required artifacts: - -1. Confirmed design brief from `shape`. -2. Approved visual direction, from generated probes / mocks when image generation is available. -3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code. -4. Semantic, functional implementation using the project's real stack and conventions. -5. Browser evidence across relevant viewports. -6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects. - -Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood." +Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong. ## Step 1: Shape the Design -Run {{command_prefix}}impeccable shape, passing along whatever feature description the user provided. +Run {{command_prefix}}impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction. -Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it. +**You must end your response after presenting the shape output and wait for the user.** Do not present a brief or direction statement and then continue to write code in the same response. The user gets to confirm, override, or course-correct. This is non-negotiable: a craft run that skips the user-confirmation pause is broken. -If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation. +If the user already supplied a confirmed brief or ran shape separately, use it and skip this step. -If the user has already run {{command_prefix}}impeccable shape and has a confirmed design brief, skip this step and use the existing brief. +When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient. ## Step 2: Load References @@ -59,9 +36,9 @@ Before implementation, generate high-fidelity visual comps when all of these are - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to set up external APIs, shell scripts, or one-off tooling. -When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory for **both brand and product work**. If image generation isn't natively available, skip silently and proceed; don't announce the skip to the user. Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration. @@ -111,27 +88,19 @@ Treat the mock as a **north star**, not a screenshot to trace. Do **not** raster ## Step 4: Asset Extraction (Need-Gated) -If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building. +If the approved direction needs raster assets, create them before building. Do not replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. -Do not replace required visual content with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy just because sourcing or generating assets would take another step. +Use the native asset producer (`impeccable_asset_producer` in Codex, `impeccable-asset-producer` in Claude Code) to create clean assets from the hi-fi mock and crops. If you do not have explicit permission to use agents, stop and ask: -Good candidates: +```text +Asset production will work better as a scoped subagent job. Should I spawn the Impeccable asset producer subagent for this step? +``` -- stickers -- badges -- seals -- tickets -- graphic labels -- textures -- abstract objects -- decorative marks -- non-semantic scene elements +Do not skip asset production or silently do it inline. Inline asset production is allowed only if the user declines subagents, the harness cannot spawn the authorized agent, or the user explicitly asks for single-thread mode. -For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes. +Pass the approved mock, crop/contact-sheet paths, output directory, dimensions/formats, transparency needs, constraints, and avoid list to the asset producer. Attach image generation capability to the spawned agent when the harness supports it; do not load image-generation reference material into the parent thread first. -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. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional. +Keep UI text, navigation, body copy, and structure semantic and editable. Prefer HTML/CSS/SVG/canvas when they can credibly reproduce an ingredient; use real/generated/stock imagery when the mock or subject matter calls for actual visual content. ## Step 5: Build to Production Quality @@ -155,9 +124,7 @@ Implement the feature following the design brief. Build in passes so structure, ## Step 6: Browser-Based Iteration -**This step is critical.** Do not stop after the first implementation pass. - -Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. +**This step is critical.** Open the result in a browser and look at it. In Codex, use browser-use or equivalent; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output. Detector or QA output is defect evidence only. A clean detector, empty array, or script pass never means the design is strong. Do not cite clean automated checks as proof that the work is finished. @@ -171,11 +138,15 @@ Check the experience at the viewports that matter for the brief. Default minimum For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow. -For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects. +For brand-register and long-form surfaces, inspect each major section individually, not only the full page. Full-page screenshots hide spacing, clipping, and cascade defects; when something looks off in a full-page thumbnail, take a targeted screenshot of that section to actually see the problem. ### Critique and fix loop -After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist: +After the first browser pass, write an honest critique for yourself. If you find material defects, patch them and re-inspect. Continue until no material issues remain against the checklist below. + +If the first inspection genuinely finds nothing material (the screenshots match the brief, the checklist is clean), say so and ship. **Do not invent a defect to demonstrate iteration.** A fake fix ("found one issue: form labels could be better; verified labels are correct") is worse than a confident "first pass clean, shipping." + +Be ruthlessly honest. Most first passes have real defects; if yours doesn't, that's worth examining (am I looking carefully? did I take a useful screenshot, not just a full-page thumbnail?) but it's not a reason to fabricate work. 1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies. 2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects. diff --git a/skill/reference/shape.md b/skill/reference/shape.md index 67614a9b4..ad40ee2fa 100644 --- a/skill/reference/shape.md +++ b/skill/reference/shape.md @@ -16,14 +16,16 @@ This is a required interaction, not optional guidance. Ask these questions in co ### Interview cadence -Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. +Discovery includes at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response. - Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop. - Ask **2-3 questions per round**, then wait for answers. - Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific. -- Round 1 should clarify purpose, audience/context, and success or emotional outcome. -- Round 2 should clarify content/data/states and scope/fidelity. -- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved. +- One round is the default. Add a second only if the first answers leave material gaps. Don't run a second round just to feel thorough. +- Round 1 should clarify purpose, audience/context, content/scope, and (for brand) visual direction. +- Round 2, when needed, fills in whatever's still genuinely missing. + +**Assert-then-confirm, not menu-with-escape.** When PRODUCT.md and the user's prompt make one option obvious, name it and ask the user to confirm or override. Don't enumerate "Restrained / Committed / Or something else?" as a real choice; "This reads as Restrained, confirm?" beats a four-option menu when the answer is already clear. ### Purpose & Context - What is this feature for? What problem does it solve? @@ -73,9 +75,9 @@ After the discovery interview, generate a small set of visual direction probes * - 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. +- The current harness gives you native image generation (Codex's `image_gen`, an equivalent MCP tool, or similar). Don't ask the user to install APIs or tooling. -When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed. +When those conditions are met, this step is mandatory. If image generation isn't natively available, skip silently and proceed; don't announce the skip. Use probes to explore visual lanes, not to replace the brief. @@ -105,11 +107,20 @@ The probes should differ in primary visual direction (hierarchy, topology, densi - 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 only with a one-line reason and proceed directly to the design brief. +If image generation isn't natively available, skip this phase silently and proceed. ## Phase 2: Design Brief -After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief. +After the interview and any required probes, present a brief and **end your response**. The user must confirm before any implementation runs. Do not present a brief and then continue to code in the same response, even if the brief feels obvious to you. The user's confirmation is the gate. + +**Choose the brief shape based on how clear the answers are:** + +- **Compact form (3-5 bullets)** when discovery was crisp and the original prompt + PRODUCT.md already pinned scope, content, and direction. State what you're building, the visual lane, and end with one or two specific questions or a clear "confirm or override?" prompt. This is the default for typical craft requests with a clear prompt. +- **Full structured form (sections below)** when the task is genuinely ambiguous, multi-screen, or when the user asked for shape as a standalone step. Use this when the discipline of structure earns its weight. + +Don't pad a clear brief into a long one to look thorough. A 70-line brief restating answers the user just gave is noise, not rigor. Equally, don't skip the confirmation pause to look efficient: the pause is the point. + +If the user already said "approved" or "go" during discovery for the *exact direction you'd present*, that counts as confirmation; you may proceed without asking again. But if your brief adds anything the user hasn't seen and approved, you must stop and confirm. ### Brief Structure @@ -143,10 +154,12 @@ What copy, labels, empty state messages, error messages, and microcopy are neede Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features). **10. Open Questions** -Anything unresolved that the implementer should resolve during build. +Anything genuinely unresolved. Don't list "open questions" you've already recommended a default for; assert the default and move on. If you'd write `Recommend: X` next to a question, just decide X. --- -{{ask_instruction}} Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed. +{{ask_instruction}} + +If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the user confirms direction (or the user already gave a clear go during discovery, which counts). Once confirmed, the brief is complete. The user can now hand it to {{command_prefix}}impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use {{command_prefix}}impeccable craft instead, which runs this command internally.)