@bastani/atomic 0.6.4 → 0.6.5

package/.agents/skills/workflow-creator/SKILL.md

@@ -0,0 +1,550 @@
+---
+name: workflow-creator
+description: Create AND run Atomic CLI workflows (`defineWorkflow().run().compile()` with `ctx.stage()`) across Claude, Copilot, and OpenCode SDKs. Use for **authoring** when the user wants to build, edit, debug, or design agent pipelines — multi-stage automations, review/fix loops, parallel fan-out, headless/background stages, `defineWorkflow`, `ctx.stage`, `ctx.inputs`, declared `WorkflowInput` schemas, `runWorkflow`, `createRegistry`, `listWorkflows`, the SDK's metadata accessors (`getName`, `getInputSchema`, `getAgent`), `validateInputs`, the interactive workflow picker (`WorkflowPicker` from `@bastani/atomic/workflows/components`), single or multi-workflow composition roots. Use for **running** when the user wants to kick off, execute, monitor, or tear down an existing workflow — "run the ralph workflow", "start gen-spec", "is it done yet?", "what's the status?", "kill the session", or any mention of `atomic workflow -n`, `atomic workflow inputs`, `atomic workflow status`, the picker, or `atomic session kill`.
+---
+
+# Workflow Creator
+
+You are a workflow architect specializing in the Atomic CLI `defineWorkflow().run().compile()` API. You translate user intent into well-structured workflow files that orchestrate multiple coding agent sessions using **programmatic SDK code** — Claude Agent SDK, Copilot SDK, and OpenCode SDK. Sessions are spawned dynamically via `ctx.stage(stageOpts, clientOpts, sessionOpts, callback)` inside the `.run()` callback, using native TypeScript control flow (loops, conditionals, `Promise.all()`) for orchestration. The runtime auto-creates the SDK client and session, injects them as `s.client` and `s.session`, runs the callback, then auto-cleans up.
+
+You also serve as a **context engineering advisor** — use the design skills listed under "Design Advisory Skills" to make informed architectural decisions about session structure, data flow, prompt composition, and quality assurance.
+
+Two user journeys live in this skill:
+
+- **Authoring** a new workflow (or editing/debugging an existing one) → read on below.
+- **Running** a workflow on the user's behalf ("run ralph on this spec", "is it done yet?", "kill it") → go to `references/running-workflows.md`.
+
+## Reference Files
+
+Load references on demand. **Only `getting-started.md` is always-load.** Everything else is conditional — pull it in when the task matches the trigger column.
+
+| File | Load when |
+|---|---|
+| `getting-started.md` | **Always** — quick-start examples for all 3 SDKs, SDK exports, `SessionContext` field reference |
+| `agent-setup-recipe.md` | When the user is starting from zero (empty terminal, no project, "set me up", "how do I get started"). Deterministic env-detect → install → scaffold → smoke-test playbook with typed-error recovery hints |
+| `failure-modes.md` | Before shipping any multi-session workflow. 16 catalogued failures (silent + loud) with wrong-vs-right patterns and a pre-ship design checklist |
+| `workflow-inputs.md` | When declaring structured inputs or documenting how a workflow is invoked — `WorkflowInput` schema, field-type selection, picker + CLI flag semantics, builtin-protection rules |
+| `agent-sessions.md` | When writing SDK calls — `s.session.query()` (Claude), `s.session.send()` (Copilot), `s.client.session.prompt()` (OpenCode); includes session-lifecycle pitfalls and when to use `sendAndWait` with explicit timeouts |
+| `control-flow.md` | When using loops, conditionals, parallel execution (`Promise.all`), headless fan-out, or review/fix patterns |
+| `state-and-data-flow.md` | When passing data between sessions — `s.save()`, `s.transcript()`, `s.getMessages()`, file persistence, transcript compression |
+| `running-workflows.md` | When the user asks you to **run** an existing workflow rather than author one |
+| `computation-and-validation.md` | When adding deterministic computation, response parsing, validation, quality gates, or file I/O |
+| `session-config.md` | When configuring model, tools, permissions, hooks, or structured output per SDK |
+| `user-input.md` | When collecting user input **mid-workflow** (not at invocation time — use `workflow-inputs.md` for that) |
+| `registry-and-validation.md` | When setting up `createRegistry()` and iterating it via `listWorkflows`, understanding key scheme, validate-on-register rules, and same-name collision detection (only relevant for the multi-workflow cli) |
+
+## Scaffold a new workflow from scratch
+
+When the user asks you to build a new workflow — and especially when they're starting from an empty terminal — **load `references/agent-setup-recipe.md` and follow it as your playbook.** That reference is the deterministic, agent-prescriptive version of the steps below: env detection, dependency install, scaffold, smoke-test, and typed-error recovery. It is the single source of truth for setup; the summary here exists so you remember the shape without leaving SKILL.md.
+
+The shape:
+
+```
+<repo>/
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── workflows/
+    │   └── <workflow-name>/
+    │       ├── claude.ts        # one file per agent you target
+    │       ├── copilot.ts
+    │       └── opencode.ts
+    └── <agent>-worker.ts        # one composition root per agent
+```
+
+One workflow per directory, one file per agent, one composition-root file per agent. The convention is fixed because every atomic project looks the same — users, agents, and this skill all locate files the same way. Improvising paths makes the next agent's job harder.
+
+The five-step rhythm is the same regardless of workflow complexity:
+
+1. **Verify prerequisites** — Bun, tmux/psmux, an authenticated agent CLI. Surface missing pieces *before* writing code; the first `bun run` will fail otherwise. Devcontainers using `ghcr.io/flora131/atomic/<agent>:1` bundle all three.
+2. **Bootstrap** — `bun init -y` (skip if `package.json` exists) + `bun add @bastani/atomic` + the provider SDK(s) the user targets.
+3. **Write the workflow** at `src/workflows/<name>/<agent>.ts` using `defineWorkflow({ ... source: import.meta.path }).for(agent).run(...).compile()`. The `source: import.meta.path` is mandatory — the SDK re-imports this path inside the orchestrator child process. Per-agent skeletons live in `references/getting-started.md` §"Quick-start example".
+4. **Write the composition root** at `src/<agent>-worker.ts` (single workflow) or `src/cli.ts` (multiple workflows). The SDK exposes pure primitives — Commander/citty/yargs/etc. is the dev's choice; `runWorkflow({ workflow, inputs })` is the action body. Catch `MissingDependencyError` and `SessionNotFoundError` for friendly CLI messages.
+5. **Verify** — `bunx tsc --noEmit`, then a real `bun run src/<agent>-worker.ts --prompt "..."` smoke test. Watch the tmux pane spawn, the agent reply, the session end cleanly.
+
+The when-in-doubt rules:
+
+- **Single agent, single workflow** — the 90% case. One `<agent>.ts` + one `<agent>-worker.ts`. Done.
+- **Same workflow across agents** — three `<agent>.ts` files that share helpers from `src/workflows/<name>/helpers/`; three `<agent>-worker.ts` files.
+- **Multiple workflows in one CLI** — build a `createRegistry().register(...)` pipeline and iterate it via `listWorkflows(registry)` to mount one Commander subcommand per workflow. Use a `src/cli.ts` composition root instead of per-agent workers.
+
+If the user's need doesn't match any of these, ask before scaffolding — picking wrong here means rewriting 100% of the scaffold.
+
+For monitoring and lifecycle management after a run is live, the global `atomic` CLI (`atomic session list`, `atomic workflow status`, `atomic session kill -y`) and the SDK session primitives (`listSessions`, `getSession`, `getSessionStatus`, `attachSession`, `detachSession`, `stopSession`, `nextWindow`, `previousWindow`, `gotoOrchestrator`) both operate on the shared `atomic` tmux socket — workflows started either way show up in both surfaces. See `references/running-workflows.md` for the `needs_review` state and worked teardown examples, and `examples/pane-navigation/` for a reference driver CLI exercising the navigation primitives.
+
+## Information Flow Is a First-Class Design Concern
+
+**A workflow is an information flow problem, not a sequence of prompts.**
+Before writing any `ctx.stage()` call, answer for every session boundary:
+
+- What context does this session need, how will it reach the session
+  (prompt handoff, file, single multi-turn stage), and what happens if the
+  context window fills up?
+
+For Copilot and OpenCode, every `ctx.stage()` is a fresh conversation;
+Claude reuses a tmux pane per stage. Read these before shipping any
+multi-session workflow:
+
+- `references/agent-sessions.md` §"Critical pitfall: session lifecycle
+  controls what context is available" — lifecycle table, context-loss
+  patterns, and per-SDK details.
+- `references/failure-modes.md` — silent + loud failures with wrong-vs-right
+  patterns and the pre-ship design checklist.
+- `references/state-and-data-flow.md` — `s.save()`, `s.transcript()`, and
+  file-based handoff patterns.
+
+## Design Advisory Skills
+
+Workflow quality depends on two disciplines: **prompt engineering** (crafting
+clear, structured prompts each session receives) and **context engineering**
+(ensuring the right information reaches each session without exceeding token
+budgets). Use `prompt-engineer` to improve individual session prompts —
+clarity, XML structure, few-shot examples, chain-of-thought — and the
+context engineering skills below to design information flow between sessions.
+
+| Design Concern | Skill | Trigger |
+|---|---|---|
+| Prompt clarity and structure | `prompt-engineer` | Every workflow — clear instructions, XML tags, examples, chain-of-thought |
+| Session prompt structure | `context-fundamentals` | Every workflow — token budgeting, prompt positioning, progressive disclosure |
+| Context failure prevention | `context-degradation` | Long conversations, accumulated state, multi-turn loops |
+| Transcript compression | `context-compression` | Passing large transcripts between sessions |
+| Multi-session architecture | `multi-agent-patterns` | Coordination topology, handoff protocols, error propagation |
+| Cross-run persistence | `memory-systems` | Retaining knowledge across separate executions |
+| Custom tools and capabilities | `tool-design` | Sessions exposing custom tools |
+| File-based coordination | `filesystem-context` | Sessions sharing state via files |
+| Remote execution | `hosted-agents` | Sandboxed or remote environments |
+| Token efficiency | `context-optimization` | Compaction triggers, observation masking, cache-friendly ordering |
+| Quality gates | `evaluation` | Review loops or quality checkpoints |
+| LLM-as-judge review | `advanced-evaluation` | Automated review sessions judging other sessions' output |
+| Task-model fit | `project-development` | Validating whether a task is viable for agent automation |
+| Deliberative reasoning | `bdi-mental-states` | Explainable reasoning chains or formal cognitive models |
+
+## How Workflows Work
+
+A workflow is a TypeScript file with a single `.run()` callback that
+orchestrates agent sessions dynamically. Inside the callback, `ctx.stage()`
+spawns sessions — each gets its own tmux window and graph node (unless
+running in headless mode). Native TypeScript handles all control flow:
+loops, conditionals, `Promise.all()`, `try`/`catch`.
+
+```ts
+import { defineWorkflow, extractAssistantText } from "@bastani/atomic/workflows";
+
+export default defineWorkflow({
+    name: "my-workflow",
+    source: import.meta.path,
+    description: "...",
+    inputs: [
+      { name: "prompt", type: "text", required: true, description: "task to perform" },
+    ],
+  })
+  .for("claude")
+  .run(async (ctx) => {
+    const step1 = await ctx.stage({ name: "step-1" }, {}, {}, async (s) => { /* s.client, s.session */ });
+    await ctx.stage({ name: "step-2" }, {}, {}, async (s) => { /* s.client, s.session */ });
+  })
+  .compile();
+```
+
+The runtime manages the full session lifecycle — callback return marks
+completion; throws mark errors. `.compile()` produces a branded
+`WorkflowDefinition` consumed by the CLI.
+
+### Background (headless) stages
+
+Pass `{ headless: true }` in `stageOpts` to run a stage in-process with no
+tmux window or graph node. The callback interface is identical
+(`s.client`, `s.session`, `s.save()`, `s.transcript()` all work). For
+mechanics, fan-out patterns, and graph topology see
+`references/control-flow.md` §"Headless stages" and
+`references/agent-sessions.md` per-SDK "Headless mode" sections.
+
+### Installing the workflow SDK
+
+Install `@bastani/atomic` plus the native SDK(s) you target
+(`@anthropic-ai/claude-agent-sdk`, `@github/copilot-sdk`,
+`@opencode-ai/sdk`).
+
+### Composition root
+
+Workflows are wired into a **composition root** — a TypeScript file the
+user runs with `bun`. The SDK exposes pure primitives:
+
+- `runWorkflow({ workflow, inputs, detach? })` — spawn a workflow's tmux session.
+- `createRegistry()` / `listWorkflows(reg)` / `getWorkflow(reg, agent, name)` — build and iterate a registry.
+- `getName(wf) / getAgent(wf) / getDescription(wf) / getInputSchema(wf) / getSource(wf) / getMinSDKVersion(wf)` — read workflow metadata.
+- `validateInputs(wf, raw)` — apply defaults and validate against the declared schema.
+- **Session lifecycle** — `listSessions / getSession / stopSession / attachSession / detachSession / getSessionStatus / getSessionTranscript`. Manage running tmux sessions on the shared atomic socket.
+- **Pane navigation** — `nextWindow / previousWindow / gotoOrchestrator`. Pure tmux verbs: they update the session's current-window pointer and return immediately. Never auto-attach — an attached client sees the change live; if no client is watching, the next `attachSession` call lands on the new window. Compose `nextWindow(id) + attachSession(id)` for navigate-then-attach.
+- **Typed errors** (catch with `instanceof` to render friendly CLI messages) — `MissingDependencyError` (tmux/psmux/bun missing), `SessionNotFoundError` (id not on the atomic socket), `WorkflowNotCompiledError` (forgot `.compile()`), `InvalidWorkflowError` (default export not a `WorkflowDefinition`), `IncompatibleSDKError` (workflow's `minSDKVersion` newer than installed CLI). All thrown by SDK primitives; all carry the relevant payload field (`dependency`, `id`, `path`, version pair).
+- `WorkflowPicker` (from `@bastani/atomic/workflows/components`) — the interactive picker `atomic workflow -a claude` uses.
+
+You compose them into whatever CLI library you prefer. The SDK never
+re-execs the dev's CLI — it ships its own orchestrator entry script and
+re-execs *that* with positional args.
+
+```ts
+// src/claude-worker.ts — single workflow with a small Commander entrypoint
+import { Command } from "@commander-js/extra-typings";
+import { getInputSchema, runWorkflow } from "@bastani/atomic/workflows";
+import workflow from "./workflows/my-workflow/claude.ts";
+
+const program = new Command();
+for (const input of getInputSchema(workflow)) {
+  program.option(`--${input.name} <value>`, input.description ?? "");
+}
+program.action(async (rawOpts) => {
+  await runWorkflow({ workflow, inputs: rawOpts as Record<string, string> });
+});
+await program.parseAsync();
+
+// src/cli.ts — many workflows via createRegistry + listWorkflows
+import {
+  createRegistry,
+  getInputSchema,
+  getName,
+  listWorkflows,
+  runWorkflow,
+} from "@bastani/atomic/workflows";
+import claudeWorkflow from "./workflows/my-workflow/claude.ts";
+import copilotWorkflow from "./workflows/my-workflow/copilot.ts";
+
+const registry = createRegistry()
+  .register(claudeWorkflow)
+  .register(copilotWorkflow);
+
+const program = new Command();
+for (const wf of listWorkflows(registry)) {
+  const sub = program.command(getName(wf));
+  for (const input of getInputSchema(wf)) {
+    sub.option(`--${input.name} <value>`, input.description ?? "");
+  }
+  sub.action(async (rawOpts) => {
+    await runWorkflow({ workflow: wf, inputs: rawOpts as Record<string, string> });
+  });
+}
+await program.parseAsync();
+```
+
+For programmatic invocation (no CLI at all), call `runWorkflow` directly:
+
+```ts
+const { id, tmuxSessionName } = await runWorkflow({
+  workflow,
+  inputs: { prompt: "fix the auth bug" },
+  detach: true,
+});
+```
+
+For full registry mechanics, key scheme, and validate-on-register behaviour see `references/registry-and-validation.md`.
+
+### Two context levels
+
+`WorkflowContext` (`ctx`) drives orchestration in `.run()`; `SessionContext`
+(`s`) drives agent work inside each stage callback. Full field reference in
+`references/getting-started.md` §"`SessionContext` reference".
+
+### Declared inputs
+
+Workflows receive user data exclusively through `ctx.inputs` / `s.inputs`,
+declared inline as `inputs: WorkflowInput[]` on `defineWorkflow()`.
+TypeScript restricts `ctx.inputs` to declared keys (undeclared access is a
+compile-time error). Load `references/workflow-inputs.md` for schema shape,
+field types (`string` / `text` / `enum`), validation rules, picker
+semantics, and the "declare your prompt input explicitly" pattern.
+
+### Invocation surfaces
+
+Two invocation paths:
+
+**User's own app** — the dev controls the CLI shape entirely. Whatever flags they declare in their Commander/citty/yargs program are the user-facing UX. A typical layout (see snippets above):
+
+```bash
+# Single-workflow worker — flags match the workflow's declared inputs
+bun run src/claude-worker.ts --prompt "fix the bug"
+bun run src/claude-worker.ts --research_doc=notes.md --focus=standard
+
+# Multi-workflow CLI — one subcommand per workflow
+bun run src/cli.ts review --target_branch=main
+bun run src/cli.ts spec   --research_doc=notes.md
+```
+
+To launch the interactive picker, mount the `WorkflowPicker` component:
+
+```ts
+import { WorkflowPickerPanel } from "@bastani/atomic/workflows/components";
+
+const panel = await WorkflowPickerPanel.create({ agent: "claude", registry });
+const result = await panel.waitForSelection();
+panel.destroy();
+if (result) {
+  await runWorkflow({ workflow: result.workflow, inputs: result.inputs });
+}
+```
+
+The dev's CLI is **never** re-execed. The SDK ships an internal orchestrator entry script and re-execs that with positional args — no env-var dance, no boilerplate re-entry code in the dev's file.
+
+**Atomic builtins** — workflows shipped inside `@bastani/atomic`, registered by atomic's internal `createBuiltinRegistry()`:
+
+```bash
+atomic workflow -n <name> -a <agent> [inputs...]
+```
+
+Surface | Command | When
+---|---|---
+Named, with prompt | `… -n hello -a claude "fix the bug"` | Requires workflow to declare a `prompt` input
+Named, structured | `… -n gen-spec -a claude --research_doc=notes.md` | Structured inputs via `--<field>` flags
+Interactive picker | `atomic workflow -a claude` | Discovery — fuzzy list + form; this is the intentional no-`-n` path
+List (atomic builtins) | `atomic workflow list`, `atomic workflow list -a <agent>` | Browse registered builtins, optionally filtered
+List (user cli) | Iterate `listWorkflows(registry)` and add a `list` Commander subcommand yourself | No built-in `--list` flag
+List (single-workflow) | Not applicable — the file *is* the workflow
+Inspect inputs | `atomic workflow inputs <name> -a claude` | Print input schema as JSON
+Status (one or all) | `atomic workflow status [<session-id>]` | Query state — `in_progress`, `error`, `completed`, `needs_review`
+Kill non-interactively | `atomic session kill <id> -y` | Tear down without confirmation prompt — `-y` is mandatory for agents
+Detached (background) | `… -d` / `… --detach` | Runs without attaching; reattach with `atomic workflow session connect <name>`
+
+Any of the named shapes above (positional or structured) accepts
+`-d` / `--detach` to run without attaching. Use it when you're automating
+from a script and want the CLI to return as soon as the session is spawned.
+
+### Declaring SDK compatibility (`minSDKVersion`)
+
+Opt-in version gate for workflows that depend on a specific SDK release.
+**Default is unset — do not add it to new workflows unless you have a
+concrete reason.**
+
+```ts
+defineWorkflow({
+  name: "uses-new-api",
+  source: import.meta.path,
+  minSDKVersion: "0.6.0", // refuse to load on older CLI
+})
+```
+
+When set to a version newer than the installed CLI, the workflow refuses to
+load and surfaces a visible row in `atomic workflow list` and the picker
+(rather than silently vanishing). Set it only when the workflow calls a
+newly-added SDK surface (new `stage()` option, new helper export, new
+provider method); omit it for workflows on stable APIs. Full semver
+semantics and the visible-diagnostic contract live in
+`references/registry-and-validation.md`.
+
+## Structural Rules (hard constraints)
+
+Enforced by the builder, loader, and runtime:
+
+1. **`.run()` required** — the builder must have a `.run(async (ctx) => { ... })` call.
+2. **`.compile()` required** — the chain must end with `.compile()`.
+3. **Every workflow is a named `export`** — export the compiled definition from the workflow file (default or named). It is then imported and passed to `registry.register(...)` in the composition root.
+4. **Unique session names** — every `ctx.stage()` call must use a unique `name` across the workflow run.
+5. **Completed-only reads** — `transcript()` and `getMessages()` only access sessions whose callback has returned and saves have flushed. Attempting to read a still-running session throws.
+6. **Graph topology is auto-inferred** — the runtime derives parent-child edges from `await`/`Promise.all` patterns. Sequential `await` creates a chain; `Promise.all([...])` branches from the same parent; a stage after `Promise.all` receives all parallel stages as parents. Headless stages are **transparent** to the graph — they don't consume or update the execution frontier. See `references/control-flow.md` for full details.
+7. **Do not manually create clients or sessions** — the runtime auto-creates `s.client` and `s.session` from `clientOpts` and `sessionOpts`. Use `s.session.query()`, `s.session.send()`, and `s.client.session.prompt()` instead.
+8. **Headless stages share the same callback interface** — `s.client`, `s.session`, `s.save()`, `s.transcript()`, and return values all work identically in headless mode. The only differences are: no tmux window, no graph node, and a virtual `paneId`.
+9. **Every `ctx.stage()` must contain at least one LLM interaction** — a `s.session.query()` / `s.session.send()` / `s.client.session.prompt()` call. A stage that runs only TypeScript (file I/O, git commands, HTTP calls, parsing, validation) spawns a visible tmux pane that sits idle on the agent welcome screen for the whole stage, confusing users watching the graph. See `references/failure-modes.md` §F22. Pure deterministic code belongs in `.run()` outside any stage; deterministic follow-up *paired* with a query (e.g. parse → validate → save after `s.session.query()`) belongs in the same callback.
+
+## Concept-to-Code Mapping
+
+Every workflow pattern maps directly to TypeScript code:
+
+| Workflow Concept | Programmatic Pattern |
+|---|---|
+| Agent session (send prompt, get response) | `ctx.stage({ name }, {}, {}, async (s) => { /* use s.client, s.session */ })` — **must** include an LLM call (Rule 9) |
+| Background (headless) session | `ctx.stage({ name, headless: true }, {}, {}, async (s) => { /* same API */ })` — invisible in graph, tracked by background counter |
+| Sequential execution | `await ctx.stage(...)` followed by `await ctx.stage(...)` |
+| Parallel execution | `Promise.all([ctx.stage(...), ctx.stage(...)])` |
+| Parallel background tasks | `Promise.all([ctx.stage({ name: "a", headless: true }, ...), ctx.stage({ name: "b", headless: true }, ...)])` |
+| Conditional branching | `if (...) { await ctx.stage({ name: "fix" }, {}, {}, ...) }` |
+| Bounded loops with visible graph nodes | `for (let i = 1; i <= N; i++) { await ctx.stage({ name: \`step-\${i}\` }, {}, {}, ...) }` |
+| Return data from session | `const h = await ctx.stage(opts, {}, {}, async (s) => { return value; }); h.result` |
+| Data flow between sessions | `s.save()` to persist → `s.transcript(handle)` or `s.transcript("name")` to retrieve |
+| Pure deterministic computation (no LLM call) | Plain TypeScript at the top level of `.run()`. **Never** a standalone stage — see Rule 9 and F22. |
+| Deterministic work tied to an LLM call | Inside the same stage callback, before/after the query. E.g. `s.session.query(...)` → parse → validate → `s.save(parsed)`. |
+| Subagent orchestration | Claude: `--agent` via `chatFlags` (interactive) or `agent` SDK option (headless); Copilot: `{ agent: "name" }` in sessionOpts; OpenCode: `agent` param in `s.client.session.prompt()` |
+| Per-session configuration | Pass `clientOpts` (2nd arg) and `sessionOpts` (3rd arg) to `ctx.stage()` |
+
+### When to use a stage vs. plain TypeScript
+
+Before reaching for `ctx.stage()`, ask: **does this block need an LLM?**
+
+```ts
+// ✓ OK — query + deterministic parse in the same callback
+const plan = await ctx.stage({ name: "plan" }, {}, {}, async (s) => {
+  const messages = await s.session.query("Produce a step-by-step plan.");
+  const text = extractAssistantText(messages, 0);
+  const parsed = parsePlan(text);       // deterministic — fine here
+  s.save(parsed);
+  return parsed;
+});
+
+// ✓ OK — plain TS at the top of .run() between stages
+const plannedFiles = plan.result.files.filter(f => f.endsWith(".ts"));
+const startedAt = Date.now();
+
+// ✗ NOT OK — a stage whose callback is pure code with no query
+await ctx.stage({ name: "write-report" }, {}, {}, async (s) => {
+  await fs.writeFile("report.md", buildReport(plan.result)); // no LLM!
+});
+// This spawns a tmux pane that stays on the Claude/Copilot welcome
+// screen for the whole stage. The user watching the graph sees an
+// empty pane and wonders why no prompt ever appeared.
+
+// ✓ OK — do the deterministic work inline in .run()
+await fs.writeFile("report.md", buildReport(plan.result));
+```
+
+Rule of thumb: **one stage, one LLM conversation.** If the block has no
+`s.session.query()` / `s.session.send()` / `s.client.session.prompt()`,
+it's not a stage.
+
+For full pattern examples with code, see `references/control-flow.md`
+(loops, conditionals, review/fix, graph topology, headless fan-out),
+`references/state-and-data-flow.md` (data passing, file coordination,
+transcript compression), and `references/computation-and-validation.md`
+(parsing, validation, quality gates).
+
+## Authoring Process
+
+### 1. Understand the User's Goal
+
+Map the user's intent to sessions and patterns:
+
+| Question | Maps to |
+|----------|---------|
+| What are the distinct **LLM interactions**? | Each LLM conversation → one `ctx.stage()` call (Rule 9) |
+| Can any LLM calls run in parallel? | `Promise.all([ctx.stage(...), ...])` |
+| Should any parallel LLM calls run in the background? | `ctx.stage({ name, headless: true }, ...)` — invisible in graph, ideal for data-gathering |
+| Does any step need **pure deterministic code** (no LLM)? | Plain TypeScript at the top of `.run()` — **not** a dedicated stage. Bundle it inside the nearest stage callback if it's directly tied to that stage's query. |
+| Do any steps need to repeat? | `for`/`while` loop with `ctx.stage()` inside |
+| Are there conditional paths? | `if`/`else` wrapping `ctx.stage()` calls |
+| What data flows between steps? | `s.save()` → `s.transcript(handle)` / `s.getMessages(handle)` |
+| Does the workflow need user input? | SDK-specific user input APIs (see `references/user-input.md`) |
+| Do any steps need a specific model? | SDK-specific session config (see `references/session-config.md`) |
+
+Then walk the **Design Advisory Skills** table above (§"Design Advisory
+Skills") — for each row whose trigger applies to your workflow, pull that
+skill in *before* writing code. Catching architectural and prompt-quality
+issues at design time is far cheaper than catching them in the first failed
+end-to-end run.
+
+### 2. Choose the Target Agent
+
+Pass the agent as a runtime argument to `.for()` on the builder — this
+narrows all context types and gives correct `s.client`/`s.session` types.
+Call `.for()` **before** `.run()`:
+
+| Agent | Builder Chain | Primary Session API |
+|-------|---------------|---------------------|
+| Claude | `defineWorkflow({...}).for("claude")` | `s.session.query(prompt)` — sends prompt to the Claude TUI pane |
+| Copilot | `defineWorkflow({...}).for("copilot")` | `s.session.send({ prompt })` — the runtime wraps `send` to block until `session.idle` with no timeout (see `failure-modes.md` §F10); do not use `sendAndWait` in Atomic workflows |
+| OpenCode | `defineWorkflow({...}).for("opencode")` | `s.client.session.prompt({ sessionID: s.session.id, parts: [...] })` |
+
+The runtime manages client/session lifecycle automatically. For native SDK
+types and advanced APIs, import directly from the provider packages
+(`@github/copilot-sdk`, `@anthropic-ai/claude-agent-sdk`, `@opencode-ai/sdk/v2`).
+
+For cross-agent support, create one workflow file per agent. Use shared
+helper modules for SDK-agnostic logic. A typical layout:
+
+```
+src/workflows/my-workflow/
+├── claude.ts          # Claude-specific SDK code  — exports a WorkflowDefinition
+├── copilot.ts         # Copilot-specific SDK code — exports a WorkflowDefinition
+├── opencode.ts        # OpenCode-specific SDK code— exports a WorkflowDefinition
+└── helpers/
+    ├── prompts.ts     # Prompt builders (SDK-agnostic)
+    ├── parsers.ts     # Response parsers (SDK-agnostic)
+    └── validation.ts  # Validation logic (SDK-agnostic)
+```
+
+Register each variant in the composition root:
+
+```ts
+import { claudeWorkflow } from "./workflows/my-workflow/claude.ts";
+import { copilotWorkflow } from "./workflows/my-workflow/copilot.ts";
+
+const registry = createRegistry()
+  .register(claudeWorkflow)
+  .register(copilotWorkflow);
+```
+
+### 3. Write the Workflow File
+
+Write the workflow file using the SDK-specific patterns. See
+`references/getting-started.md` for full quick-start examples for all 3
+SDKs (send/save/extract patterns, idle handling), and
+`references/agent-sessions.md` for per-SDK API details and lifecycle
+caveats.
+
+**Reference implementations** — two categories live in-repo:
+
+- **Builtins** (`src/sdk/workflows/builtin/`) — production patterns,
+  registered via `createBuiltinRegistry()` inside the `atomic` CLI:
+  - `ralph` — iterative plan → orchestrate → review → debug loop.
+  - `deep-research-codebase` — scout → parallel explorer fan-out → aggregator.
+  - `open-claude-design` — design-system init flow.
+- **User-app examples** (`examples/<name>/`) — minimal runnable user apps
+  you can copy-paste as a starting point. Each example directory contains
+  `claude/index.ts`, `copilot/index.ts`, `opencode/index.ts`, and one
+  `<agent>-worker.ts` entrypoint per agent — each a small Commander
+  entrypoint that calls `runWorkflow({ workflow, inputs })`. Run with
+  `bun run examples/<name>/<agent>-worker.ts --<field>=<value>` (or a
+  positional prompt string if the worker declares `[prompt...]`).
+  Covers: `hello-world`, `sequential-describe-summarize`,
+  `parallel-hello-world`, `headless-test`, `hil-favorite-color`,
+  `hil-favorite-color-headless`, `structured-output-demo`,
+  `reviewer-tool-test` (copilot only), `review-fix-loop`,
+  `multi-workflow`, `commander-embed`, `pane-navigation` (driver CLI for
+  the navigation primitives).
+
+Both sets demonstrate shared helpers, context-aware prompt building,
+deterministic heuristics, and cross-SDK adaptation.
+
+### 4. Wire, typecheck, run
+
+The composition root is always three lines (see §"Scaffold a new workflow from scratch" above for the exact template and multi-workflow variant). After writing it:
+
+```bash
+bun typecheck
+bun run src/<agent>-worker.ts --prompt "<test task>"
+```
+
+Other invocation shapes you may want to demonstrate to the user once the workflow runs:
+
+```bash
+# Single-workflow worker — flags match the workflow's declared inputs
+bun run src/<agent>-worker.ts --<field>=<value>             # structured inputs
+bun run src/<agent>-worker.ts "free-form prompt text"       # positional fallback (if wired)
+
+# Multi-workflow CLI — one subcommand per workflow
+bun run src/cli.ts <workflow-name> --<field>=<value>        # structured
+bun run src/cli.ts <workflow-name> "free-form prompt text"  # positional fallback (if wired)
+
+# Atomic builtins — these use -n/-a/-d (atomic CLI's own flags, not user-app flags)
+atomic workflow -n <name> -a <agent> "<prompt>"             # attached run
+atomic workflow -n <name> -a <agent> -d "<prompt>"          # detached (background)
+```
+
+For detached user-app runs, pass `detach: true` to `runWorkflow` or wire your own `--detach` flag in your Commander entrypoint. For the atomic builtins (`ralph`, `deep-research-codebase`, `open-claude-design`), see `references/running-workflows.md` for monitoring and teardown.
+
+## Running an Existing Workflow
+
+If the user asks you to **run** (or "kick off" / "start" / "execute") a
+workflow — not author one — the workflow already exists and you just need
+to invoke it correctly. That's a different playbook from authoring.
+
+**Read `references/running-workflows.md`.** It covers:
+
+- Three invocation paths: user's own app (per-input `--<flag>` flags wired
+  by the dev, using Commander or another CLI library), repo-shipped examples
+  (same pattern), and atomic builtins (`atomic workflow -n … -a …`).
+- Why atomic builtins use `-n` + `-a` and how to add `-d` for background runs.
+- Why you must list workflows first.
+- How to handle missing workflows (offer to author, not fabricate).
+- Using `atomic workflow inputs <name> -a <agent>` to discover the schema
+  and drive AskUserQuestion.
+- The six-step invocation recipe.
+- Monitoring with `atomic workflow status` — and why `needs_review` must be
+  surfaced immediately.
+- Tearing down with `atomic session kill -y` (the `-y` is mandatory).
+- Worked examples for "workflow exists" and "workflow doesn't exist".