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

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

@@ -0,0 +1,272 @@
+/**
+ * open-claude-design setup helpers.
+ *
+ * Capabilities that delegate to the accessible `impeccable` skill
+ * (`/skill:impeccable …`), factored into this module so the runner and phases
+ * files stay under the 500-line file-length gate:
+ *
+ *   1. Discovery + init front door: one `discovery` stage runs
+ *      `/skill:impeccable shape` and `/skill:impeccable init`, interviews the
+ *      user for the design brief/output type/references, then lets impeccable
+ *      detect/create/reconcile PRODUCT.md and DESIGN.md in the same stage.
+ *   2. Reference discovery: browse five curated galleries (Awwwards,
+ *      recent.design, Dribbble, Monet, Motionsites) and synthesize a references
+ *      brief the generator heavily emulates.
+ *   3. Live interactive QA prompt: drive `/skill:impeccable live` against the
+ *      static preview.html so the user picks elements, annotates, and accepts
+ *      on-brand variants in the browser. cross-ref: impeccable `reference/live.md`.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { WorkflowTaskResult } from "../src/shared/types.js";
+import {
+  OUTPUT_TYPES,
+  discoveryDecisionFromResult,
+  taggedPrompt,
+  type DiscoveryDecision,
+} from "./open-claude-design-utils.js";
+
+type SetupModelConfig = Record<string, object | string | readonly string[]>;
+type SetupDesignContext = {
+  task(name: string, options: object): Promise<WorkflowTaskResult>;
+};
+
+// ---------------------------------------------------------------------------
+// 0. Discovery + init front door (one workflow stage)
+// ---------------------------------------------------------------------------
+
+export type ProjectDesignContextResult = {
+  readonly summary: string;
+};
+
+export function renderDiscoveryContext(discovery: DiscoveryDecision): string {
+  return [
+    `Confirmed design brief: ${discovery.brief}`,
+    `Output type: ${discovery.output_type}`,
+    discovery.references.length > 0
+      ? `References to emulate (take precedence over DESIGN.md/PRODUCT.md): ${discovery.references.join(", ")}`
+      : "References to emulate: none provided.",
+  ].join("\n");
+}
+
+function buildDiscoveryInitPrompt(prompt: string): string {
+  const outputTypes = OUTPUT_TYPES.join(", ");
+  return `/skill:impeccable shape
+/skill:impeccable init
+
+${taggedPrompt([
+    [
+      "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.`,
+    ],
+    [
+      "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.",
+      ].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.",
+      ].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.`,
+    ],
+  ])}`;
+}
+
+export async function runDiscoveryAndInit(args: {
+  readonly designContext: SetupDesignContext;
+  readonly prompt: string;
+  readonly discoveryConfig: SetupModelConfig;
+}): Promise<{
+  readonly discovery: DiscoveryDecision;
+  readonly discoveryContext: string;
+  readonly projectContext: ProjectDesignContextResult;
+}> {
+  const result = await args.designContext.task("discovery", {
+    prompt: buildDiscoveryInitPrompt(args.prompt),
+    ...args.discoveryConfig,
+  });
+  const discovery = discoveryDecisionFromResult(result, args.prompt);
+  return {
+    discovery,
+    discoveryContext: renderDiscoveryContext(discovery),
+    projectContext: {
+      summary: [
+        "Ran `/skill:impeccable shape` + `/skill:impeccable init` in the combined discovery stage.",
+        (result.text ?? "").trim(),
+      ].filter((part) => part.length > 0).join("\n\n"),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 1. Reference discovery
+// ---------------------------------------------------------------------------
+
+/** Curated galleries of beautiful, current reference designs. */
+export const REFERENCE_DESIGN_SITES: readonly { readonly name: string; readonly url: string }[] = [
+  { name: "Awwwards", url: "https://www.awwwards.com/websites/" },
+  { name: "recent.design", url: "https://recent.design/" },
+  { name: "Dribbble (recent shots)", url: "https://dribbble.com/shots/recent" },
+  { name: "Monet", url: "https://www.monet.design/c" },
+  { name: "Motionsites", url: "https://motionsites.ai/" },
+];
+
+export const NO_REFERENCES_BRIEF =
+  "Reference discovery was skipped. Generate from the project design system and the prompt; do not fabricate external references.";
+
+export function buildReferenceDiscoveryPrompt(args: {
+  readonly prompt: string;
+  readonly outputType: string;
+  readonly designContextHint: string;
+  readonly artifactDir: string;
+  readonly browserBootstrapRules: string;
+}): string {
+  const siteList = REFERENCE_DESIGN_SITES.map(
+    (site, index) => `${index + 1}. ${site.name} — ${site.url}`,
+  ).join("\n");
+  return taggedPrompt([
+    [
+      "role",
+      "You are an opinionated staff design engineer and design researcher curating best-in-class, current 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.`,
+    ],
+    ["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.",
+      ].join("\n"),
+    ],
+    [
+      "output_format",
+      [
+        "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).",
+      ].join("\n"),
+    ],
+  ]);
+}
+
+/** Persist the curated references brief to `<artifactDir>/references.md`. Best-effort. */
+export function persistReferencesBrief(artifactDir: string, brief: string): void {
+  try {
+    mkdirSync(artifactDir, { recursive: true });
+    writeFileSync(join(artifactDir, "references.md"), `${brief}\n`);
+  } catch {
+    /* best-effort durability; never block the workflow */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Live interactive QA prompt (user-feedback display/review stages)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the interactive-QA prompt for the `user-feedback-*` stages. Drives
+ * `/skill:impeccable live` against the static preview so the user can pick
+ * elements in the browser, annotate, and accept on-brand variants; degrades to
+ * `playwright-cli show --annotate` and finally to a manual file path. The output
+ * labels (`user_notes`, `annotated_snapshot`, `live_changes`) are parsed by the
+ * generate/user-feedback loop.
+ */
+export function buildLivePreviewDisplayPrompt(args: {
+  readonly previewPath: string;
+  readonly previewFileUrl: string;
+  readonly browserBootstrapRules: string;
+  readonly iteration?: number;
+  readonly maxRefinements?: number;
+  readonly final?: boolean;
+}): string {
+  const isInitial = args.iteration === undefined;
+  const isFinal = args.final === true;
+  const label = isInitial
+    ? "the just-generated HTML artifact"
+    : `the revised preview after iteration ${args.iteration}/${args.maxRefinements}`;
+  const objective = isFinal
+    ? `Show the user ${label} as the FINAL refinement pass and let them review it in the browser. This is the last automated iteration, so do NOT solicit change requests this run cannot apply — if the user wants further changes, tell them to re-run \`/workflow open-claude-design\`. Drive \`/skill:impeccable live\` for viewing/QA when possible; degrade gracefully.`
+    : `Make ${label} visible to the user, run an interactive design-QA session against it, then capture the user's feedback for the refinement loop. Drive \`/skill:impeccable live\` against the static preview when possible; degrade gracefully when browser automation is unavailable.`;
+  const interactiveQa = isFinal
+    ? [
+        `1. Open the preview for a final review: run \`/skill:impeccable live\` (or \`playwright-cli open ${args.previewFileUrl}\`) so the user can inspect ${label} in the browser.`,
+        "2. Make clear this is the final automated refinement pass. Do NOT promise to apply further annotations; instead, tell the user exactly how to re-run the workflow to iterate again.",
+      ].join("\n")
+    : [
+        `1. Run \`/skill:impeccable live\` targeted at the preview file so the user can pick elements in the browser, annotate them, and compare on-brand variants. The preview is a single static HTML file at ${args.previewPath}; point live at it (configure \`.impeccable/live/config.json\` for that file or pass \`--target ${args.previewPath}\` per the live reference) and open ${args.previewFileUrl} in the browser.`,
+        "2. For each element the user picks, follow the live contract: read any annotation screenshot, extract the page identity FIRST, then generate three DISTINCT on-brand variants and let the user accept one. Accepted variants are written into the preview HTML in place; do NOT branch the artifact.",
+        "3. Also handle the live `steer` path for page-level direction the user types/speaks, and treat any freeform prompt as the ceiling on direction.",
+        "4. Keep iterating until the user signals they are done with this round.",
+      ].join("\n");
+  const outputFormat = isFinal
+    ? [
+        "Markdown with: `display_method` (live | playwright-annotate | manual), `preview_path`, and `next_action_hint` (how to re-run the workflow for further changes).",
+        "Do NOT collect `user_notes` or `live_changes`: this final pass cannot apply them, so don't invite feedback that would go nowhere.",
+      ].join("\n")
+    : [
+        "Markdown with these exact labels so the refinement loop can parse the captured feedback:",
+        "`display_method` (live | playwright-annotate | manual)",
+        "`preview_path`",
+        "`live_changes` (summary of every element/variant the user ACCEPTED in the live session; `none` when no live edits were made)",
+        "`annotated_snapshot` (path to any annotated screenshot, if captured)",
+        "`user_notes` (the user's verbatim notes/annotations for the next iteration; `none` when the user gave no notes)",
+        "`next_action_hint`",
+      ].join("\n");
+  return taggedPrompt([
+    [
+      "role",
+      "You are an opinionated staff design engineer running interactive `live` QA so the user can iterate on the design 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.",
+      ].join("\n"),
+    ],
+    ["output_format", outputFormat],
+  ]);
+}

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

@@ -18,15 +18,6 @@ export type OutputType = (typeof OUTPUT_TYPES)[number];
 export const DEFAULT_OUTPUT_TYPE: OutputType = "prototype";
 export const DEFAULT_MAX_REFINEMENTS = 3;
 
-/**
- * Read-only builtin tools granted to the structured-decision stages
- * (user-feedback refinement gate and pre-export gate) so they can actually
- * inspect the on-disk `preview.html` before emitting their decision. The
- * artifact stays immutable here — writes/edits belong to apply-changes and
- * forced-fix, so this list deliberately excludes write/edit/bash.
- */
-export const READ_ONLY_TOOLS = ["read", "grep", "ls"] as const;
-
 type PromptSection = readonly [tag: string, content: string];
 
 export function taggedPrompt(sections: readonly PromptSection[]): string {
@@ -60,69 +51,59 @@ export function isFileLike(value: string): boolean {
   return trimmed.length > 0 && !isUrl(trimmed);
 }
 
-export type RefinementDecision = {
-  readonly ready_for_export: boolean;
-  readonly rationale: string;
-  readonly required_changes: readonly string[];
-};
-
-export type ExportGateFinding = {
-  readonly finding: string;
-  readonly evidence: string;
-  readonly why_blocking: string;
-  readonly must_fix_action: string;
-  readonly severity: "P0";
-};
+/**
+ * Whether the browser-centric workflow should exit early instead of generating
+ * artifacts no one can review interactively. True only when the playwright-cli
+ * browser is unavailable AND we are not under the test harness (`NODE_ENV=test`,
+ * which always skips the global install and runs headlessly to completion).
+ */
+export function shouldEarlyExitForBrowser(
+  browserAvailable: boolean,
+  nodeEnv: string | undefined,
+): boolean {
+  return !browserAvailable && nodeEnv !== "test";
+}
 
-export type ExportGateDecision = {
-  readonly has_blocking_findings: boolean;
-  readonly rationale: string;
-  readonly blocking_findings: readonly ExportGateFinding[];
+export type DiscoveryDecision = {
+  readonly brief: string;
+  readonly output_type: OutputType;
+  readonly references: readonly string[];
 };
 
-export const refinementDecisionSchema = Type.Object(
-  {
-    ready_for_export: Type.Boolean(),
-    rationale: Type.String(),
-    required_changes: Type.Array(Type.String()),
-  },
-  { additionalProperties: false },
-);
-
-const exportGateFindingSchema = Type.Object(
+export const discoveryDecisionSchema = Type.Object(
   {
-    finding: Type.String(),
-    evidence: Type.String(),
-    why_blocking: Type.String(),
-    must_fix_action: Type.String(),
-    severity: Type.Literal("P0"),
+    brief: Type.String(),
+    output_type: Type.Union([...OUTPUT_TYPES].map((value) => Type.Literal(value))),
+    references: Type.Array(Type.String()),
   },
   { additionalProperties: false },
 );
 
-export const exportGateDecisionSchema = Type.Object(
-  {
-    has_blocking_findings: Type.Boolean(),
-    rationale: Type.String(),
-    blocking_findings: Type.Array(exportGateFindingSchema),
-  },
-  { additionalProperties: false },
-);
-
-export function refinementDecisionFromResult(result: WorkflowTaskResult): RefinementDecision {
-  const decision = result.structured as RefinementDecision | undefined;
-  if (!decision) {
-    throw new Error("open-claude-design refinement decision missing structured result.");
-  }
-  return decision;
-}
-
-export function exportGateDecisionFromResult(result: WorkflowTaskResult): ExportGateDecision {
-  const decision = result.structured as ExportGateDecision | undefined;
-  if (!decision) {
-    throw new Error("open-claude-design export gate decision missing structured result.");
-  }
-  return decision;
+/**
+ * Parse the discovery stage's structured result, tolerating a missing/invalid
+ * structured payload (headless / mock runs) by falling back to the raw prompt as
+ * the brief, the default output type, and an empty reference list.
+ */
+export function discoveryDecisionFromResult(
+  result: WorkflowTaskResult,
+  fallbackBrief: string,
+): DiscoveryDecision {
+  const decision = result.structured as Partial<DiscoveryDecision> | undefined;
+  const brief =
+    typeof decision?.brief === "string" && decision.brief.trim().length > 0
+      ? decision.brief.trim()
+      : fallbackBrief;
+  const references = Array.isArray(decision?.references)
+    ? decision.references
+        .filter((ref): ref is string => typeof ref === "string")
+        .map((ref) => ref.trim())
+        .filter((ref) => ref.length > 0)
+    : [];
+  return {
+    brief,
+    output_type: normalizeOutputType(decision?.output_type),
+    references,
+  };
 }
 
 export function joinResults(results: readonly WorkflowTaskResult[]): string {
@@ -144,10 +125,15 @@ export function prepareArtifactDir(cwd = process.cwd()): {
   readonly specPath: string;
 } {
   const runId = `${new Date().toISOString().replace(/[:.]/g, "-")}-${Math.random().toString(36).slice(2, 8)}`;
-  const candidates = [
-    join(cwd, "specs", "design", runId),
-    join(tmpdir(), "open-claude-design", runId),
-  ];
+  // Under automated tests, prefer the OS tmpdir so a full `d.run()` does not
+  // pollute the project's `specs/design/` tree with per-run artifact folders.
+  const candidates =
+    process.env.NODE_ENV === "test"
+      ? [join(tmpdir(), "open-claude-design", runId)]
+      : [
+          join(cwd, "specs", "design", runId),
+          join(tmpdir(), "open-claude-design", runId),
+        ];
   for (const candidate of candidates) {
     try {
       mkdirSync(candidate, { recursive: true });
@@ -187,6 +173,10 @@ export const ANTI_SLOP_RULES = [
   "Commit to a specific aesthetic direction; do not hedge with 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.";
+
 export type PlaywrightCliStatus = {
   /** Whether the `playwright-cli` command is expected to be available to downstream stages. */
   readonly available: boolean;

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

@@ -1,20 +1,16 @@
-import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+import type { WorkflowDefinition, WorkflowOutputValues } from "../src/authoring.js";
 
 export type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "component" | "theme" | "tokens";
 
-export type OpenClaudeDesignWorkflowInputs = WorkflowInputValues & {
+export type OpenClaudeDesignWorkflowInputs = {
   readonly prompt: string;
-  readonly reference?: string;
-  readonly output_type: OpenClaudeDesignOutputType;
-  readonly design_system?: string;
+  readonly discover_references: boolean;
   readonly max_refinements: number;
 };
 
-export type OpenClaudeDesignWorkflowRunInputs = WorkflowInputValues & {
+export type OpenClaudeDesignWorkflowRunInputs = {
   readonly prompt: string;
-  readonly reference?: string;
-  readonly output_type?: OpenClaudeDesignOutputType;
-  readonly design_system?: string;
+  readonly discover_references?: boolean;
   readonly max_refinements?: number;
 };
 

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

@@ -2,22 +2,18 @@
  * Builtin workflow: open-claude-design
  *
  * Adapts Atomic SDK's Claude Design workflow to the local workflow SDK:
- * design-system onboarding, reference import, generation, bounded refinement,
- * enforcement, and export/handoff all run through ctx.task()/ctx.parallel().
+ * combined discovery/init, design-system/reference research, generation, bounded
+ * refinement, export, and final display run through ctx.task()/ctx.parallel().
  *
  * Every stage prompt invokes the specific impeccable sub-skill that maps to
  * its role (see https://github.com/pbakaus/impeccable/tree/main/site/content/skills):
  *
  *   onboarding     → impeccable `document` / `extract` / `audit`
  *   import         → impeccable `extract`
- *   generator      → impeccable `craft` (HTML preview)
- *   user-feedback  → impeccable `critique` (against the live HTML preview)
- *   critique-N     → impeccable `critique`
- *   screenshot-N   → impeccable `audit` + `live`
- *   apply-changes  → impeccable `polish`
- *   pre-export     → impeccable `audit`
- *   forced-fix     → impeccable `harden`
+ *   generate-N     → impeccable `craft` / `polish` (HTML preview)
+ *   user-feedback  → impeccable `live` (browser review + user notes)
  *   exporter       → impeccable `document` (rich HTML spec)
+ *   final-display  → opens/surfaces the exported HTML spec
  */
 
 import { Type } from "typebox";
@@ -25,39 +21,31 @@ import { workflow } from "../src/authoring/workflow.js";
 import { runOpenClaudeDesignWorkflow } from "./open-claude-design-runner.js";
 import {
   DEFAULT_MAX_REFINEMENTS,
-  DEFAULT_OUTPUT_TYPE,
-  OUTPUT_TYPES,
 } from "./open-claude-design-utils.js";
 
 export default workflow({
   name: "open-claude-design",
-  description: "AI-powered design workflow: design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Each stage delegates to a specific impeccable sub-skill; the user can iteratively review the generated HTML through the playwright-cli skill.",
+  description: "AI-powered design workflow: combined discovery/init → design-system/reference research → curated reference discovery → HTML generation → live-driven refinement → rich HTML handoff. The discovery stage asks what to build, the output type, and which references to emulate, then runs impeccable init for PRODUCT.md/DESIGN.md (references take precedence over project context). The user iteratively reviews the generated HTML.",
   inputs: {
     prompt: Type.String({
-      description: "What to design (for example, a dashboard, page, component, or prototype).",
+      description: "What to design (for example, a dashboard, page, component, or prototype). The discovery stage refines this into a confirmed brief and asks for the output type and references.",
     }),
-    reference: Type.Optional(Type.String({
-      description: "URL, file path, screenshot path, or design doc to import as a reference.",
-    })),
-    output_type: Type.Union(
-      [...OUTPUT_TYPES].map((value) => Type.Literal(value)),
-      { default: DEFAULT_OUTPUT_TYPE, description: "Kind of design artifact to produce." },
-    ),
-    design_system: Type.Optional(Type.String({
+    discover_references: Type.Boolean({
+      default: true,
       description:
-        "Path(s) or description of an existing design system (DESIGN.md, PRODUCT.md, etc.); skips onboarding when provided.",
-    })),
+        "Discover beautiful, current reference designs from notable design websites (Awwwards, recent.design, Dribbble, Monet, Motionsites) and feed them to generation. Set false to skip the network/browser reference pass.",
+    }),
     max_refinements: Type.Number({
       default: DEFAULT_MAX_REFINEMENTS,
-      description: `Maximum critique/apply refinement iterations (default ${DEFAULT_MAX_REFINEMENTS}).`,
+      description: `Maximum generate/user-feedback loop iterations (default ${DEFAULT_MAX_REFINEMENTS}).`,
     }),
   },
   outputs: {
     output_type: Type.Optional(Type.String({ description: "Kind of design artifact produced." })),
-    design_system: Type.Optional(Type.String({ description: "Design system source used for generation: supplied input or project-derived design system." })),
+    design_system: Type.Optional(Type.String({ description: "Design system source used for generation: the project-derived design system." })),
     artifact: Type.Optional(Type.String({ description: "Latest final design summary from the approved preview artifact." })),
     handoff: Type.Optional(Type.String({ description: "Final rich HTML spec and implementation handoff summary." })),
-    approved_for_export: Type.Optional(Type.Boolean({ description: "Whether refinement completed before the final export gate." })),
+    approved_for_export: Type.Optional(Type.Boolean({ description: "Whether refinement completed before export." })),
     refinements_completed: Type.Optional(Type.Number({ description: "Number of refinement iterations completed." })),
     import_context: Type.Optional(Type.String({ description: "Reference-import context used during generation." })),
     run_id: Type.Optional(Type.String({ description: "Per-run design workflow artifact identifier." })),

package/dist/builtin/workflows/builtin/prompt-refinement.ts

@@ -0,0 +1,102 @@
+/**
+ * Shared prompt-refinement stage used by the ralph and goal workflows.
+ *
+ * Before the main work loop begins, both workflows run this single
+ * `prompt-refinement` stage. It invokes the prompt-engineer skill
+ * (`/skill:prompt-engineer`) to sharpen the raw user request into a clearer,
+ * more actionable objective using the Workflow Best Practices prompt anatomy
+ * documented in `packages/coding-agent/docs/workflows.md`. The refined request
+ * replaces the original as the operative objective downstream; the original is
+ * preserved by each workflow for reporting.
+ */
+
+import type { WorkflowModelValue, WorkflowTaskOptions, WorkflowTaskResult } from "../src/shared/types.js";
+
+export type PromptSection = readonly [tag: string, content: string];
+
+/**
+ * Clarity rubric mirrored from the "## Workflow Best Practices" section of
+ * `docs/workflows.md` (the user-facing docs under packages/coding-agent/docs).
+ * The refinement stage makes each element explicit where it can be reasonably
+ * inferred from the raw request.
+ */
+export const PROMPT_REFINEMENT_CRITERIA = [
+  "Apply the workflow best practices documented in the `## Workflow Best Practices` section of `docs/workflows.md`. Treat that section as the authoritative prompt-anatomy rubric: use its Objective, Context, Scope, Non-goals, Done criteria, Validation command, Reporting requirements, and Stop conditions when refining the request.",
+  "Objective — state what should be true when the work is complete.",
+  "Context — note why it matters and where the relevant code or area likely lives.",
+  "Scope — state what is allowed to change (the smallest correct change).",
+  "Non-goals — state what to avoid (unrelated refactors, redesigns, or behavior changes outside this case).",
+  "Done criteria — list verifiable completion signals: new behavior works, existing behavior is unchanged, and the validation command passes.",
+  "Validation command — name the targeted check that proves the result.",
+  "Reporting requirements — changed files, validation results, and remaining risks must be reported.",
+  "Stop conditions — name the cases where the agent should stop and ask first (public API, security, data migration, etc.).",
+].join("\n");
+
+/**
+ * Build the prompt sent to the prompt-refinement stage. The refined request is
+ * returned verbatim (no fences or preamble) so it can replace the original
+ * request as the operative objective for the rest of the workflow.
+ */
+export function renderPromptRefinementPrompt(args: {
+  readonly request: string;
+  readonly workflowLabel: string;
+  readonly workflowCwdContext?: PromptSection;
+}): string {
+  const sections: readonly string[] = [
+    `/skill:prompt-engineer Refine the following user request into a clearer, more actionable objective for the ${args.workflowLabel} workflow. Improve clarity and completeness using the rubric below without changing the user's intent, expanding scope, or inventing requirements that cannot be reasonably inferred from the request.`,
+    `<original_request>\n${args.request}\n</original_request>`,
+    `<clarity_rubric>\nApply the Workflow Best Practices prompt anatomy. Make each of the following explicit where it can be reasonably inferred from the original request:\n${PROMPT_REFINEMENT_CRITERIA}\n</clarity_rubric>`,
+    [
+      "<refinement_rules>",
+      "- Preserve the user's original intent and scope; do not add unrelated work.",
+      "- If the original request is already clear and complete, return it essentially unchanged with only clarity improvements.",
+      "- Where a criterion cannot be reasonably inferred, state it as a concise assumption or a 'to confirm' note rather than fabricating specifics.",
+      "- Do not implement anything, run commands, or edit files. This stage only produces the refined request text.",
+      "</refinement_rules>",
+    ].join("\n"),
+    `<output_format>\nReturn ONLY the refined request. No preamble, no explanation, and no Markdown fences. The returned text replaces the original request as the operative objective for the rest of the workflow, so it must be a single self-contained request.\n</output_format>`,
+  ];
+  const tail = args.workflowCwdContext === undefined
+    ? []
+    : [`<${args.workflowCwdContext[0]}>\n${args.workflowCwdContext[1].trim()}\n</${args.workflowCwdContext[0]}>`];
+  return [...sections, ...tail].join("\n\n");
+}
+
+/** Minimal context surface required to run a tracked refinement stage. */
+type PromptRefinementContext = {
+  task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
+};
+
+/** Model-chain + tool gating forwarded to the refinement stage session. */
+export type PromptRefinementModelConfig = {
+  readonly model?: WorkflowModelValue;
+  readonly fallbackModels?: readonly string[];
+  readonly noTools?: "all" | "builtin";
+  readonly excludedTools?: readonly string[];
+  readonly tools?: readonly string[];
+};
+
+/**
+ * Run the shared `prompt-refinement` stage once and return the refined request.
+ * Falls back to the original request when the stage produces no usable text.
+ */
+export async function runPromptRefinementStage(
+  ctx: PromptRefinementContext,
+  options: {
+    readonly request: string;
+    readonly workflowLabel: string;
+    readonly workflowCwdContext?: PromptSection;
+    readonly modelConfig: PromptRefinementModelConfig;
+  },
+): Promise<string> {
+  const result = await ctx.task("prompt-refinement", {
+    prompt: renderPromptRefinementPrompt({
+      request: options.request,
+      workflowLabel: options.workflowLabel,
+      ...(options.workflowCwdContext === undefined ? {} : { workflowCwdContext: options.workflowCwdContext }),
+    }),
+    ...options.modelConfig,
+  });
+  const refined = (result.text ?? "").trim();
+  return refined.length > 0 ? refined : options.request;
+}