π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
ruflo-workflows
Workflow automation across two complementary surfaces:
- MCP
workflow_*tools β declarative, persisted workflow definitions with a full state-machine lifecycle (create β run β pause β complete/cancel). Best for long-lived, resumable, human-gated pipelines. - Native Claude Code
WorkflowJS β imperative orchestration scripts (.claude/workflows/*.js) that fan subagents out deterministically viaagent/parallel/pipeline/phase. Best for comprehensive fan-out: review, audit, migration, research.
Neither subsumes the other β see Choosing a surface.
Install
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-workflows@ruflo
Features
- MCP workflow definitions: multi-step processes with conditions, parallel steps, and templates
- Lifecycle management: execute, pause, resume, cancel running workflows
- Approval gates: manual pause points for human review
- Native orchestration: author
.claude/workflows/*.jsfan-out/pipeline scripts and run them with theWorkflowtool
Commands
/workflow-- List MCP workflows + templates and native.claude/workflows/*.jsscripts
Skills
workflow-create-- Author MCP workflow templates or native.claude/workflows/*.jsorchestration scriptsworkflow-run-- Execute/manage MCP workflows or invoke + resume native workflows
User-invoked skills (ADR-507)
These skills carry disable-model-invocation: true: Claude does not pick them on its own, and they cost nothing in the per-turn skill listing. Type them to run them. The GAIA submission flow publishes to an external leaderboard; the comparison is a report.
| Skill | Run it with |
|---|---|
| gaia-architecture-comparison | /ruflo-workflows:gaia-architecture-comparison |
| gaia-submission | /ruflo-workflows:gaia-submission |
Compatibility
- CLI: pinned to
@claude-flow/cliv3.6 major+minor. - Verification:
bash plugins/ruflo-workflows/scripts/smoke.shis the contract.
MCP surface (10 tools)
All defined at v3/@claude-flow/cli/src/mcp-tools/workflow-tools.ts:
| Tool | Purpose |
|---|---|
workflow_create |
Create a new workflow definition |
workflow_run |
Run a workflow with inputs |
workflow_execute |
Execute a one-shot workflow without persistence |
workflow_status |
Inspect a running workflow |
workflow_list |
List workflows |
workflow_pause |
Pause a running workflow |
workflow_resume |
Resume a paused workflow |
workflow_cancel |
Cancel a workflow |
workflow_delete |
Delete a workflow definition |
workflow_template |
Manage workflow templates |
Lifecycle state machine
created ββrunβββ running ββpauseβββ paused ββresumeβββ running
β β
β βββcancelβββ cancelled
β
βββcompleteβββ completed
βββcancelβββββ cancelled
| State | Allowed transitions |
|---|---|
created |
running (via workflow_run), cancelled (via workflow_cancel) |
running |
paused (via workflow_pause), completed (auto), cancelled (via workflow_cancel) |
paused |
running (via workflow_resume), cancelled (via workflow_cancel) |
completed |
terminal |
cancelled |
terminal |
workflow_execute is the stateless path β fire-and-forget, no persisted state machine.
Native Workflow Orchestration (Claude Code Workflow tool)
The native surface runs a JavaScript orchestration script that fans subagents out deterministically. Scripts live in .claude/workflows/*.js and each begins with a pure-literal export const meta block β the meta.name makes it an invocable named workflow.
export const meta = {
name: 'plugin-contract-audit',
description: 'Run every plugin smoke contract, diagnose failures, report',
phases: [{ title: 'Sweep' }, { title: 'Diagnose' }, { title: 'Report' }],
}
// body runs inside an async wrapper β top-level await + return are legal
const sweep = await agent('run all plugins/*/scripts/smoke.sh ...', { schema: SWEEP_SCHEMA })
const failures = (sweep?.results || []).filter((r) => r.failed > 0)
const diagnoses = await parallel(failures.map((f) => () =>
agent(`diagnose ${f.plugin}`, { schema: DIAGNOSIS_SCHEMA })))
return { audited: sweep.results.length, failures, diagnoses }
The four-hook API
| Hook | Purpose |
|---|---|
agent(prompt, opts) |
Spawn one subagent; with opts.schema returns validated structured output |
parallel(thunks) |
Run thunks concurrently with a barrier (await all) |
pipeline(items, ...stages) |
Run each item through all stages independently β no barrier |
phase(title) / log(msg) |
Progress grouping and narration |
meta MUST be a pure literal (no variables, calls, or interpolation). Use parallel only when you genuinely need every result together; otherwise prefer pipeline.
Invocation
Workflow({ name: 'plugin-contract-audit' }) // run a named .claude/workflows/*.js
Workflow({ scriptPath: '.claude/workflows/foo.js' }) // run a script by path
Workflow({ name: 'plugin-contract-audit', args: 'ruflo-agentdb' }) // pass args (the script's `args` global)
Workflow({ scriptPath, resumeFromRunId: 'wf_β¦' }) // resume β unchanged agent() calls return cached
The repo ships a reference workflow at .claude/workflows/plugin-contract-audit.js and a worked example at .claude/workflows/intelligence-system-hardening.js.
Choosing a surface
| If you need⦠| Use |
|---|---|
| A persisted definition that pauses for human approval and resumes across sessions | MCP workflow_* |
A stateful lifecycle (created β running β paused β completed/cancelled) the engine schedules |
MCP workflow_* |
| Deterministic fan-out of many subagents (review N dimensions, audit N plugins, migrate N files) | Native Workflow JS |
| Structured, schema-validated results aggregated in code | Native Workflow JS |
| A one-shot stateless run | MCP workflow_execute or native Workflow |
Namespace coordination
This plugin owns the workflows-state AgentDB namespace (kebab-case, follows the convention from ruflo-agentdb ADR-0001 Β§"Namespace convention"). Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.
workflows-state indexes workflow definitions, current state, run history, and template metadata. Accessed via memory_* (namespace-routed).
Verification
bash plugins/ruflo-workflows/scripts/smoke.sh
# Expected: "15 passed, 0 failed"
Architecture Decisions
ADR-0001β ruflo-workflows plugin contract (10-tool MCP surface, lifecycle state machine, smoke as contract)ADR-0002β native Claude Code Workflow orchestration (.claude/workflows/*.jsfan-out) alongside the MCP surface
Related Plugins
ruflo-agentdbβ namespace convention ownerruflo-loop-workersβ sibling automation surface (loops are recurring; workflows are stateful pipelines)ruflo-sparcβ SPARC phase transitions can be modeled as workflows
As a mod
This plugin also loads as a function-hook mod (ADR-445 pattern, hooks/hooks.json β register.ts). No network, no process spawn, no model call.
- Guard (default on, tighten-only). It refuses a workflow definition, run or
gaia*/workflow*memory record that holds a secret, and aworkflow_deletethat names no single workflow id (empty,*,all). The refusal never repeats the secret. - Status file.
.claude-flow/wf-mod/status.json({version: 1, updatedMs, guard, checked, blocked, seen}), written at session start and when a counter changes. /wf-modanswers locally:status,scan <text>,lifecycle. (The plugin's own commands are prompt commands, which a hook cannot answer, so the mod has its own name.)- Option.
guard(on|off, defaulton) in the plugin'suserConfig.
Test it: claude plugin validate plugins/ruflo-workflows, claude plugin test plugins/ruflo-workflows, bash plugins/ruflo-workflows/scripts/smoke.sh.
Optional cloud execution
For Anthropic hosted dynamic workflows, use the existing ruflo-agent
managed_agent_* adapter. Its opt-in configuration and safety contract are
documented here. This is a third
execution surface alongside persisted MCP workflows and local Claude Code JS
workflows. It does not change workflow_run scheduling or turn a native
workflow script into a Managed Agents workflow program.
/wf-mod managed now discovers the installed cloud capability tool from the
current registry. Missing tools and failed discovery are reported separately.
Use /managed-workflow from ruflo-agent to execute bounded remote work. These
local commands do not establish provider access or grant execution permission.