mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-09-14 14:01:28 +08:00
Reuven
e24481f51e
5 hooks_worker-* MCP tools (worker-list, worker-dispatch, worker-status, worker-detect, worker-cancel) plus 12 worker triggers were already wired. The contract pieces were missing. Notable: this ADR maps each of the 12 worker triggers to its consumer plugin so downstream plugins (ruflo-docs/ruflo-security-audit/ruflo-testgen /ruflo-knowledge-graph/etc.) can verify their trigger names against a single canonical source. And the 270s cache-aware ScheduleWakeup heartbeat is now anchored to ruflo-autopilot ADR-0001 which owns that contract. - ADR-0001 (Proposed) at docs/adrs/0001-loop-workers-contract.md - README adds Compatibility (pin v3.6), 5-tool MCP surface table, 12-worker → consumer-plugin attribution table, Cache-aware /loop integration block (270s heartbeat, defers to ruflo-autopilot ADR-0001), Namespace coordination (claims worker-history), Verification + Architecture Decisions sections - plugin.json bumps 0.1.0 → 0.2.0; description names the 5 MCP tools + 12 trigger names; keywords add mcp, background-workers, cache-aware, schedule-wakeup - scripts/smoke.sh — 12 structural checks: version + keywords, both skills + agent + 2 commands present, 5 worker MCP tools referenced, 12 trigger names documented, v3.6 pin, namespace coordination, worker-history claimed, 270s cache-aware note, autopilot cross-reference, attribution table, ADR Proposed, no wildcard tools Verification: bash plugins/ruflo-loop-workers/scripts/smoke.sh → 12/12 Co-Authored-By: RuFlo <ruv@ruv.net>
96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# ruflo-loop-workers
|
|
|
|
Cache-aware /loop workers and CronCreate background automation. Substrate plugin for every recurring task in the ruflo family.
|
|
|
|
## Install
|
|
|
|
```
|
|
/plugin marketplace add ruvnet/ruflo
|
|
/plugin install ruflo-loop-workers@ruflo
|
|
```
|
|
|
|
## What's Included
|
|
|
|
- **Loop Workers**: Recurring tasks via `/loop` with ScheduleWakeup (delay <270s for prompt cache hits)
|
|
- **CronCreate**: Background cron jobs for audit, optimization, and monitoring
|
|
- **12 Background Workers**: ultralearn, optimize, consolidate, predict, audit, map, preload, deepdive, document, refactor, benchmark, testgaps
|
|
- **Daemon Management**: Start, stop, status, trigger, and enable workers
|
|
- **ADR-091 Integration**: Native Claude Code capabilities preferred over daemon polling
|
|
|
|
## 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
|