How do I install the Soulflow skill?

Run npx skillmds@latest add 0xtommythomas-dev/soulflow in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Soulflow skill do?

SoulFlow v2.0 - Multi-Agent Workflow Orchestrator It is listed under AI & ML on SkillMD.

Is Soulflow safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Soulflow?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Soulflow free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Soulflow?

0xtommythomas-dev (@0xtommythomas-dev) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Soulflow by 0xtommythomas-dev — Agent Skill

Name: Soulflow
Author: 0xtommythomas-dev

SoulFlow v2.0 - Multi-Agent Workflow Orchestrator

Production-grade workflow orchestration with intelligent multi-agent coordination

Overview

SoulFlow v2.0 is a complete rewrite designed for enterprise-quality workflow automation. It orchestrates specialized agents (planner, developer, verifier, tester, reviewer) to execute complex multi-step workflows with automatic verification, retry logic, and robust state management.

What It Does

Orchestrates Multi-Agent Workflows: Coordinate specialized agents to complete complex tasks
YAML-Based Workflows: Define workflows in human-readable YAML format
Automatic Verification: Agents verify each other's work (no self-verification)
Retry & Escalation: Configurable retry logic and automatic escalation on failure
State Persistence: SQLite database tracks all workflow execution
Git Integration: Optional auto-commit after each step with branch-per-workflow

Use Cases

🔒 Security Audits

Run comprehensive security reviews with multiple verification stages:

Vulnerability scanning
Manual code review
Penetration testing
Remediation planning

🐛 Bug Fixes

Systematic bug fixing with proper testing:

Root cause analysis
Solution design and review
Implementation with verification
Regression testing

✨ Feature Development

End-to-end feature development:

Requirements and architecture
Backend/frontend implementation
Comprehensive testing
Documentation and review

Installation

# Clone/download SoulFlow
cd soulflow-v2

# Link CLI globally
npm link

# Verify installation
soulflow help

Quick Start

# Run a workflow
soulflow run examples/security-audit.yaml

# With git integration
soulflow run examples/feature-dev.yaml --use-git

# Check progress
soulflow list running

# Get detailed status
soulflow status <run-id>

# View agent status
soulflow agents

Workflow Format

name: My Workflow
description: What this does

steps:
  - name: Planning
    agent: planner
    task: Break down the requirements
    retry: 3
    verify_with: reviewer
  
  - name: Implementation
    agent: developer
    task: Write the code
    retry: 3
    escalate_to: reviewer
    verify_with: verifier
  
  - name: Testing
    agent: tester
    task: Run tests
    verify_with: verifier

Agent Types

Agent	Role	When to Use
planner	Strategic planning & decomposition	Requirements, architecture, planning
developer	Implementation & coding	Building features, writing code
verifier	Quality assurance	Code review, validation
tester	Testing & edge cases	Running tests, QA
reviewer	Final approval	Senior review, sign-off

Key Features

✅ Verification Gates

Steps can require verification by a different agent:

- name: Code Changes
  agent: developer
  task: Implement feature
  verify_with: verifier  # Verifier checks the work

🔄 Automatic Retry

Configure retries per step:

- name: Complex Task
  agent: developer
  task: Difficult implementation
  retry: 5  # Try up to 5 times

⬆️ Escalation

Escalate failed steps to more experienced agents:

- name: Challenging Work
  agent: developer
  task: Complex algorithm
  escalate_to: reviewer  # If retries fail, escalate

💾 State Persistence

All workflow state is persisted in SQLite:

Workflow runs and status
Step execution history
Agent assignments
Verification results

🔧 Git Integration

Enable with --use-git:

Auto-commit after each step
Branch per workflow run
Clean change tracking
Easy rollback

CLI Commands

`soulflow run <workflow.yaml> [--use-git]`

Execute a workflow with optional git integration.

`soulflow status <run-id>`

Show detailed progress of a workflow run.

`soulflow list [status]`

List all runs, optionally filtered by status (pending/running/completed/failed).

`soulflow agents`

Show agent statistics (total/busy/idle per agent type).

`soulflow cancel <run-id>`

Cancel a running workflow.

Architecture

SoulFlow v2.0 is built on a clean, modular architecture:

Orchestrator: Main execution engine
State Manager: SQLite-based persistence
Workflow Engine: YAML parsing and validation
Agent System: Multi-agent coordination
Git Integration: Optional VCS operations

All components use zero external dependencies - only Node.js 22 built-ins.

Example Workflows Included

security-audit.yaml: Comprehensive security review
bug-fix.yaml: Systematic bug fixing workflow
feature-dev.yaml: End-to-end feature development

Integration with OpenClaw

SoulFlow detects and integrates with OpenClaw automatically:

Uses OpenClaw agents when available
Falls back to standalone mode otherwise
Agents can coordinate using OpenClaw messaging
Works in both interactive and automated contexts

Configuration

State and agent workspaces are stored in .soulflow/:

.soulflow/
├── state.db              # SQLite database
└── agents/               # Agent workspaces
    ├── planner/
    ├── developer/
    ├── verifier/
    ├── tester/
    └── reviewer/

Advanced Usage

Custom Workflows

Create your own workflows by following the YAML format:

Define workflow name and description
List steps with agent assignments
Add retry/verify/escalate as needed
Run with soulflow run

Monitoring

Check workflow progress in real-time:

# List active workflows
soulflow list running

# Watch a specific run
watch -n 2 "soulflow status <run-id>"

CI/CD Integration

SoulFlow works great in automated pipelines:

# Run workflow and exit with proper code
soulflow run workflow.yaml || exit 1

# Use git integration for clean commits
soulflow run workflow.yaml --use-git

Design Principles

Multi-Agent First: Specialized agents that verify each other
Production Ready: Robust error handling, state persistence
Zero Dependencies: Only Node.js 22 built-ins
Human-Readable: YAML workflows, clear CLI output
Git-Friendly: Optional integration for change tracking
CLI-Only: No dashboard, built for automation

Requirements

Node.js: v22.0.0 or higher
OpenClaw: Optional (enhances agent execution)
Git: Optional (for --use-git flag)

Troubleshooting

"Unknown agent type"

Make sure you're using valid agent types: planner, developer, verifier, tester, reviewer.

"Failed to create/checkout branch"

Check git is initialized: git init and you have a clean working tree.

"Run not found"

Use soulflow list to see all run IDs.

What's New in v2.0

Complete rewrite with:

✅ Multi-agent coordination
✅ Verification gates
✅ Retry and escalation logic
✅ SQLite state management
✅ Git integration
✅ YAML workflows (not JSON)
✅ Zero external dependencies
✅ Production-grade architecture

Contributing

Ideas for enhancements:

Additional agent types (security, docs, ops)
Parallel step execution
Conditional workflow branching
Workflow templates library
Agent learning from past runs

License

MIT License

Links

Tags: workflow, orchestration, multi-agent, automation, ci-cd, yaml, testing, verification

Version: 2.0.0

Soulflow

File contents