@zibby/skills 0.2.22 → 0.2.24

package/docs/workflow.md

@@ -1,558 +0,0 @@
----
-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
-```