@bastani/atomic 0.5.12-4 → 0.5.12-5

package/.agents/skills/workflow-creator/references/getting-started.md

@@ -4,7 +4,7 @@ This guide covers the basics of creating workflows with the `defineWorkflow().ru
 
 ## Quick-start example
 
-Use `defineWorkflow<"agent">().run(callback).compile()` to define your workflow. Inside the `.run()` callback, use `ctx.stage()` to spawn agent sessions dynamically. Each session gets its own tmux window and graph node. Use native TypeScript control flow (`for`, `if`, `Promise.all()`) for orchestration.
+Use `defineWorkflow({...}).for<"agent">().run(callback).compile()` to define your workflow. Inside the `.run()` callback, use `ctx.stage()` to spawn agent sessions dynamically. Each session gets its own tmux window and graph node. Use native TypeScript control flow (`for`, `if`, `Promise.all()`) for orchestration.
 
 The runtime manages the full session lifecycle automatically — it creates the client, creates the session, runs your callback, then cleans up. You never need to manually disconnect or stop anything.
 
@@ -12,15 +12,17 @@ The runtime manages the full session lifecycle automatically — it creates the
 
 ```ts
 // .atomic/workflows/my-workflow/claude/index.ts
-import { defineWorkflow } from "@bastani/atomic/workflows";
+import { defineWorkflow, extractAssistantText } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
     name: "my-workflow",
     description: "A two-session pipeline",
+    inputs: [
+      { name: "prompt", type: "text", required: true, description: "task to perform" },
+    ],
   })
+  .for<"claude">()
   .run(async (ctx) => {
-    // Free-form workflow: the positional CLI prompt lands under
-    // `inputs.prompt`. Destructure once and close over it in stages.
     const prompt = ctx.inputs.prompt ?? "";
 
     const describe = await ctx.stage(
@@ -55,10 +57,14 @@ export default defineWorkflow<"claude">({
 // .atomic/workflows/my-workflow/copilot/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"copilot">({
+export default defineWorkflow({
     name: "my-workflow",
     description: "A two-session pipeline",
+    inputs: [
+      { name: "prompt", type: "text", required: true, description: "task to perform" },
+    ],
   })
+  .for<"copilot">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
@@ -94,10 +100,14 @@ export default defineWorkflow<"copilot">({
 // .atomic/workflows/my-workflow/opencode/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"opencode">({
+export default defineWorkflow({
     name: "my-workflow",
     description: "A two-session pipeline",
+    inputs: [
+      { name: "prompt", type: "text", required: true, description: "task to perform" },
+    ],
   })
+  .for<"opencode">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
@@ -172,7 +182,7 @@ const result = await ctx.stage(
     // s.client, s.session, s.save(), s.transcript() all work identically
     const result = await s.session.query("Analyze the codebase.");
     s.save(s.sessionId);
-    return result.output;
+    return extractAssistantText(result, 0);
   },
 );
 // result.result contains the returned value
@@ -208,7 +218,7 @@ Headless stages are transparent to graph topology — `seed → [3 headless] →
 The `@bastani/atomic/workflows` package exports the workflow authoring primitives. For native SDK types and utilities, install and import from the provider packages directly.
 
 **Builder:**
-- `defineWorkflow` — entry point, accepts an optional type parameter (`"claude"`, `"copilot"`, `"opencode"`) for type narrowing; returns a chainable `WorkflowBuilder`
+- `defineWorkflow` — entry point; returns a chainable `WorkflowBuilder`. Use `.for<"agent">()` on the builder to narrow types to a specific provider.
 - `WorkflowBuilder` — the builder class (rarely needed directly)
 
 **Types** (import with `import type`):
@@ -223,13 +233,16 @@ The `@bastani/atomic/workflows` package exports the workflow authoring primitive
 - `StageSessionOptions<A>` — provider-specific session create options for `ctx.stage()` third argument
 - `ProviderClient<A>` — the `s.client` type, resolved by agent type
 - `ProviderSession<A>` — the `s.session` type, resolved by agent type
-- `ClaudeSessionWrapper` — Atomic wrapper for Claude sessions (exposes `s.session.query()`)
+- `ClaudeSessionWrapper` — Atomic wrapper for Claude sessions (exposes `s.session.query()`, which returns `SessionMessage[]`)
 - `ClaudeQueryDefaults` — per-stage query defaults (timeouts, poll interval) for Claude sessions
 - `SessionRef` — `string | SessionHandle<unknown>` for transcript/message lookups
 - `WorkflowContext` — top-level context passed to `.run()` callback
 - `WorkflowOptions` — `{ name, description? }` workflow metadata
 - `WorkflowDefinition` — sealed output of `.compile()`
 
+**Response utilities:**
+- `extractAssistantText(messages, afterIndex)` — extract plain text from the `SessionMessage[]` returned by `s.session.query()` for Claude; use `extractAssistantText(result, 0)` to get the full assistant response text
+
 **Validation helpers:**
 - `validateClaudeWorkflow` — static validation for Claude workflow source files; warns on direct `createClaudeSession` or `claudeQuery` usage
 - `validateCopilotWorkflow` — static validation for Copilot workflow source files; warns on manual `new CopilotClient` or `client.createSession()` usage
@@ -251,7 +264,7 @@ The Atomic runtime provides `s.client` and `s.session` with types resolved from
 |-------|------|-------------|
 | `client` | `ProviderClient<A>` | Pre-created SDK client (auto-managed by runtime) |
 | `session` | `ProviderSession<A>` | Pre-created provider session (auto-managed by runtime) |
-| `inputs` | `Record<string, string>` | Structured inputs for this run. Free-form workflows read `s.inputs.prompt`; structured workflows read their declared field names. See `workflow-inputs.md`. |
+| `inputs` | `{ [K in N]?: string }` | Typed inputs for this run — only declared field names are valid keys. Accessing an undeclared field is a compile-time error. See `workflow-inputs.md`. |
 | `agent` | `AgentType` | Which agent is running |
 | `transcript(ref)` | `(ref: SessionRef) => Promise<Transcript>` | Get prior session's transcript as `{ path, content }` |
 | `getMessages(ref)` | `(ref: SessionRef) => Promise<SavedMessage[]>` | Get prior session's raw native messages |
@@ -286,4 +299,4 @@ Both include `helpers/` directories with SDK-agnostic logic (prompt builders, pa
 
 ## Type safety
 
-The SDK is typed with **no `unknown` or `any`**. `SessionContext` fields are precisely typed, and native provider types may appear inside Atomic generic aliases and runtime values — if you need to name those types in your own code, import them from the provider SDK directly. Use `import type` for type-only imports. Use the `defineWorkflow<"agent">()` type parameter to narrow `s.client` and `s.session` to the correct provider types.
+The SDK is typed with **no `unknown` or `any`**. `SessionContext` fields are precisely typed, and native provider types may appear inside Atomic generic aliases and runtime values — if you need to name those types in your own code, import them from the provider SDK directly. Use `import type` for type-only imports. Use `.for<"agent">()` to narrow `s.client` and `s.session` to the correct provider types. Declare `inputs` inline so TypeScript enforces typed access on `ctx.inputs`.

package/.agents/skills/workflow-creator/references/session-config.md

@@ -20,11 +20,13 @@ await ctx.stage({ name: "..." }, {
 ### Session options (`sessionOpts` — 3rd arg to `ctx.stage()`)
 
 These are `ClaudeQueryDefaults` and set defaults for every `s.session.query()`
-call inside the callback (`timeoutMs`, `pollIntervalMs`, etc.):
+call inside the callback. The available fields are: `pollIntervalMs`,
+`submitPresses`, `maxSubmitRounds`, `readyTimeoutMs`. Note that `timeoutMs` no
+longer exists — idle detection is automatic (pane capture for interactive
+stages, SDK streaming for headless stages).
 
 ```ts
 await ctx.stage({ name: "..." }, {}, {
-  timeoutMs: 5 * 60 * 1000,     // 5 minutes per query (default)
   pollIntervalMs: 1_000,         // Poll interval for output
 }, async (s) => {
   await s.session.query((ctx.inputs.prompt ?? ""));
@@ -101,15 +103,34 @@ const result = query({
 the pane ID from `s.paneId` automatically. Call it inside the stage callback:
 
 ```ts
+import { extractAssistantText } from "@anthropic-ai/claude-agent-sdk";
+
 await ctx.stage({ name: "..." }, {}, {}, async (s) => {
   const result = await s.session.query("Your prompt");
-  // result.output — captured response text
+  // extractAssistantText(result, 0) — extract assistant text from the result
+  const text = extractAssistantText(result, 0);
   s.save(s.sessionId);
 });
 ```
 
-The query defaults (timeout, poll interval) can be configured via `sessionOpts`
-as shown above.
+The query defaults (poll interval, submit presses, etc.) can be configured via
+`sessionOpts` as shown above.
+
+For **headless stages**, SDK options (such as `permissionMode`, `agent`,
+`allowDangerouslySkipPermissions`) can be passed directly as the second
+argument to `s.session.query()`:
+
+```ts
+await ctx.stage({ name: "..." }, {}, {}, async (s) => {
+  const result = await s.session.query("Your prompt", {
+    permissionMode: "bypassPermissions",
+    allowDangerouslySkipPermissions: true,
+    agent: "worker",
+  });
+  const text = extractAssistantText(result, 0);
+  s.save(s.sessionId);
+});
+```
 
 ### Claude hooks
 

package/.agents/skills/workflow-creator/references/state-and-data-flow.md

@@ -114,13 +114,13 @@ Use closures and variables for state within a single session:
       );
 
       // Accumulate findings
-      const review = parseReviewResult(result.output);
+      const review = parseReviewResult(extractAssistantText(result, 0));
       if (review) {
         findings.push(...review.findings.map(f => f.title));
       }
 
       // Track clean streak
-      if (!hasActionableFindings(review, result.output)) {
+      if (!hasActionableFindings(review, extractAssistantText(result, 0))) {
         consecutiveClean++;
         if (consecutiveClean >= 2) break;
         continue;
@@ -129,7 +129,7 @@ Use closures and variables for state within a single session:
 
       // Apply fix
       const fixResult = await s.session.query(buildFixSpec(review, (ctx.inputs.prompt ?? "")));
-      priorOutput = fixResult.output;
+      priorOutput = extractAssistantText(fixResult, 0);
     }
 
     // All local state is available here

package/.agents/skills/workflow-creator/references/workflow-inputs.md

@@ -2,20 +2,22 @@
 
 Workflows collect structured data from the user at invocation time through
 a single uniform API: `ctx.inputs` (and `s.inputs` inside stage
-callbacks). This reference covers how the inputs pipe works, when to
-declare a schema vs. rely on the free-form fallback, and how values
-reach the workflow from the CLI and the interactive picker.
+callbacks). This reference covers how the inputs pipe works, how to
+declare input schemas, and how values reach the workflow from the CLI
+and the interactive picker.
 
 ## The inputs pipe
 
-Every workflow run receives a `Record<string, string>` of inputs. The
+Every workflow run receives a typed inputs object. When the workflow
+declares an `inputs` schema, only the declared field names are valid
+keys — accessing undeclared fields is a compile-time error. The
 runtime populates it from whichever invocation surface the user chose:
 
 | Surface | How values are supplied | How they land in `ctx.inputs` |
 |---|---|---|
-| **Named run, positional** — `atomic workflow -n hello -a claude "fix the bug"` | A single positional prompt string | `{ prompt: "fix the bug" }` |
+| **Named run, positional** — `atomic workflow -n hello -a claude "fix the bug"` | A single positional prompt string (the workflow must declare a `prompt` input) | `{ prompt: "fix the bug" }` |
 | **Named run, structured** — `atomic workflow -n gen-spec -a claude --research_doc=notes.md --focus=standard` | One `--<field>=<value>` flag per declared input | `{ research_doc: "notes.md", focus: "standard" }` |
-| **Interactive picker** — `atomic workflow -a claude` | The user fills in a form rendered from the declared schema (or the default `prompt` field if the workflow is free-form) | Whatever the user typed, keyed by field name |
+| **Interactive picker** — `atomic workflow -a claude` | The user fills in a form rendered from the declared schema | Whatever the user typed, keyed by field name |
 
 Workflow code is the same either way — it always reads
 `ctx.inputs.<name>`. The invocation surface is a CLI concern, not a
@@ -23,12 +25,19 @@ workflow concern.
 
 ## Reading inputs
 
-For free-form workflows (no declared schema), the positional prompt
-lands under the reserved `prompt` key. Destructure it once at the top of
-`.run()` so every stage can close over a bare string:
+Workflows that accept a user prompt should declare it explicitly as an
+input. Destructure it once at the top of `.run()` so every stage can
+close over a bare string:
 
 ```ts
-defineWorkflow<"claude">({ name: "answer", description: "Single-turn answer" })
+defineWorkflow({
+    name: "answer",
+    description: "Single-turn answer",
+    inputs: [
+      { name: "prompt", type: "text", required: true, description: "question to answer" },
+    ],
+  })
+  .for<"claude">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
@@ -45,7 +54,7 @@ out of `ctx.inputs` once for readability and so downstream stages can
 close over locals:
 
 ```ts
-defineWorkflow<"claude">({
+defineWorkflow({
     name: "gen-spec",
     description: "Convert a research doc into a detailed execution spec",
     inputs: [
@@ -60,6 +69,7 @@ defineWorkflow<"claude">({
       { name: "notes", type: "text" },
     ],
   })
+  .for<"claude">()
   .run(async (ctx) => {
     const { research_doc, focus } = ctx.inputs;
     const notes = ctx.inputs.notes ?? "";
@@ -99,7 +109,7 @@ interface WorkflowInput {
   /** Default value — enums use this to pick their initial value. */
   default?: string;
   /** Allowed values — required when `type` is `"enum"`. */
-  values?: string[];
+  values?: readonly string[];
 }
 ```
 
@@ -147,35 +157,29 @@ This validation runs before any workflow code, so a malformed
 invocation can never reach your `.run()` callback in a half-filled
 state.
 
-## Free-form vs structured: when to use which
+## Declaring a prompt input
 
-Choose **free-form** (no `inputs` field on `defineWorkflow`) when:
+Workflows that accept a user prompt should declare it explicitly in their
+`inputs` array rather than relying on an implicit key:
 
-- The workflow takes a single unstructured request that varies widely
-  in phrasing — "find the bug", "build me a chart", "refactor the auth
-  module".
-- You want the simplest possible CLI surface.
-- The workflow's first LLM call will do its own intent extraction from
-  the raw prompt.
-
-Read the prompt via `ctx.inputs.prompt ?? ""`.
+```ts
+inputs: [
+  { name: "prompt", type: "text", required: true, description: "task to perform" },
+]
+```
 
-Choose **structured** (declared `inputs: [...]`) when:
+This gives the same CLI ergonomics — `atomic workflow -n hello -a claude "fix the bug"` still works — while providing compile-time safety. Accessing `ctx.inputs.prompt` without declaring it is a type error.
 
-- Several distinct fields are always needed — a file path + a focus
-  level + optional notes, for example.
-- You want the picker to show a real form (each field, its type, and
-  any validation cues) instead of a single blob text area.
-- You want the CLI to reject bad inputs before spawning a workflow —
-  e.g. a nonexistent enum value.
-- You want the invocation to be scriptable and auditable — flag-based
-  invocation reads cleanly in CI.
+For workflows that need both a free-form prompt AND structured parameters,
+declare all fields in the schema:
 
-Structured workflows can also include a `prompt` field in their schema
-if they need both a free-form request AND structured parameters. The
-`prompt` key is not magic for structured workflows — it's just a
-conventional name. You only get "positional maps to `prompt`" behavior
-when the workflow has no schema at all.
+```ts
+inputs: [
+  { name: "prompt", type: "text", required: true, description: "what to build" },
+  { name: "focus", type: "enum", required: true, values: ["minimal", "standard", "exhaustive"], default: "standard" },
+  { name: "notes", type: "text", description: "extra context" },
+]
+```
 
 ## The interactive picker
 
@@ -187,8 +191,7 @@ picker. The picker:
 2. Loads each workflow's metadata (description + declared inputs).
 3. Shows a Telescope-style fuzzy list. The user types to filter,
    arrows to navigate, ↵ to lock in a selection.
-4. Renders the selected workflow's form. Free-form workflows get a
-   single `prompt` text field; structured workflows get one field
+4. Renders the selected workflow's form. The picker renders one field
    per declared input with type-specific rendering.
 5. Validates required fields on ⌃s. If any are empty, focus jumps to
    the first invalid field and the run button stays disabled.
@@ -246,18 +249,20 @@ Both `--flag=value` and `--flag value` forms are accepted. Short flags
 
 ## Pitfalls
 
-### Don't expect `inputs.prompt` on structured workflows
+### Declare every field you access
 
-A structured workflow that doesn't declare a `prompt` field will have
-`ctx.inputs.prompt === undefined`. The CLI also rejects a positional
-prompt for structured workflows outright — if you try
-`atomic workflow -n gen-spec -a claude "some text"` you'll get:
+With typed inputs, accessing `ctx.inputs.foo` when `foo` is not declared
+in the workflow's `inputs` array is a compile-time error. If your workflow
+needs a prompt field, declare it:
 
-> Error: workflow 'gen-spec' takes structured inputs — pass them as
-> `--<name>=<value>` flags instead of a positional prompt.
+```ts
+inputs: [
+  { name: "prompt", type: "text", required: true, description: "task prompt" },
+]
+```
 
-If your workflow wants both a free-form prompt AND structured fields,
-declare `prompt` as a `text` input explicitly in the schema.
+The CLI rejects positional prompt strings for workflows that don't declare
+a `prompt` input.
 
 ### Don't rename inputs across workflow versions
 

package/README.md

@@ -78,8 +78,9 @@ Each of these is a `.ts` file using Atomic's [Workflow SDK](#workflow-sdk--build
       - [Saving Transcripts](#saving-transcripts)
       - [Per-Agent Session APIs](#per-agent-session-apis)
       - [Key Rules](#key-rules)
-    - [Deep Codebase Research](#deep-codebase-research)
+    - [Research Codebase](#research-codebase)
     - [Autonomous Execution (Ralph)](#autonomous-execution-ralph)
+    - [Deep Research Codebase](#deep-research-codebase)
     - [Containerized Execution](#containerized-execution)
     - [Specialized Sub-Agents](#specialized-sub-agents)
     - [Built-in Skills](#built-in-skills)
@@ -258,10 +259,10 @@ Here's one of the [canonical use cases](#what-you-can-build) — a team pipeline
 // .atomic/workflows/review-to-merge/claude/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
   name: "review-to-merge",
   description: "Review → CI → PR → Notify → Approve → Merge",
-})
+}).for<"claude">()
   .run(async (ctx) => {
     // Step 1: Review the changes
     const review = await ctx.stage(
@@ -368,10 +369,11 @@ atomic workflow -n my-workflow -a claude "describe this project"
 // .atomic/workflows/my-workflow/claude/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
   name: "my-workflow",
   description: "Two-session pipeline: describe -> summarize",
-})
+  inputs: [{ name: "prompt", type: "text", required: true, description: "task prompt" }],
+}).for<"claude">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
@@ -407,10 +409,11 @@ export default defineWorkflow<"claude">({
 ```ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
   name: "parallel-demo",
   description: "describe -> [summarize-a, summarize-b] -> merge",
-})
+  inputs: [{ name: "prompt", type: "text", required: true, description: "task prompt" }],
+}).for<"claude">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
@@ -458,7 +461,7 @@ Declare an `inputs` array on `defineWorkflow` and the CLI materialises one `--<f
 // .atomic/workflows/gen-spec/claude/index.ts
 import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
   name: "gen-spec",
   description: "Convert a research doc into an execution spec",
   inputs: [
@@ -483,7 +486,7 @@ export default defineWorkflow<"claude">({
       description: "extra guidance for the spec writer (optional)",
     },
   ],
-})
+}).for<"claude">()
   .run(async (ctx) => {
     // Read each declared field by name.
     const { research_doc, focus } = ctx.inputs;
@@ -520,12 +523,13 @@ atomic workflow -a claude
 Stages can run in **headless mode** (`headless: true`) — they execute the provider SDK in-process instead of spawning a tmux window. Headless stages are invisible in the workflow graph but tracked via a background task counter in the statusline. Use them for parallel data-gathering tasks that don't need a visible TUI.
 
 ```ts
-import { defineWorkflow } from "@bastani/atomic/workflows";
+import { defineWorkflow, extractAssistantText } from "@bastani/atomic/workflows";
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
   name: "headless-demo",
   description: "seed -> [3 headless background] -> merge",
-})
+  inputs: [{ name: "prompt", type: "text", required: true, description: "task prompt" }],
+}).for<"claude">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
 
@@ -536,7 +540,7 @@ export default defineWorkflow<"claude">({
       async (s) => {
         const result = await s.session.query(prompt);
         s.save(s.sessionId);
-        return String(result.output ?? "");
+        return extractAssistantText(result, 0);
       },
     );
 
@@ -545,17 +549,17 @@ export default defineWorkflow<"claude">({
       ctx.stage({ name: "pros", headless: true }, {}, {}, async (s) => {
         const r = await s.session.query(`List 3 pros:\n\n${seed.result}`);
         s.save(s.sessionId);
-        return String(r.output ?? "");
+        return extractAssistantText(r, 0);
       }),
       ctx.stage({ name: "cons", headless: true }, {}, {}, async (s) => {
         const r = await s.session.query(`List 3 cons:\n\n${seed.result}`);
         s.save(s.sessionId);
-        return String(r.output ?? "");
+        return extractAssistantText(r, 0);
       }),
       ctx.stage({ name: "uses", headless: true }, {}, {}, async (s) => {
         const r = await s.session.query(`List 3 use cases:\n\n${seed.result}`);
         s.save(s.sessionId);
-        return String(r.output ?? "");
+        return extractAssistantText(r, 0);
       }),
     ]);
 
@@ -625,29 +629,29 @@ Use your workflow-creator skill to create a workflow that plans, implements, and
 
 #### WorkflowContext (`ctx`) — top-level orchestrator
 
-| Property                                       | Type                        | Description                                                                                                                                                                             |
-| ---------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ctx.inputs`                                   | `Record<string, string>`    | Structured inputs for this run. Free-form workflows store their positional prompt under `ctx.inputs.prompt`; workflows with a declared `inputs` schema store one key per declared field |
-| `ctx.agent`                                    | `AgentType`                 | Which agent is running (`"claude"`, `"copilot"`, `"opencode"`)                                                                                                                          |
-| `ctx.stage(opts, clientOpts, sessionOpts, fn)` | `Promise<SessionHandle<T>>` | Spawn a session — returns handle with `name`, `id`, `result`                                                                                                                            |
-| `ctx.transcript(ref)`                          | `Promise<Transcript>`       | Get a completed session's transcript (`{ path, content }`)                                                                                                                              |
-| `ctx.getMessages(ref)`                         | `Promise<SavedMessage[]>`   | Get a completed session's raw native messages                                                                                                                                           |
+| Property                                       | Type                        | Description                                                                                                                                                                                        |
+| ---------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.inputs`                                   | `{ [K in N]?: string }`     | Typed inputs for this run — only declared field names are valid keys. Accessing an undeclared field is a compile-time error. Workflows that need a prompt must declare it in their `inputs` schema |
+| `ctx.agent`                                    | `AgentType`                 | Which agent is running (`"claude"`, `"copilot"`, `"opencode"`)                                                                                                                                     |
+| `ctx.stage(opts, clientOpts, sessionOpts, fn)` | `Promise<SessionHandle<T>>` | Spawn a session — returns handle with `name`, `id`, `result`                                                                                                                                       |
+| `ctx.transcript(ref)`                          | `Promise<Transcript>`       | Get a completed session's transcript (`{ path, content }`)                                                                                                                                         |
+| `ctx.getMessages(ref)`                         | `Promise<SavedMessage[]>`   | Get a completed session's raw native messages                                                                                                                                                      |
 
 #### SessionContext (`s`) — inside each session callback
 
-| Property                                     | Type                        | Description                                                                                                                              |
-| -------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `s.client`                                   | `ProviderClient<A>`         | Pre-created SDK client (auto-managed by runtime)                                                                                         |
-| `s.session`                                  | `ProviderSession<A>`        | Pre-created provider session (auto-managed by runtime)                                                                                   |
-| `s.inputs`                                   | `Record<string, string>`    | Same inputs record as `ctx.inputs`, forwarded into every stage so session callbacks can read values without closing over the outer `ctx` |
-| `s.agent`                                    | `AgentType`                 | Which agent is running                                                                                                                   |
-| `s.paneId`                                   | `string`                    | tmux pane ID for this session                                                                                                            |
-| `s.sessionId`                                | `string`                    | Session UUID                                                                                                                             |
-| `s.sessionDir`                               | `string`                    | Path to this session's storage directory on disk                                                                                         |
-| `s.save(messages)`                           | `SaveTranscript`            | Save this session's output for subsequent sessions                                                                                       |
-| `s.transcript(ref)`                          | `Promise<Transcript>`       | Get a completed session's transcript                                                                                                     |
-| `s.getMessages(ref)`                         | `Promise<SavedMessage[]>`   | Get a completed session's raw native messages                                                                                            |
-| `s.stage(opts, clientOpts, sessionOpts, fn)` | `Promise<SessionHandle<T>>` | Spawn a nested sub-session (child in the graph)                                                                                          |
+| Property                                     | Type                        | Description                                                                                                                             |
+| -------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `s.client`                                   | `ProviderClient<A>`         | Pre-created SDK client (auto-managed by runtime)                                                                                        |
+| `s.session`                                  | `ProviderSession<A>`        | Pre-created provider session (auto-managed by runtime)                                                                                  |
+| `s.inputs`                                   | `{ [K in N]?: string }`     | Same typed inputs as `ctx.inputs`, forwarded into every stage so session callbacks can read values without closing over the outer `ctx` |
+| `s.agent`                                    | `AgentType`                 | Which agent is running                                                                                                                  |
+| `s.paneId`                                   | `string`                    | tmux pane ID for this session                                                                                                           |
+| `s.sessionId`                                | `string`                    | Session UUID                                                                                                                            |
+| `s.sessionDir`                               | `string`                    | Path to this session's storage directory on disk                                                                                        |
+| `s.save(messages)`                           | `SaveTranscript`            | Save this session's output for subsequent sessions                                                                                      |
+| `s.transcript(ref)`                          | `Promise<Transcript>`       | Get a completed session's transcript                                                                                                    |
+| `s.getMessages(ref)`                         | `Promise<SavedMessage[]>`   | Get a completed session's raw native messages                                                                                           |
+| `s.stage(opts, clientOpts, sessionOpts, fn)` | `Promise<SessionHandle<T>>` | Spawn a nested sub-session (child in the graph)                                                                                         |
 
 #### Session Options (`SessionRunOptions`)
 
@@ -691,9 +695,12 @@ The runtime auto-creates `s.client` and `s.session` — use them directly inside
 
 For the authoring walkthrough with worked examples, ask Atomic to use the `workflow-creator` skill or read the skill reference at `.agents/skills/workflow-creator/`.
 
+> [!TIP]
+> **Keeping workflows up to date:** When the Workflow SDK is updated (new return types, new options, deprecated patterns), you can ask the `workflow-creator` skill to migrate your existing workflows to the latest best practices. Just open your workflow file and ask: _"Update this workflow to use the latest SDK patterns."_ The skill stays current with the SDK and will apply the right changes automatically.
+
 </details>
 
-### Deep Codebase Research
+### Research Codebase
 
 The `/research-codebase` command dispatches **specialized sub-agents in parallel** to analyze your codebase:
 
@@ -752,7 +759,7 @@ Research outputs persist in your `research/` directory and specs persist in your
   <img src="assets/ralph-wiggum.jpg" alt="Ralph Wiggum" width="600">
 </p>
 
-The [Ralph Wiggum Method](https://ghuntley.com/ralph/) enables **multi-hour autonomous coding sessions**. After approving your spec, let Ralph work in the background while you focus on other tasks.
+The [Ralph Method](https://ghuntley.com/ralph/) enables **multi-hour autonomous coding sessions**. After approving your spec, let Ralph work in the background while you focus on other tasks.
 
 **How Ralph works:**
 
@@ -778,6 +785,21 @@ cd ../my-project-ralph
 atomic workflow -n ralph -a claude "Build the auth module"
 ```
 
+### Deep Research Codebase
+
+Atomic also ships with `deep-research-codebase`, a built-in workflow that performs **multi-agent parallel research** across your codebase. While `/research-codebase` is a single-shot command, the `deep-research-codebase` workflow is a full multi-stage pipeline:
+
+1. **Scout** — A single agent scans the codebase structure and produces an architectural orientation
+2. **History** — A parallel agent surfaces prior research from `research/docs/`
+3. **Explorers** — Multiple parallel agents (count scaled by LOC) each investigate a partition of the codebase, writing findings to scratch files
+4. **Aggregator** — A final agent synthesizes all explorer reports + history into a dated research document at `research/docs/YYYY-MM-DD-<slug>.md`
+
+```bash
+atomic workflow -n deep-research-codebase -a claude "How does the authentication system work?"
+```
+
+The workflow produces a permanent research artifact that can be referenced by future runs, specs, or other workflows.
+
 ### Containerized Execution
 
 Atomic ships as **devcontainer features** that bundle the CLI, agent, and all dependencies into isolated containers. This is the recommended way to run autonomous agents safely.
@@ -1043,7 +1065,7 @@ atomic chat -a claude --verbose              # Forward --verbose to claude
 | `-n, --name <name>`  | Workflow name (matches directory under `.atomic/workflows/<name>/`)                               |
 | `-a, --agent <name>` | Agent: `claude`, `opencode`, `copilot`                                                            |
 | `--<field>=<value>`  | Structured input for workflows that declare an `inputs` schema (also accepts `--<field> <value>`) |
-| `[prompt...]`        | Positional prompt for free-form workflows (rejected on workflows with a declared schema)          |
+| `[prompt...]`        | Positional prompt — requires the workflow to declare a `prompt` input                             |
 
 The workflow command supports four invocation shapes:
 
@@ -1057,7 +1079,7 @@ atomic workflow list -a claude       # filter by agent
 #    and confirm with y/n
 atomic workflow -a claude
 
-# 3. Run a free-form workflow with a positional prompt
+# 3. Run a workflow with a positional prompt (workflow must declare a "prompt" input)
 atomic workflow -n ralph -a claude "build a REST API for user management"
 
 # 4. Run a structured-input workflow with one --<field> flag per declared input
@@ -1066,7 +1088,7 @@ atomic workflow -n gen-spec -a claude \
   --focus=standard
 ```
 
-Workflows that declare an `inputs: WorkflowInput[]` schema get CLI flag validation for free — missing required fields and invalid enum values are rejected before any tmux session is spawned, with error messages that spell out the expected flag set. Workflows that don't declare a schema still accept a single positional prompt, which the runtime stores under `ctx.inputs.prompt`. **Builtin workflows (like `ralph`) are reserved names** — a local or global workflow with the same name will not shadow a builtin at resolution time.
+Workflows that declare an `inputs: WorkflowInput[]` schema get CLI flag validation for free — missing required fields and invalid enum values are rejected before any tmux session is spawned, with error messages that spell out the expected flag set. Workflows that declare a `prompt` input accept a positional prompt on the command line, which the runtime stores under `ctx.inputs.prompt`. **Builtin workflows (like `ralph`) are reserved names** — a local or global workflow with the same name will not shadow a builtin at resolution time.
 
 #### `atomic completions` — Shell Completions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.5.12-4",
+  "version": "0.5.12-5",
   "description": "Configuration management CLI and SDK for coding agents",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,7 @@
     "typescript-language-server": "^5.1.3"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.107",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.108",
     "@clack/prompts": "^1.2.0",
     "@commander-js/extra-typings": "^14.0.0",
     "@github/copilot-sdk": "^0.2.2",