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

feat(ruflo-loop-workers): v0.2.0 β€” adopt plugin contract + 12-worker trigger map (ADR-0001)

Reuvene24481f51e92
diff --git a/plugins/ruflo-loop-workers/.claude-plugin/plugin.json b/plugins/ruflo-loop-workers/.claude-plugin/plugin.json
index 0a5cd60373..3ed3c0e200 100644
--- a/plugins/ruflo-loop-workers/.claude-plugin/plugin.json
+++ b/plugins/ruflo-loop-workers/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-loop-workers",
- "description": "Cache-aware /loop workers and CronCreate background automation",
- "version": "0.1.0",
+ "description": "Cache-aware /loop workers and CronCreate background automation β€” wraps 5 hooks_worker-* MCP tools (list/dispatch/status/detect/cancel) and exposes 12 background worker triggers (ultralearn, optimize, consolidate, predict, audit, map, preload, deepdive, document, refactor, benchmark, testgaps)",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -13,6 +13,10 @@
"loop",
"cron",
"workers",
- "automation"
+ "automation",
+ "mcp",
+ "background-workers",
+ "cache-aware",
+ "schedule-wakeup"
]
}
diff --git a/plugins/ruflo-loop-workers/README.md b/plugins/ruflo-loop-workers/README.md
index 77867df88b..fdab490b46 100644
--- a/plugins/ruflo-loop-workers/README.md
+++ b/plugins/ruflo-loop-workers/README.md
@@ -1,6 +1,6 @@
# ruflo-loop-workers
-Cache-aware /loop workers and CronCreate background automation.
+Cache-aware /loop workers and CronCreate background automation. Substrate plugin for every recurring task in the ruflo family.
## Install
@@ -20,3 +20,76 @@ Cache-aware /loop workers and CronCreate background automation.
## Requires
- `ruflo-core` plugin (provides MCP server)
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-loop-workers/scripts/smoke.sh` is the contract.
+
+## MCP surface (5 tools)
+
+All defined at `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts`:
+
+| Tool | Purpose |
+|------|---------|
+| `hooks_worker-list` | List available workers and their triggers |
+| `hooks_worker-dispatch` | Dispatch a worker run with `--trigger <worker-name>` and optional `--scope` |
+| `hooks_worker-status` | Inspect a running worker |
+| `hooks_worker-detect` | Detect which workers should fire based on context |
+| `hooks_worker-cancel` | Cancel a running worker |
+
+## 12 worker triggers β†’ consumer plugins
+
+| Trigger | Consumer plugin | Purpose |
+|---------|-----------------|---------|
+| `ultralearn` | `ruflo-intelligence` | Bootstrap learning corpus from a deep codebase scan |
+| `optimize` | `ruflo-cost-tracker`, `ruflo-intelligence` | Performance + cost optimization recommendations |
+| `consolidate` | `ruflo-intelligence`, `ruflo-agentdb` | EWC++ memory consolidation |
+| `predict` | `ruflo-intelligence` | Predictive routing for upcoming tasks |
+| `audit` | `ruflo-security-audit`, `ruflo-aidefence` | Security + compliance audit pass |
+| `map` | `ruflo-knowledge-graph` | Build/refresh entity-relation knowledge graph |
+| `preload` | `ruflo-core`, `ruflo-rag-memory` | Warm caches before high-frequency operations |
+| `deepdive` | `ruflo-goals` (deep-research) | Multi-source investigation pass |
+| `document` | `ruflo-docs` | Generate API docs + drift detection |
+| `refactor` | `ruflo-jujutsu` | Diff-aware refactor recommendations |
+| `benchmark` | `ruflo-cost-tracker`, `ruflo-iot-cognitum` | Perf benchmarks |
+| `testgaps` | `ruflo-testgen` | Coverage gap detection + test generation |
+
+Invocation pattern (CLI + MCP):
+
+```bash
+# CLI
+npx @claude-flow/cli@latest hooks worker dispatch --trigger document --scope api
+
+# MCP
+mcp tool call hooks_worker-dispatch --json -- '{"trigger": "document", "scope": "api"}'
+```
+
+## Cache-aware /loop integration
+
+This plugin pairs with [ruflo-autopilot ADR-0001](../ruflo-autopilot/docs/adrs/0001-autopilot-contract.md) which **owns the 270s cache-aware ScheduleWakeup heartbeat contract**. Recommended fallback heartbeat is **270 seconds** β€” under the 5-minute prompt-cache TTL so the next wake-up reads conversation context cached. Going past 300s pays a cache-miss; rounding to 5 minutes is the worst-of-both case.
+
+For event-driven loops, arm a `Monitor` and let the 270s wake be the safety net.
+
+## Namespace coordination
+
+This plugin owns the `worker-history` 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.
+
+`worker-history` records dispatch events, durations, success/failure verdicts. Accessed via `memory_*` tools (namespace-routed).
+
+## Verification
+
+```bash
+bash plugins/ruflo-loop-workers/scripts/smoke.sh
+# Expected: "12 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-loop-workers plugin contract (12-worker trigger map, autopilot 270s cross-reference, smoke as contract)](./docs/adrs/0001-loop-workers-contract.md)
+
+## Related Plugins
+
+- `ruflo-autopilot` β€” owns the 270s cache-aware /loop heartbeat contract
+- `ruflo-docs`, `ruflo-security-audit`, `ruflo-testgen`, `ruflo-knowledge-graph`, etc. β€” worker-trigger consumers per the table above
+- `ruflo-agentdb` β€” namespace convention owner; backing store for worker-history
diff --git a/plugins/ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.md b/plugins/ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.md
new file mode 100644
index 0000000000..9e344a0e59
--- /dev/null
+++ b/plugins/ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.md
@@ -0,0 +1,54 @@
+---
+id: ADR-0001
+title: ruflo-loop-workers plugin contract β€” pinning, namespace coordination, 12-worker trigger contract, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, loop-workers, cron, schedule-wakeup, cache-aware, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-loop-workers` (v0.1.0) β€” cache-aware `/loop` workers + `CronCreate` background automation. Wraps **5 `hooks_worker-*` MCP tools** at `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts:3489, 3538, 3656, 3714, 3923` (`worker-list`, `worker-dispatch`, `worker-status`, `worker-detect`, `worker-cancel`) and exposes 12 background worker triggers per CLAUDE.md.
+
+Surface: 1 agent (`loop-worker-coordinator`), 2 skills (`loop-worker`, `cron-schedule`), 2 commands (`/ruflo-loop`, `/ruflo-schedule`).
+
+The 12 worker triggers (named in README): `ultralearn`, `optimize`, `consolidate`, `predict`, `audit`, `map`, `preload`, `deepdive`, `document`, `refactor`, `benchmark`, `testgaps`.
+
+Standard contract gaps + a notable cross-link missing:
+
+1. No plugin-level ADR.
+2. No smoke test.
+3. No Compatibility section.
+4. **No cross-reference to ruflo-autopilot's 270s cache-aware /loop heartbeat** β€” `ruflo-autopilot` ADR-0001 owns that contract and this plugin is the substrate that runs it.
+5. **No worker-trigger β†’ consumer-plugin map** β€” e.g., `document` trigger is consumed by `ruflo-docs`, `audit` by `ruflo-security-audit`, `testgaps` by `ruflo-testgen`. Documenting the map closes the discovery loop.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6); Cache-aware /loop integration block (cross-references ruflo-autopilot ADR-0001's 270s heartbeat); 5-tool MCP surface table (`worker-list`, `worker-dispatch`, `worker-status`, `worker-detect`, `worker-cancel`); 12-worker trigger map with consumer-plugin attribution; Namespace coordination (claims `worker-history`); Verification + Architecture Decisions sections.
+3. Bump `0.1.0 β†’ 0.2.0`. Keywords add `mcp`, `background-workers`, `cache-aware`, `schedule-wakeup`.
+4. `scripts/smoke.sh` β€” 12 structural checks: version + keywords; both skills + agent + 2 commands present with valid frontmatter; all 5 `hooks_worker-*` tools referenced; all 12 worker triggers documented; v3.6 pin; namespace coordination; 270s cache-aware note + ruflo-autopilot cross-reference; worker-trigger β†’ consumer-plugin attribution table; ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:**
+- 12-worker trigger map becomes contractually documented. Consumer plugins (`ruflo-docs`, `ruflo-security-audit`, `ruflo-testgen`, etc.) can verify their trigger names against a single canonical source.
+- 270s cache-aware /loop heartbeat is now anchored to ruflo-autopilot's contract.
+
+**Negative:** none material.
+
+## Verification
+
+```bash
+bash plugins/ruflo-loop-workers/scripts/smoke.sh
+# Expected: "12 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md` β€” 270s cache-aware /loop heartbeat owner
+- `plugins/ruflo-docs/docs/adrs/0001-docs-contract.md` β€” consumer of `document` trigger
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
+- `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts` β€” 5 `hooks_worker-*` tools
diff --git a/plugins/ruflo-loop-workers/scripts/smoke.sh b/plugins/ruflo-loop-workers/scripts/smoke.sh
new file mode 100755
index 0000000000..8610b3c63e
--- /dev/null
+++ b/plugins/ruflo-loop-workers/scripts/smoke.sh
@@ -0,0 +1,95 @@
+#!/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 background-workers cache-aware schedule-wakeup; 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 + 2 commands present"
+miss=""
+for s in loop-worker cron-schedule; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:' 'allowed-tools:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+[[ -f "$ROOT/agents/loop-worker-coordinator.md" ]] || miss="$miss missing-agent"
+[[ -f "$ROOT/commands/ruflo-loop.md" ]] || miss="$miss missing-loop-cmd"
+[[ -f "$ROOT/commands/ruflo-schedule.md" ]] || miss="$miss missing-schedule-cmd"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. all 5 hooks_worker-* MCP tools referenced"
+miss=""
+for t in hooks_worker-list hooks_worker-dispatch hooks_worker-status hooks_worker-detect hooks_worker-cancel; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+step "4. all 12 worker triggers documented"
+F="$ROOT/README.md"
+miss=""
+for trigger in ultralearn optimize consolidate predict audit map preload deepdive document refactor benchmark testgaps; do
+ grep -q "$trigger" "$F" || miss="$miss $trigger"
+done
+[[ -z "$miss" ]] && ok || bad "missing triggers:$miss"
+
+step "5. 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 "6. 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 "7. worker-history namespace claimed"
+grep -q "worker-history" "$ROOT/README.md" \
+ && ok || bad "worker-history namespace not claimed"
+
+step "8. 270s cache-aware ScheduleWakeup documented"
+F="$ROOT/README.md"
+grep -qE "270 ?s|270 second" "$F" \
+ && grep -qE "cache|prompt cache" "$F" \
+ && ok || bad "270s cache-aware note missing"
+
+step "9. ruflo-autopilot 270s heartbeat contract cross-reference"
+F="$ROOT/README.md"
+grep -q "ruflo-autopilot" "$F" \
+ && grep -qE "270s|270 ?second" "$F" \
+ && ok || bad "autopilot heartbeat cross-reference missing"
+
+step "10. worker-trigger β†’ consumer-plugin attribution table present"
+F="$ROOT/README.md"
+miss=""
+grep -q "Consumer plugin" "$F" || miss="$miss header"
+grep -q "ruflo-docs" "$F" || miss="$miss docs-attribution"
+grep -q "ruflo-testgen" "$F" || miss="$miss testgen-attribution"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "11. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-loop-workers-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "12. 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