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-neural-trader): adopt plugin contract β€” already-compliant namespaces + 4-namespace claim (ADR-0001)

Reuvene148c56119e5
diff --git a/plugins/ruflo-neural-trader/.claude-plugin/plugin.json b/plugins/ruflo-neural-trader/.claude-plugin/plugin.json
index fd6774f92b..27c9ed590e 100644
--- a/plugins/ruflo-neural-trader/.claude-plugin/plugin.json
+++ b/plugins/ruflo-neural-trader/.claude-plugin/plugin.json
@@ -18,6 +18,9 @@
"lstm",
"napi",
"mcp",
- "swarm"
+ "swarm",
+ "neural-trader-runtime",
+ "walk-forward",
+ "monte-carlo"
]
}
diff --git a/plugins/ruflo-neural-trader/README.md b/plugins/ruflo-neural-trader/README.md
index f52fe8d4e4..f10089e4e2 100644
--- a/plugins/ruflo-neural-trader/README.md
+++ b/plugins/ruflo-neural-trader/README.md
@@ -151,9 +151,42 @@ neural-trader uses Rust/NAPI bindings for zero-overhead performance:
- **WASM/SIMD** acceleration available
- **52,000+ inserts/sec** for market data
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Runtime:** `npx neural-trader` (Rust/NAPI bindings β€” 112+ MCP tools).
+- **Verification:** `bash plugins/ruflo-neural-trader/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns four AgentDB namespaces (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)):
+
+| Namespace | Purpose |
+|-----------|---------|
+| `trading-strategies` | Strategy definitions (loaded by `trader-backtest`, `trader-signal`) |
+| `trading-backtests` | Backtest results indexed by strategy + timestamp |
+| `trading-risk` | Risk metrics per portfolio |
+| `trading-analysis` | Regime detection + market analysis history |
+
+Note: the namespace prefix is `trading-` (the actual intent) rather than `neural-trader-` (the plugin stem). This is a deliberate ergonomic choice β€” `trading` is the load-bearing concern downstream consumers reason about. Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+All access via `memory_*` (namespace-routed). No `agentdb_hierarchical-*` or `agentdb_pattern-store` with namespace arguments β€” the plugin uses the correct routing throughout.
+
+## Verification
+
+```bash
+bash plugins/ruflo-neural-trader/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-neural-trader plugin contract (already-compliant namespaces, 4-namespace claim, smoke as contract)](./docs/adrs/0001-neural-trader-contract.md)
+
## Related Plugins
-- `ruflo-market-data` β€” OHLCV data ingestion and candlestick pattern detection
+- `ruflo-agentdb` β€” namespace convention owner; backing store
+- `ruflo-market-data` β€” OHLCV data ingestion and candlestick pattern detection (feeds `trading-strategies`)
- `ruflo-ruvector` β€” HNSW indexing for strategy pattern similarity search
- `ruflo-cost-tracker` β€” PnL tracking and cost attribution
- `ruflo-observability` β€” Strategy performance dashboards
diff --git a/plugins/ruflo-neural-trader/docs/adrs/0001-neural-trader-contract.md b/plugins/ruflo-neural-trader/docs/adrs/0001-neural-trader-contract.md
new file mode 100644
index 0000000000..a4a0835f1c
--- /dev/null
+++ b/plugins/ruflo-neural-trader/docs/adrs/0001-neural-trader-contract.md
@@ -0,0 +1,58 @@
+---
+id: ADR-0001
+title: ruflo-neural-trader plugin contract β€” pinning, namespace coordination (already-compliant), 4-namespace claim, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, neural-trader, trading, backtesting, risk, namespace, smoke-test]
+---
+
+## Context
+
+`ruflo-neural-trader` (v0.2.0) β€” neural trading via `npx neural-trader` (Rust/NAPI bindings, 112+ MCP tools, 8-19x faster than Python). 4 agents + 6 skills + 1 command.
+
+### Namespace audit β€” already compliant
+
+Four namespaces in use, all kebab-case `<plugin-stem>-<intent>` compliant per [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md):
+
+- `trading-backtests` β€” backtest results
+- `trading-risk` β€” risk metrics per portfolio
+- `trading-analysis` β€” regime + analysis history
+- `trading-strategies` β€” strategy definitions
+
+Note: namespace prefix is `trading-` (not `neural-trader-`) for ergonomic tightness β€” the trading concern is the actual intent. This is consistent with the convention's `<plugin-stem>-<intent>` form interpreted broadly (the plugin's primary concern *is* trading).
+
+All access via `memory_*` (namespace-routed) β€” no bugs found.
+
+### Other gaps
+
+1. No plugin-level ADR.
+2. No smoke test.
+3. No Compatibility section.
+
+## Decision
+
+1. Add this ADR (Proposed).
+2. README augment: Compatibility (pin v3.6 + neural-trader runtime); Namespace coordination block claiming the four namespaces; Verification + Architecture Decisions sections.
+3. Plugin metadata stays at `0.2.0` (already at the cadence). Keywords add `neural-trader-runtime`, `walk-forward`, `monte-carlo`.
+4. `scripts/smoke.sh` β€” 11 structural checks: version + new keywords; all 6 skills + 4 agents + 1 command with valid frontmatter; v3.6 pin; namespace coordination; 4 namespace claims; backtesting features documented (walk-forward, Monte Carlo, parameter optimization); ADR Proposed; no wildcard tools.
+
+## Consequences
+
+**Positive:** plugin joins the cadence. The namespace-prefix design choice (`trading-` not `neural-trader-`) is now contractually documented as a deliberate ergonomic call.
+
+**Negative:** none material.
+
+## Verification
+
+```bash
+bash plugins/ruflo-neural-trader/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
+- `plugins/ruflo-market-data/docs/adrs/0001-market-data-contract.md` β€” feeds OHLCV data into trader
+- `plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md` β€” PnL + cost attribution downstream
diff --git a/plugins/ruflo-neural-trader/scripts/smoke.sh b/plugins/ruflo-neural-trader/scripts/smoke.sh
new file mode 100755
index 0000000000..3b685f31e6
--- /dev/null
+++ b/plugins/ruflo-neural-trader/scripts/smoke.sh
@@ -0,0 +1,83 @@
+#!/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 neural-trader-runtime walk-forward monte-carlo; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all 6 skills present with valid frontmatter"
+miss=""
+for s in trader-backtest trader-portfolio trader-regime trader-risk trader-signal trader-train; 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. all 4 agents present"
+miss=""
+for a in backtest-engineer market-analyst risk-analyst trading-strategist; do
+ [[ -f "$ROOT/agents/$a.md" ]] || miss="$miss missing-$a"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. command present"
+[[ -f "$ROOT/commands/trader.md" ]] && ok || bad "trader command missing"
+
+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 pins neural-trader runtime"
+grep -qE "npx neural-trader|Rust/NAPI" "$ROOT/README.md" \
+ && ok || bad "neural-trader runtime pin missing"
+
+step "7. 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 "8. all 4 namespaces claimed (trading-strategies/-backtests/-risk/-analysis)"
+F="$ROOT/README.md"
+miss=""
+for ns in trading-strategies trading-backtests trading-risk trading-analysis; do
+ grep -q "$ns" "$F" || miss="$miss $ns"
+done
+[[ -z "$miss" ]] && ok || bad "missing namespace claims:$miss"
+
+step "9. backtesting features documented (walk-forward, Monte Carlo, parameter optimization)"
+F="$ROOT/README.md"
+miss=""
+grep -q "Walk-forward\|walk-forward" "$F" || miss="$miss walk-forward"
+grep -q "Monte Carlo\|monte-carlo" "$F" || miss="$miss monte-carlo"
+grep -q "Parameter optimization\|parameter optimization\|param-optimize" "$F" || miss="$miss param-opt"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "10. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-neural-trader-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "11. 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