agentic-flow 2.0.1-alpha.5 → 2.0.1-alpha.50

package/.claude/settings.json

@@ -5,14 +5,125 @@
     "CLAUDE_FLOW_HOOKS_ENABLED": "true",
     "CLAUDE_FLOW_TELEMETRY_ENABLED": "true",
     "CLAUDE_FLOW_REMOTE_EXECUTION": "true",
-    "CLAUDE_FLOW_CHECKPOINTS_ENABLED": "true"
+    "CLAUDE_FLOW_CHECKPOINTS_ENABLED": "true",
+    "CLAUDE_FLOW_WORKERS_ENABLED": "true",
+    "CLAUDE_FLOW_WORKER_PARALLEL": "true",
+    "CLAUDE_FLOW_MODEL_CACHE_MB": "512",
+    "CLAUDE_FLOW_SUPPRESS_WARNINGS": "true"
+  },
+  "workers": {
+    "enabled": true,
+    "parallel": true,
+    "maxConcurrent": 10,
+    "maxPerTrigger": 3,
+    "defaultTimeout": 300000,
+    "memoryDepositEnabled": true,
+    "progressEventsEnabled": true,
+    "triggers": {
+      "ultralearn": { "priority": "high", "timeout": 300000, "maxAgents": 5 },
+      "optimize": { "priority": "medium", "timeout": 180000, "maxAgents": 2 },
+      "consolidate": { "priority": "low", "timeout": 120000, "maxAgents": 1 },
+      "predict": { "priority": "medium", "timeout": 60000, "maxAgents": 2 },
+      "audit": { "priority": "high", "timeout": 300000, "maxAgents": 3 },
+      "map": { "priority": "medium", "timeout": 240000, "maxAgents": 2 },
+      "preload": { "priority": "low", "timeout": 30000, "maxAgents": 1 },
+      "deepdive": { "priority": "high", "timeout": 600000, "maxAgents": 4 },
+      "document": { "priority": "low", "timeout": 180000, "maxAgents": 2 },
+      "refactor": { "priority": "medium", "timeout": 120000, "maxAgents": 2 },
+      "benchmark": { "priority": "medium", "timeout": 180000, "maxAgents": 2 },
+      "testgaps": { "priority": "medium", "timeout": 120000, "maxAgents": 2 }
+    },
+    "agentMappings": {
+      "ultralearn": ["researcher", "coder"],
+      "optimize": ["performance-analyzer", "coder"],
+      "audit": ["security-analyst", "tester"],
+      "benchmark": ["performance-analyzer"],
+      "testgaps": ["tester"],
+      "document": ["documenter", "researcher"],
+      "deepdive": ["researcher", "security-analyst"],
+      "refactor": ["coder", "reviewer"],
+      "map": ["researcher"],
+      "preload": ["researcher"],
+      "predict": ["performance-analyzer"],
+      "consolidate": ["researcher"]
+    }
+  },
+  "performance": {
+    "modelCache": {
+      "enabled": true,
+      "maxSizeMB": 512,
+      "evictionPolicy": "lru"
+    },
+    "benchmarkThresholds": {
+      "triggerDetection": { "p95Ms": 5 },
+      "workerRegistry": { "p95Ms": 10 },
+      "agentSelection": { "p95Ms": 1 },
+      "memoryKeyGeneration": { "p95Ms": 0.1 },
+      "concurrentWorkers": { "totalMs": 1000 }
+    },
+    "optimizations": {
+      "parallelDispatch": true,
+      "batchMemoryWrites": true,
+      "cacheEmbeddings": true,
+      "suppressWarnings": true
+    }
+  },
+  "agents": {
+    "presets": {
+      "quick-scan": {
+        "phases": ["file-discovery", "pattern-discovery", "summarization"],
+        "timeout": 60000,
+        "priority": "low"
+      },
+      "deep-analysis": {
+        "phases": ["file-discovery", "static-analysis", "complexity-analysis", "pattern-extraction", "summarization"],
+        "timeout": 300000,
+        "priority": "high"
+      },
+      "security-scan": {
+        "phases": ["file-discovery", "security-analysis", "secret-detection", "summarization"],
+        "timeout": 180000,
+        "priority": "critical"
+      },
+      "learning": {
+        "phases": ["file-discovery", "pattern-extraction", "vectorization", "sona-training", "pattern-storage"],
+        "timeout": 300000,
+        "priority": "medium"
+      },
+      "api-docs": {
+        "phases": ["api-discovery", "pattern-extraction", "report-generation", "indexing"],
+        "timeout": 180000,
+        "priority": "low"
+      },
+      "test-analysis": {
+        "phases": ["file-discovery", "pattern-discovery", "coverage-analysis", "summarization"],
+        "timeout": 120000,
+        "priority": "medium"
+      }
+    },
+    "capabilities": {
+      "default": {
+        "onnxEmbeddings": true,
+        "vectorDb": true,
+        "sonaLearning": true,
+        "reasoningBank": true,
+        "intelligenceStore": true,
+        "progressEvents": true,
+        "memoryDeposits": true,
+        "persistResults": true
+      }
+    }
   },
   "permissions": {
     "allow": [
       "Bash(npx claude-flow *)",
+      "Bash(npx agentic-flow *)",
       "Bash(npm run lint)",
       "Bash(npm run test:*)",
       "Bash(npm test *)",
+      "Bash(npm run build)",
+      "Bash(npm run benchmark)",
+      "Bash(npm run workers *)",
       "Bash(git status)",
       "Bash(git diff *)",
       "Bash(git log *)",
@@ -28,7 +139,10 @@
       "Bash(node *)",
       "Bash(which *)",
       "Bash(pwd)",
-      "Bash(ls *)"
+      "Bash(ls *)",
+      "mcp__ruv-swarm",
+      "mcp__claude-flow@alpha",
+      "mcp__flow-nexus"
     ],
     "deny": [
       "Bash(rm -rf /)",
@@ -38,13 +152,23 @@
     ]
   },
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat | jq -r '.user_prompt // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha workers dispatch --prompt '{}' --parallel true 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Bash",
         "hooks": [
           {
             "type": "command",
-            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks pre-command --command '{}' --validate-safety true --prepare-resources true"
+            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks pre-command --command '{}' --validate-safety true --prepare-resources true 2>/dev/null || true"
           }
         ]
       },
@@ -53,7 +177,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks pre-edit --file '{}' --auto-assign-agents true --load-context true"
+            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks pre-edit --file '{}' --auto-assign-agents true --load-context true 2>/dev/null || true"
           }
         ]
       }
@@ -64,7 +188,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks post-command --command '{}' --track-metrics true --store-results true"
+            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks post-command --command '{}' --track-metrics true --store-results true 2>/dev/null || true"
           }
         ]
       },
@@ -73,7 +197,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks post-edit --file '{}' --format true --update-memory true"
+            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks post-edit --file '{}' --format true --update-memory true 2>/dev/null || true"
           }
         ]
       }
@@ -84,7 +208,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "/bin/bash -c 'INPUT=$(cat); CUSTOM=$(echo \"$INPUT\" | jq -r \".custom_instructions // \\\"\\\"\"); echo \"🔄 PreCompact Guidance:\"; echo \"📋 IMPORTANT: Review CLAUDE.md in project root for:\"; echo \"   • 54 available agents and concurrent usage patterns\"; echo \"   • Swarm coordination strategies (hierarchical, mesh, adaptive)\"; echo \"   • SPARC methodology workflows with batchtools optimization\"; echo \"   • Critical concurrent execution rules (GOLDEN RULE: 1 MESSAGE = ALL OPERATIONS)\"; if [ -n \"$CUSTOM\" ]; then echo \"🎯 Custom compact instructions: $CUSTOM\"; fi; echo \"✅ Ready for compact operation\"'"
+            "command": "/bin/bash -c 'echo \"🔄 PreCompact: Check CLAUDE.md for 54 agents, swarm patterns, SPARC workflows\"; echo \"✅ Ready for compact\"'"
           }
         ]
       },
@@ -93,7 +217,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "/bin/bash -c 'echo \"🔄 Auto-Compact Guidance (Context Window Full):\"; echo \"📋 CRITICAL: Before compacting, ensure you understand:\"; echo \"   • All 54 agents available in .claude/agents/ directory\"; echo \"   • Concurrent execution patterns from CLAUDE.md\"; echo \"   • Batchtools optimization for 300% performance gains\"; echo \"   • Swarm coordination strategies for complex tasks\"; echo \"⚡ Apply GOLDEN RULE: Always batch operations in single messages\"; echo \"✅ Auto-compact proceeding with full agent context\"'"
+            "command": "/bin/bash -c 'echo \"🔄 Auto-Compact: Preserving agent/worker context\"; echo \"✅ Auto-compact proceeding\"'"
           }
         ]
       }
@@ -103,7 +227,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "npx claude-flow@alpha hooks session-end --generate-summary true --persist-state true --export-metrics true"
+            "command": "npx claude-flow@alpha hooks session-end --generate-summary true --persist-state true --export-metrics true 2>/dev/null || true"
           }
         ]
       }

package/.claude/skills/worker-benchmarks/skill.md

@@ -0,0 +1,135 @@
+---
+name: worker-benchmarks
+description: Run comprehensive worker system benchmarks and performance analysis
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - performance_testing
+  - metrics_collection
+  - optimization_recommendations
+---
+
+# Worker Benchmarks Skill
+
+Run comprehensive performance benchmarks for the agentic-flow worker system.
+
+## Quick Start
+
+```bash
+# Run full benchmark suite
+npx agentic-flow workers benchmark
+
+# Run specific benchmark
+npx agentic-flow workers benchmark --type trigger-detection
+npx agentic-flow workers benchmark --type registry
+npx agentic-flow workers benchmark --type agent-selection
+npx agentic-flow workers benchmark --type concurrent
+```
+
+## Benchmark Types
+
+### 1. Trigger Detection (`trigger-detection`)
+Tests keyword detection speed across 12 worker triggers.
+- **Target**: p95 < 5ms
+- **Iterations**: 1000
+- **Metrics**: latency, throughput, histogram
+
+### 2. Worker Registry (`registry`)
+Tests CRUD operations on worker entries.
+- **Target**: p95 < 10ms
+- **Iterations**: 500 creates, gets, updates
+- **Metrics**: per-operation latency breakdown
+
+### 3. Agent Selection (`agent-selection`)
+Tests performance-based agent selection.
+- **Target**: p95 < 1ms
+- **Iterations**: 1000
+- **Metrics**: selection confidence, agent scores
+
+### 4. Model Cache (`cache`)
+Tests model caching performance.
+- **Target**: p95 < 0.5ms
+- **Metrics**: hit rate, cache size, eviction stats
+
+### 5. Concurrent Workers (`concurrent`)
+Tests parallel worker creation and updates.
+- **Target**: < 1000ms for 10 workers
+- **Metrics**: per-worker latency, memory usage
+
+### 6. Memory Key Generation (`memory-keys`)
+Tests memory pattern key generation.
+- **Target**: p95 < 0.1ms
+- **Iterations**: 5000
+- **Metrics**: unique patterns, throughput
+
+## Output Format
+
+```
+═══════════════════════════════════════════════════════════
+📈 BENCHMARK RESULTS
+═══════════════════════════════════════════════════════════
+
+✅ Trigger Detection
+   Operation: detect
+   Count: 1,000
+   Avg: 0.045ms | p95: 0.120ms (target: 5ms)
+   Throughput: 22,222 ops/s
+   Memory Δ: 0.12MB
+
+✅ Worker Registry
+   Operation: crud
+   Count: 1,500
+   Avg: 1.234ms | p95: 3.456ms (target: 10ms)
+   Throughput: 810 ops/s
+   Memory Δ: 2.34MB
+
+───────────────────────────────────────────────────────────
+📊 SUMMARY
+───────────────────────────────────────────────────────────
+Total Tests: 6
+Passed: 6 | Failed: 0
+Avg Latency: 0.567ms
+Total Duration: 2345ms
+Peak Memory: 8.90MB
+═══════════════════════════════════════════════════════════
+```
+
+## Integration with Settings
+
+Benchmark thresholds are configured in `.claude/settings.json`:
+
+```json
+{
+  "performance": {
+    "benchmarkThresholds": {
+      "triggerDetection": { "p95Ms": 5 },
+      "workerRegistry": { "p95Ms": 10 },
+      "agentSelection": { "p95Ms": 1 },
+      "memoryKeyGeneration": { "p95Ms": 0.1 },
+      "concurrentWorkers": { "totalMs": 1000 }
+    }
+  }
+}
+```
+
+## Programmatic Usage
+
+```typescript
+import { workerBenchmarks, runBenchmarks } from 'agentic-flow/workers/worker-benchmarks';
+
+// Run full suite
+const suite = await runBenchmarks();
+console.log(suite.summary);
+
+// Run individual benchmarks
+const triggerResult = await workerBenchmarks.benchmarkTriggerDetection(1000);
+const registryResult = await workerBenchmarks.benchmarkRegistryOperations(500);
+```
+
+## Performance Optimization Tips
+
+1. **Model Cache**: Enable with `CLAUDE_FLOW_MODEL_CACHE_MB=512`
+2. **Parallel Workers**: Enable with `CLAUDE_FLOW_WORKER_PARALLEL=true`
+3. **Warning Suppression**: Enable with `CLAUDE_FLOW_SUPPRESS_WARNINGS=true`
+4. **SQLite WAL Mode**: Automatic for better concurrent performance

package/.claude/skills/worker-integration/skill.md

@@ -0,0 +1,154 @@
+---
+name: worker-integration
+description: Worker-Agent integration for intelligent task dispatch and performance tracking
+version: 1.0.0
+invocable: true
+author: agentic-flow
+capabilities:
+  - agent_selection
+  - performance_tracking
+  - memory_coordination
+  - self_learning
+---
+
+# Worker-Agent Integration Skill
+
+Intelligent coordination between background workers and specialized agents.
+
+## Quick Start
+
+```bash
+# View agent recommendations for a trigger
+npx agentic-flow workers agents ultralearn
+npx agentic-flow workers agents optimize
+
+# View performance metrics
+npx agentic-flow workers metrics
+
+# View integration stats
+npx agentic-flow workers stats --integration
+```
+
+## Agent Mappings
+
+Workers automatically dispatch to optimal agents based on trigger type:
+
+| Trigger | Primary Agents | Fallback | Pipeline Phases |
+|---------|---------------|----------|-----------------|
+| `ultralearn` | researcher, coder | planner | discovery → patterns → vectorization → summary |
+| `optimize` | performance-analyzer, coder | researcher | static-analysis → performance → patterns |
+| `audit` | security-analyst, tester | reviewer | security → secrets → vulnerability-scan |
+| `benchmark` | performance-analyzer | coder, tester | performance → metrics → report |
+| `testgaps` | tester | coder | discovery → coverage → gaps |
+| `document` | documenter, researcher | coder | api-discovery → patterns → indexing |
+| `deepdive` | researcher, security-analyst | coder | call-graph → deps → trace |
+| `refactor` | coder, reviewer | researcher | complexity → smells → patterns |
+
+## Performance-Based Selection
+
+The system learns from execution history to improve agent selection:
+
+```typescript
+// Agent selection considers:
+// 1. Quality score (0-1)
+// 2. Success rate
+// 3. Average latency
+// 4. Execution count
+
+const { agent, confidence, reasoning } = selectBestAgent('optimize');
+// agent: "performance-analyzer"
+// confidence: 0.87
+// reasoning: "Selected based on 45 executions with 94.2% success"
+```
+
+## Memory Key Patterns
+
+Workers store results using consistent patterns:
+
+```
+{trigger}/{topic}/{phase}
+
+Examples:
+- ultralearn/auth-module/analysis
+- optimize/database/performance
+- audit/payment/vulnerabilities
+- benchmark/api/metrics
+```
+
+## Benchmark Thresholds
+
+Agents are monitored against performance thresholds:
+
+```json
+{
+  "researcher": {
+    "p95_latency": "<500ms",
+    "memory_mb": "<256MB"
+  },
+  "coder": {
+    "p95_latency": "<300ms",
+    "quality_score": ">0.85"
+  },
+  "security-analyst": {
+    "scan_coverage": ">95%",
+    "p95_latency": "<1000ms"
+  }
+}
+```
+
+## Feedback Loop
+
+Workers provide feedback for continuous improvement:
+
+```typescript
+import { workerAgentIntegration } from 'agentic-flow/workers/worker-agent-integration';
+
+// Record execution feedback
+workerAgentIntegration.recordFeedback(
+  'optimize',           // trigger
+  'coder',              // agent
+  true,                 // success
+  245,                  // latency ms
+  0.92                  // quality score
+);
+
+// Check compliance
+const { compliant, violations } = workerAgentIntegration.checkBenchmarkCompliance('coder');
+```
+
+## Integration Statistics
+
+```bash
+$ npx agentic-flow workers stats --integration
+
+Worker-Agent Integration Stats
+══════════════════════════════
+Total Agents:       6
+Tracked Agents:     4
+Total Feedback:     156
+Avg Quality Score:  0.89
+
+Model Cache Stats
+─────────────────
+Hits:     1,234
+Misses:   45
+Hit Rate: 96.5%
+```
+
+## Configuration
+
+Enable integration features in `.claude/settings.json`:
+
+```json
+{
+  "workers": {
+    "enabled": true,
+    "parallel": true,
+    "memoryDepositEnabled": true,
+    "agentMappings": {
+      "ultralearn": ["researcher", "coder"],
+      "optimize": ["performance-analyzer", "coder"]
+    }
+  }
+}
+```

package/README.md

@@ -60,6 +60,7 @@ Most AI coding agents are **painfully slow** and **frustratingly forgetful**. Th
 | **QUIC Transport** | Ultra-low latency agent communication via Rust/WASM QUIC protocol | 50-70% faster than TCP, 0-RTT | [Docs](https://github.com/ruvnet/agentic-flow/tree/main/crates/agentic-flow-quic) |
 | **Federation Hub** 🆕 | Ephemeral agents (5s-15min lifetime) with persistent cross-agent memory | Infinite scale, 0 waste | [Docs](./agentic-flow/src/federation) |
 | **Swarm Optimization** 🆕 | Self-learning parallel execution with AI topology selection | 3-5x speedup, auto-optimizes | [Docs](./docs/swarm-optimization-report.md) |
+| **Background Workers** 🆕 | Non-blocking keyword-triggered workers with SONA/ReasoningBank learning | <5ms dispatch, auto-learn | [Docs](#-background-workers) |
 
 **CLI Usage**:
 - **AgentDB**: Full CLI with 17 commands (`npx agentdb <command>`)
@@ -69,6 +70,8 @@ Most AI coding agents are **painfully slow** and **frustratingly forgetful**. Th
 - **QUIC Transport**: API only
 - **Federation Hub**: `npx agentic-flow federation start` 🆕
 - **Swarm Optimization**: Automatic with parallel execution 🆕
+- **Background Workers**: `npx agentic-flow workers <command>` 🆕
+- **Intelligence Hooks**: `npx agentic-flow hooks <command>` 🆕
 
 **Programmatic**: All components importable: `agentic-flow/agentdb`, `agentic-flow/router`, `agentic-flow/reasoningbank`, `agentic-flow/agent-booster`, `agentic-flow/transport/quic`
 
@@ -238,6 +241,134 @@ spec:
 
 ---
 
+### ⚡ Background Workers
+
+**Non-blocking keyword-triggered workers** that run silently while users continue chatting, with full RuVector integration:
+
+```bash
+# CLI: Background worker operations
+npx agentic-flow workers dispatch ultralearn "authentication patterns" --session abc123
+npx agentic-flow workers status                    # View all workers
+npx agentic-flow workers status --worker wrk_123   # Specific worker
+npx agentic-flow workers cancel wrk_123            # Cancel running worker
+npx agentic-flow workers triggers                  # List available triggers
+npx agentic-flow workers stats --timeframe 24h    # Aggregated statistics
+
+# Initialize hooks and workers integration
+npx agentic-flow hooks init          # Creates .claude/settings.json with all hooks
+
+# Hook-based automatic dispatch (in .claude/settings.json)
+# Workers spawn automatically when keywords detected in prompts
+```
+
+**Trigger Keywords:**
+
+| Trigger | Description | Phases | Use Case |
+|---------|-------------|--------|----------|
+| **ultralearn** | Deep knowledge acquisition | discovery → analysis → vectorization → indexing | "ultralearn authentication" |
+| **optimize** | Performance optimization | pattern-analysis → bottleneck-detect → cache-warmup | "optimize my workflow" |
+| **consolidate** | Memory consolidation | inventory → similarity → merge → prune → reindex | "consolidate memories" |
+| **predict** | Predictive preloading | context-gather → pattern-match → predict → preload | "predict next steps" |
+| **audit** | Security analysis | static-analysis → dependency-scan → vulnerability-check | "audit this codebase" |
+| **map** | Codebase mapping | file-discovery → import-analysis → graph-build → cycle-detection | "map the architecture" |
+| **deepdive** | Deep code analysis | locate → trace-calls → build-graph → analyze-depth | "deepdive into auth.ts" |
+| **document** | Auto-documentation | analyze → template → generate → format | "document this module" |
+| **refactor** | Refactoring suggestions | complexity → duplication → coupling → suggestions | "refactor opportunities" |
+| **benchmark** | Performance benchmarks | discover → instrument → execute → analyze → report | "benchmark the API" |
+| **testgaps** | Test coverage analysis | coverage → paths → criticality → suggestions | "find testgaps" |
+
+**RuVector Integration:**
+- **SONA**: Self-learning trajectory tracking for each worker
+- **ReasoningBank**: Pattern storage from successful worker runs
+- **HNSW**: Vector indexing for semantic search of results
+- **Quality-based Learning**: Workers with 80%+ quality trigger pattern learning
+
+**Programmatic API:**
+```typescript
+import {
+  getWorkerDispatchService,
+  getTriggerDetector,
+  getRuVectorWorkerIntegration
+} from 'agentic-flow/workers';
+
+// Dispatch a worker
+const dispatcher = getWorkerDispatchService();
+const workerId = await dispatcher.dispatch('ultralearn', 'authentication', 'session-123');
+
+// Monitor progress
+dispatcher.on('worker:progress', ({ workerId, progress, phase }) => {
+  console.log(`Worker ${workerId}: ${progress}% - ${phase}`);
+});
+
+// Access learned patterns
+const ruvector = getRuVectorWorkerIntegration();
+const patterns = await ruvector.findRelevantPatterns('ultralearn', 'auth', 5);
+```
+
+**MCP Tools (8 tools):**
+- `worker_dispatch` - Spawn background worker
+- `worker_status` - Get worker status
+- `worker_cancel` - Cancel running worker
+- `worker_triggers` - List available triggers
+- `worker_results` - Get completed worker results
+- `worker_detect` - Detect triggers in prompt
+- `worker_stats` - Aggregated statistics
+- `worker_context` - Get relevant context for injection
+
+**Performance:**
+- **Trigger Detection**: <5ms (regex-based)
+- **Worker Spawn**: <50ms
+- **Max Concurrent**: 10 workers (configurable)
+- **Memory Limit**: 1024MB heap per session
+- **Learning**: Automatic SONA adaptation on 80%+ quality
+
+**Documentation:** [Background Workers Source](./src/workers/)
+
+---
+
+### 🧠 Intelligence Hooks CLI
+
+**Self-learning hooks** for intelligent agent routing and code optimization:
+
+```bash
+# Initialize - creates .claude/settings.json with all hooks
+npx agentic-flow hooks init           # Full configuration
+npx agentic-flow hooks init --minimal # Minimal setup
+
+# Pre/Post hooks for learning
+npx agentic-flow hooks pre-edit src/auth.ts --task "add OAuth"
+npx agentic-flow hooks post-edit src/auth.ts --success --agent coder
+npx agentic-flow hooks pre-command "npm test"
+npx agentic-flow hooks post-command "npm test" --exit-code 0
+
+# Intelligence routing
+npx agentic-flow hooks route "implement authentication"
+npx agentic-flow hooks explain "add OAuth to API"
+
+# RuVector intelligence (SONA + MoE + HNSW)
+npx agentic-flow hooks intelligence stats
+npx agentic-flow hooks intelligence route "debug memory leak"
+npx agentic-flow hooks intelligence trajectory-start --task "build API"
+npx agentic-flow hooks intelligence pattern-store --task "auth" --resolution "JWT"
+npx agentic-flow hooks intelligence pattern-search "authentication"
+
+# Bootstrap learning from codebase
+npx agentic-flow hooks pretrain
+npx agentic-flow hooks build-agents
+```
+
+**Generated settings.json** includes:
+- **PreToolUse**: Pre-edit/pre-command intelligence
+- **PostToolUse**: Success-based learning
+- **PostToolUseFailure**: Learn from failures
+- **SessionStart**: Workers status check, intelligence stats
+- **SessionEnd**: Workers cleanup (24h retention)
+- **UserPromptSubmit**: Background worker dispatch on keyword triggers
+
+**Documentation:** [Hooks Source](./src/cli/commands/hooks.ts)
+
+---
+
 ### 🦀 agentic-jujutsu (Native Rust Package)
 
 **High-performance Rust/NAPI bindings** for change-centric version control: