---
title: create-workflow
description: Build a new Smithers workflow from a plain-English ask.
---

`create-workflow` turns a plain-English description into a real, runnable Smithers
workflow. It is the authoring counterpart to the rest of the pack: instead of
hand-writing a `.tsx` graph and its prompts, you describe what you want and the
workflow clarifies it, gathers the right docs and skills, designs the graph, scaffolds
the files, verifies the graph renders, and writes an agent-facing skill doc.

```bash
bunx smithers-orchestrator workflow run create-workflow \
  --prompt "A workflow that watches a landing request and auto-lands it once CI is green"
```

By default it pauses for you to approve the design before any files are written.
Clear the gate with `bunx smithers-orchestrator approve RUN_ID --node approve-design`, or run
autonomously with `--input '{"review":false}'`.

## Stages

1. **clarify**: turn the freeform ask into a structured, buildable spec (goal, trigger, inputs, stages, loops, human gates, success criteria).
2. **provision**: pull the relevant `llms-*.txt` docs, find the closest `examples/` template, pick components to compose, and **install the worker skills** the new workflow needs (`bunx smithers-orchestrator skills add`).
3. **design**: produce the concrete graph blueprint (schemas, tasks, JSX shape, prompts to author).
4. **approve-design**: durable human approval gate (skippable via `review: false`).
5. **scaffold**: write the workflow `.tsx` and its `.mdx` prompts to `.smithers/`.
6. **verify**: `bunx smithers-orchestrator graph` the new workflow (load + render without executing); a fix agent edits and retries until it renders cleanly.
7. **document**: write a skill doc so future agents know how to run the new workflow.

## Inputs

| Input | Type | Default |
| --- | --- | --- |
| `prompt` | string | `"Describe the workflow you want to build, in plain English."` |
| `name` | string or null | `null` (the clarify/design steps choose a kebab-case id) |
| `review` | boolean | `true` (pause for design approval before writing files) |

## Monitor it

```bash
bunx smithers-orchestrator workflow run create-workflow --prompt "…" -d   # detach
bunx smithers-orchestrator ps                                             # active / paused / recent
bunx smithers-orchestrator logs RUN_ID -f                                # follow events
bunx smithers-orchestrator approve RUN_ID --node approve-design          # clear the design gate
```

Use this when you want to add a new automation to your `.smithers/` pack without
learning the full authoring API first. The workflow grounds its design in the real
Smithers components and verifies the result before handing it back.
