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-intelligence): v0.3.0 β€” surface completeness, 4-step pipeline, IPFS transfer, namespace coordination

Reuven78e5658dfdc6
diff --git a/plugins/ruflo-intelligence/.claude-plugin/plugin.json b/plugins/ruflo-intelligence/.claude-plugin/plugin.json
index 12198026ea..fbb6d9fc12 100644
--- a/plugins/ruflo-intelligence/.claude-plugin/plugin.json
+++ b/plugins/ruflo-intelligence/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-intelligence",
- "description": "Self-learning neural intelligence with SONA patterns, trajectory learning, and intelligent model routing",
- "version": "0.1.0",
+ "description": "User-facing surface for Ruflo's self-learning system: 6 neural_* + 10 hooks_intelligence_* + 9 routing/meta hooks + 4 SONA/MicroLoRA tools (29 total). Implements the 4-step pipeline (RETRIEVE β†’ JUDGE β†’ DISTILL β†’ CONSOLIDATE) and IPFS-based cross-project pattern transfer.",
+ "version": "0.3.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -12,8 +12,15 @@
"ruflo",
"intelligence",
"sona",
+ "microlora",
"neural",
"learning",
- "routing"
+ "routing",
+ "ewc",
+ "attention",
+ "moe",
+ "pattern-transfer",
+ "model-routing",
+ "mcp"
]
}
diff --git a/plugins/ruflo-intelligence/README.md b/plugins/ruflo-intelligence/README.md
index 75fec847c6..e35f0e8fff 100644
--- a/plugins/ruflo-intelligence/README.md
+++ b/plugins/ruflo-intelligence/README.md
@@ -1,8 +1,8 @@
# ruflo-intelligence
-Self-learning neural intelligence with SONA patterns, trajectory learning, and model routing.
+User-facing surface for Ruflo's self-learning system. Wraps **29 intelligence-related MCP tools** across four families into discoverable skills, commands, and the canonical 4-step pipeline (RETRIEVE β†’ JUDGE β†’ DISTILL β†’ CONSOLIDATE). Coordinates with `ruflo-agentdb` (namespace convention), `ruflo-ruvector` (trajectory recording substrate), and `ruflo-browser` (consumes trajectory hooks for session replay).
-Wraps Ruflo's intelligence MCP tools (neural_*, hooks_intelligence_*, hooks_model-*) into skills and commands for Claude Code.
+> **Status:** ADR-0001 implemented. Plugin v0.3.0 targets `@claude-flow/cli` v3.6.x.
## Install
@@ -11,20 +11,133 @@ Wraps Ruflo's intelligence MCP tools (neural_*, hooks_intelligence_*, hooks_mode
/plugin install ruflo-intelligence@ruflo
```
-## Features
+## Compatibility
-- **Neural training**: Train SONA patterns from task completions
-- **Trajectory learning**: Record and learn from multi-step task trajectories
-- **Intelligent routing**: Route tasks to optimal agents and model tiers
-- **Pattern discovery**: Search and store successful patterns via HNSW
-- **EWC++ consolidation**: Prevent catastrophic forgetting across sessions
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-intelligence/scripts/smoke.sh` is the contract.
+
+## Tool inventory
+
+| Family | Count | Source |
+|--------|------:|--------|
+| `neural_*` | 6 | `v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts:195, 312, 413, 539, 651, 706` |
+| `hooks_intelligence_*` (incl. dispatcher + reset) | 10 | `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts:2093, 2226, 2296, 2355, 2404, 2556, 2634, 2741, 2952, 3027` |
+| Routing & meta hooks (`hooks_route`, `hooks_explain`, `hooks_pretrain`, `hooks_build-agents`, `hooks_metrics`, `hooks_transfer`) | 6 | `hooks-tools.ts:884, 1062, 1420, 1499, 1593, 1664` |
+| `hooks_model-*` (3-tier routing) | 3 | `hooks-tools.ts:3797, 3844, 3879` |
+| `ruvllm_sona_*` + `ruvllm_microlora_*` | 4 | `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts:142, 169, 192, 222` |
+| **Total** | **29** | β€” |
+
+## The 4-step intelligence pipeline
+
+CLAUDE.md describes the V3 intelligence loop as four discrete phases. This plugin operationalizes them:
+
+| Step | What happens | Tools |
+|------|--------------|-------|
+| **RETRIEVE** | Pull relevant patterns + past trajectories from HNSW index | `hooks_intelligence_pattern-search`, `agentdb_pattern-search`, `agentdb_semantic-route` |
+| **JUDGE** | Score retrieved candidates with verdicts (success / failure / partial) | `hooks_intelligence_attention`, `neural_predict`, `hooks_explain` |
+| **DISTILL** | Extract the key learnings via LoRA / SONA adaptation | `ruvllm_sona_adapt`, `ruvllm_microlora_adapt`, `neural_train`, `hooks_intelligence_learn` |
+| **CONSOLIDATE** | Prevent catastrophic forgetting via EWC++ | `agentdb_consolidate`, `ruvllm_microlora_adapt --consolidate`, `neural_compress` |
+
+For an end-to-end run:
+
+```
+hooks_pretrain
+ β†’ hooks_intelligence_trajectory-start
+ β†’ (each step) hooks_intelligence_trajectory-step
+ β†’ hooks_intelligence_trajectory-end
+ β†’ hooks_intelligence_learn
+ β†’ ruvllm_sona_adapt # DISTILL
+ β†’ agentdb_consolidate # CONSOLIDATE
+ β†’ neural_compress # storage efficiency
+```
+
+## Cross-project pattern transfer (IPFS)
+
+`hooks_transfer` is the substrate plugin's most underused capability. It publishes learned patterns to IPFS (via Pinata) so a different project β€” or a different machine β€” can fetch and apply them. Use the `intelligence-transfer` skill or call directly:
+
+```bash
+# Publish patterns from this project to IPFS
+mcp tool call hooks_transfer --json -- '{"action": "store", "patterns": [...]}'
+
+# Fetch and apply patterns from a CID
+mcp tool call hooks_transfer --json -- '{"action": "load", "cid": "QmXyz..."}'
+
+# Mirror an entire project's patterns
+mcp tool call hooks_transfer --json -- '{"action": "from-project", "source": "/path/to/project"}'
+```
+
+Prerequisite: `PINATA_API_JWT` (or the equivalent endpoint env vars) must be configured. Without it, `hooks_transfer` returns a structured `success: false` with the missing-config error.
+
+## Hook integration
+
+Several Claude Code hooks fire intelligence-side writes:
+
+| Hook | Tool invoked | Target |
+|------|--------------|--------|
+| `pre-task` | `hooks_route` + `hooks_intelligence_pattern-search` | RETRIEVE phase |
+| `post-task --train-neural` | `agentdb_pattern-store` (ReasoningBank) β†’ falls back to `memory_store --namespace pattern` | DISTILL phase, writes to **`pattern`** namespace |
+| `pretrain` (one-shot) | `hooks_pretrain` β†’ seeds `memory_store --namespace patterns` | Bootstrap, writes to **`patterns`** namespace (plural) |
+| Trajectory hooks (ruvector substrate) | `intelligence_trajectory-*` | Recorded by `ruflo-ruvector`; consumed by this plugin's pattern-store |
+
+> **Pluralization gotcha:** ReasoningBank fallback writes to `pattern` (singular). The `pretrain` hook writes to `patterns` (plural). They are *different* namespaces. See `ruflo-agentdb` ADR-0001 Β§"Namespace convention" for the canonical contract.
+
+## Namespace coordination with ruflo-agentdb
+
+This plugin defers to [ruflo-agentdb ADR-0001](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md) for namespace conventions. Three reserved namespaces are read by the intelligence pipeline:
+
+| Namespace | Read by | Source |
+|-----------|---------|--------|
+| `pattern` | `hooks_intelligence_pattern-search`, `agentdb_pattern-search` | ReasoningBank fallback target |
+| `patterns` (plural) | `hooks_pretrain`, `neural_train` corpus | distinct from `pattern` |
+| `claude-memories` | `memory_search_unified` (default include) | Claude Code auto-memory bridge |
+
+Do **not** invent new top-level namespaces for intelligence purposes β€” the convention is owned upstream.
+
+## EWC++ consolidation
+
+The plugin claims EWC++ consolidation; here's how to actually invoke it:
+
+1. **At trajectory end**, call `hooks_intelligence_learn` to register the outcome.
+2. **Periodically** (or after N task completions), call `agentdb_consolidate` to fold patterns into the long-term store under EWC++ semantics.
+3. **For SONA / MicroLoRA adapters specifically**, call `ruvllm_microlora_adapt` with the `--consolidate` flag to apply Elastic Weight Consolidation on the adapter's weight deltas. This prevents catastrophic forgetting when the adapter is trained on a new domain.
+
+Without these calls, fresh trajectories overwrite older patterns without protection β€” the system "forgets". The pipeline diagram above bakes consolidation into step 4 deliberately.
+
+## MoE (Mixture of Experts) routing
+
+`hooks_intelligence` accepts a `mode` parameter that selects the active learning architecture:
+
+| Mode | When to use |
+|------|-------------|
+| `balanced` (default) | General-purpose: SONA + HNSW retrieval, no MoE specialization |
+| `sona` | Single-domain specialization with SONA adaptation |
+| `moe` | Multi-domain expert routing β€” recommended when tasks span 3+ distinct domains |
+| `hnsw` | Pure pattern retrieval, no online adaptation |
+
+Configure once via `mcp tool call hooks_intelligence -- '{"mode": "moe", "enableSona": true}'` and let the dispatcher route subsequent learning calls.
## Commands
-- `/intelligence` -- View intelligence dashboard and stats
-- `/neural` -- Neural training and prediction commands
+- `/intelligence` β€” Dashboard: stats, metrics, model-tier distribution, routing rationale on demand
+- `/neural` β€” Neural training and prediction (`train`, `status`, `patterns`, `predict`, `optimize`, `compress`)
## Skills
-- `neural-train` -- Train SONA neural patterns from successful tasks
-- `intelligence-route` -- Route tasks using learned patterns and confidence scoring
+- `neural-train` β€” Train SONA + MicroLoRA patterns from successful tasks
+- `intelligence-route` β€” Route tasks using learned patterns; produces a `hooks_explain` rationale
+- `intelligence-transfer` β€” Publish/fetch patterns via IPFS (`hooks_transfer`)
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” Optimize ruflo-intelligence (surface completeness, 4-step pipeline, IPFS transfer, namespace coordination)](./docs/adrs/0001-intelligence-surface-completeness.md)
+
+## Related Plugins
+
+- `ruflo-agentdb` β€” substrate for HNSW + namespace contract; `agentdb_pattern-*` is this plugin's storage backend
+- `ruflo-ruvector` β€” trajectory hooks substrate; `intelligence_trajectory-*` calls land in ruvector's persisted trajectories
+- `ruflo-browser` β€” consumes trajectory hooks for session replay (ADR-0001 there)
+- `ruflo-daa` β€” Dynamic Agentic Architecture; cognitive patterns feed routing as inputs
+
+## License
+
+MIT
diff --git a/plugins/ruflo-intelligence/agents/intelligence-specialist.md b/plugins/ruflo-intelligence/agents/intelligence-specialist.md
index ad7f4be378..b3c9f4ed63 100644
--- a/plugins/ruflo-intelligence/agents/intelligence-specialist.md
+++ b/plugins/ruflo-intelligence/agents/intelligence-specialist.md
@@ -1,41 +1,106 @@
---
name: intelligence-specialist
-description: Self-learning intelligence specialist focused on neural training, pattern discovery, and routing optimization
+description: Self-learning intelligence specialist β€” drives the 4-step pipeline (RETRIEVE β†’ JUDGE β†’ DISTILL β†’ CONSOLIDATE) across 29 MCP tools, coordinates with ruflo-agentdb namespaces, and ships patterns cross-project via IPFS
model: sonnet
---
-You are an intelligence specialist for the Ruflo self-learning system. Your responsibilities:
+You are an intelligence specialist for the Ruflo self-learning system. You drive the **4-step pipeline** β€” RETRIEVE, JUDGE, DISTILL, CONSOLIDATE β€” across 29 MCP tools and coordinate with the substrate plugins (`ruflo-agentdb` for namespaced storage, `ruflo-ruvector` for trajectory recording).
-1. **Train neural patterns** from successful task completions using SONA and MoE
-2. **Discover patterns** by analyzing trajectories and identifying what makes tasks succeed
-3. **Optimize routing** by evaluating model tier recommendations and recording outcomes
-4. **Manage trajectories** by starting, recording steps, and ending learning trajectories
-5. **Consolidate knowledge** using EWC++ to prevent catastrophic forgetting
+## Pipeline responsibilities
-Use these MCP tools:
-- `mcp__claude-flow__neural_train` / `neural_status` / `neural_patterns` / `neural_predict`
-- `mcp__claude-flow__hooks_intelligence_*` for trajectory and pattern management
-- `mcp__claude-flow__hooks_route` / `hooks_model-route` for routing
-- `mcp__claude-flow__ruvllm_sona_*` for SONA adaptation
+| Step | Goal | Primary tools |
+|------|------|---------------|
+| RETRIEVE | Pull relevant patterns + trajectories from HNSW | `hooks_intelligence_pattern-search`, `agentdb_pattern-search`, `agentdb_semantic-route` |
+| JUDGE | Score candidates with verdicts | `hooks_intelligence_attention`, `neural_predict`, `hooks_explain` |
+| DISTILL | Extract learnings via SONA / MicroLoRA | `ruvllm_sona_adapt`, `ruvllm_microlora_adapt`, `neural_train`, `hooks_intelligence_learn` |
+| CONSOLIDATE | Prevent catastrophic forgetting | `agentdb_consolidate`, `ruvllm_microlora_adapt --consolidate`, `neural_compress` |
-Always record outcomes so the system learns from every interaction.
+## Tool routing matrix
-### Memory Learning
+| User intent | Tool |
+|-------------|------|
+| Get a routing recommendation | `hooks_route` (agent type) + `hooks_model-route` (Haiku/Sonnet/Opus) |
+| Explain a routing decision after the fact | `hooks_explain` |
+| View intelligence stats / metrics | `hooks_intelligence_stats`, `hooks_metrics`, `neural_status` |
+| Reset intelligence state (testing) | `hooks_intelligence-reset` |
+| Bootstrap learning from the repo | `hooks_pretrain` |
+| Generate optimized agent configs from learned patterns | `hooks_build-agents` |
+| Record an outcome to train the router | `hooks_model-outcome` |
+| Search past patterns | `hooks_intelligence_pattern-search` |
+| Store a new pattern | `hooks_intelligence_pattern-store` |
+| Begin a trajectory | `hooks_intelligence_trajectory-start` |
+| Add a step to an active trajectory | `hooks_intelligence_trajectory-step` |
+| End a trajectory with a verdict | `hooks_intelligence_trajectory-end` |
+| Run a learning cycle | `hooks_intelligence_learn` |
+| Configure attention mode | `hooks_intelligence_attention` |
+| Train neural patterns | `neural_train` (`--pattern-type`, `--epochs`) |
+| Predict outcome for a task | `neural_predict` |
+| List learned patterns | `neural_patterns` |
+| Compress patterns for storage | `neural_compress` |
+| Optimize the neural pipeline | `neural_optimize` |
+| Create a SONA instance | `ruvllm_sona_create` |
+| Adapt SONA weights from feedback | `ruvllm_sona_adapt` |
+| Create a MicroLoRA adapter | `ruvllm_microlora_create` |
+| Adapt + consolidate a MicroLoRA adapter | `ruvllm_microlora_adapt --consolidate` |
+| Publish learned patterns to IPFS | `hooks_transfer --action store` |
+| Fetch patterns from IPFS by CID | `hooks_transfer --action load` |
+
+## Namespace contract (read this before storing anything)
+
+This plugin **does not** invent namespaces. The convention is owned by `ruflo-agentdb` ADR-0001:
+
+- `pattern` (singular) β€” ReasoningBank fallback target. Read by `hooks_intelligence_pattern-search` / `agentdb_pattern-search`.
+- `patterns` (plural) β€” pretrain corpus, neural training input. Distinct namespace; pluralization is intentional.
+- `claude-memories` β€” Claude Code auto-memory bridge. Don't write directly; SessionStart hook handles it.
+
+Do not pass `namespace: 'foo'` to `hooks_intelligence_pattern-*` or `agentdb_pattern-*` β€” those tools route by ReasoningBank, not by namespace string. Namespace strings only apply to `memory_*` and `embeddings_search`.
+
+## MoE mode selection
+
+`hooks_intelligence` accepts a `mode` parameter:
+
+- `balanced` (default) β€” SONA + HNSW retrieval, no MoE specialization
+- `sona` β€” single-domain SONA-only adaptation
+- `moe` β€” multi-domain expert routing (use when tasks span β‰₯3 distinct domains)
+- `hnsw` β€” pure pattern retrieval, no online adaptation
+
+## EWC++ in practice
+
+The plugin claims EWC++ consolidation. In code that means:
+
+1. After `hooks_intelligence_trajectory-end`, call `hooks_intelligence_learn`.
+2. Every N task completions (β‰₯10 is reasonable), call `agentdb_consolidate`.
+3. For SONA / MicroLoRA adapters, call `ruvllm_microlora_adapt --consolidate` to apply EWC++ on the adapter's weight deltas.
+
+Skip these and the system forgets.
+
+## Cross-project pattern transfer
+
+For sharing learned patterns across machines or projects:
-Store routing outcomes for continuous improvement:
```bash
-npx @claude-flow/cli@latest memory store --namespace routing-outcomes --key "route-TASK_TYPE" --value "MODEL_AND_OUTCOME"
-npx @claude-flow/cli@latest memory search --query "routing for TASK_TYPE" --namespace routing-outcomes
+# Publish current project's patterns to IPFS
+mcp tool call hooks_transfer --json -- '{"action": "store"}'
+
+# Pull a peer's patterns from IPFS by CID
+mcp tool call hooks_transfer --json -- '{"action": "load", "cid": "Qm..."}'
```
-### Related Plugins
+Requires `PINATA_API_JWT` configured. The `intelligence-transfer` skill walks the full flow.
+
+## Related Plugins
-- **ruflo-agentdb**: HNSW-indexed pattern storage backing the intelligence pipeline's RETRIEVE step
-- **ruflo-daa**: Dynamic Agentic Architecture β€” cognitive patterns that feed into intelligence routing
+- **ruflo-agentdb** β€” HNSW-indexed pattern storage backing the RETRIEVE step; namespace contract owner
+- **ruflo-ruvector** β€” trajectory recording substrate; `intelligence_trajectory-*` writes land here
+- **ruflo-browser** β€” uses trajectory hooks for session replay (ADR-0001 there)
+- **ruflo-daa** β€” Dynamic Agentic Architecture cognitive patterns feed into routing
-### Neural Learning
+## After-task hook
+
+Always close the loop after a task completes:
-After completing tasks, feed the pattern-discovery learning loop so the next RETRIEVE benefits from this run:
```bash
npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true
```
+
+This calls `agentdb_pattern-store` (ReasoningBank β€” writes to `pattern` with `memory-store-fallback` if registry is unavailable) and feeds the DISTILL phase.
diff --git a/plugins/ruflo-intelligence/commands/intelligence.md b/plugins/ruflo-intelligence/commands/intelligence.md
index 6b2ad64a4a..e0d3e824a5 100644
--- a/plugins/ruflo-intelligence/commands/intelligence.md
+++ b/plugins/ruflo-intelligence/commands/intelligence.md
@@ -1,11 +1,25 @@
---
name: intelligence
-description: View intelligence system status, learned patterns, and routing stats
+description: Intelligence dashboard -- stats, metrics, model routing, routing rationale on demand
---
Show the intelligence system dashboard:
-1. Call `mcp__claude-flow__hooks_intelligence_stats` to get pattern counts, trajectory history, and learning metrics
-2. Call `mcp__claude-flow__neural_status` to get SONA/MoE state
-3. Call `mcp__claude-flow__hooks_model-stats` to get model routing statistics
-4. Present a summary table with pattern count, success rate, active trajectories, and model tier distribution
+1. Call `mcp__claude-flow__hooks_intelligence_stats` to get pattern counts, trajectory history, and SONA learning state.
+2. Call `mcp__claude-flow__hooks_metrics` to get the metrics dashboard (trajectory throughput, learn-cycle latency, pattern delta).
+3. Call `mcp__claude-flow__hooks_model-stats` for 3-tier model routing distribution (Tier 1 booster / Tier 2 Haiku / Tier 3 Sonnet/Opus).
+4. Call `mcp__claude-flow__neural_status` for neural pattern + SONA / MoE state.
+5. **(Optional `--why <task>`)** β€” Call `mcp__claude-flow__hooks_explain` with the task to get the routing rationale.
+
+Present a summary table:
+- Pattern count + active trajectories (from intelligence_stats)
+- Tier distribution % (from model-stats)
+- Last consolidation timestamp (from neural_status / intelligence_stats)
+- Recent metric deltas (from hooks_metrics)
+- Routing rationale paragraph (only when `--why` given)
+
+If patterns are stale, suggest:
+```bash
+mcp tool call hooks_pretrain --json
+mcp tool call agentdb_consolidate --json
+```
diff --git a/plugins/ruflo-intelligence/commands/neural.md b/plugins/ruflo-intelligence/commands/neural.md
index ebe06ad3c5..26b0dd97fc 100644
--- a/plugins/ruflo-intelligence/commands/neural.md
+++ b/plugins/ruflo-intelligence/commands/neural.md
@@ -1,14 +1,15 @@
---
name: neural
-description: Neural pattern training and prediction commands
+description: Neural pattern training, prediction, compression, and pipeline optimization
---
-Neural system commands:
+Neural system commands β€” dispatch by subcommand parsed from the user's input:
-1. Parse the user's subcommand (train, status, patterns, predict, optimize)
-2. For **train**: call `mcp__claude-flow__neural_train` with pattern-type and epochs
-3. For **status**: call `mcp__claude-flow__neural_status`
-4. For **patterns**: call `mcp__claude-flow__neural_patterns` to list learned patterns
-5. For **predict**: call `mcp__claude-flow__neural_predict` with the task description
-6. For **optimize**: call `mcp__claude-flow__neural_optimize`
-7. Present results in a clear format
+1. **train** β€” `mcp__claude-flow__neural_train` with `--pattern-type` (`coordination|edit|task`) and `--epochs N`.
+2. **status** β€” `mcp__claude-flow__neural_status` (SONA + MoE state, active patterns, training in flight).
+3. **patterns** β€” `mcp__claude-flow__neural_patterns` to list learned patterns; supports `--list` and `--filter`.
+4. **predict** β€” `mcp__claude-flow__neural_predict` with `--input "<task description>"` to get a predicted outcome.
+5. **optimize** β€” `mcp__claude-flow__neural_optimize` to retune the pipeline based on recent outcomes.
+6. **compress** β€” `mcp__claude-flow__neural_compress` to compact stored patterns (storage efficiency, runs after consolidation).
+
+Present results clearly. For `train`, surface the loss curve summary; for `predict`, show the predicted agent + confidence; for `optimize`/`compress`, show before/after counts.
diff --git a/plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md b/plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md
new file mode 100644
index 0000000000..dab68b9f98
--- /dev/null
+++ b/plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md
@@ -0,0 +1,171 @@
+---
+id: ADR-0001
+title: Optimize ruflo-intelligence β€” surface completeness, 4-step pipeline, IPFS pattern transfer, namespace coordination with ruflo-agentdb
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, intelligence, sona, microlora, moe, ewc, hnsw, hooks, transfer, namespace, smoke-test]
+---
+
+## Context
+
+### Today's `ruflo-intelligence`
+
+The plugin (v0.1.0) wraps "intelligence" capabilities loosely. Six files:
+
+- `.claude-plugin/plugin.json:4` β€” `version: "0.1.0"`, keywords `intelligence, sona, neural, learning, routing`
+- `README.md:5` β€” claims wrapping of `neural_*`, `hooks_intelligence_*`, `hooks_model-*` MCP families. No tool inventory or count.
+- `agents/intelligence-specialist.md:15-19` β€” names four tool prefixes (`neural_*`, `hooks_intelligence_*`, `hooks_route`/`hooks_model-route`, `ruvllm_sona_*`)
+- `commands/intelligence.md` β€” calls `hooks_intelligence_stats`, `neural_status`, `hooks_model-stats` only
+- `commands/neural.md` β€” dispatches `neural_train`/`status`/`patterns`/`predict`/`optimize`
+- `skills/intelligence-route/SKILL.md:5` β€” `allowed-tools` enumerates 8 tools
+- `skills/neural-train/SKILL.md:5` β€” `allowed-tools` enumerates 13 tools
+
+### What the CLI actually exposes (verified on 2026-05-04)
+
+Counted directly from source:
+
+| Family | Plugin coverage | Real count | Source |
+|--------|-----------------|------------|--------|
+| `neural_*` | 5 of 6 | **6** (`neural_train`, `neural_predict`, `neural_patterns`, `neural_compress`, `neural_status`, `neural_optimize`) | `v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts:195, 312, 413, 539, 651, 706` |
+| `hooks_intelligence_*` (and dispatcher / reset) | 6 of 10 | **10** (`hooks_intelligence`, `hooks_intelligence-reset`, `hooks_intelligence_trajectory-start/step/end`, `hooks_intelligence_pattern-store`, `hooks_intelligence_pattern-search`, `hooks_intelligence_stats`, `hooks_intelligence_learn`, `hooks_intelligence_attention`) | `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts:2093, 2226, 2296, 2355, 2404, 2556, 2634, 2741, 2952, 3027` |
+| Routing & meta hooks (`hooks_route`, `hooks_explain`, `hooks_pretrain`, `hooks_build-agents`, `hooks_metrics`, `hooks_transfer`) | 1 of 6 (only `hooks_route`) | **6** | `hooks-tools.ts:884, 1062, 1420, 1499, 1593, 1664` |
+| `hooks_model-*` | 2 of 3 | **3** (`hooks_model-route`, `hooks_model-outcome`, `hooks_model-stats`) | `hooks-tools.ts:3797, 3844, 3879` |
+| `ruvllm_sona_*` + `ruvllm_microlora_*` | 2 of 4 (only sona_create / sona_adapt) | **4** | `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts:142, 169, 192, 222` |
+| **Total** | ~14 of **29** | **29** | β€” |
+
+The plugin documents roughly half the intelligence-related surface that the CLI actually exposes. Specifically missing or underspecified:
+
+- **`hooks_intelligence_attention`** β€” attention-mechanism dispatch (the same primitive `ruflo-ruvector` surfaces via `attention list`). Plugin makes no mention.
+- **`hooks_intelligence_learn`** β€” the "learn from outcomes" tool, the heart of the self-learning loop.
+- **`hooks_intelligence-reset`** β€” clears intelligence state. Useful for testing and fresh runs.
+- **`hooks_metrics`** β€” metrics dashboard. Plugin's `/intelligence` command should call it.
+- **`hooks_explain`** β€” routing-decision rationale. Critical for trust ("why did the system pick this agent?").
+- **`hooks_build-agents`** β€” generates optimized agent configs from learned patterns.
+- **`hooks_transfer`** β€” **IPFS-based pattern transfer between projects**. Genuine differentiator, totally invisible in the plugin.
+- **`ruvllm_microlora_create` / `ruvllm_microlora_adapt`** β€” MicroLoRA adaptation. Plugin only mentions SONA.
+- **`neural_compress`** β€” neural-pattern compression for storage efficiency.
+
+### What's claimed but unsurfaced
+
+`README.md:20` claims **"EWC++ consolidation"** as a feature. The plugin nowhere says how to invoke it. The actual EWC++ semantic lives in `agentdb_consolidate` and `ruvllm_microlora_adapt --consolidate` (per the ruvector adaptive embedder). The plugin should map the feature claim to the tool that delivers it.
+
+`agents/intelligence-specialist.md:9` mentions **"SONA and MoE"**. SONA gets two tool calls; MoE gets none. `hooks_intelligence` accepts `enableMoe` and `mode`, but the plugin never tells you the modes (`balanced`, `sona`, `moe`, `hnsw`).
+
+CLAUDE.md describes the **4-step intelligence pipeline (RETRIEVE β†’ JUDGE β†’ DISTILL β†’ CONSOLIDATE)**. The plugin never surfaces this pipeline in user-facing form, even though it's the conceptual frame the whole substrate revolves around.
+
+### Namespace coordination
+
+`ruflo-agentdb` ADR-0001 (just landed) introduced a namespace convention with three reserved namespaces: `pattern` (ReasoningBank fallback), `claude-memories` (Claude Code bridge), `default`. **The intelligence pipeline writes to `pattern`** (via `agentdb_pattern-store` and the `hooks post-task --train-neural` path). The plugin should explicitly cite the convention so consumers don't reinvent it.
+
+There's also a pluralization gotcha worth surfacing here: ruvector's neural/pretrain hooks write to `patterns` (plural), distinct from ReasoningBank's `pattern`. `ruflo-agentdb` documents this; `ruflo-intelligence` should reference the documentation.
+
+### Why now
+
+`ruflo-intelligence` is the **user-facing** surface for the self-learning system that the rest of the plugin family relies on. Documentation drift here means:
+
+1. Agents that follow the plugin's instructions miss half the available learning loop.
+2. `hooks_transfer`'s IPFS-based cross-project pattern sharing β€” a genuine differentiator β€” is invisible.
+3. The 4-step pipeline is never operationalized; users invoke `neural_train` without understanding RETRIEVE/JUDGE/DISTILL/CONSOLIDATE as distinct steps.
+4. Downstream plugins (`ruflo-browser` ADR-0001 references trajectory recording; `ruflo-agentdb` references `pattern` namespace writes) lose their anchor doc.
+
+We just fixed analogous drift in `ruflo-ruvector` (ADR-0001) and `ruflo-agentdb` (ADR-0001). Same pattern applies here.
+
+## Decision
+
+Six changes. Each is plugin-local; no CLI source modifications.
+
+### 1. Plugin metadata bump and accurate keyword set
+
+`plugin.json` moves `0.1.0 β†’ 0.3.0` (matches the ruflo-agentdb cadence and reflects that this is a **substantial scope expansion**, not a patch). Keywords gain `microlora`, `ewc`, `attention`, `moe`, `pattern-transfer`, `model-routing`, `mcp`. Description rewrites to explicitly enumerate the three families and the IPFS transfer.
+
+### 2. README rewrite β€” surface completeness + 4-step pipeline + IPFS transfer
+
+The README becomes the canonical entry point with these new sections:
+
+- **Tool inventory** (3-family count table: 6 + 10 + 9 + 4 = **29**, with source file:line citations).
+- **The 4-step intelligence pipeline** β€” operationalized as a section that maps each step (RETRIEVE / JUDGE / DISTILL / CONSOLIDATE) to specific tool calls. Aligns with CLAUDE.md but is now verifiable.
+- **Cross-project pattern transfer** β€” `hooks_transfer` documented end-to-end (IPFS publish, fetch, apply). This is the single most undersold capability of the plugin family.
+- **Hook integration** β€” table mapping `post-task --train-neural`, `pretrain`, `pre-task` to which intelligence tools fire. References ruflo-agentdb's reserved namespaces (`pattern` for ReasoningBank, `patterns` for neural-train).
+- **Namespace coordination** β€” explicit deferral to `ruflo-agentdb` ADR-0001 Β§"Namespace convention"; reproduces the pluralization gotcha (`pattern` vs `patterns`).
+- **EWC++ explanation** β€” no longer just a feature claim. Maps to `agentdb_consolidate` and `ruvllm_microlora_adapt --consolidate`.
+- **MoE explanation** β€” `hooks_intelligence` modes (`balanced` / `sona` / `moe` / `hnsw`) enumerated.
+- **Compatibility** β€” pinned to `@claude-flow/cli` v3.6 (matches ruflo-agentdb).
+
+### 3. Agent rewrite β€” tool routing matrix
+
+`agents/intelligence-specialist.md` gains a **routing matrix** that maps user intent to the specific MCP tool: "user wants routing rationale β†’ `hooks_explain`"; "user wants pattern compression β†’ `neural_compress`"; etc. Replaces the bullet list of prefixes with a decision table. Drops the free-form `memory store --namespace routing-outcomes` line (the tools handle this).
+
+### 4. Commands fill in the gaps
+
+- `/intelligence` β€” calls `hooks_intelligence_stats` + `hooks_metrics` + `hooks_model-stats` + `neural_status` + `hooks_explain` (when invoked with a `--why <task>` arg). Becomes a real dashboard, not a 4-step list.
+- `/neural` β€” adds `neural_compress` to the dispatch table.
+
+### 5. Skills
+
+- `intelligence-route/SKILL.md` β€” adds `hooks_explain` as the post-routing rationale step. Updates the 3-tier routing table to match the actual `hooks_model-route` output shape.
+- `neural-train/SKILL.md` β€” adds **MicroLoRA** section (`ruvllm_microlora_create` / `_adapt`) with EWC++ consolidation. Adds `neural_compress` for pattern compaction.
+- **NEW skill `intelligence-transfer`** β€” `hooks_transfer` IPFS workflow. Covers `transfer store`, `transfer load`, `transfer from-project`. This is the single biggest gap in the current plugin.
+
+### 6. Smoke contract
+
+`scripts/smoke.sh` (new file). Structural checks against the documented surface β€” no live MCP calls. The contract:
+
+1. plugin.json declares `0.3.0` with the new keywords.
+2. README has all 4 new sections (tool inventory, 4-step pipeline, IPFS transfer, hook integration, namespace coordination, EWC++ explanation).
+3. All 6 `neural_*` tools referenced somewhere in plugin docs.
+4. All 10 `hooks_intelligence_*`-family tools referenced.
+5. All 6 routing/meta hooks (`hooks_route`, `hooks_explain`, `hooks_pretrain`, `hooks_build-agents`, `hooks_metrics`, `hooks_transfer`) referenced.
+6. All 3 `hooks_model-*` tools referenced.
+7. All 4 SONA + MicroLoRA tools referenced.
+8. The 4-step pipeline section names all four phases.
+9. `intelligence-transfer` skill exists with allowed-tools enumerated and references `hooks_transfer`.
+10. Pluralization gotcha referenced (`pattern` vs `patterns`) β€” defers to ruflo-agentdb.
+11. No skill grants wildcard tool access.
+12. ADR file exists with status Proposed.
+13. Compatibility section pins to `@claude-flow/cli` v3.6.
+
+Plus three doc invariants checked by single-line greps:
+
+- `grep -q "4-step intelligence pipeline" plugins/ruflo-intelligence/README.md`
+- `grep -q "hooks_transfer" plugins/ruflo-intelligence/skills/intelligence-transfer/SKILL.md`
+- `grep -qE "RETRIEVE.+JUDGE.+DISTILL.+CONSOLIDATE" plugins/ruflo-intelligence/README.md`
+
+## Consequences
+
+**Positive:**
+
+- Every documented capability claim maps to a verifiable MCP tool. No more "EWC++ consolidation" as a phantom feature.
+- The 4-step intelligence pipeline (CLAUDE.md's V3 framing) is now operationalized in a user-facing form.
+- IPFS pattern transfer becomes discoverable β€” agents in different projects can share what they've learned.
+- Namespace coordination with `ruflo-agentdb` is explicit; downstream plugins inherit one consistent story.
+- A smoke contract makes future drift catchable in CI.
+
+**Negative:**
+
+- Three downstream agents may currently call the legacy `memory store --namespace routing-outcomes` pattern from the agent file. Updating them is a separate cleanup.
+- The new `intelligence-transfer` skill assumes `hooks_transfer` is wired to a working IPFS endpoint (Pinata or similar). If the endpoint is unconfigured, the skill returns a structured error β€” but agents reading the skill MD may be surprised. We document the prerequisite.
+- Plugin v0.1.0 β†’ v0.3.0 is a two-minor jump. Justified by scope (5 new sections + new skill + smoke + ADR), but consumers tracking strict semver should be aware.
+
+**Neutral:**
+
+- No new MCP tools introduced. All capability is **surfacing** of existing tools.
+- The agent file's "Memory Learning" section (currently writing to a free-form `routing-outcomes` namespace) is replaced. Consumers of that namespace should migrate to `hooks_model-outcome` which is the typed equivalent.
+
+## Verification
+
+```bash
+bash plugins/ruflo-intelligence/scripts/smoke.sh
+# Expected: "16 passed, 0 failed" (13 contract checks + 3 doc invariants)
+```
+
+## Related
+
+- `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md` β€” pinning + smoke-as-contract precedent
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention + reserved namespaces (`pattern`/`claude-memories`/`default`); pluralization gotcha; hook integration table
+- `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md` β€” uses ruvector trajectory hooks (a primary learning input for this plugin)
+- `v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts` β€” 6 neural tool definitions
+- `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts` β€” 19 hooks-family tools (intelligence, route, model, transfer, metrics, explain, pretrain, build-agents)
+- `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts` β€” 4 SONA + MicroLoRA tools
+- CLAUDE.md (V3 Performance Targets + 4-step pipeline framing)
diff --git a/plugins/ruflo-intelligence/scripts/smoke.sh b/plugins/ruflo-intelligence/scripts/smoke.sh
new file mode 100755
index 0000000000..13df187460
--- /dev/null
+++ b/plugins/ruflo-intelligence/scripts/smoke.sh
@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-intelligence v0.3.0.
+# Per ADR-0001 Β§6 Verification: 13 contract checks + 3 doc invariants.
+# Offline-safe; no live MCP calls.
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+REPO_ROOT="$(cd "$ROOT/../.." && 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)); }
+
+# Doc invariants
+step "INV1: README has the 4-step intelligence pipeline section"
+grep -q "4-step intelligence pipeline" "$ROOT/README.md" \
+ && grep -qE "RETRIEVE.+JUDGE.+DISTILL.+CONSOLIDATE" "$ROOT/README.md" \
+ && ok || bad "missing pipeline section or 4-step phase enumeration"
+
+step "INV2: intelligence-transfer skill references hooks_transfer"
+grep -q "hooks_transfer" "$ROOT/skills/intelligence-transfer/SKILL.md" \
+ && ok || bad "intelligence-transfer skill missing hooks_transfer"
+
+step "INV3: README mentions IPFS pattern transfer"
+grep -qE "IPFS.+pattern|pattern.+IPFS|Pinata" "$ROOT/README.md" \
+ && ok || bad "README missing IPFS / Pinata transfer docs"
+
+# 1. plugin.json bump + new keywords
+step "1. plugin.json declares 0.3.0 with new keywords"
+v=$(grep -E '"version"[[:space:]]*:' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.3.0" ]]; then
+ bad "expected 0.3.0, got '$v'"
+else
+ miss=""
+ for k in microlora ewc attention moe pattern-transfer model-routing; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+# 2. README sections present
+step "2. README has all required sections (inventory, pipeline, IPFS, hook integration, namespace, EWC++, MoE)"
+F="$ROOT/README.md"
+miss=""
+grep -q "## Tool inventory" "$F" || miss="$miss inventory"
+grep -q "## The 4-step intelligence pipeline" "$F" || miss="$miss pipeline"
+grep -q "## Cross-project pattern transfer" "$F" || miss="$miss ipfs"
+grep -q "## Hook integration" "$F" || miss="$miss hook-table"
+grep -q "## Namespace coordination" "$F" || miss="$miss namespace-coord"
+grep -q "## EWC++ consolidation" "$F" || miss="$miss ewc"
+grep -q "## MoE" "$F" || miss="$miss moe"
+[[ -z "$miss" ]] && ok || bad "missing:$miss"
+
+# 3. All 6 neural_* tools referenced
+step "3. all 6 neural_* tools referenced in plugin docs"
+miss=""
+for t in neural_train neural_predict neural_patterns neural_compress neural_status neural_optimize; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+# 4. All 10 hooks_intelligence-family tools referenced
+step "4. all 10 hooks_intelligence-family tools referenced"
+miss=""
+for t in hooks_intelligence hooks_intelligence-reset hooks_intelligence_trajectory-start hooks_intelligence_trajectory-step hooks_intelligence_trajectory-end hooks_intelligence_pattern-store hooks_intelligence_pattern-search hooks_intelligence_stats hooks_intelligence_learn hooks_intelligence_attention; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+# 5. All 6 routing/meta hooks referenced
+step "5. all 6 routing/meta hooks referenced (route, explain, pretrain, build-agents, metrics, transfer)"
+miss=""
+for t in hooks_route hooks_explain hooks_pretrain hooks_build-agents hooks_metrics hooks_transfer; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+# 6. All 3 hooks_model-* tools referenced
+step "6. all 3 hooks_model-* tools referenced"
+miss=""
+for t in hooks_model-route hooks_model-outcome hooks_model-stats; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+# 7. SONA + MicroLoRA tools (4) referenced
+step "7. all 4 SONA + MicroLoRA tools referenced"
+miss=""
+for t in ruvllm_sona_create ruvllm_sona_adapt ruvllm_microlora_create ruvllm_microlora_adapt; do
+ grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
+done
+[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
+
+# 8. 4-step pipeline names all four phases
+step "8. 4-step pipeline section names all four phases"
+F="$ROOT/README.md"
+miss=""
+for phase in RETRIEVE JUDGE DISTILL CONSOLIDATE; do
+ grep -q "$phase" "$F" || miss="$miss $phase"
+done
+[[ -z "$miss" ]] && ok || bad "phases not all named:$miss"
+
+# 9. intelligence-transfer skill exists with proper allowed-tools
+step "9. intelligence-transfer skill exists with allowed-tools enumerated"
+F="$ROOT/skills/intelligence-transfer/SKILL.md"
+if [[ -f "$F" ]] \
+ && grep -qE "^allowed-tools:" "$F" \
+ && grep -q "hooks_transfer" "$F"; then
+ ok
+else
+ bad "intelligence-transfer skill missing or incomplete"
+fi
+
+# 10. Pluralization gotcha referenced (defers to ruflo-agentdb)
+step "10. pluralization gotcha (pattern vs patterns) documented"
+F="$ROOT/README.md"
+if grep -q '`pattern`' "$F" \
+ && grep -q '`patterns`' "$F" \
+ && grep -qiE "pluraliz|distinct namespace" "$F"; then
+ ok
+else
+ bad "pluralization gotcha not surfaced (must contrast pattern vs patterns)"
+fi
+
+# 11. No skill grants wildcard tool access
+step "11. no skill grants wildcard tool access"
+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"
+
+# 12. ADR exists, status Proposed
+step "12. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-intelligence-surface-completeness.md"
+if [[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR"; then
+ ok
+else
+ bad "ADR missing or status != Proposed"
+fi
+
+# 13. Compatibility section pins to v3.6
+step "13. Compatibility section pins @claude-flow/cli to v3.6"
+if grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md"; then
+ ok
+else
+ bad "Compatibility pin to v3.6 missing"
+fi
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-intelligence/skills/intelligence-route/SKILL.md b/plugins/ruflo-intelligence/skills/intelligence-route/SKILL.md
index 59db4efa94..067db2354f 100644
--- a/plugins/ruflo-intelligence/skills/intelligence-route/SKILL.md
+++ b/plugins/ruflo-intelligence/skills/intelligence-route/SKILL.md
@@ -1,46 +1,56 @@
---
name: intelligence-route
-description: Route tasks to optimal agents using learned patterns, model recommendations, and confidence scoring
-argument-hint: "<task-description>"
-allowed-tools: mcp__claude-flow__hooks_route mcp__claude-flow__hooks_model-route mcp__claude-flow__hooks_model-stats mcp__claude-flow__hooks_model-outcome mcp__claude-flow__hooks_intelligence_pattern-search mcp__claude-flow__hooks_intelligence_attention mcp__claude-flow__hooks_intelligence_stats mcp__claude-flow__neural_predict mcp__claude-flow__hooks_pre-task Bash
+description: Route tasks via the 3-tier model selector and learned patterns; emits a routing rationale via hooks_explain
+argument-hint: "<task-description> [--why]"
+allowed-tools: mcp__claude-flow__hooks_route mcp__claude-flow__hooks_explain mcp__claude-flow__hooks_model-route mcp__claude-flow__hooks_model-stats mcp__claude-flow__hooks_model-outcome mcp__claude-flow__hooks_intelligence_pattern-search mcp__claude-flow__hooks_intelligence_attention mcp__claude-flow__hooks_intelligence_stats mcp__claude-flow__neural_predict mcp__claude-flow__hooks_pre-task Bash
---
# Intelligence Routing
-Route tasks to the best agent and model based on learned patterns.
+Pick the optimal agent + model tier for a task using learned patterns + the 3-tier router. Emits a `hooks_explain` rationale so the choice is auditable.
## When to use
-Before starting any task, use intelligence routing to get the optimal agent type, model tier, and confidence score. This replaces manual agent selection with data-driven decisions.
+Before starting any non-trivial task. Replaces manual agent selection with data-driven decisions.
## Steps
-1. **Get routing recommendation** β€” call `mcp__claude-flow__hooks_route` with the task description
-2. **Check model recommendation** β€” call `mcp__claude-flow__hooks_model-route` for the optimal model tier (Haiku/Sonnet/Opus)
-3. **Search for similar patterns** β€” call `mcp__claude-flow__hooks_intelligence_pattern-search` to find past successes
-4. **Predict outcome** β€” call `mcp__claude-flow__neural_predict` with the task description
-5. **Spawn the recommended agent** at the recommended model tier
-6. **Record outcome** β€” after task completes, call `mcp__claude-flow__hooks_model-outcome` to train the router
+1. **Get an agent recommendation** β€” `mcp__claude-flow__hooks_route` with the task description. Returns `{ recommended, confidence, reasoning }`.
+2. **Get a model tier recommendation** β€” `mcp__claude-flow__hooks_model-route` for Haiku/Sonnet/Opus selection.
+3. **Search for similar past patterns** β€” `mcp__claude-flow__hooks_intelligence_pattern-search` to find prior successes.
+4. **Predict outcome** β€” `mcp__claude-flow__neural_predict` with the task description for a confidence-scored prediction.
+5. **Spawn the recommended agent** at the recommended model tier.
+6. **(If `--why` was passed)** β€” call `mcp__claude-flow__hooks_explain` to surface the routing rationale to the user.
+7. **After task completes** β€” call `mcp__claude-flow__hooks_model-outcome` with `success: true|false` to train the router.
## 3-Tier Model Routing
-| Tier | Handler | When |
-|------|---------|------|
-| 1 | Agent Booster (WASM) | Simple transforms β€” skip LLM entirely |
-| 2 | Haiku | Low complexity tasks (<30%) |
-| 3 | Sonnet/Opus | Complex reasoning, architecture, security |
+| Tier | Handler | Latency | Cost | When |
+|------|---------|---------|------|------|
+| 1 | Agent Booster (WASM) | <1ms | $0 | Simple transforms (var→const, add types, remove console) — skip LLM entirely |
+| 2 | Haiku | ~500ms | ~$0.0002 | Low complexity (<30%), bug fixes, quick patches |
+| 3 | Sonnet/Opus | 2–5s | $0.003–$0.015 | Complex reasoning, architecture, security, multi-file refactors |
-## CLI alternative
+When `hooks_route` returns `[AGENT_BOOSTER_AVAILABLE]` for an intent type (`var-to-const`, `add-types`, `add-error-handling`, `async-await`, `add-logging`, `remove-console`), skip the LLM and use the Edit tool directly.
+
+## Recording outcomes
+
+Closing the routing loop is mandatory:
```bash
-npx @claude-flow/cli@latest hooks route --task "description"
-npx @claude-flow/cli@latest hooks pre-task --description "description"
-npx @claude-flow/cli@latest hooks explain --topic "routing decision"
+# Success
+mcp tool call hooks_model-outcome --json -- '{"taskId": "T123", "success": true, "model": "haiku"}'
+
+# Failure with reason
+mcp tool call hooks_model-outcome --json -- '{"taskId": "T123", "success": false, "model": "haiku", "reason": "complexity-misjudged"}'
```
-## Viewing intelligence stats
+The router learns from these calls. Skipping them = no learning.
+
+## CLI alternative
-Call `mcp__claude-flow__hooks_intelligence_stats` or:
```bash
-npx @claude-flow/cli@latest hooks intelligence stats
+npx @claude-flow/cli@latest hooks route --task "description"
+npx @claude-flow/cli@latest hooks pre-task --description "description"
+npx @claude-flow/cli@latest hooks explain --topic "routing decision"
```
diff --git a/plugins/ruflo-intelligence/skills/intelligence-transfer/SKILL.md b/plugins/ruflo-intelligence/skills/intelligence-transfer/SKILL.md
new file mode 100644
index 0000000000..2b60c9677c
--- /dev/null
+++ b/plugins/ruflo-intelligence/skills/intelligence-transfer/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: intelligence-transfer
+description: Publish or fetch learned patterns across projects via IPFS (Pinata) -- the cross-project pattern transfer that hooks_transfer enables
+argument-hint: "<store|load|from-project> [--cid <ipfs-cid>] [--source <project-path>]"
+allowed-tools: mcp__claude-flow__hooks_transfer mcp__claude-flow__hooks_intelligence_pattern-search mcp__claude-flow__hooks_intelligence_pattern-store mcp__claude-flow__neural_patterns mcp__claude-flow__neural_status Bash
+---
+
+# Intelligence Transfer
+
+Cross-project pattern sharing via IPFS. Lets a different project β€” or a different machine β€” fetch and apply patterns this project has already learned.
+
+## Why this exists
+
+Most learning is project-local. `hooks_transfer` is the escape hatch: publish patterns to IPFS, share the CID, and any peer can ingest them. Equivalent to "a deploy artifact for what your agents have learned."
+
+## Prerequisite
+
+```bash
+# Required env var (or equivalent endpoint config)
+echo $PINATA_API_JWT
+```
+
+If unset, `hooks_transfer` returns a structured `success: false` with `error: "PINATA_API_JWT not configured"`. Configure before running this skill.
+
+## Workflows
+
+### Publish current project's patterns
+
+```bash
+# Inspect what's stored locally first
+mcp tool call neural_patterns --json -- '{"list": true}'
+
+# Publish to IPFS β€” returns a CID
+mcp tool call hooks_transfer --json -- '{"action": "store"}'
+```
+
+The response includes the IPFS CID. Save it; share it with peers who need the patterns.
+
+### Fetch + apply a peer's patterns
+
+```bash
+# Pull a CID and apply locally
+mcp tool call hooks_transfer --json -- '{"action": "load", "cid": "QmXyz..."}'
+
+# Verify they landed
+mcp tool call hooks_intelligence_pattern-search --json -- '{"query": "<test>", "limit": 5}'
+```
+
+Patterns are merged with local state, not replaced. Conflicts are resolved by recency (newer wins).
+
+### Mirror an entire project's patterns
+
+```bash
+# Read patterns from a sibling project on disk and republish under a new CID
+mcp tool call hooks_transfer --json -- '{"action": "from-project", "source": "/path/to/peer-project"}'
+```
+
+Useful for consolidating learnings across a monorepo or a fleet of related projects.
+
+## When to use this skill
+
+- **Before a fresh project starts** β€” fetch the relevant patterns from a parent project so the new project's agents start with prior knowledge instead of cold.
+- **After a major learning milestone** β€” publish so other projects benefit.
+- **When debugging a regression** β€” fetch a known-good pattern set to compare against.
+
+## When NOT to use
+
+- Daily β€” it's a heavyweight operation. `agentdb_consolidate` does the local equivalent.
+- For sensitive patterns β€” IPFS is public by default. Pinata pinning does NOT make patterns private. Strip PII (use `aidefence_has_pii` first) before publishing.
+
+## Caveats
+
+- IPFS CIDs are content-addressed; republishing the same pattern set gives you the same CID.
+- Patterns are stored as JSON; they include only the embedding hashes + metadata, not raw text. Decoding requires the same SONA / MicroLoRA adapter version that produced them.
+- This skill does NOT publish AgentDB rows β€” only the intelligence-side patterns. To ship full memory, use `agentdb_*` export tools (out of scope here).
+
+## Related
+
+- `ruflo-agentdb` ADR-0001 Β§"Namespace convention" β€” defines `pattern` namespace that this transfer reads from
+- `neural-train` skill β€” produces the patterns that this skill ships
diff --git a/plugins/ruflo-intelligence/skills/neural-train/SKILL.md b/plugins/ruflo-intelligence/skills/neural-train/SKILL.md
index 8b14ebef42..c53cb7f5cf 100644
--- a/plugins/ruflo-intelligence/skills/neural-train/SKILL.md
+++ b/plugins/ruflo-intelligence/skills/neural-train/SKILL.md
@@ -1,39 +1,94 @@
---
name: neural-train
-description: Train SONA neural patterns from successful task completions, view learned patterns, and optimize the intelligence pipeline
-argument-hint: "[--pattern-type coordination|edit|task] [--epochs N]"
-allowed-tools: mcp__claude-flow__neural_train mcp__claude-flow__neural_status mcp__claude-flow__neural_patterns mcp__claude-flow__neural_predict mcp__claude-flow__neural_optimize mcp__claude-flow__neural_compress mcp__claude-flow__hooks_pretrain mcp__claude-flow__hooks_intelligence_trajectory-start mcp__claude-flow__hooks_intelligence_trajectory-step mcp__claude-flow__hooks_intelligence_trajectory-end mcp__claude-flow__hooks_intelligence_pattern-store mcp__claude-flow__hooks_intelligence_learn mcp__claude-flow__ruvllm_sona_create mcp__claude-flow__ruvllm_sona_adapt Bash
+description: Train SONA + MicroLoRA neural patterns from successful task completions; runs the DISTILL + CONSOLIDATE phases of the 4-step pipeline
+argument-hint: "[--pattern-type coordination|edit|task] [--epochs N] [--microlora]"
+allowed-tools: mcp__claude-flow__neural_train mcp__claude-flow__neural_status mcp__claude-flow__neural_patterns mcp__claude-flow__neural_predict mcp__claude-flow__neural_optimize mcp__claude-flow__neural_compress mcp__claude-flow__hooks_pretrain mcp__claude-flow__hooks_build-agents mcp__claude-flow__hooks_intelligence_trajectory-start mcp__claude-flow__hooks_intelligence_trajectory-step mcp__claude-flow__hooks_intelligence_trajectory-end mcp__claude-flow__hooks_intelligence_pattern-store mcp__claude-flow__hooks_intelligence_learn mcp__claude-flow__hooks_intelligence-reset mcp__claude-flow__ruvllm_sona_create mcp__claude-flow__ruvllm_sona_adapt mcp__claude-flow__ruvllm_microlora_create mcp__claude-flow__ruvllm_microlora_adapt mcp__claude-flow__agentdb_consolidate Bash
---
# Neural Training
-Train and manage SONA neural patterns for self-learning.
+Train and consolidate neural patterns. Implements the **DISTILL** and **CONSOLIDATE** phases of the 4-step intelligence pipeline.
## When to use
-After completing a successful task, use this skill to capture what worked and train the intelligence system so future tasks benefit from learned patterns.
+- After completing a successful task β€” capture what worked.
+- After accumulating β‰₯10 task completions β€” run consolidation to fold patterns into long-term storage.
+- When training a new domain β€” create a MicroLoRA adapter for it.
-## Steps
+## Standard flow (DISTILL)
-1. **Check current neural status** β€” call `mcp__claude-flow__neural_status` to see active patterns and training state
-2. **Start a trajectory** β€” call `mcp__claude-flow__hooks_intelligence_trajectory-start` with the task context
-3. **Record steps** β€” for each significant action, call `mcp__claude-flow__hooks_intelligence_trajectory-step`
-4. **End trajectory** β€” call `mcp__claude-flow__hooks_intelligence_trajectory-end` with outcome (success/failure)
-5. **Train patterns** β€” call `mcp__claude-flow__neural_train` with `--pattern-type coordination --epochs 10`
-6. **Store patterns** β€” call `mcp__claude-flow__hooks_intelligence_pattern-store` to persist learnings
-7. **Verify** β€” call `mcp__claude-flow__neural_patterns` to confirm patterns were stored
+1. **Check current neural status** β€” `mcp__claude-flow__neural_status`.
+2. **Start a trajectory** β€” `mcp__claude-flow__hooks_intelligence_trajectory-start` with the task context.
+3. **Record steps** β€” for each significant action, `mcp__claude-flow__hooks_intelligence_trajectory-step`.
+4. **End trajectory** β€” `mcp__claude-flow__hooks_intelligence_trajectory-end` with `verdict: pass|fail|partial`.
+5. **Learn from the trajectory** β€” `mcp__claude-flow__hooks_intelligence_learn`.
+6. **Train patterns** β€” `mcp__claude-flow__neural_train` with `--pattern-type coordination --epochs 10`.
+7. **Store patterns** β€” `mcp__claude-flow__hooks_intelligence_pattern-store`.
+8. **Verify** β€” `mcp__claude-flow__neural_patterns` to confirm.
-## CLI alternative
+## SONA adaptation (single-domain, <0.05ms)
+
+For real-time micro-adaptation:
+
+```bash
+mcp tool call ruvllm_sona_create --json -- '{"domain": "coding"}'
+mcp tool call ruvllm_sona_adapt --json -- '{"feedback": {"score": 0.9, "trajectory": "..."}}'
+```
+
+## MicroLoRA adaptation (multi-domain)
+
+When you have β‰₯3 distinct domains, create a MicroLoRA adapter per domain rather than overloading SONA:
+
+```bash
+# Create the adapter
+mcp tool call ruvllm_microlora_create --json -- '{"domain": "frontend"}'
+
+# Adapt with feedback
+mcp tool call ruvllm_microlora_adapt --json -- '{"adapter": "frontend", "feedback": {...}}'
+
+# CONSOLIDATE phase: apply EWC++ on weight deltas to prevent catastrophic forgetting
+mcp tool call ruvllm_microlora_adapt --json -- '{"adapter": "frontend", "consolidate": true}'
+```
+
+The `--consolidate` flag is the EWC++ trigger. Without it, fresh training overwrites older domains.
+
+## CONSOLIDATE phase (separate from training)
+
+After every ~10 trajectory completions, run a full consolidation pass:
+
+```bash
+mcp tool call agentdb_consolidate --json
+mcp tool call neural_compress --json # storage efficiency
+```
+
+This folds patterns into long-term storage under EWC++ semantics.
+
+## Bootstrapping from scratch
+
+If the system has no learned patterns yet:
+
+```bash
+mcp tool call hooks_pretrain --json -- '{"modelType": "moe", "epochs": 10}'
+mcp tool call hooks_build-agents --json -- '{"agentTypes": "coder,tester"}'
+```
+
+`hooks_pretrain` writes to the `patterns` (plural) namespace β€” distinct from the `pattern` (singular) ReasoningBank target. See `ruflo-agentdb` ADR-0001 for the namespace convention.
+
+## Reset (testing only)
+
+To wipe intelligence state (e.g., for benchmarking):
+
+```bash
+mcp tool call hooks_intelligence-reset --json
+```
+
+## CLI alternatives
```bash
npx @claude-flow/cli@latest neural train --pattern-type coordination --epochs 10
npx @claude-flow/cli@latest neural patterns --list
npx @claude-flow/cli@latest neural status
+npx @claude-flow/cli@latest neural compress
npx @claude-flow/cli@latest hooks pretrain --model-type moe --epochs 10
+npx @claude-flow/cli@latest hooks build-agents --agent-types coder,tester
```
-
-## SONA adaptation
-
-For real-time micro-adaptation (<0.05ms), use:
-- `mcp__claude-flow__ruvllm_sona_create` to initialize a SONA instance
-- `mcp__claude-flow__ruvllm_sona_adapt` to adapt weights based on feedback