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

fix(ruflo-knowledge-graph): correct embeddings_embed β†’ embeddings_generate + adopt plugin contract (ADR-0001)

Reuven0aeb255b8aed
diff --git a/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json b/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json
index a66bd44acf..b0267bae22 100644
--- a/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json
+++ b/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json
@@ -13,6 +13,9 @@
"knowledge-graph",
"entities",
"relations",
- "pathfinder"
+ "pathfinder",
+ "mcp",
+ "pathfinder-traversal",
+ "entity-extraction"
]
}
diff --git a/plugins/ruflo-knowledge-graph/README.md b/plugins/ruflo-knowledge-graph/README.md
index 46bb5267cd..5776167e69 100644
--- a/plugins/ruflo-knowledge-graph/README.md
+++ b/plugins/ruflo-knowledge-graph/README.md
@@ -46,6 +46,17 @@ kg search <query> # Semantic search across the graph
| type | `User`, `OrderStatus` |
| config | `database`, `redis`, `jwt` |
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-knowledge-graph/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns the `kg-graph` 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.
+
+Entity nodes are stored via `agentdb_hierarchical-store`; relation edges via `agentdb_causal-edge`; semantic indexing via `embeddings_generate` (NOT `embeddings_embed` β€” that tool name doesn't exist; ADR-0001 fixes prior references).
+
## Pathfinder Algorithm
1. **Seed** -- start from the target entity node
@@ -66,9 +77,20 @@ The yet-pending **`graphAdapter`** controller will give this plugin a first-clas
Inspect runtime status via the `agentdb_controllers` or `agentdb_health` MCP tools.
+## Verification
+
+```bash
+bash plugins/ruflo-knowledge-graph/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-knowledge-graph plugin contract (embeddings_generate fix, namespace coordination, smoke as contract)](./docs/adrs/0001-knowledge-graph-contract.md)
+
## Related Plugins
-- `ruflo-agentdb` -- The G7 controllers above ship via this plugin's runtime; install both for full graph + traversal coverage
+- `ruflo-agentdb` -- The G7 controllers above ship via this plugin's runtime; install both for full graph + traversal coverage; namespace convention owner
- `ruflo-ruvector` -- HNSW indexing for fast semantic search across graph nodes
- `ruflo-adr` -- ADR dependency graphs share the same causal edge model
diff --git a/plugins/ruflo-knowledge-graph/agents/graph-navigator.md b/plugins/ruflo-knowledge-graph/agents/graph-navigator.md
index 3100016767..7e282e4cb5 100644
--- a/plugins/ruflo-knowledge-graph/agents/graph-navigator.md
+++ b/plugins/ruflo-knowledge-graph/agents/graph-navigator.md
@@ -53,7 +53,7 @@ The pathfinder traversal algorithm finds relevant subgraphs:
- `mcp__claude-flow__agentdb_pattern-store` -- store discovered graph patterns
- `mcp__claude-flow__agentdb_pattern-search` -- search for similar graph structures
- `mcp__claude-flow__agentdb_context-synthesize` -- synthesize context from multiple graph nodes
-- `mcp__claude-flow__embeddings_embed` -- generate embeddings for entity descriptions
+- `mcp__claude-flow__embeddings_generate` -- generate embeddings for entity descriptions
### Neural Learning
diff --git a/plugins/ruflo-knowledge-graph/docs/adrs/0001-knowledge-graph-contract.md b/plugins/ruflo-knowledge-graph/docs/adrs/0001-knowledge-graph-contract.md
new file mode 100644
index 0000000000..52ab3fd6b7
--- /dev/null
+++ b/plugins/ruflo-knowledge-graph/docs/adrs/0001-knowledge-graph-contract.md
@@ -0,0 +1,59 @@
+---
+id: ADR-0001
+title: ruflo-knowledge-graph plugin contract β€” pinning, namespace coordination, embeddings_generate fix, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, knowledge-graph, entities, relations, pathfinder, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-knowledge-graph` (v0.2.0) β€” entity extraction + relation mapping + pathfinder graph traversal. Surface: 1 agent + 2 skills + 1 command (5 subcommands). Backed by `agentdb_hierarchical-*` (entity tree), `agentdb_causal-edge` (relation tracking), `agentdb_semantic-route` (query routing), and `embeddings_*` (entity description embeddings).
+
+### The drift this ADR fixes
+
+Two files reference `mcp__claude-flow__embeddings_embed`, but the real tool is `embeddings_generate` (`v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts:260`). There is no `embeddings_embed` MCP tool.
+
+- `skills/kg-extract/SKILL.md:5` β€” `allowed-tools` line includes the wrong tool name
+- `agents/graph-navigator.md:56` β€” agent's tool list also wrong
+
+This is a real bug: invocations would fail with "tool not found". Fixing in this ADR pass.
+
+### Other gaps
+
+1. No plugin-level ADR.
+2. No smoke test.
+3. No Compatibility section.
+4. No namespace coordination cross-reference (uses graph storage but no explicit namespace claim).
+
+## Decision
+
+1. **Functional fix:** rename `embeddings_embed` β†’ `embeddings_generate` in both files.
+2. Add this ADR (Proposed).
+3. README augment: Compatibility (pin v3.6); Namespace coordination (claims `kg-graph`); Verification + Architecture Decisions sections.
+4. Plugin metadata stays at `0.2.0` (already at the cadence). Patch bump justified by the functional fix (rename of a referenced tool name) but cadence keeps it at minor for consistency. Keywords add `mcp`, `pathfinder-traversal`, `entity-extraction`.
+5. `scripts/smoke.sh` β€” 10 structural checks: version + keywords; both skills + agent + command with valid frontmatter; no reference to `embeddings_embed` anywhere (regression check on the bug fix); `embeddings_generate` referenced; 5 subcommands documented; v3.6 pin; namespace coordination; ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:**
+- Real bug fixed: kg-extract skill no longer references a non-existent MCP tool.
+- Plugin joins the cadence.
+
+**Negative:**
+- Anyone scripting against the old (broken) tool name was already silently failing. Net zero on real impact.
+
+## Verification
+
+```bash
+bash plugins/ruflo-knowledge-graph/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
+- `plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md` β€” sibling pattern of fixing real MCP-tool drift in skills
+- `v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts:260` β€” `embeddings_generate` (the real tool name)
diff --git a/plugins/ruflo-knowledge-graph/scripts/smoke.sh b/plugins/ruflo-knowledge-graph/scripts/smoke.sh
new file mode 100755
index 0000000000..512540958b
--- /dev/null
+++ b/plugins/ruflo-knowledge-graph/scripts/smoke.sh
@@ -0,0 +1,87 @@
+#!/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 pathfinder-traversal entity-extraction; 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 present with valid frontmatter"
+miss=""
+for s in kg-extract kg-traverse; 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
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. agent + command present"
+[[ -f "$ROOT/agents/graph-navigator.md" ]] && [[ -f "$ROOT/commands/kg.md" ]] \
+ && ok || bad "agent or command missing"
+
+step "4. embeddings_embed (non-existent tool) is NOT referenced as a tool call (excluding ADR + README call-outs which document the fix)"
+# ADR file legitimately mentions the broken tool as the thing being removed.
+# The README's namespace-coord note also calls it out as "NOT embeddings_embed".
+# Filter both β€” invariant is on actual tool-call-site references in skills/agent/command.
+hits=$(grep -rE 'mcp__claude-flow__embeddings_embed' "$ROOT" \
+ --include='*.md' --include='*.json' \
+ --exclude-dir='adrs' 2>/dev/null \
+ | grep -v 'NOT embeddings_embed\|embeddings_embed.*does not exist\|fixes prior references' \
+ || true)
+if [[ -n "$hits" ]]; then
+ bad "embeddings_embed reference still present at a tool-call site"
+ echo "$hits" | sed 's/^/ /'
+else
+ ok
+fi
+
+step "5. embeddings_generate (real tool) referenced in skill + agent"
+miss=""
+grep -q "embeddings_generate" "$ROOT/skills/kg-extract/SKILL.md" || miss="$miss skill"
+grep -q "embeddings_generate" "$ROOT/agents/graph-navigator.md" || miss="$miss agent"
+[[ -z "$miss" ]] && ok || bad "missing in:$miss"
+
+step "6. /kg command covers 5 subcommands"
+F="$ROOT/commands/kg.md"
+miss=""
+for sub in 'extract' 'traverse' 'relations' 'visualize' 'search'; do
+ grep -q "$sub" "$F" || miss="$miss $sub"
+done
+[[ -z "$miss" ]] && ok || bad "missing subcommands:$miss"
+
+step "7. 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 "8. 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 "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-knowledge-graph-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
diff --git a/plugins/ruflo-knowledge-graph/skills/kg-extract/SKILL.md b/plugins/ruflo-knowledge-graph/skills/kg-extract/SKILL.md
index 024edd2f67..adba8b3dce 100644
--- a/plugins/ruflo-knowledge-graph/skills/kg-extract/SKILL.md
+++ b/plugins/ruflo-knowledge-graph/skills/kg-extract/SKILL.md
@@ -2,7 +2,7 @@
name: kg-extract
description: Extract entities and relations from source files to build a knowledge graph
argument-hint: "<path>"
-allowed-tools: Read Glob Grep mcp__claude-flow__agentdb_hierarchical-store mcp__claude-flow__agentdb_causal-edge mcp__claude-flow__agentdb_semantic-route mcp__claude-flow__agentdb_pattern-store mcp__claude-flow__embeddings_embed Bash
+allowed-tools: Read Glob Grep mcp__claude-flow__agentdb_hierarchical-store mcp__claude-flow__agentdb_causal-edge mcp__claude-flow__agentdb_semantic-route mcp__claude-flow__agentdb_pattern-store mcp__claude-flow__embeddings_generate Bash
---
# KG Extract