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

Core Loop

1. Start or Resume

# Check for active instances
flowforge active

# Resume if exists
flowforge status

# Or start new
flowforge start <workflow>

2. Get Action

flowforge run <workflow>

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-<workflow>-<node>"
)

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 "<result summary>" | flowforge advance

Or:

flowforge advance --result "<result summary>"

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

• spawn = sub-agent. When action type is spawn, use sessions_spawn. Not exec, not a coding CLI, not doing it yourself in the main session.
• Never skip nodes. Execute every node's task before advancing.
• Run to completion. Execute all nodes before reporting to the user. If a node spawns a sub-agent, wait for it to finish, then advance.
• State persists. Workflows survive session restarts. Use flowforge active to resume.
• Post-run: Record results in your daily log.

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

• task (required): Natural language instruction for what to do
• executor: 'subagent' (spawn) or 'inline' (default, do it yourself)
• next: Single next node for linear flow
• branches: Array of {condition, next} for branching
• terminal: true for end nodes

Troubleshooting

• "No active instance": Run flowforge start
• "Workflow not found": Run flowforge list to see available workflows
• Wrong node / stuck: Use flowforge reset to restart
• Sub-agent failed: Check the error, fix the issue, re-run the node or advance manually