@zibby/skills 0.1.34 → 0.1.36

package/dist/trackers/types.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Neutral tracker types — the shared contract every tracker adapter implements.
+ * ============================================================================
+ *
+ * This is the "neutrality payoff": a pipeline reads/writes ANY issue tracker
+ * (Jira, Linear, GitHub Issues, Plane) through ONE interface, so a workflow
+ * template never hard-codes a provider's REST shape.
+ *
+ * Design rule (from the build plan, "中立抽象最小版"):
+ *   A field/method belongs in this contract IFF Jira AND GitHub AND Linear all
+ *   have it AND the semantics line up. Provider-only data (Jira sprint /
+ *   story-point, Linear cycle, GitHub milestone, Plane sequence_id) lives in
+ *   `_raw` — never promoted to a top-level neutral field. Resisting that
+ *   promotion is what keeps this from becoming "a Jira layer with a hat on".
+ *
+ * Field names are deliberately aligned to the OpenAI Symphony §4 domain model
+ * (id / key / title / body / state / assignee / url) so a future Symphony
+ * compatibility layer is additive, not a rewrite.
+ *
+ * STATE MODEL — the one piece of real cleverness:
+ *   `state` is the RAW provider status name ("In Progress", "测试", "Done",
+ *   "started"). It is what you WRITE BACK with — provider workflows reject made-
+ *   up names, so the pipeline must echo the tracker's own vocabulary.
+ *   `stateCategory` is the NORMALIZED bucket the pipeline BRANCHES on. Five
+ *   buckets, no more:
+ *     - 'todo'         not started yet (Jira `new`, Linear backlog/unstarted,
+ *                      GitHub open w/o a progress label, Plane backlog/unstarted)
+ *     - 'in_progress'  actively being worked (Jira `indeterminate`,
+ *                      Linear started, Plane started, GitHub open w/ an
+ *                      in-progress label)
+ *     - 'done'         terminal/closed (Jira `done`, Linear completed/canceled,
+ *                      Plane completed/cancelled, GitHub closed)
+ *     - 'blocked'      explicitly blocked — NOT a native group in any provider;
+ *                      only ever derived from a status NAME match
+ *                      (blocked / on hold / waiting / stuck). Adapters surface
+ *                      it best-effort; absence of 'blocked' is not a bug.
+ *     - 'unknown'      could not classify (missing/unrecognized state)
+ *   Keeping the pair separate is the whole trick: pipeline logic on the bucket,
+ *   write-back on the raw name. Don't collapse them.
+ */
+/**
+ * @typedef {'todo'|'in_progress'|'done'|'blocked'|'unknown'} StateCategory
+ *   Normalized 5-bucket state. The pipeline branches on this; never on `state`.
+ */
+/**
+ * A tracker ticket/issue projected onto the neutral model.
+ *
+ * @typedef {Object} NeutralTicket
+ * @property {string} id
+ *   Stable provider-internal id. Jira: issue id (numeric string). Linear: uuid.
+ *   GitHub: issue number as a string. Plane: work-item uuid. Opaque — pass it
+ *   back to the same adapter; do not parse it.
+ * @property {string} key
+ *   Human-facing reference. Jira: `PROJ-123`. Linear: `ENG-12`. GitHub:
+ *   `owner/repo#123`. Plane: `PROJ-42` (or the uuid if the identifier is
+ *   unknown). This is what shows up in PR titles / comments.
+ * @property {string} title
+ *   Short summary line (Symphony §4 `title`).
+ * @property {string} body
+ *   Full description as plain text / markdown (Symphony §4 `body`). ADF/HTML is
+ *   flattened by the adapter; never raw ADF or raw HTML here.
+ * @property {string|null} state
+ *   RAW provider status NAME, exactly as the tracker spells it ("In Progress",
+ *   "Done", "started", "测试"). Use this for write-back (transition). `null`
+ *   when the provider/issue has no resolvable status.
+ * @property {StateCategory} stateCategory
+ *   Normalized bucket — what the pipeline branches on.
+ * @property {string|null} assignee
+ *   Single human-readable assignee (display name or login). `null` if
+ *   unassigned. Multi-assignee providers (GitHub, Plane) collapse to the first;
+ *   the full list, if any, lives in `_raw`.
+ * @property {string|null} url
+ *   Canonical web URL of the ticket, or `null` if the adapter can't derive one.
+ * @property {Object} _raw
+ *   Escape hatch — the untouched provider payload. Read provider-specific data
+ *   (sprint, story points, cycle, milestone, sequence_id, labels…) from here.
+ *   NEVER promote a `_raw` field to a top-level neutral field.
+ */
+/**
+ * A single comment on a ticket, projected onto the neutral model.
+ *
+ * @typedef {Object} NeutralComment
+ * @property {string} id            Provider comment id (opaque).
+ * @property {string} author        Human-readable author (display name/login).
+ * @property {string} body          Comment text as plain text / markdown
+ *                                  (ADF/HTML flattened).
+ * @property {string|null} createdAt ISO-8601 creation timestamp, if available.
+ * @property {string|null} updatedAt ISO-8601 update timestamp, if available.
+ * @property {Object} [_raw]        Untouched provider comment payload.
+ */
+/**
+ * Options accepted by {@link TrackerAdapter.listCandidates}. Every field is
+ * optional; what each provider honors differs (documented per adapter). The
+ * shared minimum is "give me a bounded, newest-first slab of work to consider".
+ *
+ * @typedef {Object} ListCandidatesOptions
+ * @property {string} [query]
+ *   Provider-native query. Jira: a JQL string. GitHub: free-text issue search
+ *   (or used with `labels`). Linear/Plane: ignored in favor of structured
+ *   filters below. Adapters that can't honor it ignore it.
+ * @property {string|string[]} [labels]  Restrict to issues carrying label(s).
+ * @property {string} [state]            Provider state filter (raw name or, for
+ *                                      GitHub, open|closed|all).
+ * @property {string} [updatedAfter]     ISO-8601 polling cursor; only issues
+ *                                      updated at/after this.
+ * @property {number} [limit]            Max tickets to return (bounded).
+ * @property {string} [cursor]           Opaque pagination cursor (Plane).
+ * @property {Object} [ctx]              Provider scope/context (e.g. GitHub
+ *                                      {owner, repo}; Plane {workspaceSlug,
+ *                                      projectId}). Passed through verbatim.
+ */
+/**
+ * The neutral tracker interface — the 6-method MINIMUM contract.
+ *
+ * Three READ methods + three WRITE methods + identity metadata. Each concrete
+ * adapter (jira / linear / github / plane) implements exactly these. Anything a
+ * single provider can do that the others can't does NOT get a 7th method — it
+ * stays accessible only via that provider's own skill tools / the `_raw` hatch.
+ *
+ * @typedef {Object} TrackerAdapter
+ * @property {string} id
+ *   Provider id: 'jira' | 'linear' | 'github' | 'plane'.
+ *
+ * @property {(opts?: ListCandidatesOptions) => Promise<NeutralTicket[]>} listCandidates
+ *   READ. Return a bounded, newest-first set of tickets to consider for work.
+ *
+ * @property {(key: string, ctx?: Object) => Promise<NeutralTicket|null>} getTicket
+ *   READ. Fetch one ticket by its `key` (or id). `null` if not found.
+ *
+ * @property {(key: string, ctx?: Object) => Promise<NeutralComment[]>} getComments
+ *   READ. Fetch the comment thread (newest first).
+ *
+ * @property {(key: string, body: string, ctx?: Object) => Promise<{ok: boolean, id?: string|null, error?: string}>} addComment
+ *   WRITE. Add a comment. `body` is plain text / markdown; the adapter handles
+ *   provider encoding (Jira ADF, Plane HTML).
+ *
+ * @property {(key: string, targetStateName: string, ctx?: Object) => Promise<{ok: boolean, stateAfter?: string|null, stateCategoryAfter?: StateCategory, error?: string}>} transition
+ *   WRITE. Move the ticket to a target state, addressed by its RAW name
+ *   (fuzzy-matched per provider). Jira performs a workflow transition; Linear /
+ *   Plane PATCH the state directly; GitHub maps to open/close (+ a labels
+ *   convention — see github-adapter). NOT every target name is reachable on
+ *   every provider; the result carries `ok:false` + `error` when it isn't.
+ *
+ * @property {(key: string, prUrl: string, title?: string, ctx?: Object) => Promise<{ok: boolean, via?: string, error?: string}>} linkPullRequest
+ *   WRITE. Associate a PR URL with the ticket. Native where possible (Jira
+ *   remote-link, Linear attachment); a comment everywhere else. `via` reports
+ *   which path was used ('remotelink' | 'attachment' | 'comment').
+ */
+/** @type {StateCategory[]} */
+export const TRACKER_STATE_CATEGORIES: StateCategory[];
+/**
+ * Normalized 5-bucket state. The pipeline branches on this; never on `state`.
+ */
+export type StateCategory = "todo" | "in_progress" | "done" | "blocked" | "unknown";
+/**
+ * A tracker ticket/issue projected onto the neutral model.
+ */
+export type NeutralTicket = {
+    /**
+     *   Stable provider-internal id. Jira: issue id (numeric string). Linear: uuid.
+     *   GitHub: issue number as a string. Plane: work-item uuid. Opaque — pass it
+     *   back to the same adapter; do not parse it.
+     */
+    id: string;
+    /**
+     *   Human-facing reference. Jira: `PROJ-123`. Linear: `ENG-12`. GitHub:
+     *   `owner/repo#123`. Plane: `PROJ-42` (or the uuid if the identifier is
+     *   unknown). This is what shows up in PR titles / comments.
+     */
+    key: string;
+    /**
+     *   Short summary line (Symphony §4 `title`).
+     */
+    title: string;
+    /**
+     *   Full description as plain text / markdown (Symphony §4 `body`). ADF/HTML is
+     *   flattened by the adapter; never raw ADF or raw HTML here.
+     */
+    body: string;
+    /**
+     *   RAW provider status NAME, exactly as the tracker spells it ("In Progress",
+     *   "Done", "started", "测试"). Use this for write-back (transition). `null`
+     *   when the provider/issue has no resolvable status.
+     */
+    state: string | null;
+    /**
+     *   Normalized bucket — what the pipeline branches on.
+     */
+    stateCategory: StateCategory;
+    /**
+     *   Single human-readable assignee (display name or login). `null` if
+     *   unassigned. Multi-assignee providers (GitHub, Plane) collapse to the first;
+     *   the full list, if any, lives in `_raw`.
+     */
+    assignee: string | null;
+    /**
+     *   Canonical web URL of the ticket, or `null` if the adapter can't derive one.
+     */
+    url: string | null;
+    /**
+     *   Escape hatch — the untouched provider payload. Read provider-specific data
+     *   (sprint, story points, cycle, milestone, sequence_id, labels…) from here.
+     *   NEVER promote a `_raw` field to a top-level neutral field.
+     */
+    _raw: any;
+};
+/**
+ * A single comment on a ticket, projected onto the neutral model.
+ */
+export type NeutralComment = {
+    /**
+     * Provider comment id (opaque).
+     */
+    id: string;
+    /**
+     * Human-readable author (display name/login).
+     */
+    author: string;
+    /**
+     * Comment text as plain text / markdown
+     * (ADF/HTML flattened).
+     */
+    body: string;
+    /**
+     * ISO-8601 creation timestamp, if available.
+     */
+    createdAt: string | null;
+    /**
+     * ISO-8601 update timestamp, if available.
+     */
+    updatedAt: string | null;
+    /**
+     * Untouched provider comment payload.
+     */
+    _raw?: any;
+};
+/**
+ * Options accepted by {@link TrackerAdapter.listCandidates}. Every field is
+ * optional; what each provider honors differs (documented per adapter). The
+ * shared minimum is "give me a bounded, newest-first slab of work to consider".
+ */
+export type ListCandidatesOptions = {
+    /**
+     * Provider-native query. Jira: a JQL string. GitHub: free-text issue search
+     * (or used with `labels`). Linear/Plane: ignored in favor of structured
+     * filters below. Adapters that can't honor it ignore it.
+     */
+    query?: string;
+    /**
+     * Restrict to issues carrying label(s).
+     */
+    labels?: string | string[];
+    /**
+     * Provider state filter (raw name or, for
+     *            GitHub, open|closed|all).
+     */
+    state?: string;
+    /**
+     * ISO-8601 polling cursor; only issues
+     *     updated at/after this.
+     */
+    updatedAfter?: string;
+    /**
+     * Max tickets to return (bounded).
+     */
+    limit?: number;
+    /**
+     * Opaque pagination cursor (Plane).
+     */
+    cursor?: string;
+    /**
+     * Provider scope/context (e.g. GitHub
+     *              {owner, repo}; Plane {workspaceSlug,
+     *              projectId}). Passed through verbatim.
+     */
+    ctx?: any;
+};
+/**
+ * The neutral tracker interface — the 6-method MINIMUM contract.
+ *
+ * Three READ methods + three WRITE methods + identity metadata. Each concrete
+ * adapter (jira / linear / github / plane) implements exactly these. Anything a
+ * single provider can do that the others can't does NOT get a 7th method — it
+ * stays accessible only via that provider's own skill tools / the `_raw` hatch.
+ */
+export type TrackerAdapter = {
+    /**
+     *   Provider id: 'jira' | 'linear' | 'github' | 'plane'.
+     */
+    id: string;
+    /**
+     *   READ. Return a bounded, newest-first set of tickets to consider for work.
+     */
+    listCandidates: (opts?: ListCandidatesOptions) => Promise<NeutralTicket[]>;
+    /**
+     *   READ. Fetch one ticket by its `key` (or id). `null` if not found.
+     */
+    getTicket: (key: string, ctx?: any) => Promise<NeutralTicket | null>;
+    /**
+     *   READ. Fetch the comment thread (newest first).
+     */
+    getComments: (key: string, ctx?: any) => Promise<NeutralComment[]>;
+    /**
+     *   WRITE. Add a comment. `body` is plain text / markdown; the adapter handles
+     *   provider encoding (Jira ADF, Plane HTML).
+     */
+    addComment: (key: string, body: string, ctx?: any) => Promise<{
+        ok: boolean;
+        id?: string | null;
+        error?: string;
+    }>;
+    /**
+     *   WRITE. Move the ticket to a target state, addressed by its RAW name
+     *   (fuzzy-matched per provider). Jira performs a workflow transition; Linear /
+     *   Plane PATCH the state directly; GitHub maps to open/close (+ a labels
+     *   convention — see github-adapter). NOT every target name is reachable on
+     *   every provider; the result carries `ok:false` + `error` when it isn't.
+     */
+    transition: (key: string, targetStateName: string, ctx?: any) => Promise<{
+        ok: boolean;
+        stateAfter?: string | null;
+        stateCategoryAfter?: StateCategory;
+        error?: string;
+    }>;
+    /**
+     *   WRITE. Associate a PR URL with the ticket. Native where possible (Jira
+     *   remote-link, Linear attachment); a comment everywhere else. `via` reports
+     *   which path was used ('remotelink' | 'attachment' | 'comment').
+     */
+    linkPullRequest: (key: string, prUrl: string, title?: string, ctx?: any) => Promise<{
+        ok: boolean;
+        via?: string;
+        error?: string;
+    }>;
+};

package/dist/workflow-builder.d.ts

@@ -0,0 +1,245 @@
+export namespace workflowBuilderSkill {
+    export let id: string;
+    export let description: string;
+    export let envKeys: any[];
+    export { PROMPT_FRAGMENT as promptFragment };
+    export let tools: ({
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                nodes: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            name: {
+                                type: string;
+                                description: string;
+                            };
+                            description: {
+                                type: string;
+                                description: string;
+                            };
+                            inputFields: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                            outputFields: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                    description: string;
+                };
+                edges: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            from: {
+                                type: string;
+                                description: string;
+                            };
+                            to: {
+                                type: string;
+                                description: string;
+                            };
+                            condition: {
+                                type: string;
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                    description: string;
+                };
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                spec: {
+                    type: string;
+                    description: string;
+                    properties: {
+                        name: {
+                            type: string;
+                        };
+                        description: {
+                            type: string;
+                        };
+                        nodes: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                        edges: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                };
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                workflowName: {
+                    type: string;
+                    description: string;
+                };
+                nodeName: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                inputFields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                outputFields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                name?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                projectId: {
+                    type: string;
+                    description: string;
+                };
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name?: undefined;
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                topic: {
+                    type: string;
+                    description: string;
+                };
+                name?: undefined;
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+            };
+            required?: undefined;
+        };
+    })[];
+    export function handleToolCall(name: any, args: any, context: any): Promise<string>;
+    export function resolve(): any;
+}
+declare const PROMPT_FRAGMENT: "## Workflow Builder\n\nYou can help users build custom AI workflows using the Zibby workflow framework.\n\n### What makes Zibby workflows different\nEach node invokes a **real AI agent** (Cursor, Claude, Codex, or Gemini) \u2014 not a thin LLM API wrapper.\nThat means every node has full agent capabilities: tool use, MCP servers (browser, GitHub, Jira, Slack),\nmulti-turn reasoning, and structured output validation via Zod schemas.\n\nKey differentiators:\n- **Agent-powered nodes** \u2014 each step runs a full AI agent (cursor-agent, claude, codex, gemini CLI) with tool access and MCP skills, not a simple chat completion call.\n- **Structured output** \u2014 every node declares a Zod schema; the framework validates and parses the agent's response automatically.\n- **Conditional routing** \u2014 edges can branch on agent-produced fields (e.g., `state.triage.priority === 'critical'`), enabling intelligent decision graphs.\n- **MCP skill injection** \u2014 nodes declare `skills: [SKILLS.BROWSER, SKILLS.GITHUB]` and the framework spins up the right MCP servers automatically.\n- **Deploy anywhere** \u2014 `zibby deploy` pushes to Zibby Cloud with an API trigger; or self-host with `zibby start`.\n- **State accumulation** \u2014 each node's validated output is stored under its name in `state` (e.g., `state.classify_ticket`), so downstream nodes can reference upstream results.\n\n### What is a workflow?\nA directed graph of nodes (AI agent steps) connected by edges. Each node has:\n- `name` \u2014 unique identifier (snake_case)\n- `prompt` \u2014 function that receives state and returns the prompt string sent to the agent\n- `outputSchema` \u2014 Zod schema defining the structured output the agent must return\n- `skills` (optional) \u2014 array of MCP skill IDs the node needs (e.g., `SKILLS.BROWSER`, `SKILLS.GITHUB`)\n- `timeout` (optional) \u2014 max execution time in ms (default: 300000)\n- `model` (optional) \u2014 override the model for this node (e.g., `'claude-opus-4'`)\n\n### File structure\n```\n.zibby/workflows/<name>/\n\u251C\u2500\u2500 graph.mjs          \u2014 WorkflowAgent subclass with buildGraph()\n\u251C\u2500\u2500 nodes/\n\u2502   \u251C\u2500\u2500 index.mjs      \u2014 barrel export for all nodes\n\u2502   \u2514\u2500\u2500 <node>.mjs     \u2014 one file per node\n\u2514\u2500\u2500 workflow.json       \u2014 manifest (name, description, triggers)\n```\n\n### Node pattern\n```javascript\nimport { z, SKILLS } from '@zibby/core';\n\nconst OutputSchema = z.object({\n  summary: z.string().describe('Brief summary'),\n  items: z.array(z.string()).describe('List of extracted items'),\n  needsReview: z.boolean().describe('Whether a human should review this'),\n});\n\nexport const myNode = {\n  name: 'my_node',\n  skills: [SKILLS.GITHUB],  // optional \u2014 framework injects MCP servers\n  timeout: 120000,           // optional \u2014 2 min timeout\n  prompt: (state) => \\`You are analyzing a pull request.\n\nInput:\n\\${JSON.stringify(state.input || {}, null, 2)}\n\nReturn a JSON object matching the schema.\\`,\n  outputSchema: OutputSchema,\n};\n```\n\n### Graph pattern\n```javascript\nimport { WorkflowAgent, WorkflowGraph } from '@zibby/core';\nimport { classifyNode, routeNode } from './nodes/index.mjs';\n\nexport class MyWorkflow extends WorkflowAgent {\n  buildGraph() {\n    const graph = new WorkflowGraph();\n    graph.addNode('classify', classifyNode);\n    graph.addNode('route', routeNode);\n    graph.setEntryPoint('classify');\n    graph.addEdge('classify', 'route');\n    graph.addEdge('route', 'END');\n    return graph;\n  }\n\n  async onComplete(result) {\n    // Post-execution hook \u2014 save artifacts, notify, etc.\n    console.log('Workflow complete:', result.success);\n  }\n}\n```\n\nConditional edges: `graph.addConditionalEdges('node', (state) => state.node.priority === 'high' ? 'escalate' : 'notify')`\n\n### Available SKILLS constants\nImport from `@zibby/core`: `SKILLS.BROWSER`, `SKILLS.MEMORY`, `SKILLS.GITHUB`, `SKILLS.JIRA`, `SKILLS.SLACK`, `SKILLS.RUNNER`\n\n### Deep documentation\nCall `explore_framework_docs` to read detailed framework docs on demand. Use it for:\n- Advanced patterns (middleware, parallel nodes, state schemas)\n- Deployment & cloud triggers\n- CLI commands reference\n- Integration details (Jira, GitHub, etc.)\nCall with no arguments to see all available topics.\n\n### How to use the builder tools\n1. For complex workflows, call `explore_framework_docs(\"custom-workflows\")` first to learn advanced patterns.\n2. Ask the user what their workflow should do, what input it receives, and what steps are needed.\n3. Call `design_workflow` with the structured spec for the user to review.\n4. Once approved, call `build_workflow` to generate real code on disk (uses the configured agent for high-quality code generation).\n5. Remind the user: `zibby start <name>` to test locally, `zibby deploy <name> --project <id>` to deploy to cloud, `zibby logs --workflow <name>` to tail logs.\n\n### Important\n- Each node prompt should be detailed and specific \u2014 tell the AI agent exactly what to do and what format to return.\n- Zod schemas MUST use .describe() on every field so the agent knows what each field means.\n- Node names must be snake_case (e.g., classify_ticket, generate_report).\n- Workflow names must be kebab-case (e.g., ticket-triage, pr-review).\n- State flows through: each node's validated output is stored under its name in state (e.g., state.classify_ticket).\n- Downstream nodes reference upstream outputs in their prompt function (e.g., \\`\\${JSON.stringify(state.classify_ticket, null, 2)}\\`).\n- Nodes can declare skills to get MCP tool access \u2014 the framework handles server lifecycle automatically.";
+export {};