@bastani/atomic 0.5.23-0 → 0.5.24-0

package/.agents/skills/workflow-creator/references/running-workflows.md

@@ -0,0 +1,235 @@
+# Running a Workflow on Behalf of the User
+
+When the user asks you to **run** (or "kick off" / "start" / "execute") a
+workflow — *not* author one — your job is to translate their request into a
+single `atomic workflow` invocation and run it. This is the playbook for that
+flow. It is different from the authoring playbook in `SKILL.md`: the workflow
+already exists on disk; you just need to invoke it correctly.
+
+## You don't need to pass `-a` or `-d`
+
+When you (the agent) are running inside an atomic chat or workflow pane, the
+CLI reads `$ATOMIC_AGENT` from your environment and:
+
+- Fills in `-a <agent>` automatically if you don't pass it.
+- Forces detached mode on, so launching a workflow never takes over your pane.
+
+The practical result: your command is just `atomic workflow -n <name> <inputs>`.
+No provider flag, no detach flag, no chance of the orchestrator hijacking your
+terminal. The CLI prints the session name and returns immediately; you relay
+that name to the user.
+
+Override only when the user explicitly asks for a different provider (e.g.
+"run it on Copilot") — pass `-a copilot` and the CLI will honor it over the
+env var.
+
+## Always list first
+
+**Before anything else, run `atomic workflow list`.** (Optionally filter with
+`-a <agent>` if the user's pinned to one — usually unnecessary.) This is a
+cheap, read-only call that tells you three things in one shot:
+
+- Whether the workflow the user named actually exists.
+- What other workflows are available (so you can suggest close matches on a typo).
+- Source + metadata for every discoverable workflow (local vs. global vs. builtin).
+
+Skipping this step is how you end up guessing a name, typing it into
+`atomic workflow -n <name>`, and getting a `workflow not found` error you
+could have predicted. List first, decide second, run third.
+
+If the user's request is ambiguous ("run the research one"), the list output
+is also how you show them the candidates so they can pick — present the
+matching names and ask with AskUserQuestion.
+
+## If the workflow doesn't exist: offer to create it
+
+When the listed workflows don't include what the user asked for:
+
+1. **Tell the user explicitly** — "I don't see a `<name>` workflow in
+   `.atomic/workflows/` or `~/.atomic/workflows/`. Available: \<short list from
+   `atomic workflow list`>."
+2. **Check for typos first** — if one of the listed names is a close match,
+   surface it via AskUserQuestion ("Did you mean `<close-match>`?") before
+   offering to author anything.
+3. **Offer to create it** — ask with AskUserQuestion: "Want me to create a
+   `<name>` workflow first?" with choices `Yes, create it` / `No, pick from
+   the list` / `No, cancel`.
+4. **If yes → switch modes** — hand off to the authoring flow in SKILL.md
+   (Steps 1-5). Interview the user for intent, write the file at
+   `.atomic/workflows/<name>/<agent>/index.ts`, typecheck it, *then* come back
+   here and invoke it. Do not skip the typecheck — an uncompiled workflow
+   won't run.
+5. **If no → stop** — don't fabricate a command that will fail. Let the user
+   redirect you.
+
+Never invent a workflow name or silently fall back to a different workflow.
+If the thing the user asked for doesn't exist, the correct answer is to say
+so and offer concrete next steps.
+
+## Collecting inputs with AskUserQuestion
+
+Once you've confirmed the workflow exists, you need to know two things about
+its invocation shape:
+
+1. **Does it declare a `prompt` input?** If so, it's free-form — you pass a
+   positional string.
+2. **Does it declare structured inputs?** If so, you pass `--<field>=<value>`
+   flags, one per required field.
+
+**Use `atomic workflow inputs <name> -a <agent>` to get the schema.** This
+prints a JSON envelope with every field's `name`, `type`, `required`,
+`default`, `description`, and (for enums) `values` — exactly what
+AskUserQuestion needs. The `freeform: true` flag tells you whether the
+workflow takes a positional prompt vs. structured flags, with a synthetic
+`prompt` field included so the JSON shape is uniform either way.
+
+```bash
+atomic workflow inputs gen-spec -a claude
+# {"workflow":"gen-spec","agent":"claude","freeform":false,
+#  "inputs":[{"name":"research_doc","type":"string","required":true,...},
+#            {"name":"focus","type":"enum","values":["minimal","standard","exhaustive"],"default":"standard"}]}
+```
+
+Why this command instead of reading the source file: `inputs` is the contract
+the CLI actually validates against. It survives refactors, handles built-in
+workflows that aren't in the project tree, and never falls out of sync with
+the runtime. Reading TypeScript source is a fallback for the rare case where
+the command can't resolve the workflow.
+
+Once you have the schema, use the **AskUserQuestion tool** to collect any
+values the user hasn't already provided in their message. One question per
+missing input field. For enum fields, pass the declared `values` as
+multiple-choice options so the user sees exactly what's allowed. Keep
+questions tight and purposeful — if the user's message already answers a
+question, don't ask it again.
+
+Skip AskUserQuestion entirely when:
+- The user already supplied every required value in their message
+  ("run ralph on 'add OAuth to the API'" — the prompt is right there).
+- The workflow declares no required inputs and needs no prompt.
+
+## End-to-end recipe
+
+1. **List available workflows** — run `atomic workflow list`. Always. This is
+   your ground truth.
+2. **Resolve the target**:
+   - Exact match in the list → continue.
+   - Close match → confirm via AskUserQuestion before proceeding.
+   - No match → tell the user what's available and offer to author it (see
+     previous section). If they decline, stop.
+3. **Discover the inputs schema** — run `atomic workflow inputs <name> -a <agent>`
+   and parse the JSON.
+4. **Ask for missing inputs** — use AskUserQuestion, one question per
+   unanswered required field. Enums become multiple-choice.
+5. **Invoke** — build one of these commands:
+   - Free-form: `atomic workflow -n <name> "<prompt>"`
+   - Structured: `atomic workflow -n <name> --<field1>=<value1> --<field2>=<value2>`
+6. **Report the session name** the CLI printed and tell the user: "attach any
+   time with `atomic workflow session connect <session>` — or
+   `atomic workflow session list` to see what's running."
+
+## Monitoring a running workflow
+
+Detached workflows return immediately with a session name; the actual work
+runs in the background on the atomic tmux socket. Use `atomic workflow status`
+to check whether the workflow is still running, has completed, errored out, or
+paused for human input — without attaching to its TUI.
+
+```bash
+atomic workflow status atomic-wf-claude-gen-spec-a1b2c3d4
+# {"id":"atomic-wf-claude-gen-spec-a1b2c3d4","overall":"in_progress","alive":true,
+#  "sessions":[{"name":"orchestrator","status":"running",...}],...}
+```
+
+Four overall states the agent must handle distinctly:
+
+| Status | Meaning | What you should do |
+|---|---|---|
+| `in_progress` | The orchestrator is running and no stage is paused | Wait, or report progress to the user |
+| `needs_review` | At least one stage is paused for human input (HIL) — Copilot `ask_user`, OpenCode `question.asked`, Copilot/MCP elicitation | **Surface this to the user immediately** — they need to attach with `atomic workflow session connect <id>` to respond, otherwise the workflow stalls indefinitely |
+| `completed` | Workflow finished successfully | Report success and summarize the output |
+| `error` | Fatal error or a stage failed | Report the `fatalError` field and offer to investigate logs |
+
+`needs_review` outranks `completed` so a HIL pause near the end is never
+reported as done while still waiting on a human. A dead orchestrator with a
+stale snapshot is automatically downgraded to `error`.
+
+Omit the id to list every running workflow at once: `atomic workflow status`.
+Useful when checking on multiple parallel runs, or when the user just asks
+"what's running?".
+
+## Cleaning up sessions
+
+When the user is done with a workflow — or you launched one detached and it's
+no longer needed — tear it down with `-y` so no confirmation prompt blocks you:
+
+```bash
+atomic session kill atomic-wf-claude-gen-spec-a1b2c3d4 -y
+```
+
+The `-y` flag is mandatory for agent use. Without it, the CLI calls
+`@clack/prompts confirm`, which expects a TTY and will hang indefinitely in a
+non-interactive context. Same flag works for `atomic workflow session kill`
+and `atomic chat session kill`. Without an id, `kill -y` tears down every
+in-scope session — only do that when the user has asked to stop everything.
+
+## Worked examples
+
+**Example A — workflow exists, structured inputs**
+
+> **User:** "run gen-spec on research/docs/2026-04-11-auth.md"
+
+1. Run `atomic workflow list`. Output includes `gen-spec` under local. Good.
+2. Target resolved exactly: `gen-spec`.
+3. Run `atomic workflow inputs gen-spec -a claude`. Parse the JSON:
+   `research_doc` (required string — already given), `focus` (required enum
+   of `minimal|standard|exhaustive`, default `standard`), `notes`
+   (optional text).
+4. Ask via AskUserQuestion once: "What focus level for the spec?" with
+   choices `minimal`, `standard`, `exhaustive`. User picks `standard`. Skip
+   `notes` since it's optional.
+5. Run: `atomic workflow -n gen-spec --research_doc=research/docs/2026-04-11-auth.md --focus=standard`
+6. The CLI prints a session name like `atomic-wf-claude-gen-spec-a1b2c3d4`.
+   Tell the user: "Started in the background. Attach with
+   `atomic workflow session connect atomic-wf-claude-gen-spec-a1b2c3d4`,
+   check progress with `atomic workflow status atomic-wf-claude-gen-spec-a1b2c3d4`,
+   or stop it with `atomic session kill atomic-wf-claude-gen-spec-a1b2c3d4 -y`."
+
+**Example B — workflow does not exist**
+
+> **User:** "run the security-audit workflow on src/auth"
+
+1. Run `atomic workflow list`. Available: `ralph`, `deep-research-codebase`,
+   `gen-spec`, `review-to-merge`. No `security-audit`.
+2. Tell the user: "I don't see a `security-audit` workflow. Available:
+   ralph, deep-research-codebase, gen-spec, review-to-merge."
+3. Ask via AskUserQuestion: "Want me to create a `security-audit` workflow
+   first?" with choices `Yes, create it`, `No, use one of the existing
+   workflows`, `No, cancel`.
+4. If **Yes**: switch to SKILL.md's Authoring Process — interview the user
+   for what the workflow should do, draft it, typecheck, *then* return here
+   and invoke it.
+5. If **No, use existing**: ask which one via AskUserQuestion over the
+   listed options, then continue from step 3 of the recipe.
+6. If **Cancel**: stop, no command runs.
+
+## Common mistakes to avoid
+
+- **Skipping `atomic workflow list`** — leads to guessing and
+  `workflow not found` errors. It's a one-line command; always run it.
+- **Inventing a workflow name** — if it's not in the list, it doesn't exist.
+  Say so and offer to author it.
+- **Reading the workflow source file to discover inputs** — use
+  `atomic workflow inputs <name> -a <agent>` instead. JSON, no TS parsing
+  required, always in sync with the runtime. Source-file reads are a
+  fallback, not a default.
+- **Asking everything at once** — let AskUserQuestion drive one question per
+  field. Enum fields are multiple-choice, not free text.
+- **Re-asking what the user already said** — read their message first.
+- **Forgetting to report the session name** — the user needs it to reattach
+  and to query status later.
+- **Leaving `needs_review` unreported** — when `atomic workflow status`
+  returns `needs_review`, surface it to the user right away. The workflow is
+  blocked on human input and will sit forever otherwise.
+- **Calling `session kill` without `-y`** — the prompt hangs in a
+  non-interactive context. Always pass `-y` from an agent.

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

@@ -25,14 +25,24 @@ If you want to configure agent/permission/tools behavior for a **headless** Clau
 
 ```ts
 await ctx.stage({ name: "..." }, {}, {}, async (s) => {
-  await s.session.query((ctx.inputs.prompt ?? ""));
+  await s.session.query((s.inputs.prompt ?? ""));
   s.save(s.sessionId);
 });
 ```
 
-### `query()` options
+### `query()` options (reference for `s.session.query()` sdkOptions)
+
+**This block is a reference cheatsheet for the SDK option shape — it is
+not valid workflow code.** Do not import `query` from
+`@anthropic-ai/claude-agent-sdk` inside a `ctx.stage()` callback (see
+`failure-modes.md` §F16). In a **headless** stage, pass these options as
+the second argument to `s.session.query(prompt, sdkOptions)` — the runtime
+forwards them to the Agent SDK. In an **interactive** stage, the options
+are silently ignored; drive behaviour via `chatFlags` in `clientOpts`
+instead.
 
 ```ts
+// ❌ Reference only — do not call query() like this from a workflow.
 import { query } from "@anthropic-ai/claude-agent-sdk";
 
 const result = query({
@@ -40,7 +50,7 @@ const result = query({
   options: {
     // Model selection
     model: "claude-opus-4-6",         // Full model ID or alias ("opus", "sonnet", "haiku")
-    effort: "high",                   // "low", "medium", "high", "max" (max is Opus 4.6 only)
+    effort: "high",                   // "low", "medium", "high", "xhigh", "max" (max is Opus 4.6/4.7 only)
     thinking: { type: "adaptive" },   // Default for supported models; or { type: "enabled", budgetTokens: N }
     maxTurns: 50,                     // Maximum conversation turns
     maxBudgetUsd: 5.0,                // Spending cap in USD
@@ -218,10 +228,15 @@ await ctx.stage({ name: "plan" }, {}, {
     onErrorOccurred: (event) => { /* error handling */ },
   },
 
-  // Advanced
-  infiniteSessions: true,             // Auto-manage context via compaction
+  // Advanced — auto-manage context via compaction. Pass an InfiniteSessionConfig,
+  // not a boolean. See docs/copilot-cli/sdk.md for the full threshold surface.
+  infiniteSessions: {
+    enabled: true,
+    backgroundCompactionThreshold: 0.8, // start compacting at 80% window usage
+    bufferExhaustionThreshold: 0.95,    // block at 95% until compaction completes
+  },
 }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 ```
@@ -231,7 +246,7 @@ await ctx.stage({ name: "plan" }, {}, {
 ```ts
 // Approve everything (autonomous) — this is the default
 await ctx.stage({ name: "plan" }, {}, { onPermissionRequest: approveAll }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 
@@ -251,7 +266,7 @@ await ctx.stage({ name: "plan" }, {}, {
     }
   },
 }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 ```
@@ -295,7 +310,7 @@ await ctx.stage({ name: "implement" }, {}, {}, async (s) => {
   // Basic prompt
   const result = await s.client.session.prompt({
     sessionID: s.session.id,
-    parts: [{ type: "text", text: (ctx.inputs.prompt ?? "") }],
+    parts: [{ type: "text", text: (s.inputs.prompt ?? "") }],
   });
 
   // Structured output

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

@@ -110,7 +110,7 @@ Use closures and variables for state within a single session:
 
     for (let cycle = 0; cycle < 10; cycle++) {
       const result = await s.session.query(
-        buildReviewPrompt((ctx.inputs.prompt ?? ""), priorOutput),
+        buildReviewPrompt((s.inputs.prompt ?? ""), priorOutput),
       );
 
       // Accumulate findings
@@ -128,7 +128,7 @@ Use closures and variables for state within a single session:
       consecutiveClean = 0;
 
       // Apply fix
-      const fixResult = await s.session.query(buildFixSpec(review, (ctx.inputs.prompt ?? "")));
+      const fixResult = await s.session.query(buildFixSpec(review, (s.inputs.prompt ?? "")));
       priorOutput = extractAssistantText(fixResult, 0);
     }
 
@@ -148,10 +148,6 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import { join } from "path";
 
 .run(async (ctx) => {
-  await ctx.stage({ name: "plan" }, {}, {}, async (s) => {
-    // ... plan session ...
-  });
-
   const planHandle = await ctx.stage({ name: "plan" }, {}, {}, async (s) => {
     // Write artifacts to session directory
     const artifactDir = join(s.sessionDir, "artifacts");
@@ -214,6 +210,11 @@ export function buildReviewPrompt(spec: string, priorOutput?: string): string {
 
 ### Response parsers
 
+For tolerant JSON parsing, see `failure-modes.md` §F8 — the canonical
+`parseReviewResult` helper uses a layered fallback (direct parse → last
+fenced block → last balanced object) that survives prose interleaving.
+Copy that implementation into `helpers/parsers.ts` and import.
+
 ```ts
 // .atomic/workflows/my-workflow/helpers/parsers.ts
 export interface ReviewResult {
@@ -221,27 +222,9 @@ export interface ReviewResult {
   overall_correctness: string;
 }
 
-/** Layered fallback: direct parse → last fenced block → last balanced object.
- *  Always extract the LAST block, not the first — see failure-modes.md §F4/§F8. */
+// See failure-modes.md §F8 for the full implementation.
 export function parseReviewResult(text: string): ReviewResult | null {
-  // 1. Direct parse
-  try {
-    const parsed = JSON.parse(text);
-    if (parsed?.findings) return parsed;
-  } catch {}
-
-  // 2. Last fenced block
-  const blockRe = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
-  let lastBlock: string | null = null;
-  let m: RegExpExecArray | null;
-  while ((m = blockRe.exec(text)) !== null) {
-    if (m[1]) lastBlock = m[1];
-  }
-  if (lastBlock) {
-    try { return JSON.parse(lastBlock); } catch {}
-  }
-
-  return null;
+  // ... three-layer fallback per §F8
 }
 ```
 

package/.agents/skills/workflow-creator/references/user-input.md

@@ -6,58 +6,87 @@ For **invocation-time** inputs (the values the user supplies when they launch th
 
 ## Claude
 
-### Via `canUseTool` callback
+Never import `query` from `@anthropic-ai/claude-agent-sdk` inside a stage
+callback — that's the F16 anti-pattern (see `failure-modes.md` §F16). All
+options route through `s.session.query(prompt, sdkOptions)` in headless
+stages, or through `chatFlags` in interactive stages.
 
-The Claude Agent SDK provides a `canUseTool` callback for runtime approval and user interaction:
+### Via `canUseTool` callback (headless stages only)
 
-```ts
-import { query } from "@anthropic-ai/claude-agent-sdk";
+`canUseTool` is an SDK option — it only applies in a headless stage, where
+the second argument to `s.session.query()` is forwarded to the Agent SDK as
+`Partial<SDKOptions>`. In interactive stages the option is silently ignored
+because `s.session.query()` is driving the `claude` CLI binary, not the SDK.
 
-// Inside a ctx.stage() callback:
-async (s) => {
-  const result = query({
-    prompt: "Implement the feature, but ask me before making any database changes.",
-    options: {
-      canUseTool: async (toolName, toolInput, options) => {
-        if (toolName === "Write" && toolInput.file_path?.includes("migration")) {
-          // Prompt the user for approval
-          const approved = await promptUser("Allow database migration?");
-          return approved
-            ? { behavior: "allow" }
-            : { behavior: "deny", message: "User declined migration" };
-        }
-        return { behavior: "allow" };
+```ts
+await ctx.stage(
+  { name: "implement", headless: true },
+  {}, {},
+  async (s) => {
+    const messages = await s.session.query(
+      "Implement the feature, but ask me before making any database changes.",
+      {
+        canUseTool: async (toolName, toolInput) => {
+          if (toolName === "Write" && typeof toolInput.file_path === "string" && toolInput.file_path.includes("migration")) {
+            const approved = await promptUser("Allow database migration?");
+            return approved
+              ? { behavior: "allow", updatedInput: toolInput }
+              : { behavior: "deny", message: "User declined migration" };
+          }
+          return { behavior: "allow", updatedInput: toolInput };
+        },
       },
-    },
-  });
-  for await (const msg of result) { /* process */ }
-},
+    );
+    s.save(s.sessionId);
+    return extractAssistantText(messages, 0);
+  },
+);
 ```
 
 ### Via `AskUserQuestion` tool
 
-Allow the agent to ask the user questions by including `AskUserQuestion` in `allowedTools`:
+Allow the agent to ask the user questions by including `AskUserQuestion` in
+`allowedTools`. This works for both interactive stages (via `chatFlags`) and
+headless stages (via sdkOptions on `s.session.query()`).
+
+**Interactive stage** — pass the tool allowlist via `chatFlags`:
 
 ```ts
-const result = query({
-  prompt: (ctx.inputs.prompt ?? ""),
-  options: {
-    allowedTools: ["Read", "Write", "Edit", "Bash", "AskUserQuestion"],
+await ctx.stage(
+  { name: "implement" },
+  { chatFlags: ["--allowed-tools", "Read,Write,Edit,Bash,AskUserQuestion"] },
+  {},
+  async (s) => {
+    await s.session.query(s.inputs.prompt ?? "");
+    s.save(s.sessionId);
   },
-});
+);
 ```
 
-### Via streaming input
-
-For interactive sessions, use streaming mode to feed user input:
+**Headless stage** — pass `allowedTools` in the sdkOptions:
 
 ```ts
-const q = query({ prompt: (ctx.inputs.prompt ?? ""), options: { ... } });
-
-// Feed additional input while the agent is running
-q.streamInput("Here's the additional context you asked for...");
+await ctx.stage(
+  { name: "implement", headless: true },
+  {}, {},
+  async (s) => {
+    const messages = await s.session.query(s.inputs.prompt ?? "", {
+      allowedTools: ["Read", "Write", "Edit", "Bash", "AskUserQuestion"],
+    });
+    s.save(s.sessionId);
+    return extractAssistantText(messages, 0);
+  },
+);
 ```
 
+### Via streaming input (headless stages only)
+
+The Agent SDK's `streamInput()` feeds additional input while a query is
+running. It's only reachable from headless stages via an async iterable
+prompt — pass an `AsyncIterable<SDKUserMessage>` as the first argument to
+`s.session.query()` instead of a plain string. In interactive stages, send
+follow-up turns with another `s.session.query()` call to the same session.
+
 ## Copilot
 
 Session callbacks (`onUserInputRequest`, `onElicitationRequest`,
@@ -77,7 +106,7 @@ await ctx.stage({ name: "plan" }, {}, {
     return answer;
   },
 }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 ```
@@ -97,7 +126,7 @@ await ctx.stage({ name: "plan" }, {}, {
     };
   },
 }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 ```
@@ -112,7 +141,7 @@ import { approveAll } from "@github/copilot-sdk";
 
 // Explicit (same as the default):
 await ctx.stage({ name: "plan" }, {}, { onPermissionRequest: approveAll }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 ```
@@ -131,7 +160,7 @@ await ctx.stage({ name: "plan" }, {}, {
     return { kind: "approved" };
   },
 }, async (s) => {
-  await s.session.send({ prompt: (ctx.inputs.prompt ?? "") });
+  await s.session.send({ prompt: (s.inputs.prompt ?? "") });
   s.save(await s.session.getMessages());
 });
 ```
@@ -186,11 +215,10 @@ Use user input results in conditional logic. This Claude example uses
 user directly, and you parse the response to branch:
 
 ```ts
-import { query } from "@anthropic-ai/claude-agent-sdk";
-
-// Inside a ctx.stage() callback (Claude example):
+// Inside a ctx.stage() callback (Claude example).
+// AskUserQuestion must be in allowedTools — see "Via AskUserQuestion tool" above.
 async (s) => {
-  const plan = await s.transcript("plan");
+  const plan = await s.transcript("plan"); // or s.transcript(handle) if a handle is in scope (preferred)
 
   // Let the agent ask the user for approval via AskUserQuestion
   const result = await s.session.query(

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

@@ -89,6 +89,18 @@ The nullish coalescing on `notes` handles the optional field case —
 declared-but-unset inputs resolve to `undefined` unless they have a
 `default`.
 
+**Style convention.** Inside a stage callback, both `s.inputs.<name>` and
+`ctx.inputs.<name>` resolve to the same value. Either of these patterns
+works:
+
+- **Destructure once at the top of `.run()`** so each stage closes over a
+  bare local. Best when many stages reference the same input.
+- **Inline access** with `(s.inputs.<name> ?? "")` at each call site. Best
+  for short workflows or when each stage uses a different field.
+
+Pick whichever reads cleaner for your workflow. Examples in other reference
+files use the inline form for brevity in focused snippets.
+
 ## Declaring an input schema
 
 Pass an `inputs` array to `defineWorkflow({ ... })`. Each entry is a
@@ -205,50 +217,15 @@ because the form teaches the schema as the user fills it in.
 
 ## Builtin protection
 
-Builtin workflows (the ones shipped inside the SDK — currently `ralph`
-and `deep-research-codebase`) are **reserved**. A local or global
-workflow with the same name will not shadow the builtin at resolution
-time — the runtime drops user-defined workflows with reserved names
-before any precedence merge. This prevents a user from accidentally
-redefining the canonical version of a workflow in a way that confuses
-teammates or breaks automation.
-
-You'll still see shadowed local/global workflows in
-`atomic workflow list` output so the collision is visible, but running
-`atomic workflow -n ralph -a claude` will always land on the builtin.
-
-The practical implication: **don't name a new workflow `ralph` or
-`deep-research-codebase`**. Pick a distinct name and you'll never hit
-this.
-
-## Invocation cheat sheet
-
-```bash
-# List everything, grouped by source
-atomic workflow list
-
-# Launch the picker for a pinned agent
-atomic workflow -a claude
+Builtin names (`ralph`, `deep-research-codebase`) are reserved — pick
+distinct names for your workflows. Full precedence + shadowing rules
+live in `discovery-and-verification.md`.
 
-# Free-form, positional prompt
-atomic workflow -n hello -a claude "hello world"
+## Invocation details
 
-# Structured, one flag per field
-atomic workflow -n gen-spec -a claude \
-  --research_doc=research/docs/2026-04-11-auth.md \
-  --focus=standard \
-  --notes="pay special attention to session token storage"
-
-# Structured, long-form flag value (= form)
-atomic workflow -n gen-spec -a claude --focus standard --research_doc notes.md
-
-# Detached (background) — starts the orchestrator on the atomic tmux
-# socket and returns immediately. The command prints the session name
-# and hints for attaching later. Use this for scripted / CI runs where
-# the caller shouldn't block on the TUI.
-atomic workflow -n hello -a claude -d "hello world"
-atomic workflow session connect atomic-wf-claude-hello-<id>   # attach later
-```
+See SKILL.md §"Invocation surfaces" for the table of every top-level
+command. This section only covers the flag-parsing nuances specific to
+structured inputs.
 
 Both `--flag=value` and `--flag value` forms are accepted. Short flags
 (`-x value`) are NOT parsed as structured inputs — only long-form
@@ -257,6 +234,12 @@ Both `--flag=value` and `--flag value` forms are accepted. Short flags
 The `-d` / `--detach` flag composes with any named shape (positional
 prompt, structured flags) and is independent of the inputs schema.
 
+```bash
+# Structured, both flag forms work identically
+atomic workflow -n gen-spec -a claude --focus=standard --research_doc=notes.md
+atomic workflow -n gen-spec -a claude --focus standard --research_doc notes.md
+```
+
 ## Pitfalls
 
 ### Declare every field you access