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-core): v0.2.0 β€” adopt foundation plugin contract (ADR-0001, MCP server contract, sibling ADR cross-references)

Reuvenbd384ad5e665
diff --git a/plugins/ruflo-core/.claude-plugin/plugin.json b/plugins/ruflo-core/.claude-plugin/plugin.json
index 2d40bfce16..0508834a84 100644
--- a/plugins/ruflo-core/.claude-plugin/plugin.json
+++ b/plugins/ruflo-core/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-core",
- "description": "Core Ruflo MCP tools, commands, and Claude Code orchestration patterns",
- "version": "0.1.0",
+ "description": "Foundation plugin β€” registers the ruflo MCP server (300+ tools across memory/agentdb/embeddings/hooks/aidefence/neural/autopilot/browser/agent/swarm), provides 3 generalist agents (coder/researcher/reviewer), 3 first-run skills, and a curated plugin-discovery catalog",
+ "version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -12,6 +12,10 @@
"ruflo",
"mcp",
"orchestration",
- "claude-code"
+ "claude-code",
+ "foundation",
+ "mcp-server",
+ "plugin-catalog",
+ "discovery"
]
}
diff --git a/plugins/ruflo-core/README.md b/plugins/ruflo-core/README.md
index 094dedca26..3fa7236d61 100644
--- a/plugins/ruflo-core/README.md
+++ b/plugins/ruflo-core/README.md
@@ -1,6 +1,6 @@
# ruflo-core
-Core Ruflo MCP tools, commands, and Claude Code orchestration patterns.
+Foundation plugin. Registers the `ruflo` MCP server (300+ tools), provides three generalist agents (`coder`, `researcher`, `reviewer`), three first-run helpers (`init-project`, `ruflo-doctor`, `discover-plugins`), and a curated catalog covering all 30+ sibling plugins.
## Install
@@ -11,7 +11,7 @@ Core Ruflo MCP tools, commands, and Claude Code orchestration patterns.
## What's Included
-- **MCP Server**: 314 tools via `@claude-flow/cli` (memory, agents, swarm, hooks, neural, security)
+- **MCP Server**: 300+ tools via `@claude-flow/cli` (memory, agentdb, embeddings, hooks, neural, autopilot, browser, aidefence, agent, swarm, system, terminal, github, daa, coordination, performance, workflow, …)
- **CLI Commands**: 26 commands with 140+ subcommands for agent orchestration
- **3-Tier Model Routing**: Agent Booster (WASM), Haiku, Sonnet/Opus with automatic cost optimization
- **Session Management**: Persistent sessions with cross-conversation learning
@@ -20,3 +20,53 @@ Core Ruflo MCP tools, commands, and Claude Code orchestration patterns.
## Configuration
The MCP server starts automatically when this plugin is active. Override environment variables in `.mcp.json` as needed.
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor. The `.mcp.json` invocation uses `@latest` for dynamic resolution; the smoke contract verifies the resolved CLI matches the v3.6 line.
+- **Verification:** `bash plugins/ruflo-core/scripts/smoke.sh` is the contract.
+
+## MCP server contract
+
+The registered `ruflo` MCP server exposes 300+ tools across these families. Runtime truth is `mcp tool call mcp_status`:
+
+| Family | Notable tools | Plugin documenting it |
+|--------|---------------|-----------------------|
+| `memory_*` | `memory_store`, `_search`, `_search_unified`, `_import_claude`, `_bridge_status` | `ruflo-rag-memory` |
+| `agentdb_*` | 15 tools for hierarchical / pattern / causal storage | `ruflo-agentdb` |
+| `embeddings_*` | 10 tools incl. RaBitQ 32Γ— quantization | `ruflo-agentdb`, `ruflo-ruvector` |
+| `hooks_*` (incl. `hooks_intelligence_*`) | 19+ tools β€” routing, learning, transfer, metrics, explain | `ruflo-intelligence`, `ruflo-autopilot` |
+| `aidefence_*` | 6 tools β€” PII / prompt-injection / sanitization | `ruflo-aidefence` |
+| `neural_*` | 6 tools β€” train, predict, patterns, compress | `ruflo-intelligence` |
+| `autopilot_*` | 10 tools β€” autonomous loops + learning | `ruflo-autopilot` |
+| `browser_*` (+ new `browser_session_*`) | 23 + 5 = 28 tools β€” Playwright + RVF lifecycle | `ruflo-browser` |
+| `ruvllm_sona_*` / `ruvllm_microlora_*` | 4 tools β€” adaptive learning | `ruflo-intelligence`, `ruflo-ruvllm` |
+| `agent_*`, `swarm_*` | spawn, list, status, orchestrate | `ruflo-swarm` |
+| `system_*`, `terminal_*` | system + terminal session ops | this plugin |
+
+For every other plugin's tool surface, see its `docs/adrs/0001-*.md`.
+
+## Sibling contracts
+
+This foundation plugin defers to seven sibling ADRs that own specific cross-cutting contracts. New plugins (and consumers of `ruflo-core`) should reference these instead of re-deriving:
+
+| Contract | Owner |
+|----------|-------|
+| **Pinning + smoke as contract** (general pattern) | [ruflo-ruvector ADR-0001](../ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md) |
+| **Namespace convention** (`<plugin-stem>-<intent>`, reserved namespaces) | [ruflo-agentdb ADR-0001](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md) |
+| **Session-as-skill architecture** (RVF + trajectory + 3 AIDefence gates) | [ruflo-browser ADR-0001](../ruflo-browser/docs/adrs/0001-browser-skills-architecture.md) |
+| **4-step intelligence pipeline** (RETRIEVE β†’ JUDGE β†’ DISTILL β†’ CONSOLIDATE) | [ruflo-intelligence ADR-0001](../ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md) |
+| **3-gate AIDefence pattern** (PII pre-storage, sanitization, prompt-injection) | [ruflo-aidefence ADR-0001](../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md) |
+| **270s cache-aware /loop heartbeat** | [ruflo-autopilot ADR-0001](../ruflo-autopilot/docs/adrs/0001-autopilot-contract.md) |
+| **ADR plugin contract** (token-optimization via REFERENCE.md) | [ruflo-adr ADR-0001](../ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md) |
+
+## Verification
+
+```bash
+bash plugins/ruflo-core/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-core plugin contract (foundation, MCP server, plugin catalog, smoke as contract)](./docs/adrs/0001-core-contract.md)
diff --git a/plugins/ruflo-core/docs/adrs/0001-core-contract.md b/plugins/ruflo-core/docs/adrs/0001-core-contract.md
new file mode 100644
index 0000000000..e9426f78a5
--- /dev/null
+++ b/plugins/ruflo-core/docs/adrs/0001-core-contract.md
@@ -0,0 +1,97 @@
+---
+id: ADR-0001
+title: ruflo-core plugin contract β€” pinning, MCP server contract, plugin-catalog discovery, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, core, mcp, foundation, smoke-test]
+---
+
+## Context
+
+`ruflo-core` is the **foundation plugin**. Every other plugin (`ruflo-ruvector`, `ruflo-agentdb`, `ruflo-browser`, `ruflo-intelligence`, `ruflo-adr`, `ruflo-aidefence`, `ruflo-autopilot`, plus 25 others) depends on the MCP server it registers via `.mcp.json` and the orchestration patterns it documents.
+
+Today's plugin (v0.1.0):
+
+- `.claude-plugin/plugin.json:4` β€” `version: "0.1.0"`, keywords `mcp, orchestration, claude-code`
+- `.mcp.json` β€” registers `ruflo` MCP server via `npx -y @claude-flow/cli@latest`
+- `agents/` β€” 3 generalists (`coder`, `researcher`, `reviewer`)
+- `skills/` β€” 3 first-run helpers (`init-project`, `ruflo-doctor`, `discover-plugins`)
+- `commands/ruflo-status.md` β€” system status one-liner
+- `README.md` β€” terse: "What's Included" + Configuration only
+
+The discover-plugins skill is a substantial asset β€” a curated 32-plugin catalog with decision guides. That stays.
+
+What's missing matches the cadence we've established:
+
+1. **No plugin-level ADR.** Foundation plugin should document its own contract since 30+ plugins depend on it.
+2. **No smoke test.**
+3. **No Compatibility section** pinning to `@claude-flow/cli` v3.6.
+4. **MCP server tool count is undocumented.** `discover-plugins` mentions "314 tools" once, but this should be a contract claim with a verification path.
+5. **No cross-references** to sibling ADRs (namespace convention, 3-gate pattern, 4-step pipeline) that other plugins now reference.
+
+## Decision
+
+### 1. Add this ADR (Proposed)
+
+`docs/adrs/0001-core-contract.md`. Cross-links the seven sibling ADRs.
+
+### 2. README augmentation (no rewrite)
+
+Append:
+
+- **Compatibility** β€” pin to `@claude-flow/cli` v3.6. Note the `npx -y @claude-flow/cli@latest` invocation in `.mcp.json` is the dynamic resolver; smoke verifies the resolved version.
+- **MCP server contract** β€” the registered `ruflo` MCP server exposes 300+ tools across families: `memory_*`, `agentdb_*`, `embeddings_*`, `ruvllm_*`, `hooks_*`, `aidefence_*`, `neural_*`, `autopilot_*`, `browser_*`, `agent_*`, `swarm_*`, `system_*`, etc. Runtime truth via `mcp tool call mcp_status`.
+- **Sibling contracts** β€” pointer block to the seven sibling ADRs that already define namespace convention, 3-gate pattern, 4-step pipeline, etc.
+- **Architecture Decisions** + **Verification** sections.
+
+### 3. Plugin metadata bump
+
+`0.1.0 β†’ 0.2.0`. Keywords add `foundation`, `mcp-server`, `plugin-catalog`, `discovery`.
+
+### 4. Smoke contract (`scripts/smoke.sh`)
+
+10 checks:
+
+1. plugin.json declares `0.2.0` with the new keywords.
+2. `.mcp.json` exists and registers a `ruflo` MCP server.
+3. All 3 agents present (`coder`, `researcher`, `reviewer`) with valid frontmatter.
+4. All 3 skills present (`init-project`, `ruflo-doctor`, `discover-plugins`) with valid frontmatter.
+5. `discover-plugins` skill catalog references at least 25 sibling plugins (the curated catalog).
+6. README pins to `@claude-flow/cli` v3.6.
+7. README cross-references sibling contracts (namespace convention, 3-gate pattern, 4-step pipeline).
+8. ADR-0001 exists with status `Proposed`.
+9. `commands/ruflo-status.md` invokes `doctor` and `status`.
+10. No skill grants wildcard tool access.
+
+## Consequences
+
+**Positive:**
+- Foundation plugin is now contractually self-documenting.
+- Sibling-ADR cross-references make the cohesive plugin family discoverable from the entry point.
+- Plugin catalog claims are now smoke-verifiable.
+
+**Negative:**
+- `discover-plugins` catalog must be kept in sync as plugins are added. Today there are 33 plugins (including this one); the catalog covers ~32. Drift remediation is a separate, mechanical task.
+
+**Neutral:**
+- No new MCP tools, no new skills, no new agents. Documentation + smoke only.
+
+## Verification
+
+```bash
+bash plugins/ruflo-core/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md`
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention
+- `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md`
+- `plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md` β€” 4-step pipeline
+- `plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md`
+- `plugins/ruflo-aidefence/docs/adrs/0001-aidefence-contract.md` β€” 3-gate pattern
+- `plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md` β€” 270s cache-aware /loop
+- `v3/@claude-flow/cli/` β€” the MCP server source backing this plugin
diff --git a/plugins/ruflo-core/scripts/smoke.sh b/plugins/ruflo-core/scripts/smoke.sh
new file mode 100755
index 0000000000..842c30ca05
--- /dev/null
+++ b/plugins/ruflo-core/scripts/smoke.sh
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-core v0.2.0 (ADR-0001).
+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 foundation mcp-server plugin-catalog discovery; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. .mcp.json registers a 'ruflo' MCP server"
+F="$ROOT/.mcp.json"
+if [[ -f "$F" ]] && grep -q '"ruflo"' "$F" && grep -q '"command"' "$F"; then
+ ok
+else
+ bad ".mcp.json missing or no ruflo server registration"
+fi
+
+step "3. all 3 agents present with valid frontmatter"
+miss=""
+for a in coder researcher reviewer; do
+ f="$ROOT/agents/$a.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$a"; continue; }
+ for k in 'name:' 'description:'; do
+ grep -q "^$k" "$f" || miss="$miss $a-no-$k"
+ done
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. all 3 skills present with valid frontmatter"
+miss=""
+for s in init-project ruflo-doctor discover-plugins; 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 "5. discover-plugins catalog references at least 25 sibling plugins"
+F="$ROOT/skills/discover-plugins/SKILL.md"
+n=$(grep -oE 'ruflo-[a-z-]+' "$F" | sort -u | wc -l | tr -d ' ')
+if [[ $n -ge 25 ]]; then
+ ok
+else
+ bad "expected β‰₯25 distinct ruflo-* references, got $n"
+fi
+
+step "6. 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 "Compatibility pin to v3.6 missing"
+
+step "7. README cross-references sibling contracts"
+F="$ROOT/README.md"
+miss=""
+grep -q "Namespace convention" "$F" || miss="$miss namespace"
+grep -qE "3-gate|3 gates|three gates" "$F" || miss="$miss 3-gate"
+grep -qE "4-step|4 step" "$F" || miss="$miss 4-step"
+[[ -z "$miss" ]] && ok || bad "missing cross-references:$miss"
+
+step "8. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-core-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "9. /ruflo-status command invokes doctor + status"
+F="$ROOT/commands/ruflo-status.md"
+if grep -q "doctor" "$F" && grep -q "status" "$F"; then
+ ok
+else
+ bad "ruflo-status command missing doctor/status invocation"
+fi
+
+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