Workflow Composer

The visual editor for modeling project setup processes as recursive workflow trees. A 3-panel layout — context variables, workflow tree, and property inspector.

Editor Layout

Left Panel

Context variables — every variable referenced across all steps, listed at a glance.

Center Panel

Workflow tree — visual tree with drag-to-reorder, expand/collapse for branches, and Add Step button.

Right Panel

Properties — form editor for the selected step. Each step type has its own configurable properties.

Steps are ordered by array index — drag to reorder within a branch. Each sub-workflow has a flow step of type continue as a sentinel at the end — new steps are inserted before it, and it cannot be reordered or deleted.

Step Types Reference

Nine step types. Steps with branches contain nested sub-workflows that run depending on the outcome.

input

Prompts the user for text input and stores it in a named variable.

Properties

Property	Type	Description
variableName	string	Variable name to store the input
prompt	string	Question shown to the user
description	string	Help text displayed below the prompt
defaultValue	string	Pre-filled default value
required	boolean	Whether input is mandatory
secret	boolean	Masks input (for passwords/tokens)
placeholder	string	Ghost text in the input field
validationRegex	string	Regex pattern to validate input

Generated behavior: Prompts user, saves response to state. On re-run, loads saved value automatically.

choice

Presents the user with a list of options. Stores the selected value in a variable.

Properties

Property	Type	Description
variableName	string	Variable to store the choice
prompt	string	Question shown to the user
options	string[]	List of choices
defaultValue	string	Pre-selected default
allowCustomValue	boolean	Let user type a custom answer

Generated behavior: Shows a numbered list, reads user selection by index, saves the value.

commandbranches: onSuccess, onFailure

Executes a shell command. Can capture stdout, stderr, or exit code into variables.

Properties

Property	Type	Description
command	string	Shell command to execute
workingDirectory	string	Optional subdirectory to run in
captureStdoutTo	string	Variable to capture stdout output
captureStderrTo	string	Variable to capture stderr output
captureExitCodeTo	string	Variable to capture exit code

Generated behavior: Runs the command, checks exit code, jumps to success or failure branch.

checkbranches: onSuccess, onFailure

Validates a condition. Supports four check types.

Check Types

commandRun a command and check its exit code

fileExistsCheck if a file exists

directoryExistsCheck if a directory exists

environmentVariableCheck if an env var is set

Properties

Property	Type	Description
checkType	object	One of the four check types

Generated behavior: Evaluates the condition, jumps to success or failure sub-workflow.

conditionbranches: onTrue, onFalse

Branches based on comparing a variable against a value.

Properties

Property	Type	Description
variableName	string	Variable to compare
operator	enum	equals / notEquals / greaterThan / lessThan / contains, etc.
value	string	Value to compare against

Generated behavior: Evaluates the comparison at runtime, jumps to true or false sub-workflow.

filebranches: onSuccess, onFailure

Creates, appends, or modifies files on disk.

Operations

createOrOverwriteWrites content to a file (creates or replaces)

appendAppends content to the end of a file

replaceTextFind-and-replace text in an existing file

Properties

Property	Type	Description
filePath	string	Path to the target file
operation	object	One of the three file operations

Generated behavior: Performs the file operation, checks exit code, jumps to matching branch.

information

Displays a message to the user during setup. No branching.

Properties

Property	Type	Description
title	string	Heading for the message
content	string	Body text

Generated behavior: Echoes the title and content to the terminal.

osBranchbranches: macos, linux, windows

Branches based on the user's operating system. Each OS gets its own sub-workflow.

Properties

Property	Type	Description
No configurable properties

Generated behavior: Detects OS via uname / $PSVersionTable, sets NEXT to the matching branch.

flow

Controls execution flow within a sub-workflow. Acts as a sentinel — always the last step in a branch.

Properties

Property	Type	Description
flowType	enum	continue (return to parent) or jump (go to a specific step)

Generated behavior: Sets NEXT to empty (continue) or a target step ID (jump).

Data Model

A workflow is a JSON object containing an ordered list of steps. Each step has a unique UUID, a name, and a type. Steps that branch contain nested Workflow objects for each branch path, creating a recursive tree structure.

{
  "id": "uuid",
  "name": "My Workflow",
  "steps": [
    {
      "id": "step-1",
      "name": "Check Node",
      "type": "check",
      "checkType": { "type": "command", "command": "node --version" },
      "onSuccess": { "steps": [ ... ] },
      "onFailure": { "steps": [ ... ] }
    }
  ]
}

Workflows are saved as .project-igniter/workflows/<id>.json. A separate index at .project-igniter/workflows.json tracks all workflows, projects, and environment mappings.