@zibby/cli 0.1.90 → 0.1.95

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-tail.md

@@ -0,0 +1,53 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-tail — stream live logs from a Zibby workflow
+
+You are helping the user tail logs from a workflow execution.
+
+`zibby workflow logs <jobId> -t` is the live-streaming variant (like `heroku logs --tail` or `docker compose logs -f`). Without `-t`, you get a one-shot fetch.
+
+Canonical docs: **https://docs.zibby.app/workflows/logs**
+
+## What `<jobId>` accepts
+
+- A **workflow UUID** (`2b1ea07f-...`) → tails ALL currently-active executions of that workflow, plus any new ones triggered while the tail is open. Lines are interleaved by arrival time, prefixed with `(taskId)` so concurrent runs are distinguishable.
+- An **execution ID** (`abc-...`) → tails just that single execution. Closes when the execution drains.
+
+## Example flow
+
+```
+$ zibby workflow trigger 2b1ea07f-3ede-4bfd-a51d-431f0bab008e
+Job ID: 569ef1ee-15c8-4ee7-af30-933c8bec7ea7
+
+$ zibby workflow logs 2b1ea07f-3ede-4bfd-a51d-431f0bab008e -t
+  Streaming logs for workflow 2b1ea07f-...
+  Press Ctrl+C to stop.
+
+  ┌─ Execution: 569ef1ee...7ea7 (task: 9e61c690)
+  └─ Streaming logs...
+
+2026-05-04 06:16:27.621  (9e61c690) zibby v0.1.91
+2026-05-04 06:16:27.997  (9e61c690)  Workflow:  hello-world
+2026-05-04 06:16:33.055  (9e61c690) │ Prompt sent to LLM:
+...
+2026-05-04 06:16:56.389  (9e61c690) ✓ Workflow completed
+```
+
+## Tail behavior worth knowing
+
+- **Auto-switch:** when the current execution drains and a new trigger lands, the tail seamlessly picks it up — no need to re-run the command.
+- **Multi-attach:** if you trigger two workflows in parallel, the tail attaches to both. Lines from each are interleaved by timestamp.
+- **Reconnect:** transient network blips reconnect silently. Long quiet windows (3+ min) are kept alive via 5s keepalives.
+
+## Steps for this command
+
+1. Identify the jobId. If user gives a workflow name (not UUID), look it up via `zibby workflow list` and use the UUID.
+2. **Run in the background** — `-t` is a long-running stream. If you call `Bash` without `run_in_background: true` it'll block the chat for minutes:
+   ```
+   Bash({ command: "zibby workflow logs <jobId> -t", run_in_background: true })
+   ```
+   Then use `BashOutput` (or whatever your background-output tool is) to read new lines as they arrive.
+3. If the user wants a **one-shot snapshot** (no follow), drop the `-t` flag and call Bash normally:
+   ```
+   Bash({ command: "zibby workflow logs <jobId>" })
+   ```
+4. To stop the live tail: kill the background bash task. The CLI exits cleanly with `Stopped streaming.`

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

@@ -0,0 +1,59 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-test-debug — diagnose a failing Zibby test
+
+You are helping the user figure out why a test failed.
+
+Canonical docs: **https://docs.zibby.app/tests/debugging**
+
+## Diagnostic recipe
+
+Apply in order. Stop at the first thing that explains the symptom.
+
+### 1. Was the failure in the AGENT phase or the PLAYWRIGHT phase?
+
+Two places things go wrong:
+- **Agent phase** (`generate_script` / `execute_live`) — the AI couldn't figure out what to do or what selector to use. Look for `MCP error`, `tool timeout`, or generic LLM gibberish in the output.
+- **Playwright phase** (after script generation) — script ran but an assertion failed or a selector didn't match. Look for `expect(...)` failures, `Timeout` waiting for selector, or "element not visible".
+
+### 2. Open the artifacts
+
+Each run produces:
+- `test-results/<spec-name>/video.webm` — watch what happened
+- `test-results/<spec-name>/trace.zip` — Playwright trace; open with `npx playwright show-trace <path>`
+- `.zibby/output/sessions/<session-id>/` — agent's internal state, prompts, responses
+- `tests/<spec-name>.spec.js` — the generated Playwright code
+
+The video usually tells you in 30 seconds what's wrong.
+
+### 3. Check the spec
+
+Spec ambiguity is the most common cause. If the spec says "click the button" and there are five buttons, the agent picks one — possibly the wrong one. Re-read the spec asking: would a stranger know exactly which element this means?
+
+### 4. Re-run with more verbosity
+
+```
+Bash(zibby test test-specs/<name>.txt --verbose)        # info-level logs
+Bash(zibby test test-specs/<name>.txt --debug)          # all logs, lots
+Bash(zibby test test-specs/<name>.txt --headed)         # see the browser
+```
+
+### 5. Re-execute one node from a prior session
+
+If `execute_live` failed but the script generation was OK, re-execute just that node against the existing session:
+```
+Bash(zibby test --node execute_live --session last)
+```
+
+### 6. Common errors and fixes
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| "ZIBBY_API_KEY required" | not authenticated | `Bash(zibby login)` |
+| "MCP server not responding" | playwright-mcp config drifted | `Bash(zibby setup-playwright)` |
+| "Selector not found" | UI changed since last run | re-generate from the spec, or update selector in `.spec.js` |
+| Agent loops forever in `execute_live` | spec is too vague | tighten the spec; add the explicit selector text |
+| "Module not found" | missing dep in repo | `Bash(npm install)` in the repo root |
+
+### 7. When to escalate
+
+If the same spec passed yesterday and fails today, and the codebase didn't change → check if Zibby pushed an agent update (`zibby --version`). Otherwise it's almost always spec ambiguity or a real product regression.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-generate.md

@@ -0,0 +1,39 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-test-generate — generate test specs from a Jira ticket / requirements
+
+You are helping the user auto-generate test specs from a ticket description (Jira) or a free-text requirements doc. Zibby's `generate` command runs the configured AI agent against the codebase + ticket and produces `.txt` specs in `test-specs/`.
+
+Canonical docs: **https://docs.zibby.app/tests/generating**
+
+## Inputs the command accepts
+
+- **Jira ticket key:** `-t ENG-1234` — fetches the ticket from the configured Jira integration
+- **Inline description:** `-d "When a user clicks Buy, charge the card and email a receipt"`
+- **File:** `-i path/to/requirements.md`
+- **Repo path** (defaults to cwd): `--repo /path/to/codebase`
+
+## Steps
+
+1. **Get the source.** Ask the user: ticket key, file, or paste the requirements?
+
+2. **Run generate:**
+   ```
+   Bash(zibby generate -t ENG-1234)
+   Bash(zibby generate -i requirements.md)
+   Bash(zibby generate -d "happy-path checkout flow")
+   ```
+
+3. **Pick the agent and model** if the user has preferences:
+   ```
+   Bash(zibby generate -t ENG-1234 --agent claude --model claude-opus-4)
+   ```
+
+4. **Output destination.** Specs land in `test-specs/` by default; override with `-o <dir>`.
+
+5. **Review before running.** After generation, the user should read the spec(s) and tweak. Then `/zibby-test-run` to execute.
+
+## Tips
+
+- **Better tickets = better specs.** Vague tickets ("fix login") generate vague tests. Tight acceptance criteria ("login redirects to /dashboard on success, shows 'invalid' on failure") generate sharp specs.
+- **Generate iterates.** If the first cut is wrong, re-run with `-d "be more specific about X"` rather than hand-editing.
+- **The agent reads the codebase.** It looks at component files, route definitions, etc., so the specs reference real selectors and URLs. Run from the actual repo root, not a subdir.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-run.md

@@ -0,0 +1,48 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-test-run — execute a Zibby test spec
+
+You are helping the user run an existing test spec through Zibby. A spec is a `.txt` file describing what to test in plain language; Zibby's runner turns it into a Playwright execution and produces a video + JSON results.
+
+Canonical docs: **https://docs.zibby.app/tests/running**
+
+## Steps
+
+1. **Identify the spec.** Most projects keep specs under `test-specs/` (configurable in `.zibby.config.mjs` `paths.specs`). If user named one, use it. Otherwise list what's there and ask:
+   ```
+   ls test-specs/
+   ```
+
+2. **Run it.** From the project root:
+   ```
+   Bash(zibby test test-specs/<name>.txt)
+   ```
+   For a quick inline test without writing a spec file:
+   ```
+   Bash(zibby test "go to example.com and check that the title contains Example")
+   ```
+
+3. **Output to expect.** Zibby streams the run live — agent thinking, browser actions, assertion results, final pass/fail. Generated `.spec.js` lands in `tests/<name>.spec.js` (configurable via `paths.generated`). Video + traces under `test-results/`.
+
+4. **If running headless / CI:**
+   ```
+   Bash(zibby test test-specs/<name>.txt --headless)
+   ```
+
+5. **If running a specific node only** (advanced — re-execute one phase of a prior session):
+   ```
+   Bash(zibby test --node execute_live --session last)
+   ```
+
+## Useful flags
+
+- `--agent claude|cursor|codex|gemini` — override the configured agent for this run
+- `--workflow QuickSmokeWorkflow` — use a non-default workflow for the run
+- `--verbose` / `--debug` — escalate log levels
+- `-m, --mem` — enable test memory (Dolt-backed knowledge from prior runs)
+- `--sync` / `--no-sync` — force / skip cloud upload regardless of config
+
+## Common failure modes
+
+- **"No spec found"** — path is relative to project root, not cwd. Check `paths.specs` in `.zibby.config.mjs`.
+- **"Browser crashed"** — usually the playwright browser cache is stale. Re-run with `--headed` once to refresh, then `--headless`.
+- **MCP errors during `execute_live`** — the agent's MCP tool config may need refreshing. See `/zibby-test-debug`.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-write.md

@@ -0,0 +1,46 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-test-write — author a new Zibby test spec
+
+You are helping the user write a new test spec. Specs are plain-language `.txt` files in `test-specs/` (configurable via `.zibby.config.mjs` `paths.specs`). Zibby's runner converts them to Playwright at execution time.
+
+Canonical docs: **https://docs.zibby.app/tests/specs**
+
+## Spec format (informal but conventional)
+
+A spec is mostly imperative English with one action per line. Common shape:
+
+```
+Title: <one-line summary>
+
+Setup:
+- Open <url>
+- Log in as <user>
+
+Steps:
+- Click <element>
+- Type <value> into <field>
+- Wait for <state>
+
+Verify:
+- <assertion>
+- <assertion>
+```
+
+Zibby tolerates loose phrasing — what matters is being unambiguous about WHICH element and WHAT value. Use stable selectors (visible text, ARIA labels) over CSS class names.
+
+## Steps for this command
+
+1. **Ask the user what they want to test.** What's the user flow? What are they verifying? What URL?
+2. **Find a similar existing spec to mirror.** `ls test-specs/` and read 1-2 to match the project's conventions.
+3. **Write the spec to `test-specs/<kebab-case-name>.txt`** using `Write` tool.
+4. **Offer to run it immediately** with `/zibby-test-run` (or just `Bash(zibby test test-specs/<name>.txt)`).
+
+## Naming conventions
+
+- kebab-case: `login-with-sso.txt`, `cart-checkout-happy-path.txt`
+- Group by feature: `users-create.txt`, `users-edit.txt`, `users-delete.txt`
+- Avoid ambiguous names like `test1.txt`
+
+## When the spec is complex
+
+For multi-page flows or many assertions, split into multiple specs and run them as a collection. Don't pile everything into one spec — Playwright errors are easier to localize when each spec is one user goal.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-trigger.md

@@ -0,0 +1,52 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-trigger — run a deployed Zibby workflow
+
+You are helping the user trigger a deployed workflow execution.
+
+A trigger creates a new ECS Fargate task that loads the workflow's bundle, runs the graph, and writes status + logs as it goes.
+
+Canonical docs: **https://docs.zibby.app/workflows/triggering**
+
+## Steps
+
+1. **Get the workflow UUID.** The user should provide it; if not, run `zibby workflow list` to discover it. UUIDs are stable across deploys (the same workflow always has the same UUID; only the bundle version changes).
+
+2. **Construct the input.** Workflows take a JSON input that nodes can read via `ctx.input`. Ask the user what input the workflow expects (or read `workflow.json`'s `inputSchema` if present).
+
+3. **Run the trigger:**
+   ```
+   zibby workflow trigger <uuid> --input '{"key":"value"}'
+   ```
+   Or use `-p key=value` for individual params (more shell-friendly than embedded JSON):
+   ```
+   zibby workflow trigger <uuid> -p ticket=ENG-1234 -p priority=high
+   ```
+
+4. **Tail the logs immediately:**
+   ```
+   zibby workflow logs <uuid> -t
+   ```
+   This streams live output. The tail auto-attaches to all currently-running executions of the workflow (docker-compose-style), so back-to-back triggers interleave naturally.
+
+5. **Watch for completion.** Workflow runs typically end with one of:
+   - `✓ Workflow completed` — success, status `completed`
+   - `Error: Node 'X' failed` — a node threw; status `failed`
+   - silent timeout — task killed by ECS; status stays `running` then becomes a zombie. Trigger again.
+
+## Idempotency
+
+Use `--idempotency-key <key>` to prevent duplicate runs from a retry-prone caller:
+```
+zibby workflow trigger <uuid> --input '{}' --idempotency-key job-2026-05-04-001
+```
+Same key + same input within ~24h = same execution returned (no new run).
+
+## Multiple inputs / batch
+
+There's no built-in batch trigger — script it from your shell:
+```
+for ticket in ENG-1 ENG-2 ENG-3; do
+  zibby workflow trigger <uuid> -p ticket=$ticket
+done
+zibby workflow logs <uuid> -t   # tail will show all 3 interleaved
+```

package/dist/templates/zibby-workflow-claude/claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(zibby:*)",
+      "Bash(./.zibby/bin/zibby:*)",
+      "Bash(npm install:*)",
+      "Bash(node:*)"
+    ]
+  }
+}

package/dist/templates/zibby-workflow-claude/cursor/rules/zibby-workflows.mdc

@@ -0,0 +1,56 @@
+<!-- zibby-template-version: 2 -->
+---
+description: Help the user build, test, and deploy Zibby agent workflows
+globs:
+  - "**/.zibby/workflows/**"
+  - ".zibby.config.mjs"
+  - "**/workflow.json"
+  - "**/graph.mjs"
+alwaysApply: false
+---
+
+# Zibby agent workflows
+
+This project contains one or more **Zibby workflows** — graphs of AI-agent-driven steps that run inside an ECS Fargate sandbox in Zibby Cloud.
+
+## Anatomy
+
+```
+<workflowsBasePath>/<workflow-name>/
+├── workflow.json    # name, entryClass, triggers, schemas
+├── graph.mjs        # exports the graph (nodes + edges)
+├── nodes/           # one .mjs file per node
+└── package.json     # deps bundled at deploy time
+```
+
+Each node exports `{ id, description, async run(ctx) }`. `ctx` provides `input`, `agent({prompt, schema})`, `shell(cmd)`, `log(...)`.
+
+## Common dev loop
+
+```
+zibby workflow run <name>       # one-shot local run (mirrors trigger flags)
+zibby workflow deploy <name>    # build + push to cloud
+zibby workflow trigger <uuid>   # invoke the cloud workflow
+zibby workflow logs <uuid> -t   # tail live logs (docker-compose style for concurrent runs)
+```
+
+## Adding a new node
+
+1. Create `<workflow>/nodes/<name>.mjs` (mirror existing `example.mjs` pattern)
+2. Register in `<workflow>/nodes/index.mjs`
+3. Wire into `<workflow>/graph.mjs` (add to `nodes` array and connect via edges)
+4. `zibby workflow run <name>` to test locally; `zibby workflow deploy` to push
+
+## Reference
+
+Canonical, evolving docs: **https://docs.zibby.app/workflows**
+
+Topics:
+- Node SDK (ctx.agent / ctx.shell / ctx.log): 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
+- Egress proxy / static IPs: https://docs.zibby.app/workflows/egress
+- Security & secrets: https://docs.zibby.app/workflows/security
+
+Prefer the docs URL for anything you're unsure about — they're updated more frequently than these rules.

package/dist/templates/zibby-workflow-claude/manifest.json

@@ -0,0 +1,43 @@
+{
+  "templateVersion": 3,
+  "description": "Canonical agent helpers for Zibby workflows. Each shipped file carries '<!-- zibby-template-version: N -->' for idempotent upgrades. Bumped on breaking content changes.",
+  "agents": {
+    "claude": {
+      "files": [
+        ".claude/commands/zibby-add-node.md",
+        ".claude/commands/zibby-deploy.md",
+        ".claude/commands/zibby-trigger.md",
+        ".claude/commands/zibby-tail.md",
+        ".claude/commands/zibby-debug.md",
+        ".claude/commands/zibby-delete.md",
+        ".claude/commands/zibby-list.md",
+        ".claude/commands/zibby-static-ip.md",
+        ".claude/commands/zibby-test-run.md",
+        ".claude/commands/zibby-test-write.md",
+        ".claude/commands/zibby-test-generate.md",
+        ".claude/commands/zibby-test-debug.md",
+        ".claude/agents/zibby-workflow-builder.md",
+        ".claude/agents/zibby-test-author.md"
+      ],
+      "writeOnceFiles": [
+        ".claude/settings.json"
+      ],
+      "rootBlock": {
+        "target": "CLAUDE.md",
+        "source": "agents-md-block.md"
+      }
+    },
+    "cursor": {
+      "files": [
+        ".cursor/rules/zibby-workflows.mdc"
+      ]
+    },
+    "codex": {
+      "files": [],
+      "rootBlock": {
+        "target": "AGENTS.md",
+        "source": "agents-md-block.md"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/cli",
-  "version": "0.1.90",
+  "version": "0.1.95",
   "description": "Zibby CLI - Test automation generator and runner",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "build": "node ../scripts/build.mjs --extra-dirs bin",
-    "test": "vitest run test/auth*.test.js test/two-layer-auth.test.js test/trigger-params.test.js test/trigger-helpers.test.js test/deploy-helpers.test.js test/cli-namespace-consistency.test.js test/cli-workflow-subcommands.test.js test/run-bundle-core-import.test.js test/start-respects-config.test.js test/sse-backoff.test.js test/sse-reconnect-loop.test.js test/run-helpers.test.js test/sse-parser.test.js",
+    "test": "vitest run test/auth*.test.js test/two-layer-auth.test.js test/trigger-params.test.js test/trigger-helpers.test.js test/deploy-helpers.test.js test/deploy-bundles-user-config.test.js test/run-loads-user-config.test.js test/env-helpers.test.js test/env-cli.test.js test/cli-namespace-consistency.test.js test/cli-workflow-subcommands.test.js test/run-bundle-core-import.test.js test/start-respects-config.test.js test/sse-backoff.test.js test/sse-reconnect-loop.test.js test/run-helpers.test.js test/sse-parser.test.js",
     "test:unit": "vitest run src/",
     "test:auth": "vitest run test/auth*.test.js test/two-layer-auth.test.js",
     "lint": "eslint .",
@@ -33,8 +33,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-sqs": "^3.1038.0",
-    "@zibby/agent-workflow": "^0.1.2",
-    "@zibby/core": "^0.1.48",
+    "@zibby/agent-workflow": "^0.2.0",
+    "@zibby/core": "^0.2.0",
     "@zibby/memory": "^0.1.5",
     "@zibby/skills": "^0.1.11",
     "adm-zip": "^0.5.17",