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:
- User explicitly requests "workflow", "step by step", or "use flowforge"
- Task has multiple sequential steps that shouldn't be skipped
- User wants enforced execution order (e.g., always test before submit)
- Task involves state that needs to persist across sessions
Don't use for simple one-off tasks or quick questions.
My Workflows
<!-- This table maps user intents to workflow names. -->
<!-- When you notice the same intent matching the same workflow 2-3 times, add it here. -->
<!-- This saves a `flowforge list` lookup every time and makes triggering instant. -->
| 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 <workflow-name>
3. Execute Current Node
After flowforge status, you'll see:
- Current node name
- Task (natural language instruction)
- Next node or branches
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:
flowforge status — see current task- Execute the task
flowforge next — advance- 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:
- Ask about their process steps
- Draft a YAML file (see yaml-format.md)
- Save to
workflows/ directory or workspace
- 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
task: Natural language instruction (required)next: Single next node for linear flowbranches: Array of {condition, next} for branchingterminal: Set to true for end nodes
Rules
- Never skip nodes. Execute every node's task before advancing.
- Always check status. Don't assume position — run
flowforge status.
- One task at a time. Complete current node before looking ahead.
- Post-run. When a workflow reaches a terminal node, record what was done and the outcome. If your workspace has a memory or log system, write results there.
- State persists. Workflows survive session restarts.
- Use reset sparingly. Only reset if workflow is stuck or user requests it.
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:
./workflows/ in current directory~/.flowforge/workflows/ in home directory
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"
- Check if contribution workflow exists:
flowforge list
- Start:
flowforge start code-contribution
- 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"
- Check for study workflow:
flowforge list
- If exists:
flowforge start study
- 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:
flowforge active → shows interrupted workflowflowforge status → shows current node- Continue from there
Troubleshooting
"No active instance": Run flowforge start <workflow>
"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
