Skillget

flowforge

agent
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • exec() — Shell command execution in src/db.ts
  • process.env — Environment variable access in src/index.ts
  • fs module — File system access in src/index.ts
Permissions Pass
  • Permissions — No dangerous permissions requested
Purpose
This tool is an enforced workflow engine for AI agents that uses a YAML-driven state machine to ensure processes follow predefined steps without skipping ahead.

Security Assessment
The overall risk is Medium. The primary concern is a critical failure flagged in the code: it explicitly executes shell commands (`src/db.ts`). While no dangerous permissions are requested and there are no hardcoded secrets, the tool reads environment variables and accesses the file system (`src/index.ts`). The inclusion of shell execution means that if an attacker can manipulate a workflow YAML file or an agent's prompt, there is a potential risk of arbitrary command injection.

Quality Assessment
The project is actively maintained, with its most recent push occurring today. It uses the highly permissive MIT license and includes clear documentation to help developers get started quickly. However, the tool suffers from extremely low community visibility, currently boasting only 5 GitHub stars. Because of this small footprint, the codebase has likely not undergone widespread peer review or rigorous security auditing by the open-source community.

Verdict
Use with caution due to the presence of shell command execution alongside low community oversight.
SUMMARY

Enforced workflow engine — state machine + gates that block progression until conditions are met

README.md

FlowForge

Enforced workflow engine for AI agents — YAML-defined, CLI-driven state machine that prevents agents from skipping steps.

Install

npm install -g @kagura-agent/flowforge

Quick Start

1. Create a workflow YAML

name: my-workflow
description: Example workflow
start: plan

nodes:
  plan:
    task: Plan the implementation
    next: execute

  execute:
    task: Execute the plan
    next: review

  review:
    task: Review the results
    terminal: true

Save this as workflows/my-workflow.yaml (FlowForge auto-discovers workflows from the workflows/ directory).

2. Run the workflow

# Workflows are auto-loaded from workflows/ directory
flowforge list

# Start an instance
flowforge start my-workflow

# Check current status
flowforge status

# Complete current node and advance
flowforge next

# View execution history
flowforge log

Workflow Auto-Loading

FlowForge automatically discovers and loads workflows from:

  1. ./workflows/ in your current directory
  2. ~/.flowforge/workflows/ in your home directory

Simply drop .yaml or .yml files into these directories and they're immediately available. No need to manually run flowforge define.

YAML Format Reference

Node Types

Linear node (moves to single next node):

nodes:
  step1:
    task: Do something
    next: step2

Branching node (multiple possible paths):

nodes:
  check:
    task: Evaluate condition
    branches:
      - condition: success
        next: continue
      - condition: failure
        next: retry

Terminal node (end of workflow):

nodes:
  done:
    task: Finalize and report
    terminal: true

Node Fields

  • task (required): Natural language description of what to do at this node
  • next (optional): Name of next node for linear flow
  • branches (optional): Array of condition-based paths for branching
  • terminal (optional): Set to true to mark as end node

CLI Commands

Command Description
flowforge define <yaml> Register or update a workflow
flowforge start <workflow> Start new workflow instance
flowforge status Show current node, task, and branches
flowforge next [--branch N] Complete current node and advance
flowforge log View execution history
flowforge list List all defined workflows
flowforge active List active workflow instances
flowforge reset Reset current instance to start
flowforge run <workflow> Start (or resume) workflow and output next action as JSON
flowforge advance Advance workflow with result and output next action as JSON

Example Workflow

name: code-contribution
description: Generic open source contribution workflow
start: study

nodes:
  study:
    task: |
      Read project structure, contribution guidelines, and identify
      the issue or feature to work on
    next: implement

  implement:
    task: Write code changes according to project patterns
    next: test

  test:
    task: Run tests and verify implementation works
    branches:
      - condition: tests pass
        next: submit
      - condition: tests fail
        next: implement

  submit:
    task: Create pull request with clear description
    next: verify

  verify:
    task: Monitor PR feedback and address review comments
    terminal: true

Save as contribution.yaml, then:

flowforge define contribution.yaml
flowforge start code-contribution

How It Works

FlowForge enforces step-by-step execution:

  1. Define workflows as YAML (nodes + transitions)
  2. Start an instance of a workflow
  3. Execute the task at current node
  4. Advance with flowforge next (or --branch N for branching nodes)
  5. Repeat until terminal node

State persists in SQLite database at ~/.flowforge/. Workflows can be paused and resumed across sessions.

Use Cases

  • AI agent workflows: Prevent agents from skipping critical steps (e.g., always run tests before submitting)
  • Structured processes: Codify learning, contribution, or review workflows
  • State machines: Implement branching logic with conditions and history tracking

License

MIT

Star History

Star History Chart

Reviews (0)

No results found