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

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}`],
   ]);
 }

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

@@ -176,23 +176,23 @@ export function prepareArtifactDir(cwd = process.cwd()): {
 }
 
 export const HTML_PREVIEW_RULES = [
-  "Produce a single self-contained HTML document. Inline all CSS in a <style> block and inline any JS in a <script> block; no external network requests except Google Fonts when explicitly required.",
-  "Embed realistic content that respects the design brief — no Lorem ipsum, no obvious placeholders.",
-  "Implement responsive behavior with sensible breakpoints (use container queries or media queries) so the file renders well from 360px up to 1440px.",
-  "Cover at minimum: default state, hover/focus state for every interactive element, empty state if relevant, loading state if relevant, error state if relevant.",
-  "Use accessible markup: semantic landmarks, labeled form controls, sufficient contrast (WCAG AA), visible focus styles, prefers-reduced-motion respected.",
-  "Annotate the file with HTML comments that mark sections, states, and design-system token references so engineers can read the intent quickly.",
+  "Produce one self-contained HTML document: inline CSS in <style> and JS in <script>; make no external requests except explicitly required Google Fonts.",
+  "Use realistic brief-specific content, not Lorem ipsum or obvious placeholders.",
+  "Render well from 360px to 1440px with sensible container or media-query breakpoints.",
+  "Include default and hover/focus states for every interactive element, plus empty, loading, and error states where relevant.",
+  "Use semantic landmarks, labeled controls, WCAG AA contrast, visible focus, and prefers-reduced-motion.",
+  "Add HTML comments marking sections, states, and design-system token references for engineering handoff.",
 ].join("\n");
 
 export const ANTI_SLOP_RULES = [
-  "Do not produce generic AI-slop palettes (purple/indigo gradients, blue-to-pink, neon glassmorphism stacks, nested card grids).",
-  "Avoid the AI design clichés impeccable's anti-pattern catalog calls out: gradient text for emphasis, side-tab borders, three-font headers, decorative shadows on flat-by-default systems.",
-  "Commit to a specific aesthetic direction; do not hedge with generic SaaS defaults.",
+  "Avoid generic AI palettes and structures: purple/indigo or blue-to-pink gradients, neon glassmorphism stacks, and nested card grids.",
+  "Avoid impeccable catalog clichés: gradient emphasis text, side-tab borders, three-font headers, and decorative shadows in flat-by-default systems.",
+  "Commit to a specific aesthetic rather than generic SaaS defaults.",
 ].join("\n");
 
 /** Reference-import precedence note shared by import, generation, and refinement. */
 export const REFERENCE_PRECEDENCE =
-  "User-provided references in <reference_context> are the PRIMARY visual authority: when they conflict with DESIGN.md/PRODUCT.md, follow the references. DESIGN.md governs decisions the references do not cover; PRODUCT.md still governs strategic register/voice.";
+  "User references in <reference_context> are the PRIMARY visual authority and override conflicting DESIGN.md/PRODUCT.md guidance. DESIGN.md governs uncovered design decisions; PRODUCT.md still governs strategic register/voice.";
 
 export type PlaywrightCliStatus = {
   /** Whether the `playwright-cli` command is expected to be available to downstream stages. */
@@ -299,21 +299,16 @@ export function ensurePlaywrightCli(): PlaywrightCliStatus {
   }
 }
 
-/**
- * Build the per-run browser bootstrap guidance injected into stage prompts.
- * When the deterministic setup step already ensured `playwright-cli` is installed,
- * the guidance tells stages to assume availability and not waste turns
- * reinstalling; otherwise it retains the original probe-and-install fallback.
- */
+/** Build browser guidance for downstream stage prompts. */
 export function buildPlaywrightCliBootstrapRules(status: PlaywrightCliStatus): string {
   const probeRule = status.available
-    ? "The workflow's deterministic setup step already ensured the playwright-cli skill's `playwright-cli` command is installed and on PATH; assume it is available and do NOT reinstall it. Only if a `playwright-cli` command reports it is missing should you re-probe with `which playwright-cli` (or `npx --no-install playwright-cli --version`) and run `npm install -g @playwright/cli@latest` once before retrying. Do not add project dependencies."
-    : `The workflow's deterministic setup step attempted to install the playwright-cli skill's \`playwright-cli\` command but it FAILED with: "${status.error ?? "unknown error"}". Treat this as a known starting condition to work around, not a hard blocker. Probe with \`which playwright-cli\` (or \`npx --no-install playwright-cli --version\`) and retry once with \`npm install -g @playwright/cli@latest\`; if it still fails, use the error above to diagnose a workaround (for example: EACCES/permission errors → retry with a user-writable global prefix; missing npm/Node → report it plainly; network/registry errors → surface them). If the command still cannot be made available, degrade gracefully and surface the manual file path / URL. Do not add project dependencies.`;
+    ? "The playwright-cli skill's `playwright-cli` command is on PATH. Do not reinstall it unless a command reports it missing; then probe with `which playwright-cli` (or `npx --no-install playwright-cli --version`), run `npm install -g @playwright/cli@latest` once, and retry. Do not add project dependencies."
+    : `The playwright-cli skill's \`playwright-cli\` command failed setup: "${status.error ?? "unknown error"}". Probe with \`which playwright-cli\` (or \`npx --no-install playwright-cli --version\`) and retry once with \`npm install -g @playwright/cli@latest\`. For permission errors, use a user-writable global prefix; report missing npm/Node or network/registry errors plainly. If still unavailable, surface the manual file path / URL. Do not add project dependencies.`;
   return [
     probeRule,
-    "Use `playwright-cli open <url>` when a generated local preview should be visible to the user, and use `playwright-cli snapshot` plus `playwright-cli screenshot --filename=<file>` for review evidence.",
-    "If a `playwright-cli` command reports a missing browser executable, install the browser once with `npx playwright install chromium` and retry.",
-    "If `playwright-cli` is unavailable after three attempts or the browser runtime still fails, degrade gracefully and surface the manual file path / URL.",
+    "Use `playwright-cli open <url>` to show a local preview; use `playwright-cli snapshot` and `playwright-cli screenshot --filename=<file>` for review evidence.",
+    "If a `playwright-cli` command reports a missing browser executable, run `npx playwright install chromium` once and retry.",
+    "If `playwright-cli` is unavailable after three attempts or the browser runtime still fails, surface the manual file path / URL.",
   ].join("\n");
 }
 

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

@@ -18,6 +18,7 @@
 
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runOpenClaudeDesignWorkflow } from "./open-claude-design-runner.js";
 import {
   DEFAULT_MAX_REFINEMENTS,
@@ -56,5 +57,5 @@ export default workflow({
     spec_file_url: Type.Optional(Type.String({ description: "file:// URL for the generated spec.html file." })),
     playwright_cli_status: Type.Optional(Type.String({ description: "Outcome of the initial deterministic step that ensures the playwright-cli skill's `playwright-cli` command is installed." })),
   },
-  run: async (ctx) => await runOpenClaudeDesignWorkflow(ctx),
+  run: async (ctx) => await runOpenClaudeDesignWorkflow(withSteeringPropagationContext(ctx)),
 });

package/dist/builtin/workflows/builtin/ralph-core.ts

@@ -3,7 +3,10 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { Type } from "typebox";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
-import { LITERAL_OBJECTIVE_CONTRACT } from "./shared-prompts.js";
+import {
+  E2E_VERIFICATION_GUIDANCE,
+  LITERAL_OBJECTIVE_CONTRACT,
+} from "./shared-prompts.js";
 import type { ReviewDecision, ReviewFinding } from "./ralph-review-gate.js";
 import { reviewDecisionApproved } from "./ralph-review-gate.js";
 import {
@@ -177,7 +180,8 @@ export async function createImplementationNotesFile(prompt: string): Promise<str
     "",
     "## Running Notes",
     "",
-    "- Record implementation decisions, deviations from the research findings, tradeoffs, blockers, validation notes, and anything else the user should know.",
+    "- Record implementation decisions, deviations from research, tradeoffs, blockers, validation outcomes, and user-relevant facts. Keep entries concise and readable.",
+    "- 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.",
   ].join("\n");
   await writeFile(notesPath, `${initialNotes}\n`, {
     encoding: "utf8",
@@ -198,12 +202,10 @@ export async function createQaEvidenceVideoPath(): Promise<string> {
 
 export function renderQaE2eVideoGuidance(qaVideoPath: string): string {
   return [
-    "QA the change end-to-end whenever it touches user-visible UI behavior, including full-stack changes whose UI correctness depends on backend/API behavior. Use the `playwright-cli` skill (or delegate to a subagent with `skill: \"playwright-cli\"`) to drive the running application like a user and prove the implemented scenario actually works.",
-    `Record that QA E2E pass as a reviewable video so the user can watch the feature working. After \`playwright-cli open\`, start recording with \`playwright-cli video-start ${qaVideoPath}\`, annotate the scenario with \`playwright-cli video-chapter\` / \`playwright-cli video-show-actions\`, exercise the full user scenario, then \`playwright-cli video-stop\`. Write the video to exactly this path and overwrite any prior recording so it always reflects the latest implemented state: ${qaVideoPath}`,
-    `After recording, add the video to the implementation notes as a reference: include a \`## QA E2E Video\` entry with the absolute path ${qaVideoPath} and a one-line description of the proven scenario, so the user can review the proof when this stage finishes.`,
-    "If the change has no user-visible UI scenario (pure refactor, docs, infra, or non-UI library code), do not fabricate a video; record in the implementation notes that no QA E2E video applies and why.",
-    "Assume credentials, auth, and browser environment access exist until a concrete attempt proves otherwise. Before declaring the QA E2E video impractical, check credential/auth state with non-destructive commands, attempt to launch the app/flow, and record the exact command(s) plus observed failure output.",
-    "If `playwright-cli` or a browser runtime is unavailable, install it once per the skill (`npm install -g @playwright/cli@latest`, then `npx playwright install chromium` for a missing browser executable). If it still cannot run, record the smallest validation actually performed and note that the QA E2E video could not be produced — never claim a video exists when it does not.",
+    E2E_VERIFICATION_GUIDANCE,
+    `For a user-visible UI scenario, record the QA pass for review. After \`playwright-cli open\`, use \`playwright-cli video-start ${qaVideoPath}\`, annotate with \`playwright-cli video-chapter\` / \`playwright-cli video-show-actions\`, exercise the complete scenario, then run \`playwright-cli video-stop\`. Write to exactly ${qaVideoPath}, overwriting stale evidence.`,
+    `Add a \`## QA E2E Video\` entry to the implementation notes with the absolute path ${qaVideoPath} and one sentence naming the proven scenario. For changes without a user-visible UI scenario, record why video does not apply; never fabricate one.`,
+    "If `playwright-cli` or its browser runtime is unavailable, install it once per the skill (`npm install -g @playwright/cli@latest`, then `npx playwright install chromium` when needed). If a concrete attempt still fails, record the commands, observed failure output, smallest validation performed, and that no video was produced.",
   ].join("\n");
 }
 
@@ -333,29 +335,29 @@ export function renderResearchPromptRefinementPrompt(args: {
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
 }): string {
-  const basePrompt = `/skill:prompt-engineer Transform the following user request into a codebase and online research question which can be thoroughly explored: ${args.request}`;
-  return [
-    basePrompt,
-    taggedPrompt([
-      ["objective", `Research the full requested task: ${args.request}`],
-      ["acceptance_criteria", args.acceptanceCriteria],
-      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
-      args.workflowCwdContext,
-      [
-        "review_findings",
-        args.latestReviewReportPath === undefined
-          ? "No prior review artifact is available."
-          : [
-              `Latest review round artifact: ${args.latestReviewReportPath}`,
-              "Read this JSON artifact and include unresolved reviewer findings in the transformed research question only when they are consistent with the literal objective and acceptance criteria.",
-            ].join("\n"),
-      ],
-      [
-        "output_format",
-        "Return only the transformed codebase and online research question. Do not implement code changes and do not write an RFC/spec.",
-      ],
-    ]),
-  ].join("\n\n");
+  return taggedPrompt([
+    ["acceptance_criteria", args.acceptanceCriteria],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined
+        ? "No prior review artifact is available."
+        : [
+            `Latest review round artifact: ${args.latestReviewReportPath}`,
+            "Include unresolved reviewer findings in the transformed research question only when consistent with the literal objective and acceptance criteria.",
+          ].join("\n"),
+    ],
+    ["objective", `Research the full requested task: ${args.request}`],
+    [
+      "output",
+      "Return only one concise, complete codebase and online research question. Do not implement code changes or write an RFC/spec.",
+    ],
+    [
+      "instruction",
+      `/skill:prompt-engineer Transform this request into a codebase and online research question that covers the full requested task: ${args.request}`,
+    ],
+  ]);
 }
 
 
@@ -367,33 +369,35 @@ export function renderResearchPrompt(args: {
   readonly latestReviewReportPath: string | undefined;
   readonly researchPath: string;
 }): string {
-  const basePrompt = `/skill:research-codebase ${args.transformedResearchQuestion}`;
-  return [
-    basePrompt,
-    taggedPrompt([
-      ["objective", `Research implementation requirements for: ${args.prompt}`],
-      ["acceptance_criteria", args.acceptanceCriteria],
-      ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
-      args.workflowCwdContext,
-      [
-        "review_findings",
-        args.latestReviewReportPath === undefined
-          ? "No prior review artifact is available."
-          : [
-              `Latest review round artifact: ${args.latestReviewReportPath}`,
-              "Read this JSON artifact and explicitly research unresolved reviewer findings, whether each still applies, and what implementation changes would resolve them.",
-            ].join("\n"),
-      ],
+  return taggedPrompt([
+    ["acceptance_criteria", args.acceptanceCriteria],
+    ["literal_contract", LITERAL_OBJECTIVE_CONTRACT],
+    args.workflowCwdContext,
+    [
+      "review_findings",
+      args.latestReviewReportPath === undefined
+        ? "No prior review artifact is available."
+        : [
+            `Latest review round artifact: ${args.latestReviewReportPath}`,
+            "Research whether each unresolved finding still applies and what objective-aligned implementation change would resolve it.",
+          ].join("\n"),
+    ],
+    ["objective", `Research implementation requirements for: ${args.prompt}`],
+    [
+      "research_artifact",
       [
-        "research_artifact",
-        [
-          `Write research findings for this workflow run to: ${args.researchPath}`,
-          "Return a complete Markdown research report with codebase findings, online/contextual findings when useful, concrete implementation guidance, relevant files/tests/docs, unresolved reviewer finding analysis, and validation recommendations.",
-          "Do not author an RFC/spec and do not implement code changes in this stage.",
-        ].join("\n"),
-      ],
-    ]),
-  ].join("\n\n");
+        "Return the complete research report as your final message. This workflow saves that final message verbatim as the run's research artifact; downstream implementation and review stages read it from that file.",
+        `Do not write ${args.researchPath} yourself. Anything written there during this stage is replaced by your final message, so a file you author is lost and a final message that only points at the path leaves later stages with no findings. Skill-owned notes under research/docs/ and research/web/ are unaffected.`,
+        "Produce a complete Markdown report with codebase and useful online/contextual findings, implementation guidance, relevant files/tests/docs, unresolved-finding analysis, and validation recommendations. Lead with conclusions; keep facts, caveats, and implementation-relevant next steps; drop background and repetition.",
+        "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.",
+        "Do not author an RFC/spec or implement code changes.",
+      ].join("\n"),
+    ],
+    [
+      "instruction",
+      `/skill:research-codebase ${args.transformedResearchQuestion}`,
+    ],
+  ]);
 }