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-observability): v0.2.0 β€” namespace-routing fix + adopt plugin contract (ADR-0001)

Reuven1c3093d46487
diff --git a/plugins/ruflo-observability/.claude-plugin/plugin.json b/plugins/ruflo-observability/.claude-plugin/plugin.json
index c7b4ccece7..55ec5390fb 100644
--- a/plugins/ruflo-observability/.claude-plugin/plugin.json
+++ b/plugins/ruflo-observability/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-observability",
"description": "Structured logging, distributed tracing, and metrics β€” correlate agent swarm activity with application telemetry",
- "version": "0.1.0",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -14,6 +14,9 @@
"logging",
"tracing",
"metrics",
- "telemetry"
+ "telemetry",
+ "mcp",
+ "distributed-tracing",
+ "anomaly-detection"
]
}
diff --git a/plugins/ruflo-observability/README.md b/plugins/ruflo-observability/README.md
index eda64a3166..8ec68d0380 100644
--- a/plugins/ruflo-observability/README.md
+++ b/plugins/ruflo-observability/README.md
@@ -62,8 +62,33 @@ observe correlate <agent-id> # Correlate all telemetry for an agent
JSON structured logs with `timestamp`, `level`, `message`, `correlationId`, `agentId`, `taskId`, `spanId`, `traceId`, `duration_ms`, and `metadata`.
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-observability/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns the `observability` AgentDB namespace (base-name exception per [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md), same precedent as `federation` and `migrations`). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`observability` is accessed via `memory_*` tools (namespace-routed). Stores spans, metric snapshots, and log entries.
+
+> **Routing note:** Earlier versions of these skills used `agentdb_hierarchical-recall` with namespace argument β€” that tool family routes by tier and ignores namespace strings. ADR-0001 fixed the skills to use `memory_*` for namespaced reads and documented the dual pattern-store path for metric snapshots.
+
+## Verification
+
+```bash
+bash plugins/ruflo-observability/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-observability plugin contract (namespace-routing fix, smoke as contract)](./docs/adrs/0001-observability-contract.md)
+
## Related Plugins
+- `ruflo-agentdb` β€” namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
- `ruflo-cost-tracker` -- Token usage metrics feed into cost attribution
- `ruflo-iot-cognitum` -- Reuses Z-score anomaly detection for telemetry patterns
- `ruflo-market-data` -- Data feed health and ingestion latency monitoring
diff --git a/plugins/ruflo-observability/docs/adrs/0001-observability-contract.md b/plugins/ruflo-observability/docs/adrs/0001-observability-contract.md
new file mode 100644
index 0000000000..c41c177c63
--- /dev/null
+++ b/plugins/ruflo-observability/docs/adrs/0001-observability-contract.md
@@ -0,0 +1,43 @@
+---
+id: ADR-0001
+title: ruflo-observability plugin contract β€” pinning, namespace-routing fix, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, observability, tracing, metrics, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-observability` (v0.1.0) β€” structured logging, distributed tracing, metrics with anomaly detection. 1 agent + 2 skills + 1 command.
+
+Same namespace-routing bug class as cost-tracker / market-data / migrations: both skills called `agentdb_hierarchical-recall` with namespace `observability` argument, but `agentdb_hierarchical-*` routes by tier (`working|episodic|semantic`) and ignores namespace strings.
+
+## Decision
+
+1. **Functional fix:** switch namespaced reads from `agentdb_hierarchical-recall` to `memory_search` / `memory_list` (namespace-routed) in both skills. Document the dual pattern-store path in observe-metrics.
+2. Add this ADR (Proposed).
+3. README augment: Compatibility (pin v3.6); Namespace coordination (claims `observability`); Verification + Architecture Decisions sections.
+4. Bump `0.1.0 β†’ 0.2.0`. Keywords add `mcp`, `distributed-tracing`, `anomaly-detection`.
+5. `scripts/smoke.sh` β€” 10 structural checks: version + keywords; both skills + agent + command; skills use `memory_*` not `hierarchical-*` with namespace; v3.6 pin; namespace coordination; ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** real bugs fixed (silent ignored-namespace reads). Plugin joins the cadence.
+
+**Negative:** none β€” anyone scripting against the broken tool calls was already silently failing.
+
+## Verification
+
+```bash
+bash plugins/ruflo-observability/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md` β€” same bug class
+- `plugins/ruflo-market-data/docs/adrs/0001-market-data-contract.md` β€” same bug class
+- `plugins/ruflo-migrations/docs/adrs/0001-migrations-contract.md` β€” same bug class
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
diff --git a/plugins/ruflo-observability/scripts/smoke.sh b/plugins/ruflo-observability/scripts/smoke.sh
new file mode 100755
index 0000000000..aa5e11b984
--- /dev/null
+++ b/plugins/ruflo-observability/scripts/smoke.sh
@@ -0,0 +1,86 @@
+#!/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 distributed-tracing anomaly-detection; 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 observe-trace observe-metrics; 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/observability-engineer.md" ]] || miss="$miss missing-agent"
+[[ -f "$ROOT/commands/observe.md" ]] || miss="$miss missing-command"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. observe-trace uses memory_* for namespaced reads"
+F="$ROOT/skills/observe-trace/SKILL.md"
+miss=""
+grep -q "memory_search\|memory_list" "$F" || miss="$miss no-memory-load"
+grep -qE 'agentdb_hierarchical-recall.+observability|observability.+agentdb_hierarchical-recall' "$F" && miss="$miss still-uses-hierarchical-recall"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. observe-metrics uses memory_* for namespaced reads"
+F="$ROOT/skills/observe-metrics/SKILL.md"
+miss=""
+grep -q "memory_search\|memory_list" "$F" || miss="$miss no-memory-load"
+grep -qE 'agentdb_hierarchical-recall.+observability|observability.+agentdb_hierarchical-recall' "$F" && miss="$miss still-uses-hierarchical-recall"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "5. observe-metrics documents dual pattern-store path"
+F="$ROOT/skills/observe-metrics/SKILL.md"
+if grep -q "ReasoningBank" "$F" \
+ && grep -q "memory_store --namespace observability" "$F"; then
+ ok
+else
+ bad "missing dual-path documentation"
+fi
+
+step "6. /observe command covers 5 subcommands"
+F="$ROOT/commands/observe.md"
+miss=""
+for sub in trace metrics logs dashboard correlate; 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-observability-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-observability/skills/observe-metrics/SKILL.md b/plugins/ruflo-observability/skills/observe-metrics/SKILL.md
index 63177187fa..91d1c91de1 100644
--- a/plugins/ruflo-observability/skills/observe-metrics/SKILL.md
+++ b/plugins/ruflo-observability/skills/observe-metrics/SKILL.md
@@ -2,7 +2,7 @@
name: observe-metrics
description: Aggregate and display system metrics with anomaly detection for a time period
argument-hint: "[--period 1h]"
-allowed-tools: mcp__claude-flow__agentdb_hierarchical-recall mcp__claude-flow__agentdb_pattern-search mcp__claude-flow__agentdb_pattern-store mcp__claude-flow__agentdb_semantic-route Bash
+allowed-tools: mcp__claude-flow__memory_search mcp__claude-flow__memory_list mcp__claude-flow__memory_store mcp__claude-flow__agentdb_pattern-search mcp__claude-flow__agentdb_pattern-store mcp__claude-flow__agentdb_semantic-route Bash
---
# Observe Metrics
@@ -15,14 +15,16 @@ When you need a snapshot of system health -- task completion rates, error rates,
## Steps
-1. **Retrieve metrics** -- call `mcp__claude-flow__agentdb_hierarchical-recall` to fetch metric records from the `observability` namespace for the specified period (default: 1 hour)
+1. **Retrieve metrics** -- call `mcp__claude-flow__memory_search --namespace observability` (or `memory_list`) to fetch metric records for the specified period (default: 1 hour). The `memory_*` tool family routes by namespace; `agentdb_hierarchical-*` does NOT, so use `memory_*` here.
2. **Aggregate** -- compute:
- Counters: sum totals (tasks_completed, errors, token_usage)
- Gauges: current values (active_agents, memory_usage_bytes)
- Histograms: p50, p95, p99 (task_duration_ms, span_duration_ms)
-3. **Compute baselines** -- search for historical patterns via `mcp__claude-flow__agentdb_pattern-search` to establish baseline values for each metric
+3. **Compute baselines** -- call `mcp__claude-flow__agentdb_pattern-search` (ReasoningBank-routed; **don't** pass a `namespace` argument β€” pattern-* tools ignore it) to establish baseline values for each metric.
4. **Flag anomalies** -- mark metrics deviating >2 standard deviations from baseline with direction (above/below) and severity
-5. **Store patterns** -- call `mcp__claude-flow__agentdb_pattern-store` to record current metric snapshot for future baseline comparison
+5. **Store patterns** -- two paths (per ruflo-cost-tracker ADR-0001 dual-path pattern):
+ - **Pattern store (typed, recommended)**: `mcp__claude-flow__agentdb_pattern-store` with `type: 'metric-snapshot'`. No namespace arg.
+ - **Plain store (namespace-routable)**: `mcp__claude-flow__memory_store --namespace observability` for the snapshot tied to a timestamp.
6. **Report** -- display: metric name, current value, baseline, deviation, trend (up/down/stable), anomaly flag; overall health score (green/yellow/red)
## CLI alternative
diff --git a/plugins/ruflo-observability/skills/observe-trace/SKILL.md b/plugins/ruflo-observability/skills/observe-trace/SKILL.md
index f4aa40f20e..1f2413aa6a 100644
--- a/plugins/ruflo-observability/skills/observe-trace/SKILL.md
+++ b/plugins/ruflo-observability/skills/observe-trace/SKILL.md
@@ -2,7 +2,7 @@
name: observe-trace
description: Trace agent execution by collecting spans and building a trace tree for a task
argument-hint: "<task-id>"
-allowed-tools: mcp__claude-flow__agentdb_hierarchical-recall mcp__claude-flow__agentdb_semantic-route mcp__claude-flow__agentdb_context-synthesize mcp__claude-flow__agentdb_pattern-search Bash
+allowed-tools: mcp__claude-flow__memory_search mcp__claude-flow__memory_list mcp__claude-flow__agentdb_semantic-route mcp__claude-flow__agentdb_context-synthesize mcp__claude-flow__agentdb_pattern-search Bash
---
# Observe Trace
@@ -15,7 +15,7 @@ When you need to understand how a task was executed across agents -- which spans
## Steps
-1. **Collect spans** -- call `mcp__claude-flow__agentdb_hierarchical-recall` to retrieve all spans matching the `<task-id>` from the `observability` namespace
+1. **Collect spans** -- call `mcp__claude-flow__memory_search --namespace observability` (or `memory_list`) to retrieve all spans matching the `<task-id>`. The `memory_*` tool family routes by namespace; `agentdb_hierarchical-*` does NOT (it routes by tier `working|episodic|semantic`), so use `memory_*` here. See [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../../../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md).
2. **Build trace tree** -- organize spans into a parent-child hierarchy using `parentSpanId` references, with the root span at the top
3. **Calculate timing** -- for each span, compute duration (endTime - startTime), and identify the critical path (longest chain of sequential spans)
4. **Identify bottlenecks** -- flag spans where duration exceeds the p95 for that operation type, or where gaps between spans suggest idle time