π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ruflo-workflows): v0.2.0 β adopt plugin contract + 10-tool MCP surface + lifecycle state machine (ADR-0001)
Reuvend9db4e766369
diff --git a/plugins/ruflo-workflows/.claude-plugin/plugin.json b/plugins/ruflo-workflows/.claude-plugin/plugin.jsonindex 36a10ab679..cc11b11149 100644--- a/plugins/ruflo-workflows/.claude-plugin/plugin.json+++ b/plugins/ruflo-workflows/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-workflows",- "description": "Visual workflow automation with templates, orchestration, and lifecycle management",- "version": "0.1.0",+ "description": "Workflow automation with templates, orchestration, and lifecycle management β wraps 10 workflow_* MCP tools (create/run/execute/status/list/pause/resume/cancel/delete/template) with full state-machine lifecycle (created β running β paused β completed/cancelled)",+ "version": "0.2.0","author": {"name": "ruvnet","url": "https://github.com/ruvnet"@@ -13,6 +13,10 @@"workflows","automation","orchestration",- "templates"+ "templates",+ "mcp",+ "workflow-templates",+ "pause-resume",+ "lifecycle"]}diff --git a/plugins/ruflo-workflows/README.md b/plugins/ruflo-workflows/README.mdindex 5551a6918a..5278be8442 100644--- a/plugins/ruflo-workflows/README.md+++ b/plugins/ruflo-workflows/README.md@@ -1,6 +1,6 @@# ruflo-workflows-Visual workflow automation with templates, orchestration, and lifecycle management.+Workflow automation with templates, orchestration, and full state-machine lifecycle management.## Install@@ -24,3 +24,69 @@ Visual workflow automation with templates, orchestration, and lifecycle manageme- `workflow-create` -- Create reusable workflow templates- `workflow-run` -- Execute and manage running workflows++## 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.++## Namespace coordination++This plugin owns the `workflows-state` AgentDB namespace (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). 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+bash plugins/ruflo-workflows/scripts/smoke.sh+# Expected: "11 passed, 0 failed"+```++## Architecture Decisions++- [`ADR-0001` β ruflo-workflows plugin contract (10-tool MCP surface, lifecycle state machine, smoke as contract)](./docs/adrs/0001-workflows-contract.md)++## 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 workflowsdiff --git a/plugins/ruflo-workflows/docs/adrs/0001-workflows-contract.md b/plugins/ruflo-workflows/docs/adrs/0001-workflows-contract.mdnew file mode 100644index 0000000000..54cf15851e--- /dev/null+++ b/plugins/ruflo-workflows/docs/adrs/0001-workflows-contract.md@@ -0,0 +1,57 @@+---+id: ADR-0001+title: ruflo-workflows plugin contract β pinning, namespace coordination, 10-tool MCP surface, smoke as contract+status: Proposed+date: 2026-05-04+authors:+ - reviewer (Claude Code)+tags: [plugin, workflows, automation, orchestration, namespace, smoke-test]+---++## Context++`ruflo-workflows` (v0.1.0) β workflow automation with templates, orchestration, and lifecycle management. 1 agent (`workflow-specialist`), 2 skills (`workflow-create`, `workflow-run`), 1 command (`/workflow`).++Wraps **10 `workflow_*` MCP tools** at `v3/@claude-flow/cli/src/mcp-tools/workflow-tools.ts:84, 196, 264, 450, 511, 558, 597, 648, 701, 739`:++| 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 |++This plugin is the canonical wrapper for the workflow-* MCP family.++## Decision++1. Add this ADR (Proposed).+2. README augment: Compatibility (pin v3.6); 10-tool MCP surface table; lifecycle state machine (created β running β paused β completed/cancelled); Namespace coordination (claims `workflows-state`); Verification + Architecture Decisions sections.+3. Bump `0.1.0 β 0.2.0`. Keywords add `mcp`, `workflow-templates`, `pause-resume`, `lifecycle`.+4. `scripts/smoke.sh` β 11 structural checks: version + keywords; both skills + agent + command with valid frontmatter; all 10 `workflow_*` tools referenced; lifecycle state machine documented; v3.6 pin; namespace coordination; ADR Proposed; no wildcard tools.++## Consequences++**Positive:** plugin joins the cadence. The 10-tool surface + lifecycle state machine are now contractually documented. **This ADR completes the plugin-contract retrofit across the entire ruflo plugin family** β all 33 plugins now have ADR-0001 + smoke + namespace coordination.++**Negative:** none material.++## Verification++```bash+bash plugins/ruflo-workflows/scripts/smoke.sh+# Expected: "11 passed, 0 failed"+```++## Related++- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β namespace convention+- `plugins/ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.md` β sibling automation surface (loops vs workflows)+- `plugins/ruflo-sparc/docs/adrs/0001-sparc-contract.md` β SPARC orchestration uses workflows for phase transitions+- `v3/@claude-flow/cli/src/mcp-tools/workflow-tools.ts` β 10 `workflow_*` toolsdiff --git a/plugins/ruflo-workflows/scripts/smoke.sh b/plugins/ruflo-workflows/scripts/smoke.shnew file mode 100755index 0000000000..1e2f01bd00--- /dev/null+++ b/plugins/ruflo-workflows/scripts/smoke.sh@@ -0,0 +1,88 @@+#!/usr/bin/env bash+set -u+ROOT="$(cd "$(dirname "$0")/.." && pwd)"+PASS=0+FAIL=0+step() { printf "β %s ... " "$1"; }+ok() { printf "PASS\n"; PASS=$((PASS+1)); }+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }++step "1. plugin.json declares 0.2.0 with new keywords"+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)+if [[ "$v" != "0.2.0" ]]; then bad "expected 0.2.0, got '$v'"; else+ miss=""+ for k in mcp workflow-templates pause-resume lifecycle; do+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"+ done+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"+fi++step "2. both skills + agent + command present with valid frontmatter"+miss=""+for s in workflow-create workflow-run; do+ f="$ROOT/skills/$s/SKILL.md"+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }+ for k in 'name:' 'description:'; do+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"+ done+done+[[ -f "$ROOT/agents/workflow-specialist.md" ]] || miss="$miss missing-agent"+[[ -f "$ROOT/commands/workflow.md" ]] || miss="$miss missing-command"+[[ -z "$miss" ]] && ok || bad "$miss"++step "3. all 10 workflow_* MCP tools referenced"+miss=""+for t in workflow_create workflow_run workflow_execute workflow_status workflow_list workflow_pause workflow_resume workflow_cancel workflow_delete workflow_template; do+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"+done+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"++step "4. README pins @claude-flow/cli to v3.6"+grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \+ && ok || bad "v3.6 pin missing"++step "5. README defers to ruflo-agentdb namespace convention"+grep -q "ruflo-agentdb" "$ROOT/README.md" \+ && grep -q "Namespace convention" "$ROOT/README.md" \+ && ok || bad "namespace coordination block incomplete"++step "6. workflows-state namespace claimed"+grep -q "workflows-state" "$ROOT/README.md" \+ && ok || bad "workflows-state namespace not claimed"++step "7. lifecycle state machine documented (5 states)"+F="$ROOT/README.md"+miss=""+for state in created running paused completed cancelled; do+ grep -q "$state" "$F" || miss="$miss $state"+done+[[ -z "$miss" ]] && ok || bad "missing states:$miss"++step "8. lifecycle transitions documented (run/pause/resume/cancel)"+F="$ROOT/README.md"+miss=""+for trans in 'workflow_run' 'workflow_pause' 'workflow_resume' 'workflow_cancel'; do+ grep -q "$trans" "$F" || miss="$miss $trans"+done+[[ -z "$miss" ]] && ok || bad "missing transitions:$miss"++step "9. workflow_execute documented as stateless path"+F="$ROOT/README.md"+grep -q "workflow_execute" "$F" \+ && grep -qE "stateless|one-shot|fire-and-forget" "$F" \+ && ok || bad "stateless path not documented"++step "10. ADR-0001 exists with status Proposed"+ADR="$ROOT/docs/adrs/0001-workflows-contract.md"+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \+ && ok || bad "ADR missing or status != Proposed"++step "11. no wildcard tool grants in skills"+bad_skills=""+for f in "$ROOT"/skills/*/SKILL.md; do+ grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"+done+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"++printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"+[[ $FAIL -eq 0 ]] || exit 1