Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

9.1 KB
Raw Blame

ruflo-workflows

Workflow automation across two complementary surfaces:

  1. 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.
  2. Native Claude Code Workflow JS β€” imperative orchestration scripts (.claude/workflows/*.js) that fan subagents out deterministically via agent / 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/*.js fan-out/pipeline scripts and run them with the Workflow tool

Commands

  • /workflow -- List MCP workflows + templates and native .claude/workflows/*.js scripts

Skills

  • workflow-create -- Author MCP workflow templates or native .claude/workflows/*.js orchestration scripts
  • workflow-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/cli v3.6 major+minor.
  • Verification: bash plugins/ruflo-workflows/scripts/smoke.sh is 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

Related Plugins

  • ruflo-agentdb β€” namespace convention owner
  • ruflo-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 a workflow_delete that 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-mod answers 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, default on) in the plugin's userConfig.

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.