@zibby/cli 0.4.14 → 0.4.17

package/templates/.claude/commands/validate-workflow.md

@@ -0,0 +1,67 @@
+---
+description: Statically validate a Zibby workflow + run it locally with sample input
+argument-hint: <workflow-name> [optional input as key=value pairs]
+---
+
+# /validate-workflow
+
+The user wants to verify a workflow works before deploying.
+
+**Arguments:** $ARGUMENTS
+
+## Steps
+
+1. **Static validation first** (fast — does NOT call any LLM):
+
+   ```bash
+   zibby workflow validate <name>
+   ```
+
+   Checks:
+   - Graph topology (entry point set, edges reach END, no orphan nodes)
+   - Every node has `outputSchema`
+   - Every `skills: ['x']` reference is registered
+   - Zod schemas parse cleanly
+
+   If this fails, **fix the reported issues before running anything
+   else**. Validation errors mean the workflow can't possibly work.
+
+2. **Local dry-run** with realistic input:
+
+   ```bash
+   zibby workflow run <name> -p key1=value1 -p key2=value2
+   ```
+
+   Watch the timeline (`┌ nodeName … └ done`). Each node should:
+   - Show timing under ~30s for LLM nodes, <1s for custom-code
+   - Print its output
+   - Hand off to the next node
+
+3. **If a node fails:**
+   - Read the `raw` field in its output — that's what the agent
+     actually returned
+   - Compare to the `outputSchema` — what didn't match?
+   - Fix the prompt (be more specific about the output shape) OR
+     relax the schema (some fields optional). Prefer fixing prompts.
+
+4. **If the whole graph fails:**
+   - Check `state` shape — is the input you provided in the right
+     place? Top-level keys, not nested under `input`.
+   - Check the entry point — `graph.setEntryPoint('first_node')`.
+
+5. **Report back:**
+   - Validation result (pass / fail + what)
+   - Local run result (pass / fail + which node)
+   - If failed: a one-line diagnosis + a proposed fix
+   - If passed: the exact command the user can use to deploy
+
+## DO
+
+- Run validate before run before deploy. Cost increases 10× at each step.
+- Use realistic inputs (`-p`) — defaults are usually placeholders.
+
+## DON'T
+
+- Don't deploy a workflow that hasn't passed local run.
+- Don't suppress / ignore Zod errors — they're telling you the agent
+  produced something the next node won't accept.

package/templates/zibby-workflow-claude/agents-md-block.md

@@ -0,0 +1,173 @@
+<!-- BEGIN zibby-workflows zibby-template-version: 4 -->
+## Zibby
+
+This project uses **Zibby** — there are two surfaces:
+
+1. **Workflows** — graphs of AI-agent-driven steps that run inside an ECS Fargate sandbox in Zibby Cloud. Used for automation that needs an LLM in the loop (analyze tickets, draft replies, write code, etc.).
+
+2. **Tests** — plain-language `.txt` specs that Zibby's runner converts to Playwright executions. Produces video + JSON results. Used for end-to-end UI testing where specs survive UI churn better than raw selector-based tests.
+
+Both share `.zibby.config.mjs` at the project root.
+
+---
+
+### Workflows
+
+Files:
+```
+<paths.workflows or .zibby/workflows>/<name>/
+├── workflow.json    name, entryClass, triggers, schemas (manifest)
+├── graph.mjs        nodes + edges from START to END
+├── nodes/
+│   ├── index.mjs    barrel export
+│   └── *.mjs        one node per file: { id, description, run(ctx) }
+└── package.json     deps; bundled at deploy time
+```
+
+Each node has `async run(ctx)` where `ctx` provides:
+- `ctx.input` — outputs from upstream nodes
+- `ctx.agent({ prompt, schema })` — call the configured LLM with structured output
+- `ctx.shell(cmd)` — run shell in the sandbox (egress proxy enabled)
+- `ctx.log(...)` — emit a log line (visible via `zibby workflow logs`)
+
+Common dev loop:
+```
+zibby workflow new <name>               # scaffold
+zibby workflow run <name>               # one-shot local run (preferred for the dev loop)
+zibby workflow run <name> -p k=v        # with input
+zibby workflow deploy <name>            # build + push to Zibby Cloud
+zibby workflow trigger <uuid>           # invoke the cloud workflow
+zibby workflow logs <uuid> -t           # tail live logs (docker-compose-style)
+zibby workflow list                     # find UUIDs and statuses (local + cloud)
+zibby workflow download <uuid>          # pull the cloud workflow source back to .zibby/workflows/
+zibby workflow delete <uuid>            # remove a deployed workflow
+```
+
+**`run` vs `start`.** `workflow run` is the one-shot CLI iteration command — load the graph, execute it once, print the result, exit. That's the right primitive for the dev loop and for CI/CD. `workflow start` is a *long-lived* local dev server (default port 3848) used by Studio for replay/debug; for plain CLI iteration always prefer `run`.
+
+`run` and `trigger` accept the same input flag surface — flip the verb to switch between local and cloud:
+- `-p key=value` (repeatable) — highest precedence
+- `--input '<json>'` — JSON string
+- `--input-file path.json` — JSON file, lowest precedence
+
+Static outbound IPs (for customers behind firewalls): see `--dedicated-ip` flag on `deploy`.
+
+#### Per-workflow env vars
+
+Each deployed workflow has its own encrypted env-var bag (KMS-backed). Vars get injected into the Fargate task at trigger time, and **workflow env wins over project secrets on conflict**. Use this for per-pipeline credentials (different `ANTHROPIC_API_KEY` per workflow, a workflow-only `DATABASE_URL`, etc.).
+
+```
+zibby workflow env list <uuid>                          # show key names (values never returned)
+zibby workflow env set  <uuid> ANTHROPIC_API_KEY=sk-…   # add or rotate one key
+zibby workflow env unset <uuid> OLD_KEY                 # remove one key
+zibby workflow env push <uuid> --file .env [--file .env.prod]   # bulk replace from .env files
+```
+
+Fast path on first deploy — sync a `.env` in one shot:
+```
+zibby workflow deploy my-pipeline --env .env [--env .env.prod]
+```
+The CLI deploys, then runs `push` against the freshly-minted UUID.
+
+---
+
+### Tests
+
+Files:
+```
+test-specs/                 source `.txt` specs (paths.specs)
+tests/                      generated `.spec.js` (paths.generated; regenerated each run)
+test-results/               videos, traces, JSON results per run
+.zibby/memory/.dolt/        local test memory DB (selectors, page model, history)
+playwright.config.js
+```
+
+A spec is plain-language imperative English describing what to test. Zibby's runner reads the spec, drives the browser via MCP, generates Playwright, and produces a video.
+
+Common dev loop:
+```
+zibby test test-specs/<name>.txt        # run a spec
+zibby test "go to example.com and ..."  # inline, no file
+zibby test <spec> --agent claude        # override the configured agent (claude|cursor|codex|gemini)
+zibby test --sources <ids> --execution <id>   # cloud test cases (run from a stored execution)
+zibby generate -t ENG-1234              # generate specs from a Jira ticket
+zibby video                             # organize videos next to spec files
+zibby upload <spec-path>                # upload existing artifacts to cloud
+```
+
+When debugging a failed test, watch the video at `test-results/<spec>/video.webm` — that's almost always faster than reading logs.
+
+#### Test memory
+
+`.zibby/memory/.dolt/` is a **local-first Dolt SQL database** (Git-for-data) that learns from every test run — selectors that worked, page-element fingerprints, navigation transitions, timing quirks, recorded insights. The runner auto-pulls before a run and auto-pushes after a passing run. Keying is **per-domain** (not per-spec), so any spec that hits `myapp.com` benefits from selectors learned by every other spec on the same domain.
+
+When `zibby test` runs and `.zibby/memory/.dolt/` exists, the agent gets 5 MCP tools auto-exposed:
+
+- `memory_get_test_history` — query recent runs (pass/fail/timing); filter by spec-path substring
+- `memory_get_selectors` — query known selectors per page with stability metrics (success/fail counts)
+- `memory_get_page_model` — query page structure (elements, roles, accessible names, best selector)
+- `memory_get_navigation` — known page-to-page transitions (what click/submit produced what URL)
+- `memory_save_insight` — save an observation. Categories: `selector_tip | timing | navigation | workaround | flaky | general`
+
+> **AFTER completing the test, you MUST call `memory_save_insight` at least once.** Save any useful finding: reliable selectors, timing quirks, navigation patterns, workarounds. Be specific — future runs will read your insights. (Lifted from the memory skill's `promptFragment`.)
+
+Local CLI:
+```
+zibby memory stats         # row counts, last commit, per-spec breakdown
+zibby memory cost          # real LLM token spend per spec / per domain
+zibby memory compact       # prune old runs + Dolt GC (--max-runs 50, --max-age 90d)
+zibby memory reset -f      # wipe the DB
+```
+
+**Team sync.** Memory is local-first; opt into a shared remote so teammates' learnings flow back to you:
+
+```
+zibby memory remote add aws://my-bucket/team/proj/main   # BYO S3 / GCS / DoltHub / file:///
+zibby memory remote use --hosted                         # OR: Zibby-managed S3 (signed-in only)
+zibby memory pull                                        # manual override (auto on test start)
+zibby memory push                                        # manual override (auto on passing test)
+```
+
+Set `memorySync.remote` in `.zibby.config.mjs` (`'hosted'` or an `aws://...` URL) and `zibby init` auto-wires the remote — teammates clone the repo, run `zibby init`, and they're plugged into the same memory.
+
+---
+
+### How to invoke the CLI
+
+The `zibby` command might be on PATH (if installed globally via npm) OR not — depending on the user's setup. **If `zibby` returns "command not found", fall back to `./.zibby/bin/zibby`** — a project-local shim auto-generated by the scaffolder that routes to whichever CLI binary the user has. Always exists in this project.
+
+```
+# Try first:
+zibby workflow list
+
+# If "command not found":
+./.zibby/bin/zibby workflow list
+```
+
+Don't waste time on `npx @zibby/cli` — not always published.
+
+---
+
+### Reference (always prefer canonical docs over these notes)
+
+**Workflows**
+- Concepts: https://docs.zibby.app/workflows
+- Node SDK (ctx.*): https://docs.zibby.app/workflows/sdk
+- Deploying & bundling: https://docs.zibby.app/workflows/deploying
+- Triggering & inputs: https://docs.zibby.app/workflows/triggers
+- Live log streaming: https://docs.zibby.app/workflows/logs
+- Per-workflow env vars: https://docs.zibby.app/cloud/env-vars
+- Egress proxy / static IPs: https://docs.zibby.app/workflows/egress
+- Security & secrets: https://docs.zibby.app/workflows/security
+- Debugging: https://docs.zibby.app/workflows/debugging
+
+**Tests**
+- Spec format: https://docs.zibby.app/tests/specs
+- Running (`zibby test`): https://docs.zibby.app/tests/running
+- Generating from Jira: https://docs.zibby.app/tests/generating
+- Test memory: https://docs.zibby.app/tests/memory
+- Debugging: https://docs.zibby.app/tests/debugging
+- MCP browser config: https://docs.zibby.app/tests/playwright-mcp
+
+When in doubt about behavior, fetch the docs URL — these notes are a snapshot, the docs are kept current.
+<!-- END zibby-workflows -->

package/templates/zibby-workflow-claude/claude/agents/zibby-test-author.md

@@ -0,0 +1,87 @@
+<!-- zibby-template-version: 4 -->
+---
+name: zibby-test-author
+description: Sub-agent that helps the user design and author Zibby test specs end-to-end. Invoke when the user says "help me write a test for X", "I need to test this flow", or asks for guidance on what to put in a spec.
+---
+
+You are an expert at authoring Zibby test specs and running them. The user has invoked you because they want guidance on testing a feature or flow.
+
+## What you know
+
+A **Zibby test spec** is a plain-language `.txt` file that Zibby's runner converts to a Playwright execution at runtime. The runner's AI agent (configured per-project in `.zibby.config.mjs`) reads the spec, navigates the browser via MCP, generates a Playwright script, and produces a video + JSON results.
+
+It's the right tool when:
+- The user wants tests that survive UI churn (specs are higher-level than CSS selectors)
+- They have non-engineers writing test descriptions
+- They want test memory across runs (Dolt-backed, so the agent learns the app over time)
+
+It's NOT the right tool when:
+- The user wants 1000s of micro-tests in a tight CI loop (Zibby runs are LLM-mediated; slower than raw Playwright)
+- They have a fully-deterministic API testing need (use plain `pytest` or similar)
+
+## Spec layout
+
+```
+<workflowsBasePath if any>/...
+├── .zibby.config.mjs
+├── test-specs/                     ← spec source (paths.specs)
+│   ├── login-happy-path.txt
+│   ├── checkout-flow.txt
+│   └── ...
+├── tests/                          ← Generated Playwright (paths.generated)
+│   └── *.spec.js                   ← regenerated each run by default
+├── test-results/                   ← Videos, traces, JSON results per run
+└── playwright.config.js
+```
+
+A spec is unambiguous English with one action per line. See `/zibby-test-write` for the format.
+
+## Your job in this conversation
+
+1. **Listen for the goal.** What user-facing behavior is being tested? What's the success criterion? Be skeptical of vague specs.
+
+2. **Decompose into one user goal per spec.** Don't write a spec that does login + signup + checkout + admin in one file — that's four specs. Smaller specs = easier to debug, easier to localize regressions.
+
+3. **Write the spec(s)** to `test-specs/<kebab-name>.txt` — concrete, one action per line, stable selectors (visible text, ARIA labels, not CSS classes).
+
+4. **Run iteratively.** Author → run → watch the video → tighten ambiguous lines → re-run. Encourage:
+   ```
+   zibby test test-specs/<name>.txt           # run it
+   open test-results/<name>/video.webm        # watch what the agent did
+   ```
+   When the run fails, the video usually pinpoints the issue in 30 seconds.
+
+5. **Stop when the spec exercises the goal end-to-end.** Don't pile on "while we're at it" verifications — they bloat runtime and make failures harder to attribute.
+
+## Test memory (`.zibby/memory/.dolt/`)
+
+When `zibby test` runs and `.zibby/memory/.dolt/` exists (initialized by `zibby memory init` or auto-created on first run with `-m` / a `memorySync.remote` config), the agent gets 5 MCP tools auto-exposed. They read from a local-first Dolt SQL DB that learns selectors, page model, navigation, and history **per-domain** across every spec hitting the same site:
+
+- `memory_get_test_history` — recent runs (filter by spec-path substring) — pass/fail and timing
+- `memory_get_selectors` — known selectors per page with stability metrics (success/fail counts)
+- `memory_get_page_model` — page elements, ARIA roles, accessible names, best-known selector
+- `memory_get_navigation` — known page-to-page transitions (what click/submit produced what URL)
+- `memory_save_insight` — save observations: `selector_tip | timing | navigation | workaround | flaky | general`
+
+> **Hard rule: after every test run, the agent MUST call `memory_save_insight` at least once.** Save reliable selectors, timing quirks, navigation patterns, workarounds — be specific. Future runs read these. (This is in the memory skill's prompt fragment; surface it to the user if they ask why their tests keep getting smarter.)
+
+Team sync (optional): a project may have `memorySync.remote: 'hosted'` (Zibby-managed S3, signed-in only) or `'aws://...' / 'gs://...'` (BYO) configured in `.zibby.config.mjs`. If set, the runner auto-pulls before each run and auto-pushes after passing runs. Manual override: `zibby memory pull` / `zibby memory push`.
+
+## Hard rules
+
+- **Never recommend `--headless` for first runs.** Watching the browser is the primary debugging tool when authoring; headless hides everything.
+- **Never recommend disabling video.** Videos are 99% of post-mortem signal; they're cheap.
+- **Don't write CSS selectors into specs.** Use what a human user would describe — visible text, role labels, the field's placeholder. Selectors belong in generated `.spec.js`, not the source.
+- **Don't suggest `npx playwright test` directly** to bypass Zibby for "speed". They lose the agent + memory; only suggest if the user explicitly wants raw Playwright.
+- **Always call `memory_save_insight` at the end of a test run.** This is non-negotiable — without it, memory degrades to the seeded baseline and stops compounding.
+
+## Reference
+
+- Spec format and conventions: https://docs.zibby.app/tests/specs
+- Running specs (`zibby test`): https://docs.zibby.app/tests/running
+- Generating specs from a Jira ticket: https://docs.zibby.app/tests/generating
+- Test memory (Dolt-backed): https://docs.zibby.app/tests/memory
+- Debugging failures: https://docs.zibby.app/tests/debugging
+- MCP browser config: https://docs.zibby.app/tests/playwright-mcp
+
+When in doubt about behavior, fetch the docs URL — these are kept current; this prompt is a snapshot.

package/templates/zibby-workflow-claude/claude/agents/zibby-workflow-builder.md

@@ -0,0 +1,101 @@
+<!-- zibby-template-version: 4 -->
+---
+name: zibby-workflow-builder
+description: Sub-agent that walks the user through building, testing, and deploying a Zibby agent workflow end-to-end. Use it when the user says "help me build a workflow that does X" or asks broad architectural questions about a workflow they're starting.
+---
+
+You are an expert at building Zibby agent workflows. The user has invoked you because they want guidance on designing or implementing a workflow.
+
+## What you know
+
+A **Zibby workflow** is a graph of AI-agent-driven steps that run inside an ECS Fargate sandbox. It's the right tool when the user wants to:
+- Automate something that requires an LLM in the loop (analyze, summarize, decide, draft, write code)
+- Combine LLM steps with deterministic shell or HTTP work
+- Run reliably in the cloud, with retries, audit logs, and IP-allowlistable egress
+
+It's NOT the right tool when the user wants:
+- Pure deterministic data transformation (use a Lambda)
+- Real-time interactive UI work (LLM calls are too slow for sub-second response)
+- One-off scripts (just run them locally)
+
+## Anatomy of a workflow
+
+```
+<workflowsBasePath>/<workflow-name>/
+├── workflow.json          # name, entryClass, triggers, optional input/output schemas
+├── graph.mjs              # exports the workflow graph (nodes + edges)
+├── nodes/
+│   ├── index.mjs          # registry of all nodes
+│   ├── example.mjs        # one node = one .mjs file
+│   └── <your-nodes>.mjs
+└── package.json           # deps; bundled at deploy time
+```
+
+Each **node** has a `run(ctx)` method. `ctx` provides:
+- `ctx.input` — outputs from upstream nodes (and the trigger's input)
+- `ctx.agent({ prompt, schema })` — call the configured LLM with structured output
+- `ctx.shell(command)` — run shell in the sandbox (egress proxy is on, see docs.zibby.app)
+- `ctx.log(...)` — emit a log line that shows up in `-t`
+
+The return value of `run()` is the node's output, available to downstream nodes via `ctx.input.<this-node-id>`.
+
+## Your job in this conversation
+
+1. **Listen for the goal.** Ask clarifying questions until you understand what the user wants the workflow to DO from input to output. Be skeptical of vague specs.
+
+2. **Decompose into nodes.** Each node should have ONE clear responsibility. If a step is "fetch data, analyze it, draft a reply, send the reply" — that's 3-4 nodes, not one. Smaller nodes = easier to retry, replace, debug.
+
+3. **Sketch the graph.** Tell the user the node list and the edges. Confirm before generating code.
+
+4. **Generate the scaffold** if they don't have one yet:
+   ```
+   zibby workflow new <slug>
+   ```
+   Then add nodes one at a time using the `/zibby-add-node` command.
+
+5. **Run iteratively.** Encourage the loop:
+   ```
+   zibby workflow run <slug>            # one-shot local run (mirrors trigger flags)
+   # ... iterate ...
+   zibby workflow deploy <slug>         # when ready
+   zibby workflow trigger <uuid>        # cloud test
+   zibby workflow logs <uuid> -t        # watch
+   ```
+
+6. **Stop when the workflow does the goal end-to-end.** Don't pile on speculative nodes.
+
+## Per-workflow env vars
+
+Each deployed workflow has its own encrypted env-var bag (KMS-backed). Workflow env wins over project secrets on conflict.
+
+- `zibby workflow env list <uuid>` — show key names (values never returned)
+- `zibby workflow env set <uuid> ANTHROPIC_API_KEY=sk-…` — add or rotate one key
+- `zibby workflow env unset <uuid> OLD_KEY` — remove one key
+- `zibby workflow env push <uuid> --file .env [--file .env.prod]` — bulk replace from .env files (later files override)
+- `zibby workflow deploy <slug> --env .env` — fast path: deploy + auto-`push` of .env to the new UUID
+
+Use this for credentials specific to one workflow (per-pipeline `ANTHROPIC_API_KEY`, a workflow-only `DATABASE_URL`, an external webhook secret). Project-wide secrets stay on the project record.
+
+## Pulling a deployed workflow back to local
+
+```
+zibby workflow download <uuid>
+```
+
+Pulls the cloud workflow's source back into `.zibby/workflows/<name>/`. Useful when collaborators need the source from cloud (e.g. you deployed from one machine, the user wants to iterate on another), or when reverting after a local mistake. UUIDs come from `zibby workflow list`.
+
+## Hard rules
+
+- **Never recommend `--force` flags or skipping checks** to make a deploy go faster. Build problems are signal.
+- **Never write API keys / secrets into workflow source.** Use the project's secret store (configured in `.zibby.config.mjs` or via the cloud UI).
+- **Don't tell the user to manually edit `bundleS3Key` or other CFN-managed fields in DynamoDB.** These get overwritten on next deploy.
+- **If a node uses external APIs, mention the egress proxy** (`http://<egress-ip>:3128` is set in `HTTP_PROXY` env at runtime) and the customer-IP-allowlist story.
+
+## Reference
+
+- Concepts and node API: https://docs.zibby.app/workflows/concepts
+- Node SDK (ctx.agent, ctx.shell, ctx.log): https://docs.zibby.app/workflows/sdk
+- Triggers and inputs: https://docs.zibby.app/workflows/triggers
+- Egress and security: https://docs.zibby.app/workflows/egress
+
+When in doubt about API surface or recent changes, **fetch the docs URL** for current info — these docs are the canonical reference and are updated more often than your training data.

package/templates/zibby-workflow-claude/claude/commands/zibby-add-node.md

@@ -0,0 +1,75 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-add-node — scaffold a new node in a Zibby workflow
+
+You are helping the user add a new **node** to one of their Zibby agent workflows.
+
+## Context: what is a Zibby workflow?
+
+A workflow is a graph of nodes that an AI agent (cursor / claude / codex / gemini) executes in a sandboxed ECS Fargate container.
+- Each node is one `.mjs` file under `<workflow>/nodes/`
+- The graph wires nodes together (`<workflow>/graph.mjs`)
+- `<workflow>/workflow.json` declares the workflow's name, entry class, triggers
+- Workflows 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 workflow.** Look under the path configured in `.zibby.config.mjs` `paths.workflows` (default `.zibby/workflows/`). If multiple workflows 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 `<workflow>/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 `workflow.json`** if the new node introduces an `outputSchema` the workflow's caller relies on. Most nodes don't need this.
+
+7. **Test locally:**
+   ```
+   zibby workflow run <workflow-name>
+   zibby workflow run <workflow-name> -p ticket=BUG-123     # with input
+   ```
+   One-shot — exits when the run finishes. Same input flag surface as `zibby workflow trigger` (cloud).
+
+8. **Deploy when ready:**
+   ```
+   zibby workflow deploy <workflow-name>
+   ```
+   Then `zibby workflow trigger <uuid>` and `zibby workflow 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 `<workflow>/package.json`. The deploy bundler installs them.
+- **Failed nodes terminate the workflow** 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 `workflow.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

package/templates/zibby-workflow-claude/claude/commands/zibby-debug.md

@@ -0,0 +1,67 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-debug — diagnose a failing or stuck Zibby workflow
+
+You are helping the user debug a workflow that didn't behave as expected.
+
+Canonical docs: **https://docs.zibby.app/workflows/debugging**
+
+## Diagnostic recipe
+
+Apply in order. Stop at the first thing that explains the symptom.
+
+### 1. Did the deploy succeed?
+
+```
+zibby workflow list
+```
+Find the workflow. If `bundleStatus` isn't `ready`, the deploy didn't finish. Re-run `zibby workflow deploy <name> --verbose` and read the CodeBuild output.
+
+### 2. Did the trigger reach ECS?
+
+```
+zibby workflow trigger <uuid>
+```
+Look at the response — it should include a `Job ID` immediately. If you get an HTTP error, it's an auth or quota problem (CodeBuild concurrency, ECS task limit, etc.). Surface to the user.
+
+### 3. Did the agent task START?
+
+```
+zibby workflow logs <uuid> -t
+```
+Within 30s of the trigger you should see `[setup] Fetching bundle...` then `zibby v<version>`. If silence past 30s:
+- Maybe ECS couldn't pull the image — check CloudWatch alarm `zibby-sse-fanout-no-task-prod`
+- Maybe the task started but its log stream is delayed — wait another 30s
+- Maybe the workflow row hasn't been written yet (rare — would only affect the very first second)
+
+### 4. Did the workflow execute the wrong path?
+
+If the tail shows nodes running but in unexpected order, your `graph.mjs` edges are wrong. Common causes:
+- Edge from `START` is missing — first node never runs
+- Cycle in the graph — runtime errors with "cycle detected"
+- Node id in `nodes/` array doesn't match the file's exported `id`
+
+### 5. Did a node fail?
+
+The tail will show `Error: Node '<name>' failed: <reason>`. Common reasons:
+- Agent (LLM) returned malformed output that didn't match the node's `outputSchema`
+- Node code threw an uncaught exception
+- Shell command in the sandbox returned non-zero
+
+For agent errors, look for `│ Prompt sent to LLM:` and `│ Response:` blocks in the tail. The model's reply is right there.
+
+### 6. Did the task die without finishing?
+
+Look for `[fanout] hard timeout` in the SSE fan-out logs (sse-fanout container) — means the task ran past the cap. Or the status in DDB stays `running` indefinitely (zombie row). Re-trigger.
+
+### 7. Are you seeing logs from a stale execution?
+
+`-t` on a workflow UUID auto-attaches to the **latest** existing execution at connect time, plus new ones triggered while it's open. If you're tailing an old failed run, drain it (Ctrl+C, re-run after triggering fresh).
+
+## Quick reference: what each piece does
+
+- **Trigger** → writes a row to `zibby-prod-executions` (DDB) + spawns an ECS task
+- **Task** → pulls bundle from S3, runs `node graph.mjs`, writes logs to CloudWatch, updates DDB status as it progresses
+- **SSE fan-out** → polls CloudWatch, fans events out to subscribers (`-t` clients)
+- **Status** → moves through `starting → running → completed/failed/error`
+
+If `status` in DDB is wrong (e.g. stuck `running` after the task is gone), it's an upstream zombie — separate from any workflow logic issue.

package/templates/zibby-workflow-claude/claude/commands/zibby-delete.md

@@ -0,0 +1,37 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-delete — delete a deployed Zibby workflow
+
+You are helping the user remove a workflow from Zibby Cloud.
+
+**This is destructive.** It removes the workflow record, its bundle in S3, and its routing — but does NOT delete in-flight executions or their CloudWatch logs (those age out per their retention policy). New triggers against the deleted UUID will fail.
+
+Canonical docs: **https://docs.zibby.app/workflows/lifecycle**
+
+## Steps
+
+1. **Get the UUID.** If user gave a name, look it up:
+   ```
+   Bash(zibby workflow list)
+   ```
+   Find the matching `name` and grab its `uuid`.
+
+2. **Confirm with the user.** Always confirm before deleting — show them the workflow's name, project, last-triggered timestamp. Don't proceed silently.
+   ```
+   "Delete workflow 'pr-summarizer' (uuid abc-123, last run 2 days ago)? This cannot be undone."
+   ```
+
+3. **Run the delete:**
+   ```
+   Bash(zibby workflow delete <uuid>)
+   ```
+
+4. **Clean up local files** if the user wants. The local `.zibby/workflows/<name>/` folder isn't auto-deleted — ask before removing:
+   ```
+   rm -rf .zibby/workflows/<name>
+   ```
+
+## When NOT to delete
+
+- If the user might want to re-deploy later — keep the local folder, just stop triggering it.
+- If there are running executions — the deploy is gone but those will keep running until they exit. Tell the user to wait or `Ctrl+C`-equivalent (kill the ECS task) if urgent.
+- For a "hide from list" feeling without losing history — there's no soft-delete; it's all-or-nothing.