FlowForge

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. Setup will install the CLI, create the workflows directory, and configure your workspace.

When to Use FlowForge

Use FlowForge when:

Don't use for simple one-off tasks or quick questions.

My Workflows

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

Self-updating rule: When you match an intent to a workflow via flowforge list and it works well, add that mapping to the table above. Then update the description field in the YAML frontmatter at the top of this file to include the new trigger phrase — this is how OpenClaw knows when to activate this skill.

Core Workflow

1. Find the Right Workflow

First check the My Workflows table above. If the user's intent matches an entry, use it directly.

If no match, fall back to discovery:

flowforge list

If no workflow matches user's intent, help them create one (see yaml-format.md).

2. Start or Resume

# Check for active instances
flowforge active
If active instance exists → resume
flowforge status
If no active instance → start new
flowforge start 

3. Execute Current Node

After flowforge status, you'll see:

Execute the task as described. The task field tells you exactly what to do.

For complex implementation tasks: delegate to appropriate tools or sub-agents. For simple tasks: execute directly.

4. Advance to Next Node

After completing the task:

# Linear flow (no branches)
flowforge next
Branching flow (multiple paths)
flowforge next --branch 1   # first condition
flowforge next --branch 2   # second condition

5. Repeat Until Complete

Continue the cycle: 1. flowforge status — see current task 2. Execute the task 3. flowforge next — advance 4. Repeat until terminal node

6. View History

flowforge log

Shows all nodes visited with timestamps.

Creating New Workflows

If user needs a workflow that doesn't exist:

1. Ask about their process steps 2. Draft a YAML file (see yaml-format.md) 3. Save to workflows/ directory or workspace 4. Register with flowforge define workflow.yaml

See references/examples/ for templates.

YAML Format Quick Reference

name: workflow-name
description: What this workflow does
start: first-node
nodes:
  first-node:
    task: Description of what to do
    next: second-node
  second-node:
    task: Another task
    branches:
      - condition: success
        next: final-node
      - condition: failure
        next: first-node
  final-node:
    task: Wrap up and report
    terminal: true

Node Fields

Rules

Advanced Usage

Multiple Workflows

If user has multiple active workflows:

flowforge active  # list all
flowforge status  # shows current default

Reset Current Workflow

flowforge reset

Creates new instance from start node. Old history is preserved.

Workflow Discovery

FlowForge auto-loads YAML files from:

Users can drop workflow files into these directories and they're automatically available — no need to run flowforge define.

Examples

Example 1: Code Contribution

User: "Help me contribute to this project"

1. Check if contribution workflow exists: flowforge list 2. Start: flowforge start code-contribution 3. Execute each node: - study → read project structure - implement → write code - test → run tests - submit → create PR - verify → address feedback

Example 2: Learning Workflow

User: "I want to study React hooks step by step"

1. Check for study workflow: flowforge list 2. If exists: flowforge start study 3. If not: help create YAML with nodes like: - discover → find resources - deep-read → read documentation - practice → write examples - reflect → note key concepts

Example 3: Resume Interrupted Work

User returns after session ended mid-workflow:

1. flowforge active → shows interrupted workflow 2. flowforge status → shows current node 3. Continue from there

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 workflow

Need to modify workflow: Edit YAML file, run flowforge define workflow.yaml to update

See Also

Example 1: Code Contribution

User: "Help me contribute to this project"

1. Check if contribution workflow exists: flowforge list 2. Start: flowforge start code-contribution 3. Execute each node: - study → read project structure - implement → write code - test → run tests - submit → create PR - verify → address feedback

Example 2: Learning Workflow

User: "I want to study React hooks step by step"

1. Check for study workflow: flowforge list 2. If exists: flowforge start study 3. If not: help create YAML with nodes like: - discover → find resources - deep-read → read documentation - practice → write examples - reflect → note key concepts

Example 3: Resume Interrupted Work

User returns after session ended mid-workflow:

1. flowforge active → shows interrupted workflow 2. flowforge status → shows current node 3. Continue from there

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. Setup will install the CLI, create the workflows directory, and configure your workspace.

"No active instance": Run flowforge start

"Workflow not found": Run flowforge list to see available workflows

Wrong node/stuck: Use flowforge reset to restart workflow

Need to modify workflow: Edit YAML file, run flowforge define workflow.yaml to update