---
description: Add a node to an existing Zibby workflow graph
argument-hint: <workflow-name> <node-purpose>
---

# /zibby-add-node — extend an existing workflow with a new node

The user wants to extend an existing workflow with a new node.

**Arguments:** $ARGUMENTS

## Steps

1. **Find the workflow** — should be at `agents/<name>/`. If
   the user didn't specify a name and there's only one workflow, use
   that. If there are multiple, ask which.

2. **Read the existing `graph.mjs`** to understand:
   - Current node sequence
   - State shape (what each prior node returns)
   - Where the new node should slot in (before / after / parallel)

3. **Decide LLM vs custom-code:**
   - Custom-code (`execute`): the work is deterministic — git ops,
     file IO, HTTP, parsing structured data, math
   - LLM (`prompt`): the work needs judgement — summarization,
     classification, generation, planning

4. **Create the node file** at `agents/<name>/nodes/<node>.mjs`:

   ```js
   import { z } from 'zod';

   export const myNode = {
     name: 'my_node',
     outputSchema: z.object({ /* what this returns to state */ }),
     prompt: (state) => `…use state.previousNodeName.field…`,
     // OR for custom-code:
     // execute: async (state) => ({ /* match outputSchema */ }),
   };
   ```

5. **Wire it into `graph.mjs`:**
   - `import { myNode } from './nodes/my-node.mjs';`
   - `graph.addNode('my_node', myNode);`
   - `graph.addEdge('prev_node', 'my_node');`
   - `graph.addEdge('my_node', 'next_node');` (or 'END')

6. **Validate + run** to confirm it integrates:
   ```bash
   zibby agent validate <name>
   zibby agent run <name> -p ...
   ```

7. **Report**: what node you added, how state changed, the test result.

## Watch for

- The new node's `prompt` references `state.X.field` — make sure that
  field exists in the previous node's `outputSchema`. If it doesn't,
  fix the producer schema, not the consumer prompt.
- Don't change other nodes' schemas without telling the user — that's
  a breaking change to downstream consumers.