---
description: Scaffold a new Zibby workflow from a natural-language description
argument-hint: <description of what the workflow should do>
---

# /zibby-new-workflow

You're about to create a new Zibby workflow. The user's request is:

**$ARGUMENTS**

## Steps

1. **Sketch the graph.** Based on the user's request, decide:
   - How many nodes? (Typically 2-5. More than 7 is usually a sign of
     overdesign — collapse adjacent nodes.)
   - Which nodes need an LLM (judgement, generation) vs custom-code
     (deterministic: git ops, HTTP, file IO)?
   - What's the linear sequence vs conditional branching?
   - What's the final output the user cares about?

2. **Pick a workflow name** — kebab-case, ≤24 chars, descriptive.
   Examples: `code-review`, `pr-summary`, `nightly-changelog`.

3. **Run the scaffold:**
   ```bash
   zibby agent new <name>
   ```
   This creates `agents/<name>/` with starter files.

4. **Edit the files** in this order (read CLAUDE.md §1 if you've forgotten the shapes):
   - `agent.json` — set `name`, `description`, `defaultAgent`
   - `nodes/*.mjs` — one file per node, each with `name`, `outputSchema`
     (Zod), and either `prompt` (LLM) or `execute` (custom-code)
   - `graph.mjs` — wire them up with `addNode` + `addEdge` + `setEntryPoint`

5. **Validate** (this catches 80% of mistakes before running anything):
   ```bash
   zibby agent validate <name>
   ```
   Fix any reported issues.

6. **Test locally** with a realistic input:
   ```bash
   zibby agent run <name> -p <key>=<value>
   ```
   Watch the timeline. If a node fails, the `raw` field shows what the
   agent actually returned vs what the schema expected.

7. **Report back to the user** with:
   - The workflow path
   - The local test result
   - The exact `zibby agent run` command they can use
   - Ask if they want to deploy

## DO NOT

- Don't deploy without asking (`zibby agent deploy` has cost)
- Don't use `state.set()` / `state.get()` inside `execute()` — just `return`
- Don't skip `zibby agent validate` — it catches schema typos fast
- Don't add nodes the request didn't ask for