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

package/dist/builtin/workflows/builtin/index.d.ts

@@ -1,113 +1,21 @@
-import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+import type { WorkflowDefinition, WorkflowOutputValues } from "../src/authoring.js";
 
-export type DeepResearchCodebaseWorkflowInputs = WorkflowInputValues & {
-  readonly prompt: string;
-  readonly max_partitions: number;
-  readonly max_concurrency: number;
-};
-export type DeepResearchCodebaseWorkflowRunInputs = WorkflowInputValues & {
-  readonly prompt: string;
-  readonly max_partitions?: number;
-  readonly max_concurrency?: number;
-};
-export type DeepResearchCodebaseWorkflowOutputs = WorkflowOutputValues & {
-  readonly result?: string;
-  readonly findings?: string;
-  readonly research_doc_path?: string;
-  readonly artifact_dir?: string;
-  readonly manifest_path?: string;
-  readonly partitions?: string[];
-  readonly explorer_count?: number;
-  readonly specialist_count?: number;
-  readonly max_concurrency?: number;
-  readonly history?: string;
-};
-export type DeepResearchCodebaseWorkflowDefinition = WorkflowDefinition<
-  DeepResearchCodebaseWorkflowInputs,
-  DeepResearchCodebaseWorkflowOutputs,
-  DeepResearchCodebaseWorkflowRunInputs
->;
-
-export type GoalWorkflowStatus = "active" | "complete" | "blocked" | "needs_human";
-export type GoalWorkflowReceipt = {
-  readonly turn: number;
-  readonly stage: string;
-  readonly artifact_path: string;
-  readonly summary: string;
-};
-export type GoalWorkflowInputs = WorkflowInputValues & {
-  readonly objective: string;
-  readonly acceptance_criteria?: string;
-  readonly max_turns: number;
-  readonly base_branch: string;
-  readonly git_worktree_dir: string;
-  readonly create_pr: boolean;
-};
-export type GoalWorkflowRunInputs = WorkflowInputValues & {
-  readonly objective: string;
-  readonly acceptance_criteria?: string;
-  readonly max_turns?: number;
-  readonly base_branch?: string;
-  readonly git_worktree_dir?: string;
-  readonly create_pr?: boolean;
-};
-export type GoalWorkflowOutputs = WorkflowOutputValues & {
-  readonly result?: string;
-  readonly status?: GoalWorkflowStatus;
-  readonly approved?: boolean;
-  readonly goal_id?: string;
-  readonly objective?: string;
-  readonly acceptance_criteria?: string;
-  readonly ledger_path?: string;
-  readonly turns_completed?: number;
-  readonly iterations_completed?: number;
-  readonly receipts?: GoalWorkflowReceipt[];
-  readonly remaining_work?: string;
-  readonly review_report?: string;
-  readonly review_report_path?: string;
-  readonly pr_report?: string;
-};
-export type GoalWorkflowDefinition = WorkflowDefinition<
-  GoalWorkflowInputs,
-  GoalWorkflowOutputs,
-  GoalWorkflowRunInputs
->;
-
-export type RalphWorkflowInputs = WorkflowInputValues & {
-  readonly prompt: string;
-  readonly acceptance_criteria?: string;
-  readonly max_loops: number;
-  readonly base_branch: string;
-  readonly git_worktree_dir: string;
-  readonly create_pr: boolean;
-};
-export type RalphWorkflowRunInputs = WorkflowInputValues & {
-  readonly prompt: string;
-  readonly acceptance_criteria?: string;
-  readonly max_loops?: number;
-  readonly base_branch?: string;
-  readonly git_worktree_dir?: string;
-  readonly create_pr?: boolean;
-};
-export type RalphWorkflowOutputs = WorkflowOutputValues & {
-  readonly result?: string;
-  readonly plan?: string;
-  readonly plan_path?: string;
-  readonly research?: string;
-  readonly research_path?: string;
-  readonly implementation_notes_path?: string;
-  readonly qa_video_path?: string;
-  readonly pr_report?: string;
-  readonly approved?: boolean;
-  readonly iterations_completed?: number;
-  readonly review_report?: string;
-  readonly review_report_path?: string;
-};
-export type RalphWorkflowDefinition = WorkflowDefinition<
-  RalphWorkflowInputs,
-  RalphWorkflowOutputs,
-  RalphWorkflowRunInputs
->;
+export {
+  default as goal,
+  type GoalWorkflowDefinition,
+  type GoalWorkflowInputs,
+  type GoalWorkflowOutputs,
+  type GoalWorkflowReceipt,
+  type GoalWorkflowRunInputs,
+  type GoalWorkflowStatus,
+} from "./goal.js";
+export {
+  default as ralph,
+  type RalphWorkflowDefinition,
+  type RalphWorkflowInputs,
+  type RalphWorkflowOutputs,
+  type RalphWorkflowRunInputs,
+} from "./ralph.js";
 
 export type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "component" | "theme" | "tokens";
 export type OpenClaudeDesignWorkflowInputs = {
@@ -186,7 +94,4 @@ export {
   type TournamentWorkflowRunInputs,
 } from "./tournament.js";
 
-export declare const deepResearchCodebase: DeepResearchCodebaseWorkflowDefinition;
-export declare const goal: GoalWorkflowDefinition;
-export declare const ralph: RalphWorkflowDefinition;
 export declare const openClaudeDesign: OpenClaudeDesignWorkflowDefinition;

package/dist/builtin/workflows/builtin/index.ts

@@ -7,11 +7,10 @@
 
 export { default as adversarialVerification } from "./adversarial-verification.js";
 export { default as classifyAndAct } from "./classify-and-act.js";
-export { default as deepResearchCodebase } from "./deep-research-codebase.js";
 export { default as fanOutAndSynthesize } from "./fan-out-and-synthesize.js";
 export { default as generateAndFilter } from "./generate-and-filter.js";
 export { default as goal } from "./goal.js";
-export { default as ralph } from "./ralph.js";
 export { default as openClaudeDesign } from "./open-claude-design.js";
 export { default as loopUntilDone } from "./loop-until-done.js";
+export { default as ralph } from "./ralph.js";
 export { default as tournament } from "./tournament.js";

package/dist/builtin/workflows/builtin/loop-until-done-prompts.ts

@@ -1,5 +1,8 @@
 type PromptSection = readonly [tag: string, content: string];
 
+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 READABLE_REPORT = "Lead with the outcome. Keep facts, decisions, caveats, and next steps; drop background and repetition. Use complete, readable sentences rather than compressed fragments.";
+
 function taggedPrompt(sections: readonly PromptSection[]): string {
   return sections
     .map(([tag, content]) => `<${tag}>\n${content.trim()}\n</${tag}>`)
@@ -13,19 +16,21 @@ export function renderIterationPrompt(options: {
   readonly ledgerPath: string;
 }): string {
   return taggedPrompt([
+    ["progress_ledger", `Read ${options.ledgerPath} first. It is the durable source of truth for attempted work, findings, failures, validation evidence, and remaining work.`],
     ["role", "You are the active worker in a bounded evidence-driven completion loop."],
-    ["objective", options.task],
     ["iteration", `${options.iteration} of ${options.maxIterations}`],
-    ["progress_ledger", `Read ${options.ledgerPath} first. It is the durable source of truth for attempted work, findings, failures, validation evidence, and remaining work.`],
+    ["success_criteria", "This iteration makes measurable progress or supplies decisive evidence that the explicit objective is complete."],
     ["requirements", [
       "Select the highest-value unfinished item supported by the ledger and current state.",
       "Perform concrete work; do not merely restate the objective or ledger.",
       "Avoid repeating failed approaches unless new evidence justifies the retry.",
       "Run the strongest practical validation for the work completed in this iteration.",
       "Report exactly what changed, evidence gathered, failures encountered, and what remains.",
+      GROUNDED_REPORTING,
     ].join("\n")],
-    ["success_criteria", "This iteration makes measurable progress or supplies decisive evidence that the explicit objective is complete."],
-    ["output_format", "Markdown with Work performed, Changes, Validation evidence, New findings, Failures, and Remaining work."],
+    ["stop_rules", "End this iteration after delivering measurable progress, or after evidence shows the objective is complete."],
+    ["output_format", `Markdown with Work performed, Changes, Validation evidence, New findings, Failures, and Remaining work. ${READABLE_REPORT}`],
+    ["objective", options.task],
   ]);
 }
 
@@ -36,25 +41,26 @@ export function renderEvaluationPrompt(options: {
   readonly iterationPath: string;
 }): string {
   return taggedPrompt([
-    ["role", "You are an independent completion evaluator. Judge evidence, not the worker's confidence."],
-    ["objective", options.task],
     ["artifacts", [
       `Durable progress ledger: ${options.ledgerPath}`,
       `Current iteration artifact: ${options.iterationPath}`,
       "Read both files before deciding.",
     ].join("\n")],
+    ["role", "You are an independent completion evaluator. Judge evidence, not the worker's confidence."],
     ["stop_condition", [
       "Set done=true only when the objective is fully satisfied and current validation evidence proves it.",
       "Set done=false when any required behavior, validation, cleanup, or evidence remains missing or uncertain.",
       "Do not invent requirements beyond the objective.",
     ].join("\n")],
     ["evidence_rules", [
-      "List concrete validation evidence supporting the decision.",
+      "List concrete validation evidence supporting the decision, including commands and observed output; cite file:line where applicable.",
       "Record new findings and failures distinctly.",
       "When incomplete, state actionable remaining work for the next iteration.",
-      "Return the required structured decision.",
+      GROUNDED_REPORTING,
     ].join("\n")],
     ["success_criteria", `The iteration ${options.iteration} decision is reproducible from cited artifact evidence.`],
+    ["output_format", `Return only the required structured decision with done, summary, new_findings, failures, validation_evidence, and remaining_work. ${READABLE_REPORT}`],
+    ["objective", options.task],
   ]);
 }
 
@@ -64,16 +70,18 @@ export function renderCompletionPrompt(options: {
   readonly iterationPath: string;
 }): string {
   return taggedPrompt([
-    ["role", "You are the final completion reporter."],
-    ["objective", options.task],
     ["artifacts", `Read the complete ledger at ${options.ledgerPath} and final iteration artifact at ${options.iterationPath}.`],
+    ["role", "You are the final completion reporter."],
     ["requirements", [
       "Summarize the delivered outcome without adding unsupported claims.",
       "Cite the validation evidence that satisfied the stop condition.",
       "List artifact paths needed to audit the work.",
       "Report residual risks even when no work remains.",
+      GROUNDED_REPORTING,
     ].join("\n")],
-    ["success_criteria", "The final report is concise, evidence-backed, and independently auditable from the ledger."],
-    ["output_format", "Markdown with Outcome, Evidence, Artifacts, Residual risks, and Remaining work (None)."],
+    ["success_criteria", "The final report is evidence-backed and independently auditable from the ledger."],
+    ["stop_rules", "Stop after accounting for the outcome, supporting evidence, audit artifacts, residual risks, and any remaining work."],
+    ["output_format", `Markdown with Outcome, Evidence, Artifacts, Residual risks, and Remaining work (None). ${READABLE_REPORT}`],
+    ["objective", options.task],
   ]);
 }

package/dist/builtin/workflows/builtin/loop-until-done-runner.ts

@@ -158,6 +158,9 @@ export async function runLoopUntilDone(ctx: WorkflowRunContext<LoopInputs>) {
         context: "fresh",
         reads: [ledgerPath, iterationPath],
         output: resultPath,
+        // Keep the completion report out of the caller's context window;
+        // `result_path` below carries it for callers that want the contents.
+        outputMode: "file-only",
       });
       return {
         result: final.text,

package/dist/builtin/workflows/builtin/loop-until-done.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { workflow } from "../src/authoring/workflow.js";
+import { withSteeringPropagationContext } from "./steering-context.js";
 import { runLoopUntilDone } from "./loop-until-done-runner.js";
 
 export default workflow({
@@ -15,7 +16,7 @@ export default workflow({
     }),
   },
   outputs: {
-    result: Type.String({ description: "Evidence-backed completion report or deterministic exhaustion report." }),
+    result: Type.String({ description: "Compact reference to the evidence-backed completion report, or the deterministic exhaustion report; read `result_path` for the full report." }),
     status: Type.Union([Type.Literal("complete"), Type.Literal("failed")], {
       description: "Complete when evidence satisfies the stop condition; failed when max_iterations is exhausted.",
     }),
@@ -27,5 +28,5 @@ export default workflow({
     remaining_work: Type.String({ description: "Actionable remaining work; empty only after proven completion." }),
     artifact_dir: Type.String({ description: "Run-specific directory containing loop artifacts." }),
   },
-  run: async (ctx) => await runLoopUntilDone(ctx),
+  run: async (ctx) => await runLoopUntilDone(withSteeringPropagationContext(ctx)),
 });

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

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