FlowForge Workflow Engine

FlowForge Workflow Runner

Execute multi-step workflows defined in YAML files using the FlowForge state machine engine.

Prerequisites

FlowForge CLI must be installed. Check with:

flowforge --version

If the command fails or is not found, run the setup flow in setup.md before proceeding.

My Workflows

| Intent | Workflow | |--------|----------| | *(add your mappings here as you use FlowForge)* | |

Core Loop

1. Start or Resume

# Check for active instances
flowforge active
Resume if exists
flowforge status
Or start new
flowforge start 

2. Get Action

flowforge run 

Returns JSON: { action: { type, node, task, branches, ... } }

3. Execute by Action Type

type: 'spawn' — Node has executor: subagent. MUST spawn a sub-agent:

sessions_spawn(
  task: action.task,
  mode: "run",
  label: "flowforge--"
)

Wait for sub-agent to complete. Collect its output.

⚠️ NEVER execute spawn tasks yourself in the main session. The whole point of subagent nodes is delegation — they run in parallel, unblock the main session, and use the best tool for the job. If you do it yourself, you're blocking the main session and defeating the purpose.

type: 'prompt' — Node needs your direct judgment. Execute the task yourself in the main session. Use this for decision-making, lightweight checks, and coordination — not heavy implementation work.

type: 'complete' — Workflow finished. Report results to the user.

4. Advance

After getting the result (from sub-agent output or your own work):

echo "" | flowforge advance

Or:

flowforge advance --result ""

If the node had branches, include Branch: N in the result so the engine knows which path to take.

5. Repeat

Go back to step 2. Loop until type: 'complete'.

Rules

Manual Mode

If you prefer step-by-step control instead of the run/advance JSON loop:

flowforge status          # See current task
... execute task ...
flowforge next            # Advance (linear node)
flowforge next --branch N # Advance (branching node)

The same spawn rules apply: if the current node has executor: subagent, spawn a sub-agent.

Creating New Workflows

See references/yaml-format.md for the full YAML spec.

name: my-workflow
description: What this workflow does
start: first-node
nodes:
  first-node:
    task: What to do (detailed instructions for the executor)
    executor: subagent    # spawn a sub-agent for this node
    next: second-node
  second-node:
    task: Make a decision based on results
    # executor defaults to 'inline' — agent does it directly
    branches:
      - condition: success
        next: done
      - condition: retry
        next: first-node
  done:
    task: Report results
    terminal: true

Node Fields

Troubleshooting

FlowForge CLI must be installed. Check with:

flowforge --version

If the command fails or is not found, run the setup flow in setup.md before proceeding.