@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/workflows/README.md

@@ -51,19 +51,25 @@ When a stage human-in-the-loop prompt is answered from the workflow TUI/stage ch
 ### Example 1 — Single task
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-export default defineWorkflow("summarize-pr")
-  .description("Summarize a pull request in one task.")
-  .input("pr_url", Type.String({ description: "URL of the pull request to summarize." }))
-  .output("summary", Type.String({ description: "One-task summary of the pull request." }))
-  .run(async (ctx) => {
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "summarize-pr",
+  description: "Summarize a pull request in one task.",
+  inputs: {
+    pr_url: Type.String({ description: "URL of the pull request to summarize." }),
+  },
+  outputs: {
+    summary: Type.String({ description: "One-task summary of the pull request." }),
+  },
+  run: async (ctx) => {
     const summary = await ctx.task("summarize", {
       prompt: `Summarize the pull request at ${String(ctx.inputs.pr_url)} clearly and concisely.`,
     });
     return { summary: summary.text };
-  })
-  .compile();
+  },
+});
 ```
 
 ### Example 2 — Parallel fan-out with `ctx.parallel`
@@ -71,13 +77,19 @@ export default defineWorkflow("summarize-pr")
 Use `ctx.parallel` for independent specialist work. The aggregator receives the specialist outputs through typed task results instead of manual stage/session plumbing. The runtime snapshots the parent graph frontier when the fan-out starts, so every branch shares the same parents even when limited `concurrency` queues later branches or an earlier sibling fails with `failFast: false`.
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-export default defineWorkflow("parallel-research")
-  .description("Scout → three parallel specialists → aggregator.")
-  .input("topic", Type.String({ description: "Research topic." }))
-  .output("summary", Type.String({ description: "Synthesized summary of the specialist reports." }))
-  .run(async (ctx) => {
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "parallel-research",
+  description: "Scout → three parallel specialists → aggregator.",
+  inputs: {
+    topic: Type.String({ description: "Research topic." }),
+  },
+  outputs: {
+    summary: Type.String({ description: "Synthesized summary of the specialist reports." }),
+  },
+  run: async (ctx) => {
     const topic = ctx.inputs.topic;
 
     const reportPaths = {
@@ -103,21 +115,27 @@ export default defineWorkflow("parallel-research")
       reads: Object.values(reportPaths),
     });
     return { summary: summary.text };
-  })
-  .compile();
+  },
+});
 ```
 
 ### Example 3 — Human-in-the-loop (HIL)
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-export default defineWorkflow("review-and-merge")
-  .description("Plan a change, ask for human approval, then execute.")
-  .input("task", Type.String({ description: "What to implement." }))
-  .output("status", Type.Optional(Type.String({ description: "Set to \"cancelled\" when the human rejects the plan." })))
-  .output("result", Type.Optional(Type.String({ description: "Implementation result when the plan is approved." })))
-  .run(async (ctx) => {
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "review-and-merge",
+  description: "Plan a change, ask for human approval, then execute.",
+  inputs: {
+    task: Type.String({ description: "What to implement." }),
+  },
+  outputs: {
+    status: Type.Optional(Type.String({ description: "Set to \"cancelled\" when the human rejects the plan." })),
+    result: Type.Optional(Type.String({ description: "Implementation result when the plan is approved." })),
+  },
+  run: async (ctx) => {
     const planPath = ".atomic/workflows/runs/review-and-merge/plan.md";
     const plan = await ctx.task("planner", {
       prompt: `Create a concise implementation plan for: ${String(ctx.inputs.task)}`,
@@ -135,27 +153,34 @@ export default defineWorkflow("review-and-merge")
       reads: [planPath],
     });
     return { result: result.text };
-  })
-  .compile();
+  },
+});
 ```
 
-Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, `ctx.ui.editor`, or `ctx.ui.custom<T>` at the point where the workflow actually needs a decision. No builder-level declaration is required or supported.
+Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, `ctx.ui.editor`, or `ctx.ui.custom<T>` at the point where the workflow actually needs a decision. No declaration-time HIL marker is required or supported.
 
 `ctx.ui.custom<T>(factory, options?)` mounts an arbitrary focused TUI component in the attached workflow graph/stage UI and resolves with the value passed to `done(value)`. The factory uses the same real TUI/theme/keybinding/component types as Atomic extension `ctx.ui.custom`. Use `options.label` for a safe display-only graph/status label and `options.replayIdentity` (do not include secrets) when the widget's semantics can change without the callsite changing; label text is not part of replay identity. Custom widget prompts require an interactive workflow graph; they are not answerable through non-TUI `workflow send` in iteration 1. Inline graph rendering is supported; `overlay: true` is rejected clearly because nested workflow graph overlays are not safely supported yet.
 
 ### Example 4 — Compose workflows
 
-Prefer regular TypeScript module imports for reusable child workflows: import the compiled workflow definition, then pass it directly to `ctx.workflow(workflowDefinition, options)`.
+Prefer regular TypeScript module imports for reusable child workflows: import the workflow definition returned by `workflow({...})`, then pass it directly to `ctx.workflow(workflowDefinition, options)`.
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
 import goal from "@bastani/workflows/builtin/goal";
 import sharedResearch from "./shared-research.js";
 
-export default defineWorkflow("research-and-synthesize")
-  .input("topic", Type.String())
-  .output("final", Type.String({ description: "Synthesis of the child research and implementation." }))
-  .run(async (ctx) => {
+export default workflow({
+  name: "research-and-synthesize",
+  description: "Run shared research, implement from it, then synthesize the result.",
+  inputs: {
+    topic: Type.String(),
+  },
+  outputs: {
+    final: Type.String({ description: "Synthesis of the child research and implementation." }),
+  },
+  run: async (ctx) => {
     const child = await ctx.workflow(sharedResearch, {
       inputs: { topic: ctx.inputs.topic },
     });
@@ -168,31 +193,38 @@ export default defineWorkflow("research-and-synthesize")
       prompt: `Synthesize this research and implementation:\n\n${String(child.outputs.summary)}\n\n${String(implementation.outputs.result)}`,
     });
     return { final: final.text };
-  })
-  .compile();
+  },
+});
 ```
 
-The child executes as a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default, but user-facing status and graph views flatten it into the parent run. In practice it should feel like inlining the child workflow code: child stages, HIL prompt nodes, and deeper imported children appear in one expanded parent graph, while implementation-owned child run ids stay hidden from top-level `/workflow status` lists. The child still has a run id internally so the graph can attach to, pause, interrupt, resume, or kill live child stages correctly. Inputs are strictly validated against the child workflow before it starts: unknown keys, missing required values, type mismatches, and invalid `select` choices fail before the child body runs. The parent receives the child's declared `.output(...)` outputs on `child.outputs` after those outputs pass their declared runtime type checks.
+The child executes as a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default, but user-facing status and graph views flatten it into the parent run. In practice it should feel like inlining the child workflow code: child stages, HIL prompt nodes, and deeper imported children appear in one expanded parent graph, while implementation-owned child run ids stay hidden from top-level `/workflow status` lists. The child still has a run id internally so the graph can attach to, pause, interrupt, resume, or kill live child stages correctly. Inputs are strictly validated against the child workflow before it starts: unknown keys, missing required values, type mismatches, and invalid `select` choices fail before the child body runs. The parent receives the child's declared `outputs` on `child.outputs` after those outputs pass their declared runtime type checks.
 
-For workflows intended to be called as children, declare `.output(...)` for every non-default field a parent should rely on. `.output(...)` is only the schema/contract: use normal TypeScript in `.run()` to gather values from any stage/task/child workflow and return those keys.
+For workflows intended to be called as children, declare an `outputs` entry for every non-default field a parent should rely on. `outputs` is only the schema/contract: use normal TypeScript in `run()` to gather values from any stage/task/child workflow and return those keys.
 
-**Return convention:** child outputs are return-object keys. Atomic never infers child workflow outputs from stage names, stage order, or the final assistant message. If a parent should read `child.outputs.summary`, the child workflow's `.run()` must both declare `.output("summary", schema)` and return `{ summary }`. `result` is not special and is never added for you: to expose `result`, declare `.output("result", schema)` and return `{ result }` like any other output. Returning a key that is not declared with `.output(...)` fails the run with `atomic-workflows: workflow "<name>" returned undeclared output "<key>"; declare it with .output("<key>", Type....) or remove it from the .run() return` (the child-call variant reports `... child "<alias>" returned undeclared output "<key>" from "<childName>"`).
+**Return convention:** child outputs are return-object keys. Atomic never infers child workflow outputs from stage names, stage order, or the final assistant message. If a parent should read `child.outputs.summary`, the child workflow's `outputs` map must declare `summary` and `run()` must return `{ summary }`. `result` is not special and is never added for you: to expose `result`, declare `outputs: { result: schema }` and return `{ result }` like any other output. Returning a key that is not declared in `outputs` fails the run with `atomic-workflows: workflow "<name>" returned undeclared output "<key>"; declare it in outputs or remove it from the run() return` (the child-call variant reports `... child "<alias>" returned undeclared output "<key>" from "<childName>"`).
 
-A reusable child module can simply default-export a compiled workflow:
+A reusable child module can simply default-export a workflow definition:
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-export default defineWorkflow("shared-research")
-  .input("topic", Type.String())
-  .output("summary", Type.String())
-  .run(async (ctx) => {
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "shared-research",
+  description: "Reusable research helper.",
+  inputs: {
+    topic: Type.String(),
+  },
+  outputs: {
+    summary: Type.String(),
+  },
+  run: async (ctx) => {
     const report = await ctx.task("research", {
       prompt: `Research: ${String(ctx.inputs.topic)}`,
     });
     return { summary: report.text };
-  })
-  .compile();
+  },
+});
 ```
 
 Builtin workflows are also callable as modules for reuse:
@@ -203,34 +235,40 @@ import goalWorkflow from "@bastani/workflows/builtin/goal";
 import openClaudeDesignWorkflow from "@bastani/workflows/builtin/open-claude-design";
 ```
 
-Only compiled workflow definitions can be passed to `ctx.workflow(...)`; registry names, strings, and path objects are intentionally not supported for child workflow calls. Missing or invalid module imports fail when the workflow file itself is loaded. A parent receives the child's declared `.output(...)` outputs from the child `.run()` return object. Missing required outputs, schema type mismatches, returning an undeclared output, and non-JSON-serializable returned child values fail the child call before the parent continues.
+Only `workflow({...})` definitions can be passed to `ctx.workflow(...)`; registry names, strings, and path objects are intentionally not supported for child workflow calls. Missing or invalid module imports fail when the workflow file itself is loaded. A parent receives the child's declared `outputs` from the child `run()` return object. Missing required outputs, schema type mismatches, returning an undeclared output, and non-JSON-serializable returned child values fail the child call before the parent continues.
 
 ### Reusable Git worktrees
 
 Use `gitWorktreeDir` when a workflow should run in a reusable Git worktree instead of the invoking checkout. The executor creates the worktree if it is missing, reuses it when it already exists as a same-repository worktree root, defaults workflow `ctx.cwd` to the matching path inside that worktree for `worktreeFromInputs`, and defaults stage/task `cwd` to that worktree path.
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-export default defineWorkflow("safe-implementation")
-  .description("Run implementation stages in a reusable worktree.")
-  .input("task", Type.String())
-  .input("worktree", Type.String({ default: "" }))
-  .input("base_branch", Type.String({ default: "origin/main" }))
-  .worktreeFromInputs({
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "safe-implementation",
+  description: "Run implementation stages in a reusable worktree.",
+  inputs: {
+    task: Type.String(),
+    worktree: Type.String({ default: "" }),
+    base_branch: Type.String({ default: "origin/main" }),
+  },
+  worktreeFromInputs: {
     gitWorktreeDir: "worktree",
     baseBranch: "base_branch",
-  })
-  .output("result", Type.String({ description: "Implementation result text." }))
-  .run(async (ctx) => {
+  },
+  outputs: {
+    result: Type.String({ description: "Implementation result text." }),
+  },
+  run: async (ctx) => {
     const result = await ctx.task("implement", {
       task: String(ctx.inputs.task),
       // No cwd needed: when `worktree` is non-empty, this task runs from the
       // corresponding cwd inside that reusable Git worktree.
     });
     return { result: result.text };
-  })
-  .compile();
+  },
+});
 ```
 
 You can also pass worktree options per stage/task or as shared chain/parallel defaults:
@@ -289,16 +327,22 @@ Atomic registers the canonical `structured_output` tool only for schema-enabled
 Stages and high-level task helpers can retry transient provider/model failures with an ordered `fallbackModels` list. The primary `model` is tried first, then each fallback, and finally the current Atomic-selected model when available. Fallbacks are only used for retryable model/provider failures such as rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — ordinary tool, shell, validation, cancellation, and workflow-code failures are not retried.
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-export default defineWorkflow("fallback-review")
-  .description("Review with a model fallback chain.")
-  .input("topic", Type.String())
-  .output("review", Type.String({ description: "Reviewer output text." }))
-  .output("model", Type.Optional(Type.String({ description: "Model that produced the review." })))
-  .output("attemptedModels", Type.Optional(Type.Array(Type.String(), { description: "Models tried, in fallback order." })))
-  .output("modelAttempts", Type.Optional(Type.Array(Type.Unknown(), { description: "Per-attempt model fallback details." })))
-  .run(async (ctx) => {
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "fallback-review",
+  description: "Review with a model fallback chain.",
+  inputs: {
+    topic: Type.String(),
+  },
+  outputs: {
+    review: Type.String({ description: "Reviewer output text." }),
+    model: Type.Optional(Type.String({ description: "Model that produced the review." })),
+    attemptedModels: Type.Optional(Type.Array(Type.String(), { description: "Models tried, in fallback order." })),
+    modelAttempts: Type.Optional(Type.Array(Type.Unknown(), { description: "Per-attempt model fallback details." })),
+  },
+  run: async (ctx) => {
     const review = await ctx.task("reviewer", {
       prompt: `Review this topic: ${String(ctx.inputs.topic)}`,
       model: "anthropic/claude-sonnet-4",
@@ -311,8 +355,8 @@ export default defineWorkflow("fallback-review")
       attemptedModels: review.attemptedModels ? [...review.attemptedModels] : undefined,
       modelAttempts: review.modelAttempts ? [...review.modelAttempts] : undefined,
     };
-  })
-  .compile();
+  },
+});
 ```
 
 Direct helpers and workflow tool direct modes can set task-local fallbacks or a top-level default:
@@ -331,11 +375,11 @@ When pi exposes its model registry, workflow runs validate user-specified `model
 ### `createRegistry` — grouping workflows
 
 ```typescript
-import { createRegistry, defineWorkflow } from "@bastani/workflows";
+import { createRegistry, workflow } from "@bastani/workflows";
 
-const alpha = defineWorkflow("alpha").run(async () => ({})).compile();
-const beta  = defineWorkflow("beta").run(async () => ({})).compile();
-const gamma = defineWorkflow("gamma").run(async () => ({})).compile();
+const alpha = workflow({ name: "alpha", description: "", outputs: {}, run: async () => ({}) });
+const beta = workflow({ name: "beta", description: "", outputs: {}, run: async () => ({}) });
+const gamma = workflow({ name: "gamma", description: "", outputs: {}, run: async () => ({}) });
 
 const registry = createRegistry()
   .register(alpha)
@@ -343,28 +387,35 @@ const registry = createRegistry()
   .merge(createRegistry().register(gamma));
 
 registry.names();      // ["alpha", "beta", "gamma"]
-registry.all();        // compiled workflow definitions
-registry.get("alpha"); // compiled workflow definition | undefined
+registry.all();        // workflow definitions
+registry.get("alpha"); // workflow definition | undefined
 ```
 
 ### Declaring inputs and outputs with TypeBox
 
-Inputs and outputs are declared with [TypeBox](https://github.com/sinclairzx81/typebox) schemas. Import `Type` from `@bastani/workflows` (alongside `defineWorkflow`) and pass a schema to `.input(key, schema)` / `.output(key, schema)`. The builder infers precise static types for `ctx.inputs`, the `.run()` return, and `child.outputs` from those schemas, and the runtime validates against them with TypeBox `Value`.
+Inputs and outputs are declared with [TypeBox](https://github.com/sinclairzx81/typebox) schemas. Import `workflow` from `@bastani/workflows`, import `Type` from `typebox`, and put schemas in the `inputs` and `outputs` maps. `workflow({...})` infers precise static types for `ctx.inputs`, the `run()` return, and `child.outputs` from those schemas, and the runtime validates against them with TypeBox `Value`.
 
 **Prefer precise schemas.** A precise schema (`Type.Object({ topic: Type.String(), score: Type.Number() })`, `Type.Array(Type.String())`) gives consumers a precise `Static<>` type and makes runtime validation enforce the real shape. Reserve `Type.Unknown()`, `Type.Any()`, `Type.Array(Type.Unknown())`, and `Type.Object({}, { additionalProperties: true })` for genuinely dynamic data whose shape you cannot know ahead of time.
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
-
-defineWorkflow("example")
-  .input("prompt", Type.String({ description: "Required free-text input." }))   // required key -> ctx.inputs.prompt: string
-  .input("ref", Type.Optional(Type.String()))                                    // optional key -> string | undefined
-  .input("count", Type.Number({ default: 2 }))                                    // defaulted -> required key, ctx.inputs.count: number
-  .input("flavor", Type.Union([Type.Literal("a"), Type.Literal("b")], { default: "a" })) // select
-  .output("packet", Type.Object({ topic: Type.String(), score: Type.Number() })) // required object output
-  .output("note", Type.Optional(Type.String()))                                   // optional output
-  .run(async (ctx) => ({ packet: { topic: ctx.inputs.prompt, score: ctx.inputs.count } }))
-  .compile();
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+workflow({
+  name: "example",
+  description: "",
+  inputs: {
+    prompt: Type.String({ description: "Required free-text input." }), // required key -> ctx.inputs.prompt: string
+    ref: Type.Optional(Type.String()),                                  // optional key -> string | undefined
+    count: Type.Number({ default: 2 }),                                  // defaulted -> required key, ctx.inputs.count: number
+    flavor: Type.Union([Type.Literal("a"), Type.Literal("b")], { default: "a" }), // select
+  },
+  outputs: {
+    packet: Type.Object({ topic: Type.String(), score: Type.Number() }), // required object output
+    note: Type.Optional(Type.String()),                                  // optional output
+  },
+  run: async (ctx) => ({ packet: { topic: ctx.inputs.prompt, score: ctx.inputs.count } }),
+});
 ```
 
 `Static` and `TSchema` are also re-exported from `@bastani/workflows` for advanced typing.
@@ -380,11 +431,11 @@ defineWorkflow("example")
 | `Type.Union([Type.Literal("a"), Type.Literal("b")], { default? })` | `select` | Enumerated string choices                        |
 | `Type.Optional(schema)`                                      | —           | Makes the key optional (`T \| undefined`)        |
 
-A required input is any schema that is neither `Type.Optional(...)` nor carries a `default` (a defaulted input is a required key at the type level but optional for the caller to provide). Input validation is strict for named workflow runs and `ctx.workflow(...)` child calls: Atomic rejects unknown keys, missing required values, values whose runtime type does not match the declared schema, and `select` values outside the declared literals. It does not coerce strings like `"3"` into numbers; pass JSON numbers (`count=3`) for `Type.Number()`. `.input(...)` narrows `ctx.inputs` for intellisense: required/defaulted strings are `string`, numbers are `number`, booleans are `boolean`, selects are the literal union, and `Type.Optional(...)` inputs include `undefined`.
+A required input is any schema that is neither `Type.Optional(...)` nor carries a `default` (a defaulted input is a required key at the type level but optional for the caller to provide). Input validation is strict for named workflow runs and `ctx.workflow(...)` child calls: Atomic rejects unknown keys, missing required values, values whose runtime type does not match the declared schema, and `select` values outside the declared literals. It does not coerce strings like `"3"` into numbers; pass JSON numbers (`count=3`) for `Type.Number()`. The `inputs` map narrows `ctx.inputs` for intellisense: required/defaulted strings are `string`, numbers are `number`, booleans are `boolean`, selects are the literal union, and `Type.Optional(...)` inputs include `undefined`.
 
 ### Output types
 
-Declare outputs with `.output(key, schema)` when a workflow result should be part of its runtime contract, especially when another workflow will call it as a child. Lead with the most precise schema you can express — the loose rows at the bottom are last resorts for genuinely dynamic data.
+Declare outputs in `outputs` when a workflow result should be part of its runtime contract, especially when another workflow will call it as a child. Lead with the most precise schema you can express — the loose rows at the bottom are last resorts for genuinely dynamic data.
 
 | Schema                                              | Runtime value accepted                              |
 | --------------------------------------------------- | --------------------------------------------------- |
@@ -400,7 +451,7 @@ Declare outputs with `.output(key, schema)` when a workflow result should be par
 | `Type.Object({}, { additionalProperties: true })`   | any JSON object (last resort, dynamic only)         |
 | `Type.Unknown()` / `Type.Any()`                     | any JSON-serializable value (last resort)           |
 
-Wrap an output schema in `Type.Optional(...)` to make the key optional; an un-wrapped output schema is required. `.run()` must return a JSON-serializable object. Functions, symbols, `undefined` properties, `NaN`, infinite numbers, and non-plain objects (e.g. `Date`) fail validation. Declared outputs are validated before a workflow is marked completed. A required output that is missing fails with `missing output "<key>"`, and a type mismatch fails with `output "<key>" expected <kind>, got <actual>`. A workflow exposes exactly the outputs it declares with `.output(...)`: there is no automatic `result` output, and returning a key that was not declared fails the run with `atomic-workflows: workflow "<name>" returned undeclared output "<key>"; declare it with .output("<key>", Type....) or remove it from the .run() return`. To expose `result`, declare `.output("result", schema)` and return `{ result }`. Child output replay still performs a structured-clone safety check after JSON validation so completed child boundaries can be replayed.
+Wrap an output schema in `Type.Optional(...)` to make the key optional; an un-wrapped output schema is required. `run()` must return a JSON-serializable object. Functions, symbols, `undefined` properties, `NaN`, infinite numbers, and non-plain objects (e.g. `Date`) fail validation. Declared outputs are validated before a workflow is marked completed. A required output that is missing fails with `missing output "<key>"`, and a type mismatch fails with `output "<key>" expected <kind>, got <actual>`. A workflow exposes exactly the outputs it declares in `outputs`: there is no automatic `result` output, and returning a key that was not declared fails the run with `atomic-workflows: workflow "<name>" returned undeclared output "<key>"; declare it in outputs or remove it from the run() return`. To expose `result`, declare `outputs: { result: schema }` and return `{ result }`. Child output replay still performs a structured-clone safety check after JSON validation so completed child boundaries can be replayed.
 
 #### Why precise schemas
 
@@ -408,23 +459,26 @@ A loose schema types the value as `unknown`/`Record<string, unknown>` everywhere
 
 ```typescript
 // ❌ Loose: child.outputs.report is `unknown`; runtime only checks "is JSON".
-.output("report", Type.Unknown())
+outputs: { report: Type.Unknown() }
 
 // ✅ Precise: child.outputs.report is `{ topic: string; score: number; tags: string[] }`,
 //    and TypeBox rejects a returned value missing `score` or with a non-number `score`.
-.output("report", Type.Object({
-  topic: Type.String(),
-  score: Type.Number(),
-  tags: Type.Array(Type.String()),
-}))
+outputs: {
+  report: Type.Object({
+    topic: Type.String(),
+    score: Type.Number(),
+    tags: Type.Array(Type.String()),
+  }),
+}
 ```
 
 #### `Type.Unsafe<T>()` escape hatch
 
-When you already have a precise TypeScript type for a deeply-nested serializable value and don't want to hand-write the full TypeBox schema, wrap a permissive runtime schema with `Type.Unsafe<MyType>(...)`. The **static** type becomes exactly `MyType` (so `ctx.inputs`, the `.run()` return, and `child.outputs` stay precise), while the **runtime** stays as lenient as the wrapped schema. Use a `type` alias rather than an `interface` for the wrapped type — an `interface` has no implicit index signature, so it does not satisfy the serializable-output constraint:
+When you already have a precise TypeScript type for a deeply-nested serializable value and don't want to hand-write the full TypeBox schema, wrap a permissive runtime schema with `Type.Unsafe<MyType>(...)`. The **static** type becomes exactly `MyType` (so `ctx.inputs`, the `run()` return, and `child.outputs` stay precise), while the **runtime** stays as lenient as the wrapped schema. Use a `type` alias rather than an `interface` for the wrapped type — an `interface` has no implicit index signature, so it does not satisfy the serializable-output constraint:
 
 ```typescript
-import { defineWorkflow, Type } from "@bastani/workflows";
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
 
 type ResearchPacket = {
   readonly topic: string;
@@ -432,19 +486,25 @@ type ResearchPacket = {
   readonly sections: readonly { readonly heading: string; readonly body: string }[];
 };
 
-export default defineWorkflow("research-packet")
-  .input("topic", Type.String())
-  // Static type = ResearchPacket; runtime only checks "is a JSON object".
-  .output("packet", Type.Unsafe<ResearchPacket>(Type.Object({}, { additionalProperties: true })))
-  .run(async (ctx) => {
+export default workflow({
+  name: "research-packet",
+  description: "Return a typed research packet.",
+  inputs: {
+    topic: Type.String(),
+  },
+  outputs: {
+    // Static type = ResearchPacket; runtime only checks "is a JSON object".
+    packet: Type.Unsafe<ResearchPacket>(Type.Object({}, { additionalProperties: true })),
+  },
+  run: async (ctx) => {
     const packet: ResearchPacket = {
       topic: ctx.inputs.topic,
       score: 1,
       sections: [{ heading: "overview", body: "…" }],
     };
     return { packet };
-  })
-  .compile();
+  },
+});
 ```
 
 Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts the produced value matches `T`. Use it when the producing code already guarantees the shape; when you can express the shape directly, prefer a real `Type.Object(...)`/`Type.Array(...)` so runtime validation also catches drift. Keep bare `Type.Unknown()` and loose `additionalProperties` objects for genuinely dynamic data.
@@ -452,8 +512,8 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 #### How types flow
 
 - `ctx.inputs.x` is `Static<inputSchema>` — required/defaulted inputs are present, `Type.Optional(...)` adds `| undefined`.
-- The `.run()` return is checked against declared outputs at compile time (missing-required and wrong-type are TypeScript errors) and at runtime via TypeBox `Value` (undeclared keys rejected, declared shape enforced recursively).
-- `ctx.workflow(child).outputs` is typed from the child's declared `.output(...)` contract, so a parent reads precisely-typed child outputs without casting.
+- The `run()` return is checked against declared outputs at compile time (missing-required, wrong-type, and undeclared-output keys are TypeScript errors for object-form `workflow({...})`) and at runtime via TypeBox `Value` (undeclared keys rejected, declared shape enforced recursively).
+- `ctx.workflow(child).outputs` is typed from the child's declared `outputs` contract, so a parent reads precisely-typed child outputs without casting.
 
 `Static` and `TSchema` are re-exported from `@bastani/workflows`; use `Static<typeof schema>` when you need a schema's inferred TypeScript type directly.
 
@@ -544,19 +604,26 @@ For interactive use, run workflows through `/workflow <name> [key=value ...]` or
 
 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: interactive ctx.ui.confirm is unavailable in headless (non-interactive) mode; run the workflow in interactive mode or remove the interactive prompt from this stage` (the primitive name varies, including `ctx.ui.custom`). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
 
-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.
+For library or package authoring, define reusable workflows with `workflow({...})` and export the returned definition. Hand-written objects with `__piWorkflow: true` are rejected by discovery and composition; `workflow({...})` is the public authoring surface. Standalone TypeScript workflow packages import `workflow` from `@bastani/workflows` and `Type` from `typebox` directly with no local `.d.ts` file or `declare module` shim. Migration from the removed builder API is mechanical: move `.description(...)` to `description`, `.input(key, schema)` calls into `inputs`, `.output(key, schema)` calls into `outputs`, `.worktreeFromInputs(...)` to `worktreeFromInputs`, and the `.run(fn)` callback to `run: fn`; delete `.compile()`. The former imperative `runWorkflow` object-form API is removed; use workflow definitions with the exported `run()` / registry helpers for programmatic execution.
 
 ```ts
-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) => {
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "audit-auth",
+  description: "Audit the authentication module.",
+  inputs: {
+    prompt: Type.String({ default: "Investigate the auth module" }),
+  },
+  outputs: {
+    summary: Type.String(),
+  },
+  run: async (ctx) => {
     const result = await ctx.task("audit", { prompt: ctx.inputs.prompt });
     return { summary: result.text };
-  })
-  .compile();
+  },
+});
 ```
 
 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.