feat(ruflo-workflows): v0.2.0 — adopt plugin contract + 10-tool MCP surface + lifecycle state machine (ADR-0001)

This is the FINAL plugin in the ruflo family. ADR-0001 here completes
the plugin-contract retrofit across all 33 plugins.

Surface: 10 workflow_* MCP tools (create/run/execute/status/list/pause/
resume/cancel/delete/template) backed by full state machine
(created → running ↔ paused → completed/cancelled).

- ADR-0001 (Proposed) at docs/adrs/0001-workflows-contract.md
- README adds Compatibility (pin v3.6), 10-tool MCP surface table,
  Lifecycle state machine diagram + transition table (5 states +
  4 transitions), workflow_execute documented as stateless path,
  Namespace coordination (claims workflows-state; defers to
  ruflo-agentdb ADR-0001), Verification + Architecture Decisions
- plugin.json bumps 0.1.0 → 0.2.0; description names the 10 tools +
  state machine; keywords add mcp, workflow-templates, pause-resume,
  lifecycle
- scripts/smoke.sh — 11 structural checks: version + keywords, both
  skills + agent + command present, all 10 workflow_* tools referenced,
  v3.6 pin, namespace coordination, workflows-state claimed, 5
  lifecycle states + 4 transitions documented, workflow_execute
  stateless path, ADR Proposed, no wildcard tools

Verification: bash plugins/ruflo-workflows/scripts/smoke.sh → 11/11

Co-Authored-By: RuFlo <ruv@ruv.net>

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"
   ]
 }

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 workflows

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_*` tools

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