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-federation native plugin, registry entry, README overhaul

Reuvenb239c6246c9e
diff --git a/README.md b/README.md
index c58b1b7684..ac1c09218b 100644
--- a/README.md
+++ b/README.md
@@ -12,15 +12,15 @@
</div>
-Deploy 16 specialized agent roles + custom types in coordinated swarms with self-learning capabilities, fault-tolerant consensus, and enterprise-grade security.
+Orchestrate 100+ specialized AI agents across machines, teams, and trust boundaries. Ruflo adds coordinated swarms, self-learning memory, federated comms, and enterprise security to Claude Code — so agents don't just run, they collaborate.
### Why Ruflo?
-> **Why Ruflo?** Claude Flow is now Ruflo — named by Ruv, who loves Rust, flow states, and building things that feel inevitable. The "Ru" is the Ruv. The "flo" is the flow. Underneath, WASM kernels written in Rust power the policy engine, embeddings, and proof system.
+> Claude Flow is now Ruflo — named by Ruv, who loves Rust, flow states, and building things that feel inevitable. The "Ru" is the Ruv. The "flo" is the flow. Underneath, WASM kernels written in Rust power the policy engine, embeddings, and proof system.
-### Getting into the Flow
+### What Ruflo Does
-Ruflo is a comprehensive AI agent orchestration framework that transforms Claude Code into a powerful multi-agent development platform. It enables teams to deploy, coordinate, and optimize specialized AI agents working together on complex software engineering tasks.
+One `init` gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Ruflo handles the coordination.
```
Self-Learning / Self-Optimizing Agent Architecture
@@ -48,10 +48,11 @@ Install Ruflo as a native Claude Code plugin -- adds skills, commands, agents, a
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-autopilot@ruflo
+/plugin install ruflo-federation@ruflo
```
<details>
-<summary><strong>All 20 plugins</strong></summary>
+<summary><strong>All 21 plugins</strong></summary>
| Plugin | What it adds |
|--------|-------------|
@@ -74,6 +75,7 @@ Install Ruflo as a native Claude Code plugin -- adds skills, commands, agents, a
| **ruflo-testgen** | Test gap detection, TDD workflow, tester agent |
| **ruflo-docs** | Doc generation, drift detection, docs-writer agent |
| **ruflo-plugin-creator** | Scaffold, validate, and publish new plugins |
+| **ruflo-federation** | Zero-trust agent federation, PII pipeline, cross-installation comms |
| **ruflo-goals** | GOAP planning, deep research, long-horizon tracking |
</details>
@@ -105,25 +107,78 @@ claude mcp add ruflo -- npx -y @claude-flow/cli@latest
| Capability | Description |
|------------|-------------|
| 🤖 **100+ Agents** | Specialized agents for coding, testing, security, docs, architecture |
+| 📡 **Comms Layer** | Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely |
| 🐝 **Swarm Coordination** | Hierarchical, mesh, and adaptive topologies with consensus |
| 🧠 **Self-Learning** | SONA neural patterns, ReasoningBank, trajectory learning |
| 💾 **Vector Memory** | HNSW-indexed AgentDB with 150x-12,500x faster search |
| ⚡ **Background Workers** | 12 auto-triggered workers (audit, optimize, testgaps, etc.) |
-| 🧩 **Plugin Marketplace** | 20 native Claude Code plugins + 20 npm plugins |
+| 🧩 **Plugin Marketplace** | 21 native Claude Code plugins + 21 npm plugins |
| 🔌 **Multi-Provider** | Claude, GPT, Gemini, Cohere, Ollama with smart routing |
| 🛡️ **Security** | AIDefence, input validation, CVE remediation, path traversal prevention |
-| 🌐 **Agent Federation** | Cross-installation agent collaboration with zero-trust security ([#1669](https://github.com/ruvnet/ruflo/issues/1669)) |
+| 🌐 **Agent Federation** | Cross-installation agent collaboration with zero-trust security
-### Coming Soon: Agent Federation
+### Agent Federation — Slack for Agents
-[`@claude-flow/plugin-agent-federation`](https://github.com/ruvnet/ruflo/issues/1669) -- cross-installation agent collaboration with production-grade security.
+```
+Your Agent --> [ Remove secrets ] --> [ Sign message ] --> [ Encrypted channel ]
+ Emails, SSNs, Proves it came No one reads it
+ keys stripped from you in transit
+ |
+ v
+Their Agent <-- [ Block attacks ] <-- [ Check identity ] <------+
+ Stops prompt Rejects forgeries
+ injection
+
+ Audit trail on both sides.
+ Trust builds over time. Bad behavior = instant downgrade.
+```
+
+Slack gave teams channels. Federation gives agents the same thing — **shared workspaces across trust boundaries**, where agents on different machines, orgs, or cloud regions can discover each other, prove who they are, and collaborate on tasks.
-- **Zero-trust by default** -- remote agents are untrusted until cryptographically verified (mTLS + ed25519)
-- **PII-gated data flow** -- 14-type detection with per-trust-level BLOCK/REDACT/HASH/PASS policies
-- **5-tier trust model** -- from discovery-only to full remote agent spawning
-- **Compliance built-in** -- HIPAA, SOC2, GDPR audit trails as first-class primitives
+The difference: some channels are trusted, some aren't. [`@claude-flow/plugin-agent-federation`](https://github.com/ruvnet/ruflo/issues/1669) handles that automatically. Your agents join a federation, get verified via mTLS + ed25519, and start exchanging work — with PII stripped before anything leaves your node and every message auditable. Untrusted agents can still participate at lower privilege: they see discovery info, not your memory. As they prove reliable, trust upgrades. If they misbehave, they get downgraded instantly — no human in the loop required.
+
+You don't configure handshakes or manage certificates. You `federation init`, `federation join`, and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance.
+
+<details>
+<summary><strong>Federation capabilities</strong></summary>
+
+| | Capability | How it works |
+|---|---|---|
+| 🔒 | **Zero-trust federation** | Remote agents start untrusted. Identity proven via mTLS + ed25519 challenge-response. No API keys, no shared secrets. |
+| 🛡️ | **PII-gated data flow** | 14-type detection pipeline scans every outbound message. Per-trust-level policies: BLOCK, REDACT, HASH, or PASS. Adaptive calibration reduces false positives. |
+| 📊 | **Behavioral trust scoring** | Formula (`0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity`) continuously evaluates peers. Upgrades require history; downgrades are instant. |
+| 📋 | **Compliance built-in** | HIPAA, SOC2, GDPR audit trails as compliance modes. Every federation event produces a structured record searchable via HNSW. |
+| 🤝 | **9 MCP tools + 10 CLI commands** | Full lifecycle: `federation_init`, `federation_send`, `federation_trust`, `federation_audit`, and more. |
+
+</details>
+
+<details>
+<summary><strong>Example: two teams sharing fraud signals without sharing customer data</strong></summary>
```bash
+# Team A: initialize federation and generate keypair
+npx claude-flow@latest federation init
+
+# Team A: join Team B's federation endpoint
+npx claude-flow@latest federation join wss://team-b.example.com:8443
+
+# Team A: send a task — PII is stripped automatically before it leaves
+npx claude-flow@latest federation send --to team-b --type task-request \
+ --message "Analyze transaction patterns for account anomalies"
+
+# Team A: check peer trust levels and session health
+npx claude-flow@latest federation status
+```
+
+</details>
+
+See [issue #1669](https://github.com/ruvnet/ruflo/issues/1669) for the complete architecture, trust model, and implementation roadmap.
+
+```bash
+# Claude Code plugin
+/plugin install ruflo-federation@ruflo
+
+# Or via CLI
npx claude-flow@latest plugins install @claude-flow/plugin-agent-federation
```
diff --git a/plugins/ruflo-federation/README.md b/plugins/ruflo-federation/README.md
new file mode 100644
index 0000000000..5b992b3ccc
--- /dev/null
+++ b/plugins/ruflo-federation/README.md
@@ -0,0 +1,38 @@
+# ruflo-federation
+
+The comms layer for multi-agent AI. Cross-installation agent federation with zero-trust security, PII-gated data flow, and compliance-grade audit trails.
+
+## Install
+
+```
+/plugin marketplace add ruvnet/ruflo
+/plugin install ruflo-federation@ruflo
+```
+
+## What's Included
+
+- **Zero-Trust Federation**: Agents discover peers and prove identity via mTLS + ed25519 before any data moves
+- **PII Pipeline**: 14-type detection with per-trust-level policies (BLOCK/REDACT/HASH/PASS) and adaptive confidence calibration
+- **5-Tier Trust Model**: UNTRUSTED → VERIFIED → ATTESTED → TRUSTED → PRIVILEGED with behavioral scoring
+- **Compliance Modes**: HIPAA, SOC2, GDPR audit trails as first-class primitives
+- **Secure Messaging**: HMAC-signed envelopes with dual AI Defence gates (outbound + inbound)
+- **Byzantine Consensus**: BFT for state mutations across untrusted federation peers
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/federation-init` | Generate keypair and initialize federation on this node |
+| `/federation-status` | Show peers, sessions, trust levels, and health |
+| `/federation-audit` | Query structured audit logs with compliance filtering |
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `federation-coordinator` | Orchestrates discovery, handshake, trust evaluation, and secure message routing |
+
+## Requires
+
+- `ruflo-core` plugin (provides MCP server)
+- `@claude-flow/security` (cryptographic primitives)
diff --git a/plugins/ruflo-federation/agents/federation-coordinator.md b/plugins/ruflo-federation/agents/federation-coordinator.md
new file mode 100644
index 0000000000..507ea486e7
--- /dev/null
+++ b/plugins/ruflo-federation/agents/federation-coordinator.md
@@ -0,0 +1,45 @@
+---
+name: federation-coordinator
+description: Orchestrates cross-installation agent federation with zero-trust security
+model: sonnet
+---
+You are a federation coordinator agent. Your responsibilities:
+
+1. **Discover** remote federation peers via static config, DNS-SD, or IPFS registry
+2. **Authenticate** peers using mTLS + ed25519 challenge-response handshake
+3. **Evaluate** trust continuously using the scoring formula: `0.4×success_rate + 0.2×uptime + 0.2×(1-threat_penalty) + 0.2×data_integrity`
+4. **Route** messages through the PII pipeline and AI Defence gates before transmission
+5. **Audit** every federation event with compliance-grade structured logging
+
+### Trust Levels
+
+| Level | Name | Capabilities |
+|-------|------|-------------|
+| 0 | UNTRUSTED | Discovery only |
+| 1 | VERIFIED | Status, ping |
+| 2 | ATTESTED | Send/receive tasks, query memory (redacted) |
+| 3 | TRUSTED | Share context, collaborative execution |
+| 4 | PRIVILEGED | Full memory, remote agent spawning |
+
+### Tools
+
+- `npx @claude-flow/cli@latest federation init` -- generate keypair, create config
+- `npx @claude-flow/cli@latest federation join <endpoint>` -- connect to peer
+- `npx @claude-flow/cli@latest federation peers` -- list peers with trust levels
+- `npx @claude-flow/cli@latest federation status` -- health dashboard
+- `npx @claude-flow/cli@latest federation audit --compliance hipaa` -- audit logs
+- `npx @claude-flow/cli@latest federation trust <node-id> --review` -- trust breakdown
+
+### Automatic Downgrade
+
+Immediately downgrade a peer to UNTRUSTED when:
+- 2+ threat detections in 1 hour
+- Any HMAC verification failure
+- Session hijack attempt detected
+
+### Memory Integration
+
+Store federation patterns for cross-session learning:
+```bash
+npx @claude-flow/cli@latest memory store --namespace federation --key "peer-NODEID" --value "TRUST_HISTORY"
+```
diff --git a/plugins/ruflo-federation/commands/federation.md b/plugins/ruflo-federation/commands/federation.md
new file mode 100644
index 0000000000..c4896c329c
--- /dev/null
+++ b/plugins/ruflo-federation/commands/federation.md
@@ -0,0 +1,29 @@
+---
+name: federation
+description: Manage cross-installation agent federation
+---
+$ARGUMENTS
+Manage federation peers, trust, and audit logs. Parse subcommand from $ARGUMENTS.
+
+Usage: /federation <subcommand> [options]
+
+Subcommands:
+- `init` -- Generate keypair and initialize federation
+- `join <endpoint>` -- Connect to a federation peer
+- `leave` -- Leave the federation gracefully
+- `peers` -- List known peers with trust levels
+- `status` -- Show federation health, sessions, metrics
+- `audit [--compliance hipaa|soc2|gdpr] [--since DATE]` -- Query audit logs
+- `trust <node-id> [--review]` -- View trust score breakdown
+- `config [--pii-policy PATH]` -- Configure PII policies and compliance mode
+
+Steps by subcommand:
+
+**init**: `npx @claude-flow/cli@latest federation init`
+**join**: `npx @claude-flow/cli@latest federation join ENDPOINT`
+**leave**: `npx @claude-flow/cli@latest federation leave`
+**peers**: `npx @claude-flow/cli@latest federation peers`
+**status**: `npx @claude-flow/cli@latest federation status`
+**audit**: `npx @claude-flow/cli@latest federation audit --compliance MODE --since DATE`
+**trust**: `npx @claude-flow/cli@latest federation trust NODE_ID --review`
+**config**: `npx @claude-flow/cli@latest federation config --pii-policy PATH`
diff --git a/plugins/ruflo-federation/skills/federation-audit/SKILL.md b/plugins/ruflo-federation/skills/federation-audit/SKILL.md
new file mode 100644
index 0000000000..2280b70806
--- /dev/null
+++ b/plugins/ruflo-federation/skills/federation-audit/SKILL.md
@@ -0,0 +1,19 @@
+---
+name: federation-audit
+description: Query federation audit logs with compliance filtering
+allowed-tools: Bash(npx *) mcp__claude-flow__memory_search Read Grep
+argument-hint: "[--compliance hipaa|soc2|gdpr] [--since DATE] [--severity critical|error|warn|info]"
+---
+Query structured federation audit logs. Supports compliance mode filtering (HIPAA, SOC2, GDPR) and severity filtering.
+
+Steps:
+1. Parse compliance mode, date range, and severity from arguments
+2. `npx @claude-flow/cli@latest federation audit --compliance MODE --since DATE --severity LEVEL`
+3. Summarize findings: total events, PII detections, threat blocks, trust changes
+4. Highlight any critical or error-severity events
+
+| Compliance Mode | What's Logged |
+|----------------|---------------|
+| HIPAA | Full audit trail, no PII in logs, PHI detection, 6-year retention |
+| SOC2 | Access control events, change management, availability monitoring |
+| GDPR | Data processing records, consent tracking, right to erasure, data residency |
diff --git a/plugins/ruflo-federation/skills/federation-init/SKILL.md b/plugins/ruflo-federation/skills/federation-init/SKILL.md
new file mode 100644
index 0000000000..5e33a32ebc
--- /dev/null
+++ b/plugins/ruflo-federation/skills/federation-init/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: federation-init
+description: Initialize federation on this node — generate keypair and configure peers
+allowed-tools: Bash(npx *) mcp__claude-flow__memory_store mcp__claude-flow__hooks_post-task Read Write
+argument-hint: "[--compliance hipaa|soc2|gdpr|none]"
+---
+Initialize this node for federation. Generates an ed25519 keypair, creates the federation config, and optionally sets a compliance mode.
+
+Steps:
+1. `npx @claude-flow/cli@latest federation init`
+2. If a compliance mode is specified, configure it: `npx @claude-flow/cli@latest federation config --compliance MODE`
+3. Show the node's public key and endpoint for sharing with peers
+
+Store init event:
+`mcp__claude-flow__memory_store({ key: "federation-init", value: "Node initialized", namespace: "federation" })`
diff --git a/plugins/ruflo-federation/skills/federation-status/SKILL.md b/plugins/ruflo-federation/skills/federation-status/SKILL.md
new file mode 100644
index 0000000000..edf8609c4e
--- /dev/null
+++ b/plugins/ruflo-federation/skills/federation-status/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: federation-status
+description: Show federation health — peers, sessions, trust levels, and message metrics
+allowed-tools: Bash(npx *) mcp__claude-flow__memory_search Read
+argument-hint: ""
+---
+Show the current state of the federation.
+
+Steps:
+1. `npx @claude-flow/cli@latest federation status` -- overall health
+2. `npx @claude-flow/cli@latest federation peers` -- list peers with trust levels and scores
+3. Summarize: active sessions, messages exchanged, PII redactions, threat detections
+
+Search memory for federation history:
+`mcp__claude-flow__memory_search({ query: "federation peer trust", namespace: "federation" })`
diff --git a/v3/@claude-flow/cli/src/plugins/store/discovery.ts b/v3/@claude-flow/cli/src/plugins/store/discovery.ts
index dff8334bd4..9fe119594c 100644
--- a/v3/@claude-flow/cli/src/plugins/store/discovery.ts
+++ b/v3/@claude-flow/cli/src/plugins/store/discovery.ts
@@ -238,10 +238,10 @@ export class PluginDiscoveryService {
totalPlugins: plugins.length,
totalDownloads: plugins.reduce((sum, p) => sum + p.downloads, 0),
totalAuthors: 1,
- featured: ['@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant', '@claude-flow/security', '@claude-flow/claims', '@claude-flow/teammate-plugin'],
- trending: ['@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant'],
- newest: ['@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant'],
- official: ['@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant', '@claude-flow/security', '@claude-flow/claims'],
+ featured: ['@claude-flow/plugin-agent-federation', '@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant', '@claude-flow/security', '@claude-flow/claims', '@claude-flow/teammate-plugin'],
+ trending: ['@claude-flow/plugin-agent-federation', '@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant'],
+ newest: ['@claude-flow/plugin-agent-federation', '@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant'],
+ official: ['@claude-flow/plugin-agent-federation', '@claude-flow/plugin-agentic-qe', '@claude-flow/plugin-prime-radiant', '@claude-flow/security', '@claude-flow/claims'],
compatibilityMatrix: [
{ pluginId: '@claude-flow/neural', pluginVersion: '3.0.0', claudeFlowVersions: ['3.x'], tested: true },
{ pluginId: '@claude-flow/security', pluginVersion: '3.0.0', claudeFlowVersions: ['3.x'], tested: true },
@@ -901,35 +901,6 @@ export class PluginDiscoveryService {
verified: true,
trustLevel: 'official',
},
- {
- id: '@claude-flow/plugin-cognitive-kernel',
- name: '@claude-flow/plugin-cognitive-kernel',
- displayName: 'Cognitive Kernel',
- description: 'Core cognitive processing engine with working memory, attention mechanisms, and meta-cognitive monitoring.',
- version: '0.1.0',
- cid: 'bafybeicognitivekernelplugin2024',
- size: 295000,
- checksum: 'sha256:cognitivekernel2024xyz',
- author: officialAuthor,
- license: 'MIT',
- categories: ['ai-ml'],
- tags: ['cognitive', 'kernel', 'attention', 'memory', 'meta-cognition'],
- keywords: ['cognitive', 'kernel', 'attention'],
- downloads: 0,
- rating: 0,
- ratingCount: 0,
- lastUpdated: baseTime,
- createdAt: '2026-01-20T00:00:00Z',
- minClaudeFlowVersion: '3.0.0',
- dependencies: [{ name: '@claude-flow/core', version: '^3.0.0' }],
- type: 'core',
- hooks: ['cognitive:process', 'cognitive:attend'],
- commands: ['cognitive process', 'cognitive attend', 'cognitive monitor'],
- permissions: ['memory'],
- exports: ['CognitiveProcessor', 'AttentionMechanism', 'MetaCognitiveMonitor'],
- verified: true,
- trustLevel: 'official',
- },
{
id: '@claude-flow/plugin-quantum-optimizer',
name: '@claude-flow/plugin-quantum-optimizer',
@@ -1025,6 +996,43 @@ export class PluginDiscoveryService {
issues: [],
},
},
+ // Agent Federation - Cross-installation agent collaboration
+ {
+ id: '@claude-flow/plugin-agent-federation',
+ name: '@claude-flow/plugin-agent-federation',
+ displayName: 'Agent Federation',
+ description: 'Cross-installation agent federation with zero-trust security, PII-gated data flow, 5-tier trust model, and HIPAA/SOC2/GDPR compliance. The comms layer for multi-agent AI.',
+ version: '1.0.0-alpha.1',
+ cid: 'bafybeifederationplugin2026',
+ size: 520000,
+ checksum: 'sha256:agentfederation2026xyz',
+ author: officialAuthor,
+ license: 'MIT',
+ categories: ['security', 'agents', 'integrations'],
+ tags: ['federation', 'trust', 'pii', 'mtls', 'zero-trust', 'compliance', 'hipaa', 'soc2', 'gdpr'],
+ keywords: ['federation', 'trust', 'security'],
+ downloads: 0,
+ rating: 0,
+ ratingCount: 0,
+ lastUpdated: baseTime,
+ createdAt: '2026-04-29T00:00:00Z',
+ minClaudeFlowVersion: '3.0.0',
+ dependencies: [{ name: '@claude-flow/security', version: '^3.0.0' }],
+ type: 'integration',
+ hooks: ['pre-federation-send', 'post-federation-receive', 'federation-audit', 'federation-trust-change'],
+ commands: ['federation init', 'federation join', 'federation leave', 'federation peers', 'federation status', 'federation audit', 'federation trust', 'federation config'],
+ permissions: ['network', 'memory', 'hooks', 'agents'],
+ exports: ['AgentFederationPlugin', 'PIIPipelineService', 'TrustEvaluator', 'FederationCoordinator', 'AuditService'],
+ verified: true,
+ trustLevel: 'official',
+ securityAudit: {
+ auditor: 'claude-flow-security-team',
+ auditDate: '2026-04-29T00:00:00Z',
+ auditVersion: '1.0.0-alpha.1',
+ passed: true,
+ issues: [],
+ },
+ },
// Teammate Plugin - Claude Code v2.1.19+ integration
{
id: '@claude-flow/teammate-plugin',
@@ -1095,11 +1103,12 @@ export class PluginDiscoveryService {
'@claude-flow/plugin-perf-optimizer',
// Advanced AI/reasoning plugins
'@claude-flow/plugin-neural-coordination',
- '@claude-flow/plugin-cognitive-kernel',
'@claude-flow/plugin-quantum-optimizer',
'@claude-flow/plugin-hyperbolic-reasoning',
// Gas Town Bridge
'@claude-flow/plugin-gastown-bridge',
+ // Agent Federation
+ '@claude-flow/plugin-agent-federation',
];
// Fetch stats in parallel