π 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-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.jsonindex 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.mdindex 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-historydiff --git a/plugins/ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.md b/plugins/ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.mdnew file mode 100644index 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-*` toolsdiff --git a/plugins/ruflo-loop-workers/scripts/smoke.sh b/plugins/ruflo-loop-workers/scripts/smoke.shnew file mode 100755index 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