Workflow Authoring Skill

This skill teaches agents how to author CloseCode ADE workflows — visual flow-based automations built from typed nodes connected by compatible sockets.

1. Overview

A workflow is a directed graph of typed nodes connected by edges. Workflows are persisted as WorkflowDefinition objects with nodes, edges, triggers, and settings.

Key concepts:

• Nodes — Processing units with typed input/output sockets
• Edges — Connections between an output socket on one node and an input socket on another
• Triggers — Binding nodes to external events (manual, cron, webhook, schedule)
• Pipeline Interface — Contract nodes (pipeline-input / pipeline-output) that define a sub-workflow's external API

2. MCP Tools Reference

Use these closecode MCP tools (activate closecode tools first):

3. Node Kind Catalog

All built-in nodes use the kind format builtin.<category>.<name>.

Triggers (category: trigger)

Agent (category: agent)

Control (category: control)

Data (category: data)

I/O (category: io)

Interaction (category: io / interaction)

Notify (category: notify)

Chat (category: chat)

Git (category: git)

Docs (category: docs)

Ops (category: ops)

Calendar (category: io / calendar)

Pipeline (category: pipeline)

Entity (category: entity)

4. Socket Types & Compatibility

Socket Types

Compatibility Rules

isCompatible(from, to) determines if output type from can connect to input type to:

1. Same type → always allowed
2. any on either side → allowed
3. Scalar widening to json → string, number, boolean, entity-ref all widen to json
4. Everything else → rejected (use a Transform node for explicit conversion)

// Quick reference:
string    → json ✓    json → string    ✗ (use transform)
number    → json ✓    json → number    ✗ (use transform)
boolean   → json ✓    json → boolean   ✗ (use transform)
entity-ref → json ✓
trigger   → trigger ✓ (flow control only)
any       → anything ✓
anything  → any ✓

5. Workflow Creation Pattern

Step-by-step

1. Discover available nodes:

   closecode_list_workflow_node_types()
   

   Returns all kinds with their input/output socket definitions.

2. Plan the flow: Start with a trigger → add processing nodes → add output nodes.

3. Find compatible nodes for a specific socket:

   closecode_suggest_compatible_nodes(
     sourceNodeKind: "builtin.trigger.manual",
     sourceHandleId: "fire",
     direction: "downstream"
   )
   

4. Create the workflow with nodes and edges:

   json
   1{
   2  "title": "My Workflow",
   3  "nodes": [
   4    { "id": "t1", "kind": "builtin.trigger.manual", "position": { "x": 0, "y": 0 }, "config": {} },
   5    { "id": "n1", "kind": "builtin.io.read-file", "position": { "x": 300, "y": 0 }, "config": { "path": "input.txt" } },
   6    { "id": "n2", "kind": "builtin.notify.log", "position": { "x": 600, "y": 0 }, "config": {} }
   7  ],
   8  "edges": [
   9    { "id": "e1", "source": "t1", "sourceHandle": "fire", "target": "n1", "targetHandle": "fire" },
   10    { "id": "e2", "source": "n1", "sourceHandle": "content", "target": "n2", "targetHandle": "text" },
   11    { "id": "e3", "source": "n1", "sourceHandle": "done", "target": "n2", "targetHandle": "fire" }
   12  ]
   13}

5. Validate:

   closecode_validate_workflow(workflowId: "my-workflow")
   

6. Run:

   closecode_run_workflow(workflowId: "my-workflow")
   

7. Check results:

   closecode_get_workflow_run(runId: "...")
   

Edge Format

Each edge connects one output to one input:

json
1{
2  "id": "unique-edge-id",
3  "source": "source-node-id",
4  "sourceHandle": "output-socket-id",
5  "target": "target-node-id",
6  "targetHandle": "input-socket-id"
7}

6. Common Patterns

Approval Workflow (Human-in-the-Loop)

json
1{
2  "title": "Approval Workflow",
3  "nodes": [
4    { "id": "trigger", "kind": "builtin.trigger.webhook", "position": { "x": 0, "y": 0 }, "config": {} },
5    { "id": "ask", "kind": "builtin.interaction.human-input", "position": { "x": 300, "y": 0 }, "config": {
6      "message": "Approve this request?",
7      "nextActions": [
8        { "label": "Approve", "value": "approved" },
9        { "label": "Reject", "value": "rejected" }
10      ]
11    }},
12    { "id": "branch", "kind": "builtin.control.condition", "position": { "x": 600, "y": 0 }, "config": {
13      "expression": "inputs.selectedAction === 'approved'"
14    }},
15    { "id": "approved", "kind": "builtin.notify.log", "position": { "x": 900, "y": -100 }, "config": {} },
16    { "id": "rejected", "kind": "builtin.notify.log", "position": { "x": 900, "y": 100 }, "config": {} }
17  ],
18  "edges": [
19    { "id": "e1", "source": "trigger", "sourceHandle": "fire", "target": "ask", "targetHandle": "trigger" },
20    { "id": "e2", "source": "ask", "sourceHandle": "done", "target": "branch", "targetHandle": "in" },
21    { "id": "e3", "source": "ask", "sourceHandle": "selectedAction", "target": "branch", "targetHandle": "test" },
22    { "id": "e4", "source": "branch", "sourceHandle": "true", "target": "approved", "targetHandle": "fire" },
23    { "id": "e5", "source": "branch", "sourceHandle": "false", "target": "rejected", "targetHandle": "fire" }
24  ]
25}

Agent Pipeline

Trigger → Agent A → Agent B → Output:

json
1{
2  "title": "Agent Pipeline",
3  "nodes": [
4    { "id": "t", "kind": "builtin.trigger.manual", "position": { "x": 0, "y": 0 }, "config": {} },
5    { "id": "a1", "kind": "builtin.agent.invoke", "position": { "x": 300, "y": 0 }, "config": { "agent": "planner", "prompt": "Analyze: {{inputs.prompt}}" } },
6    { "id": "a2", "kind": "builtin.agent.invoke", "position": { "x": 600, "y": 0 }, "config": { "agent": "coder", "prompt": "Implement based on: " } },
7    { "id": "log", "kind": "builtin.notify.log", "position": { "x": 900, "y": 0 }, "config": {} }
8  ],
9  "edges": [
10    { "id": "e1", "source": "t", "sourceHandle": "fire", "target": "a1", "targetHandle": "fire" },
11    { "id": "e2", "source": "a1", "sourceHandle": "done", "target": "a2", "targetHandle": "fire" },
12    { "id": "e3", "source": "a1", "sourceHandle": "text", "target": "a2", "targetHandle": "prompt" },
13    { "id": "e4", "source": "a2", "sourceHandle": "done", "target": "log", "targetHandle": "fire" },
14    { "id": "e5", "source": "a2", "sourceHandle": "text", "target": "log", "targetHandle": "text" }
15  ]
16}

Sub-workflow Delegation

Use builtin.control.sub-workflow to call another workflow. The target workflow should have pipeline-input and pipeline-output nodes to define its contract.

Entity-based Routing

Connect entity.user or entity.role outputs to nodes that accept entity-ref or json inputs to route messages or tasks to specific people/roles.

7. Tips & Best Practices

• Always include a trigger node — A workflow without a trigger cannot run
• Separate data and trigger edges — Most nodes need both a trigger edge (for execution order) and data edges (for values)
• Use human-input for human-in-the-loop — Pauses execution until a human responds
• Use sub-workflow for reusable flows — Encapsulate common patterns; pipeline interfaces define contracts
• Use validate before run — Catches socket mismatches, missing required inputs, and cycles
• Position nodes for readability — Space nodes ~300px apart horizontally
• Use descriptive node labels — Set label on nodes for clarity in the editor

8. Error Prevention

Socket Mismatches

Use closecode_suggest_compatible_nodes before creating edges. Common mistake: connecting a json output to a string input (rejected — use json-stringify first).

Missing Required Inputs

Required input sockets (required: true) must be connected. Validation catches this.

Cycle Detection

Workflows must be a DAG (directed acyclic graph). Validation detects and reports cycles.

Node Config

Each node has a config object specific to its kind. Check closecode_list_workflow_node_types for configSchema. Missing required config fields cause runtime errors.