π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.jsonindex 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.mdindex 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.## ConfigurationThe 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.mdnew file mode 100644index 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 plugindiff --git a/plugins/ruflo-core/scripts/smoke.sh b/plugins/ruflo-core/scripts/smoke.shnew file mode 100755index 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