mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-11-10 06:23:28 +09:00
ruv
ca56902b27
Iter 50's parseMcpScanText reverse-engineered `harness mcp-scan` text
output to extract structured findings. If upstream changes the format
(drops `[]` markers, switches to JSON, changes the Result: regex), the
parser silently returns empty findings and iter-49's introduced/cleared
diff regresses to the original dead-code state.
This iter adds a compat tripwire mirroring scripts/check-metaharness-
compat.mjs (which protects the @metaharness/router API surface).
WHAT SHIPPED
1. scripts/check-mcp-scan-format.mjs — runs `harness mcp-scan` against
ruflo and asserts 4 invariants:
✓ At least one ` [SEV] message` line in expected regex shape
✓ Result line matches `Result: SEV (N finding, M high)`
✓ parseMcpScanText loadable (sanity)
✓ parseMcpScanText extracts ≥ 1 finding from real output
Exit 0 — invariants intact OR metaharness not installed (graceful skip)
Exit 1 — invariant violated, parser will silently break
Exit 2 — unexpected error
The "extract ≥1 finding from real output" assertion is the
load-bearing check. It catches drift the regex above might miss
(e.g., if upstream switched to identical-looking but slightly
different whitespace).
2. .github/workflows/metaharness-ci.yml — new step in the
`metaharness-real-data` job runs the tripwire BEFORE the roundtrip.
If upstream format drifted, CI fails with a clear "format invariant
violated" message before chasing downstream symptoms.
3. plugins/ruflo-metaharness/scripts/smoke.sh — step 17z43 anchors:
- tripwire script exists + parses
- All 3 invariant text markers (finding/result/parser-roundtrip)
- CI workflow references the script
- Runtime: tripwire passes against the locally-installed metaharness
WHY TWO TRIPWIRES NOW EXIST
scripts/check-metaharness-compat.mjs (iter 12)
→ Protects @metaharness/router public API (constructor, route(),
fromExamples(), TrainedRouter.fromJSON())
scripts/check-mcp-scan-format.mjs (THIS ITER)
→ Protects `harness mcp-scan` text format (regex + parser-roundtrip)
These cover different upstream surfaces. The router compat-check ran
at the API level; the new check is at the CLI-output level. Both are
necessary because ruflo depends on both surfaces in different ways.
VERIFIED LOCALLY
$ node scripts/check-mcp-scan-format.mjs
✓ All 4 invariants intact.
GATES THIS ITER
smoke: 82 → 83 (step 17z43 green)
ci: new pre-roundtrip step in metaharness-real-data job
runtime: 4 format invariants pass against metaharness@0.1.14
PROTECTION RATIONALE
Iter 50 was a downstream workaround for issue ruvnet/agent-harness-
generator#16 (`harness mcp-scan` emits text only with --json). When
upstream eventually fixes that issue and emits structured JSON, the
parser's regex-based extraction will STILL work (the parser falls back
gracefully). But the tripwire will fail on the FIRST run after upstream
adds the JSON output AND drops the text format — which is a real risk
because upstream is in v0.1.x.
When the tripwire eventually fires, the fix is upstream-aware:
- If text format dropped → switch parseMcpScanText to read r.json directly
- If JSON added alongside text → prefer r.json, keep parser as fallback
The tripwire makes that decision visible at the PR that introduces it,
not 4 weeks later when someone notices drift detection is silent.
Co-Authored-By: RuFlo <ruv@ruv.net>
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