New Workflow

Workscript Workflow Generator

Generate valid, production-ready workflow JSON files for the Workscript Agentic Workflow Engine.

Every workflow MUST include defensive guards to prevent runtime errors. See Defensive Guards & Validation section.

Workflow Generation Process

Step 1: Understand Requirements

Ask clarifying questions to understand:

• What should this workflow accomplish?
• What is the input data structure?
• What are the expected outputs/side effects?
• Are there error handling requirements?
• Will it need loops, conditionals, or API calls?
• Does the workflow use AI for structured output? (Requires JSON validation)
• Is the input from external sources? (Requires input validation)
• Is this domain-specific logic that might be reused? (May warrant a custom node)

Step 2: Fetch Node Documentation

If API server is running, fetch the compact node manifest:

curl -s http://localhost:3013/workscript/reflection/manifest/compact | jq .

If API is not running, start the dev server:

cd /Users/narcisbrindusescu/teste/workscript && bun run dev

Wait for the server to start, then retry the manifest fetch.

Alternatively, use the offline reference: references/node-quick-reference.md

Step 2.5: Complexity Assessment (CRITICAL)

Before designing the workflow, assess if it can be built with existing nodes OR if new nodes should be developed first.

Complexity Red Flags

Stop and consider node development if ANY of these apply:

Complexity Assessment Questions

Ask yourself:

1. Can I describe each workflow step in 1-2 words?

   • ✅ "Filter active" → "Sort by date" → "Send email" (Simple)
   • ❌ "Parse and extract nested JSON, validate structure, map fields, handle arrays" (Complex - needs a node)

2. Would a domain expert understand the workflow at a glance?

   • ✅ User sees: validateInvoice → calculateTax → generatePDF
   • ❌ User sees: 15 nodes doing string manipulation and math

3. Am I repeating logic that should be encapsulated?

   • ✅ One dateTime node handles all date formatting
   • ❌ Multiple stringOperations + math + logic to achieve the same

4. Is the workflow solving a generic or specific problem?

   • Generic (reusable) → Build workflow
   • Specific domain logic → Consider a node

When to Pivot to Node Development

STOP generating the workflow and suggest node development when:

Complexity Score = (nesting_depth × 2) + repeated_patterns + (nodes_for_one_concept - 1) + workarounds

If Complexity Score ≥ 6 → Suggest new node(s)

Example calculation:

• 4 levels of nesting (4 × 2 = 8)
• 1 repeated pattern (1)
• 5 nodes for "parse invoice" (5 - 1 = 4)
• 1 workaround using AI (1)
• Total: 14 → Definitely needs new node(s)

Node Suggestion Template

When complexity threshold is exceeded, respond with:

⚠️ Complexity Alert: This workflow would be too complex to maintain.

Based on your requirements, I recommend developing new node(s) first:

Benefits of building these nodes:

1. Workflow becomes 3 nodes instead of 15
2. Each node is testable in isolation
3. Logic is reusable across workflows
4. Domain concepts are explicit (not buried in JSON config)

Next steps:

1. Run /new-node to create parseInvoice node
2. Run /new-node to create calculateLineItems node
3. Return here to generate the simplified workflow

Would you like me to proceed with node development first?

Simplified Workflow Vision

Always show what the workflow WOULD look like with the suggested nodes:

{
  "id": "invoice-processor",
  "name": "Invoice Processor",
  "version": "1.0.0",
  "workflow": [
    { "parseInvoice": { "source": "$.rawData", "format": "auto" } },
    { "calculateLineItems": { "items": "$.invoiceData.lines" } },
    { "generatePDF": { "template": "invoice-template", "data": "$.processedInvoice" } }
  ]
}

Compare to what it would be WITHOUT the new nodes: (show the 15-node monstrosity briefly)

This contrast helps the user understand the value of investing in node development.

Step 3: Design Workflow Structure

Based on requirements, identify:

1. Entry point node(s) - First node(s) to execute
2. Data flow - How data moves through nodes
3. Branching points - Where edges are needed (conditionals, error handling)
4. Sequential steps - Nodes that should run one after another (use workflow array)
5. State keys - What to read ($.key) and write
6. Loop requirements - Use nodeType... suffix for loops

Use patterns from references/patterns.md as templates.

Step 4: Generate Valid JSON - FLAT BY DEFAULT

CRITICAL: Prefer flat, linear workflows. Use edges only for actual branching.

The workflow array supports sequential execution - nodes run one after another automatically. Reserve edges for:

• Conditional branching: true?/false?, valid?/invalid?, found?/not_found?
• Error handling: error? edges
• Loop control: continue?/exit? with nodeType...
• Multi-way routing: switch node dynamic edges

WRONG - Excessive Nesting (Anti-Pattern)

{
  "workflow": [
    {
      "googleConnect": {
        "email": "$.email",
        "success?": {
          "listEmails": {
            "maxResults": 10,
            "success?": {
              "ask-ai": {
                "userPrompt": "Analyze...",
                "success?": {
                  "resource-write": {
                    "content": "$.aiResponse",
                    "created?": {
                      "log": { "message": "Done" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}

Problems:

• 5+ levels of nesting
• Hard to read and maintain
• success? edges don't add value when next step is unconditional

CORRECT - Flat Sequential (Preferred)

{
  "workflow": [
    {
      "googleConnect": {
        "email": "$.email",
        "error?": { "log": { "message": "Connection failed: {{$.error}}" } }
      }
    },
    {
      "listEmails": {
        "maxResults": 10,
        "no_results?": { "log": { "message": "No emails found" } },
        "error?": { "log": { "message": "Failed: {{$.error}}" } }
      }
    },
    {
      "ask-ai": {
        "userPrompt": "Analyze...",
        "error?": { "log": { "message": "AI failed: {{$.error}}" } }
      }
    },
    {
      "resource-write": {
        "content": "$.aiResponse",
        "created?": { "log": { "message": "Created: {{$.writtenResourceId}}" } },
        "updated?": { "log": { "message": "Updated: {{$.writtenResourceId}}" } },
        "error?": { "log": { "message": "Write failed: {{$.error}}" } }
      }
    }
  ]
}

Benefits:

• Linear, easy to read
• Each node handles its own edge cases
• Sequential flow is implicit

WHEN TO USE EDGES FOR CHAINING

Use edges for actual branching - when different paths lead to different outcomes:

{
  "workflow": [
    {
      "logic": {
        "operation": "equal",
        "values": ["$.user.role", "admin"],
        "true?": {
          "editFields": {
            "fieldsToSet": [{ "name": "access", "value": "full", "type": "string" }]
          }
        },
        "false?": {
          "editFields": {
            "fieldsToSet": [{ "name": "access", "value": "limited", "type": "string" }]
          }
        }
      }
    },
    {
      "log": { "message": "User {{$.user.name}} has {{$.access}} access" }
    }
  ]
}

Here true?/false? are meaningful branches - they execute different logic.

Step 4.5: Add Defensive Guards

Before finalizing, add guards for:

1. Input validation at entry point:

   {
     "validateData": {
       "validationType": "required_fields",
       "data": "$.input",
       "requiredFields": ["requiredField1", "requiredField2"],
       "invalid?": { "log": { "message": "Missing required input: {{$.validationErrors}}" } }
     }
   }
   

2. AI response JSON validation (if using ask-ai for structured data):

   {
     "validateData": {
       "validationType": "json",
       "data": "$.aiResponse",
       "valid?": { ... },
       "invalid?": { "log": { "message": "AI did not return valid JSON" } }
     }
   }
   

3. Array guards before loops (if processing arrays):

   {
     "logic": {
       "operation": "greater",
       "values": ["$.items.length", 0],
       "true?": { ... },
       "false?": { "log": { "message": "No items to process" } }
     }
   }
   

4. Error edges on all nodes that can fail:

   {
     "nodeType": {
       "config": "...",
       "error?": { "log": { "message": "Operation failed: {{$.error}}" } }
     }
   }
   

See Defensive Guards & Validation for complete patterns.

Step 5: Validate Workflow

Run the validation script before saving:

bun /Users/narcisbrindusescu/teste/workscript/.claude/skills/new-workflow/scripts/validate-workflow.ts <workflow.json>

The script checks:

• JSON Schema compliance (required fields, patterns)
• Node type existence (all nodeTypes must be registered)
• State setter syntax validity ($.path format)
• Edge name format

Exit codes: 0 = valid, 1 = schema errors, 2 = semantic errors

Step 6: Save to Output Folder

Save validated workflow to:

/Users/narcisbrindusescu/teste/workscript/apps/sandbox/resources/shared/prompts/<kebab-case-name>.json

File naming:

• Use kebab-case matching workflow id
• Examples: user-registration.json, data-pipeline.json, email-processor.json

Workflow Structure Guidelines

Flat vs Nested Decision Matrix

Template: Flat Sequential Workflow

{
  "id": "kebab-case-id",
  "name": "Human Readable Name",
  "version": "1.0.0",
  "description": "Optional description",
  "initialState": { ... },
  "workflow": [
    { "node1": { "config": "...", "error?": { "log": {...} } } },
    { "node2": { "config": "...", "error?": { "log": {...} } } },
    { "node3": { "config": "..." } }
  ]
}

Template: Branching Workflow

{
  "id": "kebab-case-id",
  "name": "Human Readable Name",
  "version": "1.0.0",
  "initialState": { ... },
  "workflow": [
    {
      "logic": {
        "operation": "equal",
        "values": ["$.condition", true],
        "true?": { "node-for-true": { ... } },
        "false?": { "node-for-false": { ... } }
      }
    },
    { "final-node": { "message": "After branch" } }
  ]
}

API Integration

Reflection API Endpoints

Checking API Status

curl -s http://localhost:3013/health

Starting Dev Server

cd /Users/narcisbrindusescu/teste/workscript && bun run dev

The API will be available at http://localhost:3013.

Output Requirements

Quick Reference

Required Workflow Fields

Edge Route Types

State Syntax

Common Edge Names

Defensive Guards & Validation

CRITICAL: All generated workflows MUST include defensive guards to prevent runtime errors.

Guard Types

Pattern 1: Validate Input Before Processing

Always validate external/user input at workflow entry:

{
  "workflow": [
    {
      "validateData": {
        "validationType": "required_fields",
        "data": "$.input",
        "requiredFields": ["userId", "action"],
        "invalid?": {
          "log": { "message": "Missing required input: {{$.validationErrors}}" }
        },
        "error?": {
          "log": { "message": "Input validation failed: {{$.error}}" }
        }
      }
    },
    {
      "log": { "message": "Processing valid input for user {{$.input.userId}}" }
    }
  ]
}

Pattern 2: Array Length Guard Before Iteration

Check array exists and has items before looping:

{
  "workflow": [
    {
      "logic": {
        "operation": "and",
        "values": [
          { "operation": "greater", "values": ["$.items.length", 0] }
        ],
        "true?": {
          "logic...": {
            "operation": "less",
            "values": ["$.index", "$.items.length"],
            "true?": [
              { "log": { "message": "Processing item {{$.index}}" } },
              { "$.index": "$.index + 1" }
            ],
            "false?": null
          }
        },
        "false?": {
          "log": { "message": "No items to process" }
        }
      }
    }
  ]
}

Pattern 3: Validate AI Response as Structured JSON

ALWAYS validate AI output when expecting JSON structure:

{
  "workflow": [
    {
      "ask-ai": {
        "userPrompt": "Extract entities as JSON: {{$.text}}",
        "model": "openai/gpt-4o-mini",
        "systemPrompt": "Return ONLY valid JSON: {\"entities\": [{\"name\": string, \"type\": string}]}",
        "error?": {
          "editFields": {
            "fieldsToSet": [{ "name": "aiError", "value": "$.error", "type": "string" }]
          }
        }
      }
    },
    {
      "validateData": {
        "validationType": "json",
        "data": "$.aiResponse",
        "valid?": {
          "validateData": {
            "validationType": "required_fields",
            "data": "$.parsedJson",
            "requiredFields": ["entities"],
            "valid?": {
              "log": { "message": "AI returned valid structure with {{$.parsedJson.entities.length}} entities" }
            },
            "invalid?": {
              "log": { "message": "AI response missing required fields: {{$.validationErrors}}" }
            }
          }
        },
        "invalid?": {
          "log": { "message": "AI did not return valid JSON: {{$.validationErrors}}" }
        }
      }
    }
  ]
}

Pattern 4: Type Safety Before Operations

Validate types before type-sensitive operations:

{
  "workflow": [
    {
      "validateData": {
        "validationType": "type_check",
        "data": "$.data",
        "typeChecks": [
          { "field": "amount", "expectedType": "number" },
          { "field": "items", "expectedType": "array" },
          { "field": "metadata", "expectedType": "object" }
        ],
        "valid?": {
          "math": {
            "operation": "multiply",
            "values": ["$.data.amount", 1.1]
          }
        },
        "invalid?": {
          "log": { "message": "Type validation failed: {{$.validationErrors}}" }
        }
      }
    }
  ]
}

Pattern 5: Comprehensive Guard Chain

For critical workflows, chain multiple guards:

{
  "workflow": [
    {
      "validateData": {
        "validationType": "required_fields",
        "data": "$.request",
        "requiredFields": ["userId", "email", "payload"],
        "invalid?": {
          "editFields": {
            "fieldsToSet": [
              { "name": "errorType", "value": "MISSING_FIELDS", "type": "string" },
              { "name": "errorDetails", "value": "$.validationErrors", "type": "any" }
            ]
          }
        }
      }
    },
    {
      "validateData": {
        "validationType": "pattern",
        "data": "$.request",
        "patternValidations": [
          { "field": "email", "pattern": "^[^@]+@[^@]+\\.[^@]+$", "errorMessage": "Invalid email format" }
        ],
        "invalid?": {
          "editFields": {
            "fieldsToSet": [
              { "name": "errorType", "value": "INVALID_FORMAT", "type": "string" },
              { "name": "errorDetails", "value": "$.validationErrors", "type": "any" }
            ]
          }
        }
      }
    },
    {
      "validateData": {
        "validationType": "type_check",
        "data": "$.request.payload",
        "typeChecks": [
          { "field": "amount", "expectedType": "number" }
        ],
        "invalid?": {
          "editFields": {
            "fieldsToSet": [
              { "name": "errorType", "value": "TYPE_ERROR", "type": "string" },
              { "name": "errorDetails", "value": "$.validationErrors", "type": "any" }
            ]
          }
        }
      }
    },
    {
      "log": { "message": "All validations passed for {{$.request.userId}}" }
    }
  ]
}

Guard Checklist for Generated Workflows

Before finalizing any workflow, ensure:

• Entry validation: First node validates initialState or external input
• AI output validation: Any ask-ai response used as structured data is validated with validateData (validationType: json)
• Array guards: Loops check array length before iteration
• Required fields: Nested property access is guarded by required_fields validation
• Error edges: All nodes that can fail have error? edges
• Type checks: Operations requiring specific types validate beforehand
• Graceful fallbacks: invalid? edges provide meaningful error context

validateData Node Reference

State written by validateData:

• validationResult: { isValid, timestamp, validationType }
• validationErrors: Array of { field, error, value }
• parsedJson: (only for json type) The parsed JSON object

Reference Documentation

• Complexity Detection: references/complexity-detection.md - When to stop and suggest node development
• Workflow Syntax: references/workflow-syntax.md - Complete JSON structure reference
• Patterns: references/patterns.md - Common workflow patterns with examples
• Node Reference: references/node-quick-reference.md - All 45 nodes categorized
• Flat vs Nested Comparison: references/flat-vs-nested.md - Side-by-side examples
• Defensive Guards: See section above for validation patterns

Scripts

• Validate: scripts/validate-workflow.ts - Validate workflow JSON
• Fetch Manifest: scripts/fetch-manifest.sh - Fetch node manifest from API
• Start Server: scripts/start-dev-server.sh - Start dev server if not running