@bastani/atomic 0.6.8 → 0.7.0-1

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

@@ -1,553 +0,0 @@
----
-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`.
-metadata:
-  provider: atomic
----
-
-# 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()`                                                                                                              |
-| Per-session permission posture (autonomous)  | Claude: `chatFlags: ["--dangerously-skip-permissions"]` (interactive) or `permissionMode: "bypassPermissions"` on `s.session.query()` (headless). Copilot: `onPermissionRequest: approveAll` (default — auto-applied). OpenCode: pass `permission: [{ permission: "*", pattern: "*", action: "allow" }]` in `sessionOpts` on **every stage** so the posture is visible in the workflow source, not buried in runtime defaults. See `references/session-config.md` §"OpenCode session permission ruleset". |
-
-### 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".