plugins/ruflo-workflows/README.md
Workflow automation across two complementary surfaces:
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.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.
/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-workflows@ruflo
.claude/workflows/*.js fan-out/pipeline scripts and run them with the Workflow tool/workflow -- List MCP workflows + templates and native .claude/workflows/*.js scriptsworkflow-create -- Author MCP workflow templates or native .claude/workflows/*.js orchestration scriptsworkflow-run -- Execute/manage MCP workflows or invoke + resume native workflows@claude-flow/cli v3.6 major+minor.bash plugins/ruflo-workflows/scripts/smoke.sh is the contract.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 |
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.
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 }
| 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.
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.
| 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 |
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).
bash plugins/ruflo-workflows/scripts/smoke.sh
# Expected: "15 passed, 0 failed"
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/*.js fan-out) alongside the MCP surfaceruflo-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