Workflow Generate

workflow-generate

Turn a plain-language description into a *.workflow.json that conforms to the contract and passes the CLI validators.

There is no constrained decoding here — a skill is a prompt, not a schema-locked decoder. Correctness comes from a generate → validate → fix loop, not from a perfect first draft. The contract gives you the shapes; the two CLI gates give you ground truth. Get close, then let the validators drive you to exit 0.

When to use

The user describes a workflow in prose and wants a usable *.workflow.json.

Do NOT use this skill for:

• Editing an existing workflow visually — that's fh-workflow open
• Only checking an existing file — run fh-workflow check-schema / validate directly

How to run it

All validation runs through the fh-workflow CLI (the published @foresthubai/workflow-cli package), invoked by its bare binary name — never through any in-repo node …/fh-workflow.mjs path. The CLI carries its own bundled copy of the contract, so it works from any directory and needs no edge-agents checkout.

Before anything else, confirm the CLI is installed:

command -v fh-workflow

If that prints nothing, stop and tell the user to install it once with npm i -g @foresthubai/workflow-cli, then continue. Do not fall back to a repo-local node path — the whole point is that this skill runs anywhere the CLI is on PATH.

Step 1: Understand the request — ask only about pivotal unknowns

A *.workflow.json is a cheap, throwaway text file — nothing is deployed, and regenerating costs seconds. So the default posture is assume sensible defaults and build, not interrogate. The fix for "don't decide things silently" is not an interview up front; it's making the consequential assumptions visible in the report (Step 5). Sort every unknown into one of three tiers:

1. Mechanical — no behavioral effect, or exactly one sensible value: canvas positions, internal channel/edge ids, output variable names, node ids. Fill silently with a default; never ask, don't even surface it.
2. Consequential but defaultable — affects runtime behavior, result, cost, or correctness, but has a reasonable default: LLM model, numeric data type (int vs float), intervals/thresholds, debounce, QoS/retain, signal type when a default is safe. Pick a sensible default and build — do NOT block on it. These get listed in the Step 5 report so the user can change them. Most parameters live here; asking about each would be the interrogation we avoid.
3. Pivotal — no safe default, or the choice cascades through the structure (an ambiguous trigger; digital vs analog when it changes the wiring; whether an Agent is even needed). Only these are worth AskUserQuestion, and only when the description leaves them open.

So: if the description determines the workflow, skip the interview entirely and go to Step 2. When tier-3 unknowns remain, ask them — bundled into one AskUserQuestion call (it takes up to 4 questions), each with the sensible default as the first option, marked "(recommended)", so one click accepts it. Never fire several questions one after another.

Typical pivotal points: the trigger (Ticker/OnStartup/OnPinEdge/Alarm/ OnThreshold/MQTT/serial), whether hardware (pins/serial/MQTT) is involved at all, and whether an Agent/LLM node is needed.

Step 2: Load the shapes and the idioms

• Read reference/workflow.yaml next to this file — a snapshot of the contract, the source of truth for every field shape. (The CLI carries its own copy for validation; this bundled snapshot is your authoring reference. If the two ever disagree, the CLI gates win.) Look up the specific *Node schemas you need (each lists its required arguments) plus Edge, Expression, OutputBinding, OutputDeclaration, Variable, and the Channel variants. A few schemas are cross-referenced from reference/llmproxy.yaml (e.g. ModelCapability) — follow llmproxy.yaml#/... refs into that sibling snapshot.

• Read the reference fixtures in examples/ next to this file — they are known-good, fully validated workflows that show the idioms by example:

  • counter-agent.workflow.json — Ticker → SetVariable → Agent: an agentTask edge with a prompt, an OutputDeclaration in assign mode, an Expression referencing a declared variable, a declaredVariables entry.
  • gpio-pin.workflow.json — Ticker → ReadPin → WritePin: GPIOIN/GPIOOUT channels referenced by id, an OutputBinding in emit mode, and a downstream expression that references a node's emitted output (see Notes — by output id, not the emit name), digital pins.

  Do not rely on any example files outside this skill folder — only these fixtures are guaranteed to exist and stay valid.

• For the semantic rules the contract shape can't express — which fields are truly required, why a schema-optional argument can still be mandatory — read reference/parameters.md next to this file (§1 presence table, §3 optional vs activationRules). Reach for it on demand, e.g. when validate reports a missing-required-param. Two semantic facts worth knowing up front: validation runs on the deserialized domain, not the raw JSON, so a file can pass check-schema and still fail validate; and a workflow on an older schemaVersion can be migrated with fh-workflow update <file>.

• Only when the workflow defines or calls a reusable function — i.e. a FunctionCall node and a non-empty top-level functions array — read reference/functions.md next to this file (the functions analog of parameters.md). It covers the semantics the contract shape can't show: a function is a declaration (the signature — name, arguments, returns) plus a body (its own canvas of nodes/edges); on the wire a Function is { functionInfo, outputAssignments, body }; a FunctionCall references its target by functionId and carries the same flat uid-keyed arguments bag every node uses (Expression for inputs, OutputBinding for returns); return values are expressions on the declaration — there is no return node, and a return with no assignment is a hard error. The default sensor→agent→actuator workflows use none of this — skip it entirely unless a reusable function is genuinely in play.

Step 3: Generate the workflow

Where to write it. Use the path the user gave. If they named only a folder, write <name>.workflow.json inside it; if they gave a full path, use it verbatim. If they gave nothing, default to the current working directory as <name>.workflow.json. Always end the filename in .workflow.json — that suffix is the convention the tooling keys off.

Checklist for a clean first draft:

• All six required top-level fields present (schemaVersion, nodes, edges, functions, declaredVariables, channels); empty arrays are fine.
• Every node has id, type, position; the type discriminator matches a contract node exactly; required arguments per that node's schema are set.
• The graph starts at a trigger and every node is reachable from it via ctrl-port edges (see Notes — connectivity is validated).
• Declare any hardware/MQTT channels and reference them by id from the nodes that use them.
• Expressions list every variable they use in references.