@bastani/atomic 0.5.34 → 0.6.0

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

@@ -1,275 +0,0 @@
-# Workflow Authors: Getting Started
-
-This guide covers the basics of creating workflows with the `defineWorkflow().run().compile()` API.
-
-## Quick-start example
-
-Use `defineWorkflow({...}).for<"agent">().run(callback).compile()` to define your workflow. Inside the `.run()` callback, use `ctx.stage()` to spawn agent sessions dynamically. Each session gets its own tmux window and graph node. Use native TypeScript control flow (`for`, `if`, `Promise.all()`) for orchestration.
-
-The runtime manages the full session lifecycle automatically — it creates the client, creates the session, runs your callback, then cleans up. You never need to manually disconnect or stop anything.
-
-### Claude
-
-```ts
-// .atomic/workflows/my-workflow/claude/index.ts
-import { defineWorkflow, extractAssistantText } from "@bastani/atomic/workflows";
-
-export default defineWorkflow({
-    name: "my-workflow",
-    description: "A two-session pipeline",
-    inputs: [
-      { name: "prompt", type: "text", required: true, description: "task to perform" },
-    ],
-  })
-  .for<"claude">()
-  .run(async (ctx) => {
-    const prompt = ctx.inputs.prompt ?? "";
-
-    const describe = await ctx.stage(
-      { name: "describe", description: "Ask Claude to describe the project" },
-      {},
-      {},
-      async (s) => {
-        await s.session.query(prompt);
-        s.save(s.sessionId);
-      },
-    );
-
-    await ctx.stage(
-      { name: "summarize", description: "Summarize the previous session's output" },
-      {},
-      {},
-      async (s) => {
-        const research = await s.transcript(describe);
-        await s.session.query(
-          `Read ${research.path} and summarize it in 2-3 bullet points.`,
-        );
-        s.save(s.sessionId);
-      },
-    );
-  })
-  .compile();
-```
-
-### Copilot
-
-```ts
-// .atomic/workflows/my-workflow/copilot/index.ts
-import { defineWorkflow } from "@bastani/atomic/workflows";
-
-export default defineWorkflow({
-    name: "my-workflow",
-    description: "A two-session pipeline",
-    inputs: [
-      { name: "prompt", type: "text", required: true, description: "task to perform" },
-    ],
-  })
-  .for<"copilot">()
-  .run(async (ctx) => {
-    const prompt = ctx.inputs.prompt ?? "";
-
-    const describe = await ctx.stage(
-      { name: "describe", description: "Ask the agent to describe the project" },
-      {},
-      {},
-      async (s) => {
-        await s.session.send({ prompt });
-        s.save(await s.session.getMessages());
-      },
-    );
-
-    await ctx.stage(
-      { name: "summarize", description: "Summarize the previous session's output" },
-      {},
-      {},
-      async (s) => {
-        const research = await s.transcript(describe);
-        await s.session.send({
-          prompt: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
-        });
-        s.save(await s.session.getMessages());
-      },
-    );
-  })
-  .compile();
-```
-
-### OpenCode
-
-```ts
-// .atomic/workflows/my-workflow/opencode/index.ts
-import { defineWorkflow } from "@bastani/atomic/workflows";
-
-export default defineWorkflow({
-    name: "my-workflow",
-    description: "A two-session pipeline",
-    inputs: [
-      { name: "prompt", type: "text", required: true, description: "task to perform" },
-    ],
-  })
-  .for<"opencode">()
-  .run(async (ctx) => {
-    const prompt = ctx.inputs.prompt ?? "";
-
-    const describe = await ctx.stage(
-      { name: "describe", description: "Ask the agent to describe the project" },
-      {},
-      { title: "describe" },
-      async (s) => {
-        const result = await s.client.session.prompt({
-          sessionID: s.session.id,
-          parts: [{ type: "text", text: prompt }],
-        });
-        s.save(result.data!);
-      },
-    );
-
-    await ctx.stage(
-      { name: "summarize", description: "Summarize the previous session's output" },
-      {},
-      { title: "summarize" },
-      async (s) => {
-        const research = await s.transcript(describe);
-        const result = await s.client.session.prompt({
-          sessionID: s.session.id,
-          parts: [{ type: "text", text: `Summarize the following in 2-3 bullet points:\n\n${research.content}` }],
-        });
-        s.save(result.data!);
-      },
-    );
-  })
-  .compile();
-```
-
-Reading top-to-bottom: `describe → summarize`. Each session spawns a graph node and tmux window.
-
-## Native TypeScript control flow
-
-Sessions are spawned dynamically, so you can use loops, conditionals, and `Promise.all()`:
-
-```ts
-// Parallel sessions
-const [a, b] = await Promise.all([
-  ctx.stage({ name: "task-a" }, {}, {}, async (s) => { /* ... */ }),
-  ctx.stage({ name: "task-b" }, {}, {}, async (s) => { /* ... */ }),
-]);
-
-// Loop with dynamic sessions
-for (let i = 1; i <= maxIterations; i++) {
-  const result = await ctx.stage({ name: `step-${i}` }, {}, {}, async (s) => {
-    // ... do work ...
-    return someValue; // available as result.result
-  });
-  if (result.result === "done") break;
-}
-
-// Conditional sessions
-if (needsReview) {
-  await ctx.stage({ name: "review" }, {}, {}, async (s) => { /* ... */ });
-}
-```
-
-## Headless (background) stages
-
-Set `headless: true` in the stage options to run the provider SDK
-in-process instead of spawning a tmux window — invisible in the graph,
-identical callback API.
-
-```ts
-const result = await ctx.stage(
-  { name: "background-task", headless: true },
-  {}, {},
-  async (s) => {
-    const result = await s.session.query("Analyze the codebase.");
-    s.save(s.sessionId);
-    return extractAssistantText(result, 0);
-  },
-);
-```
-
-For per-provider mechanics, the canonical fan-out pattern (visible seed →
-parallel headless → visible merge), and topology semantics, see
-`control-flow.md` §"Headless stages: transparent to graph topology" and the
-per-SDK "Headless mode" sections in `agent-sessions.md`. Failure visibility
-caveats live in `failure-modes.md` §F15.
-
-## SDK exports
-
-The `@bastani/atomic/workflows` package exports the workflow authoring primitives. For native SDK types and utilities, install and import from the provider packages directly.
-
-**Builder:**
-- `defineWorkflow` — entry point; returns a chainable `WorkflowBuilder`. Use `.for<"agent">()` on the builder to narrow types to a specific provider.
-- `WorkflowBuilder` — the builder class (rarely needed directly)
-
-**Types** (import with `import type`):
-- `AgentType` — `"copilot" | "opencode" | "claude"`
-- `Transcript` — `{ path: string, content: string }` from `ctx.transcript()`
-- `SavedMessage` — union of provider-specific message types
-- `SaveTranscript` — overloaded save function type
-- `SessionContext` — the context object passed to `ctx.stage()` callbacks
-- `SessionHandle<T>` — returned by `ctx.stage()`, carries `{ name, id, result }`
-- `SessionRunOptions` — `{ name, description?, headless? }` for `ctx.stage()` first argument
-- `StageClientOptions<A>` — provider-specific client init options for `ctx.stage()` second argument
-- `StageSessionOptions<A>` — provider-specific session create options for `ctx.stage()` third argument
-- `ProviderClient<A>` — the `s.client` type, resolved by agent type
-- `ProviderSession<A>` — the `s.session` type, resolved by agent type
-- `ClaudeSessionWrapper` — Atomic wrapper for Claude sessions (exposes `s.session.query()`, which returns `SessionMessage[]`)
-- `SessionRef` — `string | SessionHandle<unknown>` for transcript/message lookups
-- `WorkflowContext` — top-level context passed to `.run()` callback
-- `WorkflowOptions` — `{ name, description? }` workflow metadata
-- `WorkflowDefinition` — sealed output of `.compile()`
-
-**Response utilities:**
-- `extractAssistantText(messages, afterIndex)` — extract plain text from the `SessionMessage[]` returned by `s.session.query()` for Claude; use `extractAssistantText(result, 0)` to get the full assistant response text
-
-**Validation helpers:**
-- `validateClaudeWorkflow` — static validation for Claude workflow source files; warns on direct `createClaudeSession` or `claudeQuery` usage
-- `validateCopilotWorkflow` — static validation for Copilot workflow source files; warns on manual `new CopilotClient` or `client.createSession()` usage
-- `validateOpenCodeWorkflow` — static validation for OpenCode workflow source files; warns on manual `createOpencodeClient()` or `client.session.create()` usage
-
-**Native SDK dependencies:**
-
-The Atomic runtime provides `s.client` and `s.session` with types resolved from the native SDKs. If you need to name those types in your own code, or use SDK utilities and advanced APIs, import them directly from the provider packages:
-
-| Provider | Package | Key imports |
-|----------|---------|-------------|
-| Copilot | `@github/copilot-sdk` | `SessionEvent`, `CopilotClient`, `CopilotSession`, `approveAll`, `defineTool` |
-| Claude | `@anthropic-ai/claude-agent-sdk` | `SessionMessage`, `query` |
-| OpenCode | `@opencode-ai/sdk/v2` | `SessionPromptResponse`, `OpencodeClient`, `Session` |
-
-## `SessionContext` reference
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `client` | `ProviderClient<A>` | Pre-created SDK client (auto-managed by runtime) |
-| `session` | `ProviderSession<A>` | Pre-created provider session (auto-managed by runtime) |
-| `inputs` | `{ [K in N]?: string }` | Typed inputs for this run — only declared field names are valid keys. Accessing an undeclared field is a compile-time error. See `workflow-inputs.md`. |
-| `agent` | `AgentType` | Which agent is running |
-| `transcript(ref)` | `(ref: SessionRef) => Promise<Transcript>` | Get prior session's transcript as `{ path, content }` |
-| `getMessages(ref)` | `(ref: SessionRef) => Promise<SavedMessage[]>` | Get prior session's raw native messages |
-| `save` | `SaveTranscript` | Save this session's output for downstream sessions |
-| `sessionDir` | `string` | Path to session storage directory |
-| `paneId` | `string` | tmux pane ID (or `headless-<name>-<id>` for headless stages) |
-| `sessionId` | `string` | Session UUID |
-| `stage(opts, clientOpts, sessionOpts, fn)` | `<T>(...) => Promise<SessionHandle<T>>` | Spawn a nested sub-session (child of this session in the graph) |
-
-## Reference files
-
-The full table of references with load triggers lives in SKILL.md
-§"Reference Files". Pull `failure-modes.md` before shipping any
-multi-session workflow, and `agent-sessions.md` whenever writing SDK calls.
-
-## Builtin reference implementations
-
-The SDK ships two builtin workflows that demonstrate production patterns for all three SDKs:
-
-- **`ralph`** (`src/sdk/workflows/builtin/ralph/`) — iterative plan → orchestrate → review → debug loop with consecutive clean-pass detection, shared helpers for prompts/parsing/git, and cross-SDK adaptation
-- **`deep-research-codebase`** (`src/sdk/workflows/builtin/deep-research-codebase/`) — deterministic codebase scout → LOC-based heuristic explorer partitioning → parallel explorers → aggregator with file-based handoffs and context-aware prompt engineering
-
-Both include `helpers/` directories with SDK-agnostic logic (prompt builders, parsers, heuristics) and per-agent `index.ts` files showing how the same workflow topology adapts to Claude, Copilot, and OpenCode.
-
-For a minimal headless example (not a builtin — it lives as a local workflow in this repo), see `.atomic/workflows/headless-test/` — demonstrates the visible → [parallel headless] → visible merge pattern for all three SDKs.
-
-## Type safety
-
-The SDK avoids `any` and uses `unknown` only at well-defined boundaries (e.g., `SessionRef = string | SessionHandle<unknown>` for handle-erased lookups). `SessionContext` fields are precisely typed, and native provider types may appear inside Atomic generic aliases and runtime values — if you need to name those types in your own code, import them from the provider SDK directly. Use `import type` for type-only imports. Use `.for<"agent">()` to narrow `s.client` and `s.session` to the correct provider types. Declare `inputs` inline so TypeScript enforces typed access on `ctx.inputs`.

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

@@ -1,235 +0,0 @@
-# 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.