@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/skills/impeccable/reference/polish.md

@@ -1,241 +1,97 @@
-> **Additional context needed**: quality bar (MVP vs flagship).
+> **Additional context needed**: quality bar and shipping constraints.
 
-Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
+Polish is refinement, never concealed redesign. Preserve the incumbent visual world, content, behavior, and everything outside scope. If the concept itself is wrong, say so and recommend redesign or `bolder` instead of smuggling in a replacement.
 
-Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path.
+A detector result is defect evidence, not proof of quality. Inspect the rendered experience and real interaction path.
 
-## Design System Discovery
+## 1. Establish the system
 
-Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work.
+Read DESIGN.md and representative tokens, shared components, patterns, and neighboring flows. If no formal system exists, use coherent project conventions.
 
-1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: design principles, target audience, color tokens, spacing scale, typography styles, component API, motion conventions.
-2. **Note the conventions**: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established? What flow shapes are used for comparable actions (modal vs full-page, inline vs route, save-on-blur vs explicit submit)?
-3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category: patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds.
+Classify each drift before fixing it:
 
-If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask. Never guess at design system principles.**
+- **missing token:** the system needs a reusable value;
+- **one-off implementation:** an existing shared component or pattern should replace it;
+- **conceptual mismatch:** the flow, information architecture, or hierarchy differs from comparable product areas;
+- **local defect:** the implementation is simply incomplete or inconsistent.
 
-## Pre-Polish Assessment
+Fix the cause at the narrowest correct level. Ask when a binding system principle cannot be inferred.
 
-Understand the current state and goals before touching anything:
+## 2. Gather the evidence
 
-1. **Review completeness**:
-   - Is it functionally complete?
-   - Are there known issues to preserve (mark with TODOs)?
-   - What's the quality bar? (MVP vs flagship feature?)
-   - When does it ship? (How much time for polish?)
+Use the feature yourself at representative desktop and mobile sizes. Determine:
 
-2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish; a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools.
+- whether the path is functionally complete;
+- the intended quality bar and time available;
+- known constraints or deliberately unfinished work;
+- the states, content lengths, roles, and input methods users will actually encounter.
 
-3. **Identify polish areas**:
-   - Visual inconsistencies
-   - Spacing and alignment issues
-   - Interaction state gaps
-   - Copy inconsistencies
-   - Edge cases and error states
-   - Loading and transition smoothness
-   - Information architecture and flow drift (does this feature reveal complexity the way neighboring features do?)
+If a prior critique exists, use it as one input:
 
-4. **Pull in any prior critique** (optional signal): If `$impeccable critique` has been run on the same target, its priority issues are a useful prior for what to address first. Resolve the target to a file path or URL, then:
-   ```bash
-   slug=$(node .agents/skills/impeccable/scripts/critique-storage.mjs slug "<resolved>")
-   node .agents/skills/impeccable/scripts/critique-storage.mjs latest "$slug"
-   ```
-   Exit 0 with body = found; fold the P0/P1 items into your polish list and mention the snapshot path so the user sees what you read. Exit 2 = no snapshot, continue without it. The critique is one input among many. Do your own pass either way.
+```bash
+node .agents/skills/impeccable/scripts/critique-storage.mjs latest "<resolved target>"
+```
 
-5. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent; never perfect one corner while leaving another rough.
+Exit 0 returns the latest snapshot; incorporate relevant P0/P1 findings and name the snapshot read. Exit 2 means none exists. Perform an independent pass either way.
 
-**CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
+## 3. Triage
 
-## Polish Systematically
+Separate functional defects from cosmetic ones and fix in this order:
 
-Work through these dimensions methodically:
+1. broken or blocked tasks, data loss, misleading state, and inaccessible paths;
+2. missing loading, empty, error, success, disabled, and permission states;
+3. flow, hierarchy, responsive, and design-system drift;
+4. visual and motion inconsistencies;
+5. code and asset cleanup.
 
-### Visual Alignment & Spacing
+Do not perfect one corner while leaving the rest below the same quality bar.
 
-- **Pixel-perfect alignment**: Everything lines up to grid
-- **Consistent spacing**: All gaps use spacing scale (no random 13px gaps)
-- **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering)
-- **Responsive consistency**: Spacing and alignment work at all breakpoints
-- **Grid adherence**: Elements snap to baseline grid
+## 4. Polish the whole path
 
-**Check**:
-- Enable grid overlay and verify alignment
-- Check spacing with browser inspector
-- Test at multiple viewport sizes
-- Look for elements that "feel" off
+### Flow and hierarchy
 
-### Information Architecture & Flow
+- Match neighboring mental models, terminology, disclosure, routing, save behavior, and optimistic or pessimistic patterns.
+- Make the primary task and current state obvious without flattening every element to equal weight.
+- Ensure arrival, transition, empty, and recovery paths connect instead of behaving as isolated screens.
 
-Visual polish on a misshapen flow is wasted work. Match the *shape* of the experience to the system, not just the surface.
+### Layout and type
 
-- **Progressive disclosure**: Match how much is revealed when, compared to neighboring features. A settings page exposing 40 fields when the rest of the app reveals 5 at a time is drift, even if every field is perfectly styled.
-- **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere: modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates.
-- **Hierarchy & complexity**: The same conceptual weight gets the same visual weight throughout. Primary actions don't become tertiary in one corner of the product, and tertiary actions don't shout.
-- **Empty, loading, and arrival transitions**: How content arrives, updates, and leaves matches how it does in adjacent features.
-- **Naming and mental model**: The feature uses the same nouns and verbs as the rest of the system. A "Workspace" here shouldn't be a "Project" three screens away.
+- Align to the project's grid and spacing scale; fix optical as well as mathematical alignment.
+- Group related content tightly and separate distinct groups generously.
+- Keep same-role typography consistent; test measure, wrapping, localization expansion, zoom, and font loading.
+- Verify every supported viewport rather than correcting only the current screenshot.
 
-### Typography Refinement
+### Color, imagery, and icons
 
-- **Hierarchy consistency**: Same elements use same sizes/weights throughout
-- **Line length**: 45-75 characters for body text
-- **Line height**: Appropriate for font size and context
-- **Widows & orphans**: No single words on last line
-- **Hyphenation**: Appropriate for language and column width
-- **Kerning**: Adjust letter spacing where needed (especially headlines)
-- **Font loading**: No FOUT/FOIT flashes
+- Use semantic tokens and stable color meanings across themes.
+- Verify text, control, and focus contrast in every state.
+- Keep icon families, stroke/weight, sizing, and optical alignment coherent.
+- Prevent image layout shift; use correct aspect ratios, responsive sources, and useful alt text.
 
-### Color & Contrast
+### Interaction and state
 
-- **Contrast ratios**: All text meets WCAG standards
-- **Consistent token usage**: No hard-coded colors, all use design tokens
-- **Theme consistency**: Works in all theme variants
-- **Color meaning**: Same colors mean same things throughout
-- **Accessible focus**: Focus indicators visible with sufficient contrast
-- **Gray on color**: Never put gray text on colored backgrounds; use a shade of that color or transparency
+- Every control needs appropriate default, hover, focus, active, disabled, loading, error, and success behavior.
+- Preserve visible keyboard focus, logical tab order, labels, and platform-appropriate touch targets.
+- Keep motion coherent, interruptible, and performant. Do not add animation merely to make polish visible.
+- Validate long, missing, localized, offline, slow, and permission-limited content where the product can encounter it.
 
-### Interaction States
+### Content and code
 
-Every interactive element needs all states:
+- Keep terminology, capitalization, punctuation, and factual copy consistent. Ask before changing claims.
+- Remove debug output, dead code, unused imports, obsolete styles, and polish-created duplication.
+- Replace custom implementations with shared components where the system owns the pattern.
+- Promote genuinely reusable values to tokens; do not create a system abstraction for one local exception.
 
-- **Default**: Resting state
-- **Hover**: Subtle feedback (color, scale, shadow)
-- **Focus**: Keyboard focus indicator (never remove without replacement)
-- **Active**: Click/tap feedback
-- **Disabled**: Clearly non-interactive
-- **Loading**: Async action feedback
-- **Error**: Validation or error state
-- **Success**: Successful completion
-
-**Missing states create confusion and broken experiences**.
-
-### Micro-interactions & Transitions
-
-- **Smooth transitions**: All state changes animated appropriately (150-300ms)
-- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic; they feel dated.
-- **No jank**: Smooth animations; use atmospheric blur/filter/mask/shadow effects when they add polish, but bound expensive paint areas and avoid casual layout-property animation
-- **Appropriate motion**: Motion serves purpose, not decoration
-- **Reduced motion**: Respects `prefers-reduced-motion`
-
-### Content & Copy
-
-- **Consistent terminology**: Same things called same names throughout
-- **Consistent capitalization**: Title Case vs Sentence case applied consistently
-- **Grammar & spelling**: No typos
-- **Appropriate length**: Not too wordy, not too terse
-- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)
-
-### Icons & Images
-
-- **Consistent style**: All icons from same family or matching style
-- **Appropriate sizing**: Icons sized consistently for context
-- **Proper alignment**: Icons align with adjacent text optically
-- **Alt text**: All images have descriptive alt text
-- **Loading states**: Images don't cause layout shift, proper aspect ratios
-- **Retina support**: 2x assets for high-DPI screens
-
-### Forms & Inputs
-
-- **Label consistency**: All inputs properly labeled
-- **Required indicators**: Clear and consistent
-- **Error messages**: Helpful and consistent
-- **Tab order**: Logical keyboard navigation
-- **Auto-focus**: Appropriate (don't overuse)
-- **Validation timing**: Consistent (on blur vs on submit)
-
-### Edge Cases & Error States
-
-- **Loading states**: All async actions have loading feedback
-- **Empty states**: Helpful empty states, not just blank space
-- **Error states**: Clear error messages with recovery paths
-- **Success states**: Confirmation of successful actions
-- **Long content**: Handles very long names, descriptions, etc.
-- **No content**: Handles missing data gracefully
-- **Offline**: Appropriate offline handling (if applicable)
-
-### Responsiveness
-
-- **All breakpoints**: Test mobile, tablet, desktop
-- **Touch targets**: 44x44px minimum on touch devices
-- **Readable text**: No text smaller than 14px on mobile
-- **No horizontal scroll**: Content fits viewport
-- **Appropriate reflow**: Content adapts logically
-
-### Performance
-
-- **Fast initial load**: Optimize critical path
-- **No layout shift**: Elements don't jump after load (CLS)
-- **Smooth interactions**: No lag or jank
-- **Optimized images**: Appropriate formats and sizes
-- **Lazy loading**: Off-screen content loads lazily
-
-### Code Quality
-
-- **Remove console logs**: No debug logging in production
-- **Remove commented code**: Clean up dead code
-- **Remove unused imports**: Clean up unused dependencies
-- **Consistent naming**: Variables and functions follow conventions
-- **Type safety**: No TypeScript `any` or ignored errors
-- **Accessibility**: Proper ARIA labels and semantic HTML
-
-## Polish Checklist
-
-Go through systematically:
-
-- [ ] Aligned to the design system (drift named and resolved by root cause)
-- [ ] Information architecture and flow shape match neighboring features
-- [ ] Visual alignment perfect at all breakpoints
-- [ ] Spacing uses design tokens consistently
-- [ ] Typography hierarchy consistent
-- [ ] All interactive states implemented
-- [ ] All transitions smooth (60fps)
-- [ ] Copy is consistent and polished
-- [ ] Icons are consistent and properly sized
-- [ ] All forms properly labeled and validated
-- [ ] Error states are helpful
-- [ ] Loading states are clear
-- [ ] Empty states are welcoming
-- [ ] Touch targets are 44x44px minimum
-- [ ] Contrast ratios meet WCAG AA
-- [ ] Keyboard navigation works
-- [ ] Focus indicators visible
-- [ ] No console errors or warnings
-- [ ] No layout shift on load
-- [ ] Works in all supported browsers
-- [ ] Respects reduced motion preference
-- [ ] Code is clean (no TODOs, console.logs, commented code)
-
-**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
-
-Sweat the details. Zoom in until the alignment is right and the spacing reads as deliberate. Then ship.
-
-**NEVER**:
-- Polish before it's functionally complete
-- Polish without aligning to the design system; that's decoration on drift
-- Guess at design system principles instead of asking when something is ambiguous
-- Spend hours on polish if it ships in 30 minutes (triage)
-- Introduce bugs while polishing (test thoroughly)
-- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
-- Perfect one thing while leaving others rough (consistent quality level)
-- Create new one-off components when design system equivalents exist
-- Hard-code values that should use design tokens
-- Introduce new patterns or flows that diverge from established ones
-
-## Final Verification
-
-Before marking as done:
-
-- **Use it yourself**: Actually interact with the feature.
-- **Test on real devices**: Not just browser DevTools.
-- **Ask someone else to review**: Fresh eyes catch things.
-- **Compare to design**: Match intended design.
-- **Check all states**: Don't just test happy path.
-- **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished.
-
-## Clean Up
-
-After polishing, ensure code quality:
-
-- **Replace custom implementations**: If the design system provides a component you reimplemented, switch to the shared version.
-- **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish.
-- **Consolidate tokens**: If you introduced new values, check whether they should be tokens.
-- **Verify DRYness**: Look for duplication introduced during polishing and consolidate.
+## 5. Verify and finish
+
+Walk the complete path again with mouse, keyboard, and touch where applicable. Check:
+
+- mobile, intermediate, and wide layouts;
+- loading, empty, error, success, disabled, long-content, and missing-content states;
+- zoom, contrast, focus, semantics, and screen-reader names;
+- console errors, layout shift, interaction latency, image loading, and supported browsers;
+- agreement with DESIGN.md, neighboring features, and the user's scope.
+
+Follow the quality guidance supplied by `context.mjs` and hooks, then run any other relevant QA commands. Context requests a manual scan only when no automatic detector is active; never add another detector pass. Fix real defects and document only narrow intentional exceptions. A clean scan does not replace visual judgment.
+
+Finish with a source diff: remove accidental churn, orphaned code, redundant values, and temporary artifacts. Ship only when the feature is functionally complete and consistently finished across the path.

package/dist/builtin/workflows/skills/impeccable/reference/quieter.md

@@ -2,11 +2,11 @@ Quiet design is harder than bold design. Subtlety needs precision. Reduce visual
 
 ---
 
-## Register
+## Visitor mode
 
-Brand: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated; the POV stays intact.
+Persuade + Experience: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated; the POV stays intact.
 
-Product: "quieter" means reducing visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
+Operate + Read: "quieter" means reducing visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
 
 ---
 

package/dist/builtin/workflows/skills/impeccable/reference/routing.md

@@ -0,0 +1,18 @@
+# No-argument routing: the context-aware menu
+
+Read this when the user invokes `$impeccable` with no argument. They are asking "what should I do?" Make the menu context-aware instead of static.
+
+Setup has already run `context.mjs`. If that reported `NO_PRODUCT_MD`, the project has no captured context yet: lead the menu with `$impeccable init` as the top recommendation (one line on why) and still show the rest below; don't silently jump into init. Otherwise run `node .agents/skills/impeccable/scripts/context-signals.mjs` once and read its JSON, then lead with the **2-3 highest-value next commands**, each with a one-line reason pulled from the signals, followed by the full menu (the Commands table in SKILL.md, grouped by category). **Never auto-run a command; the recommendation is a suggestion the user confirms.**
+
+Reason over the signals; there is no score to obey:
+
+- `setup.hasDesign` false while `setup.hasCode` true → `document` (capture the visual system).
+- `critique.latest` is `null` → the project has never been critiqued; for a set-up project with a real surface, offering `$impeccable critique <surface>` is a strong default.
+- `critique.latest` with a low `score` or non-zero `p0` / `p1` → `polish` (it reads that snapshot as its backlog), or re-run `critique` if the snapshot looks stale.
+- `git.changedFiles` pointing at one surface → scope `audit` or `polish` to those files specifically, naming them.
+- `devServer.running` true → `live` is available for in-browser iteration; if false, don't lead with `live`. **`live` and the bundled `detect.mjs` are web-only.** If `setup.platform` is `ios`, `android`, or `adaptive`, don't lead with either; the browser overlay and the HTML rule engine don't apply to native app code.
+- Otherwise group by intent (build new / improve what's there / iterate visually), tailored to the current surface and `setup.platform`.
+
+**If `scan.targets` is non-empty and `setup.platform` is not `ios`/`android`/`adaptive`, run `node .agents/skills/impeccable/scripts/detect.mjs --json <scan.targets joined by spaces>` once** (the bundled detector over local files: no network, no npx; it reads HTML/CSS, so skip it for native projects). `scan.via` tells you what they are: `git-changes` (the markup/style files in your dirty tree, the most relevant set), `source-dir` (e.g. `src`, `app`), `html`, or `root`. Fold the hits into your picks: many quality / contrast hits → `audit` or `polish`; a specific slop family → the matching command (gradient text or eyebrows → `quieter` / `typeset`, flat or gray palette → `colorize`, and so on). It's a real, current signal that beats guessing. If detect errors or the tree is large and slow, skip it and recommend the user run `audit` themselves; never block the suggestion on it.
+
+Keep it to 2-3 pointed picks with the exact command to type. The menu stays the fallback; the recommendation is the lede.

package/dist/builtin/workflows/skills/impeccable/reference/shape.md

@@ -1,165 +1,59 @@
-Shape the UX and UI for a feature before any code is written. This command produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork.
+# Shape
 
-**Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good.
+Discover what should be made and how it should work, then return a confirmed design brief without code.
 
-**Output**: A design brief that can be handed off to $impeccable craft, or directly to $impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output.
+## Phase 1: Discovery interview
 
-## Philosophy
+Do not write code or choose visual direction yet.
 
-Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This command inverts that: understand deeply first, so implementation is precise.
+### Cadence
 
-## Phase 1: Discovery Interview
+- Use the structured question tool when available; otherwise ask and stop.
+- Ask two or three related questions per round, then wait. One round is the default; add a second only when the answers expose a material gap.
+- Do not dump a questionnaire, repeat settled facts, or turn obvious facts into menus. Assert the likely reading and invite correction.
+- A sparse prompt requires at least one answer round. A precise prompt may need only a compact confirmation.
 
-**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
+### Round 1: purpose, people, and outcome
 
-This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
+Choose the two or three questions that most change the result:
 
-### Interview cadence
+- What is this surface or feature for, and what problem must it solve?
+- Who specifically reaches it, in what situation and state of mind?
+- What is the primary thing they must understand or do? What would success look like?
+- What is uniquely true here that a neighboring product or generic template could not claim?
 
-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.
+### Round 2: material, behavior, and boundaries
 
-- 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.
-- 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.
+Run only for material unresolved decisions:
 
-**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.
+- What real content, evidence, data, and assets must the experience carry? What are realistic minimum, typical, and maximum ranges?
+- Which states and transitions matter: first-run, empty, loading, error, success, permissions, overflow, or expert use?
+- What is the intended fidelity, breadth, and interactivity: exploration, production-ready screen, full flow, or broader surface?
+- What must remain untouched? What would make the result feel wrong even if it looked polished?
+- Which platform, framework, performance, accessibility, localization, or delivery constraints are binding?
 
-### Purpose & Context
-- What is this feature for? What problem does it solve?
-- Who specifically will use it? (Not "users"; be specific: role, context, frequency)
-- What does success look like? How will you know this feature is working?
-- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?)
+Never ask for CSS values or canned aesthetic lanes. New-work owns visual-world and concept choices.
 
-### Content & Data
-- What content or data does this feature display or collect?
-- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items)
-- What are the edge cases? (Empty state, error state, first-time use, power user)
-- Is any content dynamic? What changes and how often?
-- What visual assets are real content here? Note required images, product shots, illustrations, maps, textures, diagrams, generated objects, or existing project assets.
+## Phase 2: Resolve the design direction
 
-### Design Direction
+For new surfaces, brand expansion, or replacement, follow [new-work.md](new-work.md) through visual authority, any world workshop, and concept choice. Reuse discovery, then return before its contract, persistence, or implementation. Inside an established world, use its concept process only when composition or interaction remains materially open.
 
-Force a visual decision on three fronts. Skip anything PRODUCT.md or DESIGN.md already answers; ask only what's missing.
+## Phase 3: Write the brief
 
-- **Color strategy for this surface.** Pick one: Restrained / Committed / Full palette / Drenched. Can override the project default if the surface earns it (e.g. a drenched hero inside an otherwise Restrained product).
-- **Theme via scene sentence.** Write one sentence of physical context for this surface: who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
-- **Two or three named anchor references.** Specific products, brands, objects. Not adjectives like "modern" or "clean."
+Write the smallest useful brief:
 
-### Scope
+1. **Job and audience:** who arrives, their context, need, and visitor mode.
+2. **Outcome and proof:** primary task/action, success, real evidence, and product-specific truth.
+3. **Selected direction:** visual authority, structural/interaction thesis, sequence, focal moment, and implementation consequence.
+4. **Scope and boundaries:** fidelity, breadth, interactivity, named target, what remains untouched, and explicit anti-goals.
+5. **States and ranges:** realistic content/data ranges and material states.
+6. **Interaction and layout:** hierarchy, topology, responsiveness, affordances, feedback, and transitions; intent, not CSS.
+7. **Constraints and open decisions:** platform, delivery, accessibility, localization, reusable components, and choices a builder must not invent.
 
-Always ask. Sketch quality and shipped quality are different outputs; don't guess between them.
+Use three to five bullets when the task is settled; use the full structure only for ambiguous, multi-screen, or standalone planning. Do not restate the conversation.
 
-- **Fidelity.** Sketch / mid-fi / high-fi / production-ready?
-- **Breadth.** One screen / a flow / a whole surface?
-- **Interactivity.** Static visual / interactive prototype / shipped-quality component?
-- **Time intent.** Quick exploration, or polish until it ships?
+## Confirm and stop
 
-Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md; carry them through the design brief only.
+Present the brief for explicit confirmation or one correction round, then stop: shape never writes code or a direction contract.
 
-### Constraints
-- Are there technical constraints? (Framework, performance budget, browser support)
-- Are there content constraints? (Localization, dynamic text length, user-generated content)
-- Mobile/responsive requirements?
-- Accessibility requirements beyond WCAG AA?
-
-### Anti-Goals
-- What should this NOT be? What would be a wrong direction?
-- What's the biggest risk of getting this wrong?
-
-## Phase 1.5: Visual Direction Probe (Capability-Gated)
-
-After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true:
-
-- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief.
-- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning.
-- The current harness 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. If image generation isn't natively available, 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. The one-line announcement is required, not optional; it forces a conscious decision instead of letting the step quietly evaporate.
-
-Use probes to explore visual lanes, not to replace the brief.
-
-Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
-
-### What to generate
-
-Generate **2 to 4** distinct direction probes based on the discovery answers, especially:
-
-- Color strategy
-- Theme scene sentence
-- Named anchor references
-- Scope and fidelity
-
-The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks.
-
-### How to use the probes
-
-- Treat them as **direction tests**, not final designs.
-- Use them to pressure-test whether the brief is pointing at the right lane.
-- Ask the user which direction feels closest, what feels off, and what should carry forward.
-- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief.
-
-### Important limits
-
-- Do **not** skip discovery because image generation is available.
-- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior.
-- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice.
-
-If image generation isn't natively available, announce the skip in one line and proceed to the design brief.
-
-## Phase 2: Design 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.
-
-Present the brief, then **stop and wait for explicit confirmation**. You are not the judge of whether the user already approved. Even when the brief feels obviously right, ask once and wait. The pause is what separates shape from premature implementation.
-
-### Brief Structure
-
-**1. Feature Summary** (2-3 sentences)
-What this is, who it's for, what it needs to accomplish.
-
-**2. Primary User Action**
-The single most important thing a user should do or understand here.
-
-**3. Design Direction**
-Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides.
-
-If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it.
-
-**4. Scope**
-Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped; these don't persist beyond the brief.
-
-**5. Layout Strategy**
-High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS.
-
-**6. Key States**
-List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel.
-
-**7. Interaction Model**
-How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion?
-
-**8. Content Requirements**
-What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges. For image-led surfaces, also list the required image/media roles and their likely source (project asset, generated raster, semantic SVG/CSS, canvas/WebGL, icon library, or accepted omission).
-
-**9. Recommended References**
-Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., layout.md for complex layouts, animate.md for animated features, interaction-design.md for form-heavy features, typeset.md for typography-driven pages, colorize.md for color-led brands).
-
-**10. Open Questions**
-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 user confirms direction.
-
-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.)
+When no human or structured answer mechanism exists, mark assumptions plainly, return the brief, and stop.