@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

package/dist/builtin/workflows/builtin/open-claude-design-phases.ts

@@ -15,6 +15,9 @@ import {
 } from "./open-claude-design-feedback.js";
 import { buildLivePreviewDisplayPrompt } from "./open-claude-design-setup.js";
 
+const GROUNDED_REPORTING =
+  "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
+
 type DesignContext = {
   task(name: string, options: object): Promise<WorkflowTaskResult>;
   parallel(steps: readonly object[], options: { readonly task: string }): Promise<WorkflowTaskResult[]>;
@@ -142,11 +145,6 @@ function buildInitialGeneratePrompt(args: {
   readonly importContext: string;
 }): string {
   return taggedPrompt([
-    ["role", "You are an opinionated staff design engineer."],
-    [
-      "objective",
-      `Generate the first revision of a production-ready ${args.outputType} for: ${args.prompt}. Write it to disk as an interactive HTML preview the user can open in a browser. Apply the impeccable \`craft\` sub-skill to build the design with deliberate ordering and impeccable attention to detail. Every design decision must trace back to the brief, and every visual trait must be justified by the references, design system, or reference context.`,
-    ],
     ["design_brief", args.prompt],
     ["design_system", args.designSystem],
     ["reference_context", args.importContext],
@@ -155,28 +153,32 @@ function buildInitialGeneratePrompt(args: {
     ["preview_artifact_path", args.previewPath],
     ["html_rules", HTML_PREVIEW_RULES],
     ["anti_design_slop_rules", ANTI_SLOP_RULES],
+    ["role", "You are an opinionated staff design engineer."],
+    [
+      "objective",
+      `Create the first production-ready ${args.outputType} for: ${args.prompt}. Write an interactive browser preview and apply impeccable \`craft\`; each decision must trace to the brief, references, design system, or reference context.`,
+    ],
     [
       "instructions",
       [
-        `1. Create the HTML artifact at exactly this path: ${args.previewPath}.`,
-        "2. Follow the `<reference_precedence>` rule: user-provided references in `<reference_context>` win over DESIGN.md/PRODUCT.md where they conflict; DESIGN.md fills gaps the references do not cover.",
-        "3. Heavily reference the `<reference_inspiration>` block while staying consistent with the imported user references; never copy a reference wholesale or invent traits it does not contain.",
-        `4. Build the artifact as the requested output_type (${args.outputType}). For prototypes/pages, render full layouts with realistic content. For components, render the component in 3+ representative contexts.`,
-        "5. Include structure, states, accessibility behavior, responsive behavior, and integration notes — but keep them in HTML comments inside the file so the rendered preview stays clean.",
-        "6. Do not use generic placeholder language when project conventions are available.",
-        "7. After writing the file, return a short markdown summary (NOT the HTML body) describing what you built, decisions made, and assumptions left for the user to confirm.",
+        `Create the HTML artifact exactly at ${args.previewPath}.`,
+        "Follow <reference_precedence>; heavily reference <reference_inspiration> without copying wholesale or inventing traits.",
+        `Build the requested output_type (${args.outputType}): render full realistic layouts for prototypes/pages, or the component in at least three representative contexts.`,
+        "Include structure, states, accessibility, responsive behavior, and integration notes as HTML comments so the preview stays clean.",
+        "Use project language rather than generic placeholders when conventions exist. Add no features or abstractions beyond this design brief.",
       ].join("\n"),
     ],
     [
       "output_format",
       [
-        "Return markdown with the headings below. DO NOT paste the HTML; the file at preview_artifact_path is the artifact.",
+        "In at most 500 words, return Markdown, not the HTML body:",
         "1. Artifact overview",
-        "2. Files written (must include the absolute path to preview.html)",
-        "3. UI structure and states (referenced by HTML section IDs)",
+        "2. Files written (including the absolute preview.html path)",
+        "3. UI structure and states (by HTML section ID)",
         "4. Accessibility and responsive behavior",
         "5. Implementation notes",
         "6. Assumptions / open questions",
+        GROUNDED_REPORTING,
       ].join("\n"),
     ],
   ]);
@@ -194,11 +196,6 @@ function buildGenerateRevisionPrompt(args: {
 }): string {
   const annotations = userAnnotationsBlock([args.feedback]);
   return taggedPrompt([
-    ["role", "You are an opinionated staff design engineer."],
-    [
-      "objective",
-      `Generate the next ${args.outputType} revision for: ${args.prompt}. Update the HTML preview in place using only the user's captured feedback from the latest live review. Apply the impeccable \`craft\` and \`polish\` sub-skills with deliberate restraint: this is a focused revision, not an internal critique pass.`,
-    ],
     ["design_system", args.designSystem],
     ["reference_inspiration", args.referencesBrief],
     ["reference_context", args.importContext],
@@ -208,25 +205,29 @@ function buildGenerateRevisionPrompt(args: {
     ["current_design_summary", args.latestDesign],
     ["html_rules", HTML_PREVIEW_RULES],
     ["anti_design_slop_rules", ANTI_SLOP_RULES],
+    ["role", "You are an opinionated staff design engineer."],
+    [
+      "objective",
+      `Revise the ${args.outputType} for: ${args.prompt}. Update the preview in place from only the latest live-review feedback, applying impeccable \`craft\` and \`polish\` with restraint rather than adding an internal critique.`,
+    ],
     [
       "instructions",
       [
-        "1. Read the current HTML at preview_artifact_path with your file-read tool.",
-        "2. Treat `<user_feedback>` as the only refinement brief. Do not invent separate critique, screenshot, audit, or gate findings.",
-        "3. Every user note or accepted live change MUST be visibly addressed in the revised preview, or explicitly explained as a conflict with DESIGN.md/reference precedence in your summary.",
-        `4. Overwrite ${args.previewPath} with the revised self-contained HTML file. Do not branch the artifact and do not create extra preview files.`,
-        "5. Preserve strong existing design decisions unless the user feedback requires a change.",
-        "6. After writing, return a concise markdown summary of what changed and any user feedback you could not apply. Do NOT paste the HTML body.",
+        "Read the current HTML at preview_artifact_path. Treat <user_feedback> as the only refinement brief; do not invent critique, screenshot, audit, or gate findings.",
+        "Address every user note and accepted live change visibly, or identify its DESIGN.md/reference-precedence conflict in the summary.",
+        `Overwrite ${args.previewPath} with one revised self-contained HTML file; do not branch or create extra previews.`,
+        "Preserve strong decisions unless feedback requires change; add no unrelated features or abstractions.",
       ].join("\n"),
     ],
     [
       "output_format",
       [
-        "Markdown with headings:",
+        "In at most 400 words, return Markdown, not the HTML body:",
         "1. Revised artifact (path only)",
-        "2. User feedback addressed (each note/live change → how it was applied, or why it was deferred/conflicts)",
+        "2. User feedback addressed (each note/live change and its application or conflict)",
         "3. Changes applied",
         "4. Trade-offs / unresolved user feedback",
+        GROUNDED_REPORTING,
       ].join("\n"),
     ],
   ]);
@@ -252,34 +253,30 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
 
   const handoff = await designContext.task("exporter", {
     prompt: taggedPrompt([
-      ["role", "You are an opinionated staff design engineer."],
-      [
-        "objective",
-        `Export the final ${outputType} for "${prompt}" as a rich HTML spec the engineering team can read directly in a browser. The spec must embed or link the approved preview so reviewers see exactly what is being implemented. Apply the impeccable \`document\` sub-skill to produce a rich HTML spec that bundles the approved preview together with implementation guidance for another design/frontend engineer to implement.`,
-      ],
       ["design_system", designSystem],
       ["preview_artifact_path", previewPath],
       ["spec_artifact_path", specPath],
       ["final_design_summary", "{previous}"],
+      ["html_rules", HTML_PREVIEW_RULES],
+      ["anti_design_slop_rules", ANTI_SLOP_RULES],
+      ["role", "You are an opinionated staff design engineer."],
+      [
+        "objective",
+        `Export the final ${outputType} for "${prompt}" as a rich browser-readable HTML spec. Apply impeccable \`document\` and embed or link the approved preview so implementation reviewers see the agreed design.`,
+      ],
       [
         "instructions",
         [
-          `1. Read the approved HTML at preview_artifact_path. Use it as the canonical source of truth for the agreed design.`,
-          `2. Use the Write tool to create a rich HTML document at exactly: ${specPath}. The spec must be a single self-contained HTML5 file.`,
-          "3. The spec MUST contain, in order: (a) a sticky header with the design title + status + run id, (b) an Executive Summary section, (c) a 'Live Preview' section that EMBEDS the approved design via either an `<iframe srcdoc=\"...\">` containing the full preview HTML or a side-by-side rendered copy of the preview inside an `<article class=\"preview-frame\">` container, (d) the six DESIGN.md sections (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) rendered with swatches/tables/code blocks, (e) Implementation handoff (Recommended files + components | Implementation steps | Usage example | Accessibility & responsive checklist | Validation commands | Known limitations), (f) Appendix linking to the raw preview file path.",
-          "4. Style the spec itself with care: high-density legible typography, generous whitespace, code blocks with monospaced font, swatches that render with the actual hex/oklch values, copy-to-clipboard hints in HTML comments.",
-          `5. Embed the absolute preview path (${previewPath}) and file URL (${previewFileUrl}) prominently so the user can open the live preview separately.`,
-          "6. Preserve assumptions and known limitations so implementers do not treat uncertain items as facts.",
-          "7. Do not introduce design requirements that were absent from the final design or DESIGN.md.",
-          "8. After writing, return a concise markdown summary of what is in the spec (NOT the HTML).",
+          "Read preview_artifact_path as the canonical approved design, then use the Write tool to create one self-contained HTML5 file at spec_artifact_path.",
+          "In order, include: sticky header with title/status/run id; Executive Summary; Live Preview embedding the full preview via `<iframe srcdoc=\"...\">` or a side-by-side rendered copy in `<article class=\"preview-frame\">`; the six DESIGN.md sections (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) rendered with swatches, tables, and code blocks; Implementation handoff (Recommended files + components, Implementation steps, Usage example, Accessibility & responsive checklist, Validation commands, Known limitations); and an appendix linking the raw preview path.",
+          "Use dense legible typography, generous whitespace, monospaced code, rendered hex/oklch swatches, and copy-to-clipboard hints in HTML comments.",
+          `Show the absolute preview path (${previewPath}) and file URL (${previewFileUrl}) prominently. Preserve assumptions and limitations; introduce no requirement absent from the final design or DESIGN.md.`,
         ].join("\n"),
       ],
-      ["html_rules", HTML_PREVIEW_RULES],
-      ["anti_design_slop_rules", ANTI_SLOP_RULES],
       [
         "output_format",
         [
-          "Return markdown with headings (NOT the HTML):",
+          "In at most 600 words, return Markdown, not the HTML:",
           "1. Spec written to (absolute path)",
           "2. Sections included",
           "3. How to open the spec (playwright-cli command + manual fallback path)",
@@ -289,6 +286,7 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
           "7. Accessibility / responsive checklist",
           "8. Validation commands",
           "9. Known limitations",
+          GROUNDED_REPORTING,
         ].join("\n"),
       ],
     ]),
@@ -299,29 +297,28 @@ export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{
   await designContext
     .task("final-display", {
       prompt: taggedPrompt([
-        ["role", "You are an opinionated staff design engineer."],
-        [
-          "objective",
-          "Make the rich HTML spec visible to the user. Open the final spec.html with the playwright-cli skill's `playwright-cli` command so the user can review the agreed design and implementation handoff. This is post-export — do NOT solicit change requests; if the user wants more changes, tell them to re-run the workflow. Degrade gracefully if browser automation is unavailable.",
-        ],
         ["spec_path", specPath],
         ["spec_file_url", specFileUrl],
         ["preview_path", previewPath],
         ["preview_file_url", previewFileUrl],
         ["browser_use_guidelines", browserBootstrapRules],
+        ["role", "You are an opinionated staff design engineer."],
+        [
+          "objective",
+          "Show the exported spec with the playwright-cli skill's `playwright-cli` command. Export is complete, so do not solicit changes; direct further changes to a new `/workflow open-claude-design` run and degrade gracefully when browser automation is unavailable.",
+        ],
         [
           "instructions",
           [
-            "1. Probe for `playwright-cli` availability using the bootstrap rules above.",
-            `2. If available, run \`playwright-cli open ${specFileUrl}\`. If that reports a missing browser executable, follow the bootstrap rules and retry once, then \`playwright-cli snapshot\`.`,
-            "3. Do NOT run `show --annotate` or otherwise invite change requests: export is done and there is no further refinement pass. If the user wants changes, tell them to re-run `/workflow open-claude-design`.",
-            `4. Always print, prominently, the absolute paths so the user can open them manually:\n   - Final spec: ${specPath}\n   - Approved preview: ${previewPath}`,
-            "5. Do not block the workflow; return a structured summary even if no tooling worked.",
+            `Use the bootstrap rules, run \`playwright-cli open ${specFileUrl}\`, and if a browser executable is missing follow those rules and retry once before \`playwright-cli snapshot\`.`,
+            "Do not run `show --annotate` or invite changes because no refinement pass remains.",
+            `Prominently print the manual paths:\n- Final spec: ${specPath}\n- Approved preview: ${previewPath}`,
+            "Unavailable tooling must not block the workflow; return the structured summary.",
           ].join("\n"),
         ],
         [
           "output_format",
-          "Markdown with: `display_method` | `spec_path` | `preview_path` | `manual_open_instructions` | `next_action_hint` (how to re-run the workflow for further changes).",
+          `Under 250 words, return Markdown with: \`display_method\` | \`spec_path\` | \`preview_path\` | \`manual_open_instructions\` | \`next_action_hint\` (how to re-run the workflow). ${GROUNDED_REPORTING}`,
         ],
       ]),
       ...designModelConfig,

package/dist/builtin/workflows/builtin/open-claude-design-runner.ts

@@ -19,6 +19,11 @@ import {
   runDiscoveryAndInit,
 } from "./open-claude-design-setup.js";
 
+const GROUNDED_REPORTING =
+  "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
+const DELEGATION_RULE =
+  "Delegate further only work genuinely independent and too large for a handful of tool calls; do not delegate self-verification, and prefer one subagent over several.";
+
 type OpenClaudeDesignOutputs = {
   readonly output_type?: string; readonly design_system?: string; readonly artifact?: string; readonly handoff?: string;
   readonly approved_for_export?: boolean; readonly refinements_completed?: number; readonly import_context?: string; readonly run_id?: string;
@@ -74,28 +79,26 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     });
   }
 
-  // Anthropic-heavy chain for design taste; sonnet-5/sonnet-4.6 dropped as
-  // strictly dominated in Atomic's benchmark (see ralph-models.ts). Opus stays
-  // at :xhigh here — visual quality, not $/task, is the objective for design.
+  // Anthropic-heavy chain for design taste. Opus stays at :xhigh here because
+  // visual quality, rather than cost per task, is the primary objective.
   const designModelConfig = {
-    model: "anthropic/claude-fable-5:high",
+    model: "anthropic/claude-opus-5:high",
     fallbackModels: [
-      "github-copilot/claude-opus-4.8 (1m):high",
-      "anthropic/claude-opus-4-8:high",
-      "cursor/claude-fable-5:high",
-      "cursor/claude-opus-4-8-thinking:high",
+      "github-copilot/claude-opus-5:high",
+      "anthropic/claude-fable-5:high",
+      "github-copilot/claude-fable-5:high",
       "kimi-coding/k3:max",
       "moonshotai/kimi-k3:max",
       "moonshotai-cn/kimi-k3:max",
+      "anthropic/claude-opus-4-8:high",
+      "github-copilot/claude-opus-4.8:high",
       "openai-codex/gpt-5.6-sol:xhigh",
       "github-copilot/gpt-5.6-sol:xhigh",
       "openai/gpt-5.6-sol:xhigh",
-      "cursor/gpt-5.6-sol:xhigh",
       "xai/grok-4.5:high",
-      "cursor/grok-4.5:high",
       "zai/glm-5.2:xhigh",
       "zai-coding-cn/glm-5.2:xhigh",
-      "cursor/glm-5.2",
+      "openrouter/anthropic/claude-opus-5:high",
       "openrouter/anthropic/claude-fable-5:high",
       "openrouter/anthropic/claude-opus-4-8:high",
       "openrouter/moonshotai/kimi-k3:max",
@@ -137,26 +140,26 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     {
       name: "ds-locator",
       task: taggedPrompt([
+        ["user_references", userReferenceContext],
+        ["reference_handling", referenceHandlingRules],
+        ["browser_use_guidelines", browserBootstrapRules],
         ["role", "You are an opinionated staff design engineer."],
         [
           "objective",
-          `Find UI/design-system sources for this request: ${designBrief}. Apply the impeccable \`extract\` sub-skill to find design-system evidence already living in this codebase, plus any user-provided reference URLs/files that should steer generation.`,
+          `Find UI/design-system sources for: ${designBrief}. Apply impeccable \`extract\` to codebase evidence and user reference URLs/files that should steer generation.`,
         ],
-        ["user_references", userReferenceContext],
-        ["reference_handling", referenceHandlingRules],
-        ["browser_use_guidelines", browserBootstrapRules],
+        ["delegation_rule", DELEGATION_RULE],
         [
           "instructions",
           [
-            "1. Locate UI components, stylesheets, tokens, Storybook/examples, screenshots, tests, design docs, and user references.",
-            "2. Return concrete file paths, URLs, or artifact paths plus why each source informs design generation.",
-            "3. Separate primary sources from supporting examples and from reference-only inspiration.",
-            "4. If no explicit design system exists, identify the strongest implicit evidence (most-repeated literals, dominant component patterns).",
+            "Locate UI components, stylesheets, tokens, Storybook/examples, screenshots, tests, design docs, and user references.",
+            "Report concrete file, URL, or artifact paths and why each informs generation; separate primary sources, supporting examples, and reference-only inspiration.",
+            "If no explicit system exists, report the strongest implicit evidence such as repeated literals and dominant component patterns.",
           ].join("\n"),
         ],
         [
           "output_format",
-          "Markdown sections: Project sources table | User reference sources | Reference requirements | Confidence notes.",
+          `In at most 500 words, return Markdown sections: Project sources table | User reference sources | Reference requirements | Confidence notes. ${GROUNDED_REPORTING}`,
         ],
       ]),
       ...designModelConfig,
@@ -164,40 +167,30 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     {
       name: "ds-analyzer",
       task: taggedPrompt([
-        ["role", "You are an opinionated staff design engineer."],
-        [
-          "objective",
-          `Audit the project UI constraints that must shape: ${designBrief}. Independently scan the repository and evaluate the evidence you find against impeccable's six dimensions of design quality. Also capture/parse any user-provided references in this same pass. Do your own scan; do not assume any other stage's output is available.`,
-        ],
+        ["user_references", userReferenceContext],
+        ["reference_handling", referenceHandlingRules],
+        ["browser_use_guidelines", browserBootstrapRules],
         [
           "impeccable_skill",
           "audit — score 0–4 across Accessibility, Performance, Theming, Responsive, Anti-patterns. Tag every finding P0 (blocks release) → P3 (polish). Document, do not fix.",
         ],
-        ["user_references", userReferenceContext],
-        ["reference_handling", referenceHandlingRules],
-        ["browser_use_guidelines", browserBootstrapRules],
+        ["role", "You are an opinionated staff design engineer."],
+        [
+          "objective",
+          `Independently audit UI constraints for: ${designBrief}. Scan the repository, assess evidence across impeccable's six quality dimensions, and capture or parse user references without relying on another stage's output.`,
+        ],
+        ["delegation_rule", DELEGATION_RULE],
         [
           "instructions",
           [
-            "1. Inspect: UI stack, styling approach, token usage, responsive behavior, accessibility conventions, component APIs.",
-            "2. Ground every claim in exact paths, symbols, code examples, screenshots, URLs, or quoted reference excerpts.",
-            "3. Call out constraints that generated designs MUST follow to integrate cleanly.",
-            "4. State uncertainty rather than guessing when evidence is incomplete.",
+            "Inspect the UI stack, styling, tokens, responsive behavior, accessibility conventions, and component APIs.",
+            "Ground each claim in exact paths, symbols, code examples, screenshots, URLs, or quoted reference excerpts.",
+            "Identify integration constraints the generated design must follow, and state uncertainty when evidence is incomplete.",
           ].join("\n"),
         ],
         [
           "output_format",
-          [
-            "Markdown sections in this order:",
-            "1. Stack",
-            "2. Tokens",
-            "3. Components",
-            "4. Layout / responsiveness",
-            "5. Accessibility",
-            "6. Audit scores (per dimension, 0–4)",
-            "7. Reference requirements",
-            "8. Hard constraints for generation",
-          ].join("\n"),
+          `In at most 700 words, return Markdown sections in this order: Stack | Tokens | Components | Layout / responsiveness | Accessibility | Audit scores (per dimension, 0–4) | Reference requirements | Hard constraints for generation. ${GROUNDED_REPORTING}`,
         ],
       ]),
       ...designModelConfig,
@@ -205,26 +198,26 @@ export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext):
     {
       name: "ds-patterns",
       task: taggedPrompt([
+        ["user_references", userReferenceContext],
+        ["reference_handling", referenceHandlingRules],
+        ["browser_use_guidelines", browserBootstrapRules],
         ["role", "You are an opinionated staff design engineer."],
         [
           "objective",
-          `Extract reusable patterns and anti-patterns for: ${designBrief}. Apply the impeccable \`extract\` sub-skill to find design patterns to reuse and anti-patterns to avoid. Also parse/capture user references inside this same pass, translating them into reusable generation patterns. Do your own scan; do not assume any other stage's output is available.`,
+          `Extract reusable patterns and anti-patterns for: ${designBrief}. Apply impeccable \`extract\` to repository evidence and user references, translating them into generation guidance without relying on another stage's output.`,
         ],
-        ["user_references", userReferenceContext],
-        ["reference_handling", referenceHandlingRules],
-        ["browser_use_guidelines", browserBootstrapRules],
+        ["delegation_rule", DELEGATION_RULE],
         [
           "instructions",
           [
-            "1. Find naming, variant, composition, state, animation, and layout patterns that should be reused.",
-            "2. Include examples with concrete paths, component/symbol names, reference URLs, or quoted file/screenshot evidence.",
-            "3. Identify anti-patterns the generated design must avoid — cross-reference impeccable's 25 deterministic anti-patterns.",
-            "4. Do not generalize beyond the evidence found in the repository or imported references.",
+            "Find reusable naming, variant, composition, state, animation, and layout patterns.",
+            "Cite concrete paths, component/symbol names, reference URLs, or quoted file/screenshot evidence.",
+            "Identify generated-design anti-patterns using impeccable's 25 deterministic anti-patterns; do not generalize beyond repository or reference evidence.",
           ].join("\n"),
         ],
         [
           "output_format",
-          "Markdown sections: Reusable patterns | Examples | Reference requirements | Anti-patterns | Generation implications.",
+          `In at most 600 words, return Markdown sections: Reusable patterns | Examples | Reference requirements | Anti-patterns | Generation implications. ${GROUNDED_REPORTING}`,
         ],
       ]),
       ...designModelConfig,

package/dist/builtin/workflows/builtin/open-claude-design-setup.ts

@@ -32,6 +32,9 @@ type SetupDesignContext = {
   task(name: string, options: object): Promise<WorkflowTaskResult>;
 };
 
+const GROUNDED_REPORTING =
+  "Before reporting progress, audit each claim against a tool result from this session. Report only work you can point to evidence for; say so explicitly when something is unverified.";
+
 // ---------------------------------------------------------------------------
 // 0. Discovery + init front door (one workflow stage)
 // ---------------------------------------------------------------------------
@@ -56,36 +59,31 @@ function buildDiscoveryInitPrompt(prompt: string): string {
 /skill:impeccable init
 
 ${taggedPrompt([
-    [
-      "role",
-      "You are an opinionated staff designer running the open-claude-design front door.",
-    ],
+    ["role", "You are an opinionated staff designer running the open-claude-design front door."],
     [
       "objective",
-      `In ONE workflow stage, first shape the request into a confirmed design brief, output type, and reference list for: ${prompt}. Then immediately run impeccable's \`init\` setup so PRODUCT.md and DESIGN.md are detected, created, or reconciled before downstream design research. Do not ask for or wait on a separate init stage.`,
+      `In one stage, confirm the design brief, output type, and references for: ${prompt}. Then run impeccable's \`init\` so PRODUCT.md and DESIGN.md are detected, created, or reconciled before design research; do not wait for another init stage.`,
     ],
     [
       "interview",
       [
-        "Use your `ask_user_question` tool for important gaps you cannot infer from the request or repo.",
-        `Cover: (a) what to build and core jobs/screens; (b) output type — one of ${outputTypes}; (c) references to emulate (URLs, local paths, screenshots, or design docs).`,
-        "Ask 2-3 questions per round; propose inferred answers as options, not finished facts.",
-        "User-provided references are the PRIMARY visual authority and take precedence over DESIGN.md/PRODUCT.md where they conflict.",
+        "Use `ask_user_question` for important gaps not inferable from the request or repository.",
+        `Cover the product and core jobs/screens, one output type (${outputTypes}), and references to emulate (URLs, local paths, screenshots, or design docs).`,
+        "Ask 2-3 questions per round and present inferred answers as options rather than facts.",
+        "User references are the PRIMARY visual authority and override conflicting DESIGN.md/PRODUCT.md guidance.",
       ].join("\n"),
     ],
     [
       "init_instructions",
       [
-        "After the brief is confirmed, run `/skill:impeccable init` in this same stage.",
-        "Let impeccable init perform its own PRODUCT.md/DESIGN.md detection; do not rely on precomputed detection from the workflow runner.",
-        "Create missing PRODUCT.md and/or DESIGN.md when needed, and reconcile existing files against the confirmed brief. Never silently overwrite existing files.",
-        "When the files already exist, keep it light: load them, reconcile against the brief, and only ask about genuine gaps.",
-        "If headless, infer the most defensible brief/register from the prompt and repo signals, write explicit `## Gaps / Assumptions`, and never block.",
+        "After confirmation, run `/skill:impeccable init` in this stage. Let impeccable init perform its own PRODUCT.md/DESIGN.md detection rather than relying on runner detection.",
+        "Create missing files when needed and reconcile existing ones without silently overwriting them; ask only about genuine gaps.",
+        "When headless, infer the most defensible brief/register from the prompt and repository, record explicit `## Gaps / Assumptions`, and do not block.",
       ].join("\n"),
     ],
     [
       "output_format",
-      `Return the structured final answer with: \`brief\` (confirmed expanded design brief), \`output_type\` (one of ${outputTypes}), and \`references\` (array of verbatim URLs/paths; empty array when none). In your visible summary, also include PRODUCT.md/DESIGN.md files written or reconciled and any assumptions.`,
+      `Return the structured fields \`brief\`, \`output_type\` (one of ${outputTypes}), and \`references\` (verbatim URL/path array, empty when none). In at most 250 words, summarize PRODUCT.md/DESIGN.md changes and assumptions. ${GROUNDED_REPORTING}`,
     ],
   ])}`;
 }
@@ -143,44 +141,41 @@ export function buildReferenceDiscoveryPrompt(args: {
     (site, index) => `${index + 1}. ${site.name} — ${site.url}`,
   ).join("\n");
   return taggedPrompt([
+    ["reference_galleries", siteList],
+    ["design_context", args.designContextHint],
+    ["browser_use_guidelines", args.browserBootstrapRules],
+    ["screenshot_dir", args.artifactDir],
     [
       "role",
-      "You are an opinionated staff design engineer and design researcher curating best-in-class, current visual references.",
+      "You are an opinionated staff design engineer curating current, best-in-class visual references.",
     ],
     [
       "objective",
-      `Find beautiful, current reference designs the team can heavily reference to build a stunning ${args.outputType} for: ${args.prompt}. Open each gallery, CLICK THROUGH to the actual design pages of interest, and — ideally — record a scroll-through video of each page so its ANIMATIONS are captured (with a full-page screenshot as a supplement/fallback) plus its real destination URL. Apply the impeccable \`extract\` sub-skill to lift concrete, citable design traits — never vague adjectives.`,
+      `Curate references for a ${args.outputType} serving: ${args.prompt}. Open actual design pages, capture motion with scroll-through video when possible and a full-page screenshot as fallback, record destination URLs, and apply impeccable \`extract\` to report concrete observed traits.`,
     ],
-    ["reference_galleries", siteList],
-    ["design_context", args.designContextHint],
-    ["browser_use_guidelines", args.browserBootstrapRules],
-    ["screenshot_dir", args.artifactDir],
     [
       "instructions",
       [
-        "1. Use the playwright-cli skill to open each gallery above; if `playwright-cli` reports a missing browser executable, follow the bootstrap rules and retry once.",
-        "2. On each gallery, scan the thumbnail grid and pick 1-3 designs of interest whose aesthetic fits this brief.",
-        "3. CLICK INTO each chosen design to open its ACTUAL page — the live site or project detail the thumbnail links to (for example the gallery's 'visit site' / shot-detail link). Do NOT capture the gallery grid or the thumbnail; navigate to the real design page first.",
-        `4. Capture the design's MOTION, not just a still: record a scroll-through video of the ENTIRE page so scroll-triggered animations, parallax, reveals, and transitions are captured. Start with \`playwright-cli video-start ${join(args.artifactDir, "ref-<site>-<n>.webm")}\`, then scroll smoothly from top to bottom — a \`playwright-cli run-code\` script that scrolls in small increments with short waits, or repeated \`playwright-cli mousewheel 0 600\` with pauses — so animations fire and lazy content loads, then \`playwright-cli video-stop\`.`,
-        `5. ALSO take a FULL-PAGE still as a supplement/fallback: \`playwright-cli screenshot --full-page --filename=${join(args.artifactDir, "ref-<site>-<n>.png")}\`. If video recording is unavailable, the full-page screenshot is the minimum.`,
-        "6. Record the FULL destination URL you actually landed on (the live site / project URL, not the gallery listing URL), plus the work's title and author.",
-        "7. For every reference, extract the CONCRETE transferable trait (layout topology, type pairing, color strategy, spacing rhythm) AND the MOTION vocabulary you saw in the recording (entrance animations, scroll reveals, easing, parallax, hover/active states) — cite what you observed on the real page, not what you imagine.",
-        "8. For on-brand fit, consult the project's DESIGN.md / PRODUCT.md and the ds-* discovery evidence in <design_context>; prefer references that fit, and flag any that would require departing from the project's system.",
-        "9. After curating the strongest options, use ask_user_question to ask the user which reference direction they prefer. Offer 2-4 concise choices drawn from the best references/directions and include a clear `None of these fit` choice when appropriate.",
-        "10. If the user says none of the discovered references align with their preference, ask them to provide a reference image, screenshot, URL, or local file path for best results, and include that request and any answer in the final brief.",
-        "11. If `playwright-cli` is unavailable or a site blocks automation, fall back to web search / page fetch to reach the actual design pages, and clearly mark any reference you could not capture with a recording or full-page screenshot.",
-        "12. Never fabricate references or visual claims; if a gallery yielded nothing usable, say so.",
+        "Use the playwright-cli skill to open each gallery; if `playwright-cli` reports a missing browser executable, follow the bootstrap rules and retry once.",
+        "From each gallery, choose 1-3 fitting designs and CLICK INTO each actual live or project-detail page; do not capture only the grid or thumbnail.",
+        `Capture motion across the entire page: start \`playwright-cli video-start ${join(args.artifactDir, "ref-<site>-<n>.webm")}\`, scroll smoothly in small increments with waits (using \`playwright-cli run-code\` or repeated \`playwright-cli mousewheel 0 600\`) so animations fire and lazy content loads, then run \`playwright-cli video-stop\`.`,
+        `Also run \`playwright-cli screenshot --full-page --filename=${join(args.artifactDir, "ref-<site>-<n>.png")}\`; this still is the minimum when video is unavailable.`,
+        "Record the actual destination URL, title, and author. For each reference, cite observed layout, typography, color, spacing, and motion traits rather than inferred traits.",
+        "Assess fit against DESIGN.md, PRODUCT.md, and the ds-* discovery evidence in <design_context>; prefer on-brand references and flag departures.",
+        "Use ask_user_question to ask which reference direction they prefer, offering 2-4 strongest options plus `None of these fit`. If none fit, ask them to provide a reference image, screenshot, URL, or local file path and record the answer.",
+        "If `playwright-cli` is unavailable or automation is blocked, use web search / page fetch to reach actual pages and mark missing recordings or screenshots. Never fabricate references or visual claims; report galleries with no usable result.",
       ].join("\n"),
     ],
     [
       "output_format",
       [
-        "Markdown sections:",
+        "In at most 900 words, return these Markdown sections:",
         "1. Curated references (table: Source gallery | Work (title/author) | Full page URL (destination) | Scroll-through video path | Full-page screenshot path | Transferable trait (incl. motion) | On-brand?)",
-        "2. User preference check: which curated direction/reference the user preferred, or that none aligned and a reference image/screenshot/URL/path was requested for best results.",
-        "3. Synthesis: the 3-5 strongest directions to emulate for THIS design, ranked by fit, calling out motion/animation worth reproducing.",
-        "4. What to avoid (anti-references observed on the real pages).",
-        "5. Verification notes (which references have a scroll-through recording and/or full-page screenshot of the actual design page vs search-only).",
+        "2. User preference check (selected direction, or none plus the requested/provided reference)",
+        "3. Synthesis (3-5 strongest directions ranked by fit, including motion to reproduce)",
+        "4. What to avoid (observed anti-references)",
+        "5. Verification notes (actual-page video/screenshot versus search-only)",
+        GROUNDED_REPORTING,
       ].join("\n"),
     ],
   ]);
@@ -250,23 +245,23 @@ export function buildLivePreviewDisplayPrompt(args: {
         "`next_action_hint`",
       ].join("\n");
   return taggedPrompt([
+    ["preview_path", args.previewPath],
+    ["preview_file_url", args.previewFileUrl],
+    ["browser_use_guidelines", args.browserBootstrapRules],
     [
       "role",
-      "You are an opinionated staff design engineer running interactive `live` QA so the user can iterate on the design in a real browser.",
+      "You are an opinionated staff design engineer running interactive `live` QA in a real browser.",
     ],
     ["objective", objective],
-    ["preview_path", args.previewPath],
-    ["preview_file_url", args.previewFileUrl],
-    ["browser_use_guidelines", args.browserBootstrapRules],
     ["interactive_live_qa", interactiveQa],
     [
       "graceful_degradation",
       [
-        `If \`/skill:impeccable live\` cannot boot (no dev server/HMR for the static file, missing config, or sandbox limits), fall back to opening the preview directly: \`playwright-cli open ${args.previewFileUrl}\`, then \`playwright-cli snapshot\`${isFinal ? "" : " and `playwright-cli show --annotate` so the user can draw/type notes on the page"}. If a \`playwright-cli\` command reports a missing browser executable, follow the bootstrap rules and retry once.`,
-        `If \`playwright-cli\` is also unavailable, print a clear instruction block telling the user to open the file manually at ${args.previewPath} (or ${args.previewFileUrl}).`,
-        "Never block the workflow on unavailable tooling; always exit with a non-empty status string.",
+        `If \`/skill:impeccable live\` cannot boot, open the preview with \`playwright-cli open ${args.previewFileUrl}\`, then run \`playwright-cli snapshot\`${isFinal ? "" : " and `playwright-cli show --annotate` for user notes"}. If the browser executable is missing, follow the bootstrap rules and retry once.`,
+        `If \`playwright-cli\` is unavailable, tell the user to open ${args.previewPath} or ${args.previewFileUrl} manually.`,
+        "Unavailable tooling must not block the workflow; return a non-empty status.",
       ].join("\n"),
     ],
-    ["output_format", outputFormat],
+    ["output_format", `${outputFormat}\nKeep the report under 250 words. ${GROUNDED_REPORTING}`],
   ]);
 }