@zibby/cli 0.4.18 → 0.4.21

package/templates/.claude/CLAUDE.md

@@ -13,20 +13,31 @@ the intent.
 ## 0. The 30-second tour
 
 ```
-.zibby/workflows/<name>/
-├── workflow.json     # name, description, version, default agent
-├── graph.mjs         # graph topology (nodes + edges)
-├── nodes/            # one file per node — prompt + outputSchema + skills
+workflows/<name>/                  # default. Override via paths.workflows
+                                   # in .zibby.config.mjs (legacy projects
+                                   # may have .zibby/workflows/).
+├── workflow.json     # name, description, entryClass, triggers, defaultAgent
+├── graph.mjs         # WorkflowAgent class — buildGraph() + onComplete()
+├── state.js          # Zod schema for caller-provided inputs (-p key=value)
+├── nodes/            # one file per node — prompt|execute + outputSchema
+│   ├── index.mjs     # OPTIONAL barrel — re-exports keep graph.mjs imports
+│   │                 # tidy ("import { fooNode, barNode } from './nodes/'")
+│   │                 # but a graph that imports each file directly is
+│   │                 # equally valid. Pick whichever you prefer.
 │   ├── plan.mjs
 │   ├── implement.mjs
 │   └── verify.mjs
-└── package.json      # @zibby/agent-workflow + zod, nothing else needed
+└── package.json      # @zibby/core + zod (core re-exports WorkflowGraph,
+                      # WorkflowAgent, z, skills, agent strategies).
 ```
 
 Lifecycle:
 
 ```bash
-zibby workflow new <name>            # scaffold (creates .zibby/workflows/<name>/)
+zibby workflow new <name>            # scaffold (creates workflows/<name>/ by default;
+                                     # also writes a starter nodes/example.mjs that
+                                     # you can replace/delete once your real nodes
+                                     # are in place)
 zibby workflow run <name> -p key=val # run locally — one-shot, no server
 zibby workflow start <name>          # run locally with hot-reload (server)
 zibby workflow validate <name>       # static check (graph topology, schemas, skills)
@@ -49,44 +60,76 @@ start; cloud is ~60s. Iterating in cloud is 12× slower.
 {
   "name": "code-review",
   "description": "Review a git diff and return structured findings",
-  "version": "0.1.0",
-  "defaultAgent": "claude",
-  "stateSchema": {
-    "diff": "string",
-    "findings": "array"
-  }
+  "entryClass": "CodeReviewWorkflow",
+  "triggers": { "api": true },
+  "defaultAgent": "claude"
 }
 ```
 
-`defaultAgent` is one of: `claude`, `cursor`, `codex`, `gemini`. Any node
-can override with `agent: 'cursor'` in its config.
+- `name` — kebab-case slug, ≤24 chars
+- `entryClass` — the class exported from `graph.mjs` (CLI uses this to
+  pick the right export when there are multiple)
+- `triggers.api` — `true` exposes a webhook URL after `zibby workflow
+  deploy`; `false` hides it (cron-only or internal)
+- `defaultAgent` — one of `claude`, `cursor`, `codex`, `gemini`. Any
+  node overrides with its own `agent: 'cursor'` field.
 
-### `graph.mjs`
+### `graph.mjs` (class form — what production runtime expects)
 
 ```js
-import { WorkflowGraph } from '@zibby/agent-workflow';
-import { z } from 'zod';
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
 import { planNode } from './nodes/plan.mjs';
 import { implementNode } from './nodes/implement.mjs';
 import { verifyNode } from './nodes/verify.mjs';
+import { codeReviewStateSchema } from './state.js';
 
-export default function buildGraph() {
-  const graph = new WorkflowGraph();
+export class CodeReviewWorkflow extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.setStateSchema(codeReviewStateSchema);
 
-  graph.addNode('plan',      planNode);
-  graph.addNode('implement', implementNode);
-  graph.addNode('verify',    verifyNode);
+    graph.addNode('plan',      planNode);
+    graph.addNode('implement', implementNode);
+    graph.addNode('verify',    verifyNode);
 
-  graph.addEdge('plan', 'implement');
-  graph.addEdge('implement', 'verify');
-  graph.addEdge('verify', 'END');         // 'END' is the terminal sentinel
+    graph.addEdge('plan',      'implement');
+    graph.addEdge('implement', 'verify');
+    graph.addEdge('verify',    'END');      // 'END' is the terminal sentinel
 
-  graph.setEntryPoint('plan');
+    graph.setEntryPoint('plan');
+    return graph;
+  }
 
-  return graph;
+  async onComplete(result) {
+    // Optional — runs after the graph finishes. Useful for posting a
+    // summary somewhere or transforming `result` before the runner
+    // logs it.
+    console.log(`[code-review] done — success=${result.success !== false}`);
+  }
 }
 ```
 
+The class name MUST match `entryClass` in workflow.json. The CLI
+instantiates it (`new CodeReviewWorkflow()`), calls `.buildGraph()`,
+runs the graph, then invokes `.onComplete(result)`.
+
+### `state.js`
+
+```js
+import { z } from 'zod';
+
+export const codeReviewStateSchema = z.object({
+  diff: z.string().describe('Staged git diff to review'),
+  strict: z.boolean().optional().describe('Treat warnings as errors'),
+});
+```
+
+Declares which user-input fields callers can pass via `-p key=value`
+or `--input '{"key":"value"}'`. The runner validates inputs against
+this schema at run time — invalid inputs fail fast with a Zod error.
+Read fields in nodes via `state.diff`, `state.strict`, etc. Optional
+in v1 — graphs without `state.js` work but lose input validation.
+
 ### A node — `nodes/plan.mjs`
 
 ```js
@@ -159,6 +202,13 @@ the first node sees `state.userRequest = "fix login"`.
 are internal to the graph runtime. Just `return` a plain object that
 matches your `outputSchema`. The runtime puts it under `state[nodeName]`.
 
+**Execute nodes can ONLY write under `state[nodeName]`.** There's no
+mechanism to mutate a top-level state key from inside `execute()`. If
+you need a counter that survives across loop iterations (retries,
+attempts, accumulator), put it inside the node's own output schema —
+read the prior value via `state.<nodeName>?.<field>`, return the new
+value as part of `execute()`'s output. See §3 for the loop pattern.
+
 ---
 
 ## 3. Conditional routing
@@ -173,7 +223,47 @@ graph.addConditionalEdges('verify', (state) => {
 
 The router function receives the full state, returns the name of the
 next node (or `'END'`). All possible target nodes must also be declared
-elsewhere via `addNode`.
+elsewhere via `addNode` — a router returning an unregistered name will
+fail at runtime (validate also catches it as `graph-edge-to-unknown`).
+
+### Loops with a retry counter
+
+Graphs aren't DAGs — you can route back to an earlier node. The
+counter pattern lives **inside the looping node's own output**, since
+`execute()` can only write to `state[nodeName]`. Example: a
+`generate → check` loop that retries up to 2 times on failure.
+
+```js
+// nodes/check.mjs
+export const checkNode = {
+  name: 'check',
+  outputSchema: z.object({
+    passed: z.boolean(),
+    attempts: z.number(),
+  }),
+  execute: async (state) => {
+    const priorAttempts = state.check?.attempts ?? 0;
+    const passed = /* … your check logic … */ false;
+    return { passed, attempts: priorAttempts + 1 };
+  },
+};
+
+// graph.mjs (inside buildGraph)
+graph.addNode('generate', generateNode);
+graph.addNode('check',    checkNode);
+graph.addEdge('generate', 'check');
+graph.addConditionalEdges('check', (state) => {
+  if (state.check.passed)            return 'END';
+  if (state.check.attempts < 2)      return 'generate';   // loop back
+  return 'END';                                            // give up
+});
+graph.setEntryPoint('generate');
+```
+
+Each iteration through `check`, `priorAttempts` reads the value the
+previous iteration wrote, and the new value is what the next router
+call sees as `state.check.attempts`. `'END'` is the only sentinel —
+any other return value must be an `addNode`'d name.
 
 ---
 
@@ -202,7 +292,7 @@ don't list each tool.
 
 ```js
 // .zibby/workflows/<name>/skills/slack.mjs
-import { registerSkill } from '@zibby/agent-workflow';
+import { registerSkill } from '@zibby/core';
 
 registerSkill({
   id: 'slack',                            // referenced by `skills: ['slack']`
@@ -219,7 +309,7 @@ Then import it from your `graph.mjs` BEFORE building the graph:
 
 ```js
 import './skills/slack.mjs';              // side-effect: registers the skill
-import { WorkflowGraph } from '@zibby/agent-workflow';
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
 // ...
 ```
 
@@ -361,6 +451,7 @@ cleaned up too.
 
 | Symptom                                          | Fix                                            |
 |--------------------------------------------------|------------------------------------------------|
+| `No WorkflowAgent class found in graph.mjs`      | Class name in `graph.mjs` must match `entryClass` in `workflow.json`. Or export a class that `extends WorkflowAgent` from `@zibby/core`. |
 | `Node 'X' must define outputSchema`              | Add `outputSchema: z.object({...})` to the node config |
 | `Skill 'foo' not registered`                     | Import the skill file in graph.mjs BEFORE `new WorkflowGraph()` |
 | `state.previousNode is undefined` in a prompt    | Wrong order — add `graph.addEdge('previousNode', 'thisNode')` |
@@ -369,6 +460,9 @@ cleaned up too.
 | Zod error: "Expected string, received undefined" | The previous node's outputSchema doesn't match its return — fix the producer, not the consumer |
 | `workflow trigger` works but `run` doesn't       | Local run reads env from `.env` / shell; cloud reads from `zibby workflow env`. Set both. |
 | Hangs forever on a node                          | Add `retries: 0` to fail fast while debugging; check the prompt isn't asking the agent to wait |
+| `Workflow "<name>" not found.`                   | Check `paths.workflows` in `.zibby.config.mjs` matches where you scaffolded. Default is `workflows/` at repo root. |
+| Router returns a string that's not a registered node name | All possible return values must be either `'END'` or a name passed to `graph.addNode(...)` elsewhere. `validate` flags this as `graph-edge-to-unknown`. |
+| Need a counter / accumulator across loop iterations | Put it in the looping node's own outputSchema. Read prior value via `state.<nodeName>?.<field>` inside `execute()`, return new value. See §3 retry-loop example. |
 
 ---
 
@@ -399,27 +493,49 @@ Read `.claude/commands/` for slash commands the user can invoke:
 ## 9. Quick reference
 
 ```js
-import { WorkflowGraph, registerSkill, registerStrategy, AgentStrategy } from '@zibby/agent-workflow';
-import { z } from 'zod';
-
-// Graph
-const graph = new WorkflowGraph();
-graph.addNode(name, { prompt, outputSchema, execute, skills, agent, retries });
-graph.addEdge(from, to);
-graph.addConditionalEdges(from, (state) => 'nextNodeName');
-graph.setEntryPoint(name);
-
-// Skill
-registerSkill({ id, serverName, command, args, allowedTools, envKeys });
-
-// Strategy (rare — only when wrapping a non-built-in LLM)
-class MyAgent extends AgentStrategy { /* implement invoke() */ }
-registerStrategy(new MyAgent());
+// Imports — @zibby/core re-exports everything you need.
+import {
+  WorkflowAgent,        // base class your workflow extends
+  WorkflowGraph,        // construct + wire nodes inside buildGraph()
+  registerSkill,        // for custom MCP tool bundles
+  registerStrategy, AgentStrategy,  // for custom LLM strategies (rare)
+  z,                    // re-exported Zod for schemas
+} from '@zibby/core';
+
+// Workflow shell (production form — what run/start/deploy expect):
+export class MyWorkflow extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+    graph.setStateSchema(myStateSchema);    // from ./state.js (optional)
+    graph.addNode(name, { prompt, outputSchema, execute, skills, agent, retries });
+    graph.addEdge(from, to);
+    graph.addConditionalEdges(from, (state) =>
+      state.cond ? 'nextNodeName' : 'END'              // 'END' = terminal sentinel
+    );
+    graph.setEntryPoint(name);
+    return graph;
+  }
+  async onComplete(result) { /* optional post-processing */ }
+}
 
 // State (inside execute / prompt fns)
 //   READ:  state.someKey   or   state.previousNode.field
 //   WRITE: return { ... } from execute() — runtime puts it at state[nodeName]
 ```
 
-That's the whole API. Anything else is either a convenience or a
-footgun — when in doubt, prefer the above.
+**Two API surfaces** — when in doubt, use the class form:
+
+- **Class form** (above) — what `zibby workflow new` scaffolds and what
+  `zibby workflow run/start/deploy` execute. Required for cloud
+  deployment. Use this for anything you might trigger remotely.
+
+- **Function form** — `export default function buildGraph() { return new
+  WorkflowGraph()... }`. Works for local `validate` + the standalone
+  `@zibby/agent-workflow` library (the underlying graph runtime), but
+  NOT for `run`/`deploy` (they look for the class). Useful for one-off
+  local scripts that import the graph runtime directly. **For Zibby
+  workflows, always use the class form** — import from `@zibby/core`,
+  which re-exports everything you need.
+
+`zibby workflow validate` accepts both shapes. Other commands need the
+class.

package/templates/.claude/commands/add-skill.md

@@ -18,31 +18,43 @@ The user wants to add a custom skill (MCP tool bundle) to a workflow.
    - If unsure, ask: "Which MCP server should this skill wrap, or
      should it be a JS-only middleware?"
 
-2. **Find the workflow** at `.zibby/workflows/<name>/`. Create a
-   `skills/` subfolder if it doesn't exist.
+2. **Find the workflow** under your project's workflows path —
+   `workflows/<name>/` by default, or whatever `paths.workflows` is
+   set to in `.zibby.config.mjs`. (Legacy projects may still use
+   `.zibby/workflows/`.) Create a `skills/` subfolder if it doesn't
+   exist.
 
 3. **Write `skills/<id>.mjs`:**
 
    ```js
-   import { registerSkill } from '@zibby/agent-workflow';
+   import { registerSkill } from '@zibby/core';
 
    registerSkill({
      id: 'slack',                       // referenced by node `skills: ['slack']`
      serverName: 'slack-mcp',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-slack'],
-     allowedTools: ['mcp__slack__*'],   // pattern of tools the agent gets access to
-     envKeys: ['SLACK_BOT_TOKEN'],
-     description: 'Read channels, post messages, search history',
+     // Convention: 'mcp__<short-server-name>__*' matches every tool the
+     // MCP server exposes. Use the short name from the npm package
+     // (e.g. server-filesystem → 'mcp__filesystem__*').
+     allowedTools: ['mcp__slack__*'],
+     envKeys: ['SLACK_BOT_TOKEN'],      // optional — env required to run
+     description: 'Read channels, post messages, search history',   // optional
    });
    ```
 
+   **MCP-server-specific args:** some servers need extra positional
+   arguments. `@modelcontextprotocol/server-filesystem` requires the
+   allowed paths as args, e.g.
+   `args: ['-y', '@modelcontextprotocol/server-filesystem', process.cwd()]`.
+   Check the server's npm page for required args.
+
 4. **Import the skill file from `graph.mjs`** at the TOP, before
    `new WorkflowGraph()`:
 
    ```js
    import './skills/slack.mjs';        // side-effect: registers the skill
-   import { WorkflowGraph } from '@zibby/agent-workflow';
+   import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
    // ...
    ```