@bastani/atomic 0.9.0-alpha.2 → 0.9.0-alpha.4

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

@@ -1,12 +1,19 @@
-import { join } from "node:path";
 import type { WorkflowTaskResult } from "../src/shared/types.js";
 import {
   ANTI_SLOP_RULES,
   HTML_PREVIEW_RULES,
-  exportGateDecisionFromResult,
-  refinementDecisionFromResult,
+  REFERENCE_PRECEDENCE,
   taggedPrompt,
 } from "./open-claude-design-utils.js";
+import {
+  assertUserAnnotationsThreaded,
+  hasMeaningfulFeedback,
+  persistPreviewFeedback,
+  toPreviewFeedback,
+  userAnnotationsBlock,
+  type PreviewFeedback,
+} from "./open-claude-design-feedback.js";
+import { buildLivePreviewDisplayPrompt } from "./open-claude-design-setup.js";
 
 type DesignContext = {
   task(name: string, options: object): Promise<WorkflowTaskResult>;
@@ -15,6 +22,19 @@ type DesignContext = {
 
 type ModelConfig = Record<string, object | string | readonly string[]>;
 
+type ForkContinuationOptions = {
+  readonly context?: "fork";
+  readonly forkFromSessionFile?: string;
+};
+
+function forkContinuationOptions(
+  sessionFile: string | undefined,
+): ForkContinuationOptions {
+  return sessionFile === undefined || sessionFile.length === 0
+    ? {}
+    : { context: "fork", forkFromSessionFile: sessionFile };
+}
+
 type RefineOptions = {
   readonly designContext: DesignContext;
   readonly prompt: string;
@@ -25,230 +45,195 @@ type RefineOptions = {
   readonly artifactDir: string;
   readonly browserBootstrapRules: string;
   readonly designSystem: string;
-  readonly latestDesign: string;
+  readonly generationContext: readonly WorkflowTaskResult[];
   readonly designModelConfig: ModelConfig;
-  readonly refinementDecisionConfig: ModelConfig;
+  readonly workflowCwd: string;
+  readonly referencesBrief?: string;
+  readonly importContext?: string;
 };
 
 export async function refineOpenClaudeDesign(options: RefineOptions): Promise<{ readonly latestDesign: string; readonly approvedForExport: boolean; readonly refinementCount: number; }> {
-  const { designContext, prompt, outputType, maxRefinements, previewPath, previewFileUrl, artifactDir, browserBootstrapRules, designSystem, designModelConfig, refinementDecisionConfig } = options;
-  let latestDesign = options.latestDesign;
+  const { designContext, prompt, outputType, maxRefinements, previewPath, previewFileUrl, artifactDir, browserBootstrapRules, designSystem, designModelConfig, workflowCwd } = options;
+  const referencesBrief = options.referencesBrief ?? "";
+  const importContext = options.importContext ?? "";
+  let latestDesign = "";
+  let latestGenerateSessionFile: string | undefined;
+  let latestUserFeedbackSessionFile: string | undefined;
+  let pendingFeedback: PreviewFeedback | undefined;
   let approvedForExport = false;
   let refinementCount = 0;
-  for (let iteration = 1; iteration <= maxRefinements; iteration += 1) {
-    refinementCount = iteration;
 
-    const feedback = await designContext.task(`user-feedback-${iteration}`, {
-      prompt: taggedPrompt([
-        [
-        "role",
-        "You are a staff product manager with deep design and engineering empathy collecting actionable refinement feedback from the user about the rendered HTML preview. You call out bs because the user is your partner, not your boss; you want to get to a great design together, and that means being honest about what you don't like and what the user won't like. You are user-experience-obsessed.",
-        ],
-        [
-        "objective",
-        `Decide whether refinement is needed for iteration ${iteration}/${maxRefinements} of: ${prompt}. Apply the impeccable \`critique\` sub-skill to decide whether the artifact is ready. Score Nielsen's 10 heuristics 0–4, cognitive-load count 0–8, persona-based passes, cross-check the 25 anti-pattern detector. Produce a prioritized list, not free-form prose.`,
-        ],
-        ["preview_path", previewPath],
-        ["preview_file_url", previewFileUrl],
-        ["current_design_summary", "{previous}"],
-        [
-        "instructions",
-        [
-          "1. If a previous `preview-display-*` step captured annotated user feedback or notes, honor them as the primary signal.",
-          "2. Otherwise, you may inspect the HTML file at preview_path directly (read it from disk) and run an impeccable `critique` against it.",
-          "3. Decide whether the current design is ready for export.",
-          "4. If refinement is still needed, put specific changes in required_changes ordered by user value and implementation risk.",
-          "5. Never request changes that contradict DESIGN.md unless you explicitly identify and explain the conflict.",
-        ].join("\n"),
-        ],
-        [
-        "output_format",
-        [
-          "Set ready_for_export=true only when the current preview needs no further refinement before export.",
-          "Set ready_for_export=false and populate required_changes when another polish iteration is needed.",
-        ].join("\n"),
-        ],
-      ]),
-      previous: { name: "current-design", text: latestDesign },
-      ...refinementDecisionConfig,
-    });
-
-    const feedbackDecision = refinementDecisionFromResult(feedback);
-    if (feedbackDecision.ready_for_export) {
-      approvedForExport = true;
-      break;
+  for (let iteration = 1; iteration <= maxRefinements; iteration += 1) {
+    const generateStageName = `generate-${iteration}`;
+    const generatePrompt = pendingFeedback === undefined
+      ? buildInitialGeneratePrompt({
+          prompt,
+          outputType,
+          previewPath,
+          designSystem,
+          referencesBrief,
+          importContext,
+        })
+      : buildGenerateRevisionPrompt({
+          prompt,
+          outputType,
+          previewPath,
+          designSystem,
+          latestDesign,
+          referencesBrief,
+          importContext,
+          feedback: pendingFeedback,
+        });
+    if (pendingFeedback !== undefined) {
+      assertUserAnnotationsThreaded(generatePrompt, [pendingFeedback], generateStageName);
     }
 
-    const validation = await designContext.parallel(
-      [
-        {
-        name: `critique-${iteration}`,
-        task: taggedPrompt([
-          [
-            "role",
-            "You are a staff product manager with deep design and engineering empathy collecting actionable refinement feedback from the user about the rendered HTML preview. You call out bs because the user is your partner, not your boss; you want to get to a great design together, and that means being honest about what you don't like and what the user won't like. You are user-experience-obsessed.",
-          ],
-          [
-            "objective",
-            `Critique the current ${outputType} for: ${prompt}. Produce the formal impeccable critique report. Apply the impeccable \`critique\` sub-skill to run the formal two-pass review against the live HTML preview.`,
-          ],
-          ["preview_path", previewPath],
-          ["current_design_and_feedback", "{previous}"],
-          [
-            "instructions",
-            [
-            "1. Read the HTML at preview_path and ground every finding in concrete element/selector references.",
-            "2. Return concrete fixes only; avoid generic praise or non-actionable subjective notes.",
-            "3. Call out every DESIGN.md conflict and every missing state explicitly.",
-            ].join("\n"),
-          ],
-          [
-            "output_format",
-            [
-            "Markdown with sections in this order:",
-            "1. AI-slop verdict (PASS or FAIL with the specific tells)",
-            "2. Heuristic scores (table: heuristic | 0–4)",
-            "3. Cognitive load failure count (0–8) with named failures",
-            "4. Issues table: Issue | Evidence (selector/line) | Impact | Recommended fix | Severity P0–P3",
-            "5. Questions worth answering before shipping",
-            ].join("\n"),
-          ],
-        ]),
-        previous: [
-          { name: "current-design", text: latestDesign },
-          feedback,
-        ],
-        ...designModelConfig,
-        },
-        {
-        name: `screenshot-${iteration}`,
-        task: taggedPrompt([
-          [
-            "role",
-            "You are a staff QA engineer with design expertise.",
-          ],
-          [
-            "objective",
-            `Validate visual implementation risks for: ${prompt}. Apply the impeccable \`audit + live\` sub-skills to run a live audit against the rendered HTML preview, validating or invalidating every visual risk with evidence from the actual rendered page in a real browser, not just the source code.`,
-          ],
-          ["preview_path", previewPath],
-          ["preview_file_url", previewFileUrl],
-          ["current_design_and_feedback", "{previous}"],
-          [
-            "browser_use_guidelines",
-            browserBootstrapRules,
-          ],
-          [
-            "instructions",
-            [
-            `1. Attempt rendering verification via the playwright-cli skill: \`playwright-cli open ${previewFileUrl}\`. If that reports a missing browser executable, follow the bootstrap rules and retry once.`,
-            `2. Then run \`playwright-cli resize 360 800\`, \`playwright-cli screenshot --filename=${join(artifactDir, `mobile-${iteration}.png`)}\`, \`playwright-cli resize 1440 900\`, \`playwright-cli screenshot --filename=${join(artifactDir, `desktop-${iteration}.png`)}\`.`,
-            "3. Check: contrast (WCAG AA), overflow, spacing rhythm, alignment, breakpoint behavior, empty/loading/error states, keyboard/pointer affordances, focus rings, prefers-reduced-motion.",
-            "4. If `playwright-cli` is unavailable or browser bootstrap fails, perform a static design review of the HTML source and mark every finding as `needs-rendering-verification`.",
-            "5. Distinguish confirmed visual issues from risks that need rendering verification. Never fabricate rendered evidence.",
-            ].join("\n"),
-          ],
-          [
-            "output_format",
-            "Markdown sections: Tooling used | Confirmed issues (with screenshot refs) | Needs rendering verification | Suggested fixes | Audit scores (0–4 per impeccable audit dimension).",
-          ],
-        ]),
-        previous: [
-          { name: "current-design", text: latestDesign },
-          feedback,
-        ],
-        ...designModelConfig,
-        },
-      ],
-      { task: prompt },
-    );
-
-    const applied = await designContext.task(`apply-changes-${iteration}`, {
-      prompt: taggedPrompt([
-        [
-        "role",
-        "You are an opinionated staff design engineer.",
-        ],
-        [
-        "objective",
-        `Produce the next ${outputType} revision for: ${prompt}. Update the HTML file in place; do not branch the artifact. Apply the impeccable \`polish\` sub-skill to methodically apply the required changes, addressing every critique finding and screenshot-validated issue with surgical precision. This is not a redesign; it's a focused polish iteration to get from the current design to an export-ready state in one step.`,
-        ],
-        ["design_system", designSystem],
-        ["preview_artifact_path", previewPath],
-        ["revision_context", "{previous}"],
-        [
-        "instructions",
-        [
-          "1. Read the current HTML at preview_artifact_path with your file-read tool.",
-          `2. Apply user feedback, critique findings, screenshot/visual QA findings, and DESIGN.md constraints together. Overwrite ${previewPath} with the revised HTML (full file rewrite, not patches — the artifact must always be self-contained).`,
-          "3. Preserve strong existing design decisions unless a finding requires change.",
-          "4. Resolve conflicting feedback explicitly; choose the safest DESIGN.md-aligned option and note the trade-off.",
-          "5. Update states, accessibility, responsiveness, and HTML implementation comments when changes affect them.",
-          "6. After writing, return a short markdown summary listing the changes, trade-offs, and remaining questions — do NOT paste the HTML body.",
-        ].join("\n"),
-        ],
-        [
-        "output_format",
-        [
-          "Markdown with headings:",
-          "1. Revised artifact (path only)",
-          "2. Changes applied (bullet list, each tied to a critique or screenshot finding)",
-          "3. Trade-offs / conflicts resolved",
-          "4. Remaining questions",
-        ].join("\n"),
-        ],
-      ]),
-      previous: [
-        { name: "current-design", text: latestDesign },
-        feedback,
-        ...validation,
-      ],
+    const generated = await designContext.task(generateStageName, {
+      prompt: generatePrompt,
+      previous: pendingFeedback === undefined
+        ? options.generationContext
+        : { name: "current-design", text: latestDesign },
       ...designModelConfig,
+      ...forkContinuationOptions(latestGenerateSessionFile),
     });
-    latestDesign = applied.text;
+    latestDesign = generated.text;
+    latestGenerateSessionFile = generated.sessionFile ?? latestGenerateSessionFile;
+    refinementCount = iteration;
 
-    // Re-display the freshly revised preview so the user can keep iterating.
-    await designContext
-      .task(`preview-display-${iteration}`, {
-        prompt: taggedPrompt([
-        [
-          "role",
-          "You are a staff product manager with expertise in design. Re-open the revised HTML preview so the user can review the latest iteration.",
-        ],
-        [
-          "objective",
-          `Show the user the revised preview after iteration ${iteration}/${maxRefinements} and capture any new annotated feedback for the next loop.`,
-        ],
-        ["preview_path", previewPath],
-        ["preview_file_url", previewFileUrl],
-        [
-          "browser_use_bootstrap",
+    const userFeedbackResult = await designContext
+      .task(`user-feedback-${iteration}`, {
+        prompt: buildLivePreviewDisplayPrompt({
+          previewPath,
+          previewFileUrl,
           browserBootstrapRules,
-        ],
-        [
-          "instructions",
-          [
-            `1. If \`playwright-cli\` is available, run \`playwright-cli open ${previewFileUrl}\`. If that reports a missing browser executable, follow the bootstrap rules and retry once.`,
-            "2. Then run `playwright-cli snapshot` and, for interactive review, `playwright-cli show --annotate`; otherwise ask the user to provide feedback inline.",
-            `3. If \`playwright-cli\` is unavailable or browser bootstrap fails, surface the path clearly: ${previewPath} (URL: ${previewFileUrl}).`,
-            "4. Return any captured annotations as structured notes the next user-feedback step can read.",
-            "5. Do not block on unavailable tooling.",
-          ].join("\n"),
-        ],
-        [
-          "output_format",
-          "Markdown with: `display_method`, `preview_path`, `annotated_snapshot` (if any), `user_notes` (if any), `next_action_hint`.",
-        ],
-        ]),
+          iteration,
+          maxRefinements,
+        }),
         ...designModelConfig,
+        ...forkContinuationOptions(
+          latestUserFeedbackSessionFile ?? latestGenerateSessionFile,
+        ),
       })
       .catch(() => undefined);
-    }
 
+    latestUserFeedbackSessionFile =
+      userFeedbackResult?.sessionFile ?? latestUserFeedbackSessionFile;
+    const feedback = toPreviewFeedback({
+      iteration,
+      stageName: `user-feedback-${iteration}`,
+      result: userFeedbackResult,
+    });
+    persistPreviewFeedback({ artifactDir, workflowCwd, feedback });
+
+    if (!hasMeaningfulFeedback(feedback)) {
+      approvedForExport = true;
+      break;
+    }
+    pendingFeedback = feedback;
+  }
 
   return { latestDesign, approvedForExport, refinementCount };
 }
 
+function buildInitialGeneratePrompt(args: {
+  readonly prompt: string;
+  readonly outputType: string;
+  readonly previewPath: string;
+  readonly designSystem: string;
+  readonly referencesBrief: string;
+  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],
+    ["reference_inspiration", args.referencesBrief],
+    ["reference_precedence", REFERENCE_PRECEDENCE],
+    ["preview_artifact_path", args.previewPath],
+    ["html_rules", HTML_PREVIEW_RULES],
+    ["anti_design_slop_rules", ANTI_SLOP_RULES],
+    [
+      "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.",
+      ].join("\n"),
+    ],
+    [
+      "output_format",
+      [
+        "Return markdown with the headings below. DO NOT paste the HTML; the file at preview_artifact_path is the artifact.",
+        "1. Artifact overview",
+        "2. Files written (must include the absolute path to preview.html)",
+        "3. UI structure and states (referenced by HTML section IDs)",
+        "4. Accessibility and responsive behavior",
+        "5. Implementation notes",
+        "6. Assumptions / open questions",
+      ].join("\n"),
+    ],
+  ]);
+}
+
+function buildGenerateRevisionPrompt(args: {
+  readonly prompt: string;
+  readonly outputType: string;
+  readonly previewPath: string;
+  readonly designSystem: string;
+  readonly latestDesign: string;
+  readonly referencesBrief: string;
+  readonly importContext: string;
+  readonly feedback: PreviewFeedback;
+}): 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],
+    ["reference_precedence", REFERENCE_PRECEDENCE],
+    ["preview_artifact_path", args.previewPath],
+    ["user_feedback", annotations.text],
+    ["current_design_summary", args.latestDesign],
+    ["html_rules", HTML_PREVIEW_RULES],
+    ["anti_design_slop_rules", ANTI_SLOP_RULES],
+    [
+      "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.",
+      ].join("\n"),
+    ],
+    [
+      "output_format",
+      [
+        "Markdown with headings:",
+        "1. Revised artifact (path only)",
+        "2. User feedback addressed (each note/live change → how it was applied, or why it was deferred/conflicts)",
+        "3. Changes applied",
+        "4. Trade-offs / unresolved user feedback",
+      ].join("\n"),
+    ],
+  ]);
+}
+
 type ExportOptions = {
   readonly designContext: DesignContext;
   readonly prompt: string;
@@ -261,172 +246,89 @@ type ExportOptions = {
   readonly designSystem: string;
   readonly latestDesign: string;
   readonly designModelConfig: ModelConfig;
-  readonly exportGateDecisionConfig: ModelConfig;
 };
 
 export async function exportOpenClaudeDesign(options: ExportOptions): Promise<{ readonly latestDesign: string; readonly handoff: WorkflowTaskResult; }> {
-  const { designContext, prompt, outputType, previewPath, previewFileUrl, specPath, specFileUrl, browserBootstrapRules, designSystem, designModelConfig, exportGateDecisionConfig } = options;
-  let latestDesign = options.latestDesign;
-  const preExport = await designContext.task("pre-export-scan", {
-      prompt: taggedPrompt([
-        [
-          "role",
-          "You are a staff product manager with deep design and engineering empathy collecting actionable refinement feedback from the user about the rendered HTML preview. You call out bs because the user is your partner, not your boss; you want to get to a great design together, and that means being honest about what you don't like and what the user won't like. You are user-experience-obsessed.",
-        ],
-        [
-          "objective",
-          `Final quality gate for this ${outputType}: ${prompt}. Decide whether the HTML preview at preview_path is safe to export. Apply the impeccable \`audit\` sub-skill one final time to block export only for concrete, evidence-backed issues.`,
-        ],
-        ["preview_path", previewPath],
-        ["final_design_summary", "{previous}"],
+  const { designContext, prompt, outputType, previewPath, previewFileUrl, specPath, specFileUrl, browserBootstrapRules, designSystem, designModelConfig } = options;
+  const latestDesign = options.latestDesign;
+
+  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}"],
+      [
+        "instructions",
         [
-          "instructions",
-          [
-            "1. Read the HTML at preview_path and score it across all five audit dimensions.",
-            "2. Scan for banned anti-patterns, accessibility blockers, severe visual regressions, missing critical states, and handoff gaps.",
-            "3. Only mark findings as blocking when they would materially harm implementation or user experience (impeccable P0 severity).",
-            "4. Decide whether export is blocked.",
-            "5. Every blocking finding must include selector-level evidence and a must-fix action.",
-          ].join("\n"),
-        ],
+          `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).",
+        ].join("\n"),
+      ],
+      ["html_rules", HTML_PREVIEW_RULES],
+      ["anti_design_slop_rules", ANTI_SLOP_RULES],
+      [
+        "output_format",
         [
-          "decision_rules",
-          [
-            "Set has_blocking_findings=true only when one or more P0 findings block export.",
-            "Populate blocking_findings with every blocking P0 issue; leave it empty when export is safe.",
-          ].join("\n"),
-        ],
-      ]),
-      previous: { name: "final-design", text: latestDesign },
-      ...exportGateDecisionConfig,
-    });
-
-    const exportGateDecision = exportGateDecisionFromResult(preExport);
-  if (exportGateDecision.has_blocking_findings) {
-      const forcedFix = await designContext.task("forced-fix", {
-        prompt: taggedPrompt([
-          [
-            "role",
-            "You are an opinionated staff design engineer. Apply the impeccable `harden` sub-skill to remove blocking findings without redesigning.",
-          ],
-          [
-            "objective",
-            `Remove the blocking findings from the HTML preview without broad redesign. Output: ${prompt}.`,
-          ],
-          [
-            "impeccable_skill",
-            "harden — make the artifact production-ready against real-world data extremes, error scenarios, internationalization, and device/context variability. Fix only what is broken; do not redesign.",
-          ],
-          ["blocking_findings", preExport.text],
-          ["design_system", designSystem],
-          ["preview_artifact_path", previewPath],
-          ["current_final_design_summary", "{previous}"],
-          [
-            "instructions",
-            [
-              "1. Read the HTML at preview_artifact_path and apply only the fixes needed to clear the blocking findings.",
-              `2. Overwrite ${previewPath} with the corrected HTML (full file rewrite, still self-contained).`,
-              "3. Preserve DESIGN.md alignment and previously approved decisions.",
-              "4. Explain each forced change and how it resolves a specific blocking finding.",
-              "5. If a blocker cannot be resolved with available context, state the remaining risk plainly and propose a follow-up.",
-            ].join("\n"),
-          ],
-          [
-            "output_format",
-            "Markdown with sections: Corrected final design (path) | Forced fixes applied (table: finding → fix) | Remaining risk.",
-          ],
-        ]),
-        previous: { name: "final-design", text: latestDesign },
-        ...designModelConfig,
-      });
-      latestDesign = forcedFix.text;
-    }
+          "Return markdown with headings (NOT the HTML):",
+          "1. Spec written to (absolute path)",
+          "2. Sections included",
+          "3. How to open the spec (playwright-cli command + manual fallback path)",
+          "4. Recommended files and components",
+          "5. Implementation steps",
+          "6. Usage example",
+          "7. Accessibility / responsive checklist",
+          "8. Validation commands",
+          "9. Known limitations",
+        ].join("\n"),
+      ],
+    ]),
+    previous: { name: "final-design", text: latestDesign },
+    ...designModelConfig,
+  });
 
-  const handoff = await designContext.task("exporter", {
+  await designContext
+    .task("final-display", {
       prompt: taggedPrompt([
-        [
-          "role",
-          "You are an opinionated staff design engineer.",
-        ],
+        ["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.`,
+          "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.",
         ],
-        ["design_system", designSystem],
-        ["preview_artifact_path", previewPath],
-        ["spec_artifact_path", specPath],
-        ["final_design_summary", "{previous}"],
+        ["spec_path", specPath],
+        ["spec_file_url", specFileUrl],
+        ["preview_path", previewPath],
+        ["preview_file_url", previewFileUrl],
+        ["browser_use_guidelines", browserBootstrapRules],
         [
           "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).",
+            "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.",
           ].join("\n"),
         ],
-        ["html_rules", HTML_PREVIEW_RULES],
-        ["anti_design_slop_rules", ANTI_SLOP_RULES],
         [
           "output_format",
-          [
-            "Return markdown with headings (NOT the HTML):",
-            "1. Spec written to (absolute path)",
-            "2. Sections included",
-            "3. How to open the spec (playwright-cli command + manual fallback path)",
-            "4. Recommended files and components",
-            "5. Implementation steps",
-            "6. Usage example",
-            "7. Accessibility / responsive checklist",
-            "8. Validation commands",
-            "9. Known limitations",
-          ].join("\n"),
+          "Markdown with: `display_method` | `spec_path` | `preview_path` | `manual_open_instructions` | `next_action_hint` (how to re-run the workflow for further changes).",
         ],
       ]),
-      previous: { name: "final-design", text: latestDesign },
       ...designModelConfig,
-    });
-
-    // Final display attempt: open the spec.html for the user (or surface its path).
-    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. 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],
-          [
-            "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.`,
-              "3. Then run `playwright-cli snapshot` and, for interactive review, `playwright-cli show --annotate` so the user can capture any final notes.",
-              `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.",
-            ].join("\n"),
-          ],
-          [
-            "output_format",
-            "Markdown with: `display_method` | `spec_path` | `preview_path` | `annotated_snapshot` (if any) | `user_notes` (if any) | `manual_open_instructions`.",
-          ],
-        ]),
-        ...designModelConfig,
-      })
-      .catch(() => undefined);
-
+    })
+    .catch(() => undefined);
 
   return { latestDesign, handoff };
 }