<!-- zibby-template-version: 4 -->
# /zibby-add-node — scaffold a new node in a Zibby agent

You are helping the user add a new **node** to one of their Zibby agents.

## Context: what is a Zibby agent?

A agent is a graph of nodes that an AI agent (cursor / claude / codex / gemini) executes in a sandboxed container.
- Each node is one `.mjs` file under `<agent>/nodes/`
- The graph wires nodes together (`<agent>/graph.mjs`)
- `<agent>/agent.json` declares the agent's name, entry class, triggers
- Agents live under `<workflowsBasePath>/<workflow-name>/` (default `.zibby/workflows/`, configured in the project root's `.zibby.config.mjs`)

For canonical, evolving docs see **https://docs.zibby.app/workflows/nodes**

## Steps for this command

1. **Identify the target agent.** Look under the path configured in `.zibby.config.mjs` `paths.agents` (default `.zibby/workflows/`). If multiple agents exist, ask the user which one. If they're already `cd`'d inside one, infer from `${cwd}`.

2. **Get the node spec from the user.** Ask:
   - Node name (kebab-case, e.g. `analyze-ticket`)
   - One-sentence description of what it does
   - Inputs (variables it reads from prior nodes)
   - Outputs (variables it produces — these become available to downstream nodes)

3. **Create the node file** at `<agent>/nodes/<name>.mjs`. Pattern from the existing `example.mjs`:
   ```js
   export default {
     id: '<name>',
     description: '<one-sentence description>',
     async run(ctx) {
       // ctx.input — outputs from upstream nodes
       // ctx.agent — call the configured AI agent
       // ctx.shell — run shell commands in the sandbox
       // return value becomes the node's output
       return { /* ... */ };
     },
   };
   ```

4. **Register the node in `nodes/index.mjs`** — add the import + export.

5. **Wire into `graph.mjs`** — add the node id to the graph's `nodes` array, then add an `edge` from its predecessor (or from `START` if it's first) and an edge to `END` (or its successor).

6. **Update `agent.json`** if the new node introduces an `outputSchema` the agent's caller relies on. Most nodes don't need this.

7. **Test locally:**
   ```
   zibby agent run <workflow-name>
   zibby agent run <workflow-name> -p ticket=BUG-123     # with input
   ```
   One-shot — exits when the run finishes. Same input flag surface as `zibby agent trigger` (cloud).

8. **Deploy when ready:**
   ```
   zibby agent deploy <workflow-name>
   ```
   Then `zibby agent trigger <uuid>` and `zibby agent logs <uuid> -t` to verify.

## Common pitfalls

- **Node name must match the file name and `id`** — mismatches cause silent skip.
- **`ctx.agent` calls block on the LLM** — large prompts can take 30+ seconds. Stream output for visibility.
- **Don't import npm packages inside `run()`** — declare deps in `<agent>/package.json`. The deploy bundler installs them.
- **Failed nodes terminate the agent** unless wrapped in try/catch and explicit `outputSchema.status: 'warn'`.

## When to consult the user vs proceed

Always ask before:
- Creating a node that calls external APIs (cost / data egress concern)
- Modifying `agent.json` (changes the contract for downstream callers)

Proceed without asking when:
- Just adding a self-contained node and wiring it
- Tweaking the example/implementation in response to user spec