ruflo 3.10.36 → 3.10.38

package/src/ruvocal/docs/adr/ADR-035-MCP-TOOL-GROUPS.md

@@ -1,186 +1,186 @@
-# ADR-035: MCP Tool Groups — Modular Tool Organization
-
-**Status:** Accepted
-**Date:** 2026-03-05
-**Supersedes:** ADR-033, ADR-034
-
-## Context
-
-The MCP bridge grew to 331+ tools from multiple backends (ruvector, ruflo, agentic-flow, Claude Code, Gemini, Codex). Exposing all tools simultaneously caused:
-
-1. **Context flooding** — AI models struggle to select the right tool from 300+ options
-2. **Startup overhead** — loading all backends when only a subset is needed
-3. **No discoverability** — the AI had no structured way to learn about available capabilities
-
-## Decision
-
-Reorganize all tools into **12 logical groups** that can be independently enabled/disabled via `MCP_GROUP_*` environment variables. Add a built-in `guidance` tool that provides structured instructions to the AI about available capabilities.
-
-### Tool Groups
-
-| Group | Source | Tools | Default | Env Var |
-|-------|--------|-------|---------|---------|
-| **core** | built-in | search, web_research, guidance | always on | — |
-| **intelligence** | ruvector | ~10 | enabled | `MCP_GROUP_INTELLIGENCE` |
-| **agents** | ruflo | ~50 | enabled | `MCP_GROUP_AGENTS` |
-| **memory** | ruflo | ~25 | enabled | `MCP_GROUP_MEMORY` |
-| **devtools** | ruflo | ~60 | enabled | `MCP_GROUP_DEVTOOLS` |
-| **security** | ruflo | ~25 | disabled | `MCP_GROUP_SECURITY` |
-| **browser** | ruflo | ~23 | disabled | `MCP_GROUP_BROWSER` |
-| **neural** | ruflo | ~20 | disabled | `MCP_GROUP_NEURAL` |
-| **agentic-flow** | agentic-flow@alpha | 15 | disabled | `MCP_GROUP_AGENTIC_FLOW` |
-| **claude-code** | claude mcp serve | varies | disabled | `MCP_GROUP_CLAUDE_CODE` |
-| **gemini** | gemini-mcp-server | varies | disabled | `MCP_GROUP_GEMINI` |
-| **codex** | @openai/codex | varies | disabled | `MCP_GROUP_CODEX` |
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  HF Chat UI → /mcp                                     │
-└─────────────┬───────────────────────────────────────────┘
-              ▼
-┌─────────────────────────────────────────────────────────┐
-│  MCP Bridge v2.0.0                                      │
-│                                                         │
-│  ┌─────────────────────────────────────────────────┐   │
-│  │  TOOL GROUP FILTER                               │   │
-│  │  MCP_GROUP_INTELLIGENCE=true  → include          │   │
-│  │  MCP_GROUP_AGENTS=true        → include          │   │
-│  │  MCP_GROUP_BROWSER=false      → exclude          │   │
-│  │  MCP_GROUP_NEURAL=false       → exclude          │   │
-│  └─────────────────────────────────────────────────┘   │
-│         ▼                    ▼                ▼         │
-│  ┌──────────┐  ┌──────────────┐  ┌─────────────────┐  │
-│  │ ruvector │  │    ruflo     │  │ agentic-flow    │  │
-│  │ (stdio)  │  │   (stdio)   │  │    (stdio)      │  │
-│  └──────────┘  └──────────────┘  └─────────────────┘  │
-│                                                         │
-│  Optional (disabled by default):                        │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
-│  │  Claude  │  │  Gemini  │  │  Codex   │             │
-│  └──────────┘  └──────────┘  └──────────┘             │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Group Filtering
-
-Tools from external backends are filtered by matching their original tool name against group prefix patterns:
-
-```javascript
-// Group definition
-agents: {
-  source: "ruflo",
-  prefixes: ["agent_", "swarm_", "task_", "session_", "hive-mind_", "workflow_", "coordination_"],
-}
-
-// ruflo tool "agent_spawn" → matches "agent_" prefix → included if agents group enabled
-// ruflo tool "browser_open" → matches "browser_" prefix → only if browser group enabled
-```
-
-A backend is only started if at least one of its groups is enabled. This means disabling all ruflo groups prevents the ruflo process from spawning entirely.
-
-### Guidance Tool
-
-The `guidance` tool replaces the old `system_guide`. It provides structured, AI-optimized instructions:
-
-```
-guidance(topic="overview")     → capabilities summary + decision guide
-guidance(topic="groups")       → table of all groups with status
-guidance(topic="agents")       → detailed usage for the agents group
-guidance(topic="tool", tool_name="ruflo__memory_search") → specific tool docs
-```
-
-The system prompt instructs the AI to call `guidance` when:
-- Unsure which tool to use
-- User asks "what can you do?"
-- Needs to learn a specific tool group before using it
-
-### Agentic-Flow Integration
-
-`agentic-flow@alpha` (npm package) provides 15 tools:
-
-| Tool | Description |
-|------|-------------|
-| `agentic_flow_agent` | Execute any of 66+ specialized agents |
-| `agentic_flow_list_agents` | List available agent types |
-| `agentic_flow_create_agent` | Create custom agents |
-| `agentic_flow_list_all_agents` | List with sources |
-| `agentic_flow_agent_info` | Get agent details |
-| `agentic_flow_check_conflicts` | Agent conflict detection |
-| `agentic_flow_optimize_model` | Auto-select best model |
-| `agent_booster_edit_file` | 352x faster code editing |
-| `agent_booster_batch_edit` | Multi-file refactoring |
-| `agent_booster_parse_markdown` | LLM output parsing |
-| `agentdb_stats` | Database statistics |
-| `agentdb_pattern_store` | Store reasoning patterns |
-| `agentdb_pattern_search` | Search similar patterns |
-| `agentdb_pattern_stats` | Pattern analytics |
-| `agentdb_clear_cache` | Clear query cache |
-
-## Configuration Examples
-
-### Minimal (research assistant)
-```env
-MCP_GROUP_INTELLIGENCE=false
-MCP_GROUP_AGENTS=false
-MCP_GROUP_MEMORY=false
-MCP_GROUP_DEVTOOLS=false
-# Only core tools: search, web_research, guidance
-```
-
-### Developer workstation
-```env
-MCP_GROUP_INTELLIGENCE=true
-MCP_GROUP_AGENTS=true
-MCP_GROUP_MEMORY=true
-MCP_GROUP_DEVTOOLS=true
-MCP_GROUP_AGENTIC_FLOW=true   # agent execution + boosted editing
-```
-
-### Full capabilities
-```env
-MCP_GROUP_INTELLIGENCE=true
-MCP_GROUP_AGENTS=true
-MCP_GROUP_MEMORY=true
-MCP_GROUP_DEVTOOLS=true
-MCP_GROUP_SECURITY=true
-MCP_GROUP_BROWSER=true
-MCP_GROUP_NEURAL=true
-MCP_GROUP_AGENTIC_FLOW=true
-MCP_GROUP_CLAUDE_CODE=true
-MCP_GROUP_GEMINI=true
-MCP_GROUP_CODEX=true
-ANTHROPIC_API_KEY=sk-ant-...
-```
-
-## API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/health` | GET | System health with group status |
-| `/groups` | GET | Detailed group info with tool counts |
-| `/models` | GET | Available LLM models |
-| `/mcp` | POST | MCP JSON-RPC (tools/list, tools/call) |
-
-## Consequences
-
-### Positive
-- AI sees only relevant tools (20-50 instead of 300+), improving tool selection accuracy
-- Unused backends don't start, saving memory and CPU
-- `guidance` tool provides structured discoverability
-- Groups can be mixed and matched per deployment
-- New backends/groups can be added without touching existing code
-
-### Negative
-- Some tools appear in multiple potential groups (e.g., ruflo `hooks_*` in both intelligence and devtools) — resolved by prefix matching
-- Group boundaries are somewhat arbitrary for the ruflo "Uncategorized" tools
-
-### Mitigations
-- `guidance` tool helps AI navigate regardless of how tools are grouped
-- `/groups` endpoint lets operators inspect what's actually active
-
-## Related
-
-- [ADR-029: HuggingFace Chat UI Cloud Run](ADR-029-HUGGINGFACE-CHAT-UI-CLOUD-RUN.md)
-- [ADR-032: RVF Private MCP Tunnel](ADR-032-RVF-PRIVATE-MCP-TUNNEL.md)
+# ADR-035: MCP Tool Groups — Modular Tool Organization
+
+**Status:** Accepted
+**Date:** 2026-03-05
+**Supersedes:** ADR-033, ADR-034
+
+## Context
+
+The MCP bridge grew to 331+ tools from multiple backends (ruvector, ruflo, agentic-flow, Claude Code, Gemini, Codex). Exposing all tools simultaneously caused:
+
+1. **Context flooding** — AI models struggle to select the right tool from 300+ options
+2. **Startup overhead** — loading all backends when only a subset is needed
+3. **No discoverability** — the AI had no structured way to learn about available capabilities
+
+## Decision
+
+Reorganize all tools into **12 logical groups** that can be independently enabled/disabled via `MCP_GROUP_*` environment variables. Add a built-in `guidance` tool that provides structured instructions to the AI about available capabilities.
+
+### Tool Groups
+
+| Group | Source | Tools | Default | Env Var |
+|-------|--------|-------|---------|---------|
+| **core** | built-in | search, web_research, guidance | always on | — |
+| **intelligence** | ruvector | ~10 | enabled | `MCP_GROUP_INTELLIGENCE` |
+| **agents** | ruflo | ~50 | enabled | `MCP_GROUP_AGENTS` |
+| **memory** | ruflo | ~25 | enabled | `MCP_GROUP_MEMORY` |
+| **devtools** | ruflo | ~60 | enabled | `MCP_GROUP_DEVTOOLS` |
+| **security** | ruflo | ~25 | disabled | `MCP_GROUP_SECURITY` |
+| **browser** | ruflo | ~23 | disabled | `MCP_GROUP_BROWSER` |
+| **neural** | ruflo | ~20 | disabled | `MCP_GROUP_NEURAL` |
+| **agentic-flow** | agentic-flow@alpha | 15 | disabled | `MCP_GROUP_AGENTIC_FLOW` |
+| **claude-code** | claude mcp serve | varies | disabled | `MCP_GROUP_CLAUDE_CODE` |
+| **gemini** | gemini-mcp-server | varies | disabled | `MCP_GROUP_GEMINI` |
+| **codex** | @openai/codex | varies | disabled | `MCP_GROUP_CODEX` |
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  HF Chat UI → /mcp                                     │
+└─────────────┬───────────────────────────────────────────┘
+              ▼
+┌─────────────────────────────────────────────────────────┐
+│  MCP Bridge v2.0.0                                      │
+│                                                         │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  TOOL GROUP FILTER                               │   │
+│  │  MCP_GROUP_INTELLIGENCE=true  → include          │   │
+│  │  MCP_GROUP_AGENTS=true        → include          │   │
+│  │  MCP_GROUP_BROWSER=false      → exclude          │   │
+│  │  MCP_GROUP_NEURAL=false       → exclude          │   │
+│  └─────────────────────────────────────────────────┘   │
+│         ▼                    ▼                ▼         │
+│  ┌──────────┐  ┌──────────────┐  ┌─────────────────┐  │
+│  │ ruvector │  │    ruflo     │  │ agentic-flow    │  │
+│  │ (stdio)  │  │   (stdio)   │  │    (stdio)      │  │
+│  └──────────┘  └──────────────┘  └─────────────────┘  │
+│                                                         │
+│  Optional (disabled by default):                        │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
+│  │  Claude  │  │  Gemini  │  │  Codex   │             │
+│  └──────────┘  └──────────┘  └──────────┘             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Group Filtering
+
+Tools from external backends are filtered by matching their original tool name against group prefix patterns:
+
+```javascript
+// Group definition
+agents: {
+  source: "ruflo",
+  prefixes: ["agent_", "swarm_", "task_", "session_", "hive-mind_", "workflow_", "coordination_"],
+}
+
+// ruflo tool "agent_spawn" → matches "agent_" prefix → included if agents group enabled
+// ruflo tool "browser_open" → matches "browser_" prefix → only if browser group enabled
+```
+
+A backend is only started if at least one of its groups is enabled. This means disabling all ruflo groups prevents the ruflo process from spawning entirely.
+
+### Guidance Tool
+
+The `guidance` tool replaces the old `system_guide`. It provides structured, AI-optimized instructions:
+
+```
+guidance(topic="overview")     → capabilities summary + decision guide
+guidance(topic="groups")       → table of all groups with status
+guidance(topic="agents")       → detailed usage for the agents group
+guidance(topic="tool", tool_name="ruflo__memory_search") → specific tool docs
+```
+
+The system prompt instructs the AI to call `guidance` when:
+- Unsure which tool to use
+- User asks "what can you do?"
+- Needs to learn a specific tool group before using it
+
+### Agentic-Flow Integration
+
+`agentic-flow@alpha` (npm package) provides 15 tools:
+
+| Tool | Description |
+|------|-------------|
+| `agentic_flow_agent` | Execute any of 66+ specialized agents |
+| `agentic_flow_list_agents` | List available agent types |
+| `agentic_flow_create_agent` | Create custom agents |
+| `agentic_flow_list_all_agents` | List with sources |
+| `agentic_flow_agent_info` | Get agent details |
+| `agentic_flow_check_conflicts` | Agent conflict detection |
+| `agentic_flow_optimize_model` | Auto-select best model |
+| `agent_booster_edit_file` | 352x faster code editing |
+| `agent_booster_batch_edit` | Multi-file refactoring |
+| `agent_booster_parse_markdown` | LLM output parsing |
+| `agentdb_stats` | Database statistics |
+| `agentdb_pattern_store` | Store reasoning patterns |
+| `agentdb_pattern_search` | Search similar patterns |
+| `agentdb_pattern_stats` | Pattern analytics |
+| `agentdb_clear_cache` | Clear query cache |
+
+## Configuration Examples
+
+### Minimal (research assistant)
+```env
+MCP_GROUP_INTELLIGENCE=false
+MCP_GROUP_AGENTS=false
+MCP_GROUP_MEMORY=false
+MCP_GROUP_DEVTOOLS=false
+# Only core tools: search, web_research, guidance
+```
+
+### Developer workstation
+```env
+MCP_GROUP_INTELLIGENCE=true
+MCP_GROUP_AGENTS=true
+MCP_GROUP_MEMORY=true
+MCP_GROUP_DEVTOOLS=true
+MCP_GROUP_AGENTIC_FLOW=true   # agent execution + boosted editing
+```
+
+### Full capabilities
+```env
+MCP_GROUP_INTELLIGENCE=true
+MCP_GROUP_AGENTS=true
+MCP_GROUP_MEMORY=true
+MCP_GROUP_DEVTOOLS=true
+MCP_GROUP_SECURITY=true
+MCP_GROUP_BROWSER=true
+MCP_GROUP_NEURAL=true
+MCP_GROUP_AGENTIC_FLOW=true
+MCP_GROUP_CLAUDE_CODE=true
+MCP_GROUP_GEMINI=true
+MCP_GROUP_CODEX=true
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | System health with group status |
+| `/groups` | GET | Detailed group info with tool counts |
+| `/models` | GET | Available LLM models |
+| `/mcp` | POST | MCP JSON-RPC (tools/list, tools/call) |
+
+## Consequences
+
+### Positive
+- AI sees only relevant tools (20-50 instead of 300+), improving tool selection accuracy
+- Unused backends don't start, saving memory and CPU
+- `guidance` tool provides structured discoverability
+- Groups can be mixed and matched per deployment
+- New backends/groups can be added without touching existing code
+
+### Negative
+- Some tools appear in multiple potential groups (e.g., ruflo `hooks_*` in both intelligence and devtools) — resolved by prefix matching
+- Group boundaries are somewhat arbitrary for the ruflo "Uncategorized" tools
+
+### Mitigations
+- `guidance` tool helps AI navigate regardless of how tools are grouped
+- `/groups` endpoint lets operators inspect what's actually active
+
+## Related
+
+- [ADR-029: HuggingFace Chat UI Cloud Run](ADR-029-HUGGINGFACE-CHAT-UI-CLOUD-RUN.md)
+- [ADR-032: RVF Private MCP Tunnel](ADR-032-RVF-PRIVATE-MCP-TUNNEL.md)