Create a workflow

Create a workflow

A workflow is a folder containing workflow.json plus one subfolder per node. Use light init to scaffold, or create the structure manually.

Folder layout

my-workflow/
  workflow.json                  # id, name, network, nodes[], links[]
  node-a/
    .node.json                   # id, name, image, entrypoint, setup, I/O schema
    index.js                     # code
    lp.js                        # helper (auto-generated)
    lp.d.ts                      # helper types (auto-generated)

workflow.json shape

{
  "id": "my-workflow",
  "name": "My Workflow",
  "networks": [],
  "networkDefs": [],
  "nodes": [{ "id": "node-a", "name": "Node A", "dir": "node-a" }],
  "links": [
    {
      "from": "node-a",
      "to": "node-b",
      "when": { "status": "ok" },
      "data": { "passthrough": "$.output.value" }
    }
  ]
}

Commands

• light init - scaffold a new workflow in the current directory
• light init <name> - scaffold inside <name>/
• light check <dir> - validate workflow structure (AJV against schema)
• light describe <dir> - render the DAG with I/O schemas (text + Mermaid HTML)
• light pack <name> - convert folder to single JSON file (use --keep to preserve folder)
• light unpack <file> - convert JSON to folder
• light list - list all workflows in the current directory

Link conditions (MongoDB-style)

Operators: gt, gte, lt, lte, ne, in, exists, regex, or.

{ "count": { "gt": 5 }, "status": "ok" }

Top-level fields are AND. Use { "or": [...] } for OR logic.

Back-links (cycles)

Any link that creates a cycle is a back-link and must declare maxIterations to prevent infinite loops.

Spec-driven reflex

If the user has not written the workflow's purpose, inputs, and exit criteria yet, ask them to write a short README first before generating nodes. KISS / YAGNI - do not add nodes "for later".