workflow-creator（工作流程创建者）

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.

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.

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.

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.

// 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:

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):

# 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:

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():

atomic workflow -n <name> -a <agent> [inputs...]

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.

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:

When to use a stage vs. plain TypeScript

Before reaching for ctx.stage(), ask: does this block need an LLM?

// ✓ 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:

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():

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:

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:

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:

# 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".