@bastani/atomic 0.9.0-alpha.1 → 0.9.0-alpha.3

package/dist/builtin/workflows/builtin/goal-runner.ts

@@ -1,10 +1,11 @@
 import { join } from "node:path";
-import type { WorkflowTaskResult } from "../src/shared/types.js";
+import type { WorkflowParallelOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "../src/shared/types.js";
 import { reviewDecisionSchema } from "./goal-schemas.js";
 import {
   DEFAULT_BLOCKER_THRESHOLD,
   DEFAULT_MAX_TURNS,
   DEFAULT_REVIEW_QUORUM,
+  type GoalWorkflowInputs,
   type GoalWorkflowOutputs,
   type ReviewRecord,
 } from "./goal-types.js";
@@ -28,6 +29,8 @@ import {
   renderGoalContinuationPrompt,
   renderReviewerPrompt,
 } from "./goal-prompts.js";
+import { promptEngineerModelConfig } from "./ralph-models.js";
+import { runPromptRefinementStage } from "./prompt-refinement.js";
 
 function positiveInteger(value: number | undefined, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
@@ -63,32 +66,25 @@ function normalizeBranchInput(
     );
   return looksLikeSafeGitRef ? trimmed : fallback;
 }
-  type GoalRunnerContext = {
-  readonly inputs: {
-    readonly objective: string;
-    readonly max_turns?: number;
-    readonly base_branch?: string;
-  };
-  task(name: string, options: object): Promise<WorkflowTaskResult>;
-  parallel(
-    steps: readonly object[],
-    options: { readonly task: string; readonly failFast: false },
-  ): Promise<WorkflowTaskResult[]>;
+type GoalRunnerContext = {
+  readonly inputs: GoalWorkflowInputs;
+  task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
+  parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
 };
 
-export async function runGoalWorkflow(ctx: unknown): Promise<GoalWorkflowOutputs> {
-  const goalContext = ctx as GoalRunnerContext;
-    const inputs = goalContext.inputs;
-    const objective = inputs.objective.trim();
-    if (!objective) {
+export async function runGoalWorkflow(ctx: GoalRunnerContext): Promise<GoalWorkflowOutputs> {
+    const inputs = ctx.inputs;
+    const rawObjective = inputs.objective.trim();
+    if (!rawObjective) {
       throw new Error("goal requires an objective input.");
     }
+    const objective = await runPromptRefinementStage(ctx, { request: rawObjective, workflowLabel: "Goal", modelConfig: promptEngineerModelConfig });
 
     const maxTurns = positiveInteger(inputs.max_turns, DEFAULT_MAX_TURNS);
     const reviewQuorum = DEFAULT_REVIEW_QUORUM;
     const blockerThreshold = Math.min(DEFAULT_BLOCKER_THRESHOLD, maxTurns);
     const comparisonBaseBranch = normalizeBranchInput(inputs.base_branch, "origin/main");
-    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective);
+    const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective, rawObjective);
 
     const workerModelConfig = {
       model: "openai-codex/gpt-5.5:medium",
@@ -169,7 +165,7 @@ export async function runGoalWorkflow(ctx: unknown): Promise<GoalWorkflowOutputs
 
       let worker: WorkflowTaskResult;
       try {
-        worker = await goalContext.task(`work-turn-${turn}`, {
+        worker = await ctx.task(`work-turn-${turn}`, {
           prompt: workerPrompt,
           reads: [ledgerPath, ...latestReviewArtifactPaths],
           output: workTurnPath,
@@ -249,7 +245,7 @@ export async function runGoalWorkflow(ctx: unknown): Promise<GoalWorkflowOutputs
 
       let reviewResults: WorkflowTaskResult[];
       try {
-        reviewResults = await goalContext.parallel(reviewerSteps, {
+        reviewResults = await ctx.parallel(reviewerSteps, {
           task: objective,
           failFast: false,
         });
@@ -332,6 +328,7 @@ export async function runGoalWorkflow(ctx: unknown): Promise<GoalWorkflowOutputs
       approved: ledger.status === "complete",
       goal_id: ledger.goal_id,
       objective: ledger.objective,
+      ...(ledger.original_objective === undefined ? {} : { original_objective: ledger.original_objective }),
       ledger_path: ledgerPath,
       turns_completed: ledger.turns,
       iterations_completed: ledger.turns,

package/dist/builtin/workflows/builtin/goal-types.ts

@@ -93,6 +93,7 @@ export type GoalLifecycleEvent = {
 export type GoalLedger = {
   readonly goal_id: string;
   readonly objective: string;
+  readonly original_objective?: string;
   status: GoalStatus;
   turns: number;
   readonly created_at: string;
@@ -122,6 +123,7 @@ export type GoalWorkflowOutputs = {
   readonly approved?: boolean;
   readonly goal_id?: string;
   readonly objective?: string;
+  readonly original_objective?: string;
   readonly ledger_path?: string;
   readonly turns_completed?: number;
   readonly iterations_completed?: number;

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

@@ -27,6 +27,7 @@ export type GoalWorkflowOutputs = WorkflowOutputValues & {
   readonly approved?: boolean;
   readonly goal_id?: string;
   readonly objective?: string;
+  readonly original_objective?: string;
   readonly ledger_path?: string;
   readonly turns_completed?: number;
   readonly iterations_completed?: number;

package/dist/builtin/workflows/builtin/goal.ts

@@ -7,50 +7,46 @@
  */
 
 import { Type } from "typebox";
-import { defineWorkflow } from "../src/workflows/define-workflow.js";
+import { workflow } from "../src/authoring/workflow.js";
 import { runGoalWorkflow } from "./goal-runner.js";
 import { DEFAULT_MAX_TURNS } from "./goal-types.js";
 
-export default defineWorkflow("goal")
-  .description(
-    "Goal Runner workflow with bounded LM turns, ledger artifacts, parallel reviewers, and reducer-gated completion.",
-  )
-  .input("objective", Type.String({ description: "The objective for the Goal Runner workflow." }))
-  .input("max_turns", Type.Number({
-    default: DEFAULT_MAX_TURNS,
-    description: "Maximum worker/review turns before Goal Runner stops as needs_human.",
-  }))
-  .input("base_branch", Type.String({
-    default: "origin/main",
-    description: "Optional branch reviewers compare the current code delta against (default origin/main).",
-  }))
-  .output("result", Type.Optional(Type.String({ description: "Final report with objective, status, receipts, turns, and remaining work." })))
-  .output("status", Type.Optional(Type.Union(
-    [Type.Literal("complete"), Type.Literal("blocked"), Type.Literal("needs_human"), Type.Literal("active")],
-    { description: "Final reducer status: complete, blocked, needs_human, or active if externally interrupted." },
-  )))
-  .output("approved", Type.Optional(Type.Boolean({ description: "Whether the reducer reached complete." })))
-  .output("goal_id", Type.Optional(Type.String({ description: "Per-run goal identifier stored in the ledger." })))
-  .output("objective", Type.Optional(Type.String({ description: "Normalized goal objective used by the run." })))
-  .output("ledger_path", Type.Optional(Type.String({ description: "OS-temp path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })))
-  .output("turns_completed", Type.Optional(Type.Number({ description: "Worker/review turns completed." })))
-  .output("iterations_completed", Type.Optional(Type.Number({ description: "Worker/review turns completed, retained for status summaries." })))
-  .output(
-    "receipts",
-    Type.Optional(
-      Type.Array(
-        Type.Object({
-          turn: Type.Number(),
-          stage: Type.String(),
-          artifact_path: Type.String(),
-          summary: Type.String(),
-        }),
-        { description: "Ledger receipt summaries and worker artifact paths." },
-      ),
-    ),
-  )
-  .output("remaining_work", Type.Optional(Type.String({ description: "Remaining gaps or blockers when incomplete, or none." })))
-  .output("review_report", Type.Optional(Type.String({ description: "Compact report pointing to the latest reviewer decision artifacts used by the reducer." })))
-  .output("review_report_path", Type.Optional(Type.String({ description: "JSON artifact path for the latest reviewer decision round." })))
-  .run(runGoalWorkflow)
-  .compile();
+export default workflow({
+  name: "goal",
+  description: "Goal Runner workflow with bounded LM turns, ledger artifacts, parallel reviewers, and reducer-gated completion.",
+  inputs: {
+    objective: Type.String({ description: "The objective for the Goal Runner workflow." }),
+    max_turns: Type.Number({
+      default: DEFAULT_MAX_TURNS,
+      description: "Maximum worker/review turns before Goal Runner stops as needs_human.",
+    }),
+    base_branch: Type.String({
+      default: "origin/main",
+      description: "Optional branch reviewers compare the current code delta against (default origin/main).",
+    }),
+  },
+  outputs: {
+    result: Type.Optional(Type.String({ description: "Final report with objective, status, receipts, turns, and remaining work." })),
+    status: Type.Optional(Type.Union(
+      [Type.Literal("complete"), Type.Literal("blocked"), Type.Literal("needs_human"), Type.Literal("active")],
+      { description: "Final reducer status: complete, blocked, needs_human, or active if externally interrupted." },
+    )),
+    approved: Type.Optional(Type.Boolean({ description: "Whether the reducer reached complete." })),
+    goal_id: Type.Optional(Type.String({ description: "Per-run goal identifier stored in the ledger." })),
+    objective: Type.Optional(Type.String({ description: "Normalized goal objective used by the run (refined by the prompt-refinement stage)." })),
+    original_objective: Type.Optional(Type.String({ description: "The raw user-provided objective exactly as given, before prompt refinement. Omitted when refinement left it unchanged." })),
+    ledger_path: Type.Optional(Type.String({ description: "OS-temp path to goal-ledger.json with receipts, reviewer decisions, blockers, and lifecycle events." })),
+    turns_completed: Type.Optional(Type.Number({ description: "Worker/review turns completed." })),
+    iterations_completed: Type.Optional(Type.Number({ description: "Worker/review turns completed, retained for status summaries." })),
+    receipts: Type.Optional(Type.Array(Type.Object({
+      turn: Type.Number(),
+      stage: Type.String(),
+      artifact_path: Type.String(),
+      summary: Type.String(),
+    }), { description: "Ledger receipt summaries and worker artifact paths." })),
+    remaining_work: Type.Optional(Type.String({ description: "Remaining gaps or blockers when incomplete, or none." })),
+    review_report: Type.Optional(Type.String({ description: "Compact report pointing to the latest reviewer decision artifacts used by the reducer." })),
+    review_report_path: Type.Optional(Type.String({ description: "JSON artifact path for the latest reviewer decision round." })),
+  },
+  run: async (ctx) => await runGoalWorkflow(ctx),
+});

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

@@ -127,6 +127,7 @@ export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
   readonly preview_file_url?: string;
   readonly spec_path?: string;
   readonly spec_file_url?: string;
+  readonly playwright_cli_status?: string;
 };
 export type OpenClaudeDesignWorkflowDefinition = WorkflowDefinition<
   OpenClaudeDesignWorkflowInputs,

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

@@ -1,4 +1,4 @@
-import type { WorkflowTaskResult, WorkflowTaskStep } from "../src/shared/types.js";
+import type { WorkflowParallelOptions, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "../src/shared/types.js";
 import {
   ANTI_SLOP_RULES,
   DEFAULT_MAX_REFINEMENTS,
@@ -18,24 +18,22 @@ import {
 } from "./open-claude-design-utils.js";
 import { exportOpenClaudeDesign, refineOpenClaudeDesign } from "./open-claude-design-phases.js";
 
+type OpenClaudeDesignOutputs = {
+  readonly output_type?: string; readonly design_system?: string; readonly artifact?: string; readonly handoff?: string;
+  readonly approved_for_export?: boolean; readonly refinements_completed?: number; readonly import_context?: string; readonly run_id?: string;
+  readonly artifact_dir?: string; readonly preview_path?: string; readonly preview_file_url?: string; readonly spec_path?: string; readonly spec_file_url?: string;
+  readonly playwright_cli_status?: string;
+};
+
 type OpenClaudeDesignContext = {
-  readonly cwd: string;
-  readonly inputs: {
-    readonly prompt: string;
-    readonly reference?: string;
-    readonly output_type?: string;
-    readonly design_system?: string;
-    readonly max_refinements?: number;
-  };
-  task(name: string, options: object): Promise<WorkflowTaskResult>;
-  parallel(
-    steps: readonly WorkflowTaskStep[],
-    options: { readonly task: string },
-  ): Promise<WorkflowTaskResult[]>;
+  readonly cwd?: string;
+  readonly inputs: { readonly prompt: string; readonly reference?: string; readonly output_type?: string; readonly design_system?: string; readonly max_refinements?: number };
+  task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
+  parallel(steps: readonly WorkflowTaskStep[], options: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
 };
 
-export async function runOpenClaudeDesignWorkflow(ctx: unknown): Promise<object> {
-  const designContext = ctx as OpenClaudeDesignContext;
+export async function runOpenClaudeDesignWorkflow(ctx: OpenClaudeDesignContext): Promise<OpenClaudeDesignOutputs> {
+  const designContext = ctx;
 
     // Initial deterministic setup step (no LLM): ensure the playwright-cli skill's
     // `playwright-cli` command is installed before any design stage runs. Best-effort —
@@ -55,8 +53,9 @@ export async function runOpenClaudeDesignWorkflow(ctx: unknown): Promise<object>
       DEFAULT_MAX_REFINEMENTS,
     );
 
+    const workflowCwd = designContext.cwd ?? process.cwd();
     const { runId, artifactDir, previewPath, specPath } = prepareArtifactDir(
-      designContext.cwd,
+      workflowCwd,
     );
     const previewFileUrl = `file://${previewPath}`;
     const specFileUrl = `file://${specPath}`;

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

@@ -32,6 +32,7 @@ export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
   readonly preview_file_url?: string;
   readonly spec_path?: string;
   readonly spec_file_url?: string;
+  readonly playwright_cli_status?: string;
 };
 
 export type OpenClaudeDesignWorkflowDefinition = WorkflowDefinition<

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

@@ -18,21 +18,10 @@
  *   pre-export     → impeccable `audit`
  *   forced-fix     → impeccable `harden`
  *   exporter       → impeccable `document` (rich HTML spec)
- *
- * The refinement loop has been re-shaped so that the artifact under review is
- * a real HTML page on disk (`preview.html`). The workflow attempts to open it
- * through the `playwright-cli` skill so the user can interactively review;
- * when browser automation is unavailable, the file path is surfaced so the user
- * can open it manually. Before any stage runs, an initial deterministic setup
- * step ensures the playwright-cli skill's `playwright-cli` command is available
- * (`npx --no-install playwright-cli --version`, then
- * `npm install -g @playwright/cli@latest` when missing); it is best-effort and
- * never blocks the run. The final exporter produces a rich `spec.html` that
- * embeds the agreed-upon design alongside the implementation handoff.
  */
 
-import { defineWorkflow } from "../src/workflows/define-workflow.js";
 import { Type } from "typebox";
+import { workflow } from "../src/authoring/workflow.js";
 import { runOpenClaudeDesignWorkflow } from "./open-claude-design-runner.js";
 import {
   DEFAULT_MAX_REFINEMENTS,
@@ -40,41 +29,44 @@ import {
   OUTPUT_TYPES,
 } from "./open-claude-design-utils.js";
 
-export default defineWorkflow("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.",
-  )
-  .input("prompt", Type.String({
-    description: "What to design (for example, a dashboard, page, component, or prototype).",
-  }))
-  .input("reference", Type.Optional(Type.String({
-    description: "URL, file path, screenshot path, or design doc to import as a reference.",
-  })))
-  .input("output_type", Type.Union(
-    [...OUTPUT_TYPES].map((value) => Type.Literal(value)),
-    { default: DEFAULT_OUTPUT_TYPE, description: "Kind of design artifact to produce." },
-  ))
-  .input("design_system", Type.Optional(Type.String({
-    description:
-      "Path(s) or description of an existing design system (DESIGN.md, PRODUCT.md, etc.); skips onboarding when provided.",
-  })))
-  .input("max_refinements", Type.Number({
-    default: DEFAULT_MAX_REFINEMENTS,
-    description: `Maximum critique/apply refinement iterations (default ${DEFAULT_MAX_REFINEMENTS}).`,
-  }))
-  .output("output_type", Type.Optional(Type.String({ description: "Kind of design artifact produced." })))
-  .output("design_system", Type.Optional(Type.String({ description: "Design system source used for generation: supplied input or project-derived design system." })))
-  .output("artifact", Type.Optional(Type.String({ description: "Latest final design summary from the approved preview artifact." })))
-  .output("handoff", Type.Optional(Type.String({ description: "Final rich HTML spec and implementation handoff summary." })))
-  .output("approved_for_export", Type.Optional(Type.Boolean({ description: "Whether refinement completed before the final export gate." })))
-  .output("refinements_completed", Type.Optional(Type.Number({ description: "Number of refinement iterations completed." })))
-  .output("import_context", Type.Optional(Type.String({ description: "Reference-import context used during generation." })))
-  .output("run_id", Type.Optional(Type.String({ description: "Per-run design workflow artifact identifier." })))
-  .output("artifact_dir", Type.Optional(Type.String({ description: "Directory containing preview and spec artifacts." })))
-  .output("preview_path", Type.Optional(Type.String({ description: "Absolute path to the generated preview.html file." })))
-  .output("preview_file_url", Type.Optional(Type.String({ description: "file:// URL for the generated preview.html file." })))
-  .output("spec_path", Type.Optional(Type.String({ description: "Absolute path to the generated spec.html file." })))
-  .output("spec_file_url", Type.Optional(Type.String({ description: "file:// URL for the generated spec.html file." })))
-  .output("playwright_cli_status", Type.Optional(Type.String({ description: "Outcome of the initial deterministic step that ensures the playwright-cli skill's `playwright-cli` command is installed." })))
-  .run(runOpenClaudeDesignWorkflow)
-  .compile();
+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.",
+  inputs: {
+    prompt: Type.String({
+      description: "What to design (for example, a dashboard, page, component, or prototype).",
+    }),
+    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({
+      description:
+        "Path(s) or description of an existing design system (DESIGN.md, PRODUCT.md, etc.); skips onboarding when provided.",
+    })),
+    max_refinements: Type.Number({
+      default: DEFAULT_MAX_REFINEMENTS,
+      description: `Maximum critique/apply refinement 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." })),
+    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." })),
+    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." })),
+    artifact_dir: Type.Optional(Type.String({ description: "Directory containing preview and spec artifacts." })),
+    preview_path: Type.Optional(Type.String({ description: "Absolute path to the generated preview.html file." })),
+    preview_file_url: Type.Optional(Type.String({ description: "file:// URL for the generated preview.html file." })),
+    spec_path: Type.Optional(Type.String({ description: "Absolute path to the generated spec.html file." })),
+    spec_file_url: Type.Optional(Type.String({ description: "file:// URL for the generated spec.html file." })),
+    playwright_cli_status: Type.Optional(Type.String({ description: "Outcome of the initial deterministic step that ensures the playwright-cli skill's `playwright-cli` command is installed." })),
+  },
+  run: async (ctx) => await runOpenClaudeDesignWorkflow(ctx),
+});

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;
+}

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

@@ -258,18 +258,18 @@ export function forkContinuationOptions(
     : { context: "fork", forkFromSessionFile: sessionFile };
 }
 
-export function renderPromptEngineerPrompt(args: {
+export function renderResearchPromptRefinementPrompt(args: {
   readonly iteration: number;
   readonly maxLoops: number;
-  readonly prompt: string;
+  readonly request: string;
   readonly workflowCwdContext: PromptSection;
   readonly latestReviewReportPath: string | undefined;
 }): string {
-  const basePrompt = `/skill:prompt-engineer Transform the following user prompt to a codebase and online research question which can be thoroughly explored: ${args.prompt}`;
+  const basePrompt = `/skill:prompt-engineer Transform the following refined user request into a codebase and online research question which can be thoroughly explored: ${args.request}`;
   return [
     basePrompt,
     taggedPrompt([
-      ["iteration", `Prompt engineering iteration ${args.iteration}/${args.maxLoops}.`],
+      ["iteration", `Research prompt refinement iteration ${args.iteration}/${args.maxLoops}.`],
       args.workflowCwdContext,
       [
         "review_findings",
@@ -404,5 +404,7 @@ export type RalphWorkflowResult = {
   readonly iterations_completed: number;
   readonly review_report: string;
   readonly review_report_path?: string;
+  readonly original_prompt: string;
+  readonly refined_prompt: string;
 };