StepForge

Improved workflow engine for AI agents — forked from FlowForge with critical improvements.

FlowForge asked: "What if agents couldn't skip steps?" StepForge asks: "What if they couldn't get stuck either?"

Why StepForge?

FlowForge was a great start — YAML-defined workflows, SQLite persistence, CLI-driven state machine. But it had gaps that caused real problems in practice:

Gap in FlowForge	StepForge Fix
No graph validation — agents get stuck in broken workflows	stepforge validate catches unreachable nodes, infinite cycles, dead ends
Only one active workflow at a time	Parallel instances — run multiple workflows simultaneously
Silent errors on bad YAML files	Error reporting — every validation issue is surfaced
No node-level retry or timeout	retry and timeout fields per node
No data passing between nodes	Variables — vars set data, collect stores results, {{interpolation}} uses them
No way to undo a wrong branch	stepforge rollback — go back to the previous node
No way to preview a workflow	stepforge dry-run — see the execution path before running
Tests mock the entire DB	Real integration tests planned against SQLite

Install

npm install -g @blutagent/stepforge

Quick Start

1. Write a workflow

name: code-reviewdescription: Review a pull requeststart: read_prnodes:
read_pr:
task: Read PR #{{pr_number}} and understand the changesvars:
pr_number: "42"collect: pr_summarynext: analyzeanalyze:
task: Analyze the changes. Previous: {{pr_summary}}executor: subagentretry: 2timeout: 120branches:
- condition: clean code, no issuesnext: approve
- condition: issues foundnext: commentapprove:
task: Approve the PR with a positive reviewterminal: truecomment:
task: Leave constructive review commentsterminal: true

2. Validate it first

stepforge validate workflows/code-review.yaml
stepforge dry-run workflows/code-review.yaml

3. Run it

stepforge start workflows/code-review.yaml
stepforge status # see current task
stepforge next # advance
stepforge rollback # oops, went wrong way — go back

CLI Commands

Command	Description
stepforge define <yaml>	Register or update a workflow
stepforge validate <yaml>	NEW — validate without registering
stepforge dry-run <yaml>	NEW — preview execution path
stepforge start <workflow>	Start new instance (name or .yaml path)
stepforge status	Show current node, task, branches, variables
stepforge next [--branch N]	Complete current node and advance
stepforge rollback	NEW — go back to previous node
stepforge log	View execution history
stepforge list	List all defined workflows
stepforge active	List active instances (supports parallel)
stepforge reset	Reset current instance to start
stepforge run <workflow>	Start/resume and output next action as JSON
stepforge advance --result "..."	Advance with result, output next action as JSON
stepforge remove [workflow]	NEW — remove a workflow definition

YAML Node Fields

Field	Type	Default	Description
task	string	required	What to do at this node
executor	inline | subagent	inline	How to execute
next	string	—	Single next node
branches	[{condition, next}]	—	Conditional paths
terminal	boolean	false	End of workflow
retry	number	0	Retries on failure
timeout	number	0 (none)	Timeout in seconds
vars	{key: value}	{}	Variables to set on entry
collect	string	—	Store result in this variable

Variable Interpolation

Variables set via vars or collect are interpolated into task strings:

nodes:
init:
task: Set up {{project_name}}vars:
project_name: my-appcollect: outputnext: buildbuild:
task: Build {{project_name}} with output: {{output}}terminal: true

License

MIT