@zibby/skills 0.1.8 → 0.1.9

package/docs/workflow-artifact-layout-evaluation.md

@@ -0,0 +1,119 @@
+# Workflow Artifact Layout Evaluation
+
+## Context
+
+Current workflow authoring is centered on hidden project files under `.zibby/`:
+
+- `.zibby/graph.mjs`
+- `.zibby/nodes/*`
+- `.zibby/chat.mjs`
+- `.zibby/result-handler.mjs`
+- runtime output in `.zibby/output/sessions/*`
+
+The product direction is to support live workflow creation via `zibby chat` and local/remote arbitrary workflow execution, while keeping user-authored workflow code commit-friendly.
+
+## Options
+
+### Option A: Keep everything in hidden `.zibby/`
+
+Pros:
+- No migration needed.
+- Fully compatible with current Studio/CLI assumptions.
+
+Cons:
+- User-authored workflow source remains hidden and less discoverable.
+- Weaker commit ergonomics for user-owned workflow code.
+
+### Option B: Move everything to visible `zibby/`
+
+Pros:
+- Clear, commit-friendly source-of-truth for workflow code.
+- Better UX for editing workflow artifacts directly.
+
+Cons:
+- High migration cost.
+- Breaks many path assumptions in Studio bridge, Electron, docs, and integrations.
+- Requires dual-path compatibility window to avoid immediate breakage.
+
+### Option C: Hybrid (recommended)
+
+Store user-authored workflow source in visible `zibby/`, keep runtime/output in hidden `.zibby/output`.
+
+Pros:
+- Commit-friendly source artifacts.
+- Preserves hidden runtime/cache/output behavior.
+- Smaller migration blast radius than full move.
+
+Cons:
+- Requires resolver precedence logic and migration tooling.
+- Transitional complexity (legacy `.zibby` source + new `zibby` source).
+
+### Option D: Hybrid + configurable path in `.zibby.config.mjs`
+
+Same as Option C, but adds explicit config override for source workflow path.
+
+Pros:
+- Flexible for monorepos and custom project conventions.
+- Future-proofs enterprise setups.
+
+Cons:
+- Slightly larger surface area and testing burden.
+
+## Impact Map (Current Coupling)
+
+Key areas that currently assume hidden-source and/or hidden-output conventions:
+
+- `studio/electron/main.js`
+  - project-root detection uses `.zibby/graph.mjs`
+  - default sessions root uses `.zibby/output/sessions`
+- `studio/vite.config.js`
+  - bridge fallbacks for session/output discovery
+- `studio/src/adapters/platform.js`
+  - APIs and comments assume `.zibby/output/sessions`
+- `docsite/docs/*`
+  - user docs describe hidden `.zibby` workflow/source model
+
+Secondary impacts:
+
+- integrations under `integrations/*` referencing current command/path patterns
+- helper comments and UI command snippets across Studio/frontend
+
+## Recommended Migration Strategy
+
+### Phase 1 (compatibility, no breakage)
+
+- Keep `.zibby/` source loading as primary behavior.
+- Add support for visible `zibby/` source layout in resolvers.
+- Resolver precedence:
+  1. explicit config path (if set)
+  2. `zibby/` source
+  3. legacy `.zibby/` source
+- Keep runtime output in `.zibby/output`.
+
+### Phase 2 (opt-in default shift)
+
+- New projects scaffold workflow source under `zibby/`.
+- Existing projects continue to work with `.zibby/`.
+- Add migration helper command to copy/move source artifacts safely.
+
+### Phase 3 (deprecation)
+
+- Emit warnings for legacy hidden-source layouts.
+- After a compatibility window, finalize the preferred source layout.
+- Continue hidden runtime/output unless there is strong product need to change it.
+
+## Suggested Source/Runtime Split
+
+- User-authored source (commit-friendly):
+  - `zibby/graph.mjs`
+  - `zibby/nodes/*`
+  - `zibby/chat.mjs`
+  - `zibby/result-handler.mjs`
+- Runtime/cache/output (hidden):
+  - `.zibby/output/*`
+  - `.zibby/scratch/*`
+  - `.zibby/memory/*`
+
+## Why this recommendation
+
+Hybrid with configuration gives the best balance: user-visible source for authoring and version control, while preserving stable hidden runtime/output semantics already used by Studio, CLI, and integrations.

package/docs/workflow.md

@@ -0,0 +1,558 @@
+---
+sidebar_position: 4
+title: Workflow Engine
+---
+
+# Workflow Engine
+
+Zibby's workflow engine is a **graph-based orchestration system for AI agents**, inspired by [LangGraph](https://github.com/langchain-ai/langgraph) but designed to be **agent-agnostic**. The same workflow definition runs identically on Cursor, Claude, or Codex — you switch agents with a single flag, not by rewriting your pipeline.
+
+## Core Concepts
+
+### Graph = Nodes + Edges + State
+
+A workflow is a directed graph where:
+
+- **Nodes** — individual steps (AI calls, data transformations, tool usage)
+- **Edges** — connections between nodes (linear or conditional)
+- **State** — a shared key-value store that flows through the graph; every node reads from and writes to it
+
+```
+┌──────────┐     ┌──────────────┐     ┌─────────────────┐
+│ preflight│────▶│ execute_live  │────▶│ generate_script  │───▶ END
+└──────────┘     └──────────────┘     └─────────────────┘
+                        │
+                        ▼ (conditional)
+                       END
+                 (no actions recorded)
+```
+
+### Agent-Agnostic Design
+
+The workflow framework never calls a specific AI provider directly. Instead, it uses a **Strategy Pattern**:
+
+1. Each agent (Cursor, Claude, Codex) implements the `AgentStrategy` base class
+2. The `invokeAgent()` function selects the right strategy at runtime based on your config
+3. Nodes call `invokeAgent()` — they never know which provider executes the prompt
+
+This means:
+- Workflows are **portable** across agents
+- Skills (MCP tools) are resolved per-agent automatically
+- You can override the model per-node in config without touching workflow code
+
+```javascript
+// .zibby.config.js — switch agent with one line
+export default {
+  agent: {
+    cursor: { model: 'auto' },
+    // claude: { model: 'sonnet-4.6' },
+    // codex: { model: 'gpt-5.2-codex' },
+  }
+};
+```
+
+### Three Supported Agents
+
+| Agent | SDK | MCP Integration | Structured Output |
+|---|---|---|---|
+| **Cursor** | cursor-agent CLI / API | MCP servers via `~/.cursor/mcp.json` | JSON extraction from response |
+| **Claude** | `@anthropic-ai/claude-agent-sdk` | Native MCP tool_use with `allowedTools` | Zod schema → SDK structured output |
+| **Codex** | `@openai/codex-sdk` | `mcp_servers` config in SDK | Zod → JSON Schema via `outputSchema` |
+
+All three implement the same interface:
+
+```javascript
+class AgentStrategy {
+  canHandle(context)              // Is this agent available?
+  invoke(prompt, options)         // Execute prompt with tools + schema
+  getName()                       // 'cursor' | 'claude' | 'codex'
+}
+```
+
+## Building a Workflow
+
+### The Built-in Default: Browser Test Automation
+
+When you run `zibby test test.txt`, the CLI uses the built-in `BrowserTestAutomationAgent` workflow — no init or config needed:
+
+```javascript
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { preflightNode, executeLiveNode, generateScriptNode } from './nodes/index.mjs';
+
+export class BrowserTestAutomationAgent extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+
+    graph.addNode('preflight', preflightNode);
+    graph.addNode('execute_live', executeLiveNode);
+    graph.addNode('generate_script', generateScriptNode);
+
+    graph.setEntryPoint('preflight');
+    graph.addEdge('preflight', 'execute_live');
+
+    graph.addConditionalEdges('execute_live', (state) => {
+      const result = state.execute_live;
+      const hasExecution = (result?.steps?.length > 0) || (result?.actions?.length > 0);
+      return hasExecution ? 'generate_script' : 'END';
+    });
+
+    graph.addEdge('generate_script', 'END');
+    return graph;
+  }
+
+  async onComplete(result) {
+    // Save artifacts, push to memory, etc.
+  }
+}
+```
+
+**What each node does:**
+
+| Node | Type | Skills | Purpose |
+|---|---|---|---|
+| `preflight` | Prompt-only (no tools) | — | Reads test spec, extracts title + assertion checklist via LLM |
+| `execute_live` | Tool-using | Browser, Memory | AI drives a real browser, fills forms, clicks, captures selectors |
+| `generate_script` | Prompt-only | — | Converts recorded actions into a reusable Playwright `.spec.js` |
+
+### Custom Workflows via `zibby init`
+
+Scaffold a customizable workflow into your project:
+
+```bash
+zibby init --agent cursor
+```
+
+This creates:
+
+```
+.zibby.config.js           # Project configuration
+.zibby/
+├── graph.js                # Workflow graph (nodes + edges)
+├── nodes/
+│   ├── preflight.js        # Extract title + assertions
+│   ├── execute-live.js     # AI drives browser
+│   └── generate-script.js  # Generate Playwright script
+└── result-handler.js       # Post-execution artifact saving
+```
+
+You can then modify any node, add new nodes, or change the graph structure.
+
+## WorkflowGraph API
+
+### Creating a Graph
+
+```javascript
+import { WorkflowGraph, Node } from '@zibby/core';
+
+const graph = new WorkflowGraph({
+  stateSchema: MyZodSchema,     // Optional: Zod schema for state validation
+  middleware: [myMiddleware],    // Optional: middleware functions
+});
+```
+
+### Adding Nodes
+
+```javascript
+// Simple node with prompt function + output schema
+graph.addNode('my_node', {
+  name: 'my_node',
+  prompt: (state) => `Analyze: ${state.testSpec}`,
+  outputSchema: z.object({
+    title: z.string(),
+    items: z.array(z.string()),
+  }),
+});
+
+// Node with skills (MCP tools)
+graph.addNode('browser_step', {
+  name: 'browser_step',
+  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
+  prompt: (state) => `Execute: ${state.testSpec}`,
+  outputSchema: ExecutionSchema,
+  timeout: 600000,
+});
+
+// Node with custom execute (no LLM call)
+graph.addNode('transform', {
+  name: 'transform',
+  _isCustomCode: true,
+  execute: async (context) => {
+    const data = context.state.get('raw_data');
+    return { cleaned: data.trim(), wordCount: data.split(' ').length };
+  },
+  outputSchema: TransformSchema,
+});
+```
+
+### Wiring Edges
+
+```javascript
+// Linear flow
+graph.setEntryPoint('step_a');
+graph.addEdge('step_a', 'step_b');
+graph.addEdge('step_b', 'step_c');
+graph.addEdge('step_c', 'END');
+
+// Conditional branching
+graph.addConditionalEdges('step_b', (state) => {
+  return state.step_b.success ? 'step_c' : 'error_handler';
+});
+```
+
+### Running the Graph
+
+```javascript
+const result = await graph.run(agent, {
+  testSpec: 'Go to example.com and verify the title',
+  cwd: process.cwd(),
+  config: { agent: { cursor: { model: 'auto' } } },
+});
+
+console.log(result.success);        // true
+console.log(result.state.preflight); // { title: '...', assertions: [...] }
+console.log(result.executionLog);    // [{ node, success, duration }, ...]
+```
+
+## Node Anatomy
+
+Every node has three key parts:
+
+### 1. Prompt
+
+A function or string template that receives the current state and produces the LLM prompt:
+
+```javascript
+prompt: (state) => `
+  Test spec: ${state.testSpec}
+  Previous results: ${JSON.stringify(state.preflight)}
+  
+  Execute the test and return structured results.
+`
+```
+
+Nodes can also use Handlebars templates when configured with a `prompt` option:
+
+```javascript
+graph.addNode('my_node', nodeImpl, {
+  prompt: `Analyze {{testSpec}} and produce {{outputFormat}} results`
+});
+```
+
+### 2. Output Schema (Zod)
+
+Every node declares a Zod schema for its output. The framework validates the AI response against it:
+
+```javascript
+import { z } from '@zibby/core';
+
+const MyOutputSchema = z.object({
+  title: z.string().describe('Concise test title'),
+  assertions: z.array(z.object({
+    description: z.string(),
+    expected: z.string(),
+  })),
+});
+
+export const myNode = {
+  name: 'my_node',
+  outputSchema: MyOutputSchema,
+  prompt: (state) => '...',
+};
+```
+
+The schema serves three purposes:
+- **Runtime validation** — the LLM response is parsed and validated against the schema
+- **Structured output** — Claude and Codex agents use the schema for native structured output (no JSON extraction needed)
+- **State contract** — downstream nodes know exactly what shape to expect from upstream output
+
+### 3. Skills
+
+Skills declare what MCP tools a node needs. The framework resolves the right MCP server per-agent:
+
+```javascript
+import { SKILLS } from '@zibby/core';
+
+export const executeLiveNode = {
+  name: 'execute_live',
+  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
+  // ...
+};
+```
+
+Available built-in skills: `BROWSER`, `JIRA`, `GITHUB`, `SLACK`, `MEMORY`.
+
+## State Management
+
+State is a shared key-value store managed by `WorkflowState`. Each node's output is automatically stored under its name:
+
+```javascript
+// After preflight runs:
+state.get('preflight')  // → { title: '...', assertions: [...] }
+
+// After execute_live runs:
+state.get('execute_live')  // → { success: true, steps: [...], actions: [...] }
+```
+
+Built-in state keys:
+
+| Key | Type | Description |
+|---|---|---|
+| `messages` | `Array` | Accumulated messages |
+| `errors` | `Array` | Error records `{ node, error }` |
+| `artifacts` | `Object` | Generated artifacts |
+| `config` | `Object` | Resolved `.zibby.config.js` |
+| `agentType` | `string` | Active agent (`cursor`, `claude`, `codex`) |
+| `sessionPath` | `string` | Path to session output directory |
+| `context` | `Object` | Loaded context files (CONTEXT.md, AGENTS.md, env) |
+| `testSpec` | `string` | The test specification text |
+| `<node_name>` | `Object` | Each node's validated output |
+
+State supports history and rollback:
+
+```javascript
+state.set('key', 'value');
+state.update({ a: 1, b: 2 });
+state.append('errors', { node: 'x', error: 'failed' });
+state.rollback();  // Undo last mutation
+```
+
+## Graph Compiler
+
+Zibby includes a **graph compiler** that takes a serialized JSON graph (from the dashboard's visual editor) and compiles it into an executable `WorkflowGraph`:
+
+```javascript
+import { compileGraph, validateGraphConfig } from '@zibby/core';
+
+// Validate before compiling
+const { valid, errors } = validateGraphConfig(graphJson);
+
+// Compile JSON → executable graph
+const graph = compileGraph(graphJson, {
+  stateSchema: MySchema,
+  middleware: [memoryMiddleware],
+});
+
+await graph.run(agent, initialState);
+```
+
+The compiler handles:
+- **Node resolution** — maps node types to registered implementations
+- **Decision nodes** — collapses visual decision diamonds into `addConditionalEdges`
+- **Custom code** — safely compiles inline JavaScript from the visual editor
+- **Tool resolution** — wires MCP tool permissions per node
+- **Entry point detection** — finds the node with no incoming edges
+
+## Middleware
+
+Middleware wraps every node execution, enabling cross-cutting concerns:
+
+```javascript
+const graph = new WorkflowGraph({
+  middleware: [
+    async (nodeName, next, stateValues, state) => {
+      console.log(`Starting: ${nodeName}`);
+      const result = await next();
+      console.log(`Completed: ${nodeName} in ${result.duration}ms`);
+      return result;
+    }
+  ]
+});
+```
+
+Skills can also provide middleware. For example, the Memory skill injects a middleware that loads test history before each node and persists insights after:
+
+```javascript
+// Automatically injected when a node declares skills: [SKILLS.MEMORY]
+const memoryMiddleware = await memorySkill.middleware();
+```
+
+## Skill Adaptation per Agent
+
+Skills are resolved differently depending on which agent is active:
+
+| Agent | How Skills (MCP servers) Are Wired |
+|---|---|
+| **Cursor** | Written to `~/.cursor/mcp.json` — Cursor IDE manages the MCP lifecycle |
+| **Claude** | Passed as `mcpServers` config to the Claude Agent SDK — native MCP support |
+| **Codex** | Passed as `mcp_servers` config to the Codex SDK — SDK manages MCP processes |
+
+The skill's `resolve()` function returns a platform-neutral server config:
+
+```javascript
+{
+  command: 'node',
+  args: ['/path/to/mcp-browser.js', '--save-video=1280x720', '--viewport-size=1280x720', '--output-dir=./output'],
+  env: { SOME_KEY: '...' }
+}
+```
+
+Each agent strategy translates this into its native MCP format. Node code never changes.
+
+## Context Loading
+
+The workflow engine auto-discovers context files that are prepended to prompts:
+
+```javascript
+// .zibby.config.js
+export default {
+  context: {
+    filenames: ['CONTEXT.md', 'AGENTS.md'],
+    discovery: {
+      env: `env-${process.env.ENV || 'local'}.js`,
+    }
+  }
+};
+```
+
+Context files cascade from the project root down to the spec's directory. This lets you provide domain knowledge (login credentials, app structure, known quirks) that the AI uses during execution.
+
+## Per-Node Model Override
+
+Override the AI model for specific nodes without changing the workflow:
+
+```javascript
+// .zibby.config.js
+export default {
+  agent: {
+    cursor: { model: 'auto' },
+  },
+  models: {
+    default: 'auto',
+    execute_live: 'claude-opus-4',    // Use a more capable model for browser execution
+    preflight: 'claude-sonnet-4.6',   // Faster model for analysis
+  }
+};
+```
+
+Model resolution priority: node override → `models.default` → agent block model → `'auto'`.
+
+## Workflow Templates
+
+`@zibby/core` ships two built-in workflow templates:
+
+### Browser Test Automation (`browser-test-automation`)
+
+The default workflow for `zibby test`:
+
+```
+preflight → execute_live → generate_script → END
+```
+
+Three nodes: extract spec, drive browser, generate Playwright script.
+
+### Code Analysis (`code-analysis`)
+
+Used by the cloud analysis pipeline:
+
+```
+setup → analyze_ticket → generate_code → generate_test_cases → finalize → END
+```
+
+Six nodes: clone repo, analyze Jira ticket, generate code changes, write test cases, compile report.
+
+## Creating Custom Skills
+
+### MCP Skill (wraps an external MCP server)
+
+```javascript
+import { skill } from '@zibby/skills';
+
+export const linear = skill('linear', {
+  description: 'Linear project management',
+  serverName: 'linear',
+  allowedTools: ['mcp__linear__*'],
+  envKeys: ['LINEAR_API_KEY'],
+  resolve() {
+    if (!process.env.LINEAR_API_KEY) return null;
+    return {
+      command: 'npx',
+      args: ['-y', '@anthropic/linear-mcp-server'],
+      env: { LINEAR_API_KEY: process.env.LINEAR_API_KEY }
+    };
+  }
+});
+```
+
+### Function Skill (single tool, no MCP server)
+
+```javascript
+import { skill } from '@zibby/skills';
+
+export const add = skill('add', {
+  description: 'Add two numbers',
+  input: { a: 'number', b: 'number' },
+  handler: async ({ a, b }) => ({ result: a + b })
+});
+```
+
+Function skills are automatically bridged to MCP at runtime — the framework spawns a lightweight MCP server that delegates to your handler.
+
+## End-to-End Example: Custom Workflow
+
+```javascript
+import { WorkflowGraph, SKILLS } from '@zibby/core';
+import { z } from '@zibby/core';
+
+// 1. Define output schemas
+const AnalysisSchema = z.object({
+  summary: z.string(),
+  testCases: z.array(z.object({
+    name: z.string(),
+    steps: z.array(z.string()),
+  })),
+});
+
+const ExecutionSchema = z.object({
+  success: z.boolean(),
+  steps: z.array(z.string()),
+  actions: z.array(z.object({
+    type: z.string(),
+    description: z.string(),
+  })),
+  browserClosed: z.boolean(),
+});
+
+// 2. Define nodes
+const analyzeNode = {
+  name: 'analyze',
+  prompt: (state) => `Analyze this requirement and produce test cases:\n${state.testSpec}`,
+  outputSchema: AnalysisSchema,
+};
+
+const executeNode = {
+  name: 'execute',
+  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
+  prompt: (state) => `Execute test "${state.analyze.testCases[0].name}":\n${state.analyze.testCases[0].steps.join('\n')}`,
+  outputSchema: ExecutionSchema,
+  timeout: 600000,
+};
+
+// 3. Build graph
+const graph = new WorkflowGraph();
+graph.addNode('analyze', analyzeNode);
+graph.addNode('execute', executeNode);
+graph.setEntryPoint('analyze');
+graph.addEdge('analyze', 'execute');
+graph.addEdge('execute', 'END');
+
+// 4. Run
+const result = await graph.run(agent, {
+  testSpec: 'Verify the user can log in and see the dashboard',
+  cwd: process.cwd(),
+});
+```
+
+## Workflow CLI Commands
+
+```bash
+# Run a specific workflow (if you have multiple defined)
+zibby test test.txt --workflow QuickSmokeWorkflow
+
+# Run a single node (for debugging)
+zibby test test.txt --node execute_live --session last
+
+# Upload/download workflow graphs to/from Zibby Cloud
+zibby workflow list
+zibby workflow download --type run_test
+zibby workflow upload --type analysis --file .zibby/workflow-analysis.json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Built-in skill definitions for Zibby test automation framework",
   "type": "module",
   "main": "dist/index.js",
@@ -15,6 +15,7 @@
   },
   "scripts": {
     "build": "node ../scripts/build.mjs",
+    "prepack": "node scripts/copy-docs.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint --fix ."
   },
@@ -37,12 +38,16 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "README.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "@zibby/workflow": "^0.1.0"
+  },
   "peerDependencies": {
     "@zibby/core": ">=0.1.0"
   },