/workflow-json-builder

name: workflow-json-builder
description: Use this skill when the online UI chat assistant must guide a user through designing a ChengOS workflow and generate an importable workflow JSON file. The assistant uses Workflow API endpoints for templates, node schemas, and LLM model lists.

Workflow JSON Builder

Use this skill in the online UI chat dialog when the goal is to help the user design a workflow and produce a JSON artifact they can import into the workflow editor.

The assistant calls the separately deployed Workflow API to gather context, then returns workflow JSON to the user.

> **Authoritative contract:** all generated workflow JSON must follow the > **Workflow JSON Contract** (`docs/workflow-json-generation-guide.md`) — the > single source of truth for structure, field names, port handling, and > `skipValidation` semantics. This skill is the UI-chat front end to that > contract; when in doubt, defer to the contract. > > **Scope & contract boundary:** this skill targets the **UI/REST API DTO** path > (the endpoints below), which is distinct from the canonical **file-import** > contract (`workflow.json` = `WorkflowFileV1`: camelCase, required top-level > `name`, nested `definition`). `skipValidation` affects only this API/DTO path, > **not** the file importer. Use the same field names (`nodeId`, `nodeType`, > `sourceNode`/`sourcePort`/`targetNode`/`targetPort`) and identity rules (all > IDs are UUIDs) as the contract. Never emit the flat snake_case shape > (`node_type`, `node_config`, `source_port`) — the canonical decoder rejects it. > Agents running inside the engine should prefer the `tools/import_workflow` > structured create mode, which validates against live schemas before writing.

Allowed APIs

Base URL: use the Workflow service base URL configured by the UI/runtime, then append `/api/v1`.

Read-only discovery:

GET /api/v1/workflows/templates
GET /api/v1/workflows/templates/{id}
GET /api/v1/nodes/types
GET /api/v1/nodes/schema/{nodeType}
GET /api/v1/llm/models

API Details

GET /api/v1/workflows/templates

Returns all template workflow summaries: name, description, node count, edge count, tags, visibility. LLM uses it to recommend templates, pick by user intent, or explain template purpose. To get full nodes and edges, call `GET /api/v1/workflows/templates/{id}` which returns `definition.nodes` and `definition.edges`.

GET /api/v1/workflows/templates/{id}

Returns a full template definition with nodes and edges. Use it to adapt an existing workflow instead of inventing everything from scratch.

GET /api/v1/nodes/types and GET /api/v1/nodes/schema/{nodeType}

Returns node types, categories, descriptions, input JSON Schema, output JSON Schema, and i18n keys. LLM uses it to understand available nodes, how to configure each, what input/output ports exist, which nodes can connect to which, and to generate node config JSON. `POST /api/v1/nodes/validate` can validate a single node config, but it is a protected write route.

GET /api/v1/llm/models

Returns models grouped by provider, including chat and embedding types. LLM uses it to select models for `ai/llm`, `ai/llm_config`, embedding/RAG nodes, or to fill model names when generating workflow JSON. Note: this endpoint currently does not read user settings, so `enabled` defaults to false; full user-level provider/credential info is in the protected `GET /api/v1/llm/providers`.

LLM Capabilities

Based on these APIs, the assistant can:

1. Analyze node wiring for the user

Read a workflow's `nodes + edges`, then use `/nodes/schema/{nodeType}` to get each node's input/output schema, and check:

• Does the edge's `sourcePort` exist in the source node's outputs?
• Does the edge's `targetPort` exist in the target node's inputs?
• Are data types roughly compatible?
• Are there orphan nodes, nodes with no entry, cycle risks, or missing critical configs?

2. Create workflow JSON from natural language

Example flow: user says "I want to upload a file, convert it to text, then let LLM summarize". LLM calls `/nodes/types` to find file upload, document-to-text, LLM, and output nodes; calls `/llm/models` to pick an available model; generates a `CreateWorkflowRequest.definition` with `nodes + edges` (structure matches `workflow_dto.rs` line 189); returns importable JSON.

3. Configure or switch LLM models

For an existing workflow, use `GET /api/v1/workflows/{id}/llm-nodes` to find LLM nodes, then `PUT /api/v1/workflows/{id}/llm-nodes/{node_id}` to update model/provider/config (code in `workflow/mod.rs` line 1510). **Note**: these are protected write routes requiring authentication.

4. Generate from templates

List templates, read a full template definition, then modify per user needs:

• Replace the model
• Add/remove nodes
• Change prompts/configs
• Adjust wiring
• Generate new workflow JSON or create a copy

5. Explain workflows and node capabilities

Because node schemas include `description`, `category`, and `input/output` schemas, LLM can translate a complex workflow into human language: what each step does, how data flows, where credentials are needed, where failures may occur.

Boundary

The APIs listed above are **read-only discovery**. LLM can analyze, recommend, and generate draft JSON, but cannot truly save. To persist, use `POST /api/v1/workflows` to create; `PUT/PATCH /api/v1/workflows/{id}` to update; `POST /api/v1/nodes/validate` to validate a node config. These protected write routes require authentication.

Conversation Flow

1. Understand the user's goal in one or two turns.

• Ask only for missing information that changes the workflow structure, such as input source, desired output, target channel, model preference, schedule, storage destination, or approval step.
• Do not ask for technical node names unless the user already thinks in nodes.

2. Load discovery context.

• Call `/nodes/types` first.
• Call `/workflows/templates` when the goal sounds