mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-11-09 22:13:39 +09:00
rUv
8485302f10
* feat(x-gateway): 0.6.1 — Seraphina bounded by budget, not by an admin token Squashes what is actually running on x.ruv.io so git and production agree. Seraphina was gated alongside the write tools, but it is not like them: it reads the roster, the claims board and recent messages, asks a model, and returns advice. It writes nothing and carries no authority. The gate answered the wrong question — the exposure is model spend, and spend is bounded with a budget, not a password. The practical cost was worse than a wrong abstraction. A browser cannot hold a bearer secret, so a published UI was either locked out or tempted to ship RUFLO_ADMIN_TOKEN to the client — the same token that mints invites and publishes as the gateway identity. The safe-looking option was the catastrophic one. Seraphina now answers with no token, bounded by a shared daily cap and a per-client hourly cap, and anonymous callers cannot select the high or ultra tiers. An admin token lifts both. Every write tool keeps its gate; verified live that claims_issue, federation_invite_mint, federation_publish, federation_admit and channel_publish all still refuse an anonymous caller. Not included, deliberately: a tool to relay member-signed events through the gateway. It was built, tested against the live relay, and removed. buzz-relay refuses any EVENT whose pubkey differs from the NIP-42 authenticated connection, so a gateway cannot publish on another identity's behalf — and it does not need to. Members already publish as themselves through the wss://x.ruv.io proxy, verified end to end. Shipping a tool that always fails would be worse than none. Co-Authored-By: RuFlo <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_013u4pmL9ZUAXb6usVQgNo67 * feat(x-gateway): serve onboarding guidance, and deliberately not key generation The registry said "generate a Nostr keypair" and stopped, and it never named the two identities in play. That gap was not theoretical: a capable agent inspected the surface, found only gateway-signed publishing, and concluded ordinary members could not publish from a dashboard at all. They can. It just was not written anywhere they could reach. federation_onboarding and ruv://federation/onboarding now answer it, open, no token. The guide leads with the distinction that causes the confusion — your key signs for you, the gateway's key signs for the service, and the gated tools are gated precisely because they speak as the service. It carries the five steps, the four things never to do, and the three traps this service has actually taught us: sign the NIP-42 relay tag with the canonical URL even when proxied, the relay binds publishing to the authenticated connection, and the channel tag is `c` not `h`. It does NOT generate keys, and that is the point rather than an omission. A service that mints your keypair and returns the secret has seen your secret, and becomes custodian of every identity it "helped" — the same custody mistake as putting an admin token in a browser, inverted. The guide ships the code so the caller runs it locally and the key never crosses the wire. One test note worth keeping: the first version of the safety assertion regex- matched for "send your secret" and failed on the guide's own "Never send your secret key" line. It is now structural — no field may be named for secret material — because a string search cannot tell an instruction from its negation. Verified live on 0.7.0 (ruflo-x-gateway-00015-qj7) with an anonymous call. 20/20. Co-Authored-By: RuFlo <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_013u4pmL9ZUAXb6usVQgNo67 * fix(ci): register the gateway's credential and budget knobs, and skip test/ like tests/ The ADR-125 precedence audit failed the gateway PR, and it was right to look — but for two reasons that are both about the audit, not the code. RUFLO_ADMIN_TOKEN was not registered as an escape hatch even though its sibling RUFLO_X_ADMIN_TOKEN is, with the same reasoning: a secret must never be a CLI flag, where it lands in shell history and process listings. The gateway is a long-running service with no typed command surface at all, so there is no invocation to attach a flag to. Same for the two Seraphina budget knobs added in #3275. The other half was a naming gap. SKIP_DIRS already excludes `tests` and `__tests__` because the audit is about production precedence, not test setup — but the flagged lines were in `plugins/ruflo-x-gateway/test/`, singular, which was not in the set. Two `process.env.X = 'test-admin-token'` assignments inside a test fixture were reported as undeclared production reads. Verified: the audit now exits clean on this branch. Co-Authored-By: RuFlo <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_013u4pmL9ZUAXb6usVQgNo67
Ruflo Plugins
32 Claude Code plugins for agent-powered development workflows. Load with --plugin-dir.
Quick Start
# Load specific plugins
claude --plugin-dir plugins/ruflo-core --plugin-dir plugins/ruflo-swarm
# Load all plugins
claude $(ls -d plugins/ruflo-*/ | sed 's|^|--plugin-dir |' | tr '\n' ' ')
Plugin Catalog
Core & Coordination
| Plugin | Description |
|---|---|
| ruflo-core | MCP server, status, doctor, coder/researcher/reviewer agents |
| ruflo-swarm | Swarm topologies (hierarchical, mesh), Monitor streaming |
| ruflo-autopilot | Autonomous /loop task completion with prediction |
| ruflo-loop-workers | 12 background workers via /loop or CronCreate |
| ruflo-workflows | Workflow templates, parallel execution, branching |
Memory & Intelligence
| Plugin | Description |
|---|---|
| ruflo-agentdb | AgentDB with HNSW vector search (150x-12,500x faster) |
| ruflo-rag-memory | SOTA RAG — hybrid search, Graph RAG, MMR diversity, memory bridge |
| ruflo-rvf | Portable RVF memory format, session persistence |
| ruflo-ruvector | ruvector — FlashAttention-3, Graph RAG, hybrid search, 103 MCP tools, Brain AGI |
| ruflo-knowledge-graph | Entity extraction, relation mapping, pathfinder traversal |
| ruflo-intelligence | SONA neural patterns, trajectory learning, model routing |
| ruflo-daa | Dynamic Agentic Architecture, cognitive patterns |
Architecture & Methodology
| Plugin | Description |
|---|---|
| ruflo-adr | ADR lifecycle — create, index, supersede, compliance checking |
| ruflo-ddd | DDD scaffolding — bounded contexts, aggregates, domain events |
| ruflo-sparc | SPARC methodology with 5 phases and quality gates |
Quality & Security
| Plugin | Description |
|---|---|
| ruflo-security-audit | CVE scanning, dependency vulnerability checks |
| ruflo-aidefence | Prompt injection detection, PII scanning |
| ruflo-testgen | Test gap detection, TDD London School workflow |
| ruflo-browser | Playwright browser automation and testing |
Development Tools
| Plugin | Description |
|---|---|
| ruflo-jujutsu | Diff analysis, risk scoring, reviewer recommendations |
| ruflo-docs | Doc generation, drift detection, API docs |
| ruflo-ruvllm | Local LLM inference, MicroLoRA, chat formatting |
| ruflo-agent | WASM agent sandboxing and gallery |
| ruflo-plugin-creator | Scaffold and validate new plugins |
| ruflo-migrations | Database schema migration management |
| ruflo-observability | Structured logging, tracing, metrics correlation |
| ruflo-cost-tracker | Token usage tracking, budget alerts, cost optimization |
Domain-Specific
| Plugin | Description |
|---|---|
| ruflo-goals | GOAP planning, deep research, horizon tracking |
| ruflo-federation | Zero-trust cross-installation agent federation |
| ruflo-iot-cognitum | Cognitum Seed IoT — trust scoring, anomaly detection, fleet management |
| ruflo-neural-trader | neural-trader — 4 agents, LSTM/Transformer, Rust/NAPI backtesting, 112+ MCP tools |
| ruflo-market-data | Market data ingestion, OHLCV vectorization, pattern matching |
Recommended Stacks
| Use Case | Plugins |
|---|---|
| Feature development | ruflo-core + ruflo-swarm + ruflo-testgen + ruflo-ddd |
| Security audit | ruflo-core + ruflo-security-audit + ruflo-aidefence |
| Architecture work | ruflo-core + ruflo-adr + ruflo-ddd + ruflo-sparc |
| Deep research | ruflo-core + ruflo-goals + ruflo-rag-memory + ruflo-intelligence |
| Vector search | ruflo-core + ruflo-ruvector + ruflo-rag-memory + ruflo-knowledge-graph |
| IoT development | ruflo-core + ruflo-iot-cognitum + ruflo-agentdb |
| Trading systems | ruflo-core + ruflo-neural-trader + ruflo-market-data + ruflo-ruvector |
| Full stack | All 32 plugins |
npm Package Integration
Several plugins wrap standalone npm packages for deeper functionality:
| Plugin | npm Package | What It Adds |
|---|---|---|
ruflo-neural-trader |
neural-trader |
112+ MCP tools, Rust/NAPI engine, LSTM/Transformer models |
ruflo-ruvector |
ruvector |
103 MCP tools, FlashAttention-3, Graph RAG, Brain AGI |
# Install backing packages
npm install neural-trader ruvector
# Add as MCP servers (optional, for direct tool access)
claude mcp add neural-trader -- npx neural-trader mcp start
claude mcp add ruvector -- npx ruvector mcp start
Plugin Structure
Each plugin follows the Claude Code plugin specification:
ruflo-<name>/
.claude-plugin/plugin.json # Plugin manifest
agents/<name>.md # Agent definitions (frontmatter: name, description, model)
commands/<name>.md # CLI command mappings
skills/<name>/SKILL.md # Interactive skills (frontmatter: name, description, argument-hint, allowed-tools)
README.md # Plugin documentation
Creating a Plugin
claude --plugin-dir plugins/ruflo-plugin-creator
# Then: /create-plugin my-new-plugin
Or manually: copy any existing plugin directory and modify.
Validation
claude plugin validate plugins/ruflo-<name>
Verification & Discoverability
Every MCP tool description across the 32 plugins must answer "use this over native (Bash/Read/Grep/Glob/Task/TodoWrite) when?" per ADR-112. The rule is enforced by CI:
# Run the audit (scans all MCPTool definitions across all plugins)
node scripts/audit-tool-descriptions.mjs
# Gates: every description must include "Use when …" guidance,
# be ≥ 80 chars, and be unique. Baseline at verification/mcp-tool-baseline.json
# is monotone-decreasing — CI fails on any regression.
Combined with verification/ (Ed25519-signed witness manifest, 103+ documented fixes attested), the plugin surface is regression-protected at three layers: install smoke (npm i), behavioral smoke (paired-tool round-trips), and presence attestation (every load-bearing line of every documented fix). See verification/README.md for the full stack.
License
MIT