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-ruvllm): v0.2.0 β€” adopt plugin contract + cross-plugin tool ownership table (ADR-0001)

Reuven1ef889cb3a80
diff --git a/plugins/ruflo-ruvllm/.claude-plugin/plugin.json b/plugins/ruflo-ruvllm/.claude-plugin/plugin.json
index ca2d759c8f..ae602b7b1e 100644
--- a/plugins/ruflo-ruvllm/.claude-plugin/plugin.json
+++ b/plugins/ruflo-ruvllm/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-ruvllm",
- "description": "RuVLLM local inference with chat formatting, model configuration, and MicroLoRA fine-tuning",
- "version": "0.1.0",
+ "description": "RuVLLM local inference with chat formatting (Claude/GPT/Gemini/Ollama/Cohere), model configuration, MicroLoRA fine-tuning, and SONA real-time adaptation",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -14,6 +14,9 @@
"llm",
"inference",
"microlora",
- "fine-tuning"
+ "fine-tuning",
+ "mcp",
+ "local-inference",
+ "chat-templates"
]
}
diff --git a/plugins/ruflo-ruvllm/README.md b/plugins/ruflo-ruvllm/README.md
index 33f2f40a8b..ec3a7243bc 100644
--- a/plugins/ruflo-ruvllm/README.md
+++ b/plugins/ruflo-ruvllm/README.md
@@ -1,6 +1,6 @@
# ruflo-ruvllm
-RuVLLM local inference with chat formatting, model configuration, and MicroLoRA fine-tuning.
+RuVLLM local inference with chat formatting, model configuration, MicroLoRA fine-tuning, and SONA real-time adaptation.
## Install
@@ -15,7 +15,7 @@ RuVLLM local inference with chat formatting, model configuration, and MicroLoRA
- **MicroLoRA**: Task-specific fine-tuning with lightweight adapters
- **SONA adaptation**: Real-time neural adaptation (<0.05ms)
- **Chat formatting**: Multi-provider prompt formatting (Claude, GPT, Gemini, Ollama, Cohere)
-- **HNSW routing**: Context retrieval for RAG pipelines
+- **HNSW routing**: Context retrieval for RAG pipelines (≀11 hot patterns; for large-corpus search see `ruflo-agentdb` `embeddings_search`)
## Commands
@@ -25,3 +25,44 @@ RuVLLM local inference with chat formatting, model configuration, and MicroLoRA
- `llm-config` -- Configure models, MicroLoRA, and SONA
- `chat-format` -- Format prompts for different LLM providers
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-ruvllm/scripts/smoke.sh` is the contract.
+
+## Cross-plugin tool ownership
+
+This plugin shares the `ruvllm_*` MCP family with two sibling plugins. Each tool group has a canonical owner; this plugin is the entry point for LLM-config + chat formatting:
+
+| Tool group | Canonical owner | This plugin's role |
+|-----------|-----------------|-------------------|
+| `ruvllm_sona_create`, `ruvllm_sona_adapt` | [ruflo-intelligence ADR-0001](../ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md) (4-step pipeline DISTILL phase) | Surfaces SONA in `llm-config` skill |
+| `ruvllm_microlora_create`, `ruvllm_microlora_adapt` | [ruflo-intelligence ADR-0001](../ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md) (DISTILL + CONSOLIDATE phases via `--consolidate` flag) | Surfaces MicroLoRA in `llm-config` skill |
+| `ruvllm_hnsw_create`, `ruvllm_hnsw_add`, `ruvllm_hnsw_route` | [ruflo-agentdb ADR-0001](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md) (WASM router, ≀11 patterns β€” distinct from large-corpus `embeddings_search`) | References from `chat-format` for context routing |
+
+Source: `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts:142, 169, 192, 222` (SONA + MicroLoRA) and `:57-58` (HNSW WASM router with `~11 patterns` cap).
+
+## Namespace coordination
+
+This plugin owns the `ruvllm-config` 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.
+
+`ruvllm-config` stores model configurations, adapter manifests, and chat-format templates. Accessed via `memory_*` (namespace-routed).
+
+## Verification
+
+```bash
+bash plugins/ruflo-ruvllm/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-ruvllm plugin contract (cross-plugin tool ownership table, namespace coordination, smoke as contract)](./docs/adrs/0001-ruvllm-contract.md)
+
+## Related Plugins
+
+- `ruflo-intelligence` β€” owns SONA + MicroLoRA in the 4-step pipeline
+- `ruflo-agentdb` β€” owns HNSW WASM router; namespace convention owner
+- `ruflo-ruvector` β€” sibling substrate plugin (pinned `[email protected]`)
+- `ruflo-rag-memory` β€” consumes RAG context routing
diff --git a/plugins/ruflo-ruvllm/docs/adrs/0001-ruvllm-contract.md b/plugins/ruflo-ruvllm/docs/adrs/0001-ruvllm-contract.md
new file mode 100644
index 0000000000..661084c234
--- /dev/null
+++ b/plugins/ruflo-ruvllm/docs/adrs/0001-ruvllm-contract.md
@@ -0,0 +1,44 @@
+---
+id: ADR-0001
+title: ruflo-ruvllm plugin contract β€” pinning, namespace coordination, MicroLoRA + SONA cross-references, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, ruvllm, microlora, sona, llm, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-ruvllm` (v0.1.0) β€” local LLM inference + MicroLoRA fine-tuning + chat formatting. 1 agent (`llm-specialist`), 2 skills (`llm-config`, `chat-format`), 1 command (`/ruvllm`).
+
+Wraps `ruvllm_*` MCP family β€” same family that exposes the SONA + MicroLoRA tools `ruflo-intelligence` ADR-0001 already documents (`ruvllm_sona_create`, `ruvllm_sona_adapt`, `ruvllm_microlora_create`, `ruvllm_microlora_adapt` per `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts:142, 169, 192, 222`). The HNSW WASM router (`ruvllm_hnsw_create/_add/_route`) is documented in `ruflo-agentdb` ADR-0001 Β§"Tool inventory".
+
+This plugin is the canonical owner of the LLM-config + chat-format slice of the `ruvllm_*` surface; SONA + MicroLoRA + HNSW each have other canonical homes.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6); Namespace coordination (claims `ruvllm-config`); Cross-reference table β€” SONA tools owned by ruflo-intelligence ADR-0001, MicroLoRA tools shared with ruflo-intelligence (DISTILL/CONSOLIDATE phase), HNSW WASM router owned by ruflo-agentdb ADR-0001; Verification + Architecture Decisions sections.
+3. Bump `0.1.0 β†’ 0.2.0`. Keywords add `mcp`, `local-inference`, `chat-templates`.
+4. `scripts/smoke.sh` β€” 10 structural checks: version + keywords; both skills + agent + command with valid frontmatter; SONA cross-reference (ruflo-intelligence); MicroLoRA cross-reference (ruflo-intelligence DISTILL phase); HNSW cross-reference (ruflo-agentdb); v3.6 pin; namespace coordination; ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** plugin joins the cadence. Cross-plugin shared-tool ownership is now contractually documented (SONA β†’ intelligence, MicroLoRA β†’ intelligence DISTILL, HNSW WASM β†’ agentdb).
+
+**Negative:** none material.
+
+## Verification
+
+```bash
+bash plugins/ruflo-ruvllm/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md` β€” owns SONA + MicroLoRA in the 4-step pipeline
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” owns HNSW WASM router (`ruvllm_hnsw_*`) + namespace convention
+- `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md` β€” sibling substrate plugin
+- `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts` β€” 4 SONA + MicroLoRA tools at lines 142, 169, 192, 222
diff --git a/plugins/ruflo-ruvllm/scripts/smoke.sh b/plugins/ruflo-ruvllm/scripts/smoke.sh
new file mode 100755
index 0000000000..64c0ce844e
--- /dev/null
+++ b/plugins/ruflo-ruvllm/scripts/smoke.sh
@@ -0,0 +1,77 @@
+#!/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 local-inference chat-templates; 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 llm-config chat-format; 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/llm-specialist.md" ]] || miss="$miss missing-agent"
+[[ -f "$ROOT/commands/ruvllm.md" ]] || miss="$miss missing-command"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. 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 "4. 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 "5. ruvllm-config namespace claimed"
+grep -q "ruvllm-config" "$ROOT/README.md" \
+ && ok || bad "ruvllm-config namespace not claimed"
+
+step "6. SONA cross-reference (ruflo-intelligence canonical owner)"
+F="$ROOT/README.md"
+grep -q "ruflo-intelligence" "$F" \
+ && grep -qE "SONA|sona_create|sona_adapt" "$F" \
+ && ok || bad "SONA cross-reference missing"
+
+step "7. MicroLoRA cross-reference (ruflo-intelligence DISTILL phase)"
+F="$ROOT/README.md"
+grep -qE "MicroLoRA|microlora" "$F" \
+ && grep -qE "DISTILL|CONSOLIDATE|--consolidate" "$F" \
+ && ok || bad "MicroLoRA / DISTILL cross-reference missing"
+
+step "8. HNSW WASM router cross-reference (ruflo-agentdb canonical owner)"
+F="$ROOT/README.md"
+grep -qE "ruvllm_hnsw|HNSW WASM router|11 patterns" "$F" \
+ && grep -q "ruflo-agentdb" "$F" \
+ && ok || bad "HNSW router cross-reference missing"
+
+step "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-ruvllm-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "10. 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