@bastani/atomic 0.8.23 → 0.8.24-alpha.1

package/dist/builtin/workflows/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <b>Turn coding agents into reliable engineering workflows.</b><br>
-  An open-source pi extension: install it, author workflows in TypeScript, run them from chat.
+  An open-source Atomic workflow extension: install it, author workflows in TypeScript, run them from chat.
 </p>
 
 <p align="center">
@@ -507,49 +507,28 @@ Press **F2** while a workflow is running to open the DAG overlay for the active
 
 ### Execution model
 
-`@bastani/workflows` follows pi's package/extension model: pi loads `src/extension/index.ts` from the package `pi.extensions` manifest, then the extension registers the `workflow` tool, `/workflow` slash command, renderers, widget, and lifecycle hooks in-process.
+`@bastani/workflows` follows Atomic's package/extension model: Atomic loads `src/extension/index.ts` from the package `atomic.extensions` manifest, with legacy `pi.extensions` still supported, then the extension registers the `workflow` tool, `/workflow` slash command, renderers, widget, and lifecycle hooks in-process.
 
 For interactive use, run workflows through `/workflow <name> [key=value ...]` or let the LLM call the `workflow` tool. In non-interactive (`-p` / `--print` / `--mode json`) sessions, `/workflow <name> key=value` and LLM calls to the `workflow` tool remain available for deterministic workflows. The input picker and graph picker are disabled, top-level `ctx.ui.*` is unavailable, and stage child sessions exclude `ask_user_question`. Named workflow dispatch waits for the terminal run snapshot before returning.
 
 Because human input is runtime-only and workflows no longer carry a declaration-time HIL marker, headless dispatch does not reject a workflow just because its source contains `ctx.ui.*`. If you copy the HIL example above into a non-interactive session, it can pass dispatch and then fail when execution reaches the prompt with an error such as `atomic-workflows: HIL ctx.ui.confirm is unavailable because Atomic runtime did not provide a UI adapter` (the primitive name varies). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
 
-For library or scripted use, you can also call the explicit programmatic runner:
+For library or package authoring, define reusable workflows with the builder and export the compiled definition. Hand-written objects with `__piWorkflow: true` are rejected by discovery and composition; `defineWorkflow(...).compile()` is the public authoring surface. Standalone TypeScript workflow packages can import `defineWorkflow` and `Type` from `@bastani/workflows` directly with no local `.d.ts` file or `declare module` shim. The former imperative `runWorkflow` object-form API is removed; use compiled workflow definitions with the exported `run()` / registry helpers for programmatic execution.
 
 ```ts
-import { runWorkflow, type WorkflowOptions } from "@bastani/workflows";
-
-const definition = {
-  mode: "workflow",
-  workflow: "deep-research-codebase",
-  inputs: {
-    prompt: "Investigate the auth module",
-    max_partitions: 6,
-    max_concurrency: 4,
-  },
-} as const;
-
-const options: WorkflowOptions = {};
-
-await runWorkflow(definition, options);
-
-await runWorkflow({
-  mode: "parallel",
-  task: "Audit auth changes",
-  tasks: [
-    { name: "security", task: "Review security risks" },
-    { name: "runtime", task: "Review runtime risks" },
-  ],
-  concurrency: 2,
-  reads: ["research/context.md"],
-  output: "research/auth-audit.md",
-  outputMode: "file-only",
-  worktree: false,
-  maxOutput: { lines: 2000 },
-  artifacts: true,
-});
+import { defineWorkflow, Type } from "@bastani/workflows";
+
+export default defineWorkflow("audit-auth")
+  .input("prompt", Type.String({ default: "Investigate the auth module" }))
+  .output("summary", Type.String())
+  .run(async (ctx) => {
+    const result = await ctx.task("audit", { prompt: ctx.inputs.prompt });
+    return { summary: result.text };
+  })
+  .compile();
 ```
 
-The programmatic definition object mirrors the workflow tool: named workflow runs, single-task runs, parallel `tasks`, and mixed `chain` runs accept the same direct options (`reads`, `output`, `outputMode`, `worktree`, `gitWorktreeDir`, `baseBranch`, `maxOutput`, `artifacts`, `concurrency`, `failFast`, and stage/session options such as `cwd`, `agentDir`, `model`, `tools`, `context`, and `sessionDir`). `chainDir` is chain-only: it provides the shared artifact directory for chain reads, outputs, and worktree diffs.
+The `workflow` tool still supports direct one-off `task`, `tasks`, and `chain` modes for agent-initiated orchestration. Those direct modes are runtime tool inputs, not workflow definition files.
 
 For large handoffs, prefer artifact paths over prompt injection: write stage output to `output`, set `outputMode: "file-only"` when the parent only needs the path, pass paths with `reads`, and instruct downstream agents explicitly with wording like `Read the file at <path>...`. Reserve `previous`/`{previous}` for compact summaries; avoid passing full session histories, all prior stage outputs, or every review round directly into the next model prompt. In review loops, save JSON review artifacts and pass only the latest review-round artifact, with a ledger or index file linking older rounds when needed.
 
@@ -636,13 +615,15 @@ Child workflow outputs: `output_type`, `design_system`, `artifact`, `handoff`, `
 
 ## Custom workflow discovery
 
-`@bastani/workflows` automatically discovers workflow files from three locations:
+`@bastani/workflows` discovers workflow files from project-local paths, user-global paths, configured workflow paths, installed Atomic package resources, and bundled workflows:
 
-| Location                          | Scope      | Example path                               |
-| --------------------------------- | ---------- | ------------------------------------------ |
-| `.atomic/workflows/*.ts`          | Project    | `.atomic/workflows/my-workflow.ts`         |
-| `~/.atomic/agent/workflows/*.ts`  | User       | `~/.atomic/agent/workflows/my-workflow.ts` |
-| `workflows.<name>.path` in config | Configured | see config example below                   |
+| Location                           | Scope      | Example path                                                                           |
+| ---------------------------------- | ---------- | -------------------------------------------------------------------------------------- |
+| `.atomic/workflows/*.ts`           | Project    | `.atomic/workflows/my-workflow.ts`                                                     |
+| `~/.atomic/agent/workflows/*.ts`   | User       | `~/.atomic/agent/workflows/my-workflow.ts`                                             |
+| `workflows.<name>.path` in config  | Configured | see config example below                                                               |
+| Installed Atomic package workflows | Package    | `atomic.workflows`, legacy `pi.workflows`, or `workflows/` / `workflow/` directories   |
+| Bundled workflows                  | Built-in   | shipped with `@bastani/workflows`                                                      |
 
 Config-based discovery (`~/.atomic/agent/extensions/workflow/config.json` or `.atomic/extensions/workflow/config.json`):
 
@@ -667,3 +648,19 @@ MIT — see [LICENSE](LICENSE).
 ---
 
 **Development:** see [DEV_SETUP.md](../../DEV_SETUP.md) for setup, testing, layout, and the local-extension dev loop.
+
+## Model reasoning levels
+
+Workflow stage `model` and `fallbackModels` strings support suffix-first reasoning levels using the `model_name:thinking_effort` syntax: append `:off`, `:minimal`, `:low`, `:medium`, `:high`, or `:xhigh` to the model id (for example `openai/gpt-5:high` or `anthropic/claude-haiku-4-5:off`). A suffix on a fallback candidate controls only that retry attempt, so fallback chains can mix reasoning levels.
+
+The older `thinkingLevel` stage option remains accepted as a deprecated default for candidates without a suffix. If both are present, the model suffix wins. Migrate legacy `thinkingLevel` stages by folding the effort into the model strings:
+
+```diff
+-  model: "openai/gpt-5.5",
+-  fallbackModels: ["anthropic/claude-opus-4-8"],
+-  thinkingLevel: "high",
++  model: "openai/gpt-5.5:high",
++  fallbackModels: ["anthropic/claude-opus-4-8:high"],
+```
+
+`fallbackThinkingLevels` is an optional compatibility helper aligned by index to `fallbackModels`; it is used only for fallback entries that do not already include a suffix.

package/dist/builtin/workflows/builtin/deep-research-codebase.d.ts

@@ -0,0 +1,35 @@
+import type { WorkflowDefinition, WorkflowInputValues, 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
+>;
+
+declare const workflow: DeepResearchCodebaseWorkflowDefinition;
+export default workflow;

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -15,7 +15,6 @@ import { defineWorkflow } from "../src/workflows/define-workflow.js";
 import { Type } from "typebox";
 import type {
   WorkflowOutputMode,
-  WorkflowOutputValues,
   WorkflowTaskResult,
   WorkflowTaskStep,
 } from "../src/shared/types.js";
@@ -30,7 +29,7 @@ const GIT_LS_FILES_TIMEOUT_MS = 2_000;
 
 type PromptSection = readonly [tag: string, content: string];
 
-interface DeepResearchCodebaseResult extends WorkflowOutputValues {
+interface DeepResearchCodebaseResult {
   readonly result: string;
   readonly findings: string;
   readonly research_doc_path: string;
@@ -413,26 +412,24 @@ export default defineWorkflow("deep-research-codebase")
     );
 
     const plannerModelConfig = {
-      model: "openai/gpt-5.5",
+      model: "openai/gpt-5.5:xhigh",
       fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-opus-4-8",
-        "github-copilot/claude-opus-4.7",
+        "openai-codex/gpt-5.5:xhigh",
+        "github-copilot/gpt-5.5:xhigh",
+        "anthropic/claude-opus-4-8:xhigh",
+        "github-copilot/claude-opus-4.8:medium",
       ],
-      thinkingLevel: "high" as const,
       excludedTools: ["ask_user_question"],
     };
 
     const explorerModelConfig = {
-      model: "openai/gpt-5.4-mini",
+      model: "openai/gpt-5.4-mini:low",
       fallbackModels: [
-        "openai-codex/gpt-5.4-mini",
-        "github-copilot/gpt-5.4-mini",
-        "anthropic/claude-haiku-4-5",
-        "github-copilot/claude-haiku-4.5",
+        "openai-codex/gpt-5.4-mini:low",
+        "github-copilot/gpt-5.4-mini:low",
+        "anthropic/claude-haiku-4-5:low",
+        "github-copilot/claude-haiku-4.5:low",
       ],
-      thinkingLevel: "low" as const,
       excludedTools: ["ask_user_question"],
     };
 

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

@@ -0,0 +1,46 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+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 max_turns: number;
+  readonly base_branch: string;
+};
+
+export type GoalWorkflowRunInputs = WorkflowInputValues & {
+  readonly objective: string;
+  readonly max_turns?: number;
+  readonly base_branch?: string;
+};
+
+export type GoalWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly status?: GoalWorkflowStatus;
+  readonly approved?: boolean;
+  readonly goal_id?: string;
+  readonly objective?: 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;
+};
+
+export type GoalWorkflowDefinition = WorkflowDefinition<
+  GoalWorkflowInputs,
+  GoalWorkflowOutputs,
+  GoalWorkflowRunInputs
+>;
+
+declare const workflow: GoalWorkflowDefinition;
+export default workflow;

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

@@ -1026,26 +1026,24 @@ export default defineWorkflow("goal")
     const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective);
 
     const workerModelConfig = {
-      model: "openai/gpt-5.5",
+      model: "openai/gpt-5.5:medium",
       fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-sonnet-4-7",
-        "github-copilot/claude-sonnet-4.7",
+        "openai-codex/gpt-5.5:medium",
+        "github-copilot/gpt-5.5:medium",
+        "anthropic/claude-sonnet-4-8:medium",
+        "github-copilot/claude-sonnet-4.8:medium",
       ],
-      thinkingLevel: "low" as const,
       tools: goalRunnerTools,
     };
 
     const reviewerModelConfig = {
-      model: "openai/gpt-5.5",
+      model: "openai/gpt-5.5:xhigh",
       fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-sonnet-4-7",
-        "github-copilot/claude-sonnet-4.7",
+        "openai-codex/gpt-5.5:xhigh",
+        "github-copilot/gpt-5.5:xhigh",
+        "anthropic/claude-sonnet-4-8:xhigh",
+        "github-copilot/claude-sonnet-4.8:medium",
       ],
-      thinkingLevel: "high" as const,
       tools: [...goalRunnerTools, reviewDecisionTool.name],
       customTools: [reviewDecisionTool],
     };

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

@@ -0,0 +1,136 @@
+import type { WorkflowDefinition, WorkflowInputValues, 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 max_turns: number;
+  readonly base_branch: string;
+};
+export type GoalWorkflowRunInputs = WorkflowInputValues & {
+  readonly objective: string;
+  readonly max_turns?: number;
+  readonly base_branch?: string;
+};
+export type GoalWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly status?: GoalWorkflowStatus;
+  readonly approved?: boolean;
+  readonly goal_id?: string;
+  readonly objective?: 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;
+};
+export type GoalWorkflowDefinition = WorkflowDefinition<
+  GoalWorkflowInputs,
+  GoalWorkflowOutputs,
+  GoalWorkflowRunInputs
+>;
+
+export type RalphWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_loops: number;
+  readonly base_branch: string;
+  readonly git_worktree_dir: string;
+};
+export type RalphWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_loops?: number;
+  readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
+};
+export type RalphWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly plan?: string;
+  readonly plan_path?: string;
+  readonly implementation_notes_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 type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "component" | "theme" | "tokens";
+export type OpenClaudeDesignWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements: number;
+};
+export type OpenClaudeDesignWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type?: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements?: number;
+};
+export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
+  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;
+};
+export type OpenClaudeDesignWorkflowDefinition = WorkflowDefinition<
+  OpenClaudeDesignWorkflowInputs,
+  OpenClaudeDesignWorkflowOutputs,
+  OpenClaudeDesignWorkflowRunInputs
+>;
+
+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/open-claude-design.d.ts

@@ -0,0 +1,44 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "component" | "theme" | "tokens";
+
+export type OpenClaudeDesignWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements: number;
+};
+
+export type OpenClaudeDesignWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type?: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements?: number;
+};
+
+export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
+  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;
+};
+
+export type OpenClaudeDesignWorkflowDefinition = WorkflowDefinition<
+  OpenClaudeDesignWorkflowInputs,
+  OpenClaudeDesignWorkflowOutputs,
+  OpenClaudeDesignWorkflowRunInputs
+>;
+
+declare const workflow: OpenClaudeDesignWorkflowDefinition;
+export default workflow;

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

@@ -226,13 +226,12 @@ export default defineWorkflow("open-claude-design")
     const specFileUrl = `file://${specPath}`;
 
     const designModelConfig = {
-      model: "anthropic/claude-opus-4-8",
+      model: "anthropic/claude-opus-4-8:xhigh",
       fallbackModels: [
-        "github-copilot/claude-opus-4.7",
-        "anthropic/claude-sonnet-4-6",
-        "github-copilot/claude-sonnet-4.6",
+        "github-copilot/claude-opus-4.8:medium",
+        "anthropic/claude-sonnet-4-6:xhigh",
+        "github-copilot/claude-sonnet-4.6:medium",
       ],
-      thinkingLevel: "high" as const,
     };
 
     let designSystem: string;
@@ -243,7 +242,7 @@ export default defineWorkflow("open-claude-design")
         prompt: taggedPrompt([
           [
             "role",
-            "You are an impeccable design-system analyst. Apply the impeccable `document` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/document.md) to read an existing DESIGN.md / PRODUCT.md (or equivalent) and re-emit it in the six-section Google Stitch DESIGN.md format so the rest of this workflow can rely on it.",
+            "You are an impeccable design-system analyst. Apply the impeccable `document` sub-skill to read an existing DESIGN.md / PRODUCT.md (or equivalent) and re-emit it in the six-section Google Stitch DESIGN.md format so the rest of this workflow can rely on it.",
           ],
           [
             "objective",
@@ -289,7 +288,7 @@ export default defineWorkflow("open-claude-design")
             task: taggedPrompt([
               [
                 "role",
-                "You are an impeccable design-system locator. Apply the impeccable `extract` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/extract.md) to find design-system evidence already living in this codebase.",
+                "You are an impeccable design-system locator. Apply the impeccable `extract` sub-skill to find design-system evidence already living in this codebase.",
               ],
               [
                 "objective",
@@ -320,7 +319,7 @@ export default defineWorkflow("open-claude-design")
             task: taggedPrompt([
               [
                 "role",
-                "You are an impeccable UI architecture auditor. Apply the impeccable `audit` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/audit.md) to score the project's UI implementation across five dimensions.",
+                "You are an impeccable UI architecture auditor. Apply the impeccable `audit` sub-skill to score the project's UI implementation across five dimensions.",
               ],
               [
                 "objective",
@@ -360,7 +359,7 @@ export default defineWorkflow("open-claude-design")
             task: taggedPrompt([
               [
                 "role",
-                "You are an impeccable pattern miner. Apply the impeccable `extract` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/extract.md) to harvest reusable design and component patterns, plus the anti-patterns to avoid.",
+                "You are an impeccable pattern miner. Apply the impeccable `extract` sub-skill to harvest reusable design and component patterns, plus the anti-patterns to avoid.",
               ],
               [
                 "objective",
@@ -394,7 +393,7 @@ export default defineWorkflow("open-claude-design")
         prompt: taggedPrompt([
           [
             "role",
-            "You are an impeccable design-system author. Apply the impeccable `document` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/document.md) to synthesize a project-specific DESIGN.md in the six-section Google Stitch format from the three onboarding analyses.",
+            "You are an impeccable design-system author. Apply the impeccable `document` sub-skill to synthesize a project-specific DESIGN.md in the six-section Google Stitch format from the three onboarding analyses.",
           ],
           [
             "objective",
@@ -442,7 +441,7 @@ export default defineWorkflow("open-claude-design")
         task: taggedPrompt([
           [
             "role",
-            "You are an impeccable reference extractor for live web pages. Apply the impeccable `extract` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/extract.md) to pull only the design traits that should transfer into the project — never just clone the source.",
+            "You are an impeccable reference extractor for live web pages. Apply the impeccable `extract` sub-skill to pull only the design traits that should transfer into the project — never just clone the source.",
           ],
           [
             "objective",
@@ -478,7 +477,7 @@ export default defineWorkflow("open-claude-design")
         task: taggedPrompt([
           [
             "role",
-            "You are an impeccable reference parser for local design files. Apply the impeccable `extract` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/extract.md) to lift concrete, citable requirements out of supplied references.",
+            "You are an impeccable reference parser for local design files. Apply the impeccable `extract` sub-skill to lift concrete, citable requirements out of supplied references.",
           ],
           [
             "objective",
@@ -520,7 +519,7 @@ export default defineWorkflow("open-claude-design")
       prompt: taggedPrompt([
         [
           "role",
-          "You are an impeccable design-and-build engineer. Apply the impeccable `craft` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/craft.md) to ship a production-quality HTML artifact that traces back to the synthesized DESIGN.md.",
+          "You are an impeccable design-and-build engineer. Apply the impeccable `craft` sub-skill to ship a production-quality HTML artifact that traces back to the synthesized DESIGN.md.",
         ],
         [
           "objective",
@@ -609,7 +608,7 @@ export default defineWorkflow("open-claude-design")
         prompt: taggedPrompt([
           [
             "role",
-            "You are an impeccable design reviewer collecting actionable refinement feedback from the user about the rendered HTML preview. Apply the impeccable `critique` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/critique.md) to decide whether the artifact is ready.",
+            "You are an impeccable design reviewer collecting actionable refinement feedback from the user about the rendered HTML preview. Apply the impeccable `critique` sub-skill to decide whether the artifact is ready.",
           ],
           [
             "objective",
@@ -653,7 +652,7 @@ export default defineWorkflow("open-claude-design")
             task: taggedPrompt([
               [
                 "role",
-                "You are an impeccable design critic. Apply the impeccable `critique` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/critique.md) to run the formal two-pass review against the live HTML preview.",
+                "You are an impeccable design critic. Apply the impeccable `critique` sub-skill to run the formal two-pass review against the live HTML preview.",
               ],
               [
                 "objective",
@@ -696,7 +695,7 @@ export default defineWorkflow("open-claude-design")
             task: taggedPrompt([
               [
                 "role",
-                "You are an impeccable visual QA specialist for the rendered HTML preview. Apply the impeccable `audit` (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/audit.md) plus `live` (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/live.md) sub-skills to validate the rendered output against breakpoints, states, and accessibility.",
+                "You are an impeccable visual QA specialist for the rendered HTML preview. Apply the impeccable `audit` plus `live` sub-skills to validate the rendered output against breakpoints, states, and accessibility.",
               ],
               [
                 "objective",
@@ -742,7 +741,7 @@ export default defineWorkflow("open-claude-design")
         prompt: taggedPrompt([
           [
             "role",
-            "You are an impeccable design polisher. Apply the impeccable `polish` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/polish.md) — the meticulous final pass between good and great — to revise the HTML preview in place.",
+            "You are an impeccable design polisher. Apply the impeccable `polish` — the meticulous final pass between good and great — to revise the HTML preview in place.",
           ],
           [
             "objective",
@@ -828,7 +827,7 @@ export default defineWorkflow("open-claude-design")
       prompt: taggedPrompt([
         [
           "role",
-          "You are an impeccable pre-release gate. Apply the impeccable `audit` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/audit.md) one final time to block export only for concrete, evidence-backed issues.",
+          "You are an impeccable pre-release gate. Apply the impeccable `audit` sub-skill one final time to block export only for concrete, evidence-backed issues.",
         ],
         [
           "objective",
@@ -864,7 +863,7 @@ export default defineWorkflow("open-claude-design")
         prompt: taggedPrompt([
           [
             "role",
-            "You are an impeccable production-readiness hardener. Apply the impeccable `harden` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/harden.md) to remove blocking findings without redesigning.",
+            "You are an impeccable production-readiness hardener. Apply the impeccable `harden` sub-skill to remove blocking findings without redesigning.",
           ],
           [
             "objective",
@@ -903,7 +902,7 @@ export default defineWorkflow("open-claude-design")
       prompt: taggedPrompt([
         [
           "role",
-          "You are an impeccable design documenter. Apply the impeccable `document` sub-skill (https://github.com/pbakaus/impeccable/blob/main/site/content/skills/document.md) to produce a RICH HTML SPEC that bundles the approved preview together with implementation guidance for Claude Code / frontend engineers.",
+          "You are an impeccable design documenter. Apply the impeccable `document` sub-skill to produce a RICH HTML SPEC that bundles the approved preview together with implementation guidance for a design/frontend engineer.",
         ],
         [
           "objective",

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

@@ -0,0 +1,36 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type RalphWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_loops: number;
+  readonly base_branch: string;
+  readonly git_worktree_dir: string;
+};
+
+export type RalphWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_loops?: number;
+  readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
+};
+
+export type RalphWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly plan?: string;
+  readonly plan_path?: string;
+  readonly implementation_notes_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
+>;
+
+declare const workflow: RalphWorkflowDefinition;
+export default workflow;