@bastani/atomic 0.8.21 → 0.8.22-0

package/docs/workflows.md

@@ -38,7 +38,9 @@ Use a workflow when a task should be repeatable, inspectable, resumable, or spli
 - [Running Workflows](#running-workflows)
 - [Workflow Commands](#workflow-commands)
 - [Monitor and Control Runs](#monitor-and-control-runs)
+- [Lifecycle Notices and Human Input](#lifecycle-notices-and-human-input)
 - [Direct One-Off Runs](#direct-one-off-runs)
+- [Codex Fast Mode for Workflow Stages](#codex-fast-mode-for-workflow-stages)
 - [Writing a Workflow](#writing-a-workflow)
 - [Workflow Primitives](#workflow-primitives)
 - [Task and Stage Options](#task-and-stage-options)
@@ -85,7 +87,9 @@ Atomic will:
 - ask clarifying questions when stage purpose, inputs, models, or handoffs are ambiguous,
 - write a `.atomic/workflows/<name>.ts` file using `defineWorkflow(...).input(...).run(...).compile()`,
 - pick `ctx.task` / `ctx.chain` / `ctx.parallel` / `ctx.ui` per the [primitives](#workflow-primitives) and [task options](#task-and-stage-options) reference, and
-- reload discovery so you can run it immediately.
+- run `/workflow reload` so Atomic rediscovers the workflow resource and you can launch it immediately.
+
+Atomic does not use the long-running `/goal` workflow by default for first-time workflow creation. If you explicitly choose `/goal` for reviewer-gated implementation, keep the objective tightly scoped with concrete done criteria and validation steps, and monitor the run with workflow status/connect controls rather than manual sleep-and-poll loops.
 
 The same plain-chat approach works for editing or hardening an existing workflow — ask Atomic to add a stage, switch a model, save artifacts, or wire in a human approval gate.
 
@@ -104,15 +108,17 @@ Named workflow runs are background-oriented. After launch, expect a run id and m
 Workflow files are plain TypeScript modules. Create `.atomic/workflows/explain-file.ts`:
 
 ```ts
-import { defineWorkflow } from "@bastani/workflows";
+import { defineWorkflow, Type } from "@bastani/workflows";
 
 export default defineWorkflow("explain-file")
   .description("Explain a file with tracked workflow stages.")
-  .input("path", {
-    type: "text",
-    required: true,
-    description: "File path to explain.",
-  })
+  .input("path", Type.String({ description: "File path to explain." }))
+  .output(
+    "explanation",
+    Type.String({
+      description: "Explanation of the file's purpose, risks, and key symbols.",
+    }),
+  )
   .run(async (ctx) => {
     const explanation = await ctx.task("explain", {
       prompt: `Read ${String(ctx.inputs.path)} and explain purpose, risks, and key symbols.`,
@@ -124,7 +130,7 @@ export default defineWorkflow("explain-file")
   .compile();
 ```
 
-Restart Atomic or run `/reload`, then list and run it:
+Run `/workflow reload` or restart Atomic, then list and run it:
 
 ```text
 /workflow list
@@ -138,12 +144,16 @@ See [Writing a Workflow](#writing-a-workflow) for the full builder API and [Work
 
 Atomic bundles four workflows that cover the most common multi-stage jobs. They are available in every session — no install step required. Use `/workflow list` to confirm they are loaded, and `/workflow inputs <name>` to see the exact inputs in your environment.
 
+These same builtin workflows are also available to workflow authors as compiled definitions. Import them from `@bastani/workflows/builtin` and pass the definition directly to `ctx.workflow(...)` when one workflow should call `deep-research-codebase`, `goal`, `ralph`, `open-claude-design`, or another builtin as a nested child workflow. See [Workflow Composition](#workflow-composition) for full examples alongside user-defined child workflows.
+
+For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralph` explicitly declare `.output("result", Type.String(...))` and return a `result` key from `.run()`, so `result` is part of their declared output contract. Every output a workflow exposes — including `result` — must be both declared with `.output(...)` and returned from `.run()`; Atomic no longer adds any automatic `result` output.
+
 | Workflow | What it does | When to use |
 |---|---|---|
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
 | `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. |
 | `ralph` | RFC planning → sub-agent orchestration → simplification → infrastructure discovery → parallel review → PR handoff. | Larger migrations, broad refactors, multi-package changes, and spec-to-PR work where you want Atomic to plan the approach, delegate implementation through sub-agents, simplify, review, iterate, and prepare a pull-request report. |
-| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `playwright-cli` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
+| `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser-use` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
 
 ### `deep-research-codebase`
 
@@ -153,7 +163,7 @@ Inputs:
 |---|---|---|---|---|
 | `prompt` | text | yes | — | Research question or investigation focus. |
 | `max_partitions` | number | no | `100` | Maximum codebase partitions explored in parallel. Actual partitions scale by one per 10K LoC, capped by this value. |
-| `max_concurrency` | number | no | `4` | Maximum workflow stages running concurrently during deep research. |
+| `max_concurrency` | number | no | `100` | Maximum workflow stages running concurrently during deep research. |
 
 Run examples:
 
@@ -176,6 +186,7 @@ Output locations and result fields:
 
 | Field | Meaning |
 |---|---|
+| `result` | Final Markdown research report text, matching `findings`. |
 | `findings` | Final Markdown research report text. |
 | `research_doc_path` | Public report path under `research/<date>-<topic>.md`. If a file already exists, the workflow writes a suffixed filename. |
 | `artifact_dir` | Hidden per-run handoff directory under `research/.deep-research-<run-id>/`. |
@@ -280,6 +291,26 @@ Inputs:
 | `design_system` | text | no | — | Path(s) or description of an existing design system (e.g. `DESIGN.md`, `PRODUCT.md`). Skips onboarding when provided. |
 | `max_refinements` | number | no | `3` | Maximum critique/apply refinement iterations. |
 
+Result fields:
+
+| Field | Meaning |
+|---|---|
+| `output_type` | Kind of design artifact produced. |
+| `design_system` | Design system source used for generation: supplied input or project-derived design system. |
+| `artifact` | Latest final design summary from the approved preview artifact. |
+| `handoff` | Final rich HTML spec and implementation handoff summary. |
+| `approved_for_export` | Whether refinement completed before the final export gate. |
+| `refinements_completed` | Number of refinement iterations completed. |
+| `import_context` | Reference-import context used during generation. |
+| `run_id` | Per-run design workflow artifact identifier. |
+| `artifact_dir` | Directory containing preview and spec artifacts. |
+| `preview_path` | Absolute path to the generated `preview.html` file. |
+| `preview_file_url` | `file://` URL for the generated `preview.html` file. |
+| `spec_path` | Absolute path to the generated `spec.html` file. |
+| `spec_file_url` | `file://` URL for the generated `spec.html` file. |
+
+`open-claude-design` has no `result` output; it exposes only the declared fields listed above. Use the declared `artifact` and `handoff` fields for generated content.
+
 Run examples:
 
 ```text
@@ -411,7 +442,11 @@ Example config:
   "maxDepth": 4,
   "persistRuns": true,
   "statusFile": false,
-  "resumeInFlight": "ask"
+  "resumeInFlight": "ask",
+  "workflowNotifications": {
+    "enabled": true,
+    "notifyOn": ["completed", "failed", "awaiting_input"]
+  }
 }
 ```
 
@@ -424,6 +459,8 @@ Runtime config defaults:
 | `persistRuns` | `true` | Persist run metadata for status/resume/history |
 | `statusFile` | `false` | Write a derived status file; defaults under `.atomic/workflows/status.json` when enabled |
 | `resumeInFlight` | `"ask"` | Behavior when discovering resumable in-flight work |
+| `workflowNotifications.enabled` | `true` | Emit terminal workflow lifecycle notices into the active main chat |
+| `workflowNotifications.notifyOn` | `["completed", "failed", "awaiting_input"]` | Lifecycle states to track; terminal `completed`/`failed` states create main-chat notices, while `awaiting_input` is tracked for dedupe/restore without waking the main agent |
 
 Invalid JSON or invalid shapes produce `CONFIG_INVALID` diagnostics. Missing config files are ignored.
 
@@ -522,6 +559,14 @@ workflow({ action: "get", workflow: "deep-research-codebase" })
 workflow({ action: "inputs", workflow: "deep-research-codebase" })
 ```
 
+The workflow tool action surface is:
+
+- discovery: `list`, `get`, `inputs`
+- execution: named `run`, plus direct one-off `task`, `tasks`, and `chain` modes
+- inspection: `status`, `stages`, `stage`, `transcript`
+- messaging and run control: `send`, `pause`, `interrupt`, `kill`, `resume`
+- rediscovery: `reload`
+
 Run a named workflow with inputs:
 
 ```ts
@@ -540,10 +585,12 @@ Slash equivalent:
 
 <p align="center"><img src="images/workflow-command.png" alt="Running a Workflow Command" width="600" /></p>
 
-Input overrides are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=3`, `flag=true`, and `prompt="multi word value"` preserve useful types. A whole input object can also be passed as one JSON token.
+Input overrides are bare `key=value` tokens. Values are JSON-parsed when possible, so `count=3`, `flag=true`, and `prompt="multi word value"` preserve useful types. A whole input object can also be passed as one JSON token. Runtime validation is strict: unknown input keys, missing required values, type mismatches, and invalid `select` choices fail before a named workflow run starts or before a child workflow starts.
 
 In the TUI, `/workflow <name>` opens an input picker when the workflow declares inputs and either no arguments were supplied or required inputs are missing. Supplied values seed the picker. Pass `--no-picker` to skip that interactive flow.
 
+In non-interactive (`-p`, `--print`, or `--mode json`) sessions, named workflow dispatch waits for the terminal run snapshot and skips pickers. 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 a HIL workflow example into a headless 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.
+
 <p align="center"><img src="images/workflow-input-picker.png" alt="Workflow Input Picker" width="600" /></p>
 
 ## Workflow Commands
@@ -564,11 +611,11 @@ In the TUI, `/workflow <name>` opens an input picker when the workflow declares
 /workflow reload
 ```
 
-Use `connect` for the workflow graph. Use `attach` when you want a chat pane for a specific stage. Use `interrupt`, `pause`, and `resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot or overlay. Use `kill` only when the run should be terminated; killed runs are retained in live history/status for read-only inspection. Use `/workflow reload` after adding, editing, installing, or removing workflow resources and you want Atomic to rediscover them in-process. `/workflow status` lists all retained active and terminal runs by default; `/workflow status --all` is retained as a compatibility alias.
+Use `connect` for the workflow graph. Use `attach` when you want a chat pane for a specific stage. Use `interrupt`, `pause`, and `resume` for resumable live work; `resume` on a non-paused run reopens the saved snapshot or overlay. Use `kill` only when the run should be terminated; killed runs are retained in live history/status for read-only inspection. Use `/workflow reload` after adding, editing, installing, or removing workflow resources or package manifest workflow entries and you want Atomic to rediscover them in-process. `/workflow status` lists all retained active and terminal top-level runs by default; implementation-owned nested child runs are flattened into their parent workflow rather than listed separately. `/workflow status --all` is retained as a compatibility alias.
 
 <p align="center"><img src="images/workflow-graph.png" alt="Workflow Graph Viewer" width="600" /></p>
 
-Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` appear as awaiting-input nodes in the workflow UI/graph viewer, not as ordinary chat modals.
+Human-in-the-loop prompts from `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, and `ctx.ui.editor` appear as awaiting-input nodes in the workflow UI/graph viewer, not as ordinary chat modals. Workflows do not declare HIL up front; prompt nodes are created when the runtime `ctx.ui.*` call executes. If the prompt lives inside an imported child workflow, it still appears in the same expanded parent graph so the user can focus and answer it without switching to a separate child status entry.
 
 ## Monitor and Control Runs
 
@@ -580,11 +627,15 @@ workflow({ action: "status", runId: "<id-or-prefix>" })
 
 workflow({ action: "stages", runId: "<id-or-prefix>", statusFilter: "all" })
 workflow({ action: "stage", runId: "<id-or-prefix>", stageId: "review" })
+// Prefer sessionFile/transcriptPath from stages/stage; quote the exact path, preserve Windows separators, then search/read small ranges.
+workflow({ action: "transcript", runId: "<id-or-prefix>", stageId: "review" })
+// Omit tail/limit for the default 5-entry preview; pass them for quick recent-context checks.
 workflow({ action: "transcript", runId: "<id-or-prefix>", stageId: "review", tail: 40 })
-workflow({ action: "transcript", runId: "<id-or-prefix>", stageId: "review", includeToolOutput: true })
+workflow({ action: "transcript", runId: "<id-or-prefix>", stageId: "review", limit: 20, includeToolOutput: true })
 
 workflow({ action: "send", runId: "<id-or-prefix>", stageId: "review", text: "please focus on tests" })
-workflow({ action: "send", runId: "<id-or-prefix>", stageId: "approval", response: true, delivery: "answer" })
+workflow({ action: "send", runId: "<id-or-prefix>", stageId: "approval", promptId: "prompt-1", response: true, delivery: "answer" })
+workflow({ action: "send", runId: "<id-or-prefix>", stageId: "review", message: "continue with tests", delivery: "resume" })
 
 workflow({ action: "pause", runId: "<id-or-prefix>" })
 workflow({ action: "pause", runId: "<id-or-prefix>", stageId: "review" })
@@ -603,12 +654,13 @@ workflow({ action: "reload", reason: "added team workflow" })
 
 Control behavior:
 
-- `runId` accepts full run ids or unique prefixes for lifecycle and inspection actions.
-- `stages` lists stage summaries. Use `statusFilter: "all"` to include completed, failed, skipped, and pending stages.
-- `stage` returns details for one stage by stage id, unique prefix, or stage name.
-- `transcript` reads recent messages for a stage. `tail` overrides `limit`; `includeToolOutput` includes captured snapshot tool output when available.
-- `send` can answer pending prompts, steer streaming stages, queue follow-ups, or resume paused work. `delivery: "auto"` chooses in that order; use `delivery: "answer"` with `promptId` or `response` for explicit prompt answers.
-- `pause`, `interrupt`, and `kill` can target one run or `all: true`; `stageId` cannot be combined with `all: true`.
+- `runId` accepts full run ids or unique prefixes for lifecycle and inspection actions. Status lists and run pickers show top-level user-launched workflows; nested child runs are implementation details of the expanded parent graph.
+- `stages` lists stage summaries, including flattened stages from nested `ctx.workflow(...)` imports and `sessionFile`/`transcriptPath` when a stage has a persisted session. Use `statusFilter: "all"` to include completed, failed, skipped, and pending stages.
+- `stage` returns details for one stage by stage id, unique prefix, or stage name, including nested child stages shown in the expanded graph and the persisted `sessionFile` when available.
+- `transcript` is reference-first with a small preview by default: it returns metadata, transcript paths, and up to 5 recent entries. For targeted lookup, quote the exact `sessionFile`/`transcriptPath` value without changing platform separators (preserve Windows backslashes), search it with `rg` or `grep`, then read only small surrounding ranges. Text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals. Pass explicit `tail` or `limit` to override the 5-entry preview; `tail` overrides `limit`; `includeToolOutput` includes captured snapshot tool output in snapshot transcript results.
+- `send` delivery modes are `auto`, `answer`, `prompt`, `steer`, `followUp`, and `resume`. Prompt answers can include `promptId` and can carry answer content in `response`, `text`, or `message`; structured UI prompts usually prefer `response`.
+- `delivery: "auto"` first answers a pending prompt, then resumes paused work, then steers a streaming stage, then queues a follow-up.
+- `pause`, `interrupt`, and `kill` can target one top-level run or `all: true`; `stageId` cannot be combined with `all: true`. Stage-scoped controls can target a visible nested child stage from the expanded graph; Atomic routes the operation to the owning nested run internally.
 - `interrupt` is resumable: it pauses live work when pausable stages exist and keeps the run in live history/status.
 - `pause` is useful for pausing a live run or a single live stage without treating it as a destructive abort.
 - `resume` can target a stage with `stageId`; the target may be a stage id, unique prefix, or stage name. `message` is forwarded to paused work.
@@ -617,6 +669,23 @@ Control behavior:
 
 Use slash commands for graph connect and stage attach because those are interactive TUI surfaces. When a run needs user input or attention, surface that to the user instead of polling silently.
 
+## Lifecycle Notices and Human Input
+
+Atomic emits deduplicated main-chat notices when top-level workflow runs complete or fail. Nested child workflow completion/failure is reflected inside the expanded parent graph instead of producing separate top-level completion cards. These terminal notices are queued into the active main chat as steering/context messages (`triggerTurn: true`, `deliverAs: "steer"`) so the model can react without the user manually polling status. Awaiting-input workflow states are tracked for dedupe/restore, but they do not enqueue main-chat connect cards or wake the model; prompt state remains visible through workflow status/connect surfaces. Configure lifecycle behavior with `workflowNotifications.enabled` (default `true`) and `workflowNotifications.notifyOn` (default `["completed", "failed", "awaiting_input"]`).
+
+Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, or `ctx.ui.editor` at the point where the workflow actually needs a decision. No builder-level declaration is required or supported.
+
+When a workflow needs human input, answer in the graph viewer or attached stage chat when possible:
+
+```text
+/workflow connect <run-id>
+/workflow attach <run-id> <stage-id-or-name>
+```
+
+Agents can answer pending prompts programmatically with `workflow({ action: "send", delivery: "answer", ... })`; use `promptId` when it is present in the stage details, and provide answer content with `response`, `text`, or `message`.
+
+If the user answers a human-in-the-loop prompt in the workflow UI or stage UI broker, the stage receives the answer directly and the active main chat receives a display-only notice (`triggerTurn: false`, `excludeFromContext: true`) containing a concise answer summary. The notice is rendered for the user and persisted for audit, but it does not wake the model, enter LLM context, or authorize answering any other workflow prompt. Prompt answers sent by the main-chat `workflow` tool are suppressed from this notice because the tool result already informs the current turn.
+
 ## Direct One-Off Runs
 
 Use direct workflow-native orchestration for one-off tracked work that does not need a reusable workflow file.
@@ -688,20 +757,26 @@ Direct mode supports top-level/default options and per-task options such as `con
 
 For large fan-outs, prefer `outputMode: "file-only"` so the parent result contains compact file references instead of full output. Treat intercom payloads from async direct runs as user-visible workflow output.
 
+## Codex Fast Mode for Workflow Stages
+
+Use `/fast` to manage Codex fast mode separately for normal chat and workflow-stage sessions. The settings are `codexFastMode.chat` and `codexFastMode.workflow`; workflow stages use the workflow scope, not the chat scope.
+
+Fast mode is eligible only for supported `openai/*` and `openai-codex/*` providers. It does not apply to `github-copilot/*`, Azure OpenAI, OpenRouter, or custom OpenAI-compatible providers. When applied, workflow stage displays keep the raw model id and expose `fast` as a separate marker/stage metadata indicator.
+
+Enable workflow fast mode deliberately for broad workflows: parallel fan-out and fallback attempts can multiply priority-tier requests and cost.
+
 ## Writing a Workflow
 
 Workflow files are TypeScript modules that export a compiled definition:
 
 ```ts
-import { defineWorkflow } from "@bastani/workflows";
+import { defineWorkflow, Type } from "@bastani/workflows";
 
 export default defineWorkflow("my-workflow")
   .description("Short description shown in workflow listings.")
-  .input("prompt", {
-    type: "text",
-    required: true,
-    description: "Task or question for the workflow.",
-  })
+  .input("prompt", Type.String({ description: "Task or question for the workflow." }))
+  .output("summary", Type.String({ description: "Synthesized findings and recommended next steps." }))
+  .output("reviewer_count", Type.Number({ description: "Number of parallel reviewers that ran." }))
   .run(async (ctx) => {
     const prompt = String(ctx.inputs.prompt);
 
@@ -735,23 +810,305 @@ Builder basics:
 - `.description(text)` sets the listing text.
 - `.input(key, schema)` declares typed user inputs.
 - `.worktreeFromInputs({ gitWorktreeDir, baseBranch })` optionally maps input names to workflow-wide reusable Git worktree defaults.
+- `.output(key, schema?)` declares typed outputs that parent workflows receive from `ctx.workflow(childWorkflow, ...)`.
 - `.run(async (ctx) => { ... })` defines the workflow body.
 - `.compile()` returns the workflow definition for discovery.
 
 `prompt` and `task` are aliases for task text. Prefer `prompt` inside authored workflow files because it mirrors lower-level `stage.prompt(...)`; `task` remains useful in direct tool calls and chain examples.
 
-A valid workflow must create at least one tracked stage by calling `ctx.task()`, `ctx.chain()`, `ctx.parallel()`, or `ctx.stage()` in its run body. A no-stage workflow is skipped during discovery because it has no graph node to inspect, attach to, interrupt, resume, or render.
+A valid workflow must create at least one tracked stage by calling `ctx.task()`, `ctx.chain()`, `ctx.parallel()`, `ctx.stage()`, or `ctx.workflow()` in its run body. A no-stage workflow is skipped during discovery because it has no graph node to inspect, attach to, interrupt, resume, or render.
 
 ### Inputs
 
-Supported input schema types are:
+Inputs are declared with TypeBox `Type.*` schemas passed to `.input(key, schema)`. `Type` is re-exported from `@bastani/workflows` (along with the `Static` and `TSchema` type helpers), so you can author and type schemas without adding a separate `typebox` dependency. Common input schemas map to picker kinds and accepted runtime values:
+
+| TypeBox schema | Picker kind | Accepted runtime value |
+|---|---|---|
+| `Type.String({ default? })` | text | string |
+| `Type.Number({ default? })` | number | number |
+| `Type.Integer({ default? })` | integer | integer (whole number) |
+| `Type.Boolean({ default? })` | boolean | boolean |
+| `Type.Union([Type.Literal("a"), Type.Literal("b")], { default? })` | select | one of the literal strings |
+
+A `Type.Union([Type.Literal(...)])` of string literals is how a 'select' is expressed: the input picker renders those literals as the selectable choices, and runtime validation rejects any value outside them. Put `description` and `default` in the schema options object, e.g. `Type.String({ description: "…", default: "…" })`. An input is required when its schema is **not** wrapped in `Type.Optional(...)` and declares no `default`; wrap optional inputs in `Type.Optional(...)`. A `default` does not make an input optional — a defaulted input is always present after defaults are applied.
+
+Prefer explicit descriptions because `/workflow inputs <name>`, `/workflow <name> --help`, and the input picker show them to the user. Runtime validation uses TypeBox `Value` and is strict for both top-level named runs and `ctx.workflow(...)` child calls: Atomic rejects unknown keys, missing required values, type mismatches, non-JSON-serializable values, and union/literal values outside the declared choices before the workflow body starts. It does not coerce strings like `"3"` to numbers; pass `count=3` or JSON numbers when a schema declares `Type.Number()`.
+
+In TypeScript workflow files, `.input(...)` also narrows `ctx.inputs` for better intellisense: required/defaulted `Type.String()` inputs are `string`, `Type.Number()` is `number`, `Type.Boolean()` is `boolean`, a `Type.Union([Type.Literal(...)])` select is the literal string union, and `Type.Optional(...)` inputs include `undefined`. Use `Static<typeof schema>` when you need the inferred TypeScript type of a schema directly.
+
+### Outputs
+
+Workflow outputs are runtime contracts for completed workflow runs and for parent workflows that call a child with `ctx.workflow(childWorkflow, ...)`. A workflow returns a JSON-serializable object from `.run()`, and `.output(key, schema?)` documents, validates, and exposes keys from that returned object. Primitives, arrays, `null`, functions, symbols, `undefined` properties, `NaN`, and infinite numbers fail validation.
+
+**Return convention:** 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.foo`, the child workflow's `.run()` must both declare `.output("foo", schema)` and return `{ foo: value }`. `result` is not special and is never added for you: to expose `result`, declare `.output("result", schema)` and return `{ result }` exactly 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`.
+
+`.output(...)` is a schema contract, not an automatic stage selector. To expose values from any stage, capture the stage/task/child result in normal TypeScript and return it from `.run()` under the desired key:
+
+```ts
+export default defineWorkflow("review-with-summary")
+  .output("research_summary", Type.String())
+  .output("review", Type.String())
+  .run(async (ctx) => {
+    const research = await ctx.task("research", { prompt: "Research the target." });
+    const review = await ctx.task("review", {
+      prompt: "Review using this research:\n\n{previous}",
+      previous: research,
+    });
+
+    return {
+      research_summary: research.text,
+      review: review.text,
+    };
+  })
+  .compile();
+```
+
+There is no automatic `result` output. A workflow exposes exactly the keys it declares with `.output(...)` and returns from `.run()` — nothing more. To expose `result`, declare `.output("result", schema)` and return `{ result }` like any other output. If `.run()` returns a key that was never declared with `.output(...)`, the run fails 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>"`).
+
+Outputs are declared with TypeBox `Type.*` schemas passed to `.output(key, schema)`. **Prefer precise schemas.** A precise schema gives a precise `Static<>` type for the `.run()` return and for any parent reading `child.outputs`, and it makes runtime validation enforce the real shape instead of waving values through. Reach for `Type.Unknown()`, `Type.Any()`, `Type.Array(Type.Unknown())`, or `Type.Object({}, { additionalProperties: true })` only for genuinely dynamic data whose shape you cannot know ahead of time.
+
+| TypeBox schema | Static type | Accepted runtime value |
+|---|---|---|
+| `Type.String({ ... })` | `string` | string |
+| `Type.Number({ ... })` | `number` | finite number |
+| `Type.Integer({ ... })` | `number` | integer |
+| `Type.Boolean({ ... })` | `boolean` | boolean |
+| `Type.Union([Type.Literal("a"), Type.Literal("b")], { ... })` | `"a" \| "b"` | one of the literal strings |
+| `Type.Array(Type.String())` | `string[]` | array of strings |
+| `Type.Object({ topic: Type.String(), score: Type.Number() })` | `{ topic: string; score: number }` | object matching that shape |
+| `Type.Unsafe<MyInterface>(runtimeSchema)` | `MyInterface` | whatever `runtimeSchema` accepts (escape hatch) |
+| `Type.Array(Type.Unknown())` | `unknown[]` | any JSON array (last resort, dynamic only) |
+| `Type.Object({}, { additionalProperties: true })` | `Record<string, unknown>` | any JSON object (last resort, dynamic only) |
+| `Type.Unknown()` / `Type.Any()` | `unknown` / `any` | any JSON-serializable value (last resort) |
+
+Output schemas carry `description` in their options object. A declared output is required when its schema is **not** wrapped in `Type.Optional(...)`; wrap outputs that may be absent in `Type.Optional(...)`. A required output means the workflow `.run()` return object must contain that output before the run can complete; a missing required output fails with `missing output "<key>"`, and a declared value whose runtime type does not match the schema fails with `output "<key>" expected <type>, got <actual>`. For child workflow calls, the parent boundary fails before the parent continues. Declared outputs are validated against the declared schema with TypeBox `Value` on completion, and every returned/exposed value is recursively validated as JSON-serializable. Child output replay still performs a structured-clone safety check after JSON validation so continuation can restore completed child workflow boundaries.
+
+#### Prefer precise schemas
+
+A loose output like `Type.Unknown()` or `Type.Object({}, { additionalProperties: true })` types the `.run()` return and `child.outputs.x` as `unknown`/`Record<string, unknown>`, so every consumer must cast or guard before using the value, and runtime validation only checks "is this JSON?" instead of the real shape. Declaring the shape fixes both at once:
+
+```ts
+// ❌ Loose: child.outputs.report is `unknown`; nothing checks the shape at runtime.
+.output("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()),
+  }),
+)
+```
+
+The same rule applies to inputs: `.input("counts", Type.Array(Type.Number()))` makes `ctx.inputs.counts` a `number[]`, while `Type.Array(Type.Unknown())` only gives you `unknown[]`.
+
+#### `Type.Unsafe<T>()` escape hatch for deeply-nested values
+
+When you already have a precise TypeScript interface for a deeply-nested serializable value and don't want to hand-write the equivalent TypeBox schema, wrap a permissive runtime schema with `Type.Unsafe<MyInterface>(...)`. The **static** type becomes exactly `MyInterface` (so `ctx.inputs`, the `.run()` return, and `child.outputs` stay precise), while the **runtime** check stays as lenient as the wrapped schema:
+
+```ts
+import { defineWorkflow, Type } from "@bastani/workflows";
+
+interface ResearchPacket {
+  readonly topic: string;
+  readonly score: number;
+  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) => {
+    const packet: ResearchPacket = {
+      topic: ctx.inputs.topic,
+      score: 1,
+      sections: [{ heading: "overview", body: "…" }],
+    };
+    return { packet }; // statically checked against ResearchPacket
+  })
+  .compile();
+```
+
+Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts that the produced value matches `T`. Use it when the producing code already guarantees the shape (the `contract-complex-leaf` contract workflow does exactly this, wrapping `Type.Unsafe<ComplexPacket>(...)` and `Type.Unsafe<readonly ComplexRecord[]>(...)` around permissive runtime schemas). 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 `Type.Object({}, { additionalProperties: true })` for the rare cases where the value is genuinely dynamic.
+
+#### How types flow
+
+- `ctx.inputs.x` is `Static<inputSchema>` for the input you declared with `.input("x", schema)` — required and defaulted schemas are always present, and `Type.Optional(...)` adds `| undefined`.
+- The `.run()` return is checked against your declared outputs at **compile time** (a missing required output or a wrong value type is a TypeScript error) and at **runtime** via TypeBox `Value` (undeclared keys are rejected and the declared shape is 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.
+
+Use `Static<typeof schema>` (both `Static` and `TSchema` are re-exported from `@bastani/workflows`) when you need the inferred TypeScript type of a schema directly — for example to type a helper that builds an output value.
+
+### Workflow Composition
+
+Use workflow composition when one workflow should call another reusable workflow and consume its outputs as a tracked boundary stage. The child can be a user-defined workflow from your project/package or a bundled builtin workflow. In both cases, use normal TypeScript imports: import the compiled child workflow definition, then pass that definition directly to `ctx.workflow(workflowDefinition, options)`. Registry names, path objects, and string aliases are not accepted by `ctx.workflow(...)`.
+
+For workflows intended to be called by parent workflows, declare `.output(...)` for every field a parent should rely on, including `result`. No output exists without declaration: a child exposes exactly its declared outputs, and returning an undeclared key fails the child call.
+
+#### Compose with a user-defined workflow
+
+User-defined workflows are ordinary TypeScript modules. Import the compiled definition with a relative module specifier and call it directly from the parent workflow:
+
+```ts
+// .atomic/workflows/shared-research.ts
+import { defineWorkflow, Type } from "@bastani/workflows";
+
+export default defineWorkflow("shared-research")
+  .input("topic", Type.String())
+  .output("summary", Type.String({ description: "Research summary markdown." }))
+  // Precise element type: child.outputs.sources is `string[] | undefined`, not `unknown[]`.
+  .output("sources", Type.Optional(Type.Array(Type.String(), { description: "Source URLs and file references." })))
+  .run(async (ctx) => {
+    const result = await ctx.task("research", { prompt: `Research ${String(ctx.inputs.topic)}` });
+    return { summary: result.text, sources: [] };
+  })
+  .compile();
+
+// .atomic/workflows/research-and-synthesize.ts
+import { defineWorkflow, Type } from "@bastani/workflows";
+import sharedResearch from "./shared-research.js";
+
+export default defineWorkflow("research-and-synthesize")
+  .input("topic", Type.String())
+  .output("final", Type.String({ description: "Synthesis built from the child research summary." }))
+  .output("child_run_id", Type.String({ description: "Run id of the nested shared-research child." }))
+  .run(async (ctx) => {
+    const child = await ctx.workflow(sharedResearch, {
+      inputs: { topic: ctx.inputs.topic },
+      stageName: "run shared research",
+    });
+
+    const final = await ctx.task("synthesize", {
+      prompt: `Synthesize:\n\n${String(child.outputs.summary)}`,
+    });
+    return { final: final.text, child_run_id: child.runId };
+  })
+  .compile();
+```
+
+#### Compose with builtin workflows
+
+Builtin workflows are also exported as compiled workflow definitions, so parent workflows can call them exactly like user-defined workflows. Use the barrel export when you want several builtins:
+
+```ts
+import { deepResearchCodebase, goal, openClaudeDesign, ralph } from "@bastani/workflows/builtin";
+```
+
+Or import one builtin from its individual module path:
+
+```ts
+import deepResearchCodebase from "@bastani/workflows/builtin/deep-research-codebase";
+import goal from "@bastani/workflows/builtin/goal";
+import openClaudeDesign from "@bastani/workflows/builtin/open-claude-design";
+import ralph from "@bastani/workflows/builtin/ralph";
+```
+
+Common builtin import targets:
+
+| Workflow name | TypeScript export | Individual module path | Typical use inside another workflow |
+|---|---|---|---|
+| `deep-research-codebase` | `deepResearchCodebase` | `@bastani/workflows/builtin/deep-research-codebase` | Gather broad repo research before planning, synthesis, or implementation. |
+| `goal` | `goal` | `@bastani/workflows/builtin/goal` | Run a bounded implementation/check loop with receipts and reviewer-gated completion. |
+| `ralph` | `ralph` | `@bastani/workflows/builtin/ralph` | Delegate a larger migration/refactor/spec-to-PR effort to Ralph's plan/orchestrate/review loop. |
+| `open-claude-design` | `openClaudeDesign` | `@bastani/workflows/builtin/open-claude-design` | Generate and refine a UI/design artifact and handoff spec. |
+
+Example parent workflow that runs builtin deep research, then chooses either `goal` or `ralph` as the nested implementation runner:
+
+```ts
+import { defineWorkflow, Type } from "@bastani/workflows";
+import { deepResearchCodebase, goal, ralph } from "@bastani/workflows/builtin";
+
+export default defineWorkflow("research-then-implement")
+  .input("topic", Type.String())
+  .input(
+    "runner",
+    Type.Union([Type.Literal("goal"), Type.Literal("ralph")], {
+      default: "goal",
+      description: "Use goal for bounded changes or Ralph for broad spec-to-PR work.",
+    }),
+  )
+  .output("research_doc_path", Type.String({ description: "Path to the deep-research document used for implementation." }))
+  .output("runner", Type.String({ description: "Which nested runner executed: \"goal\" or \"ralph\"." }))
+  // Genuinely dynamic: the nested runner (goal vs ralph) is chosen at runtime and
+  // each exposes a different declared output shape, so a loose object is appropriate here.
+  // When a child's outputs are known and fixed, declare the precise shape instead.
+  .output("implementation", Type.Object({}, { additionalProperties: true, description: "Declared outputs from the nested implementation workflow." }))
+  .run(async (ctx) => {
+    const topic = String(ctx.inputs.topic);
+    const research = await ctx.workflow(deepResearchCodebase, {
+      inputs: { prompt: topic, max_concurrency: 4 },
+      stageName: "deep research",
+    });
+
+    if (String(ctx.inputs.runner) === "ralph") {
+      const implementation = await ctx.workflow(ralph, {
+        inputs: {
+          prompt: `Use the research document at ${String(research.outputs.research_doc_path)} to plan, implement, review, and prepare a PR for: ${topic}`,
+        },
+        stageName: "ralph implementation",
+      });
+
+      return {
+        research_doc_path: research.outputs.research_doc_path,
+        runner: "ralph",
+        implementation: implementation.outputs,
+      };
+    }
+
+    const implementation = await ctx.workflow(goal, {
+      inputs: {
+        objective: `Use the research document at ${String(research.outputs.research_doc_path)} to implement and validate: ${topic}`,
+        max_turns: 3,
+      },
+      stageName: "goal implementation",
+    });
+
+    return {
+      research_doc_path: research.outputs.research_doc_path,
+      runner: "goal",
+      implementation: implementation.outputs,
+    };
+  })
+  .compile();
+```
+
+Passing a compiled definition directly to `ctx.workflow(...)` uses the child workflow's normalized name for replay metadata and default boundary labels (`shared-research` for the user-defined example above, or builtin names such as `deep-research-codebase`, `goal`, and `ralph`).
+
+`ctx.workflow(workflowDefinition)` starts a nested workflow behind a parent boundary stage named `workflow:<workflow-name>` by default. User-facing status and graph views flatten that child into the parent run, so composition behaves like inlining the child workflow code: child stages, HIL prompt nodes, and deeper imported workflows appear in one expanded graph. The nested run id remains available internally for routing attach/pause/interrupt/resume/kill to the correct live stage, but it is not shown as a separate top-level `/workflow status` entry. The returned child result has:
+
+| Field | Meaning |
+|---|---|
+| `workflow` | Normalized child workflow name. |
+| `runId` | Nested child run id. |
+| `status` | `completed` when the child workflow succeeds. Failed or interrupted children make the parent child call fail. |
+| `outputs` | Declared child outputs. |
+
+`ctx.workflow()` options:
+
+| Option | Meaning |
+|---|---|
+| `inputs` | Values validated against the child workflow's `.input()` schema before the child starts. |
+| `stageName` | Parent boundary stage label. Defaults to `workflow:<workflow-name>`. |
+
+Output exposure rules:
+
+```ts
+const child = await ctx.workflow(sharedResearch);
+child.outputs.summary; // declared by sharedResearch.output("summary", ...)
+child.outputs.sources; // declared by sharedResearch.output("sources", ...)
+```
+
+A child exposes exactly its declared outputs — the keys it declared with `.output(...)` and returned from `.run()`. There are no implicit outputs and no raw return-object passthrough. If `.run()` returns a key that was not declared with `.output(...)`, the child call fails with `atomic-workflows: workflow "<name>" returned undeclared output "<key>"; declare it with .output("<key>", Type....) or remove it from the .run() return` (surfaced through the parent as `... child "<alias>" returned undeclared output "<key>" from "<childName>"`). A child with no declared outputs therefore exposes no outputs. Missing required outputs, schema type mismatches, and non-JSON-serializable returned values fail the child workflow call before the parent continues.
+
+Only compiled workflow definitions can be passed to `ctx.workflow(...)`. Import reusable workflows with TypeScript `import` statements first; use `/workflow` names such as `goal` only for launching named runs, not as `ctx.workflow(...)` arguments. If a module is missing or does not export a compiled workflow definition, workflow discovery fails when loading that module. Nested child workflows count against `maxDepth` (default `4` total workflow levels).
 
-- `text` / `string`: optional `default: string`
-- `number`: optional `default: number`
-- `boolean`: optional `default: boolean`
-- `select`: required `choices: string[]`, optional `default: string`
+The graph includes both the parent boundary node and the imported child workflow's own stages while the child is loading/running, so the user can observe progress and interrupt sub-workflows before they complete. Completed boundaries still retain the child workflow name, child run id prefix, and exposed output count for replay/debugging. Use `stageName` when the parent needs a more specific label, but keep it concise so the child summary remains readable in the graph.
 
-All schemas support `description` and `required`. Prefer explicit descriptions because `/workflow inputs <name>`, `/workflow <name> --help`, and the input picker show them to the user. Runtime validation rejects unknown keys, missing required values, type mismatches, and select values outside `choices`; it does not coerce strings like `"3"` to numbers.
+Continuation replay treats the parent child-workflow boundary as the durable checkpoint: a previously completed child boundary replays with the original exposed outputs and without re-running the child, while a child that failed or was interrupted before completion starts again from the beginning on continuation.
 
 ## Workflow Primitives
 
@@ -762,6 +1119,7 @@ Prefer high-level primitives because they create tracked graph nodes, provide co
 | One LLM/session task with workflow tracking | `ctx.task(name, options)` |
 | Dependent sequential tasks | `ctx.chain(steps, options?)` |
 | Independent concurrent branches | `ctx.parallel(steps, options?)` |
+| Reusable child workflow | Call `ctx.workflow(workflowDefinition, options?)` |
 | Human input during a workflow run | `ctx.ui.input/confirm/select/editor` |
 | Pure deterministic computation, parsing, or file I/O | Plain TypeScript in `.run()` or helpers |
 | Fine-grained session control | `ctx.stage(name, options?)` |
@@ -804,10 +1162,11 @@ To bind user inputs to a workflow-wide worktree default, use the builder method:
 
 ```ts
 export default defineWorkflow("safe-implementation")
-  .input("task", { type: "text", required: true })
-  .input("git_worktree_dir", { type: "string", default: "" })
-  .input("base_branch", { type: "string", default: "origin/main" })
+  .input("task", Type.String())
+  .input("git_worktree_dir", Type.String({ default: "" }))
+  .input("base_branch", Type.String({ default: "origin/main" }))
   .worktreeFromInputs({ gitWorktreeDir: "git_worktree_dir", baseBranch: "base_branch" })
+  .output("result", Type.String({ description: "Implementation result text." }))
   .run(async (ctx) => {
     const result = await ctx.task("implement", { task: String(ctx.inputs.task) });
     return { result: result.text };
@@ -853,9 +1212,10 @@ The programmatic definition object mirrors the workflow tool for named runs (`mo
 Use `createRegistry()` when code needs to group definitions explicitly:
 
 ```ts
-import { createRegistry, defineWorkflow } from "@bastani/workflows";
+import { createRegistry, defineWorkflow, Type } from "@bastani/workflows";
 
 const alpha = defineWorkflow("alpha")
+  .output("text", Type.String({ description: "Alpha task output text." }))
   .run(async (ctx) => {
     const result = await ctx.task("alpha", { prompt: "Run alpha." });
     return { text: result.text };
@@ -990,6 +1350,7 @@ Before implementing or shipping a non-trivial workflow, answer these questions:
 - **Inputs:** Which values should be declared as inputs? What is the narrowest schema type? Which defaults are safe?
 - **Stage decomposition:** For each stage, what question does it answer, what context does it need, what output should it return, and what model/tool/MCP requirements does it have?
 - **Information flow:** For every edge between stages, is `previous` enough, or should the handoff use structured returns, files, `reads`, `output`, or `outputMode`?
+- **Output contract:** Which outputs should be declared with `.output(...)`, which stage/task/child results should `.run()` return for those keys, and what runtime type must each value have? If another workflow may call this workflow as a child, which non-default outputs should the parent rely on?
 - **Context size:** Can downstream stages succeed from the handoff alone? Should large transcripts, logs, or research bundles be summarized or saved as artifacts?
 - **Control flow:** Should the workflow use `ctx.chain`, `ctx.parallel`, `ctx.ui`, bounded loops, `failFast`, or `fallbackModels`?
 - **User experience:** Are stage names readable in status and graph views? Is the final output compact? Are important artifacts saved with stable paths?
@@ -1003,6 +1364,9 @@ Good workflows are information-flow systems, not just prompt sequences. Keep sta
 - Do not guess input keys; inspect with `inputs` or `get` first.
 - Do not call `create`, `update`, or `delete` on the workflow tool; definitions are code-authored.
 - Do not use legacy workflow tool fields like `agent`, `stage`, or run-control `name`.
+- Do not pass strings such as `"goal"` or path objects to `ctx.workflow(...)`; import the compiled workflow definition from `@bastani/workflows/builtin` or another TypeScript module first.
+- Do not rely on undeclared child outputs; returning a key that is not declared with `.output(...)` fails the run. Declare `.output(...)` for every child-workflow field you expose — including `result` — and return values matching those schemas from `.run()`.
+- Do not expect to select or rename child outputs at the call site; parent workflows receive the child's declared output contract as `child.outputs`.
 - Do not expect named workflow runs to block the chat turn; they are background tasks.
 - Do not call `kill` when the user asks to interrupt or pause resumably.
 - Keep stage names readable because they appear in workflow status and UI.